This manual page describes POSIX Access Control Lists, which are used to
define more fine-grained discretionary access rights for files and direc
tories.
ACL TYPES
Every object can be thought of as having associated with it an ACL that
governs the discretionary 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 di
rectory; 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 ac
cess permissions on the associated object for an individual user or a
group of users as a combination of read, write and search/execute permis
sions.
An ACL entry contains an entry tag type, an optional entry tag qualifier,
and a set of permissions. 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 pro
cesses 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
fault ACL. The acl_set_file() function also accepts an ACL with zero ACL
entries as a valid default ACL for directories, denoting that the direc
tory 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 speci
fied by the file permission bits. The permissions defined for the file
owner correspond to the permissions of the ACL_USER_OBJ entry. The per
missions defined for the file group correspond to the permissions 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 corre
spond to the permissions 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 per
missions in the ACL entries results in the modification of the file per
mission 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 creating 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_MASK. The permissions of
these entries are set to the permissions specified by the file cre
ation 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 ob
ject 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
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_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.
4. else if the ACL_OTHER entry contains the requested permissions, ac
cess 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 qualifier, and the discretionary access
permissions. The first field contains one of the following 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 us
er (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 speci
fied 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 pro
cess that does not match any user or group ACL entries (en
try 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_US
ER 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 identifi
er 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).
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 unabbreviated 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 standard working group defined this relatively
complex interface in order to ensure that applications 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 interface in section B.23.
CHANGES TO THE FILE UTILITIES
On a system that supports ACLs, the file utilities ls(1), cp(1) and
mv(1) change their behavior in the following way:
· 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.
· If the -p flag is specified, the cp(1) utility also preserves ACLs.
If this is not possible, a warning is produced.
· The mv(1) utility always preserves ACLs. If this is not possible, a
warning is produced.
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 securi
ty 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 utili
ties defined for Access Control Lists in POSIX.1e, and several exten
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 sys
tems. 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 5
Man(1) output converted with
man2html