mirror of https://github.com/sol1/rustguac.git synced 2026-10-24 04:32:21 +00:00

Files

T

Dave Kempe f2cd9119d3 sessions: owner-only first connection, optional read-only joins

The first WebSocket to a pending session takes its guacd stream, already
logged in to the target. Any operator could claim another user's pending
session that way, and session ids are visible in reports. Now only the
session's creator may make that connection, with no admin bypass: an admin
"shadowing" a pending session used to silently become its owner and lock
the real owner out, so shadow now refuses sessions that have not started
(409). handle_ws only takes the stream when the owner check passed at
upgrade time.

POST /api/sessions accepts an admin-only `owner` field so a backend using
an API key can create a session for a user who then connects with their
own login. That user is recorded as the creator.

Share links and shadow tokens gain an optional read-only mode; the default
stays read/write. Each shareable session gets a second token
(share_url_readonly), and shadow takes {"read_only": true}. guacd enforces
it per joining user via the read-only connect arg, which was previously
hardcoded to false. The Share dialog offers both links, the Sessions page
offers watch and shadow, and docs no longer claim a read-only mode that
did not exist.

2026-10-01 21:21:35 +10:00

8.8 KiB

Raw Blame History

rustguac

A lightweight Rust replacement for the Apache Guacamole Java webapp. Browser-based SSH, RDP, VNC, SPICE, Proxmox VE consoles, web browsing, and VDI desktop containers through guacd.

No Java. No Tomcat. Single binary + guacd.

Architecture

Browser (HTML/JS)
    |
    | WebSocket over HTTPS
    v
rustguac (Rust, axum)
    |
    | TLS (Guacamole protocol)
    v
guacd (C, from guacamole-server)
    |
    +---> SSH server
    +---> RDP server
    +---> VNC server
    +---> SPICE server (libvirt/QEMU displays)
    +---> Proxmox VE VM console (SPICE via the PVE spiceproxy API)
    +---> Xvnc + Chromium (web browser sessions)
    +---> Docker container + xrdp (VDI desktop sessions)

Features

Session types

Type	Description
SSH	Browser-based terminal with password, private key, or ephemeral keypair auth. SFTP file transfer.
RDP	Windows/Linux RDP with auto-fit resize, Kerberos NLA, RemoteApp/RAIL, H.264 passthrough, GFX pipeline.
VNC	Connect to any VNC server (KVM/IPMI consoles, remote desktops, VM displays).
SPICE	Direct SPICE displays (libvirt/QEMU consoles) with TLS, CA verification, certificate-subject pinning, and SPICE-proxy support.
Proxmox VE	VM consoles brokered through the Proxmox API. One-time SPICE tickets fetched just-in-time at connect (only the API token is stored), node auto-detected from the VM ID, and SSH-tunnel aware.
Web	Headless Chromium on Xvnc with native autofill, domain allowlisting, login script automation.
VDI	Ephemeral Docker desktop containers per user. Persist after disconnect, auto-cleanup on idle.

Security & authentication

OIDC single sign-on: Authentik, Google, Okta, Keycloak, or any OpenID Connect provider
4-tier role system: admin, poweruser, operator, viewer with OIDC group mapping
API key auth: SHA-256 hashed keys with IP allowlists and expiry
Vault-backed connections: credentials in HashiCorp Vault or OpenBao KV v2, never reach the browser (see Requirements)
TLS everywhere: HTTPS for clients, TLS between rustguac and guacd
CIDR allowlists: per-protocol network restrictions for session targets
Per-entry clipboard control: disable copy and/or paste for data loss prevention
Rate limiting: per-IP, per-endpoint via tower_governor
Session recording: Guacamole format with playback UI, disk rotation, per-entry limits

Connectivity

Multi-hop SSH tunnels: chain jump hosts/bastions to reach isolated networks (all session types, including the Proxmox API and console hops)
Session sharing: share links for view-only or collaborative access, plus admin shadowing
Headless API integration: create a session over the REST API and hand a browser a ready-to-open URL via a single-use WebSocket ticket, with no OIDC login and no API key in the browser (see Connecting to a session)
Encrypted file transfer: LUKS-encrypted per-session drive storage (RDP), SFTP (SSH)
Credential variables: shared credentials across connections entries

VDI desktop containers

Docker-based: one container per user, deterministic naming, BYO image
Persist after disconnect: reconnect to the same desktop within idle timeout
Logout detection: desktop logout stops the container, tab close preserves it
Session thumbnails: live preview in the connections, click to reconnect
Persistent home directories: bind-mounted user data survives container restarts
Per-entry resource limits: CPU, memory, idle timeout per connections entry
VdiDriver trait: extensible for downstream forks (Nomad, Proxmox, cloud)

UI

Connections with folder-based organisation and OIDC group access control
Active Sessions section with live thumbnail previews
Session ended overlay with Reconnect/Close buttons
Clipboard panel controls (Home + Fullscreen)
8 built-in themes with CSS gradient backgrounds, or configure your own
Reports page with session analytics, history, and CSV export

Requirements

Component	Status	Notes
guacd	Bundled	Built from `apache/guacamole-server`, ships in the .deb and Docker image. No separate install.
Vault or OpenBao	Required for the Connections UI	Stores connection entries and credentials server-side. Without it the Connections page is unavailable and users can only run ad-hoc sessions via the API. Use `contrib/vault-quickstart.sh` for one-command setup (auto-detects `vault` or `bao`, supports `--dev` and `--local` modes).
OIDC provider	Optional	For SSO. API-key auth works on its own. Authentik/Google/Okta/Keycloak/JumpCloud all tested.
Docker	Optional	Only needed for VDI desktop containers.

Supported browsers

The client runs in any modern browser (Chrome, Firefox, Edge, Safari, Chromium, Brave). One caveat applies only to H.264-accelerated RDP, which is opt-in per connection (the per-entry H.264 toggle, off by default):

Standard connections (SSH, RDP, VNC, web sessions, VDI) work in every modern browser.
H.264-accelerated connections need a browser that can decode H.264 through the WebCodecs API. Chrome and Firefox work. Open-source Chromium and Brave builds without the bundled H.264 codec, and older Safari, render a blank display on those connections. Leave H.264 off (the default) for universal browser support, or use Chrome or Firefox where it is enabled.

Quick start

Debian 13 (.deb)

Pre-built packages for amd64 and arm64 are available from Releases:

sudo apt install ./rustguac_*.deb
/opt/rustguac/bin/rustguac --config /opt/rustguac/config.toml add-admin --name admin
sudo systemctl enable --now rustguac

Docker

docker pull sol1/rustguac:latest
docker run -d -p 8089:8089 sol1/rustguac:latest

For VDI support, mount the Docker socket:

docker run -d -p 8089:8089 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --group-add $(getent group docker | cut -d: -f3) \
  sol1/rustguac:latest

Other distributions

Pre-built packages are provided for Debian 13. For other distributions, build from source:

sudo ./install.sh

See the Installation guide for full details including Docker Compose, TLS setup, and development builds.

VDI setup

VDI requires Docker on the host:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker rustguac
sudo systemctl restart rustguac

Add [vdi] to your config and create a VDI entry in the connections. See VDI Desktop Containers for image requirements and configuration.

Documentation

Getting started

Installation: Debian packages, Docker, bare-metal, development builds
Configuration: TOML config reference with all sections
Deployment Guide: step-by-step production setup

Features

Roles & Access Control: OIDC, roles, group mappings, API tokens
Web Browser Sessions: autofill, domain allowlisting, login scripts
VDI Desktop Containers: Docker desktops, image requirements, persistent homes
RDP Video Performance: H.264 passthrough, GFX pipeline, xrdp tuning
RDP H.264 Passthrough: enabling it, and the Windows host settings it requires
Credential Variables: shared credentials across entries
Reports: session analytics, history, CSV export

Integration & reference

Integrations: Vault, LUKS drives, SSH tunnels, Kerberos, HAProxy, Knocknoc
NetBox: connections sync via custom fields and webhooks
Security: TLS, rate limiting, headers, audit logging, hardening
API Reference: REST API endpoints, the session connection flow, and headless ws-ticket integration
Migration from Apache Guacamole: MySQL/MariaDB to Vault

Commercial support

Commercial support for rustguac is available from Sol1.

License

Apache License 2.0. See LICENSE for details.

8.8 KiB Raw Blame History

rustguac

Architecture

Features

Session types

Security & authentication

Connectivity

VDI desktop containers

UI

Requirements

Supported browsers

Quick start

Debian 13 (.deb)

Docker

Other distributions

VDI setup

Documentation

Getting started

Features

Integration & reference

Commercial support

License

8.8 KiB

Raw Blame History