The primary rules of ACL access on a ZFS file are as follows:
ZFS processes ACL entries in the order they are listed in the ACL, from the top down.
Only ACL entries where the specified user matches the requester of the access are processed.
Once an allow permission has been granted, it cannot be denied by a subsequent ACL deny entry in the same ACL permission set.
The owner of the file is granted the write_acl permission unconditionally even if the permission is explicitly denied. Otherwise, any permission left unspecified is denied.
In the cases of deny permissions or when an access permission is missing, the PRIV_FILE* privileges determine access. The privileges mechanism prevents file owners from getting locked out of their files and enables superuser to modify files for recovery purposes. For more information, see the privileges(5) man page.
To set or modify ACLs, use the chmod command. The command syntax resembles the syntax for setting permission bits on files, except that you type A before typing the operator (+, =, or -).
chmod command syntax for trivial ACLs
chmod [options] A[index]{+|=}owner@ |group@ |everyone@: \
access-permissions/...[:inheritance-flags]:deny | allow file
chmod [options] A-owner@, group@, everyone@: \ access-permissions/...[:inheritance-flags]:deny | allow file ...
chmod [options] A[index]- file
chmod command syntax for non-trivial ACLs
chmod [options] A[index]{+|=}user|group:name: \
access-permissions/...[:inheritance-flags]:deny | allow file
chmod [options] A-user|group:name: \ access-permissions/...[:inheritance-flags]:deny | allow file ...
chmod [options] A[index]- file
The chmod command uses the following operators for ACLs:
A+ adds an ACL entry. An+ adds the ACL for the specified index number.
For example, chmod A+ adds an ACL entry, while chmod A3+ adds an ACL entry to index number 3.
A= replaces the ACL. An= replaces the ACL of the specified index number.
For example, chmod A= replaces an entire ACL, while chmod A3= replaces only the existing ACL entry of index number 3.
A- removes an ACL entry. Use this command syntax to restore a trivial ACL to the file. After you issue the command, only the entries for owner@, group@, and everyone@ that comprise a trivial ACL remain.
An- removes the ACL from the specified index number. For example, chmod A3- removes the existing ACL entry from index number 3.
Permissions and inheritance flags are represented by unique letters listed in the NFSv4 ACLs section of the acl(5). When you set ZFS ACLs, you can either use the letters that correspond to those permissions (compact mode) or type the permissions in full (verbose mode).
Example 8 Setting ACLs on Files and DirectoriesThe following examples illustrate the use of the chmod command to set ACLs on a file.
The following two commands are equivalent. The first command uses the compact mode of the permission. Each command grants read and execute permissions to user Tamiko on file.1.
$ chmod A+user:tamiko:rx:allow file.1 $ chmod A+user:tamiko:read_data/execute:allow file.1
Similarly, the following command grants user Tamiko inheritable read, write, and execute permissions for the newly created dir.2 and its files.
$ chmod A+user:tamiko:rwx:fd:allow dir.2
The verbose mode of the permission grants the same access.
$ chmod A+user:tamiko:list_directory/write_data/execute:file_inherit/dir_inherit:allow dir.2
The use of the A+ operator enables group@ to write data to file.1 and does not affect existing ACL entries.
$ chmod A+group@:w:allow file.1Example 9 Replacing ACLs
The use of the A= operator removes existing ACL entries for file.1 and replaces them with the single entry for everyone@. This entry removes the remaining default permissions (read_xattr/read_attributes/read_acl/synchronize:allow) for everyone@.
$ chmod A=everyone@:rx:allow file.1Example 10 Removing ACLs
The following examples illustrate the use of the chmod command to remove ACLs from a file.
This example removes all non-trivial ACL entries for a file without listing each entry to be removed.
$ chmod A- file.1
In the following example, the owner grants read_data/write_data permissions to group@. This command removes the other default permissions, read_xattr/read_attributes/read_acl/synchronize:allow.
$ chmod A1=group@:read_data/write_data:allow file.1 $ ls -v file.1 -rw-rw-r-- 1 root root 206695 Jul 20 13:43 file.1 0:owner@:read_data/write_data/append_data/read_xattr/write_xattr /read_attributes/write_attributes/read_acl/write_acl/write_owner /synchronize:allow 1:group@:read_data/write_data:allow 2:everyone@:read_data/read_xattr/read_attributes/read_acl/synchronize :allowExample 11 Removing an Added ACL Entry by Index Number
In the following example, read_data/execute permissions are added for the user Alice on the test.dir directory. Alice's entry is index number 0.
$ chmod A0+user:alice:read_data/execute:allow test.dir $ ls -dv test.dir drwxr-xr-x+ 2 root root 2 Jul 20 14:23 test.dir 0:user:alice:list_directory/read_data/execute:allow 1:owner@:list_directory/read_data/add_file/write_data/add_subdirectory /append_data/read_xattr/write_xattr/execute/delete_child /read_attributes/write_attributes/read_acl/write_acl/write_owner /synchronize:allow 2:group@:list_directory/read_data/read_xattr/execute/read_attributes /read_acl/synchronize:allow 3:everyone@:list_directory/read_data/read_xattr/execute/read_attributes /read_acl/synchronize:allow
In the following example, access permissions are removed for user Alice by using the index number of her ACL entry.
$ chmod A0- test.dir $ ls -dv test.dir drwxr-xr-x 2 root root 2 Jul 20 14:23 test.dir 0:owner@:list_directory/read_data/add_file/write_data/add_subdirectory /append_data/read_xattr/write_xattr/execute/delete_child /read_attributes/write_attributes/read_acl/write_acl/write_owner /synchronize:allow 1:group@:list_directory/read_data/read_xattr/execute/read_attributes /read_acl/synchronize:allow 2:everyone@:list_directory/read_data/read_xattr/execute/read_attributes /read_acl/synchronize:allow
$ chmod A3=everyone@:list_directory/read_data/read_xattr/execute/read_attributes \
/read_acl/synchronize:allow:failed_access:audit dir1
$ ls -v
total 1
drwxr-xr-x 2 foo staff 2 Feb 1 19:28 dir1
0:everyone@:list_directory/read_data/read_attributes/read_acl:failed_access:audit
1:owner@:list_directory/read_data/add_file/write_data/add_subdirectory
/append_data/read_xattr/write_xattr/execute/delete_child
/read_attributes/write_attributes/read_acl/write_acl/write_owner
/synchronize:allow
2:group@:list_directory/read_data/read_xattr/execute/read_attributes
/read_acl/synchronize:allow
3:everyone@:list_directory/read_data/read_xattr/execute/read_attributes
/read_acl/synchronize:allow
With the ls command, you can display ACL information in one of two formats. The –v option displays the permissions in full or verbose form. The –V option generates compact output by using letters that represent the permissions and flags.
Example 12 Displaying ACLs in Compact and Verbose FormatThe following example shows how the same ACL information is displayed in verbose format and compact format:
$ ls -v file.1 -rw-r--r-- 1 root root 206695 Jul 20 14:27 file.1 0:owner@:read_data/write_data/append_data/read_attributes /write_xattr/read_xattr/write_attributes/read_acl/write_acl /write_owner/synchronize:allow 1:group@:read_data/read_attributes/read_xattr/read_acl /synchronize:allow 2:everyone@:read_data/append_data/read_xattr/read_acl /synchronize:allow $ ls -V file.1 -rw-r--r-- 1 root root 206695 Jul 20 14:27 file.1 owner@:rw-p--aARWcCos:-------:allow group@:r-----a-R-c--s:-------:allow everyone@:r-----a-R-c--s:-------:allow
For a description of ACL access privileges, see the NFSv4 ACLs section of the acl(5) man page.
In ZFS files, the UNIX permission bits correspond to the ACL entries, but are cached. When you change a file's permission bits, the file's ACL is updated accordingly. Likewise, modifying a file's ACL causes changes in the permission bits.
For more information about permission bits, see chmod(1).
The following examples show the relationship between a file or directory's ACLs and the permission bits and how permission changes in one affect the other.
Example 13 Showing How ACLs and Permission Bits InteractThe first example begins with the following ACL for file.2. The permission bits, 644, display as -rw-r--r--.
$ ls -v file.2 -rw-r--r-- 1 root root 2693 Jul 20 14:26 file.2 0:owner@:read_data/write_data/append_data/read_xattr/write_xattr /read_attributes/write_attributes/read_acl/write_acl/write_owner /synchronize:allow 1:group@:read_data/read_xattr/read_attributes/read_acl/synchronize:allow 2:everyone@:read_data/read_xattr/read_attributes/read_acl/synchronize:allow
The chmod command removes the ACL entry for everyone@. Accordingly, the read permission for everyone is also removed, so the permission bits change to 640, which display as -rw-r-----.
$ chmod A2- file.2 $ ls -v file.2 -rw-r----- 1 root root 2693 Jul 20 14:26 file.2 0:owner@:read_data/write_data/append_data/read_xattr/write_xattr /read_attributes/write_attributes/read_acl/write_acl/write_owner /synchronize:allow 1:group@:read_data/read_xattr/read_attributes/read_acl/synchronize:allow
Next, the ACL is replaced with just read_data/write_data permissions for everyone@. Because no owner@ or group@ ACL entry exists to override the permissions for owner and group, the permission bits become 666, which display as -rw-rw-rw-.
$ chmod A=everyone@:rw:allow file.2
$ ls -v file.2
-rw-rw-rw- 1 root root 2440 Jul 20 14:28 file.3Permission bits become 666.
0:everyone@:read_data/write_data:allow
If you replace this ACL with read permissions just for user Alice, the file will become inaccessible because no trivial ACL entries exist. Consequently, the permission bits are set to 000, which denies Alice access to file.2, as well as denies access to everyone else.
$ chmod A=user:alice:r:allow file.2 $ ls -v file.2 ----------+ 1 root root 2440 Jul 20 14:28 file.3 0:user:alice:read_data:allow
If you set the permission bits for an inaccessible file, the default trivial ACL permissions are reset. The following command sets the bits for file.2 to 655. Automatically, the default trivial ACL permissions are set. Because the permission bits are set to 655, the owner is denied execute access.
$ pfexec chmod 655 file.2 $ ls -v file.3 -rw-r-xr-x 1 root root 2440 Jul 20 14:28 file.3 0:user:alice:read_data:allow 1:owner@:execute:deny 2:owner@:read_data/write_data/append_data/read_xattr/write_xattr /read_attributes/write_attributes/read_acl/write_acl/write_owner/synchronize:allow 3:group@:read_data/read_xattr/execute/read_attributes/read_acl/synchronize:allow 4:everyone@:read_data/read_xattr/execute/read_attributes/read_acl/synchronize:allowExample 14 Showing the Effects of the aclmode and aclinherit Properties on ACL Permissions
The following examples illustrate how specific aclmode and aclinherit property values affect ACL behavior. If these properties are set, ACL permissions for a file or directory are either reduced or expanded to be consistent with the owning group.
In this example, the administrator who runs the zfs set commands must be assigned the ZFS File System Management rights profile. To run the chown command, the administrator is assigned the Object Access Management rights profile.
Suppose that the aclmode property is set to mask and the aclinherit property is set to restricted in the pool, and that the original file and group ownership and ACL permissions are as follows:
$ pfbash ; zfs set aclmode=mask system1/data $ zfs set aclinherit=restricted system1/data $ ls -lV file.1 -rwxrwx---+ 1 root root 206695 Aug 30 16:03 file.1 user:amy:r-----a-R-c---:-------:allow user:rory:r-----a-R-c---:-------:allow group:sysadmin:rw-p--aARWc---:-------:allow group:staff:rw-p--aARWc---:-------:allow owner@:rwxp--aARWcCos:-------:allow group@:rwxp--aARWc--s:-------:allow everyone@:------a-R-c--s:-------:allow
To understand the meaning of the values set for the two properties, see ACL Properties.
A chown operation changes the ownership of file.1 to Amy and the group Staff.
$ chown amy:staff file.1
Amy then changes the permission bits for file.1 to 640. Because the ACL properties were previously set, the permissions for the groups in the ACL are reduced so that they do not exceed the permissions of the owning Staff.
$ su - amy $ chmod 640 file.1 $ ls -lV file.1 -rw-r-----+ 1 amy staff 206695 Aug 30 16:03 file.1 user:amy:r-----a-R-c---:-------:allow user:rory:r-----a-R-c---:-------:allow group:sysadmin:r-----a-R-c---:-------:allow group:staff:r-----a-R-c---:-------:allow owner@:rw-p--aARWcCos:-------:allow group@:r-----a-R-c--s:-------:allow everyone@:------a-R-c--s:-------:allow
Amy then changes the permission bits to 770. Consequently, the permissions of the groups in the ACL are also changed to match the permission of the owning group Staff.
$ chmod 770 file.1 $ ls -lV file.1 -rwxrwx---+ 1 amy staff 206695 Aug 30 16:03 file.1 user:amy:r-----a-R-c---:-------:allow user:rory:r-----a-R-c---:-------:allow group:sysadmin:rw-p--aARWc---:-------:allow group:staff:rw-p--aARWc---:-------:allow owner@:rwxp--aARWcCos:-------:allow group@:rwxp--aARWc--s:-------:allow everyone@:------a-R-c--s:-------:allow