1RICHACL(7) Rich Access Control Lists RICHACL(7)
2
6 richacl - Rich Access Control Lists
7
9 Rich Access Control Lists (RichACLs) are an extension of the tradi‐
10 tional POSIX file permission model to support NFSv4 Access Control
11 Lists ⟨https://tools.ietf.org/rfc/rfc5661.txt⟩ on local and remote-
12 mounted filesystems.
13 A RichACL can always be translated into an equivalent NFSv4 ACL which
15 grants the same permissions.
16 RichACLs can be enabled on supported local filesystems (currently, ext4
18 and XFS). The in-kernel NFSv4 server and client also include RichACL
19 support.
20 Enabling RichACLs disables POSIX Access Control Lists; the two ACL mod‐
22 els cannot coexist on the same filesystem.
23 When used on a filesystem that does not support RichACLs, the get‐
25 richacl(1) and setrichacl(1) utilities will operate on the file permis‐
26 sion bits instead: getrichacl(1) will display the file permission bits
27 as a RichACL; when a RichACL is set with setrichacl(1) which can be
28 represented exactly by the file permission bits, setrichacl(1) will set
29 the file permission bits instead. An attempt to set a RichACL that
30 cannot be represented exactly by the file permission bits results in an
31 error.
32 This man-page describes the structure, concepts and algorithms involved
34 in RichACLs. For examples, please refer to richaclex(7).
35 Structure of RichACLs
37 RichACLs consist of a number of ACL entries, three file masks, and a
38 set of flags specifying attributes of the ACL as a whole (by contrast
39 with the per-ACL-entry flags described below).
40 Each of the ACL entries allows or denies some permissions to a particu‐
42 lar user, group, or special identifier. An ACL entry consists of four
43 fields:
44 · A tag which specifies the user, group, or special identifier the
46 entry applies to. Special identifiers can be the file owner
47 (owner@), the owning group (group@), or everyone (everyone@).
48 · A set of permissions the entry allows or denies.
50 · A set of flags that indicate whether the user or group identifier is
52 mapped or unmapped, and whether the entry has been and can be inher‐
53 ited.
54 · A type field indicating whether the entry allows or denies the per‐
56 missions specified in the second field.
57 The owner, group, and other file masks further control which permis‐
59 sions the ACL grants, subject to the masked (m) and write_through (w)
60 ACL flags: when the permissions of a file or directory are changed with
61 chmod(2), the file masks are set based on the new file mode, and the
62 masked and write_through ACL flags are set. Likewise, when a new file
63 or directory inherits an ACL from its parent directory, the file masks
64 are set to the intersection between the permissions granted by the
65 inherited ACL and the mode parameter as given to open(2), mkdir(2), and
66 similar, and the masked ACL flag is set. In both cases, the file masks
67 limit the permissions that the ACL will grant.
68 The purpose of the file masks is to allow traditional POSIX applica‐
70 tions which are unaware of RichACLs to place limits on the permissions
71 granted by the RichACL without causing the ACL entries to be modified.
72 Without the file mask, the only alternative would be for the kernel to
73 directly modify the ACL entries. However, this latter approach could
74 have a “hysteresis effect”, whereby a RichACL-unaware application that
75 performs a transition from one file mode to another file mode and then
76 back to the original file mode could cause destruction of the permis‐
77 sion information in ACL entries. When creating files or directories,
78 the mode parameter to open(2), mkdir(2), and similar would have the
79 same effect.
80 Note that entries with the identifier everyone@ apply to all processes,
82 whereas the “other” file permissions and “other” (ACL_OTHER) entries in
83 POSIX ACLs apply to all processes which are not the owner, are not in
84 the owning group, and do not match a user or group mentioned in the
85 ACL.
86 Unlike POSIX ACLs, RichACLs do not have separate “access” ACLs that
88 define the access permissions and “default” ACLs that define the inher‐
89 itable permissions. Instead, flags on each ACL entry determine whether
90 the entry is effective during access checks and/or inheritable.
91 ACL flags
93 The following ACL flags are defined:
94 masked (m)
96 When set, the file masks define upper limits on the permissions
97 the ACL may grant. When not set, the file masks are ignored.
98 write_through (w)
100 When this flag and the masked flag are both set, the owner and
101 other file masks define the actual permissions granted to the
102 file owner and to others instead of defining an upper limit.
103 When the masked flag is not set, the write_through flag has no
104 effect.
105 auto_inherit (a)
107 Automatic Inheritance is enabled. See Automatic Inheritance.
108 protected (p)
110 The ACL is protected from modification by Automatic Inheritance.
111 defaulted (d)
113 Indicates that the ACL has been assigned in an application-
114 dependent way when the file or directory was created; it has
115 neither been inherited nor set explicitly. ACLs of files created
116 on Linux will never have the defaulted flag set, but the flag
117 may be set on files created on or copied over from other operat‐
118 ing systems. When this flag is set for an ACL, Automatic Inher‐
119 itance will completely replace the ACL.
120 ACL entry flags
122 The following flags on ACL entries are defined:
123 file_inherit (f)
125 When this flag appears in the ACL entry of a directory, then:
126 · That entry is inherited by new files created in the directory
128 such that the permissions of the entry apply to the file (the
129 inheritance flags of the inherited entry are cleared).
130 · The entry is is inherited by new subdirectories created in the
132 directory such that the permissions of the entry will apply to
133 new files created in the subdirectory.
134 dir_inherit (d)
136 When this flag appears in the ACL entry of a directory, then
137 that entry is inherited by new subdirectories created in the
138 directory such that the permissions of the entry apply to the
139 subdirectory (the inherit_only flag is cleared).
140 no_propagate (n)
142 Inheritance stops at the next subdirectory level. When a file
143 or directory inherits an entry that has this flag set, the
144 file_inherit, dir_inherit, no_propagate, and inherit_only flags
145 are cleared.
146 inherit_only (i)
148 The entry defines inheritable permissions only and is ignored
149 for access checking. When a file or directory inherits an entry
150 that has this flag set, the flag is cleared.
151 inherited (a)
153 The entry has been automatically inherited from the parent
154 directory.
155 unmapped (u)
157 The user or group identifier is a textual string and is not
158 mapped to a numeric user or group identifier. ACLs with
159 unmapped identifiers can occur on NFSv4 mounted filesystems when
160 the client cannot determine numeric user or group identifiers
161 for some of the NFSv4 user@domain or group@domain who values.
162 They cannot be assigned to local files or directories.
163 Permissions
165 The following permissions are defined for RichACL entries and for the
166 three file masks:
167 read_data / list_directory (r)
169 For a file: read the data of the file. For a directory: list
170 the contents of the directory.
171 write_data / add_file (w)
173 For a file: modify the data of the file; does not include open‐
174 ing the file in append mode. For a directory: add a new file in
175 the directory.
176 append_data / add_subdirectory (p)
178 For a file: open the file in append mode. For a directory: cre‐
179 ate a subdirectory in the directory.
180 execute (x)
182 For a file: execute the file. For a directory: traverse
183 (search) the directory.
184 delete_child (d)
186 Delete a file or directory within a directory. This permission
187 is meaningful only for directories.
188 delete (D)
190 Delete the file or directory.
191 read_attributes (a)
193 Read basic attributes of a file or directory (see stat(2)).
194 This permission is defined by NFSv4. It is stored, but ignored.
195 Reading basic attributes of files and directories is always
196 allowed on Linux.
197 write_attributes (A)
199 Change the times associated with a file or directory to an arbi‐
200 trary value. This permission is always implicitly granted to
201 the file owner.
202 read_acl (c)
204 Read the ACL of a file or directory. Like reading the basic file
205 attributes (the read_attributes permission), reading ACLs is
206 always allowed on Linux.
207 write_acl (C)
209 Change the ACL or file mode of a file or directory.
210 write_owner (o)
212 Take ownership of a file or directory. Change the owning group
213 of a file or directory to a group of which the calling process
214 is a member.
215 read_named_attrs (R), write_named_attrs (W), synchronize (S),
217 write_retention (e), write_retention_hold (E)
218 These permissions are defined by NFSv4 and NFSv4.1. They are
219 stored, but ignored.
220 For the r, w, and p permissions, which have different long forms for
222 files and directories, the getrichacl(1) utility will output the appro‐
223 priate form(s) depending on the context. The setrichacl(1) utility
224 will accept either form for any file type.
225 Text form
227 The common textual representation of a RichACL consists of the colon-
228 separated fields of the ACL flags, file masks, and ACL entries in the
229 following format:
230 flags:acl_flags
232 The ACL flags.
233 owner:perm::mask, group:perm::mask, other:perm::mask
235 The file masks and their permissions.
236 who:perm:flags:allow, who:perm:flags:deny
238 For each ACL entry, who the entry applies to, the permissions of
239 the entry, the entry flags, and the entry type. The who field is
240 one of the following:
241 · One of the special identifiers: owner@, group@, or everyone@,
243 · A user: or u: prefix followed by a user name or user ID that
245 designates a specific user,
246 · A group: or g: prefix followed by a group name or group ID
248 that designates a specific group.
249 The ACL flags, file masks, and ACL entries are comma, whitespace, or
251 newline separated.
252 Flags and permissions have single-letter as well as long forms, as
254 listed under ACL flags, ACL entry flags, and Permissions. When the
255 single-letter forms are used, the flags or permissions are concate‐
256 nated. When the long forms are used, the flags or permissions are sepa‐
257 rated by slashes. To align permissions or flags vertically, dashes can
258 be used for padding.
259 Setting and modifying file permissions
261 The access permissions for a file can either be set by assigning an
262 Access Control List (setrichacl(1)) or by changing the file mode per‐
263 mission bits (chmod(1)). In addition, a file can inherit an ACL from
264 its parent directory at creation time as described under Permissions at
265 file-creation time.
266 Assigning an Access Control List
268 When assigning an ACL to a file, unless explicitly specified, the
269 owner, group, and other file masks will be computed from the ACL
270 entries as described in the section Computing the maximum file masks.
271 The owner, group, and other file mode permission bits are then each set
272 from the owner, group, and other file mask as follows:
273 · If the file mask includes the r permission, the read file mode per‐
275 mission bit will be set.
276 · If the file mask includes the w or p permission, the write file mode
278 permission bit will be set.
279 · If the file mask includes the x permission, the execute file mode
281 permission bit will be set.
282 If the ACL can be represented exactly by the file mode permission bits,
284 the file permission bits are set to match the ACL and no ACL is stored.
285 (When the ACL of a file is requested which doesn't have an ACL, the
286 file mode permission bits are converted into an equivalent ACL.)
287 Changing the file mode permission bits
289 When changing the file mode permission bits with chmod(1), the owner,
290 group, and other file permission bits are set to the permission bits in
291 the new mode, and the owner, group, and other file masks are set based
292 on the new mode bits as follows:
293 · If the read bit in a set of permissions is set, the r permission in
295 the corresponding file mask will be set.
296 · If the write bit in a set of permissions is set, the w and p permis‐
298 sions in the corresponding file mask will be set.
299 · If the execute bit in a set of permissions is set, the x permission
301 in the corresponding file mask will be set.
302 In addition, the masked and write_through ACL flags are set. This has
304 the effect of limiting the permissions granted by the ACL to the file
305 mode permission bits; in addition, the owner is granted the owner mode
306 bits and others are granted the other mode bits. If the auto_inherit
307 flag is set, the protected flag is also set to prevent the Automatic
308 Inheritance algorithm from modifying the ACL.
309 Permissions at file-creation time
311 When a directory has any inheritable ACL entries, the following happens
312 when a file or directory is created inside that directory:
313 1. A file created inside that directory will inherit all of the ACL
315 entries that have the file_inherit flag set, and all inheritance-
316 related flags in the inherited entries flag will be cleared.
317 A subdirectory created inside that directory will inherit all of
319 the ACL entries that either have the dir_inherit flag set, or the
320 file_inherit flag set and the no_propagate flag not set. Entries
321 whose dir_inherit flag is set will have their inherit_only flag
322 cleared, and entries whose dir_inherit flag is not set will have
323 their inherit_only flag set. Finally, entries whose no_propagate
324 flag is set will have all inheritance-related flags cleared.
325 2. If the parent directory's ACL has the auto_inherit flag set, then
327 the inherited ACL will have its auto_inherit flag set, and all
328 entries will have their inherited flag set. Otherwise, the
329 auto_inherit and inherited flags are cleared.
330 3. The three file masks are computed from the inherited ACL as
332 described in the section Computing the maximum file masks.
333 4. The three sets of permissions for the owner, the group, and for
335 others in the mode parameter as given to open(2), mkdir(2), and
336 similar are converted into sets of RichACL permissions. The corre‐
337 spondence between mask flags and RichACL permission bits is
338 described in the section Changing the file mode permission bits.
339 Any RichACL permissions not included in those sets are removed from
340 the owner, group, and other file masks. The file mode permission
341 bits are then computed from the file masks as described in the sec‐
342 tion Assigning an Access Control List. The process umask (see
343 umask(2)) is ignored.
344 5. The masked ACL flag is set. The write_through ACL flag remains
346 cleared. In addition, if the auto_inherit flag of the inherited ACL
347 is set, the protected flag is also set to prevent the Automatic
348 Inheritance algorithm from modifying the ACL.
349 When a directory does not have inheritable ACL entries, files and
351 directories created inside that directory will not be assigned Access
352 Control Lists and the file mode permission bits will be set to
353 (mode & ~umask) where mode is the mode argument of the relevant system
354 call and umask is the process umask (see umask(2)).
355 Automatic Inheritance
357 Automatic Inheritance is a mechanism that allows permission changes to
358 propagate from a directory to files and subdirectories inside that
359 directory, recursively. Propagation is carried out by the process
360 changing the directory permissions (usually, setrichacl(1)); it happens
361 without user intervention albeit not entirely automatically.
362 A significant limitation of the Automatic Inheritance feature is that
364 this mechanism works only as long as files are created without explic‐
365 itly specifying the file permissions to use. The standard system calls
366 for creating files and directories (open(2), mkdir(2), mknod(2), and so
367 on) all have mandatory mode parameters which define the maximum allowed
368 permissions of the new files. To take account of this restriction, the
369 protected ACL flag must be set if the inherited flag is set. This
370 effectively disables Automatic Inheritance for that particular file.
371 Notwithstanding the aforementioned limitation, Automatic Inheritance
373 still remains useful for network protocols like NFSv4 and SMB, which
374 both support creating files and directories without defining their per‐
375 missions. These protocols can implement those operations by using the
376 standard system calls and by then undoing the effect of applying the
377 mode parameters.
378 When the ACL of a directory is changed, the following happens for each
380 entry (“child”) inside that directory:
381 1. If the entry is a symbolic link, skip the child.
383 2. If the auto_inherit flag of the entry's ACL is not set or the pro‐
385 tected flag is set, skip the child.
386 3. With the child's ACL:
388 a) If the defaulted flag is set, replace the ACL with an empty ACL
390 with the auto_inherit flag set.
391 b) Delete all entries which have the inherited flag set.
393 c) Append all entries inherited from the parent directory accord‐
395 ing to step 1 of the algorithm described under Permissions at
396 file-creation time. Set the inherited flag of each of these
397 entries.
398 d) Recompute the file masks as decribed in the section Computing
400 the maximum file masks.
401 4. If the child is a directory, recursively apply this algorithm.
403 Access check algorithm
405 When a process requests a particular kind of access (expressed as a set
406 of RichACL permissions) to a file, the following algorithm determines
407 whether the access is granted or denied:
408 1. If the masked ACL flag is set, then:
410 a) If the write_through ACL flag is set, then:
412 · If the requesting process is the file owner, then access is
414 granted if the owner mask includes the requested permissions,
415 and is otherwise denied.
416 · If the requesting process is not the file owner and it is in
418 the owning group or matches any ACL entries other than every‐
419 one@, proceed to step b).
420 · If the requesting process is not the file owner, is not in
422 the owning group, and no ACL entries other than everyone@
423 match the process, then access is granted if the other mask
424 includes the requested permissions, and is otherwise denied.
425 b) If any of the following is true:
427 · the requesting process is the file owner and the owner mask
429 does not include all requested permissions,
430 · the requesting process is not the file owner and it is in the
432 owning group or matches any ACL entries other than everyone@,
433 and the group mask does not include all requested permis‐
434 sions,
435 · the requesting process is not the file owner, not in the own‐
437 ing group, it matches no ACL entries other than everyone@,
438 and the other mask does not include all requested permis‐
439 sions,
440 then access is denied.
442 2. Upon reaching this point, the determination of whether or not
444 access is granted is made by scanning all ACL entries to see if one
445 or more applicable entries together grant a cumulative set of per‐
446 missions that matches the requested permissions or there is an
447 applicable entry that explicitly denies one or more of the
448 requested permissions. The scan of all ACL entries begins by first
449 initializing the set of remaining permissions (i.e., those that
450 have not yet been satisfied during the scan) to be the set of
451 requested permissions. Then the ACL entries are scanned in order,
452 and for each entry:
453 a) If the inherit_only or unmapped flags are set, continue with
455 the next ACL entry.
456 b) If any of the following is true:
458 · the entry's identifier is owner@ and the requesting process
460 is the file owner,
461 · the entry's identifier is group@ and the requesting process
463 is in the owning group,
464 · the entry's identifier is a user and the requesting process
466 is owned by that user,
467 · the entry's identifier is a group and the requesting process
469 is a member in that group,
470 · the entry's identifier is everyone@,
472 then the entry matches the process; proceed to the next step.
474 Otherwise, continue with the next ACL entry.
475 c) If the entry denies any of the remaining permissions, access is
477 denied.
478 d) If the entry allows any of the remaining permissions, then:
480 · If the masked ACL flag is set and the entry's identifier is
482 not owner@ or everyone@ or is a user entry matching the file
483 owner, remove all permissions from the remaining permissions
484 which are both allowed by the entry and included in the group
485 mask,
486 · Otherwise, remove all permissions from the remaining permis‐
488 sions which are allowed by the entry.
489 3. If there are no more remaining permissions, access is allowed. Oth‐
491 erwise, access is denied.
492 In this algorithm, a process can gain the permissions it requires by
494 accumulating them from multiple RichACL entries. This is in contrast
495 with POSIX ACLs, where access is only granted if an ACL entry exists
496 that matches the requesting process and includes all the requested per‐
497 missions.
498 Computing the maximum file masks
500 When setting an ACL and no file masks have been explicitly specified
501 and when inheriting an ACL from the parent directory (as described in
502 the section Permissions at file-creation time), the following algorithm
503 is used for computing the file masks:
504 1. Clear the owner, group, and other file masks. Remember which per‐
506 missions have already been processed (initially, the empty set).
507 2. For each ACL entry:
509 · If the inherit_only flag is set, skip the entry.
511 · Otherwise, compute which permissions the entry allows or denies
513 that have not been processed yet (the remaining permissions).
514 · If the entry is an owner@ entry, add the remaining permissions to
516 the owner mask for allow entries, and remove the remaining per‐
517 missions from the owner mask for deny entries.
518 · Otherwise, if the entry is an everyone@ entry, proceed as with
520 owner@ entries but add or remove the remaining permissions from
521 the owner, group, and other file masks.
522 · Otherwise, proceed as with owner@ entries but add or remove the
524 remaining permissions from the owner and group file masks.
525 · Add the entry's permissions to the processed permissions.
527 The resulting file masks represent the ACL as closely as possible. With
529 these file masks, the effective permissions that the ACL grants will be
530 the same when the masked flag is set as when it is not set.
531
533 Written by Andreas Grünbacher <agruenba@redhat.com>.
534 Please send your bug reports, suggested features and comments to the
536 above address.
537
539 Rich Access Control Lists are Linux-specific.
540
542 richaclex(7), chmod(1), getrichacl(1), ls(1), setrichacl(1) stat(2),
543 umask(2), acl(5)
544Linux 2016-02-23 RICHACL(7)