unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



setacl(1)							    setacl(1)



NAME

  setacl - Changes the specified access	control	list (ACL) on a	file or
  directory

SYNOPSIS

  setacl [-a] [-d] [-D]	[-b] [-E] [-k] [-K]
	 [-x entries]
	 [-X file1] [-u	entries]
	 [-U file2] filename ...

FLAGS

  -a  Specifies	that the operation applies to the access ACL.  This flag is
      implied if none of -a, -d, or -D is supplied.

  -b  Delete the access	ACL on the specified file or directory.	 The permis-
      sion bits	are not	removed	or changed in this operation, and the permis-
      sion bits	are considered to be the "base"	entries	of an ACL, so this
      can be considered	equivalent to resetting	the access ACL to just the
      base entries (u::, g::, o::).

  -d  The operation applies to the default access ACL.	Default	ACLs can only
      be set on	directories, an	error is returned if this operation applies
      to a file	instead	of a directory.	 Default ACLs must contain at least
      the 3 base entries entries of the	directory's access ACL (or the
      directory's permission bits if it	does not have an access	ACL).  You
      should specify values for	the 3 base entries if the current value	in
      the access ACL is	not appropriate.

      The -d flag is not defined by POSIX.

  -D  [Tru64 UNIX]  The	operation applies to the default directory ACL.
      Default ACLs can only be set on directories, an error is returned	if
      this operation applies to	a file instead of a directory.	Default	ACLs
      must contain at least the	3 base entries (the entries that correspond
      to the permission	bits).	When you first create a	default	ACL, if	you
      do not specify these 3 entries they default to the current value of the
      3	base entries of	the directory's	access ACL (or the directory's per-
      mission bits if it does not have an access ACL).	You should specify
      values for the 3 base entries if the current value in the	access ACL is
      not appropriate.

      The -D flag is not defined by POSIX.

  -E  [Tru64 UNIX]  Invoke the character cell ACL editor.

  -k  Delete the default access	ACL for	the designated directory.  No error
      is returned if the designated directory does not have a default access
      ACL.  An error is	returned if this operation is applied to a file
      instead of a directory.  If the -k flag is specified and the -d flag is
      not specified, all the other flags apply to the access ACL, not the
      default access ACL.

  -K  [Tru64 UNIX]  Delete the default directory ACL for the designated
      directory.  No error is returned if the designated directory does	not
      have a default directory ACL.  An	error is returned if this operation
      is applied to a file instead of a	directory.  If the -K flag is
      specified	and the	-d flag	is not specified, all the other	flags apply
      to the access ACL, not the default directory ACL.

  -X file1
      Removes the ACL entries listed in	file1 from the specified ACL of	the
      designated file or directory.

  -x entries
      Removes the specifed entries from	the specified ACL of the designated
      file or directory.

  -u entries
      Updates the ACL with the specified entries.  Matching entries are	modi-
      fied or overwritten, new entries are added.  An entry is considered
      matching if the tag type and tag qualifier are the same.	See the	For-
      mat of an	ACL Entry section for a	description of the format of ACL
      entries and how they are modified.

  -U file2
      Updates the ACL with the entries specified in file2.  Matching entries
      are modified or overwritten, new entries are added.  An entry is con-
      sidered matching if the tag type and tag qualifier are the same.	See
      the Format of an ACL Entry section for a description of the format of
      ACL entries and how they are modified.

  The -a, -d, and -D flags are not mutually exclusive; they can	all be speci-
  fied,	and all	are set.  If none are specified	the -a flag is assumed.	 The
  -d and -D flags only apply to	directories.

  The -b flag is applied before	any of the -u, -U, -x, or -X flags

  Multiple -u, -U, -x, and -X flags are	all applied to the ACL in the order
  listed on the	command	line.  All of flags are	applied	to a temporary copy
  of the ACL before the	ACL is applied to the files.  It is not	an error for
  an intermediate version of the ACL to	be ill formed, as long as the ACL is
  well formed by the time it is	applied.

  Several flags	accept arguments of the	following types:

  entries   The	ACL entries used to perform the	requested operation.  Multi-
	    ple	ACL entries are	separated by commas.  There is no required
	    ordering of	entries.

  file	    A file containing ACL entries to use to perform the	requested
	    operation.	Each entry should be on	a separate line.  There	is no
	    required ordering of entries.  If a	line contains the comment
	    character, #, setacl ignores the line.

  ACLs may be set on files and directories if ACLs are disabled	on the sys-
  tem, but ACL access checks and ACL inheritance won't take place.  The
  setacl command will print a warning if ACLs are disabled on the system.

  Not all types	of filesystems support ACLs.  The setacl command will fail if
  ACLs are not supported on the	filesystem.

DESCRIPTION





				     Note

       This command is based on	Draft 13 of the	POSIX P1003.6 standard.

  The setacl command is	used to	add, modify, and remove	access control lists
  (ACL)	and individual ACL entries on files and	directories.

  Files	only have one ACL, an access ACL.  Directories may have	up to 3	ACLs,
  an access ACL, a default access ACL, and a default directory ACL.  The
  default ACLs are used	to specify ACLs	to be inherited	by new files and sub-
  directories created within the directory.  See the acl(4) reference page
  and the Security guide for more information on ACL types and ACL inheri-
  tance.

  Format of an ACL Entry

  The external representation of an ACL	entry consists of three	colon (:)
  separated fields. The	first field is a tag type, the second field contains
  optional qualifiers whose meaning depend on the tag type, and	the third
  field	is a list of the permissions. The following examples are typical:

       user::rwx
       user:jdoe:rw-
       user:mightymouse:r--
       user:bsmith:rwx
       group::r--
       other::---

  The tag types	and associated qualifiers are:

  user::    If the qualifier field is empty, the user tag type defines the
	    permissions	for the	user who owns the file or directory.  This
	    entry should be considered exactly the same	as the owning user
	    permission bits.  Setting this entry will cause the	appropriate
	    change in the permission bits.

  user:x:   The	user tag type with a username or uid as	a tag qualifier
	    defines the	permissions for	the given user.	 If a numeric user
	    name exists	in the user database, the uid associated with that
	    user name will be used as the entry	uid.  For example if there is
	    a user name	"39456"	with uid 420, a	user name "fred" with uid
	    39456, and you create the entry "user:39456:rwx"; the uid 420
	    will be associated with the	ACL entry, not the uid 39456.

  group::   If the qualifier field is empty, the group tag type	defines	the
	    permissions	of users who are members of the	group associated with
	    the	file or	directory.  This entry should be considered exactly
	    the	same as	the owning group permission bits.  Setting this	entry
	    will cause the appropriate change in the permission	bits.

  group:x:  The	group tag type with a groupname	or gid as a tag	qualifier
	    defines the	permissions for	members	of the given group.  If	a
	    numeric group name exists in the group database, the gid associ-
	    ated with that group name will be used as the entry	gid.  For
	    example if there is	a group	name "521" with	gid 40,	a group	name
	    "mygroup" with gid 521, and	you create the entry "group:521:r--";
	    the	gid 40 will be associated with the ACL entry, not the gid
	    521.

  other	    No qualifiers are allowed for the other tag	type. The other	tag
	    type defines the permissions for users who are not covered by any
	    other ACL entries.	This entry should be considered	exactly	the
	    same as the	other permission bits.	Setting	this entry will	cause
	    the	appropriate change in the permission bits.

  The third field specifies the	discretionary access permissions.  They	are:


       Letter  Octal   PERMISSION
       r       4       Read access
       w       2       Write access
       x       1       Execute/Search access
       -       0       No access

  A set	of permissions in an ACL entry is internally represented in three
  bits.	The permissions	are displayed as a character string, similar to	the
  way that ls -l displays permissions.

  The set of permissions can be	specified in three ways:

       As a single octal digit.	 Add the numbers shown above to	determine the
       permissions.  The value 0 (zero), for example, specifies	no permis-
       sions, and the value 7 specifies	all permissions.

       As an absolute character	string.	An absolute character string contains
       three characters. The first specifies read permission, the second
       write permission, and the third specifies execute/search	permission.
       To grant	all permissions, specify rwx in	that order. To deny one	or
       more permissions, use the character - in	the appropriate	positions.
       For example, the	entry r-x grants read and execute/search permissions
       and denies write	permission.

       As a relative character string. A relative character string adds	or
       removes permissions from	the existing set. To add permissions, specify
       a "+" followed by one or	more permission	letters. For example, +r adds
       read permission to the existing set. To remove permissions, specify a
       "^" followed by one or more permission letters. For example, ^x
       removes execute/search permission. Some shells consider "^" as a	spe-
       cial character.	You may	need to	escape the character by	preceeding it
       with a back slash () or surrounding it with double quotes ("^").

  Both octal digits and	absolute character strings set the permissions to the
  specified values. One	of these forms should be used for new entries.

  Relative permissions modify an existing ACL entry (flags -u and -U) with an
  input	entry that matches in tag type and tag qualifier. If setacl adds an
  entry	to an ACL, a + prefix is ignored and the set of	permissions is
  entered as an	absolute string; if the	prefix is ^, the permissions field is
  set to no access.  If	an entry is to be removed from an ACL, input permis-
  sions	are ignored altogether.

  Suppose an ACL entry is specified with relative permissions,

       group:dec:\^wx  (remove wx permissions)

  to be	applied	to a matching entry with permissions r-x.  The matching	entry
  will have a new set of permissions as	follows:

       group:dec:r--  (read only)

  Format of an ACL

  An ACL contains at least three base tag type entries:

       A user entry with no qualifiers

       A group entry with no qualifiers

       An other	entry

       In an access ACL, these three entries are equivalent to the permission
       bits of the file	or directory.

       An ACL also has one or more user	or group entries with qualifiers, for
       example:

       user::rwx
       group::rw-
       user:user1:r-x
       group:dec:--x
       other::rwx

  The entry group::rw- is the file group owner and specifies the read and
  write	permissions.

  AUTHORIZATIONS

  To change or remove the ACL of a file	or directory, the user must either
  own the file or directory or be privileged (root).

EXAMPLES

   1.  Assume that the ACL on a	file named shared contains the following
       minimum entries:

	    user::rwx
	    group::r-x
	    other::---

       The following command updates and adds entries:

	    $ setacl -u	group::r--,user:alpha:-w- shared

       The resulting ACL entries are:

	    user::rwx
	    user:alpha:-w-
	    group::r--
	    other::---

       The owning group	entry on the command line matches the existing	group
       entry, so the permission	set is reduced to read only.  The user entry
       on the command line does	not match an existing entry and	is added.

   2.  Assume that the ACL on a	file named shared contains the following
       entries:

	    user::rwx
	    user:user1:-w-
	    group::-w-
	    group:dec:-wx
	    other::---

       Apply the setacl	-u command (update) to the shared file as follows:

	    $ setacl -u	user:user1:-wx shared

       The resulting ACL entries are:
	    user::rwx
	    user:user1:-wx-
	    group::-w-
	    group:dec:-wx
	    other::---

   3.  Assume that the directory foo contains no default ACLs, and the fol-
       lowing command is issued:

	    $ setacl -d	-u user::rw-,group::r--,other::r--,user:dec:rw-	foo

       Any file	or directory that is created within the	directory foo now
       inherits	the following ACL as the access	ACL:

	    user::rw-
	    user:dec:r--
	    group::r--
	    other::r--

       Any directory also inherits the same ACL	as the default access ACL.

   4.  Assume that the directory foo contains no default ACLs, and the fol-
       lowing command is issued:

	    $ setacl -D	-u user::rwx,group::r-x,other::---,user:dec:r-x	foo

       Any directory that is created within the	directory foo now inherits
       the following ACL as the	access ACL, as well as its default directory
       ACL:

	    user::rwx
	    user:dec:r-x
	    group::r-x
	    other::---

       Any file	does not inherit an ACL.  File permissions are set in the
       same way	as they	are without ACLs.

   5.  Assume that the directory foo contains no default ACLs, the 3 base
       entries of the access ACL on directory foo are u::rwx, group::r-x,
       other::r-x, and the following commands are issued:

	    $ setacl -D	-u user:dec:r--	foo
	    $ setacl -d	-u user::rw-,group::r--,other::---,user:alpha:r-- foo

       Any directory that is created within the	directory foo now inherits
       the default directory ACL of foo	as its access ACL as well as its
       default directory ACL:

	    user::rwx
	    user:dec:r--
	    group::r-x
	    other::r-x

       In addition, any	directory that is created within the directory foo
       inherits	the default access ACL of foo as its default access ACL:

	    user::rw-
	    user:alpha:r--
	    group::r--
	    other::r--

       Any file	created	in directory foo inherits the default access ACL of
       foo as its access ACL:

	    user::rw-
	    user:alpha:r--
	    group::r--
	    other::r--

EXIT VALUES

  If setacl is invoked incorrectly or cannot decipher the specified ACL, it
  returns an exit status of 1.	setacl returns an exit status of 0 (zero) if
  all files are	changed.

ERRORS

  The setacl command displays an error message explaining why the ACL could
  not be changed.

RELATED	INFORMATION

  Commands: getacl(1)

  Files:  acl(4)

  Security