Import Upstream version 1.8.5

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

=head1 NAME

fs_setacl - Sets the ACL for a directory

=head1 SYNOPSIS

=for html
<div class="synopsis">

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

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

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

=for html
</div>

=head1 DESCRIPTION

The B<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
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;
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<Negative
rights> 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<fs copyacl> command.

=head1 CAUTIONS

If the ACL already grants certain permissions to a user or group, the
permissions specified with the B<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 C<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 system:anyuser group on the same ACL; the user needs only to issue the
B<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 C<l> (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<a> (administer) permission
even on a cleared ACL, but must know to use it to add other permissions.)

=head1 OPTIONS

=over 4

=item B<-dir> <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,
F</afs/.example.com>). For further discussion of the concept of read/write and
read-only paths through the filespace, see the B<fs mkmount> reference
page.

=item B<-acl> <I<access list entries>>+

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, optionally
followed by a single plus (+) or minus (-) chracter to request a relative
ACL change

=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<fs listacl> command to examine the directory's
ACL.

=item r (read)

Read the contents of files in the directory; issue the C<ls -l> command to
stat the elements in the directory.

=item w (write)

Modify the contents of files in the directory, and issue the UNIX B<chmod>
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<rlidwka>).

=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<r> (read) and C<l> (lookup) permissions.

=item write

Equals all permissions except C<a> (administer), that is, C<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.

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>

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 DROPBOXES

If an accessing user has the C<l> (lookup) 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
the current working directory's ACL: the first entry grants C<r> (read)
and C<l> (lookup) permissions to the group pat:friends, while the other
(using the C<write> shorthand) gives all permissions except C<a>
(administer) to the user C<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 B<fs listacl> command) from
the current working directory's F<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 F<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

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
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<fs_copyacl(1)>,
L<fs_listacl(1)>,
L<fs_mkmount(1)>

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> 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.