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