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
 452     <sect2>
 453       <title>Dropbox Permissions</title>
 454
 455       <para>If a user or group is granted the <emphasis
 456       role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) and
 457       <emphasis role="bold">i</emphasis> (<emphasis
 458       role="bold">insert</emphasis>) permissions, but not the <emphasis
 459       role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) and/or
 460       <emphasis role="bold">w</emphasis> (<emphasis
 461       role="bold">write</emphasis>) permissions, this is commonly referred to
 462       as a "dropbox" for that user or group. What this means is that that user
 463       or group may deposit files in the directory, but they may not read or
 464       modify their file later, nor any other file in the directory.</para>
 465
 466       <para>Know, however, that some of these restrictions are enforced on the
 467       client and not on the fileserver, and so should not be relied on for
 468       security. In particular, the fileserver does not know when a file is
 469       opened or closed on the client, and and so read and write permissions are
 470       granted to any user with "dropbox" permissions that owns the accessed
 471       file.</para>
 472
 473       <para>Additionally, granting "dropbox" permissons to <emphasis
 474       role="bold">system:anyuser</emphasis> raises additional problems, if you
 475       want the dropbox to work for unauthenticated users. Any file deposited by
 476       an unauthenticated user will be owned by the unauthenticated user ID, and
 477       so would be readable and modifiable by anyone. In order to try and
 478       prevent accidentally revealing private information, the fileserver does
 479       not grant the implicit read permission to unauthenticated users, even if
 480       they have dropbox permissions. This may cause depositing files as an
 481       unauthenticated user to arbitrarily fail, and so you should not depend on
 482       granting dropbox permissions to unauthenticated users to work
 483       reliably.</para>
 484     </sect2>
 485   </sect1>
 486
 487   <sect1 id="HDRWQ50">
 488     <title>Using the System Groups on ACLs</title>
 489
 490     <para><indexterm>
 491         <primary>system groups</primary>
 492
 493         <secondary>using on ACLs</secondary>
 494       </indexterm> <indexterm>
 495         <primary>system:anyuser group</primary>
 496
 497         <secondary>using on ACLs</secondary>
 498       </indexterm> <indexterm>
 499         <primary>system:authuser group</primary>
 500       </indexterm> <indexterm>
 501         <primary>system:administrators group</primary>
 502       </indexterm> AFS defines two <emphasis>system groups</emphasis> that grant access to a large number of users at once when
 503     placed on an ACL. However, you cannot control the membership of these groups, so consider carefully what kind of permissions you
 504     wish to give them. (You do control the membership of the groups you own; see <link linkend="HDRWQ60">Using Groups</link>.)
 505     <variablelist>
 506         <varlistentry>
 507           <term><emphasis role="bold">system:anyuser</emphasis></term>
 508
 509           <listitem>
 510             <para>Includes anyone who can access the cell's file tree, including users who have tokens in the local cell, users who
 511             have logged in on a local AFS client machine but have not obtained tokens (such as the local superuser <emphasis
 512             role="bold">root</emphasis>), and users who have connected to a local machine from outside the cell. Creating an ACL
 513             entry for this group is the only way to extend access to AFS users from foreign cells, unless your system administrator
 514             creates local authentication accounts for them. <indexterm>
 515                 <primary>ACL</primary>
 516
 517                 <secondary>foreign users on</secondary>
 518               </indexterm></para>
 519           </listitem>
 520         </varlistentry>
 521
 522         <varlistentry>
 523           <term><emphasis role="bold">system:authuser</emphasis></term>
 524
 525           <listitem>
 526             <para>Includes all users who have a valid AFS token obtained from the local cell's AFS authentication service.</para>
 527           </listitem>
 528         </varlistentry>
 529       </variablelist></para>
 530
 531     <para>The third system group, <emphasis role="bold">system:administrators</emphasis>, includes a small group of administrators
 532     who have extensive permissions in the cell. You do not generally need to put this group on your ACLs, because its members always
 533     have the <emphasis role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) permission on every ACL, even if the
 534     group does not appear on it.</para>
 535
 536     <sect2 id="Header_90">
 537       <title>Enabling Access to Subdirectories</title>
 538
 539       <indexterm>
 540         <primary>subdirectories, accessing</primary>
 541       </indexterm>
 542
 543       <indexterm>
 544         <primary>access to AFS filespace</primary>
 545
 546         <secondary>controlling for subdirectories</secondary>
 547       </indexterm>
 548
 549       <para>A user must have the <emphasis role="bold">l</emphasis> permission on a directory to access its subdirectories in any
 550       way. Even if users have extensive permissions on a subdirectory, they cannot access it if the parent directory's ACL does not
 551       grant the <emphasis role="bold">l</emphasis> permission.</para>
 552
 553       <para>You can grant the <emphasis role="bold">l</emphasis> permission in one of three ways: grant it to a system group
 554       (<emphasis role="bold">system:anyuser</emphasis> or <emphasis role="bold">system:authuser</emphasis>), grant it to individual
 555       users, or grant it to one or more groups of users defined by you or other users (see <link linkend="HDRWQ60">Using
 556       Groups</link>). Granting the <emphasis role="bold">l</emphasis> permission to the <emphasis
 557       role="bold">system:anyuser</emphasis> group is the easiest option and is generally secure because the permission only enables
 558       users to list the contents of the directory, not to read the files in it. If you want to enable only locally authenticated
 559       users to list a directory's contents, substitute the <emphasis role="bold">system:authuser</emphasis> group for the <emphasis
 560       role="bold">system:anyuser</emphasis> group. Your system administrator has possibly already created an entry on your home
 561       directory's ACL that grants the <emphasis role="bold">r</emphasis> and <emphasis role="bold">l</emphasis> permissions to the
 562       <emphasis role="bold">system:anyuser</emphasis> group.</para>
 563     </sect2>
 564
 565     <sect2 id="Header_91">
 566       <title>Extending Access to Service Processes</title>
 567
 568       <indexterm>
 569         <primary>access to AFS filespace</primary>
 570
 571         <secondary>enabling for service processes</secondary>
 572       </indexterm>
 573
 574       <para>It is sometimes necessary to grant more extensive permissions to the <emphasis role="bold">system:anyuser</emphasis>
 575       group so that processes that provide printing and mail delivery service can work correctly. For example, printing processes
 576       sometimes need the <emphasis role="bold">r</emphasis> permission in addition to the <emphasis role="bold">l</emphasis>
 577       permission. A mail delivery process possibly needs the <emphasis role="bold">i</emphasis> permission to place new messages in
 578       your mail directory. Your system administrator has probably already created the necessary ACL entries. If you notice an ACL
 579       entry for which the purpose is unclear, check with your system administrator before removing it.</para>
 580     </sect2>
 581
 582     <sect2 id="HDRWQ51">
 583       <title>Extending Access to Users from Foreign Cells</title>
 584
 585       <para><indexterm>
 586           <primary>access to AFS filespace</primary>
 587
 588           <secondary>enabling for users from foreign cells</secondary>
 589         </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
 590       <emphasis role="bold">system:anyuser</emphasis> group on an ACL. Remember, however, that such an entry extends access to
 591       everyone who can reach your cell, not just the AFS users from foreign cells that you have in mind.</para>
 592     </sect2>
 593   </sect1>
 594
 595   <sect1 id="HDRWQ52">
 596     <title>Displaying an ACL</title>
 597
 598     <indexterm>
 599       <primary>ACL</primary>
 600
 601       <secondary>displaying</secondary>
 602     </indexterm>
 603
 604     <indexterm>
 605       <primary>displaying</primary>
 606
 607       <secondary>ACL entries</secondary>
 608     </indexterm>
 609
 610     <indexterm>
 611       <primary>permissions on ACL</primary>
 612
 613       <secondary>displaying</secondary>
 614     </indexterm>
 615
 616     <para>To display the ACL associated with a file or directory, issue the <emphasis role="bold">fs listacl</emphasis>
 617     command.</para>
 618
 619     <para><emphasis role="bold">Note for AFS/DFS Migration Toolkit users:</emphasis> If the machine on which you issue the <emphasis
 620     role="bold">fs listacl</emphasis> command is configured to access a DCE cell's DFS filespace via the AFS/DFS Migration Toolkit,
 621     you can use the command to display the ACL on DFS files and directories. To display a DFS directory's Initial Container or
 622     Initial Object ACL instead of the regular one, include the <emphasis role="bold">fs listacl</emphasis> command's <emphasis
 623     role="bold">-id</emphasis> or <emphasis role="bold">-if</emphasis> flag. For more information, ask your system administrator.
 624     The <emphasis role="bold">fs</emphasis> command interpreter ignores the <emphasis role="bold">-id</emphasis> and <emphasis
 625     role="bold">-if</emphasis> flags if you include them when displaying an AFS ACL.</para>
 626
 627     <sect2 id="HDRWQ53">
 628       <title>To display an ACL</title>
 629
 630       <orderedlist>
 631         <listitem>
 632           <para>Issue the <emphasis role="bold">fs listacl</emphasis> command. <indexterm>
 633               <primary>fs commands</primary>
 634
 635               <secondary>listacl</secondary>
 636             </indexterm> <indexterm>
 637               <primary>commands</primary>
 638
 639               <secondary>fs listacl</secondary>
 640             </indexterm> <programlisting>
 641    % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;<superscript>+</superscript>]
 642 </programlisting></para>
 643
 644           <para>where</para>
 645
 646           <variablelist>
 647             <varlistentry>
 648               <term><emphasis role="bold">la</emphasis></term>
 649
 650               <listitem>
 651                 <para>Is an acceptable alias for <emphasis role="bold">listacl</emphasis> (and <emphasis
 652                 role="bold">lista</emphasis> is the shortest acceptable abbreviation).</para>
 653               </listitem>
 654             </varlistentry>
 655
 656             <varlistentry>
 657               <term><emphasis role="bold"><replaceable>dir/file path</replaceable></emphasis></term>
 658
 659               <listitem>
 660                 <para>Names one or more files or directories for which to display the ACL. For a file, the output displays the ACL
 661                 on its directory. If you omit this argument, the output is for the current working directory. Partial pathnames are
 662                 interpreted relative to the current working directory. You can also use the following notation on its own or as part
 663                 of a pathname: <variablelist>
 664                     <varlistentry>
 665                       <term><emphasis role="bold">.</emphasis></term>
 666
 667                       <listitem>
 668                         <para>(A single period). Specifies the current working directory.</para>
 669                       </listitem>
 670                     </varlistentry>
 671
 672                     <varlistentry>
 673                       <term><emphasis role="bold">..</emphasis></term>
 674
 675                       <listitem>
 676                         <para>(Two periods). Specifies the current working directory's parent directory.</para>
 677                       </listitem>
 678                     </varlistentry>
 679
 680                     <varlistentry>
 681                       <term><emphasis role="bold">*</emphasis></term>
 682
 683                       <listitem>
 684                         <para>(The asterisk). Specifies each file and subdirectory in the current working directory. The ACL
 685                         displayed for a file is always the same as for its directory, but the ACL for each subdirectory can
 686                         differ.</para>
 687                       </listitem>
 688                     </varlistentry>
 689                   </variablelist></para>
 690               </listitem>
 691             </varlistentry>
 692           </variablelist>
 693         </listitem>
 694       </orderedlist>
 695
 696       <para>The output for each file or directory specified as <replaceable>dir/file path</replaceable> begins with the following
 697       header to identify it:</para>
 698
 699       <programlisting>
 700    Access list for  <replaceable>dir/file path</replaceable> is
 701 </programlisting>
 702
 703       <para>The <computeroutput>Normal rights</computeroutput> header appears on the next line, followed by lines that each pair a
 704       user or group name and a set of permissions. The permissions appear as the single letters defined in <link
 705       linkend="HDRWQ46">The AFS ACL Permissions</link>, and always in the order <emphasis role="bold">rlidwka</emphasis>. If there
 706       are any negative permissions, the <computeroutput>Negative rights</computeroutput> header appears next, followed by pairs of
 707       negative permissions.</para>
 708
 709       <para>If the following error message appears instead of an ACL, you do not have the permissions needed to display an ACL. To
 710       specify a directory name as the <replaceable>dir/file path</replaceable> argument, you must have the <emphasis
 711       role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permission on the ACL. To specify a filename, you must also
 712       have the <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) permission on its directory's ACL.</para>
 713
 714       <programlisting>
 715    fs: You don't have the required access permissions on '<replaceable>dir/file path</replaceable>'
 716 </programlisting>
 717     </sect2>
 718
 719     <sect2 id="Header_95">
 720       <title>Example: Displaying the ACL on One Directory</title>
 721
 722       <indexterm>
 723         <primary>examples</primary>
 724
 725         <secondary>displaying ACL for single directory</secondary>
 726       </indexterm>
 727
 728       <para>The following example displays the ACL on user <emphasis role="bold">terry</emphasis>'s home directory in the Example
 729       Corporation cell:</para>
 730
 731       <programlisting>
 732    % <emphasis role="bold">fs la /afs/example.com/usr/terry</emphasis>
 733    Access list for /afs/example.com/usr/terry is
 734    Normal rights:
 735       system:authuser rl
 736       pat rlw
 737       terry rlidwka
 738    Negative rights:
 739       terry:other-dept rl
 740       jones rl
 741 </programlisting>
 742
 743       <para>where <emphasis role="bold">pat</emphasis>, <emphasis role="bold">terry</emphasis>, and <emphasis
 744       role="bold">jones</emphasis> are individual users, <emphasis role="bold">system:authuser</emphasis> is a system group, and
 745       <emphasis role="bold">terry:other-dept</emphasis> is a group that <emphasis role="bold">terry</emphasis> owns. The list of
 746       normal permissions grants all permissions to <emphasis role="bold">terry</emphasis>, the <emphasis role="bold">rlw</emphasis>
 747       permissions to <emphasis role="bold">pat</emphasis>, and the <emphasis role="bold">rl</emphasis> permissions to the members of
 748       the <emphasis role="bold">system:authuser</emphasis> group.</para>
 749
 750       <para>The list of negative permissions denies the <emphasis role="bold">rl</emphasis> permissions to <emphasis
 751       role="bold">jones</emphasis> and the members of the <emphasis role="bold">terry:other-dept</emphasis> group. These entries
 752       effectively prevent them from accessing <emphasis role="bold">terry</emphasis>'s home directory in any way; they cancel out
 753       the <emphasis role="bold">rl</emphasis> permissions extended to the <emphasis role="bold">system:authuser</emphasis> group,
 754       which is the only entry on the normal permissions section of the ACL that possibly applies to them.</para>
 755     </sect2>
 756
 757     <sect2 id="Header_96">
 758       <title>Example: Displaying the ACLs on Multiple Directories</title>
 759
 760       <indexterm>
 761         <primary>examples</primary>
 762
 763         <secondary>displaying ACLs for multiple directories</secondary>
 764       </indexterm>
 765
 766       <para>The following example illustrates how you can specify pathnames in different ways, and the appearance of the output for
 767       multiple directories. It displays the ACL for three directories: the current working directory (which is a subdirectory of
 768       user <emphasis role="bold">terry</emphasis>'s home directory), the home directory for user <emphasis
 769       role="bold">pat</emphasis>, and another subdirectory of <emphasis role="bold">terry</emphasis>'s home directory called
 770       <emphasis role="bold">plans</emphasis>.</para>
 771
 772       <programlisting>
 773    % <emphasis role="bold">fs listacl  .  /afs/example.com/usr/pat  ../plans</emphasis>
 774    Access list for . is
 775    Normal rights:
 776       system:anyuser rl
 777       pat:dept rliw
 778    Access list for /afs/example.com/usr/pat is
 779    Normal rights:
 780       system:anyuser rl
 781       pat rlidwka
 782       terry rliw
 783    Access list for ../plans is
 784    Normal rights:
 785       terry rlidwka
 786       pat rlidw
 787 </programlisting>
 788     </sect2>
 789   </sect1>
 790
 791   <sect1 id="HDRWQ54">
 792     <title>Changing an ACL</title>
 793
 794     <indexterm>
 795       <primary>changing</primary>
 796
 797       <secondary>ACLs</secondary>
 798     </indexterm>
 799
 800     <indexterm>
 801       <primary>setting permissions on ACL</primary>
 802     </indexterm>
 803
 804     <indexterm>
 805       <primary>ACL</primary>
 806
 807       <secondary>setting</secondary>
 808     </indexterm>
 809
 810     <indexterm>
 811       <primary>permissions on ACL</primary>
 812
 813       <secondary>setting</secondary>
 814     </indexterm>
 815
 816     <para>To add, remove, or edit ACL entries, use the <emphasis role="bold">fs setacl</emphasis> command. By default, the command
 817     manipulates entries on the normal permissions section of the ACL. To manipulate entries on the negative permissions section,
 818     include the <emphasis role="bold">-negative</emphasis> flag as instructed in <link linkend="HDRWQ56">To Add, Remove, or Edit
 819     Negative ACL Permissions</link>.</para>
 820
 821     <para>You can change any ACL on which you already have the <emphasis role="bold">a</emphasis> permission. You always have the
 822     <emphasis role="bold">a</emphasis> permission on the ACL of every directory that you own, even if you accidentally remove that
 823     permission from the ACL. (The <emphasis role="bold">ls -ld</emphasis> command reports a directory's owner.) Your system
 824     administrator normally designates you as the owner of your home directory and its subdirectories, and you possibly own other
 825     directories also.</para>
 826
 827     <para>If an ACL entry already exists for the user or group you specify, then the new permissions completely replace the existing
 828     permissions rather than being added to them. In other words, when issuing the <emphasis role="bold">fs setacl</emphasis>
 829     command, you must include all permissions that you want to grant to a user or group.</para>
 830
 831     <para><emphasis role="bold">Note for AFS/DFS Migration Toolkit users:</emphasis> If the machine on which you issue the <emphasis
 832     role="bold">fs setacl</emphasis> command is configured to access a DCE cell's DFS filespace via the AFS/DFS Migration Toolkit,
 833     you can use the command to set the ACL on DFS files and directories. To set a DFS directory's Initial Container or Initial
 834     Object ACL instead of the regular one, include the <emphasis role="bold">fs setacl</emphasis> command's <emphasis
 835     role="bold">-id</emphasis> or <emphasis role="bold">-if</emphasis> flag. For more information, ask your system administrator.
 836     The <emphasis role="bold">fs</emphasis> command interpreter ignores the <emphasis role="bold">-id</emphasis> and <emphasis
 837     role="bold">-if</emphasis> flags if you include them when setting an AFS ACL.</para>
 838
 839     <sect2 id="HDRWQ55">
 840       <title>To Add, Remove, or Edit Normal ACL Permissions</title>
 841
 842       <indexterm>
 843         <primary>creating</primary>
 844
 845         <secondary>ACL entry in normal permissions section</secondary>
 846       </indexterm>
 847
 848       <indexterm>
 849         <primary>ACL</primary>
 850
 851         <secondary>creating normal entry</secondary>
 852       </indexterm>
 853
 854       <indexterm>
 855         <primary>adding</primary>
 856
 857         <secondary>ACL entry to normal permissions section</secondary>
 858       </indexterm>
 859
 860       <indexterm>
 861         <primary>granting access to AFS filespace</primary>
 862       </indexterm>
 863
 864       <indexterm>
 865         <primary>access to AFS filespace</primary>
 866
 867         <secondary>ACL entries control</secondary>
 868       </indexterm>
 869
 870       <indexterm>
 871         <primary>directories</primary>
 872
 873         <secondary>granting access</secondary>
 874       </indexterm>
 875
 876       <indexterm>
 877         <primary>files</primary>
 878
 879         <secondary>granting access</secondary>
 880       </indexterm>
 881
 882       <para>Issue the <emphasis role="bold">fs setacl</emphasis> command to edit entries in the normal permissions section of the
 883       ACL. To remove an entry, specify the <emphasis role="bold">none</emphasis> shorthand as the permissions. If an ACL entry
 884       already exists for a user or group, the permissions you specify completely replace those in the existing entry. <indexterm>
 885           <primary>commands</primary>
 886
 887           <secondary>fs setacl</secondary>
 888         </indexterm> <indexterm>
 889           <primary>fs commands</primary>
 890
 891           <secondary>setacl</secondary>
 892         </indexterm></para>
 893
 894       <programlisting>
 895    % <emphasis role="bold">fs setacl  -dir</emphasis> &lt;<replaceable>directory</replaceable>&gt;<superscript>+</superscript> <emphasis
 896           role="bold">-acl</emphasis> &lt;<replaceable>access list entries</replaceable>&gt;<superscript>+</superscript>
 897 </programlisting>
 898
 899       <para>where <variablelist>
 900           <varlistentry>
 901             <term><emphasis role="bold">sa</emphasis></term>
 902
 903             <listitem>
 904               <para>Is an acceptable alias for <emphasis role="bold">setacl</emphasis> (and <emphasis role="bold">seta</emphasis> is
 905               the shortest acceptable abbreviation).</para>
 906             </listitem>
 907           </varlistentry>
 908
 909           <varlistentry>
 910             <term><emphasis role="bold">-dir</emphasis></term>
 911
 912             <listitem>
 913               <para>Names one or more directories to which to apply the ACL entries defined by the <emphasis
 914               role="bold">-acl</emphasis> argument. Partial pathnames are interpreted relative to the current working directory. You
 915               can also use the following notation on its own or as part of a pathname: <variablelist>
 916                   <varlistentry>
 917                     <term><emphasis role="bold">.</emphasis></term>
 918
 919                     <listitem>
 920                       <para>(A single period). If used by itself, sets the ACL on the current working directory.</para>
 921                     </listitem>
 922                   </varlistentry>
 923
 924                   <varlistentry>
 925                     <term><emphasis role="bold">..</emphasis></term>
 926
 927                     <listitem>
 928                       <para>(Two periods). If used by itself, sets the ACL on the current working directory's parent
 929                       directory.</para>
 930                     </listitem>
 931                   </varlistentry>
 932
 933                   <varlistentry>
 934                     <term><emphasis role="bold">*</emphasis></term>
 935
 936                     <listitem>
 937                       <para>(The asterisk). Sets the ACL on each of the subdirectories in the current working directory. You must
 938                       precede it with the <emphasis role="bold">-dir</emphasis> switch, since it potentially designates multiple
 939                       directories. The <emphasis role="bold">fs</emphasis> command interpreter generates the following error message
 940                       for each file in the directory: <programlisting>
 941    fs: '<replaceable>filename</replaceable>': Not a directory
 942 </programlisting></para>
 943                     </listitem>
 944                   </varlistentry>
 945                 </variablelist></para>
 946
 947               <para>If you specify only one directory (or file) name, you can omit the <emphasis role="bold">-dir</emphasis> and
 948               <emphasis role="bold">-acl</emphasis> switches. For more on omitting switches, see <link linkend="HDRWQ86">Appendix B,
 949               OpenAFS Command Syntax and Online Help</link>.</para>
 950             </listitem>
 951           </varlistentry>
 952
 953           <varlistentry>
 954             <term><emphasis role="bold">-acl</emphasis></term>
 955
 956             <listitem>
 957               <para>Specifies one or more ACL entries, each of which pairs a user or group name and a set of permissions. Separate
 958               the pairs, and the two parts of each pair, with one or more spaces.</para>
 959
 960               <para>To define the permissions, provide either:</para>
 961
 962               <itemizedlist>
 963                 <listitem>
 964                   <para>One or more of the letters that represent the standard or auxiliary permissions (<emphasis
 965                   role="bold">rlidwka</emphasis> and <emphasis role="bold">ABCDEFGH</emphasis>), in any order</para>
 966                 </listitem>
 967
 968                 <listitem>
 969                   <para>One of the four shorthand notations: <itemizedlist>
 970                       <listitem>
 971                         <para><emphasis role="bold">all</emphasis> (equals <emphasis role="bold">rlidwka</emphasis>)</para>
 972                       </listitem>
 973
 974                       <listitem>
 975                         <para><emphasis role="bold">none</emphasis> (removes the entry)</para>
 976                       </listitem>
 977
 978                       <listitem>
 979                         <para><emphasis role="bold">read</emphasis> (equals <emphasis role="bold">rl</emphasis>)</para>
 980                       </listitem>
 981
 982                       <listitem>
 983                         <para><emphasis role="bold">write</emphasis> (equals <emphasis role="bold">rlidwk</emphasis>)</para>
 984                       </listitem>
 985                     </itemizedlist></para>
 986                 </listitem>
 987               </itemizedlist>
 988
 989               <para>On a single command line, you can combine user and group entries. Also, you can both combine individual letters
 990               and use the shorthand notations, but not within a single pair.</para>
 991             </listitem>
 992           </varlistentry>
 993         </variablelist></para>
 994     </sect2>
 995
 996     <sect2 id="Header_99">
 997       <title>Example: Adding a Single ACL Entry</title>
 998
 999       <indexterm>
1000         <primary>examples</primary>
1001
1002         <secondary>adding a user to an ACL</secondary>
1003       </indexterm>
1004
1005       <para>Either of the following example commands grants user <emphasis role="bold">pat</emphasis> the <emphasis
1006       role="bold">r</emphasis> and <emphasis role="bold">l</emphasis> permissions on the ACL of the <emphasis
1007       role="bold">notes</emphasis> subdirectory of the current working directory. They illustrate how it is possible to omit the
1008       <emphasis role="bold">-dir</emphasis> and <emphasis role="bold">-acl</emphasis> switches when you name only one
1009       directory.</para>
1010
1011       <programlisting>
1012    % <emphasis role="bold">fs sa notes pat rl</emphasis>
1013    % <emphasis role="bold">fs sa notes pat read</emphasis>
1014 </programlisting>
1015     </sect2>
1016
1017     <sect2 id="Header_100">
1018       <title>Example: Setting Several ACL Entries on One Directory</title>
1019
1020       <para>The following example edits the ACL for the current working directory. It removes the entry for the <emphasis
1021       role="bold">system:anyuser</emphasis> group, and adds two entries: one grants all permissions except <emphasis
1022       role="bold">a</emphasis> to the members of the <emphasis role="bold">terry:colleagues</emphasis> group and the other grants
1023       the <emphasis role="bold">r</emphasis> and <emphasis role="bold">l</emphasis> permissions to the <emphasis
1024       role="bold">system:authuser</emphasis> group.</para>
1025
1026       <programlisting>
1027    % <emphasis role="bold">fs sa  -dir . -acl  system:anyuser none  terry:colleagues write</emphasis>  \
1028             <emphasis role="bold">system:authuser rl</emphasis>
1029 </programlisting>
1030     </sect2>
1031
1032     <sect2 id="HDRWQ56">
1033       <title>To Add, Remove, or Edit Negative ACL Permissions</title>
1034
1035       <indexterm>
1036         <primary>creating</primary>
1037
1038         <secondary>ACL entry in negative permissions section</secondary>
1039       </indexterm>
1040
1041       <indexterm>
1042         <primary>ACL</primary>
1043
1044         <secondary>creating negative entry</secondary>
1045       </indexterm>
1046
1047       <indexterm>
1048         <primary>adding</primary>
1049
1050         <secondary>ACL entry to negative permissions section</secondary>
1051       </indexterm>
1052
1053       <indexterm>
1054         <primary>denying access with negative ACL entry</primary>
1055       </indexterm>
1056
1057       <indexterm>
1058         <primary>directories</primary>
1059
1060         <secondary>denying access</secondary>
1061       </indexterm>
1062
1063       <indexterm>
1064         <primary>files</primary>
1065
1066         <secondary>denying access</secondary>
1067       </indexterm>
1068
1069       <para>Issue the <emphasis role="bold">fs setacl</emphasis> command with the <emphasis role="bold">-negative</emphasis> flag to
1070       edit entries in the negative permissions section of the ACL. To remove an entry, specify the <emphasis
1071       role="bold">none</emphasis> shorthand as the permissions. If an ACL entry already exists for a user or group, the permissions
1072       you specify completely replace those in the existing entry. <indexterm>
1073           <primary>fs commands</primary>
1074
1075           <secondary>setacl</secondary>
1076
1077           <tertiary>with -negative flag</tertiary>
1078         </indexterm> <indexterm>
1079           <primary>commands</primary>
1080
1081           <secondary>fs setacl</secondary>
1082         </indexterm></para>
1083
1084       <programlisting>
1085    % <emphasis role="bold">fs setacl  -dir</emphasis> &lt;<replaceable>directory</replaceable>&gt;<superscript>+</superscript> <emphasis
1086           role="bold">-acl</emphasis> &lt;<replaceable>access list entries</replaceable>&gt;<superscript>+</superscript>  <emphasis
1087           role="bold">-negative</emphasis>
1088 </programlisting>
1089
1090       <para>where <variablelist>
1091           <varlistentry>
1092             <term><emphasis role="bold">sa</emphasis></term>
1093
1094             <listitem>
1095               <para>Is an acceptable alias for <emphasis role="bold">setacl</emphasis> (and <emphasis role="bold">seta</emphasis> is
1096               the shortest acceptable abbreviation).</para>
1097             </listitem>
1098           </varlistentry>
1099
1100           <varlistentry>
1101             <term><emphasis role="bold">-dir</emphasis></term>
1102
1103             <listitem>
1104               <para>Names one or more directories to which to apply the negative ACL entries defined by the <emphasis
1105               role="bold">-acl</emphasis> argument. For a detailed description of acceptable values, see <link linkend="HDRWQ55">To
1106               Add, Remove, or Edit Normal ACL Permissions</link>.</para>
1107             </listitem>
1108           </varlistentry>
1109
1110           <varlistentry>
1111             <term><emphasis role="bold">-acl</emphasis></term>
1112
1113             <listitem>
1114               <para>Specifies one or more ACL entries, each of which pairs a user or group name and a set of permissions. Separate
1115               the pairs, and the two parts of each pair, with one or more spaces. For a detailed description of acceptable values,
1116               see <link linkend="HDRWQ55">To Add, Remove, or Edit Normal ACL Permissions</link>. Keep in mind that the usual meaning
1117               of each permission is reversed.</para>
1118             </listitem>
1119           </varlistentry>
1120
1121           <varlistentry>
1122             <term><emphasis role="bold">-negative</emphasis></term>
1123
1124             <listitem>
1125               <para>Places the entries defined by the <emphasis role="bold">-acl</emphasis> argument on the negative permissions
1126               section of the ACL for each directory named by the <emphasis role="bold">-dir</emphasis> argument.</para>
1127             </listitem>
1128           </varlistentry>
1129         </variablelist></para>
1130     </sect2>
1131
1132     <sect2 id="Header_102">
1133       <title>Example: Setting an Entry in the Negative Permissions Section</title>
1134
1135       <indexterm>
1136         <primary>examples</primary>
1137
1138         <secondary>creating entry on negative permissions section of ACL</secondary>
1139       </indexterm>
1140
1141       <para>User <emphasis role="bold">terry</emphasis> has granted all access permissions except <emphasis role="bold">a</emphasis>
1142       to the group <emphasis role="bold">terry:team</emphasis> on her <emphasis role="bold">plans</emphasis> subdirectory.</para>
1143
1144       <programlisting>
1145    % <emphasis role="bold">cd /afs/example.com/usr/terry</emphasis>
1146    % <emphasis role="bold">fs listacl plans</emphasis>
1147    Access control list for plans is
1148    Normal rights:
1149       system:anyuser rl
1150       terry:team rlidwk
1151       terry  rlidwka
1152 </programlisting>
1153
1154       <para>However, <emphasis role="bold">terry</emphasis> notices that one of the members of the group, user <emphasis
1155       role="bold">pat</emphasis>, has been making inappropriate changes to files. To prevent this without removing <emphasis
1156       role="bold">pat</emphasis> from the group or changing the permissions for the <emphasis role="bold">terry:team</emphasis>
1157       group, <emphasis role="bold">terry</emphasis> creates an entry on the negative permissions section of the ACL that denies the
1158       <emphasis role="bold">w</emphasis> and <emphasis role="bold">d</emphasis> permissions to <emphasis
1159       role="bold">pat</emphasis>:</para>
1160
1161       <programlisting>
1162    % <emphasis role="bold">fs setacl plans pat wd -negative</emphasis>
1163    % <emphasis role="bold">fs listacl plans</emphasis>
1164    Access control list for plans is
1165    Normal rights:
1166       system:anyuser rl
1167       terry:team rlidwk
1168       terry: rlidwka
1169    Negative rights:
1170       pat wd
1171 </programlisting>
1172     </sect2>
1173
1174     <sect2 id="Header_103">
1175       <title>Example: Restoring Access by Removing an Entry from the Negative Permissions Section</title>
1176
1177       <para>In the previous example, user <emphasis role="bold">terry</emphasis> put <emphasis role="bold">pat</emphasis> on the
1178       negative permissions section of ACL for the <emphasis role="bold">plans</emphasis> subdirectory. But the result has been
1179       inconvenient and <emphasis role="bold">pat</emphasis> has promised not to change files any more. To enable <emphasis
1180       role="bold">pat</emphasis> to exercise all permissions granted to the members of the <emphasis
1181       role="bold">terry:team</emphasis> group, <emphasis role="bold">terry</emphasis> removes the entry for <emphasis
1182       role="bold">pat</emphasis> from the negative permissions section of the ACL.</para>
1183
1184       <programlisting>
1185    % <emphasis role="bold">fs setacl plans pat  none -negative</emphasis>
1186    % <emphasis role="bold">fs listacl plans</emphasis>
1187    Access control list for plans is
1188    Normal rights:
1189       system:anyuser rl
1190       terry:team rlidwk
1191       terry  rlidwka
1192 </programlisting>
1193     </sect2>
1194   </sect1>
1195
1196   <sect1 id="HDRWQ57">
1197     <title>Completely Replacing an ACL</title>
1198
1199     <indexterm>
1200       <primary>ACL</primary>
1201
1202       <secondary>replacing all entries</secondary>
1203     </indexterm>
1204
1205     <indexterm>
1206       <primary>ACL</primary>
1207
1208       <secondary>clearing</secondary>
1209     </indexterm>
1210
1211     <indexterm>
1212       <primary>replacing</primary>
1213
1214       <secondary>all entries on ACL</secondary>
1215     </indexterm>
1216
1217     <indexterm>
1218       <primary>erasing all ACL entries</primary>
1219     </indexterm>
1220
1221     <indexterm>
1222       <primary>clearing all ACL entries</primary>
1223     </indexterm>
1224
1225     <indexterm>
1226       <primary>removing</primary>
1227
1228       <secondary>all ACL entries</secondary>
1229     </indexterm>
1230
1231     <indexterm>
1232       <primary>directories</primary>
1233
1234       <secondary>replacing ACL</secondary>
1235     </indexterm>
1236
1237     <para>It is sometimes simplest to clear an ACL completely before defining new permissions on it, for instance if the mix of
1238     normal and negative permissions makes it difficult to understand how their interaction affects access to the directory. To clear
1239     an ACL completely while you define new entries, include the <emphasis role="bold">-clear</emphasis> flag on the <emphasis
1240     role="bold">fs setacl</emphasis> command. When you include this flag, you can create entries on either the normal permissions or
1241     the negative permissions section of the ACL, but not on both at once.</para>
1242
1243     <para>Remember to create an entry for yourself. As the owner of the directory, you always have the <emphasis
1244     role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) permission required to replace a deleted entry, but the
1245     effects the effects of a missing ACL entry can be confusing enough to make it difficult to realize that the problem is a missing
1246     entry. In particular, the lack of the <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permission
1247     prevents you from using any shorthand notation in pathnames (such as a period for the current working directory or two periods
1248     for the parent directory).</para>
1249
1250     <sect2 id="Header_105">
1251       <title>To Replace an ACL Completely</title>
1252
1253       <para>Issue the <emphasis role="bold">fs setacl</emphasis> command with the <emphasis role="bold">-clear</emphasis> flag to
1254       clear the ACL completely before setting either normal or negative permissions. Because you need to grant the owner of the
1255       directory all permissions, it is better in most cases to set normal permissions at this point. <indexterm>
1256           <primary>fs commands</primary>
1257
1258           <secondary>setacl</secondary>
1259
1260           <tertiary>completely replacing ACL</tertiary>
1261         </indexterm></para>
1262
1263       <programlisting>
1264    % <emphasis role="bold">fs setacl  -dir</emphasis> &lt;<replaceable>directory</replaceable>&gt;<superscript>+</superscript> <emphasis
1265           role="bold">-acl</emphasis> &lt;<replaceable>access list entries</replaceable>&gt;<superscript>+</superscript> <emphasis
1266           role="bold">-clear</emphasis>  [<emphasis role="bold">-negative</emphasis>]
1267 </programlisting>
1268
1269       <para>where <variablelist>
1270           <varlistentry>
1271             <term><emphasis role="bold">sa</emphasis></term>
1272
1273             <listitem>
1274               <para>Is an acceptable alias for <emphasis role="bold">setacl</emphasis> (and <emphasis role="bold">seta</emphasis> is
1275               the shortest acceptable abbreviation).</para>
1276             </listitem>
1277           </varlistentry>
1278
1279           <varlistentry>
1280             <term><emphasis role="bold">-dir</emphasis></term>
1281
1282             <listitem>
1283               <para>Names one or more directories to which to apply the ACL entries defined by the <emphasis
1284               role="bold">-acl</emphasis> argument. For a detailed description of acceptable values, see <link linkend="HDRWQ55">To
1285               Add, Remove, or Edit Normal ACL Permissions</link>.</para>
1286             </listitem>
1287           </varlistentry>
1288
1289           <varlistentry>
1290             <term><emphasis role="bold">-acl</emphasis></term>
1291
1292             <listitem>
1293               <para>Specifies one or more ACL entries, each of which pairs a user or group name and a set of permissions. Separate
1294               the pairs, and the two parts of each pair, with one or more spaces. Remember to grant all permissions to the owner of
1295               the directory. For a detailed description of acceptable values, see <link linkend="HDRWQ55">To Add, Remove, or Edit
1296               Normal ACL Permissions</link>.</para>
1297             </listitem>
1298           </varlistentry>
1299
1300           <varlistentry>
1301             <term><emphasis role="bold">-clear</emphasis></term>
1302
1303             <listitem>
1304               <para>Removes all entries from each ACL before creating the entries indicated by the <emphasis
1305               role="bold">-acl</emphasis> argument.</para>
1306             </listitem>
1307           </varlistentry>
1308
1309           <varlistentry>
1310             <term><emphasis role="bold">-negative</emphasis></term>
1311
1312             <listitem>
1313               <para>Places the entries defined by the <emphasis role="bold">-acl</emphasis> argument on the negative permissions
1314               section of each ACL.</para>
1315             </listitem>
1316           </varlistentry>
1317         </variablelist></para>
1318     </sect2>
1319
1320     <sect2 id="Header_106">
1321       <title>Example: Replacing an ACL</title>
1322
1323       <indexterm>
1324         <primary>examples</primary>
1325
1326         <secondary>replacing an ACL</secondary>
1327       </indexterm>
1328
1329       <para>The following example clears the ACL on the current working directory and creates entries that grant all permissions to
1330       user <emphasis role="bold">terry</emphasis> and all permissions except <emphasis role="bold">a</emphasis> to user <emphasis
1331       role="bold">pat</emphasis>.</para>
1332
1333       <programlisting>
1334    % <emphasis role="bold">fs setacl . terry all pat write -clear</emphasis>
1335    % <emphasis role="bold">fs listacl .</emphasis>
1336    Access control list for . is
1337    Normal rights:
1338      terry rlidwka
1339      pat rlidwk
1340 </programlisting>
1341     </sect2>
1342   </sect1>
1343
1344   <sect1 id="HDRWQ58">
1345     <title>Copying ACLs Between Directories</title>
1346
1347     <indexterm>
1348       <primary>ACL</primary>
1349
1350       <secondary>copying between directories</secondary>
1351     </indexterm>
1352
1353     <indexterm>
1354       <primary>creating</primary>
1355
1356       <secondary>ACL as copy of another</secondary>
1357     </indexterm>
1358
1359     <indexterm>
1360       <primary>copying</primary>
1361
1362       <secondary>ACL between directories</secondary>
1363     </indexterm>
1364
1365     <indexterm>
1366       <primary>directories</primary>
1367
1368       <secondary>copying ACLs between</secondary>
1369     </indexterm>
1370
1371     <para>The <emphasis role="bold">fs copyacl</emphasis> command copies a source directory's ACL to one or more destination
1372     directories. It does not affect the source ACL at all, but changes each destination ACL as follows: <itemizedlist>
1373         <listitem>
1374           <para>If an entry on the source ACL does not exist on the destination ACL, the command copies it to the destination
1375           ACL.</para>
1376         </listitem>
1377
1378         <listitem>
1379           <para>If an entry on the destination ACL does not also exist on the source ACL, the command does not remove it unless you
1380           include the <emphasis role="bold">-clear</emphasis> flag, which overwrites the destination ACL completely.</para>
1381         </listitem>
1382
1383         <listitem>
1384           <para>If an entry is on both ACLs, the command changes the destination ACL entry to match the source ACL entry.</para>
1385         </listitem>
1386       </itemizedlist></para>
1387
1388     <para>To copy an ACL, you must have the <emphasis role="bold">l</emphasis> permission on the source ACL and the <emphasis
1389     role="bold">a</emphasis> permission on each destination ACL. If you identify the source directory by naming a file in it, you
1390     must also have the <emphasis role="bold">r</emphasis> permission on the source ACL. To display the permissions you have on the
1391     two directories, use the <emphasis role="bold">fs listacl</emphasis> command as described in <link linkend="HDRWQ52">Displaying
1392     an ACL</link>.</para>
1393
1394     <para><emphasis role="bold">Note for AFS/DFS Migration Toolkit users:</emphasis> If the machine on which you issue the <emphasis
1395     role="bold">fs copyacl</emphasis> command is configured for access to a DCE cell's DFS filespace via the AFS/DFS Migration
1396     Toolkit, you can use the command to copy ACLs between DFS files and directories also. The command includes <emphasis
1397     role="bold">-id</emphasis> and <emphasis role="bold">-if</emphasis> flags for altering a DFS directory's Initial Container and
1398     Initial Object ACLs as well as its regular ACL; for details, ask your system administrator. You cannot copy ACLs between AFS and
1399     DFS directories, because they use different ACL formats. The <emphasis role="bold">fs</emphasis> command interpreter ignores the
1400     <emphasis role="bold">-id</emphasis> and <emphasis role="bold">-if</emphasis> flags if you include them when copying AFS
1401     ACLs.</para>
1402
1403     <sect2 id="Header_108">
1404       <title>To Copy an ACL Between Directories</title>
1405
1406       <indexterm>
1407         <primary>commands</primary>
1408
1409         <secondary>fs copyacl</secondary>
1410       </indexterm>
1411
1412       <indexterm>
1413         <primary>fs commands</primary>
1414
1415         <secondary>copyacl</secondary>
1416       </indexterm>
1417
1418       <para>Issue the <emphasis role="bold">fs copyacl</emphasis> command to copy a source ACL to the ACL on one or more destination
1419       directories.</para>
1420
1421       <programlisting>
1422    % <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>  \
1423                 [<emphasis role="bold">-clear</emphasis>]
1424 </programlisting>
1425
1426       <para>where <variablelist>
1427           <varlistentry>
1428             <term><emphasis role="bold">co</emphasis></term>
1429
1430             <listitem>
1431               <para>Is the shortest acceptable abbreviation for <emphasis role="bold">copyacl</emphasis>.</para>
1432             </listitem>
1433           </varlistentry>
1434
1435           <varlistentry>
1436             <term><emphasis role="bold">-fromdir</emphasis></term>
1437
1438             <listitem>
1439               <para>Names the source directory from which to copy the ACL. Partial pathnames are interpreted relative to the current
1440               working directory. If this argument names a file, the ACL is copied from its directory.</para>
1441             </listitem>
1442           </varlistentry>
1443
1444           <varlistentry>
1445             <term><emphasis role="bold">-todir</emphasis></term>
1446
1447             <listitem>
1448               <para>Names each destination directory to which to copy the source ACL. Partial pathnames are interpreted relative to
1449               the current working directory. Filenames are not acceptable.</para>
1450             </listitem>
1451           </varlistentry>
1452
1453           <varlistentry>
1454             <term><emphasis role="bold">-clear</emphasis></term>
1455
1456             <listitem>
1457               <para>Completely overwrites each destination directory's ACL with the source ACL.</para>
1458             </listitem>
1459           </varlistentry>
1460         </variablelist></para>
1461     </sect2>
1462
1463     <sect2 id="Header_109">
1464       <title>Example: Copying an ACL from One Directory to Another</title>
1465
1466       <indexterm>
1467         <primary>examples</primary>
1468
1469         <secondary>copying ACL between directories</secondary>
1470       </indexterm>
1471
1472       <para>In this example, user <emphasis role="bold">terry</emphasis> copies the ACL from her home directory (the current working
1473       directory) to its <emphasis role="bold">plans</emphasis> subdirectory. She begins by displaying both ACLs.</para>
1474
1475       <programlisting>
1476    % <emphasis role="bold">fs listacl . plans</emphasis>
1477    Access list for . is
1478    Normal rights:
1479       terry rlidwka
1480       pat rlidwk
1481       jones rl
1482    Access list for plans is
1483    Normal rights:
1484       terry rlidwka
1485       pat rl
1486       smith rl
1487
1488   % <emphasis role="bold">fs copyacl -from . -to plans</emphasis>
1489
1490    % <emphasis role="bold">fs listacl . plans</emphasis>
1491    Access list for . is
1492    Normal rights:
1493       terry rlidwka
1494       pat rlidwk
1495       jones rl
1496    Access list for plans is
1497    Normal rights:
1498       terry rlidwka
1499       pat rlidwk
1500       jones rl
1501       smith rl
1502 </programlisting>
1503     </sect2>
1504   </sect1>
1505
1506   <sect1 id="HDRWQ59">
1507     <title>How AFS Uses the UNIX Mode Bits</title>
1508
1509     <indexterm>
1510       <primary>UNIX, differences with AFS</primary>
1511
1512       <secondary>mode bits, interpretation</secondary>
1513     </indexterm>
1514
1515     <indexterm>
1516       <primary>mode bits (UNIX)</primary>
1517
1518       <secondary>interpretation in AFS</secondary>
1519     </indexterm>
1520
1521     <para>Although AFS protects data primarily with ACLs rather than mode bits, it does not ignore the mode bits entirely. An
1522     explanation of how mode bits work in the UNIX file system is outside the scope of this document, and the following discussion
1523     assumes you understand them; if necessary, see your UNIX documentation. Also, the following discussion does not cover the
1524     setuid, setgid or sticky bits. If you need to understand how those bits work on AFS files, see the <emphasis>OpenAFS
1525     Administration Guide</emphasis> or ask your system administrator.</para>
1526
1527     <para>AFS uses the UNIX mode bits in the following way:</para>
1528
1529     <itemizedlist>
1530       <listitem>
1531         <para>It uses the initial bit to distinguish files and directories. This is the bit that appears first in the output from
1532         the <emphasis role="bold">ls -l</emphasis> command and shows the hyphen (<computeroutput>-</computeroutput>) for a file or
1533         the letter <computeroutput>d</computeroutput> for a directory.</para>
1534       </listitem>
1535
1536       <listitem>
1537         <para>It does not use any of the mode bits on a directory. The AFS ACL alone controls directory access.</para>
1538       </listitem>
1539
1540       <listitem>
1541         <para>For a file, the owner (first) set of bits interacts with the ACL entries that apply to the file in the following way.
1542         AFS does not use the group or world (second and third sets) of mode bits at all. <itemizedlist>
1543             <listitem>
1544               <para>If the first <emphasis role="bold">r</emphasis> mode bit is not set, no one (including the owner) can read the
1545               file, no matter what permissions they have on the ACL. If the bit is set, users also need the <emphasis
1546               role="bold">r</emphasis> and <emphasis role="bold">l</emphasis> permissions on the ACL of the file's directory to read
1547               the file.</para>
1548             </listitem>
1549
1550             <listitem>
1551               <para>If the first <emphasis role="bold">w</emphasis> mode bit is not set, no one (including the owner) can modify the
1552               file. If the <emphasis role="bold">w</emphasis> bit is set, users also need the <emphasis role="bold">w</emphasis> and
1553               <emphasis role="bold">l</emphasis> permissions on the ACL of the file's directory to modify the file.</para>
1554             </listitem>
1555
1556             <listitem>
1557               <para>There is no ACL permission directly corresponding to the <emphasis role="bold">x</emphasis> mode bit, but to
1558               execute a file stored in AFS, the user must also have the <emphasis role="bold">r</emphasis> and <emphasis
1559               role="bold">l</emphasis> permissions on the ACL of the file's directory.</para>
1560             </listitem>
1561           </itemizedlist></para>
1562       </listitem>
1563     </itemizedlist>
1564
1565     <para>When you issue the UNIX <emphasis role="bold">chmod</emphasis> command on an AFS file or directory, AFS changes the bits
1566     appropriately. To change a file's mode bits, you must have the AFS <emphasis role="bold">w</emphasis> permission on the ACL of
1567     the file's directory. To change a directory's mode bits, you must have the <emphasis role="bold">d</emphasis>, <emphasis
1568     role="bold">i</emphasis>, and <emphasis role="bold">l</emphasis> permissions on its ACL. <indexterm>
1569         <primary>commands</primary>
1570
1571         <secondary>chmod</secondary>
1572       </indexterm> <indexterm>
1573         <primary>chmod command</primary>
1574       </indexterm></para>
1575
1576     <sect2 id="Header_111">
1577       <title>Example: Disabling Write Access for a File</title>
1578
1579       <para><indexterm>
1580           <primary>examples</primary>
1581
1582           <secondary>using chmod</secondary>
1583         </indexterm></para>
1584
1585       <para>Suppose <emphasis role="bold">terry</emphasis> is chairing a committee that is writing a proposal. As each section is
1586       approved, she turns off write access to that file to prevent further changes. For example, the following <emphasis
1587       role="bold">chmod</emphasis> command turns off the <emphasis role="bold">w</emphasis> mode bits on the file <emphasis
1588       role="bold">proposal.chap2</emphasis>. This makes it impossible for anyone to change the file, no matter what permissions are
1589       granted on the directory ACL.</para>
1590
1591       <programlisting>
1592    % <emphasis role="bold">chmod -w proposal.chap2</emphasis>
1593    % <emphasis role="bold">ls -l</emphasis>
1594    -rw-r--r--  1 terry     573 Nov 10 09:57 conclusion
1595    -r--r--r--  1 terry     573 Nov 15 10:34 intro
1596    -r--r--r--  1 terry     573 Dec  1 15:07 proposal.chap2
1597    -rw-r--r--  1 terry     573 Nov 10 09:57 proposal.chap3
1598    -rw-r--r--  1 terry     573 Nov 10 09:57 proposal.chap4
1599 </programlisting>
1600     </sect2>
1601   </sect1>
1602 </chapter>