diff --git a/docs/reverse_proxy.md b/docs/reverse_proxy.md new file mode 100644 index 00000000..247bc58d --- /dev/null +++ b/docs/reverse_proxy.md @@ -0,0 +1,118 @@ +# Reverse Proxy + +A reverse proxy allows you to pass requests through your web server to another site or program. +The reverse proxy will make it look like PiKVM Web UI is a page within your existing site. + +This is especially useful if: + +* You need to access the WebUI on port `80` or `443` but you already host a website on the same device. + +* You want to share SSL certificates with an existing site. + +* You want to share authentication with an existing setup. + + +----- +## PiKVM Configuration + +PiKVM supports reverse proxying since KVMD 4.51. For older version, please update OS first: + +{!_update_os.md!} + +By default, PiKVM redirects all requests from HTTP port `80` to HTTPS port `443` with self-signed +certificate. For the simplest configuration, you can leave it as it is, and terminate +SSL traffic from PiKVM on your web server. + +Alternatively, you can change the HTTP and HTTPS ports on PiKVM or disable HTTPS at all +to deliver HTTP-only traffic to your server. + +In both cases you should take care of your own SSL certificate for your web server because +when using HTTP-only access to your website, you will lose the ability to use some features +such as [Direct H.264](video.md) streaming, because browser security policies will require +HTTPS for them. + +??? example "Various examples with changing HTTP/HTTPS settings" + + PiKVM uses Nginx internally, so don't be confused by its own configuration, + it has nothing to do with your reverse proxy if you're using Nginx too. + + * Changing HTTP and HTTPS ports. Place this config to `/etc/kvmd/override.yaml` on PiKVM: + + ```yaml + nginx: + https: + port: 4430 + http: + port: 8080 + ``` + + * Disabling HTTPS. All requests will be handled via HTTP port `80`. + + ```yaml + nginx: + https: + enabled: false + ``` + + Don't forget to run `systemctl restart kvmd-nginx` to apply your changes. + +----- +## Server Configuration + +If you have access to your web server’s configuration use the following examples +to pass the location `/pikvm` on the server to PiKVM Web UI hosted on `https://pikvm.local` +on HTTPS port `443`. + + +### Nginx + +Nginx does not validate certificates by default and PiKVM's self-signed certificate is fine for it. + +```nginx +location /pikvm { + rewrite ^/pikvm$ / break; + rewrite ^/pikvm\?(.*)$ ?$1 break; + rewrite ^/pikvm/(.*)$ /$1 break; + proxy_redirect ~^(/.*)$ /pikvm$1; + proxy_pass https://pikvm.local; + + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Scheme $scheme; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Port $server_port; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + + # For some handles (like MJPEG) buffering should be disabled + postpone_output 0; + proxy_buffering off; + proxy_ignore_headers X-Accel-Buffering; + + # Some handles (ends with /ws) are WebSockets + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_connect_timeout 7d; + proxy_send_timeout 7d; + proxy_read_timeout 7d; + + # Some other handles requires big POST payload + client_max_body_size 0; + proxy_request_buffering off; +} +``` + + +### Caddy + +Caddy doesn't like self-signed certificates, so we'll have to convince it that it's okay. + +```nginx +handle_path /pikvm/* { + reverse_proxy https://pikvm.local { + transport http { + tls_insecure_skip_verify # Same behaviour as Nginx + } + header_up Host {upstream_hostport} + } +} +``` diff --git a/mkdocs.yml b/mkdocs.yml index 90b63075..a7506493 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -82,6 +82,7 @@ nav: - "Networking": - "Internet access": - "Port forwarding": port_forwarding.md + - "Reverse proxy": reverse_proxy.md - "Tailscale VPN": tailscale.md - "Cloudflare Tunnel": cloudflared.md - "Setting up Wi-Fi": wifi.md