NFS4_ACL(5)

💖 NFS4_ACL(5) — NFSv4 Access Control Lists 💖

okay bestie, welcome to the manual page for nfs4_acl, aka NFSv4 Access Control Lists. this is section 5 of the manual, and it's literally the lore drop for how NFSv4 permissions work. grab a snack, we're going in 🍓

---

✨ NAME ✨

nfs4_acl — NFSv4 Access Control Lists 🎀

---

🌸 DESCRIPTION 🌸

so, an ACL is a list of permissions attached to a file or directory, and it's made of one or more Access Control Entries (ACEs, for short). NFSv4 ACLs are way more granular than the basic POSIX read/write/execute situation, and honestly? they're giving CIFS ACLs. cousins fr fr 💅

a sample NFSv4 file ACL could look like this (the ACL FORMAT section below has the full deets):

A::OWNER@:rwatTnNcCy
A::alice@nfsdomain.org:rxtncy
A::bob@nfsdomain.org:rwadtTnNcCy
A:g:GROUP@:rtncy
D:g:GROUP@:waxTC
A::EVERYONE@:rtncy
D::EVERYONE@:waxTC

some observations, bestie, let's break it down 👑

• in that example output up there, the user alice@nfsdomain.org has the equivalent of "read" and "execute" permissions, bob@nfsdomain.org has "read" and "write", and both GROUP@ and EVERYONE@ have "read".
• NFSv4 ACLs are "default-deny" — meaning if a permission is not explicitly granted by an Allow ACE, it's denied. periodt. because of that, those two Deny ACEs above are literally superfluous and the server could just exclude them. the A WARNING ABOUT DENY ACES section has more on this, go read it i'm begging 🙈
• NFSv4 servers may hand you back an ACL that's slightly different from the one you set. for example, a server that always allows reading a file's attributes might silently turn on the read-attributes permission, and a server that doesn't support separate write-data and append-data permissions might, say, turn both off if you set only one. in extreme cases the server might even reorder or combine ACEs 😭 as a general rule though, servers will try to make sure the ACLs they return are no more permissive than the ones you set. so like, they won't hand you more power than you asked for.

---

🌈 ACL FORMAT 🌈

an NFSv4 ACL is written as an acl_spec, which is a comma- or tab-delimited string made of one or more ace_specs. a single NFSv4 ACE is written as an ace_spec, which is a colon-delimited, 4-field string in this exact format:

type:flags:principal:permissions

---

💫 ACE TYPES 💫

there are four types of ACEs, each one represented by a single character. an ACE must have exactly one type. no mixing and matching, bestie.

• A — Allow — allow principal to perform actions requiring permissions.
• D — Deny — prevent principal from performing actions requiring permissions.
• U — Audit — log any attempted access by principal which requires permissions. requires one or both of the successful-access and failed-access flags. system-dependent; not supported by all servers. 😔
• L — Alarm — generate a system alarm at any attempted access by principal which requires permissions. requires one or both of the successful-access and failed-access flags. system-dependent; not supported by all servers. 🚨

---

🦋 ACE FLAGS 🦋

there are three kinds of ACE flags: group, inheritance, and administrative. an Allow or Deny ACE may contain zero or more flags, while an Audit or Alarm ACE must contain at least one of the successful-access and failed-access flags. no flag, no audit, that's the rule 💀

quick note before we go any further: ACEs are inherited from the parent directory's ACL at the time a file or subdirectory is created. so inheritance flags can only be used in ACEs inside a directory's ACL (and are therefore stripped from inherited ACEs in a new file's ACL). the INHERITANCE FLAGS COMMENTARY section below has the whole story, go look 🫶

GROUP FLAG — can be used in any ACE

• g — group — indicates that principal represents a group instead of a user.

INHERITED FLAG — can be used in any ACE

• I — inherited — indicates that the ACE was inherited from the parent directory. this flag can only be used with the NFSv4.1 protocol or newer when using the --dacl or --sacl options.

INHERITANCE FLAGS — can be used in any directory ACE

• d — directory-inherit — newly-created subdirectories will inherit the ACE.
• f — file-inherit — newly-created files will inherit the ACE, minus its inheritance flags. newly-created subdirectories will inherit the ACE; if directory-inherit is not also specified in the parent ACE, inherit-only will be added to the inherited ACE.
• n — no-propagate-inherit — newly-created subdirectories will inherit the ACE, minus its inheritance flags.
• i — inherit-only — the ACE is not considered in permissions checks, but it is heritable; however, the inherit-only flag is stripped from inherited ACEs.

ADMINISTRATIVE FLAGS — can be used in Audit and Alarm ACEs

• S — successful-access — trigger an alarm/audit when principal is allowed to perform an action covered by permissions.
• F — failed-access — trigger an alarm/audit when principal is prevented from performing an action covered by permissions.

---

👑 ACE PRINCIPALS 👑

a principal is either a named user (like myuser@nfsdomain.org) or a group (only if the group flag is also set), or one of three special principals: OWNER@, GROUP@, and EVERYONE@:

• OWNER@ matches the file's owner
• GROUP@ matches the file's group
• EVERYONE@ — always matches. (note this is different from the "other" used in mode bits or POSIX ACLs, which does not match the file's owner or group. important distinction, don't get got 💅)

---

💅 ACE PERMISSIONS 💅

there's a whole buffet of ACE permissions — 13 for files, 14 for directories — each represented by a single character. an ACE should have one or more of the following permissions specified:

• r — read-data (files) / list-directory (directories)
• w — write-data (files) / create-file (directories)
• a — append-data (files) / create-subdirectory (directories)
• x — execute (files) / change-directory (directories)
• d — delete — delete the file/directory. some servers will allow a delete to occur if either this permission is set in the file/directory or if the delete-child permission is set in its parent directory.
• D — delete-child — remove a file or subdirectory from within the given directory (directories only)
• t — read-attributes — read the attributes of the file/directory.
• T — write-attributes — write the attributes of the file/directory.
• n — read-named-attributes — read the named attributes of the file/directory.
• N — write-named-attributes — write the named attributes of the file/directory.
• c — read-ACL — read the file/directory NFSv4 ACL.
• C — write-ACL — write the file/directory NFSv4 ACL.
• o — write-owner — change ownership of the file/directory.
• y — synchronize — allow clients to use synchronous I/O with the server.

---

🧚 INHERITANCE FLAGS COMMENTARY 🧚

okay so inheritance flags split into two little categories: "primary" (file-inherit and directory-inherit) and "secondary" (no-propagate-inherit and inherit-only). the secondary ones only really matter in terms of how they affect the two "primary" flags. they're the supporting cast, but they're highkey important.

the no-propagate-inherit and inherit-only flags can be tricky to keep straight: the former determines whether or not a new child directory's inherited ACE is itself heritable by a grandchild subdirectory; the latter determines whether or not a heritable ACE affects the parent directory itself (in addition to being heritable). they can be used in-tandem, bestie. duo goals fr fr ✨

when a subdirectory inherits an ACE from its parent directory's ACL, it can go down one of two paths, depending on the server implementation:

• in the simple case, that exact same ACE is set in the subdirectory's ACL.
• in the other case, two different ACEs get set in the subdirectory's ACL instead: one with all inheritance flags removed, and one with the inherit-only flag added. the former is the "effective" inherited ACE (used in the subdirectory's own permissions checks); the latter is the "heritable" inherited ACE (so when the subdirectory has directories created within it, they inherit it). this approach makes it easier to modify access rights to the subdirectory itself without modifying its heritable ACEs. the Linux kernel server uses this approach. 🐧

---

🚨 A WARNING ABOUT DENY ACES 🚨

Deny ACEs should be avoided whenever possible. they are technically a valid part of NFSv4 ACLs, but Deny ACEs can be confusing and complicated, and honestly they're a whole mess. this comes mainly from the fact that — unlike POSIX ACLs and CIFS ACLs — the ordering of ACEs within NFSv4 ACLs affects how they're evaluated. order matters. it's giving plot twist 💀

first things first, it's important to note that (despite some unfortunate ambiguity in RFC3530) NFSv4 ACLs are "default-deny" in practice. that is, if a permission is not explicitly granted, it is denied. no permission for you, periodt.

in general, when a principal is attempting to perform an action over NFSv4 which requires one or more permissions, an access check happens. the NFSv4 ACL (assuming one is present) is evaluated ACE-by-ACE until every one of those permissions has been addressed, or until the end of the ACL is reached. if every requisite permission was granted by Allow ACEs and was not forbidden by Deny ACEs (see next paragraph), the action is allowed to proceed. otherwise, the action is forbidden. simple as that 🎀

note that each requisite permission is only addressed once — that is, after a permission has been explicitly Allowed or Denied once during an access check, any subsequent ACEs in the ACL which affect that permission are no longer considered. this often introduces problematic ordering issues when Deny ACEs are present. 😭

additionally, in some cases Group-Deny ACEs can be difficult (if not impossible) to enforce, since a server might not know about all of a given principal's memberships in remote groups, e.g. 🙈

because NFSv4 ACLs are "default-deny", the use of Deny ACEs can (and should) be avoided entirely in most cases. just don't, bestie. save yourself the pain 💖

---

💜 AUTHORS 💜

the tools for viewing and manipulating NFSv4 ACLs, nfs4_getfacl and nfs4_setfacl, were written by people at CITI, the Center for Information Technology Integration (http://www.citi.umich.edu). this manpage was written by David Richter and J. Bruce Fields. legends, honestly 👑

---

📬 CONTACT 📬

please send bug reports, feature requests, and comments to <nfsv4@linux-nfs.org>. they wanna hear from you, fr fr 🫶

---

🌟 SEE ALSO 🌟

• nfs4_getfacl(1)
• nfs4_setfacl(1)
• RFC3530 (NFSv4.0)
• NFSv4.1 Minor Version Draft

---

and that's the whole page, bestie 💖 this one's from the Linux crew — version 0.3.4, August 2018 — and it's the NFS4_ACL(5) manual page, section 5, so you know it's the real deal. slay, go set some ACLs responsibly, and remember: no Deny ACEs unless you absolutely have to 🌸✨💅