1RICHACLEX(7) Rich Access Control Lists RICHACLEX(7)
2
6 richaclex - RichACL Examples
7
9 This man-page demonstrates the various features of Rich Access Control
10 Lists (RichACLs) by example, and shows how they interact with the POSIX
11 file permission bits.
12 For a complete description of the structure, concepts, and algorithms
14 involved, please refer to richacl(7).
15
17 Traditional POSIX file permissions as RichACLs
18 In the traditional POSIX file permission model, each file and directory
19 has a file mode that specifies the file type and file permission bits.
20 The file permission bits determine the permissions for the owner,
21 group, and other classes of processes. The owner class includes pro‐
22 cesses which are the file owner. The group class includes processes
23 which are not the file owner and which are either a user mentioned in
24 an ACL, or which are in the owning group or in a group mentioned in an
25 ACL. The other class includes all processes which are not in the owner
26 or group class.
27 In the absence of inheritable permissions, when a file or directory is
29 created, the effective file permissions of the new file or directory
30 are (mode & ~umask), where mode is the mode parameter to open(2),
31 mkdir(2), and similar, and umask is the process umask (see umask(2)):
32 $ umask
34 0022
35 $ touch f
36 $ ls -l f
37 -rw-r--r-- 1 agruenba users 0 Feb 24 09:37 f
38 Here, the umask has a value of 022. The touch(1) command calls open(2)
40 with a mode parameter of 0666 to create a new file, and the resulting
41 effective file permissions are 0644, displayed as rw-r--r-- by ls(1):
42 the owner has read and write access, and the group and other classes
43 have read access only.
44 These permissions are displayed as a RichACL as follows:
46 $ getrichacl f
48 f:
49 owner@:rwp----------::allow
50 everyone@:r------------::allow
51 $ getrichacl --long f
53 f:
54 owner@:read_data/write_data/append_data::allow
55 everyone@:read_data::allow
56 RichACLs have both a short text form in which each permission is repre‐
59 sented by a single letter, and a long text form in which each permis‐
60 sion is represented by an equivalent string. The owner@ special inden‐
61 tifier refers to the file owner, an the everyone@ special identifier
62 refers to everyone including the owner and the owning group. The POSIX
63 read permission maps to the RichACL read_data (r) permission; the POSIX
64 write permission maps to the RichACL write_data (w) and append_data (p)
65 permissions.
66 Creating directories works similarly:
68 $ mkdir d
70 $ ls -dl d
71 drwxr-xr-x 2 agruenba users 4096 Feb 24 09:37 d
72 Here, the mkdir(1) command calls mkdir(2) with a mode parameter of 0777
74 to create a new directory, and the resulting effective file permissions
75 are 0755, displayed as rwxr-xr-x by ls(1). The owner has read, write
76 and execute (search) access, and the group and other classes have read
77 and execute (search) access.
78 These permissions are displayed as a RichACL as follows:
80 $ getrichacl d
82 d:
83 owner@:rwpxd--------::allow
84 everyone@:r--x---------::allow
85 $ getrichacl --long d
87 d:
88 owner@:list_directory/add_file/add_subdirectory/execute/delete_child::allow
89 everyone@:list_directory/execute::allow
90 For directories, the POSIX read permission maps to the RichACL
93 list_directory (r) permission; the POSIX write permission maps to the
94 RichACL add_file (w), add_subdirectory (p), and delete_child (d) per‐
95 missions; the POSIX execute (search) permission maps to the RichACL
96 execute (x) permission. The long text forms for some of the permissions
97 differ between files and directories. When setting ACLs, either form
98 can be used interchangeably.
99 When the file permission bits of a file are set to the unusual value of
101 0604, the owning group will not have read access, but everyone else
102 will. This maps to the following RichACL:
103 $ chmod 604 f
105 $ getrichacl f
106 f:
107 owner@:rwp----------::allow
108 group@:r------------::deny
109 everyone@:r------------::allow
110 A deny entry for the owning group (group@) before the final allow entry
113 for everyone else indicates that the owning group is denied
114 read_data (r) access.
115 RichACLs
117 RichACLs can be used for granting users and groups additional permis‐
118 sions, or for denying them some permissions. This includes permissions
119 that go beyond what can be granted by the traditional POSIX read,
120 write, and execute permissions. The following example grants user Tim
121 the right to read, write, and append to a file, to change the file's
122 permissions (write_acl (C)), and to take ownership of the file
123 (write_owner (o)):
124 $ touch f
126 $ ls -l f
127 -rw-r--r-- 1 agruenba users 0 Feb 24 09:37 f
128 $ setrichacl --modify user:tim:rwpCo::allow f
129 $ getrichacl f
130 f:
131 owner@:rwp----------::allow
132 everyone@:r------------::allow
133 user:tim:rwp------Co--::allow
134 $ ls -l f
136 -rw-rw-r--+ 1 agruenba users 0 Feb 24 09:37 f
137 Setting the ACL has updated the file permission bits, and ls(1) shows a
139 + sign after the file permissions to indicate that the file now has an
140 ACL. The change in file permission bits indicates that one or more mem‐
141 bers of the group class now have POSIX write access, or a subset of
142 POSIX write access (in this case, the RichACL write_data (w) and
143 append_data (p) permissions).
144 The group class permissions are not the same as the permissions of the
146 owning group; the owning group still only has read_data (r) access.
147 In general, when the ACL of a file or directory is changed, the file
149 permission bits are updated to reflect the maximum permissions of each
150 of the file classes as closely as possible. Permissions that go beyond
151 the POSIX read, write, and execute permissions are not reflected in the
152 file permission bits.
153 Changing the file permission bits
155 When the file permission bits of a file or directory are changed with
156 chmod(2), POSIX requires that the new file permission bits define the
157 maximum permissions that any process is granted. Therefore, when the
158 file permission bits of file f from the previous example are changed to
159 0664 (their current value), the following happens:
160 $ chmod 664 f
162 $ ls -l f
163 -rw-rw-r--+ 1 agruenba users 0 Feb 24 09:37 f
164 $ getrichacl f
165 f:
166 owner@:rwp----------::allow
167 user:tim:rwp----------::allow
168 everyone@:r------------::allow
169 User Tim loses the write_acl (C) and write_owner (o) permissions. In
172 addition, the entry for the special identifier everyone@ moves to the
173 end of the ACL; this does not change the permissions that the ACL
174 grants.
175 When the file permission bits are changed so that only the file owner
177 has access to the file, the ACL changes in the following way:
178 $ chmod 600 f
180 $ ls -l f
181 -rw-------+ 1 agruenba users 0 Feb 24 09:37 f
182 $ getrichacl f
183 f:
184 owner@:rwp----------::allow
185 The ACL reflects that user Tim and the special identfier everyone@ no
188 longer have access to the file. The permissions prevously granted by
189 the ACL have not entirely disappeared, they are merely masked by the
190 new file permission bits, though (by way of the file masks; see
191 richacl(7)). When the file permission bits are changed back to their
192 previous value, those permissions become effective again:
193 $ chmod 664 f
195 $ ls -l f
196 -rw-rw-r--+ 1 agruenba users 0 Feb 24 09:37 f
197 $ getrichacl f
198 f:
199 owner@:rwp----------::allow
200 user:tim:rwp----------::allow
201 everyone@:r------------::allow
202 When the file permission bits are changed to the value 0666, we end up
205 with the following result:
206 $ chmod 666 f
208 $ ls -l f
209 -rw-rw-rw-+ 1 agruenba users 0 Feb 24 09:37 f
210 $ getrichacl f
211 f:
212 owner@:rwp----------::allow
213 user:tim:rwp----------::allow
214 group@:-wp----------::deny
215 everyone@:rwp----------::allow
216 By giving POSIX write access to the other class, the everyone@ special
219 identifier has gained write_data (w) and append_data (p) access to the
220 file. The owning group still only has read_data (r) access, though.
221 Inheritance of permissions at file-creation time
223 When a file or directory is created, the ACL of the parent directory
224 defines which of the parent's ACL entries the new file or directory
225 will inherit: files will inherit entries with the file_inherit (f) flag
226 set. Directories will inherit entries with the dir_inherit (d) flag
227 set. In addition, directories will inherit entries with the
228 file_inherit (f) flag set as inheritable-only permissions for their
229 children; the inherit_only (i) flag is set. The no_propagate (n) flag
230 can be used to inherit permissions one level deep only.
231 When a file or directory inherits permissions, the file permissions are
233 determined by the mode parameter as given to open(2), mkdir(2), and
234 similar, and by the inherited permissions; the process umask (see
235 umask(2)) is ignored.
236 The following example creates a directory and sets up inheritable per‐
238 missions for files and subdirectories (the example is indented and
239 padded with dashes for improved readability):
240 $ mkdir d
242 $ setrichacl --set '
243 > owner@:rwpxd:fd:allow
244 > user:tim:rwpxd:fd:allow
245 > group:staff:r--x-:f-:allow
246 > everyone@:r--x-:fd:allow' d
247 Of the four ACL entries, three are inheritable for files and directo‐
249 ries (the file_inherit (f) and dir_inherit (d) flags are set), and the
250 entry for group Staff is inheritable for files only (the
251 dir_inherit (d) flag is not set).
252 Files created inside d inherit the following permissions:
254 $ touch d/f
256 $ ls -l d/f
257 -rw-rw-r--+ 1 agruenba users 0 Feb 24 09:37 d/f
258 $ getrichacl d/f
259 d/f:
260 owner@:rwp----------::allow
261 user:tim:rwp----------::allow
262 group:staff:r------------::allow
263 everyone@:r------------::allow
264 The touch(1) command calls open(2) with a mode parameter of 0666 to
267 create a new file, so the execute (x) permission is masked by the file
268 permission bits. When the file permission bits are changed to the value
269 0775 with chmod(1), the ACL changes as follows:
270 $ chmod 775 d/f
272 $ getrichacl d/f
273 d/f:
274 owner@:rwpx---------::allow
275 user:tim:rwpx---------::allow
276 group:staff:r--x---------::allow
277 everyone@:r--x---------::allow
278 Directories created inside d inherit the following permissions:
281 $ mkdir d/d
283 $ ls -dl d/d
284 drwxrwxr-x+ 2 agruenba users 4096 Feb 24 09:37 d/d
285 $ getrichacl d/d
286 d/d:
287 owner@:rwpxd--------:fd:allow
288 user:tim:rwpxd--------:fd:allow
289 group:staff:r--x---------:fi:allow
290 everyone@:r--x---------:fd:allow
291 The inherit_only (i) flag of the entry for group Staff is set to indi‐
294 cate that the entry has no effect on the effective permissions of d/d.
295 When a file is created inside d/d, the inherit_only (i) flag in the
296 entry inherited by the file is cleared again, and the resulting ACL is
297 somilar to that of d/f.
298 Inheritance of file permission bits only
300 When the permissions inherited by a new file or directory can be
301 exactly represented by the file permission bits, only the file permis‐
302 sion bits of the new file or directory will be set, and no ACL will be
303 stored (no + sign is shown after the file permission bits):
304 $ ls -dl d
306 drw-------+ 3 agruenba users 4096 Feb 24 09:37 d
307 $ getrichacl d
308 d:
309 owner@:rwp----------:f:allow
310 $ touch d/f
312 $ ls -l d/f
313 -rw------- 1 agruenba users 0 Feb 24 09:37 d/f
314 $ getrichacl d/f
315 d/f:
316 owner@:rwp----------::allow
317 Automatic Inheritance
320 The NFSv4 and SMB network protocols support creating files and directo‐
321 ries without specifying any permissions for the new file or directory.
322 When the directory in which such a file is created has the
323 auto_inherit (a) ACL flag set, then the new files and directories cre‐
324 ated in the directory will have the auto_inherit (a) ACL flag set, and
325 each ACL entry inherited from the parent directory will have the inher‐
326 ited (a) flag set. For example, consider the following directory:
327 $ ls -dl d
329 drw-rw----+ 2 agruenba users 4096 Feb 24 09:37 d
330 $ getrichacl d
331 d:
332 flags:a
333 owner@:rwp----------:f:allow
334 user:tim:rwp----------:f:allow
335 When a file is created inside that directory without specifying any
338 file permissions, the file inherits the following ACL:
339 $ getrichacl d/f
341 d/f:
342 flags:a
343 owner@:rwp----------:a:allow
344 user:tim:rwp----------:a:allow
345 When the ACL of the directory is then changed, those changes propagate
348 to the file:
349 $ setrichacl --modify group:staff:r:f:allow d
351 $ getrichacl d/f
352 d:
353 flags:a
354 owner@:rwp----------:a:allow
355 user:tim:rwp----------:a:allow
356 group:staff:r------------:a:allow
357 When ACL entries are propagated from a directory to one of its children
360 (the files and directories inside the directory), all entries in the
361 child's ACL that have the inherited (a) flag set are removed, and the
362 child inherits ACL entries from the parent in the same way as when a
363 new file or directory is created. The inherited (a) flag of those
364 inherited entries is set. Existing entries in the child's ACL that do
365 not have the inherited (a) flag set are left untouched:
366 $ setrichacl --modify user:ada:rwp::allow d/f
368 $ getrichacl d/f
369 d:
370 flags:a
371 user:ada:rwp----------::allow
372 owner@:rwp----------:a:allow
373 user:tim:rwp----------:a:allow
374 group:staff:r------------:a:allow
375 $ setrichacl --modify group:staff:::allow d
377 $ getrichacl d
378 d:
379 flags:a
380 owner@:rwp----------:f:allow
381 user:tim:rwp----------:f:allow
382 $ getrichacl d/f
384 d:
385 flags:a
386 user:ada:rwp----------::allow
387 owner@:rwp----------:a:allow
388 user:tim:rwp----------:a:allow
389 We remove the allow entry for group Staff from the ACL by assigning it
392 an empty set of permissions.
393 When the file permission bits of a file or directory are changed with
395 chmod(2), the Automatic Inheritance algorithm must no longer override
396 those permissions. Likewise, when a file or directory is created with
397 open(2), mkdir(2), or similar, the mode parameter to those system calls
398 defines an upper limit to the file permission bits of the new file or
399 directory, and the Automatic Inheritance algorithm must no longer over‐
400 ride the resulting permissions. To achieve that, when the ACL of the
401 file or directory has the auto_inherit (a) flag set, those operations
402 set the protected (p) flag, which stops the Automatic Inheritance algo‐
403 rithm from modifying the ACL:
404 $ chmod 660 d/f
406 $ getrichacl d/f
407 d/f:
408 flags:ap
409 user:ada:rwp----------::allow
410 owner@:rwp----------:a:allow
411 user:tim:rwp----------:a:allow
412 $ touch d/g
414 $ getrichacl d/g
415 d/g:
416 flags:ap
417 owner@:rwp----------:a:allow
418 user:tim:rwp----------:a:allow
419 Effective permissions
422 With complex ACLs, it can become difficult to determine the permissions
423 of a particular user or group. In this situation, the --access option
424 of getrichacl(1) can be used:
425 $ getrichacl --access d/f
427 rwpx--------- d/f
428 $ getrichacl --access=tim d/f
429 rwpx--------- d/f
430 $ getrichacl --access=:staff d/f
431 r--x--------- d/f
432 When the --access option is used without arguments, getrichacl displays
434 the permissions the current process has for the specified file or
435 files. With a user name as the argument, getrichacl displays the per‐
436 missions of that user. With a colon followed by a group name, get‐
437 richacl displays the permissions of that group.
438
440 Written by Andreas Grünbacher <agruenba@redhat.com>.
441 Please send your bug reports, suggested features and comments to the
443 above address.
444
446 Rich Access Control Lists are Linux-specific.
447
449 getrichacl(1), setrichacl(1), richacl(7)
450Linux 2016-02-24 RICHACLEX(7)