Chapter 3. Configuring Guacamole

After installing Guacamole, it will be minimally configured to use the default authentication, which reads all users and connections from a single, monolithic user-mapping.xml file. You can modify this configuration if you need to use a different authentication module (such as the MySQL authentication, which is discussed in a separate chapter) or if you need to veer from the defaults.

Guacamole's configuration 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 reads files from its own configuration directory by default, resorting to the classpath only when this directory cannot be found. When locating this directory, Guacamole will try, in order:

  1. The directory specified within the system property guacamole.home.

  2. The directory specified within the environment variable GUACAMOLE_HOME.

  3. The directory .guacamole, located within the home directory of the user running the servlet container.

This directory will be referred to as GUACAMOLE_HOME elsewhere in the documentation.

Guacamole uses GUACAMOLE_HOME as the primary search location for configuration file like guacamole.properties.

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.

At the bare minimum, the guacamole.properties file provides five basic properties:

guacd-host

The host the Guacamole proxy daemon (guacd) is listening on. This is most likely localhost.

guacd-port

The port the Guacamole proxy daemon (guacd) is listening on. This is port 4822 by default.

guacd-ssl

If set to "true", requires SSL/TLS encryption between the web application and guacd. This property is not required. 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.

auth-provider

The authentication provider to use when authenticating. Normally, this will be set to BasicFileAuthenticationProvider which is the default authentication provider provided with Guacamole.

lib-directory

The directory to load extensions to Guacamole from. If you wish to use a custom authentication provider or custom hooks, the .jar file and all dependencies must be placed in the directory specified here.

event-listeners

A comma-delimited list of event listeners which should be loaded and installed such that they are informed of Guacamole-related events. These classes must be in the classpath, preferably by having their corresponding .jar files placed within the directory specified by the lib-directory property.

Example 3.1. Minimal guacamole.properties

# Hostname and port of guacamole proxy
guacd-hostname: localhost
guacd-port:     4822

# Location to read extra .jar's from
lib-directory:  /var/lib/guacamole/classpath

# Authentication provider class
auth-provider: net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider

# Properties used by BasicFileAuthenticationProvider
basic-user-mapping: /etc/guacamole/user-mapping.xml

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. If you wish to use this authentication mechanism, you must ensure the auth-provider property is set to the fully-qualified name of BasicFileAuthenticationProvider[1]This is the case within the example guacamole.properties file shown above, and in the guacamole.properties file included with Guacamole. Unless you have already tried another authentication module, you will not need to edit this value yourself if you are using the configuration files that come with Guacamole.

There are other authentication modules available. The Guacamole project now provides a MySQL-backed authentication module with extra features (like 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.xml

The default authentication provider used by Guacamole reads all username, password, and configuration information from a file called the "user mapping" (typically named user-mapping.xml). An example of this file is included with Guacamole, and looks something like this:

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

Adding users

When using BasicFileAuthenticationProvider, 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:

<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:

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

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.

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, installed by default.

Table 3.1. VNC configuration parameters

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

password

The password to use when attempting authentication, if any. This parameter is optional.

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.

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.

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.

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.

dest-hostThe 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-portThe 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.
enable-audio

If set to "true", experimental sound support will be enabled. VNC does not support sound, but Guacamole's VNC support can include sound using PulseAudio.

Most Linux systems provide audio through a service called PulseAudio. This service is capable of communicating over the network. 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.

Beware that you must disable authentication within PulseAudio in order to allow Guacamole to connect, as Guacamole does not yet support this. The amount of latency you will see depends largely on the network and how PulseAudio is configured.

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.


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:

<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 0.8.0, 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.

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 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 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 depends on a recent version of FreeRDP (version 1.0 or higher). If your distribution does not have a recent enough version of FreeRDP, the Guacamole project will not build a libguac-client-rdp package for you. You will need to build and install a recent version of FreeRDP, and then build and install libguac-client-rdp from source.

Table 3.2. RDP configuration parameters

NameDescription
hostname

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

port

The port the RDP server is listening on, usually 3389. This parameter is optional. If this is not specified, the default of 3389 will be used.

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.

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.

disable-audioAudio 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-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.

console

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

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

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:

en-us-qwerty

English (US) keyboard

de-de-qwertz

German keyboard (qwertz)

fr-fr-azerty

French keyboard (azerty)

failsafe

Unknown keyboard - this option sends only Unicode events and should work for any keyboard, though not necessarily all RDP servers or applications.

If your server's keyboard layout is not yet supported, this option should work in the meantime.

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, the server is allowed to control what type of security is used.

Possible values are:

rdp

Standard RDP encryption. This mode should be supported by all RDP servers.

nla

Network Level Authentication. This mode requires the username and password, and performs an authentication step before the remote desktop session actually starts. If the username and password are not given, the connection cannot be made.

tls

TLS encryption. TLS (Transport Layer Security) is the successor to SSL.

any

Allow the server to choose the type of security. This is the default.

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.


Adding an RDP connection

If you are using the default authentication built into Guacamole, and you wish to grant access to a RDP 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:

<connection name="Unique Name">
    <protocol>rdp</protocol>
    <param name="hostname">localhost</param>
    <param name="port">3389</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 RDP to connect to localhost at port 3389. Naturally, you will want to change some or all of these values.

If you want to login automatically rather than receive a login prompt upon connecting, you can specify a username and password with additional <param> tags. Other options are available for controlling the color depth, size of the screen, etc.

Other authentication methods will provide documentation describing how to configure new connections. If the authentication method in use fully implements the features of Guacamole 0.8.0, you will be able to add a new RDP connection easily and intuitively using the administration interface built into Guacamole. You will not need to edit configuration files.

SSH

Unlike VNC or RDP, SSH is a text protocol. Its implementation in Guacamole is actually a combination of a terminal emulator and SSH client, because the SSH protocol isn't inherently graphical. Guacamole's SSH support emulates a terminal on the server side, and draws the screen of this terminal remotely on the client.

SSH support for Guacamole is provided by the libguac-client-ssh library, which depends on libssh.

Table 3.3. SSH configuration parameters

NameDescription
hostname

The hostname or IP address of the SSH server Guacamole should connect to.

port

The port the SSH server is listening on, usually 22. This parameter is optional. If this is not specified, the default of 22 will be used.

username

The username to use to authenticate, if any. This parameter is optional. If not specified, you will be prompted for the username upon connecting.

password

The password to use when attempting authentication, if any. This parameter is optional. If not specified, you will be prompted for your password upon connecting.

font-name

The name of the font to use. This parameter is optional. If not specified, the default of "monospace" will be used instead.

font-size

The size of the font to use, in points. This parameter is optional. If not specified, the default of 12 will be used instead.


Adding an SSH connection

If you are using the default authentication built into Guacamole, and you wish to grant access to a SSH 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:

<connection name="Unique Name">
    <protocol>ssh</protocol>
    <param name="hostname">localhost</param>
    <param name="port">22</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 SSH to connect to localhost at port 22. Naturally, you will want to change some or all of these values.

If you want to login automatically rather than receive a login prompt upon connecting, you can specify a username and password with additional <param> tags. Other options are available for controlling the font.

Other authentication methods will provide documentation describing how to configure new connections.



[1] net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider