=head1 NAME
-fs setacl - Sets the ACL for a directory
+fs_setacl - Sets the ACL for a directory
=head1 SYNOPSIS
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;
=item *
One or more ACL permissions, indicated either by combining the individual
-letters or by one of the four acceptable shorthand words.
+letters or by one of the four acceptable shorthand words, optionally
+followed by a single plus (+) or minus (-) chracter to request a relative
+ACL change
=back
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>
=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
pat rlidwka
pat:friends rli
+The following example demonstrates the use of the + and - options to
+modfiy ACLs relative to the existing set
+
+ % fs setacl dir . -acl pat:friends r-
+ % fs listacl -path .
+ Access list for . is
+ Normal rights:
+ pat rlidwka
+ pat:friends li
+ % fs setacl dir . acl pat:friends w+
+ % fs listacl -path .
+ Access list for . is
+ Normal rights:
+ pat rlidwka
+ pat:friends wli
+
=head1 PRIVILEGE REQUIRED
The issuer must have the C<a> (administer) permission on the directory's
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.