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
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¶
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
file:
path: /etc/foo.conf
owner: foo
group: foo
mode: '0644'
- name: Give insecure permissions to an existing file
file:
path: /work
owner: root
group: root
mode: '1777'
- name: Create a symbolic link
file:
src: /file/to/link/to
dest: /path/to/symlink
owner: foo
group: foo
state: link
- name: Create two hard links
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)
file:
path: /etc/foo.conf
state: touch
mode: u=rw,g=r,o=r
- name: Touch the same file, but add/remove some permissions
file:
path: /etc/foo.conf
state: touch
mode: u+rw,g-wx,o-rwx
- name: Touch again the same file, but dont change times this makes the task idempotent
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
file:
path: /etc/some_directory
state: directory
mode: '0755'
- name: Update modification and access time of given file
file:
path: /etc/some_file
state: file
modification_time: now
access_time: now
- name: Set access time based on seconds from epoch value
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
file:
path: /etc/foo
state: directory
recurse: yes
owner: foo
group: foo
- name: Remove file (delete file)
file:
path: /etc/foo.txt
state: absent
- name: Recursively remove directory
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