Ansible 社区文档

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

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使不指定 collections 关键字，也可以使用简短的模块名称 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`，这意味着对于 `state=[file,directory,link,hard]`，默认值为 `preserve`；对于 `state=touch`，默认值为 `now`。
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` 可以与 `mode` 等参数结合使用时修改 `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，这意味着对于`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 / 必填	要管理的文件的路径。
recurse（递归）布尔值	递归地将指定的文件属性设置到目录内容上。这仅在`state`设置为`directory`时适用。选项 `false` ← (默认) `true`
selevel（SELinux 安全级别）字符串	SELinux 文件系统对象上下文中的级别部分。这是 MLS/MCS 属性，有时称为`range`。设置为`_default`时，如果可用，它将使用策略的`level`部分。
serole（SELinux 安全角色）字符串	SELinux 文件系统对象上下文中的角色部分。设置为`_default`时，如果可用，它将使用策略的`role`部分。
setype（SELinux 安全类型）字符串	SELinux 文件系统对象上下文中的类型部分。设置为`_default`时，如果可用，它将使用策略的`type`部分。
seuser（SELinux 安全用户）字符串	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（检查模式）	支持：完全支持	可以在检查模式下运行并返回更改状态预测，而无需修改目标，如果不支持，则将跳过该操作。
diff_mode（差异模式）	支持：部分支持将显示权限和所有权，但 absent/touch 的文件内容将不会显示。	在差异模式下，将返回有关已更改内容（或在检查模式下可能需要更改的内容）的详细信息。
platform（平台）	平台： posix	可以对其进行操作的目标操作系统/系列。

另请参阅 

另请参阅

ansible.builtin.assemble: 从片段组装配置文件。
ansible.builtin.copy: 将文件复制到远程位置。
ansible.builtin.stat: 检索文件或文件系统状态。
ansible.builtin.template: 将文件模板输出到目标主机。
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

资源链接