.\" NFSv4 Access Control Lists manual pages
.\" format with: groff -man -Tascii foo.1
.\" 
.TH NFS4_ACL 5 "version 0.3.4, August 2018" "Linux" "NFSv4 Access Control Lists"
.SH NAME
nfs4_acl \- NFSv4 Access Control Lists
.SH DESCRIPTION

An ACL is a list of permissions associated with a file or directory and 
consists of one or more Access Control Entries (ACEs).  NFSv4 
ACLs provide finer granularity than typical POSIX read/write/execute
permissions and are similar to CIFS ACLs.  

A sample NFSv4 file ACL might
look like the following (see the
.BR "ACL FORMAT" " section for detailed information):"
.RS
.nf

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
.fi
.RE

Some observations:
.IP - 3
In the example output above, 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".
.IP - 3
NFSv4 ACLs are "default-deny"; that is, if a permission is not explicitly 
granted by an Allow ACE, it is denied.  Because of this, the two Deny ACEs 
above are superfluous and could be excluded by the server.  See the
.BR "A WARNING ABOUT DENY ACES" " section for more information."
.IP - 3
NFSv4 servers may return an ACL slightly different than one you set.  For 
example, a server that always allows reading the attributes of a file may 
silently turn on the read-attributes
.IR permission ,
and a server that does not support separate write-data and append-data 
.IR permissions ,
e.g., may choose to turn off both if you set only one.  In extreme 
cases the server may also reorder or combine ACEs.  As a general rule, 
however, servers will attempt to ensure that the ACLs they return are no 
more permissive than the ones you set.
.\"NFSv4 servers may return implementation-dependent representations for
.\"a given ACL.  Two different server implementations may represent a given 
.\"file's ACL differently, and a given server may return a different-looking ACL 
.\"from one set immediately prior.  Nevertheless, in either case, the effective 
.\"permissions of the ACLs should be identical.
.SH ACL FORMAT
An NFSv4 ACL is written as an
.IR acl_spec ,
which is a comma- or tab-delimited string consisting of one or more
.IR ace_specs .
A single NFSv4 ACE is written as an
.IR ace_spec ,
which is a colon-delimited, 4-field string in the following format:

.RS
.IR type ":" flags ":" principal ":" permissions
.RE
.SS ACE TYPES:
There are four
.I types
of ACEs, each represented by a single character.  An ACE must have exactly one 
.IR type .
.TP
.\".RB "'" "A" "' Allow"
.B A
Allow - allow
.I principal
to perform actions requiring
.IR permissions .
.TP
.\".RB "'" "D" "' Deny"
.B D
Deny - prevent
.I principal
from performing actions requiring
.IR permissions .
.TP
.\".RB "'" "U" "' Audit"
.B U
Audit - log any attempted access by
.I principal
which requires
.IR permissions .
Requires one or both of the successful-access and failed-access 
.IR flags .
System-dependent; not supported by all servers.
.TP
.\".RB "'" "L" "' Alarm"
.B L
Alarm - generate a system alarm at any attempted access by
.I principal
which requires
.IR permissions .
Requires one or both of the successful-access and failed-access 
.IR flags .
System-dependent; not supported by all servers.
.SS ACE FLAGS:
There are three kinds of ACE
.IR flags ": group, inheritance, and administrative.  An Allow or Deny ACE may contain zero or more
.IR flags ,
while an Audit or Alarm ACE must contain at least one of the successful-access and failed-access
.IR flags .
.P
Note that ACEs are inherited from the parent directory's ACL at the time a file
or subdirectory is created.  Accordingly, inheritance flags can be used only in 
ACEs in a directory's ACL (and are therefore stripped from inherited ACEs in a
new file's ACL).  Please see the 
.BR "INHERITANCE FLAGS COMMENTARY" " section for more information."
.TP
.\".BR "GROUP FLAG" " - can be used with " Allow ", " Deny ", " Audit ", and " Alarm " ACEs
.BR "GROUP FLAG" " - can be used in any ACE"
.TP
.B g
group - indicates that
.I principal
represents a group instead of a user.
.TP
.BR "INHERITED FLAG" " - can be used in any ACE"
.TP
.B 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
.BR --dacl
or
.BR --sacl
options.
.TP
.BR "INHERITANCE FLAGS" " - can be used in any directory ACE"
.TP
.B d
directory-inherit - newly-created subdirectories will inherit the ACE.
.TP
.B f
file-inherit - newly-created files will inherit the ACE, minus its inheritance 
.IR 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.
.TP
.B n
no-propagate-inherit - newly-created subdirectories will inherit the ACE, minus its inheritance 
.IR flags .
.TP
.B i
inherit-only - the ACE is not considered in permissions checks, but it is heritable;
however, the inherit-only 
.I flag 
is stripped from inherited ACEs.
.TP
.\".B administrative flags
.\"can be used only with ACEs of
.\".I type
.\".B Audit
.\"or
.\".B Alarm
.BR "ADMINISTRATIVE FLAGS" " - can be used in " Audit " and " Alarm " ACEs"
.TP
.B S
successful-access - trigger an alarm/audit when
.I principal
is allowed to perform an action covered by
.IR permissions .
.TP
.B F
failed-access - trigger an alarm/audit when
.I principal
is prevented from performing an action covered by
.IR permissions .
.SS ACE PRINCIPALS:
A 
.I principal
is either a named user (e.g., `myuser@nfsdomain.org') or group 
(provided the group 
.I flag 
is also set), or one of three special 
.IR principals :
`OWNER@', `GROUP@', and `EVERYONE@':
.TP
.B OWNER@
matches the file's owner
.TP
.B GROUP@
matches the file's group
.TP
.B 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.)
.SS ACE PERMISSIONS:
There are a variety of different ACE
.I permissions 
(13 for files, 14 for directories), each represented by a single character.  
An ACE should have one or more of the following 
.I permissions
specified:
.TP
.B r
read-data (files) / list-directory (directories)
.TP
.B w
write-data (files) / create-file (directories)
.TP
.B a
append-data (files) / create-subdirectory (directories)
.TP
.B x
execute (files) / change-directory (directories)
.TP
.B d
delete - delete the file/directory.  Some servers will allow a delete to occur 
if either this 
.I permission 
is set in the file/directory or if the delete-child 
.I permission
is set in its parent directory.
.TP
.B D
delete-child - remove a file or subdirectory from within the given directory
(directories only)
.TP
.B t
read-attributes - read the attributes of the file/directory.
.TP
.B T
write-attributes - write the attributes of the file/directory.
.TP
.B n
read-named-attributes - read the named attributes of the file/directory.
.TP
.B N
write-named-attributes - write the named attributes of the file/directory.
.TP
.B c
read-ACL - read the file/directory NFSv4 ACL.
.TP
.B C
write-ACL - write the file/directory NFSv4 ACL.
.TP
.B o
write-owner - change ownership of the file/directory.
.TP 
.B y
synchronize - allow clients to use synchronous I/O with the server.

.SH INHERITANCE FLAGS COMMENTARY
Inheritance 
.I flags 
can be divided into two categories: 
"primary" (file-inherit and directory-inherit); and 
"secondary" (no-propagate-inherit and inherit-only), 
which are significant only insofar as they affect the two "primary" 
.IR flags .

The no-propagate-inherit and inherit-only 
.I flags 
can be tricky to remember:
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.

When a subdirectory inherits an ACE from its parent directory's ACL, this
can happen in one of two different ways, depending on the server
implementation:
.IP - 3 
In the simple case, that exact same ACE is set in the subdirectory's ACL.
.IP - 3
In the other case, two different ACEs will instead be set in the subdirectory's ACL:
one with all inheritance 
.I flags 
removed, and one with the inherit-only 
.I flag
added.  The former is the "effective" inherited ACE (used in the subdirectory's
own permissions checks); the latter is the "heritable" inherited ACE (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.
.PP
.ns
.SH A WARNING ABOUT DENY ACES 
Deny ACEs should be avoided whenever possible.  Although they are a valid part
of NFSv4 ACLs, Deny ACEs can be confusing and complicated.  This stems 
primarily from the fact that, unlike POSIX ACLs and CIFS ACLs, the ordering of
ACEs within NFSv4 ACLs affects how they are evaluated.

First, it is important to note that (despite some unfortunate ambiguity in 
.IR RFC3530 )
NFSv4 ACLs are "default-deny" in practice.  That is, if a
.I permission
is not explicitly granted, it is denied.  

In general, when a
.I principal 
is attempting to perform an action over NFSv4 which requires one or more 
.IR permissions ,
an access check is performed.
The NFSv4 ACL (assuming one is present) is evaluated ACE-by-ACE until every one of those
.I permissions 
has been addressed, or until the end of the ACL is reached.  If every requisite
.I 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.

Note that each requisite
.I permission
is only addressed once -- that is, after a
.I permission
has been explicitly Allowed or Denied once during an access check, 
any subsequent ACEs in the ACL which affect that
.I 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
.IR 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.  
.SH AUTHORS
Tools for viewing and manipulating NFSv4 ACLs, 
.BR nfs4_getfacl " and " nfs4_setfacl ,
were written by people at CITI, the Center for Information Technology Integration
.RI ( http://www.citi.umich.edu ).
This manpage was written by David Richter and J. Bruce Fields.
.SH CONTACT
Please send bug reports, feature requests, and comments to
.RI < linux-nfs@vger.kernel.org >.
.SH SEE ALSO
.BR nfs4_getfacl "(1), " nfs4_setfacl (1), 
.IR RFC3530 " (NFSv4.0), NFSv4.1 Minor Version Draft."