mike-jumper commented on a change in pull request #165: URL: https://github.com/apache/guacamole-manual/pull/165#discussion_r642142065
########## File path: src/configuring-guacamole.md ########## @@ -0,0 +1,2770 @@ +Configuring Guacamole +===================== + +After installing Guacamole, you need to configure users and connections before +Guacamole will work. This chapter covers general configuration of Guacamole and +the use of its default authentication method. + +Guacamole's default authentication method reads all users and connections from +a single file called `user-mapping.xml`. This authentication method is intended +to be: + +1. Sufficient for small deployments of Guacamole. + +2. A relatively-easy means of verifying that Guacamole has been properly set + up. + +Other, more complex authentication methods which use backend databases, LDAP, +etc. are discussed in a separate, dedicated chapters. + +Regardless of the authentication method you use, Guacamole's configuration +always consists of two main pieces: a directory referred to as +`GUACAMOLE_HOME`, which is the primary search location for configuration files, +and `guacamole.properties`, the main configuration file used by Guacamole and +its extensions. + +(guacamole-home)= + +`GUACAMOLE_HOME` (`/etc/guacamole`) +--------------------------------------- + +`GUACAMOLE_HOME` is the name given to Guacamole's configuration directory, +which is located at `/etc/guacamole` by default. All configuration files, +extensions, etc. reside within this directory. The structure of +`GUACAMOLE_HOME` is rigorously defined, and consists of the following optional +files: + +`guacamole.properties` +: The main Guacamole configuration file. Properties within this file dictate + how Guacamole will connect to guacd, and may configure the behavior of + installed authentication extensions. + +`logback.xml` +: Guacamole uses a logging system called Logback for all messages. By + default, Guacamole will log to the console only, but you can change this + by providing your own Logback configuration file. + +`extensions/` +: The install location for all Guacamole extensions. Guacamole will + automatically load all `.jar` files within this directory on startup. + +`lib/` +: The search directory for libraries required by any Guacamole extensions. + Guacamole will make the `.jar` files within this directory available to + all extensions. If your extensions require additional libraries, such as + database drivers, this is the proper place to put them. + +(overriding-guacamole-home)= + +### Overriding `GUACAMOLE_HOME` + +If you cannot or do not wish to use `/etc/guacamole` for `GUACAMOLE_HOME`, the +location can be overridden through any of the following methods: + +1. Creating a directory named `.guacamole`, within the home directory of *the + user running the servlet container*. This directory will automatically be + used for `GUACAMOLE_HOME` if it exists. + +2. Specifying the full path to an alternative directory with the environment + variable `GUACAMOLE_HOME`. *Be sure to consult the documentation for your + servlet container to determine how to properly set environment variables.* + +3. Specifying the full path to an alternative directory with the system + property guacamole.home. + +(initial-setup)= + +`guacamole.properties` +------------------------ + +The Guacamole web application uses one main configuration file called +`guacamole.properties`. This file is the common location for all configuration +properties read by Guacamole or any extension of Guacamole, including +authentication providers. + +In previous releases, this file had to be in the classpath of your servlet +container. Now, the location of `guacamole.properties` can be explicitly +defined with environment variables or system properties, and the classpath is +only used as a last resort. When searching for `guacamole.properties`, +Guacamole will check, in order: + +1. Within `GUACAMOLE_HOME`, as defined above. + +2. The classpath of the servlet container. + +The `guacamole.properties` file is optional and is used to configure Guacamole +in situations where the defaults are insufficient, or to provide additional +configuration information for extensions. There are several standard properties +that are always available for use: + +`api-session-timeout` +: The amount of time, in minutes, to allow Guacamole sessions + (authentication tokens) to remain valid despite inactivity. If omitted, + Guacamole sessions will expire after 60 minutes of inactivity. + +`api-max-request-size` +: The maximum number of bytes to accept within the entity body of any + particular HTTP request, where 0 indicates that no limit should be + applied. If omitted, requests will be limited to 2097152 bytes (2 MB) by + default. This limit does not apply to file uploads. + + If using a reverse proxy for SSL termination, *keep in mind that reverse + proxies may enforce their own limits independently of this*. For example, + [Nginx will enforce a 1 MB request size limit by + default](nginx-file-upload-size). + +`allowed-languages` +: A comma-separated whitelist of language keys to allow as display language + choices within the Guacamole interface. For example, to restrict Guacamole + to only English and German, you would specify: + + ``` + allowed-languages: en, de + ``` + + As English is the fallback language, used whenever a translation key is + missing from the chosen language, English should only be omitted from this + list if you are absolutely positive that no strings are missing. + + The corresponding JSON of any built-in languages not listed here will + still be available over HTTP, but the Guacamole interface will not use + them, nor will they be used automatically based on local browser language. + If omitted, all defined languages will be available. + +`enable-environment-properties` +: If set to "true", Guacamole will first evaluate its environment to obtain + the value for any given configuration property, before using a value + specified in `guacamole.properties` or falling back to a default value. By + enabling this option, you can easily override any other configuration + property using an environment variable. + + ``` + enable-environment-properties: true + ``` + + When searching for a configuration property in the environment, the name + of the property is first transformed by converting all lower case + characters to their upper case equivalents, and by replacing all hyphen + characters (`-`) with underscore characters (`_`). For example, the + `guacd-hostname` property would be transformed to `GUACD_HOSTNAME` when + searching the environment. + +`guacd-hostname` +: The host the Guacamole proxy daemon (guacd) is listening on. If omitted, + Guacamole will assume guacd is listening on localhost. + +`guacd-port` +: The port the Guacamole proxy daemon (guacd) is listening on. If omitted, + Guacamole will assume guacd is listening on port 4822. + +`guacd-ssl` +: If set to "true", Guacamole will require SSL/TLS encryption between the + web application and guacd. By default, communication between the web + application and guacd will be unencrypted. + + Note that if you enable this option, you must also configure guacd to use + SSL via command line options. These options are documented in the manpage + of guacd. You will need an SSL certificate and private key. + +`skip-if-unavailable` +: A comma-separated list of the identifiers of authentication providers that + should be allowed to fail internally without aborting the authentication + process. For example, to request that Guacamole ignore failures due to the + LDAP directory or MySQL server being unexpectedly down, allowing other + authentication providers to continue functioning: + + ``` + skip-if-unavailable: mysql, ldap + ``` + + By default, Guacamole takes a conservative approach to internal failures, + aborting the authentication process if an internal error occurs within any + authentication provider. Depending on the nature of the error, this may + mean that no users can log in until the cause of the failure is dealt + with. The `skip-if-unavailable` property may be used to explicitly inform + Guacamole that one or more underlying systems are expected to occasionally + experience failures, and that other functioning systems should be relied + upon if they do fail. + + +``` +# Hostname and port of guacamole proxy +guacd-hostname: localhost +guacd-port: 4822 +``` + +(webapp-logging)= + +Logging within the web application +---------------------------------- + +By default, Guacamole logs all messages to the console. Servlet containers like +Tomcat will automatically redirect these messages to a log file, `catalina.out` +in the case of Tomcat, which you can read through while Guacamole runs. +Messages are logged at four different log levels, depending on message +importance and severity: + +`error` +: Errors are fatal conditions. An operation, described in the log message, + was attempted but could not proceed, and the failure of this operation is + a serious problem that needs to be addressed. + +`warn` +: Warnings are generally non-fatal conditions. The operation continued, but + encountered noteworthy problems. + +`info` +: "Info" messages are purely informational. They may be useful or + interesting to administrators, but are not generally critical to proper + operation of a Guacamole server. + +`debug` +: Debug messages are highly detailed and oriented toward development. Most + debug messages will contain stack traces and internal information that is + useful when investigating problems within code. It is expected that debug + messages, though verbose, will not affect performance. + +`trace` +: Trace messages are similar to debug messages in intent and verbosity, but + are so low-level that they may affect performance due to their frequency. + Trace-level logging is rarely necessary, and is mainly useful in providing + highly detailed context around issues being investigated. + +Guacamole logs messages using a logging framework called +[Logback](http://logback.qos.ch/) and, by default, will only log messages at +the "`info`" level or higher. If you wish to change the log level, or configure +how or where Guacamole logs messages, you can do so by providing your own +`logback.xml` file within `GUACAMOLE_HOME`. For example, to log all messages +to the console, even "`debug`" messages, you might use the following +`logback.xml`: + +```xml +<configuration> + + <!-- Appender for debugging --> + <appender name="GUAC-DEBUG" class="ch.qos.logback.core.ConsoleAppender"> + <encoder> + <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> + </encoder> + </appender> + + <!-- Log at DEBUG level --> + <root level="debug"> + <appender-ref ref="GUAC-DEBUG"/> + </root> + +</configuration> +``` + +Guacamole and the above example configure only one appender which logs to the +console, but Logback is extremely flexible and allows any number of appenders +which can each log to separate files, the console, etc. based on a number of +criteria, including the log level and the source of the message. + +More thorough [documentation on configuring +Logback](http://logback.qos.ch/manual/configuration.html) is provided on the +Logback project's web site. + +(basic-auth)= + +Using the default authentication +-------------------------------- + +Guacamole's default authentication module is simple and consists of a mapping +of usernames to configurations. This authentication module comes with Guacamole +and simply reads usernames and passwords from an XML file. It is always +enabled, but will only read from the XML file if it exists, and is always last +in priority relative to any other authentication extensions. + +There are other authentication modules available. The Guacamole project +provides database-backed authentication modules with the ability to manage +connections and users from the web interface, and other authentication modules +can be created using the extension API provided along with the Guacamole web +application, guacamole-ext. + +(user-mapping)= + +### `user-mapping.xml` + +The default authentication provider used by Guacamole reads all username, +password, and configuration information from a file called the "user mapping" +located at `GUACAMOLE_HOME/user-mapping.xml`. An example of a user mapping file +is included with Guacamole, and looks something like this: + +```xml +<user-mapping> + + <!-- Per-user authentication and config information --> + <authorize username="USERNAME" password="PASSWORD"> + <protocol>vnc</protocol> + <param name="hostname">localhost</param> + <param name="port">5900</param> + <param name="password">VNCPASS</param> + </authorize> + + <!-- Another user, but using md5 to hash the password + (example below uses the md5 hash of "PASSWORD") --> + <authorize + username="USERNAME2" + password="319f4d26e3c536b5dd871bb2c52e3178" + encoding="md5"> + + <!-- First authorized connection --> + <connection name="localhost"> + <protocol>vnc</protocol> + <param name="hostname">localhost</param> + <param name="port">5901</param> + <param name="password">VNCPASS</param> + </connection> + + <!-- Second authorized connection --> + <connection name="otherhost"> + <protocol>vnc</protocol> + <param name="hostname">otherhost</param> + <param name="port">5900</param> + <param name="password">VNCPASS</param> + </connection> + + </authorize> + +</user-mapping> +``` + +Each user is specified with a corresponding `<authorize>` tag. This tag +contains all authorized connections for that user, each denoted with a +`<connection>` tag. Each `<connection>` tag contains a corresponding protocol +and set of protocol-specific parameters, specified with the `<protocol>` and +`<param>` tags respectively. + +(user-setup)= + +#### Adding users + +When using `user-mapping.xml`, username/password pairs are specified with +`<authorize>` tags, which each have a `username` and `password` attribute. Each +`<authorize>` tag authorizes a specific username/password pair to access all +connections within the tag: + +```xml +<authorize username="USER" password="PASS"> + ... +</authorize> +``` + +In the example above, the password would be listed in plaintext. If you don't +want to do this, you can also specify your password hashed with MD5: + +```xml +<authorize username="USER" + password="319f4d26e3c536b5dd871bb2c52e3178" + encoding="md5"> + ... +</authorize> +``` + +After modifying `user-mapping.xml`, the file will be automatically reread by +Guacamole, and your changes will take effect immediately. The newly-added user +will be able to log in - no restart of the servlet container is needed. + +(connection-setup)= + +#### Adding connections to a user + +To specify a connection within an `<authorize>` tag, you can either list a +single protocol and set of parameters (specified with a `<protocol>` tag and +any number of `<param>` tags), in which case that user will have access to only +one connection named "DEFAULT", or you can specify one or more connections with +one or more `<connection>` tags, each of which can be named and contains a +`<protocol>` tag and any number of `<param>` tags. + +(connection-configuration)= + +Configuring connections +----------------------- + +Each protocol supported by Guacamole has its own set of configuration +parameters. These parameters typically describe the hostname and port of the +remote desktop server, the credentials to use when connecting, if any, and the +size and color depth of the display. If the protocol supports file transfer, +options for enabling that functionality will be provided as well. + +### VNC + +The VNC protocol is the simplest and first protocol supported by Guacamole. +Although generally not as fast as RDP, many VNC servers are adequate, and VNC +over Guacamole tends to be faster than VNC by itself due to decreased bandwidth +usage. + +VNC support for Guacamole is provided by the libguac-client-vnc library, which +will be installed as part of guacamole-server if the required dependencies are +present during the build. + +:::{note} +In addition to the VNC-specific parameters below, Guacamole's VNC support also +accepts the parameters of several features that Guacamole provides for multiple +protocols: + +* [](disable-clipboard) +* [](common-sftp) +* [](graphical-recording) +* [](wake-on-lan) +::: + +(vnc-network-parameters)= + +#### Network parameters + +With the exception of reverse-mode VNC connections, VNC works by making +outbound network connections to a particular host which runs one or more VNC +servers. Each VNC server is associated with a display number, from which the +appropriate port number is derived. + +`hostname` +: The hostname or IP address of the VNC server Guacamole should connect to. + +`port` +: The port the VNC server is listening on, usually 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. + +`autoretry` +: The number of times to retry connecting before giving up and returning an + error. In the case of a reverse connection, this is the number of times + the connection process is allowed to time out. + +(vnc-authentication)= + +#### Authentication + +The VNC standard defines only password based authentication. Other +authentication mechanisms exist, but are non-standard or proprietary. +Guacamole currently supports both standard password-only based authentication, +as well as username and password authentication. + +`username` +: The username to use when attempting authentication, if any. This parameter + is optional. + +`password` +: The password to use when attempting authentication, if any. This parameter + is optional. + +(vnc-display-settings)= + +#### 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. + +`color-depth` +: The color depth to request, in bits-per-pixel. This parameter is optional. + If specified, this must be either 8, 16, 24, or 32. Regardless of what + value is chosen here, if a particular update uses less than 256 colors, + Guacamole will always send that update as a 256-color PNG. + +`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. This + parameter is optional. + +`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. + +`encodings` +: A space-delimited list of VNC encodings to use. The format of this + parameter is dictated by libvncclient and thus doesn't really follow the + form of other Guacamole parameters. This parameter is optional, and + libguac-client-vnc will use any supported encoding by default. + + Beware that this parameter is intended to be replaced with individual, + encoding-specific parameters in a future release. + +`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. This parameter + is optional. + +`force-lossless` +: Whether this connection should only use lossless compression for graphical + updates. If set to "true", lossy compression will not be used. This + parameter is optional. By default, lossy compression will be used when + heuristics determine that it would likely outperform lossless compression. + +#### VNC Repeater + +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. + +`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. + +`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-reverse-connections)= + +#### Reverse VNC connections + +Guacamole supports "reverse" VNC connections, where the VNC client listens for +an incoming connection from the VNC server. When reverse VNC connections are +used, the VNC client and server switch network roles, but otherwise function as +they normally would. The VNC server still provides the remote display, and the +VNC client still provides all keyboard and mouse input. + +`reverse-connect` +: Whether reverse connection should be used. If set to "true", instead of + connecting to a server at a given hostname and port, guacd will listen on + the given port for inbound connections from a VNC server. + +`listen-timeout` +: If reverse connection is in use, the maximum amount of time to wait for an + inbound connection from a VNC server, in milliseconds. If blank, the + default value is 5000 (five seconds). + +(vnc-audio)= + +#### Audio support (via 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. + +Configuring PulseAudio for network connections requires an additional line +within the PulseAudio configuration file, usually `/etc/pulse/default.pa`: + +``` +load-module module-native-protocol-tcp auth-ip-acl=192.168.1.0/24 auth-anonymous=1 +``` + +This loads the TCP module for PulseAudio, configuring it to accept connections +without authentication and *only* from the `192.168.1.0/24` subnet. You will +want to replace this value with the subnet or IP address from which guacd will +be connecting. It is 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 +``` + +In either case, 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. + +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 {command}`netstat`: + +```console +$ netstat -ln | grep 4713 +tcp 0 0 0.0.0.0:4713 0.0.0.0:* LISTEN +tcp6 0 0 :::4713 :::* LISTEN +$ +``` + +The following parameters are available for configuring the audio support for +VNC: + +`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-servername` +: The name of the PulseAudio server to connect to. This will be the hostname + of the computer providing audio for your connection via PulseAudio, most + likely the same as the value given for the `hostname` parameter. + + 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. + +(vnc-clipboard-encoding)= + +#### Clipboard encoding + +While Guacamole will always use UTF-8 for its own clipboard data, the VNC +standard requires that clipboard data be encoded in ISO 8859-1. As most VNC +servers will not accept data in any other format, Guacamole will translate +between UTF-8 and ISO 8859-1 when exchanging clipboard data with the VNC +server, but this behavior can be overridden with the `clipboard-encoding` +parameter. + +:::{important} +*The only clipboard encoding guaranteed to be supported by VNC servers is ISO +8859-1.* You should only override the clipboard encoding using the +`clipboard-encoding` parameter of you are absolutely positive your VNC server +supports other encodings. +::: + +`clipboard-encoding` +: The encoding to assume for the VNC clipboard. This parameter is optional. + By default, the standard encoding ISO 8859-1 will be used. *Only use this + parameter if you are sure your VNC server supports other encodings beyond + the standard ISO 8859-1.* + + Possible values are: + + ISO8859-1 + : ISO 8859-1 is the clipboard encoding mandated by the VNC standard, and + supports only basic Latin characters. Unless your VNC server specifies + otherwise, this encoding is the only encoding guaranteed to work. + + UTF-8 + : UTF-8 - the most common encoding used for Unicode. Using this encoding + for the VNC clipboard violates the VNC specification, but some servers + do support this. This parameter value should only be used if you know + your VNC server supports this encoding. + + UTF-16 + : UTF-16 - a 16-bit encoding for Unicode which is not as common as UTF-8, + but still widely used. Using this encoding for the VNC clipboard + violates the VNC specification. This parameter value should only be used + if you know your VNC server supports this encoding. + + CP1252 + : Code page 1252 - a Windows-specific encoding for Latin characters which + is mostly a superset of ISO 8859-1, mapping some additional displayable + characters onto what would otherwise be control characters. Using this + encoding for the VNC clipboard violates the VNC specification. This + parameter value should only be used if you know your VNC server supports + this encoding. + +(adding-vnc)= + +#### Adding a VNC connection + +If you are using the default authentication built into Guacamole, and you wish +to grant access to a VNC connection to a particular user, you need to locate +the `<authorize>` section for that user within your `user-mapping.xml`, and add +a section like the following within it: + +```xml +<connection name="Unique Name"> + <protocol>vnc</protocol> + <param name="hostname">localhost</param> + <param name="port">5901</param> +</connection> +``` + +If added exactly as above, a new connection named "`Unique Name`" will be +available to the user associated with the `<authorize>` section containing it. +The connection will use VNC to connect to localhost at port 5901. Naturally, +you will want to change some or all of these values. + +If your VNC server requires a password, or you wish to specify other +configuration parameters (to reduce the color depth, for example), you will +need to add additional `<param>` tags accordingly. + +Other authentication methods will provide documentation describing how to +configure new connections. If the authentication method in use fully implements +the features of Guacamole's authentication API, you will be able to add a new +VNC connection easily and intuitively using the administration interface built +into Guacamole. You will not need to edit configuration files. + +(vnc-servers)= + +#### Which VNC server? + +The choice of VNC server can make a big difference when it comes to +performance, especially over slower networks. While many systems provide VNC +access by default, using this is often not the fastest method. + +(realvnc)= + +##### RealVNC or TigerVNC + +RealVNC, and its derivative TigerVNC, perform quite well. In our testing, they +perform the best with Guacamole. If you are okay with having a desktop that can +only be accessed via VNC, one of these is likely your best choice. Both +optimize window movement and (depending on the application) scrolling, giving a +very responsive user experience. + +##### TightVNC + +TightVNC is widely-available and performs generally as well as RealVNC or +TigerVNC. If you wish to use TightVNC with Guacamole, performance should be +just fine, but we highly recommend disabling its JPEG encoding. This is because +images transmitted to Guacamole are always encoded losslessly as PNG images. +When this operation is performed on a JPEG image, the artifacts present from +JPEG's lossy compression reduce the compressibility of the image for PNG, thus +leading to a slower experience overall than if JPEG was simply not used to +begin with. + +##### x11vnc + +The main benefit of using x11vnc is that it allows you to continue using your +desktop normally, while simultaneously exposing control of your desktop via +VNC. Performance of x11vnc is comparable to RealVNC, TigerVNC, and TightVNC. If +you need to use your desktop locally as well as via VNC, you will likely be +quite happy with x11vnc. + +##### vino + +vino is the VNC server that comes with the Gnome desktop environment, and is +enabled if you enable "desktop sharing" via the system preferences available +within Gnome. If you need to share your local desktop, we recommend using +x11vnc rather vino, as it has proven more performant and feature-complete in +our testing. If you don't need to share a local desktop but simply need an +environment you can access remotely, using a VNC server like RealVNC, TigerVNC, +or TightVNC is a better choice. + +(qemu)= + +##### QEMU or KVM + +QEMU (and thus KVM) expose the displays of virtual machines using VNC. If you +need to see the virtual monitor of your virtual machine, using this VNC +connection is really your only choice. As the VNC server built into QEMU cannot +be aware of higher-level operations like window movement, resizing, or +scrolling, those operations will tend to be sent suboptimally, and will not be +as fast as a VNC server running within the virtual machine. + +If you wish to use a virtual machine for desktop access, we recommend +installing a native VNC server inside the virtual machine after the virtual +machine is set up. This will give a more responsive desktop. + +### RDP + +The RDP protocol is more complicated than VNC and was the second protocol +officially supported by Guacamole. RDP tends to be faster than VNC due to the +use of caching, which Guacamole does take advantage of. + +RDP support for Guacamole is provided by the libguac-client-rdp library, which +will be installed as part of guacamole-server if the required dependencies are +present during the build. + +:::{note} +In addition to the RDP-specific parameters below, Guacamole's RDP support also +accepts the parameters of several features that Guacamole provides for multiple +protocols: + +* [](disable-clipboard) +* [](common-sftp) +* [](graphical-recording) +* [](wake-on-lan) +::: + +(rdp-network-parameters)= + +#### Network parameters + +RDP connections require a hostname or IP address defining the +destination machine. The RDP port is defined to be 3389, and will be +this value in most cases. You only need to specify the RDP port if you +are not using port 3389. + +`hostname` +: The hostname or IP address of the RDP server Guacamole should connect to. + +`port` +: The port the RDP server is listening on. This parameter is optional. 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. + +(rdp-authentication)= + +#### Authentication and security + +RDP provides authentication through the use of a username, password, and +optional domain. All RDP connections are encrypted. + +Most RDP servers will provide a graphical login if the username, password, and +domain parameters are omitted. One notable exception to this is Network Level +Authentication, or NLA, which performs all authentication outside of a desktop +session, and thus in the absence of a graphical interface. + +Servers that require NLA can be handled by Guacamole in one of two ways. The +first is to provide the username and password within the connection +configuration, either via static values or by passing through the Guacamole +credentials with [parameter tokens](parameter-tokens) and [](ldap-auth). +Alternatively, if credentials are not configured within the connection +configuration, Guacamole will attempt to prompt the user for the credentials +interactively, if the versions of both guacd and Guacamole Client in use +support it. If either component does not support prompting and the credentials +are not configured, NLA-based connections will fail. + +`username` +: The username to use to authenticate, if any. This parameter is optional. + +`password` +: The password to use when attempting authentication, if any. This parameter + is optional. + +`domain` +: The domain to use when attempting authentication, if any. This parameter + is optional. + +`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, a security mode is selected based on a negotiation + process which determines what both the client and the server support. + + Possible values are: + + any + : Automatically select the security mode based on the security protocols + supported by both the client and the server. *This is the default*. + + nla + : Network Level Authentication, sometimes also referred to as "hybrid" or + CredSSP (the protocol that drives NLA). This mode uses TLS encryption + and requires the username and password to be given in advance. Unlike + RDP mode, the authentication step is performed before the remote desktop + session actually starts, avoiding the need for the Windows server to + allocate significant resources for users that may not be authorized. + + If the versions of guacd and Guacamole Client in use support prompting + and the username, password, and domain are not specified, the user will + be interactively prompted to enter credentials to complete NLA and + continue the connection. Otherwise, when prompting is not supported and + credentials are not provided, NLA connections will fail. + + nla-ext + : Extended Network Level Authentication. This mode is identical to NLA + except that an additional "[Early User Authorization + Result](https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-rdpbcgr/d0e560a3-25cb-4563-8bdc-6c4cc625bbfc)" + is required to be sent from the server to the client immediately after the + NLA handshake is completed. + + tls + : RDP authentication and encryption implemented via TLS (Transport Layer + Security). Also referred to as RDSTLS, the TLS security mode is + primarily used in load balanced configurations where the initial RDP + server may redirect the connection to a different RDP server. + + 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](rdp-preconnection-pdu). + + rdp + : Legacy RDP encryption. This mode is generally only used for older + Windows servers or in cases where a standard Windows login screen is + desired. Newer versions of Windows have this mode disabled by default + and will only accept NLA unless explicitly configured otherwise. + +`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). + +`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. + +(rdp-session-settings)= + +#### Session 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 what they *do* ("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 the Guacamole +team by [opening an issue in +JIRA](https://issues.apache.org/jira/browse/GUACAMOLE). + + +`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. + +`console` +: If set to "true", you will be connected to the console (admin) session of + the RDP server. + +`initial-program` +: The full path to the program to run immediately upon connecting. This + parameter is optional. + +`server-layout` +: The server-side keyboard layout. 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, + however, 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. + + Possible values are generally in the format + {samp}`{LANGUAGE}-{REGION}-{VARIANT}`, where `LANGUAGE` is the standard + two-letter language code for the primary language associated with the + layout, `REGION` is a standard representation of the location that the + keyboard is used (the two-letter country code, when possible), and + `VARIANT` is the specific keyboard layout variant (such as "qwerty", + "qwertz", or "azerty"): + + | Keyboard layout | Parameter value | + | ------------------------------ | ---------------------- | + | Brazilian (Portuguese) | `pt-br-qwerty` | + | English (UK) | `en-gb-qwerty` | + | English (US) | `en-us-qwerty` | + | French | `fr-fr-azerty` | + | French (Belgian) | `fr-be-azerty` | + | French (Swiss) | `fr-ch-qwertz` | + | German | `de-de-qwertz` | + | German (Swiss) | `de-ch-qwertz` | + | Hungarian | `hu-hu-qwertz` | + | Italian | `it-it-qwerty` | + | Japanese | `ja-jp-qwerty` | + | Spanish | `es-es-qwerty` | + | Spanish (Latin American) | `es-latam-qwerty` | + | Swedish | `sv-se-qwerty` | + | Turkish-Q | `tr-tr-qwerty` | + + If you server's keyboard layout is not yet supported, and it is not possible + to set your server to use a supported layout, the `failsafe` layout may be used + to force Unicode events to be used for all input, however beware that doing so + may prevent keyboard shortcuts from working as expected. + +`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. + + The timezone is detected and will be passed to the server during the + handshake phase of the connection, and may used by protocols, like RDP, + that support it. This parameter can be used to override the value detected + and passed during the handshake, or can be used in situations where guacd + does not support passing the timezone parameter during the handshake phase + (guacd versions prior to 1.3.0). + + 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, for + example, xrdp, may not implement this feature at all. Consult the + documentation for the RDP server to determine whether or not this feature + is supported. + +(rdp-display-settings)= + +#### Display settings + +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 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 RDP server. + +`color-depth` +: The color depth to request, in bits-per-pixel. This parameter is optional. + If specified, this must be either 8, 16, or 24. Regardless of what value + is chosen here, if a particular update uses less than 256 colors, + Guacamole will always send that update as a 256-color PNG. + +`width` +: The width of the display to request, in pixels. This parameter is + optional. If this value is not specified, the width of the connecting + client display will be used instead. + +`height` +: The height of the display to request, in pixels. This parameter is + optional. If this value is not specified, the height of the connecting + client display will be used instead. + +`dpi` +: The desired effective resolution of the client display, in DPI. This + parameter is optional. 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. + +`resize-method` +: The method to use to update the RDP server when the width or height of the + client display changes. This parameter is optional. 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. + + Possible values are: + + display-update + : Uses the "Display Update" channel added with RDP 8.1 to signal the + server when the client display size has changed. + + reconnect + : Automatically disconnects the RDP session when the client display size + has changed, and reconnects with the new size. + +`force-lossless` +: Whether this connection should only use lossless compression for graphical + updates. If set to "true", lossy compression will not be used. This + parameter is optional. By default, lossy compression will be used when + heuristics determine that it would likely outperform lossless compression. + +(rdp-device-redirection)= + +#### Device redirection + +Device redirection refers to the use of non-display devices over RDP. +Guacamole's RDP support currently allows redirection of audio, printing, and +disk access, some of which require additional configuration in order to +function properly. + +Audio redirection will be enabled by default. If Guacamole was correctly +installed, and audio redirection is supported by your RDP server, sound should +play within remote connections without manual intervention. + +Printing requires GhostScript to be installed on the Guacamole server, and +allows users to print arbitrary documents directly to PDF. When documents are +printed to the redirected printer, the user will receive a PDF of that document +within their web browser. + +Guacamole provides support for file transfer over RDP by emulating a virtual +disk drive. This drive will persist on the Guacamole server, confined within +the drive path specified. If drive redirection is enabled on a Guacamole RDP +connection, users will be able to upload and download files as described in +[](using-guacamole). + +`disable-audio` +: Audio is enabled by default in both the client and in libguac-client-rdp. + If you are concerned about bandwidth usage, or sound is causing problems, + you can explicitly disable sound by setting this parameter to "true". + +`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` +: Printing is disabled by default, but with printing enabled, RDP users can + print to a virtual printer that sends a PDF containing the document + printed to the Guacamole client. Enable printing by setting this parameter + to "true". + + *Printing support requires GhostScript to be installed.* If guacd cannot + find the `gs` executable when printing, the print attempt will fail. + +`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, for example, the + Devices and Printers control panel. + + If printer redirection is not enabled, this option has no effect. + +`enable-drive` +: File transfer is disabled by default, but with file transfer enabled, RDP + users can transfer files to and from a virtual drive which persists on the + Guacamole server. Enable file transfer support by setting this parameter + to "true". + + Files will be stored in the directory specified by the "`drive-path`" + parameter, which is required if file transfer is enabled. + +`disable-download` +: If set to true downloads from the remote server to client (browser) will + be disabled. This includes both downloads down via the hidden Guacamole + menu, as well as using the special "Download" folder presented to the + remote server. The default is false, which means that downloads will be + allowed. + + If file transfer is not enabled, this parameter is ignored. + +`disable-upload` +: If set to true, uploads from the client (browser) to the remote server + location will be disabled. The default is false, which means uploads will + be allowed if file transfer is enabled. + + If file transfer is not enabled, this parameter is ignored. + +`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 (for example, "Guacamole on Guacamole RDP"), and is + also the name of the share when accessing the special `\\tsclient` network + location. + + If file transfer is not enabled, this parameter is ignored. + +`drive-path` +: The directory on the Guacamole server in which transferred files should be + stored. This directory must be accessible by guacd and both readable and + writable by the user that runs guacd. *This parameter does not refer to a + directory on the RDP server.* + + If file transfer is not enabled, this parameter is ignored. + +`create-drive-path` +: If set to "true", and file transfer is enabled, the directory specified by + the `drive-path` parameter will automatically be created if it does not + yet exist. Only the final directory in the path will be created - if other + directories earlier in the path do not exist, automatic creation will + fail, and an error will be logged. + + By default, the directory specified by the `drive-path` parameter will not + automatically be created, and attempts to transfer files to a non-existent + directory will be logged as errors. + + If file transfer is not enabled, this parameter is ignored. + +`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". + +`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. + +(rdp-preconnection-pdu)= + +#### Preconnection PDU (Hyper-V / VMConnect) + +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](https://msdn.microsoft.com/en-us/library/cc242359.aspx) 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 within the `preconnection-blob` parameter. This value can be +determined using PowerShell: + +```ps1con +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 requires +different parameters for authentication 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 "`username`" and "`password`" appropriately, and set + "`security`" 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, set "`ignore-cert`" to "`true`". Hyper-V may use a self-signed + certificate. + +`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 optional, and is only required if the RDP server + is documented as requiring it. *If using Hyper-V, this should be left + blank.* + +`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 optional, and 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-gateway)= + +#### Remote desktop gateway + +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. + +`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.* + +`gateway-port` +: The port of the remote desktop gateway that should be used as an + intermediary for the remote desktop connection. By default, this will be + "443". + +`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. + +`gateway-password` +: The password to provide when authenticating with the remote desktop + gateway, if a gateway is being used. + +`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. + +(rdp-connection-broker)= + +#### Load balancing and RDP connection brokers + +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. + +`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.* + +(rdp-perf-flags)= + +#### Performance 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. + +`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` +: If set to "true", enables use of theming of windows and controls. By + default, theming within RDP sessions is disabled. + +`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` +: 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` +: 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` +: If set to "true", menu open and close animations will be allowed. Menu + animations are disabled by default. + +`disable-bitmap-caching` +: In certain situations, particularly with RDP server implementations with + known bugs, it is necessary to disable RDP's built-in bitmap caching + functionality. This parameter allows that to be controlled in a Guacamole + session. If set to "true" the RDP bitmap cache will not be used. + +`disable-offscreen-caching` +: RDP normally maintains caches of regions of the screen that are current + not visible in the client in order to accelerate retrieval of those + regions when they come into view. This parameter, when set to "true," will + disable caching of those regions. This is usually only useful when dealing + with known bugs in RDP server implementations and should remain enabled in + most circumstances. + +`disable-glyph-caching` +: In addition to screen regions, RDP maintains caches of frequently used + symbols or fonts, collectively known as "glyphs." As with bitmap and + offscreen caching, certain known bugs in RDP implementations can cause + performance issues with this enabled, and setting this parameter to "true" + will disable that glyph caching in the RDP session. Review comment: Sure - that sounds like a good idea. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org
