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模块。
参数
参数 |
注释 |
|---|---|
此参数指示应将文件的访问时间设置为的时间。 当不需要修改时应为 默认值为 |
|
结果文件系统对象应具有的属性。 要获取支持的标志，请查看目标系统上 此字符串应包含与 默认情况下假定使用 |
|
此标志指示应跟踪文件系统链接（如果存在）。
在 Ansible 2.5 之前，默认值为 在创建目标不存在的符号链接时，设置 选项
|
|
应该拥有文件系统对象的组的名称，就像将其提供给 如果未指定，则使用当前用户的当前组，除非您是 root 用户，在这种情况下，它可以保留以前的所有权。 |
|
结果文件系统对象应具有的权限。 对于那些习惯于 如果 Ansible 没有遵循这些规则，则会得到一个十进制数，这会产生意外的结果。 从 Ansible 1.8 开始，可以将模式指定为符号模式（例如， 如果未指定 如果未指定 指定 |
|
此参数指示应将文件的修改时间设置为的时间。 当不需要修改时应为 默认值为 None，表示对于 |
|
应该拥有文件系统对象的用户的名称，就像将其提供给 如果未指定，则使用当前用户，除非您是 root 用户，在这种情况下，它可以保留以前的所有权。 指定数字用户名将被视为用户 ID 而不是用户名。避免使用数字用户名，以避免这种混淆。 |
|
要管理的文件的路径。 |
|
SELinux 文件系统对象上下文的级别部分。 这是 MLS/MCS 属性，有时称为 当设置为 |
|
SELinux 文件系统对象上下文的角色部分。 当设置为 |
|
SELinux 文件系统对象上下文的类型部分。 当设置为 |
|
SELinux 文件系统对象上下文的用户部分。 默认情况下，它使用 当设置为 |
|
要链接到的文件路径。 仅适用于 对于 相对路径是相对于正在创建的文件 ( |
|
如果 如果 如果 如果 如果 如果 如果 默认值为文件（如果存在）的当前状态，如果 选项
|
|
影响何时使用原子操作来防止数据损坏或从目标文件系统对象读取不一致的数据。 默认情况下，此模块使用原子操作来防止数据损坏或从目标文件系统对象读取不一致的数据，但有时系统会配置或以某种方式损坏，从而阻止了此操作。一个例子是 docker 挂载的文件系统对象，它不能从容器内部原子更新，只能以不安全的方式写入。 当原子操作失败时，此选项允许 Ansible 回退到更新文件系统对象的不安全方法（但是，它不会强制 Ansible 执行不安全的写入）。 重要提示！不安全的写入容易发生竞争条件，并可能导致数据损坏。 选项
|
属性
属性 |
支持 |
描述 |
|---|---|---|
支持： 完全 |
可以在 check_mode 中运行并返回更改的状态预测，而无需修改目标，如果不支持，则会跳过该操作。 |
|
支持： 部分 将显示权限和所有权，但不显示 absent/touch 上的文件内容。 |
在 diff 模式下，将返回有关已更改的内容（或可能需要在 check_mode 中更改的内容）的详细信息 |
|
平台： 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
返回值
常见的返回值记录在 此处，以下是此模块独有的字段
键 |
描述 |
|---|---|