first commit

README.md

@@ -0,0 +1,184 @@
+# 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.