SSH

Advanced configuration of SSH Protocol connection type

Support for the SSH protocol within Keeper Connection Manager is provided by the kcm-libguac-client-ssh package. This package will be installed by default if the @kcm package group was used during installation, and is already installed within the keeper/guacd Docker 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[8]: WARNING: Support for protocol "ssh" is not installed

If such an error appears within the guacd logs, simply installing kcm-libguac-client-ssh is 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.

Overview

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.

• Keeper Secrets Manager parameters

• Network parameters

• Authentication parameters

• Display settings

  • Custom color schemes

• Clipboard parameters

• Session / Environment parameters

• Terminal behavior parameters

• Text session recording (typescripts)

• Screen recording parameters

• SFTP parameters (file transfer)

Keeper Secrets Manager parameters

Field header	Parameter name	Description
Allow user-provided KSM configuration:	ksm-user-config-enabled	If set to "true", each Keeper Connection Manager user profile can be assigned to a Keeper Secrets Manager configuration for any connection. See the Multiple Vaults Integration screen for more information.

Network parameters

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).

Field header (web interface)	Parameter name	Description
Hostname:	hostname	REQUIRED: The hostname or IP address of the SSH server Guacamole should connect to.
Port:	port	The port the SSH server is listening on. By default, the standard SSH port of 22 will be used.
Public host key (Base64):	host-key	The known hosts entry for the SSH server, in the same format as would be specified within an OpenSSH known_hosts file. If not provided, no verification of host identity will be performed.

Authentication parameters

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.

Field header (web interface)	Parameter name	Description
Username:	username	The username to authenticate as when connecting to the specified SSH server. If not provided, the user will be prompted to provide a username upon connecting.
Password:	password	The password to use when authenticating with the specified SSH server. If not provided, and no private key is used, the user will be prompted to provide a password upon connecting.
Private key:	private-key	The entire contents of the private key to use for public key authentication. If this parameter is not specified, public key authentication will not be used. The private key must be in OpenSSH format, as would be generated by the OpenSSH ssh-keygen utility.
Passphrase:	passphrase	The passphrase to use to decrypt the private key for use in public key authentication. This parameter is not needed if the private key does not require a passphrase.

Display settings

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.

Field header (web interface)	Parameter name	Description
Color scheme:	color-scheme	The color scheme to use for the terminal emulator used by SSH connections. Each color scheme dictates the default foreground and background color for the terminal. Programs which specify colors when printing text will override these defaults. Legal values are: "black-white" - Black text over a white background "gray-black" - Gray text over a black background (the default) "green-black" - Green text over a black background "white-black" - White text over a black background A custom color scheme (as described below) By default, Guacamole will render text as gray over a black background.
Font name:	font-name	The name of the font to use. If not specified, the default of "monospace" will be used instead. This must be the name of a font installed on the server running guacd, and should be a monospaced font. If a non-monospaced font is used, individual glyphs may render incorrectly.
Font size:	font-size	The size of the font to use, in points. By default, the size of rendered text will be 12 point.
Maximum scrollback size:	scrollback	The maximum number of rows to allow within the terminal scrollback buffer. By default, the scrollback buffer will be limited to a maximum of 1000 rows.
Read-only:	read-only	Whether this connection should be read-only. If set to "true", no input will be accepted on the connection at all. Users will be able to see the terminal (or the application running within the terminal) but will be unable to interact.

Custom color schemes

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:

foreground: rgb:00/00/ff;
background: rgb:ff/ff/ff;
color9: rgb:80/00/80

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:f/8/0", "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.

• "NAME" - the color with human-readable name "NAME", where "NAME" is one of the standard color names supported by X11. These names generally correspond to the names standardized by the W3C for CSS.

Clipboard parameters

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.

Field header (web interface)	Parameter name	Description
Disable copying from terminal:	disable-copy	If set to "true", text copied within the SSH session will not be accessible by the user at the browser side of the Guacamole session, and will be usable only within the remote desktop. By default, the user will be given access to the copied text.
Disable pasting from client:	disable-paste	If set to "true", text copied at the browser side of the Guacamole session will not be accessible within the SSH session. By default, the user will be able to paste data from outside the browser within the SSH session.

Session / Environment parameters

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 chsh or within /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.

Field header (web interface)	Parameter name	Description
Execute command:	command	The command to execute over the SSH session, if any. If not specified, the SSH session will use the user's default shell.
Language/Locale ($LANG):	locale	The specific locale to request for the SSH session. This may be any value accepted by the LANG environment variable of the SSH server. If not specified, the SSH server's default locale will be used. As this parameter is sent to the SSH server using the LANG environment variable, the parameter will only have an effect if the SSH server allows the LANG environment variable to be set by SSH clients.
Time zone ($TZ):	timezone	The time zone to request for the SSH session. This may be any value accepted by the TZ environment variable of the SSH server, typically the standard names defined by the IANA time zone database. If not specified, the SSH server's default time zone will be used. As this parameter is sent to the SSH server using the TZ environment variable, the parameter will only have an effect if the SSH server allows the TZ environment variable to be set by SSH clients.
Server keepalive interval:	server-alive-interval	The interval in seconds between which keepalive packets should be sent to the SSH server, where "0" indicates that no keepalive packets should be sent at all (the default behavior). The minimum legal value is "2".

Terminal behavior parameters

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 TERM environment variable.

Field header (web interface)	Parameter name	Description
Backspace key sends:	backspace	The integer value of the terminal control code that should be sent when backspace is pressed. Under most circumstances this should not need to be adjusted; however, if, when pressing the backspace key, you see control characters (often either ^? or ^H) instead of seeing the text erased, you may need to adjust this parameter. By default, the control code 127 (Delete) is sent.
Terminal type:	terminal-type	The terminal type string that should be passed to the SSH server. This value will typically be exposed within the SSH session as the TERM environment variable and will affect the control characters sent by applications. By default, the terminal type string "linux" is used.

Text session recording (typescripts)

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 "NAME.timing" respectively.

This format is compatible with the format used by the standard UNIX script command, and can be replayed using scriptreplay (if installed). For example, to replay a typescript called "NAME", you would run:

$ scriptreplay NAME.timing NAME

Field header (web interface)	Parameter name	Description
Typescript path:	typescript-path	The directory in which typescript files should be created. If a typescript needs to be recorded, then this parameter is required. Specifying this parameter enables typescript recording. If this parameter is omitted, no typescript will be recorded.
Typescript name:	typescript-name	The base filename to use for any created recordings. If omitted, the base filename "typescript" will be used. Guacamole will never overwrite an existing typescript. If necessary, a numeric suffix like ".1", ".2", ".3", etc. will be appended to the base filename to avoid overwriting an existing recording. If even appending a numeric suffix does not help, the typescript will not be recorded, and an error will be logged. This parameter only has an effect if typescript recording is enabled, which is controlled by specifying a typescript path. If the typescript path is not specified, recording of typescripts will not be enabled, and this parameter will be ignored.
Automatically create typescript path:	create-typescript-path	If set to "true", the final directory within the specified typescript path will automatically be created if it does not yet exist. By default, no part of the typescript path will be automatically created, and any attempt to use a non-existent directory will result in the typescript not being recorded and an error being logged. Only the final directory in the path will be automatically created. If other directories earlier in the path do not exist, the typescript will not be recorded, and an error will be logged. This parameter only has an effect if typescript recording is enabled, which is controlled by specifying a typescript path. If the typescript path is not specified, recording of typescripts will not be enabled, and this parameter will be ignored.

Screen recording parameters

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).

The player is a static web application, using only JavaScript to play back provided recordings. This functionality is implemented strictly locally; the recordings are not uploaded to a remote service for processing. If you would prefer to use your own deployment of this application, or would like to investigate the source, the full source of the Glyptodon Enterprise Session Recording Player can be found on GitHub, along with instructions for local deployment: https://github.com/glyptodon/glyptodon-enterprise-player

The latest version of Keeper Connection Manager supports on-screen playback of recorded sessions. See the Session Recording documentation page.

Field header (web interface)	Parameter name	Description
Recording path:	recording-path	The directory in which screen recording files should be created. If a graphical recording needs to be created, then this parameter is required. Specifying this parameter enables graphical screen recording. If this parameter is omitted, no graphical recording will be created.
Recording name:	recording-name	The filename to use for any created recordings. If omitted, the filename of each recording will simply be "recording". Guacamole will never overwrite an existing recording. If necessary, a numeric suffix like ".1", ".2", ".3", etc. will be appended to the filename to avoid overwriting an existing recording. If even appending a numeric suffix does not help, the session will not be recorded, and an error will be logged. This parameter only has an effect if graphical recording is enabled, which is controlled by specifying a recording path. If the recording path is not specified, graphical session recording will not be enabled, and this parameter will be ignored.
Exclude graphics/streams:	recording-exclude-output	If set to "true", graphical output and other data normally streamed from server to client will be excluded from the recording, producing a recording which contains only user input events. By default, graphical output will be included in the recording. This parameter only has an effect if graphical recording is enabled, which is controlled by specifying a recording path. If the recording path is not specified, graphical session recording will not be enabled, and this parameter will be ignored.
Exclude mouse:	recording-exclude-mouse	If set to "true", user mouse events will be excluded from the recording, producing a recording which lacks a visible mouse cursor. By default, mouse events will be included in the recording. This parameter only has an effect if graphical recording is enabled, which is controlled by specifying a recording path. If the recording path is not specified, graphical session recording will not be enabled, and this parameter will be ignored.
Include key events:	recording-include-keys	If set to "true", user key events will be included in the recording. The recording can subsequently be passed through the guaclog utility to produce a human-readable interpretation of the keys pressed during the session. By default, for privacy's sake, key events will be NOT included in the recording. This parameter only has an effect if graphical recording is enabled, which is controlled by specifying a recording path. If the recording path is not specified, graphical session recording will not be enabled, and this parameter will be ignored.
Automatically create recording path:	create-recording-path	If set to "true", the final directory within the specified recording path will automatically be created if it does not yet exist. By default, no part of the recording path will be automatically created, and any attempt to use a non-existent directory will result in the session not being recorded and an error being logged. Only the final directory in the path will be automatically created. If other directories earlier in the path do not exist, the session will not be recorded, and an error will be logged. This parameter only has an effect if graphical recording is enabled, which is controlled by specifying a recording path. If the recording path is not specified, graphical session recording will not be enabled, and this parameter will be ignored.

SFTP parameters (file transfer)

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 guacctl utility. The guacctl utility 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.

Field header (web interface)	Parameter name	Description
Enable SFTP:	enable-sftp	Whether file transfer should be enabled. If set to "true", the user will be allowed to upload or download files from the SSH server using SFTP.
File browser root directory:	sftp-root-directory	The directory to expose to connected users via Guacamole's file browser. If omitted, the root directory will be used by default.