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

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

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

Run it manually:

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

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

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

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

```ini
[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`:

```ini
[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:

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

Check its status:

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

Run the repair immediately through systemd:

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

View logs:

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

## What gets changed

For each running local Kasm workspace, the script compares:

```text
public.kasms.container_ip
```

with the actual Docker address on:

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

```text
6901
4901
4902
4903
```

For example:

```text
proxy_pass https://172.18.0.11:6901/;
```

becomes:

```text
proxy_pass https://172.18.0.7:6901/;
```

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

```text
<container_id>.conf.bak.YYYYMMDD-HHMMSS
```

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