Ansible Core 文档

ansible.builtin.file 模块 – 管理文件和文件属性

注意

此模块是 ansible-core 的一部分，并包含在所有 Ansible 安装中。在大多数情况下，即使不指定集合关键字，也可以使用简短的模块名称 file。但是，我们建议您使用完全限定集合名称 (FQCN) ansible.builtin.file，以便轻松链接到模块文档并避免与其他可能具有相同模块名称的集合冲突。

概要 

设置文件、目录或符号链接及其目标的属性。
或者，删除文件、符号链接或目录。
许多其他模块支持与 ansible.builtin.file 模块相同的选项，包括 ansible.builtin.copy、ansible.builtin.template 和 ansible.builtin.assemble。
对于 Windows 目标，请改用 ansible.windows.win_file 模块。

参数 

参数	注释
access_time 字符串在 Ansible 2.7 中添加	此参数指示应将文件的访问时间设置为的时间。当不需要修改时，应为 `preserve`；当使用默认时间格式时，应为 `YYYYMMDDHHMM.SS`；或者应为 `now`。默认为 `None`，这意味着 `preserve` 是 `state=[file,directory,link,hard]` 的默认值，而 `now` 是 `state=touch` 的默认值。
access_time_format 字符串在 Ansible 2.7 中添加	当与 `access_time` 一起使用时，指示必须使用的时间格式。基于默认 Python 格式（请参阅 time.strftime 文档）。默认值： `"%Y%m%d%H%M.%S"`
attributes 别名：attr 字符串	结果文件系统对象应具有的属性。要获取支持的标志，请查看目标系统上的 `chattr` 的手册页。此字符串应包含与 `lsattr` 显示顺序相同的属性。 `=` 运算符被假定为默认值，否则需要在字符串中包含 `+` 或 `-` 运算符。
follow 布尔值	此标志指示应跟随文件系统链接（如果存在）。 `follow=yes` 和 `state=link` 可以修改 `src`，当与 `mode` 等参数组合使用时。在 Ansible 2.5 之前，此值默认为 `false`。当创建具有不存在的目标的符号链接时，请设置 `follow=false`，以避免与权限问题相关的警告消息。添加警告消息是为了通知用户，我们无法将权限设置为不存在的目标。选项 `false` `true` ←（默认）
force 布尔值	在两种情况下强制创建链接：如果链接类型是符号链接，并且源文件不存在（但稍后会出现）；目标存在并且是一个文件（因此，我们需要取消链接 `path` 文件，并创建一个链接到 `src` 文件来代替它）。选项 `false` ←（默认） `true`
group 字符串	应拥有文件系统对象的所有者的组的名称，就像将其提供给 `chown` 一样。如果未指定，则使用当前用户的当前组，除非您是 root 用户，在这种情况下，它可以保留以前的所有权。
mode 任何	结果文件系统对象应具有的权限。对于那些习惯于 `/usr/bin/chmod` 的人来说，请记住，模式实际上是八进制数。您必须向 Ansible 提供足够的信息才能正确解析它们。为了获得一致的结果，请引用八进制数（例如，`'644'` 或 `'1777'`），以便 Ansible 接收字符串并可以执行其自己的从字符串到数字的转换。添加前导零（例如，`0755`）有时可以工作，但在循环和其他某些情况下可能会失败。如果 Ansible 未遵循这些规则，则最终会得到一个十进制数，这将产生意想不到的结果。从 Ansible 1.8 开始，可以将模式指定为符号模式（例如，`u+rwx` 或 `u=rw,g=r,o=r`）。如果未指定 `mode` 并且目标文件系统对象不存在，则在设置新创建的文件系统对象的模式时，将使用系统上的默认 `umask`。如果未指定 `mode` 且目标文件系统对象确实存在，则将使用现有文件系统对象的模式。指定 `mode` 是确保文件系统对象以正确权限创建的最佳方法。有关更多详细信息，请参阅 CVE-2020-1736。
modification_time 字符串在 Ansible 2.7 中添加	此参数指示文件修改时间应设置的时间。当不需要修改时，应为 `preserve`；当使用默认时间格式时，应为 `YYYYMMDDHHMM.SS`；或者应为 `now`。默认值为 None，表示对于 `state=[file,directory,link,hard]`，默认值为 `preserve`，而对于 `state=touch`，默认值为 `now`。
modification_time_format 字符串在 Ansible 2.7 中添加	与 `modification_time` 一起使用时，表示必须使用的时间格式。基于默认 Python 格式（请参阅 time.strftime 文档）。默认值： `"%Y%m%d%H%M.%S"`
owner 字符串	应该拥有文件系统对象的用户的名称，与传递给 `chown` 的方式相同。如果未指定，则使用当前用户，除非您是 root 用户，在这种情况下可以保留之前的属主。指定数字用户名将被假定为用户 ID 而不是用户名。请避免使用数字用户名，以避免这种混淆。
path 别名: dest, name path / required	要管理的文件的路径。
recurse 布尔值	递归地在目录内容上设置指定的文件属性。仅当 `state` 设置为 `directory` 时适用。选项 `false` ←（默认） `true`
selevel 字符串	SELinux 文件系统对象上下文的级别部分。这是 MLS/MCS 属性，有时称为 `range`。当设置为 `_default` 时，如果策略可用，它将使用策略的 `level` 部分。
serole 字符串	SELinux 文件系统对象上下文的角色部分。当设置为 `_default` 时，如果策略可用，它将使用策略的 `role` 部分。
setype 字符串	SELinux 文件系统对象上下文的类型部分。当设置为 `_default` 时，如果策略可用，它将使用策略的 `type` 部分。
seuser 字符串	SELinux 文件系统对象上下文的用户部分。默认情况下，它使用 `system` 策略（如果适用）。当设置为 `_default` 时，如果策略可用，它将使用策略的 `user` 部分。
src path	要链接到的文件的路径。仅适用于 `state=link` 和 `state=hard`。对于 `state=link`，这也将接受一个不存在的路径。相对路径相对于正在创建的文件（`path`），这与 Unix 命令 `ln -s SRC DEST` 处理相对路径的方式相同。
state 字符串	如果为 `absent`，则将递归删除目录，并取消链接文件或符号链接。对于目录，如果声明了 `diff`，您将在 `path_contents` 下看到已删除的文件和文件夹列表。请注意，如果 `path` 不存在，`absent` 不会导致 ansible.builtin.file 失败，因为状态没有更改。如果为 `directory`，则如果不存在，将创建所有中间子目录。自 Ansible 1.7 起，它们将使用提供的权限创建。如果为 `file`，且没有其他选项，则返回 `path` 的当前状态。如果为 `file`，即使有其他选项（例如 `mode`），如果文件存在，则会修改该文件，但如果文件不存在，则不会创建该文件。设置为 `touch` 或使用 ansible.builtin.copy 或 ansible.builtin.template 模块，如果您想在文件不存在时创建文件。如果为 `hard`，则将创建或更改硬链接。如果为 `link`，则将创建或更改符号链接。如果为 `touch`（1.4 中新增），则如果文件不存在，将创建一个空文件，而现有文件或目录将接收更新的文件访问和修改时间（类似于 `touch` 从命令行工作的方式）。默认值是文件（如果存在）的当前状态，如果 `recurse=yes`，则为 `directory`，否则为 `file`。选项 `"absent"` `"directory"` `"file"` `"hard"` `"link"` `"touch"`
unsafe_writes 布尔值	影响何时使用原子操作以防止目标文件系统对象的数据损坏或不一致的读取。默认情况下，此模块使用原子操作来防止目标文件系统对象的数据损坏或不一致的读取，但有时系统配置或损坏的方式会阻止这种情况。一个例子是 docker 挂载的文件系统对象，无法从容器内部以原子方式更新，并且只能以不安全的方式写入。此选项允许 Ansible 在原子操作失败时回退到不安全的方法来更新文件系统对象（但是，它不会强制 Ansible 执行不安全的写入）。重要提示！不安全的写入会受到竞争条件的影响，并可能导致数据损坏。选项 `false` ←（默认） `true`

属性 

属性	支持	描述
check_mode	支持: 完全	可以在 check_mode 中运行并返回更改的状态预测，而无需修改目标，如果不支持，则将跳过该操作。
diff_mode	支持: 部分将显示权限和所有权，但不会显示 absent/touch 的文件内容。	当处于 diff 模式时，将返回有关已更改（或在 check_mode 中可能需要更改）的详细信息
platform	平台: posix	可以对其进行操作的目标操作系统/系列

另请参阅 

另请参阅

ansible.builtin.assemble: 从片段组装配置文件。
ansible.builtin.copy: 将文件复制到远程位置。
ansible.builtin.stat: 检索文件或文件系统状态。
ansible.builtin.template: 将文件模板化到目标主机。
ansible.windows.win_file: 关于 ansible.windows.win_file 模块的官方文档。

示例 

- name: Change file ownership, group and permissions
  ansible.builtin.file:
    path: /etc/foo.conf
    owner: foo
    group: foo
    mode: '0644'

- name: Give insecure permissions to an existing file
  ansible.builtin.file:
    path: /work
    owner: root
    group: root
    mode: '1777'

- name: Create a symbolic link
  ansible.builtin.file:
    src: /file/to/link/to
    dest: /path/to/symlink
    owner: foo
    group: foo
    state: link

- name: Create two hard links
  ansible.builtin.file:
    src: '/tmp/{{ item.src }}'
    dest: '{{ item.dest }}'
    state: hard
  loop:
    - { src: x, dest: y }
    - { src: z, dest: k }

- name: Touch a file, using symbolic modes to set the permissions (equivalent to 0644)
  ansible.builtin.file:
    path: /etc/foo.conf
    state: touch
    mode: u=rw,g=r,o=r

- name: Touch the same file, but add/remove some permissions
  ansible.builtin.file:
    path: /etc/foo.conf
    state: touch
    mode: u+rw,g-wx,o-rwx

- name: Touch again the same file, but do not change times this makes the task idempotent
  ansible.builtin.file:
    path: /etc/foo.conf
    state: touch
    mode: u+rw,g-wx,o-rwx
    modification_time: preserve
    access_time: preserve

- name: Create a directory if it does not exist
  ansible.builtin.file:
    path: /etc/some_directory
    state: directory
    mode: '0755'

- name: Update modification and access time of given file
  ansible.builtin.file:
    path: /etc/some_file
    state: file
    modification_time: now
    access_time: now

- name: Set access time based on seconds from epoch value
  ansible.builtin.file:
    path: /etc/another_file
    state: file
    access_time: '{{ "%Y%m%d%H%M.%S" | strftime(stat_var.stat.atime) }}'

- name: Recursively change ownership of a directory
  ansible.builtin.file:
    path: /etc/foo
    state: directory
    recurse: yes
    owner: foo
    group: foo

- name: Remove file (delete file)
  ansible.builtin.file:
    path: /etc/foo.txt
    state: absent

- name: Recursively remove directory
  ansible.builtin.file:
    path: /etc/foo
    state: absent

返回值 

通用返回值记录在此处此处，以下是此模块特有的字段

键	描述
dest 字符串	目标文件/路径，等于传递给 `path` 的值。返回: `state=touch`, `state=hard`, `state=link` 示例: `"/path/to/file.txt"`
path 字符串	目标文件/路径，等于传递给 `path` 的值。返回: `state=absent`, `state=directory`, `state=file` 示例: `"/path/to/file.txt"`

作者

Ansible 核心团队
Michael DeHaan

集合链接