kasm-fix-session-ips/README.md

Kasm Session IP Fix

kasm-fix-session-ips.sh repairs stale Kasm Workspaces session IP mappings after a host or Docker restart.

The problem occurs when Docker assigns an existing Kasm workspace container a new address, while Kasm still keeps the old address in:

• PostgreSQL: public.kasms.container_ip
• nginx session config: conf/nginx/containers.d/<container_id>.conf

This can cause Kasm sessions to stay in running state while opening the desktop returns 502 Bad Gateway.

The script:

1. Finds all running Kasm container sessions in public.kasms.
2. Reads each container's actual IP from Docker.
3. Updates public.kasms.container_ip when it is stale.
4. Updates the matching nginx containers.d/<container_id>.conf.
5. Creates a backup of every nginx config it changes.
6. Runs nginx -t.
7. Reloads kasm_proxy only if the nginx configuration is valid and was changed.

Requirements

• Kasm Workspaces single-server/containerised installation
• Docker
• PostgreSQL container named kasm_db
• Kasm proxy container named kasm_proxy
• Docker network named kasm_default_network
• flock
• root privileges

Defaults can be overridden with environment variables:

KASM_DB_CONTAINER=kasm_db
KASM_PROXY_CONTAINER=kasm_proxy
KASM_NETWORK=kasm_default_network
DB_USER=kasmapp
DB_NAME=kasm
WAIT_SECONDS=120

Install

Clone or copy the files to the Kasm host, then install the script:

sudo install -m 0755 kasm-fix-session-ips.sh /usr/local/sbin/kasm-fix-session-ips

Run it manually:

sudo /usr/local/sbin/kasm-fix-session-ips

A healthy system where no changes are required should produce output similar to:

Using nginx config root: /opt/kasm/1.17.0/conf/nginx
Session e1241aac-ab8c-4e82-b1ae-db5962076b75:
  container=354e7ee145644b71b9c5899fd35c4f7779111d5064bb9db9f3d720009b3e579c
  db_ip=172.18.0.7
  docker_ip=172.18.0.7
Done: processed=1 db_fixed=0 nginx_fixed=0

If Docker changed the workspace address, the output will look similar to:

db_ip=172.18.0.7
docker_ip=172.18.0.13
DB fixed: 172.18.0.7 -> 172.18.0.13
nginx fixed: proxy_pass targets -> 172.18.0.13
Validating nginx configuration...
Reloading nginx...
Done: processed=1 db_fixed=1 nginx_fixed=1

systemd service

Create /etc/systemd/system/kasm-fix-session-ips.service:

[Unit]
Description=Repair stale Kasm Workspace container IP mappings
After=docker.service network-online.target
Requires=docker.service

[Service]
Type=oneshot
ExecStart=/usr/local/sbin/kasm-fix-session-ips
TimeoutStartSec=180

systemd timer

Create /etc/systemd/system/kasm-fix-session-ips.timer:

[Unit]
Description=Periodically repair stale Kasm Workspace container IP mappings

[Timer]
OnBootSec=30s
OnUnitActiveSec=2min
AccuracySec=10s
Persistent=true
Unit=kasm-fix-session-ips.service

[Install]
WantedBy=timers.target

Enable the timer:

sudo systemctl daemon-reload
sudo systemctl enable --now kasm-fix-session-ips.timer

Check its status:

systemctl status kasm-fix-session-ips.timer --no-pager
systemctl list-timers kasm-fix-session-ips.timer

Run the repair immediately through systemd:

sudo systemctl start kasm-fix-session-ips.service

View logs:

journalctl -u kasm-fix-session-ips.service -n 100 --no-pager

What gets changed

For each running local Kasm workspace, the script compares:

public.kasms.container_ip

with the actual Docker address on:

kasm_default_network

If they differ, the database record is updated.

It then updates only these KasmVNC-related nginx upstream ports in the corresponding session config:

6901
4901
4902
4903

For example:

proxy_pass https://172.18.0.11:6901/;

becomes:

proxy_pass https://172.18.0.7:6901/;

Before changing a session nginx config, the script creates a timestamped backup:

<container_id>.conf.bak.YYYYMMDD-HHMMSS

If the file does not actually change, the unnecessary backup is removed.