Chapter 5. Configuring Guacamole
file:///home/mjumper/guacamole/guacamole-manu...
Chapter 5. 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. 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.
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 of 21
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
file:///home/mjumper/guacamole/guacamole-manu...
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 three standard properties that
are always available for use:
guacd-host
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.
Example 5.1. Example guacamole.properties
# Hostname and port of guacamole proxy
guacd-hostname: localhost
guacd-port:
4822
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.
Guacamole logs messages using a logging framework called Logback 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:
2 of 21
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
file:///home/mjumper/guacamole/guacamole-manu...
<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 is provided on the Logback project's web site.
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, simply do not install and 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.xml
The default authentication provider used by Guacamole reads all username, password, and configuration information
from a file called the "user mapping". By default, Guacamole will look for this file at GUACAMOLE_HOME/usermapping.xml, but this can be overridden by specifying the location with the user-mapping property within
guacamole.properties:
user-mapping: /path/to/user-mapping.xml
An example of a user mapping 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
3 of 21
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
file:///home/mjumper/guacamole/guacamole-manu...
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.
4 of 21
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
file:///home/mjumper/guacamole/guacamole-manu...
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 guacamoleserver if the required dependencies are present during the build.
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.
Parameter name
Description
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.
Authentication
The VNC standard defines only password based authentication. Other authentication mechanisms exist, but are
non-standard or proprietary. Guacamole supports only the password method.
Parameter name
Description
password
The password to use when attempting authentication, if any. This parameter is
optional.
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
5 of 21
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
file:///home/mjumper/guacamole/guacamole-manu...
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.
Parameter name
Description
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, encodingspecific 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.
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.
Parameter name
Description
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.
Reverse VNC connections
6 of 21
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
file:///home/mjumper/guacamole/guacamole-manu...
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.
Parameter name
Description
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).
Audio support
VNC does not provide any support for audio, but Guacamole's VNC support can provide audio support through a
secondary network connection to a PulseAudio server running on the same machine as the VNC server. Guacamole
will thus combine two separate streams (one graphical stream and one audio stream) from two distinct network
sources into a single stream of Guacamole protocol data.
The following parameters are available for configuring the experimental audio support for VNC:
Parameter name
Description
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.
enable-audio
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.
Important
Audio support within VNC is experimental. Please report any problems encountered while using the
experimental audio support for VNC to the Guacamole team by opening an issue in JIRA.
7 of 21
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
file:///home/mjumper/guacamole/guacamole-manu...
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'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.
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
8 of 21
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
file:///home/mjumper/guacamole/guacamole-manu...
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 guacamoleserver if the required dependencies are present during the build.
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.
Parameter name
Description
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.
Authentication and security
RDP provides authentication through the use of a username, password, and optional domain.
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. If your server requires NLA, you will need to
manually choose this as your security mode, and you must provide a username and password.
All RDP connections are encrypted. Higher-grade encryption is available in the form of TLS, another possible security
mode.
9 of 21
Parameter name
Description
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, the
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
Parameter name
file:///home/mjumper/guacamole/guacamole-manu...
Description
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
disable-auth
If set to "true", the certificate returned by the server will be ignored, even if that
certificate cannot be validated. This is useful if you universally trust the server and
your connection to the server, and you know that the server's certificate cannot be
validated (for example, if it is self-signed).
If 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.
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.
10 of 21
Parameter name
Description
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
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
Parameter name
file:///home/mjumper/guacamole/guacamole-manu...
Description
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.
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
server-layout
French keyboard (azerty)
it-it-qwerty
Italian keyboard
sv-se-qwerty
Swedish keyboard
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.
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
11 of 21
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
file:///home/mjumper/guacamole/guacamole-manu...
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.
Parameter name
Description
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.
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 SSH
connection, users will be able to upload and download files as described in Chapter 9, Using Guacamole.
Parameter name
Description
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-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.
12 of 21
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
Parameter name
enable-drive
file:///home/mjumper/guacamole/guacamole-manu...
Description
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.
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.
console-audio
static-channels
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".
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.
RemoteApp
Recent versions of Windows provide a feature called RemoteApp which allows individual applications to be used over
RDP, without providing access to the full desktop environment. If your RDP server has this feature enabled and
configured, you can configure Guacamole connections to use those individual applications.
Parameter name
Description
Specifies the RemoteApp to start on the remote desktop. If supported by your remote
desktop server, this application, and only this application, will be visible to the user.
remote-app
13 of 21
Windows requires a special notation for the names of remote applications. The
names of remote applications must be prefixed with two vertical bars. For example, if
you have created a remote application on your server for notepad.exe and have
assigned it the name "notepad", you would set this parameter to: "||notepad".
remote-app-dir
The working directory, if any, for the remote application. This parameter has no effect
if RemoteApp is not in use.
remote-app-args
The command-line arguments, if any, for the remote application. This parameter has
no effect if RemoteApp is not in use.
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
file:///home/mjumper/guacamole/guacamole-manu...
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'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.
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 will be installed as part of guacamoleserver if the required dependencies are present during the build.
Network parameters
SSH connections require a hostname or IP address defining the destination machine. SSH is standardized to use port
22 and this will be the proper value in most cases. You only need to specify the SSH port if you are not using the
standard port.
Parameter name
Description
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.
Authentication
SSH provides authentication through passwords and public key authentication.
For Guacamole to use public key authentication, it must have access to your private key and, if applicable, its
passphrase. If the private key requires a passphrase, but no passphrase is provided, you will be prompted for the
passphrase upon connecting.
If no private key is provided, Guacamole will attempt to authenticate using a password, reading that password from the
14 of 21
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
file:///home/mjumper/guacamole/guacamole-manu...
connection parameters, if provided, or by prompting the user directly.
Parameter name
Description
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.
private-key
The entire contents of the private key to use for public key authentication. If this
parameter is not specified, public key authentication will not be used. The private key
must be in OpenSSH format, as would be generated by the OpenSSH ssh-keygen
utility.
passphrase
The passphrase to use to decrypt the private key for use in public key authentication.
This parameter is not needed if the private key does not require a passphrase. If the
private key requires a passphrase, but this parameter is not provided, the user will be
prompted for the passphrase upon connecting.
Display settings
Guacamole's SSH support provides a display, but not in the same sense as a remote desktop protocol like VNC or
RDP. The display is a terminal emulator, and thus provides options for configuring the font used and its size. In this
case, the chosen font must be installed on the server, as it is the server that will handle rendering of characters to the
terminal display, not the client.
Parameter name
Description
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.
SFTP
Guacamole provides support for file transfer over SSH using SFTP, the file transfer protocol built into most SSH
servers. If SFTP is enabled on a Guacamole SSH connection, users will be able to upload and download files as
described in Chapter 9, Using Guacamole.
15 of 21
Parameter name
Description
enable-sftp
Whether file transfer should be enabled. If set to "true", the user will be allowed to
upload or download files from the SSH server using SFTP. Guacamole includes the
guacctl utility which controls file downloads and uploads when run on the SSH
server by the user over the SSH connection.
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
file:///home/mjumper/guacamole/guacamole-manu...
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.
Telnet
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 will be installed as part of
guacamole-server if the required dependencies are present during the build.
Network parameters
Telnet connections require a hostname or IP address defining the destination machine. Telnet is standardized to use
port 23 and this will be the proper value in most cases. You only need to specify the telnet port if you are not using the
standard port.
Parameter name
Description
hostname
The hostname or IP address of the telnet server Guacamole should connect to.
port
The port the telnet server is listening on, usually 23. This parameter is optional. If this
is not specified, the default of 23 will be used.
Authentication
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
16 of 21
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
file:///home/mjumper/guacamole/guacamole-manu...
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).
Parameter name
Description
username
The username to use to authenticate, if any. This parameter is optional. If not
specified, or not supported by the telnet server, the login process on the telnet server
will prompt you for your credentials. For this to work, your telnet server must support
the NEW-ENVIRON option, and the telnet login process must pay attention to the
USER environment variable. Most telnet servers satisfy this criteria.
password
The password to use when attempting authentication, if any. This parameter is
optional. If specified, your password will be typed on your behalf when the password
prompt is detected.
username-regex
The regular expression to use when waiting for the username prompt. This
parameter is optional. If not specified, a reasonable default built into Guacamole will
be used. The regular expression must be written in the POSIX ERE dialect (the
dialect typically used by egrep).
password-regex
The regular expression to use when waiting for the password prompt. This parameter
is optional. If not specified, a reasonable default built into Guacamole will be used.
The regular expression must be written in the POSIX ERE dialect (the dialect
typically used by egrep).
Display settings
Guacamole's telnet support provides a display, but not in the same sense as a remote desktop protocol like VNC or
RDP. The display is a terminal emulator, and thus provides options for configuring the font used and its size. In this
case, the chosen font must be installed on the server, as it is the server that will handle rendering of characters to the
terminal display, not the client.
17 of 21
Parameter name
Description
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.
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
file:///home/mjumper/guacamole/guacamole-manu...
Adding a telnet connection
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.
Parameter tokens
The values of connection parameters can contain "tokens" which will be replaced by Guacamole when used. These
tokens allow the values of connection parameters to vary dynamically by the user using the connection, and provide a
simple means of forwarding authentication information without storing that information in the connection configuration
itself, so long as the remote desktop connection uses the same credentials as Guacamole.
Each token is of the form ${ TOKEN_NAME }, where TOKEN_NAME is some descriptive name for the value the token
represents. Tokens with no corresponding value will never be replaced, but should you need such text within your
connection parameters, and wish to guarantee that this text will not be replaced with a token value, you can escape the
token by adding an additional leading "$", as in "$${TOKEN_NAME}".
${GUAC_USERNAME}
The username of the current Guacamole user. When a user accesses this connection, this token will be
dynamically replaced with the username they provided when logging in to Guacamole.
${GUAC_PASSWORD}
The password of the current Guacamole user. When a user accesses this connection, this token will be
dynamically replaced with the password they used when logging in to Guacamole.
Note that these tokens are replaced dynamically each time a connection is used. If two different users access the same
connection at the same time, both users will be connected independently of each other using different sets of
connection parameters.
Configuring guacd
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
18 of 21
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
file:///home/mjumper/guacamole/guacamole-manu...
log_level = info
[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:
1. If the value contains no special characters, just include it as-is.
2. If the value contains any special characters (whitespace, newlines, #, \, or "), enclose the entire value within
double quotes.
19 of 21
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
file:///home/mjumper/guacamole/guacamole-manu...
3. If the value is enclosed within double quotes, escape newlines, \, and " with a backslash.
Table 5.1. guacd.conf parameters
Section
daemon
daemon
Name
Description
pid_file
The name of the file in which the PID of the main guacd
process should be written. This is mainly needed for
startup scripts, which need to monitor the state of guacd,
killing it if necessary. If this parameter is specified, the
user running guacd must have sufficient permissions to
create or modify the specified file, or startup will fail.
log_level
The maximum level at which guacd will log messages to
syslog and, if running in the foreground, the console. If
omitted, the default level of info will be used.
Legal values are debug, info, warning, and error.
server
bind_host
The host that guacd should bind to when listening for
connections. If unspecified, guacd will bind to localhost,
and only connections from within the server hosting guacd
will succeed.
server
bind_port
The port that guacd should bind to when listening for
connections. If unspecified, port 4822 will be used.
server_certificate
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.properties to use SSL as well.
server_key
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.properties to use SSL as well.
ssl
ssl
You can also affect the configuration of guacd with command-line options. If given, these options take precendence
over the system-wide configuration file:
-b HOST
Changes the host or address that guacd listens on.
This corresponds to the bind_host parameter within the server section of guacd.conf.
-l PORT
20 of 21
06/09/2015 08:12 PM
Chapter 5. Configuring Guacamole
file:///home/mjumper/guacamole/guacamole-manu...
Changes the port that guacd listens on (the default is port 4822).
This corresponds to the bind_port parameter within the server section of guacd.conf.
-p PIDFILE
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_file parameter within the daemon section of guacd.conf.
-L LEVEL
Sets the maximum level at which guacd will log messages to syslog and, if running in the foreground, the
console. Legal values are debug, info, warning, and error. The default value is info.
This corresponds to the log_level parameter within the daemon section of guacd.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:
-C CERTIFICATE
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.properties to use SSL as well.
This corresponds to the server_certificate parameter within the ssl section of guacd.conf.
-K KEY
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.properties to use SSL as well.
This corresponds to the server_key parameter within the ssl section of guacd.conf.
21 of 21
06/09/2015 08:12 PM