Document dropbox permissions

[openafs.git] / doc / man-pages / pod1 / fs_setacl.pod

diff --git a/doc/man-pages/pod1/fs_setacl.pod b/doc/man-pages/pod1/fs_setacl.pod
index ec43702..cbe0e4d 100644 (file)
--- a/doc/man-pages/pod1/fs_setacl.pod
+++ b/doc/man-pages/pod1/fs_setacl.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-fs setacl - Sets the ACL for a directory
+fs_setacl - Sets the ACL for a directory
 
 =head1 SYNOPSIS
 
@@ -28,8 +28,7 @@ the B<-dir> argument.
 If the B<-dir> argument designates a pathname in DFS filespace (accessed
 via the AFS/DFS Migration Toolkit Protocol Translator), it can be a file
 as well as a directory. The ACL must already include an entry for
-C<mask_obj>, however. For more details, refer to the I<IBM AFS/DFS
-Migration Toolkit Administration Guide and Reference>.
+C<mask_obj>, however.
 
 Only user and group entries are acceptable values for the B<-acl>
 argument. Do not place machine entries (IP addresses) directly on an ACL;
@@ -169,8 +168,13 @@ It is acceptable to mix entries that combine the individual letters with
 entries that use the shorthand words, but not use both types of notation
 within an individual pairing of user or group and permissions.
 
-To learn the proper format and acceptable values for DFS ACL entries, see
-the I<IBM AFS/DFS Migration Toolkit Administration Guide and Reference>.
+Granting the C<l> (lookup) and C<i> (insert) permissions without
+granting the C<w> (write) and/or C<r> (read) permissions is a special
+case, and grants rights approrpriate for "dropbox" directories. See the
+L<DROPBOXES> section for details.
+
+If setting ACLs on a pathname in DFS filespace, see the DFS documentation
+for the proper format and acceptable values for DFS ACL entries.
 
 =item B<-clear>
 
@@ -204,6 +208,38 @@ ignored.
 
 =back
 
+=head1 DROPBOXES
+
+If an accessing user has the C<l> (read) and C<i> (insert) permissions
+on a directory, but not the C<w> (write) and/or C<r> (read) permissions,
+the user is implicitly granted the ability to write and/or read any file
+they create in that directory, until they close the file. This is to
+allow "dropbox"-style directories to exist, where users can deposit
+files, but cannot modify them later nor can they modify or read any
+files deposited in the directory by other users.
+
+Note, however, that the dropbox functionality is not perfect. The
+fileserver does not have knowledge of when a file is opened or closed on
+the client, and so the fileserver always allows an accessing user to
+read or write to a file in a "dropbox" directory if they own the file.
+While the client prevents the user from reading or modifying their
+deposited file later, this is not enforced on the fileserver, and so
+should not be relied on for security.
+
+Additionally, if "dropbox" permissions are granted to C<system:anyuser>,
+unauthenticated users may deposit files in the directory. If an
+unauthenticated user deposits a file in the directory, the new file will
+be owned by the unauthenticated user ID, and is thus potentially
+modifiable by anyone.
+
+In an effort to try and reduce accidentally publicizing private data, the
+fileserver may refuse read requests for "dropbox" files from unauthenticated
+users. As a result, depositing files as an unauthenticated user may arbitrarily
+fail if C<system:anyuser> has been granted dropbox permissions. While this
+should be rare, it is not completely preventable, and so for this reason
+relying on unauthenticated users to be able to deposit files in a dropbox is
+B<NOT RECOMMENDED>.
+
 =head1 EXAMPLES
 
 The following example adds two entries to the C<Normal rights> section of
@@ -280,8 +316,6 @@ L<fs_copyacl(1)>,
 L<fs_listacl(1)>,
 L<fs_mkmount(1)>
 
-I<IBM AFS/DFS Migration Toolkit Administration Guide and Reference>
-
 =head1 COPYRIGHT
 
 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.