file and the meaning of state · Ansible

ansible.builtin.file does not write file contents. It manages everything around the contents: existence, type, ownership, permissions, SELinux context, timestamps, and extended attributes. One option decides which of those operations you get.

Read-only / Safethe documented choices— Executed against ansible-core 2.21.3. Six values, and the module's behaviour differs completely between them.

$ ansible-doc ansible.builtin.file | grep -A2 'choices:'

        choices: [absent, directory, file, hard, link, touch]
      default: null
      type: str

Read that list as six verbs, not six adjectives.

`state`	Operation	Creates?	Can destroy?
`file`	Set attributes on an existing path	No	No
`directory`	Create the path and all intermediate directories	Yes	No
`link`	Create or repoint a symbolic link	Yes	With `force`
`hard`	Create or change a hard link	Yes	With `force`
`touch`	Create empty, or update access and modification times	Yes	No
`absent`	Unlink a file or link; recursively delete a directory	No	Yes

`state: file` does not create a file

This is the one that surprises people, and the documentation is blunt about it:

If file, even with other options (such as mode), the file will be modified if it exists but will NOT be created if it does not exist. Set to touch or use the ansible.builtin.copy or ansible.builtin.template module if you want to create the file if it does not exist.

The task fails if the path is missing. That is deliberate: state: file means “this path is a regular file and has these attributes”, and a missing path cannot satisfy that with an empty file you never asked for.

state: file to fix permissions on a file that may not be there

A common remediation task reads:

- name: Lock down the token file
  ansible.builtin.file:
    path: /etc/app/token
    owner: appsvc
    group: appsvc
    mode: '0600'
    state: file

On the hosts where the file exists, it does the right thing. On the hosts where the application has not run yet, the task fails — and because it fails rather than skipping, a rolling run stops. The diagnosis “the permissions task failed” sends people looking at permissions; the cause is a missing path.

If the file is genuinely optional, stat it first and guard the task with when. If it should always exist, the module that creates it — copy or template — should be setting the mode, and this task should not exist at all.

`directory` and what `recurse` covers

state: directory creates every intermediate directory, like mkdir -p, and applies the supplied permissions to the ones it creates. recurse: true extends the attribute application to the directory’s existing contents — and the documentation constrains it tightly:

Recursively set the specified file attributes on directory contents. This applies only when state is set to directory.

Two consequences worth stating plainly.

recurse never deletes anything. It is not rsync --delete. Files in the directory that your automation did not create keep existing; they just acquire your ownership and mode.

recurse applies one mode to files and directories alike. That is usually wrong. mode: '0644' on a recursed tree strips the execute bit from every directory, which makes the directory untraversable. The symbolic form solves it, because capital X sets the execute bit only where it is already set on something, or on directories.

Configuration changerecursive permissions that do not break directories— Capital X in the symbolic mode sets execute on directories and on files that were already executable, and leaves plain files alone.

# Wrong: 0644 on a tree makes every directory non-traversable.
- name: Fix ownership of the app tree
ansible.builtin.file:
  path: /opt/app
  state: directory
  owner: appsvc
  group: appsvc
  mode: '0644'
  recurse: true

# Right: u=rwX,g=rX,o= - the capital X only touches directories and
# files that already carried an execute bit.
- name: Fix ownership of the app tree
ansible.builtin.file:
  path: /opt/app
  state: directory
  owner: appsvc
  group: appsvc
  mode: u=rwX,g=rX,o=
  recurse: true

`link`, `hard`, and `force`

state: link creates a symbolic link at path pointing at src. The option that decides how aggressive it is:

force: Force the creation of the links in two cases: if the link type is symbolic and the source file does not exist (but will appear later); the destination exists and is a file (so, we need to unlink the path file and create a link to the src file in place of it).

That second clause is the one to read twice. force: true will unlink a real file and replace it with a symlink. That is exactly what you want when converting a config file into a link to a shared one, and exactly what you do not want when the path was a real file holding data.

Configuration changethe release-directory symlink pattern— Repointing a current symlink is the atomic step in a deploy. force is needed only if the path might currently be a directory or a file rather than a link.

- name: Point current at the new release
ansible.builtin.file:
  src: /opt/app/releases/{{ app_release }}
  dest: /opt/app/current
  state: link
  owner: appsvc
  group: appsvc
notify: Reload the application

follow interacts with this and defaults to true on the file module. With follow: true and state: link, setting mode can modify the target of the link rather than the link itself, which the documentation names explicitly. When you are creating a link to a destination that does not exist yet, set follow: false to avoid the permission warning the module raises about a path it cannot stat.

Under the hood

link and hard differ in what the filesystem stores, and the difference decides how each behaves when things move.

A symbolic link is a small file whose contents are a path. Resolution happens at every access, so the link survives its target being replaced — which is what makes the current symlink pattern work for deploys. It also means the link can dangle, and it can cross filesystems.

A hard link is a second directory entry pointing at the same inode. There is no “original”; both names are equal, the data lives until the last name is unlinked, and the link cannot cross a filesystem boundary because inode numbers are per-filesystem.

The operational consequence: state: hard on a config file means an edit through either path changes both, and state: absent on one of them leaves the data intact under the other. stat reports this directly — nlink above 1 means another name exists somewhere, and nothing in the playbook tells you where.

`absent`, and the size of the hole it makes

state: absent is the only value on this module that destroys data, and what it destroys depends on what the path turned out to be:

If absent, directories will be recursively deleted, and files or symlinks will be unlinked.

A templated path that resolves one level higher than intended does not fail — it succeeds, recursively, and reports changed. There is no confirmation and no --force gate.

The module also documents that absent does not fail when the path does not exist, because the state did not change. That is correct idempotency and it also means a typo in the path is invisible: the task reports ok forever against a path that was never there.

A variable in an absent path is a fleet-wide delete waiting for an empty string

- name: Remove the old release
  ansible.builtin.file:
    path: /opt/app/releases/{{ old_release }}
    state: absent

If old_release is undefined the task fails, which is safe. If it is defined and empty, the path becomes /opt/app/releases/ and the module recursively deletes every release on every host in the play.

Guard it. An assert before any absent task with a variable in its path costs one task and turns a silent fleet-wide deletion into a failed precondition:

- name: Refuse to proceed without a specific release to remove
  ansible.builtin.assert:
    that:
      - old_release is defined
      - old_release | length > 0
      - old_release is match('^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-f0-9]{7}$')
    fail_msg: old_release must be a full release identifier

Part XXIV builds this into a general pattern. The instance that matters most is this one.

`touch` and the check-mode footnote

state: touch creates an empty file if the path is missing, and updates the access and modification times if it is not. Because updating a timestamp is a change by definition, a touch task reports changed on every run unless you constrain it with modification_time: preserve and access_time: preserve.

That perpetual changed is not cosmetic. It notifies handlers, it inflates the change count an auditor reads, and it means a run that should have been quiet never is. If you are using touch to create a log file, copy with content: '' and force: false states the intent better and stays ok.

Verifying the result

Whatever the play claims, stat on the host is the fact. It is read-only and it is the right first move in any diagnosis.

Read-only / Safewhat the path actually is— Read-only. islnk, isdir and isreg are mutually exclusive; lnk_target is populated only for a symlink.

ansible -i inventories/prod app -m ansible.builtin.stat \
-a "path=/opt/app/current follow=false" \
| grep -E '"islnk"|"isdir"|"isreg"|"lnk_target"|"nlink"|"mode"'

Read-only / Safea symlink, and a directory pretending to be one— Illustrative. The second host had the deploy fail halfway and left a real directory where the link should be; the play that only set state: link without force would report ok on the first and fail on the second.

$ ansible -i inventories/prod app -m ansible.builtin.stat -a 'path=/opt/app/current follow=false'

app01.example.com | SUCCESS => {
  "stat": {
      "islnk": true,
      "isdir": false,
      "lnk_target": "/opt/app/releases/2026-08-04-9f3c1ab",
      "mode": "0777"
  }
}
app02.example.com | SUCCESS => {
  "stat": {
      "islnk": false,
      "isdir": true,
      "mode": "0755"
  }
}

Illustrative output

The 0777 on the symlink is normal and not a finding: on Linux, symlink permission bits are not consulted, and stat reports them as 0777. The finding is app02, where islnk is false.

state: file does not create a file

directory and what recurse covers

link, hard, and force

absent, and the size of the hole it makes

touch and the check-mode footnote