SudoSpawner

The SudoSpawner, derived from the LocalProcessSpawner, enables JupyterHub to spawn single-user servers for other UNIX users without running JupyterHub as the root user. This works by granting permissions to use sudo to start an intermediate process from a specific script.

The sudospawner mediator script, the intermediate process, can only do two things:

1. send a signal to another process using the os.kill() call
2. spawn single-user servers

Installation and setup

1. Install sudospawner in the Python environment running JupyterHub.

   pip install sudospawner
   

2. Grant a UNIX user sudo access to the sudospawner mediator script.

3. To configure JupyterHub to use SudoSpawner, add the following to your jupyterhub_config.py:

   c.JupyterHub.spawner_class = "sudo"
   

   The JupyterHub documentation has additional information about creating a configuration file, if needed, and recommended file locations for configuration files.

Dynamic UNIX user creation

A JupyterHub Authenticator can be configured to create UNIX users when needed. This however require the UNIX user running JupyterHub to have permissions to do so.

Until this is documented better in this README (help wanted), please refer to the discussion in issue #58.

Custom singleuser launch command

In order to limit what permissions the use of sudospawner grants the Hub, when a single-user server is launched the executable spawned is hardcoded as dirname(sudospawner)/jupyterhub-singleuser. This requires the sudospawner executable to be in the same directory as the jupyterhub-singleuser command. It is very important that users cannot modify the bin/ directory containing sudospawner, otherwise they can modify what sudospawner actually enables JupyterHub to do.

You may want to initialize user environment variables before launching the server, or do other initialization. If you install a script called sudospawner-singleuser next to sudospawner, this will be used instead of the direct jupyterhub-singleuser command.

For example, you might want to spawn notebook servers from conda environments that are revised and deployed separately from your hub instance.

#!/bin/bash -l
set -e

# Activate the notebook environment
source /opt/miniconda/bin/activate /opt/envs/notebook-latest

# Show environment info in the log to aid debugging
conda info

# Delegate the notebook server launch to the jupyterhub-singleuser script.
# this is how most sudospawner-singleuser scripts should end.
exec "$(dirname "$0")/jupyterhub-singleuser" $@

Example

The example folder provides an example configuration for setting up a JupyterHub system, without any need to run anything as root.