Troubleshoot Kasm Workspaces behind a reverse proxy

This reference covers common issues when Kasm Workspaces runs behind a reverse proxy such as NGINX, and how to resolve them. For setup guidance, see the reverse proxy guide. The reverse proxy must support WebSockets, and the zone configuration must be updated accordingly.

Users can reach the UI but cannot connect to a session

Run through the advanced connection troubleshooting steps.

Users cannot reach the UI at all

First, confirm that Kasm Workspaces is accessible directly, without the reverse proxy. Next, confirm that the reverse proxy can reach Kasm Workspaces with curl:

curl -k https://<ip-address>:<port>/api/__healthcheck
{"ok": true}

Replace <ip-address> with the IP address of one of your Kasm Web App servers, and <port> with the port Kasm Workspaces listens on, which is 443 by default. Repeat this test for all Web App servers and on all reverse proxies in front of Kasm Workspaces.

When you can reach Kasm Workspaces directly and can curl it from the reverse proxy, but still cannot load the UI through the reverse proxy domain or IP address, consult the documentation for your reverse proxy.

caution

When you use the RDP local client workspace option, disable the Restrict RDP Client IP Address setting in Infrastructure, then Zones. Otherwise the connection may fail, because the IP address stored with the request differs when the connection passes through a reverse proxy. The error logs report this with a message such as Invalid Request. Wrong client IP.

RDP session disconnects

Reverse proxies and load balancers time out requests after they fail to get a response from the upstream server within a set period. This can disconnect Kasm desktop and app sessions when the user is inactive. Container-based sessions send a keep-alive every 5 seconds, so most container-based sessions are unaffected. This issue primarily affects sessions brokered by the Kasm RDP HTTPS Gateway, because RDP does not send a keep-alive by default. Proxied RDP connections can disconnect when the user is inactive for longer than the reverse proxies in the path allow.

Kasm NGINX servers use a proxy_send_timeout and proxy_read_timeout of 3600 seconds, or 1 hour. The NGINX default for both is 60 seconds. RDP can send keep-alives through a registry setting. Either set a proxy_send_timeout and proxy_read_timeout on all proxies in the path that is long enough to allow for normal inactivity during an RDP session, or enable keep-alives with the registry setting.

The proxy_send_timeout and proxy_read_timeout directives are specific to NGINX. When you do not use NGINX in front of Kasm, consult the documentation for your reverse proxy or load balancer. Each vendor uses different defaults and terminology. For example, the Azure Application Gateway has a short default of 20 seconds for its request time-out setting.