File Permissions Basics and ACL

Access-control Lists (ACL) are how POSIX-based file systems control file permissions. This article forms a primer to understanding how exactly the actions in Setting Default File Permissions work and how to debug them.

In short, ACL helps to control which users can read, write, or execute certain file objects, which are defined as anything in the file system (regular files, directories, symlinks, etc.). Note that ACL does not have complete authority on creating permissions for new file objects. In analogy, ACL is akin to the guest list at a club. Continuing the analogy, the OS kernel is the bouncer of the club, determining who can get in to which section of the club based on the ACL.

Much of the information presented here is written out in the ACL manpage. This wiki hopefully serves as a primer for that manpage, as the terms it uses are different than the ones that are commonly presented and used when dealing with normal file permissions. I recommend reading the manpage if you're having to debug a permissions issue. It's not too long.

Basics of Unix/POSIX File Permissions

What are they?

• All files and directories have permissions assigned to them via ACL entries
• There are three different "levels" of file permissions in a standard POSIX file system: read (r), write (w), and execute (x).
  • Read allows viewing the contents of the file/directory, and copying the files
  • Write allows rewriting and deleting files. For a directory with write permissions, it also allows creation of subdirectories and creation of new files
  • Execute allows files to be executed directly.
    • Note that for script files (such as bash or python), they can still be run by passing the file to it's interpreter if the file is readable (ie. bash non_executableScript.sh is still possible if non_executableScript.sh has rw- permissions).
• ACL entries apply the three different "levels" of file permission onto 6 possible tags. From the ACL manpage, they are:

ACL_USER_OBJ    The ACL_USER_OBJ entry denotes access rights for the file owner.

ACL_USER        ACL_USER entries denote access rights for users identified by the entry's qualifier.

ACL_GROUP_OBJ   The ACL_GROUP_OBJ entry denotes access rights for the file group.

ACL_GROUP       ACL_GROUP entries denote access rights for groups identified by the entry's qualifier.

ACL_MASK        The ACL_MASK entry denotes the maximum access rights that can be granted by entries of type ACL_USER, ACL_GROUP_OBJ, or ACL_GROUP.

ACL_OTHER       The ACL_OTHER entry denotes access rights for processes that do not match any other entry in the ACL.

• ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER correspond to the standard three user categories: file owner, file group, and "other". These three categories are the ones listed by ls -l.
  • The file owner and file group are set to the user that originally created the file and their respective user group (though this can be changed using chown).
• "Others" simply refers to all other users that are not the file owner and are not members of the file group.
• The other three tags, ACL_MASK, ACL_GROUP, and ACL_USER, are only used for custom ACL entries that are set by a user.
  • Additionally, ACL_MASK is only required if ACL_GROUP or ACL_USER entries are utilized.

• The file permissions for ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER together form the file mode parameter
  • This parameter is used by programs to set the permissions of files they create. This is discussed further in the Custom Permissions section.

Viewing Them

Using ls

The simplest and most common way of viewing the basic permissions of a file is by using ls. As an example, if you run ls -l on a directory, you might see:

drwxr-x---+ 2 jrwrigh7 a1983 4.0K 2020-07-04 08:09 test2
-rw-r-x---+ 1 jrwrigh7 a1983   38 2020-07-02 12:38 test2file
lrwxrwxrwx  1 jrwrigh7 a1983    9 2020-07-04 08:40 test2fileLink -> test2file

The first block (-rw-r-x---+) shows the permissions of the file for the three primary ACL tags (ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER). (described below). The file owner is shown as jrwrigh7 and the file group is a1983. These correspond to ACL_USER_OBJ and ACL_GROUP_OBJ.

Permissions Block:

• First character displays what kind of file it is, be it a link (l), directory (d), regular file (-), etc.
• The next 9 characters show the permissions for the ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER
  • So for test2file in the above output:
    • File Owner: rw-
    • File Group: r-x
    • Others: ---
• The last character is optional. A + means that there are other permission rules not displayed. This is where ACL rules come into play.

See the ls coreutils manual for more information on the 'long' format for ls.

Using getfacl

You can also use getfacl to get a more detailed look at the permissions of a file or directory. Simply running getfacl with a file object as it's argument will show the permissions for that file object:

$ getfacl test2file
# file: test2file
# owner: jrwrigh7
# group: a1983
user::rw-
group::r-x
group:a1983:r-x
mask::r-x
other::---

This argument will show all permissions for a file object, including custom ones. user::, group::, and other:: refer to the permissions set for the ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER.

To set more specific permissions, a group or user can be inserted between the colons. This can be seen in the line group:a1983: where the members of the group have r-x permissions to the file. These permissions fall under the ACL_USER and ACL_GROUP tags.

If default ACL entries are used, they will also be displayed using getfacl. An example is presented below for the directory test (note that default ACL entries can only be applied to directories):

$ getfacl test
# file: test
# owner: jrwrigh7
# group: a1983
user::rwx
group::r-x
group:a1983:r-x
mask::r-x
other::---
default:user::rwx
default:group::r-x
default:group:a1983:r-x
default:mask::r-x
default:other::---

Permissions as Octal Numbers

The file mode is often conveyed in the form of three octal numbers (ie. base 8 numbers). It is very similar to how PHASTA handles specifying boundary conditions using bitwise logic. The first bit handles read, the second bit handles write, and the third handles execute.

Permissions	Execute bit	Write Bit	Read Bit	Octal Number equivalent
---	0	0	0	0
--x	1	0	0	1
-w-	0	1	0	2
-wx	1	1	0	3
r--	0	0	1	4
r-x	1	0	1	5
rw-	0	1	1	6
rwx	1	1	1	7

Using test2file as the example permissions block(rw-r-x---), it is stored as 110 101 000. When translated into decimal, that equals 3 5 0.

Another way to think about it is that the octal number equivalent of a permission set = 1*x + 2*w + 4*r, where r, w, and x equal 1 or 0 depending on whether they're set or not.

Custom Permissions

The other two tags, ACL_GROUP and ACL_USER, are for more custom permissions and are not set by default on a blank system. Different sets of permissions can be set on a per user and per group basis. For more information on complex interactions (ie. if a user has permissions set and is a member of a group that has its own custom permissions), I recommend seeing the ACL manpage section on the Access Check Algorithm

What determines the permissions for a new file?

When a new file object is created, a new set of ACL entries must be created for that file object. There are three sources that determine what ACL entries will be set; umask, the "mode" parameter used by the program creating the file, and ACL entries of the parent directory of the file object being created.

umask

umask is a function that contains file permission settings for any file created by a user and it is unique to the user. The user can change it at anytime using the umask command. To see what it is set to, simply run umask with no arguments. The output is usually in octal notation, and represents the bits that will be blocked, not the bits that will be set. So an output of 022 will allow any user permission bits to be set, but will not allow for the executable bit to be set for user and group settings.

"Mode" Parameter

When a new file is created, the syscall open() (among others) is used and a file mode parameter must be chosen by that program. For example, touch will automatically apply the mode 666 to the file, which will make the file owner, file group, and "others" all have rw- permissions.

ACL Defaults

ACL default entries are set for a directory and are used for files and subdirectories created inside that directory. Note that ACL default entries can only be set for directories.

How are new file permissions set?

This is simply a paraphrasing/rewording of the "Object Creation and Default ACLs" section of the ACL manpage.

When creating a file/subdirectory in a parent directory:

• If the parent directory does have default ACL rules, only the ACL default entries of the parent directory and "mode" parameter are used:
  • The new file/subdirectory first inherits the ACL default entries of its parent directory as its normal ACL entries
  • The new file/subdirectory has its ACL entries adjusted such that no permissions exceed the "mode" parameter.
    • The ACL_USER_OBJ and ACL_OTHER are changed directly
    • The ACL_GROUP, ACL_GROUP_OBJ, and ACL_USER are changed through adjusting the ACL_MASK
  • Additionally, if a new subdirectory is created, it will inherit its parents default ACL rules. Note that a file cannot have default ACL rules set.

• If the parent directory does not have default ACL rules, only umask and "mode" parameter are used:
  • The new file/subdirectory's ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER are set based on the permissions set by umask via a bit wise NAND
  • The new file/subdirectory's are then adjusted to limit permissions to be no looser than the "mode" parameter

Note that this all means that if you have a default ACL rule that gives execute permissions to a group, the group will not have execute permissions by default unless the "mode" parameter also has execute permissions. Most compilers will use the execute permission bit for the "mode" parameter of it's executable, but other files will not.