Provided by: nfs4-acl-tools_0.3.3-1_i386 bug

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

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.

CONTACT

       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.