sessiongurad/docs/OPERATIONS.md

Production Operations

Recommended rollout order

1. Deploy PostgreSQL and Master behind TLS/reverse proxy.
2. Configure PocketID group RBAC and verify a read-only user and an administrator.
3. Upgrade one RDS host/agent and keep profile cleanup in Dry-Run.
4. Verify heartbeat telemetry, processes, health and session history.
5. Create a canary Farm containing only that host.
6. Load the Guacamole extension and create one brokered canary connection.
7. Verify existing-session reconnect and lease behavior.
8. Add a second canary RDS host; test load balancing, drain and maintenance.
9. Enable selected-folder profile restore/backup if not already validated.
10. Enable automatic disconnected-session logoff.
11. Enable destructive cleanup only after profile backup/recovery has been exercised.
12. Expand farm membership gradually.

PostgreSQL

Production should set SESSIONGUARD_DATABASE_URL.

Example:

postgres://sessionguard:SECRET@sessionguard-postgres:5432/sessionguard?sslmode=disable

Use TLS (sslmode=require/verify modes) when PostgreSQL crosses an untrusted network. The provided compose uses an internal Docker network and therefore demonstrates sslmode=disable only for that local link.

Back up the SessionGuard database like any other control-plane database. It contains operational metadata, session usernames/SIDs, audit history and policies, but not profile files themselves.

Master backup and restore

Back up:

• PostgreSQL database
• master.json configuration (without assuming env-injected secrets are present)
• external secret-management values
• custom Guacamole extension image/tag

Restore database and configuration together. After Master starts, Agents will reconnect with their existing per-agent credentials.

Profile store backup

The profile store is independent from PostgreSQL and must be protected separately. Snapshot/backup the underlying SMB storage according to your recovery objectives.

SessionGuard maintains per-user current plus optional historical snapshots, but these are operational generations, not a replacement for storage backup.

Drain workflow

For planned patching:

1. Set host to drain.
2. Optionally send a message to users.
3. Existing users can reconnect to the same host; new users go elsewhere.
4. Wait for sessions to finish or use policy/bulk logoff as appropriate.
5. Set restart_when_drained if automatic restart is desired.
6. After reboot/health verification, set host to online.

Use maintenance when reconnects must also be blocked.

Upgrades

Master

• back up PostgreSQL;
• deploy the new binary/image;
• start one master against the DB and verify /healthz reports the expected version/store;
• verify OIDC and dashboard;
• then upgrade the Guacamole extension if required.

The database migration code is designed to be forward-applied by the Master. v0.3 also holds a PostgreSQL advisory lock and intentionally refuses a second active Master against the same database. Do not attempt active/active deployment; for manual failover stop/lose the old Master first, then start the replacement against the same restored/reachable database.

Agents

Upgrade in farm batches using drain mode. Agent state in C:\ProgramData\SessionGuard should be preserved across binary replacement.

Observability

Monitor at minimum:

• /healthz
• /metrics
• active alerts in Director
• PostgreSQL health
• profile-store availability
• master heartbeat freshness

Alert webhook delivery is best-effort and should complement, not replace, your infrastructure monitoring.

Master outage

Existing sessions and agent-side policy continue. Brokered new connections cannot be authoritatively placed while the Master is unavailable. This fail-closed behavior protects farm affinity and profile concurrency.

If emergency bypass access is required, maintain a separately controlled break-glass RDP path rather than silently making the normal broker choose an arbitrary host.

JSON fallback migration

If upgrading from JSON storage:

1. stop the old Master;
2. preserve master.json;
3. start v0.3 once with the existing file and verify state;
4. configure PostgreSQL and perform an explicit controlled migration/import workflow before retiring the file.

The code can read legacy control-plane JSON state and PostgreSQL migrations can normalize embedded history, but operationally treat backend migration as a change window and verify counts/history.