Ansible 核心文档

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` 等参数结合使用时修改 `src`。在 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，这意味着 `preserve` 是 `state=[file,directory,link,hard]` 的默认值，而 `now` 是 `state=touch` 的默认值。
modification_time_format 字符串在 Ansible 2.7 中添加	与 `modification_time` 一起使用时，表示必须使用的时间格式。基于默认的 Python 格式（参见 time.strftime 文档）。默认值： `"%Y%m%d%H%M.%S"`
owner 字符串	应该拥有文件系统对象的用户的名称，如同传递给 `chown` 一样。如果未指定，它将使用当前用户，除非您是 root 用户，在这种情况下它可以保留之前的拥有者。指定数字用户名将被视为用户 ID，而不是用户名。避免使用数字用户名以避免混淆。
path 别名: dest, name 路径 / 必需	要管理的文件的路径。
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` 下被删除的文件和文件夹。请注意，`absent` 不会导致 ansible.builtin.file 失败，因为如果 `path` 不存在，状态没有改变。如果 `directory`，如果所有中间子目录不存在，则将创建它们。从 Ansible 1.7 开始，它们将使用提供的权限创建。如果 `file`，没有其他选项，则返回 `path` 的当前状态。如果 `file`，即使使用其他选项（如 `mode`），如果文件存在则将修改文件，但如果文件不存在则不会创建文件。如果要创建文件（如果不存在），请设置为 `touch` 或使用 ansible.builtin.copy 或 ansible.builtin.template 模块。如果 `hard`，则将创建或更改硬链接。如果 `link`，则将创建或更改符号链接。如果 `touch`（1.4 中新增），如果文件不存在，则将创建一个空文件，而现有文件或目录将接收更新的文件访问和修改时间（类似于 `touch` 从命令行工作的方式）。默认情况下是文件当前状态（如果存在）、`directory`（如果 `recurse=yes`），否则是 `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

集合链接