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 the Solaris release: POSIX-draft ACLs and NFSv4
12 ACLs.
13
14
15 The older, POSIX-draft model is supported by the UFS file system. This
16 model is based on a withdrawn ACL POSIX specification that was never
17 standardized. It was subsequently withdrawn by the POSIX committee.
18
19
20 The other model is based on the standards of the NFSv4 working group
21 and is an approved standard from the Internet Engineering Task Force
22 (IETF). The ZFS file system uses the NFSv4 model, and provides richer
23 semantics and finer grained permission capabilities than the POSIX-
24 draft model.
25
26 POSIX-draft ACLs
27 POSIX-draft ACLs provide an alternative security mechanism to basic
28 UNIX file permissions in the Solaris release. Their purpose is to
29 further restrict access to files and directories or to extend
30 permissions to a particular user. ACLs can be used to change the
31 permissions for the standard owner, group and other class bits of a
32 file's mode. ACLs can give additional users and groups access to the
33 file. A directory can also have a special kind of ACL called a default
34 ACL, which defines ACL entries to be inherited by descendents of the
35 directory. POSIX-draft ACLs have an ACL entry called mask. The mask
36 defines the maximum permissions that can be granted to additional user
37 and group entries. Whenever a file is created or its mode is changed by
38 chmod(1) or chmod(2), the mask is recomputed. It is recomputed to be
39 the group permission defined in the mode passed to chmod(2).
40
41
42 The POSIX-draft ACL model uses the standard rwx model of traditional
43 UNIX permissions.
44
45
46 An ACL is represented as follows:
47
48 acl_entry[,acl_entry]...
49
50
51
52
53 Each acl_entry contains one ACL entry. An ACL entry is represented by
54 two or three colon-separated(:) fields.
55
56 user:[uid]:perms
57 If uid blank, it represents the file owner.
58
59
61 If gid is blank, it represents the owning group.
62
63
64 other:perms
65 Represents the file other class.
66
67
68 mask:perms
69 Defines the MAX permission to hand out.
70
71
72
73 For example to give user joe read and write permissions, the ACL entry
74 is specified as:
75
76 user:joe:rw-
77
78
79
80 NFSv4 ACLs
81 NFSv4 ACL model is based loosely on the Windows NT ACL model. NFSv4
82 ACLs provide a much richer ACL model than POSIX-draft ACLs.
83
84
85 The major differences between NFSv4 and POSIX-draft ACLs are as
86 follows:
87
88 o NFSv4 ACLs provide finer grained permissions than the rwx
89 model.
90
91 o NFSv4 ACLs allow for both ALLOW and DENY entries.
92
93 o NFSv4 ACLs provide a rich set of inheritance semantics.
94 POSIX ACLs also have inheritance, but with the NFSv4 model
95 you can control the following inheritance features:
96
97 o Whether inheritance cascades to both files and
98 directories or only to files or directories.
99
100 o In the case of directories, you can indicate whether
101 inheritance is applied to the directory itself, to just
102 one level of subdirectories, or cascades to all
103 subdirectories of the directory.
104
105 o NFSv4 ACLs provide a mechanism for hooking into a system's
106 audit trail. Currently, Solaris does not support this
107 mechanism.
108
109 o NFSv4 ACLs enable administrators to specify the order in
110 which ACL entries are checked. With POSIX-draft ACLs the
111 file system reorders ACL entries into a well defined, strict
112 access, checking order.
113
114
115 POSIX-draft ACL semantics can be achieved with NFSv4 ACLs. However,
116 only some NFSv4 ACLs can be translated to equivalent POSIX-draft ACLs.
117
118
119 Permissions can be specified in three different chmod ACL formats:
120 verbose, compact, or positional. The verbose format uses words to
121 indicate that the permissions are separated with a forward slash (/)
122 character. Compact format uses the permission letters and positional
123 format uses the permission letters or the hyphen (-) to identify no
124 permissions.
125
126
325 user:fred:rw------R------:file_inherit:allow
326
327
328
329
330 Or you can remove the - and scrunch it together.
331
332 user:fred:rwR:file_inherit:allow
333
334
335
336
337 The inheritance flags can also be specified in a more compact manner,
338 as follows:
339
340 user:fred:rwR:f:allow
341 user:fred:rwR:f------:allow
342
343
344
345 Shell-level Solaris API
346 The Solaris command interface supports the manipulation of ACLs. The
347 following Solaris utilities accommodate both ACL models:
348
349 chmod
350 The chmod utility has been enhanced to allow for the
351 setting and deleting of ACLs. This is achieved by extending
352 the symbolic-mode argument to support ACL manipulation. See
353 chmod(1) for details.
354
355
356 compress
357 When a file is compressed any ACL associated with the
358 original file is preserved with the compressed file.
359
360
361 cp
362 By default, cp ignores ACLs, unless the -p option is
363 specified. When -p is specified the owner and group id,
364 permission modes, modification and access times, ACLs, and
365 extended attributes if applicable are preserved.
366
367
392 file is preserved with the packed file.
393
394
395 rcp
396 rcp has been enhanced to support copying. A file's ACL is
397 only preserved when the remote host supports ACLs.
398
399
400 tar
401 ACLs are preserved when the -p option is specified.
402
403
404 unpack
405 When a file with an ACL is unpacked, the unpacked file
406 retains the ACL information.
407
408
409 Application-level API
410 The primary interfaces required to access file system ACLs at the
411 programmatic level are the acl_get() and acl_set() functions. These
412 functions support both POSIX draft ACLs and NFSv4 ACLs.
413
414 Retrieving a file's ACL
415 int acl_get(const char *path, int flag, acl_t **aclp);
416 int facl_get(int fd, int flag, acl_t **aclp);
417
418
419
420 The acl_get(3SEC) and facl_get(3SEC) functions retrieves an ACL on a
421 file whose name is given by path or referenced by the open file
422 descriptor fd. The flag argument specifies whether a trivial ACL should
423 be retrieved. When the flag argument equals ACL_NO_TRIVIAL then only
424 ACLs that are not trivial are retrieved. The ACL is returned in the
425 aclp argument.
426
427 Freeing ACL structure
428 void acl_free(acl_t *aclp)s;
429
430
431
432 The acl_free() function frees up memory allocated for the argument
433 aclp;.
434
435 Setting an ACL on a file
436 int acl_set(const char *path, acl_t *aclp);
437 int facl_set(int fd, acl_t *aclp);
438
439
440
441 The acl_set(3SEC) and facl_get(3SEC) functions are used for setting an
442 ACL on a file whose name is given by path or referenced by the open
443 file descriptor fd. The aclp argument specifies the ACL to set. The
444 acl_set(3SEC) translates an POSIX-draft ACL into a NFSv4 ACL when the
445 target file systems supports NFSv4 ACLs. No translation is performed
446 when trying to set an NFSv4 ACL on a POSIX-draft ACL supported file
447 system.
448
449 Determining an ACL's trivialness
450 int acl_trivial(const char *path);
451
452
453
454 The acl_trivial() function is used to determine whether a file has a
455 trivial ACL.
456
457 Removing all ACLs from a file
458 int acl_strip(const char *path, uid_t uid, gid_t gid, mode_t mode);
459
460
461
462 The acl_strip() function removes all ACLs from a file and replaces them
463 with a trivial ACL based off of the passed in argument mode. After
464 replacing the ACL the owner and group of the file are set to the values
465 specified in the uid and gid parameters.
466
467 Converting ACLs to/from external representation
468 int acl_fromtext(const char *path, acl_t **aclp);
469 char *acl_totext(acl_t *aclp, int flags);
470
471
472
473 The acl_totext() function converts an internal ACL representation
474 pointed to by aclp into an external representation. See DESCRIPTION for
475 details about external representation.
476
477
478 The acl_fromtext() functions converts and external representation into
479 an internal representation. See DESCRIPTION for details about external
480 representation.
481
482 EXAMPLES
483 The following examples demonstrate how the API can be used to perform
484 basic operations on ACLs.
485
486 Example 1 Retrieving and Setting an ACL
487
488
489 Use the following to retrieve an ACL and set it on another file:
490
491
492 error = acl_get("file", ACL_NO_TRIVIAL, &aclp);
493
494 if (error == 0 && aclp != NULL) {
495 error = acl_set("file2", aclp);
496 acl_free(aclp);
497 }
498 ...
499
531
532 Example 4 Removing all ACLs from a File
533
534
535 Use the following to remove all ACLs from a file, and set a new mode,
536 owner, and group:
537
538
539 error = acl_strip("file", 10, 100, 0644);
540 ...
541
542
543 SEE ALSO
544 chgrp(1), chmod(1), chown(1), cp(1), cpio(1), find(1), ls(1), mv(1),
545 tar(1), setfacl(1), chmod(2), acl(2), stat(2), acl_get(3SEC),
546 aclsort(3SEC), acl_fromtext(3SEC), acl_free(3SEC), acl_strip(3SEC),
547 acl_trivial(3SEC)
548
549
550
551 November 24, 2014 ACL(5)
|
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
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
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
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
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)
|