1RICHACLEX(7)               Rich Access Control Lists              RICHACLEX(7)
2
3
4

NAME

6       richaclex - RichACL Examples
7

DESCRIPTION

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
13       For  a  complete description of the structure, concepts, and algorithms
14       involved, please refer to richacl(7).
15

EXAMPLES

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
28       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
33           $ umask
34           0022
35           $ touch f
36           $ ls -l f
37           -rw-r--r-- 1 agruenba users 0 Feb 24 09:37 f
38
39       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
45       These permissions are displayed as a RichACL as follows:
46
47           $ getrichacl f
48           f:
49               owner@:rwp----------::allow
50            everyone@:r------------::allow
51
52           $ getrichacl --long f
53           f:
54               owner@:read_data/write_data/append_data::allow
55            everyone@:read_data::allow
56
57
58       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
67       Creating directories works similarly:
68
69           $ mkdir d
70           $ ls -dl d
71           drwxr-xr-x 2 agruenba users 4096 Feb 24 09:37 d
72
73       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
79       These permissions are displayed as a RichACL as follows:
80
81           $ getrichacl d
82           d:
83               owner@:rwpxd--------::allow
84            everyone@:r--x---------::allow
85
86           $ getrichacl --long d
87           d:
88               owner@:list_directory/add_file/add_subdirectory/execute/delete_child::allow
89            everyone@:list_directory/execute::allow
90
91
92       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
100       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
104           $ chmod 604 f
105           $ getrichacl f
106           f:
107               owner@:rwp----------::allow
108               group@:r------------::deny
109            everyone@:r------------::allow
110
111
112       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
116   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
125           $ 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
135           $ ls -l f
136           -rw-rw-r--+ 1 agruenba users 0 Feb 24 09:37 f
137
138       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
145       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
148       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
154   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
161           $ 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
170
171       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
176       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
179           $ 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
186
187       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
194           $ 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
203
204       When  the file permission bits are changed to the value 0666, we end up
205       with the following result:
206
207           $ 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
217
218       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
222   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
232       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
237       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
241           $ 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
248       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
253       Files created inside d inherit the following permissions:
254
255           $ 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
265
266       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
271           $ 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
279
280       Directories created inside d inherit the following permissions:
281
282           $ 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
292
293       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
299   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
305           $ 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
311           $ 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
318
319   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
328           $ 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
336
337       When  a  file  is  created inside that directory without specifying any
338       file permissions, the file inherits the following ACL:
339
340           $ getrichacl d/f
341           d/f:
342               flags:a
343              owner@:rwp----------:a:allow
344            user:tim:rwp----------:a:allow
345
346
347       When the ACL of the directory is then changed, those changes  propagate
348       to the file:
349
350           $ 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
358
359       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
367           $ 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
376           $ 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
383           $ 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
390
391       We  remove the allow entry for group Staff from the ACL by assigning it
392       an empty set of permissions.
393
394       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
405           $ 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
413           $ 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
420
421   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
426           $ 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
433       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

AUTHOR

440       Written by Andreas Grünbacher <agruenba@redhat.com>.
441
442       Please  send  your  bug reports, suggested features and comments to the
443       above address.
444

CONFORMING TO

446       Rich Access Control Lists are Linux-specific.
447

SEE ALSO

449       getrichacl(1), setrichacl(1), richacl(7)
450
451
452
453Linux                             2016-02-24                      RICHACLEX(7)
Impressum