f016b737194c80d9115e14e34d13a39e9f9cdb7b
[openafs.git] / doc / xml / AdminGuide / auagd020.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="HDRWQ562">
3   <title>Managing Access Control Lists</title>
4
5   <para>To control access to a directory and all of the files in it, AFS associates an <emphasis>access control list</emphasis>
6   (<emphasis>ACL</emphasis>) with it, rather than the mode bits that the UNIX file system (UFS) associates with individual files or
7   directories. AFS ACLs provide more refined access control because there are seven access permissions rather than UFS's three, and
8   there is room for approximately 20 user or group entries on an ACL, rather than just the three UFS entries (<emphasis
9   role="bold">owner</emphasis>, <emphasis role="bold">group</emphasis>, and <emphasis role="bold">other</emphasis>).</para>
10
11   <sect1 id="HDRWQ563">
12     <title>Summary of Instructions</title>
13
14     <para>This chapter explains how to perform the following tasks by using the indicated commands:</para>
15
16     <informaltable frame="none">
17       <tgroup cols="2">
18         <colspec colwidth="57*" />
19
20         <colspec colwidth="43*" />
21
22         <tbody>
23           <row>
24             <entry>Examine access control list</entry>
25
26             <entry><emphasis role="bold">fs listacl</emphasis></entry>
27           </row>
28
29           <row>
30             <entry>Edit ACL's normal permissions section</entry>
31
32             <entry><emphasis role="bold">fs setacl</emphasis></entry>
33           </row>
34
35           <row>
36             <entry>Edit ACL's negative permissions section</entry>
37
38             <entry><emphasis role="bold">fs setacl</emphasis> with <emphasis role="bold">-negative</emphasis> flag</entry>
39           </row>
40
41           <row>
42             <entry>Replace an ACL</entry>
43
44             <entry><emphasis role="bold">fs setacl</emphasis> with <emphasis role="bold">-clear</emphasis> flag</entry>
45           </row>
46
47           <row>
48             <entry>Copy an ACL</entry>
49
50             <entry><emphasis role="bold">fs copyacl</emphasis></entry>
51           </row>
52
53           <row>
54             <entry>Remove obsolete AFS UIDs</entry>
55
56             <entry><emphasis role="bold">fs cleanacl</emphasis></entry>
57           </row>
58         </tbody>
59       </tgroup>
60     </informaltable>
61   </sect1>
62
63   <sect1 id="HDRWQ565">
64     <title>Protecting Data in AFS</title>
65
66     <indexterm>
67       <primary>protection of file data</primary>
68
69       <secondary>see also: <emphasis>ACL</emphasis></secondary>
70     </indexterm>
71
72     <indexterm>
73       <primary>protection of file data</primary>
74
75       <secondary>AFS compared to UFS<emphasis>ACL</emphasis></secondary>
76     </indexterm>
77
78     <para>This section describes the main differences between the AFS and UFS file protection systems, discusses the implications of
79     directory-level protections, and describes the seven access permissions.</para>
80
81     <sect2 id="HDRWQ566">
82       <title>Differences Between UFS and AFS Data Protection</title>
83
84       <indexterm>
85         <primary>UFS</primary>
86
87         <secondary>file protection compared to AFS</secondary>
88       </indexterm>
89
90       <indexterm>
91         <primary>protection of file data</primary>
92
93         <secondary>AFS compared to UFS<emphasis>ACL</emphasis></secondary>
94       </indexterm>
95
96       <indexterm>
97         <primary>ACL</primary>
98
99         <secondary>compared to UNIX protection</secondary>
100       </indexterm>
101
102       <para>The UFS mode bits data protection system and the AFS ACL system differ in the following ways: <itemizedlist>
103           <listitem>
104             <para>Protection at the file level (UFS) versus the directory level (AFS)</para>
105
106             <para>UFS associates a set of nine mode bits with each file element, three (<emphasis role="bold">rwx</emphasis>) for
107             each of the element's owner, owning group, and all other users. A similar set of mode bits on the file's directory
108             applies to the file only in an oblique way.</para>
109
110             <para>An AFS ACL instead protects all files in a directory in the same way. If a certain file is more sensitive than
111             others, store it in a directory with a more restrictive ACL.</para>
112
113             <para>Defining access at the directory level has important consequences: <indexterm>
114                 <primary>directory-level data protection</primary>
115
116                 <secondary>implications</secondary>
117               </indexterm> <itemizedlist>
118                 <listitem>
119                   <para>The permissions on a directory's ACL apply to all of the files in the directory. When you move a file to a
120                   different directory, you effectively change the access permissions that apply to it to those on its new
121                   directory's ACL. Changing a directory's ACL changes the protection on all the files in it.</para>
122                 </listitem>
123
124                 <listitem>
125                   <para>When you create a subdirectory, its initial ACL is created as a copy of its parent directory's ACL. You can
126                   then change the subdirectory's ACL independently. However, the parent directory's ACL continues to control access
127                   to the subdirectory in the following way: the parent directory's ACL must grant the <emphasis
128                   role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permission to a user (or a group the user
129                   belongs to) in order for the user to access the subdirectory at all.</para>
130
131                   <para>In general, then, it is best to assign fairly liberal access permissions to high-level directories
132                   (including user home directories). In particular, it often makes sense to grant at least the <emphasis
133                   role="bold">l</emphasis> permission to the <emphasis role="bold">system:anyuser</emphasis> or <emphasis
134                   role="bold">system:authuser</emphasis> group on high-level directories. For further discussion, see <link
135                   linkend="HDRWQ571">Using Groups on ACLs</link>.</para>
136                 </listitem>
137               </itemizedlist></para>
138           </listitem>
139
140           <listitem>
141             <para>How the mode bits are interpreted</para>
142
143             <para>Mode bits are the only file-protection system in UFS. AFS allows you to set the UNIX mode bits on a file in
144             addition to the ACL on its directory, but it interprets them differently. See <link linkend="HDRWQ580">How AFS
145             Interprets the UNIX Mode Bits</link>.</para>
146           </listitem>
147
148           <listitem>
149             <para>Three access permissions (UFS) versus seven (AFS)</para>
150
151             <para>UFS defines three access permissions in the form of mode bits: <emphasis role="bold">r</emphasis> (<emphasis
152             role="bold">read</emphasis>), <emphasis role="bold">w</emphasis> (<emphasis role="bold">write</emphasis>), and <emphasis
153             role="bold">x</emphasis> (<emphasis role="bold">execute</emphasis>). AFS defines seven permissions, which makes access
154             control more precise. For detailed descriptions, see <link linkend="HDRWQ567">The AFS ACL Permissions</link>.
155             <simplelist>
156                 <member><emphasis role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>)</member>
157
158                 <member><emphasis role="bold">d</emphasis> (<emphasis role="bold">delete</emphasis>)</member>
159
160                 <member><emphasis role="bold">i</emphasis> (<emphasis role="bold">insert</emphasis>)</member>
161
162                 <member><emphasis role="bold">k</emphasis> (<emphasis role="bold">lock</emphasis>)</member>
163
164                 <member><emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>)</member>
165
166                 <member><emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>)</member>
167
168                 <member><emphasis role="bold">w</emphasis> (<emphasis role="bold">write</emphasis>)</member>
169               </simplelist></para>
170           </listitem>
171
172           <listitem>
173             <para>Three defined users and groups (UFS) versus many (AFS)</para>
174
175             <para>UFS controls access for one user and two groups by providing a set of mode bits for each: the user who owns the
176             file or directory, a single defined group, and everyone who has an account on the system.</para>
177
178             <para>AFS, in contrast, allows you to place many entries (individual users or groups) on an ACL, granting a different
179             set of access permissions to each one. The number of possible entries is about 20, and depends on how much space each
180             entry occupies in the memory allocated for the ACL itself.</para>
181
182             <para>AFS defines two system groups, <emphasis role="bold">system:anyuser</emphasis> and <emphasis
183             role="bold">system:authuser</emphasis>, which represent all users and all authenticated users, respectively; for further
184             discussion, see <link linkend="HDRWQ571">Using Groups on ACLs</link>. In addition, users can define their own groups in
185             the Protection Database, consisting of individual users or machine IP addresses. Users who have the <emphasis
186             role="bold">a</emphasis> permission on an ACL can create entries for the system groups as well as groups defined by
187             themselves or other users. For information on defining groups, see <link linkend="HDRWQ531">Administering the Protection
188             Database</link>.</para>
189
190             <para>When a user requests access to a file or directory, the File Server sums together all of the permissions that the
191             relevant ACL extends to the user and to groups to which the user belongs. Placing group entries on ACLs therefore can
192             control access for many more users than the ACL can accommodate as individual entries.</para>
193           </listitem>
194         </itemizedlist></para>
195     </sect2>
196
197     <sect2 id="HDRWQ567">
198       <title>The AFS ACL Permissions</title>
199
200       <indexterm>
201         <primary>access</primary>
202
203         <secondary>permissions on ACL (see entries: <emphasis>permissions on ACL</emphasis>, <emphasis>ACL</emphasis>)</secondary>
204       </indexterm>
205
206       <indexterm>
207         <primary>permissions on ACL</primary>
208
209         <secondary>defined</secondary>
210       </indexterm>
211
212       <indexterm>
213         <primary>ACL</primary>
214
215         <secondary>permissions defined</secondary>
216       </indexterm>
217
218       <para>Functionally, the seven standard ACL permissions fall into two groups: one that applies to the directory itself and one
219       that applies to the files it contains.</para>
220
221       <sect3 id="HDRWQ568">
222         <title>The Four Directory Permissions</title>
223
224         <para>The four permissions in this group are meaningful with respect to the directory itself. For example, the <emphasis
225         role="bold">i</emphasis> (<emphasis role="bold">insert</emphasis>) permission does not control addition of data to a file,
226         but rather creation of a new file or subdirectory. <variablelist>
227             <varlistentry>
228               <term><emphasis role="bold">The l (lookup) permission</emphasis></term>
229
230               <listitem>
231                 <para>This permission functions as something of a gate keeper for access to the directory and its files, because a
232                 user must have it in order to exercise any other permissions. In particular, a user must have this permission to
233                 access anything in the directory's subdirectories, even if the ACL on a subdirectory grants extensive permissions.
234                 <indexterm>
235                     <primary>lookup ACL permission</primary>
236
237                     <secondary></secondary>
238
239                     <see>l ACL permission</see>
240                   </indexterm> <indexterm>
241                     <primary>l ACL permission</primary>
242                   </indexterm></para>
243
244                 <para>This permission enables a user to issue the following commands: <itemizedlist>
245                     <listitem>
246                       <para>The <emphasis role="bold">ls</emphasis> command to list the names of the files and subdirectories in the
247                       directory</para>
248                     </listitem>
249
250                     <listitem>
251                       <para>The <emphasis role="bold">ls -ld</emphasis> command to obtain complete status information for the
252                       directory element itself</para>
253                     </listitem>
254
255                     <listitem>
256                       <para>The <emphasis role="bold">fs listacl</emphasis> command to examine the directory's ACL</para>
257                     </listitem>
258                   </itemizedlist></para>
259
260                 <para>This permission does not enable a user to read the contents of a file in the directory, to issue the <emphasis
261                 role="bold">ls -l</emphasis> command on a file in the directory, or to issue the <emphasis role="bold">fs
262                 listacl</emphasis> command with the filename as the <emphasis role="bold">-path</emphasis> argument. Those
263                 operations require the <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) permission which
264                 is described in <link linkend="HDRWQ569">The Three File Permissions</link>.</para>
265
266                 <para>Similarly, this permission does not enable a user to issue the <emphasis role="bold">ls</emphasis>, <emphasis
267                 role="bold">ls -l</emphasis>, <emphasis role="bold">ls -ld</emphasis>, or <emphasis role="bold">fs
268                 listacl</emphasis> commands against a subdirectory of the directory. Those operations require the <emphasis
269                 role="bold">l</emphasis> permission on the ACL of the subdirectory itself.</para>
270               </listitem>
271             </varlistentry>
272
273             <varlistentry>
274               <term><emphasis role="bold">The i (insert) permission</emphasis></term>
275
276               <listitem>
277                 <para>This permission enables a user to add new files to the directory, either by creating or copying, and to create
278                 new subdirectories. It does not extend into any subdirectories, which are protected by their own ACLs. <indexterm>
279                     <primary>insert ACL permission</primary>
280
281                     <secondary></secondary>
282
283                     <see>i ACL permission</see>
284                   </indexterm> <indexterm>
285                     <primary>i ACL permission</primary>
286                   </indexterm></para>
287               </listitem>
288             </varlistentry>
289
290             <varlistentry>
291               <term><emphasis role="bold">The d (delete) permission</emphasis></term>
292
293               <listitem>
294                 <para>This permission enables a user to remove files and subdirectories from the directory or move them into other
295                 directories (assuming that the user has the <emphasis role="bold">i</emphasis> permission on the ACL of the other
296                 directories). <indexterm>
297                     <primary>delete ACL permission</primary>
298
299                     <secondary></secondary>
300
301                     <see>d ACL permission</see>
302                   </indexterm> <indexterm>
303                     <primary>d ACL permission</primary>
304                   </indexterm></para>
305               </listitem>
306             </varlistentry>
307
308             <varlistentry>
309               <term><emphasis role="bold">The a (administer) permission</emphasis></term>
310
311               <listitem>
312                 <para>This permission enables a user to change the directory's ACL. Members of the <emphasis
313                 role="bold">system:administrators</emphasis> group implicitly have this permission on every directory (that is, even
314                 if that group does not appear on the ACL). Similarly, the owner of a directory implicitly has this permission on its
315                 ACL and those of all directories below it that he or she owns. <indexterm>
316                     <primary>administer ACL permission</primary>
317
318                     <secondary></secondary>
319
320                     <see>a ACL permission</see>
321                   </indexterm> <indexterm>
322                     <primary>a ACL permission</primary>
323                   </indexterm></para>
324               </listitem>
325             </varlistentry>
326           </variablelist></para>
327       </sect3>
328
329       <sect3 id="HDRWQ569">
330         <title>The Three File Permissions</title>
331
332         <para>The three permissions in this group are meaningful with respect to files in a directory, rather than the directory
333         itself or its subdirectories. <variablelist>
334             <varlistentry>
335               <term><emphasis role="bold">The r (read) permission</emphasis></term>
336
337               <listitem>
338                 <para>This permission enables a user to read the contents of files in the directory and to issue the <emphasis
339                 role="bold">ls -l</emphasis> command to stat the file elements. <indexterm>
340                     <primary>read</primary>
341
342                     <secondary>ACL permission</secondary>
343
344                     <see>r ACL permission)</see>
345                   </indexterm> <indexterm>
346                     <primary>r ACL permission</primary>
347                   </indexterm></para>
348               </listitem>
349             </varlistentry>
350
351             <varlistentry>
352               <term><emphasis role="bold">The w (write) permission</emphasis></term>
353
354               <listitem>
355                 <para>This permission enables a user to modify the contents of files in the directory and to issue the <emphasis
356                 role="bold">chmod</emphasis> command to change their UNIX mode bits. <indexterm>
357                     <primary>write</primary>
358
359                     <secondary>ACL permission</secondary>
360
361                     <see>write ACL permission</see>
362                   </indexterm> <indexterm>
363                     <primary>w ACL permission</primary>
364                   </indexterm></para>
365               </listitem>
366             </varlistentry>
367
368             <varlistentry>
369               <term><emphasis role="bold">The k (lock) permission</emphasis></term>
370
371               <listitem>
372                 <para>This permission enables the user to run programs that issue system calls to lock files in the directory.
373                 <indexterm>
374                     <primary>lock ACL permission</primary>
375
376                     <secondary></secondary>
377
378                     <see>k ACL permission</see>
379                   </indexterm> <indexterm>
380                     <primary>k ACL permission</primary>
381                   </indexterm></para>
382               </listitem>
383             </varlistentry>
384           </variablelist></para>
385       </sect3>
386
387       <sect3 id="Header_635">
388         <title>The Eight Auxiliary Permissions</title>
389
390         <indexterm>
391           <primary>undefined ACL permissions</primary>
392         </indexterm>
393
394         <indexterm>
395           <primary>auxiliary ACL permissions</primary>
396         </indexterm>
397
398         <indexterm>
399           <primary>ACL</primary>
400
401           <secondary>auxiliary permissions</secondary>
402         </indexterm>
403
404         <para>AFS provides eight additional permissions that do not have a defined meaning, denoted by the uppercase letters
405         <emphasis role="bold">A</emphasis>, <emphasis role="bold">B</emphasis>, <emphasis role="bold">C</emphasis>, <emphasis
406         role="bold">D</emphasis>, <emphasis role="bold">E</emphasis>, <emphasis role="bold">F</emphasis>, <emphasis
407         role="bold">G</emphasis>, and <emphasis role="bold">H</emphasis>.</para>
408
409         <para>You can write application programs that assign a meaning to one or more of the permissions, and then place them on
410         ACLs to control file access by those programs. For example, you can modify a print program to recognize and interpret the
411         permissions, and then place them on directories that house files that the program accesses. Use the <emphasis role="bold">fs
412         listacl</emphasis> and <emphasis role="bold">fs setacl</emphasis> commands to display and set the auxiliary permissions on
413         ACLs just like the standard seven.</para>
414       </sect3>
415
416       <sect3 id="Header_636">
417         <title>Shorthand Notation for Sets of Permissions</title>
418
419         <indexterm>
420           <primary>ACL</primary>
421
422           <secondary>shorthand notation for grouping permissions</secondary>
423         </indexterm>
424
425         <indexterm>
426           <primary>shorthand notation</primary>
427
428           <secondary>ACL permissions</secondary>
429         </indexterm>
430
431         <para>You can combine the seven permissions in any way in an ACL entry, but certain combinations are more useful than
432         others. Four of the more common combinations have corresponding shorthand forms. When using the <emphasis role="bold">fs
433         setacl</emphasis> command to define ACL entries, you can provide either one or more of the individual letters that represent
434         the permissions, or one of the following shorthand forms: <variablelist>
435             <indexterm>
436               <primary>all shorthand for ACL permissions</primary>
437             </indexterm>
438
439             <varlistentry>
440               <term><emphasis role="bold">all</emphasis></term>
441
442               <listitem>
443                 <para>Represents all seven standard permissions (<emphasis role="bold">rlidwka</emphasis>). <indexterm>
444                     <primary>none shorthand for ACL permissions</primary>
445                   </indexterm></para>
446               </listitem>
447             </varlistentry>
448
449             <varlistentry>
450               <term><emphasis role="bold">none</emphasis></term>
451
452               <listitem>
453                 <para>Removes the entry from the ACL, leaving the user or group with no permissions. <indexterm>
454                     <primary>read</primary>
455
456                     <secondary>shorthand for ACL permissions</secondary>
457                   </indexterm></para>
458               </listitem>
459             </varlistentry>
460
461             <varlistentry>
462               <term><emphasis role="bold">read</emphasis></term>
463
464               <listitem>
465                 <para>Represents the <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) and <emphasis
466                 role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permissions. <indexterm>
467                     <primary>write</primary>
468
469                     <secondary>shorthand for ACL permissions</secondary>
470                   </indexterm></para>
471               </listitem>
472             </varlistentry>
473
474             <varlistentry>
475               <term><emphasis role="bold">write</emphasis></term>
476
477               <listitem>
478                 <para>Represents all permissions except <emphasis role="bold">a</emphasis> (<emphasis
479                 role="bold">administer</emphasis>): <emphasis role="bold">rlidwk</emphasis>.</para>
480               </listitem>
481             </varlistentry>
482           </variablelist></para>
483       </sect3>
484     </sect2>
485
486     <sect2 id="HDRWQ570">
487       <title>Using Normal and Negative Permissions</title>
488
489       <indexterm>
490         <primary>ACL</primary>
491
492         <secondary>normal vs. negative permissions</secondary>
493       </indexterm>
494
495       <indexterm>
496         <primary>normal ACL permissions</primary>
497
498         <secondary>defined</secondary>
499       </indexterm>
500
501       <indexterm>
502         <primary>negative ACL permissions</primary>
503
504         <secondary>defined</secondary>
505       </indexterm>
506
507       <para>ACLs enable you both to grant and to deny access to a directory and the files in it. To grant access, use the <emphasis
508       role="bold">fs setacl</emphasis> command to create an ACL entry that associates a set of permissions with a user or group, as
509       described in <link linkend="HDRWQ573">Setting ACL Entries</link>. When you use the <emphasis role="bold">fs listacl</emphasis>
510       command to display an ACL (as described in <link linkend="HDRWQ572">Displaying ACLs</link>), such entries appear underneath
511       the following header, which uses the term <emphasis>rights</emphasis> to refer to permissions:</para>
512
513       <programlisting>
514    Normal rights
515 </programlisting>
516
517       <para>There are two ways to deny access: <orderedlist>
518           <listitem>
519             <para>The recommended method is simply to omit an entry for the user or group from the ACL, or to omit the appropriate
520             permissions from the entry. Use the <emphasis role="bold">fs setacl</emphasis> command to remove or edit an existing
521             entry, using the instructions in <link linkend="HDRWQ574">To add, remove, or edit normal ACL permissions</link>. In most
522             circumstances, this method is enough to prevent access of certain kinds or by certain users. You must take care,
523             however, not to grant the undesired permissions to any groups to which such users belong.</para>
524           </listitem>
525
526           <listitem>
527             <para>The more explicit method for denying access is to use the <emphasis role="bold">-negative</emphasis> flag to the
528             <emphasis role="bold">fs setacl</emphasis> command to create an entry that associates <emphasis>negative
529             permissions</emphasis> with the user or group; for instructions, see <link linkend="HDRWQ575">To add, remove, or edit
530             negative ACL permissions</link>. The output from the <emphasis role="bold">fs listacl</emphasis> command lists negative
531             entries underneath the following header: <programlisting>
532    Negative rights
533 </programlisting></para>
534
535             <para>When determining what type of access to grant to a user, the File Server first compiles a set of permissions by
536             examining all of the entries in the <computeroutput>Normal rights</computeroutput> section of the ACL. It then subtracts
537             any permissions associated with the user (or with groups to which the user belongs) on the <computeroutput>Negative
538             rights</computeroutput> section of the ACL. Therefore, negative permissions always cancel out normal permissions.</para>
539
540             <para>Using negative permissions reverses the usual semantics of the <emphasis role="bold">fs setacl</emphasis> command,
541             introducing the potential for confusion. In particular, combining the <emphasis role="bold">none</emphasis> shorthand
542             and the <emphasis role="bold">-negative</emphasis> flag constitutes a double negative: by removing an entry from the
543             <computeroutput>Negative rights</computeroutput> section of the ACL, you enable a user once again to obtain permissions
544             via entries in the <computeroutput>Normal rights</computeroutput> section. Combining the <emphasis
545             role="bold">all</emphasis> shorthand with the <emphasis role="bold">-negative</emphasis> flag explicitly denies all
546             permissions.</para>
547
548             <para>Note also that it is pointless to create an entry in the <computeroutput>Negative rights</computeroutput> section
549             if an entry in the <computeroutput>Normal rights</computeroutput> section grants the denied permissions to the <emphasis
550             role="bold">system:anyuser</emphasis> group. In this case, users can obtain the permissions simply by using the
551             <emphasis role="bold">unlog</emphasis> command to discard their tokens. When they do so, the File Server recognizes them
552             as the <emphasis role="bold">anonymous</emphasis> user, who belongs to the <emphasis
553             role="bold">system:anyuser</emphasis> group but does not match the entries on the <computeroutput>Negative
554             rights</computeroutput> section of the ACL.</para>
555           </listitem>
556         </orderedlist></para>
557     </sect2>
558
559     <sect2 id="HDRWQ571">
560       <title>Using Groups on ACLs</title>
561
562       <indexterm>
563         <primary>group</primary>
564
565         <secondary>ACL entry, usefulness of</secondary>
566       </indexterm>
567
568       <indexterm>
569         <primary>ACL</primary>
570
571         <secondary>group entries, usefulness</secondary>
572       </indexterm>
573
574       <para>As previously mentioned, placing a group entry on an ACL enables you to control access for many users at once. You can
575       grant a new user access to many files and directories simply by adding the user to a group that appears on the relevant ACLs.
576       You can also create groups of machines, in which case any user logged on to the machine obtains the access that is granted to
577       the group. On directories where they have the <emphasis role="bold">a</emphasis> permission on the ACL, users can define their
578       own groups and can create ACL entries for any groups, not just groups that they create or own themselves. For instructions on
579       creating groups of users or machines, and a discussion of the most effective ways to use different types of groups, see <link
580       linkend="HDRWQ531">Administering the Protection Database</link>. <indexterm>
581           <primary>system groups</primary>
582
583           <secondary>using on ACLs</secondary>
584         </indexterm> <indexterm>
585           <primary>group</primary>
586
587           <secondary>system-defined on ACLs</secondary>
588         </indexterm> <indexterm>
589           <primary>ACL</primary>
590
591           <secondary>system groups on</secondary>
592         </indexterm> <indexterm>
593           <primary>system:anyuser group</primary>
594
595           <secondary>using on ACLs</secondary>
596         </indexterm> <indexterm>
597           <primary>system:authuser group</primary>
598
599           <secondary>using on ACLs</secondary>
600         </indexterm></para>
601
602       <para>AFS also defines the following two system groups, which can be very useful on ACLs because they potentially represent a
603       large group of people. For more information about these groups, see <link linkend="HDRWQ535">The System Groups</link>.
604       <variablelist>
605           <varlistentry>
606             <term><emphasis role="bold">system:anyuser</emphasis></term>
607
608             <listitem>
609               <para>Includes anyone who can access the cell's file tree, including users who have logged in as the local superuser
610               <emphasis role="bold">root</emphasis>, have connected to a local machine from somewhere outside the cell, and AFS
611               users who belong to a foreign cell. This group includes users who do not have tokens that are valid for the local AFS
612               servers; the servers recognize them as the user <emphasis role="bold">anonymous</emphasis>.</para>
613
614               <para>Note that creating an ACL entry for this group is the only way to extend access to AFS users from foreign cells,
615               unless you create local authentication accounts for them. <indexterm>
616                   <primary>ACL</primary>
617
618                   <secondary>foreign users on</secondary>
619                 </indexterm></para>
620             </listitem>
621           </varlistentry>
622
623           <varlistentry>
624             <term><emphasis role="bold">system:authuser</emphasis></term>
625
626             <listitem>
627               <para>Includes all users who have a valid AFS token obtained from the local cell's authentication service.</para>
628             </listitem>
629           </varlistentry>
630         </variablelist></para>
631
632       <para>It is particularly useful to grant the <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>)
633       permission to the <emphasis role="bold">system:anyuser</emphasis> group on the ACL of most directories in the file system,
634       especially at the upper levels. This permission enables users only to learn the names of files and subdirectories in a
635       directory, but without it they cannot traverse their way through the directories in the path to a target file.</para>
636
637       <para>A slightly more restrictive alternative is to grant the <emphasis role="bold">l</emphasis> permission to the <emphasis
638       role="bold">system:authuser</emphasis> group. If that is still not restrictive enough, you can grant the <emphasis
639       role="bold">l</emphasis> to specific users or groups, which cannot exceed about 20 in number on a given ACL.</para>
640
641       <para>Another reason to grant certain permissions to the <emphasis role="bold">system:anyuser</emphasis> group is to enable
642       the correct operation of processes that provide services such as printing and mail delivery. For example, in addition to the
643       <emphasis role="bold">l</emphasis> permission, a print process possibly needs the <emphasis role="bold">r</emphasis>
644       (<emphasis role="bold">read</emphasis>) permission in order to access the contents of files, and a mail delivery process
645       possibly requires the <emphasis role="bold">i</emphasis> (<emphasis role="bold">insert</emphasis>) permission to deliver new
646       pieces of mail.</para>
647
648       <para>The ACL on the root directory of every newly created volume grants all permissions to the <emphasis
649       role="bold">system:administrators</emphasis> group. You can remove this entry if you wish, but members of the <emphasis
650       role="bold">system:administrators</emphasis> group always implicitly have the <emphasis role="bold">a</emphasis> (<emphasis
651       role="bold">administer</emphasis>), and by default also the <emphasis role="bold">l</emphasis>, permission on every
652       directory's ACL. The <emphasis role="bold">a</emphasis> permission enables them to grant themselves other permissions
653       explicitly when necessary. To learn about changing this default set of permissions, see <link linkend="HDRWQ586">Administering
654       the system:administrators Group</link>.</para>
655     </sect2>
656   </sect1>
657
658   <sect1 id="HDRWQ572">
659     <title>Displaying ACLs</title>
660
661     <indexterm>
662       <primary>ACL</primary>
663
664       <secondary>displaying</secondary>
665     </indexterm>
666
667     <indexterm>
668       <primary>displaying</primary>
669
670       <secondary>ACL entries</secondary>
671     </indexterm>
672
673     <para>To display the ACL associated with a file, directory or symbolic link, issue the <emphasis role="bold">fs
674     listacl</emphasis> command. The output for a symbolic link displays the ACL that applies to its target file or directory, rather
675     than the ACL on the directory that houses the symbolic link.</para>
676
677     <para><emphasis role="bold">Note for AFS/DFS Migration Toolkit users:</emphasis> If the machine on which you issue the <emphasis
678     role="bold">fs listacl</emphasis> command is configured to access a DCE cell's DFS filespace via the AFS/DFS Migration Toolkit,
679     you can use the command to display the ACL on DFS files and directories. To display a DFS directory's Initial Container and
680     Initial Object ACL instead of the regular one, include the <emphasis role="bold">fs listacl</emphasis> command's <emphasis
681     role="bold">-id</emphasis> or <emphasis role="bold">-if</emphasis> flag. For instructions, see the <emphasis>OpenAFS/DFS
682     Migration Toolkit Administration Guide and Reference</emphasis>. The <emphasis role="bold">fs</emphasis> command interpreter
683     ignores the <emphasis role="bold">-id</emphasis> and <emphasis role="bold">-if</emphasis> flags if you include them when
684     displaying an AFS ACL. <indexterm>
685         <primary>fs commands</primary>
686
687         <secondary>listacl</secondary>
688       </indexterm><indexterm>
689         <primary>commands</primary>
690
691         <secondary>fs listacl</secondary>
692       </indexterm></para>
693
694     <sect2 id="Header_640">
695       <title>To display an ACL</title>
696
697       <orderedlist>
698         <listitem>
699           <para>Issue the <emphasis role="bold">fs listacl</emphasis> command. <programlisting>
700    % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;+]
701 </programlisting></para>
702
703           <para>where</para>
704
705           <variablelist>
706             <varlistentry>
707               <term><emphasis role="bold">la</emphasis></term>
708
709               <listitem>
710                 <para>Is an acceptable alias for <emphasis role="bold">listacl</emphasis> (and <emphasis
711                 role="bold">lista</emphasis> is the shortest acceptable abbreviation).</para>
712               </listitem>
713             </varlistentry>
714
715             <varlistentry>
716               <term><emphasis role="bold">dir/file path</emphasis></term>
717
718               <listitem>
719                 <para>Names one or more files or directories for which to display the ACL. For files, the output displays the ACL
720                 for its directory. If you omit this argument, the output is for the current working directory. Partial pathnames are
721                 interpreted relative to the current working directory. You can also use the following notation on its own or as part
722                 of a pathname: <variablelist>
723                     <varlistentry>
724                       <term><emphasis role="bold">.</emphasis></term>
725
726                       <listitem>
727                         <para>(A single period). Specifies the current working directory.</para>
728                       </listitem>
729                     </varlistentry>
730
731                     <varlistentry>
732                       <term><emphasis role="bold">..</emphasis></term>
733
734                       <listitem>
735                         <para>(Two periods). Specifies the current working directory's parent directory.</para>
736                       </listitem>
737                     </varlistentry>
738
739                     <varlistentry>
740                       <term><emphasis role="bold">*</emphasis></term>
741
742                       <listitem>
743                         <para>(The asterisk). Specifies each file and subdirectory in the current working directory. The ACL
744                         displayed for a file is always the same as for its directory, but the ACL for each subdirectory can
745                         differ.</para>
746                       </listitem>
747                     </varlistentry>
748                   </variablelist></para>
749               </listitem>
750             </varlistentry>
751           </variablelist>
752         </listitem>
753       </orderedlist>
754
755       <para>The following error message indicates that you do not have the permissions needed to display an ACL. To specify a
756       directory name as the dir/file path argument, you must have the <emphasis role="bold">l</emphasis> (<emphasis
757       role="bold">lookup</emphasis>) permission on the ACL. To specify a filename, you must also have the <emphasis
758       role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) permission on its directory's ACL.</para>
759
760       <programlisting>
761    fs: You don't have the required access permissions on 'dir/file path'
762 </programlisting>
763
764       <para>Members of the <emphasis role="bold">system:administrators</emphasis> group and the directory's owner (as reported by
765       the <emphasis role="bold">ls -ld</emphasis> command) implicitly have the <emphasis role="bold">a</emphasis> (<emphasis
766       role="bold">administer</emphasis>) permission on every directory's ACL, and can use the <emphasis role="bold">fs
767       setacl</emphasis> command to grant themselves the required permissions; for instructions, see <link linkend="HDRWQ573">Setting
768       ACL Entries</link>.</para>
769
770       <para>The output for each file or directory specified as dir/file path begins with the following header to identify it:</para>
771
772       <programlisting>
773    Access list for  dir/file path is
774 </programlisting>
775
776       <para>The <computeroutput>Normal rights</computeroutput> header appears on the next line, followed by lines that each pair a
777       user or group name and a set of permissions. The permissions appear as the single letters defined in <link
778       linkend="HDRWQ567">The AFS ACL Permissions</link>, and always in the order <emphasis role="bold">rlidwka</emphasis>. If there
779       are any negative permissions, the <computeroutput>Negative rights</computeroutput> header appears next, followed by pairs of
780       negative permissions.</para>
781
782       <para>The following example displays the ACL on user <emphasis role="bold">terry</emphasis>'s home directory in the Example
783       Corporation cell:</para>
784
785       <programlisting>
786    % <emphasis role="bold">fs la /afs/example.com/usr/terry</emphasis>
787    Access list for /afs/example.com/usr/terry is
788    Normal permissions:
789       system:authuser rl
790       pat rlw
791       terry rlidwka
792    Negative permissions:
793       terry:other-dept rl
794       jones rl
795 </programlisting>
796
797       <para>where <emphasis role="bold">pat</emphasis>, <emphasis role="bold">terry</emphasis>, and <emphasis
798       role="bold">jones</emphasis> are individual users, <emphasis role="bold">system:authuser</emphasis> is a system group, and
799       <emphasis role="bold">terry:other-dept</emphasis> is a group that <emphasis role="bold">terry</emphasis> owns. The list of
800       normal permissions grants all permissions to <emphasis role="bold">terry</emphasis>, the <emphasis role="bold">r</emphasis>
801       (<emphasis role="bold">read</emphasis>), <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>), and
802       <emphasis role="bold">w</emphasis> (<emphasis role="bold">write</emphasis>) permissions to <emphasis
803       role="bold">pat</emphasis>, and the <emphasis role="bold">r</emphasis> and <emphasis role="bold">l</emphasis> permissions to
804       the members of the <emphasis role="bold">system:authuser</emphasis> group.</para>
805
806       <para>The list of negative permissions denies the <emphasis role="bold">r</emphasis> and <emphasis role="bold">l</emphasis>
807       permissions to <emphasis role="bold">jones</emphasis> and the members of the <emphasis role="bold">terry:other-dept</emphasis>
808       group. These entries effectively prevent them from accessing <emphasis role="bold">terry</emphasis>'s home directory in any
809       way, because they cancel out the <emphasis role="bold">r</emphasis> and <emphasis role="bold">l</emphasis> permissions
810       extended to the <emphasis role="bold">system:authuser</emphasis> group, which is the only entry on the <computeroutput>Normal
811       rights</computeroutput> section of the ACL that possibly applies to them.</para>
812     </sect2>
813   </sect1>
814
815   <sect1 id="HDRWQ573">
816     <title>Setting ACL Entries</title>
817
818     <indexterm>
819       <primary>ACL</primary>
820
821       <secondary>setting entries</secondary>
822     </indexterm>
823
824     <indexterm>
825       <primary>ACL</primary>
826
827       <secondary>editing entries</secondary>
828     </indexterm>
829
830     <indexterm>
831       <primary>ACL</primary>
832
833       <secondary>adding entries</secondary>
834     </indexterm>
835
836     <indexterm>
837       <primary>ACL</primary>
838
839       <secondary>removing entries</secondary>
840     </indexterm>
841
842     <indexterm>
843       <primary>changing</primary>
844
845       <secondary>ACL entries</secondary>
846     </indexterm>
847
848     <indexterm>
849       <primary>setting</primary>
850
851       <secondary>ACL entries</secondary>
852     </indexterm>
853
854     <indexterm>
855       <primary>granting</primary>
856
857       <secondary>file access by setting ACL</secondary>
858     </indexterm>
859
860     <indexterm>
861       <primary>creating</primary>
862
863       <secondary>ACL entry</secondary>
864     </indexterm>
865
866     <indexterm>
867       <primary>adding</primary>
868
869       <secondary>ACL entry</secondary>
870
871       <tertiary>normal permissions</tertiary>
872     </indexterm>
873
874     <indexterm>
875       <primary>removing</primary>
876
877       <secondary>ACL entry</secondary>
878     </indexterm>
879
880     <para>To add, remove, or edit ACL entries, use the <emphasis role="bold">fs setacl</emphasis> command. By default, the command
881     manipulates entries on the normal permissions section of the ACL. To manipulate entries on the negative permissions section,
882     include the <emphasis role="bold">-negative</emphasis> flag.</para>
883
884     <para>You must have the <emphasis role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) permission on an ACL to
885     edit it. The owner of a directory (as reported by the <emphasis role="bold">ls -ld</emphasis>) command and members of the
886     <emphasis role="bold">system:administrators</emphasis> group always implicitly have it on every ACL. By default, members of the
887     <emphasis role="bold">system:administrators</emphasis> group also implicitly have the <emphasis role="bold">l</emphasis>
888     (<emphasis role="bold">lookup</emphasis>) permission.</para>
889
890     <para><emphasis role="bold">Note for AFS/DFS Migration Toolkit users:</emphasis> If the machine on which you issue the <emphasis
891     role="bold">fs setacl</emphasis> command is configured to access a DCE cell's DFS filespace via the AFS/DFS Migration Toolkit,
892     you can use the command to set the ACL on DFS files and directories. To set a DFS directory's Initial Container and Initial
893     Object ACL instead of the regular one, include the <emphasis role="bold">fs setacl</emphasis> command's <emphasis
894     role="bold">-id</emphasis> or <emphasis role="bold">-if</emphasis> flag. For instructions, see the <emphasis>OpenAFS/DFS
895     Migration Toolkit Administration Guide and Reference</emphasis>. The <emphasis role="bold">fs</emphasis> command interpreter
896     ignores the <emphasis role="bold">-id</emphasis> and <emphasis role="bold">-if</emphasis> flags if you include them when setting
897     an AFS ACL. <indexterm>
898         <primary>fs commands</primary>
899
900         <secondary>setacl</secondary>
901       </indexterm><indexterm>
902         <primary>commands</primary>
903
904         <secondary>fs setacl</secondary>
905       </indexterm></para>
906
907     <sect2 id="HDRWQ574">
908       <title>To add, remove, or edit normal ACL permissions</title>
909
910       <orderedlist>
911         <listitem>
912           <para>Verify that you have the <emphasis role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) permission
913           on each directory for which you are editing the ACL. If necessary, issue the <emphasis role="bold">fs listacl</emphasis>
914           command, which is fully described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
915    % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
916 </programlisting></para>
917         </listitem>
918
919         <listitem>
920           <para>Issue the <emphasis role="bold">fs setacl</emphasis> command to edit entries in the normal permissions section of
921           the ACL. To remove an entry, specify the <emphasis role="bold">none</emphasis> shorthand as the permissions. If an ACL
922           entry already exists, the permissions you specify completely replace those in the existing entry. <programlisting>
923    % <emphasis role="bold">fs setacl  -dir</emphasis> &lt;<replaceable>directory</replaceable>&gt;+ <emphasis role="bold">-acl</emphasis> &lt;<replaceable>access list entries</replaceable>&gt;+
924 </programlisting></para>
925
926           <para>where</para>
927
928           <variablelist>
929             <varlistentry>
930               <term><emphasis role="bold">sa</emphasis></term>
931
932               <listitem>
933                 <para>Is an acceptable alias for <emphasis role="bold">setacl</emphasis> (and <emphasis role="bold">seta</emphasis>
934                 is the shortest acceptable abbreviation).</para>
935               </listitem>
936             </varlistentry>
937
938             <varlistentry>
939               <term><emphasis role="bold">-dir</emphasis></term>
940
941               <listitem>
942                 <para>Names one or more directories to which to apply the ACL entries defined by the <emphasis
943                 role="bold">-acl</emphasis> argument. Partial pathnames are interpreted relative to the current working
944                 directory.</para>
945
946                 <para>Specify the read/write path to each directory, to avoid the failure that results when you attempt to change a
947                 read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the
948                 pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). For further discussion of the
949                 concept of read/write and read-only paths through the filespace, see <link linkend="HDRWQ209">The Rules of Mount
950                 Point Traversal</link>.</para>
951
952                 <para>You can also use the following notation on its own or as part of a pathname:</para>
953
954                 <variablelist>
955                   <varlistentry>
956                     <term><emphasis role="bold">.</emphasis></term>
957
958                     <listitem>
959                       <para>(A single period). If used by itself, sets the ACL on the current working directory.</para>
960                     </listitem>
961                   </varlistentry>
962
963                   <varlistentry>
964                     <term><emphasis role="bold">..</emphasis></term>
965
966                     <listitem>
967                       <para>(Two periods). If used by itself, sets the ACL on the current working directory's parent
968                       directory.</para>
969                     </listitem>
970                   </varlistentry>
971
972                   <varlistentry>
973                     <term><emphasis role="bold">*</emphasis></term>
974
975                     <listitem>
976                       <para>(The asterisk). Sets the ACL on each of the subdirectories in the current working directory. You must
977                       precede it with the <emphasis role="bold">-dir</emphasis> switch, since it potentially designates multiple
978                       directories. The <emphasis role="bold">fs</emphasis> command interpreter generates the following error message
979                       for each file in the directory: <programlisting>
980    fs: 'filename': Not a directory
981 </programlisting></para>
982                     </listitem>
983                   </varlistentry>
984                 </variablelist>
985
986                 <para>If you specify only one directory or file name, you can omit the <emphasis role="bold">-dir</emphasis> and
987                 <emphasis role="bold">-acl</emphasis> switches.</para>
988               </listitem>
989             </varlistentry>
990
991             <varlistentry>
992               <term><emphasis role="bold">-acl</emphasis></term>
993
994               <listitem>
995                 <para>Specifies one or more ACL entries, each of which pairs a user or group name and a set of permissions. Separate
996                 the pairs, and the two parts of each pair, with one or more spaces.</para>
997
998                 <para>To define the permissions, provide either:</para>
999
1000                 <itemizedlist>
1001                   <listitem>
1002                     <para>One or more of the letters that represent the standard or auxiliary permissions (<emphasis
1003                     role="bold">rlidwka</emphasis> and <emphasis role="bold">ABCDEFGH</emphasis>), in any order</para>
1004                   </listitem>
1005
1006                   <listitem>
1007                     <para>One of the four shorthand notations: <itemizedlist>
1008                         <listitem>
1009                           <para><emphasis role="bold">all</emphasis> (equals <emphasis role="bold">rlidwka</emphasis>)</para>
1010                         </listitem>
1011
1012                         <listitem>
1013                           <para><emphasis role="bold">none</emphasis> (removes the entry)</para>
1014                         </listitem>
1015
1016                         <listitem>
1017                           <para><emphasis role="bold">read</emphasis> (equals <emphasis role="bold">rl</emphasis>)</para>
1018                         </listitem>
1019
1020                         <listitem>
1021                           <para><emphasis role="bold">write</emphasis> (equals <emphasis role="bold">rlidwk</emphasis>)</para>
1022                         </listitem>
1023                       </itemizedlist></para>
1024                   </listitem>
1025                 </itemizedlist>
1026
1027                 <para>For a more detailed description of the permissions and shorthand notations, see <link linkend="HDRWQ567">The
1028                 AFS ACL Permissions</link>.</para>
1029
1030                 <para>On a single command line, you can combine user and group entries. You can also use individual letters in some
1031                 pairs and the shorthand notations in other pairs, but cannot combine letters and shorthand notation within a single
1032                 pair.</para>
1033               </listitem>
1034             </varlistentry>
1035           </variablelist>
1036         </listitem>
1037       </orderedlist>
1038
1039       <para>Either of the following examples grants user <emphasis role="bold">pat</emphasis> the <emphasis role="bold">r</emphasis>
1040       (<emphasis role="bold">read</emphasis>) and <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>)
1041       permissions on the ACL of the <emphasis role="bold">notes</emphasis> subdirectory in the issuer's home directory. They
1042       illustrate how it is possible to omit the <emphasis role="bold">-dir</emphasis> and <emphasis role="bold">-acl</emphasis>
1043       switches when you name only one directory.</para>
1044
1045       <programlisting>
1046    % <emphasis role="bold">fs sa ~/notes pat rl</emphasis>
1047    % <emphasis role="bold">fs sa ~/notes pat read</emphasis>
1048 </programlisting>
1049
1050       <para>The following example edits the ACL for the current working directory. It removes the entry for the <emphasis
1051       role="bold">system:anyuser</emphasis> group, and adds two entries: one grants all permissions except <emphasis
1052       role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) to the members of the <emphasis
1053       role="bold">terry:colleagues</emphasis> group and the other grants the <emphasis role="bold">r</emphasis> (<emphasis
1054       role="bold">read</emphasis>) and <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permissions to
1055       the <emphasis role="bold">system:authuser</emphasis> group. The command appears on two lines here only for legibility.</para>
1056
1057       <programlisting>
1058    % <emphasis role="bold">fs  sa  -dir . -acl  system:anyuser  none  terry:colleagues  write  \
1059            system:authuser  rl</emphasis>
1060 </programlisting>
1061
1062       <indexterm>
1063         <primary>fs commands</primary>
1064
1065         <secondary>setacl</secondary>
1066
1067         <tertiary>with -negative flag</tertiary>
1068       </indexterm>
1069
1070       <indexterm>
1071         <primary>commands</primary>
1072
1073         <secondary>fs setacl</secondary>
1074
1075         <tertiary>with -negative flag</tertiary>
1076       </indexterm>
1077
1078       <indexterm>
1079         <primary>creating</primary>
1080
1081         <secondary>ACL entry in negative permissions section</secondary>
1082       </indexterm>
1083
1084       <indexterm>
1085         <primary>adding</primary>
1086
1087         <secondary>ACL entry</secondary>
1088
1089         <tertiary>negative permissions</tertiary>
1090       </indexterm>
1091
1092       <indexterm>
1093         <primary>denying</primary>
1094
1095         <secondary>file access with negative ACL entry</secondary>
1096       </indexterm>
1097     </sect2>
1098
1099     <sect2 id="HDRWQ575">
1100       <title>To add, remove, or edit negative ACL permissions</title>
1101
1102       <orderedlist>
1103         <listitem>
1104           <para>Verify that you have the <emphasis role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) permission
1105           on each directory for which you are editing the ACL. If necessary, issue the <emphasis role="bold">fs listacl</emphasis>
1106           command, which is fully described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
1107    % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
1108 </programlisting></para>
1109         </listitem>
1110
1111         <listitem>
1112           <para>Issue the <emphasis role="bold">fs setacl</emphasis> command with the <emphasis role="bold">-negative</emphasis>
1113           flag to edit entries in the negative permissions section of the ACL. To remove an entry, specify the <emphasis
1114           role="bold">none</emphasis> shorthand as the permissions. If an ACL entry already exists for a user or group, the
1115           permissions you specify completely replace those in the existing entry. <programlisting>
1116    % <emphasis role="bold">fs setacl -dir</emphasis> &lt;<replaceable>directory</replaceable>&gt;+ <emphasis role="bold">-acl</emphasis> &lt;<replaceable>access list entries</replaceable>&gt;+  <emphasis
1117                 role="bold">-negative</emphasis> 
1118 </programlisting></para>
1119
1120           <para>where</para>
1121
1122           <variablelist>
1123             <varlistentry>
1124               <term><emphasis role="bold">sa</emphasis></term>
1125
1126               <listitem>
1127                 <para>Is an acceptable alias for <emphasis role="bold">setacl</emphasis> (and <emphasis role="bold">seta</emphasis>
1128                 is the shortest acceptable abbreviation).</para>
1129               </listitem>
1130             </varlistentry>
1131
1132             <varlistentry>
1133               <term><emphasis role="bold">-dir</emphasis></term>
1134
1135               <listitem>
1136                 <para>Names one or more directories to which to apply the negative ACL entries defined by the <emphasis
1137                 role="bold">-acl</emphasis> argument. Specify the read/write path to each directory, to avoid the failure that
1138                 results when you attempt to change a read-only volume. For a detailed description of acceptable values, see <link
1139                 linkend="HDRWQ574">To add, remove, or edit normal ACL permissions</link>.</para>
1140               </listitem>
1141             </varlistentry>
1142
1143             <varlistentry>
1144               <term><emphasis role="bold">-acl</emphasis></term>
1145
1146               <listitem>
1147                 <para>Specifies one or more ACL entries, each of which pairs a user or group name and a set of permissions. Separate
1148                 the pairs, and the two parts of each pair, with one or more spaces. For a detailed description of acceptable values,
1149                 see <link linkend="HDRWQ574">To add, remove, or edit normal ACL permissions</link>. Keep in mind that the usual
1150                 meaning of each permission is reversed.</para>
1151               </listitem>
1152             </varlistentry>
1153
1154             <varlistentry>
1155               <term><emphasis role="bold">-negative</emphasis></term>
1156
1157               <listitem>
1158                 <para>Places the entries defined by the <emphasis role="bold">-acl</emphasis> argument on the negative permissions
1159                 section of the ACL for each directory named by the <emphasis role="bold">-dir</emphasis> argument.</para>
1160               </listitem>
1161             </varlistentry>
1162           </variablelist>
1163         </listitem>
1164       </orderedlist>
1165
1166       <para>The following example denies user <emphasis role="bold">pat</emphasis> the <emphasis role="bold">w</emphasis> (<emphasis
1167       role="bold">write</emphasis>) and <emphasis role="bold">d</emphasis> (<emphasis role="bold">delete</emphasis>) permissions for
1168       the <emphasis role="bold">project</emphasis> subdirectory of the current working directory.</para>
1169
1170       <programlisting>
1171    % <emphasis role="bold">fs sa project pat wd -neg</emphasis>
1172 </programlisting>
1173     </sect2>
1174   </sect1>
1175
1176   <sect1 id="HDRWQ576">
1177     <title>Completely Replacing an ACL</title>
1178
1179     <indexterm>
1180       <primary>ACL</primary>
1181
1182       <secondary>replacing all entries</secondary>
1183     </indexterm>
1184
1185     <indexterm>
1186       <primary>ACL</primary>
1187
1188       <secondary>clearing</secondary>
1189     </indexterm>
1190
1191     <indexterm>
1192       <primary>replacing</primary>
1193
1194       <secondary>all entries on ACL</secondary>
1195     </indexterm>
1196
1197     <indexterm>
1198       <primary>erasing</primary>
1199
1200       <secondary>all ACL entries</secondary>
1201     </indexterm>
1202
1203     <indexterm>
1204       <primary>clearing</primary>
1205
1206       <secondary>all ACL entries</secondary>
1207     </indexterm>
1208
1209     <indexterm>
1210       <primary>removing</primary>
1211
1212       <secondary>all ACL entries</secondary>
1213     </indexterm>
1214
1215     <para>It is sometimes simplest to clear an ACL completely before defining new permissions on it, for instance if the mix of
1216     normal and negative permissions makes it difficult to understand how their interaction affects a user's access to the directory.
1217     To clear an ACL completely while you define new entries, include the <emphasis role="bold">-clear</emphasis> flag on the
1218     <emphasis role="bold">fs setacl</emphasis> command. When you include this flag, you can create entries on either the normal
1219     permissions or the negative permissions section of the ACL, but not on both at once.</para>
1220
1221     <para>Remember to create an entry that grants appropriate permissions to the directory's owner. The owner implicitly has the
1222     <emphasis role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) permission required to replace a deleted entry,
1223     but the effects of a missing ACL entry (particularly the lack of the <emphasis role="bold">lookup</emphasis> permission) can be
1224     so confusing that it becomes difficult for the owner to realize that the missing entry is causing the problems. <indexterm>
1225         <primary>fs commands</primary>
1226
1227         <secondary>setacl</secondary>
1228
1229         <tertiary>with -clear flag</tertiary>
1230       </indexterm> <indexterm>
1231         <primary>commands</primary>
1232
1233         <secondary>fs setacl</secondary>
1234
1235         <tertiary>with -clear flag</tertiary>
1236       </indexterm></para>
1237
1238     <sect2 id="Header_645">
1239       <title>To replace an ACL completely</title>
1240
1241       <orderedlist>
1242         <listitem>
1243           <para>Verify that you have the <emphasis role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) permission
1244           on each directory for which you are editing the ACL. If necessary, issue the <emphasis role="bold">fs listacl</emphasis>
1245           command, which is fully described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
1246    % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
1247 </programlisting></para>
1248         </listitem>
1249
1250         <listitem>
1251           <para>Issue the <emphasis role="bold">fs setacl</emphasis> command with the <emphasis role="bold">-clear</emphasis> flag
1252           to clear the ACL completely before setting either normal or negative permissions. Because you need to grant the owner of
1253           the directory all permissions, it is better in most cases to set normal permissions at this point. <programlisting>
1254    % <emphasis role="bold">fs setacl -dir</emphasis> &lt;<replaceable>directory</replaceable>&gt;+ <emphasis role="bold">-acl</emphasis> &lt;<replaceable>access list entries</replaceable>&gt;+ <emphasis
1255                 role="bold">-clear</emphasis>  \
1256                [<emphasis role="bold">-negative</emphasis>] 
1257 </programlisting></para>
1258
1259           <para>where</para>
1260
1261           <variablelist>
1262             <varlistentry>
1263               <term><emphasis role="bold">sa</emphasis></term>
1264
1265               <listitem>
1266                 <para>Is an acceptable alias for <emphasis role="bold">setacl</emphasis> (and <emphasis role="bold">seta</emphasis>
1267                 is the shortest acceptable abbreviation).</para>
1268               </listitem>
1269             </varlistentry>
1270
1271             <varlistentry>
1272               <term><emphasis role="bold">-dir</emphasis></term>
1273
1274               <listitem>
1275                 <para>Names one or more directories to which to apply the negative ACL entries defined by the <emphasis
1276                 role="bold">-acl</emphasis> argument. Specify the read/write path to each directory, to avoid the failure that
1277                 results when you attempt to change a read-only volume. For a detailed description of acceptable values, see <link
1278                 linkend="HDRWQ574">To add, remove, or edit normal ACL permissions</link>.</para>
1279               </listitem>
1280             </varlistentry>
1281
1282             <varlistentry>
1283               <term><emphasis role="bold">-acl</emphasis></term>
1284
1285               <listitem>
1286                 <para>Specifies one or more ACL entries, each of which pairs a user or group name and a set of permissions. Separate
1287                 the pairs, and the two parts of each pair, with one or more spaces. Remember to grant all permissions to the owner
1288                 of the directory. For a detailed description of acceptable values, see <link linkend="HDRWQ574">To add, remove, or
1289                 edit normal ACL permissions</link>.</para>
1290               </listitem>
1291             </varlistentry>
1292
1293             <varlistentry>
1294               <term><emphasis role="bold">-clear</emphasis></term>
1295
1296               <listitem>
1297                 <para>Removes all entries from each ACL before creating the entries indicated by the <emphasis
1298                 role="bold">-acl</emphasis> argument.</para>
1299               </listitem>
1300             </varlistentry>
1301
1302             <varlistentry>
1303               <term><emphasis role="bold">-negative</emphasis></term>
1304
1305               <listitem>
1306                 <para>Places the entries defined by the <emphasis role="bold">-acl</emphasis> argument on the negative permissions
1307                 section of each ACL.</para>
1308               </listitem>
1309             </varlistentry>
1310           </variablelist>
1311         </listitem>
1312       </orderedlist>
1313     </sect2>
1314   </sect1>
1315
1316   <sect1 id="HDRWQ577">
1317     <title>Copying ACLs Between Directories</title>
1318
1319     <indexterm>
1320       <primary>ACL</primary>
1321
1322       <secondary>copying between directories</secondary>
1323     </indexterm>
1324
1325     <indexterm>
1326       <primary>creating</primary>
1327
1328       <secondary>ACL as copy of another</secondary>
1329     </indexterm>
1330
1331     <indexterm>
1332       <primary>copying</primary>
1333
1334       <secondary>ACL between directories</secondary>
1335     </indexterm>
1336
1337     <para>The <emphasis role="bold">fs copyacl</emphasis> command copies a source directory's ACL to one or more destination
1338     directories. It does not affect the source ACL at all, but changes each destination ACL as follows: <itemizedlist>
1339         <listitem>
1340           <para>If an entry on the source ACL does not exist on the destination ACL, the command copies it to the destination
1341           ACL.</para>
1342         </listitem>
1343
1344         <listitem>
1345           <para>If an entry on the destination ACL does not also exist on the source ACL, the command does not remove it unless you
1346           include the <emphasis role="bold">-clear</emphasis> flag to overwrite the destination ACL completely.</para>
1347         </listitem>
1348
1349         <listitem>
1350           <para>If an entry is on both ACLs, the command changes the permissions on the destination ACL entry to match the source
1351           ACL entry.</para>
1352         </listitem>
1353       </itemizedlist></para>
1354
1355     <para><emphasis role="bold">Note for AFS/DFS Migration Toolkit users:</emphasis> If the machine is configured to enable AFS
1356     users to access a DCE cell's DFS filespace via the AFS/DFS Migration Toolkit, then you can use the <emphasis role="bold">fs
1357     copyacl</emphasis> command to copy ACLs between DFS files and directories also. The command includes <emphasis
1358     role="bold">-id</emphasis> and <emphasis role="bold">-if</emphasis> flags for altering a DFS directory's Initial Container and
1359     Initial Object ACLs as well as its regular ACL; see the <emphasis>OpenAFS/DFS Migration Toolkit Administration Guide and
1360     Reference</emphasis>. You cannot copy ACLs between AFS and DFS directories, because they use different ACL formats. The
1361     <emphasis role="bold">fs</emphasis> command interpreter ignores the <emphasis role="bold">-id</emphasis> and <emphasis
1362     role="bold">-if</emphasis> flags if you include them when copying AFS ACLs. <indexterm>
1363         <primary>fs commands</primary>
1364
1365         <secondary>copyacl</secondary>
1366       </indexterm><indexterm>
1367         <primary>commands</primary>
1368
1369         <secondary>fs copyacl</secondary>
1370       </indexterm></para>
1371
1372     <sect2 id="Header_647">
1373       <title>To copy an ACL between directories</title>
1374
1375       <orderedlist>
1376         <listitem>
1377           <para>Verify that you have the <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permission on
1378           the source ACL and the <emphasis role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) permission on each
1379           destination ACL. To identify the source directory by naming a file in it, you must also have the <emphasis
1380           role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) permission on the source ACL. If necessary, issue the
1381           <emphasis role="bold">fs listacl</emphasis> command, which is fully described in <link linkend="HDRWQ572">Displaying
1382           ACLs</link>. <programlisting>
1383    % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
1384 </programlisting></para>
1385         </listitem>
1386
1387         <listitem>
1388           <para>Issue the <emphasis role="bold">fs copyacl</emphasis> command to copy a source ACL to the ACL
1389           on one or more destination directories. (The command appears here on two lines only for legibility.) <programlisting>
1390    % <emphasis role="bold">fs copyacl -fromdir</emphasis> &lt;<replaceable>source directory</replaceable>&gt; <emphasis role="bold">-todir</emphasis> &lt;<replaceable>destination directory</replaceable>&gt;+  \
1391                 [<emphasis role="bold">-clear</emphasis>]
1392 </programlisting></para>
1393
1394           <para>where</para>
1395
1396           <variablelist>
1397             <varlistentry>
1398               <term><emphasis role="bold">co</emphasis></term>
1399
1400               <listitem>
1401                 <para>Is the shortest acceptable abbreviation for <emphasis role="bold">copyacl</emphasis>.</para>
1402               </listitem>
1403             </varlistentry>
1404
1405             <varlistentry>
1406               <term><emphasis role="bold">-fromdir</emphasis></term>
1407
1408               <listitem>
1409                 <para>Names the source directory from which to copy the ACL. Partial pathnames are interpreted relative to the
1410                 current working directory. If this argument names a file, the ACL is copied from its directory.</para>
1411               </listitem>
1412             </varlistentry>
1413
1414             <varlistentry>
1415               <term><emphasis role="bold">-todir</emphasis></term>
1416
1417               <listitem>
1418                 <para>Names each destination directory to which to copy the source ACL. Partial pathnames are interpreted relative
1419                 to the current working directory. Filenames are not acceptable.</para>
1420
1421                 <para>Specify the read/write path to each directory, to avoid the failure that results when you attempt to change a
1422                 read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the
1423                 pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). For further discussion of the
1424                 concept of read/write and read-only paths through the filespace, see <link linkend="HDRWQ209">The Rules of Mount
1425                 Point Traversal</link>.</para>
1426               </listitem>
1427             </varlistentry>
1428
1429             <varlistentry>
1430               <term><emphasis role="bold">-clear</emphasis></term>
1431
1432               <listitem>
1433                 <para>Completely overwrites each destination directory's ACL with the source ACL.</para>
1434               </listitem>
1435             </varlistentry>
1436           </variablelist>
1437         </listitem>
1438       </orderedlist>
1439
1440       <para>The following example copies the ACL from the current working directory's <emphasis role="bold">notes</emphasis>
1441       subdirectory to the <emphasis role="bold">plans</emphasis> subdirectory. The issuer does not include the <emphasis
1442       role="bold">-clear</emphasis> flag, so the entry for user <emphasis role="bold">pat</emphasis> remains on the <emphasis
1443       role="bold">plans</emphasis> directory's ACL although there is no corresponding entry on the <emphasis
1444       role="bold">notes</emphasis> directory's ACL.</para>
1445
1446       <programlisting>
1447    % <emphasis role="bold">fs la notes plans</emphasis>
1448    Access list for notes is
1449    Normal permissions:
1450       terry rlidwka
1451       smith rl
1452       jones rl
1453    Access list for plans is
1454    Normal permissions:
1455       terry rlidwk
1456       pat rlidwk
1457    % <emphasis role="bold">fs copyacl notes plans</emphasis>
1458    % <emphasis role="bold">fs la notes plans</emphasis>
1459    Access list for notes is
1460    Normal permissions:
1461       terry rlidwka
1462       smith rl
1463       jones rl
1464    Access list for plans is
1465    Normal permissions:
1466       terry rlidwka
1467       pat rlidwk
1468       smith rl
1469       jones rl
1470 </programlisting>
1471
1472       <indexterm>
1473         <primary>ACL</primary>
1474
1475         <secondary>removing obsolete AFS IDs</secondary>
1476       </indexterm>
1477
1478       <indexterm>
1479         <primary>removing</primary>
1480
1481         <secondary>obsolete AFS IDs from ACL</secondary>
1482       </indexterm>
1483
1484       <indexterm>
1485         <primary>AFS UID</primary>
1486
1487         <secondary>removing obsolete from ACL</secondary>
1488       </indexterm>
1489
1490       <indexterm>
1491         <primary>AFS GID</primary>
1492
1493         <secondary>removing obsolete from ACL</secondary>
1494       </indexterm>
1495
1496       <indexterm>
1497         <primary>ACL</primary>
1498
1499         <secondary>cleaning</secondary>
1500       </indexterm>
1501     </sect2>
1502   </sect1>
1503
1504   <sect1 id="HDRWQ579">
1505     <title>Removing Obsolete AFS IDs from ACLs</title>
1506
1507     <para>When you remove a user or group entry from the Protection Database, the <emphasis role="bold">fs listacl</emphasis>
1508     command displays the user's AFS UID (or group's AFS GID) in ACL entries, rather than the name. In the following example, user
1509     <emphasis role="bold">terry</emphasis> has an ACL entry for the group <emphasis role="bold">terry:friends</emphasis> (AFS GID
1510     -567) on her home directory in the Example Corporation cell, and then removes the group from the Protection Database.</para>
1511
1512     <programlisting>
1513    % <emphasis role="bold">fs listacl /afs/example.com/usr/terry</emphasis>
1514    Access list for /afs/example.com/usr/terry is
1515    Normal permissions:
1516      terry:friends rlik
1517      system:anyuser l
1518      terry rlidwka
1519    % <emphasis role="bold">pts delete terry:friends</emphasis>
1520    % <emphasis role="bold">fs listacl /afs/example.com/usr/terry</emphasis>
1521    Access list for /afs/example.com/usr/terry is
1522    Normal permissions:
1523      -567 rlik
1524      system:anyuser l
1525      terry rlidwka
1526 </programlisting>
1527
1528     <para>Leaving AFS IDs on ACLs serves no function, because the ID no longer corresponds to an active user or group. Furthermore,
1529     if the ID is ever assigned to a new user or group, then the new possessor of the ID gains access that the owner of the directory
1530     actually intended for the previous possessor. (Reusing AFS IDs is not recommended precisely for this reason.)</para>
1531
1532     <para>To remove obsolete AFS UIDs from ACLs, use the <emphasis role="bold">fs cleanacl</emphasis> command. <indexterm>
1533         <primary>commands</primary>
1534
1535         <secondary>fs cleanacl</secondary>
1536       </indexterm> <indexterm>
1537         <primary>fs commands</primary>
1538
1539         <secondary>cleanacl</secondary>
1540       </indexterm></para>
1541
1542     <sect2 id="Header_649">
1543       <title>To clean obsolete AFS IDs from an ACL</title>
1544
1545       <orderedlist>
1546         <listitem>
1547           <para>Verify that you have the <emphasis role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) permission
1548           on each directory for which you are cleaning the ACL. If necessary, issue the <emphasis role="bold">fs listacl</emphasis>
1549           command, which is fully described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
1550    % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
1551 </programlisting></para>
1552         </listitem>
1553
1554         <listitem>
1555           <para>Issue the <emphasis role="bold">fs cleanacl</emphasis> command to remove entries for obsolete AFS IDs.
1556           <programlisting>
1557    % <emphasis role="bold">fs cleanacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;+]
1558 </programlisting></para>
1559
1560           <para>where</para>
1561
1562           <variablelist>
1563             <varlistentry>
1564               <term><emphasis role="bold">cl</emphasis></term>
1565
1566               <listitem>
1567                 <para>Is the shortest acceptable abbreviation of <emphasis role="bold">cleanacl</emphasis>.</para>
1568               </listitem>
1569             </varlistentry>
1570
1571             <varlistentry>
1572               <term><emphasis role="bold">dir/file path</emphasis></term>
1573
1574               <listitem>
1575                 <para>Names each directory for which to clean the ACL. If this argument names a file, its directory's ACL is
1576                 cleaned. Omit this argument to clean the current working directory's ACL.</para>
1577
1578                 <para>Specify the read/write path to each directory, to avoid the failure that results when you attempt to change a
1579                 read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the
1580                 pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). For further discussion of the
1581                 concept of read/write and read-only paths through the filespace, see <link linkend="HDRWQ209">The Rules of Mount
1582                 Point Traversal</link>.</para>
1583
1584                 <para>You can also use the following notation on its own or as part of a pathname:</para>
1585
1586                 <variablelist>
1587                   <varlistentry>
1588                     <term><emphasis role="bold">.</emphasis></term>
1589
1590                     <listitem>
1591                       <para>(A single period). If used by itself, cleans the current working directory's ACL.</para>
1592                     </listitem>
1593                   </varlistentry>
1594
1595                   <varlistentry>
1596                     <term><emphasis role="bold">..</emphasis></term>
1597
1598                     <listitem>
1599                       <para>(Two periods). If used by itself, cleans the ACL on the current working directory's parent
1600                       directory.</para>
1601                     </listitem>
1602                   </varlistentry>
1603
1604                   <varlistentry>
1605                     <term><emphasis role="bold">*</emphasis></term>
1606
1607                     <listitem>
1608                       <para>(The asterisk). Cleans the ACL of each of the subdirectories in the current working directory. However,
1609                       if you use the asterisk and there are obsolete AFS IDs on any directory's ACL, the following error message
1610                       appears for every file in the directory: <programlisting>
1611    fs: 'filename': Not a directory
1612 </programlisting></para>
1613                     </listitem>
1614                   </varlistentry>
1615                 </variablelist>
1616               </listitem>
1617             </varlistentry>
1618           </variablelist>
1619         </listitem>
1620       </orderedlist>
1621
1622       <para>If there are obsolete AFS IDs on a directory, the command interpreter displays its cleaned ACL under the following
1623       header.</para>
1624
1625       <programlisting>
1626    Access list for directory is now
1627 </programlisting>
1628
1629       <para>If a directory's ACL has no obsolete AFS IDs on it, the following message appears for each.</para>
1630
1631       <programlisting>
1632    Access list for directory is fine.
1633 </programlisting>
1634     </sect2>
1635   </sect1>
1636
1637   <sect1 id="HDRWQ580">
1638     <title>How AFS Interprets the UNIX Mode Bits</title>
1639
1640     <indexterm>
1641       <primary>UNIX</primary>
1642
1643       <secondary>mode bits, interpretation in AFS</secondary>
1644     </indexterm>
1645
1646     <indexterm>
1647       <primary>UFS</primary>
1648
1649       <secondary>mode bits, interpretation in AFS</secondary>
1650     </indexterm>
1651
1652     <indexterm>
1653       <primary>mode bits (UNIX)</primary>
1654
1655       <secondary>interpretation in AFS</secondary>
1656     </indexterm>
1657
1658     <para>Although AFS uses ACLs to protect file data rather than the mode bits that UFS uses, it does not ignore the mode bits
1659     entirely. When you issue the <emphasis role="bold">chmod</emphasis> command on an AFS file or directory, AFS changes the bits
1660     appropriately. To change a file's mode bits, you must have the AFS <emphasis role="bold">w</emphasis> (<emphasis
1661     role="bold">write</emphasis>) permission on the ACL of the file's directory. To change a directory's mode bits, you must have
1662     the <emphasis role="bold">d</emphasis> (<emphasis role="bold">delete</emphasis>), <emphasis role="bold">i</emphasis> (<emphasis
1663     role="bold">insert</emphasis>), and <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permissions on
1664     its ACL.</para>
1665
1666     <para>AFS also uses the UNIX mode bits as follows:</para>
1667
1668     <itemizedlist>
1669       <listitem>
1670         <para>It uses the initial bit to determine the element's type. This is the bit that appears first in the output from the
1671         <emphasis role="bold">ls -l</emphasis> command and shows the hyphen (<emphasis role="bold">-</emphasis>) for a file or the
1672         letter <emphasis role="bold">d</emphasis> for a directory.</para>
1673       </listitem>
1674
1675       <listitem>
1676         <para>It does not use any of the mode bits on a directory.</para>
1677       </listitem>
1678
1679       <listitem>
1680         <para>For a file, the first (owner) set of bits interacts with the ACL entries that apply to the file in the following way:
1681         <itemizedlist>
1682             <listitem>
1683               <para>If the first <emphasis role="bold">r</emphasis> mode bit is not set, no one (including the owner) can read the
1684               file, no matter what permissions they have on the ACL. If the bit is set, users also need the <emphasis
1685               role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) and <emphasis role="bold">l</emphasis> permissions on
1686               the ACL of the file's directory to read the file.</para>
1687             </listitem>
1688
1689             <listitem>
1690               <para>If the first <emphasis role="bold">w</emphasis> mode bit is not set, no one (including the owner) can modify the
1691               file. If the <emphasis role="bold">w</emphasis> bit is set, users also need the <emphasis role="bold">w</emphasis> and
1692               <emphasis role="bold">l</emphasis> permissions on the ACL of the file's directory to modify the file.</para>
1693             </listitem>
1694
1695             <listitem>
1696               <para>There is no ACL permission directly corresponding to the <emphasis role="bold">x</emphasis> mode bit, but to
1697               execute a file stored in AFS, the user must also have the <emphasis role="bold">r</emphasis> and <emphasis
1698               role="bold">l</emphasis> permissions on the ACL of the file's directory.</para>
1699             </listitem>
1700           </itemizedlist></para>
1701       </listitem>
1702     </itemizedlist>
1703   </sect1>
1704 </chapter>