Table of Contents
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 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:
-
The directory specified within the system property guacamole.home.
-
The directory specified within the environment variable
GUACAMOLE_HOME. -
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.
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:
-
Within
GUACAMOLE_HOME, as defined above. -
The classpath of the servlet container.
At the bare minimum, the guacamole.properties file contains at
least three basic properties, required in all deployments of Guacamole:
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.
auth-provider-
The authentication provider to use when authenticating. Normally, this will be set to
BasicFileAuthenticationProviderwhich is the default authentication provider provided with Guacamole. No extensions are needed if you use the default authentication provider.
If you need custom authentication or wish to enable optional features of Guacamole, such as WebSocket or HTTP Basic authentication support, you will need to specify additional properties:
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.
lib-directory-
The directory to load extensions to Guacamole from. If you wish to use a custom authentication provider or custom hooks, the
.jarfile and all dependencies must be placed in the directory specified here. On most systems,/var/lib/guacamole/classpathis an appropriate choice.Note that this property is only needed if you are using an extension.
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
.jarfiles placed within the directory specified by the lib-directory property. enable-websocket-
trueif WebSocket support should be enabled,false(or simply leave the property out) otherwise.WebSocket is supported in Guacamole for Tomcat 7 and Jetty 8. Note that if Tomcat is used, it must be version 7.0.37 or newer. Older versions of Tomcat are only supported for HTTP. Guacamole does not yet support Tomcat 8 for WebSocket.
enable-http-auth-
trueif HTTP Basic authentication support should be enabled,false(or simply leave the property out) otherwise. This will not cause Guacamole to require HTTP Basic authentication; it simply tells Guacamole to inspect the HTTP "Authorization" header when authenticating users, if present.When HTTP Basic authentication is in use, the web browser submits the username/password pair with each HTTP request in an "Authorization" header. If you have an upstream authentication system or proxy which uses HTTP Basic authentication, setting this property causes Guacamole to read and use these credentials if the username and password are not given through other means.
Example 3.1. Minimal guacamole.properties
# Hostname and port of guacamole proxy
guacd-hostname: localhost
guacd-port: 4822
# Authentication provider class
auth-provider: net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider
# Properties used by BasicFileAuthenticationProvider
basic-user-mapping: /etc/guacamole/user-mapping.xml
Yes, if you can.
WebSocket has performance benefits and a much lower overhead on the client, so
enabling WebSocket is beneficial if you know your servlet container supports it. In
the event that Guacamole cannot connect using WebSocket, it will immediately and
transparently fall back to using HTTP. If things are regularly not working as
expected, and you suspect it's the WebSocket support, you can always disable it by
editing guacamole.properties.
When eventually WebSocket is widely supported across servlet containers and network hardware, it will likely be enabled by default.
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.
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.
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.
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.
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
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'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.
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, 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 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.
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 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 (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.
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
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's authentication API, 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.
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 libssh2 and libssl.
Table 3.3. SSH configuration parameters
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.
Telnet is a text protocol and provides similar functionality to SSH. By nature, it is not encrypted, and does not provide support for file transfer. As far as graphics are concerned, Guacamole's telnet support works in the same manner as SSH: it emulates a terminal on the server side which renders to the Guacamole client's display.
Telnet support for Guacamole is provided by the libguac-client-telnet library, which depends on libtelnet.
Table 3.4. Telnet configuration parameters
If you are using the default authentication built into Guacamole, and you wish to
grant access to a telnet 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>telnet</protocol> <param name="hostname">localhost</param> <param name="port">23</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
telnet to connect to localhost at port
23. Naturally, you will want to change some or all of
these values.
As telnet is inherently insecure compared to SSH, you should use SSH instead wherever possible. If Guacamole is set up to use HTTPS then communication with the Guacamole client will be encrypted, but communication between guacd and the telnet server will still be unencrypted. You should not use telnet unless the network between guacd and the telnet server is trusted.
Telnet does not actually provide any standard means of authentication. Authentication over telnet depends entirely on the login process running on the server and is interactive. To cope with this, Guacamole provides non-standard mechanisms for automatically passing the username and entering password. Whether these mechanisms work depends on specific login process used by your telnet server.
The de-facto method for passing the username automatically via telnet is to submit
it via the USER environment variable, sent using the
NEW-ENVIRON option. This is the mechanism used by most
telnet clients, typically via the -l command-line option.
Passwords cannot typically be sent automatically - at least not as reliably as the
username. There is no PASSWORD environment variable (this would
actually be a horrible idea) nor any similar mechanism for passing the password to
the telnet login process, and most telnet clients provide no built-in support for
automatically entering the password. The best that can be done is to heuristically
detect the password prompt, and type the password on behalf of the user when the
prompt appears. The prescribed method for doing this with a traditional command-line
telnet is to use a utility like expect. Guacamole provides
similar functionality by searching for the password prompt with a regular
expression.
If Guacamole receives a line of text which matches the regular expression, the password is automatically sent. If no such line is ever received, the password is not sent, and the user must type the password manually. Pressing any key during this process cancels the heuristic password prompt detection.
If the password prompt is not being detected properly, you can try using your own
regular expression by specifying it within the password-regex
parameter. The regular expression must be written in the POSIX ERE dialect (the
dialect typically used by egrep).
guacd is configured with a configuration file called
guacd.conf, by default located in
/etc/guacamole. This file follows a simple, INI-like
format:
# # guacd configuration file # [daemon] pid_file = /var/run/guacd.pid [server] bind_host = localhost bind_port = 4822 # # The following parameters are valid only if # guacd was built with SSL support. # [ssl] server_certificate = /etc/ssl/certs/guacd.crt server_key = /etc/ssl/private/guacd.key
Configuration options are given as parameter/value pairs, where the name of the
parameter is specified on the left side of an "=", and the value is
specified on the right. Each parameter must occur within a proper section, indicated by
a section name within brackets. The names of these sections are important; it is the
pairing of a section name with a parameter that constitutes the fully-qualified
parameter being set.
For the sake of documentation and readability, comments can be added anywhere within
guacd.conf using "#" symbols. All text following a "#" until
end-of-line will be ignored.
If you need to include special characters within the value of a parameter, such as whitespace or any of the above symbols, you can do so by placing the parameter within double quotes:
[ssl] # Whitespace is legal within double quotes ... server_certificate = "/etc/ssl/my certs/guacd.crt" # ... as are other special symbols server_key = "/etc/ssl/#private/guacd.key"
Note that even within double quotes, some characters still have special meaning, such as the double quote itself or newline characters. If you need to include these, they must be "escaped" with a backslash:
# Parameter value containing a double quote parameter = "some\"value" # Parameter value containing newline characters parameter2 = "line1\ line2\ line3" # Parameter value containing backslashes parameter3 = "c:\\windows\\path\\to\\file.txt"
Don't worry too much about the more complex formatting examples - they are only rarely necessary, and guacd will complain with parsing errors if the configuration file is somehow invalid. To ensure parameter values are entered correctly, just follow the following guidelines:
-
If the value contains no special characters, just include it as-is.
-
If the value contains any special characters (whitespace, newlines,
#,\, or"), enclose the entire value within double quotes. -
If the value is enclosed within double quotes, escape newlines,
\, and"with a backslash.
Table 3.5. guacd.conf parameters
You can also affect the configuration of guacd with command-line options. If given, these options take precendence over the system-wide configuration file:
-bHOST-
Changes the host or address that guacd listens on.
This corresponds to the
bind_hostparameter within theserversection ofguacd.conf. -lPORT-
Changes the port that guacd listens on (the default is port 4822).
This corresponds to the
bind_portparameter within theserversection ofguacd.conf. -pPIDFILE-
Causes guacd to write the PID of the daemon process to the specified file. This is useful for init scripts and is used by the provided init script.
This corresponds to the
pid_fileparameter within thedaemonsection ofguacd.conf. -f-
Causes guacd to run in the foreground, rather than automatically forking into the background.
If guacd was built with support for SSL, data sent via the Guacamole protocol can be encrypted with SSL if an SSL certificate and private key are given with the following options:
-CCERTIFICATE-
The filename of the certificate to use for SSL encryption of the Guacamole protocol. If this option is specified, SSL encryption will be enabled, and the Guacamole web application will need to be configured within
guacamole.propertiesto use SSL as well.This corresponds to the
server_certificateparameter within thesslsection ofguacd.conf. -KKEY-
The filename of the private key to use for SSL encryption of the Guacamole protocol. If this option is specified, SSL encryption will be enabled, and the Guacamole web application will need to be configured within
guacamole.propertiesto use SSL as well.This corresponds to the
server_keyparameter within thesslsection ofguacd.conf.