Skip to content

NFSv4 ACLs and permissions: making fine-grained access work end to end

Configure NFSv4 ACLs on Linux, understand how POSIX mode bits and v4 ACEs interact, and avoid the "nobody:nogroup" trap that breaks ownership across the wire.

NFSv4 introduced a richer ACL model than the legacy POSIX mode bits — an Access Control Entry can grant or deny a dozen distinct rights, inherit down a directory tree, and apply to user names rather than UIDs. The catch is that the kernel still computes effective access using the mode bits when both are present, the client toolchain (nfs4_setfacl, nfs4_getfacl) is separate from getfacl/setfacl, and the underlying filesystem on the server has to be ext4 or XFS with the matching ACL support. This article documents the model and the commands we use when a client asks for “group A can read but only the owner can delete” semantics over NFS.

How to verify

# Server: confirm the export filesystem supports ACLs
tune2fs -l /dev/sda1 | grep -i 'default mount options'
mount | grep '/srv/nfs'

# Client: install nfs4-acl-tools
sudo apt install -y nfs4-acl-tools acl

# See the v4 ACL on an exported path
nfs4_getfacl /mnt/uploads/report.pdf
nfs4_getfacl -v /mnt/uploads/

# Compare with the POSIX view (mode bits + POSIX ACL)
getfacl /mnt/uploads/report.pdf
stat /mnt/uploads/report.pdf

What’s happening

NFSv4 ACEs come in four types: A (allow), D (deny), U (audit), L (alarm). The format is type:flags:principal:permissions — for example A::alice@example.com:rwadtTnNcCy grants Alice nearly every operation. Principals are strings, mapped to local UIDs by idmapd on both ends. Inheritance is controlled by flags like f (file inherit) and d (directory inherit), so a directory ACL with A:fd:devs@example.com:rwadtTnNcCy propagates the right to new files and subdirectories the way Windows ACLs do — a relief if you’re coming from CIFS and tired of the POSIX +t sticky-bit gymnastics.

What confuses everyone the first time is how mode bits interact. The Linux kernel computes effective access as the intersection of the mode bits and the ACL — if chmod 600 says only owner can read, no NFSv4 ACE will let group X read. The Linux NFS client also synthesizes POSIX permissions from the v4 ACL when applications ask via stat(), and that synthesis is lossy — a complex ACL can still report as rwxrwxrwx to ls, which is correct but unhelpful. Treat the v4 ACL as the source of truth and use nfs4_getfacl when you actually need to know who has access.

The nobody:nogroup failure mode is the second-most-common ticket on NFSv4: a file owned by alice:devs on the server appears as nobody:nogroup on the client, even though id alice returns the same UID on both. That’s an idmapd problem, not a permission problem. The protocol carries owners as strings (alice@example.com), and if the client and server disagree on the domain — example.com vs example.internal — idmapd can’t resolve the string, falls back to nobody, and the file looks ownerless. Setting Domain identically in /etc/idmapd.conf on both sides is the fix; nfsidmap -c flushes the kernel keyring without remounting.

The procedure

  1. On the server, ensure the underlying filesystem is mounted with ACL support. For ext4 and XFS the kernel default is acl,user_xattr on modern distros; verify with mount | grep nfs and add acl to /etc/fstab if absent. Restart nfs-server after changes.

  2. Install the v4 ACL tooling on every client that needs to write ACLs:

    sudo apt install -y nfs4-acl-tools
  3. Set a baseline ACL on a directory using mode bits, then layer v4 ACEs:

    sudo chmod 770 /mnt/uploads
    nfs4_setfacl -a 'A:fd:OWNER@:rwaDdxtTnNcCy' /mnt/uploads
    nfs4_setfacl -a 'A:fd:GROUP@:rwaDdxtTnNcCy' /mnt/uploads
    nfs4_setfacl -a 'A:fd:EVERYONE@:rxtncy' /mnt/uploads
    nfs4_setfacl -a 'A:fd:devs@example.internal:rwaDdxtTnNcCy' /mnt/uploads
  4. To remove a single ACE:

    nfs4_getfacl /mnt/uploads
    nfs4_setfacl -x 'A:fd:contractors@example.internal:rxtncy' /mnt/uploads
  5. Edit interactively (opens $EDITOR with the current ACL serialized):

    nfs4_editfacl /mnt/uploads
  6. For “group can read but only owner can delete,” combine an allow with a deny:

    nfs4_setfacl -a 'A:fd:devs@example.internal:rxtncy' /mnt/uploads
    nfs4_setfacl -a 'D:fd:devs@example.internal:Dd' /mnt/uploads
  7. To bulk-apply on existing content, walk the tree:

    find /mnt/uploads -type d -exec nfs4_setfacl -a 'A:fd:devs@example.internal:rwaDdxtTnNcCy' {} \;
    find /mnt/uploads -type f -exec nfs4_setfacl -a 'A::devs@example.internal:rwaDdxtTnNcCy' {} \;

Common pitfalls

  • ACLs propagated via inherit flags (fd) only apply to new files; existing files keep their old ACL. You have to walk the tree after a change.
  • nfs4_setfacl rejects an ACL that doesn’t include explicit OWNER@ and GROUP@ entries on Linux servers — write the full set, don’t try to patch in a single ACE.
  • A D (deny) ACE evaluated before an A (allow) ACE wins. Reorder with nfs4_editfacl if a deny is masking access you intended.
  • Client-side caching: the Linux NFS client caches ACL state for 60 seconds by default. After a change, either wait or unmount/remount to see the new ACL on existing handles.
  • If nfs4_getfacl returns “Operation not supported,” the export is being served as NFSv3 or the underlying filesystem doesn’t have ACL support — check nfsstat -m on the client.

In the engagements we run, NFSv4 ACLs become important when the application has a multi-tenant access model and the team is unwilling to push permissions into the application layer. We script the ACL definitions in Ansible, treat them as code, and audit them on a schedule to catch drift — the same way we manage other layered security controls. When the access model gets complex enough that this article feels short, the better answer is usually to move the directory off NFS and into an object store with bucket policies — but that’s a refactor, not a configuration change.