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. The permissions defined for the file
81 owner correspond to the permissions of the ACL_USER_OBJ entry. The per‐
82 missions defined for the file group correspond to the permissions of the
83 ACL_GROUP_OBJ entry, if the ACL has no ACL_MASK entry. If the ACL has an
84 ACL_MASK entry, then the permissions defined for the file group corre‐
85 spond to the permissions of the ACL_MASK entry. The permissions defined
86 for the other class correspond to the permissions of the ACL_OTHER_OBJ
87 entry.
88 Modification of the file permission bits results in the modification of
90 the permissions in the associated ACL entries. Modification of the per‐
91 missions in the ACL entries results in the modification of the file per‐
92 mission bits.
93
95 The access ACL of a file object is initialized when the object is created
96 with any of the creat(), mkdir(), mknod(), mkfifo(), or open() functions.
97 If a default ACL is associated with a directory, the mode parameter to
98 the functions creating file objects and the default ACL of the directory
99 are used to determine the ACL of the new object:
100 1. The new object inherits the default ACL of the containing directory
102 as its access ACL.
103 2. The access ACL entries corresponding to the file permission bits are
105 modified so that they contain no permissions that are not contained
106 in the permissions specified by the mode parameter.
107 If no default ACL is associated with a directory, the mode parameter to
109 the functions creating file objects and the file creation mask (see
110 umask(2)) are used to determine the ACL of the new object:
111 1. The new object is assigned an access ACL containing entries of tag
113 types ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER. The permissions of
114 these entries are set to the permissions specified by the file cre‐
115 ation mask.
116 2. The access ACL entries corresponding to the file permission bits are
118 modified so that they contain no permissions that are not contained
119 in the permissions specified by the mode parameter.
120
122 A process may request read, write, or execute/search access to a file
123 object protected by an ACL. The access check algorithm determines whether
124 access to the object will be granted.
125 1. If the effective user ID of the process matches the user ID of the
127 file object owner, then
128 if the ACL_USER_OBJ entry contains the requested permissions,
130 access is granted,
131 else access is denied.
133 2. else if the effective user ID of the process matches the qualifier
135 of any entry of type ACL_USER, then
136 if the matching ACL_USER entry and the ACL_MASK entry contain
138 the requested permissions, access is granted,
139 else access is denied.
141 3. else if the effective group ID or any of the supplementary group IDs
143 of the process match the file group or the qualifier of any entry of
144 type ACL_GROUP, then
145 if the ACL contains an ACL_MASK entry, then
147 if the ACL_MASK entry and any of the matching ACL_GROUP_OBJ
149 or ACL_GROUP entries contain the requested permissions,
150 access is granted,
151 else access is denied.
153 else (note that there can be no ACL_GROUP entries without an
155 ACL_MASK entry)
156 if the ACL_GROUP_OBJ entry contains the requested permis‐
158 sions, access is granted,
159 else access is denied.
161 4. else if the ACL_OTHER entry contains the requested permissions,
163 access is granted.
164 5. else access is denied.
166
168 A long and a short text form for representing ACLs is defined. In both
169 forms, ACL entries are represented as three colon separated fields: an
170 ACL entry tag type, an ACL entry qualifier, and the discretionary access
171 permissions. The first field contains one of the following entry tag type
172 keywords:
173 user A user ACL entry specifies the access granted to either the
175 file owner (entry tag type ACL_USER_OBJ) or a specified
176 user (entry tag type ACL_USER).
177 group A group ACL entry specifies the access granted to either
179 the file group (entry tag type ACL_GROUP_OBJ) or a speci‐
180 fied group (entry tag type ACL_GROUP).
181 mask A mask ACL entry specifies the maximum access which can be
183 granted by any ACL entry except the user entry for the file
184 owner and the other entry (entry tag type ACL_MASK).
185 other An other ACL entry specifies the access granted to any
187 process that does not match any user or group ACL entries
188 (entry tag type ACL_OTHER).
189 The second field contains the user or group identifier of the user or
191 group associated with the ACL entry for entries of entry tag type
192 ACL_USER or ACL_GROUP, and is empty for all other entries. A user identi‐
193 fier can be a user name or a user ID number in decimal form. A group
194 identifier can be a group name or a group ID number in decimal form.
195 The third field contains the discretionary access permissions. The read,
197 write and search/execute permissions are represented by the r, w, and x
198 characters, in this order. Each of these characters is replaced by the -
199 character to denote that a permission is absent in the ACL entry. When
200 converting from the text form to the internal representation, permissions
201 that are absent need not be specified.
202 White space is permitted at the beginning and end of each ACL entry, and
204 immediately before and after a field separator (the colon character).
205 LONG TEXT FORM
207 The long text form contains one ACL entry per line. In addition, a number
208 sign (#) may start a comment that extends until the end of the line. If
209 an ACL_USER, ACL_GROUP_OBJ or ACL_GROUP ACL entry contains permissions
210 that are not also contained in the ACL_MASK entry, the entry is followed
211 by a number sign, the string “effective:”, and the effective access per‐
212 missions defined by that entry. This is an example of the long text form:
213 user::rw-
215 user:lisa:rw- #effective:r--
216 group::r--
217 group:toolies:rw- #effective:r--
218 mask::r--
219 other::r--
220 SHORT TEXT FORM
222 The short text form is a sequence of ACL entries separated by commas, and
223 is used for input. Comments are not supported. Entry tag type keywords
224 may either appear in their full unabbreviated form, or in their single
225 letter abbreviated form. The abbreviation for user is u, the abbreviation
226 for group is g, the abbreviation for mask is m, and the abbreviation for
227 other is o. The permissions may contain at most one each of the follow‐
228 ing characters in any order: r, w, x. These are examples of the short
229 text form:
230 u::rw-,u:lisa:rw-,g::r--,g:toolies:rw-,m::r--,o::r--
232 g:toolies:rw,u:lisa:rw,u::wr,g::r,o::r,m::r
233
235 IEEE 1003.1e draft 17 defines Access Control Lists that include entries
236 of tag type ACL_MASK, and defines a mapping between file permission bits
237 that is not constant. The standard working group defined this relatively
238 complex interface in order to ensure that applications that are compliant
239 with IEEE 1003.1 (“POSIX.1”) will still function as expected on systems
240 with ACLs. The IEEE 1003.1e draft 17 contains the rationale for choosing
241 this interface in section B.23.
242
244 On a system that supports ACLs, the file utilities ls(1), cp(1), and
245 mv(1) change their behavior in the following way:
246 · For files that have a default ACL or an access ACL that contains more
248 than the three required ACL entries, the ls(1) utility in the long
249 form produced by ls -l displays a plus sign (+) after the permission
250 string.
251 · If the -p flag is specified, the cp(1) utility also preserves ACLs.
253 If this is not possible, a warning is produced.
254 · The mv(1) utility always preserves ACLs. If this is not possible, a
256 warning is produced.
257 The effect of the chmod(1) utility, and of the chmod(2) system call, on
259 the access ACL is described in CORRESPONDENCE BETWEEN ACL ENTRIES AND
260 FILE PERMISSION BITS.
261
263 The IEEE 1003.1e draft 17 (“POSIX.1e”) document describes several secu‐
264 rity extensions to the IEEE 1003.1 standard. While the work on 1003.1e
265 has been abandoned, many UNIX style systems implement parts of POSIX.1e
266 draft 17, or of earlier drafts.
267 Linux Access Control Lists implement the full set of functions and utili‐
269 ties defined for Access Control Lists in POSIX.1e, and several exten‐
270 sions. The implementation is fully compliant with POSIX.1e draft 17;
271 extensions are marked as such. The Access Control List manipulation
272 functions are defined in the ACL library (libacl, -lacl). The POSIX com‐
273 pliant interfaces are declared in the <sys/acl.h> header. Linux-specific
274 extensions to these functions are declared in the <acl/libacl.h> header.
275
277 chmod(1), creat(2), getfacl(1), ls(1), mkdir(2), mkfifo(2), mknod(2),
278 open(2), setfacl(1), stat(2), umask(1)
279 POSIX 1003.1e DRAFT 17
281 http://www.guug.de/~winni/posix.1e/download.html
282 POSIX 1003.1e FUNCTIONS BY CATEGORY
284 ACL storage management
285 acl_dup(3), acl_free(3), acl_init(3)
286 ACL entry manipulation
288 acl_copy_entry(3), acl_create_entry(3), acl_delete_entry(3),
289 acl_get_entry(3), acl_valid(3)
290 acl_add_perm(3), acl_calc_mask(3), acl_clear_perms(3),
292 acl_delete_perm(3), acl_get_permset(3), acl_set_permset(3)
293 acl_get_qualifier(3), acl_get_tag_type(3), acl_set_qualifier(3),
295 acl_set_tag_type(3)
296 ACL manipulation on an object
298 acl_delete_def_file(3), acl_get_fd(3), acl_get_file(3),
299 acl_set_fd(3), acl_set_file(3)
300 ACL format translation
302 acl_copy_entry(3), acl_copy_ext(3), acl_from_text(3),
303 acl_to_text(3), acl_size(3)
304 POSIX 1003.1e FUNCTIONS BY AVAILABILITY
306 The first group of functions is supported on most systems with POSIX-like
307 access control lists, while the second group is supported on fewer sys‐
308 tems. For applications that will be ported the second group is best
309 avoided.
310 acl_delete_def_file(3), acl_dup(3), acl_free(3), acl_from_text(3),
312 acl_get_fd(3), acl_get_file(3), acl_init(3), acl_set_fd(3),
313 acl_set_file(3), acl_to_text(3), acl_valid(3)
314 acl_add_perm(3), acl_calc_mask(3), acl_clear_perms(3), acl_copy_entry(3),
316 acl_copy_ext(3), acl_copy_int(3), acl_create_entry(3),
317 acl_delete_entry(3), acl_delete_perm(3), acl_get_entry(3),
318 acl_get_permset(3), acl_get_qualifier(3), acl_get_tag_type(3),
319 acl_set_permset(3), acl_set_qualifier(3), acl_set_tag_type(3),
320 acl_size(3)
321 LINUX EXTENSIONS
323 These non-portable extensions are available on Linux systems.
324 acl_check(3), acl_cmp(3), acl_entries(3), acl_equiv_mode(3),
326 acl_error(3), acl_extended_fd(3), acl_extended_file(3), acl_from_mode(3),
327 acl_get_perm(3), acl_to_any_text(3)
328
330 Andreas Gruenbacher, <a.gruenbacher@bestbits.at>
331Linux ACL March 23, 2002 Linux ACL