1NFS4_ACL(5) NFSv4 Access Control Lists NFS4_ACL(5)
2
6 nfs4_acl - NFSv4 Access Control Lists
7
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 A sample NFSv4 file ACL might look like the following (see the ACL FOR‐
15 MAT section for detailed information):
16 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 Some observations:
26 - 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 - NFSv4 ACLs are "default-deny"; that is, if a permission is not ex‐
33 plicitly 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 - 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
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 type:flags:principal:permissions
54 ACE TYPES:
56 There are four types of ACEs, each represented by a single character.
57 An ACE must have exactly one type.
58 A Allow - allow principal to perform actions requiring permis‐
60 sions.
61 D Deny - prevent principal from performing actions requiring per‐
63 missions.
64 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 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 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 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 IN‐
85 HERITANCE FLAGS COMMENTARY section for more information.
86 GROUP FLAG - can be used in any ACE
88 g group - indicates that principal represents a group instead of a
90 user.
91 INHERITED FLAG - can be used in any ACE
93 I inherited - indicates that the ACE was inherited from the parent
95 directory. This flag can only be used with the NFSv4.1 protocol
96 or newer when using the --dacl or --sacl options.
97 INHERITANCE FLAGS - can be used in any directory ACE
99 d directory-inherit - newly-created subdirectories will inherit
101 the ACE.
102 f file-inherit - newly-created files will inherit the ACE, minus
104 its inheritance flags. Newly-created subdirectories will in‐
105 herit the ACE; if directory-inherit is not also specified in the
106 parent ACE, inherit-only will be added to the inherited ACE.
107 n no-propagate-inherit - newly-created subdirectories will inherit
109 the ACE, minus its inheritance flags.
110 i inherit-only - the ACE is not considered in permissions checks,
112 but it is heritable; however, the inherit-only flag is stripped
113 from inherited ACEs.
114 ADMINISTRATIVE FLAGS - can be used in Audit and Alarm ACEs
116 S successful-access - trigger an alarm/audit when principal is al‐
118 lowed to perform an action covered by permissions.
119 F failed-access - trigger an alarm/audit when principal is pre‐
121 vented from performing an action covered by permissions.
122 ACE PRINCIPALS:
124 A principal is either a named user (e.g., `myuser@nfsdomain.org') or
125 group (provided the group flag is also set), or one of three special
126 principals: `OWNER@', `GROUP@', and `EVERYONE@':
127 OWNER@ matches the file's owner
129 GROUP@ matches the file's group
131 EVERYONE@
133 always matches. (Note this is different from the "other" used
134 in mode bits or POSIX ACLs, which does not match the file's
135 owner or group.)
136 ACE PERMISSIONS:
138 There are a variety of different ACE permissions (13 for files, 14 for
139 directories), each represented by a single character. An ACE should
140 have one or more of the following permissions specified:
141 r read-data (files) / list-directory (directories)
143 w write-data (files) / create-file (directories)
145 a append-data (files) / create-subdirectory (directories)
147 x execute (files) / change-directory (directories)
149 d delete - delete the file/directory. Some servers will allow a
151 delete to occur if either this permission is set in the file/di‐
152 rectory or if the delete-child permission is set in its parent
153 directory.
154 D delete-child - remove a file or subdirectory from within the
156 given directory (directories only)
157 t read-attributes - read the attributes of the file/directory.
159 T write-attributes - write the attributes of the file/directory.
161 n read-named-attributes - read the named attributes of the
163 file/directory.
164 N write-named-attributes - write the named attributes of the
166 file/directory.
167 c read-ACL - read the file/directory NFSv4 ACL.
169 C write-ACL - write the file/directory NFSv4 ACL.
171 o write-owner - change ownership of the file/directory.
173 y synchronize - allow clients to use synchronous I/O with the
175 server.
176
179 Inheritance flags can be divided into two categories: "primary" (file-
180 inherit and directory-inherit); and "secondary" (no-propagate-inherit
181 and inherit-only), which are significant only insofar as they affect
182 the two "primary" flags.
183 The no-propagate-inherit and inherit-only flags can be tricky to remem‐
185 ber: the former determines whether or not a new child directory's in‐
186 herited ACE is itself heritable by a grandchild subdirectory; the lat‐
187 ter determines whether or not a heritable ACE affects the parent direc‐
188 tory itself (in addition to being heritable). They can be used in-tan‐
189 dem.
190 When a subdirectory inherits an ACE from its parent directory's ACL,
192 this can happen in one of two different ways, depending on the server
193 implementation:
194 - In the simple case, that exact same ACE is set in the subdirectory's
196 ACL.
197 - In the other case, two different ACEs will instead be set in the
199 subdirectory's ACL: one with all inheritance flags removed, and one
200 with the inherit-only flag added. The former is the "effective" in‐
201 herited ACE (used in the subdirectory's own permissions checks); the
202 latter is the "heritable" inherited ACE (when the subdirectory has
203 directories created within it, they inherit it). This approach
204 makes it easier to modify access rights to the subdirectory itself
205 without modifying its heritable ACEs. The Linux kernel server uses
206 this approach.
207
209 Deny ACEs should be avoided whenever possible. Although they are a
210 valid part of NFSv4 ACLs, Deny ACEs can be confusing and complicated.
211 This stems primarily from the fact that, unlike POSIX ACLs and CIFS
212 ACLs, the ordering of ACEs within NFSv4 ACLs affects how they are eval‐
213 uated.
214 First, it is important to note that (despite some unfortunate ambiguity
216 in RFC3530) NFSv4 ACLs are "default-deny" in practice. That is, if a
217 permission is not explicitly granted, it is denied.
218 In general, when a principal is attempting to perform an action over
220 NFSv4 which requires one or more permissions, an access check is per‐
221 formed. The NFSv4 ACL (assuming one is present) is evaluated ACE-by-
222 ACE until every one of those permissions has been addressed, or until
223 the end of the ACL is reached. If every requisite permission was
224 granted by Allow ACEs and was not forbidden by Deny ACEs (see next
225 paragraph), the action is allowed to proceed. Otherwise, the action is
226 forbidden.
227 Note that each requisite permission is only addressed once -- that is,
229 after a permission has been explicitly Allowed or Denied once during an
230 access check, any subsequent ACEs in the ACL which affect that permis‐
231 sion are no longer considered. This often introduces problematic or‐
232 dering issues when Deny ACEs are present.
233 Additionally, in some cases Group-Deny ACEs can be difficult (if not
235 impossible) to enforce, since a server might not know about all of a
236 given principal's memberships in remote groups, e.g.
237 Because NFSv4 ACLs are "default-deny", the use of Deny ACEs can (and
239 should) be avoided entirely in most cases.
240
242 Tools for viewing and manipulating NFSv4 ACLs, nfs4_getfacl and
243 nfs4_setfacl, were written by people at CITI, the Center for Informa‐
244 tion Technology Integration (http://www.citi.umich.edu). This manpage
245 was written by David Richter and J. Bruce Fields.
246
248 Please send bug reports, feature requests, and comments to
249 <nfsv4@linux-nfs.org>.
250
252 nfs4_getfacl(1), nfs4_setfacl(1), RFC3530 (NFSv4.0), NFSv4.1 Minor Ver‐
253 sion Draft.
254Linux version 0.3.4, August 2018 NFS4_ACL(5)