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