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:

Updating PiKVM OS

To update, run following commands under the root user:

[root@pikvm ~]# pikvm-update

If you encounter an error like:

[root@pikvm ~]# pikvm-update
bash: pikvm-update: command not found

It's most likely you have an old OS release. You can update the OS as follows:

[root@pikvm ~]# rw
[root@pikvm ~]# pacman -Syy
[root@pikvm ~]# pacman -S pikvm-os-updater
[root@pikvm ~]# pikvm-update

Next time you will be able to use the usual method with pikvm-update.

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 streaming, because browser security policies will require HTTPS for them.

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:

nginx:
    https:
        port: 4430
    http:
        port: 8080

Disabling HTTPS. All requests will be handled via HTTP port 80.
```
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.

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.

handle_path /pikvm/* {
    reverse_proxy https://pikvm.local {
        transport http {
            tls_insecure_skip_verify  # Same behaviour as Nginx
        }
        header_up Host {upstream_hostport}
    }
}