ansible.builtin.file – Manage files and file properties¶
Note
This module is part of ansible-base and included in all Ansible
installations. In most cases, you can use the short module name
file even without specifying the collections: keyword.
Despite that, we recommend you use the FQCN 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, symlinks or directories.
Alternatively, remove files, symlinks or directories.
Many other modules support the same options as the
filemodule - including ansible.builtin.copy, ansible.builtin.template, and ansible.builtin.assemble.For Windows targets, use the ansible.windows.win_file module instead.
Parameters¶
See Also¶
See also
- ansible.builtin.assemble
The official documentation on the ansible.builtin.assemble module.
- ansible.builtin.copy
The official documentation on the ansible.builtin.copy module.
- ansible.builtin.stat
The official documentation on the ansible.builtin.stat module.
- ansible.builtin.template
The official documentation on the ansible.builtin.template module.
- ansible.windows.win_file
The official documentation on the ansible.windows.win_file module.
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:
Authors¶
Ansible Core Team
Michael DeHaan