From Linux NFS

Jump to: navigation, search


Introduction to NFSv4 ACLs

Some NFSv2 and v3 implementations support ACLs based on POSIX draft ACLs which depend on a separate rpc program (instead of being part of the NFS protocol itself).

The NFSv4 protocol includes integrated support for ACLs which are similar to those used by Windows. NFSv4 ACLs are richer than POSIX draft ACLs--any POSIX ACL can be represented by an NFSv4 ACL with almost the same semantics, whereas the reverse is not true.

Useful references:

  • rfc3530 (especially section 5.11)]
  • POSIX draft ACLs: POSIX ACLs aren't really POSIX--they were never accepted--but some variation of them is implemented on many operating systems, including Linux.
  • The Linux man pages, specifically, acl(5), setfacl(1), getfacl(1), and setxattr(2).
  • The POSIX<->NFSv4 mapping draft, which explains how we map between POSIX and NFSv4 ACLs.
  • The CITI NFSv4 project page, which has links to client tools for using NFSv4 ACLs as well as patches to libacl which allow the client to treat NFSv4 ACLs as if they were POSIX ACLs. Given the choice, we recommend the former approach, as the libacl patches are complex and affect basic utilities like "ls".
  • draft-falkner-nfsv4-acls-00.txt, which suggests some clarifications to the NFSv4 ACL specification, and addresses some issues for NFSv4 implementors on UNIXy systems, including, for example, details on interactions with chmod.

Design of the linux NFSv4 ACL implementation


None of the filesystems which the linux server exports support NFSv4 ACLs. However, many of them do support POSIX ACLs. So we map NFSv4 ACLs to POSIX ACLs and store POSIX ACLs in the filesystem. The mapping is imperfect. It accepts most NFSv4 ACLs. (The only exceptions are ACLs which explicitly deny permissions to read attributes or acls, or which explicitly deny the owner permissions to write attributes or acls.) The lossy nature of the NFSv4->POSIX mapping means that querying an ACL will almost always result in an ACL returned that is different from the one set. However, if the original ACL is representable as a POSIX ACL, then the ACL returned should represent equivalent permissions to the one set. If not, then the ACL returned should have permissions that are stricter than those requested.

The code to perform this mapping on the server side is in the kernel, in fs/nfsd/nfs4acl.c.

We could instead store NFSv4 ACLs somewhere else--say in a separate extended attribute used only by the NFSv4 server. However, this would prevent our ACLs from being enforced against local users of the same filesystem.

Work is under way to include NFSv4 ACLs in the underlying filesystem, which would solve all of the above problems at the expense of increased filesystem complexity. As of this writing, patches for production use are not yet available.


The kernel nfs client exposes ACLs on NFSv4 filesystems to userspace in the extended attribute named "system.nfs4_acl", which contains the raw xdr data which the client receives from the server as the value of the NFSv4 "acl" attribute. Writing to that attribute will modify the ACL on the server.

We have client NFSv4 ACL tools. They present NFSv4 ACLs to the user untranslated, using NFSv4 names. As a result they are usable against any NFSv4 server (even if the client doesn't know about all of the users on the server).

It is also possible to modify the client POSIX ACL tools to transparently map between POSIX and NFSv4 ACLs in userspace. This also requires mapping the names contained in the ACLs into local uid's. We have patches to libacl available which do this. However, this mapping is complex and (as on the server side) lossy. Also, the mapping of names to id's is complicated, and (in our current implementation) introduces unfortunate dependencies of basic system tools (like ls) on a great deal of unrelated NFSv4 and krb5 code. For these reasons we do not recommend this approach.

The ACL Interoperability Problem

We now have three ACL models to deal with: NFSv4, Windows, and "POSIX ACLs"/mode bits. And we have to decide what to do with them all in the face of existing users, tools, and system interfaces that assume one or the other.

More specifically:

A server has to store ACL's persistently on its filesystem. There are immense advantages to storing those ACL's using whatever ACL's the filesystem and operating system support, because that will ensure that they are automatically enforced against other applications and protocol services using the same filesystem.

Some servers are therefore translating to and from their native format. Others are implementing NFSv4 ACL's in the filesystem.

The client in theory has a simpler problem--it can always provide its own application for manipulating NFSv4 ACLs. However:

  • Some applications manipulate ACL's directly using interfaces designed for one particular ACL model (e.g. MS Office apparently does this on temporary files--other examples?)
  • Users may have experience with existing ACL models and tools, which may be better integrated into standard file managers
  • Administrators may have built up scripts that manipulate or check ACL's.

For these reasons client implementers may also want to support preexisting ACL models.

Since individual clients and applications with different ACL models may not deal well with the full generality of NFSv4 ACLs, problems may also arise from clients reading and modifying ACLs written by clients with different expectations.

ACL models

NFSv4 and Windows ACLs

NFSv4 ACLs are documented by section 5.11 of rfc3530. See msdn for Windows ACL documentation.

The two ACL models are essentially the same, with some minor differences:

  • Windows does not have the special owner, group or everyone principals in ACEs. You could handle owner and group ACEs by translating them to ACEs that refer explicitly to the current owner or group, but the result won't behave correctly under chown().
  • RFC3530 says that if an ACL neither allows nor denies a certain mode bit, then behavior is undefined. But users of Windows ACLs expect them to deny by default. (I believe NFSv4 is now specified to have Windows behavior in RFC3530bis and RFC5661?)
  • Windows documentation suggests that if some but not all requested access bits have been allowed, then DENY aces will still apply even if they only deny bits among those already allowed. This has the somewhat bizarre result that an ACL can allow certain permissions individually but deny them in combination. The NFSv4 ACL algorithm doesn't have this property. (We're waiting the results of experiments to confirm this property of Windows ACLs.)

A bigger (and perhaps more important!) difference is in the way ACEs refer to users--NFSv4 uses string names of the form user@domain, Windows uses SIDs--but we're ignoring the name-mapping issue for now.

The new OSX ACLs seem to be essentially identical to Windows ACLs; the obvious major exception being that instead of denying by default, when the ACL doesn't determine access, OSX falls back on the mode bits.

Though there is at least one proof of concept NFSv4/Windows ACL implementation for Linux, we know of no concerted effort to push native Linux support for NFSv4/Windows ACLs. However, AIX, FreeBSD, and Solaris support NFSv4 ACLs. Two Sun developers have an internet draft draft-falkner-nfsv4-acls-00.txt which proposes more precise semantics for NFSv4 ACLs and deals with mode-bit mapping and other issues of particular interest for NFSv4 ACL implementors on POSIX systems; implementation in ZFS (in both Solaris and FreeBSD) and UFS (FreeBSD) implement semantics described in this draft.

In practice many Windows applications (such as Explorer) may use only a small subset of Windows ACLs, and may not deal well with ACLs outside of that subset; for example, they generally want to sort all DENY ACE's before ALLOW ACE's. See this msdn documentation.

Documentation of existing Windows ACL manipulation tools would also be useful; cacls.exe has been mentioned as one tool that is commonly used by administrators and whose interface might be worth examination by people implementing NFSv4 ACL tools.


As noted above, these aren't really POSIX, though they've been implemented on lots of operating systems, including Solaris and Linux. See the POSIX draft for detailed documentation.

NFSv4/Windows ACLs are more fine-grained than POSIX ACLs.

The popularity and flexibility of Windows/NFSv4 ACLs makes it tempting to just ignore POSIX ACLs. However,

  • The flexibility of Windows ACL's could make them harder to use them correctly. People with experience suggested that in practice users do have trouble. (Any references to published evidence here would be useful. Windows Access Control Demystified studies ACL misconfiguration problems, though the specific problems identified seem to be with access bits not relevant to file system permissions.)
  • POSIX ACL's are what are currently available on Linux and some other platforms, so we can expect that they are what developers are currently coding to; thus even if they aren't widely used now, they may be in a few years (by which time file managers have built-in support for them, etc.; see this news about Nautilus POSIX ACL support.


AFS ACLs are only set on directories, and affect the directory and all files contained in it; hardlinks are unsupported. They have more access bits than POSIX ACLs, but less than NFSv4/Windows ACLs. Denies are supported (though discouraged), and always supercede allows. (So an AFS ACL is roughly equivalent to a Windows/NFSv4 ACL with all DENY aces at the beginning.)

DCE ACLs appear to be a superset of POSIX ACLs, with additional mode bits and entities.

AIX? Others?

Interoperability Strategies

In the following we tend to focus on mapping between different ACL types, though of course that's only one tool.

Strict Mapping

The POSIX<->NFSv4 mapping draft), which is what the linux client and server implement, takes a very strict approach: POSIX ACLs are mapped on the fly to NFSv4 ACLs, but attempts to get or set NFSv4 ACLs fail unless they are precisely equal to a POSIX-mapped NFSv4 ACL. Since NFSv4 ACLs are much finer-grained, almost all NFSv4 ACLs will fail to map to a POSIX ACL.

This approach has a few disadvantages:

  • The NFSv4 ACLs produced by this mapping are hard to read, and are nearly impossible for users to manipulate without software that understands the mapping to aid them. Thus a user modifying the ACLs through an application that doesn't treat them as POSIX ACLs will almost certainly produce an ACL that can no longer be read by applications that expect POSIX ACLs.
  • An NFSv4 server like Linux with backend POSIX ACLs can accept only a very limited subset of ACLs, probably impossible to generate without software that understands the mapping.

Strict mapping between Windows and NFSv4 ACLs is much easier.

Lossy mapping

See Jeremy Allison's presentation for a description of a mapping used to store and retrieve NFSv4 ACLs from a backend that supports only POSIX ACLs. This mapping always succeeds, sacrificing some semantics instead.

(Summarize tradeoffs.)

The current Linux server also implements a lossy algorithm described in draft-ietf-nfsv4-acl-mapping-05.txt.

POSIX ACLs provide another interesting example: mode bits are themselves a primitive sort of ACL, and operating systems that support POSIX ACLs have to continue supporting mode bits as well. They do this in a rather interesting way--the POSIX ACL is guaranteed not to give more access than the corresponding mode bits, except that some named users and groups may be permitted more access than they otherwise would, with the restriction that that additional access is bounded by the mode bits given to the file's group.

When modifying mode bits, to ensure that chmod restricts access, without completely removing an existing POSIX ACL, POSIX has a special MASK ACE that restricts the access that may be given by named user and group ACEs without requiring those ACEs be modified or removed.

Also, standard commands such as "ls" are modified to provide some visual indication that a POSIX ACL is present even when only the mode bits are displayed.

The Windows Services for Unix documentation provides another interesting example: they provide an NFS server that must use a Windows backend to store mode bits. (They don't appear to deal with POSIX ACLs.) Their mapping from mode bits to Windows ACLs is similar to the mapping described by the POSIX<->NFSv4 ietf draft, though they leave out some superfluous DENY aces. The mapping back from Windows ACLs to mode bits necessarily loses some information, but never fails.

Other options

A server could store multiple ACL's and enforce only one type, or enforce all of them (permitting access only if each ACL permits access). Setting one type of ACL could remove the others, or replace them by translations of the ACL set, or (gack) not affect the other ACLs at all.

User tools need to fail gracefully when mapping fails; e.g. they should be able to give the user a helpful error message and give them the option of overwriting the ACL completely or leaving it alone.

Personal tools