Grant a Named User File Access with Linux ACLs

setfacl and getfacl let you hand one extra user access to a file without touching its owner, group or the rest of the permission bits. You will finish with a file that keeps its normal permissions while granting one additional user access through a POSIX access control list, inspect the effective permissions, apply a directory default ACL for new files, and remove the changes without guessing.

Allow about 15 minutes. You need the acl package, which provides getfacl and setfacl. The examples below were checked with acl package version 2.3.2-1build1.1. Use an existing test file or a disposable directory first. Do not experiment on a production tree until you have confirmed which users and groups should receive access.

1. Inspect the existing permissions

Choose a real path and read its current ACL. Replace /srv/project/report.txt with the file you want to inspect. This is an ordinary, read-only command:

$ getfacl -p /srv/project/report.txt
# file: /srv/project/report.txt
# owner: project-owner
# group: project
user::rw-
group::r--
other::---

The three entries beginning with user::, group:: and other:: are the owner, owning group and everyone else. The -p option keeps the absolute path in the header. The header names will differ on your machine, so compare the entries rather than copying this output literally.

Checkpoint: confirm the file is the intended target and note its current ACL before changing anything. A plus sign after the mode in ls -l is a useful hint that an extended ACL exists:

$ ls -l /srv/project/report.txt
$ getfacl -p /srv/project/report.txt

2. Add a named-user entry

Replace alice with an existing local user and use setfacl -m to modify the file's ACL. This normally requires the file owner or an appropriately privileged administrator:

$ setfacl -m u:alice:rw /srv/project/report.txt
$ getfacl -p /srv/project/report.txt
# file: /srv/project/report.txt
# owner: project-owner
# group: project
user::rw-
user:alice:rw-
group::r--
mask::rw-
other::---

The u:alice:rw text has three parts: a user entry, the account qualifier, and the read/write permissions. The command adds or replaces that user's entry; it does not replace the rest of the ACL. Because this is now an extended ACL, a mask:: entry appears. The mask limits named users, named groups and the owning group. It does not limit the file owner or other.

The output above is an example, not a promise about your original mode. If alice does not exist, use getent passwd alice to check the name before retrying. A numeric user ID can be used instead, for example u:1007:rw, but names are easier to review.

3. Check the effective permission

An ACL entry can request more access than the mask permits. Ask getfacl to show effective rights:

$ getfacl -e -p /srv/project/report.txt
user::rw-
user:alice:rw-
group::r--
mask::rw-
other::---

If the mask were r--, the named-user line would be displayed with an annotation such as #effective:r--, even if the stored entry says rw-. That is a common ACL trap: the named entry is not the final answer. Access checks also depend on the process identity and supplementary groups, and the owner entry is checked before named users.

To demonstrate the mask without changing a real file, use a disposable copy or test directory. The following command deliberately reduces the maximum permissions available to group-related entries and named users:

$ setfacl -m m:r /srv/project/report.txt
$ getfacl -e -p /srv/project/report.txt
user:alice:rw-          #effective:r--

Recovery: restore the intended mask with setfacl -m m:rw if the reduced access was only a test. Do not assume that adding w to a named-user entry can bypass a restrictive mask.

4. Apply access to a directory tree carefully

For a directory, the ACL on the directory controls access to that directory itself. A user also needs search permission, shown as x, to reach entries below it. If you want Alice to work with existing contents, decide whether the change should be recursive before using -R:

$ setfacl -R -m u:alice:rwX /srv/project
$ getfacl -p /srv/project

The uppercase X grants execute/search only where the target is a directory or already has execute permission. It avoids making every ordinary data file executable. Recursive changes can affect a large number of files and may expose more data than intended, so list the target first and take an ACL backup if the tree matters.

Before a broad change, save the current ACLs:

$ getfacl -R -p /srv/project > project.acls

The output can be restored with the matching utility:

$ setfacl --restore=project.acls

Security warning: treat the backup as security-sensitive: it contains paths, owners, groups and permissions. Keep it protected and remove it only when your normal retention policy allows.

5. Set permissions for files created later

An access ACL affects the object it is attached to. To give new files and directories an initial ACL, add a default ACL to their parent directory. This changes future object creation in that directory, so check the scope first:

$ setfacl -m d:u:alice:rwX,d:m:rwX /srv/project
$ getfacl -p /srv/project
default:user::rwx
default:user:alice:rw-
default:group::r-x
default:mask::rwx
default:other::---

A default ACL must contain the base default entries as well as any named entries. setfacl fills missing required entries from the directory's access ACL where possible. The mode requested by the creating program still limits the inherited access ACL, so a default entry is not a way to override an application that deliberately creates a file without a permission.

Create a harmless test file and inspect it:

$ : > /srv/project/acl-check.txt
$ getfacl -e -p /srv/project/acl-check.txt
user::rw-
user:alice:rw-
group::r-x          #effective:r--
mask::rw-
other::---

Remove the test file only after checking the result. Deleting a file is irreversible unless you have a backup. If the directory should no longer provide defaults, remove them with the directory-specific operation:

$ setfacl -k /srv/project
$ getfacl -d -p /srv/project
getfacl: Removing leading '/' from absolute path names

The final diagnostic text may vary with the command options and version. The useful check is that no default: entries remain. Removing a default ACL does not remove access ACL entries already inherited by existing files.

6. Undo a named entry without wiping unrelated ACLs

When the extra access is no longer needed, remove only Alice's named entry:

$ setfacl -x u:alice /srv/project/report.txt
$ getfacl -p /srv/project/report.txt

For a matching directory-tree change, use the same path selection and -R carefully:

$ setfacl -R -x u:alice /srv/project

Warning: do not use setfacl -b as a general clean-up command unless you explicitly want to remove every extended ACL entry. It removes named users, named groups, the mask and any default ACLs, which can revoke legitimate access. If you used an ACL backup, setfacl --restore=project.acls is the more precise recovery path.

Done means