Improve demand-attach fileserver bos documentation
[openafs.git] / doc / xml / UserGuide / auusg007.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="HDRWQ44">
3   <title>Protecting Your Directories and Files</title>
4
5   <para>This chapter explains how to protect AFS files and directories by defining permissions on an access control list.</para>
6
7   <sect1 id="HDRWQ45">
8     <title>Access Control Lists</title>
9
10     <indexterm>
11       <primary>protection</primary>
12
13       <secondary>for files and directories</secondary>
14     </indexterm>
15
16     <indexterm>
17       <primary>access to AFS filespace</primary>
18
19       <secondary>granting and denying to users</secondary>
20     </indexterm>
21
22     <indexterm>
23       <primary>directories</primary>
24
25       <secondary>setting access control list</secondary>
26     </indexterm>
27
28     <indexterm>
29       <primary>ACL</primary>
30
31       <secondary>described</secondary>
32     </indexterm>
33
34     <indexterm>
35       <primary>access control list</primary>
36
37       <see>ACL</see>
38     </indexterm>
39
40     <para>AFS augments and refines the standard UNIX scheme for controlling access to files and directories. Instead of using mode
41     bits to define access permissions for individual files, as UNIX does, AFS stores an <emphasis>access control list</emphasis>
42     (<emphasis>ACL</emphasis>) with each directory. It defines which users and groups can access the directory and the files it
43     contains, and in what manner. An ACL can store up to about 20 entries, each of which pairs a user or group and a set of
44     permissions. AFS defines seven permissions rather than the three that UNIX uses.</para>
45
46     <para>Another refinement to the standard UNIX protection scheme is that users can define their own protection
47     <emphasis>groups</emphasis> and then place the groups on ACLs as though they were individual users. A group can include both
48     users and machines. Each user who belongs to a group inherits all of the permissions granted to the group on the ACL. Similarly,
49     all users who are logged into a machine that belongs to a group inherits all of the permissions granted to the group. You can
50     create groups to place on ACLs and also use groups that other users have created. To learn more about group creation, see <link
51     linkend="HDRWQ60">Using Groups</link>.</para>
52
53     <para>In addition, AFS defines two system groups called <emphasis role="bold">system:anyuser</emphasis> and <emphasis
54     role="bold">system:authuser</emphasis>. By placing them on ACLs, you can grant access to large numbers of users at once. See
55     <link linkend="HDRWQ50">Using the System Groups on ACLs</link>.</para>
56
57     <para>Although AFS uses ACLs to protect files and directories, it also uses the UNIX mode bits to a limited extent. See <link
58     linkend="HDRWQ59">How AFS Uses the UNIX Mode Bits</link>.</para>
59
60     <sect2 id="Header_81">
61       <title>Directory Level Access Control</title>
62
63       <para>As noted, AFS associates an ACL with each directory, and it applies to all of the files stored in the directory. Files
64       do not have separate ACLs. Defining access at the directory level has several consequences: <itemizedlist>
65           <listitem>
66             <para>The permissions on a directory's ACL apply to all of the files in the directory. When you move a file to a
67             different directory, you effectively change its permissions to those on its new directory's ACL. Changing a directory's
68             ACL changes the protection on all the files in it.</para>
69           </listitem>
70
71           <listitem>
72             <para>When you create a subdirectory, it inherits the current ACL of its parent directory. You can then set the
73             subdirectory's ACL to be different from its parent's. However, do not make the ACL on the parent directory more
74             restrictive than on a subdirectory, because that can prevent users from accessing the subdirectory even when they have
75             the necessary permissions on its ACL. Specifically, a user must have the <emphasis role="bold">l</emphasis> (<emphasis
76             role="bold">lookup</emphasis>) permission (defined in <link linkend="HDRWQ46">The AFS ACL Permissions</link>) on the
77             parent directory to reach its subdirectories. <indexterm>
78                 <primary>subdirectories, accessing</primary>
79               </indexterm> <indexterm>
80                 <primary>access to AFS filespace</primary>
81
82                 <secondary>controlling at directory level</secondary>
83               </indexterm></para>
84           </listitem>
85         </itemizedlist></para>
86
87       <para>As a general rule, it makes sense to grant fairly liberal access to your home directory. If you need to protect certain
88       files more closely, place them in subdirectories that have more restrictive ACLs.</para>
89     </sect2>
90   </sect1>
91
92   <sect1 id="HDRWQ46">
93     <title>The AFS ACL Permissions</title>
94
95     <indexterm>
96       <primary>access permissions on ACL</primary>
97
98       <seealso>permissions on ACL</seealso>
99
100       <seealso>ACL</seealso>
101     </indexterm>
102
103     <indexterm>
104       <primary>permissions on ACL</primary>
105
106       <secondary>defined</secondary>
107     </indexterm>
108
109     <indexterm>
110       <primary>ACL</primary>
111
112       <secondary>permissions defined</secondary>
113     </indexterm>
114
115     <para>There are seven standard AFS ACL permissions. Functionally, they fall into two groups: one that applies to the directory
116     itself and one that applies to the files.</para>
117
118     <sect2 id="HDRWQ47">
119       <title>The Four Directory Permissions</title>
120
121       <para>The four permissions in this group are meaningful with respect to the directory itself. For example, the <emphasis
122       role="bold">i</emphasis> (<emphasis role="bold">insert</emphasis>) permission does not control addition of data to a file, but
123       rather creation of a new file or subdirectory. <variablelist>
124           <varlistentry>
125             <term><emphasis role="bold">The l (lookup) permission</emphasis></term>
126
127             <listitem>
128               <para>This permission functions as something of a gate keeper for access to the directory and its files, because a
129               user must have it in order to exercise any other permissions. In particular, a user must have this permission to
130               access anything in the directory's subdirectories. <indexterm>
131                   <primary>lookup ACL permission</primary>
132                 </indexterm> <indexterm>
133                   <primary>l ACL permission</primary>
134                 </indexterm></para>
135
136               <para>This permission enables a user to issue the following commands: <itemizedlist>
137                   <listitem>
138                     <para>The <emphasis role="bold">ls</emphasis> command to list the names of the files and subdirectories in the
139                     directory</para>
140                   </listitem>
141
142                   <listitem>
143                     <para>The <emphasis role="bold">ls -ld</emphasis> command to obtain complete status information for the
144                     directory element itself</para>
145                   </listitem>
146
147                   <listitem>
148                     <para>The <emphasis role="bold">fs listacl</emphasis> command to examine the directory's ACL</para>
149                   </listitem>
150                 </itemizedlist></para>
151
152               <para>This permission does not enable a user to read the contents of a file in the directory or to issue the <emphasis
153               role="bold">ls -l</emphasis> or <emphasis role="bold">fs listacl</emphasis> commands with a filename as the argument.
154               Those operations require the <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) permission,
155               which is described in <link linkend="HDRWQ48">The Three File Permissions</link>.</para>
156
157               <para>Similarly, this permission does not enable a user to issue the <emphasis role="bold">ls</emphasis>, <emphasis
158               role="bold">ls -l</emphasis>, <emphasis role="bold">ls -ld</emphasis>, or <emphasis role="bold">fs listacl</emphasis>
159               commands against a subdirectory of the directory. Those operations require the <emphasis role="bold">l</emphasis>
160               permission on the ACL of the subdirectory itself.</para>
161             </listitem>
162           </varlistentry>
163
164           <varlistentry>
165             <term><emphasis role="bold">The i (insert) permission</emphasis></term>
166
167             <listitem>
168               <para>This permission enables a user to add new files to the directory, either by creating or copying, and to create
169               new subdirectories. It does not extend into any subdirectories, which are protected by their own ACLs. <indexterm>
170                   <primary>insert ACL permission</primary>
171                 </indexterm> <indexterm>
172                   <primary>i ACL permission</primary>
173                 </indexterm></para>
174             </listitem>
175           </varlistentry>
176
177           <varlistentry>
178             <term><emphasis role="bold">The d (delete) permission</emphasis></term>
179
180             <listitem>
181               <para>This permission enables a user to remove files and subdirectories from the directory or move them into other
182               directories (assuming that the user has the <emphasis role="bold">i</emphasis> permission on the ACL of the other
183               directories). <indexterm>
184                   <primary>delete ACL permission</primary>
185                 </indexterm> <indexterm>
186                   <primary>d ACL permission</primary>
187                 </indexterm></para>
188             </listitem>
189           </varlistentry>
190
191           <varlistentry>
192             <term><emphasis role="bold">The a (administer) permission</emphasis></term>
193
194             <listitem>
195               <para>This permission enables a user to change the directory's ACL. Members of the <emphasis
196               role="bold">system:administrators</emphasis> group implicitly have this permission on every directory (that is, even
197               if that group does not appear on the ACL). Similarly, the owner of a directory implicitly has this permission on its
198               ACL and those of all directories below it. <indexterm>
199                   <primary>administer ACL permission</primary>
200                 </indexterm> <indexterm>
201                   <primary>a ACL permission</primary>
202                 </indexterm></para>
203             </listitem>
204           </varlistentry>
205         </variablelist></para>
206     </sect2>
207
208     <sect2 id="HDRWQ48">
209       <title>The Three File Permissions</title>
210
211       <para>The three permissions in this group are meaningful with respect to files in a directory, rather than the directory
212       itself or its subdirectories. <variablelist>
213           <varlistentry>
214             <term><emphasis role="bold">The r (read) permission</emphasis></term>
215
216             <listitem>
217               <para>This permission enables a user to read the contents of files in the directory and to issue the <emphasis
218               role="bold">ls -l</emphasis> command to stat the file elements. <indexterm>
219                   <primary>read ACL permission</primary>
220                 </indexterm> <indexterm>
221                   <primary>r ACL permission</primary>
222                 </indexterm></para>
223             </listitem>
224           </varlistentry>
225
226           <varlistentry>
227             <term><emphasis role="bold">The w (write) permission</emphasis></term>
228
229             <listitem>
230               <para>This permission enables a user to modify the contents of files in the directory and to issue the <emphasis
231               role="bold">chmod</emphasis> command to change their UNIX mode bits. <indexterm>
232                   <primary>write ACL permission</primary>
233                 </indexterm> <indexterm>
234                   <primary>w ACL permission</primary>
235                 </indexterm></para>
236             </listitem>
237           </varlistentry>
238
239           <varlistentry>
240             <term><emphasis role="bold">The k (lock) permission</emphasis></term>
241
242             <listitem>
243               <para>This permission enables a user to run programs that issue system calls to lock files in the directory.
244               <indexterm>
245                   <primary>k ACL permission</primary>
246                 </indexterm> <indexterm>
247                   <primary>lock ACL permission</primary>
248                 </indexterm></para>
249             </listitem>
250           </varlistentry>
251         </variablelist></para>
252     </sect2>
253
254     <sect2 id="Header_85">
255       <title>The Eight Auxiliary Permissions</title>
256
257       <indexterm>
258         <primary>auxiliary ACL permissions</primary>
259       </indexterm>
260
261       <indexterm>
262         <primary>ACL</primary>
263
264         <secondary>auxiliary permissions</secondary>
265       </indexterm>
266
267       <para>AFS provides eight additional permissions that do not have a defined meaning. They are denoted by the uppercase letters
268       <emphasis role="bold">A</emphasis>, <emphasis role="bold">B</emphasis>, <emphasis role="bold">C</emphasis>, <emphasis
269       role="bold">D</emphasis>, <emphasis role="bold">E</emphasis>, <emphasis role="bold">F</emphasis>, <emphasis
270       role="bold">G</emphasis>, and <emphasis role="bold">H</emphasis>.</para>
271
272       <para>Your system administrator can choose to write application programs that assign a meaning to one or more of the
273       permissions, and then place them on ACLs to control file access by those programs. Use the <emphasis role="bold">fs
274       listacl</emphasis> and <emphasis role="bold">fs setacl</emphasis> commands to display and set the auxiliary permissions on
275       ACLs just like the standard seven.</para>
276     </sect2>
277
278     <sect2 id="Header_86">
279       <title>Shorthand Notation for Sets of Permissions</title>
280
281       <indexterm>
282         <primary>ACL</primary>
283
284         <secondary>shorthand notation for grouping sets of permissions</secondary>
285       </indexterm>
286
287       <indexterm>
288         <primary>shorthand notation for ACL permissions</primary>
289       </indexterm>
290
291       <indexterm>
292         <primary>permissions on ACL</primary>
293
294         <secondary>shorthand for</secondary>
295       </indexterm>
296
297       <para>You can combine the seven permissions in any way in an ACL entry, but certain combinations are more useful than others.
298       Four of the more common combinations have corresponding shorthand forms. When using the <emphasis role="bold">fs
299       setacl</emphasis> command to define ACL entries, you can provide either one or more of the individual letters that represent
300       the permissions, or one of the following shorthand forms: <variablelist>
301           <varlistentry>
302             <term><emphasis role="bold">all</emphasis></term>
303
304             <listitem>
305               <para>Represents all seven standard permissions (<emphasis role="bold">rlidwka</emphasis>) <indexterm>
306                   <primary>all shorthand for ACL permissions</primary>
307                 </indexterm></para>
308             </listitem>
309           </varlistentry>
310
311           <varlistentry>
312             <term><emphasis role="bold">none</emphasis></term>
313
314             <listitem>
315               <para>Removes the entry from the ACL, leaving the user or group with no permission <indexterm>
316                   <primary>none shorthand for ACL permissions</primary>
317                 </indexterm></para>
318             </listitem>
319           </varlistentry>
320
321           <varlistentry>
322             <term><emphasis role="bold">read</emphasis></term>
323
324             <listitem>
325               <para>Represents the <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) and <emphasis
326               role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permissions <indexterm>
327                   <primary>read shorthand for ACL permissions</primary>
328                 </indexterm></para>
329             </listitem>
330           </varlistentry>
331
332           <varlistentry>
333             <term><emphasis role="bold">write</emphasis></term>
334
335             <listitem>
336               <para>Represents all permissions except <emphasis role="bold">a</emphasis> (<emphasis
337               role="bold">administer</emphasis>): <emphasis role="bold">rlidwk</emphasis> <indexterm>
338                   <primary>write shorthand for ACL permissions</primary>
339                 </indexterm></para>
340             </listitem>
341           </varlistentry>
342         </variablelist></para>
343     </sect2>
344
345     <sect2 id="HDRWQ49">
346       <title>About Normal and Negative Permissions</title>
347
348       <indexterm>
349         <primary>ACL</primary>
350
351         <secondary>normal vs. negative permissions</secondary>
352       </indexterm>
353
354       <indexterm>
355         <primary>ACL</primary>
356
357         <secondary>normal permissions</secondary>
358       </indexterm>
359
360       <indexterm>
361         <primary>ACL</primary>
362
363         <secondary>negative permissions</secondary>
364       </indexterm>
365
366       <indexterm>
367         <primary>permissions on ACL</primary>
368
369         <secondary>normal vs. negative</secondary>
370       </indexterm>
371
372       <indexterm>
373         <primary>normal ACL permissions</primary>
374
375         <secondary>defined</secondary>
376       </indexterm>
377
378       <indexterm>
379         <primary>normal ACL permissions</primary>
380
381         <secondary>setting</secondary>
382       </indexterm>
383
384       <indexterm>
385         <primary>negative ACL permissions</primary>
386
387         <secondary>defined</secondary>
388       </indexterm>
389
390       <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
391       role="bold">fs setacl</emphasis> command to create an ACL entry that associates a set of permissions with a user or group, as
392       described in <link linkend="HDRWQ54">Changing an ACL</link>. When you use the <emphasis role="bold">fs listacl</emphasis>
393       command to display an ACL (as described in <link linkend="HDRWQ52">Displaying an ACL</link>), such entries appear underneath
394       the following header, which uses the term <emphasis>rights</emphasis> to refer to permissions:</para>
395
396       <programlisting>
397    Normal rights
398 </programlisting>
399
400       <para>There are two ways to deny access: <indexterm>
401           <primary>negative ACL permissions</primary>
402
403           <secondary>setting</secondary>
404         </indexterm> <orderedlist>
405           <listitem>
406             <para>The recommended method is simply to omit an entry for the user or group from the ACL, or to omit the appropriate
407             permissions from an entry. Use the <emphasis role="bold">fs setacl</emphasis> command to remove or edit an existing
408             entry. In most cases, this method is enough to prevent access of certain kinds or by certain users. You must take care,
409             however, not to grant the undesired permissions to any groups to which such users belong.</para>
410           </listitem>
411
412           <listitem>
413             <para>The more explicit method for denying access is to place an entry on the <emphasis>negative permissions</emphasis>
414             section of an ACL, by including the <emphasis role="bold">-negative</emphasis> flag to the <emphasis role="bold">fs
415             setacl</emphasis> command. For instructions, see <link linkend="HDRWQ56">To Add, Remove, or Edit Negative ACL
416             Permissions</link>. The <emphasis role="bold">fs listacl</emphasis> command displays the negative permissions section of
417             an ACL underneath the following header: <programlisting>
418    Negative rights
419 </programlisting></para>
420
421             <para>When determining what type of access to grant to a user, AFS first examines all of the entries in the normal
422             permissions section of the ACL. It then subtracts any permissions associated with the user (or with groups to which the
423             user belongs) on the negative permissions section of the ACL. Therefore, negative permissions always cancel out normal
424             permissions.</para>
425
426             <para>Negative permissions can be confusing, because they reverse the usual meaning of the <emphasis role="bold">fs
427             setacl</emphasis> command. In particular, combining the <emphasis role="bold">none</emphasis> shorthand and the
428             <emphasis role="bold">-negative</emphasis> flag is a double negative: by removing an entry from the negative permissions
429             section of the ACL, you enable a user once again to obtain permissions via entries in the normal permissions section.
430             Combining the <emphasis role="bold">all</emphasis> shorthand with the <emphasis role="bold">-negative</emphasis> flag
431             explicitly denies all permissions.</para>
432
433             <para>It is useless to create an entry in the negative permissions section if an entry in the normal permissions section
434             grants the denied permissions to the <emphasis role="bold">system:anyuser</emphasis> group. In this case, users can
435             obtain the permissions simply by using the <emphasis role="bold">unlog</emphasis> command to discard their tokens. When
436             they do so, AFS recognizes them as the <emphasis role="bold">anonymous</emphasis> user, who belongs to the <emphasis
437             role="bold">system:anyuser</emphasis> group but does not match the entries on the negative permissions section of the
438             ACL.</para>
439           </listitem>
440         </orderedlist></para>
441     </sect2>
442
443     <sect2 id="Header_88">
444       <title>Setting DFS ACLs</title>
445
446       <para>If your machine is configured to access a DCE cell's DFS filespace via the AFS/DFS Migration Toolkit, then you can use
447       the AFS <emphasis role="bold">fs listacl</emphasis> and <emphasis role="bold">fs setacl</emphasis> commands to display and set
448       the ACLs on DFS directories and files that you own. However, DFS uses a slightly different set of permissions and a different
449       syntax for ACL entries. See the DFS documentation or ask your system administrator.</para>
450     </sect2>
451   </sect1>
452
453   <sect1 id="HDRWQ50">
454     <title>Using the System Groups on ACLs</title>
455
456     <para><indexterm>
457         <primary>system groups</primary>
458
459         <secondary>using on ACLs</secondary>
460       </indexterm> <indexterm>
461         <primary>system:anyuser group</primary>
462
463         <secondary>using on ACLs</secondary>
464       </indexterm> <indexterm>
465         <primary>system:authuser group</primary>
466       </indexterm> <indexterm>
467         <primary>system:administrators group</primary>
468       </indexterm> AFS defines two <emphasis>system groups</emphasis> that grant access to a large number of users at once when
469     placed on an ACL. However, you cannot control the membership of these groups, so consider carefully what kind of permissions you
470     wish to give them. (You do control the membership of the groups you own; see <link linkend="HDRWQ60">Using Groups</link>.)
471     <variablelist>
472         <varlistentry>
473           <term><emphasis role="bold">system:anyuser</emphasis></term>
474
475           <listitem>
476             <para>Includes anyone who can access the cell's file tree, including users who have tokens in the local cell, users who
477             have logged in on a local AFS client machine but have not obtained tokens (such as the local superuser <emphasis
478             role="bold">root</emphasis>), and users who have connected to a local machine from outside the cell. Creating an ACL
479             entry for this group is the only way to extend access to AFS users from foreign cells, unless your system administrator
480             creates local authentication accounts for them. <indexterm>
481                 <primary>ACL</primary>
482
483                 <secondary>foreign users on</secondary>
484               </indexterm></para>
485           </listitem>
486         </varlistentry>
487
488         <varlistentry>
489           <term><emphasis role="bold">system:authuser</emphasis></term>
490
491           <listitem>
492             <para>Includes all users who have a valid AFS token obtained from the local cell's AFS authentication service.</para>
493           </listitem>
494         </varlistentry>
495       </variablelist></para>
496
497     <para>The third system group, <emphasis role="bold">system:administrators</emphasis>, includes a small group of administrators
498     who have extensive permissions in the cell. You do not generally need to put this group on your ACLs, because its members always
499     have the <emphasis role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) permission on every ACL, even if the
500     group does not appear on it.</para>
501
502     <sect2 id="Header_90">
503       <title>Enabling Access to Subdirectories</title>
504
505       <indexterm>
506         <primary>subdirectories, accessing</primary>
507       </indexterm>
508
509       <indexterm>
510         <primary>access to AFS filespace</primary>
511
512         <secondary>controlling for subdirectories</secondary>
513       </indexterm>
514
515       <para>A user must have the <emphasis role="bold">l</emphasis> permission on a directory to access its subdirectories in any
516       way. Even if users have extensive permissions on a subdirectory, they cannot access it if the parent directory's ACL does not
517       grant the <emphasis role="bold">l</emphasis> permission.</para>
518
519       <para>You can grant the <emphasis role="bold">l</emphasis> permission in one of three ways: grant it to a system group
520       (<emphasis role="bold">system:anyuser</emphasis> or <emphasis role="bold">system:authuser</emphasis>), grant it to individual
521       users, or grant it to one or more groups of users defined by you or other users (see <link linkend="HDRWQ60">Using
522       Groups</link>). Granting the <emphasis role="bold">l</emphasis> permission to the <emphasis
523       role="bold">system:anyuser</emphasis> group is the easiest option and is generally secure because the permission only enables
524       users to list the contents of the directory, not to read the files in it. If you want to enable only locally authenticated
525       users to list a directory's contents, substitute the <emphasis role="bold">system:authuser</emphasis> group for the <emphasis
526       role="bold">system:anyuser</emphasis> group. Your system administrator has possibly already created an entry on your home
527       directory's ACL that grants the <emphasis role="bold">r</emphasis> and <emphasis role="bold">l</emphasis> permissions to the
528       <emphasis role="bold">system:anyuser</emphasis> group.</para>
529     </sect2>
530
531     <sect2 id="Header_91">
532       <title>Extending Access to Service Processes</title>
533
534       <indexterm>
535         <primary>access to AFS filespace</primary>
536
537         <secondary>enabling for service processes</secondary>
538       </indexterm>
539
540       <para>It is sometimes necessary to grant more extensive permissions to the <emphasis role="bold">system:anyuser</emphasis>
541       group so that processes that provide printing and mail delivery service can work correctly. For example, printing processes
542       sometimes need the <emphasis role="bold">r</emphasis> permission in addition to the <emphasis role="bold">l</emphasis>
543       permission. A mail delivery process possibly needs the <emphasis role="bold">i</emphasis> permission to place new messages in
544       your mail directory. Your system administrator has probably already created the necessary ACL entries. If you notice an ACL
545       entry for which the purpose is unclear, check with your system administrator before removing it.</para>
546     </sect2>
547
548     <sect2 id="HDRWQ51">
549       <title>Extending Access to Users from Foreign Cells</title>
550
551       <para><indexterm>
552           <primary>access to AFS filespace</primary>
553
554           <secondary>enabling for users from foreign cells</secondary>
555         </indexterm> The only way to grant access to users from foreign cells who do not have an account in your cell is to put the
556       <emphasis role="bold">system:anyuser</emphasis> group on an ACL. Remember, however, that such an entry extends access to
557       everyone who can reach your cell, not just the AFS users from foreign cells that you have in mind.</para>
558     </sect2>
559   </sect1>
560
561   <sect1 id="HDRWQ52">
562     <title>Displaying an ACL</title>
563
564     <indexterm>
565       <primary>ACL</primary>
566
567       <secondary>displaying</secondary>
568     </indexterm>
569
570     <indexterm>
571       <primary>displaying</primary>
572
573       <secondary>ACL entries</secondary>
574     </indexterm>
575
576     <indexterm>
577       <primary>permissions on ACL</primary>
578
579       <secondary>displaying</secondary>
580     </indexterm>
581
582     <para>To display the ACL associated with a file or directory, issue the <emphasis role="bold">fs listacl</emphasis>
583     command.</para>
584
585     <para><emphasis role="bold">Note for AFS/DFS Migration Toolkit users:</emphasis> If the machine on which you issue the <emphasis
586     role="bold">fs listacl</emphasis> command is configured to access a DCE cell's DFS filespace via the AFS/DFS Migration Toolkit,
587     you can use the command to display the ACL on DFS files and directories. To display a DFS directory's Initial Container or
588     Initial Object ACL instead of the regular one, include the <emphasis role="bold">fs listacl</emphasis> command's <emphasis
589     role="bold">-id</emphasis> or <emphasis role="bold">-if</emphasis> flag. For more information, ask your system administrator.
590     The <emphasis role="bold">fs</emphasis> command interpreter ignores the <emphasis role="bold">-id</emphasis> and <emphasis
591     role="bold">-if</emphasis> flags if you include them when displaying an AFS ACL.</para>
592
593     <sect2 id="HDRWQ53">
594       <title>To display an ACL</title>
595
596       <orderedlist>
597         <listitem>
598           <para>Issue the <emphasis role="bold">fs listacl</emphasis> command. <indexterm>
599               <primary>fs commands</primary>
600
601               <secondary>listacl</secondary>
602             </indexterm> <indexterm>
603               <primary>commands</primary>
604
605               <secondary>fs listacl</secondary>
606             </indexterm> <programlisting>
607    % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;<superscript>+</superscript>]
608 </programlisting></para>
609
610           <para>where</para>
611
612           <variablelist>
613             <varlistentry>
614               <term><emphasis role="bold">la</emphasis></term>
615
616               <listitem>
617                 <para>Is an acceptable alias for <emphasis role="bold">listacl</emphasis> (and <emphasis
618                 role="bold">lista</emphasis> is the shortest acceptable abbreviation).</para>
619               </listitem>
620             </varlistentry>
621
622             <varlistentry>
623               <term><emphasis role="bold"><replaceable>dir/file path</replaceable></emphasis></term>
624
625               <listitem>
626                 <para>Names one or more files or directories for which to display the ACL. For a file, the output displays the ACL
627                 on its directory. If you omit this argument, the output is for the current working directory. Partial pathnames are
628                 interpreted relative to the current working directory. You can also use the following notation on its own or as part
629                 of a pathname: <variablelist>
630                     <varlistentry>
631                       <term><emphasis role="bold">.</emphasis></term>
632
633                       <listitem>
634                         <para>(A single period). Specifies the current working directory.</para>
635                       </listitem>
636                     </varlistentry>
637
638                     <varlistentry>
639                       <term><emphasis role="bold">..</emphasis></term>
640
641                       <listitem>
642                         <para>(Two periods). Specifies the current working directory's parent directory.</para>
643                       </listitem>
644                     </varlistentry>
645
646                     <varlistentry>
647                       <term><emphasis role="bold">*</emphasis></term>
648
649                       <listitem>
650                         <para>(The asterisk). Specifies each file and subdirectory in the current working directory. The ACL
651                         displayed for a file is always the same as for its directory, but the ACL for each subdirectory can
652                         differ.</para>
653                       </listitem>
654                     </varlistentry>
655                   </variablelist></para>
656               </listitem>
657             </varlistentry>
658           </variablelist>
659         </listitem>
660       </orderedlist>
661
662       <para>The output for each file or directory specified as <replaceable>dir/file path</replaceable> begins with the following
663       header to identify it:</para>
664
665       <programlisting>
666    Access list for  <replaceable>dir/file path</replaceable> is
667 </programlisting>
668
669       <para>The <computeroutput>Normal rights</computeroutput> header appears on the next line, followed by lines that each pair a
670       user or group name and a set of permissions. The permissions appear as the single letters defined in <link
671       linkend="HDRWQ46">The AFS ACL Permissions</link>, and always in the order <emphasis role="bold">rlidwka</emphasis>. If there
672       are any negative permissions, the <computeroutput>Negative rights</computeroutput> header appears next, followed by pairs of
673       negative permissions.</para>
674
675       <para>If the following error message appears instead of an ACL, you do not have the permissions needed to display an ACL. To
676       specify a directory name as the <replaceable>dir/file path</replaceable> argument, you must have the <emphasis
677       role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permission on the ACL. To specify a filename, you must also
678       have the <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) permission on its directory's ACL.</para>
679
680       <programlisting>
681    fs: You don't have the required access permissions on '<replaceable>dir/file path</replaceable>'
682 </programlisting>
683     </sect2>
684
685     <sect2 id="Header_95">
686       <title>Example: Displaying the ACL on One Directory</title>
687
688       <indexterm>
689         <primary>examples</primary>
690
691         <secondary>displaying ACL for single directory</secondary>
692       </indexterm>
693
694       <para>The following example displays the ACL on user <emphasis role="bold">terry</emphasis>'s home directory in the ABC
695       Corporation cell:</para>
696
697       <programlisting>
698    % <emphasis role="bold">fs la /afs/abc.com/usr/terry</emphasis>
699    Access list for /afs/abc.com/usr/terry is
700    Normal rights:
701       system:authuser rl
702       pat rlw
703       terry rlidwka
704    Negative rights:
705       terry:other-dept rl
706       jones rl
707 </programlisting>
708
709       <para>where <emphasis role="bold">pat</emphasis>, <emphasis role="bold">terry</emphasis>, and <emphasis
710       role="bold">jones</emphasis> are individual users, <emphasis role="bold">system:authuser</emphasis> is a system group, and
711       <emphasis role="bold">terry:other-dept</emphasis> is a group that <emphasis role="bold">terry</emphasis> owns. The list of
712       normal permissions grants all permissions to <emphasis role="bold">terry</emphasis>, the <emphasis role="bold">rlw</emphasis>
713       permissions to <emphasis role="bold">pat</emphasis>, and the <emphasis role="bold">rl</emphasis> permissions to the members of
714       the <emphasis role="bold">system:authuser</emphasis> group.</para>
715
716       <para>The list of negative permissions denies the <emphasis role="bold">rl</emphasis> permissions to <emphasis
717       role="bold">jones</emphasis> and the members of the <emphasis role="bold">terry:other-dept</emphasis> group. These entries
718       effectively prevent them from accessing <emphasis role="bold">terry</emphasis>'s home directory in any way; they cancel out
719       the <emphasis role="bold">rl</emphasis> permissions extended to the <emphasis role="bold">system:authuser</emphasis> group,
720       which is the only entry on the normal permissions section of the ACL that possibly applies to them.</para>
721     </sect2>
722
723     <sect2 id="Header_96">
724       <title>Example: Displaying the ACLs on Multiple Directories</title>
725
726       <indexterm>
727         <primary>examples</primary>
728
729         <secondary>displaying ACLs for multiple directories</secondary>
730       </indexterm>
731
732       <para>The following example illustrates how you can specify pathnames in different ways, and the appearance of the output for
733       multiple directories. It displays the ACL for three directories: the current working directory (which is a subdirectory of
734       user <emphasis role="bold">terry</emphasis>'s home directory), the home directory for user <emphasis
735       role="bold">pat</emphasis>, and another subdirectory of <emphasis role="bold">terry</emphasis>'s home directory called
736       <emphasis role="bold">plans</emphasis>.</para>
737
738       <programlisting>
739    % <emphasis role="bold">fs listacl  .  /afs/abc.com/usr/pat  ../plans</emphasis>
740    Access list for . is
741    Normal rights:
742       system:anyuser rl
743       pat:dept rliw
744    Access list for /afs/abc.com/usr/pat is
745    Normal rights:
746       system:anyuser rl
747       pat rlidwka
748       terry rliw
749    Access list for ../plans is
750    Normal rights:
751       terry rlidwka
752       pat rlidw
753 </programlisting>
754     </sect2>
755   </sect1>
756
757   <sect1 id="HDRWQ54">
758     <title>Changing an ACL</title>
759
760     <indexterm>
761       <primary>changing</primary>
762
763       <secondary>ACLs</secondary>
764     </indexterm>
765
766     <indexterm>
767       <primary>setting permissions on ACL</primary>
768     </indexterm>
769
770     <indexterm>
771       <primary>ACL</primary>
772
773       <secondary>setting</secondary>
774     </indexterm>
775
776     <indexterm>
777       <primary>permissions on ACL</primary>
778
779       <secondary>setting</secondary>
780     </indexterm>
781
782     <para>To add, remove, or edit ACL entries, use the <emphasis role="bold">fs setacl</emphasis> command. By default, the command
783     manipulates entries on the normal permissions section of the ACL. To manipulate entries on the negative permissions section,
784     include the <emphasis role="bold">-negative</emphasis> flag as instructed in <link linkend="HDRWQ56">To Add, Remove, or Edit
785     Negative ACL Permissions</link>.</para>
786
787     <para>You can change any ACL on which you already have the <emphasis role="bold">a</emphasis> permission. You always have the
788     <emphasis role="bold">a</emphasis> permission on the ACL of every directory that you own, even if you accidentally remove that
789     permission from the ACL. (The <emphasis role="bold">ls -ld</emphasis> command reports a directory's owner.) Your system
790     administrator normally designates you as the owner of your home directory and its subdirectories, and you possibly own other
791     directories also.</para>
792
793     <para>If an ACL entry already exists for the user or group you specify, then the new permissions completely replace the existing
794     permissions rather than being added to them. In other words, when issuing the <emphasis role="bold">fs setacl</emphasis>
795     command, you must include all permissions that you want to grant to a user or group.</para>
796
797     <para><emphasis role="bold">Note for AFS/DFS Migration Toolkit users:</emphasis> If the machine on which you issue the <emphasis
798     role="bold">fs setacl</emphasis> command is configured to access a DCE cell's DFS filespace via the AFS/DFS Migration Toolkit,
799     you can use the command to set the ACL on DFS files and directories. To set a DFS directory's Initial Container or Initial
800     Object ACL instead of the regular one, include the <emphasis role="bold">fs setacl</emphasis> command's <emphasis
801     role="bold">-id</emphasis> or <emphasis role="bold">-if</emphasis> flag. For more information, ask your system administrator.
802     The <emphasis role="bold">fs</emphasis> command interpreter ignores the <emphasis role="bold">-id</emphasis> and <emphasis
803     role="bold">-if</emphasis> flags if you include them when setting an AFS ACL.</para>
804
805     <sect2 id="HDRWQ55">
806       <title>To Add, Remove, or Edit Normal ACL Permissions</title>
807
808       <indexterm>
809         <primary>creating</primary>
810
811         <secondary>ACL entry in normal permissions section</secondary>
812       </indexterm>
813
814       <indexterm>
815         <primary>ACL</primary>
816
817         <secondary>creating normal entry</secondary>
818       </indexterm>
819
820       <indexterm>
821         <primary>adding</primary>
822
823         <secondary>ACL entry to normal permissions section</secondary>
824       </indexterm>
825
826       <indexterm>
827         <primary>granting access to AFS filespace</primary>
828       </indexterm>
829
830       <indexterm>
831         <primary>access to AFS filespace</primary>
832
833         <secondary>ACL entries control</secondary>
834       </indexterm>
835
836       <indexterm>
837         <primary>directories</primary>
838
839         <secondary>granting access</secondary>
840       </indexterm>
841
842       <indexterm>
843         <primary>files</primary>
844
845         <secondary>granting access</secondary>
846       </indexterm>
847
848       <para>Issue the <emphasis role="bold">fs setacl</emphasis> command to edit entries in the normal permissions section of the
849       ACL. To remove an entry, specify the <emphasis role="bold">none</emphasis> shorthand as the permissions. If an ACL entry
850       already exists for a user or group, the permissions you specify completely replace those in the existing entry. <indexterm>
851           <primary>commands</primary>
852
853           <secondary>fs setacl</secondary>
854         </indexterm> <indexterm>
855           <primary>fs commands</primary>
856
857           <secondary>setacl</secondary>
858         </indexterm></para>
859
860       <programlisting>
861    % <emphasis role="bold">fs setacl  -dir</emphasis> &lt;<replaceable>directory</replaceable>&gt;<superscript>+</superscript> <emphasis
862           role="bold">-acl</emphasis> &lt;<replaceable>access list entries</replaceable>&gt;<superscript>+</superscript>
863 </programlisting>
864
865       <para>where <variablelist>
866           <varlistentry>
867             <term><emphasis role="bold">sa</emphasis></term>
868
869             <listitem>
870               <para>Is an acceptable alias for <emphasis role="bold">setacl</emphasis> (and <emphasis role="bold">seta</emphasis> is
871               the shortest acceptable abbreviation).</para>
872             </listitem>
873           </varlistentry>
874
875           <varlistentry>
876             <term><emphasis role="bold">-dir</emphasis></term>
877
878             <listitem>
879               <para>Names one or more directories to which to apply the ACL entries defined by the <emphasis
880               role="bold">-acl</emphasis> argument. Partial pathnames are interpreted relative to the current working directory. You
881               can also use the following notation on its own or as part of a pathname: <variablelist>
882                   <varlistentry>
883                     <term><emphasis role="bold">.</emphasis></term>
884
885                     <listitem>
886                       <para>(A single period). If used by itself, sets the ACL on the current working directory.</para>
887                     </listitem>
888                   </varlistentry>
889
890                   <varlistentry>
891                     <term><emphasis role="bold">..</emphasis></term>
892
893                     <listitem>
894                       <para>(Two periods). If used by itself, sets the ACL on the current working directory's parent
895                       directory.</para>
896                     </listitem>
897                   </varlistentry>
898
899                   <varlistentry>
900                     <term><emphasis role="bold">*</emphasis></term>
901
902                     <listitem>
903                       <para>(The asterisk). Sets the ACL on each of the subdirectories in the current working directory. You must
904                       precede it with the <emphasis role="bold">-dir</emphasis> switch, since it potentially designates multiple
905                       directories. The <emphasis role="bold">fs</emphasis> command interpreter generates the following error message
906                       for each file in the directory: <programlisting>
907    fs: '<replaceable>filename</replaceable>': Not a directory
908 </programlisting></para>
909                     </listitem>
910                   </varlistentry>
911                 </variablelist></para>
912
913               <para>If you specify only one directory (or file) name, you can omit the <emphasis role="bold">-dir</emphasis> and
914               <emphasis role="bold">-acl</emphasis> switches. For more on omitting switches, see <link linkend="HDRWQ86">Appendix B,
915               OpenAFS Command Syntax and Online Help</link>.</para>
916             </listitem>
917           </varlistentry>
918
919           <varlistentry>
920             <term><emphasis role="bold">-acl</emphasis></term>
921
922             <listitem>
923               <para>Specifies one or more ACL entries, each of which pairs a user or group name and a set of permissions. Separate
924               the pairs, and the two parts of each pair, with one or more spaces.</para>
925
926               <para>To define the permissions, provide either:</para>
927
928               <itemizedlist>
929                 <listitem>
930                   <para>One or more of the letters that represent the standard or auxiliary permissions (<emphasis
931                   role="bold">rlidwka</emphasis> and <emphasis role="bold">ABCDEFGH</emphasis>), in any order</para>
932                 </listitem>
933
934                 <listitem>
935                   <para>One of the four shorthand notations: <itemizedlist>
936                       <listitem>
937                         <para><emphasis role="bold">all</emphasis> (equals <emphasis role="bold">rlidwka</emphasis>)</para>
938                       </listitem>
939
940                       <listitem>
941                         <para><emphasis role="bold">none</emphasis> (removes the entry)</para>
942                       </listitem>
943
944                       <listitem>
945                         <para><emphasis role="bold">read</emphasis> (equals <emphasis role="bold">rl</emphasis>)</para>
946                       </listitem>
947
948                       <listitem>
949                         <para><emphasis role="bold">write</emphasis> (equals <emphasis role="bold">rlidwk</emphasis>)</para>
950                       </listitem>
951                     </itemizedlist></para>
952                 </listitem>
953               </itemizedlist>
954
955               <para>On a single command line, you can combine user and group entries. Also, you can both combine individual letters
956               and use the shorthand notations, but not within a single pair.</para>
957             </listitem>
958           </varlistentry>
959         </variablelist></para>
960     </sect2>
961
962     <sect2 id="Header_99">
963       <title>Example: Adding a Single ACL Entry</title>
964
965       <indexterm>
966         <primary>examples</primary>
967
968         <secondary>adding a user to an ACL</secondary>
969       </indexterm>
970
971       <para>Either of the following example commands grants user <emphasis role="bold">pat</emphasis> the <emphasis
972       role="bold">r</emphasis> and <emphasis role="bold">l</emphasis> permissions on the ACL of the <emphasis
973       role="bold">notes</emphasis> subdirectory of the current working directory. They illustrate how it is possible to omit the
974       <emphasis role="bold">-dir</emphasis> and <emphasis role="bold">-acl</emphasis> switches when you name only one
975       directory.</para>
976
977       <programlisting>
978    % <emphasis role="bold">fs sa notes pat rl</emphasis>
979    % <emphasis role="bold">fs sa notes pat read</emphasis>
980 </programlisting>
981     </sect2>
982
983     <sect2 id="Header_100">
984       <title>Example: Setting Several ACL Entries on One Directory</title>
985
986       <para>The following example edits the ACL for the current working directory. It removes the entry for the <emphasis
987       role="bold">system:anyuser</emphasis> group, and adds two entries: one grants all permissions except <emphasis
988       role="bold">a</emphasis> to the members of the <emphasis role="bold">terry:colleagues</emphasis> group and the other grants
989       the <emphasis role="bold">r</emphasis> and <emphasis role="bold">l</emphasis> permissions to the <emphasis
990       role="bold">system:authuser</emphasis> group.</para>
991
992       <programlisting>
993    % <emphasis role="bold">fs sa  -dir . -acl  system:anyuser none  terry:colleagues write</emphasis>  \
994             <emphasis role="bold">system:authuser rl</emphasis>
995 </programlisting>
996     </sect2>
997
998     <sect2 id="HDRWQ56">
999       <title>To Add, Remove, or Edit Negative ACL Permissions</title>
1000
1001       <indexterm>
1002         <primary>creating</primary>
1003
1004         <secondary>ACL entry in negative permissions section</secondary>
1005       </indexterm>
1006
1007       <indexterm>
1008         <primary>ACL</primary>
1009
1010         <secondary>creating negative entry</secondary>
1011       </indexterm>
1012
1013       <indexterm>
1014         <primary>adding</primary>
1015
1016         <secondary>ACL entry to negative permissions section</secondary>
1017       </indexterm>
1018
1019       <indexterm>
1020         <primary>denying access with negative ACL entry</primary>
1021       </indexterm>
1022
1023       <indexterm>
1024         <primary>directories</primary>
1025
1026         <secondary>denying access</secondary>
1027       </indexterm>
1028
1029       <indexterm>
1030         <primary>files</primary>
1031
1032         <secondary>denying access</secondary>
1033       </indexterm>
1034
1035       <para>Issue the <emphasis role="bold">fs setacl</emphasis> command with the <emphasis role="bold">-negative</emphasis> flag to
1036       edit entries in the negative permissions section of the ACL. To remove an entry, specify the <emphasis
1037       role="bold">none</emphasis> shorthand as the permissions. If an ACL entry already exists for a user or group, the permissions
1038       you specify completely replace those in the existing entry. <indexterm>
1039           <primary>fs commands</primary>
1040
1041           <secondary>setacl</secondary>
1042
1043           <tertiary>with -negative flag</tertiary>
1044         </indexterm> <indexterm>
1045           <primary>commands</primary>
1046
1047           <secondary>fs setacl</secondary>
1048         </indexterm></para>
1049
1050       <programlisting>
1051    % <emphasis role="bold">fs setacl  -dir</emphasis> &lt;<replaceable>directory</replaceable>&gt;<superscript>+</superscript> <emphasis
1052           role="bold">-acl</emphasis> &lt;<replaceable>access list entries</replaceable>&gt;<superscript>+</superscript>  <emphasis
1053           role="bold">-negative</emphasis>
1054 </programlisting>
1055
1056       <para>where <variablelist>
1057           <varlistentry>
1058             <term><emphasis role="bold">sa</emphasis></term>
1059
1060             <listitem>
1061               <para>Is an acceptable alias for <emphasis role="bold">setacl</emphasis> (and <emphasis role="bold">seta</emphasis> is
1062               the shortest acceptable abbreviation).</para>
1063             </listitem>
1064           </varlistentry>
1065
1066           <varlistentry>
1067             <term><emphasis role="bold">-dir</emphasis></term>
1068
1069             <listitem>
1070               <para>Names one or more directories to which to apply the negative ACL entries defined by the <emphasis
1071               role="bold">-acl</emphasis> argument. For a detailed description of acceptable values, see <link linkend="HDRWQ55">To
1072               Add, Remove, or Edit Normal ACL Permissions</link>.</para>
1073             </listitem>
1074           </varlistentry>
1075
1076           <varlistentry>
1077             <term><emphasis role="bold">-acl</emphasis></term>
1078
1079             <listitem>
1080               <para>Specifies one or more ACL entries, each of which pairs a user or group name and a set of permissions. Separate
1081               the pairs, and the two parts of each pair, with one or more spaces. For a detailed description of acceptable values,
1082               see <link linkend="HDRWQ55">To Add, Remove, or Edit Normal ACL Permissions</link>. Keep in mind that the usual meaning
1083               of each permission is reversed.</para>
1084             </listitem>
1085           </varlistentry>
1086
1087           <varlistentry>
1088             <term><emphasis role="bold">-negative</emphasis></term>
1089
1090             <listitem>
1091               <para>Places the entries defined by the <emphasis role="bold">-acl</emphasis> argument on the negative permissions
1092               section of the ACL for each directory named by the <emphasis role="bold">-dir</emphasis> argument.</para>
1093             </listitem>
1094           </varlistentry>
1095         </variablelist></para>
1096     </sect2>
1097
1098     <sect2 id="Header_102">
1099       <title>Example: Setting an Entry in the Negative Permissions Section</title>
1100
1101       <indexterm>
1102         <primary>examples</primary>
1103
1104         <secondary>creating entry on negative permissions section of ACL</secondary>
1105       </indexterm>
1106
1107       <para>User <emphasis role="bold">terry</emphasis> has granted all access permissions except <emphasis role="bold">a</emphasis>
1108       to the group <emphasis role="bold">terry:team</emphasis> on her <emphasis role="bold">plans</emphasis> subdirectory.</para>
1109
1110       <programlisting>
1111    % <emphasis role="bold">cd /afs/abc.com/usr/terry</emphasis>
1112    % <emphasis role="bold">fs listacl plans</emphasis>
1113    Access control list for plans is
1114    Normal rights:
1115       system:anyuser rl
1116       terry:team rlidwk
1117       terry  rlidwka
1118 </programlisting>
1119
1120       <para>However, <emphasis role="bold">terry</emphasis> notices that one of the members of the group, user <emphasis
1121       role="bold">pat</emphasis>, has been making inappropriate changes to files. To prevent this without removing <emphasis
1122       role="bold">pat</emphasis> from the group or changing the permissions for the <emphasis role="bold">terry:team</emphasis>
1123       group, <emphasis role="bold">terry</emphasis> creates an entry on the negative permissions section of the ACL that denies the
1124       <emphasis role="bold">w</emphasis> and <emphasis role="bold">d</emphasis> permissions to <emphasis
1125       role="bold">pat</emphasis>:</para>
1126
1127       <programlisting>
1128    % <emphasis role="bold">fs setacl plans pat wd -negative</emphasis>
1129    % <emphasis role="bold">fs listacl plans</emphasis>
1130    Access control list for plans is
1131    Normal rights:
1132       system:anyuser rl
1133       terry:team rlidwk
1134       terry: rlidwka
1135    Negative rights:
1136       pat wd
1137 </programlisting>
1138     </sect2>
1139
1140     <sect2 id="Header_103">
1141       <title>Example: Restoring Access by Removing an Entry from the Negative Permissions Section</title>
1142
1143       <para>In the previous example, user <emphasis role="bold">terry</emphasis> put <emphasis role="bold">pat</emphasis> on the
1144       negative permissions section of ACL for the <emphasis role="bold">plans</emphasis> subdirectory. But the result has been
1145       inconvenient and <emphasis role="bold">pat</emphasis> has promised not to change files any more. To enable <emphasis
1146       role="bold">pat</emphasis> to exercise all permissions granted to the members of the <emphasis
1147       role="bold">terry:team</emphasis> group, <emphasis role="bold">terry</emphasis> removes the entry for <emphasis
1148       role="bold">pat</emphasis> from the negative permissions section of the ACL.</para>
1149
1150       <programlisting>
1151    % <emphasis role="bold">fs setacl plans pat  none -negative</emphasis>
1152    % <emphasis role="bold">fs listacl plans</emphasis>
1153    Access control list for plans is
1154    Normal rights:
1155       system:anyuser rl
1156       terry:team rlidwk
1157       terry  rlidwka
1158 </programlisting>
1159     </sect2>
1160   </sect1>
1161
1162   <sect1 id="HDRWQ57">
1163     <title>Completely Replacing an ACL</title>
1164
1165     <indexterm>
1166       <primary>ACL</primary>
1167
1168       <secondary>replacing all entries</secondary>
1169     </indexterm>
1170
1171     <indexterm>
1172       <primary>ACL</primary>
1173
1174       <secondary>clearing</secondary>
1175     </indexterm>
1176
1177     <indexterm>
1178       <primary>replacing</primary>
1179
1180       <secondary>all entries on ACL</secondary>
1181     </indexterm>
1182
1183     <indexterm>
1184       <primary>erasing all ACL entries</primary>
1185     </indexterm>
1186
1187     <indexterm>
1188       <primary>clearing all ACL entries</primary>
1189     </indexterm>
1190
1191     <indexterm>
1192       <primary>removing</primary>
1193
1194       <secondary>all ACL entries</secondary>
1195     </indexterm>
1196
1197     <indexterm>
1198       <primary>directories</primary>
1199
1200       <secondary>replacing ACL</secondary>
1201     </indexterm>
1202
1203     <para>It is sometimes simplest to clear an ACL completely before defining new permissions on it, for instance if the mix of
1204     normal and negative permissions makes it difficult to understand how their interaction affects access to the directory. To clear
1205     an ACL completely while you define new entries, include the <emphasis role="bold">-clear</emphasis> flag on the <emphasis
1206     role="bold">fs setacl</emphasis> command. When you include this flag, you can create entries on either the normal permissions or
1207     the negative permissions section of the ACL, but not on both at once.</para>
1208
1209     <para>Remember to create an entry for yourself. As the owner of the directory, you always have the <emphasis
1210     role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) permission required to replace a deleted entry, but the
1211     effects the effects of a missing ACL entry can be confusing enough to make it difficult to realize that the problem is a missing
1212     entry. In particular, the lack of the <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permission
1213     prevents you from using any shorthand notation in pathnames (such as a period for the current working directory or two periods
1214     for the parent directory).</para>
1215
1216     <sect2 id="Header_105">
1217       <title>To Replace an ACL Completely</title>
1218
1219       <para>Issue the <emphasis role="bold">fs setacl</emphasis> command with the <emphasis role="bold">-clear</emphasis> flag to
1220       clear the ACL completely before setting either normal or negative permissions. Because you need to grant the owner of the
1221       directory all permissions, it is better in most cases to set normal permissions at this point. <indexterm>
1222           <primary>fs commands</primary>
1223
1224           <secondary>setacl</secondary>
1225
1226           <tertiary>completely replacing ACL</tertiary>
1227         </indexterm></para>
1228
1229       <programlisting>
1230    % <emphasis role="bold">fs setacl  -dir</emphasis> &lt;<replaceable>directory</replaceable>&gt;<superscript>+</superscript> <emphasis
1231           role="bold">-acl</emphasis> &lt;<replaceable>access list entries</replaceable>&gt;<superscript>+</superscript> <emphasis
1232           role="bold">-clear</emphasis>  [<emphasis role="bold">-negative</emphasis>]
1233 </programlisting>
1234
1235       <para>where <variablelist>
1236           <varlistentry>
1237             <term><emphasis role="bold">sa</emphasis></term>
1238
1239             <listitem>
1240               <para>Is an acceptable alias for <emphasis role="bold">setacl</emphasis> (and <emphasis role="bold">seta</emphasis> is
1241               the shortest acceptable abbreviation).</para>
1242             </listitem>
1243           </varlistentry>
1244
1245           <varlistentry>
1246             <term><emphasis role="bold">-dir</emphasis></term>
1247
1248             <listitem>
1249               <para>Names one or more directories to which to apply the ACL entries defined by the <emphasis
1250               role="bold">-acl</emphasis> argument. For a detailed description of acceptable values, see <link linkend="HDRWQ55">To
1251               Add, Remove, or Edit Normal ACL Permissions</link>.</para>
1252             </listitem>
1253           </varlistentry>
1254
1255           <varlistentry>
1256             <term><emphasis role="bold">-acl</emphasis></term>
1257
1258             <listitem>
1259               <para>Specifies one or more ACL entries, each of which pairs a user or group name and a set of permissions. Separate
1260               the pairs, and the two parts of each pair, with one or more spaces. Remember to grant all permissions to the owner of
1261               the directory. For a detailed description of acceptable values, see <link linkend="HDRWQ55">To Add, Remove, or Edit
1262               Normal ACL Permissions</link>.</para>
1263             </listitem>
1264           </varlistentry>
1265
1266           <varlistentry>
1267             <term><emphasis role="bold">-clear</emphasis></term>
1268
1269             <listitem>
1270               <para>Removes all entries from each ACL before creating the entries indicated by the <emphasis
1271               role="bold">-acl</emphasis> argument.</para>
1272             </listitem>
1273           </varlistentry>
1274
1275           <varlistentry>
1276             <term><emphasis role="bold">-negative</emphasis></term>
1277
1278             <listitem>
1279               <para>Places the entries defined by the <emphasis role="bold">-acl</emphasis> argument on the negative permissions
1280               section of each ACL.</para>
1281             </listitem>
1282           </varlistentry>
1283         </variablelist></para>
1284     </sect2>
1285
1286     <sect2 id="Header_106">
1287       <title>Example: Replacing an ACL</title>
1288
1289       <indexterm>
1290         <primary>examples</primary>
1291
1292         <secondary>replacing an ACL</secondary>
1293       </indexterm>
1294
1295       <para>The following example clears the ACL on the current working directory and creates entries that grant all permissions to
1296       user <emphasis role="bold">terry</emphasis> and all permissions except <emphasis role="bold">a</emphasis> to user <emphasis
1297       role="bold">pat</emphasis>.</para>
1298
1299       <programlisting>
1300    % <emphasis role="bold">fs setacl . terry all pat write -clear</emphasis>
1301    % <emphasis role="bold">fs listacl .</emphasis>
1302    Access control list for . is
1303    Normal rights:
1304      terry rlidwka
1305      pat rlidwk
1306 </programlisting>
1307     </sect2>
1308   </sect1>
1309
1310   <sect1 id="HDRWQ58">
1311     <title>Copying ACLs Between Directories</title>
1312
1313     <indexterm>
1314       <primary>ACL</primary>
1315
1316       <secondary>copying between directories</secondary>
1317     </indexterm>
1318
1319     <indexterm>
1320       <primary>creating</primary>
1321
1322       <secondary>ACL as copy of another</secondary>
1323     </indexterm>
1324
1325     <indexterm>
1326       <primary>copying</primary>
1327
1328       <secondary>ACL between directories</secondary>
1329     </indexterm>
1330
1331     <indexterm>
1332       <primary>directories</primary>
1333
1334       <secondary>copying ACLs between</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, which overwrites the destination ACL completely.</para>
1347         </listitem>
1348
1349         <listitem>
1350           <para>If an entry is on both ACLs, the command changes the destination ACL entry to match the source ACL entry.</para>
1351         </listitem>
1352       </itemizedlist></para>
1353
1354     <para>To copy an ACL, you must have the <emphasis role="bold">l</emphasis> permission on the source ACL and the <emphasis
1355     role="bold">a</emphasis> permission on each destination ACL. If you identify the source directory by naming a file in it, you
1356     must also have the <emphasis role="bold">r</emphasis> permission on the source ACL. To display the permissions you have on the
1357     two directories, use the <emphasis role="bold">fs listacl</emphasis> command as described in <link linkend="HDRWQ52">Displaying
1358     an ACL</link>.</para>
1359
1360     <para><emphasis role="bold">Note for AFS/DFS Migration Toolkit users:</emphasis> If the machine on which you issue the <emphasis
1361     role="bold">fs copyacl</emphasis> command is configured for access to a DCE cell's DFS filespace via the AFS/DFS Migration
1362     Toolkit, you can use the command to copy ACLs between DFS files and directories also. The command includes <emphasis
1363     role="bold">-id</emphasis> and <emphasis role="bold">-if</emphasis> flags for altering a DFS directory's Initial Container and
1364     Initial Object ACLs as well as its regular ACL; for details, ask your system administrator. You cannot copy ACLs between AFS and
1365     DFS directories, because they use different ACL formats. The <emphasis role="bold">fs</emphasis> command interpreter ignores the
1366     <emphasis role="bold">-id</emphasis> and <emphasis role="bold">-if</emphasis> flags if you include them when copying AFS
1367     ACLs.</para>
1368
1369     <sect2 id="Header_108">
1370       <title>To Copy an ACL Between Directories</title>
1371
1372       <indexterm>
1373         <primary>commands</primary>
1374
1375         <secondary>fs copyacl</secondary>
1376       </indexterm>
1377
1378       <indexterm>
1379         <primary>fs commands</primary>
1380
1381         <secondary>copyacl</secondary>
1382       </indexterm>
1383
1384       <para>Issue the <emphasis role="bold">fs copyacl</emphasis> command to copy a source ACL to the ACL on one or more destination
1385       directories.</para>
1386
1387       <programlisting>
1388    % <emphasis role="bold">fs copyacl -fromdir</emphasis> &lt;<replaceable>source directory</replaceable>&gt; <emphasis role="bold">-todir</emphasis> &lt;<replaceable>destination directory</replaceable>&gt;<superscript>+</superscript>  \
1389                 [<emphasis role="bold">-clear</emphasis>]
1390 </programlisting>
1391
1392       <para>where <variablelist>
1393           <varlistentry>
1394             <term><emphasis role="bold">co</emphasis></term>
1395
1396             <listitem>
1397               <para>Is the shortest acceptable abbreviation for <emphasis role="bold">copyacl</emphasis>.</para>
1398             </listitem>
1399           </varlistentry>
1400
1401           <varlistentry>
1402             <term><emphasis role="bold">-fromdir</emphasis></term>
1403
1404             <listitem>
1405               <para>Names the source directory from which to copy the ACL. Partial pathnames are interpreted relative to the current
1406               working directory. If this argument names a file, the ACL is copied from its directory.</para>
1407             </listitem>
1408           </varlistentry>
1409
1410           <varlistentry>
1411             <term><emphasis role="bold">-todir</emphasis></term>
1412
1413             <listitem>
1414               <para>Names each destination directory to which to copy the source ACL. Partial pathnames are interpreted relative to
1415               the current working directory. Filenames are not acceptable.</para>
1416             </listitem>
1417           </varlistentry>
1418
1419           <varlistentry>
1420             <term><emphasis role="bold">-clear</emphasis></term>
1421
1422             <listitem>
1423               <para>Completely overwrites each destination directory's ACL with the source ACL.</para>
1424             </listitem>
1425           </varlistentry>
1426         </variablelist></para>
1427     </sect2>
1428
1429     <sect2 id="Header_109">
1430       <title>Example: Copying an ACL from One Directory to Another</title>
1431
1432       <indexterm>
1433         <primary>examples</primary>
1434
1435         <secondary>copying ACL between directories</secondary>
1436       </indexterm>
1437
1438       <para>In this example, user <emphasis role="bold">terry</emphasis> copies the ACL from her home directory (the current working
1439       directory) to its <emphasis role="bold">plans</emphasis> subdirectory. She begins by displaying both ACLs.</para>
1440
1441       <programlisting>
1442    % <emphasis role="bold">fs listacl . plans</emphasis>
1443    Access list for . is
1444    Normal rights:
1445       terry rlidwka
1446       pat rlidwk
1447       jones rl
1448    Access list for plans is
1449    Normal rights:
1450       terry rlidwka
1451       pat rl
1452       smith rl
1453
1454   % <emphasis role="bold">fs copyacl -from . -to plans</emphasis>
1455
1456    % <emphasis role="bold">fs listacl . plans</emphasis>
1457    Access list for . is
1458    Normal rights:
1459       terry rlidwka
1460       pat rlidwk
1461       jones rl
1462    Access list for plans is
1463    Normal rights:
1464       terry rlidwka
1465       pat rlidwk
1466       jones rl
1467       smith rl
1468 </programlisting>
1469     </sect2>
1470   </sect1>
1471
1472   <sect1 id="HDRWQ59">
1473     <title>How AFS Uses the UNIX Mode Bits</title>
1474
1475     <indexterm>
1476       <primary>UNIX, differences with AFS</primary>
1477
1478       <secondary>mode bits, interpretation</secondary>
1479     </indexterm>
1480
1481     <indexterm>
1482       <primary>mode bits (UNIX)</primary>
1483
1484       <secondary>interpretation in AFS</secondary>
1485     </indexterm>
1486
1487     <para>Although AFS protects data primarily with ACLs rather than mode bits, it does not ignore the mode bits entirely. An
1488     explanation of how mode bits work in the UNIX file system is outside the scope of this document, and the following discussion
1489     assumes you understand them; if necessary, see your UNIX documentation. Also, the following discussion does not cover the
1490     setuid, setgid or sticky bits. If you need to understand how those bits work on AFS files, see the <emphasis>OpenAFS
1491     Administration Guide</emphasis> or ask your system administrator.</para>
1492
1493     <para>AFS uses the UNIX mode bits in the following way:</para>
1494
1495     <itemizedlist>
1496       <listitem>
1497         <para>It uses the initial bit to distinguish files and directories. This is the bit that appears first in the output from
1498         the <emphasis role="bold">ls -l</emphasis> command and shows the hyphen (<computeroutput>-</computeroutput>) for a file or
1499         the letter <computeroutput>d</computeroutput> for a directory.</para>
1500       </listitem>
1501
1502       <listitem>
1503         <para>It does not use any of the mode bits on a directory. The AFS ACL alone controls directory access.</para>
1504       </listitem>
1505
1506       <listitem>
1507         <para>For a file, the owner (first) set of bits interacts with the ACL entries that apply to the file in the following way.
1508         AFS does not use the group or world (second and third sets) of mode bits at all. <itemizedlist>
1509             <listitem>
1510               <para>If the first <emphasis role="bold">r</emphasis> mode bit is not set, no one (including the owner) can read the
1511               file, no matter what permissions they have on the ACL. If the bit is set, users also need the <emphasis
1512               role="bold">r</emphasis> and <emphasis role="bold">l</emphasis> permissions on the ACL of the file's directory to read
1513               the file.</para>
1514             </listitem>
1515
1516             <listitem>
1517               <para>If the first <emphasis role="bold">w</emphasis> mode bit is not set, no one (including the owner) can modify the
1518               file. If the <emphasis role="bold">w</emphasis> bit is set, users also need the <emphasis role="bold">w</emphasis> and
1519               <emphasis role="bold">l</emphasis> permissions on the ACL of the file's directory to modify the file.</para>
1520             </listitem>
1521
1522             <listitem>
1523               <para>There is no ACL permission directly corresponding to the <emphasis role="bold">x</emphasis> mode bit, but to
1524               execute a file stored in AFS, the user must also have the <emphasis role="bold">r</emphasis> and <emphasis
1525               role="bold">l</emphasis> permissions on the ACL of the file's directory.</para>
1526             </listitem>
1527           </itemizedlist></para>
1528       </listitem>
1529     </itemizedlist>
1530
1531     <para>When you issue the UNIX <emphasis role="bold">chmod</emphasis> command on an AFS file or directory, AFS changes the bits
1532     appropriately. To change a file's mode bits, you must have the AFS <emphasis role="bold">w</emphasis> permission on the ACL of
1533     the file's directory. To change a directory's mode bits, you must have the <emphasis role="bold">d</emphasis>, <emphasis
1534     role="bold">i</emphasis>, and <emphasis role="bold">l</emphasis> permissions on its ACL. <indexterm>
1535         <primary>commands</primary>
1536
1537         <secondary>chmod</secondary>
1538       </indexterm> <indexterm>
1539         <primary>chmod command</primary>
1540       </indexterm></para>
1541
1542     <sect2 id="Header_111">
1543       <title>Example: Disabling Write Access for a File</title>
1544
1545       <para><indexterm>
1546           <primary>examples</primary>
1547
1548           <secondary>using chmod</secondary>
1549         </indexterm></para>
1550
1551       <para>Suppose <emphasis role="bold">terry</emphasis> is chairing a committee that is writing a proposal. As each section is
1552       approved, she turns off write access to that file to prevent further changes. For example, the following <emphasis
1553       role="bold">chmod</emphasis> command turns off the <emphasis role="bold">w</emphasis> mode bits on the file <emphasis
1554       role="bold">proposal.chap2</emphasis>. This makes it impossible for anyone to change the file, no matter what permissions are
1555       granted on the directory ACL.</para>
1556
1557       <programlisting>
1558    % <emphasis role="bold">chmod -w proposal.chap2</emphasis>
1559    % <emphasis role="bold">ls -l</emphasis>
1560    -rw-r--r--  1 terry     573 Nov 10 09:57 conclusion
1561    -r--r--r--  1 terry     573 Nov 15 10:34 intro
1562    -r--r--r--  1 terry     573 Dec  1 15:07 proposal.chap2
1563    -rw-r--r--  1 terry     573 Nov 10 09:57 proposal.chap3
1564    -rw-r--r--  1 terry     573 Nov 10 09:57 proposal.chap4
1565 </programlisting>
1566     </sect2>
1567   </sect1>
1568 </chapter>