=head1 NAME

fs setacl - Sets the ACL for a directory

=head1 SYNOPSIS

fs setacl B<-dir> I<directory> [I<directory> ...]  B<-acl> I<access list entries> [I<access list entries> ...]
[B<-clear>]  [B<-negative>]  [B<-id>]  [B<-if>]  [B<-help>]

fs sa B<-d> I<directory> [I<directory> ...]  B<-a> I<access list entries> [I<access list entries> ...]
[B<-c>]  [B<-n>]  [B<-id>]  [B<-if>]  [B<-h>]

fs seta B<-d> I<directory> [I<directory> ...]  B<-a> I<access list entries> [I<access list entries> ...]
[B<-c>]  [B<-n>]  [B<-id>]  [B<-if>]  [B<-h>]

=head1 DESCRIPTION

The C<fs setacl> 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
B<mask_obj>, however. For more details, refer to the IBM AFS/DFS
Migration Toolkit Administration Guide and Reference.

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 Negative
rights section of the ACL (deny rights to specified users or groups),
provide the B<-negative> flag.

To display an ACL, use the C<fs listacl> command. To copy an ACL from one
directory to another, use the C<fs copyacl> command.

=head1 OPTIONS

=over 4

=item B<-dir> I<directory> [I<directory> ...]

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, B</afs/.abc.com>). For
further discussion of the concept of read/write and read-only
paths through the filespace, see the L<fs_mkmount(1)> reference page.

=item B<-acl> I<access list entries> [I<access list entries> ...]

Defines a list of one or more ACL entries, each a pair that
names

=over

=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

=item B<a>

(B<administer>): change the entries on the ACL

=item B<d>

(B<delete>): remove files and subdirectories from the
directory or move them to other directories

=item B<i>

(B<insert>): add files or subdirectories to the directory by
copying, moving or creating

=item B<k>

(B<lock>): set read locks or write locks on the files in the
directory

=item B<l>

(B<lookup>): list the files and subdirectories in the
directory, stat the directory itself, and issue the C<fs
listacl> command to examine the directory's ACL

=item B<r>

(B<read>): read the contents of files in the directory;
issue the C<ls -l> command to stat the elements in the
directory

=item B<w>

(B<write>): modify the contents of files in the directory,
and issue the UNIX C<chmod> command to change their mode
bits

=item B<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 B<all>

Equals all seven permissions (B<rlidwka>).

=item B<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 B<read>

Equals the B<r> (B<read>) and B<l> (B<lookup>) permissions.

=item B<write>

Equals all permissions except B<a> (B<administer>), that is,
B<rlidwk>.

=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 IBM AFS/DFS Migration Toolkit Administration
Guide and Reference.

=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<Negative rights> section
of each ACL, explicitly denying the rights to the user or
group, even if entries on the accompanying C<Normal rights>
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<Normal rights> section of
the current working directory's ACL: the first entry grants B<r> (B<read>)
and B<l> (B<lookup>) permissions to the group B<pat:friends>, while the other
(using the B<write> shorthand) gives all permissions except B<a>
(B<administer>) to the user B<smith>.

    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 C<fs listacl> command) from
the current working directory's B<reports> 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 public 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 B<a> (B<administer>) permission on the directory's
ACL; the directory's owner and the members of the
B<system:administrators> group have the right implicitly, even if it does
not appear on the ACL.

=head1 CAVEATS

If the ACL already grants certain permissions to a user or group, the
permissions specified with the C<fs setacl> 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 Normal rights
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 B<system:anyuser> group on the same ACL; the
user needs only to issue the C<unlog> 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 B<l> (B<lookup>)
permission. Without that permission, it is impossible to resolve the
"dot" ( . ) and "dot dot" ( .. ) shorthand from within the directory.
(The directory's owner does implicitly have the B<a> [B<administer>]
permission even on a cleared ACL, but must know to use it to add other
permissions.)

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.

=head1 SEE ALSO

L<fs_copyacl(1)>,
L<fs_listacl(1)>,
L<fs_mkmount(1)>,
IBM_AFS/DFS_Migration Toolkit_Administration Guide_and Reference

=cut
