Debian Codegraph @

docs/source/howto/configuration/config-sudo.md

raw
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`.