NAME

fs_setacl - Sets the ACL for a file or directory

SYNOPSIS

fs setacl -path <path>+ -acl <access list entries>+ [-clear] [-negative] [-help]

DESCRIPTION

The fs setacl command (alias fs sa adds the access control list (ACL) entries specified with the -acl argument to the ACL of each directory or file named by the -path argument.

Only user and group entries are acceptable values for the -acl argument. Do not place IP address entries 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 -clear flag. To add the specified entries to the Negative rights section of the ACL (deny rights to specified users or groups), provide the -negative flag.

To display an ACL, use the fs_listacl(1) command. To copy an ACL from one file or directory to another, use the fs_copyacl(1) command.

If the target object is a file that currently inherits its parent's ACL, a file specific ACL will be set and it will no longer inherit from its parent. A file can be returned to the inheriting state by clearing the file specific ACL with the fs_removeacl(1) command.

If the volume containing the object has a maximum ACL set, it will limit the permissions that can be granted. Access to the object will also need to statisfy the volume maximum ACL. Volume maximum ACLs can be adjusted by members of the system:administrators group via use of the vos_setmaxacl(1) command.

CAUTIONS

If the ACL already grants certain permissions to a user or group, the permissions specified with the 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 the anonymous identity or members of the system:anyuser group on the same ACL; the user need only issue the unlog(1) command to receive the denied permissions.

When including the -clear option, be sure to reinstate an entry for each directory's owner that includes at least the l (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 a (administer) permission even on a cleared ACL, but must know to use it to add other permissions.)

OPTIONS

-path <dir/file path>+

Names each AFS file or directory to run the command on. Partial pathnames are interpreted relative to the current working directory, which is also the default value if this argument is omitted.

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

-acl <access list entries>+

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

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:

a (administer)

Change the entries on the ACL.

d (delete)

Remove files and subdirectories from the directory or move them to other directories.

i (insert)

Add files or subdirectories to the directory by copying, moving or creating.

k (lock)

Set read locks or write locks on the files in the directory.

l (lookup)

List the files and subdirectories in the directory, stat the directory itself, and issue the fs listacl command to examine the directory's ACL.

r (read)

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

w (write)

Modify the contents of files in the directory, and issue the UNIX chmod command to change their mode bits.

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.

all

Equals all seven permissions (rlidwka).

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.

read

Equals the r (read) and l (lookup) permissions.

write

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

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 l (lookup) and i (insert) permissions without granting the w (write) and/or r (read) permissions is a special case, and grants rights approrpriate for "dropbox" directories. See the DROPBOXES section for details.

-clear

Removes all existing entries on each ACL before adding the entries specified with the -acl argument.

-negative

Places the specified ACL entries in the Negative rights section of each ACL, explicitly denying the rights to the user or group, even if entries on the accompanying Normal rights section of the ACL grant them permissions.

-help

Prints the online help for this command. All other valid options are ignored.

EXAMPLES

The following example adds two entries to the Normal rights section of the current working directory's ACL: the first entry grants r (read) and l (lookup) permissions to the group pat:friends, while the other (using the write shorthand) gives all permissions except a (administer) to the user smith.

   % fs setacl -path . -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 -clear flag, which removes the existing permissions (as displayed with the fs listacl command) from the current working directory's reports subdirectory and replaces them with a new set.

   % fs listacl -path 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 -path reports -acl pat all smith write system:anyuser rl

   % fs listacl -path reports
   Access list for reports is
   Normal rights:
      system:anyuser rl
      smith rlidwk
      pat rlidwka

The following example uses the -path and -acl switches because it sets the ACL for more than one directory (both the current working directory and its public subdirectory).

   % fs setacl -path . 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

The following example gives all rights to user pat, but only if the access is from from a keyed client on machine pat_laptop.

   % fs setacl dir -acl pat,pat_laptop all
   % fs listacl -path .
   Access list for dir is
   Normal rights:
      pat,pat_laptop rlidwka

PRIVILEGE REQUIRED

The issuer must have the 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.

SEE ALSO

fs_copyacl(1), fs_listacl(1), fs_removeacl(1), fs_mkmount(1), vos_setmaxacl(1) vos_listmaxacl(1)

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.

ACKNOWLEDGEMENTS

"AFS" is a registered mark of International Business Machines Corporation, used under license. (USPTO Registration 1598389)

"OpenAFS" is a registered mark of International Business Machines Corporation. (USPTO Registration 4577045)

The "AuriStor" name, log 'S' brand mark, and icon are registered marks of AuriStor, Inc. (USPTO Registrations 4849419, 4849421, and 4928460) (EUIPO Registration 015539653).

"Your File System" is a registered mark of AuriStor, Inc. (USPTO Registrations 4801402 and 4849418).

"YFS" and "AuriStor File System" are trademarks of AuriStor, Inc.