VNC

Advanced configuration of VNC Protocol connection type

Support for the VNC protocol within Keeper Connection Manager is provided by the kcm-libguac-client-vnc 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, VNC connections will not be functional, with guacd logging a warning noting the absence of needed protocol support:

guacd[8]: WARNING: Support for protocol "vnc" is not installed

If such an error appears within the guacd logs, simply installing kcm-libguac-client-vnc is sufficient to resolve the issue:

$ sudo yum install kcm-libguac-client-vnc

The guacd service does not need to be restarted for installation of VNC support to take effect.

Overview

Keeper's support for the VNC 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.

Some features provided by Guacamole's VNC support are implemented through additional protocols like SFTP and PulseAudio. This is done transparently. While additional network connections may be used between guacd and the remote desktop servers, everything between the user and Guacamole will still use only a single connection.

Keeper Secrets Manager parameters

Field header Parameter name Description

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.

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

VNC connections are established over TCP to a specific port and a specific hostname or IP address. In general, each VNC server is associated with a display number, from which the appropriate port number is derived, though most VNC servers provide a means of overriding this default behavior. Both the hostname and port are required parameters for all VNC connections.

Field header (web interface) Parameter name Description

Field header (web interface)	Parameter name	Description
Hostname:	`hostname`	REQUIRED: The hostname or IP address of the VNC server that Guacamole should connect to.
Port:	`port`	REQUIRED: The TCP port that the VNC server is listening on. This value is typically 5900 or 5900 + display number. For example, if your VNC server is serving display number 1 (sometimes written as ":1"), your port number here would be 5901.

Hostname:

hostname

REQUIRED: The hostname or IP address of the VNC server that Guacamole should connect to.

Port:

port

REQUIRED: The TCP port that the VNC server is listening on.

This value is typically 5900 or 5900 + display number. For example, if your VNC server is serving display number 1 (sometimes written as ":1"), your port number here would be 5901.

Authentication parameters

The VNC standard defines only password based authentication, with other authentication mechanisms being non-standard or proprietary. Keeper Connection Manager currently supports only the password method.

Field header (web interface) Parameter name Description

Field header (web interface)	Parameter name	Description
Password:	`password`	The password to use when attempting authentication, if any.

Password:

password

The password to use when attempting authentication, if any.

Display settings

VNC servers do not allow the client to request particular display sizes, so you are at the mercy of your VNC server with respect to display width and height. However, to reduce bandwidth usage, you may request that the VNC server reduce its color depth. Guacamole will automatically detect 256-color images, but this can be guaranteed for absolutely all graphics sent over the connection by forcing the color depth to 8-bit. Color depth is otherwise dictated by the VNC server.

If you are noticing problems with your VNC display, such as the lack of a mouse cursor, the presence of multiple mouse cursors, or strange colors (such as blue colors appearing more like orange or red), these are typically the result of bugs or limitations within the VNC server, and additional parameters are available to work around such issues.

Field header (web interface) Parameter name Description

Field header (web interface)	Parameter name	Description
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 only see the desktop and whatever other users using that same desktop are doing.
Swap red/blue components:	`swap-red-blue`	If the colors of your display appear wrong (blues appear orange or red, etc.), it may be that your VNC server is sending image data incorrectly, and the red and blue components of each color are swapped. If this is the case, set this parameter to "true" to work around the problem.
Cursor:	`cursor`	If set to "remote", the mouse pointer will be rendered remotely, and the local position of the mouse pointer will be indicated by a small dot. A remote mouse cursor will feel slower than a local cursor, but may be necessary if the VNC server does not support sending the cursor image to the client.
Color depth:	`color-depth`	The color depth to request, in bits per pixel. Legal values are 8, 16, 24, or 32. Note that, regardless of what value is chosen here, Guacamole will always attempt to optimize image transmission, automatically using fewer bits per pixel if doing so will not visibly alter image quality.
Force lossless compression:	`force-lossless`	Whether this connection should use lossless compression only. If set to "true", all graphical updates will use lossless compression algorithms. By default, lossy compression will automatically be used when Guacamole detects that doing so would likely outperform lossless compression.

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 only see the desktop and whatever other users using that same desktop are doing.

Swap red/blue components:

swap-red-blue

If the colors of your display appear wrong (blues appear orange or red, etc.), it may be that your VNC server is sending image data incorrectly, and the red and blue components of each color are swapped. If this is the case, set this parameter to "true" to work around the problem.

Cursor:

cursor

If set to "remote", the mouse pointer will be rendered remotely, and the local position of the mouse pointer will be indicated by a small dot. A remote mouse cursor will feel slower than a local cursor, but may be necessary if the VNC server does not support sending the cursor image to the client.

Color depth:

color-depth

The color depth to request, in bits per pixel. Legal values are 8, 16, 24, or 32. Note that, regardless of what value is chosen here, Guacamole will always attempt to optimize image transmission, automatically using fewer bits per pixel if doing so will not visibly alter image quality.

Force lossless compression:

force-lossless

Whether this connection should use lossless compression only. If set to "true", all graphical updates will use lossless compression algorithms. By default, lossy compression will automatically be used when Guacamole detects that doing so would likely outperform lossless compression.

Clipboard parameters

Guacamole provides bidirectional access to the clipboard by default for VNC connections, and will automatically translate clipboard data from its native UTF-8 format into the ISO 8859-1 encoding required by the VNC standard. This behavior can be overridden on a per-connection basis, restricting access to the clipboard and/or forcing Guacamole to assume that the VNC server uses a non-standard encoding.

The only clipboard encoding guaranteed to be supported by VNC servers is ISO 8859-1. You should only override the clipboard encoding if you are absolutely positive that the VNC server supports and expects a different encoding.

Field header (web interface) Parameter name Description

Field header (web interface)	Parameter name	Description
Encoding:	`clipboard-encoding`	The encoding to assume for the VNC clipboard. By default, the standard encoding ISO 8859-1 will be used. Only use this parameter if you are sure your VNC server expects a different, non-standard encoding. Possible values are: "`ISO8859-1`" - The clipboard encoding mandated by the VNC standard. "`UTF-8`" "`UTF-16`" "`CP1252`" - Code page 1252, a Windows-specific encoding for Latin characters which is mostly a superset of ISO 8859-1.
Disable copying from remote desktop:	`disable-copy`	If set to "true", text copied within the VNC 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 VNC session. By default, the user will be able to paste data from outside the browser within the VNC session.

Encoding:

clipboard-encoding

The encoding to assume for the VNC clipboard. By default, the standard encoding ISO 8859-1 will be used. Only use this parameter if you are sure your VNC server expects a different, non-standard encoding.

Possible values are:

"ISO8859-1" - The clipboard encoding mandated by the VNC standard.
"UTF-8"
"UTF-16"
"CP1252" - Code page 1252, a Windows-specific encoding for Latin characters which is mostly a superset of ISO 8859-1.

Disable copying from remote desktop:

disable-copy

If set to "true", text copied within the VNC 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 VNC session. By default, the user will be able to paste data from outside the browser within the VNC session.

VNC repeater parameters

There exist VNC repeaters, such as UltraVNC Repeater, which act as intermediaries or proxies, providing a single logical VNC connection which is then routed to another VNC server elsewhere. Additional parameters are required to select which VNC host behind the repeater will receive the connection.

Field header (web interface) Parameter name Description

Field header (web interface)	Parameter name	Description
Destination host:	`dest-host`	The destination host to request when connecting to a VNC proxy such as UltraVNC Repeater. This is only necessary if the VNC proxy in use requires the connecting user to specify which VNC server to connect to. If the VNC proxy automatically connects to a specific server, this parameter is not necessary.
Destination port:	`dest-port`	The destination port to request when connecting to a VNC proxy such as UltraVNC Repeater. This is only necessary if the VNC proxy in use requires the connecting user to specify which VNC server to connect to. If the VNC proxy automatically connects to a specific server, this parameter is not necessary.

Destination host:

dest-host

The destination host to request when connecting to a VNC proxy such as UltraVNC Repeater. This is only necessary if the VNC proxy in use requires the connecting user to specify which VNC server to connect to. If the VNC proxy automatically connects to a specific server, this parameter is not necessary.

Destination port:

dest-port

The destination port to request when connecting to a VNC proxy such as UltraVNC Repeater. This is only necessary if the VNC proxy in use requires the connecting user to specify which VNC server to connect to. If the VNC proxy automatically connects to a specific server, this parameter is not necessary.

Screen recording parameters

VNC 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

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.

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.

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.

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.

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.

SFTP parameters (file transfer)

VNC does not normally support file transfer, but Guacamole can provide file transfer over SFTP even when the remote desktop is otherwise being accessed through VNC and not SSH.

Field header (web interface) Parameter name Description

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 specified server using SFTP. If omitted, SFTP will be disabled.
Hostname:	`sftp-hostname`	The hostname or IP address of the server hosting SFTP. If omitted, the specified hostname or address of the VNC server will be used.
Port:	`sftp-port`	The port the SSH server providing SFTP is listening on, usually 22. If omitted, the standard port of 22 will be used.
Public host key (Base64):	`sftp-host-key`	The known hosts entry for the SSH server providing SFTP, 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.
Username:	`sftp-username`	The username to authenticate as when connecting to the specified SSH server for SFTP. This parameter is required if SFTP is enabled.
Password:	`sftp-password`	The password to use when authenticating with the specified SSH server for SFTP.
Private key:	`sftp-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:	`sftp-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.
File browser upload 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.
Default upload directory:	`sftp-directory`	The directory to upload files to if they are simply dragged and dropped, and thus otherwise lack a specific upload location. If omitted, the default upload location of the SSH server providing SFTP will be used.
SFTP keepalive interval:	`sftp-server-alive-interval`	The interval in seconds between which keepalive packets should be sent to the SSH server for the SFTP connection, where "0" indicates that no keepalive packets should be sent at all (the default behavior). The minimum legal value is "2".

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 specified server using SFTP. If omitted, SFTP will be disabled.

Hostname:

sftp-hostname

The hostname or IP address of the server hosting SFTP. If omitted, the specified hostname or address of the VNC server will be used.

Port:

sftp-port

The port the SSH server providing SFTP is listening on, usually 22. If omitted, the standard port of 22 will be used.

Public host key (Base64):

sftp-host-key

The known hosts entry for the SSH server providing SFTP, 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.

Username:

sftp-username

The username to authenticate as when connecting to the specified SSH server for SFTP. This parameter is required if SFTP is enabled.

Password:

sftp-password

The password to use when authenticating with the specified SSH server for SFTP.

Private key:

sftp-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:

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

File browser upload 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.

Default upload directory:

sftp-directory

The directory to upload files to if they are simply dragged and dropped, and thus otherwise lack a specific upload location. If omitted, the default upload location of the SSH server providing SFTP will be used.

SFTP keepalive interval:

sftp-server-alive-interval

The interval in seconds between which keepalive packets should be sent to the SSH server for the SFTP connection, where "0" indicates that no keepalive packets should be sent at all (the default behavior). The minimum legal value is "2".

Audio parameters (PulseAudio)

VNC does not provide its own support for audio, but Guacamole's VNC support can obtain audio through a secondary network connection to a PulseAudio server running on the same machine as the VNC server.

Most Linux systems provide audio through a service called PulseAudio. This service is capable of communicating over the network, and if PulseAudio is configured to allow TCP connections, Guacamole can connect to your PulseAudio server and combine its audio with the graphics coming over VNC.

The following parameters are available for configuring the audio support for VNC:

Field header (web interface) Parameter name Description

Field header (web interface)	Parameter name	Description
Enable audio:	`enable-audio`	If set to "true", audio support will be enabled, and a second connection for PulseAudio will be made in addition to the VNC connection. By default, audio support within VNC is disabled.
Audio server name:	`audio-servername`	The name of the PulseAudio server to connect to. This will be the hostname or address of the computer providing audio for your connection via PulseAudio, most likely the same as the hostname/address of the VNC server. If this parameter is omitted, the default PulseAudio device will be used, which will be the PulseAudio server running on the same machine as guacd.

Enable audio:

enable-audio

If set to "true", audio support will be enabled, and a second connection for PulseAudio will be made in addition to the VNC connection. By default, audio support within VNC is disabled.

Audio server name:

audio-servername

The name of the PulseAudio server to connect to. This will be the hostname or address of the computer providing audio for your connection via PulseAudio, most likely the same as the hostname/address of the VNC server.

If this parameter is omitted, the default PulseAudio device will be used, which will be the PulseAudio server running on the same machine as guacd.

Configuring PulseAudio to accept TCP connections

For PulseAudio to accept network connections, its TCP module must be loaded. The TCP module is not typically loaded by default, and must be manually loaded through an additional line within the PulseAudio configuration file (usually /etc/pulse/default.pa). The options specified for the module dictate exactly where these connections are allowed from, providing a degree of security. For example, to allow connections from only the 10.0.0.0/8 subnet:

load-module module-native-protocol-tcp auth-ip-acl=10.0.0.0/8 auth-anonymous=1

It is also possible to allow connections from absolutely anywhere, but beware that you should only do so if the nature of your network prevents unauthorized access:

load-module module-native-protocol-tcp auth-anonymous=1

Once the PulseAudio configuration file has been modified appropriately, restart the PulseAudio service. PulseAudio should then begin listening on port 4713 (the default PulseAudio port) for incoming TCP connections. You can verify this using a utility like netstat:

$ netstat -ln | grep 4713
tcp        0      0 0.0.0.0:4713            0.0.0.0:*                LISTEN
tcp6       0      0 :::4713                 :::*                     LISTEN
$

In all cases, the auth-anonymous=1 parameter is strictly required. Guacamole does not currently support the cookie-based authentication used by PulseAudio for non-anonymous connections. If this parameter is omitted, Guacamole will not be able to connect to PulseAudio.

PreviousSSH NextKubernetes

Last updated 1 year ago