file_access_control_list
An access control list gives named accounts and groups access to a file or
directory beyond its owner, group, and mode. file_access_control_list
manages the named account and group entries of one file's or directory's
list, through getfacl and setfacl on the node. Use file or
directory to set the owner, group, and mode of the file or
directory.
Set up
getfacl and setfacl are in the package acl. Install acl in an earlier
node task when the node lacks acl:
- when: {equals: ["{{ .node.package_manager }}", apt]}
apt_package: {packages: [{name: acl, version: newest_when_first_installed}]}
- when: {equals: ["{{ .node.package_manager }}", dnf]}
dnf_package: {packages: [{name: acl, version: newest_when_first_installed}]}
Inputs
path(string; required): absolute; must exist and must not be a symbolic linkentries(list; optional): each {user_account: name, permissions: r-x} or {group: name, permissions: r-x}; exactly one of user_account or group; permissions are r or -, w or -, then x or -; required unless state: absententries_not_listed(removeorkeep; optional): required with entries; remove makes entries the whole list of named accounts and groups, and entries: [] removes them all; keep adds or corrects the listed entries onlyalso_apply_to_everything_inside(boolean; defaultfalse): directories only: the same entries for every file and directory below path; symbolic links inside are skippedalso_use_for_new_files_inside(boolean; defaultfalse): directories only: also sets the entries as the directory's default entries, which new files and directories inside inheritstate(presentorabsent; defaultpresent): absent removes every named entry and accepts only path and the two also_ settings
Outputs
The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.
statuschangevalue.addedvalue.updatedvalue.removedvalue.number_of_paths_changed
What a dryrun reports
Supported; lists the entries to add, update, or remove; not checked while the acl package, the path, or a named account is missing.
Retries and time limits
Bounded automatic retries by default; retry: false turns them off.
The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.
Examples
Let a log shipper read an application's logs
A log shipper that runs as its own account can read an application's logs without joining the application's group:
- file_access_control_list:
path: /var/log/myapp
entries:
- {user_account: promtail, permissions: r-x}
- {group: support, permissions: r-x}
entries_not_listed: remove
also_apply_to_everything_inside: true
also_use_for_new_files_inside: true
On the node, MMX reads the list of /var/log/myapp and of every file and
directory below it. It gives the account promtail and the group support
read access, and removes every other named entry, because
entries_not_listed is remove. Because also_use_for_new_files_inside
is true, the same entries also become the directory's default entries,
which files created inside later inherit, such as tomorrow's log file.
The group bits of the directory's permissions_mode limit what the named
entries allow (the list's mask). setfacl -m recalculates that mask to
include the entries' permissions. The directory's group mode bits can change
from 0700 to 0750 when a named entry gets r-x.
Remove every named entry
- file_access_control_list:
path: /var/log/myapp
also_apply_to_everything_inside: true
also_use_for_new_files_inside: true
state: absent
state: absent removes every named entry. With
also_use_for_new_files_inside: true, MMX also removes named default entries
and clears the remaining default entries. A default list without named
entries stays unchanged.
How it works
- Each entry names exactly one of
user_accountorgroup, withpermissionswritten asgetfaclprints them:ror-,wor-, thenxor-. entries_not_listedis required:removemakes the listed entries the whole list of named accounts and groups, andkeepadds or corrects the listed ones only.also_apply_to_everything_inside: truegives every file and directory belowpaththe entries listed inentries.also_use_for_new_files_inside: truealso makes the entries listed inentriesthe directory's default entries, which files and directories created inside later inherit.also_apply_to_everything_insideandalso_use_for_new_files_insideare for directories only.- MMX refuses a symbolic link at the path, and it never follows a symbolic link inside a directory.
- Dryrun and results list the entries in
value.added,value.updated, andvalue.removed, such asuser_account promtail: r-x, and withalso_apply_to_everything_insidethe number of paths that change invalue.number_of_paths_changed. A run that fails lists only the entries that itssetfaclcalls changed before the failure, so a node task inon_failurecan read what happened.
Errors and what they mean
| The reason holds | What the error means, and what to do |
|---|---|
setfacl is not installed; install the package acl first |
Install the package in an earlier node task; see Set up. The same holds for getfacl. A dryrun reports the node task not checked, because an earlier node task may install the package. |
/var/log/myapp does not exist yet |
The path is missing. A dryrun reports the node task not checked, because an earlier node task may create it. A missing account or group is treated the same way. |
... is a symbolic link; give the path of the file or directory itself |
MMX refuses a symbolic link at the path. Write the path of the file or directory itself. |
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.
The suite tests/integration/access_control_lists_and_capabilities.py runs
on Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, and AlmaLinux 10, in containers on the first four and in virtual machines on the last two. The validation
record has the latest results.
Why it works this way
setfacl -m recalculates the mask from the access entries. A restrictive
starting mode therefore does not prevent the requested named access.
This page is docs/reference/modules/file_access_control_list.md in the MMX repository.