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

A WARNING ABOUT DENY ACES

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

AUTHORS

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

CONTACT

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

SEE ALSO

238       nfs4_getfacl(1),  nfs4_setacl(1), RFC3530 (NFSv4.0), NFSv4.1 Minor Ver‐
239       sion Draft.
240
241
242
243Linux                     version 0.3.3, August 2008               NFS4_ACL(5)
Impressum