acl(4)acl(4)NAMEacl - Access Control Lists
SYNOPSIS
#include <sys/acl.h>
DESCRIPTION
Access Control Lists (ACLs) are supported on XFS and UDF file systems
only.
ACLs provide a mechanism for finer grained access control than the
traditional UNIX discretionary access control mechanism. An ACL is a
list of users and/or groups and their access rights, which is associated
with a file or directory. ACLs are optional. In addition to the ACL
used to mediate access, a directory may have a second ACL which defines
the default initial ACL for files created in that directory. Files have
only the single access control ACL.
EXTERNAL REPRESENTATION
ACLs are represented in a standard format for human readable input /
output and consists of a set of ACL entries. An ACL entry specifies the
access permissions on the associated file for an individual user or a
group of users.
The text form for ACLs is used for either input or output of ACLs and is
defined as follows:
acl_entry[,acl_entry]...
Each entry contains one ACL statement with three required colon-separated
fields and an optional comment:
entry tag type:entry qualifier:discretionary access permissions # comment
ACL entries are separated by white space or new lines. Comments may be
included with any entry. If a comment starts at the beginning of a line,
then the entire line is interpreted as a comment. Comments have no effect
on the discretionary access check of the object with which they are
associated.
The first field of an ACL entry is the entry tag type, which can be one
of the following:
"user", "group", "other", "mask", "u", "g", "o", or "m"
user A "user" ACL entry specifies the access granted to either the
file owner or to a specified user account.
group A "group" ACL entry specifies the access granted to either the
file-owning user group or to a specified user group.
Page 1
acl(4)acl(4)
other An "other" ACL entry specifies the access granted to any
process that does not match any user, group, or
implementation-defined ACL entries.
mask A "mask" ACL entry specifies the maximum access that can be
granted by any ACL entry except the user entry for the file
owner and the other entry. See the Algorithm section for
detail.
The "u", "g", "o" and "m" are abbreviation of "user", "group", "other"
and "mask" respectively.
The second field is entry qualifier which contains a user name, numeric
UID, group name, or numeric GID, depending on the value of the first
field. (acl_from_text(3c) supports only the strings, not the numeric
UID/GID values.) If the second field is empty, it implies that the ACL
entry is for the owning user or group of the file. Mask and other
entries must have an empty second field.
The third field is the discretionary access permissions for this ACL
entry. This may be represented in two forms. The first is the string
"rwx" where each letter may be replaced by a "-" indicating no access of
that type. The parsing of this string by acl_from_text(3c) requires that
it be exactly as shown and not be reordered, e.g. rxw is not valid.
Some programs allow a second form, the relative symbolic form (used for
input). The relative symbolic form is preceded by a ``+'' to indicate
additional access or a ``^'' to indicate that access is to be removed,
similarly to the inputs to the chmod(1) command. The relative symbolic
string is at least one character. The symbolic string contains at most
one each of the following characters in any order: "r", "w", and "x".
A "user" entry with an empty qualifier specifies the access granted to
the file owner. A user entry with a uid qualifier specifies the access
permissions granted to the user name matching the uid value.
A "group" entry with an empty qualifier specifies the access granted to
the default user group of the file owner. A group entry with a gid
qualifier specifies the access permissions granted to the group name
matching the gid value.
Interface
At the interface to the library routines, ACLs are represented in a
struct acl which is defined in <sys/acl.h>.
#define ACL_MAX_ENTRIES 25
typedef ushort acl_perm_t;
typedef int acl_type_t;
typedef int acl_tag_t;
struct acl_entry {
Page 2
acl(4)acl(4)
acl_tag_t ae_tag;
uid_t ae_id;
acl_perm_t ae_perm;
};
typedef struct acl_entry * acl_entry_t;
struct acl {
int acl_cnt;
struct acl_entry acl_entry[ACL_MAX_ENTRIES];
};
This is a fixed size structure with a variable number of active struct
acl_entry entries. The maximum number of entries is ACL_MAX_ENTRIES
which is currently defined to be 25. The number of active entries is
indicated in acl_cnt.
The struct acl_entry consists of three fields, ae_tag, which identifies
the type of the entry, and is one of the following values (all other
values are invalid):
ACL_USER_OBJ (0x01)
ACL entry starts with tag user or 'u', and second field is
empty. This is the entry for the owner of the object. Its
third field determines the permissions of the owner.
ACL_USER (0x02)
ACL entry starts with tag user or 'u', but the second
field specifies an user name of userid Its third field and
the third field of the ACL_MASK entry determines the
permissions of the user specified in the second field.
ACL_GROUP_OBJ (0x04)
ACL entry starts with tag group or 'g', and the second
field is empty. Its third field and the third field of
ACL_MASK entry determines the permissions for all users
which are in the same group specified by the second field.
ACL_GROUP (0x08)
ACL entry starts with tag group or 'g, and the second
field specifies a group name or groupid. Its third field
and the third field of the ACL_MASK entry determines the
permissions for all the users in the group specified by
the second field.
ACL_MASK (0x10)
ACL entry starts with tag mask or 'm', and the second
field is empty. Its third field specifies the maximum
permissions for all the upper categories except
ACL_USER_OBJ and ACL_OTHER_OBJ.
Page 3
acl(4)acl(4)
ACL_OTHER_OBJ (0x20)
ACL entry starts with tag other or 'o', and the second
field is empty. Its third field determines the permissions
for all the other users not specified in the upper
categories.
The ae_id field of struct acl_entry specifies the UID or
GID for the entry. The ae_perm field specifies the
permissions using the following defined values:
ACL_READ (0x04)
read access permitted
ACL_WRITE (0x02)
write access permitted
ACL_EXECUTE (0x01)
execute (search for directories) access permitted
As with the basic permissions for a file, these may be or'ed together.
Two types of ACLs are defined. ACL_TYPE_ACCESS (0) indicates that the ACL
is to be used in making access control decisions for the file or
directory with which it is associated. ACL_TYPE_DEFAULT (1) indicates
that the ACL is a default ACL. Default ACLs are associated only with
directories, and supply the initial ACL for a file created in that
directory. Note that file-creation mode masks may effect the ACLs of
files created as a result of using directory default ACLs (see umask(1)).
ACLs are supplied using the acl_get_file(3c) and acl_set_file(3c) calls.
ACL Algorithm
Assuming a process has userid uid and accesses an object (file or
directory) with ACLs, the followings are how ACL entries are matched
against process characteristics:
IF (ACL_USER_OBJ exists and
process's uid is the owner of the object)
ACL_USER_OBJECT's permission bits determines the
permissions of the process on the object;
ELSE IF (an ACL_USER exists and
qualifier field of ACL_USER equals process's uid)
ACL_USER's permission bits (logical) and ACL_MASK's
permission bits determines the permissions of the
process on the object;
ELSE IF (an ACL_GROUP_OBJ exists and
process's uid is in the same group with the object)
Page 4
acl(4)acl(4)
ACL_GROUP_OBJECT's permission bits (logical) and
ACL_MASK's permission bits determines the permissions
of the process on the object;
ELSE IF (an ACL_GROUP exists and process's uid is in the group
specified by the qualifier field of the entry)
ACL_GROUP's permission bits (logical) and ACL_MASK's
permission bits determines the permissions of the
process on the object.
ELSE
ACL_OTHER_OBJECT's permissions bits determine the
permissions of the process on the object.
For IRIX, the privileged root user has all permissions on all objects
regardless of the ACL entries.
Example
Here is an example of a correct long text form ACL for a file:
user::rwx,user:332:r--,user:ernie:rw-
The above example sets full permissions for the owner with the first
entry on the line, sets read permission for user ID 332 with the second
entry, and sets read and write permission for the user account ernie.
A shortened ACL entry could look very similar to the following:
u::rwx # The file owner has complete access
u:332:r-- # User Acct 332 has read access only
g:10:rw- # User Group 10 has read/write access
u:653:r-- # User Acct 653 (who is in group 10) has read access only
o::--- # No one else has any permission
m::rw- # The maximum permission except for the owner and other entry is read/write
Page 5
