Guide: Multi-user Unix Permissions and Data Access Control

Tips on how to manage permissions and data access control.

This guide explains how to set up accounts when there are multiple unix users interacting with the same CryoSPARC instance. For standard instructions about how to set up unix accounts for CryoSPARC installation see the Installation Pre-requisites.

The permissions system built into Linux (and all Unix-like operating systems) can be used to make it easier for multiple users to interact with CryoSPARC's data, or to establish a degree of separation between data belonging to different research teams. This page offers some tips on how this can be done.

Changing file permissions has security implications. If you aren't familiar with how Unix permissions work, it is advisable to consult with your system administrator, consult your operating system's documentation, or do some online research into Unix permissions before running the commands in this guide.

Allowing users' Linux accounts to access CryoSPARC files

CryoSPARC should be installed under its own operating system account. Typically, individual researchers will have their own accounts for accessing the computer(s) that CryoSPARC is installed on. By default on most Linux distributions, user accounts cannot modify files created by other user accounts, so the accounts belonging to individual researchers can only read files created or owned by CryoSPARC. This can be a barrier when trying to, for example, copy exported job files into another project for import. The standard permission system built into Linux can be used to work around this problem. Below is an example of how.

For the purpose of this example, we'll assume we are working with a fresh CryoSPARC installation. We will create a cryosparc user account (all CryoSPARC processes will run as this user), and we'll create two user accounts for people who will be using CryoSPARC.

root@host:~# useradd cryosparc
root@host:~# useradd alice
root@host:~# useradd tom

We'll add Alice and Tom's accounts to the "cryosparc" group:

root@host:~# usermod -aG cryosparc alice
root@host:~# usermod -aG cryosparc tom

Since in this example we're assuming this is a brand new CryoSPARC installation, we'll set up the directory that we will be storing our project files in. We'll then change the ownership of that directory so that it's under the control of the cryosparc account and group, and lastly we'll change the permissions on that directory. Specifically, we want g+ws, which will make anyone in the cryosparc group able to write to that directory (that's the w), and will make it so that any time new file is created in that directory, the file is owned by the cryosparc group (that's the s).

root@host:~# mkdir -p /data/cryosp_projs
root@host:~# chown cryosparc:cryosparc /data/cryosp_projs
root@host:~# chmod g+ws /data/cryosp_projs/

A demonstration of the result:

# the cryosparc user creates a bunch of files

root@host:~# su cryosparc
cryosparc@host:/root$ touch /data/cryosp_projs/file1
cryosparc@host:/root$ touch /data/cryosp_projs/file2
cryosparc@host:/root$ touch /data/cryosp_projs/file3
cryosparc@host:/root$ ls -l /data/cryosp_projs/
total 0
-rw-rw-r-- 1 cryosparc cryosparc 0 Jun 18 17:05 file1
-rw-rw-r-- 1 cryosparc cryosparc 0 Jun 18 17:05 file2
-rw-rw-r-- 1 cryosparc cryosparc 0 Jun 18 17:05 file3
cryosparc@host:/root$ exit


# alice logs in, and also creates a file in that directory

root@host:~# su alice
alice@host:/root$ touch /data/cryosp_projs/file4
alice@host:/root$ ls -l /data/cryosp_projs/
total 0
-rw-rw-r-- 1 cryosparc cryosparc 0 Jun 18 17:05 file1
-rw-rw-r-- 1 cryosparc cryosparc 0 Jun 18 17:05 file2
-rw-rw-r-- 1 cryosparc cryosparc 0 Jun 18 17:05 file3
-rw-rw-r-- 1 alice     cryosparc 0 Jun 18 17:06 file4
alice@host:/root$ exit

# notice how the file alice made is owned by the cryosparc group.
#
# now tom can log in and is able to modify the files created by...
# ... both alice and cyosparc

root@host:~# su tom
tom@host:/root$ rm /data/cryosp_projs/file2 
tom@host:/root$ rm /data/cryosp_projs/file4
tom@host:/root$ ls -l /data/cryosp_projs/
total 0
-rw-rw-r-- 1 cryosparc cryosparc 0 Jun 18 17:05 file1
-rw-rw-r-- 1 cryosparc cryosparc 0 Jun 18 17:05 file3
tom@host:/root$ touch /data/cryosp_projs/file
tom@host:/root$ ls /data/cryosp_projs/ -l
total 0
-rw-rw-r-- 1 tom       cryosparc 0 Jun 18 17:07 file
-rw-rw-r-- 1 cryosparc cryosparc 0 Jun 18 17:05 file1
-rw-rw-r-- 1 cryosparc cryosparc 0 Jun 18 17:05 file3

On some systems, the default umask variable may disable group write permissions. This would cause new files created by a user to not have group write permission unless manually changed with chmod. You can determine what the current umask is by running umask at a command prompt. If the second-to-last digit is not zero, you may run into issues. Putting umask 0002 in the ~/.bashrc file for the cryosparc account and each individual user account will correct this issue if it occurs.

Establishing teams of users, and limiting access to data owned by another team

Another area where unix permissions can help is in separating CryoSPARC users into teams that cannot interact with each other's data. Be sure to read the above section before this one, as a few important ideas are not repeated here.

While this guide can be used as a basis for limiting access to data and projects at the level of unix user accounts, the cryosparc user can still access the data from all teams. This is necessary for CryoSPARC to function correctly. As a result, users could still access another group's work by using the CryoSPARC user interface and navigating to a project directory owned by another group. One group could, for example, import raw data owned by another group. This will be addressed in a future CryoSPARC release.

This guide will proceed by example, similar to the previous.

We assume we're starting with a blank slate. Suppose we have four researchers in two separate research groups: Alice and Tom are in the 'lab1' group, Dmitri and Sonja are in the 'lab2' group.

root@host:~# useradd tom
root@host:~# useradd alice
root@host:~# useradd dmitri
root@host:~# useradd sonja
root@host:~# groupadd lab1
root@host:~# groupadd lab2
root@host:~# usermod -aG lab1 tom
root@host:~# usermod -aG lab1 alice
root@host:~# usermod -aG lab2 dmitri
root@host:~# usermod -aG lab2 sonja 

# add the cryosparc user account to both lab1 and lab2

root@host:~# useradd cryosparc
root@host:~# usermod -aG lab1 cryosparc
root@host:~# usermod -aG lab2 cryosparc

Create the directory that will be used to store CryoSPARC projects, and establish the same permissions as in the previous guide.

To briefly recap, we're going to use "chmod g+sw", where the "s" means that files created within the folder will be associated with the folder's group. Right now, that isn't terribly useful as we haven't added any users to the cryosparc group. But that "s" setting - the "setgid" bit, will be set on any created subdirectories as well, which will become important shortly.

root@host:~# mkdir -p /data/cryosp_projs
root@host:~# chmod g+ws /data/cryosp_projs/
root@host:~# chown cryosparc:cryosparc /data/cryosp_projs/

At this point, create some projects via the CryoSPARC UI which, will automatically create project subfolders. (e.g. "P1", "P2", "P3", etc). Decide which project subfolders should be owned by which group, and change the folder ownership appropriately as shown below. Note that the 'mkdir' lines are just simulating what the UI will do when creating a project - these don't need to actually be run.

root@host:~# su cryosparc
cryosparc@host:/root$ cd /data/cryosp_projs/
cryosparc@host:/data/cryosp_projs$ mkdir P1
cryosparc@host:/data/cryosp_projs$ mkdir P2
cryosparc@host:/data/cryosp_projs$ mkdir P3
cryosparc@host:/data/cryosp_projs$ chgrp lab1 P1
cryosparc@host:/data/cryosp_projs$ chgrp lab2 P2
cryosparc@host:/data/cryosp_projs$ chgrp lab2 P3
cryosparc@host:/data/cryosp_projs$ chmod o-rx *
cryosparc@host:/data/cryosp_projs$ ls -l
total 12
drwxrws--- 2 cryosparc lab1 4096 Jun 18 17:12 P1
drwxrws--- 2 cryosparc lab2 4096 Jun 18 17:12 P2
drwxrws--- 2 cryosparc lab2 4096 Jun 18 17:12 P3
cryosparc@host:/data/cryosp_projs$ exit

Take a look at the output of the ls -l command. Notice that each project folder has an "s" where the group "x" would normally be. This happened because we added the "s" bit to the cryosparc_projs directory before we created the projects (it could be added with chmod if we were doing this retroactively). As a result of the presence of that "s" bit and the fact that each project folder is now owned by one of the lab groups, any files created inside the project folders will be owned by the corresponding lab group, which allows our researcher accounts to access and modify them as appropriate.

Notice also that we used chmod o-rx, meaning that users who aren't cryosparc or part of the appropriate lab group cannot even see the contents of the project directories.

The resulting configuration is demonstrated below:

root@host:~# su tom
tom@host:/root$ cd /data/cryosp_projs/
tom@host:/data/cryosp_projs$ ls
P1  P2	P3
tom@host:/data/cryosp_projs$ cd P1/
tom@host:/data/cryosp_projs/P1$ touch file1
tom@host:/data/cryosp_projs/P1$ cd ..
tom@host:/data/cryosp_projs$ cd P2
bash: cd: P2: Permission denied
tom@host:/data/cryosp_projs$ exit


root@host:~# su sonja
sonja@host:/root$ cd /data/cryosp_projs/
sonja@host:/data/cryosp_projs$ ls P1
ls: cannot open directory 'P1': Permission denied
sonja@host:/data/cryosp_projs$ touch P3/file
sonja@host:/data/cryosp_projs$ ls -l P3
total 0
-rw-rw-r-- 1 sonja lab2 0 Jun 18 17:14 file
sonja@host:/data/cryosp_projs$ exit


root@host:~# su cryosparc
cryosparc@host:/root$ cd /data/cryosp_projs/
cryosparc@host:/data/cryosp_projs$ ls
P1  P2	P3
cryosparc@host:/data/cryosp_projs$ find
.
./P3
./P3/file
./P1
./P1/file1
./P2
cryosparc@host:/data/cryosp_projs$ rm P3/file
cryosparc@host:/data/cryosp_projs$ rm P1/file1