.. title:: Reverse Proxy 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 :ref:`update_zones`. .. figure:: /images/reverse_proxy/reverse_proxy.png :width: 90% :align: center **Kasm Workspaces Behind a Reverse Proxy** Troubleshooting info can be found on the :doc:`Troubleshooting Page <../guide/troubleshooting>` 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** .. code-block:: Bash :caption: Example Nginx Configuration :name: nginx_config 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. .. code-block:: Bash :emphasize-lines: 3,15 :caption: Multiple Server Names Example :name: server_names 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** .. code-block:: Bash :caption: Example Caddyfile :name: caddy_config 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** .. code-block:: Bash :caption: Example Caddyfile V2 :name: caddy_config_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** .. code-block:: Bash :caption: Example HAProxy config :name: HAProxy 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**. .. code-block:: Bash :caption: Example Apache Configuration :name: apache_config # 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 .. _update_zones: 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 :term:`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 WebApp 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. #. Log into the Kasm Workspaces UI as an administrator. #. Select **Zones**. #. Edit the default Zone. #. Change the **Upstream Auth Address** setting to the "proxy" or the IP or FQDN of the Kasm Workspaces server. #. Change the **Proxy Port** setting to 0. #. Repeat for each additional **Zone**. .. figure:: /images/reverse_proxy/update_zone.png :width: 90% :align: center **Updating the default zone**