---
myst:
  html_meta:
    "description lang=en": "Placing Kasm Workspaces behind a reverse proxy using NGINX, Apache, Caddy, and HAProxy."
    "keywords": "Kasm, How to, How-to, Reverse, Proxy, NGINX, Apache, Caddy, HAProxy"
    "property=og:locale": "en_US"
---
```{title} Reverse Proxy
```

# Reverse Proxy

## Overview

Administrators may desire to run Kasm Workspaces behind a reverse proxy such as [Nginx](https://nginx.org/) or
[Caddy](https://caddyserver.com/docs/proxy) . 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](#update-zones).
```

```{figure} /images/reverse_proxy/reverse_proxy.png
: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 supports proxying via subdomains (e.g <https://kasm1.example.com/> / <https://kasm2.example.com/>) or paths (e.g <https://example.com/kasm1/> / <https://example.com/kasm2/>)

### Proxy via Subdomain

Use a dedicated `server_name` for traffic destined for Kasm. (e.g <https://kasm.example.com/>). See
[Nginx Server Names](http://nginx.org/en/docs/http/server_names.html) documentation for more details.

#### Example Nginx Config

```{code-block} Bash
:caption: Multiple Server Names Example
:emphasize-lines: 3,15
: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 Caddy v2 config with the appropriate settings for Kasm. In this example, Caddy is configured to listen
for requests on **kasm.example.com** and reverse proxy them to Kasm running on 
**https://127.0.0.1:8443** Note that we include
the **tls_insecure_skip_verify** option to skip TLS certificate verification.
For more information on configuring Caddy, check out the Caddy documentation at <https://caddyserver.com/docs/caddyfile/directives/reverse_proxy#defaults>

```{code-block} Bash
:caption: Example Caddy Configuration
:name: caddy_config

 kasm.example.com {
	reverse_proxy https://127.0.0.1:8443 {
		transport http {
			tls_insecure_skip_verify
		}
	}
}
```

#### 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 alpn http/1.1
        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

 <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>
```

### Proxy via Path

The same settings need to be sent as with subdomain proxies, we are sending the majority outside of the location block so that they apply to all the locations, but feel free to change this to suit your needs.

#### Set Proxy Path global setting

- Select **Settings > Global** from the navigation menu.
- Find the **Proxy Path** setting and update the value to match the path for this server. The value should start with a trailing slash, therefore if the path url in the address bar looks like `https://example.com/kasm1/#/settings` then the value entered should be **/kasm1**

```{figure} /images/reverse_proxy/proxy-path.webp
:align: center
**Updating the Proxy Path**
```

```{warning}
Do not use paths that overlap, for example `/kasm` and `/kasm2` as it will cause issues. This is only the case for where it's an exact overlap from the beginning including the slash. `/kasm` and `/mykasm` would be fine, `/server` and `/servers-us` would not be. When setting up for the first time, on initial login a cookie will be set for the root `/` location. After setting a path value and logging out and logging in again, the correct cookie will be set, but the original root cookie will also still exist. It is recommended to clear cookies before logging in to prevent any conflicts when first setting up.
```

#### Example Nginx Config

```{code-block} Bash
:caption: Multiple Paths Example
:emphasize-lines: 29,34
:name: server_paths

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

    # 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;

    location /kasm1/ {
        # Proxy to Kasm Workspaces running locally on 8443 using ssl
        proxy_pass https://127.0.0.1:8443/;
    }
    
    location /kasm2/ {
        # Proxy to Kasm Workspaces running externally over ssl
    	proxy_pass https://kasm.example.com/;
    }

 }
```

## 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<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 **Infrastructure** -> **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. If using reverse proxy via path then it needs to be the IP or FQDN that points directly to the upstream server if using a multiserver setup.
5. Change the **Proxy Port** setting to 0.
6. Repeat for each additional **Zone**.

```{figure} /images/reverse_proxy/update_zone.webp
:align: center
**Updating the default zone**
```