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

NAME

4     acl — Access Control Lists
5

DESCRIPTION

7     This manual page describes POSIX Access Control Lists, which are used to
8     define more fine-grained discretionary access rights for files and direc‐
9     tories.
10

ACL TYPES

12     Every object can be thought of as having associated with it an ACL that
13     governs the discretionary access to that object; this ACL is referred to
14     as an access ACL. In addition, a directory may have an associated ACL
15     that governs the initial access ACL for objects created within that
16     directory; this ACL is referred to as a default ACL.
17

ACL ENTRIES

19     An ACL consists of a set of ACL entries. An ACL entry specifies the
20     access permissions on the associated object for an individual user or a
21     group of users as a combination of read, write and search/execute permis‐
22     sions.
23
24     An ACL entry contains an entry tag type, an optional entry tag qualifier,
25     and a set of permissions.  We use the term qualifier to denote the entry
26     tag qualifier of an ACL entry.
27
28     The qualifier denotes the identifier of a user or a group, for entries
29     with tag types of ACL_USER or ACL_GROUP, respectively. Entries with tag
30     types other than ACL_USER or ACL_GROUP have no defined qualifiers.
31
32     The following entry tag types are defined:
33
34           ACL_USER_OBJ    The ACL_USER_OBJ entry denotes access rights for
35                           the file owner.
36
37           ACL_USER        ACL_USER entries denote access rights for users
38                           identified by the entry's qualifier.
39
40           ACL_GROUP_OBJ   The ACL_GROUP_OBJ entry denotes access rights for
41                           the file group.
42
43           ACL_GROUP       ACL_GROUP entries denote access rights for groups
44                           identified by the entry's qualifier.
45
46           ACL_MASK        The ACL_MASK entry denotes the maximum access
47                           rights that can be granted by entries of type
48                           ACL_USER, ACL_GROUP_OBJ, or ACL_GROUP.
49
50           ACL_OTHER       The ACL_OTHER entry denotes access rights for pro‐
51                           cesses that do not match any other entry in the
52                           ACL.
53
54     When an access check is performed, the ACL_USER_OBJ and ACL_USER entries
55     are tested against the effective user ID. The effective group ID, as well
56     as all supplementary group IDs are tested against the ACL_GROUP_OBJ and
57     ACL_GROUP entries.
58

VALID ACLs

60     A valid ACL contains exactly one entry with each of the ACL_USER_OBJ,
61     ACL_GROUP_OBJ, and ACL_OTHER tag types. Entries with ACL_USER and
62     ACL_GROUP tag types may appear zero or more times in an ACL. An ACL that
63     contains entries of ACL_USER or ACL_GROUP tag types must contain exactly
64     one entry of the ACL_MASK tag type. If an ACL contains no entries of
65     ACL_USER or ACL_GROUP tag types, the ACL_MASK entry is optional.
66
67     All user ID qualifiers must be unique among all entries of ACL_USER tag
68     type, and all group IDs must be unique among all entries of ACL_GROUP tag
69     type.
70
71       The acl_get_file() function returns an ACL with zero ACL entries as the
72     default ACL of a directory, if the directory is not associated with a
73     default ACL. The acl_set_file() function also accepts an ACL with zero
74     ACL entries as a valid default ACL for directories, denoting that the
75     directory shall not be associated with a default ACL. This is equivalent
76     to using the acl_delete_def_file() function.
77

CORRESPONDENCE BETWEEN ACL ENTRIES AND FILE PERMISSION BITS

79     The permissions defined by ACLs are a superset of the permissions speci‐
80     fied by the file permission bits.
81
82     There is a correspondence between the file owner, group, and other per‐
83     missions and specific ACL entries: the owner permissions correspond to
84     the permissions of the ACL_USER_OBJ entry. If the ACL has an ACL_MASK
85     entry, the group permissions correspond to the permissions of the
86     ACL_MASK entry.  Otherwise, if the ACL has no ACL_MASK entry, the group
87     permissions correspond to the permissions of the ACL_GROUP_OBJ entry.
88     The other permissions correspond to the permissions of the ACL_OTHER_OBJ
89     entry.
90
91     The file owner, group, and other permissions always match the permissions
92     of the corresponding ACL entry. Modification of the file permission bits
93     results in the modification of the associated ACL entries, and modifica‐
94     tion of these ACL entries results in the modification of the file permis‐
95     sion bits.
96

OBJECT CREATION AND DEFAULT ACLs

98     The access ACL of a file object is initialized when the object is created
99     with any of the creat(), mkdir(), mknod(), mkfifo(), or open() functions.
100     If a default ACL is associated with a directory, the mode parameter to
101     the functions creating file objects and the default ACL of the directory
102     are used to determine the ACL of the new object:
103
104     1.   The new object inherits the default ACL of the containing directory
105          as its access ACL.
106
107     2.   The access ACL entries corresponding to the file permission bits are
108          modified so that they contain no permissions that are not contained
109          in the permissions specified by the mode parameter.
110
111     If no default ACL is associated with a directory, the mode parameter to
112     the functions creating file objects and the file creation mask (see
113     umask(2)) are used to determine the ACL of the new object:
114
115     1.   The new object is assigned an access ACL containing entries of tag
116          types ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER. The permissions of
117          these entries are set to the permissions specified by the file cre‐
118          ation mask.
119
120     2.   The access ACL entries corresponding to the file permission bits are
121          modified so that they contain no permissions that are not contained
122          in the permissions specified by the mode parameter.
123

ACCESS CHECK ALGORITHM

125     A process may request read, write, or execute/search access to a file
126     object protected by an ACL. The access check algorithm determines whether
127     access to the object will be granted.
128
129     1.   If the effective user ID of the process matches the user ID of the
130          file object owner, then
131
132                if the ACL_USER_OBJ entry contains the requested  permissions,
133                access is granted,
134
135                else access is denied.
136
137     2.   else if the effective user ID of the process matches the qualifier
138          of any entry of type ACL_USER, then
139
140                if the matching ACL_USER entry and the ACL_MASK entry  contain
141                the requested permissions, access is granted,
142
143                else access is denied.
144
145     3.   else if the effective group ID or any of the supplementary group IDs
146          of the process match the file group or the qualifier of any entry of
147          type ACL_GROUP, then
148
149                if the ACL contains an ACL_MASK entry, then
150
151                      if   the   ACL_MASK   entry  and  any  of  the  matching
152                      ACL_GROUP_OBJ or ACL_GROUP entries contain the requested
153                      permissions, access is granted,
154
155                      else access is denied.
156
157                else  (note  that there can be no ACL_GROUP entries without an
158                ACL_MASK entry)
159
160                      if the ACL_GROUP_OBJ entry contains the  requested  per‐
161                      missions, access is granted,
162
163                      else access is denied.
164
165     4.   else if the ACL_OTHER entry contains the requested permissions,
166          access is granted.
167
168     5.   else access is denied.
169

ACL TEXT FORMS

171     A long and a short text form for representing ACLs is defined. In both
172     forms, ACL entries are represented as three colon separated fields: an
173     ACL entry tag type, an ACL entry qualifier, and the discretionary access
174     permissions. The first field contains one of the following entry tag type
175     keywords:
176
177           user    A user ACL entry specifies the access granted to either the
178                   file owner (entry tag type ACL_USER_OBJ) or a specified
179                   user (entry tag type ACL_USER).
180
181           group   A group ACL entry specifies the access granted to either
182                   the file group (entry tag type ACL_GROUP_OBJ) or a speci‐
183                   fied group (entry tag type ACL_GROUP).
184
185           mask    A mask ACL entry specifies the maximum access which can be
186                   granted by any ACL entry except the user entry for the file
187                   owner and the other entry (entry tag type ACL_MASK).
188
189           other   An other ACL entry specifies the access granted to any
190                   process that does not match any user or group ACL entries
191                   (entry tag type ACL_OTHER).
192
193     The second field contains the user or group identifier of the user or
194     group associated with the ACL entry for entries of entry tag type
195     ACL_USER or ACL_GROUP, and is empty for all other entries. A user identi‐
196     fier can be a user name or a user ID number in decimal form. A group
197     identifier can be a group name or a group ID number in decimal form.
198
199     The third field contains the discretionary access permissions. The read,
200     write and search/execute permissions are represented by the r, w, and x
201     characters, in this order. Each of these characters is replaced by the -
202     character to denote that a permission is absent in the ACL entry.  When
203     converting from the text form to the internal representation, permissions
204     that are absent need not be specified.
205
206     White space is permitted at the beginning and end of each ACL entry, and
207     immediately before and after a field separator (the colon character).
208
209   LONG TEXT FORM
210     The long text form contains one ACL entry per line. In addition, a number
211     sign (#) may start a comment that extends until the end of the line. If
212     an ACL_USER, ACL_GROUP_OBJ or ACL_GROUP ACL entry contains permissions
213     that are not also contained in the ACL_MASK entry, the entry is followed
214     by a number sign, the string “effective:”, and the effective access per‐
215     missions defined by that entry. This is an example of the long text form:
216
217           user::rw-
218           user:lisa:rw-         #effective:r--
219           group::r--
220           group:toolies:rw-     #effective:r--
221           mask::r--
222           other::r--
223
224   SHORT TEXT FORM
225     The short text form is a sequence of ACL entries separated by commas, and
226     is used for input. Comments are not supported. Entry tag type keywords
227     may either appear in their full unabbreviated form, or in their single
228     letter abbreviated form. The abbreviation for user is u, the abbreviation
229     for group is g, the abbreviation for mask is m, and the abbreviation for
230     other is o.  The permissions may contain at most one each of the follow‐
231     ing characters in any order: r, w, x.  These are examples of the short
232     text form:
233
234           u::rw-,u:lisa:rw-,g::r--,g:toolies:rw-,m::r--,o::r--
235           g:toolies:rw,u:lisa:rw,u::wr,g::r,o::r,m::r
236

RATIONALE

238     IEEE 1003.1e draft 17 defines Access Control Lists that include entries
239     of tag type ACL_MASK, and defines a mapping between file permission bits
240     that is not constant. The standard working group defined this relatively
241     complex interface in order to ensure that applications that are compliant
242     with IEEE 1003.1 (“POSIX.1”) will still function as expected on systems
243     with ACLs. The IEEE 1003.1e draft 17 contains the rationale for choosing
244     this interface in section B.23.
245

CHANGES TO THE FILE UTILITIES

247     On a system that supports ACLs, the file utilities ls(1), cp(1), and
248     mv(1) change their behavior in the following way:
249
250     ·   For files that have a default ACL or an access ACL that contains more
251         than the three required ACL entries, the ls(1) utility in the long
252         form produced by ls -l displays a plus sign (+) after the permission
253         string.
254
255     ·   If the -p flag is specified, the cp(1) utility also preserves ACLs.
256         If this is not possible, a warning is produced.
257
258     ·     The mv(1) utility always preserves ACLs. If this is not possible, a
259         warning is produced.
260
261     The effect of the chmod(1) utility, and of the chmod(2) system call, on
262     the access ACL is described in CORRESPONDENCE BETWEEN ACL ENTRIES AND
263     FILE PERMISSION BITS.
264

STANDARDS

266     The IEEE 1003.1e draft 17 (“POSIX.1e”) document describes several secu‐
267     rity extensions to the IEEE 1003.1 standard. While the work on 1003.1e
268     has been abandoned, many UNIX style systems implement parts of POSIX.1e
269     draft 17, or of earlier drafts.
270
271     Linux Access Control Lists implement the full set of functions and utili‐
272     ties defined for Access Control Lists in POSIX.1e, and several exten‐
273     sions.  The implementation is fully compliant with POSIX.1e draft 17;
274     extensions are marked as such.  The Access Control List manipulation
275     functions are defined in the ACL library (libacl, -lacl). The POSIX com‐
276     pliant interfaces are declared in the <sys/acl.h> header.  Linux-specific
277     extensions to these functions are declared in the <acl/libacl.h> header.
278

SEE ALSO

280     chmod(1), creat(2), getfacl(1), ls(1), mkdir(2), mkfifo(2), mknod(2),
281     open(2), setfacl(1), stat(2), umask(1)
282
283   POSIX 1003.1e DRAFT 17
284     http://wt.tuxomania.net/publications/posix.1e/download.html
285
286   POSIX 1003.1e FUNCTIONS BY CATEGORY
287     ACL storage management
288          acl_dup(3), acl_free(3), acl_init(3)
289
290     ACL entry manipulation
291          acl_copy_entry(3), acl_create_entry(3), acl_delete_entry(3),
292          acl_get_entry(3), acl_valid(3)
293
294          acl_add_perm(3), acl_calc_mask(3), acl_clear_perms(3),
295          acl_delete_perm(3), acl_get_permset(3), acl_set_permset(3)
296
297          acl_get_qualifier(3), acl_get_tag_type(3), acl_set_qualifier(3),
298          acl_set_tag_type(3)
299
300     ACL manipulation on an object
301          acl_delete_def_file(3), acl_get_fd(3), acl_get_file(3),
302          acl_set_fd(3), acl_set_file(3)
303
304     ACL format translation
305          acl_copy_entry(3), acl_copy_ext(3), acl_from_text(3),
306          acl_to_text(3), acl_size(3)
307
308   POSIX 1003.1e FUNCTIONS BY AVAILABILITY
309     The first group of functions is supported on most systems with POSIX-like
310     access control lists, while the second group is supported on fewer sys‐
311     tems.  For applications that will be ported the second group is best
312     avoided.
313
314     acl_delete_def_file(3), acl_dup(3), acl_free(3), acl_from_text(3),
315     acl_get_fd(3), acl_get_file(3), acl_init(3), acl_set_fd(3),
316     acl_set_file(3), acl_to_text(3), acl_valid(3)
317
318     acl_add_perm(3), acl_calc_mask(3), acl_clear_perms(3), acl_copy_entry(3),
319     acl_copy_ext(3), acl_copy_int(3), acl_create_entry(3),
320     acl_delete_entry(3), acl_delete_perm(3), acl_get_entry(3),
321     acl_get_permset(3), acl_get_qualifier(3), acl_get_tag_type(3),
322     acl_set_permset(3), acl_set_qualifier(3), acl_set_tag_type(3),
323     acl_size(3)
324
325   LINUX EXTENSIONS
326     These non-portable extensions are available on Linux systems.
327
328     acl_check(3), acl_cmp(3), acl_entries(3), acl_equiv_mode(3),
329     acl_error(3), acl_extended_fd(3), acl_extended_file(3),
330     acl_extended_file_nofollow(3), acl_from_mode(3), acl_get_perm(3),
331     acl_to_any_text(3)
332

AUTHOR

334     Andreas Gruenbacher, <a.gruenbacher@bestbits.at>
335
336Linux ACL                       March 23, 2002                       Linux ACL
Impressum