| 1 |
(howto:config:no-sudo)= |
| 2 |
|
| 3 |
# Run JupyterHub without root privileges using `sudo` |
| 4 |
|
| 5 |
**Note:** Setting up `sudo` permissions involves many pieces of system |
| 6 |
configuration. It is quite easy to get wrong and very difficult to debug. |
| 7 |
Only do this if you are very sure you must. |
| 8 |
|
| 9 |
## Overview |
| 10 |
|
| 11 |
There are many [Authenticators](authenticators) and [Spawners](spawners) available for JupyterHub. Some, such |
| 12 |
as [DockerSpawner](https://github.com/jupyterhub/dockerspawner) or [OAuthenticator](https://github.com/jupyterhub/oauthenticator), do not need any elevated permissions. This |
| 13 |
document describes how to get the full default behavior of JupyterHub while |
| 14 |
running notebook servers as real system users on a shared system, without |
| 15 |
running the Hub itself as root. |
| 16 |
|
| 17 |
Since JupyterHub needs to spawn processes as other users, the simplest way |
| 18 |
is to run it as root, spawning user servers with [setuid](https://linux.die.net/man/2/setuid). |
| 19 |
But this isn't especially safe, because you have a process running on the |
| 20 |
public web as root. |
| 21 |
|
| 22 |
A **more prudent way** to run the server while preserving functionality is to |
| 23 |
create a dedicated user with `sudo` access restricted to launching and |
| 24 |
monitoring single-user servers. |
| 25 |
|
| 26 |
## Create a user |
| 27 |
|
| 28 |
To do this, first create a user that will run the Hub: |
| 29 |
|
| 30 |
```bash |
| 31 |
sudo useradd rhea |
| 32 |
``` |
| 33 |
|
| 34 |
This user shouldn't have a login shell or password (possible with -r). |
| 35 |
|
| 36 |
## Set up sudospawner |
| 37 |
|
| 38 |
Next, you will need [sudospawner](https://github.com/jupyter/sudospawner) |
| 39 |
to enable monitoring the single-user servers with sudo: |
| 40 |
|
| 41 |
```bash |
| 42 |
sudo python3 -m pip install sudospawner |
| 43 |
``` |
| 44 |
|
| 45 |
Now we have to configure sudo to allow the Hub user (`rhea`) to launch |
| 46 |
the sudospawner script on behalf of our hub users (here `zoe` and `wash`). |
| 47 |
We want to confine these permissions to only what we really need. |
| 48 |
|
| 49 |
## Edit `/etc/sudoers` |
| 50 |
|
| 51 |
To do this we add to `/etc/sudoers` (use `visudo` for safe editing of sudoers): |
| 52 |
|
| 53 |
- specify the list of users `JUPYTER_USERS` for whom `rhea` can spawn servers |
| 54 |
- set the command `JUPYTER_CMD` that `rhea` can execute on behalf of users |
| 55 |
- give `rhea` permission to run `JUPYTER_CMD` on behalf of `JUPYTER_USERS` |
| 56 |
without entering a password |
| 57 |
|
| 58 |
For example: |
| 59 |
|
| 60 |
```bash |
| 61 |
# comma-separated list of users that can spawn single-user servers |
| 62 |
# this should include all of your Hub users |
| 63 |
Runas_Alias JUPYTER_USERS = rhea, zoe, wash |
| 64 |
|
| 65 |
# the command(s) the Hub can run on behalf of the above users without needing a password |
| 66 |
# the exact path may differ, depending on how sudospawner was installed |
| 67 |
Cmnd_Alias JUPYTER_CMD = /usr/local/bin/sudospawner |
| 68 |
|
| 69 |
# actually give the Hub user permission to run the above command on behalf |
| 70 |
# of the above users without prompting for a password |
| 71 |
rhea ALL=(JUPYTER_USERS) NOPASSWD:JUPYTER_CMD |
| 72 |
``` |
| 73 |
|
| 74 |
It might be useful to modify `secure_path` to add commands in path. (Search for |
| 75 |
`secure_path` in the [sudo docs](https://www.sudo.ws/man/1.8.14/sudoers.man.html) |
| 76 |
|
| 77 |
As an alternative to adding every user to the `/etc/sudoers` file, you can |
| 78 |
use a group in the last line above, instead of `JUPYTER_USERS`: |
| 79 |
|
| 80 |
```bash |
| 81 |
rhea ALL=(%jupyterhub) NOPASSWD:JUPYTER_CMD |
| 82 |
``` |
| 83 |
|
| 84 |
If the `jupyterhub` group exists, there will be no need to edit `/etc/sudoers` |
| 85 |
again. A new user will gain access to the application when added to the group: |
| 86 |
|
| 87 |
```bash |
| 88 |
$ adduser -G jupyterhub newuser |
| 89 |
``` |
| 90 |
|
| 91 |
## Test `sudo` setup |
| 92 |
|
| 93 |
Test that the new user doesn't need to enter a password to run the sudospawner |
| 94 |
command. |
| 95 |
|
| 96 |
This should prompt for your password to switch to `rhea`, but _not_ prompt for |
| 97 |
any password for the second switch. It should show some help output about |
| 98 |
logging options: |
| 99 |
|
| 100 |
```bash |
| 101 |
$ sudo -u rhea sudo -n -u $USER /usr/local/bin/sudospawner --help |
| 102 |
Usage: /usr/local/bin/sudospawner [OPTIONS] |
| 103 |
|
| 104 |
Options: |
| 105 |
|
| 106 |
--help show this help information |
| 107 |
... |
| 108 |
``` |
| 109 |
|
| 110 |
And this should fail: |
| 111 |
|
| 112 |
```bash |
| 113 |
$ sudo -u rhea sudo -n -u $USER echo 'fail' |
| 114 |
sudo: a password is required |
| 115 |
``` |
| 116 |
|
| 117 |
## Enable PAM for non-root |
| 118 |
|
| 119 |
By default, [PAM authentication](https://en.wikipedia.org/wiki/Pluggable_authentication_module) |
| 120 |
is used by JupyterHub. To use PAM, the process may need to be able to read |
| 121 |
the shadow password database. |
| 122 |
|
| 123 |
### Shadow group (Linux) |
| 124 |
|
| 125 |
**Note:** On [Fedora based distributions](https://fedoraproject.org/wiki/List_of_Fedora_remixes) there is no clear way to configure |
| 126 |
the PAM database to allow sufficient access for authenticating with the target user's password |
| 127 |
from JupyterHub. As a workaround we recommend use an |
| 128 |
[alternative authentication method](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators). |
| 129 |
|
| 130 |
```bash |
| 131 |
$ ls -l /etc/shadow |
| 132 |
-rw-r----- 1 root shadow 2197 Jul 21 13:41 shadow |
| 133 |
``` |
| 134 |
|
| 135 |
If there's already a shadow group, you are set. If its permissions are more like: |
| 136 |
|
| 137 |
```bash |
| 138 |
$ ls -l /etc/shadow |
| 139 |
-rw------- 1 root wheel 2197 Jul 21 13:41 shadow |
| 140 |
``` |
| 141 |
|
| 142 |
Then you may want to add a shadow group, and make the shadow file group-readable: |
| 143 |
|
| 144 |
```bash |
| 145 |
$ sudo groupadd shadow |
| 146 |
$ sudo chgrp shadow /etc/shadow |
| 147 |
$ sudo chmod g+r /etc/shadow |
| 148 |
``` |
| 149 |
|
| 150 |
We want our new user to be able to read the shadow passwords, so add it to the shadow group: |
| 151 |
|
| 152 |
```bash |
| 153 |
$ sudo usermod -a -G shadow rhea |
| 154 |
``` |
| 155 |
|
| 156 |
If you want jupyterhub to serve pages on a restricted port (such as port 80 for HTTP), |
| 157 |
then you will need to give `node` permission to do so: |
| 158 |
|
| 159 |
```bash |
| 160 |
sudo setcap 'cap_net_bind_service=+ep' /usr/bin/node |
| 161 |
``` |
| 162 |
|
| 163 |
However, you may want to further understand the consequences of this. |
| 164 |
([Further reading](https://man7.org/linux/man-pages/man7/capabilities.7.html)) |
| 165 |
|
| 166 |
You may also be interested in limiting the amount of CPU any process can use |
| 167 |
on your server. `cpulimit` is a useful tool that is available for many Linux |
| 168 |
distributions' packaging system. This can be used to keep any user's process |
| 169 |
from using too much CPU cycles. You can configure it accoring to [these |
| 170 |
instructions](https://ubuntuforums.org/showthread.php?t=992706). |
| 171 |
|
| 172 |
### Shadow group (FreeBSD) |
| 173 |
|
| 174 |
**NOTE:** This has not been tested on FreeBSD and may not work as expected on |
| 175 |
the FreeBSD platform. _Do not use in production without verifying that it works properly!_ |
| 176 |
|
| 177 |
```bash |
| 178 |
$ ls -l /etc/spwd.db /etc/master.passwd |
| 179 |
-rw------- 1 root wheel 2516 Aug 22 13:35 /etc/master.passwd |
| 180 |
-rw------- 1 root wheel 40960 Aug 22 13:35 /etc/spwd.db |
| 181 |
``` |
| 182 |
|
| 183 |
Add a shadow group if there isn't one, and make the shadow file group-readable: |
| 184 |
|
| 185 |
```bash |
| 186 |
$ sudo pw group add shadow |
| 187 |
$ sudo chgrp shadow /etc/spwd.db |
| 188 |
$ sudo chmod g+r /etc/spwd.db |
| 189 |
$ sudo chgrp shadow /etc/master.passwd |
| 190 |
$ sudo chmod g+r /etc/master.passwd |
| 191 |
``` |
| 192 |
|
| 193 |
We want our new user to be able to read the shadow passwords, so add it to the |
| 194 |
shadow group: |
| 195 |
|
| 196 |
```bash |
| 197 |
$ sudo pw user mod rhea -G shadow |
| 198 |
``` |
| 199 |
|
| 200 |
## Test that PAM works |
| 201 |
|
| 202 |
We can verify that PAM is working, with: |
| 203 |
|
| 204 |
```bash |
| 205 |
$ sudo -u rhea python3 -c "import pamela, getpass; print(pamela.authenticate('$USER', getpass.getpass()))" |
| 206 |
Password: [enter your unix password] |
| 207 |
``` |
| 208 |
|
| 209 |
## Make a directory for JupyterHub |
| 210 |
|
| 211 |
JupyterHub stores its state in a database, so it needs write access to a directory. |
| 212 |
The simplest way to deal with this is to make a directory owned by your Hub user, |
| 213 |
and use that as the CWD when launching the server. |
| 214 |
|
| 215 |
```bash |
| 216 |
$ sudo mkdir /etc/jupyterhub |
| 217 |
$ sudo chown rhea /etc/jupyterhub |
| 218 |
``` |
| 219 |
|
| 220 |
## Start jupyterhub |
| 221 |
|
| 222 |
Finally, start the server as our newly configured user, `rhea`: |
| 223 |
|
| 224 |
```bash |
| 225 |
$ cd /etc/jupyterhub |
| 226 |
$ sudo -u rhea jupyterhub --JupyterHub.spawner_class=sudospawner.SudoSpawner |
| 227 |
``` |
| 228 |
|
| 229 |
And try logging in. |
| 230 |
|
| 231 |
## Troubleshooting: SELinux |
| 232 |
|
| 233 |
If you still get a generic `Permission denied` `PermissionError`, it's possible SELinux is blocking you. |
| 234 |
Here's how you can make a module to resolve this. |
| 235 |
First, put this in a file named `sudo_exec_selinux.te`: |
| 236 |
|
| 237 |
```bash |
| 238 |
module sudo_exec_selinux 1.1; |
| 239 |
|
| 240 |
require { |
| 241 |
type unconfined_t; |
| 242 |
type sudo_exec_t; |
| 243 |
class file { read entrypoint }; |
| 244 |
} |
| 245 |
|
| 246 |
#============= unconfined_t ============== |
| 247 |
allow unconfined_t sudo_exec_t:file entrypoint; |
| 248 |
``` |
| 249 |
|
| 250 |
Then run all of these commands as root: |
| 251 |
|
| 252 |
```bash |
| 253 |
$ checkmodule -M -m -o sudo_exec_selinux.mod sudo_exec_selinux.te |
| 254 |
$ semodule_package -o sudo_exec_selinux.pp -m sudo_exec_selinux.mod |
| 255 |
$ semodule -i sudo_exec_selinux.pp |
| 256 |
``` |
| 257 |
|
| 258 |
## Troubleshooting: PAM session errors |
| 259 |
|
| 260 |
If the PAM authentication doesn't work and you see errors for |
| 261 |
`login:session-auth`, or similar, consider updating to a more recent version |
| 262 |
of jupyterhub and disabling the opening of PAM sessions with |
| 263 |
`c.PAMAuthenticator.open_sessions=False`. |