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 |
|---|---|
This parameter indicates the time the file’s access time should be set to. Should be Default is |
|
When used with Based on default Python format (see time.strftime doc). Default: |
|
The attributes the resulting filesystem object should have. To get supported flags look at the man page for This string should contain the attributes in the same order as the one displayed by The |
|
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:
|
|
Name of the group that should own the filesystem object, as would be fed to 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. |
|
The permissions the resulting filesystem object should have. For those used to 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 |
|
This parameter indicates the time the file’s modification time should be set to. Should be Default is None meaning that |
|
When used with Based on default Python format (see time.strftime doc). Default: |
|
Name of the user that should own the filesystem object, as would be fed to 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 to the file being managed. |
|
Recursively set the specified file attributes on directory contents. This applies only when Choices:
|
|
The level part of the SELinux filesystem object context. This is the MLS/MCS attribute, sometimes known as the When set to |
|
The role part of the SELinux filesystem object context. When set to |
|
The type part of the SELinux filesystem object context. When set to |
|
The user part of the SELinux filesystem object context. By default it uses the When set to |
|
Path of the file to link to. This applies only to For Relative paths are relative to the file being created ( |
|
If If If If If If If Default is the current state of the file if it exists, Choices:
|
|
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 |
|---|---|---|
Support: full |
Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped. |
|
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: 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 |
|---|---|
Destination file/path, equal to the value passed to Returned: Sample: |
|
Destination file/path, equal to the value passed to Returned: Sample: |