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.