Administrating your JupyterHub

Administrators are responsible for configuring, securing, and maintaining JupyterHub to ensure reliable and performant operation.

Resource management

The JupyterHub installer bundles a conda environment that includes SystemdSpawner to manage resource allocation, security, and process isolation for user notebooks by integrating with systemd and Linux cgroups. SystemdSpawner provides:

Memory and CPU limits per user
Fair scheduling independent of process count
Accurate resource accounting via cgroups
Path restrictions for user write access
Automatic log collection to journald with rotation
Process isolation through systemd units

Configuration file location

JupyterHub configuration is managed in:

/opt/jupyterhub/etc/jupyterhub/jupyterhub_config.py

Basic resource configuration

Set default resource limits for all users:

c.JupyterHub.spawner_class = 'systemdspawner.SystemdSpawner'
c.SystemdSpawner.default_shell = '/bin/bash'
c.SystemdSpawner.mem_limit = '2G'
c.SystemdSpawner.cpu_limit = 1.0
c.SystemdSpawner.isolate_tmp = True
c.SystemdSpawner.isolate_devices = True
c.SystemdSpawner.disable_user_sudo = True
c.SystemdSpawner.unit_extra_properties = {'RuntimeDirectoryPreserve': 'no'}

Advanced resource configuration

Working directory and paths

As an admin, you can control how users access different parts of the workspace. For example, you might make shared data readonly while allowing notebook outputs to be writeable. To configure workspace locations:

c.SystemdSpawner.user_workingdir = '/shared/users/{USERNAME}'
c.SystemdSpawner.readonly_paths = ['/opt/shared-data']
c.SystemdSpawner.readwrite_paths = ['/tmp', '/shared/notebook-outputs']

Applying configuration changes

Before you restart the JupyterHub service, have all users save their work and log out. JupyterHub is configured through the jupyterhub_config.py file. Apply any configuration updates to that file, then restart the JupyterHub service:

# Validate configuration
sudo /opt/jupyterhub/bin/jupyterhub --config=/opt/jupyterhub/etc/jupyterhub/jupyterhub_config.py --generate-config

# Restart JupyterHub
sudo systemctl restart jupyterhub

# Check status
sudo systemctl status jupyterhub

Security management

SSL/TLS certificate management

Third-party certificates
Self-signed certificates

To replace certificates from external providers, copy the new certs to the correct location:

# Copy new certificates
sudo cp your-cert.crt /opt/jupyterhub/certs/cert.pem
sudo cp your-key.key /opt/jupyterhub/certs/cert.key

# Restart services
sudo systemctl restart nginx jupyterhub

Generate new self-signed certificates using the DIY-SSL-CA package:

# Replace <HOSTNAME> with your JupyterHub server hostname
cd DIY-SSL-CA
bash create_noprompt.sh <HOSTNAME>

Once you have the new certificates, copy them to the /opt/jupyterhub/certs directory:

# Replace <HOSTNAME> with your JupyterHub server hostname
sudo cp DIY-SSL-CA/out/<HOSTNAME>/<HOSTNAME>-bundle.crt /opt/jupyterhub/certs/cert.pem
sudo cp DIY-SSL-CA/out/<HOSTNAME>/<HOSTNAME>.key /opt/jupyterhub/certs/cert.key

# Restart services
sudo systemctl restart nginx

Security hardening

Additional security configurations:

# Disable user sudo access in notebooks
c.SystemdSpawner.disable_user_sudo = True

# Isolate temporary directories
c.SystemdSpawner.isolate_tmp = True

# Isolate devices
c.SystemdSpawner.isolate_devices = True

# Set secure headers
c.JupyterHub.tornado_settings = {}

Refer to the official JupyterHub documentation for more information on using secure headers.

Monitoring & troubleshooting

Log management

JupyterHub logs
User session logs

To view JupyterHub service logs:

# View recent logs
sudo journalctl -u jupyterhub -f

# View logs for specific time period
sudo journalctl -u jupyterhub --since "2024-01-01" --until "2024-01-02"

# View logs with specific priority
sudo journalctl -u jupyterhub -p err

To view individual user session logs:

# List user sessions
sudo systemctl list-units --type=service jupyter-*

# View specific user logs
sudo journalctl -u jupyter-username

User sessions failing

Check user-specific logs:

sudo journalctl -u jupyter-username --no-pager

Package Security Manager (6.8.0)

Administrating your JupyterHub

Resource management

Configuration file location

Basic resource configuration

Advanced resource configuration

Working directory and paths

Applying configuration changes

Security management

SSL/TLS certificate management

Security hardening

Monitoring & troubleshooting

Log management

User sessions failing

Need more help with JupyterHub?

​Resource management

​Configuration file location

​Basic resource configuration

​Advanced resource configuration

​Working directory and paths

​Applying configuration changes

​Security management

​SSL/TLS certificate management

​Security hardening

​Monitoring & troubleshooting

​Log management

​User sessions failing

​Need more help with JupyterHub?

Resource management

Configuration file location

Basic resource configuration

Advanced resource configuration

Working directory and paths

Applying configuration changes

Security management

SSL/TLS certificate management

Security hardening

Monitoring & troubleshooting

Log management

User sessions failing

Need more help with JupyterHub?