--- name: "acl" section: "5" platform: "linux" package: "acl" version: "2.4.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/acl/5" --- # acl(5) Access Control Lists ## 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 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 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 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\_GROUP 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 contain 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**() function 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 permission bits. There is a correspondence between the file owner, group, and other permissions and specific ACL entries: the owner permissions correspond to the permissions of the ACL\_USER\_OBJ entry. If the ACL has an ACL\_MASK entry, the group permissions correspond to the permissions of the ACL\_MASK entry. Otherwise, if the ACL has no ACL\_MASK entry, the group permissions correspond to the permissions of the ACL\_GROUP\_OBJ entry. The other permissions correspond to the permissions of the ACL\_OTHER entry. The file owner, group, and other permissions always match the permissions of the corresponding ACL entry. Modification of the file permission bits results in the modification of the associated ACL entries, and modification of these 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 creating file objects and the file creation mask (see [umask(2)](/umask/2.md)) 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 permissions 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 permissions, 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 file group 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 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 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 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)](/ls/1.md), [cp(1)](/cp/1.md), and [mv(1)](/mv/1.md) 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)](/ls/1.md) 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)](/cp/1.md) utility also preserves ACLs. If this is not possible, a warning is produced. - The [mv(1)](/mv/1.md) utility always preserves ACLs. If this is not possible, a warning is produced. The effect of the [chmod(1)](/chmod/1.md) utility, and of the [chmod(2)](/chmod/2.md) 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 compliant 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 \ header. Linux-specific extensions to these functions are declared in the \ header. ## NOTES ### DENIED PERMISSIONS AND LINUX USER NAMESPACES While ACLs can be used to deny processes permissions based on the groups they are in, this is considered bad practice. Privileged helpers such as [newuidmap(1)](/newuidmap/1.md) can give unprivileged processes access to the [setgroups(2)](/setgroups/2.md) system call, which allows them to drop supplementary group membership and render restrictions based on that membership ineffective. For further details, see [user\_namespaces(7)](/user_namespaces/7.md). ## SEE ALSO [chmod(1)](/chmod/1.md), [creat(2)](/creat/2.md), [getfacl(1)](/getfacl/1.md), [ls(1)](/ls/1.md), [mkdir(2)](/mkdir/2.md), [mkfifo(2)](/mkfifo/2.md), [mknod(2)](/mknod/2.md), [mount(8)](/mount/8.md), [open(2)](/open/2.md), [setfacl(1)](/setfacl/1.md), [stat(2)](/stat/2.md), [umask(1)](/umask/1.md) ### POSIX 1003.1e DRAFT 17 https://wt.tuxomania.net/publications/posix.1e/download.html ### POSIX 1003.1e FUNCTIONS BY CATEGORY - **ACL** **storage** **management** [acl\_dup(3)](/acl_dup/3.md), [acl\_free(3)](/acl_free/3.md), [acl\_init(3)](/acl_init/3.md) - **ACL** **entry** **manipulation** [acl\_copy\_entry(3)](/acl_copy_entry/3.md), [acl\_create\_entry(3)](/acl_create_entry/3.md), [acl\_delete\_entry(3)](/acl_delete_entry/3.md), [acl\_get\_entry(3)](/acl_get_entry/3.md), [acl\_valid(3)](/acl_valid/3.md) [acl\_add\_perm(3)](/acl_add_perm/3.md), [acl\_calc\_mask(3)](/acl_calc_mask/3.md), [acl\_clear\_perms(3)](/acl_clear_perms/3.md), [acl\_delete\_perm(3)](/acl_delete_perm/3.md), [acl\_get\_permset(3)](/acl_get_permset/3.md), [acl\_set\_permset(3)](/acl_set_permset/3.md) [acl\_get\_qualifier(3)](/acl_get_qualifier/3.md), [acl\_get\_tag\_type(3)](/acl_get_tag_type/3.md), [acl\_set\_qualifier(3)](/acl_set_qualifier/3.md), [acl\_set\_tag\_type(3)](/acl_set_tag_type/3.md) - **ACL** **manipulation** **on** **an** **object** [acl\_delete\_def\_file(3)](/acl_delete_def_file/3.md), [acl\_get\_fd(3)](/acl_get_fd/3.md), [acl\_get\_file(3)](/acl_get_file/3.md), [acl\_set\_fd(3)](/acl_set_fd/3.md), [acl\_set\_file(3)](/acl_set_file/3.md) - **ACL** **format** **translation** [acl\_copy\_entry(3)](/acl_copy_entry/3.md), [acl\_copy\_ext(3)](/acl_copy_ext/3.md), [acl\_from\_text(3)](/acl_from_text/3.md), [acl\_to\_text(3)](/acl_to_text/3.md), [acl\_size(3)](/acl_size/3.md) ### 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_delete_def_file/3.md), [acl\_dup(3)](/acl_dup/3.md), [acl\_free(3)](/acl_free/3.md), [acl\_from\_text(3)](/acl_from_text/3.md), [acl\_get\_fd(3)](/acl_get_fd/3.md), [acl\_get\_file(3)](/acl_get_file/3.md), [acl\_init(3)](/acl_init/3.md), [acl\_set\_fd(3)](/acl_set_fd/3.md), [acl\_set\_file(3)](/acl_set_file/3.md), [acl\_to\_text(3)](/acl_to_text/3.md), [acl\_valid(3)](/acl_valid/3.md) [acl\_add\_perm(3)](/acl_add_perm/3.md), [acl\_calc\_mask(3)](/acl_calc_mask/3.md), [acl\_clear\_perms(3)](/acl_clear_perms/3.md), [acl\_copy\_entry(3)](/acl_copy_entry/3.md), [acl\_copy\_ext(3)](/acl_copy_ext/3.md), [acl\_copy\_int(3)](/acl_copy_int/3.md), [acl\_create\_entry(3)](/acl_create_entry/3.md), [acl\_delete\_entry(3)](/acl_delete_entry/3.md), [acl\_delete\_perm(3)](/acl_delete_perm/3.md), [acl\_get\_entry(3)](/acl_get_entry/3.md), [acl\_get\_permset(3)](/acl_get_permset/3.md), [acl\_get\_qualifier(3)](/acl_get_qualifier/3.md), [acl\_get\_tag\_type(3)](/acl_get_tag_type/3.md), [acl\_set\_permset(3)](/acl_set_permset/3.md), [acl\_set\_qualifier(3)](/acl_set_qualifier/3.md), [acl\_set\_tag\_type(3)](/acl_set_tag_type/3.md), [acl\_size(3)](/acl_size/3.md) ### LINUX EXTENSIONS These non-portable extensions are available on Linux systems. [acl\_check(3)](/acl_check/3.md), [acl\_cmp(3)](/acl_cmp/3.md), [acl\_delete\_def\_file\_at(3)](/acl_delete_def_file_at/3.md), [acl\_entries(3)](/acl_entries/3.md), [acl\_equiv\_mode(3)](/acl_equiv_mode/3.md), [acl\_error(3)](/acl_error/3.md), [acl\_extended\_fd(3)](/acl_extended_fd/3.md), [acl\_extended\_file(3)](/acl_extended_file/3.md), [acl\_extended\_file\_at(3)](/acl_extended_file_at/3.md), [acl\_extended\_file\_nofollow(3)](/acl_extended_file_nofollow/3.md), [acl\_from\_mode(3)](/acl_from_mode/3.md), [acl\_get\_file\_at(3)](/acl_get_file_at/3.md), [acl\_get\_perm(3)](/acl_get_perm/3.md), [acl\_set\_file\_at(3)](/acl_set_file_at/3.md), [acl\_to\_any\_text(3)](/acl_to_any_text/3.md) ## AUTHOR Andreas Gruenbacher, \