GUACAMOLE-261: Document the SPICE protocol - #297
Open
ciroiriarte wants to merge 12 commits into
Open
Conversation
Add a full SPICE protocol section to configuring-guacamole.md.j2, mirroring the structure of the VNC and RDP sections. Documents all connection parameters grouped by subsection: network, authentication, TLS/certificate settings, display, keyboard, clipboard, audio (with a note on server-side codec configuration and browser autoplay policy), native file transfer, SFTP (via common-sftp cross-reference), graphical recording (via graphical-recording cross-reference), and Wake-on-LAN (via wake-on-lan cross-reference). Includes a minimal user-mapping.xml example under "Adding a SPICE connection". Also update protocol-reference.rst to include "spice" alongside "vnc" and "rdp" in the two places where supported protocol names are cited as examples.
Disabling Opus does not force CELT on modern SPICE servers (which dropped CELT); the server falls back to raw/lossless audio instead. Document the accurate fallback behavior and the resulting lossless-on-LAN use case.
Multi-monitor QXL composites all heads into one combined primary surface, so vgamem_mb (not ram_size/vram_size) must be sized for the total framebuffer or the guest silently mirrors instead of extending. Add the sizing formula and Proxmox (vga: qxlN,memory=) / libvirt (vgamem=) configuration guidance.
Note that SPICE clipboard now supports images (PNG/BMP/JPEG/TIFF) as well as text, that clipboard-buffer-size may need raising for images, and document the new recording-include-clipboard parameter.
Note that recording-include-clipboard now captures both directions (including images) and annotates each transfer with its direction, for data-exfiltration auditing.
Describe the two SPICE file-transfer mechanisms (bidirectional WebDAV shared folder vs upload-only direct-to-guest SPICE agent), the file-transfer-mode selector, its routing and back-compat behaviour, and note that the agent saves files to the guest user's download/desktop location.
Add documentation for the new guacclip tool (guacamole-server), which extracts clipboard text and images from a session recording into per-item files plus a manifest.json (direction, mimetype, size, SHA-256). Requires clipboard recording (recording-include-clipboard) to have been enabled. - configuring-guacamole: new (guacclip)= tool section alongside guacenc/ guaclog, with an example invocation, the direction/exfiltration framing, and a pointer to the manpage for the full option list. - guacamole-native: list guacclip in the configure build-summary transcripts. - recording-playback: note that the in-browser player surfaces clipboard activity inline in the key-event log, and cross-link guacclip for recovering the underlying artifacts for offline audit.
The native build guide (guacamole-native.md.j2) omitted SPICE, even though configure.ac treats --with-spice like VNC/RDP (spice-client-glib-2.0 >= 0.38, plus optional libphodav for the shared-folder/WebDAV feature). - Add a "SPICE support depends on ..." bullet to the optional-dependency list. - Add spice-gtk (libspice-client-glib) and libphodav library entries with the Debian/Ubuntu and Fedora/CentOS/RHEL package names. - Update the ./configure output transcripts (both systemd and SysV tabs) to show "spice-gtk"/"libphodav" under Library status and "SPICE" under Protocol support, matching real configure output.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents the native SPICE protocol for GUACAMOLE-261.
Contents
secondary-monitorsmulti-monitor parameter and QXLvgamem_mbsizing guidance (GUACAMOLE-288).file-transfer-mode/ agent-based upload, bidirectional clipboard recording with direction annotation, and theguacclipclipboard-artifact extractor.Companion PRs: server (
apache/guacamole-server) and client (apache/guacamole-client).