Previous Next

# Run JupyterHub without root privileges using sudo

Note: Setting up sudo permissions involves many pieces of system configuration. It is quite easy to get wrong and very difficult to debug. Only do this if you are very sure you must.

## Overview

There are many Authenticators and Spawners available for JupyterHub. Some, such as DockerSpawner or OAuthenticator, do not need any elevated permissions. This document describes how to get the full default behavior of JupyterHub while running notebook servers as real system users on a shared system without running the Hub itself as root.

Since JupyterHub needs to spawn processes as other users, the simplest way is to run it as root, spawning user servers with [setuid](http://linux.die.net/man/2/setuid). But this isn’t especially safe, because you have a process running on the public web as root.

A more prudent way to run the server while preserving functionality is to create a dedicated user with sudo access restricted to launching and monitoring single-user servers.

## Create a user

To do this, first create a user that will run the Hub:

`bash sudo useradd rhea `

This user shouldn’t have a login shell or password (possible with -r).

## Set up sudospawner

Next, you will need [sudospawner](https://github.com/jupyter/sudospawner) to enable monitoring the single-user servers with sudo:

`bash sudo pip install sudospawner `

Now we have to configure sudo to allow the Hub user (rhea) to launch the sudospawner script on behalf of our hub users (here zoe and wash). We want to confine these permissions to only what we really need.

## Edit /etc/sudoers

To do this we add to /etc/sudoers (use visudo for safe editing of sudoers):

  • specify the list of users JUPYTER_USERS for whom rhea can spawn servers

  • set the command JUPYTER_CMD that rhea can execute on behalf of users

  • give rhea permission to run JUPYTER_CMD on behalf of JUPYTER_USERS without entering a password

For example:

```bash # comma-separated whitelist of users that can spawn single-user servers # this should include all of your Hub users Runas_Alias JUPYTER_USERS = rhea, zoe, wash

# the command(s) the Hub can run on behalf of the above users without needing a password # the exact path may differ, depending on how sudospawner was installed Cmnd_Alias JUPYTER_CMD = /usr/local/bin/sudospawner

# actually give the Hub user permission to run the above command on behalf # of the above users without prompting for a password rhea ALL=(JUPYTER_USERS) NOPASSWD:JUPYTER_CMD ```

It might be useful to modify secure_path to add commands in path.

As an alternative to adding every user to the /etc/sudoers file, you can use a group in the last line above, instead of JUPYTER_USERS:

`bash rhea ALL=(%jupyterhub) NOPASSWD:JUPYTER_CMD `

If the jupyterhub group exists, there will be no need to edit /etc/sudoers again. A new user will gain access to the application when added to the group:

`bash $ adduser -G jupyterhub newuser `

## Test sudo setup

Test that the new user doesn’t need to enter a password to run the sudospawner command.

This should prompt for your password to switch to rhea, but not prompt for any password for the second switch. It should show some help output about logging options:

```bash $ sudo -u rhea sudo -n -u $USER /usr/local/bin/sudospawner –help Usage: /usr/local/bin/sudospawner [OPTIONS]

Options:

--help

show this help information

…

And this should fail:

`bash $ sudo -u rhea sudo -n -u $USER echo 'fail' sudo: a password is required `

## Enable PAM for non-root

By default, [PAM authentication](http://en.wikipedia.org/wiki/Pluggable_authentication_module) is used by JupyterHub. To use PAM, the process may need to be able to read the shadow password database.

### Shadow group (Linux)

`bash $ ls -l /etc/shadow -rw-r-----  1 root shadow   2197 Jul 21 13:41 shadow `

If there’s already a shadow group, you are set. If its permissions are more like:

```bash

$ ls -l /etc/shadow -rw——- 1 root wheel 2197 Jul 21 13:41 shadow

```

Then you may want to add a shadow group, and make the shadow file group-readable:

`bash $ sudo groupadd shadow $ sudo chgrp shadow /etc/shadow $ sudo chmod g+r /etc/shadow `

We want our new user to be able to read the shadow passwords, so add it to the shadow group:

```bash

$ sudo usermod -a -G shadow rhea

```

If you want jupyterhub to serve pages on a restricted port (such as port 80 for http), then you will need to give node permission to do so:

`bash sudo setcap 'cap_net_bind_service=+ep' /usr/bin/node ` However, you may want to further understand the consequences of this.

You may also be interested in limiting the amount of CPU any process can use on your server. cpulimit is a useful tool that is available for many Linux distributions’ packaging system. This can be used to keep any user’s process from using too much CPU cycles. You can configure it accoring to [these instructions](http://ubuntuforums.org/showthread.php?t=992706).

### Shadow group (FreeBSD)

NOTE: This has not been tested and may not work as expected.

`bash $ ls -l /etc/spwd.db /etc/master.passwd -rw-------  1 root  wheel   2516 Aug 22 13:35 /etc/master.passwd -rw-------  1 root  wheel  40960 Aug 22 13:35 /etc/spwd.db `

Add a shadow group if there isn’t one, and make the shadow file group-readable:

`bash $ sudo pw group add shadow $ sudo chgrp shadow /etc/spwd.db $ sudo chmod g+r /etc/spwd.db $ sudo chgrp shadow /etc/master.passwd $ sudo chmod g+r /etc/master.passwd `

We want our new user to be able to read the shadow passwords, so add it to the shadow group:

`bash $ sudo pw user mod rhea -G shadow `

## Test that PAM works

We can verify that PAM is working, with:

`bash $ sudo -u rhea python3 -c "import pamela, getpass; print(pamela.authenticate('$USER', getpass.getpass()))" Password: [enter your unix password] `

## Make a directory for JupyterHub

JupyterHub stores its state in a database, so it needs write access to a directory. The simplest way to deal with this is to make a directory owned by your Hub user, and use that as the CWD when launching the server.

```bash

$ sudo mkdir /etc/jupyterhub $ sudo chown rhea /etc/jupyterhub

```

## Start jupyterhub

Finally, start the server as our newly configured user, rhea:

```bash

$ cd /etc/jupyterhub $ sudo -u rhea jupyterhub –JupyterHub.spawner_class=sudospawner.SudoSpawner

```

And try logging in.

### Troubleshooting: SELinux

If you still get a generic Permission denied PermissionError, it’s possible SELinux is blocking you. Here’s how you can make a module to allow this. First, put this in a file sudo_exec_selinux.te:

```bash module sudo_exec 1.1;

require {

type unconfined_t; type sudo_exec_t; class file { read entrypoint };

}

#============= unconfined_t ============== allow unconfined_t sudo_exec_t:file entrypoint; ```

Then run all of these commands as root:

`bash $ checkmodule -M -m -o sudo_exec_selinux.mod sudo_exec_selinux.te $ semodule_package -o sudo_exec_selinux.pp -m sudo_exec_selinux.mod $ semodule -i sudo_exec_selinux.pp `

### Troubleshooting: PAM session errors

If the PAM authentication doesn’t work and you see errors for login:session-auth, or similar, considering updating to master and/or incorporating this commit https://github.com/jupyter/jupyterhub/commit/40368b8f555f04ffdd662ffe99d32392a088b1d2 and configuration option, c.PAMAuthenticator.open_sessions = False.

} The JupyterHub API