shellroom setup

shellroom setup helps you in setting up a training environment.

Standard setup

shellroom setup will:

Install the shellroom binary to /usr/local/bin. The binary is required to be in $PATH for user logins to work.
Read the users CSV file. For users without a password column: generate random passwords and update the file.
Create a system user for each entry in the users CSV file (using useradd --create-home --shell /bin/bash), and set the password.
Optional: Recursively copy files from a template folder to each user’s home folder and change their ownership.
Add shellroom join to each user’s .bash_profile so that they automatically enter the training environment after login.

Example usage

shellroom setup --users-csv my-users.csv --skeleton-copy-dir ~/my-course-data

Flags

Flag	Description
`--users-csv`	File containing the users and passwords in CSV, TSV or SSV format
`--skeleton-copy-dir`	Files and sub-folders within the skeleton directory will be copied to each user’s `$HOME`
`--skeleton-hardlink-dir`	Files and sub-folders within the skeleton directory will be copied to each user’s `$HOME` using hard-links

`--users-csv`

The users file expected by --users-csv is a simple text file specifying your users, roles and passwords.

example.csv

harry,lumos
ron,lumos
snape*,lumos

File format: The two columns can be separated by a comma (CSV format), tab (TSV format) or a whitespace (SSV). The separator is auto-detected by inspecting the first line. Hence, you can copy the two columns from a spreadsheet and simply paste them into a text file.

Usernames: As the usernames are also Linux usernames, they should contain only lowercase letters (a–z), digits (0–9), underscores (_), and dashes (-) and have a maximum length of 32 characters.

Roles: Users with an asterisk * get the trainer role, other users get the participant role.

Password: The password column is optional. If no password is provided, a random password will be generated and written to the file.

`skeleton-copy-dir`

Files and sub-folders within the skeleton directory will be copied to each user’s $HOME (via the cp -R command). The ownership of files and directories will be changed to the user. Existing files will be overwritten.

Tip

Feel free to put dotfiles like .bashrc in the skeleton folder to facilitate setting up environments (e.g., conda), $PATH and tools. System-default dotfiles created by useradd will be overwritten, so make sure niceties like coloring are included in yours.

`skeleton-hardlink-dir`

Files and sub-folders within the skeleton directory will be copied to each user’s $HOME using hard-links (via the cp -lR command). This will save disk space, but requires a) that the skeleton directory is on the same filesystem as the user home and b) that the contained files are read-only for users (otherwise they could be accidentially modified for all users). The ownership of directories will be changed to the user, but not the ownership of files. Existing files will be overwritten.

Note

Hard-linked files look like normal files but are actually stored only once. This is useful for large data files, but make sure they are read-only - otherwise, any participant could overwrite the file for all users!

For files that can be modified by users, use skeleton-copy-dir.

Command Reference shellroom start