Sharing Files and Access Control (ACLs)

On the cluster, the standard Unix owner/group/other permission model controls who can access your files, but it cannot express every type of sharing. When you need to share a specific directory with a colleague, grant a second research group access to a dataset, or provide access to someone outside your group, Access Control Lists (ACLs) give you that flexibility. An ACL allows a file or directory to grant different levels of access to multiple named users and groups at once, without making your data accessible to everyone.

ACLs are supported on the /resnick storage system that backs your home, group, and scratch spaces. The /groups and /home paths you see in your shell are shortcuts to /resnick/groups and /resnick/home, so either form works in the examples on this page. ACLs are managed with two commands: getfacl, which displays existing ACLs, and setfacl, which modifies them. This page introduces both commands and walks through the most common sharing scenarios.

Tip

Use an ACL instead of making a file or directory globally accessible whenever possible. Granting g:hpc_collaborator_group:rx limits access to the intended collaborators, while chmod 777 (or a world-readable directory) exposes the data to every account on the cluster.

Why ACLs? The limits of chmod

Every file and directory has permissions for three classes of users: the owner, a single owning group, and everyone else (other). Each class can be granted read (r), write (w), and execute (x) permissions. You can see these permissions in the output of ls -l:

-rwxr-x---  1 alice  hpc_mylab  4096 Jun 15 09:00 results

While this model is simple and effective, it has an important limitation: it cannot grant access to a specific user who is not the owner, nor can it grant permissions to a second group in addition to the owning group. There is simply no place in the standard permission model to express either case.

Access Control Lists (ACLs) remove this limitation. An ACL is an extended set of permission entries that can grant different levels of access to specific users and groups, while preserving the standard owner/group/other permissions.

Files and directories with additional ACL entries display a + at the end of their permission string in ls -l:

-rw-rwx---+  1 alice  hpc_mylab  4096 Jun 15 09:00 shared

The trailing + indicates that extended ACL entries are present. Use getfacl to view them.

Checking access with getfacl

getfacl displays the complete permission set for a file or directory, including any ACL entries:

getfacl /resnick/groups/mylab/shared

A directory shared with a second group might look like this:

# file: resnick/groups/mylab/shared
# owner: alice
# group: hpc_mylab
# flags: -s-
user::rwx
group::rwx
group:hpc_cs156b:rwx
mask::rwx
other::r-x

The output can be interpreted as follows:

Line	Meaning
# owner: / # group:	The file or directory owner and owning group.
# flags: -s-	Special permission bits in the order setuid · setgid · sticky. The middle s indicates that setgid is enabled, causing newly created files and directories to inherit the parent directory’s group rather than the creator’s primary group. This is the desired behavior for shared group storage. Directories under /resnick/groups already have this set.
user::rwx	Permissions granted to the owner.
group::rwx	Permissions granted to the owning group (hpc_mylab in this example).
group:hpc_cs156b:rwx	A named group ACL entry that grants permissions to a second group. A named user entry would appear as user:johnbot:rwx.
mask::rwx	The maximum permissions that can be granted to the owning group and all named user and group entries. (See Effective permissions and the mask).
other::r-x	Permissions granted to all other users on the cluster.

Granting access with setfacl

Use setfacl -m (“modify”) to add or update ACL entries. Each entry has the form type:name:permissions:

• u:USERNAME:PERMS — a specific user

• g:GROUPNAME:PERMS — a group (research groups use Unix group names of the form hpc_<groupname>, such as hpc_cs156b)

Grant a user read-write access to a file:

setfacl -m u:johnbot:rw /resnick/groups/mylab/results.csv

Grant a group read-only access to a directory:

setfacl -m g:hpc_cs156b:rx /resnick/groups/mylab/dataset

In general, use rw or rwx for read-write access and r or rx for read-only access.

Warning

When granting permissions on a directory, almost always include x along with r/w.

For directories, the execute bit means “enter and traverse.” Without it, a user cannot cd into the directory or access files and subdirectories beneath it, even if they have been granted read or write permissions.

Use rx when collaborators should be able to browse and read files without modifying them. Use rwx when they should also be able to create, modify, or remove files.

Granting rw on a directory without x is a common mistake. It appears to provide access, but the user still cannot enter the directory or reach its contents.

Reaching the file: every parent directory needs x

This is one of the most common reasons a correctly shared file still returns “Permission denied.”

To access /resnick/groups/mylab/shared/data.csv, a user must have execute (x) permission on every directory in the path, not just on the file itself. In this example, that includes /resnick/groups/mylab and /resnick/groups/mylab/shared. Granting access to the file or final directory alone is not sufficient if the user cannot traverse the directories above it.

When sharing data with someone outside your research group, missing execute permissions on a parent directory are often the cause. Grant the minimum traversal permissions needed at each level:

setfacl -m u:johnbot:x  /resnick/groups/mylab
setfacl -m u:johnbot:rx /resnick/groups/mylab/shared

An (x) permission without (r) allows a user to traverse a directory to a known path without listing its contents. This is often useful on parent directories because it allows access to the shared location without exposing the rest of your group’s files and folders.

Sharing Outside your Group

Sharing data with someone who is not a member of your research group works the same way as any other ACL grant, with one additional requirement: the user must be able to traverse into your group’s directory.

By default, /resnick/groups/<group> is restricted to group members (drwxrws---). An outside user cannot reach files inside the directory until they are granted execute (x) permission on the group directory itself.

There is one important limitation: only the owner of a directory, or root, can modify its ACL. Membership in the owning group allows you to use a directory, but not to change its permissions. Because group directories are normally owned by root, granting traversal access to an outside user typically requires assistance from HPC staff.

Granting an outside user outsideuser read-write access to a file therefore requires two ACL grants, often performed by two different people:

# 1. The group directory's owner (usually root / HPC staff / or PI):
setfacl -m u:outsideuser:x  /resnick/groups/<group>

# 2. The file's owner:
setfacl -m u:outsideuser:rw /resnick/groups/<group>/path/to/file

The first grant provides traversal only. It allows outsideuser to reach the shared file without being able to list the contents of the group directory. This is typically a one-time step for each outside collaborator. Afterward, file owners can manage access to their own files and directories using ACLs.

Note

You only need to grant traversal permissions on directories that are not already accessible. Once an outside user can traverse the group directory, the remainder of the path may already be traversable.

If an intermediate directory is restricted, only that directory’s owner (or root) can grant the required x permission. Likewise, ACLs on a file can only be managed by the file’s owner (or root).

Groups that regularly collaborate with external users should manage the top-level directory themselves. See Setting up Self-Service Sharing (For PIs).

Setting up Self-Service Sharing (For PIs)

Groups that frequently share data with external collaborators can avoid repeated requests to HPC staff by taking ownership of their top-level group directory.

By default, /resnick/groups/<group> is owned by root, which means only HPC staff can grant traversal access to outside users. A one-time ownership transfer allows the group to manage this step directly.

To set this up, the PI must submit a request through the Caltech Help System asking that ownership of /resnick/groups/<group> be transferred to them. The request must come directly from the PI, not an HPC lab admin or researcher.

Once ownership has been transferred:

• The PI can grant traversal access to outside users or groups without involving HPC staff:

  setfacl -m u:outsideuser:x /resnick/groups/<group>
  

• Group members continue to manage ACLs on the files and directories they own. This behavior does not change. Transferring ownership of the group directory only gives the PI control over the top-level entry point into the group’s storage.

Important

Ownership of the group directory carries responsibility. As owner, the PI controls who can traverse into the group’s storage at a basic level. Individual researchers continue to manage ACLs on the files and directories they own and remain fully responsible for granting and revoking access to their own data.

Keeping New Files Shared: Default ACLs

There is a second common pitfall. An ACL applied to a directory affects that directory only; it is not automatically inherited by files created inside it later. If you grant hpc_cs156b access to a shared folder, files created there afterward will not automatically receive the same ACL.

The solution is a default ACL. A default ACL acts as a template that is applied to every new file and subdirectory created within a directory. Create one with the -d option:

setfacl -d -m g:hpc_cs156b:rwx /resnick/groups/mylab/shared

Afterward, any new files and directories created under shared/ automatically grant hpc_cs156b the specified access.

Note

A default ACL affects only files and directories created after it is set; it does not modify existing content.

To update a directory’s current contents and establish a default ACL for future files, apply both the access ACL and the default ACL recursively:

setfacl -R -m g:hpc_cs156b:rwX,d:g:hpc_cs156b:rwX /resnick/groups/mylab/shared

Use a capital X rather than lowercase x. The special X permission grants execute access only on directories (and on files that are already executable), ensuring that directories remain traversable without making ordinary data files executable.

Worked Example: Share a Project Directory with Another Group

Suppose you maintain /resnick/groups/imss_admin/shared and want the hpc_cs156b group to collaborate in it. Create the directory and inspect its current permissions:

mkdir /resnick/groups/imss_admin/shared
getfacl /resnick/groups/imss_admin/shared

A newly created directory might look similar to:

# file: resnick/groups/imss_admin/shared
# owner: johnbot
# group: hpc_imss_admin
# flags: -s-
user::rwx
group::rwx
other::r-x

Grant hpc_cs156b read-write access to the directory, including x so its members can enter it, and set a matching default ACL so files created later remain shared:

setfacl -m    g:hpc_CS156b:rwx /resnick/groups/imss_admin/shared
setfacl -d -m g:hpc_CS156b:rwx /resnick/groups/imss_admin/shared

Confirm the result:

getfacl /resnick/groups/imss_admin/shared

# file: resnick/groups/imss_admin/shared
# owner: naveed
# group: hpc_imss_admin
# flags: -s-
user::rwx
group::rwx
group:hpc_CS156b:rwx
mask::rwx
other::r-x
default:user::rwx
default:group::rwx
default:group:hpc_CS156b:rwx
default:mask::rwx
default:other::r-x

The group:hpc_cs156b:rwx entry grants access to the collaborating group. The default: entries ensure that newly created files and subdirectories automatically inherit the same permissions.

Tip

This example expands on the earlier setfacl -m g:hpc_cs156b:rw... recipe. Two additional steps make the sharing arrangement practical for a directory:

• Grant rwx (not just rw) so collaborators can traverse and enter the directory.

• Add a default ACL if required so newly created files and subdirectories remain shared automatically.

Because hpc_cs156b is not the owning group (hpc_imss_admin), its members must also be able to traverse /resnick/groups/imss_admin before they can reach the shared directory. Since that directory is normally owned by root, granting traversal to another group typically requires HPC staff see Sharing outside your group.

Removing Access

Use setfacl -x to remove a specific ACL entry while leaving all other permissions unchanged:

setfacl -x u:johnbot        /resnick/groups/mylab/shared
setfacl -x g:hpc_cs156b /resnick/groups/mylab/shared

To remove all ACL entries and return a file or directory to the standard owner/group/other permission model:

setfacl -b /resnick/groups/mylab/shared

To remove only the default ACL, leaving existing access permissions intact:

setfacl -k /resnick/groups/mylab/shared

The -x option takes only the entry to remove; it does not accept a permission field. You specify the user or group entry to delete, not the permissions to subtract.

The -b option removes all named ACL entries as well as any default ACL. In most cases, use -x when you want to revoke access for a specific user or group without affecting anyone

Effective Permissions and the Mask

Whenever an ACL contains named user or group entries, it also includes a mask:: entry. The mask acts as a ceiling on permissions: it limits the effective permissions granted to the owning group and all named users and groups. It does not affect the file owner or the other entry.

If an ACL entry grants permissions that exceed the mask, the extra permissions are ignored. getfacl highlights this by showing the effective permissions:

user:johnbot:rwx          #effective:r-x
mask::r-x

In this example, Johnbots’s ACL entry grants rwx, but the mask allows only r-x, so Johnbot’s effective permissions are reduced to r-x.

In normal use, you rarely need to manage the mask directly. When you use setfacl -m, the mask is typically updated automatically to accommodate the permissions you grant.

However, if a collaborator appears to have write access in the ACL but still cannot write, inspect the output of getfacl and look for #effective: annotations. An overly restrictive mask is often the cause.

setfacl -m m::rwx /resnick/groups/mylab/shared

Copying Files Can Preserve — or Strip — ACLs

ACLs are stored as extended attributes, and not all file-copying tools preserve them by default. This is easy to overlook when reorganizing or migrating shared data.

• cp — a standard copy does not preserve ACLs. Use cp -a (archive mode) or cp --preserve=all to retain them.

• rsync — include -A (--acls) to preserve ACLs. A common choice is rsync -aAX where (-X) also preserves other extended attributes).

• tar — use --acls when creating and extracting archives if you want ACLs to be preserved.

• mv — normally preserves ACLs when moving files within the same filesystem because the file itself is not recreated.

After copying shared data, run getfacl on the destination to confirm the ACLs were preserved.

Quick Reference

Task	Command
Show all permissions and ACLs	getfacl PATH
Grant a user read-write access	setfacl -m u:USER:rw PATH
Grant a group read-only access (directory)	setfacl -m g:GROUP:rx DIR
Grant a group read-write access (directory)	setfacl -m g:GROUP:rwx DIR
Make new files and directories inherit the grant	setfacl -d -m g:GROUP:rwx DIR
Apply a grant to an existing directory tree and future files	setfacl -R -m g:GROUP:rwX,d:g:GROUP:rwX DIR
Allow a user to traverse a parent directory	setfacl -m u:USER:x DIR
Allow an outside user to traverse a group directory (owner/root only)	setfacl -m u:USER:x /resnick/groups/GROUP
Remove one user or group ACL entry	setfacl -x u:USER PATH
Remove all ACLs	setfacl -b PATH
Remove only the default ACL	setfacl -k DIR
Reset the ACL mask	setfacl -m m::rwx PATH

Troubleshooting

“Permission denied,” even though you granted access

The most common cause is missing directory traversal permissions. The user lacks execute x permission on one or more parent directories in the path. Grant x at each level as needed; see Reaching the file.

A collaborator outside your group gets “Permission denied” on the entire path

Your group’s top-level directory (/resnick/groups/<group>) is restricted to group members and is normally owned by root. An outside user cannot reach shared files until someone who owns that directory—typically HPC staff or PI—grants them execute x permission on it. Being a member of the group is not sufficient. See Sharing outside your group.

New files in a shared folder are not accessible

An access ACL was configured, but no default ACL was set. New files and directories do not automatically inherit access permissions unless a default ACL is present. Add one with setfacl -d -m ...; see default ACLs.

A collaborator can see the directory but cannot enter it

The directory ACL is missing execute x permission. Grant rx for read-only access or rwx for read-write access. A directory ACL of rw without x is a common mistake.

A grant appears in getfacl but does not work

Check the mask:: entry and any #effective: annotations in the getfacl output. An overly restrictive mask can silently reduce the permissions granted by an ACL. Reapply the ACL or reset the mask; see Effective permissions and the mask).

setfacl reports “Operation not supported”

That path’s filesystem does not have POSIX ACLs enabled. ACLs are supported on /resnick storage; if you encounter this on a path that should support them, email help-hpc@caltech.edu.

Note

The ACLs described on this page are standard POSIX ACLs implemented through getfacl and setfacl. The getfacl command always shows the permissions currently in effect, including any restrictions imposed by the ACL mask. Additional details are available in man setfacl on the cluster. If you need assistance, contact help-hpc@caltech.edu.