RDP

Advanced configuration of Remote Desktop Protocol connection type

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

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

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

Overview

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.

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

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

Field header (web interface) Parameter name Description

Field header (web interface)	Parameter name	Description
Hostname:	`hostname`	REQUIRED: The hostname or IP address of the RDP server Guacamole should connect to.
Port:	`port`	The port the RDP server is listening on. If this is not specified, the standard port for RDP (3389) or Hyper-V's default port for VMConnect (2179) will be used, depending on the security mode selected.

Hostname:

hostname

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

Port:

port

The port the RDP server is listening on. If this is not specified, the standard port for RDP (3389) or Hyper-V's default port for VMConnect (2179) will be used, depending on the security mode selected.

Authentication/security parameters

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.

If the necessary username and password will be the same as the username and password used to log into Guacamole (due to integrating Guacamole with Active Directory using LDAP, for example), the Guacamole username and password can be passed through by specifying the ${GUAC_USERNAME} and ${GUAC_PASSWORD} tokens respectively.

Field header (web interface) Parameter name Description

Field header (web interface)	Parameter name	Description
Username:	`username`	The username to use to authenticate, if any.
Password:	`password`	The password to use when attempting authentication, if any.
Domain:	`domain`	The domain to use when attempting authentication, if any.
Security mode:	`security`	The security mode to use for the RDP connection. This mode dictates how data will be encrypted and what type of authentication will be performed, if any. By default, security mode negotiation is performed. Legal values are: "`any`" - Negotiate with the server, allowing the RDP server to choose its preferred security mode (the default). "`nla`" - Network Level Authentication, sometimes also referred to as "hybrid" or CredSSP (the protocol that drives NLA) and uses TLS encryption. "`nla-ext`" - Extended Network Level Authentication. This mode is identical to NLA except that an additional "Early User Authorization Result" is required to be sent from the server to the client immediately after the NLA handshake is completed. "`tls`" - Transport Layer Security. "`vmconnect`" - Automatically select the security mode based on the security protocols supported by both the client and the server, limiting that negotiation to only the protocols known to be supported by Hyper-V / VMConnect. This security mode must be selected if connecting to the console of a Hyper-V virtual machine. "`rdp`" - Standard RDP encryption. Newer Windows servers generally have this mode disabled by default, and instead require NLA.
Disable authentication:	`disable-auth`	If set to "`true`", authentication will be disabled. Note that this refers to authentication that takes place while connecting. Any authentication enforced by the server over the remote desktop session (such as a login dialog) will still take place. By default, authentication is enabled and only used when requested by the server. If you are using NLA, authentication must be enabled by definition.
Ignore server certificate:	`ignore-cert`	If set to "true", the certificate returned by the server will be ignored, even if that certificate cannot be validated. This is useful if you universally trust the server and your connection to the server, and you know that the server's certificate cannot be validated (for example, if it is self-signed).

Username:

username

The username to use to authenticate, if any.

Password:

password

The password to use when attempting authentication, if any.

Domain:

domain

The domain to use when attempting authentication, if any.

Security mode:

security

The security mode to use for the RDP connection. This mode dictates how data will be encrypted and what type of authentication will be performed, if any. By default, security mode negotiation is performed.

Legal values are:

"any" - Negotiate with the server, allowing the RDP server to choose its preferred security mode (the default).
"nla" - Network Level Authentication, sometimes also referred to as "hybrid" or CredSSP (the protocol that drives NLA) and uses TLS encryption.
"nla-ext" - Extended Network Level Authentication. This mode is identical to NLA except that an additional "Early User Authorization Result" is required to be sent from the server to the client immediately after the NLA handshake is completed.
"tls" - Transport Layer Security.
"vmconnect" - Automatically select the security mode based on the security protocols supported by both the client and the server, limiting that negotiation to only the protocols known to be supported by Hyper-V / VMConnect. This security mode must be selected if connecting to the console of a Hyper-V virtual machine.
"rdp" - Standard RDP encryption. Newer Windows servers generally have this mode disabled by default, and instead require NLA.

Disable authentication:

disable-auth

If set to "true", authentication will be disabled. Note that this refers to authentication that takes place while connecting. Any authentication enforced by the server over the remote desktop session (such as a login dialog) will still take place. By default, authentication is enabled and only used when requested by the server.

If you are using NLA, authentication must be enabled by definition.

Ignore server certificate:

ignore-cert

If set to "true", the certificate returned by the server will be ignored, even if that certificate cannot be validated. This is useful if you universally trust the server and your connection to the server, and you know that the server's certificate cannot be validated (for example, if it is self-signed).

If you have a corporate CA certificate root that is trusted, you can update the CA_CERTIFICATES environment variable of the keeper/guacd image.

Remote desktop gateway parameters

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.

Field header (web interface) Parameter name Description

Field header (web interface)	Parameter name	Description
Hostname:	`gateway-hostname`	The hostname of the remote desktop gateway that should be used as an intermediary for the remote desktop connection. If omitted, a gateway will not be used.
Port:	`gateway-port`	The port of the remote desktop gateway that should be used as an intermediary for the remote desktop connection. By default, port 443 will be used.
Username:	`gateway-username`	The username of the user authenticating with the remote desktop gateway, if a gateway is being used. This is not necessarily the same as the user actually using the remote desktop connection.
Password:	`gateway-password`	The password to provide when authenticating with the remote desktop gateway, if a gateway is being used.
Domain:	`gateway-domain`	The domain of the user authenticating with the remote desktop gateway, if a gateway is being used. This is not necessarily the same domain as the user actually using the remote desktop connection.

Hostname:

gateway-hostname

The hostname of the remote desktop gateway that should be used as an intermediary for the remote desktop connection. If omitted, a gateway will not be used.

Port:

gateway-port

The port of the remote desktop gateway that should be used as an intermediary for the remote desktop connection. By default, port 443 will be used.

Username:

gateway-username

The username of the user authenticating with the remote desktop gateway, if a gateway is being used. This is not necessarily the same as the user actually using the remote desktop connection.

Password:

gateway-password

The password to provide when authenticating with the remote desktop gateway, if a gateway is being used.

Domain:

gateway-domain

The domain of the user authenticating with the remote desktop gateway, if a gateway is being used. This is not necessarily the same domain as the user actually using the remote desktop connection.

Basic settings

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.

Field header (web interface) Parameter name Description

Field header (web interface)	Parameter name	Description
Initial program:	`initial-program`	The full path to the program to run immediately upon connecting.
Client name:	`client-name`	When connecting to the RDP server, Guacamole will normally provide its own hostname as the name of the client. If this parameter is specified, Guacamole will use its value instead. On Windows RDP servers, this value is exposed within the session as the `CLIENTNAME` environment variable.
Keyboard layout:	`server-layout`	The keyboard layout that the RDP server will be using. Legal values are: "`da-dk-qwerty`" - Danish "`de-ch-qwertz`" - Swiss German "`de-de-qwertz`" - German "`en-gb-qwerty`" - UK English "`en-us-qwerty`" - US English (the default) "`es-es-qwerty`" - Spanish "`es-latam-qwerty`" - Latin American "`fr-be-azerty`" - Belgian French "`fr-ch-qwertz`" - Swiss French "`fr-fr-azerty`" - French "`hu-hu-qwertz`" - Hungarian "`it-it-qwerty`" - Italian "`ja-jp-qwerty`" - Japanese "`pt-br-qwerty`" - Portuguese Brazilian "`sv-se-qwerty`" - Swedish "`tr-tr-qwerty`" - Turkish-Q "`failsafe`" - Force use of Unicode events rather than key events for all keys This is the layout of the RDP server and has nothing to do with the keyboard layout in use on the client. The Guacamole client is independent of keyboard layout. The RDP protocol is not independent of keyboard layout, and Guacamole needs to know the keyboard layout of the server in order to send the proper keys when a user is typing. If you require a keyboard layout that is not currently supported, please notify us by opening a support ticket through your account.
Time zone:	`timezone`	The timezone that the client should send to the server for configuring the local time display of that server. The format of the timezone is in the standard IANA key zone format, which is the format used in UNIX/Linux. This will be converted by RDP into the correct format for Windows. Support for forwarding the client timezone varies by RDP server implementation. For example, with Windows, support for forwarding timezones is only present in Windows Server with Remote Desktop Services (RDS, formerly known as Terminal Services) installed. Windows Server installations in admin mode, along with Windows workstation versions, do not allow the timezone to be forwarded. Other server implementations, such as XRDP, may not implement this feature at all. Consult the documentation for the RDP server to determine whether or not this feature is supported.
Enable multi-touch:	`enable-touch`	"true" if multi-touch support should be enabled for the RDP connection. Enabling RDP support for multi-touch allows touch events to be passed through to the remote desktop, and requires that the RDP server support the RDPEI channel. This parameter does not control whether Guacamole itself supports touch events. Guacamole always supports touch events and will use any touch events to emulate a mouse by default. This parameter controls only whether touch events should be passed directly through to the RDP server instead of emulating a mouse.
Administrator console:	`console`	If set to "true", you will be connected to the console (admin) session of the RDP server.

Initial program:

initial-program

The full path to the program to run immediately upon connecting.

Client name:

client-name

When connecting to the RDP server, Guacamole will normally provide its own hostname as the name of the client. If this parameter is specified, Guacamole will use its value instead.

On Windows RDP servers, this value is exposed within the session as the CLIENTNAME environment variable.

Keyboard layout:

server-layout

The keyboard layout that the RDP server will be using. Legal values are:

"da-dk-qwerty" - Danish
"de-ch-qwertz" - Swiss German
"de-de-qwertz" - German
"en-gb-qwerty" - UK English
"en-us-qwerty" - US English (the default)
"es-es-qwerty" - Spanish
"es-latam-qwerty" - Latin American
"fr-be-azerty" - Belgian French
"fr-ch-qwertz" - Swiss French
"fr-fr-azerty" - French
"hu-hu-qwertz" - Hungarian
"it-it-qwerty" - Italian
"ja-jp-qwerty" - Japanese
"pt-br-qwerty" - Portuguese Brazilian
"sv-se-qwerty" - Swedish
"tr-tr-qwerty" - Turkish-Q
"failsafe" - Force use of Unicode events rather than key events for all keys

This is the layout of the RDP server and has nothing to do with the keyboard layout in use on the client. The Guacamole client is independent of keyboard layout. The RDP protocol is not independent of keyboard layout, and Guacamole needs to know the keyboard layout of the server in order to send the proper keys when a user is typing.

If you require a keyboard layout that is not currently supported, please notify us by opening a support ticket through your account.

Time zone:

timezone

The timezone that the client should send to the server for configuring the local time display of that server. The format of the timezone is in the standard IANA key zone format, which is the format used in UNIX/Linux. This will be converted by RDP into the correct format for Windows.

Support for forwarding the client timezone varies by RDP server implementation. For example, with Windows, support for forwarding timezones is only present in Windows Server with Remote Desktop Services (RDS, formerly known as Terminal Services) installed. Windows Server installations in admin mode, along with Windows workstation versions, do not allow the timezone to be forwarded. Other server implementations, such as XRDP, may not implement this feature at all. Consult the documentation for the RDP server to determine whether or not this feature is supported.

Enable multi-touch:

enable-touch

"true" if multi-touch support should be enabled for the RDP connection. Enabling RDP support for multi-touch allows touch events to be passed through to the remote desktop, and requires that the RDP server support the RDPEI channel.

This parameter does not control whether Guacamole itself supports touch events. Guacamole always supports touch events and will use any touch events to emulate a mouse by default. This parameter controls only whether touch events should be passed directly through to the RDP server instead of emulating a mouse.

Administrator console:

console

If set to "true", you will be connected to the console (admin) session of the RDP server.

Display parameters

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.

Field header (web interface) Parameter name Description

Field header (web interface)	Parameter name	Description
Width:	`width`	The width of the display to request, in pixels. If this value is not specified, the width of the connecting client display will be used instead.
Height:	`height`	The height of the display to request, in pixels. If this value is not specified, the height of the connecting client display will be used instead.
Resolution (DPI):	`dpi`	The desired effective resolution of the client display, in DPI. If this value is not specified, the resolution and size of the client display will be used together to determine, heuristically, an appropriate resolution for the RDP session.
Color depth:	`color-depth`	The color depth to request, in bits per pixel. Legal values 8, 16, or 24. 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.
Resize method:	`resize-method`	The method to use to update the RDP server when the width or height of the client display changes. If this value is not specified, no action will be taken when the client display changes size. Normally, the display size of an RDP session is constant and can only be changed when initially connecting. As of RDP 8.1, the "Display Update" channel can be used to request that the server change the display size. For older RDP servers, the only option is to disconnect and reconnect with the new size. Legal values are: "`display-update`" - Use the "Display Update" channel (added in RDP 8.1) to signal the server when display size has changed "`reconnect`" - Automatically disconnect and reconnect the RDP session when the client display size has changed
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 desktop or application but will be unable to interact.

Width:

width

The width of the display to request, in pixels. If this value is not specified, the width of the connecting client display will be used instead.

Height:

height

The height of the display to request, in pixels. If this value is not specified, the height of the connecting client display will be used instead.

Resolution (DPI):

dpi

The desired effective resolution of the client display, in DPI. If this value is not specified, the resolution and size of the client display will be used together to determine, heuristically, an appropriate resolution for the RDP session.

Color depth:

color-depth

The color depth to request, in bits per pixel. Legal values 8, 16, or 24. 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.

Resize method:

resize-method

The method to use to update the RDP server when the width or height of the client display changes. If this value is not specified, no action will be taken when the client display changes size.

Normally, the display size of an RDP session is constant and can only be changed when initially connecting. As of RDP 8.1, the "Display Update" channel can be used to request that the server change the display size. For older RDP servers, the only option is to disconnect and reconnect with the new size.

Legal values are:

"display-update" - Use the "Display Update" channel (added in RDP 8.1) to signal the server when display size has changed
"reconnect" - Automatically disconnect and reconnect the RDP session when the client display size has changed

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 desktop or application but will be unable to interact.

Clipboard parameters

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.

Field header (web interface) Parameter name Description

Field header (web interface)	Parameter name	Description
Disable copying from remote desktop:	`disable-copy`	If set to "true", text copied within the RDP 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 RDP session. By default, the user will be able to paste data from outside the browser within the RDP session.

Disable copying from remote desktop:

disable-copy

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

Device redirection parameters

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.

Field header (web interface) Parameter name Description

Field header (web interface)	Parameter name	Description
Support audio in console:	`console-audio`	If set to "true", audio will be explicitly enabled in the console (admin) session of the RDP server. Setting this option to "true" only makes sense if the `console` parameter is also set to "true".
Disable audio:	`disable-audio`	Audio output is always enabled by default. If you are concerned about bandwidth usage, or audio is causing problems, you can explicitly disable audio output by setting this parameter to "true".
Enable audio input (microphone):	`enable-audio-input`	If set to "true", audio input support (microphone) will be enabled, leveraging the standard "AUDIO_INPUT" channel of RDP. By default, audio input support within RDP is disabled.
Enable printing:	`enable-printing`	If set to "true", a redirected printer will be made available within the RDP session that users can use to print to a PDF. The PDF is received and automatically downloaded by the user's browser. By default, printing is disabled.
Redirected printer name:	`printer-name`	The name of the redirected printer device that is passed through to the RDP session. This is the name that the user will see in their applications and within the Devices and Printers control panel. If printer redirection is not enabled, this parameter has no effect.
Enable drive:	`enable-drive`	If set to "true", a redirected drive will be made available within the RDP session that users can use to transfer files. The contents of the virtual drive are persisted on the Guacamole server in the directory specified by the "`drive-path`" parameter. By default, drive redirection is disabled.
Drive name:	`drive-name`	The name of the filesystem used when passed through to the RDP session. This is the name that users will see in their Computer/My Computer area along with client name, and is also the name of the share when accessing the special `\\tsclient` network location. If drive redirection is not enabled, this parameter is ignored.
Drive path:	`drive-path`	The directory on the Guacamole server in which transferred files should be stored. This directory must be accessible by the guacd service user or group. If drive redirection is not enabled, this parameter is ignored.
Automatically create drive:	`create-drive-path`	If set to "true", the final directory within the specified drive path will automatically be created if it does not yet exist. By default, no part of the drive path will be automatically created, and any attempt to use a non-existent directory will result in an error. Only the final directory in the path will be automatically created. If other directories earlier in the path do not exist, the will fail with an error. If drive redirection is not enabled, this parameter is ignored.
Static channel names:	`static-channels`	A comma-separated list of static channel names to open and expose as pipes. If you wish to communicate between an application running on the remote desktop and JavaScript, this is the best way to do it. Guacamole will open an outbound pipe with the name of the static channel. If JavaScript needs to communicate back in the other direction, it should respond by opening another pipe with the same name. Guacamole allows any number of static channels to be opened, but protocol restrictions of RDP limit the size of each channel name to 7 characters.

Support audio in console:

console-audio

If set to "true", audio will be explicitly enabled in the console (admin) session of the RDP server. Setting this option to "true" only makes sense if the console parameter is also set to "true".

Disable audio:

disable-audio

Audio output is always enabled by default. If you are concerned about bandwidth usage, or audio is causing problems, you can explicitly disable audio output by setting this parameter to "true".

Enable audio input (microphone):

enable-audio-input

If set to "true", audio input support (microphone) will be enabled, leveraging the standard "AUDIO_INPUT" channel of RDP. By default, audio input support within RDP is disabled.

Enable printing:

enable-printing

If set to "true", a redirected printer will be made available within the RDP session that users can use to print to a PDF. The PDF is received and automatically downloaded by the user's browser. By default, printing is disabled.

Redirected printer name:

printer-name

The name of the redirected printer device that is passed through to the RDP session. This is the name that the user will see in their applications and within the Devices and Printers control panel. If printer redirection is not enabled, this parameter has no effect.

Enable drive:

enable-drive

If set to "true", a redirected drive will be made available within the RDP session that users can use to transfer files. The contents of the virtual drive are persisted on the Guacamole server in the directory specified by the "drive-path" parameter. By default, drive redirection is disabled.

Drive name:

drive-name

The name of the filesystem used when passed through to the RDP session. This is the name that users will see in their Computer/My Computer area along with client name, and is also the name of the share when accessing the special \\tsclient network location.

If drive redirection is not enabled, this parameter is ignored.

Drive path:

drive-path

The directory on the Guacamole server in which transferred files should be stored. This directory must be accessible by the guacd service user or group.

If drive redirection is not enabled, this parameter is ignored.

Automatically create drive:

create-drive-path

If set to "true", the final directory within the specified drive path will automatically be created if it does not yet exist. By default, no part of the drive path will be automatically created, and any attempt to use a non-existent directory will result in an error.

Only the final directory in the path will be automatically created. If other directories earlier in the path do not exist, the will fail with an error.

If drive redirection is not enabled, this parameter is ignored.

Static channel names:

static-channels

A comma-separated list of static channel names to open and expose as pipes. If you wish to communicate between an application running on the remote desktop and JavaScript, this is the best way to do it. Guacamole will open an outbound pipe with the name of the static channel. If JavaScript needs to communicate back in the other direction, it should respond by opening another pipe with the same name.

Guacamole allows any number of static channels to be opened, but protocol restrictions of RDP limit the size of each channel name to 7 characters.

Performance parameters / flags

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.

Field header (web interface) Parameter name Description

Field header (web interface)	Parameter name	Description
Enable wallpaper:	`enable-wallpaper`	If set to "true", enables rendering of the desktop wallpaper. By default, wallpaper will be disabled, such that unnecessary bandwidth need not be spent redrawing the desktop.
Enable theming:	`enable-theming`	If set to "true", enables use of theming of windows and controls. By default, theming within RDP sessions is disabled.
Enable font smoothing (ClearType):	`enable-font-smoothing`	If set to "true", text will be rendered with smooth edges. Text over RDP is rendered with rough edges by default, as this reduces the number of colors used by text, and thus reduces the bandwidth required for the connection.
Enable full-window drag:	`enable-full-window-drag`	If set to "true", the contents of windows will be displayed as windows are moved. By default, the RDP server will only draw the window border while windows are being dragged.
Enable desktop composition (Aero):	`enable-desktop-composition`	If set to "true", graphical effects such as transparent windows and shadows will be allowed. By default, such effects, if available, are disabled.
Enable menu animations:	`enable-menu-animations`	If set to "true", menu open and close animations will be allowed. Menu animations are disabled by default.
Disable bitmap caching:	`disable-bitmap-caching`	If set to "true", the RDP bitmap cache will not be used. By default, caching of bitmaps is enabled. This is generally only useful when dealing with an RDP server that has known bugs in its implementation of bitmap caching, and should remain enabled in most circumstances.
Disable off-screen caching:	`disable-offscreen-caching`	If set to "true," caching of regions of the screen that are not currently visible will be disabled. By default, caching of off-screen regions is enabled. This is generally only useful when dealing with an RDP server that has known bugs in its implementation of off-screen caching, and should remain enabled in most circumstances.
Disable glyph caching:	`disable-glyph-caching`	If set to "true", the RDP glyph cache will not be used. By default, caching of glyphs is enabled. This is generally only useful when dealing with an RDP server that has known bugs in its implementation of glyph caching, and should remain enabled in most circumstances.

Enable wallpaper:

enable-wallpaper

If set to "true", enables rendering of the desktop wallpaper. By default, wallpaper will be disabled, such that unnecessary bandwidth need not be spent redrawing the desktop.

Enable theming:

enable-theming

If set to "true", enables use of theming of windows and controls. By default, theming within RDP sessions is disabled.

Enable font smoothing (ClearType):

enable-font-smoothing

If set to "true", text will be rendered with smooth edges. Text over RDP is rendered with rough edges by default, as this reduces the number of colors used by text, and thus reduces the bandwidth required for the connection.

Enable full-window drag:

enable-full-window-drag

If set to "true", the contents of windows will be displayed as windows are moved. By default, the RDP server will only draw the window border while windows are being dragged.

Enable desktop composition (Aero):

enable-desktop-composition

If set to "true", graphical effects such as transparent windows and shadows will be allowed. By default, such effects, if available, are disabled.

Enable menu animations:

enable-menu-animations

If set to "true", menu open and close animations will be allowed. Menu animations are disabled by default.

Disable bitmap caching:

disable-bitmap-caching

If set to "true", the RDP bitmap cache will not be used. By default, caching of bitmaps is enabled.

This is generally only useful when dealing with an RDP server that has known bugs in its implementation of bitmap caching, and should remain enabled in most circumstances.

Disable off-screen caching:

disable-offscreen-caching

If set to "true," caching of regions of the screen that are not currently visible will be disabled. By default, caching of off-screen regions is enabled.

This is generally only useful when dealing with an RDP server that has known bugs in its implementation of off-screen caching, and should remain enabled in most circumstances.

Disable glyph caching:

disable-glyph-caching

If set to "true", the RDP glyph cache will not be used. By default, caching of glyphs is enabled.

This is generally only useful when dealing with an RDP server that has known bugs in its implementation of glyph caching, and should remain enabled in most circumstances.

RemoteApp parameters

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.

Field header (web interface) Parameter name Description

Field header (web interface)	Parameter name	Description
Program:	`remote-app`	The RemoteApp to start on the remote desktop. If supported by your remote desktop server, this application, and only this application, will be visible to the user. For an application to be available, it must generally be explicitly listed as allowed ahead of time within Windows Server Manager. Windows requires a special notation for the aliases of remote applications. When specifying the alias of a remote application, it must be prefixed with two vertical bars ("`\|\|`"). For example, if you have created a remote application on your server for `notepad.exe` and have assigned it the alias "notepad", you would set this parameter to "`\|\|notepad`".
Working directory:	`remote-app-dir`	The working directory of the remote application, if any. This parameter has no effect if RemoteApp is not in use.
Parameters:	`remote-app-args`	The command-line arguments to pass to the remote application, if any. This parameter has no effect if RemoteApp is not in use.

Program:

remote-app

The RemoteApp to start on the remote desktop. If supported by your remote desktop server, this application, and only this application, will be visible to the user. For an application to be available, it must generally be explicitly listed as allowed ahead of time within Windows Server Manager.

Windows requires a special notation for the aliases of remote applications. When specifying the alias of a remote application, it must be prefixed with two vertical bars ("||"). For example, if you have created a remote application on your server for notepad.exe and have assigned it the alias "notepad", you would set this parameter to "||notepad".

Working directory:

remote-app-dir

The working directory of the remote application, if any. This parameter has no effect if RemoteApp is not in use.

Parameters:

remote-app-args

The command-line arguments to pass to the remote application, if any. This parameter has no effect if RemoteApp is not in use.

Load balancing parameters (connection broker)

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 .rdp files 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.

Field header (web interface) Parameter name Description

Field header (web interface)	Parameter name	Description
Load balance info/cookie:	`load-balance-info`	The load balancing information or cookie which should be provided to the connection broker. If no connection broker is being used, this should be left blank.

Load balance info/cookie:

load-balance-info

The load balancing information or cookie which should be provided to the connection broker. If no connection broker is being used, this should be left blank.

Preconnection PDU (Hyper-V)

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 

Id
--
ed272546-87bd-4db9-acba-e36e1a9ca20a


PS C:\>

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:

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).
If necessary, ignore the TLS certificate used by Hyper-V, which may be self-signed.

Field header (web interface) Parameter name Description

Field header (web interface)	Parameter name	Description
RDP source ID:	`preconnection-id`	The numeric ID of the RDP source. This is a non-negative integer value dictating which of potentially several logical RDP connections should be used. This parameter is only required if the RDP server is documented as requiring it. If using Hyper-V, this should be left blank.
Preconnection BLOB (VM ID):	`preconnection-blob`	An arbitrary string which identifies the RDP source - one of potentially several logical RDP connections hosted by the same RDP server. This parameter is only required if the RDP server is documented as requiring it, such as Hyper-V. In all cases, the meaning of this parameter is opaque to the RDP protocol itself and is dictated by the RDP server. For Hyper-V, this will be the ID of the destination virtual machine.

RDP source ID:

preconnection-id

The numeric ID of the RDP source. This is a non-negative integer value dictating which of potentially several logical RDP connections should be used. This parameter is only required if the RDP server is documented as requiring it. If using Hyper-V, this should be left blank.

Preconnection BLOB (VM ID):

preconnection-blob

An arbitrary string which identifies the RDP source - one of potentially several logical RDP connections hosted by the same RDP server. This parameter is only required if the RDP server is documented as requiring it, such as Hyper-V. In all cases, the meaning of this parameter is opaque to the RDP protocol itself and is dictated by the RDP server. For Hyper-V, this will be the ID of the destination virtual machine.

Screen recording parameters

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

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 Keeper Connection Manager 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.
Exclude touch events:	`recording-exclude-touch`	If set to "true", user touch events will be excluded from the recording, producing a recording which lacks the exact details of touch interactions. This will not necessarily prevent touch events from being visible, as the remote desktop server may still choose to render touch interaction on its own. By default, touch 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.

Exclude touch events:

recording-exclude-touch

If set to "true", user touch events will be excluded from the recording, producing a recording which lacks the exact details of touch interactions. This will not necessarily prevent touch events from being visible, as the remote desktop server may still choose to render touch interaction on its own. By default, touch 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)

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.

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 RDP 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 RDP 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".

PreviousConnection Protocols NextSSH

Last updated 25 days ago