=head1 NAME fs setacl - Sets the ACL for a directory =head1 SYNOPSIS =for html
B S<<< B<-dir> >+ >>> S<<< B<-acl> >+ >>> [B<-clear>] [B<-negative>] [B<-id>] [B<-if>] [B<-help>] B S<<< B<-d> >+ >>> S<<< B<-a> >+ >>> [B<-c>] [B<-n>] [B<-id>] [B<-if>] [B<-h>] B S<<< B<-d> >+ >>> S<<< B<-a> >+ >>> [B<-c>] [B<-n>] [B<-id>] [B<-if>] [B<-h>] =for html
=head1 DESCRIPTION The B command adds the access control list (ACL) entries specified with the B<-acl> argument to the ACL of each directory named by 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, however. For more details, refer to the I. Only user and group entries are acceptable values for the B<-acl> argument. Do not place machine entries (IP addresses) directly on an ACL; instead, make the machine entry a group member and place the group on the ACL. To completely erase the existing ACL before adding the new entries, provide the B<-clear> flag. To add the specified entries to the C section of the ACL (deny rights to specified users or groups), provide the B<-negative> flag. To display an ACL, use the fs listacl command. To copy an ACL from one directory to another, use the B command. =head1 CAUTIONS If the ACL already grants certain permissions to a user or group, the permissions specified with the B command replace the existing permissions, rather than being added to them. Setting negative permissions is generally unnecessary and not recommended. Simply omitting a user or group from the C section of the ACL is normally adequate to prevent access. In particular, note that it is futile to deny permissions that are granted to members of the system:anyuser group on the same ACL; the user needs only to issue the B command to receive the denied permissions. When including the B<-clear> option, be sure to reinstate an entry for each directory's owner that includes at least the C (lookup) permission. Without that permission, it is impossible to resolve the "dot" (C<.>) and "dot dot" (C<..>) shorthand from within the directory. (The directory's owner does implicitly have the C (administer) permission even on a cleared ACL, but must know to use it to add other permissions.) =head1 OPTIONS =over 4 =item B<-dir> >+ Names each AFS directory, or DFS directory or file, for which the set the ACL. Partial pathnames are interpreted relative to the current working directory. Specify the read/write path to each directory (or DFS file), to avoid the failure that results from attempting to change a read-only volume. By convention, the read/write path is indicated by placing a period before the cell name at the pathname's second level (for example, F). For further discussion of the concept of read/write and read-only paths through the filespace, see the B reference page. =item B<-acl> >+ Defines a list of one or more ACL entries, each a pair that names: =over 4 =item * A user name or group name as listed in the Protection Database. =item * One or more ACL permissions, indicated either by combining the individual letters or by one of the four acceptable shorthand words. =back in that order, separated by a space (thus every instance of this argument has two parts). The accepted AFS abbreviations and shorthand words, and the meaning of each, are as follows: =over 4 =item a (administer) Change the entries on the ACL. =item d (delete) Remove files and subdirectories from the directory or move them to other directories. =item i (insert) Add files or subdirectories to the directory by copying, moving or creating. =item k (lock) Set read locks or write locks on the files in the directory. =item l (lookup) List the files and subdirectories in the directory, stat the directory itself, and issue the B command to examine the directory's ACL. =item r (read) Read the contents of files in the directory; issue the C command to stat the elements in the directory. =item w (write) Modify the contents of files in the directory, and issue the UNIX B command to change their mode bits. =item A, B, C, D, E, F, G, H Have no default meaning to the AFS server processes, but are made available for applications to use in controlling access to the directory's contents in additional ways. The letters must be uppercase. =item all Equals all seven permissions (C). =item none No permissions. Removes the user/group from the ACL, but does not guarantee they have no permissions if they belong to groups that remain on the ACL. =item read Equals the C (read) and C (lookup) permissions. =item write Equals all permissions except C (administer), that is, C. =back 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. =item B<-clear> Removes all existing entries on each ACL before adding the entries specified with the B<-acl> argument. =item B<-negative> Places the specified ACL entries in the C section of each ACL, explicitly denying the rights to the user or group, even if entries on the accompanying C section of the ACL grant them permissions. This argument is not supported for DFS files or directories, because DFS does not implement negative ACL permissions. =item B<-id> Places the ACL entries on the Initial Container ACL of each DFS directory, which are the only file system objects for which this flag is supported. =item B<-if> Places the ACL entries on the Initial Object ACL of each DFS directory, which are the only file system objects for which this flag is supported. =item B<-help> Prints the online help for this command. All other valid options are ignored. =back =head1 EXAMPLES The following example adds two entries to the C section of the current working directory's ACL: the first entry grants C (read) and C (lookup) permissions to the group pat:friends, while the other (using the C shorthand) gives all permissions except C (administer) to the user C. % fs setacl -dir . -acl pat:friends rl smith write % fs listacl -path . Access list for . is Normal rights: pat:friends rl smith rlidwk The following example includes the B<-clear> flag, which removes the existing permissions (as displayed with the B command) from the current working directory's F subdirectory and replaces them with a new set. % fs listacl -dir reports Access list for reports is Normal rights: system:authuser rl pat:friends rlid smith rlidwk pat rlidwka Negative rights: terry rl % fs setacl -clear -dir reports -acl pat all smith write system:anyuser rl % fs listacl -dir reports Access list for reports is Normal rights: system:anyuser rl smith rlidwk pat rlidwka The following example use the B<-dir> and B<-acl> switches because it sets the ACL for more than one directory (both the current working directory and its F subdirectory). % fs setacl -dir . public -acl pat:friends rli % fs listacl -path . public Access list for . is Normal rights: pat rlidwka pat:friends rli Access list for public is Normal rights: pat rlidwka pat:friends rli =head1 PRIVILEGE REQUIRED The issuer must have the C (administer) permission on the directory's ACL, a member of the system:administrators group, or, as a special case, must be the UID owner of the top-level directory of the volume containing this directory. The last provision allows the UID owner of a volume to repair accidental ACL errors without requiring intervention by a member of system:administrators. Earlier versions of OpenAFS also extended implicit administer permission to the owner of any directory. In current versions of OpenAFS, only the owner of the top-level directory of the volume has this special permission. =head1 SEE ALSO L, L, L I =head1 COPYRIGHT IBM Corporation 2000. All Rights Reserved. This documentation is covered by the IBM Public License Version 1.0. It was converted from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.