1 ACL(5) Standards, Environments, and Macros ACL(5)
2
3
4
5 NAME
6 acl - Access Control Lists
7
8 DESCRIPTION
9 Access control lists (ACLs) are discretionary access control mechanisms
10 that grant and deny access to files and directories. Two different ACL
11 models are supported in this release: POSIX-draft ACLs and NFSv4 ACLs.
12
13
14 The older, POSIX-draft model is supported by the UFS file system. This
15 model is based on a withdrawn ACL POSIX specification that was never
16 standardized. It was subsequently withdrawn by the POSIX committee.
17
18
19 The other model is based on the standards of the NFSv4 working group
20 and is an approved standard from the Internet Engineering Task Force
21 (IETF). The ZFS file system uses the NFSv4 model, and provides richer
22 semantics and finer grained permission capabilities than the POSIX-
23 draft model.
24
25 POSIX-draft ACLs
26 POSIX-draft ACLs provide an alternative security mechanism to basic
27 UNIX file permissions. Their purpose is to further restrict access to
28 files and directories or to extend permissions to a particular user.
29 ACLs can be used to change the permissions for the standard owner,
30 group and other class bits of a file's mode. ACLs can give additional
31 users and groups access to the file. A directory can also have a
32 special kind of ACL called a default ACL, which defines ACL entries to
33 be inherited by descendents of the directory. POSIX-draft ACLs have an
34 ACL entry called mask. The mask defines the maximum permissions that
35 can be granted to additional user and group entries. Whenever a file is
36 created or its mode is changed by chmod(1) or chmod(2), the mask is
37 recomputed. It is recomputed to be the group permission defined in the
38 mode passed to chmod(2).
39
40
41 The POSIX-draft ACL model uses the standard rwx model of traditional
42 UNIX permissions.
43
44
45 An ACL is represented as follows:
46
47 acl_entry[,acl_entry]...
48
49
50
51
52 Each acl_entry contains one ACL entry. An ACL entry is represented by
53 two or three colon-separated(:) fields.
54
55 user:[uid]:perms
56 If uid blank, it represents the file owner.
57
58
59 group:[gid]:perms
60 If gid is blank, it represents the owning group.
61
62
63 other:perms
64 Represents the file other class.
65
66
67 mask:perms
68 Defines the MAX permission to hand out.
69
70
71
72 For example to give user joe read and write permissions, the ACL entry
73 is specified as:
74
75 user:joe:rw-
76
77
78
79 NFSv4 ACLs
80 The NFSv4 ACL model is based loosely on the Windows NT ACL model. NFSv4
81 ACLs provide a much richer ACL model than POSIX-draft ACLs.
82
83
84 The major differences between NFSv4 and POSIX-draft ACLs are as
85 follows:
86
87 o NFSv4 ACLs provide finer grained permissions than the rwx
88 model.
89
90 o NFSv4 ACLs allow for both ALLOW and DENY entries.
91
92 o NFSv4 ACLs provide a rich set of inheritance semantics.
93 POSIX ACLs also have inheritance, but with the NFSv4 model
94 you can control the following inheritance features:
95
96 o Whether inheritance cascades to both files and
97 directories or only to files or directories.
98
99 o In the case of directories, you can indicate whether
100 inheritance is applied to the directory itself, to just
101 one level of subdirectories, or cascades to all
102 subdirectories of the directory.
103
104 o NFSv4 ACLs provide a mechanism for hooking into a system's
105 audit trail. Currently, illumos does not support this
106 mechanism.
107
108 o NFSv4 ACLs enable administrators to specify the order in
109 which ACL entries are checked. With POSIX-draft ACLs the
110 file system reorders ACL entries into a well defined, strict
111 access, checking order.
112
113
114 POSIX-draft ACL semantics can be achieved with NFSv4 ACLs. However,
115 only some NFSv4 ACLs can be translated to equivalent POSIX-draft ACLs.
116
117
118 Permissions can be specified in three different chmod ACL formats:
119 verbose, compact, or positional. The verbose format uses words to
120 indicate that the permissions are separated with a forward slash (/)
121 character. Compact format uses the permission letters and positional
122 format uses the permission letters or the hyphen (-) to identify no
123 permissions.
124
125
126 The permissions for verbose mode and their abbreviated form in
127 parentheses for compact and positional mode are described as follows:
128
129 read_data (r)
130 Permission to read the data of the file
131
132
133 list_directory (r)
134 Permission to list the contents of a directory.
135
136
137 write_data (w)
138 Permission to modify a file's data anywhere in
139 the file's offset range. This includes the
140 ability to grow the file or write to any
141 arbitrary offset.
142
143
144 add_file (w)
145 Permission to add a new file to a directory.
146
147
148 append_data (p)
149 The ability to modify the file's data, but only
150 starting at EOF. Currently, this permission is
151 not supported.
152
153
154 add_subdirectory (p)
155 Permission to create a subdirectory to a
156 directory.
157
158
159 read_xattr (R)
160 The ability to read the extended attributes of
161 a file or do a lookup in the extended
162 attributes directory.
163
164
165 write_xattr (W)
166 The ability to create extended attributes or
167 write to the extended attributes directory.
168
169
170 execute (x)
171 Permission to execute a file.
172
173
174 read_attributes (a)
175 The ability to read basic attributes (non-ACLs)
176 of a file. Basic attributes are considered to
177 be the stat level attributes. Allowing this
178 access mask bit means that the entity can
179 execute ls(1) and stat(2).
180
181
182 write_attributes (A)
183 Permission to change the times associated with
184 a file or directory to an arbitrary value.
185
186
187 delete (d)
188 Permission to delete the file.
189
190
191 delete_child (D)
192 Permission to delete a file within a directory.
193
194
195 read_acl (c)
196 Permission to read the ACL.
197
198
199 write_acl (C)
200 Permission to write the ACL or the ability to
201 execute chmod(1) or setfacl(1).
202
203
204 write_owner (o)
205 Permission to change the owner or the ability
206 to execute chown(1) or chgrp(1).
207
208
209 synchronize (s)
210 Permission to access a file locally at the
211 server with synchronous reads and writes.
212 Currently, this permission is not supported.
213
214
215
216 The following inheritance flags are supported by NFSv4 ACLs:
217
218 file_inherit (f)
219 Inherit to all newly created files in a
220 directory.
221
222
223 dir_inherit (d)
224 Inherit to all newly created directories in a
225 directory.
226
227
228 inherit_only (i)
229 Placed on a directory, but does not apply to
230 the directory itself, only to newly created
231 files and directories. This flag requires
232 file_inherit and/or dir_inherit to indicate
233 what to inherit.
234
235
236 no_propagate (n)
237 Placed on directories and indicates that ACL
238 entries should only be inherited one level of
239 the tree. This flag requires file_inherit
240 and/or dir_inherit to indicate what to
241 inherit.
242
243
244 successful_access (S)
245 Indicates whether an alarm or audit record
246 should be initiated upon successful accesses.
247 Used with audit/alarm ACE types.
248
249
250 failed_access (F)
251 Indicates whether an alarm or audit record
252 should be initiated when access fails. Used
253 with audit/alarm ACE types.
254
255
256 inherited (I)
257 ACE was inherited.
258
259
260 -
261 No permission granted.
262
263
264
265 An NFSv4 ACL is expressed using the following syntax:
266
267 acl_entry[,acl_entry]...
268
269 owner@:<perms>[:inheritance flags]:<allow|deny>
270 group@:<perms>[:inheritance flags]:<allow|deny>
271 everyone@:<perms>[:inheritance flags]:<allow|deny>
272 user:<username>:<perms>[:inheritance flags]:<allow|deny>
273 usersid:<sid string>:<perms>[:inheritance flags]:<allow|deny>
274 group:<groupname>:<perms>[:inheritance flags]:<allow|deny>
275 groupsid:<sid string>:<perms>[:inheritance flags]:<allow|deny>
276 sid:<sid string>:<perms>[:inheritance flags]:<allow|deny>
277
278
279 owner@
280 File owner
281
282
283 group@
284 Group owner
285
286
287 user
288 Permissions for a specific user
289
290
291 group
292 Permissions for a specific group
293
294
295
296 Permission and inheritance flags are separated by a / character.
297
298
299 ACL specification examples:
300
301 user:fred:read_data/write_data/read_attributes:file_inherit:allow
302 owner@:read_data:allow,group@:read_data:allow,user:tom:read_data:deny
303
304
305
306
307 Using the compact ACL format, permissions are specified by using 14
308 unique letters to indicate permissions.
309
310
311 Using the positional ACL format, permissions are specified as
312 positional arguments similar to the ls -V format. The hyphen (-), which
313 indicates that no permission is granted at that position, can be
314 omitted and only the required letters have to be specified.
315
316
317 The letters above are listed in the order they would be specified in
318 positional notation.
319
320
321 With these letters you can specify permissions in the following
322 equivalent ways.
323
324 user:fred:rw------R------:file_inherit:allow
325
326
327
328
329 Or you can remove the - and scrunch it together.
330
331 user:fred:rwR:file_inherit:allow
332
333
334
335
336 The inheritance flags can also be specified in a more compact manner,
337 as follows:
338
339 user:fred:rwR:f:allow
340 user:fred:rwR:f------:allow
341
342
343
344 Shell-level API
345 Several utilities support the manipulation of ACLs. The following
346 utilities accommodate both ACL models:
347
348 chmod
349 The chmod utility has been enhanced to allow for the
350 setting and deleting of ACLs. This is achieved by extending
351 the symbolic-mode argument to support ACL manipulation. See
352 chmod(1) for details.
353
354
355 compress
356 When a file is compressed any ACL associated with the
357 original file is preserved with the compressed file.
358
359
360 cp
361 By default, cp ignores ACLs, unless the -p option is
362 specified. When -p is specified the owner and group id,
363 permission modes, modification and access times, ACLs, and
364 extended attributes if applicable are preserved.
365
366
367 cpio
368 ACLs are preserved when the -P option is specified.
369
370
371 find
372 Find locates files with ACLs when the -acl flag is
373 specified.
374
375
376 ls
377 By default ls does not display ACL information. When the -v
378 option is specified, a file's ACL is displayed.
379
380
381 mv
382 When a file is moved, all attributes are carried along with
383 the renamed file. When a file is moved across a file
384 system boundary, the ACLs are replicated. If the ACL
385 information cannot be replicated, the move fails and the
386 source file is not removed.
387
388
389 pack
390 When a file is packed, any ACL associated with the original
391 file is preserved with the packed file.
392
393
394 rcp
395 rcp has been enhanced to support copying. A file's ACL is
396 only preserved when the remote host supports ACLs.
397
398
399 tar
400 ACLs are preserved when the -p option is specified.
401
402
403 unpack
404 When a file with an ACL is unpacked, the unpacked file
405 retains the ACL information.
406
407
408 Application-level API
409 The primary interfaces required to access file system ACLs at the
410 programmatic level are the acl_get() and acl_set() functions. These
411 functions support both POSIX-draft ACLs and NFSv4 ACLs.
412
413 Retrieving a file's ACL
414 int acl_get(const char *path, int flag, acl_t **aclp);
415 int facl_get(int fd, int flag, acl_t **aclp);
416
417
418
419 The acl_get(3SEC) and facl_get(3SEC) functions retrieve an ACL on a
420 file whose name is given by path or referenced by the open file
421 descriptor fd. The flag argument specifies whether a trivial ACL should
422 be retrieved. When the flag argument equals ACL_NO_TRIVIAL only ACLs
423 that are not trivial are retrieved. The ACL is returned in the aclp
424 argument.
425
426 Freeing ACL structure
427 void acl_free(acl_t *aclp);
428
429
430
431 The acl_free() function frees up memory allocated for the argument
432 aclp.
433
434 Setting an ACL on a file
435 int acl_set(const char *path, acl_t *aclp);
436 int facl_set(int fd, acl_t *aclp);
437
438
439
440 The acl_set(3SEC) and facl_get(3SEC) functions are used for setting an
441 ACL on a file whose name is given by path or referenced by the open
442 file descriptor fd. The aclp argument specifies the ACL to set. The
443 acl_set(3SEC) function translates a POSIX-draft ACL into a NFSv4 ACL
444 when the target file system supports NFSv4 ACLs. No translation is
445 performed when trying to set an NFSv4 ACL on a POSIX-draft ACL
446 supported file system.
447
448 Determining an ACL's trivialness
449 int acl_trivial(const char *path);
450
451
452
453 The acl_trivial() function is used to determine whether a file has a
454 trivial ACL.
455
456 Removing all ACLs from a file
457 int acl_strip(const char *path, uid_t uid, gid_t gid, mode_t mode);
458
459
460
461 The acl_strip() function removes all ACLs from a file and replaces them
462 with a trivial ACL based off of the passed in argument mode. After
463 replacing the ACL the owner and group of the file are set to the values
464 specified in the uid and gid parameters.
465
466 Converting ACLs to/from external representation
467 int acl_fromtext(const char *path, acl_t **aclp);
468 char *acl_totext(acl_t *aclp, int flags);
469
470
471
472 The acl_totext() function converts an internal ACL representation
473 pointed to by aclp into an external representation. See DESCRIPTION for
474 details about external representation.
475
476
477 The acl_fromtext() function converts an external representation into an
478 internal representation. See DESCRIPTION for details about external
479 representation.
480
481 EXAMPLES
482 The following examples demonstrate how the API can be used to perform
483 basic operations on ACLs.
484
485 Example 1 Retrieving and Setting an ACL
486
487
488 Use the following to retrieve an ACL and set it on another file:
489
490
491 error = acl_get("file", ACL_NO_TRIVIAL, &aclp);
492
493 if (error == 0 && aclp != NULL) {
494 error = acl_set("file2", aclp);
495 acl_free(aclp);
496 }
497 ...
498
499
500 Example 2 Retrieving and Setting Any ACLs
501
502
503 Use the following to retrieve any ACL, including trivial ACLs, and set
504 it on another file:
505
506
507 error = acl_get("file3", 0, &aclp);
508 if (error == 0) {
509 error = acl_set("file4", aclp);
510 acl_free(aclp);
511 }
512 ...
513
514
515 Example 3 Determining if a File has a Trivial ACL
516
517
518 Use the following to determine if a file has a trivial ACL:
519
520
521 char *file = "file5";
522 istrivial = acl_trivial(file);
523
524 if (istrivial == 0)
525 printf("file %s has a trivial ACL\n", file);
526 else
527 printf("file %s has a NON-trivial ACL\n", file);
528 ...
529
530
531 Example 4 Removing all ACLs from a File
532
533
534 Use the following to remove all ACLs from a file, and set a new mode,
535 owner, and group:
536
537
538 error = acl_strip("file", 10, 100, 0644);
539 ...
540
541
542 SEE ALSO
543 chgrp(1), chmod(1), chown(1), cp(1), cpio(1), find(1), ls(1), mv(1),
544 tar(1), setfacl(1), chmod(2), acl(2), stat(2), acl_get(3SEC),
545 aclsort(3SEC), acl_fromtext(3SEC), acl_free(3SEC), acl_strip(3SEC),
546 acl_trivial(3SEC)
547
548
549
550 February 8, 2020 ACL(5)