VNC
Advanced configuration of VNC Protocol connection type
Last updated
Advanced configuration of VNC Protocol connection type
Last updated
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 Keeper'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 Keeper will still use only a single connection.
Allow user-provided KSM configuration:
ksm-user-config-enabled
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.
Hostname:
hostname
REQUIRED: The hostname or IP address of the VNC server that Keeper 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.
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.
Password:
password
The password to use when attempting authentication, if any.
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. Keeper 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.
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, Keeper 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 Keeper detects that doing so would likely outperform lossless compression.
Keeper Connection Manager 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 Keeper 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.
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 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 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.
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.
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.
VNC sessions can be recorded graphically. These recordings take the form of Apache Guacamole protocol dumps and are recorded automatically to a specified directory. Recordings can be subsequently played back using the web interface or 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.
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".
Keeper 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.
VNC does not normally support file transfer, but Keeper Connection Manager can provide file transfer over SFTP even when the remote desktop is otherwise being accessed through VNC and not SSH.
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".
VNC does not provide its own support for audio, but Keeper Connection Manager'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, Keeper 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:
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.
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:
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:
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:
In all cases, the auth-anonymous=1 parameter is strictly required. Keeper Connection Manager does not currently support the cookie-based authentication used by PulseAudio for non-anonymous connections. If this parameter is omitted, Keeper will not be able to connect to PulseAudio.
If set to "true", each Keeper Connection Manager user profile can be assigned to a Keeper Secrets Manager configuration for any connection. See the screen for more information.
