1 '\" te
2 .\" Copyright 2014 Nexenta Systems, Inc. All rights reserved.
3 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH ACL 5 "Nov 24, 2014"
8 .SH NAME
9 acl \- Access Control Lists
10 .SH DESCRIPTION
11 .LP
12 Access control lists (ACLs) are discretionary access control mechanisms that
13 grant and deny access to files and directories. Two different ACL models are
14 supported in the Solaris release: POSIX-draft ACLs and NFSv4 ACLs.
15 .sp
16 .LP
17 The older, POSIX-draft model is supported by the UFS file system. This model is
18 based on a withdrawn ACL POSIX specification that was never standardized. It
19 was subsequently withdrawn by the POSIX committee.
20 .sp
21 .LP
22 The other model is based on the standards of the NFSv4 working group and is an
23 approved standard from the Internet Engineering Task Force (IETF). The ZFS file
24 system uses the NFSv4 model, and provides richer semantics and finer grained
25 permission capabilities than the POSIX-draft model.
26 .SS "\fBPOSIX\fR-draft \fBACL\fRs"
27 .LP
28 POSIX-draft ACLs provide an alternative security mechanism to basic UNIX file
29 permissions in the Solaris release. Their purpose is to further restrict access
30 to files and directories or to extend permissions to a particular user. ACLs
31 can be used to change the permissions for the standard owner, group and other
32 class bits of a file's mode. ACLs can give additional users and groups access
33 to the file. A directory can also have a special kind of ACL called a
34 \fBdefault\fR ACL, which defines ACL entries to be inherited by descendents of
35 the directory. POSIX-draft ACLs have an ACL entry called \fBmask\fR. The mask
36 defines the maximum permissions that can be granted to additional user and
37 group entries. Whenever a file is created or its mode is changed by
38 \fBchmod\fR(1) or \fBchmod\fR(2), the mask is recomputed. It is recomputed to
39 be the group permission defined in the mode passed to \fBchmod\fR(2).
40 .sp
41 .LP
42 The POSIX-draft ACL model uses the standard \fBrwx\fR model of traditional UNIX
43 permissions.
44 .sp
45 .LP
46 An ACL is represented as follows:
47 .sp
48 .in +2
49 .nf
87 .ne 2
88 .na
89 \fB\fImask\fR:\fIperms\fR\fR
90 .ad
91 .RS 21n
92 Defines the \fBMAX\fR permission to hand out.
93 .RE
94
95 .sp
96 .LP
97 For example to give user \fBjoe\fR read and write permissions, the ACL entry is
98 specified as:
99 .sp
100 .in +2
101 .nf
102 user:joe:rw-
103 .fi
104 .in -2
105 .sp
106
107 .SS "\fBNFS\fRv4 \fBACL\fRs"
108 .LP
109 NFSv4 ACL model is based loosely on the Windows NT ACL model. NFSv4 ACLs
110 provide a much richer ACL model than POSIX-draft ACLs.
111 .sp
112 .LP
113 The major differences between NFSv4 and POSIX-draft ACLs are as follows:
114 .RS +4
115 .TP
116 .ie t \(bu
117 .el o
118 NFSv4 ACLs provide finer grained permissions than the \fBrwx\fR model.
119 .RE
120 .RS +4
121 .TP
122 .ie t \(bu
123 .el o
124 NFSv4 ACLs allow for both \fBALLOW\fR and \fBDENY\fR entries.
125 .RE
126 .RS +4
127 .TP
128 .ie t \(bu
129 .el o
134 .TP
135 .ie t \(bu
136 .el o
137 Whether inheritance cascades to both files and directories or only to files or
138 directories.
139 .RE
140 .RS +4
141 .TP
142 .ie t \(bu
143 .el o
144 In the case of directories, you can indicate whether inheritance is applied to
145 the directory itself, to just one level of subdirectories, or cascades to all
146 subdirectories of the directory.
147 .RE
148 .RE
149 .RS +4
150 .TP
151 .ie t \(bu
152 .el o
153 NFSv4 ACLs provide a mechanism for hooking into a system's audit trail.
154 Currently, Solaris does not support this mechanism.
155 .RE
156 .RS +4
157 .TP
158 .ie t \(bu
159 .el o
160 NFSv4 ACLs enable administrators to specify the order in which ACL entries are
161 checked. With POSIX-draft ACLs the file system reorders ACL entries into a well
162 defined, strict access, checking order.
163 .RE
164 .sp
165 .LP
166 POSIX-draft ACL semantics can be achieved with NFSv4 ACLs. However, only some
167 NFSv4 ACLs can be translated to equivalent POSIX-draft ACLs.
168 .sp
169 .LP
170 Permissions can be specified in three different \fBchmod\fR ACL formats:
171 verbose, compact, or positional. The verbose format uses words to indicate that
172 the permissions are separated with a forward slash (\fB/\fR) character. Compact
173 format uses the permission letters and positional format uses the permission
174 letters or the hyphen (\fB-\fR) to identify no permissions.
523 .in +2
524 .nf
525 user:fred:rwR:file_inherit:allow
526 .fi
527 .in -2
528 .sp
529
530 .sp
531 .LP
532 The inheritance flags can also be specified in a more compact manner, as
533 follows:
534 .sp
535 .in +2
536 .nf
537 user:fred:rwR:f:allow
538 user:fred:rwR:f------:allow
539 .fi
540 .in -2
541 .sp
542
543 .SS "Shell-level Solaris \fBAPI\fR"
544 .LP
545 The Solaris command interface supports the manipulation of ACLs. The following
546 Solaris utilities accommodate both ACL models:
547 .sp
548 .ne 2
549 .na
550 \fB\fBchmod\fR\fR
551 .ad
552 .RS 12n
553 The \fBchmod\fR utility has been enhanced to allow for the setting and deleting
554 of ACLs. This is achieved by extending the symbolic-mode argument to support
555 ACL manipulation. See \fBchmod\fR(1) for details.
556 .RE
557
558 .sp
559 .ne 2
560 .na
561 \fB\fBcompress\fR\fR
562 .ad
563 .RS 12n
564 When a file is compressed any ACL associated with the original file is
565 preserved with the compressed file.
566 .RE
639
640 .sp
641 .ne 2
642 .na
643 \fB\fBtar\fR\fR
644 .ad
645 .RS 12n
646 ACLs are preserved when the \fB-p\fR option is specified.
647 .RE
648
649 .sp
650 .ne 2
651 .na
652 \fB\fBunpack\fR\fR
653 .ad
654 .RS 12n
655 When a file with an ACL is unpacked, the unpacked file retains the ACL
656 information.
657 .RE
658
659 .SS "Application-level \fBAPI\fR"
660 .LP
661 The primary interfaces required to access file system ACLs at the programmatic
662 level are the \fBacl_get()\fR and \fBacl_set()\fR functions. These functions
663 support both POSIX draft ACLs and NFSv4 ACLs.
664 .SS "Retrieving a file's \fBACL\fR"
665 .in +2
666 .nf
667 int acl_get(const char *path, int flag, acl_t **aclp);
668 int facl_get(int fd, int flag, acl_t **aclp);
669 .fi
670 .in -2
671
672 .sp
673 .LP
674 The \fBacl_get\fR(3SEC) and \fBfacl_get\fR(3SEC) functions retrieves an ACL on
675 a file whose name is given by path or referenced by the open file descriptor
676 fd. The flag argument specifies whether a trivial ACL should be retrieved. When
677 the flag argument equals \fBACL_NO_TRIVIAL\fR then only ACLs that are not
678 trivial are retrieved. The ACL is returned in the \fBaclp\fR argument.
679 .SS "Freeing \fBACL\fR structure"
680 .in +2
681 .nf
682 void acl_free(acl_t *aclp)s;
683 .fi
684 .in -2
685
686 .sp
687 .LP
688 The \fBacl_free()\fR function frees up memory allocated for the argument
689 \fBaclp;\fR.
690 .SS "Setting an \fBACL\fR on a file"
691 .in +2
692 .nf
693 int acl_set(const char *path, acl_t *aclp);
694 int facl_set(int fd, acl_t *aclp);
695 .fi
696 .in -2
697
698 .sp
699 .LP
700 The \fBacl_set\fR(3SEC) and \fBfacl_get\fR(3SEC) functions are used for setting
701 an ACL on a file whose name is given by path or referenced by the open file
702 descriptor \fBfd\fR. The \fBaclp\fR argument specifies the ACL to set. The
703 \fBacl_set\fR(3SEC) translates an POSIX-draft ACL into a NFSv4 ACL when the
704 target file systems supports NFSv4 ACLs. No translation is performed when
705 trying to set an NFSv4 ACL on a POSIX-draft ACL supported file system.
706 .SS "Determining an \fBACL\fR's trivialness"
707 .in +2
708 .nf
709 int acl_trivial(const char *path);
710 .fi
711 .in -2
712
713 .sp
714 .LP
715 The \fBacl_trivial()\fR function is used to determine whether a file has a
716 trivial ACL.
717 .SS "Removing all \fBACL\fRs from a file"
718 .in +2
719 .nf
720 int acl_strip(const char *path, uid_t uid, gid_t gid, mode_t mode);
721 .fi
722 .in -2
723
724 .sp
725 .LP
726 The \fBacl_strip()\fR function removes all ACLs from a file and replaces them
727 with a trivial ACL based off of the passed in argument mode. After replacing
728 the ACL the owner and group of the file are set to the values specified in the
729 uid and gid parameters.
730 .SS "Converting \fBACL\fRs to/from external representation"
731 .in +2
732 .nf
733 int acl_fromtext(const char *path, acl_t **aclp);
734 char *acl_totext(acl_t *aclp, int flags);
735 .fi
736 .in -2
737
738 .sp
739 .LP
740 The \fBacl_totext()\fR function converts an internal ACL representation pointed
741 to by aclp into an external representation. See \fBDESCRIPTION\fR for details
742 about external representation.
743 .sp
744 .LP
745 The \fBacl_fromtext()\fR functions converts and external representation into an
746 internal representation. See \fBDESCRIPTION\fR for details about external
747 representation.
748 .SH EXAMPLES
749 .LP
750 The following examples demonstrate how the API can be used to perform basic
751 operations on ACLs.
752 .LP
753 \fBExample 1 \fRRetrieving and Setting an ACL
754 .sp
755 .LP
756 Use the following to retrieve an ACL and set it on another file:
757
758 .sp
759 .in +2
760 .nf
761 error = acl_get("file", ACL_NO_TRIVIAL, &aclp);
762
763 if (error == 0 && aclp != NULL) {
764 .in +8
765 error = acl_set("file2", aclp);
766 acl_free(aclp);
767 .in -8
768 }
769 \&...
814 \&...
815 .fi
816 .in -2
817
818 .LP
819 \fBExample 4 \fRRemoving all ACLs from a File
820 .sp
821 .LP
822 Use the following to remove all ACLs from a file, and set a new mode, owner,
823 and group:
824
825 .sp
826 .in +2
827 .nf
828 error = acl_strip("file", 10, 100, 0644);
829 \&...
830 .fi
831 .in -2
832
833 .SH SEE ALSO
834 .LP
835 \fBchgrp\fR(1), \fBchmod\fR(1), \fBchown\fR(1), \fBcp\fR(1), \fBcpio\fR(1),
836 \fBfind\fR(1), \fBls\fR(1), \fBmv\fR(1), \fBtar\fR(1), \fBsetfacl\fR(1),
837 \fBchmod\fR(2), \fBacl\fR(2), \fBstat\fR(2), \fBacl_get\fR(3SEC),
838 \fBaclsort\fR(3SEC), \fBacl_fromtext\fR(3SEC), \fBacl_free\fR(3SEC),
839 \fBacl_strip\fR(3SEC), \fBacl_trivial\fR(3SEC)
|
1 '\" te
2 .\" Copyright (c) 2020 Peter Tribble.
3 .\" Copyright 2014 Nexenta Systems, Inc. All rights reserved.
4 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
5 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
7 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
8 .TH ACL 5 "Feb 8, 2020"
9 .SH NAME
10 acl \- Access Control Lists
11 .SH DESCRIPTION
12 Access control lists (ACLs) are discretionary access control mechanisms that
13 grant and deny access to files and directories. Two different ACL models are
14 supported in this release: POSIX-draft ACLs and NFSv4 ACLs.
15 .sp
16 .LP
17 The older, POSIX-draft model is supported by the UFS file system. This model is
18 based on a withdrawn ACL POSIX specification that was never standardized. It
19 was subsequently withdrawn by the POSIX committee.
20 .sp
21 .LP
22 The other model is based on the standards of the NFSv4 working group and is an
23 approved standard from the Internet Engineering Task Force (IETF). The ZFS file
24 system uses the NFSv4 model, and provides richer semantics and finer grained
25 permission capabilities than the POSIX-draft model.
26 .SS "POSIX-draft ACLs"
27 POSIX-draft ACLs provide an alternative security mechanism to basic UNIX file
28 permissions. Their purpose is to further restrict access
29 to files and directories or to extend permissions to a particular user. ACLs
30 can be used to change the permissions for the standard owner, group and other
31 class bits of a file's mode. ACLs can give additional users and groups access
32 to the file. A directory can also have a special kind of ACL called a
33 \fBdefault\fR ACL, which defines ACL entries to be inherited by descendents of
34 the directory. POSIX-draft ACLs have an ACL entry called \fBmask\fR. The mask
35 defines the maximum permissions that can be granted to additional user and
36 group entries. Whenever a file is created or its mode is changed by
37 \fBchmod\fR(1) or \fBchmod\fR(2), the mask is recomputed. It is recomputed to
38 be the group permission defined in the mode passed to \fBchmod\fR(2).
39 .sp
40 .LP
41 The POSIX-draft ACL model uses the standard \fBrwx\fR model of traditional UNIX
42 permissions.
43 .sp
44 .LP
45 An ACL is represented as follows:
46 .sp
47 .in +2
48 .nf
86 .ne 2
87 .na
88 \fB\fImask\fR:\fIperms\fR\fR
89 .ad
90 .RS 21n
91 Defines the \fBMAX\fR permission to hand out.
92 .RE
93
94 .sp
95 .LP
96 For example to give user \fBjoe\fR read and write permissions, the ACL entry is
97 specified as:
98 .sp
99 .in +2
100 .nf
101 user:joe:rw-
102 .fi
103 .in -2
104 .sp
105
106 .SS "NFSv4 ACLs"
107 The NFSv4 ACL model is based loosely on the Windows NT ACL model. NFSv4 ACLs
108 provide a much richer ACL model than POSIX-draft ACLs.
109 .sp
110 .LP
111 The major differences between NFSv4 and POSIX-draft ACLs are as follows:
112 .RS +4
113 .TP
114 .ie t \(bu
115 .el o
116 NFSv4 ACLs provide finer grained permissions than the \fBrwx\fR model.
117 .RE
118 .RS +4
119 .TP
120 .ie t \(bu
121 .el o
122 NFSv4 ACLs allow for both \fBALLOW\fR and \fBDENY\fR entries.
123 .RE
124 .RS +4
125 .TP
126 .ie t \(bu
127 .el o
132 .TP
133 .ie t \(bu
134 .el o
135 Whether inheritance cascades to both files and directories or only to files or
136 directories.
137 .RE
138 .RS +4
139 .TP
140 .ie t \(bu
141 .el o
142 In the case of directories, you can indicate whether inheritance is applied to
143 the directory itself, to just one level of subdirectories, or cascades to all
144 subdirectories of the directory.
145 .RE
146 .RE
147 .RS +4
148 .TP
149 .ie t \(bu
150 .el o
151 NFSv4 ACLs provide a mechanism for hooking into a system's audit trail.
152 Currently, illumos does not support this mechanism.
153 .RE
154 .RS +4
155 .TP
156 .ie t \(bu
157 .el o
158 NFSv4 ACLs enable administrators to specify the order in which ACL entries are
159 checked. With POSIX-draft ACLs the file system reorders ACL entries into a well
160 defined, strict access, checking order.
161 .RE
162 .sp
163 .LP
164 POSIX-draft ACL semantics can be achieved with NFSv4 ACLs. However, only some
165 NFSv4 ACLs can be translated to equivalent POSIX-draft ACLs.
166 .sp
167 .LP
168 Permissions can be specified in three different \fBchmod\fR ACL formats:
169 verbose, compact, or positional. The verbose format uses words to indicate that
170 the permissions are separated with a forward slash (\fB/\fR) character. Compact
171 format uses the permission letters and positional format uses the permission
172 letters or the hyphen (\fB-\fR) to identify no permissions.
521 .in +2
522 .nf
523 user:fred:rwR:file_inherit:allow
524 .fi
525 .in -2
526 .sp
527
528 .sp
529 .LP
530 The inheritance flags can also be specified in a more compact manner, as
531 follows:
532 .sp
533 .in +2
534 .nf
535 user:fred:rwR:f:allow
536 user:fred:rwR:f------:allow
537 .fi
538 .in -2
539 .sp
540
541 .SS "Shell-level API"
542 Several utilities support the manipulation of ACLs. The following
543 utilities accommodate both ACL models:
544 .sp
545 .ne 2
546 .na
547 \fB\fBchmod\fR\fR
548 .ad
549 .RS 12n
550 The \fBchmod\fR utility has been enhanced to allow for the setting and deleting
551 of ACLs. This is achieved by extending the symbolic-mode argument to support
552 ACL manipulation. See \fBchmod\fR(1) for details.
553 .RE
554
555 .sp
556 .ne 2
557 .na
558 \fB\fBcompress\fR\fR
559 .ad
560 .RS 12n
561 When a file is compressed any ACL associated with the original file is
562 preserved with the compressed file.
563 .RE
636
637 .sp
638 .ne 2
639 .na
640 \fB\fBtar\fR\fR
641 .ad
642 .RS 12n
643 ACLs are preserved when the \fB-p\fR option is specified.
644 .RE
645
646 .sp
647 .ne 2
648 .na
649 \fB\fBunpack\fR\fR
650 .ad
651 .RS 12n
652 When a file with an ACL is unpacked, the unpacked file retains the ACL
653 information.
654 .RE
655
656 .SS "Application-level API"
657 The primary interfaces required to access file system ACLs at the programmatic
658 level are the \fBacl_get()\fR and \fBacl_set()\fR functions. These functions
659 support both POSIX-draft ACLs and NFSv4 ACLs.
660 .SS "Retrieving a file's ACL"
661 .in +2
662 .nf
663 int acl_get(const char *path, int flag, acl_t **aclp);
664 int facl_get(int fd, int flag, acl_t **aclp);
665 .fi
666 .in -2
667
668 .sp
669 .LP
670 The \fBacl_get\fR(3SEC) and \fBfacl_get\fR(3SEC) functions retrieve an ACL on
671 a file whose name is given by path or referenced by the open file descriptor
672 fd. The flag argument specifies whether a trivial ACL should be retrieved. When
673 the flag argument equals \fBACL_NO_TRIVIAL\fR only ACLs that are not
674 trivial are retrieved. The ACL is returned in the \fBaclp\fR argument.
675 .SS "Freeing ACL structure"
676 .in +2
677 .nf
678 void acl_free(acl_t *aclp);
679 .fi
680 .in -2
681
682 .sp
683 .LP
684 The \fBacl_free()\fR function frees up memory allocated for the argument
685 \fBaclp\fR.
686 .SS "Setting an ACL on a file"
687 .in +2
688 .nf
689 int acl_set(const char *path, acl_t *aclp);
690 int facl_set(int fd, acl_t *aclp);
691 .fi
692 .in -2
693
694 .sp
695 .LP
696 The \fBacl_set\fR(3SEC) and \fBfacl_get\fR(3SEC) functions are used for setting
697 an ACL on a file whose name is given by path or referenced by the open file
698 descriptor \fBfd\fR. The \fBaclp\fR argument specifies the ACL to set. The
699 \fBacl_set\fR(3SEC) function translates a POSIX-draft ACL into a NFSv4 ACL when
700 the target file system supports NFSv4 ACLs. No translation is performed when
701 trying to set an NFSv4 ACL on a POSIX-draft ACL supported file system.
702 .SS "Determining an ACL's trivialness"
703 .in +2
704 .nf
705 int acl_trivial(const char *path);
706 .fi
707 .in -2
708
709 .sp
710 .LP
711 The \fBacl_trivial()\fR function is used to determine whether a file has a
712 trivial ACL.
713 .SS "Removing all ACLs from a file"
714 .in +2
715 .nf
716 int acl_strip(const char *path, uid_t uid, gid_t gid, mode_t mode);
717 .fi
718 .in -2
719
720 .sp
721 .LP
722 The \fBacl_strip()\fR function removes all ACLs from a file and replaces them
723 with a trivial ACL based off of the passed in argument mode. After replacing
724 the ACL the owner and group of the file are set to the values specified in the
725 uid and gid parameters.
726 .SS "Converting ACLs to/from external representation"
727 .in +2
728 .nf
729 int acl_fromtext(const char *path, acl_t **aclp);
730 char *acl_totext(acl_t *aclp, int flags);
731 .fi
732 .in -2
733
734 .sp
735 .LP
736 The \fBacl_totext()\fR function converts an internal ACL representation pointed
737 to by aclp into an external representation. See \fBDESCRIPTION\fR for details
738 about external representation.
739 .sp
740 .LP
741 The \fBacl_fromtext()\fR function converts an external representation into an
742 internal representation. See \fBDESCRIPTION\fR for details about external
743 representation.
744 .SH EXAMPLES
745 The following examples demonstrate how the API can be used to perform basic
746 operations on ACLs.
747 .LP
748 \fBExample 1 \fRRetrieving and Setting an ACL
749 .sp
750 .LP
751 Use the following to retrieve an ACL and set it on another file:
752
753 .sp
754 .in +2
755 .nf
756 error = acl_get("file", ACL_NO_TRIVIAL, &aclp);
757
758 if (error == 0 && aclp != NULL) {
759 .in +8
760 error = acl_set("file2", aclp);
761 acl_free(aclp);
762 .in -8
763 }
764 \&...
809 \&...
810 .fi
811 .in -2
812
813 .LP
814 \fBExample 4 \fRRemoving all ACLs from a File
815 .sp
816 .LP
817 Use the following to remove all ACLs from a file, and set a new mode, owner,
818 and group:
819
820 .sp
821 .in +2
822 .nf
823 error = acl_strip("file", 10, 100, 0644);
824 \&...
825 .fi
826 .in -2
827
828 .SH SEE ALSO
829 \fBchgrp\fR(1), \fBchmod\fR(1), \fBchown\fR(1), \fBcp\fR(1), \fBcpio\fR(1),
830 \fBfind\fR(1), \fBls\fR(1), \fBmv\fR(1), \fBtar\fR(1), \fBsetfacl\fR(1),
831 \fBchmod\fR(2), \fBacl\fR(2), \fBstat\fR(2), \fBacl_get\fR(3SEC),
832 \fBaclsort\fR(3SEC), \fBacl_fromtext\fR(3SEC), \fBacl_free\fR(3SEC),
833 \fBacl_strip\fR(3SEC), \fBacl_trivial\fR(3SEC)
|