1ACL(5) BSD File Formats Manual ACL(5)
2
4 acl — Access Control Lists
5
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
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
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 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 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 The following entry tag types are defined:
33 ACL_USER_OBJ The ACL_USER_OBJ entry denotes access rights for
35 the file owner.
36 ACL_USER ACL_USER entries denote access rights for users
38 identified by the entry's qualifier.
39 ACL_GROUP_OBJ The ACL_GROUP_OBJ entry denotes access rights for
41 the file group.
42 ACL_GROUP ACL_GROUP entries denote access rights for groups
44 identified by the entry's qualifier.
45 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 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 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
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 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 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
79 The permissions defined by ACLs are a superset of the permissions speci‐
80 fied by the file permission bits.
81 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 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
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 1. The new object inherits the default ACL of the containing directory
105 as its access ACL.
106 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 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 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 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
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 1. If the effective user ID of the process matches the user ID of the
130 file object owner, then
131 if the ACL_USER_OBJ entry contains the requested permissions,
133 access is granted,
134 else access is denied.
136 2. else if the effective user ID of the process matches the qualifier
138 of any entry of type ACL_USER, then
139 if the matching ACL_USER entry and the ACL_MASK entry contain
141 the requested permissions, access is granted,
142 else access is denied.
144 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 if the ACL contains an ACL_MASK entry, then
150 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 else access is denied.
156 else (note that there can be no ACL_GROUP entries without an
158 ACL_MASK entry)
159 if the ACL_GROUP_OBJ entry contains the requested per‐
161 missions, access is granted,
162 else access is denied.
164 4. else if the ACL_OTHER entry contains the requested permissions,
166 access is granted.
167 5. else access is denied.
169
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 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 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 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 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 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 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 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 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 user::rw-
218 user:lisa:rw- #effective:r--
219 group::r--
220 group:toolies:rw- #effective:r--
221 mask::r--
222 other::r--
223 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 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
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
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 · 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 · If the -p flag is specified, the cp(1) utility also preserves ACLs.
256 If this is not possible, a warning is produced.
257 · The mv(1) utility always preserves ACLs. If this is not possible, a
259 warning is produced.
260 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
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 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
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 POSIX 1003.1e DRAFT 17
284 http://wt.tuxomania.net/publications/posix.1e/download.html
285 POSIX 1003.1e FUNCTIONS BY CATEGORY
287 ACL storage management
288 acl_dup(3), acl_free(3), acl_init(3)
289 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 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 acl_get_qualifier(3), acl_get_tag_type(3), acl_set_qualifier(3),
298 acl_set_tag_type(3)
299 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 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 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 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 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 LINUX EXTENSIONS
326 These non-portable extensions are available on Linux systems.
327 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
334 Andreas Gruenbacher, <a.gruenbacher@bestbits.at>
335Linux ACL March 23, 2002 Linux ACL