From dd6ddf3763f18e22da91dcedf616dad7c85b7ffe Mon Sep 17 00:00:00 2001 From: Jad Seifeddine Date: Mon, 19 Oct 2026 14:37:27 +0700 Subject: [PATCH] docs: link the SPICE and Proxmox VE page from the other docs Add the page to the Documentation lists in the README and overview, and link it where SPICE and Proxmox come up: the session types in the overview, the session and entry fields in the API reference, the vnc_allowed_networks row in the configuration reference, and the entry types and jump-host table in integrations. Those two lists also now name SPICE and Proxmox VE, which they had left out, and no longer claim that every session type can use a jump host, since VDI cannot. (cherry picked from commit 638c5794020bb4e6473e3788bf61bf578b629f78) --- README.md | 1 + docs/api.md | 4 ++-- docs/configuration.md | 2 +- docs/integrations.md | 6 ++++-- docs/overview.md | 9 ++++++++- 5 files changed, 16 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index b6d8c41..6c3c8e9 100644 --- a/README.md +++ b/README.md @@ -160,6 +160,7 @@ Add `[vdi]` to your config and create a VDI entry in the connections. See [VDI D ### Features - [Roles & Access Control](docs/roles-and-access-control.md): OIDC, roles, group mappings, API tokens - [Web Browser Sessions](docs/web-sessions.md): autofill, domain allowlisting, login scripts +- [SPICE and Proxmox VE Sessions](docs/spice-and-proxmox.md): SPICE displays, Proxmox VE consoles, API tokens, TLS, troubleshooting - [VDI Desktop Containers](docs/vdi.md): Docker desktops, image requirements, persistent homes - [RDP Video Performance](docs/rdp-video-performance.md): H.264 passthrough, GFX pipeline, xrdp tuning - [RDP H.264 Passthrough](docs/rdp-h264.md): enabling it, and the Windows host settings it requires diff --git a/docs/api.md b/docs/api.md index 4039352..2603564 100644 --- a/docs/api.md +++ b/docs/api.md @@ -273,7 +273,7 @@ Requests from admins, an admin API key included, are used as sent. | `proxmox_token_secret` | string | API token secret (the UUID half) | | `proxmox_verify_tls` | boolean | Verify the PVE / SPICE-proxy TLS certificate (default false; PVE ships a self-signed cluster cert) | -The token needs `VM.Console` (and `VM.Audit` for node auto-detect) on the target VM. rustguac calls the PVE `spiceproxy` API at connect to fetch a one-time SPICE ticket, so nothing sensitive is stored beyond the token. +The token needs `VM.Console` (and `VM.Audit` for node auto-detect) on the target VM. rustguac calls the PVE `spiceproxy` API at connect to fetch a one-time SPICE ticket, so nothing sensitive is stored beyond the token. See [SPICE and Proxmox VE Sessions](spice-and-proxmox.md) for the connect flow, TLS options and troubleshooting. **Jump host object fields:** @@ -624,7 +624,7 @@ Create a connection entry. The body includes a `name` field plus all entry field | `jump_hosts` | array | All | Multi-hop SSH tunnel chain (same format as session creation) | | `external_id` | string | All | Stable id of the record the entry is synced from (the [NetBox webhook](netbox.md#create-webhook-device-createdupdated) sends `netbox:device:`). What `PUT ...?move=true` matches on; never used to connect. Preserved on update when omitted. | -For `spice` and `proxmox` entries, the `spice_*` and `proxmox_*` fields listed under [`POST /api/sessions`](#post-apisessions) apply here too. The `proxmox_token_secret` is write-only: it is never returned by the read endpoints (a `has_proxmox_token_secret` boolean indicates whether one is stored), and it is preserved on update when omitted. +For `spice` and `proxmox` entries, the `spice_*` and `proxmox_*` fields listed under [`POST /api/sessions`](#post-apisessions) apply here too. The `proxmox_token_secret` is write-only: it is never returned by the read endpoints (a `has_proxmox_token_secret` boolean indicates whether one is stored), and it is preserved on update when omitted. See [SPICE and Proxmox VE Sessions](spice-and-proxmox.md) for the editor fields and how the token is stored. ### `PUT /api/addressbook/folders/:scope/:folder/entries/:entry` (admin) diff --git a/docs/configuration.md b/docs/configuration.md index 029dbc0..d833813 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -50,7 +50,7 @@ CIDR ranges controlling which hosts sessions can connect to. All default to loca |-----|---------|-------------| | `ssh_allowed_networks` | `["127.0.0.0/8", "::1/128"]` | Allowed SSH targets (plus first jump hosts and host-key probes for non-admin ad-hoc use) | | `rdp_allowed_networks` | `["127.0.0.0/8", "::1/128"]` | Allowed RDP targets | -| `vnc_allowed_networks` | `["127.0.0.0/8", "::1/128"]` | Allowed VNC and SPICE targets (plus Proxmox VE API and SPICE proxy hosts for non-admin ad-hoc use) | +| `vnc_allowed_networks` | `["127.0.0.0/8", "::1/128"]` | Allowed VNC and SPICE targets (plus Proxmox VE API and SPICE proxy hosts for non-admin ad-hoc use; see [SPICE and Proxmox VE](spice-and-proxmox.md#network-allowlists)) | | `web_allowed_networks` | `["127.0.0.0/8", "::1/128"]` | Allowed web session URL hosts | ## Trusted proxies diff --git a/docs/integrations.md b/docs/integrations.md index f43d57e..8c111b2 100644 --- a/docs/integrations.md +++ b/docs/integrations.md @@ -556,12 +556,12 @@ This allows a fleet of rustguac instances to share common entries while maintain ### Entry types -Connections entries can be SSH, RDP, VNC, or Web connections. Each entry stores: +Connections entries can be SSH, RDP, VNC, SPICE, Proxmox VE console, Web, or VDI connections (see [SPICE and Proxmox VE Sessions](spice-and-proxmox.md) and [VDI Desktop Containers](vdi.md)). Each entry stores: - Connection type and target (hostname, port, URL) - Credentials (username, password, private key) - Protocol-specific settings (domain, security mode, certificate ignore, drive override) -- **Multi-hop SSH tunnel chain** — optional ordered list of SSH bastion hosts to route through (all session types) +- **Multi-hop SSH tunnel chain** — optional ordered list of SSH bastion hosts to route through (all session types except VDI) - **Prompt for credentials** — when enabled, users are asked for username/password at connect time, even if stored credentials exist - **NLA auth package** (RDP only) — force Kerberos or NTLM for NLA authentication - **KDC URL** (RDP only) — Kerberos Key Distribution Center proxy URL @@ -642,6 +642,8 @@ At least one of `password` or `private_key` should be provided per hop. | SSH | Yes | Tunnel forwards to SSH target | | RDP | Yes | Tunnel forwards to RDP target | | VNC | Yes | Tunnel forwards to VNC target | +| SPICE | Yes | Tunnel forwards to the SPICE server's TLS port with TLS on, otherwise its plain port. See [SPICE and Proxmox VE](spice-and-proxmox.md#ssh-tunnels-and-jump-hosts) | +| Proxmox VE | Yes | Two tunnels: one to the PVE API, one to the SPICE proxy Proxmox returns. See [SPICE and Proxmox VE](spice-and-proxmox.md#ssh-tunnels-and-jump-hosts) | | Web | Yes | Tunnel forwards to URL host:port; URL is rewritten to `127.0.0.1:{tunnel_port}` | | SPICE | Yes | Tunnel forwards to the SPICE host; with TLS on, to `tls_port` (or `port` if no TLS port is set), otherwise to `port` | | Proxmox VE | Yes | The PVE API and the SPICE proxy that Proxmox returns are each tunnelled through the chain | diff --git a/docs/overview.md b/docs/overview.md index 06dacb2..3be7052 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -103,6 +103,12 @@ Connects guacd to a target VNC server. Supports password-based authentication, p Supports optional [multi-hop SSH tunnel chains](#ssh-tunnel--jump-hosts) to reach VNC targets through bastion hosts. +### SPICE and Proxmox VE + +SPICE sessions connect guacd's SPICE plugin to a SPICE server, such as a libvirt/QEMU VM console, with optional TLS, CA verification, certificate-subject pinning and a SPICE proxy. Proxmox VE console sessions open a Proxmox VE VM's console: at connect time rustguac fetches a one-time SPICE ticket from the Proxmox API, so only the API token is stored. + +Both support optional [multi-hop SSH tunnel chains](#ssh-tunnel--jump-hosts). See [SPICE and Proxmox VE Sessions](spice-and-proxmox.md) for entry fields, the API token, TLS and troubleshooting. + ### Web browser Spawns a headless Xvnc display and Chromium in kiosk mode, then connects guacd via VNC to the local display. The user sees a full browser session in their own browser. Each session gets an isolated Chromium profile directory. @@ -119,7 +125,7 @@ VDI sessions support persistent home directories, per-entry resource limits and ## SSH tunnel / jump hosts -SSH, RDP, VNC, and web browser sessions can be routed through one or more SSH bastion hosts using multi-hop SSH tunnel chains. This is useful when target machines are not directly reachable from the rustguac server. VDI sessions do not support tunnels (containers run locally). +SSH, RDP, VNC, SPICE, Proxmox VE, and web browser sessions can be routed through one or more SSH bastion hosts using multi-hop SSH tunnel chains. This is useful when target machines are not directly reachable from the rustguac server. VDI sessions do not support tunnels (containers run locally). Each hop in the chain establishes an SSH connection and creates a local TCP port forward (`direct-tcpip`). The hops are chained sequentially — each hop connects through the previous hop's local listener. The final hop forwards to the actual target (e.g., an RDP server on port 3389). @@ -181,6 +187,7 @@ scripts/ Utility scripts (drive-setup.sh) ### Features - [Roles and Access Control](roles-and-access-control.md) -- 4-tier role hierarchy, OIDC groups, user API tokens - [Web Browser Sessions](web-sessions.md) -- autofill, domain allowlisting, login scripts +- [SPICE and Proxmox VE Sessions](spice-and-proxmox.md) -- SPICE displays, Proxmox VE consoles, API tokens, TLS, troubleshooting - [Credential Variables](credential-variables.md) -- shared credentials across entries - [Reports](reports.md) -- session analytics, history, CSV export - [RDP Video Performance](rdp-video-performance.md) -- H.264 passthrough, GFX pipeline, xrdp/Windows tuning