Advanced configuration of Remote Desktop Protocol connection type
Support for the RDP protocol within Keeper Connection Manager is provided by the
kcm-libguac-client-rdppackage. 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, RDP connections will not be functional, with guacd logging a warning noting the absence of needed protocol support:
guacd: WARNING: Support for protocol "rdp" is not installed
If such an error appears within the guacd logs, simply installing
kcm-libguac-client-rdpis sufficient to resolve the issue:
$ sudo yum install kcm-libguac-client-rdp
The guacd service does not need to be restarted for installation of RDP support to take effect.
Keeper's support for the RDP protocol is controlled through the use of several parameters. When a database like MySQL or PostgreSQL is used, these parameters are presented through the 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.
RDP connections are established over TCP to a specific port and a specific hostname or IP address. The hostname/address must be specified for all RDP connections, but you only need to specify a port if you are not using the standard RDP port (3389).
RDP provides authentication through the use of a username, password, and optional domain. All RDP connections are encrypted, with higher-grade encryption available in the form of TLS.
Microsoft's remote desktop server provides an additional gateway service which allows external connections to be forwarded to internal RDP servers which are otherwise not accessible. If you will be using Guacamole to connect through such a gateway, you will need to provide additional parameters describing the connection to that gateway, as well as any required credentials.
RDP sessions will typically involve the full desktop environment of a normal user. Alternatively, you can manually specify a program to use instead of the RDP server's default shell, or connect to the administrative console.
Although Guacamole is independent of keyboard layout, RDP is not. This is because Guacamole represents keys based on their identity ("press the Enter key"), while RDP uses identifiers based on the key's location ("press the rightmost key in the second row"). To translate between a Guacamole key event and an RDP key event, Guacamole must know ahead of time the keyboard layout of the RDP server.
By default, the US English qwerty keyboard will be used. If this does not match the keyboard layout of your RDP server, keys will not be properly translated, and you will need to explicitly choose a different layout in your connection settings. If your keyboard layout is not supported, please notify us by opening a support ticket through your account.
Guacamole will automatically choose an appropriate display size for RDP connections based on the size of the browser window and the DPI of the device. The size of the display can be forced by specifying explicit width or height values. To reduce bandwidth usage, you may also request that the server reduce its color depth.
Guacamole provides bidirectional access to the clipboard by default for RDP connections. This behavior can be overridden on a per-connection basis, restricting access to the clipboard.
Device redirection refers to the use of non-display devices over RDP. Guacamole's RDP support currently allows redirection of audio (both output and input), printing, and disk access, some of which require additional configuration in order to function properly:
- Audio output is always enabled by default. Configuration changes for audio output need only be made if this should be disabled.
- Audio input, if enabled, allows users to make use of their local microphone within the remote desktop session. Enabling this typically also requires additional configuration within Windows, as group policy is often configured to disable this. Older versions of Windows may lack support for audio input via remote desktop entirely.
- Printing, if enabled, allows users to print arbitrary documents directly to PDF. When documents are printed to the redirected printer, the user will receive a PDF download of that document within their web browser.
- File transfer, if enabled, is provided by emulating a virtual disk drive. This drive will persist on the Guacamole server, confined within the drive path specified.
RDP provides several flags which control the availability of features that decrease performance and increase bandwidth for the sake of aesthetics, such as wallpaper, window theming, menu effects, and smooth fonts. These features are all disabled by default within Guacamole such that bandwidth usage is minimized, but you can manually re-enable them on a per-connection basis if desired.
Recent versions of Windows provide a feature called RemoteApp which allows individual applications to be used over RDP, without providing access to the full desktop environment. If your RDP server has this feature enabled and configured, you can configure Guacamole connections to use those individual applications.
If your remote desktop servers are behind a load balancer, sometimes referred to as a "connection broker" or "TS session broker", that balancer may require additional information during the connection process to determine how the incoming connection should be routed. RDP does not dictate the format of this information; it is specific to the balancer in use.
If you are using a load balancer and are unsure whether such information is required, you will need to check the documentation for your balancer. If your balancer provides
.rdpfiles for convenience, look through the contents of those files for a string field called "
loadbalanceinfo", as that field is where the required information/cookie would be specified.
Some RDP servers host multiple logical RDP connections behind a single server listening on a single TCP port. To select between these logical connections, an RDP client must send the "preconnection PDU" - a message which contains values that uniquely identify the destination, referred to as the "RDP source". This mechanism is defined by the "Session Selection Extension" for the RDP protocol, and is implemented by Microsoft's Hyper-V hypervisor.
If you are using Hyper-V, you will need to specify the ID of the destination virtual machine as the "preconnection BLOB". This value can be determined using PowerShell:
PS C:\> Get-VM VirtualMachineName | Select-Object Id
The preconnection PDU is intentionally generic. While its primary use is as a means for selecting virtual machines behind Hyper-V, other RDP servers may use it as well. It is up to the RDP server itself to determine whether the preconnection ID, BLOB, or both will be used, and what their values mean.
If you do intend to use Hyper-V, beware that its built-in RDP server uses slightly different parameters for both authentication and the port number, and Guacamole's defaults will not work. In most cases, you will need to do the following when connecting to Hyper-V:
- 1.Specify both the username and password appropriately, and set the security mode to "
vmconnect". Selecting the "
vmconnect" security mode will configure Guacamole to automatically negotiate security modes known to be supported by Hyper-V, and will automatically select Hyper-V's default RDP port (2179).
- 2.If necessary, ignore the TLS certificate used by Hyper-V, which may be self-signed.
RDP 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 Keeper Connection Manager Session Recording Player application hosted at player.glyptodon.com (or using a local deployment of this application).
Guacamole can provide file transfer over SFTP even when the remote desktop is otherwise being accessed through RDP and not SSH. This support is independent of the file transfer implemented through RDP's own "drive redirection" (RDPDR), and is particularly useful for RDP servers which do not support RDPDR.