← Full reference

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

EntryFor whom
u:alice:rwuser alice (u = user)
g:devs:rgroup devs (g = group)
u::rwx / g::r / o::-owner / owning group / others (same as chmod)
m::rwthe mask — the ceiling on permissions for all entries except owner and others
d:u:alice:rwxa 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

OptionWhat it does
-m entriesadd or modify entries
-x entriesremove entries
-bremove the whole extended ACL, keep regular permissions
-kremove only the directory's default ACL
-dapply -m/-x to the default ACL (inherited by new files)
-Rrecursively through a directory
--set entriesreplace the ACL entirely; u::, g::, o:: are required
-M file / -X fileread entries for -m / -x from a file (- — stdin)
--restore=filerestore ACLs from getfacl -R output
-ndon't recalculate the mask
--testshow what the result would be without changing anything
-L / -Pwith -R: follow / don't follow symbolic links

getfacl options

OptionWhat it does
-cno # file / # owner / # group header
-Rrecursively
-a / -donly the access ACL / only the default ACL
-sskip files without an extended ACL — find where ACLs exist at all
-nnumbers instead of user and group names
-e / -Eshow #effective on all entries / never show it
-pdon't strip the leading / from paths
-ttabular 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

  • chmod changes the mask. On a file with an ACL, chmod g-w or chmod 600 cuts 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 x on directories there is no access. Permission on a file is useless if the user can't enter the directory: you need at least x on 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 0644 gets the mask rw-, so rwx from the default ACL becomes #effective:rw-. That's by design: regular files don't become executable.
  • cp without -p/-a loses ACLs — the copy won't have a +. mv within one filesystem keeps them. tar keeps 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 -R strips the leading / from paths, so --restore applies the paths relative to the current directory.

See also

chmod · chown · umask · ls · capabilities · cp