Shared Work Space
This guide will show you how to manage sharing permissions on the cluster for 4 common scenarios, and explain how things work along the way to help you work effectively with other users and groups.
- You have a directory called
you10001/on the scratch filesystem.
- Your username is
- You want to give your lab mate
thy20002access to a project in the directory
partner/which you are working on together.
- Your professor / advisor's name is
- You don't want anyone to see the files in
private/except allow your lab mate and advisor to read your project notes
- You want all of your lab mates to have access to
- Your directories follow this structure:
[you10001@cn02 ~]$ tree -d /scratch/you10001 /scratch/you10001 ├── collaborator ├── lab ├── partner └── private 4 directories
It just so happens that the alphabetical order of the directories in the list above also matches how restrictive we want the directories to be,
collaborator/ being the least restrictive and
private/ being the most restrictive.
Let's get started!
You can only share or restrict directories that you own.
If someone else owns a directory, say
thy20002 owned the directory,
you should ask
thy20002 to come and read this page to help manage the sharing,
thy20002 is no longer working at the lab,
you should e-mail the cluster admins to change ownership over to you (which they will do using the
and cc your advisor so that the admins can confirm with your advisor.
You can check whether you own a directory among many other things using the
[you10001@cn02 ~]$ alias getfacl='getfacl -p'
[you10001@cn02 ~]$ getfacl /scratch/you10001/ # file: scratch/you10001/ # owner: you10001 # group: Domain_Users user::rwx group::r-x other::r-x
You can see you are the owner!
These permissions are the default for a directory you create.
We will see how to customize these settings as we go through this guide.
By the way, we used the
aliascommand to avoid the annoying message we would otherwise get of "getfacl: Removing leading '/' from absolute path names".
There are two ways to share files and directories:
- The normal UNIX permissions and managing those permissions with the
- The more modern and powerful ACL (Access Control List) system managed with the
Case 1: private directory
To make a directory private to yourself, remove both the "group" and "other" permissions.
This is what our
private/ directory looks like with the default permissions:
[you10001@cn02 ~]$ getfacl /scratch/you10001/private/ # file: scratch/you10001/private/ # owner: you10001 # group: Domain_Users user::rwx group::r-x other::r-x
Remove the read permissions from
and check the changes using
[you10001@cn02 ~]$ chmod g-rx,o-rx /scratch/you10001/private/
[you10001@cn02 ~]$ getfacl /scratch/you10001/private/ # file: scratch/you10001/private/ # owner: you10001 # group: Domain_Users user::rwx group::--- other::---
Now if someone else were to try and see the
private/ directory they would see "Permission denied":
[thy20002@cn02 ~]$ ls /scratch/you10001/private/ ls: cannot open directory /scratch/you10001/private/: Permission denied
It's important to understand 2 things about making files and directories private on our cluster:
Domain_Usersgroup is special to our cluster, and that group includes all users. This means one might want to treat the "group"
Domain_Usersas no different that "other". This universal
Domain_Usersgroup is an idiosyncrasy of our cluster that's not typical of most UNIX filesystems.
- Files can be private even if they have read permission enabled, if there is any directory in the path that blocks those read permissions. For example everything in your home directory is private to you because your
you10001directory is private. This is why even though your
~/.bashrchas read permissions for everyone it is actually private:
[thy20002@cn02 ~]$ ls /home/you10001/ ls: cannot open directory /home/you10001/: Permission denied
[you10001@cn02 ~]$ namei -l ~/.bashrc f: /home/pan14001/.bashrc dr-xr-xr-x root root / drwxr-xr-x root root home drwx------ you10001 Domain_Users you10001 -rw-r--r-- you10001 Domain_Users .bashrc
[you10001@cn02 ~]$ getfacl /home/you10001/ # file: /home/you10001/ # owner: you10001 # group: Domain_Users user::rwx group::--- other::---
Sometimes the admins are asked "can you share this file in my home directory with my lab mate"? This is a reasonable question, but is technically difficult. #Exceptions inside a private directory explains why this is not a good arrangement. The recommended way to share is to move your the file or directory somewhere else outside of the purely private directory.
Case 2: partner project
We assume that for a partner project you will want to create a new shared directory such that all files in it can be seen and edited by you and your partner.
- make a new directory
- Revoke other's access to the directory
- Grant your partner access to the directory, by adding an ACL rule with their netid.
- Change the default ACL of the directory so that all newly created files are accessible to both of you
$ mkdir /scratch/$USER-lab/ #STEP 1 create a directory on /scratch/ named your_netid-lab $ chmod go-rwx /scratch/$USER-lab/ #STEP 2 $ setfacl -m "u:partner's_netid:rwx" /scratch/$USER-lab/ #STEP 3 Replace partner's_netid with your partner's netid $ setfacl -dm "u:partner's_netid:rwx" /scratch/$USER-lab/ #STEP 4 Do the same netid replacement as step 3 $ setfacl -dm "u:$USER:rwx" /scratch/$USER-lab/ #STEP 4
If we follow the above procedure with pan14001 as our partner's netid then we will get the following ACL for /scratch/$USER-lab/:
$ getfacl -p /scratch/$USER-lab/ # file: /scratch/lwm14001-lab/ # owner: lwm14001 # group: Domain_Users user::rwx # I can read/write/execute this directory user:pan14001:rwx # My partner can read/write/execute this directory group::--- mask::rwx other::--- default:user::rwx # We can rwx all new files created by ourselves under this directory default:user:pan14001:rwx # My partner can rwx all new files created by me under this directory default:user:lwm14001:rwx # I can rwx all new files created by my partner under this directory default:group::--- default:mask::rwx default:other::---
Now to to test our new settings we can do:
$ touch example $ getfacl example # file: example # owner: lwm14001 # group: Domain_Users user::rw- user:pan14001:rwx #effective:rw- # Partner can read or write user:lwm14001:rwx #effective:rw- # I can read or write group::--- mask::rw- other::---
And it is clear that we have properly setup our new shared directory!
Case 3: multiple users in a lab
(Explain ACLs and also suggest UNIX groups for larger labs).
(Explain UNIX groups necessary for /archive)
Case 4: collaborators outside of the lab
(Permissive vs restrictive)
(Explain UNIX groups necessary to restrict permissions in /archive because ACLs disabled there)
Using ACLs: more flexible
Normal UNIX permissions managed through chown, and chmod, are extremely limited. One major limitation is that they do not allow you to provide access to just one other user, you have to provide access to a group of users, or all users. Since non-adminstrators cannot create UNIX groups, you cannot pass a file off one/more users without asking the HPC admin team to make you a group. File access control lists (facl's) solve this problem by allowing you to allow specific users/groups to access your files. The primary advantage to this is that you do not need to contact our support team to provide shared work space, and can instead create shared directories yourself.
To give one other user some permissions(same format as UNIX permissions) to access your file, you can do something akin to the following:
$ setfacl -m "u:user_name:permissions' example_file
To make your permission permeate to all new subdirectories and files you can set a default ACL for some directory.
$ setfacl -dm "u:user_name:permissions' example_dir
Properly set default ACLs, will be functionally equivalent to the shared work directories we can create for you. The advantage again being that you can make these shared work directories yourselves, with an added advantage that you can make any file or directory readable by just your colleagues. You can even make your home directory accessible.
To create a shared directory on our temporary file system you would do:
$ mkdir /scratch/shared_dir_name $ setfacl -m "u:your_user_name:rwx" -m "u:associate_1_user_name:rwx" -m "u:associate_2_user_name:rwx" /scratch/shared_dir_name $ setfacl -m "d:u:your_user_name:rwx" -m "d:u:associate_1_user_name:rwx" -m "d:u:associate_2_user_name:rwx" /scratch/shared_dir_name
You can add any number of "u:user_name:perm" fields to the above command while replacing the italicized areas appropriately.
To check some file or directories Access Control List you can do:
$ getfacl dir_or_file
For more information you can go to:
Using native permissions: more
If you're in a large group, or your work requires persistent storage, you should open a ticket with Storrs HPC support, and we will evaluate if it necessary to provide disk space on /shared/, or /archive/.
Exceptions inside a private directory
Making exceptions in a purely private directory is hard but not impossible. In general it's a bad idea and makes life complicated as we will see in the rest of this sub-section, and instead the better thing to do when you want to share a file is to move it somewhere else outside of the purely private directory.
But for the sake of better learning about how the permission system works, let's try making an exception.
In our case we want our lab mate
thy20002 to be able to see our
notes_project_partner.txt document inside the
Give read permission to
thy20002 only using
[you10001@cn02 ~]$ setfacl -m u:thy20002:r /scratch/you10001/private/notes_project_partner.txt
[you10001@cn02 ~]$ getfacl /scratch/you10001/private/notes_project_partner.txt # file: /scratch/you10001/private/notes_project_partner.txt # owner: you10001 # group: Domain_Users user::rw- user:thy20002:r-- group::r-- mask::r-- other::r--
However still our lab mate cannot see the file:
[thy20002@cn02 ~]$ ls /scratch/you10001/private/notes_project_partner.txt ls: cannot access /scratch/you10001/private/notes_project_partner.txt: Permission denied
This is because the entire chain of directories needs to have read permission, but we took it away with the chmod command.
namei command helps show why our lab mate cannot see the file by inspecting all the directories in the path:
[you10001@cn02 ~]$ namei -l /scratch/you10001/private/notes_project_partner.txt f: /scratch/you10001/private/notes_project_partner.txt dr-xr-xr-x root root / lrwxrwxrwx root root scratch -> /gpfs/scratchfs1 dr-xr-xr-x root root / drwxr-xr-x root root gpfs drwxrwxrwt root root scratchfs1 drwxr-xr-x you10001 Domain_Users you10001 drwx------ you10001 Domain_Users private -rw-r--r-- you10001 Domain_Users notes_project_partner.txt
So we need to add an exception to the
[you10001@cn02 ~]$ setfacl -m u:hpc-pan:rx /scratch/you10001/private/