ACL: getfacl and setfacl
Permissions for individual users and groups beyond owner/group/other rwx; the mask and default ACLs
Regular permissions (chmod) know only three subjects: the owner, the group and everyone else. An ACL (access control list) adds entries for specific users and groups: "alice can read and write, group devs can only read". getfacl shows the ACL, setfacl changes it. Package acl; ext4, xfs, btrfs and tmpfs support ACLs by default.
Syntax
getfacl [options] file…
setfacl [options] -m entries file… # add or modify
setfacl [options] -x entries file… # remove
Entry format
| Entry | For whom |
|---|---|
u:alice:rw | user alice (u = user) |
g:devs:r | group devs (g = group) |
u::rwx / g::r / o::- | owner / owning group / others (same as chmod) |
m::rw | the mask — the ceiling on permissions for all entries except owner and others |
d:u:alice:rwx | a default ACL entry of a directory (same as -d -m u:alice:rwx) |
Permissions are written as letters rwx, - means no permission. X (capital) means x only for directories and for files that already have x for someone. Several entries are separated by commas: u:alice:rw,g:devs:r. With -x you don't give permissions: -x u:alice.
setfacl options
| Option | What it does |
|---|---|
-m entries | add or modify entries |
-x entries | remove entries |
-b | remove the whole extended ACL, keep regular permissions |
-k | remove only the directory's default ACL |
-d | apply -m/-x to the default ACL (inherited by new files) |
-R | recursively through a directory |
--set entries | replace the ACL entirely; u::, g::, o:: are required |
-M file / -X file | read entries for -m / -x from a file (- — stdin) |
--restore=file | restore ACLs from getfacl -R output |
-n | don't recalculate the mask |
--test | show what the result would be without changing anything |
-L / -P | with -R: follow / don't follow symbolic links |
getfacl options
| Option | What it does |
|---|---|
-c | no # file / # owner / # group header |
-R | recursively |
-a / -d | only the access ACL / only the default ACL |
-s | skip files without an extended ACL — find where ACLs exist at all |
-n | numbers instead of user and group names |
-e / -E | show #effective on all entries / never show it |
-p | don't strip the leading / from paths |
-t | tabular output |
Reading the output
# file: proj/f
# owner: root
# group: root
user::rw- ← owner
user:alice:rw- #effective:r-- ← alice's entry, but the mask cuts it to r--
group::r-- ← owning group
group:devs:r--
mask::r-- ← ceiling for alice, group, devs
other::---
In ls -l a file with an ACL is marked with + after the permissions: -rw-rw----+. In that case the middle permission triplet shows the mask, not the group's permissions.
The mask is the maximum permissions for named users, named groups and the owning group. The real permissions of an entry = entry permissions ∩ mask; if that is less than what's written, getfacl prints #effective:. setfacl -m recalculates the mask automatically as the union of these entries.
A default ACL exists only on a directory. It doesn't affect the directory itself but is copied into the ACL of every new file and subdirectory inside (a subdirectory also gets it as its own default — inheritance flows downward).
Examples
mkdir -p /srv/proj && echo data > /srv/proj/report.txt
# give alice read and write on one file
setfacl -m u:alice:rw /srv/proj/report.txt
getfacl /srv/proj/report.txt
# give group devs read on the whole directory; X allows entering directories but doesn't make files executable
setfacl -R -m g:devs:rX /srv/proj
# so new files get these permissions too — default ACL
setfacl -d -m g:devs:rX /srv/proj
setfacl -d -m u:alice:rwX /srv/proj
# remove alice, remove the default ACL, remove everything extended
setfacl -x u:alice /srv/proj/report.txt
setfacl -k /srv/proj
setfacl -R -b /srv/proj
# find files with ACLs
getfacl -R -s -p /srv 2>/dev/null | grep '^# file'
# save and restore the ACLs of a tree (restore from the same directory)
cd /srv && getfacl -R proj > /tmp/proj.acl
cd /srv && setfacl --restore=/tmp/proj.acl
# copy the ACL from one file to another
getfacl file1 | setfacl --set-file=- file2
Pitfalls
chmodchanges the mask. On a file with an ACL,chmod g-worchmod 600cuts the mask, and all named entries get#effective:---. The entries are still there but have no effect. Restore the mask:setfacl -m m::rw file.- Without
xon directories there is no access. Permission on a file is useless if the user can't enter the directory: you need at leastxon every directory along the path (setfacl -m u:alice:x /srv). - A default ACL doesn't touch existing files. For files already created you need a separate
setfacl -R -m …without-d. - A default ACL beats umask, but not the creation mode: a file created with
0644gets the maskrw-, sorwxfrom the default ACL becomes#effective:rw-. That's by design: regular files don't become executable. cpwithout-p/-aloses ACLs — the copy won't have a+.mvwithin one filesystem keeps them.tarkeeps ACLs only with--acls(both when creating and when extracting),rsync— with-A.- A non-existent user in an entry gives "Invalid argument near character 3" and exit code 2 — a typo in the name, not in the syntax.
getfacl -Rstrips the leading/from paths, so--restoreapplies the paths relative to the current directory.