Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jupyterhub/sudospawner

Spawn JupyterHub single-user servers with sudo
https://github.com/jupyterhub/sudospawner

jupyter jupyterhub spawner

Last synced: 27 days ago
JSON representation

Spawn JupyterHub single-user servers with sudo

Awesome Lists containing this project

README 

        
# SudoSpawner



[![PyPI](https://img.shields.io/pypi/v/sudospawner.svg)](https://pypi.python.org/pypi/sudospawner)



[![GitHub Workflow Status - Test](https://img.shields.io/github/workflow/status/jupyterhub/sudospawner/Test?logo=github&label=tests)](https://github.com/jupyterhub/sudospawner/actions)



The SudoSpawner enables [JupyterHub](https://github.com/jupyter/jupyterhub)

to spawn single-user servers without being root, by spawning an intermediate

process via `sudo`, which takes actions on behalf of the user.



The ``sudospawner`` mediator, 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



Launching the ``sudospawner`` script is the only action that requires a

JupyterHub administrator to have ``sudo`` access to execute.



## Installation and setup



1. Install:



        pip install -e .



2. [Add sudo access to the script](https://jupyterhub.readthedocs.io/en/stable/howto/configuration/config-sudo.html).



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

`jupyterhub_config.py`:



        c.JupyterHub.spawner_class='sudospawner.SudoSpawner'

    

   The [JupyterHub documentation](http://jupyterhub.readthedocs.org/en/latest/index.html)

   has additional information about [creating a configuration file](https://jupyterhub.readthedocs.io/en/latest/getting-started/config-basics.html#generate-a-default-config-file),

   if needed, and recommended file locations for configuration files.



If you would like to use JupyterLab, then all you have to do is set the `default_url`

in `jupyterhub_config.py`:



    c.Spawner.default_url = '/lab'



## 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. 



```bash

#!/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 [Dockerfile](https://github.com/jupyter/sudospawner/blob/master/examples/Dockerfile) in this repo contains an example configuration for setting up a JupyterHub system, without any need to run anything as root.