Reverse Proxy

Overview

Administrators may desire to run Kasm Workspaces behind a reverse proxy such as Nginx or Caddy . A handful of configurations are required for communication to properly flow between the proxy and Kasm.

Important

Once Kasm is placed behind a reverse proxy, be sure to update the Zone configuration. See Update Zones.

../_images/reverse_proxy.png

Kasm Workspaces Behind a Reverse Proxy

Troubleshooting info can be found on the Troubleshooting Page

Running Kasm Workspaces on a Non-Standard Port

By default, Kasm Workspaces will listen on port 443. Administrators may wish to run the application on another port so that the reverse proxy can run on port 443.

During the installation pass the -L flag to choose a different port. e.g sudo bash kasm_release/install.sh -L 8443

Users will now access Kasm Workspaces via the defined port https://kasm.server:8443

Example Nginx Config

Below is an example Nginx config with the appropriate settings for Kasm annotated. In this example, Nginx is listening on port 443 and Kasm Workspaces is listening on port 8443

Example Nginx Configuration
 server {
     listen 443 ssl;
     ssl_certificate /etc/nginx/ssl/nginx.crt;
     ssl_certificate_key /etc/nginx/ssl/nginx.key;

     location / {
         # The following configurations must be configured when proxying to Kasm Workspaces

         # WebSocket Support
         proxy_set_header        Upgrade $http_upgrade;
         proxy_set_header        Connection "upgrade";

         # Host and X headers
         proxy_set_header        Host $host;
         proxy_set_header        X-Real-IP $remote_addr;
         proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header        X-Forwarded-Proto $scheme;

         # Connectivity Options
         proxy_http_version      1.1;
         proxy_read_timeout      1800s;
         proxy_send_timeout      1800s;
         proxy_connect_timeout   1800s;
         proxy_buffering         off;

         # Allow large requests to support file uploads to sessions
         client_max_body_size 10M;

         # Proxy to Kasm Workspaces running locally on 8443 using ssl
         proxy_pass https://127.0.0.1:8443 ;
     }
 }

Multiple Server Names

Kasm Workspaces does not support being proxied to using alternate paths, (e.g https://example.com/kasm/). If Administrators desire to run multiple applications behind Nginx, it is recommended to use a dedicated server_name for traffic destined for Kasm. (e.g https://kasm.example.com/). See Nginx Server Names documentation for more details.

Multiple Server Names Example
 server {
     listen 443 ssl;
     server_name app1.example.com;
     ssl_certificate /etc/nginx/ssl/nginx.crt;
     ssl_certificate_key /etc/nginx/ssl/nginx.key;

     location / {
         return 200 'App 1';
         add_header Content-Type text/plain;
     }
 }

 server {
     listen 443 ssl;
     server_name kasm.example.com;
     ssl_certificate /etc/nginx/ssl/nginx.crt;
     ssl_certificate_key /etc/nginx/ssl/nginx.key;

     location / {
         # The following configurations must be configured when proxying to Kasm Workspaces

         # WebSocket Support
         proxy_set_header        Upgrade $http_upgrade;
         proxy_set_header        Connection "upgrade";

         # Host and X headers
         proxy_set_header        Host $host;
         proxy_set_header        X-Real-IP $remote_addr;
         proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header        X-Forwarded-Proto $scheme;

         # Connectivity Options
         proxy_http_version      1.1;
         proxy_read_timeout      1800s;
         proxy_send_timeout      1800s;
         proxy_connect_timeout   1800s;
         proxy_buffering         off;

         # Allow large requests to support file uploads to sessions
         client_max_body_size 10M;

         # Proxy to Kasm Workspaces running locally on 8443 using ssl
         proxy_pass https://127.0.0.1:8443 ;
     }
 }

Example Caddy Config

Below is an example Caddyfile with the appropriate settings for Kasm annotated. In this example Caddy is listening on port 443 and Kasm Workspaces is listening on port 8443

Example Caddyfile
 192.168.117.130:443
 tls self_signed
 log stdout

 # Proxy to Kasm running locally on port 8443
 proxy / https://localhost:8443 {

         # By default Kasm Workspaces installs with self-signed certificates. If these are not replaced
         # then Caddy must be instructed to skip verification of these certs.
         insecure_skip_verify

         # WebSocket Support
         header_upstream Connection {>Connection}
         header_upstream Upgrade {>Upgrade}


         # Host and X headers
         header_upstream Host {host}
         header_upstream X-Real-IP {remote}
         header_upstream X-Forwarded-For {remote}
         header_upstream X-Forwarded-Port {server_port}
         header_upstream X-Forwarded-Proto {scheme}
 }

Example Caddy V2 Config

Below is an example V2 Caddyfile. In this example Caddy is listening on port 443 and Kasm Workspaces is listening on port 8443

Example Caddyfile V2
 {
      local_certs
      default_sni kasm.example.local
   }
   https://kasm.example.local:443 {

           reverse_proxy https://127.0.0.1:8443 {
                   transport http {
                           tls_insecure_skip_verify
                   }

               header_up Host {host}
               header_up X-Real-IP {remote}
               header_up X-Forwarded-For {remote}
               header_up X-Forwarded-Port {server_port}
               header_up X-Forwarded-Proto {scheme}

           }
 }

Example HAProxy Config

Below is an example HAProxy config with the appropriate settings for Kasm annotated. In this example HAProxy is listening on port 443 and Kasm Workspaces is listening on port 8443

Example HAProxy config
 global
         log /dev/log    local0
         log /dev/log    local1 notice
         chroot /var/lib/haproxy
         stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners
         stats timeout 30s
         user haproxy
         group haproxy
         daemon

         # Default SSL material locations
         ca-base /etc/ssl/certs
         crt-base /etc/ssl/private

         ssl-default-bind-ciphers ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:RSA+AESGCM:RSA+AES:!aNULL:!MD5:!DSS
         ssl-default-bind-options no-sslv3

 defaults
         log     global
         mode    http
         option  httplog
         option  dontlognull
         timeout connect 5000
         timeout client  50000
         timeout server  50000
         errorfile 400 /etc/haproxy/errors/400.http
         errorfile 403 /etc/haproxy/errors/403.http
         errorfile 408 /etc/haproxy/errors/408.http
         errorfile 500 /etc/haproxy/errors/500.http
         errorfile 502 /etc/haproxy/errors/502.http
         errorfile 503 /etc/haproxy/errors/503.http
         errorfile 504 /etc/haproxy/errors/504.http

 frontend localhost
        bind *:443 ssl crt /tmp/all.pem
        redirect scheme https if !{ ssl_fc }
        mode http
        default_backend node

 backend node
         mode http
         option forwardfor
         server kasm 127.0.0.1:8443 check ssl verify none
         http-request set-header X-Forwarded-Port %[dst_port]
         http-request add-header X-Forwarded-Proto https if { ssl_fc }

Example Apache Config

Below is an example Apache config with the appropriate settings for Kasm annotated. In this example, Apache is listening on port 443 and Kasm Workspaces is listening on port 8443.

Example Apache Configuration
 <VirtualHost *:443>
   # Server and ssl
   ServerName kasm.example.com
   SSLEngine on
   SSLCertificateFile /etc/ssl/apache2/server.pem
   SSLCertificateKeyFile /etc/ssl/apache2/server.key
   # Websocket upgrade
   RewriteEngine on
   RewriteCond ${HTTP:Upgrade} websocket [NC]
   RewriteCond ${HTTP:Connection} upgrade [NC]
   RewriteRule .* "wss://127.0.0.1:8443/$1" [P,L]
   # Proxy
   SSLProxyEngine on
   SSLProxyVerify none
   SSLProxyCheckPeerCN off
   SSLProxyCheckPeerName off
   SSLProxyCheckPeerExpire off
   ProxyPreserveHost on
   ProxyPass / https://127.0.0.1:8443/
   ProxyPassReverse / https://127.0.0.1:8443/
   ProxyRequests off
 </VirtualHost>

Update Zones

In order for clients to properly make connections to Kasm sessions when using a reverse proxy, the Upstream Auth Address and Proxy Port settings for each Deployment Zone must be updated. Update the Proxy Port setting to 0, and Kasm Workspaces will attempt to automatically determine the correct port from window.location.port. Update the Upstream Auth Address with either the word “proxy” or the IP or FQDN of the Kasm Workspaces server if using a single-server installation or if using a multi-server deployment, using the IP or FQDN of the Web App role for that Zone.

Note

Updates to Zone settings are applied to new sessions created after the change. Resuming existing sessions will not have the changes applied.

  1. Log into the Kasm Workspaces UI as an administrator.

  2. Select Zones.

  3. Edit the default Zone.

  4. Change the Upstream Auth Address setting to the “proxy” or the IP or FQDN of the Kasm Workspaces server.

  5. Change the Proxy Port setting to 0.

  6. Repeat for each additional Zone.

../_images/update_zone.png

Updating the default zone