Managing File Permissions on Oak#

Data owners are responsible for managing permissions

SRCC administrators generally defer data management tasks, including permission changes and file deletions, to data owners whenever possible. If you need permissions updated on a file or folder, please ask the data owner. If the owner is unavailable or no longer a member of the Oak space where their data resides, please email srcc-support@stanford.edu to request an ownership transfer of their data. PIs must provide written approval for these changes.

Use `setfacl` for managing permissions on Oak#

Oak supports POSIX Access Control Lists (ACLs), which extend the traditional UNIX permission model. While chmod only manages permissions for three categories (owner, group, and others), setfacl can do everything chmod does and grant access to specific named users and groups. Because Oak workflows frequently involve sharing data with collaborators, setfacl is the recommended tool for managing permissions on Oak.

How ACLs differ from standard UNIX permissions#

Standard permissions with `chmod`#

The chmod command manages the traditional UNIX permission model, which assigns read (r), write (w), and execute (x) permissions to exactly three categories:

Owner -- the user who owns the file
Group -- the group associated with the file
Others -- everyone else

For example:

chmod 750 mydir

This gives the owner full access (rwx), the group read and execute access (r-x), and others no access (---). This model works well when access requirements align neatly with owner/group/others, but it falls short when you need to grant different levels of access to specific users or multiple groups.

Avoid using chmod on files that have ACL entries

When you run chmod on a file that has ACL entries, the group permission bits modify the ACL mask, not the actual group entry. This can silently restrict or widen the effective permissions of all named-user and named-group ACL entries, breaking collaborator access. If ACLs are in use on a file or directory, always use setfacl instead.

Extended permissions with `setfacl`#

The setfacl command manages POSIX ACLs, which extend the permission model by allowing you to specify access for named users and groups beyond the three standard categories. This means you can do things like:

Grant read access to a specific user without changing group membership
Allow a second group to access files without affecting the primary group permissions
Set default permissions that new files and subdirectories will inherit

For example:

setfacl -m u:jstanford:rx mydir

This grants the user jstanford read and execute access to mydir, without affecting the permissions of the owner, the group, or others.

Key ACL concepts#

Viewing ACLs with `getfacl`#

You can view the full ACL of a file or directory with getfacl:

$ getfacl /oak/stanford/groups/ruthm/shared_data
# file: shared_data/
# owner: ktully
# group: oak_ruthm
# flags: -st
user::rwx
user:jstanford:r-x
group::rwx
group:oak_ruthm:rwx
mask::rwx
other::---
default:user::rwx
default:group::rwx
default:group:oak_ruthm:rwx
default:mask::rwx
default:other::---

This output shows both the standard UNIX permissions and the additional ACL entries. The user:jstanford:r-x line is an ACL entry that grants user jstanford read and execute access.

The ACL mask#

The mask is an important concept that is unique to ACLs. It acts as an upper limit on the permissions that can be granted through ACL entries (named users, named groups, and the owning group). The mask does not affect the file owner's permissions or the "other" permissions.

For example, if the mask is set to r-x:

An ACL entry granting rwx to a user will be limited to r-x in practice
An ACL entry granting r-- will remain r-- (already within the mask)

You can see the effective permissions when the mask restricts an entry:

$ getfacl 5_GB.dat
# file: 5_GB.dat
# owner: mpiercy
# group: oak_bprogers
user::rw-
group::rwx                  #effective:r-x
group:oak_bprogers:rwx      #effective:r-x
mask::r-x
other::---

The mask is automatically recalculated when you use setfacl to add or modify entries. You can also set it explicitly:

setfacl -m m::rx myfile

Interaction between chmod and the ACL mask

When you run chmod on a file that has ACL entries, the group permission bits modify the ACL mask, not the actual group entry. This means a chmod command can inadvertently restrict the effective permissions of all ACL entries. For this reason, it is best to use setfacl consistently once ACLs are in use on a file or directory, and avoid mixing chmod and setfacl on the same object.

Default ACLs on directories#

Default ACLs can be set on directories to define the ACL entries that new files and subdirectories will inherit upon creation. This is useful when you want every new file in a shared directory to automatically grant access to a specific collaborator.

setfacl -d -m u:jstanford:rx /oak/stanford/groups/ruthm/shared_data

The -d flag indicates that this is a default ACL. New files created inside shared_data will automatically include an ACL entry granting jstanford read and execute access.

Default ACLs only apply to newly created items

Files and directories that already exist are not affected when you set a default ACL. To apply the same permissions to existing contents, use the recursive flag: setfacl -R -m u:jstanford:rx /path/to/dir.

Common operations on Oak#

Grant a user in your Oak group read access to a directory#

setfacl -m u:jstanford:rx /oak/stanford/groups/ruthm/results

Revoke an ACL entry for a user#

setfacl -x u:jstanford /oak/stanford/groups/ruthm/results

Remove all ACL entries from a file#

setfacl -b myfile # Use sparingly, and with caution!

Apply ACLs recursively#

setfacl -R -m u:jstanford:rx /oak/stanford/groups/ruthm/results

The `setgid` bit#

The default directory permissions on Oak rely on the setgid bit (g+S or chmod mask 2000 set on the directory). With regular UNIX permissions, files are created using the user's primary group, but this setgid permission bit ensures that new directories and files are created using the same group as the parent directory. While it is usually not a problem when accessing Oak from Sherlock (because a primary group is defined on Sherlock), it might be a problem if you remove this bit and access Oak from the gateways. Oak is using Stanford LDAP that doesn't provide a primary group.

For more information, please see the Advanced topics page: "What is a Sticky Bit?"

When to use `chmod` vs. `setfacl`#

Scenario	Recommended Tool
Setting basic owner/group/others permissions	`setfacl` (preferred); `chmod` is acceptable only when no ACLs are present
Granting access to a specific user outside your group	`setfacl`
Granting access to a second group	`setfacl`
Setting permissions that new files should inherit	`setfacl` (default ACLs)
Revoking individual user access without changing group membership	`setfacl`

When in doubt, use setfacl

If ACLs already exist on a file or directory, always use setfacl to avoid accidentally modifying the ACL mask. You can check whether ACLs are present by running getfacl on the file.

For more information on sharing files with users outside of your Oak group using ACLs, see our Advanced File Sharing page.

Getting Help#

Understanding how to construct commands to change permissions can be challenging. If you aren't sure how to structure a command to set permissions the way you'd like, please email us at srcc-support@stanford.edu and we can help guide you with examples that suit your needs.