Advanced configuration of SSH Protocol connection type
Support for the SSH protocol within Keeper Connection Manager is provided by the
kcm-libguac-client-sshpackage. This package will be installed by default if the
@kcmpackage group was used during installation, and is already installed within the
keeper/guacdDocker image. If this package has not yet been installed, SSH connections will not be functional, with guacd logging a warning noting the absence of needed protocol support:
guacd: WARNING: Support for protocol "ssh" is not installed
If such an error appears within the guacd logs, simply installing
kcm-libguac-client-sshis sufficient to resolve the issue:
$ sudo yum install kcm-libguac-client-ssh
The guacd service does not need to be restarted for installation of SSH support to take effect.
Unlike VNC or RDP, SSH is a text protocol. Its implementation in Guacamole is actually a combination of a terminal emulator and SSH client, because the SSH protocol isn't inherently graphical. Guacamole's SSH support emulates a terminal on the server side, and draws the screen of this terminal remotely on the client.
Keeper's support for the SSH protocol is controlled through the use of several parameters. When a database like MySQL or PostgreSQL is used, these parameters are presented in a convenient web interface. If defining connections through another mechanism, such as through encrypted JSON or LDAP schema modifications, parameters are specified using their internal parameter names.
This document is intended to cover all supported parameters, grouped in the same way they are grouped within the web interface. The field headings which would appear in the web interface are provided for each parameter, along with each parameter's internal name and a thorough description of the behavior and legal values for that parameter.
SSH connections are established over TCP to a specific port and a specific hostname or IP address. The hostname/address must be specified for all SSH connections, but you only need to specify a port if you are not using the standard SSH port (22).
Guacamole supports keyboard-interactive, password, and public key authentication with SSH servers. To use public key authentication, it must have access to the private key and, if applicable, its passphrase. If the private key requires a passphrase, but no passphrase is provided, the user will be prompted for the passphrase upon connecting.
Guacamole's SSH support provides a display, but not in the same sense as a remote desktop protocol like VNC or RDP. The display is a terminal emulator, and thus provides options for configuring the font used and its size.
If selecting a different font for an SSH connection, the chosen font must be installed on the server running guacd. It is the server that will handle rendering of characters to the terminal display, not the client.
Custom color schemes may be provided for the terminal emulator used by SSH connections. Custom schemes mimic the format used by Xterm and consist of a semicolon-separated series of name-value pairs. Each name-value pair is separated by a colon and assigns a value to a color in the terminal emulator palette.
For example, to use blue text on white background by default, and change the red color to a purple shade, you would specify:
Legal color names are:
foreground" - the default foreground color.
background" - the default background color.
colorN" - the color at index N within the Xterm 256-color palette. For example, "color9" refers to the color at palette index 9, normally red.
Legal color values are:
- "rgb:RR/GG/BB" - a color in RGB format, with each component in hexadecimal. For example, "
rgb:ff/00/00" specifies the color red. Each hexadecimal component may be one to four digits, but the effective values are always zero-extended or truncated to two digits; for example, "
rgb:f0/80/00", and "
rgb:f0f/808/00f" all refer to the same effective color.
colorN" - the color currently assigned to index N within the Xterm 256-color palette. For example, "
color9" specifies the color currently assigned to palette index 9. Note that the current color value is used rather than a reference to that color. If the referenced color is changed later in the color scheme configuration, that new color value will not be reflected in this assignment.
Guacamole provides bidirectional access to the clipboard by default for SSH connections. This behavior can be overridden on a per-connection basis, restricting access to the clipboard.
By default, SSH sessions will start an interactive shell. The shell which will be used is determined by the SSH server, normally by reading the user's default shell previously set with
/etc/passwd. If you wish to override this and instead run a specific command, you can do so by specifying that command in the configuration of the Guacamole SSH connection.
In most cases, the default behavior of the Guacamole terminal emulator works without modification. However, when connecting to certain systems (particularly operating systems other than Linux), the terminal behavior may need to be tweaked to allow it to operate properly. Guacamole's SSH support provides parameters for controlling the control code sent for backspace, as well as the terminal type claimed via the
The full, raw text content of SSH sessions, including timing information, can be recorded automatically to a specified directory. This recording, also known as a "typescript", will be written to two files within the directory specified: one file contains the raw text data, and the other contains timing information. Where "
NAME" is the value provided for the typescript name, these files will be named "
NAME" and "
This format is compatible with the format used by the standard UNIX
scriptcommand, and can be replayed using
scriptreplay(if installed). For example, to replay a typescript called "
NAME", you would run:
$ scriptreplay NAME.timing NAME
SSH sessions can be recorded graphically. These recordings take the form of Guacamole protocol dumps and are recorded automatically to a specified directory. Recordings can be subsequently played back using the Glyptodon Enterprise Session Recording Player application hosted at player.glyptodon.com (or using a local deployment of this application).
Guacamole provides support for file transfer over SSH using SFTP, the file transfer protocol built into most SSH servers. If SFTP is enabled on a Guacamole SSH connection, users will be able to upload and download files through that connection.
While it is always possible to download/upload files using the Guacamole menu accessed using Ctrl+Alt+Shift, it can be more convenient to use the
guacctlutility is a shell script which allows control codes specific to the Guacamole terminal emulator to be sent. If placed within the path on the SSH server(s) being accessed, it can be used by users to initiate file downloads directly within the SSH session.