1acl(5) Standards, Environments, and Macros acl(5)
2
6 acl - Access Control Lists
7
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 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 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 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 fur‐
29 ther restrict access to files and directories or to extend permissions
30 to a particular user. ACLs can be used to change the permissions for
31 the standard owner, group and other class bits of a file's mode. ACLs
32 can give additional users and groups access to the file. A directory
33 can also have a special kind of ACL called a default ACL, which defines
34 ACL entries to be inherited by descendents of the directory. POSIX-
35 draft ACLs have an ACL entry called mask. The mask defines the maximum
36 permissions that can be granted to additional user and group entries.
37 Whenever a file is created or its mode is changed by chmod(1) or
38 chmod(2), the mask is recomputed. It is recomputed to be the group per‐
39 mission defined in the mode passed to chmod(2).
40 The POSIX-draft ACL model uses the standard rwx model of traditional
43 UNIX permissions.
44 An ACL is represented as follows:
47 acl_entry[,acl_entry]...
49 Each acl_entry contains one ACL entry. An ACL entry is represented by
54 two or three colon-separated(:) fields.
55 user:[uid]:perms If uid blank, it represents the file owner.
57 group:[gid]:perms If gid is blank, it represents the owning group.
60 other:perms Represents the file other class.
63 mask:perms Defines the MAX permission to hand out.
66 For example to give user joe read and write permissions, the ACL entry
70 is specified as:
71 user:joe:rw-
73 NFSv4 ACLs
77 NFSv4 ACL model is based loosely on the Windows NT ACL model. NFSv4
78 ACLs provide a much richer ACL model than POSIX-draft ACLs.
79 The major differences between NFSv4 and POSIX-draft ACLs are as fol‐
82 lows:
83 o NFSv4 ACLs provide finer grained permissions than the rwx
85 model.
86 o NFSv4 ACLs allow for both ALLOW and DENY entries.
88 o NFSv4 ACLs provide a rich set of inheritance semantics.
90 POSIX ACLs also have inheritance, but with the NFSv4 model
91 you can control the following inheritance features:
92 o Whether inheritance cascades to both files and directo‐
94 ries or only to files or directories.
95 o In the case of directories, you can indicate whether
97 inheritance is applied to the directory itself, to just
98 one level of subdirectories, or cascades to all subdi‐
99 rectories of the directory.
100 o NFSv4 ACLs provide a mechanism for hooking into a system's
102 audit trail. Currently, Solaris does not support this mecha‐
103 nism.
104 o NFSv4 ACLs enable adminstrators to specify the order in
106 which ACL entries are checked. With POSIX-draft ACLs the
107 file system reorders ACL entries into a well defined, strict
108 access, checking order.
109 POSIX-draft ACL semantics can be achieved with NFSv4 ACLs. However,
112 only some NFSv4 ACLs can be translated to equivalent POSIX-draft ACLs.
113 Permissions can be specified in three different chmod ACL formats: ver‐
116 bose, compact, or positional. The verbose format uses words to indicate
117 that the permissions are separated with a forward slash (/) character.
118 Compact format uses the permission letters and positional format uses
119 the permission letters or the hypen (-) to identify no permissions.
120 The permissions for verbose mode and their abbreviated form in paren‐
123 theses for compact and positional mode are described as follows:
124 read_data (r) Permission to read the data of the file
126 list_directory (r) Permission to list the contents of a directory.
129 write_data (w) Permission to modify a file's data anywhere in
132 the file's offset range. This includes the
133 ability to grow the file or write to any arbi‐
134 trary offset.
135 add_file (w) Permission to add a new file to a directory.
138 append_data (p) The ability to modify the file's data, but only
141 starting at EOF. Currently, this permission is
142 not supported.
143 add_subdirectory (p) Permission to create a subdirectory to a direc‐
146 tory.
147 read_xattr (R) The ability to read the extended attributes of
150 a file or do a lookup in the extended
151 attributes directory.
152 write_xattr (W) The ability to create extended attributes or
155 write to the extended attributes directory.
156 execute (x) Permission to execute a file.
159 read_attributes (a) The ability to read basic attributes (non-ACLs)
162 of a file. Basic attributes are considered to
163 be the stat level attributes. Allowing this
164 access mask bit means that the entity can exe‐
165 cute ls(1) and stat(2).
166 write_attributes (A) Permission to change the times associated with
169 a file or directory to an arbitrary value.
170 delete (d) Permission to delete the file.
173 delete_child (D) Permission to delete a file within a directory.
176 read_acl (c) Permission to read the ACL.
179 write_acl (C) Permission to write the ACL or the ability to
182 execute chmod(1) or setfacl(1).
183 write_owner (o) Permission to change the owner or the ability
186 to execute chown(1) or chgrp(1).
187 synchronize (s) Permission to access a file locally at the
190 server with synchronous reads and writes. Cur‐
191 rently, this permission is not supported.
192 The following inheritance flags are supported by NFSv4:
196 file_inherit (f) Inherit to all newly created files in a
198 directory.
199 dir_inherit (d) Inherit to all newly created directories in a
202 directory.
203 inherit_only (i) Placed on a directory, but does not apply to
206 the directory itself, only to newly created
207 created files and directories. This flag
208 requires file_inherit and or dir_inherit to
209 indicate what to inherit.
210 no_propagate (n) Placed on directories and indicates that ACL
213 entries should only be inherited one level of
214 the tree. This flag requires file_inherit and
215 or dir_inherit to indicate what to inherit.
216 successful_access (S)) Indicates if an alarm or audit record should
219 be initiated upon successful accesses. Used
220 with audit/alarm ACE types.
221 failed_access (F) Indicates if an alarm or audit record should
224 be initiated when access fails. Used with
225 audit/alarm ACE types.
226 inherited (I) ACE was inherited.
229 - No permission granted.
232 An NFSv4 ACL is expressed using the following syntax:
236 acl_entry[,acl_entry]...
238 owner@:<perms>[:inheritance flags]:<allow|deny>
240 group@:<perms>[:inheritance flags]:<allow|deny>
241 everyone@:<perms>[:inheritance flags]:<allow|deny>
242 user:<username>[:inheritance flags]:<allow|deny>
243 group:<groupname>[:inheritance flags]:<allow|deny>
244 owner@ File owner
247 group@ Group owner
250 user Permissions for a specific user
253 group Permissions for a specific group
256 Permission and inheritance flags are separated by a / character.
260 ACL specification examples:
263 user:fred:read_data/write_data/read_attributes:file_inherit:allow
265 owner@:read_data:allow,group@:read_data:allow,user:tom:read_data:deny
266 Using the compact ACL format, permissions are specified by using 14
271 unique letters to indicate permissions.
272 Using the positional ACL format, permissions are specified as posi‐
275 tional arguments similar to the ls -V format. The hyphen (-), which
276 indicates that no permission is granted at that position, can be omit‐
277 ted and only the required letters have to be specified.
278 The letters above are listed in the order they would be specified in
281 positional notation.
282 With these letters you can specify permissions in the following equiva‐
285 lent ways.
286 user:fred:rw------R------:file_inherit:allow
288 Or you can remove the - and scrunch it together.
293 user:fred:rwR:file_inherit:allow
295 The inheritance flags can also be specified in a more compact manner,
300 as follows:
301 user:fred:rwR:f:allow
303 user:fred:rwR:f------:allow
304 Shell-level Solaris API
308 The Solaris command interface supports the manipulation of ACLs. The
309 following Solaris utilities accommodate both ACL models:
310 chmod The chmod utility has been enhanced to allow for the set‐
312 ting and deleting of ACLs. This is achieved by extending
313 the symbolic-mode argument to support ACL manipulation. See
314 chmod(1) for details.
315 compress When a file is compressed any ACL associated with the orig‐
318 inal file is preserved with the compressed file.
319 cp By default, cp ignores ACLs, unless the -p option is speci‐
322 fied. When -p is specified the owner and group id, permis‐
323 sion modes, modification and access times, ACLs, and
324 extended attributes if applicable are preserved.
325 cpio ACLs are preserved when the -P option is specified.
328 find Find locates files with ACLs when the -acl flag is speci‐
331 fied.
332 ls By default ls does not display ACL information. When the -v
335 option is specified, a file's ACL is displayed.
336 mv When a file is moved, all attributes are carried along with
339 the renamed file. When a file is moved across a file system
340 boundary, the ACLs are replicated. If the ACL information
341 cannot be replicated, the move fails and the source file is
342 not removed.
343 pack When a file is packed, any ACL associated with the original
346 file is preserved with the packed file.
347 rcp rcp has been enhanced to support copying. A file's ACL is
350 only preserved when the remote host supports ACLs.
351 tar ACLs are preserved when the -p option is specified.
354 unpack When a file with an ACL is unpacked, the unpacked file
357 retains the ACL information.
358 Application-level API
361 The primary interfaces required to access file system ACLs at the pro‐
362 grammatic level are the acl_get() and acl_set() functions. These func‐
363 tions support both POSIX draft ACLs and NFSv4 ACLs.
364 Retrieving a file's ACL
366 int acl_get(const char *path, int flag, acl_t **aclp);
367 int facl_get(int fd, int flag, acl_t **aclp);
368 The acl_get(3SEC) and facl_get(3SEC) functions retrieves an ACL on a
372 file whose name is given by path or referenced by the open file
373 descriptor fd. The flag argument specifies whether a trivial ACL should
374 be retrieved. When the flag argument equals ACL_NO_TRIVIAL then only
375 ACLs that are not trivial are retrieved. The ACL is returned in the
376 aclp argument.
377 Freeing ACL structure
379 void acl_free(acl_t *aclp)s;
380 The acl_free() function frees up memory allocated for the argument
384 aclp;.
385 Setting an ACL on a file
387 int acl_set(const char *path, acl_t *aclp);
388 int facl_set(int fd, acl_t *aclp);
389 The acl_set(3SEC) and facl_get(3SEC) functions are used for setting an
393 ACL on a file whose name is given by path or referenced by the open
394 file descriptor fd. The aclp argument specifies the ACL to set. The
395 acl_set(3SEC) translates an POSIX-draft ACL into a NFSv4 ACL when the
396 target file systems supports NFSv4 ACLs. No translation is performed
397 when trying to set an NFSv4 ACL on a POSIX-draft ACL supported file
398 system.
399 Determining an ACL's trivialness
401 int acl_trivial(const char *path);
402 The acl_trivial() function is used to determine whether a file has a
406 trivial ACL. The trivialness of a file's ACL depends on the type of ACL
407 it is. For POSIX-draft ACLs, it implies the ACL has greater than
408 MIN_ACL_ENTRIES. For NFSv4/ZFS style ACLs, it implies that the ACL has
409 entries other than owner@, group@ and everyone@, inheritance flags are
410 set, or the ACL is not ordered in a manner that meets POSIX access con‐
411 trol requirements.
412 Removing all ACLs from a file
414 int acl_strip(const char *path, uid_t uid, gid_t gid, mode_t mode);
415 The acl_strip() function removes all ACLs from a file and replaces them
419 with a trivial ACL based off of the passed in argument mode. After
420 replacing the ACL the owner and group of the file are set to the values
421 specified in the uid and gid parameters.
422 Converting ACLs to/from external representation
424 int acl_fromtext(const char *path, acl_t **aclp);
425 char *acl_totext(acl_t *aclp, int flags);
426 The acl_text() function converts an internal ACL representation pointed
430 to by aclp into an external representation. See DESCRIPTION for details
431 about external representation.
432 The acl_fromtext() functions converts and external representation into
435 an internal representation. See DESCRIPTION for details about external
436 representation.
437
439 The following examples demonstrate how the API can be used to perform
440 basic operations on ACLs.
441 Example 1 Retrieving and Setting an ACL
443 Use the following to retrieve an ACL and set it on another file:
446 error = acl_get("file", ACL_NO_TRIVIAL, &aclp);
449 if (error == 0 && aclp != NULL) {
451 error = acl_set("file2", aclp)
452 acl_free(aclp);
453 }
454 ...
455 Example 2 Retrieving and Setting Any ACLs
458 Use the following to retrieve any ACL, including trivial ACLs, and set
461 it on another file:
462 error = acl_get("file3", 0, &aclp);
465 if (error == 0) {
466 error = acl_set("file4", aclp)
467 acl_free(aclp);
468 }
469 ...
470 Example 3 Determining if a File has a Trivial ACL
473 Use the following to determine if a file has a trivial ACL:
476 istrivial = acl_trivial("file")
479 if (istrivial == 0)
481 printf("file %s has a trivial ACL0, file);
482 else
483 printf("file %s has a NON-trivial ACL0, file);
484 ...
485 Example 4 Removing all ACLs from a File
488 Use the following to remove all ACLs from a file, and set a new mode,
491 owner, and group:
492 error = acl_strip("file", 10, 100, 0644);
495 ...
496
499 chgrp(1), chmod(1), chown(1), cp(1), cpio(1), find(1), ls(1), mv(1),
500 tar(1), setfacl(1), chmod(2), acl(2),stat(2),acl_get(3SEC),
501 aclsort(3SEC), acl_fromtext(3SEC), acl_free(3SEC), acl_strip(3SEC),
502 acl_trivial(3SEC)
503SunOS 5.11 29 Sep 2008 acl(5)