# nfs4_acl

## 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.
    


## ACL FORMAT



           An NFSv4 ACL is written as an _acl_spec_ , which is a comma- or tab-
           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.
    
           **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 (e.g., `myuser@nfsdomain.org')
           or group (provided 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.)
    
       **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 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



           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. The Linux kernel server uses this approach.
    


## 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.
    


## CONTACT



           Please send bug reports, feature requests, and comments to
           <_nfsv4@linux-nfs.org_ >.
    


* * *