acl(5) — Linux manual page

NAME | DESCRIPTION | ACL TYPES | ACL ENTRIES | VALID ACLs | CORRESPONDENCE BETWEEN ACL ENTRIES AND FILE PERMISSION BITS | OBJECT CREATION AND DEFAULT ACLs | ACCESS CHECK ALGORITHM | ACL TEXT FORMS | RATIONALE | CHANGES TO THE FILE UTILITIES | STANDARDS | NOTES | SEE ALSO | AUTHOR | COLOPHON

ACL(5)                     File Formats Manual                    ACL(5)

NAME         top

       acl — Access Control Lists

DESCRIPTION         top

       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         top

       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         top

       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         top

       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         top

       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         top

       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_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         top

       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         top

       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         top

       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         top

       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         top

       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 <sys/acl.h> header.  Linux-specific extensions to
       these functions are declared in the <acl/libacl.h> header.

NOTES         top

   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) can give unprivileged processes
       access to the setgroups(2) 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).

SEE ALSO         top

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

   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_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_extended_file_nofollow(3), acl_from_mode(3), acl_get_perm(3),
       acl_to_any_text(3)

AUTHOR         top

       Andreas Gruenbacher, <andreas.gruenbacher@gmail.com>

COLOPHON         top

       This page is part of the acl (manipulating access control lists)
       project.  Information about the project can be found at
       http://savannah.nongnu.org/projects/acl.  If you have a bug
       report for this manual page, see
       ⟨http://savannah.nongnu.org/bugs/?group=acl⟩.  This page was
       obtained from the project's upstream Git repository
       ⟨git://git.savannah.nongnu.org/acl.git⟩ on 2023-12-22.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2023-12-01.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

Linux ACL                    March 23, 2002                       ACL(5)

Pages that refer to this page: chacl(1)getfacl(1)setfacl(1)mkdir(2)mknod(2)open(2)umask(2)erofs(5)ext4(5)tmpfiles.d(5)xattr(7)mount(8)