setfacl — Set, remove, and change access control lists (ACLs)

Format

setfacl [–ahqv] -s entries [path ... ]
setfacl [–ahqv] -S file [path ...
setfacl [–ahqv] -D type [...] [path ... ]
setfacl [–ahqv]  -m|M|x|X EntryOrFile [...] [path ... ]

Description

setfacl sets (replaces), modifies, or removes the access control list (ACL). It also updates and deletes ACL entries for each file and directory that was specified by path. If path was not specified, then file and directory names are read from standard input (stdin). In this case, the input should give one path name per line.

Requirement: To issue setfacl, you must be the file owner or have superuser authority (either UID 0 or READ access to SUPERUSER.FILESYS.CHANGEPERMS in the UNIXPRIV class).

If you specify stdin ("-") in place of a file name, you cannot specify it for any of the other options, and you cannot read the target path names from stdin.

The maximum number of ACL entries for a file or directory is regulated by the security product and the physical file system.

The first two forms allow you to set (replace) the entire ACL. The third form allows you to delete an entire extended ACL. The fourth form allows you to delete, add or modify ACL entries. You can specify the m, M, x, and X options on a single command line, but you can only specify each option once.

When you are setting the access ACL, the ACL entries must consist of three required base ACL entries that correspond to the file permission bits. The ACL entries must also consist of zero or more extended ACL entries, which will allow a greater level of granularity when controlling access. The permissions for base entries must be in absolute form.

When you are updating ACL entries, you can specify zero or more base entries.

The three required base ACL entry types have the following format:
u[ser]::perm
g[roup]::perm 
o[ther]::perm	
They correspond to the owner, group and other fields of the file permission bits.
Extended ACL entries have the following format:
[d[efault]: | f[default]:]u[ser]:uid:[+|^]perm
[d[efault]: | f[default]:]g[roup]:gid:[+|^]perm
where:
d[efault]
If specified, extended ACL refers to directory default ACL
f[default]
If specified, extended ACL refers to file default ACL
u[ser]
Extended ACL refers to a particular numeric user ID (UID) or user name
g[roup]
Extended ACL refers to a particular numeric group ID (GID) or group name
uid
User name or numeric user ID (UID)
gid
Group name, or numeric group ID (GID)
perm
Permissions specified either in absolute form (string rwx with - as a placeholder or octal form), or in relative format (using the + or^ modifiers).

Rule: For relative permission settings, only one of + or ^ is allowed per ACL entry. When using relative permissions, you must have at least one of r, w, or x. For example, +rw or ^rwx.

The first field of an ACL entry is optional; it specifies the type of ACL (access, directory default, or file default) that will be processed. If the type is not specified, the operation applies only to the access ACL. If you are updating the ACL entries, you can specify the base ACL entries; however, specifying the base ACL entries might cause the file or directory's permission bits to change if what is specified is different than the current settings.

If the permissions are specified in relative format for an ACL entry that does not currently exist, then the permissions will be assigned as though they were given in absolute form. Any permissions that were not specified will default to no permission. For instance, if an extended ACL entry is given as follows to be updated:
user:BILLYJC:+rw 
and user entry BILLYJC does not currently exist, then the resulting entry will be:
user:BILLYJC:rw- 
Similarly, if you try to remove the permissions from an extended ACL entry that does not exist, the resulting permissions will be:
---
That is, no permission.

For additional information about ACLs and ACL entries, see z/OS UNIX System Services Planning.

Options

–a
Aborts setfacl processing if one of the following errors or warnings occurs:
  1. During the attempt to change an ACL for a file or directory, setfacl performs a stat(), and the stat() fails with a unique reason code.
  2. The user tried to change the file default ACL or directory default ACL for a path name that is not a directory.
  3. An attempt to delete all extended ACL entries failed for the current path name.
  4. An attempt to set or modify extended ACL entries failed for the current path name.
When you do not specify –a, the setfacl processing continues.
–D type
Deletes all extended ACL entries for the ACL of type. For an access ACL, this leaves only the three required base entries intact. For a file default or directory default ACL, the entire ACL for the specified type is deleted. You can specify type as one of the following:
a
Access ACL
d
Directory default ACL
f
File default ACL
e
Every extended ACL for all ACL types that are applicable for the current path name
–h
Does not follow symbolic links. Because ACLs are not associated with symbolic links, nothing will happen if a symbolic link is encountered.
–m EntryOrFile
Modifies the ACL entries specified by EntryOrFile. EntryOrFile represents a string of ACL entries typed directly on the command line. If an ACL entry does not exist for a user or group specified in EntryOrFile, then it is created. If an ACL entry already exists for a user or group that was specified in EntryOrFile, then it is replaced.

The specified entries must be unique for each ACL type and its associated user or group combinations.

–M EntryOrFile
Modifies the ACL entries specified in EntryOrFile. EntryOrFile represents a file containing ACL entries. If an ACL entry does not exist for a user or group specified in EntryOrFile, then it is created. If an ACL entry already exists for a user or group that was specified in EntryOrFile, then it is replaced. If EntryOrFile is , then entries are read from stdin.

The specified entries must be unique for each ACL type and its associated user or group combinations.

–q
Quiet mode. setfacl will suppress all warning and error messages for the following conditions:
  • During the attempt to change an ACL for a file or directory, setfacl performs a stat(), and the stat() fails with a unique reason code.
  • The user tried to change the file default ACL or directory default ACL for a path name that is not a directory.
The condition that caused the warning or error will not affect the return code.
–s entries
Sets (replaces) all ACLs with entries.
–S file
Sets (replaces) all ACLs with the entries specified in file. If file is , then entries are read from stdin.
–v
Verbose
–x EntryOrFile
Deletes the extended ACL entries specified by EntryOrFile. EntryOrFile is a string of ACL entries typed directly on the command line. If an ACL entry does not exist for the user or group specified, then you will not get an error. If the permissions field is provided in EntryOrFile, then it is ignored when this option is processed. Users cannot delete the base ACL entries (file owner, owning group, and others). If base ACL entries are specified with this option, they are ignored. Deleting an extended ACL entry does not necessarily have the same effect as removing all the permissions from an entry.
–X EntryOrFile
Deletes the extended ACL entries specified by EntryOrFile. EntryOrFile is a file containing ACL entries. If an ACL entry does not exist for the user or group specified, then you will not get an error. If EntryOrFile is , then entries are read from stdin. If the permissions field is provided in EntryOrFile, then it is ignored when this option is processed. Users cannot delete the base ACL entries (file owner, owning group, and others). If base ACL entries are specified with this option, they are ignored. Deleting an extended ACL entry does not necessarily have the same effect as removing all the permissions from an entry.

Examples

  1. To set (replace) the current access ACL for file foo, giving only user Billy read and execute access:
    setfacl -s user::rwx,group::---,other::---,user:billy:r-x foo

    This might change the permission bits of the file.

  2. To modify the current access ACL for file foo to contain an extended ACL entry for group cartoons, giving that group read access:
    setfacl -m group:cartoons:+r foo
  3. To set (replace) the current access and directory default ACLs for directory Haunted so that users user1 and user2 have read and search permissions, while the group thegang has read permissions:
    setfacl -s "u::rwx,g::---,o::---, \
         user:user1:r-x,group:thegang:r--,user:user2:r-x, \
         d:user:user1:r-x,d:group:thegang:r--,d:user:user2:r-x" Haunted 
  4. To copy the ACL from file foo such that the file bar will have the same ACL:
    getfacl foo | setfacl -S - bar
  5. To delete all of the extended ACL entries for user user3 for all files and directories in the current directory:
    setfacl -x user:user3,d:user:user3,f:user:user3 *
  6. To delete all of the extended ACL entries for all files and directories in the current working directory:
    setfacl -D e *
  7. To change a directory's access ACL so that user1 has read, write, and execute access for all files in the Haunted directory:
    setfacl -m user:user1:rwx Haunted
  8. RACF® recommends placing ACLs on directories, rather than on each file in a directory. To find and remove all of the extended ACL entries for user1 that are associated with only the files in directory Haunted:
    setfacl -x user:user1 $(find Haunted -type f -acl_user user1)

    Even if the setfacl command is successful in removing access from user1, user1 might still be able to obtain access to the files in directory Haunted based on the file permission bits, assuming the user has search permission for Haunted.

Localization

setfacl uses the following localization environment variables:
  • LANG
  • LC_ALL
  • LC_CTYPE
  • LC_SYNTAX
  • NLSPATH

See Localization for more information.

Usage notes

  1. When you use setfacl to add, change and delete ACL entries, all deletion operations are performed first. In other words, deletion operations are processed before any change or add operations.
  2. setfacl should not be considered an atomic operation because if multiple operations are requested and an error occurs, some of the operations might have been processed before the error was encountered. Note that the -s option is considered a multiple operation request.

Exit values

0
Success.
1
Failure due to any of the following:
  • Incorrect command-line option.
  • Too few arguments on the command line.
  • An attempt was made to read from stdin in more than one place.
  • An attempt was made to combine setfacl operations that are mutually exclusive.
2
Failure due to any of the following:
  • A specified path name does not exist.
  • An error occurred while attempting to read the entries file.
  • An attempt was made to alter the file default ACL or directory default ACL for a path name that is not a directory.
3
Failure due to any of the following:
  • Unable to delete all extended ACL entries from a path name.
  • Unable to set or modify ACL entries for a path name.
  • Improper syntax of ACL entries.
  • An incorrect ACL was specified.
  • Unable to allocate enough memory.
  • Unable to determine the PATH_MAX.
  • Unable to open the entries file for reading.
  • The entries file is empty.

Portability

An approved POSIX standard does not exist for setfacl.

Related information

chmod, find, getfacl, ls, filetest, pax, test