Table of Contents
After installing Guacamole, you need to configure users and connections before Guacamole will work. This chapter covers general configuration of Guacamole and the use of its default authentication method.
Guacamole's default authentication method reads all users and connections from a single
file called user-mapping.xml. This authentication method is intended to
be:
Sufficient for small deployments of Guacamole.
A relatively-easy means of verifying that Guacamole has been properly set up.
Other, more complex authentication methods which use backend databases, LDAP, etc. are discussed in a separate, dedicated chapters.
Regardless of the authentication method you use, Guacamole's configuration always consists
of two main pieces: a directory referred to as GUACAMOLE_HOME, which is
the primary search location for configuration files, and
guacamole.properties, the main configuration file used by Guacamole
and its extensions.
GUACAMOLE_HOME is the name given to Guacamole's configuration
directory, which is located at /etc/guacamole by default. All
configuration files, extensions, etc. reside within this directory. The structure of
GUACAMOLE_HOME is rigorously defined, and consists of the
following optional files:
guacamole.propertiesThe 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.xmlGuacamole 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
.jarfiles within this directory on startup.lib/The search directory for libraries required by any Guacamole extensions. Guacamole will make the
.jarfiles 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.
If you cannot or do not wish to use /etc/guacamole for
GUACAMOLE_HOME, the location can be overridden through any of
the following methods:
Creating a directory named
.guacamole, within the home directory of the user running the servlet container. This directory will automatically be used forGUACAMOLE_HOMEif it exists.Specifying the full path to an alternative directory with the environment variable
GUACAMOLE_HOME. Be sure to consult the documentation for your servlet container to determine how to properly set environment variables.Specifying the full path to an alternative directory with the system property guacamole.home.
The Guacamole web application uses one main configuration file called
guacamole.properties. This file is the common location for all
configuration properties read by Guacamole or any extension of Guacamole, including
authentication providers.
In previous releases, this file had to be in the classpath of your servlet container.
Now, the location of guacamole.properties can be explicitly defined
with environment variables or system properties, and the classpath is only used as a
last resort. When searching for guacamole.properties, Guacamole
will check, in order:
Within
GUACAMOLE_HOME, as defined above.The classpath of the servlet container.
The guacamole.properties file is optional and is used to
configure Guacamole in situations where the defaults are insufficient, or to provide
additional configuration information for extensions. There are several standard
properties that are always available for use:
api-session-timeoutThe amount of time, in minutes, to allow Guacamole sessions (authentication tokens) to remain valid despite inactivity. If omitted, Guacamole sessions will expire after 60 minutes of inactivity.
available-languagesA comma-separated whitelist of language keys to allow as display language choices within the Guacamole interface. For example, to restrict Guacamole to only English and German, you would specify:
available-languages: en, de
As English is the fallback language, used whenever a translation key is missing from the chosen language, English should only be omitted from this list if you are absolutely positive that no strings are missing.
The corresponding JSON of any built-in languages not listed here will still be available over HTTP, but the Guacamole interface will not use them, nor will they be used automatically based on local browser language. If omitted, all defined languages will be available.
enable-environment-propertiesIf set to "true", Guacamole will first evaluate its environment to obtain the value for any given configuration property, before using a value specified in
guacamole.propertiesor falling back to a default value. By enabling this option, you can easily override any other configuration property using an environment variable.enable-environment-properties: true
When searching for a configuration property in the environment, the name of the property is first transformed by converting all lower case characters to their upper case equivalents, and by replacing all hyphen characters (
-) with underscore characters (_). For example, theguacd-hostnameproperty would be transformed toGUACD_HOSTNAMEwhen searching the environment.guacd-hostnameThe host the Guacamole proxy daemon (guacd) is listening on. If omitted, Guacamole will assume guacd is listening on localhost.
guacd-portThe port the Guacamole proxy daemon (guacd) is listening on. If omitted, Guacamole will assume guacd is listening on port 4822.
guacd-sslIf 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.
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:
errorErrors 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.
warnWarnings 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.
debugDebug messages are highly detailed and oriented toward development. Most debug messages will contain stack traces and internal information that is useful when investigating problems within code. It is expected that debug messages, though verbose, will not affect performance.
traceTrace messages are similar to debug messages in intent and verbosity, but are so low-level that they may affect performance due to their frequency. Trace-level logging is rarely necessary, and is mainly useful in providing highly detailed context around issues being investigated.
Guacamole logs messages using a logging framework called Logback 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:
<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.
Guacamole's default authentication module is simple and consists of a mapping of usernames to configurations. This authentication module comes with Guacamole and simply reads usernames and passwords from an XML file. It is always enabled, but will only read from the XML file if it exists, and is always last in priority relative to any other authentication extensions.
There are other authentication modules available. The Guacamole project provides database-backed authentication modules with the ability to manage connections and users from the web interface, and other authentication modules can be created using the extension API provided along with the Guacamole web application, guacamole-ext.
The default authentication provider used by Guacamole reads all username,
password, and configuration information from a file called the "user mapping"
located at GUACAMOLE_HOME/user-mapping.xml. An example of a
user mapping file is included with Guacamole, and looks something like this:
<user-mapping>
<!-- Per-user authentication and config information -->
<authorize username="USERNAME" password="PASSWORD">
<protocol>vnc</protocol>
<param name="hostname">localhost</param>
<param name="port">5900</param>
<param name="password">VNCPASS</param>
</authorize>
<!-- Another user, but using md5 to hash the password
(example below uses the md5 hash of "PASSWORD") -->
<authorize
username="USERNAME2"
password="319f4d26e3c536b5dd871bb2c52e3178"
encoding="md5">
<!-- First authorized connection -->
<connection name="localhost">
<protocol>vnc</protocol>
<param name="hostname">localhost</param>
<param name="port">5901</param>
<param name="password">VNCPASS</param>
</connection>
<!-- Second authorized connection -->
<connection name="otherhost">
<protocol>vnc</protocol>
<param name="hostname">otherhost</param>
<param name="port">5900</param>
<param name="password">VNCPASS</param>
</connection>
</authorize>
</user-mapping>Each user is specified with a corresponding
<authorize> tag. This tag contains all
authorized connections for that user, each denoted with a
<connection> tag. Each
<connection> tag contains a corresponding
protocol and set of protocol-specific parameters, specified with
the <protocol> and <param> tags
respectively.
When using
BasicFileAuthenticationProvider,
username/password pairs are specified with
<authorize> tags, which each have a
username and password
attribute. Each <authorize> tag authorizes a
specific username/password pair to access all connections
within the tag:
<authorize username="USER" password="PASS"> ... </authorize>
In the example above, the password would be listed in plaintext. If you don't want to do this, you can also specify your password hashed with MD5:
<authorize username="USER" password="319f4d26e3c536b5dd871bb2c52e3178" encoding="md5"> ... </authorize>
After modifying user-mapping.xml, the file will be automatically reread by Guacamole, and your changes will take effect immediately. The newly-added user will be able to log in - no restart of the servlet container is needed.
To specify a connection within an
<authorize> tag, you can either list a
single protocol and set of parameters (specified with a
<protocol> tag and any number of
<param> tags), in which case that user
will have access to only one connection named "DEFAULT", or
you can specify one or more connections with one or more
<connection> tags, each of which can be
named and contains a <protocol> tag and any
number of <param> tags.
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.
The VNC protocol is the simplest and first protocol supported by Guacamole. Although generally not as fast as RDP, many VNC servers are adequate, and VNC over Guacamole tends to be faster than VNC by itself due to decreased bandwidth usage.
VNC support for Guacamole is provided by the libguac-client-vnc library, which will be installed as part of guacamole-server if the required dependencies are present during the build.
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.
The VNC standard defines only password based authentication. Other authentication mechanisms exist, but are non-standard or proprietary. Guacamole supports only the password method.
VNC servers do not allow the client to request particular display sizes, so you are at the mercy of your VNC server with respect to display width and height. However, to reduce bandwidth usage, you may request that the VNC server reduce its color depth. Guacamole will automatically detect 256-color images, but this can be guaranteed for absolutely all graphics sent over the connection by forcing the color depth to 8-bit. Color depth is otherwise dictated by the VNC server.
If you are noticing problems with your VNC display, such as the lack of a mouse cursor, the presence of multiple mouse cursors, or strange colors (such as blue colors appearing more like orange or red), these are typically the result of bugs or limitations within the VNC server, and additional parameters are available to work around such issues.
VNC sessions can be recorded graphically. These recordings take the form of Guacamole protocol dumps and are recorded automatically to a specified directory. Recordings can be subsequently translated to a normal video stream using the guacenc utility provided with guacamole-server.
For example, to produce a video called "NAME.m4v"
from the recording "NAME", you would run:
$guacenc/path/to/recording/NAME
The guacenc utility has additional options for overriding default behavior, including tweaking the output format, which are documented in detail within the manpage:
$man guacenc
If recording of key events is explicitly enabled using the
recording-include-keys parameter, recordings can also
be translated into human-readable interpretations of the keys pressed during the
session using the guaclog utility. The usage of
guaclog is analogous to guacenc, and
results in the creation of a new text file containing the interpreted
events:
$guaclog/path/to/recording/NAMEguaclog: INFO: Guacamole input log interpreter (guaclog) version 1.0.0 guaclog: INFO: 1 input file(s) provided. guaclog: INFO: Writing input events from "/path/to/recording/NAME" to "/path/to/recording/NAME.txt" ... guaclog: INFO: All files interpreted successfully.$
Important
Guacamole will never overwrite an existing recording. If necessary, a
numeric suffix like ".1", ".2", ".3", etc. will be appended to
NAME to avoid overwriting an existing
recording. If even appending a numeric suffix does not help, the session
will simply not be recorded.
VNC does not normally support file transfer, but Guacamole can provide file transfer over SFTP even when the remote desktop is otherwise being accessed through VNC and not SSH. If SFTP is enabled on a Guacamole VNC connection, users will be able to upload and download files as described in Chapter 15, Using Guacamole.
| 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 specified server using SFTP. If omitted, SFTP will be disabled. |
sftp-hostname |
The hostname or IP address of the server hosting SFTP.
This parameter is optional. If omitted, the hostname of the
VNC server specified with the
|
sftp-port |
The port the SSH server providing SFTP is listening on, usually 22. This parameter is optional. If omitted, the standard port of 22 will be used. |
sftp-host-key |
The known hosts entry for the SFTP server. This parameter is optional, and, if not provided, no verification of SFTP host identity will be done. If the parameter is provided the identity of the server will be checked against the data. The format of this parameter should be that of a single
entry from an OpenSSH For more information, please see the section called “SSH Host Verification”. |
sftp-username |
The username to authenticate as when connecting to the specified SSH server for SFTP. This parameter is required. |
sftp-password |
The password to use when authenticating with the specified SSH server for SFTP. |
sftp-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. |
sftp-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. |
sftp-directory |
The directory to upload files to if they are simply dragged and dropped, and thus otherwise lack a specific upload location. This parameter is optional. If omitted, the default upload location of the SSH server providing SFTP will be used. |
sftp-root-directory |
The directory to expose to connected users via Guacamole's file browser. If omitted, the root directory will be used by default. |
sftp-server-alive-interval |
The interval in seconds at which to send keepalive packets to the SSH server for the SFTP connection. This parameter is optional. If omitted, the default of 0 will be used, disabling sending keepalive packets. The minimum value is 2. |
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.
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.
VNC does not provide its own support for audio, but Guacamole's VNC support can obtain audio through a secondary network connection to a PulseAudio server running on the same machine as the VNC server.
Most Linux systems provide audio through a service called PulseAudio. This service is capable of communicating over the network, and if PulseAudio is configured to allow TCP connections, Guacamole can connect to your PulseAudio server and combine its audio with the graphics coming over VNC.
Configuring PulseAudio for network connections requires an additional line
within the PulseAudio configuration file, usually
/etc/pulse/default.pa:
load-module module-native-protocol-tcp auth-ip-acl=192.168.1.0/24 auth-anonymous=1This loads the TCP module for PulseAudio, configuring it to accept connections
without authentication and only from the
192.168.1.0/24 subnet. You will want to replace
this value with the subnet or IP address from which guacd will be connecting. It
is possible to allow connections from absolutely anywhere, but beware that you
should only do so if the nature of your network prevents unauthorized
access:
load-module module-native-protocol-tcp auth-anonymous=1
In either case, the auth-anonymous=1 parameter is strictly
required. Guacamole does not currently support the cookie-based authentication
used by PulseAudio for non-anonymous connections. If this parameter is omitted,
Guacamole will not be able to connect to PulseAudio.
Once the PulseAudio configuration file has been modified appropriately, restart the PulseAudio service. PulseAudio should then begin listening on port 4713 (the default PulseAudio port) for incoming TCP connections. You can verify this using a utility like netstat:
$netstat -ln | grep 4713tcp 0 0 0.0.0.0:4713 0.0.0.0:* LISTEN tcp6 0 0 :::4713 :::* LISTEN$
The following parameters are available for configuring the audio support for VNC:
While Guacamole will always use UTF-8 for its own clipboard data, the VNC
standard requires that clipboard data be encoded in ISO 8859-1. As most VNC
servers will not accept data in any other format, Guacamole will translate
between UTF-8 and ISO 8859-1 when exchanging clipboard data with the VNC server,
but this behavior can be overridden with the
clipboard-encoding parameter.
Important
The only clipboard encoding guaranteed to be supported by VNC
servers is ISO 8859-1. You should only override the clipboard
encoding using the clipboard-encoding parameter of
you are absolutely positive your VNC server supports other encodings.
If you are using the default authentication built into Guacamole, and you wish
to grant access to a VNC connection to a particular user, you need to locate the
<authorize> section for that user within your
user-mapping.xml, and add a section like the following
within it:
<connection name="Unique Name"> <protocol>vnc</protocol> <param name="hostname">localhost</param> <param name="port">5901</param> </connection>
If added exactly as above, a new connection named "Unique
Name" will be available to the user associated with the
<authorize> section containing it. The connection will use
VNC to connect to localhost at port
5901. Naturally, you will want to change some or
all of these values.
If your VNC server requires a password, or you wish to specify other
configuration parameters (to reduce the color depth, for example), you will need
to add additional <param> tags accordingly.
Other authentication methods will provide documentation describing how to configure new connections. If the authentication method in use fully implements the features of Guacamole's authentication API, you will be able to add a new VNC connection easily and intuitively using the administration interface built into Guacamole. You will not need to edit configuration files.
The choice of VNC server can make a big difference when it comes to performance, especially over slower networks. While many systems provide VNC access by default, using this is often not the fastest method.
RealVNC, and its derivative TigerVNC, perform quite well. In our testing, they perform the best with Guacamole. If you are okay with having a desktop that can only be accessed via VNC, one of these is likely your best choice. Both optimize window movement and (depending on the application) scrolling, giving a very responsive user experience.
TightVNC is widely-available and performs generally as well as RealVNC or TigerVNC. If you wish to use TightVNC with Guacamole, performance should be just fine, but we highly recommend disabling its JPEG encoding. This is because images transmitted to Guacamole are always encoded losslessly as PNG images. When this operation is performed on a JPEG image, the artifacts present from JPEG's lossy compression reduce the compressibility of the image for PNG, thus leading to a slower experience overall than if JPEG was simply not used to begin with.
The main benefit of using x11vnc is that it allows you to continue using your desktop normally, while simultaneously exposing control of your desktop via VNC. Performance of x11vnc is comparable to RealVNC, TigerVNC, and TightVNC. If you need to use your desktop locally as well as via VNC, you will likely be quite happy with x11vnc.
vino is the VNC server that comes with the Gnome desktop environment, and is enabled if you enable "desktop sharing" via the system preferences available within Gnome. If you need to share your local desktop, we recommend using x11vnc rather vino, as it has proven more performant and feature-complete in our testing. If you don't need to share a local desktop but simply need an environment you can access remotely, using a VNC server like RealVNC, TigerVNC, or TightVNC is a better choice.
QEMU (and thus KVM) expose the displays of virtual machines using VNC. If you need to see the virtual monitor of your virtual machine, using this VNC connection is really your only choice. As the VNC server built into QEMU cannot be aware of higher-level operations like window movement, resizing, or scrolling, those operations will tend to be sent suboptimally, and will not be as fast as a VNC server running within the virtual machine.
If you wish to use a virtual machine for desktop access, we recommend installing a native VNC server inside the virtual machine after the virtual machine is set up. This will give a more responsive desktop.
The RDP protocol is more complicated than VNC and was the second protocol officially supported by Guacamole. RDP tends to be faster than VNC due to the use of caching, which Guacamole does take advantage of.
RDP support for Guacamole is provided by the libguac-client-rdp library, which will be installed as part of guacamole-server if the required dependencies are present during the build.
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.
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.
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.
Guacamole will automatically choose an appropriate display size for RDP connections based on the size of the browser window and the DPI of the device. The size of the display can be forced by specifying explicit width or height values.
To reduce bandwidth usage, you may also request that the server reduce its color depth. Guacamole will automatically detect 256-color images, but this can be guaranteed for absolutely all graphics sent over the connection by forcing the color depth to 8-bit. Color depth is otherwise dictated by the RDP server.
RDP sessions can be recorded graphically. These recordings take the form of Guacamole protocol dumps and are recorded automatically to a specified directory. Recordings can be subsequently translated to a normal video stream using the guacenc utility provided with guacamole-server.
For example, to produce a video called "NAME.m4v"
from the recording "NAME", you would run:
$guacenc/path/to/recording/NAME
The guacenc utility has additional options for overriding default behavior, including tweaking the output format, which are documented in detail within the manpage:
$man guacenc
If recording of key events is explicitly enabled using the
recording-include-keys parameter, recordings can also
be translated into human-readable interpretations of the keys pressed during the
session using the guaclog utility. The usage of
guaclog is analogous to guacenc, and
results in the creation of a new text file containing the interpreted
events:
$guaclog/path/to/recording/NAMEguaclog: INFO: Guacamole input log interpreter (guaclog) version 1.0.0 guaclog: INFO: 1 input file(s) provided. guaclog: INFO: Writing input events from "/path/to/recording/NAME" to "/path/to/recording/NAME.txt" ... guaclog: INFO: All files interpreted successfully.$
Important
Guacamole will never overwrite an existing recording. If necessary, a
numeric suffix like ".1", ".2", ".3", etc. will be appended to
NAME to avoid overwriting an existing
recording. If even appending a numeric suffix does not help, the session
will simply not be recorded.
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 15, Using Guacamole.
Some RDP servers host multiple logical RDP connections behind a single server listening on a single TCP port. To select between these logical connections, an RDP client must send the "preconnection PDU" - a message which contains values that uniquely identify the destination, referred to as the "RDP source". This mechanism is defined by the "Session Selection Extension" for the RDP protocol, and is implemented by Microsoft's Hyper-V hypervisor.
If you are using Hyper-V, you will need to specify the ID of the destination
virtual machine within the preconnection-blob parameter.
This value can be determined using PowerShell:
PS C:\>Get-VMVirtualMachineName| Select-Object IdId -- ed272546-87bd-4db9-acba-e36e1a9ca20aPS C:\>
The preconnection PDU is intentionally generic. While its primary use is as a means for selecting virtual machines behind Hyper-V, other RDP servers may use it as well. It is up to the RDP server itself to determine whether the preconnection ID, BLOB, or both will be used, and what their values mean.
If you do intend to use Hyper-V, beware that its built-in RDP server uses slightly different parameters for both authentication and the port number, and Guacamole's defaults will not work. In most cases, you will need to do the following when connecting to Hyper-V:
Set "
port" to "2179", as this is the default port used by Hyper-V. The standard RDP port is 3389, and Guacamole will use port 3389 unless a different value is specified.Specify both "
username" and "password" appropriately, and set "security" to "nla" or "any". Hyper-V requires Network Level Authentication from connecting clients. Guacamole's default is to use standard RDP encryption without Network Level Authentication, which Hyper-V does not support.If necessary, set "
ignore-cert" to "true". Hyper-V may use a self-signed certificate.
Microsoft's remote desktop server provides an additional gateway service which allows external connections to be forwarded to internal RDP servers which are otherwise not accessible. If you will be using Guacamole to connect through such a gateway, you will need to provide additional parameters describing the connection to that gateway, as well as any required credentials.
This functionality is only available if Guacamole was built against FreeRDP 1.1 or later. Older versions of FreeRDP do not have support for RDP gateways.
If your remote desktop servers are behind a load balancer, sometimes referred to as a "connection broker" or "TS session broker", that balancer may require additional information during the connection process to determine how the incoming connection should be routed. RDP does not dictate the format of this information; it is specific to the balancer in use.
If you are using a load balancer and are unsure whether such information is
required, you will need to check the documentation for your
balancer. If your balancer provides .rdp
files for convenience, look through the contents of those files for a string
field called "loadbalanceinfo", as that field is where the required
information/cookie would be specified.
This functionality is only available if Guacamole was built against FreeRDP 1.1 or later. Older versions of FreeRDP do not have support for load balancers which require additional information during the connection process.
Guacamole can provide file transfer over SFTP even when the remote desktop is otherwise being accessed through RDP and not SSH. If SFTP is enabled on a Guacamole RDP connection, users will be able to upload and download files as described in Chapter 15, Using Guacamole.
This support is independent of the file transfer implemented through RDP's own "drive redirection" (RDPDR), and is particularly useful for RDP servers which do not support RDPDR.
| 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 specified server using SFTP. If omitted, SFTP will be disabled. |
sftp-hostname |
The hostname or IP address of the server hosting SFTP.
This parameter is optional. If omitted, the hostname of the
RDP server specified with the
|
sftp-port |
The port the SSH server providing SFTP is listening on, usually 22. This parameter is optional. If omitted, the standard port of 22 will be used. |
sftp-host-key |
The known hosts entry for the SFTP server. This parameter is optional, and, if not provided, no verification of SFTP host identity will be done. If the parameter is provided the identity of the server will be checked against the data. The format of this parameter is that of a single entry
from an OpenSSH For more information, please see the section called “SSH Host Verification”. |
sftp-username |
The username to authenticate as when connecting to the
specified SSH server for SFTP. This parameter is optional if
a username is specified for the RDP connection. If omitted,
the value provided for the |
sftp-password |
The password to use when authenticating with the specified SSH server for SFTP. |
sftp-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. |
sftp-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. |
sftp-directory |
The directory to upload files to if they are simply dragged and dropped, and thus otherwise lack a specific upload location. This parameter is optional. If omitted, the default upload location of the SSH server providing SFTP will be used. |
sftp-root-directory |
The directory to expose to connected users via Guacamole's file browser. If omitted, the root directory will be used by default. |
sftp-server-alive-interval |
The interval in seconds at which to send keepalive packets to the SSH server for the SFTP connection. This parameter is optional. If omitted, the default of 0 will be used, disabling sending keepalive packets. The minimum value is 2. |
RDP provides several flags which control the availability of features that decrease performance and increase bandwidth for the sake of aesthetics, such as wallpaper, window theming, menu effects, and smooth fonts. These features are all disabled by default within Guacamole such that bandwidth usage is minimized, but you can manually re-enable them on a per-connection basis if desired.
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.
If you are using the default authentication built into Guacamole, and you wish
to grant access to a RDP connection to a particular user, you need to locate the
<authorize> section for that user within your
user-mapping.xml, and add a section like the following
within it:
<connection name="Unique Name"> <protocol>rdp</protocol> <param name="hostname">localhost</param> <param name="port">3389</param> </connection>
If added exactly as above, a new connection named "Unique
Name" will be available to the user associated with the
<authorize> section containing it. The connection will use
RDP to connect to localhost at port
3389. Naturally, you will want to change some or
all of these values.
If you want to login automatically rather than receive a login prompt upon
connecting, you can specify a username and password with additional
<param> tags. Other options are available for controlling
the color depth, size of the screen, etc.
Other authentication methods will provide documentation describing how to configure new connections. If the authentication method in use fully implements the features of Guacamole's authentication API, you will be able to add a new RDP connection easily and intuitively using the administration interface built into Guacamole. You will not need to edit configuration files.
Unlike VNC or RDP, SSH is a text protocol. Its implementation in Guacamole is actually a combination of a terminal emulator and SSH client, because the SSH protocol isn't inherently graphical. Guacamole's SSH support emulates a terminal on the server side, and draws the screen of this terminal remotely on the client.
SSH support for Guacamole is provided by the libguac-client-ssh library, which will be installed as part of guacamole-server if the required dependencies are present during the build.
By default, Guacamole does not do any verification of host identity before establishing SSH connections. While this may be safe for private and trusted networks, it is not ideal for large networks with unknown/untrusted systems, or for SSH connections that traverse the Internet. The potential exists for Man-in-the-Middle (MitM) attacks when connecting to these hosts.
Guacamole includes two methods for verifying SSH (and SFTP) server identity
that can be used to make sure that the host you are connecting to is a host
that you know and trust. The first method is by reading a file in
GUACAMOLE_HOME called ssh_known_hosts.
This file should be in the format of a standard OpenSSH known_hosts file.
If the file is not present, no verification is done. If the file is present,
it is read in at connection time and remote host identities are verified
against the keys present in the file.
The second method for verifying host identity is by passing a connection
parameter that contains an OpenSSH known hosts entry for that specific host.
The host-key parameter is used for SSH connections,
while the SFTP connections associated with RDP and VNC use the
sftp-host-key parameter. If these parameters are
not present on their respective connections no host identity verification
is performed. If the parameter is present then the identity of the remote
host is verified against the identity provided in the parameter before a
connection is established.
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. |
host-key |
The known hosts entry for the SSH server. This parameter is optional, and, if not provided, no verification of host identity will be done. If the parameter is provided the identity of the server will be checked against the data. The format of this parameter is that of a single entry from
an OpenSSH For more information, please see the section called “SSH Host Verification”. |
server-alive-interval |
By default the SSH client does not send keepalive requests to the server. This parameter allows you to configure the the interval in seconds at which the client connection sends keepalive packets to the server. The default is 0, which disables sending the packets. The minimum value is 2. |
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 connection parameters, if provided, or by prompting the user directly.
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.
By default, SSH sessions will start an interactive shell. The shell which will
be used is determined by the SSH server, normally by reading the user's default
shell previously set with chsh or within
/etc/passwd. If you wish to override this and instead
run a specific command, you can do so by specifying that command in the
configuration of the Guacamole SSH connection.
In most cases, the default behavior for a terminal works without modification. However, when connecting to certain systems, particularly operating systems other than Linux, the terminal behavior may need to be tweaked to allow it to operate properly. The settings in this section control that behavior.
The full, raw text content of SSH sessions, including timing information, can
be recorded automatically to a specified directory. This recording, also known
as a "typescript", will be written to two files within the directory specified
by typescript-path:
NAMENAME.timingNAME is the
value provided for the typescript-name parameter.
This format is compatible with the format used by the standard UNIX
script command, and can be replayed using
scriptreplay (if installed). For example, to replay a
typescript called "NAME", you would run:
$scriptreplayNAME.timingNAME
Important
Guacamole will never overwrite an existing recording. If necessary, a
numeric suffix like ".1", ".2", ".3", etc. will be appended to
NAME to avoid overwriting an existing
recording. If even appending a numeric suffix does not help, the session
will simply not be recorded.
In addition to text-based recordings, SSH sessions can be recorded graphically. These recordings take the form of Guacamole protocol dumps and are recorded automatically to a specified directory. Recordings can be subsequently translated to a normal video stream using the guacenc utility provided with guacamole-server.
For example, to produce a video called "NAME.m4v"
from the recording "NAME", you would run:
$guacenc/path/to/recording/NAME
The guacenc utility has additional options for overriding default behavior, including tweaking the output format, which are documented in detail within the manpage:
$man guacenc
If recording of key events is explicitly enabled using the
recording-include-keys parameter, recordings can also
be translated into human-readable interpretations of the keys pressed during the
session using the guaclog utility. The usage of
guaclog is analogous to guacenc, and
results in the creation of a new text file containing the interpreted
events:
$guaclog/path/to/recording/NAMEguaclog: INFO: Guacamole input log interpreter (guaclog) version 1.0.0 guaclog: INFO: 1 input file(s) provided. guaclog: INFO: Writing input events from "/path/to/recording/NAME" to "/path/to/recording/NAME.txt" ... guaclog: INFO: All files interpreted successfully.$
Important
Guacamole will never overwrite an existing recording. If necessary, a
numeric suffix like ".1", ".2", ".3", etc. will be appended to
NAME to avoid overwriting an existing
recording. If even appending a numeric suffix does not help, the session
will simply not be recorded.
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 15, Using Guacamole.
| 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. |
sftp-root-directory |
The directory to expose to connected users via Guacamole's file browser. If omitted, the root directory will be used by default. |
If you are using the default authentication built into Guacamole, and you wish
to grant access to a SSH connection to a particular user, you need to locate the
<authorize> section for that user within your
user-mapping.xml, and add a section like the following
within it:
<connection name="Unique Name"> <protocol>ssh</protocol> <param name="hostname">localhost</param> <param name="port">22</param> </connection>
If added exactly as above, a new connection named "Unique
Name" will be available to the user associated with the
<authorize> section containing it. The connection will use
SSH to connect to localhost at port
22. Naturally, you will want to change some or
all of these values.
If you want to login automatically rather than receive a login prompt upon
connecting, you can specify a username and password with additional
<param> tags. Other options are available for controlling
the font.
Other authentication methods will provide documentation describing how to configure new connections.
Telnet is a text protocol and provides similar functionality to SSH. By nature, it is not encrypted, and does not provide support for file transfer. As far as graphics are concerned, Guacamole's telnet support works in the same manner as SSH: it emulates a terminal on the server side which renders to the Guacamole client's display.
Telnet support for Guacamole is provided by the libguac-client-telnet library, which will be installed as part of guacamole-server if the required dependencies are present during the build.
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.
Telnet does not actually provide any standard means of authentication. Authentication over telnet depends entirely on the login process running on the server and is interactive. To cope with this, Guacamole provides non-standard mechanisms for automatically passing the username and entering password. Whether these mechanisms work depends on specific login process used by your telnet server.
The de-facto method for passing the username automatically via telnet is to
submit it via the USER environment variable, sent using the
NEW-ENVIRON option. This is the mechanism used by
most telnet clients, typically via the -l command-line
option.
Passwords cannot typically be sent automatically - at least not as reliably as
the username. There is no PASSWORD environment variable (this
would actually be a horrible idea) nor any similar mechanism for passing the
password to the telnet login process, and most telnet clients provide no
built-in support for automatically entering the password. The best that can be
done is to heuristically detect the password prompt, and type the password on
behalf of the user when the prompt appears. The prescribed method for doing this
with a traditional command-line telnet is to use a utility like
expect. Guacamole provides similar functionality by
searching for the password prompt with a regular expression.
If Guacamole receives a line of text which matches the regular expression, the password is automatically sent. If no such line is ever received, the password is not sent, and the user must type the password manually. Pressing any key during this process cancels the heuristic password prompt detection.
If the password prompt is not being detected properly, you can try using your
own regular expression by specifying it within the
password-regex parameter. The regular expression must
be written in the POSIX ERE dialect (the dialect typically used by
egrep).
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.
In most cases, the default behavior for a terminal works without modification. However, when connecting to certain systems, particularly operating systems other than Linux, the terminal behavior may need to be tweaked to allow it to operate properly. The settings in this section control that behavior.
The full, raw text content of telnet sessions, including timing information,
can be recorded automatically to a specified directory. This recording, also
known as a "typescript", will be written to two files within the directory
specified by typescript-path:
NAMENAME.timingNAME is the
value provided for the typescript-name parameter.
This format is compatible with the format used by the standard UNIX
script command, and can be replayed using
scriptreplay (if installed). For example, to replay a
typescript called "NAME", you would run:
$scriptreplayNAME.timingNAME
Important
Guacamole will never overwrite an existing recording. If necessary, a
numeric suffix like ".1", ".2", ".3", etc. will be appended to
NAME to avoid overwriting an existing
recording. If even appending a numeric suffix does not help, the session
will simply not be recorded.
In addition to text-based recordings, telnet sessions can be recorded graphically. These recordings take the form of Guacamole protocol dumps and are recorded automatically to a specified directory. Recordings can be subsequently translated to a normal video stream using the guacenc utility provided with guacamole-server.
For example, to produce a video called "NAME.m4v"
from the recording "NAME", you would run:
$guacenc/path/to/recording/NAME
The guacenc utility has additional options for overriding default behavior, including tweaking the output format, which are documented in detail within the manpage:
$man guacenc
If recording of key events is explicitly enabled using the
recording-include-keys parameter, recordings can also
be translated into human-readable interpretations of the keys pressed during the
session using the guaclog utility. The usage of
guaclog is analogous to guacenc, and
results in the creation of a new text file containing the interpreted
events:
$guaclog/path/to/recording/NAMEguaclog: INFO: Guacamole input log interpreter (guaclog) version 1.0.0 guaclog: INFO: 1 input file(s) provided. guaclog: INFO: Writing input events from "/path/to/recording/NAME" to "/path/to/recording/NAME.txt" ... guaclog: INFO: All files interpreted successfully.$
Important
Guacamole will never overwrite an existing recording. If necessary, a
numeric suffix like ".1", ".2", ".3", etc. will be appended to
NAME to avoid overwriting an existing
recording. If even appending a numeric suffix does not help, the session
will simply not be recorded.
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.
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
${, where
TOKEN_NAME}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 a 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 a connection, this token will be dynamically replaced with the password they used when logging in to Guacamole.
${GUAC_CLIENT_ADDRESS}The IPv4 or IPv6 address of the current Guacamole user. This will be the address of the client side of the HTTP connection to the Guacamole server at the time the current user logged in.
${GUAC_CLIENT_HOSTNAME}The hostname of the current Guacamole user. This will be the hostname of the client side of the HTTP connection to the Guacamole server at the time the current user logged in. If no such hostname can be determined, the IPv4 or IPv6 address will be used instead, and this token will be equivalent to
${GUAC_CLIENT_ADDRESS}.${GUAC_DATE}The current date in the local time zone of the Guacamole server. This will be written in "YYYYMMDD" format, where "YYYY" is the year, "MM" is the month number, and "DD" is the day of the month, all zero-padded. When a user accesses a connection, this token will be dynamically replaced with the date that the connection began.
${GUAC_TIME}The current time in the local time zone of the Guacamole server. This will be written in "HHMMSS" format, where "HH" is hours in 24-hour time, "MM" is minutes, and "SS" is seconds, all zero-padded. When a user accesses a connection, this token will be dynamically replaced with the time that the connection began.
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.
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. # [ssl] server_certificate = /etc/ssl/certs/guacd.crt server_key = /etc/ssl/private/guacd.key
Configuration options are given as parameter/value pairs, where the name of the
parameter is specified on the left side of an "=", and the value is
specified on the right. Each parameter must occur within a proper section, indicated by
a section name within brackets. The names of these sections are important; it is the
pairing of a section name with a parameter that constitutes the fully-qualified
parameter being set.
For the sake of documentation and readability, comments can be added anywhere within
guacd.conf using "#" symbols. All text following a "#" until
end-of-line will be ignored.
If you need to include special characters within the value of a parameter, such as whitespace or any of the above symbols, you can do so by placing the parameter within double quotes:
[ssl] # Whitespace is legal within double quotes ... server_certificate = "/etc/ssl/my certs/guacd.crt" # ... as are other special symbols server_key = "/etc/ssl/#private/guacd.key"
Note that even within double quotes, some characters still have special meaning, such as the double quote itself or newline characters. If you need to include these, they must be "escaped" with a backslash:
# Parameter value containing a double quote parameter = "some\"value" # Parameter value containing newline characters parameter2 = "line1\ line2\ line3" # Parameter value containing backslashes parameter3 = "c:\\windows\\path\\to\\file.txt"
Don't worry too much about the more complex formatting examples - they are only rarely necessary, and guacd will complain with parsing errors if the configuration file is somehow invalid. To ensure parameter values are entered correctly, just follow the following guidelines:
If the value contains no special characters, just include it as-is.
If the value contains any special characters (whitespace, newlines,
#,\, or"), enclose the entire value within double quotes.If the value is enclosed within double quotes, escape newlines,
\, and"with a backslash.
Table 5.1. guacd.conf parameters
You can also affect the configuration of guacd with command-line options. If given, these options take precendence over the system-wide configuration file:
-bHOSTChanges the host or address that guacd listens on.
This corresponds to the
bind_hostparameter within theserversection ofguacd.conf.-lPORTChanges the port that guacd listens on (the default is port 4822).
This corresponds to the
bind_portparameter within theserversection ofguacd.conf.-pPIDFILECauses guacd to write the PID of the daemon process to the specified file. This is useful for init scripts and is used by the provided init script.
This corresponds to the
pid_fileparameter within thedaemonsection ofguacd.conf.-LLEVELSets the maximum level at which guacd will log messages to syslog and, if running in the foreground, the console. Legal values are
trace,debug,info,warning, anderror. The default value isinfo.This corresponds to the
log_levelparameter within thedaemonsection ofguacd.conf.-fCauses 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:
-CCERTIFICATEThe filename of the certificate to use for SSL encryption of the Guacamole protocol. If this option is specified, SSL encryption will be enabled, and the Guacamole web application will need to be configured within
guacamole.propertiesto use SSL as well.This corresponds to the
server_certificateparameter within thesslsection ofguacd.conf.-KKEYThe filename of the private key to use for SSL encryption of the Guacamole protocol. If this option is specified, SSL encryption will be enabled, and the Guacamole web application will need to be configured within
guacamole.propertiesto use SSL as well.This corresponds to the
server_keyparameter within thesslsection ofguacd.conf.