NAME¶
nfs4_acl - NFSv4 Access Control Lists
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
ACL FORMAT
section for detailed information):
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:
- -
- 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".
- -
- 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 A WARNING ABOUT DENY ACES section
for more information.
- -
- 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 permission, and
a server that does not support separate write-data and append-data
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.
An NFSv4 ACL is written as an
acl_spec, which is a comma- or
whitespace-delimited string consisting 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 the following format:
type:flags:principal:permissions
ACE TYPES:¶
There are four
types of ACEs, each represented by a single character. An
ACE must have exactly one
type.
- 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.
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
INHERITANCE FLAGS COMMENTARY section
for more information.
- GROUP FLAG - can be used in any ACE
- g
- group - indicates that principal represents a group
instead of a user.
- 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 (e.g., `myuser@nfsdomain.org') or
group (provided the group
flag is also set), or one of three special
principals: `OWNER@', `GROUP@', and `EVERYONE@', which are,
respectively, analogous to the POSIX user/group/other distinctions used in,
e.g.,
chmod(1).
ACE PERMISSIONS:¶
There are a variety of different 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 direcory.
- 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 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"
flags.
The no-propagate-inherit and inherit-only
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:
- -
- In the simple case, that exact same ACE is set in the
subdirectory's ACL.
- -
- In the other case, two different ACEs will instead be set
in the subdirectory's ACL: 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
(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.
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
RFC3530) NFSv4 ACLs are "default-deny" in practice. That is,
if a
permission is not explicitly granted, it is denied.
In general, when a
principal is attempting to perform an action over
NFSv4 which requires one or more
permissions, an access check is
performed. 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.
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.
AUTHORS¶
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.
Please send bug reports, feature requests, and comments to
<
nfsv4@linux-nfs.org>.
SEE ALSO¶
nfs4_getfacl(1),
nfs4_setacl(1),
RFC3530 (NFSv4.0), NFSv4.1
Minor Version Draft.
