ra6r2015 Chapter 3. Coniguing Guacamole
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 GUACANOLE_HOME.
3. The directory . guacamole, located within the home directory of the user running the serviet 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 fle called guacanole. properties. This fle 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:
41, Within GUACAMOLE_HOME, as defined above.
2. 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 (guaed) 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
BasicFileduthenticationProvider which is the default authentication provider provided with
Guacamole. No extensions are needed if you use the default authentication provider.
Fipiiguac-devergldocigua/conigring-quacamie Him! 9raer2015
Chapter 3. Coniguing Guacamole
If you need custom authentication or wish to enable optional features of Guacamole, such as HTTP Basic
authentication support, you will need to specify additional properties:
guacd-sst
If set to "true", requires SSLITLS 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 .jar file and all dependencies must be placed in the directory
Specified here. On most systems, /var/1ib/guacamole/classpath is 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-telated 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
# Authentication provider class
auth-provider: net.sourceforge. guacamole.net.basic.BasicFileauthenticationProvider
# Properties used by BasicFileauthenticationProvider
basic-user-mapping:
/etc/guacamole/user-mapping. xml
Logging within the web application
By default, Guacamole logs all messages to the console, Servlet containers like Tomeat 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
warn
info
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.
Warnings are generally non-fatal conditions. The operation continued, but encountered noteworthy
problems.
“Info” messages are purely informational. They may be useful or interesting to administrators, but
Fipiiguac-devergldocigua/conigring-quacamie Him! 219rae2015 Chapter 3. Ceniguring Guacamole
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:
= Appender for debugging -->
&d{HH:nm:ss.SSS} [Rthread] %-Slevel %logger{36} - %msg%n
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 usemames 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!IThis 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 usemame, 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:
Fipiiguac-devergldocigua/conigring-quacamie Him! v9raev2005 Chapter 3. Coniguring Guacamole
vnc
localhost
59@8
First authorized connection
vnc
localhost
S901
VNCPASS
vnc
otherhost
5980
VNCPASS
Each user is specified with a corresponding tag. This tag contains all authorized connections
for that user, each denoted with a tag. Each tag contains a corresponding
protocol and set of protocol-specific parameters, specified with the and tags
respectively.
Adding users
When using BasicFileAuthenticationProvider, usermame/password pairs are specified with
tags, which each have a username and password attribute, Each tag authorizes
a specific username/password pair to access all connections within the tag
In the example above, the password would be listed in plaintext, If you don't want to do this
specify your password hashed with MDS:
you can also
Fipiiguac-devergldocigua/conigring-quacamie Him! a9raer2015 Chapter 3. Coniguing Guacamole
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 tag, you can either list a single protocol and set of
parameters (specified with a tag and any number of 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 tags, each of which can be named and contains a tag and any
number of tags.
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
NC
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.
NC support for Guacamole is provided by the libguac-client-vnc library, installed by default
Table 3.1. VNC configuration parameters
Name Description
The hostname or IP address of the VNC server Guacamole should connect
hostname
to,
The port the VNC server is listening on, usually 5900 or 5900 + display
port number . For example, if your VNC server is serving display number 1
(sometimes written as :1), your port number here would be 5901.
The password to use when attempting authentication, if any. This
Password parameter is optional.
Whether this connection should be read-only. if set to “true”, no input wil be
read-only 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.
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.
swap-red-blue
Fipiiguac-devergldoclgua/conigring-quacame Him! 50rapr2015
color-depth
cursor
autoretry
encodings
dest-host
dest-port
enable-audio
audio-servername
Chapter 3. Coniguing Guacamole
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.
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.
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
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-vne 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.
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
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
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
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.
Fipiiguac-devergldoclgua/conigring-quacamie Him!
onorapr2015 Chapter 3. Coniguing Guacamole
Whether reverse connection should be used. If set to “true”, instead of
reverse-connect connecting to a server at a given hostname and port, guacd will listen on
the given port for inbound connections from a VNC server.
If reverse connection is in use, the maximum amount of time to wait for an
Listen-timeout inbound cones
value is 5000 (five seconds).
Adding a VNC connection
If you are using the default authentication built into Guacamole, and you wish to grant access to a VNC
conneetion to a particular user, you need to locate the section for that user within your user
mapping. xm, and add a section like the following within it:
vne
localhost
5901
If added exactly as above, a new connection named " Unique Nane " will be available to the user associated
with the 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 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 TigorVNC
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
Tesponsive 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.
Fipiiguac-devergldocigua/conigring-quacamie Him! mora6r2015 Chapter 3. Coniguing Guacamole
xtivne
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 x1 1vnc is comparable to RealVNC,
Tiger VNC, and TightVNC. If you need to use your desktop locally as well as via VNC, you will likely be quite
happy with x1 tyne.
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
Ifyou 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
Name Description
The hostname or IP address of the RDP server Guacamole should connect
hostname
to
ort The port the RDP server is listening on, usually 3389, This parameter is
p optional. If this is not specified, the default of 3389 willbe used,
username The username to use to authenticate, if any. This parameter is optional.
assword The password to use when attempting authentication, if any. This
p parameter is optional
domain The domain to use when attempting authentication, if any. This parameter
tipiiguac-devergldocigua/conigring-quacamie Him! a9rapr2015
color-depth
width
height
dpi
disable-audio
enable-printing
enable-drive
drive-path
console
Chapter 3. Coniguing Guacamole
is optional
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,
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.
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.
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.
Audio is enabled by default in both the client and in libguac-client-rdp. If you
are concemed about bandwidth usage, or sound is causing problems, you
can explicitly disable sound by setting this parameter to true”.
Printing is disabled by default, but with printing enabled, ROP 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
File transfer is disabled by default, but with fle 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 fle transfer is enabled
The directory on the Guacamole server in which transfered 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 ROP server.
If file transfer is not enabled, this parameter is ignored.
If set to "true", you will be connected to the console (adi
RDP server.
session of the
Fipiiguac-devergldoclgua/conigring-quacame Him!
a9rapr2015 Chapter 3. Coniguing Guacamole
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
consoLe-audio rae
the consoLe parameter is also set to “true”
The full path to the program to run immediately upon connecting. This
intttal-program parameter is optional
The server-side keyboard layout. This is the layout of the ROP 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-querty
English (US) keyboard
de-de-quertz
German keyboard (qwertz)
fr-fr-azerty
server-Layout French keyboard (azerty)
iteit-querty
Italian keyboard
sv-se-querty
Swedish keyboard
failsafe
Unknown keyboard - this option sends only Unicode events and
should work for any keyboard, though not necessarily all ROP
servers or applications.
If your server's keyboard layout is not yet supported, this option
should work in the meantime,
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
ROP servers.
nla
Fipiiguac-devergldocigua/conigring-quacamie Him! 1019rapr2015
security
‘ignore-cert
disable-auth
remote-app
remote-app-dir
remote-app-args
static-channels
Chapter 3. Goniguring Guacamole
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.
tis
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
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, ifit 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 stil take place. By default, authentication is enabled and only
used when requested by the server.
Ifyou are using NLA, authentication must be enabled by definition.
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.
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: "|Inotepad”,
The working directory, if any, for the remote application. This parameter has
no effect if RemoteApp is not in use.
The command-line arguments, if any, for the remote application, This
parameter has no effect if RemoteApp is not in use.
‘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
Fipiiguac-devergldocigua/conigring-quacamie Him!
9rapr2015 Chapter 3. Coniguing Guacamole
characters.
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 section for that user within your user-
mapping.xml, and add a section like the following within it:
rdp localhost
3389
If added exactly as above, a new connection named" Unique Name " will be available to the user associated
with the 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 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 ROP, 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 libs!
Table 3.3. SSH configuration parameters
Name Description
The hostname or IP address of the SSH server Guacamole should connect
hostname to
ort The port the SSH server is listening on, usually 22. This parameter is
Pr optional. If this is not specified, the default of 22 will be used.
The username to use to authenticate, if any. This parameter is optional. If
username
not specified, you will be prompted for the username upon connecting
The password to use when attempting authentication, if any. This
password parameter is optional. If not specified, you will be prompted for your
Password upon connecting
Fipiiguac-devergldoclgua/conigring-quacamie Him! wi9rapr2015
font-name
font-size
enable-sftp
private-key
passphrase
Adding an SSH connection
If you are using the default authentication buil
Chapter 3. Coniguing Guacamole
The name of the font to use. This parameter is optional. If not specified, the
default of "monospace" will be used instead.
The size of the font to use, in points. This parameter is optional. If not
specified, the default of 12 will be used instead
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.
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
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
into Guacamole, and you wish to grant access to a SSH
connection to a particular user, you need to locate the section for that user within your user
mapping.xml, and add a section like the following within it:
«connection name=" Unique Name ">
ssh
hostname"> localhost
port"> 22
If added exactly as above, a new connection named " Unique Nane " will be available to the user associated
with the section conlaining 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 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 concemed, 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.
Fipiiguac-devergldocigua/conigring-quacamie Him!
1019ra6r2015
Chapter 3. Coniguing Guacamole
Telnet support for Guacamole is provided by the libguac-client-telnet library, which depends on libteinet,
Table 3.4. Telnet configuration parameters
Name
hostname
port
username
username-regex
password
password-regex
font-name
font-size
Adding a telnet connection
Description
The hostname or IP address of the telnet server Guacamole should
connect to.
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.
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 togin
process must pay attention to the USER environment variable. Most telnet
servers satisfy this criteria.
‘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).
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.
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)
The name of the font to use. This parameter is optional. If not specified, the
default of "monospace" will be used instead.
The size of the font to use, in points. This parameter is optional. If not
specified, the default of 12 will be used instead
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 section for that user within your user-
mapping. xml, and add a section like the following within it:
Fipiiguac-devergldocigua/conigring-quacamie Him!
anoraer2015 Chapter 3. Coniguing Guacamole
telnet localhost
23
If added exactly as above, a new connection named" Unique Nane " will be available to the user associated
with the 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
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 -1 command-line option
Passwords cannot typically be sent automatically - at least not as reliably as the usemame. 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).
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 "S", as in "$S(TOKEN_NAME)"
${GUAC_USERNAME}
The usemame 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}
Fipiiguac-devergldocigua/coniguing-quacamie Him! 1519rae2015 Chapter 3. Coniguring Guacamole
‘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
log_level = info
[server]
bind_host = localhost
bind_port = 4822
#
# The following parameters are valid only if
# guacd was built with SSL support.
#
[ssi]
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
“4” symbols. All text following a "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:
[ssi]
tt 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:
Fipiiguac-devergldocigua/conigring-quacamie Him! 1819raer2015
# Parameter value containing a double quote
parameter = “some\"value"
Chapter 3. Coniguing Guacamole
# Parameter value containing newline characters
parameter2 =
Line2\
Line:
‘Line1\
# Parameter value containing backslashes
c:\\windows\\path\\to\\file. txt”
parameter3 =
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, Ifthe value contains no special characters, just include it as-is.
2. Ifthe value contains any special characters (whitespace, newlines, #, \, or "), enclose the entire value
within double quotes.
3. Ifthe value is enclosed within double quotes, escape newlines, \, and " with a backslash.
Table 3.5. guacd.conf parameters
Section Name
daemon pid_file
daemon Log_level
server bind_host
server bind_port
Fipiiguac-devergldocigua/conigring-quacamie Him!
Descri
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 fal.
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.
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
The port that guacd should bind to when
listening for connections, If unspecified, port
4822 will be used.
The filename of the certificate to use for SSL
encryption of the Guacamole protocol. If this
m9rapr2015 Chapter 3. Coniguing Guacamole
ssl server_certificate | 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.
The filename of the private key to use for SSL
encryption of the Guacamole protocol. If t
option is specified, SSL encryption will be
enabled, and the Guacamole web application will
need to be_~—sconfigured within
guacamole. properties to use SSL as well.
ssl server_key
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. cont
-1 port
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. cont
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 guacanole. 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
Fipiiguac-devergldocigua/conigring-quacamie Him! 1819raer2015 Chapter 3. Coniguing Guacamole
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.
Ulnet. sourceforge. guacamole.net.basic.BasicFileAuthenticationProvider
ipuigusc-dev ergldocguatconigring-guacamele him! 1919