1NFS4_ACL(5)               NFSv4 Access Control Lists               NFS4_ACL(5)
2
3
4

NAME

6       nfs4_acl - NFSv4 Access Control Lists
7

DESCRIPTION

9       An ACL is a list of permissions associated with a file or directory and
10       consists of one or more Access Control Entries (ACEs).  NFSv4 ACLs pro‐
11       vide  finer  granularity  than typical POSIX read/write/execute permis‐
12       sions and are similar to CIFS ACLs.
13
14       A sample NFSv4 file ACL might look like the following (see the ACL FOR‐
15       MAT section for detailed information):
16
17              A::OWNER@:rwatTnNcCy
18              A::alice@nfsdomain.org:rxtncy
19              A::bob@nfsdomain.org:rwadtTnNcCy
20              A:g:GROUP@:rtncy
21              D:g:GROUP@:waxTC
22              A::EVERYONE@:rtncy
23              D::EVERYONE@:waxTC
24
25       Some observations:
26
27       -  In  the example output above, the user `alice@nfsdomain.org' has the
28          equivalent of "read" and "execute" permissions,  `bob@nfsdomain.org'
29          has  "read"  and  "write",  and  both  `GROUP@' and `EVERYONE@' have
30          "read".
31
32       -  NFSv4 ACLs are "default-deny"; that  is,  if  a  permission  is  not
33          explicitly  granted by an Allow ACE, it is denied.  Because of this,
34          the two Deny ACEs above are superfluous and could be excluded by the
35          server.  See the A WARNING ABOUT DENY ACES section for more informa‐
36          tion.
37
38       -  NFSv4 servers may return an ACL slightly different than one you set.
39          For example, a server that always allows reading the attributes of a
40          file may silently turn on  the  read-attributes  permission,  and  a
41          server  that  does  not  support separate write-data and append-data
42          permissions, e.g., may choose to turn off both if you set only  one.
43          In  extreme cases the server may also reorder or combine ACEs.  As a
44          general rule, however, servers will attempt to ensure that the  ACLs
45          they return are no more permissive than the ones you set.
46

ACL FORMAT

48       An NFSv4 ACL is written as an acl_spec, which is a comma- or tab-delim‐
49       ited string consisting of one or more ace_specs.  A single NFSv4 ACE is
50       written  as  an ace_spec, which is a colon-delimited, 4-field string in
51       the following format:
52
53              type:flags:principal:permissions
54
55   ACE TYPES:
56       There are four types of ACEs, each represented by a  single  character.
57       An ACE must have exactly one type.
58
59       A      Allow  -  allow  principal  to perform actions requiring permis‐
60              sions.
61
62       D      Deny - prevent principal from performing actions requiring  per‐
63              missions.
64
65       U      Audit  -  log  any  attempted access by principal which requires
66              permissions.  Requires one or both of the successful-access  and
67              failed-access  flags.   System-dependent;  not  supported by all
68              servers.
69
70       L      Alarm - generate a system alarm at any attempted access by prin‐
71              cipal  which  requires permissions.  Requires one or both of the
72              successful-access and  failed-access  flags.   System-dependent;
73              not supported by all servers.
74
75   ACE FLAGS:
76       There are three kinds of ACE flags: group, inheritance, and administra‐
77       tive.  An Allow or Deny ACE may contain zero or more  flags,  while  an
78       Audit  or  Alarm ACE must contain at least one of the successful-access
79       and failed-access flags.
80
81       Note that ACEs are inherited from the parent  directory's  ACL  at  the
82       time a file or subdirectory is created.  Accordingly, inheritance flags
83       can be used only in ACEs  in  a  directory's  ACL  (and  are  therefore
84       stripped  from  inherited  ACEs  in  a new file's ACL).  Please see the
85       INHERITANCE FLAGS COMMENTARY section for more information.
86
87       GROUP FLAG - can be used in any ACE
88
89       g      group - indicates that principal represents a group instead of a
90              user.
91
92       INHERITANCE FLAGS - can be used in any directory ACE
93
94       d      directory-inherit  -  newly-created  subdirectories will inherit
95              the ACE.
96
97       f      file-inherit - newly-created files will inherit the  ACE,  minus
98              its   inheritance   flags.   Newly-created  subdirectories  will
99              inherit the ACE; if directory-inherit is not also  specified  in
100              the parent ACE, inherit-only will be added to the inherited ACE.
101
102       n      no-propagate-inherit - newly-created subdirectories will inherit
103              the ACE, minus its inheritance flags.
104
105       i      inherit-only - the ACE is not considered in permissions  checks,
106              but  it is heritable; however, the inherit-only flag is stripped
107              from inherited ACEs.
108
109       ADMINISTRATIVE FLAGS - can be used in Audit and Alarm ACEs
110
111       S      successful-access - trigger an  alarm/audit  when  principal  is
112              allowed to perform an action covered by permissions.
113
114       F      failed-access  -  trigger  an alarm/audit when principal is pre‐
115              vented from performing an action covered by permissions.
116
117   ACE PRINCIPALS:
118       A principal is either a named user  (e.g.,  `myuser@nfsdomain.org')  or
119       group  (provided  the  group flag is also set), or one of three special
120       principals: `OWNER@', `GROUP@', and  `EVERYONE@',  which  are,  respec‐
121       tively,  analogous  to the POSIX user/group/other distinctions used in,
122       e.g., chmod(1).
123
124   ACE PERMISSIONS:
125       There are a variety of different ACE permissions (13 for files, 14  for
126       directories),  each  represented  by a single character.  An ACE should
127       have one or more of the following permissions specified:
128
129       r      read-data (files) / list-directory (directories)
130
131       w      write-data (files) / create-file (directories)
132
133       a      append-data (files) / create-subdirectory (directories)
134
135       x      execute (files) / change-directory (directories)
136
137       d      delete - delete the file/directory.  Some servers will  allow  a
138              delete  to  occur  if  either  this  permission  is  set  in the
139              file/directory or if the delete-child permission is set  in  its
140              parent directory.
141
142       D      delete-child  -  remove  a  file or subdirectory from within the
143              given directory (directories only)
144
145       t      read-attributes - read the attributes of the file/directory.
146
147       T      write-attributes - write the attributes of the file/directory.
148
149       n      read-named-attributes  -  read  the  named  attributes  of   the
150              file/directory.
151
152       N      write-named-attributes  -  write  the  named  attributes  of the
153              file/directory.
154
155       c      read-ACL - read the file/directory NFSv4 ACL.
156
157       C      write-ACL - write the file/directory NFSv4 ACL.
158
159       o      write-owner - change ownership of the file/directory.
160
161       y      synchronize - allow clients to  use  synchronous  I/O  with  the
162              server.
163
164

INHERITANCE FLAGS COMMENTARY

166       Inheritance  flags can be divided into two categories: "primary" (file-
167       inherit and directory-inherit); and  "secondary"  (no-propagate-inherit
168       and  inherit-only),  which  are significant only insofar as they affect
169       the two "primary" flags.
170
171       The no-propagate-inherit and inherit-only flags can be tricky to remem‐
172       ber:  the  former  determines  whether  or  not a new child directory's
173       inherited ACE is itself heritable by  a  grandchild  subdirectory;  the
174       latter  determines  whether  or  not a heritable ACE affects the parent
175       directory itself (in addition to being heritable).  They  can  be  used
176       in-tandem.
177
178       When  a  subdirectory  inherits an ACE from its parent directory's ACL,
179       this can happen in one of two different ways, depending on  the  server
180       implementation:
181
182       -  In the simple case, that exact same ACE is set in the subdirectory's
183          ACL.
184
185       -  In the other case, two different ACEs will instead  be  set  in  the
186          subdirectory's  ACL: one with all inheritance flags removed, and one
187          with the inherit-only flag added.  The  former  is  the  "effective"
188          inherited  ACE  (used in the subdirectory's own permissions checks);
189          the latter is the "heritable" inherited ACE (when  the  subdirectory
190          has  directories created within it, they inherit it).  This approach
191          makes it easier to modify access rights to the  subdirectory  itself
192          without  modifying  its heritable ACEs. The Linux kernel server uses
193          this approach.
194

A WARNING ABOUT DENY ACES

196       Deny ACEs should be avoided whenever possible.   Although  they  are  a
197       valid  part  of NFSv4 ACLs, Deny ACEs can be confusing and complicated.
198       This stems primarily from the fact that, unlike  POSIX  ACLs  and  CIFS
199       ACLs, the ordering of ACEs within NFSv4 ACLs affects how they are eval‐
200       uated.
201
202       First, it is important to note that (despite some unfortunate ambiguity
203       in  RFC3530)  NFSv4 ACLs are "default-deny" in practice.  That is, if a
204       permission is not explicitly granted, it is denied.
205
206       In general, when a principal is attempting to perform  an  action  over
207       NFSv4  which  requires one or more permissions, an access check is per‐
208       formed.  The NFSv4 ACL (assuming one is present) is  evaluated  ACE-by-
209       ACE  until  every one of those permissions has been addressed, or until
210       the end of the ACL is  reached.   If  every  requisite  permission  was
211       granted  by  Allow  ACEs  and  was not forbidden by Deny ACEs (see next
212       paragraph), the action is allowed to proceed.  Otherwise, the action is
213       forbidden.
214
215       Note  that each requisite permission is only addressed once -- that is,
216       after a permission has been explicitly Allowed or Denied once during an
217       access  check, any subsequent ACEs in the ACL which affect that permis‐
218       sion are no  longer  considered.   This  often  introduces  problematic
219       ordering issues when Deny ACEs are present.
220
221       Additionally,  in  some  cases Group-Deny ACEs can be difficult (if not
222       impossible) to enforce, since a server might not know about  all  of  a
223       given principal's memberships in remote groups, e.g.
224
225       Because  NFSv4  ACLs  are "default-deny", the use of Deny ACEs can (and
226       should) be avoided entirely in most cases.
227

AUTHORS

229       Tools  for  viewing  and  manipulating  NFSv4  ACLs,  nfs4_getfacl  and
230       nfs4_setfacl,  were  written by people at CITI, the Center for Informa‐
231       tion Technology Integration (http://www.citi.umich.edu).  This  manpage
232       was written by David Richter and J. Bruce Fields.
233

CONTACT

235       Please   send   bug   reports,   feature   requests,  and  comments  to
236       <nfsv4@linux-nfs.org>.
237

SEE ALSO

239       nfs4_getfacl(1), nfs4_setfacl(1), RFC3530 (NFSv4.0), NFSv4.1 Minor Ver‐
240       sion Draft.
241
242
243
244Linux                     version 0.3.4, August 2018               NFS4_ACL(5)
Impressum