[jira] [Created] (GUACAMOLE-2307) Add opt-in raw text-output mode for terminal protocols (SSH/telnet/Kubernetes)

["Ciro Iriarte (Jira)" <ji...@apache.org>]

Ciro Iriarte created GUACAMOLE-2307:
---------------------------------------

             Summary: Add opt-in raw text-output mode for terminal protocols (SSH/telnet/Kubernetes)
                 Key: GUACAMOLE-2307
                 URL: https://issues.apache.org/jira/browse/GUACAMOLE-2307
             Project: Guacamole
          Issue Type: New Feature
          Components: guacamole-server
            Reporter: Ciro Iriarte


h2. Summary

Add an opt-in per-connection parameter, {{text-output}}, that makes guacd tee the
raw remote PTY byte stream (including ANSI/CSI/OSC sequences) to an outbound
Guacamole {{pipe}} stream named {{STDOUT}}, for the SSH, telnet, and Kubernetes
protocols. This lets a non-graphical / native CLI client present a terminal session
as true in-terminal text instead of decoding rasterized glyphs. Default off; no
change to existing connections.

h2. Motivation

The browser terminal renders output graphically: guacd runs the emulator and emits
only drawing instructions, so no character codepoints reach the client. A native or
CLI client therefore cannot reconstruct the text of a session. This adds a faithful
raw byte channel in the output direction, complementing the inbound STDIN pipe
(GUACAMOLE-574). It deliberately does *not* reuse the {{guacctl}} pipe redirect
(GUACAMOLE-17): that path runs through {{guac_terminal_echo()}}, which strips
ESC/CSI/OSC sequences and so cannot carry a faithful raw stream.

h2. Design

* New connection parameter {{text-output}} (string enum):
** {{true}} — tee mode: raw bytes are teed to STDOUT *and* the graphical display is
   still rendered, so browser users are unaffected.
** {{raw}} — headless mode: the graphical terminal is not rendered at all; bytes are
   delivered only via STDOUT, eliminating the graphical instruction stream and its
   render cost.
** anything else, including {{false}} or omitted — disabled.
* guacd opens an outbound {{pipe}} stream named {{STDOUT}}, mimetype
  {{application/octet-stream}} (advisory; payload is raw bytes carried in base64
  {{blob}} instructions, so it is binary-safe and charset-agnostic — the client
  decodes the bytes itself).
* The tee is taken *at the protocol source* — in each protocol's PTY read path,
  upstream of the terminal emulator — via a dedicated {{text_output_stream}} on
  {{guac_terminal}}, independent of the {{guacctl}} pipe machinery.
* The stream is allocated on the connection *owner's* user socket
  ({{guac_user_alloc_stream}}), not broadcast to every user, and uses an even
  (ack-routable) stream index so client {{ack}} instructions return to the stream.
* New additive public API in {{terminal.h}}:
  {{guac_terminal_text_output_open/write/flush/close}} (+ a {{should_open}} helper).
  No existing symbol is changed.
* In {{raw}} mode the read loop skips {{guac_terminal_write()}} (the terminal is kept
  for input/size/stdin) and flushes per-read, since there is no graphical frame cycle.

h2. Flow control / backpressure

This is the subtle part and is worth reviewer attention:

* Clients must {{ack}} every {{blob}}, on receipt rather than after rendering.
* guacd bounds the unacknowledged backlog by *bytes*: 256 KB
  ({{GUAC_TERMINAL_TEXT_OUTPUT_MAX_INFLIGHT_BYTES}}), plus a 256-blob cap purely to
  bound a small size-tracking FIFO. The byte bound is the operative one, because
  {{raw}} mode emits one blob per PTY read and those blobs are often only a few bytes.
* On a stalled consumer the response differs by mode, deliberately:
** {{tee}}: buffered output is *dropped* and the session continues. The tee shares the
   protocol read loop with the graphical display, so blocking on a stalled text
   consumer would also stall any co-attached browser user.
** {{raw}}: the read loop is *throttled* — the writer waits (on a condition variable)
   for the window to drain, which propagates backpressure to the remote program
   through the PTY exactly as a slow local terminal would. Raw renders nothing
   graphically, so pausing starves no one and the byte stream stays intact.
* A consumer that stops acking entirely for 15 s
  ({{GUAC_TERMINAL_TEXT_OUTPUT_STALL_TIMEOUT}}) is disconnected with {{SERVER_ERROR}}.
  The wait also short-circuits immediately once the connection is going away, so an
  abrupt disconnect does not delay teardown.

h2. Security

* {{text-output}} is effectively a copy/export channel, so it is gated behind
  {{disable-copy}}: guacd refuses to open the pipe when copying from the terminal is
  disabled (and logs a warning).
* Pipe contents are not logged or recorded by default (output may echo secrets).
* Intended trust model: the parameter is admin-provisioned on the connection (not
  client-requestable); guacd is reached only over the authenticated tunnel/gateway.
  No new port, no new protocol instruction (reuses {{pipe}}/{{blob}}/{{end}}/{{ack}}),
  no authentication change.

h2. Backwards compatibility / ABI

Additive and opt-in, default off. No new protocol instruction, no DB schema change,
and no web-app change is required — an unmodified guacamole-client already passes the
parameter through, since {{ConfiguredGuacamoleSocket}} builds the {{connect}}
instruction from the argument list guacd announces in its handshake. No ABI break:
only additive public symbols are introduced.

h2. Validation

* CUnit unit tests for terminal text-output: disable-copy gating, owner-stream + ack
  routing, tee drop-on-stall, raw throttle-vs-abort, the byte bound, ACK retiring the
  oldest blob's byte count, surplus-ACK safety, disconnect short-circuit, and
  closed-stream-unroutable. Full {{make check}} is green on Debian 12 and openSUSE
  Leap 16.
* An end-to-end harness (direct-to-guacd, no web app) covers SSH/telnet/Kubernetes
  across 13 scenarios: positive tee, negative (default-off and disable-copy -> no
  pipe), a byte-bound flood with and without acks, small-unacked-not-dropped, and
  raw (text delivered, graphics suppressed). All pass.
* Validated live through an unmodified guacamole-client gateway with a native CLI
  client, in both tee and raw modes, including a 20,000-line flood and the 15 s
  give-up path (measured: 256 KB delivered, then a clean SERVER_ERROR abort).

h2. Patch / branch

Implemented on a fork branch, 23 commits atop apache/main (base 6719b20d). A
redistributable {{git format-patch}} artifact is available and applies cleanly onto
that base. Happy to open a PR against apache/main. The client side is UI-only
convenience (protocol JSON enum + i18n strings), and a matching manual section
documents the parameter and the backpressure contract.

h2. Related

* GUACAMOLE-17 (resolved) — the original {{guacctl}} output-to-pipe redirect; routes
  through the escape-stripping echo path, so it is not usable for a faithful raw
  stream. This issue is the complement, taken at the source.
* GUACAMOLE-574 — inbound STDIN pipe (the input direction).



--
This message was sent by Atlassian Jira
(v8.20.10#820010)