Debian Codegraph @

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

raw
1 (howto:config:reverse-proxy)=
2
3 # Using a reverse proxy
4
5 In the following example, we show configuration files for a JupyterHub server
6 running locally on port `8000` but accessible from the outside on the standard
7 SSL port `443`. This could be useful if the JupyterHub server machine is also
8 hosting other domains or content on `443`. The goal in this example is to
9 satisfy the following:
10
11 - JupyterHub is running on a server, accessed _only_ via `HUB.DOMAIN.TLD:443`
12 - On the same machine, `NO_HUB.DOMAIN.TLD` strictly serves different content,
13 also on port `443`
14 - `nginx` or `apache` is used as the public access point (which means that
15 only nginx/apache will bind to `443`)
16 - After testing, the server in question should be able to score at least an A on the
17 Qualys SSL Labs [SSL Server Test](https://www.ssllabs.com/ssltest/)
18
19 Let's start out with the needed JupyterHub configuration in `jupyterhub_config.py`:
20
21 ```python
22 # Force the proxy to only listen to connections to 127.0.0.1 (on port 8000)
23 c.JupyterHub.bind_url = 'http://127.0.0.1:8000'
24 ```
25
26 (For Jupyterhub < 0.9 use `c.JupyterHub.ip = '127.0.0.1'`.)
27
28 For high-quality SSL configuration, we also generate Diffie-Helman parameters.
29 This can take a few minutes:
30
31 ```bash
32 openssl dhparam -out /etc/ssl/certs/dhparam.pem 4096
33 ```
34
35 ## Nginx
36
37 This **`nginx` config file** is fairly standard fare except for the two
38 `location` blocks within the main section for HUB.DOMAIN.tld.
39 To create a new site for jupyterhub in your Nginx config, make a new file
40 in `sites.enabled`, e.g. `/etc/nginx/sites.enabled/jupyterhub.conf`:
41
42 ```bash
43 # Top-level HTTP config for WebSocket headers
44 # If Upgrade is defined, Connection = upgrade
45 # If Upgrade is empty, Connection = close
46 map $http_upgrade $connection_upgrade {
47 default upgrade;
48 '' close;
49 }
50
51 # HTTP server to redirect all 80 traffic to SSL/HTTPS
52 server {
53 listen 80;
54 server_name HUB.DOMAIN.TLD;
55
56 # Redirect the request to HTTPS
57 return 302 https://$host$request_uri;
58 }
59
60 # HTTPS server to handle JupyterHub
61 server {
62 listen 443;
63 ssl on;
64
65 server_name HUB.DOMAIN.TLD;
66
67 ssl_certificate /etc/letsencrypt/live/HUB.DOMAIN.TLD/fullchain.pem;
68 ssl_certificate_key /etc/letsencrypt/live/HUB.DOMAIN.TLD/privkey.pem;
69
70 ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
71 ssl_prefer_server_ciphers on;
72 ssl_dhparam /etc/ssl/certs/dhparam.pem;
73 ssl_ciphers 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA';
74 ssl_session_timeout 1d;
75 ssl_session_cache shared:SSL:50m;
76 ssl_stapling on;
77 ssl_stapling_verify on;
78 add_header Strict-Transport-Security max-age=15768000;
79
80 # Managing literal requests to the JupyterHub frontend
81 location / {
82 proxy_pass http://127.0.0.1:8000;
83 proxy_set_header X-Real-IP $remote_addr;
84 proxy_set_header Host $http_host;
85 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
86
87 # websocket headers
88 proxy_http_version 1.1;
89 proxy_set_header Upgrade $http_upgrade;
90 proxy_set_header Connection $connection_upgrade;
91 proxy_set_header X-Scheme $scheme;
92
93 proxy_buffering off;
94 }
95
96 # Managing requests to verify letsencrypt host
97 location ~ /.well-known {
98 allow all;
99 }
100 }
101 ```
102
103 If `nginx` is not running on port 443, substitute `$http_host` for `$host` on
104 the lines setting the `Host` header.
105
106 `nginx` will now be the front-facing element of JupyterHub on `443` which means
107 it is also free to bind other servers, like `NO_HUB.DOMAIN.TLD` to the same port
108 on the same machine and network interface. In fact, one can simply use the same
109 server blocks as above for `NO_HUB` and simply add a line for the root directory
110 of the site as well as the applicable location call:
111
112 ```bash
113 server {
114 listen 80;
115 server_name NO_HUB.DOMAIN.TLD;
116
117 # Redirect the request to HTTPS
118 return 302 https://$host$request_uri;
119 }
120
121 server {
122 listen 443;
123 ssl on;
124
125 # INSERT OTHER SSL PARAMETERS HERE AS ABOVE
126 # SSL cert may differ
127
128 # Set the appropriate root directory
129 root /var/www/html
130
131 # Set URI handling
132 location / {
133 try_files $uri $uri/ =404;
134 }
135
136 # Managing requests to verify letsencrypt host
137 location ~ /.well-known {
138 allow all;
139 }
140
141 }
142 ```
143
144 Now restart `nginx`, restart the JupyterHub, and enjoy accessing
145 `https://HUB.DOMAIN.TLD` while serving other content securely on
146 `https://NO_HUB.DOMAIN.TLD`.
147
148 ### SELinux permissions for Nginx
149
150 On distributions with SELinux enabled (e.g. Fedora), one may encounter permission errors
151 when the Nginx service is started.
152
153 We need to allow Nginx to perform network relay and connect to the JupyterHub port. The
154 following commands do that:
155
156 ```bash
157 semanage port -a -t http_port_t -p tcp 8000
158 setsebool -P httpd_can_network_relay 1
159 setsebool -P httpd_can_network_connect 1
160 ```
161
162 Replace 8000 with the port the JupyterHub server is running from.
163
164 ## Apache
165
166 As with Nginx above, you can use [Apache](https://httpd.apache.org) as the reverse proxy.
167 First, we will need to enable the Apache modules that we are going to need:
168
169 ```bash
170 a2enmod ssl rewrite proxy headers proxy_http proxy_wstunnel
171 ```
172
173 Our Apache configuration is equivalent to the Nginx configuration above:
174
175 - Redirect HTTP to HTTPS
176 - Good SSL Configuration
177 - Support for WebSocket on any proxied URL
178 - JupyterHub is running locally at http://127.0.0.1:8000
179
180 ```bash
181 # Redirect HTTP to HTTPS
182 Listen 80
183 <VirtualHost HUB.DOMAIN.TLD:80>
184 ServerName HUB.DOMAIN.TLD
185 Redirect / https://HUB.DOMAIN.TLD/
186 </VirtualHost>
187
188 Listen 443
189 <VirtualHost HUB.DOMAIN.TLD:443>
190
191 ServerName HUB.DOMAIN.TLD
192
193 # Enable HTTP/2, if available
194 Protocols h2 http/1.1
195
196 # HTTP Strict Transport Security (mod_headers is required) (63072000 seconds)
197 Header always set Strict-Transport-Security "max-age=63072000"
198
199 # Configure SSL
200 SSLEngine on
201 SSLCertificateFile /etc/letsencrypt/live/HUB.DOMAIN.TLD/fullchain.pem
202 SSLCertificateKeyFile /etc/letsencrypt/live/HUB.DOMAIN.TLD/privkey.pem
203 SSLOpenSSLConfCmd DHParameters /etc/ssl/certs/dhparam.pem
204
205 # Intermediate configuration from SSL-config.mozilla.org (2022-03-03)
206 # Please note, that this configuration might be outdated - please update it accordingly using https://ssl-config.mozilla.org/
207 SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
208 SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
209 SSLHonorCipherOrder off
210 SSLSessionTickets off
211
212 # Use RewriteEngine to handle WebSocket connection upgrades
213 RewriteEngine On
214 RewriteCond %{HTTP:Connection} Upgrade [NC]
215 RewriteCond %{HTTP:Upgrade} websocket [NC]
216 RewriteRule /(.*) ws://127.0.0.1:8000/$1 [P,L]
217
218 <Location "/">
219 # preserve Host header to avoid cross-origin problems
220 ProxyPreserveHost on
221 # proxy to JupyterHub
222 ProxyPass http://127.0.0.1:8000/
223 ProxyPassReverse http://127.0.0.1:8000/
224 RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
225 </Location>
226 </VirtualHost>
227 ```
228
229 In case of the need to run JupyterHub under /jhub/ or another location please use the below configurations:
230
231 - JupyterHub running locally at http://127.0.0.1:8000/jhub/ or other location
232
233 httpd.conf amendments:
234
235 ```bash
236 RewriteRule /jhub/(.*) ws://127.0.0.1:8000/jhub/$1 [P,L]
237 RewriteRule /jhub/(.*) http://127.0.0.1:8000/jhub/$1 [P,L]
238
239 ProxyPass /jhub/ http://127.0.0.1:8000/jhub/
240 ProxyPassReverse /jhub/ http://127.0.0.1:8000/jhub/
241 ```
242
243 jupyterhub_config.py amendments:
244
245 ```python
246 # The public facing URL of the whole JupyterHub application.
247 # This is the address on which the proxy will bind. Sets protocol, IP, base_url
248 c.JupyterHub.bind_url = 'http://127.0.0.1:8000/jhub/'
249 ```