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
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 - 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
85 INHERITANCE 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 INHERITANCE FLAGS - can be used in any directory ACE
93 d directory-inherit - newly-created subdirectories will inherit
95 the ACE.
96 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 n no-propagate-inherit - newly-created subdirectories will inherit
103 the ACE, minus its inheritance flags.
104 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 ADMINISTRATIVE FLAGS - can be used in Audit and Alarm ACEs
110 S successful-access - trigger an alarm/audit when principal is
112 allowed to perform an action covered by permissions.
113 F failed-access - trigger an alarm/audit when principal is pre‐
115 vented from performing an action covered by permissions.
116 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 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 r read-data (files) / list-directory (directories)
130 w write-data (files) / create-file (directories)
132 a append-data (files) / create-subdirectory (directories)
134 x execute (files) / change-directory (directories)
136 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 D delete-child - remove a file or subdirectory from within the
143 given directory (directories only)
144 t read-attributes - read the attributes of the file/directory.
146 T write-attributes - write the attributes of the file/directory.
148 n read-named-attributes - read the named attributes of the
150 file/directory.
151 N write-named-attributes - write the named attributes of the
153 file/directory.
154 c read-ACL - read the file/directory NFSv4 ACL.
156 C write-ACL - write the file/directory NFSv4 ACL.
158 o write-owner - change ownership of the file/directory.
160 y synchronize - allow clients to use synchronous I/O with the
162 server.
163
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 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 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 - In the simple case, that exact same ACE is set in the subdirectory's
183 ACL.
184 - 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
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 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 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 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 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 Because NFSv4 ACLs are "default-deny", the use of Deny ACEs can (and
226 should) be avoided entirely in most cases.
227
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
235 Please send bug reports, feature requests, and comments to
236 <nfsv4@linux-nfs.org>.
237
239 nfs4_getfacl(1), nfs4_setfacl(1), RFC3530 (NFSv4.0), NFSv4.1 Minor Ver‐
240 sion Draft.
241Linux version 0.3.4, August 2018 NFS4_ACL(5)