From ec3799dfa96b8b59b9b680d33d7818b89d3b84fa Mon Sep 17 00:00:00 2001 From: Amin Rezaie Mehr Date: Tue, 14 Jul 2026 02:10:40 +0330 Subject: [PATCH] GUACAMOLE-2064: Document database terminal protocols. Document the new MySQL, PostgreSQL, SQL Server, MongoDB, and Oracle terminal protocols provided by guacamole-server. Add a "Database terminals" section to the connection configuration chapter describing the interactive shell (line editing, history, and per-dialect statement terminators), the parameters common to all database protocols, and the parameters, capabilities, and caveats specific to each database. List the required client libraries among the build dependencies, note that Oracle support requires the Oracle Instant Client and is not built by default, and record which database protocols the guacd Docker image includes. --- src/configuring-guacamole.md.j2 | 202 ++++++++++++++++++++++++++++++++ src/guacamole-docker.md | 14 ++- src/guacamole-native.md.j2 | 85 +++++++++++++- 3 files changed, 296 insertions(+), 5 deletions(-) diff --git a/src/configuring-guacamole.md.j2 b/src/configuring-guacamole.md.j2 index 9793561b..a31a699d 100644 --- a/src/configuring-guacamole.md.j2 +++ b/src/configuring-guacamole.md.j2 @@ -1894,6 +1894,208 @@ the Guacamole *client* will be encrypted, but communication between guacd and the telnet server will still be unencrypted. You should not use telnet unless the network between guacd and the telnet server is trusted. +### Database terminals (MySQL, PostgreSQL, SQL Server, MongoDB, Oracle) + +Guacamole can provide interactive, shell-style access to several databases +directly within the browser. As with SSH and telnet, a terminal is emulated on +the server side and rendered to the Guacamole client's display, so all of +Guacamole's session logging facilities (typescripts and graphical session +recording) apply to database sessions, too. Rather than launching a +command-line client like `mysql` or `psql` on a remote machine, guacd connects +to the database server directly using the database's own client library, and +presents a prompt at which statements can be typed, edited, and executed. + +Database support for Guacamole is provided by the libguac-client-mysql, +libguac-client-postgresql, libguac-client-mssql, libguac-client-mongodb, and +libguac-client-oracle libraries, each of which will be installed as part of +guacamole-server if the required client library is present during the build. + +:::{note} +In addition to the database-specific parameters below, Guacamole's database +support also accepts the parameters of several features that Guacamole +provides for multiple protocols: + +* [](disable-clipboard) +* [](graphical-recording) +* [](typescripts) +* [](stdin-pipe) +* [](terminal-behavior) +* [](terminal-display-settings) +* [](wake-on-lan) +::: + +(database-shell)= + +#### The database shell + +Each line typed at the prompt is edited locally within guacd, with support for +cursor movement (Left/Right/Home/End), in-memory command history (Up/Down), +and the common control shortcuts Ctrl+A, Ctrl+E, Ctrl+K, Ctrl+U, Ctrl+W, and +Ctrl+L. History is kept only in memory and is discarded when the session ends. + +Input is sent to the database only once a complete statement has been entered. +For the SQL databases, statements end with a semicolon (`;`), with two +additions matching the conventions of the native clients: SQL Server also +accepts a line containing only `GO` as a batch separator, and Oracle PL/SQL +blocks (statements beginning with `DECLARE`, `BEGIN`, or `CREATE` of a +procedural object) end only with a line containing only a slash (`/`). For +MongoDB, each statement is a single JSON document, which may span several +lines until its braces balance. + +Pressing Ctrl+C cancels the statement currently being entered. If a statement +is already executing, Ctrl+C requests cancellation of that statement where the +database supports it (see the per-database notes below). The session ends when +`\q`, `quit`, or `exit` is entered, or when Ctrl+D is pressed at an empty +prompt, and `\h` displays the available shell commands. + +(database-common-parameters)= + +#### Common parameters + +All database protocols accept the following connection parameters: + +`hostname` +: The hostname or IP address of the database server Guacamole should connect + to. This parameter is required. + +`port` +: The port the database server is listening on. If omitted, the standard port + of the database in question will be used (3306 for MySQL, 5432 for + PostgreSQL, 1433 for SQL Server, 27017 for MongoDB, and 1521 for Oracle). + +`username` +: The username to authenticate as. If omitted, the user will be prompted for + a username within the terminal when the connection is opened (except for + MongoDB, where omitting the username results in an unauthenticated + connection). + +`password` +: The password to authenticate with. If omitted and the database requires a + password, the user will be prompted for the password within the terminal, + with the typed characters displayed as asterisks. + +`database` +: The name of the database to use initially. This parameter is optional for + all databases except Oracle, which uses `service-name` instead. For MongoDB, + this selects the database that commands are directed to, which may later be + changed with the `\use` shell command. + +`timeout` +: The number of seconds to wait for the connection to the database server to + be established before giving up. If omitted, the default of 10 seconds will + be used. This parameter currently has no effect for Oracle connections, + where connection timeouts are governed by Oracle Net configuration. + +(mysql-protocol-parameters)= + +#### MySQL / MariaDB + +MySQL support is implemented using MariaDB Connector/C, which can connect to +both MySQL and MariaDB servers. The non-blocking API of MariaDB Connector/C is +required; Oracle's libmysqlclient cannot be used. While a statement is +executing, Ctrl+C cancels it by issuing `KILL QUERY` over a separate, +short-lived connection, exactly as the `mysql` command-line client does. For +security reasons, `LOAD DATA LOCAL INFILE` is unconditionally disabled; the +database server can never read files local to guacd. + +`ssl-mode` +: The TLS behavior of the connection: one of `disabled`, `preferred`, + `required`, `verify-ca`, or `verify-identity`. If omitted, TLS is used if + available but is not required, and the server certificate is not verified. + +`ssl-ca-file` +: The path, *on the server hosting guacd*, of the certificate authority file + used to verify the database server certificate. + +(postgresql-protocol-parameters)= + +#### PostgreSQL + +PostgreSQL support is implemented using libpq. Statement splitting understands +PostgreSQL dollar-quoted string literals (`$tag$ ... $tag$`) and nested block +comments, so functions and procedures can be entered directly. Server notices +(such as those produced by `RAISE NOTICE`) are displayed within the terminal +as they arrive, and Ctrl+C cancels a running statement using PostgreSQL's +native cancellation mechanism. + +`ssl-mode` +: The libpq `sslmode` of the connection: one of `disable`, `allow`, `prefer`, + `require`, `verify-ca`, or `verify-full`. If omitted, libpq's default + (`prefer`) applies. + +`ssl-ca-file` +: The path, *on the server hosting guacd*, of the certificate authority file + used to verify the database server certificate (libpq's `sslrootcert`). + +(mssql-protocol-parameters)= + +#### SQL Server + +SQL Server support is implemented using the CT-Library interface of FreeTDS. +In addition to semicolons, a line containing only `GO` (case-insensitive) +submits the current batch, as in `sqlcmd`. Messages raised by the server, +including `PRINT` output, are displayed within the terminal. Ctrl+C cancels a +running statement by sending a TDS attention, as `sqlcmd` and `sqsh` do. + +Whether the TDS connection itself is encrypted is governed by the FreeTDS +configuration (`freetds.conf`) of the server hosting guacd; see the FreeTDS +documentation for the `encryption` setting. + +`tds-version` +: The TDS protocol version to use: one of `7.1`, `7.2`, `7.3`, or `7.4`. If + omitted, the version is negotiated automatically. + +(mongodb-protocol-parameters)= + +#### MongoDB + +MongoDB support is implemented using the MongoDB C Driver (libmongoc). Unlike +the SQL databases, the MongoDB shell does not accept a query language of its +own: each statement is a [MongoDB database +command](https://www.mongodb.com/docs/manual/reference/command/) written as a +JSON document, giving access to everything the server supports. For example: + +``` +mongodb> {"find": "users", "filter": {"age": {"$gt": 30}}} +mongodb> {"insert": "users", "documents": [{"name": "guac"}]} +mongodb> {"aggregate": "events", "pipeline": [{"$group": {"_id": "$type", "n": {"$sum": 1}}}], "cursor": {}} +``` + +Replies are displayed as indented, relaxed Extended JSON. When a command +returns a cursor (such as `find` or `aggregate`), the shell automatically +issues `getMore` commands until the cursor is exhausted. The shell additionally +provides `\use ` to switch the database commands are directed to, and +`\show dbs` / `\show collections` to list databases and collections. +Cancellation of a running command with Ctrl+C is not supported by the MongoDB +C Driver; the session's socket timeouts bound how long a command can run. + +`auth-database` +: The database to authenticate against (`authSource`), if different from the + connected database. + +`use-ssl` +: If set to "true", TLS is used for the connection to the MongoDB server. + +`ssl-ca-file` +: The path, *on the server hosting guacd*, of the certificate authority file + used to verify the database server certificate. + +(oracle-protocol-parameters)= + +#### Oracle Database + +Oracle support is implemented using the Oracle Call Interface (OCI) and is +built only when guacamole-server is explicitly configured with the Oracle +Instant Client SDK (see [](installing-guacamole)). Plain SQL statements end +with a semicolon, while PL/SQL blocks end with a line containing only `/`, as +in SQL*Plus. Statements are committed upon successful execution. Ctrl+C +cancels a running statement using `OCIBreak()`. + +`service-name` +: The service name of the database to connect to, as would appear in an + EZConnect string (`//hostname:port/service-name`). This parameter is + required; the `database` parameter is not used by Oracle connections. + ### Kubernetes Kubernetes provides an API for attaching to the console of a container over the diff --git a/src/guacamole-docker.md b/src/guacamole-docker.md index c12293e5..c875ddd8 100644 --- a/src/guacamole-docker.md +++ b/src/guacamole-docker.md @@ -11,7 +11,8 @@ containers, connected over the network: `guacamole/guacd` : Provides the guacd daemon, built from the released guacamole-server source - with support for VNC, RDP, SSH, telnet, and Kubernetes. + with support for VNC, RDP, SSH, telnet, Kubernetes, and the database + terminal protocols (MySQL, PostgreSQL, SQL Server, and MongoDB). `guacamole/guacamole` : Provides the Guacamole web application running within Tomcat 9.x with support @@ -44,11 +45,20 @@ Running the guacd Docker image ------------------------------ The guacd Docker image is built from the released guacamole-server source with -support for VNC, RDP, SSH, telnet, and Kubernetes. Common pitfalls like +support for VNC, RDP, SSH, telnet, Kubernetes, and the database terminal +protocols (MySQL, PostgreSQL, SQL Server, and MongoDB). Common pitfalls like installing the required dependencies, installing fonts for SSH, telnet, or Kubernetes, and ensuring the FreeRDP plugins are installed to the correct location are all taken care of. It will simply just work. +:::{note} +The Oracle Database protocol is not included in the guacd Docker image, as the +required Oracle Instant Client is proprietary software which cannot be +redistributed. To use the Oracle protocol with Docker, build a custom image +which downloads the Instant Client "Basic" and "SDK" packages and builds +guacamole-server with `--with-oracle=`. +::: + (guacd-docker-guacamole)= ### Running guacd for use by the Guacamole Docker image diff --git a/src/guacamole-native.md.j2 b/src/guacamole-native.md.j2 index cc4e8f73..9b161e0e 100644 --- a/src/guacamole-native.md.j2 +++ b/src/guacamole-native.md.j2 @@ -204,9 +204,9 @@ carefully before deciding not to install an optional dependency. [Pango](http://www.pango.org/) : Pango is a text layout library which Guacamole uses to render text for - protocols that require a terminal (Kubernetes, SSH, and telnet). If you do - not wish to build any terminal-based protocol support, this library is not - needed. + protocols that require a terminal (Kubernetes, SSH, telnet, and the + database protocols). If you do not wish to build any terminal-based + protocol support, this library is not needed. :::{list-table} :stub-columns: 1 @@ -264,6 +264,65 @@ carefully before deciding not to install an optional dependency. - `libwebsockets-devel` ::: +[MariaDB Connector/C](https://mariadb.com/kb/en/mariadb-connector-c/) +: MariaDB Connector/C is required for the MySQL protocol, and can connect to + both MySQL and MariaDB servers. Its non-blocking API is required; Oracle's + libmysqlclient cannot be used instead. If you do not wish to build MySQL + support, this library is not needed. + + :::{list-table} + :stub-columns: 1 + * - Debian / Ubuntu package + - `libmariadb-dev` + * - Fedora / CentOS / RHEL package + - `mariadb-connector-c-devel` + ::: + +[libpq](https://www.postgresql.org/docs/current/libpq.html) +: libpq is required for the PostgreSQL protocol. If you do not wish to build + PostgreSQL support, this library is not needed. + + :::{list-table} + :stub-columns: 1 + * - Debian / Ubuntu package + - `libpq-dev` + * - Fedora / CentOS / RHEL package + - `libpq-devel` + ::: + +[FreeTDS](https://www.freetds.org/) +: FreeTDS provides the CT-Library interface required for the SQL Server + protocol. If you do not wish to build SQL Server support, this library is + not needed. + + :::{list-table} + :stub-columns: 1 + * - Debian / Ubuntu package + - `freetds-dev` + * - Fedora / CentOS / RHEL package + - `freetds-devel` + ::: + +[MongoDB C Driver](https://mongoc.org/) +: The MongoDB C Driver (libmongoc) is required for the MongoDB protocol. If + you do not wish to build MongoDB support, this library is not needed. + + :::{list-table} + :stub-columns: 1 + * - Debian / Ubuntu package + - `libmongoc-dev` + * - Fedora / CentOS / RHEL package + - `mongo-c-driver-devel` + ::: + +[Oracle Instant Client SDK](https://www.oracle.com/database/technologies/instant-client.html) +: The Oracle Call Interface (OCI) of the Oracle Instant Client is required + for the Oracle Database protocol. As the Instant Client is proprietary + software which cannot be redistributed with Guacamole, Oracle support is + never built by default: download the Instant Client "Basic" (or "Basic + Light") and "SDK" packages from Oracle, unzip both to the same directory, + and pass that directory to `configure` via `--with-oracle=`. + [PulseAudio](http://www.freedesktop.org/wiki/Software/PulseAudio/) : PulseAudio provides libpulse, which is used by Guacamole's VNC support to provide experimental audio support. If you are not going to be using the @@ -413,10 +472,15 @@ guacamole-server version {{ version }} libavcodec .......... yes libavformat ......... yes libavutil ........... yes + freetds ............. yes + libmariadb .......... yes + libmongoc ........... yes + libpq ............... yes libssh2 ............. yes libssl .............. yes libswscale .......... yes libtelnet ........... yes + oracle (OCI) ........ no libVNCServer ........ yes libvorbis ........... yes libpulse ............ yes @@ -427,6 +491,11 @@ guacamole-server version {{ version }} Protocol support: Kubernetes .... yes + MongoDB ....... yes + MySQL ......... yes + Oracle ........ no + PostgreSQL .... yes + SQL Server .... yes RDP ........... yes SSH ........... yes Telnet ........ yes @@ -475,10 +544,15 @@ guacamole-server version {{ version }} libavcodec .......... yes libavformat ......... yes libavutil ........... yes + freetds ............. yes + libmariadb .......... yes + libmongoc ........... yes + libpq ............... yes libssh2 ............. yes libssl .............. yes libswscale .......... yes libtelnet ........... yes + oracle (OCI) ........ no libVNCServer ........ yes libvorbis ........... yes libpulse ............ yes @@ -489,6 +563,11 @@ guacamole-server version {{ version }} Protocol support: Kubernetes .... yes + MongoDB ....... yes + MySQL ......... yes + Oracle ........ no + PostgreSQL .... yes + SQL Server .... yes RDP ........... yes SSH ........... yes Telnet ........ yes