Advanced configuration of VNC Protocol connection type
Support for the VNC protocol within Keeper Connection Manager is provided by the
kcm-libguac-client-vncpackage. 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, VNC connections will not be functional, with guacd logging a warning noting the absence of needed protocol support:
guacd: WARNING: Support for protocol "vnc" is not installed
If such an error appears within the guacd logs, simply installing
kcm-libguac-client-vncis 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.
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.
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.
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.
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.
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.
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.
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).
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.
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:
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
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 -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=1parameter 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.