ansible.builtin.file module – Manage files and file properties
Note
This module is part of ansible-core and included in all Ansible installations. In most cases, you can use the short module name file even without specifying the collections keyword. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.file for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.
Synopsis
- Set attributes of files, directories, or symlinks and their targets.
- Alternatively, remove files, symlinks or directories.
- Many other modules support the same options as the ansible.builtin.file module - including ansible.builtin.copy, ansible.builtin.template, and ansible.builtin.assemble.
- For Windows targets, use the ansible.windows.win_file module instead.
Parameters
Parameter | Comments |
|---|---|
access_time string added in Ansible 2.7 | This parameter indicates the time the file’s access time should be set to. Should be Default is |
access_time_format string added in Ansible 2.7 | When used with Based on default Python format (see time.strftime doc). Default: |
attributes aliases: attr string | The attributes the resulting filesystem object should have. To get supported flags look at the man page for chattr on the target system. This string should contain the attributes in the same order as the one displayed by lsattr. The |
follow boolean | This flag indicates that filesystem links, if they exist, should be followed.
Previous to Ansible 2.5, this was While creating a symlink with a non-existent destination, set Choices:
|
force boolean | |
group string | Name of the group that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. |
mode any | The permissions the resulting filesystem object should have. For those used to /usr/bin/chmod remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal numbers (for example, Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, If If Specifying |
modification_time string added in Ansible 2.7 | This parameter indicates the time the file’s modification time should be set to. Should be Default is None meaning that |
modification_time_format string added in Ansible 2.7 | When used with Based on default Python format (see time.strftime doc). Default: |
owner string | Name of the user that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. |
path aliases: dest, name path / required | Path to the file being managed. |
recurse boolean | Recursively set the specified file attributes on directory contents. This applies only when Choices:
|
selevel string | The level part of the SELinux filesystem object context. This is the MLS/MCS attribute, sometimes known as the When set to |
serole string | The role part of the SELinux filesystem object context. When set to |
setype string | The type part of the SELinux filesystem object context. When set to |
seuser string | The user part of the SELinux filesystem object context. By default it uses the When set to |
src path | Path of the file to link to. This applies only to For Relative paths are relative to the file being created ( |
state string | If If If If If If If Default is the current state of the file if it exists, Choices:
|
unsafe_writes boolean | Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target filesystem object. By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target filesystem objects, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted filesystem objects, which cannot be updated atomically from inside the container and can only be written in an unsafe manner. This option allows Ansible to fall back to unsafe methods of updating filesystem objects when atomic operations fail (however, it doesn’t force Ansible to perform unsafe writes). IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. Choices:
|
Attributes
Attribute | Support | Description |
|---|---|---|
check_mode | Support: full | Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped. |
diff_mode | Support: partial permissions and ownership will be shown but file contents on absent/touch will not. | Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode |
platform | Platform: posix | Target OS/families that can be operated against |
See Also
See also
- ansible.builtin.assemble
-
Assemble configuration files from fragments.
- ansible.builtin.copy
-
Copy files to remote locations.
- ansible.builtin.stat
-
Retrieve file or file system status.
- ansible.builtin.template
-
Template a file out to a target host.
- ansible.windows.win_file
-
Creates, touches or removes files or directories.
Examples
- 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
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key | Description |
|---|---|
dest string | Destination file/path, equal to the value passed to Returned: Sample: |
path string | Destination file/path, equal to the value passed to Returned: Sample: |
Collection links
© 2012–2018 Michael DeHaan
© 2018–2024 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ansible/builtin/file_module.html