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`，这意味着 `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 文件系统对象上下文的 role 部分。设置为 `_default` 时，它将使用策略的 `role` 部分（如果可用）。
setype 字符串	SELinux 文件系统对象上下文的 type 部分。设置为 `_default` 时，它将使用策略的 `type` 部分（如果可用）。
seuser 字符串	SELinux 文件系统对象上下文的 user 部分。默认情况下，它使用 `system` 策略（如果适用）。设置为 `_default` 时，它将使用策略的 `user` 部分（如果可用）。
src 路径	要链接到的文件的路径。仅适用于 `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` 的值。返回值： `state=absent`、`state=directory`、`state=file` 示例： `"/path/to/file.txt"`

作者

Ansible 核心团队
Michael DeHaan

集合链接