mirror of
https://github.com/sol1/rustguac.git
synced 2026-10-25 13:09:56 +00:00
Jad Seifeddine
cc01469b07
A folder can lend a username, password, private key and domain per session type to entries that have no password or private key of their own, so an entry created without secrets (a NetBox webhook, a bulk import) connects the moment it exists. The defaults live at `<folder>/.defaults` beside `.config`, are reserved like it (never listed, not a valid entry name) and are removed with the folder. `GET/PUT/DELETE .../defaults` manage them (secrets write-only, audited as update_folder_defaults / delete_folder_defaults) and the folder dialog gains a Default credentials section. Listings report such entries as `has_credentials: true` with `inherited_credentials: true`. An entry's own credentials always win and an entry set to prompt still prompts. A subfolder without its own `.defaults` takes its nearest ancestor's, per type, but the walk follows the access rule: it only continues past a folder whose `.config` has `inherit_from_parent: true`. That flag is how a folder is isolated for access, so a key set on a parent must not reach a subfolder shared with someone else through `allowed_users`. The isolated folder's own `.defaults` still apply to its entries. A folder with no `.config`, or one written before the flag existed, counts as not inheriting, exactly as `resolve_folder_access` treats it. The walk is `resolve_effective_defaults` over a small `DefaultsSource` trait so it is tested without a Vault. Both connect paths resolve defaults through one helper, `lend_folder_defaults`: the Connections endpoint (`POST .../entries/:entry/connect`) and `/api/connect` quick links, so an entry that works from the page works from a link. `rustguac vault-migrate` copies each folder's `.defaults` alongside its `.config`, so a DR split keeps them (the dry run lists them as `[defaults]`). Docs cover the storage layout, the inheritance rule and its boundary, the migrate behaviour, and the warning that a web entry using a default password has that password typed into a page the user can read. Part 2/3 of #253.
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.