afs.h: fix out of tree build failures
[openafs.git] / doc / xml / UserGuide / auusg007.xml
index d9adfbf..6c47f2c 100644 (file)
             <term><emphasis role="bold">The a (administer) permission</emphasis></term>
 
             <listitem>
-              <para>This permission enables a user to change the directory's ACL. Members of the <emphasis
-              role="bold">system:administrators</emphasis> group implicitly have this permission on every directory (that is, even
-              if that group does not appear on the ACL). Similarly, the owner of a directory implicitly has this permission on its
-              ACL and those of all directories below it. <indexterm>
+              <para>This permission enables a user to change the directory's ACL. Members of the
+                  <emphasis role="bold">system:administrators</emphasis> group implicitly have this
+                permission on every directory (that is, even if that group does not appear on the
+                ACL). Similarly, the owner of a volume root directory implicitly has this permission
+                on its ACL and those of all directories within the volume. <indexterm>
                   <primary>administer ACL permission</primary>
-                </indexterm> <indexterm>
+                </indexterm><indexterm>
+                  <primary>implicit ACL permissions</primary>
+                </indexterm>
+                <indexterm>
                   <primary>a ACL permission</primary>
                 </indexterm></para>
             </listitem>
       the ACLs on DFS directories and files that you own. However, DFS uses a slightly different set of permissions and a different
       syntax for ACL entries. See the DFS documentation or ask your system administrator.</para>
     </sect2>
+
+    <sect2>
+      <title>Dropbox Permissions</title>
+
+      <para>If a user or group is granted the <emphasis
+      role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) and
+      <emphasis role="bold">i</emphasis> (<emphasis
+      role="bold">insert</emphasis>) permissions, but not the <emphasis
+      role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) and/or
+      <emphasis role="bold">w</emphasis> (<emphasis
+      role="bold">write</emphasis>) permissions, this is commonly referred to
+      as a "dropbox" for that user or group. What this means is that that user
+      or group may deposit files in the directory, but they may not read or
+      modify their file later, nor any other file in the directory.</para>
+
+      <para>Know, however, that some of these restrictions are enforced on the
+      client and not on the fileserver, and so should not be relied on for
+      security. In particular, the fileserver does not know when a file is
+      opened or closed on the client, and and so read and write permissions are
+      granted to any user with "dropbox" permissions that owns the accessed
+      file.</para>
+
+      <para>Additionally, granting "dropbox" permissons to <emphasis
+      role="bold">system:anyuser</emphasis> raises additional problems, if you
+      want the dropbox to work for unauthenticated users. Any file deposited by
+      an unauthenticated user will be owned by the unauthenticated user ID, and
+      so would be readable and modifiable by anyone. In order to try and
+      prevent accidentally revealing private information, the fileserver does
+      not grant the implicit read permission to unauthenticated users, even if
+      they have dropbox permissions. This may cause depositing files as an
+      unauthenticated user to arbitrarily fail, and so you should not depend on
+      granting dropbox permissions to unauthenticated users to work
+      reliably.</para>
+    </sect2>
   </sect1>
 
   <sect1 id="HDRWQ50">
         <secondary>displaying ACL for single directory</secondary>
       </indexterm>
 
-      <para>The following example displays the ACL on user <emphasis role="bold">terry</emphasis>'s home directory in the ABC
+      <para>The following example displays the ACL on user <emphasis role="bold">terry</emphasis>'s home directory in the Example
       Corporation cell:</para>
 
       <programlisting>
-   % <emphasis role="bold">fs la /afs/abc.com/usr/terry</emphasis>
-   Access list for /afs/abc.com/usr/terry is
+   % <emphasis role="bold">fs la /afs/example.com/usr/terry</emphasis>
+   Access list for /afs/example.com/usr/terry is
    Normal rights:
       system:authuser rl
       pat rlw
       <emphasis role="bold">plans</emphasis>.</para>
 
       <programlisting>
-   % <emphasis role="bold">fs listacl  .  /afs/abc.com/usr/pat  ../plans</emphasis>
+   % <emphasis role="bold">fs listacl  .  /afs/example.com/usr/pat  ../plans</emphasis>
    Access list for . is
    Normal rights:
       system:anyuser rl
       pat:dept rliw
-   Access list for /afs/abc.com/usr/pat is
+   Access list for /afs/example.com/usr/pat is
    Normal rights:
       system:anyuser rl
       pat rlidwka
-      terry rliw 
+      terry rliw
    Access list for ../plans is
    Normal rights:
       terry rlidwka
 
               <para>If you specify only one directory (or file) name, you can omit the <emphasis role="bold">-dir</emphasis> and
               <emphasis role="bold">-acl</emphasis> switches. For more on omitting switches, see <link linkend="HDRWQ86">Appendix B,
-              AFS Command Syntax and Online Help</link>.</para>
+              OpenAFS Command Syntax and Online Help</link>.</para>
             </listitem>
           </varlistentry>
 
 
       <programlisting>
    % <emphasis role="bold">fs sa notes pat rl</emphasis>
-   % <emphasis role="bold">fs sa pat read</emphasis>
+   % <emphasis role="bold">fs sa notes pat read</emphasis>
 </programlisting>
     </sect2>
 
       <programlisting>
    % <emphasis role="bold">fs setacl  -dir</emphasis> &lt;<replaceable>directory</replaceable>&gt;<superscript>+</superscript> <emphasis
           role="bold">-acl</emphasis> &lt;<replaceable>access list entries</replaceable>&gt;<superscript>+</superscript>  <emphasis
-          role="bold">-negative</emphasis> 
+          role="bold">-negative</emphasis>
 </programlisting>
 
       <para>where <variablelist>
       to the group <emphasis role="bold">terry:team</emphasis> on her <emphasis role="bold">plans</emphasis> subdirectory.</para>
 
       <programlisting>
-   % <emphasis role="bold">cd /afs/abc.com/usr/terry</emphasis>
+   % <emphasis role="bold">cd /afs/example.com/usr/terry</emphasis>
    % <emphasis role="bold">fs listacl plans</emphasis>
    Access control list for plans is
    Normal rights:
    Normal rights:
       terry rlidwka
       pat rl
-      smith rl   
-     
+      smith rl
+
   % <emphasis role="bold">fs copyacl -from . -to plans</emphasis>
-   
+
    % <emphasis role="bold">fs listacl . plans</emphasis>
    Access list for . is
    Normal rights:
       terry rlidwka
       pat rlidwk
       jones rl
-      smith rl   
+      smith rl
 </programlisting>
     </sect2>
   </sect1>
     <para>Although AFS protects data primarily with ACLs rather than mode bits, it does not ignore the mode bits entirely. An
     explanation of how mode bits work in the UNIX file system is outside the scope of this document, and the following discussion
     assumes you understand them; if necessary, see your UNIX documentation. Also, the following discussion does not cover the
-    setuid, setgid or sticky bits. If you need to understand how those bits work on AFS files, see the <emphasis>IBM AFS
+    setuid, setgid or sticky bits. If you need to understand how those bits work on AFS files, see the <emphasis>OpenAFS
     Administration Guide</emphasis> or ask your system administrator.</para>
 
     <para>AFS uses the UNIX mode bits in the following way:</para>
 </programlisting>
     </sect2>
   </sect1>
-</chapter>
\ No newline at end of file
+</chapter>