Unix/Linux Go Back    


man page for acl (all section 5)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


ACL(5)				     BSD File Formats Manual				   ACL(5)

NAME
     acl -- Access Control Lists

DESCRIPTION
     This manual page describes POSIX Access Control Lists, which are used to define more fine-
     grained discretionary access rights for files and directories.

ACL TYPES
     Every object can be thought of as having associated with it an ACL that governs the discre-
     tionary access to that object; this ACL is referred to as an access ACL. In addition, a
     directory may have an associated ACL that governs the initial access ACL for objects created
     within that directory; this ACL is referred to as a default ACL.

ACL ENTRIES
     An ACL consists of a set of ACL entries. An ACL entry specifies the access permissions on
     the associated object for an individual user or a group of users as a combination of read,
     write and search/execute permissions.

     An ACL entry contains an entry tag type, an optional entry tag qualifier, and a set of per-
     missions.	We use the term qualifier to denote the entry tag qualifier of an ACL entry.

     The qualifier denotes the identifier of a user or a group, for entries with tag types of
     ACL_USER or ACL_GROUP, respectively. Entries with tag types other than ACL_USER or ACL_GROUP
     have no defined qualifiers.

     The following entry tag types are defined:

	   ACL_USER_OBJ    The ACL_USER_OBJ entry denotes access rights for the file owner.

	   ACL_USER	   ACL_USER entries denote access rights for users identified by the
			   entry's qualifier.

	   ACL_GROUP_OBJ   The ACL_GROUP_OBJ entry denotes access rights for the file group.

	   ACL_GROUP	   ACL_USER entries denote access rights for groups identified by the
			   entry's qualifier.

	   ACL_MASK	   The ACL_MASK entry denotes the maximum access rights that can be
			   granted by entries of type ACL_USER, ACL_GROUP_OBJ, or ACL_GROUP.

	   ACL_OTHER	   The ACL_OTHER entry denotes access rights for processes that do not
			   match any other entry in the ACL.

     When an access check is performed, the ACL_USER_OBJ and ACL_USER entries are tested against
     the effective user ID. The effective group ID, as well as all supplementary group IDs are
     tested against the ACL_GROUP_OBJ and ACL_GROUP entries.

VALID ACLs
     A valid ACL contains exactly one entry with each of the ACL_USER_OBJ, ACL_GROUP_OBJ, and
     ACL_OTHER tag types. Entries with ACL_USER and ACL_GROUP tag types may appear zero or more
     times in an ACL. An ACL that contains entries of ACL_USER or ACL_GROUP tag types must con-
     tain exactly one entry of the ACL_MASK tag type. If an ACL contains no entries of ACL_USER
     or ACL_GROUP tag types, the ACL_MASK entry is optional.

     All user ID qualifiers must be unique among all entries of ACL_USER tag type, and all group
     IDs must be unique among all entries of ACL_GROUP tag type.

       The acl_get_file() function returns an ACL with zero ACL entries as the default ACL of a
     directory, if the directory is not associated with a default ACL. The acl_set_file() func-
     tion also accepts an ACL with zero ACL entries as a valid default ACL for directories,
     denoting that the directory shall not be associated with a default ACL. This is equivalent
     to using the acl_delete_def_file() function.

CORRESPONDENCE BETWEEN ACL ENTRIES AND FILE PERMISSION BITS
     The permissions defined by ACLs are a superset of the permissions specified by the file per-
     mission bits. The permissions defined for the file owner correspond to the permissions of
     the ACL_USER_OBJ entry.  The permissions defined for the file group correspond to the per-
     missions of the ACL_GROUP_OBJ entry, if the ACL has no ACL_MASK entry. If the ACL has an
     ACL_MASK entry, then the permissions defined for the file group correspond to the permis-
     sions of the ACL_MASK entry. The permissions defined for the other class correspond to the
     permissions of the ACL_OTHER_OBJ entry.

     Modification of the file permission bits results in the modification of the permissions in
     the associated ACL entries. Modification of the permissions in the ACL entries results in
     the modification of the file permission bits.

OBJECT CREATION AND DEFAULT ACLs
     The access ACL of a file object is initialized when the object is created with any of the
     creat(), mkdir(), mknod(), mkfifo(), or open() functions. If a default ACL is associated
     with a directory, the mode parameter to the functions creating file objects and the default
     ACL of the directory are used to determine the ACL of the new object:

     1.   The new object inherits the default ACL of the containing directory as its access ACL.

     2.   The access ACL entries corresponding to the file permission bits are modified so that
	  they contain no permissions that are not contained in the permissions specified by the
	  mode parameter.

     If no default ACL is associated with a directory, the mode parameter to the functions creat-
     ing file objects and the file creation mask (see umask(2)) are used to determine the ACL of
     the new object:

     1.   The new object is assigned an access ACL containing entries of tag types ACL_USER_OBJ,
	  ACL_GROUP_OBJ, and ACL_OTHER. The permissions of these entries are set to the permis-
	  sions specified by the file creation mask.

     2.   The access ACL entries corresponding to the file permission bits are modified so that
	  they contain no permissions that are not contained in the permissions specified by the
	  mode parameter.

ACCESS CHECK ALGORITHM
     A process may request read, write, or execute/search access to a file object protected by an
     ACL. The access check algorithm determines whether access to the object will be granted.

     1.   If the effective user ID of the process matches the user ID of the file object owner,
	  then

	      if the ACL_USER_OBJ entry contains the requested permissions, access is granted,

	      else access is denied.

     2.   else if the effective user ID of the process matches the qualifier of any entry of type
	  ACL_USER, then

	      if the matching ACL_USER entry and the ACL_MASK entry contain the requested permis-
	      sions, access is granted,

	      else access is denied.

     3.   else if the effective group ID or any of the supplementary group IDs of the process
	  match the qualifier of the entry of type ACL_GROUP_OBJ, or the qualifier of any entry
	  of type ACL_GROUP, then

	      if the ACL contains an ACL_MASK entry, then

		  if the ACL_MASK entry and  any  of  the  matching  ACL_GROUP_OBJ  or	ACL_GROUP
		  entries contain the requested permissions, access is granted,

		  else access is denied.

	      else (note that there can be no ACL_GROUP entries without an ACL_MASK entry)

		  if  the  ACL_GROUP_OBJ  entry  contains  the	requested  permissions, access is
		  granted,

		  else access is denied.

     4.   else if the ACL_OTHER entry contains the requested permissions, access is granted.

     5.   else access is denied.

ACL TEXT FORMS
     A long and a short text form for representing ACLs is defined. In both forms, ACL entries
     are represented as three colon separated fields: an ACL entry tag type, an ACL entry quali-
     fier, and the discretionary access permissions. The first field contains one of the follow-
     ing entry tag type keywords:

	   user    A user ACL entry specifies the access granted to either the file owner (entry
		   tag type ACL_USER_OBJ) or a specified user (entry tag type ACL_USER).

	   group   A group ACL entry specifies the access granted to either the file group (entry
		   tag type ACL_GROUP_OBJ) or a specified group (entry tag type ACL_GROUP).

	   mask    A mask ACL entry specifies the maximum access which can be granted by any ACL
		   entry except the user entry for the file owner and the other entry (entry tag
		   type ACL_MASK).

	   other   An other ACL entry specifies the access granted to any process that does not
		   match any user or group ACL entries (entry tag type ACL_OTHER).

     The second field contains the user or group identifier of the user or group associated with
     the ACL entry for entries of entry tag type ACL_USER or ACL_GROUP, and is empty for all
     other entries. A user identifier can be a user name or a user ID number in decimal form. A
     group identifier can be a group name or a group ID number in decimal form.

     The third field contains the discretionary access permissions. The read, write and
     search/execute permissions are represented by the r, w, and x characters, in this order.
     Each of these characters is replaced by the - character to denote that a permission is
     absent in the ACL entry.  When converting from the text form to the internal representation,
     permissions that are absent need not be specified.

     White space is permitted at the beginning and end of each ACL entry, and immediately before
     and after a field separator (the colon character).

   LONG TEXT FORM
     The long text form contains one ACL entry per line. In addition, a number sign (#) may start
     a comment that extends until the end of the line. If an ACL_USER, ACL_GROUP_OBJ or ACL_GROUP
     ACL entry contains permissions that are not also contained in the ACL_MASK entry, the entry
     is followed by a number sign, the string "effective:", and the effective access permissions
     defined by that entry. This is an example of the long text form:

	   user::rw-
	   user:lisa:rw-	 #effective:r--
	   group::r--
	   group:toolies:rw-	 #effective:r--
	   mask::r--
	   other::r--

   SHORT TEXT FORM
     The short text form is a sequence of ACL entries separated by commas, and is used for input.
     Comments are not supported. Entry tag type keywords may either appear in their full unabbre-
     viated form, or in their single letter abbreviated form. The abbreviation for user is u, the
     abbreviation for group is g, the abbreviation for mask is m, and the abbreviation for other
     is o.  The permissions may contain at most one each of the following characters in any
     order: r, w, x.  These are examples of the short text form:

	   u::rw-,u:lisa:rw-,g::r--,g:toolies:rw-,m::r--,o::r--
	   g:toolies:rw,u:lisa:rw,u::wr,g::r,o::r,m::r

RATIONALE
     IEEE 1003.1e draft 17 defines Access Control Lists that include entries of tag type
     ACL_MASK, and defines a mapping between file permission bits that is not constant. The stan-
     dard working group defined this relatively complex interface in order to ensure that appli-
     cations that are compliant with IEEE 1003.1 ("POSIX.1") will still function as expected on
     systems with ACLs. The IEEE 1003.1e draft 17 contains the rationale for choosing this inter-
     face in section B.23.

CHANGES TO THE FILE UTILITIES
     On a system that supports ACLs in its file utilities, the ls(1), cp(1) and mv(1) commands
     change their behavior in the following way:

     o	 For files that have a default ACL or an access ACL that contains more than the three
	 required ACL entries, the ls(1) utility in the long form produced by ls -l displays a
	 plus sign (+) after the permission string.

     o	 If the -p flag is specified, the cp(1) utility also preserves ACLs.  If this is not pos-
	 sible, a warning is produced.

     o	   The mv(1) utility always preserves ACLs. If this is not possible, a warning is pro-
	 duced.

     The effect of the chmod(1) utility, and of the chmod(2) system call, on the access ACL is
     described in CORRESPONDENCE BETWEEN ACL ENTRIES AND FILE PERMISSION BITS.

STANDARDS
     The IEEE 1003.1e draft 17 ("POSIX.1e") document describes several security extensions to the
     IEEE 1003.1 standard. While the work on 1003.1e has been abandoned, many UNIX style systems
     implement parts of POSIX.1e draft 17, or of earlier drafts.

     Linux Access Control Lists implement the full set of functions and utilities defined for
     Access Control Lists in POSIX.1e, and several extensions.	The implementation is fully com-
     pliant with POSIX.1e draft 17; extensions are marked as such.  The Access Control List
     manipulation functions are defined in the ACL library (libacl, -lacl). The POSIX compliant
     interfaces are declared in the <sys/acl.h> header.  Linux-specific extensions to these func-
     tions are declared in the <acl/libacl.h> header.

SEE ALSO
     chmod(1), creat(2), getfacl(1), ls(1), mkdir(2), mkfifo(2), mknod(2), open(2), setfacl(1),
     stat(2), umask(1)

   POSIX 1003.1e DRAFT 17
     http://www.guug.de/~winni/posix.1e/download.html

   POSIX 1003.1e FUNCTIONS BY CATEGORY
     ACL storage management
	  acl_dup(3), acl_free(3), acl_init(3)

     ACL entry manipulation
	  acl_copy_entry(3), acl_create_entry(3), acl_delete_entry(3), acl_get_entry(3),
	  acl_valid(3)

	  acl_add_perm(3), acl_calc_mask(3), acl_clear_perms(3), acl_delete_perm(3),
	  acl_get_permset(3), acl_set_permset(3)

	  acl_get_qualifier(3), acl_get_tag_type(3), acl_set_qualifier(3), acl_set_tag_type(3)

     ACL manipulation on an object
	  acl_delete_def_file(3), acl_get_fd(3), acl_get_file(3), acl_set_fd(3), acl_set_file(3)

     ACL format translation
	  acl_copy_entry(3), acl_copy_ext(3), acl_from_text(3), acl_to_text(3), acl_size(3)

   POSIX 1003.1e FUNCTIONS BY AVAILABILITY
     The first group of functions is supported on most systems with POSIX-like access control
     lists, while the second group is supported on fewer systems.  For applications that will be
     ported the second group is best avoided.

     acl_delete_def_file(3), acl_dup(3), acl_free(3), acl_from_text(3), acl_get_fd(3),
     acl_get_file(3), acl_init(3), acl_set_fd(3), acl_set_file(3), acl_to_text(3), acl_valid(3)

     acl_add_perm(3), acl_calc_mask(3), acl_clear_perms(3), acl_copy_entry(3), acl_copy_ext(3),
     acl_copy_int(3), acl_create_entry(3), acl_delete_entry(3), acl_delete_perm(3),
     acl_get_entry(3), acl_get_permset(3), acl_get_qualifier(3), acl_get_tag_type(3),
     acl_set_permset(3), acl_set_qualifier(3), acl_set_tag_type(3), acl_size(3)

   LINUX EXTENSIONS
     These non-portable extensions are available on Linux systems.

     acl_check(3), acl_cmp(3), acl_entries(3), acl_equiv_mode(3), acl_error(3),
     acl_extended_fd(3), acl_extended_file(3), acl_from_mode(3), acl_get_perm(3),
     acl_to_any_text(3)

Linux ACL				  March 23, 2002				Linux ACL
Unix & Linux Commands & Man Pages : ©2000 - 2017 Unix and Linux Forums


All times are GMT -4. The time now is 10:43 PM.