File permissions and modes¶

Checked against GNU coreutils 9.7 (Debian 13), 9.5 (AlmaLinux 10 and Rocky Linux 10) and 9.12 (Arch and Gentoo), uutils coreutils 0.10.0 (Ubuntu 26.04), and acl 2.4.0 (Arch and Gentoo), on Linux 6.12 and later.

Ubuntu 26.04 ships chmod, chown and chgrp from uutils coreutils, a reimplementation in Rust, instead of GNU coreutils. The modes, the special-bit behaviour and the options listed here are the same in both, except where a section says otherwise.

Synopsis¶

chmod [OPTION]... MODE[,MODE]... FILE...
chmod [OPTION]... OCTAL-MODE FILE...
chmod [OPTION]... --reference=RFILE FILE...

chown [OPTION]... [OWNER][:[GROUP]] FILE...
chown [OPTION]... --reference=RFILE FILE...

chgrp [OPTION]... GROUP FILE...
chgrp [OPTION]... --reference=RFILE FILE...

umask [-S] [MODE]

getfacl [OPTION]... FILE...
setfacl [OPTION]... {-m|-M|-x|-X} ACL_SPEC... FILE...

Description¶

Every file and directory (every inode) has an owning user (UID), an owning group (GID) and a 12-bit mode: nine permission bits and three special bits. The kernel compares the mode with the identity of the process that asks for access. It checks exactly one permission class: user if the process's filesystem UID is the file's owner, otherwise group if the file's group is the process's filesystem GID or one of its supplementary groups, otherwise other. The classes don't combine: an owner whose user bits deny an access is refused even if the group or other bits allow it.

A process with the CAP_DAC_OVERRIDE capability, which includes root, bypasses read and write checks, and bypasses execute checks on directories. It may execute a regular file only if at least one of the three execute bits is set.

Permission bits¶

Notes:

• Deleting or renaming a file is a change to its directory: it needs w and x on the directory, not w on the file.
• r without x on a directory lists names but not their attributes or contents; x without r allows access to entries whose names you already know.
• Every directory on a path needs x for the class that applies, or the path can't be followed.
• A script needs r as well as x, because the interpreter reads it.

Octal modes¶

An octal mode is up to four digits. The last three give the user, group and other permissions, each the sum of 4 (read), 2 (write) and 1 (execute). An optional leading digit sets the special bits.

Common modes:

chmod (GNU and uutils) keeps the setuid and setgid bits of a directory when you give a mode of three or four digits that doesn't mention them; chmod 755 and chmod 0755 leave a setgid directory setgid. To clear them numerically, give five digits with a leading zero, such as 00755, or use the symbolic g-s and u-s.

Symbolic modes¶

A symbolic mode is one or more clauses separated by commas. Each clause is [WHO]OPERATOR[PERMISSIONS], and several operator and permission pairs may follow one WHO.

Examples of the notation:

Special bits¶

Notes:

• Linux ignores setuid and setgid on scripts that start with #!; they work only on compiled programs.
• Filesystems mounted with nosuid ignore setuid and setgid on files.
• When the owner or group of a non-directory changes, Linux clears its setuid bit, and clears its setgid bit if the group execute bit is set. This happens even when root runs chown. Directories keep both bits.
• When a process without the CAP_FSETID capability writes to a file, Linux clears the file's setuid bit, and its setgid bit if the group execute bit is set.

The ls -l mode string¶

ls -l and stat -c %A show the mode as ten characters, optionally followed by one more:

-rwxr-x---+
│└┬┘└┬┘└┬┘│
│ │  │  │ └── + : the file has an extended ACL; . : it has an SELinux context and no ACL
│ │  │  └──── other permissions
│ │  └─────── group permissions
│ └────────── user (owner) permissions
└──────────── file type

Symbolic links always show rwxrwxrwx; Linux ignores their permissions and checks those of the target.

stat -c '%a %A %U:%G' FILE prints the octal mode, the mode string, and the owner and group.

umask¶

The umask is a per-process mask of permission bits that new files and directories don't get. A program that creates a file requests a mode, usually 0666 for files and 0777 for directories, and the kernel clears the bits that are set in the umask. Children inherit the umask, and umask is a shell built-in because it must change the shell's own value.

The umask never adds permissions: a file created with mode 0666 never becomes executable. umask without arguments prints the current value in octal; umask -S prints it in symbolic form, such as u=rwx,g=rx,o=rx. A symbolic argument such as umask g-w describes permissions to allow, not bits to mask.

Default umask for an ordinary user logging in over SSH, as observed on the verification labs:

A directory with a default ACL (see below) replaces the umask for entries created inside it.

chmod¶

Changes the mode of each file. Only the file's owner, or a process with CAP_FOWNER, may change the mode. If an unprivileged owner sets the setgid bit on a file whose group the owner isn't a member of, the kernel silently clears it.

chmod 640 app.conf
chmod u+x,go-w deploy.sh
chmod -R u=rwX,g=rX,o= /srv/project

chown¶

Changes the owner and, optionally, the group of each file. Only a privileged process (CAP_CHOWN) may change the owner. The file's owner may change its group to any group the owner is a member of.

Owners and groups may be given as names or as numeric IDs.

sudo chown www-data:www-data /srv/www/index.html
sudo chown -R alice: /home/alice

chgrp¶

Changes the group of each file. It is equivalent to chown :GROUP. The options -R, -h, -c, -v, -f, --reference, --preserve-root, -H, -L and -P behave as they do for chown, including the default of -P.

chgrp developers report.txt

Access control lists¶

POSIX access control lists (ACLs) extend the mode with entries for additional named users and groups. ext4, XFS and Btrfs support them without special mount options. The getfacl and setfacl commands come from the acl package, which isn't installed by default on Debian, Ubuntu, AlmaLinux or Rocky Linux; it is installed on Arch and Gentoo (sys-apps/acl).

ACL entries¶

user, group, mask, other and default may be abbreviated to u, g, m, o and d.

When a file has an extended ACL, the group bits shown by ls -l are the mask, not the owning group's entry, and chmod g=… changes the mask. Lowering the mask limits every named entry; getfacl then shows the effective permissions after a #effective: comment.

$ getfacl report.txt
# file: report.txt
# owner: labuser
# group: labuser
user::rw-
user:alice:rwx                  #effective:r-x
group::r--
mask::r-x
other::r--

getfacl¶

setfacl¶

setfacl -m u:alice:rw report.txt          # give alice read and write
setfacl -m g:developers:rwX -R /srv/project
setfacl -d -m g:developers:rwX /srv/project   # inherited by new entries
setfacl -x u:alice report.txt             # remove alice's entry
setfacl -b report.txt                     # remove all extended entries
getfacl report.txt | setfacl --set-file=- copy.txt   # copy an ACL

cp -a, cp --preserve=all, mv within one filesystem, and tar --acls keep ACLs; plain cp doesn't.

Files¶

See also¶

• chmod(1), chown(1) and chgrp(1), from GNU coreutils 9.7, and the uutils coreutils 0.10.0 --help output; the GNU coreutils manual's File permissions chapter
• chmod(2), umask(2), path_resolution(7) and capabilities(7) from the Linux man-pages project
• acl(5), getfacl(1) and setfacl(1), from acl 2.4.0
• pam_umask(8) and login.defs(5)
• stat(1) and ls(1)

Related¶

• Tutorial: First steps on a Linux server
• How-to guide: How to grant a user sudo access
• Explanation: Users, groups and permissions