Google Git
Sign in
apache / guacamole-manual / d554d94f8310b589f7f22cd2438bfb90dec6624a / . / src / chapters / configuring.xml
blob: a28e4c348079d1a3607944fe46a177241cab5d92 [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<chapter xml:id="configuring-guacamole"
xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en"
xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Configuring Guacamole</title>
<para>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.</para>
<para>Guacamole's default authentication method reads all users and connections from a single
file called <filename>user-mapping.xml</filename>. This authentication method is intended to
be:</para>
<orderedlist>
<listitem>
<para>Sufficient for small deployments of Guacamole.</para>
</listitem>
<listitem>
<para>A relatively-easy means of verifying that Guacamole has been properly set
up.</para>
</listitem>
</orderedlist>
<para>Other, more complex authentication methods which use backend databases, LDAP, etc. are
discussed in a separate, dedicated chapters.</para>
<para>Regardless of the authentication method you use, Guacamole's configuration always consists
of two main pieces: a directory referred to as <varname>GUACAMOLE_HOME</varname>, which is
the primary search location for configuration files, and
<filename>guacamole.properties</filename>, the main configuration file used by Guacamole
and its extensions.</para>
<section xml:id="guacamole-home">
<title><varname>GUACAMOLE_HOME</varname> (<filename>/etc/guacamole</filename>)</title>
<indexterm xmlns:xl="http://www.w3.org/1999/xlink">
<primary><varname>GUACAMOLE_HOME</varname></primary>
</indexterm>
<para><varname>GUACAMOLE_HOME</varname> is the name given to Guacamole's configuration
directory, which is located at <filename>/etc/guacamole</filename> by default. All
configuration files, extensions, etc. reside within this directory. The structure of
<varname>GUACAMOLE_HOME</varname> is rigorously defined, and consists of the
following optional files:</para>
<variablelist>
<varlistentry>
<term><filename>guacamole.properties</filename></term>
<listitem>
<para>The main Guacamole configuration file. Properties within this file dictate
how Guacamole will connect to <package>guacd</package>, and may configure
the behavior of installed authentication extensions.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>logback.xml</filename></term>
<listitem>
<para>Guacamole uses a logging system called Logback for all messages. By
default, Guacamole will log to the console only, but you can change this by
providing your own Logback configuration file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>extensions/</filename></term>
<listitem>
<para>The install location for all Guacamole extensions. Guacamole will
automatically load all <filename>.jar</filename> files within this directory
on startup.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>lib/</filename></term>
<listitem>
<para>The search directory for libraries required by any Guacamole extensions.
Guacamole will make the <filename>.jar</filename> files within this
directory available to all extensions. If your extensions require additional
libraries, such as database drivers, this is the proper place to put
them.</para>
</listitem>
</varlistentry>
</variablelist>
<section xml:id="overriding-guacamole-home">
<title>Overriding <varname>GUACAMOLE_HOME</varname></title>
<para>If you cannot or do not wish to use <filename>/etc/guacamole</filename> for
<varname>GUACAMOLE_HOME</varname>, the location can be overridden through any of
the following methods:</para>
<orderedlist>
<listitem>
<para>Creating a directory named <filename>.guacamole</filename>, within the
home directory of <emphasis>the user running the servlet
container</emphasis>. This directory will automatically be used for
<varname>GUACAMOLE_HOME</varname> if it exists.</para>
</listitem>
<listitem>
<para>Specifying the full path to an alternative directory with the environment
variable <varname>GUACAMOLE_HOME</varname>. <emphasis>Be sure to consult the
documentation for your servlet container to determine how to properly
set environment variables.</emphasis></para>
</listitem>
<listitem>
<para>Specifying the full path to an alternative directory with the system
property <property>guacamole.home</property>.</para>
</listitem>
</orderedlist>
</section>
</section>
<section xml:id="initial-setup">
<title><filename>guacamole.properties</filename></title>
<indexterm xmlns:xl="http://www.w3.org/1999/xlink">
<primary><filename>guacamole.properties</filename></primary>
</indexterm>
<indexterm xmlns:xl="http://www.w3.org/1999/xlink">
<primary>configuration</primary>
</indexterm>
<para>The Guacamole web application uses one main configuration file called
<filename>guacamole.properties</filename>. This file is the common location for all
configuration properties read by Guacamole or any extension of Guacamole, including
authentication providers.</para>
<para>In previous releases, this file had to be in the classpath of your servlet container.
Now, the location of <filename>guacamole.properties</filename> can be explicitly defined
with environment variables or system properties, and the classpath is only used as a
last resort. When searching for <filename>guacamole.properties</filename>, Guacamole
will check, in order:</para>
<orderedlist>
<listitem>
<para>Within <varname>GUACAMOLE_HOME</varname>, as defined above.</para>
</listitem>
<listitem>
<para>The classpath of the servlet container.</para>
</listitem>
</orderedlist>
<para>The <filename>guacamole.properties</filename> 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:</para>
<variablelist>
<varlistentry>
<term><indexterm xmlns:xl="http://www.w3.org/1999/xlink">
<primary>api-session-timeout</primary>
</indexterm><parameter>api-session-timeout</parameter></term>
<listitem>
<para>The 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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><indexterm xmlns:xl="http://www.w3.org/1999/xlink">
<primary>available-languages</primary>
</indexterm><parameter>available-languages</parameter></term>
<listitem>
<para>A 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:</para>
<informalexample>
<programlisting>available-languages: en, de</programlisting>
</informalexample>
<para>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.</para>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><indexterm xmlns:xl="http://www.w3.org/1999/xlink">
<primary>enable-environment-properties</primary>
</indexterm><parameter>enable-environment-properties</parameter></term>
<listitem>
<para>If set to "true", Guacamole will first evaluate its environment to obtain
the value for any given configuration property, before using a value specified
in <filename>guacamole.properties</filename> or falling back to a default
value. By enabling this option, you can easily override any other configuration
property using an environment variable.</para>
<informalexample>
<programlisting>enable-environment-properties: true</programlisting>
</informalexample>
<para>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 (<code>-</code>) with
underscore characters (<code>_</code>). For example, the
<parameter>guacd-hostname</parameter> property would be transformed to
<parameter>GUACD_HOSTNAME</parameter> when searching the environment.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><indexterm xmlns:xl="http://www.w3.org/1999/xlink">
<primary>guacd-hostname</primary>
</indexterm><parameter>guacd-hostname</parameter></term>
<listitem>
<para>The host the Guacamole proxy daemon (<package>guacd</package>) is
listening on. If omitted, Guacamole will assume <package>guacd</package> is
listening on localhost.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><indexterm xmlns:xl="http://www.w3.org/1999/xlink">
<primary>guacd-port</primary>
</indexterm><parameter>guacd-port</parameter></term>
<listitem>
<para>The port the Guacamole proxy daemon (<package>guacd</package>) is
listening on. If omitted, Guacamole will assume <package>guacd</package> is
listening on port 4822.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><indexterm xmlns:xl="http://www.w3.org/1999/xlink">
<primary>guacd-ssl</primary>
</indexterm><parameter>guacd-ssl</parameter></term>
<listitem>
<para>If set to "true", Guacamole will require SSL/TLS encryption between the
web application and <package>guacd</package>. By default, communication
between the web application and <package>guacd</package> will be
unencrypted.</para>
<para>Note that if you enable this option, you must also configure
<package>guacd</package> to use SSL via command line options. These
options are documented in the manpage of <package>guacd</package>. You will
need an SSL certificate and private key.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><indexterm xmlns:xl="http://www.w3.org/1999/xlink">
<primary>skip-if-unavailable</primary>
</indexterm><parameter>skip-if-unavailable</parameter></term>
<listitem>
<para>A comma-separated list of the identifiers of authentication providers that
should be allowed to fail internally without aborting the authentication
process. For example, to request that Guacamole ignore failures due to the
LDAP directory or MySQL server being unexpectedly down, allowing other
authentication providers to continue functioning:</para>
<informalexample>
<programlisting>skip-if-unavailable: mysql, ldap</programlisting>
</informalexample>
<para>By default, Guacamole takes a conservative approach to internal failures,
aborting the authentication process if an internal error occurs within any
authentication provider. Depending on the nature of the error, this may mean
that no users can log in until the cause of the failure is dealt with. The
<parameter>skip-if-unavailable</parameter> property may be used to
explicitly inform Guacamole that one or more underlying systems are expected
to occasionally experience failures, and that other functioning systems
should be relied upon if they do fail.</para>
</listitem>
</varlistentry>
</variablelist>
<example>
<title>Example <filename>guacamole.properties</filename></title>
<programlisting xml:id="guacamole.properties" version="5.0" xml:lang="en"># Hostname and port of guacamole proxy
guacd-hostname: localhost
guacd-port: 4822</programlisting>
</example>
</section>
<section xml:id="webapp-logging">
<title>Logging within the web application</title>
<indexterm>
<primary>logging</primary>
</indexterm>
<para>By default, Guacamole logs all messages to the console. Servlet containers like Tomcat
will automatically redirect these messages to a log file,
<filename>catalina.out</filename> 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:</para>
<variablelist>
<varlistentry>
<term><indexterm>
<primary>logging</primary>
<secondary>errors</secondary>
</indexterm><constant>error</constant></term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><indexterm>
<primary>logging</primary>
<secondary>warnings</secondary>
</indexterm><constant>warn</constant></term>
<listitem>
<para>Warnings are generally non-fatal conditions. The operation continued, but
encountered noteworthy problems.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><indexterm>
<primary>logging</primary>
<secondary>info</secondary>
</indexterm><constant>info</constant></term>
<listitem>
<para>"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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><indexterm>
<primary>logging</primary>
<secondary>debug</secondary>
</indexterm><constant>debug</constant></term>
<listitem>
<para>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. It is expected that debug
messages, though verbose, will not affect performance.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><indexterm>
<primary>logging</primary>
<secondary>trace</secondary>
</indexterm><constant>trace</constant></term>
<listitem>
<para>Trace 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.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Guacamole logs messages using a logging framework called <link
xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://logback.qos.ch/"
>Logback</link> and, by default, will only log messages at the
"<constant>info</constant>" 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
<filename>logback.xml</filename> file within <varname>GUACAMOLE_HOME</varname>. For
example, to log all messages to the console, even "<constant>debug</constant>" messages,
you might use the following <filename>logback.xml</filename>:</para>
<informalexample>
<programlisting>&lt;configuration>
&lt;!-- Appender for debugging -->
&lt;appender name="GUAC-DEBUG" class="ch.qos.logback.core.ConsoleAppender">
&lt;encoder>
&lt;pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n&lt;/pattern>
&lt;/encoder>
&lt;/appender>
&lt;!-- Log at DEBUG level -->
&lt;root level="debug">
&lt;appender-ref ref="GUAC-DEBUG"/>
&lt;/root>
&lt;/configuration></programlisting>
</informalexample>
<para>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.</para>
<para>More thorough <link xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="http://logback.qos.ch/manual/configuration.html">documentation on
configuring Logback</link> is provided on the Logback project's web site.</para>
</section>
<section xml:id="basic-auth">
<title>Using the default authentication</title>
<indexterm>
<primary>authentication</primary>
</indexterm>
<para>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.</para>
<para>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,
<package>guacamole-ext</package>.</para>
<section xml:id="user-mapping">
<title><filename>user-mapping.xml</filename></title>
<indexterm>
<primary>user-mapping.xml</primary>
</indexterm>
<para>The default authentication provider used by Guacamole reads all username,
password, and configuration information from a file called the "user mapping"
located at <filename>GUACAMOLE_HOME/user-mapping.xml</filename>. An example of a
user mapping file is included with Guacamole, and looks something like this:</para>
<programlisting>&lt;user-mapping>
&lt;!-- Per-user authentication and config information -->
&lt;authorize username="USERNAME" password="PASSWORD">
&lt;protocol>vnc&lt;/protocol>
&lt;param name="hostname">localhost&lt;/param>
&lt;param name="port">5900&lt;/param>
&lt;param name="password">VNCPASS&lt;/param>
&lt;/authorize>
&lt;!-- Another user, but using md5 to hash the password
(example below uses the md5 hash of "PASSWORD") -->
&lt;authorize
username="USERNAME2"
password="319f4d26e3c536b5dd871bb2c52e3178"
encoding="md5">
&lt;!-- First authorized connection -->
&lt;connection name="localhost">
&lt;protocol>vnc&lt;/protocol>
&lt;param name="hostname">localhost&lt;/param>
&lt;param name="port">5901&lt;/param>
&lt;param name="password">VNCPASS&lt;/param>
&lt;/connection>
&lt;!-- Second authorized connection -->
&lt;connection name="otherhost">
&lt;protocol>vnc&lt;/protocol>
&lt;param name="hostname">otherhost&lt;/param>
&lt;param name="port">5900&lt;/param>
&lt;param name="password">VNCPASS&lt;/param>
&lt;/connection>
&lt;/authorize>
&lt;/user-mapping></programlisting>
<para>Each user is specified with a corresponding
<code>&lt;authorize></code> tag. This tag contains all
authorized connections for that user, each denoted with a
<code>&lt;connection></code> tag. Each
<code>&lt;connection></code> tag contains a corresponding
protocol and set of protocol-specific parameters, specified with
the <code>&lt;protocol></code> and <code>&lt;param></code> tags
respectively.</para>
<section xml:id="user-setup">
<title>Adding users</title>
<indexterm>
<primary>users</primary>
<secondary>adding</secondary>
</indexterm>
<para>When using
<classname>BasicFileAuthenticationProvider</classname>,
username/password pairs are specified with
<code>&lt;authorize></code> tags, which each have a
<code>username</code> and <code>password</code>
attribute. Each <code>&lt;authorize></code> tag authorizes a
specific username/password pair to access all connections
within the tag:</para>
<programlisting>&lt;authorize username="<replaceable>USER</replaceable>" password="<replaceable>PASS</replaceable>">
...
&lt;/authorize></programlisting>
<para>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:</para>
<programlisting>&lt;authorize username="<replaceable>USER</replaceable>"
password="<replaceable>319f4d26e3c536b5dd871bb2c52e3178</replaceable>"
encoding="md5">
...
&lt;/authorize></programlisting>
<para>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.</para>
</section>
<section xml:id="connection-setup">
<title>Adding connections to a user</title>
<indexterm>
<primary>connections</primary>
<secondary>adding</secondary>
</indexterm>
<para>To specify a connection within an
<code>&lt;authorize></code> tag, you can either list a
single protocol and set of parameters (specified with a
<code>&lt;protocol></code> tag and any number of
<code>&lt;param></code> 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
<code>&lt;connection></code> tags, each of which can be
named and contains a <code>&lt;protocol></code> tag and any
number of <code>&lt;param></code> tags.</para>
</section>
</section>
</section>
<section xml:id="connection-configuration">
<title xml:id="configuring-connections">Configuring connections</title>
<para>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.</para>
<section xml:id="vnc">
<title>VNC</title>
<indexterm>
<primary>VNC</primary>
</indexterm>
<para>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.</para>
<para>VNC support for Guacamole is provided by the <package>libguac-client-vnc</package>
library, which will be installed as part of guacamole-server if the required
dependencies are present during the build.</para>
<section xml:id="vnc-network-parameters">
<title>Network parameters</title>
<para>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.</para>
<informaltable frame="all" xml:id="vnc-parameters">
<indexterm>
<primary>parameters</primary>
<secondary>VNC</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>hostname</parameter></entry>
<entry>
<para><indexterm>
<primary>VNC</primary>
<secondary>hostname</secondary>
</indexterm>The hostname or IP address of the VNC server
Guacamole should connect to.</para>
</entry>
</row>
<row>
<entry><parameter>port</parameter></entry>
<entry>
<para><indexterm>
<primary>VNC</primary>
<secondary>port</secondary>
</indexterm>The port the VNC server is listening on, usually
5900 or 5900 + <replaceable>display number</replaceable>.
For example, if your VNC server is serving display number 1
(sometimes written as <constant>:1</constant>), your port
number here would be 5901.</para>
</entry>
</row>
<row>
<entry><parameter>autoretry</parameter></entry>
<entry>
<para><indexterm>
<primary>VNC</primary>
<secondary>retrying connections</secondary>
</indexterm>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.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="vnc-authentication">
<title>Authentication</title>
<para>The VNC standard defines only password based authentication. Other
authentication mechanisms exist, but are non-standard or proprietary. Guacamole
currently supports both standard password-only based authentication, as well
as username and password authentication.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>VNC</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>username</parameter></entry>
<entry>
<para><indexterm>
<primary>VNC</primary>
<secondary>username</secondary>
</indexterm>The username to use when attempting
authentication, if any. This parameter is optional.</para>
</entry>
</row>
<row>
<entry><parameter>password</parameter></entry>
<entry>
<para><indexterm>
<primary>VNC</primary>
<secondary>password</secondary>
</indexterm>The password to use when attempting
authentication, if any. This parameter is optional.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="vnc-display-settings">
<title>Display settings</title>
<para>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.</para>
<para>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.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>VNC</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>color-depth</parameter></entry>
<entry>
<para><indexterm>
<primary>VNC</primary>
<secondary>color depth</secondary>
</indexterm>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.</para>
</entry>
</row>
<row>
<entry><parameter>swap-red-blue</parameter></entry>
<entry>
<para>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.</para>
</entry>
</row>
<row>
<entry><parameter>cursor</parameter></entry>
<entry>
<para><indexterm>
<primary>VNC</primary>
<secondary>mouse pointer</secondary>
</indexterm>If set to "remote", the mouse pointer will be
rendered remotely, and the local position of the mouse
pointer will be indicated by a small dot. A remote mouse
cursor will feel slower than a local cursor, but may be
necessary if the VNC server does not support sending the
cursor image to the client.</para>
</entry>
</row>
<row>
<entry><parameter>encodings</parameter></entry>
<entry>
<para><indexterm>
<primary>VNC</primary>
<secondary>encodings</secondary>
</indexterm>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
<package>libguac-client-vnc</package> will use any
supported encoding by default.</para>
<para>Beware that this parameter is intended to be replaced with
individual, encoding-specific parameters in a future
release.</para>
</entry>
</row>
<row>
<entry><parameter>read-only</parameter></entry>
<entry>
<para><indexterm>
<primary>VNC</primary>
<secondary>read-only</secondary>
</indexterm>Whether this connection should be read-only. If
set to "true", no input will be accepted on the connection
at all. Users will only see the desktop and whatever other
users using that same desktop are doing. This parameter is
optional.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="vnc-recording">
<title>Session recording</title>
<para>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 <command>guacenc</command> utility provided with
guacamole-server.</para>
<para>For example, to produce a video called "<replaceable>NAME</replaceable>.m4v"
from the recording "<replaceable>NAME</replaceable>", you would run:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>guacenc <replaceable>/path/to/recording/NAME</replaceable></userinput></screen>
</informalexample>
<para>The <command>guacenc</command> utility has additional options for overriding
default behavior, including tweaking the output format, which are documented in
detail within the manpage:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>man guacenc</userinput></screen>
</informalexample>
<para>If recording of key events is explicitly enabled using the
<parameter>recording-include-keys</parameter> parameter, recordings can also
be translated into human-readable interpretations of the keys pressed during the
session using the <command>guaclog</command> utility. The usage of
<command>guaclog</command> is analogous to <command>guacenc</command>, and
results in the creation of a new text file containing the interpreted
events:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>guaclog <replaceable>/path/to/recording/NAME</replaceable></userinput><computeroutput>
guaclog: INFO: Guacamole input log interpreter (guaclog) version 1.1.0
guaclog: INFO: 1 input file(s) provided.
guaclog: INFO: Writing input events from "<replaceable>/path/to/recording/NAME</replaceable>" to "<replaceable annotations="">/path/to/recording/NAME</replaceable>.txt" ...
guaclog: INFO: All files interpreted successfully.</computeroutput>
<prompt>$</prompt> </screen>
</informalexample>
<important>
<para>Guacamole will never overwrite an existing recording. If necessary, a
numeric suffix like ".1", ".2", ".3", etc. will be appended to
<replaceable>NAME</replaceable> to avoid overwriting an existing
recording. If even appending a numeric suffix does not help, the session
will simply not be recorded.</para>
</important>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>VNC</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>recording-path</parameter></entry>
<entry>
<para><indexterm>
<primary>VNC</primary>
<secondary>graphical recording</secondary>
</indexterm>The directory in which screen recording files
should be created. <emphasis>If a graphical recording needs
to be created, then this parameter is
required.</emphasis> Specifying this parameter enables
graphical screen recording. If this parameter is omitted, no
graphical recording will be created.</para>
</entry>
</row>
<row>
<entry><parameter>create-recording-path</parameter></entry>
<entry>
<para>If set to "true", the directory specified by the
<parameter>recording-path</parameter> parameter will
automatically be created if it does not yet exist. Only the
final directory in the path will be created - if other
directories earlier in the path do not exist, automatic
creation will fail, and an error will be logged.</para>
<para><emphasis>This parameter is optional.</emphasis> By
default, the directory specified by the
<parameter>recording-path</parameter> parameter will not
automatically be created, and attempts to create recordings
within a non-existent directory will be logged as
errors.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-name</parameter></entry>
<entry>
<para>The filename to use for any created recordings.
<emphasis>This parameter is optional.</emphasis> If
omitted, the value "recording" will be used instead.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-exclude-output</parameter></entry>
<entry>
<para>If set to "true", graphical output and other data normally
streamed from server to client will be excluded from the
recording, producing a recording which contains only user
input events. <emphasis>This parameter is
optional.</emphasis> If omitted, graphical output will
be included in the recording.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-exclude-mouse</parameter></entry>
<entry>
<para>If set to "true", user mouse events will be excluded from
the recording, producing a recording which lacks a visible
mouse cursor. <emphasis>This parameter is
optional.</emphasis> If omitted, mouse events will be
included in the recording.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-include-keys</parameter></entry>
<entry>
<para>If set to "true", user key events will be included in the
recording. The recording can subsequently be passed through
the <command>guaclog</command> utility to produce a
human-readable interpretation of the keys pressed during the
session. <emphasis>This parameter is optional.</emphasis> If
omitted, key events will be not included in the
recording.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="vnc-sftp">
<title>File transfer (via SFTP)</title>
<para>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 <xref
linkend="using-guacamole"/>.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>VNC</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>enable-sftp</parameter></entry>
<entry>
<para><indexterm>
<primary>VNC</primary>
<secondary>file transfer</secondary>
</indexterm><indexterm>
<primary>SFTP</primary>
</indexterm>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.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-hostname</parameter></entry>
<entry>
<para>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
<parameter>hostname</parameter> parameter will be
used.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-port</parameter></entry>
<entry>
<para>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.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-host-key</parameter></entry>
<entry>
<para>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.</para>
<para>The format of this parameter should be that of a single
entry from an OpenSSH <filename>known_hosts</filename>
file.</para>
<para>For more information, please see <xref linkend="ssh-host-verification"/>.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-username</parameter></entry>
<entry>
<para>The username to authenticate as when connecting to the
specified SSH server for SFTP. This parameter is
required.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-password</parameter></entry>
<entry>
<para>The password to use when authenticating with the specified
SSH server for SFTP.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-private-key</parameter></entry>
<entry>
<para>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 <command>ssh-keygen</command> utility.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-passphrase</parameter></entry>
<entry>
<para>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.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-directory</parameter></entry>
<entry>
<para>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.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-root-directory</parameter></entry>
<entry>
<para>The directory to expose to connected users via Guacamole's
<link xmlns:xlink="http://www.w3.org/1999/xlink"
linkend="file-browser">file browser</link>. If omitted,
the root directory will be used by default.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-server-alive-interval</parameter></entry>
<entry>
<para>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.
</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="vnc-repeater">
<title>VNC Repeater</title>
<para>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.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>VNC</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>dest-host</parameter></entry>
<entry><indexterm>
<primary>repeater</primary>
<secondary>VNC</secondary>
</indexterm><indexterm>
<primary>proxy</primary>
<secondary>VNC</secondary>
</indexterm><indexterm>
<primary>VNC</primary>
<secondary>repeater</secondary>
</indexterm>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.</entry>
</row>
<row>
<entry><parameter>dest-port</parameter></entry>
<entry><indexterm>
<primary>repeater</primary>
<secondary>VNC</secondary>
</indexterm><indexterm>
<primary>proxy</primary>
<secondary>VNC</secondary>
</indexterm>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.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="vnc-reverse-connections">
<title>Reverse VNC connections</title>
<para>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.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>VNC</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>reverse-connect</parameter></entry>
<entry>
<para><indexterm>
<primary>VNC</primary>
<secondary>reverse connection</secondary>
</indexterm>Whether reverse connection should be used. If
set to "true", instead of connecting to a server at a given
hostname and port, guacd will listen on the given port for
inbound connections from a VNC server.</para>
</entry>
</row>
<row>
<entry><parameter>listen-timeout</parameter></entry>
<entry>
<para><indexterm>
<primary>VNC</primary>
<secondary>listen timeout</secondary>
</indexterm>If reverse connection is in use, the maximum
amount of time to wait for an inbound connection from a VNC
server, in milliseconds. If blank, the default value is 5000
(five seconds).</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="vnc-audio">
<title>Audio support (via PulseAudio)</title>
<para>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.</para>
<para>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.</para>
<para>Configuring PulseAudio for network connections requires an additional line
within the PulseAudio configuration file, usually
<filename>/etc/pulse/default.pa</filename>:</para>
<informalexample>
<programlisting>load-module module-native-protocol-tcp auth-ip-acl=<replaceable>192.168.1.0/24</replaceable> auth-anonymous=1</programlisting>
</informalexample>
<para>This loads the TCP module for PulseAudio, configuring it to accept connections
without authentication and <emphasis>only</emphasis> from the
<replaceable>192.168.1.0/24</replaceable> 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:</para>
<informalexample>
<programlisting>load-module module-native-protocol-tcp auth-anonymous=1</programlisting>
</informalexample>
<para>In either case, the <code>auth-anonymous=1</code> 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.</para>
<para>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 <command>netstat</command>:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>netstat -ln | grep 4713</userinput>
<computeroutput>tcp 0 0 0.0.0.0:4713 0.0.0.0:* LISTEN
tcp6 0 0 :::4713 :::* LISTEN</computeroutput>
<prompt>$</prompt></screen>
</informalexample>
<para>The following parameters are available for configuring the audio support for
VNC:</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>VNC</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>enable-audio</parameter></entry>
<entry>
<para><indexterm>
<primary>VNC</primary>
<secondary>sound</secondary>
</indexterm><indexterm>
<primary>VNC</primary>
<secondary>PulseAudio</secondary>
</indexterm>If set to "true", audio support will be enabled,
and a second connection for PulseAudio will be made in
addition to the VNC connection. By default, audio support
within VNC is disabled.</para>
</entry>
</row>
<row>
<entry><parameter>audio-servername</parameter></entry>
<entry>
<para>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 <parameter>hostname</parameter>
parameter.</para>
<para>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.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="vnc-clipboard-encoding">
<title>Clipboard encoding</title>
<para>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
<parameter>clipboard-encoding</parameter> parameter.</para>
<important>
<para><emphasis>The only clipboard encoding guaranteed to be supported by VNC
servers is ISO 8859-1.</emphasis> You should only override the clipboard
encoding using the <parameter>clipboard-encoding</parameter> parameter of
you are absolutely positive your VNC server supports other encodings.</para>
</important>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>VNC</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>clipboard-encoding</parameter></entry>
<entry>
<para><indexterm>
<primary>clipboard encoding</primary>
</indexterm><indexterm>
<primary>VNC</primary>
<secondary>clipboard encoding</secondary>
</indexterm>The encoding to assume for the VNC clipboard.
This parameter is optionl. By default, the standard encoding
ISO 8859-1 will be used. <emphasis>Only use this parameter
if you are sure your VNC server supports other encodings
beyond the standard ISO 8859-1.</emphasis></para>
<para>Possible values are:</para>
<variablelist>
<varlistentry>
<term><constant>ISO8859-1</constant></term>
<listitem>
<para>ISO 8859-1 is the clipboard encoding mandated
by the VNC standard, and supports only basic Latin
characters. Unless your VNC server specifies
otherwise, this encoding is the only encoding
guaranteed to work.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>UTF-8</constant></term>
<listitem>
<para>UTF-8 - the most common encoding used for
Unicode. Using this encoding for the VNC clipboard
violates the VNC specification, but some servers
do support this. This parameter value should only
be used if you know your VNC server supports this
encoding.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>UTF-16</constant></term>
<listitem>
<para>UTF-16 - a 16-bit encoding for Unicode which
is not as common as UTF-8, but still widely used.
Using this encoding for the VNC clipboard violates
the VNC specification. This parameter value should
only be used if you know your VNC server supports
this encoding.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>CP1252</constant></term>
<listitem>
<para>Code page 1252 - a Windows-specific encoding
for Latin characters which is mostly a superset of
ISO 8859-1, mapping some additional displayable
characters onto what would otherwise be control
characters. Using this encoding for the VNC
clipboard violates the VNC specification. This
parameter value should only be used if you know
your VNC server supports this encoding.</para>
</listitem>
</varlistentry>
</variablelist>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="vnc-disable-clipboard">
<title>Disabling clipboard access</title>
<para>Guacamole provides bidirectional access to the clipboard by default for VNC
connections. This behavior can be overridden on a per-connection basis with the
<parameter>disable-copy</parameter> and <parameter>disable-paste</parameter>
parameters.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>VNC</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>disable-copy</parameter></entry>
<entry>
<para><indexterm>
<primary>disable clipboard</primary>
</indexterm><indexterm>
<primary>VNC</primary>
<secondary>disable clipboard</secondary>
</indexterm>If set to "true", text copied within the VNC
session will not be accessible by the user at the browser
side of the Guacamole session, and will be usable only
within the remote desktop. This parameter is optional. By
default, the user will be given access to the copied
text.</para>
</entry>
</row>
<row>
<entry><parameter>disable-paste</parameter></entry>
<entry>
<para><indexterm>
<primary>disable clipboard</primary>
</indexterm><indexterm>
<primary>VNC</primary>
<secondary>disable clipboard</secondary>
</indexterm>If set to "true", text copied at the browser
side of the Guacamole session will not be accessible within
the VNC session. This parameter is optional. By default, the
user will be able to paste data from outside the browser
within the VNC session.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="adding-vnc">
<title>Adding a VNC connection</title>
<indexterm>
<primary>VNC</primary>
<secondary>adding</secondary>
</indexterm>
<para>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
<code>&lt;authorize></code> section for that user within your
<filename>user-mapping.xml</filename>, and add a section like the following
within it:</para>
<programlisting>&lt;connection name="<replaceable>Unique Name</replaceable>">
&lt;protocol>vnc&lt;/protocol>
&lt;param name="hostname"><replaceable>localhost</replaceable>&lt;/param>
&lt;param name="port"><replaceable>5901</replaceable>&lt;/param>
&lt;/connection></programlisting>
<para>If added exactly as above, a new connection named "<replaceable>Unique
Name</replaceable>" will be available to the user associated with the
<code>&lt;authorize></code> section containing it. The connection will use
VNC to connect to <replaceable>localhost</replaceable> at port
<replaceable>5901</replaceable>. Naturally, you will want to change some or
all of these values.</para>
<para>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 <code>&lt;param></code> tags accordingly.</para>
<para>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.</para>
</section>
<section xml:id="vnc-servers">
<title>Which VNC server?</title>
<indexterm>
<primary>VNC servers</primary>
</indexterm>
<para>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.</para>
<section xml:id="realvnc">
<title>RealVNC or TigerVNC</title>
<indexterm>
<primary>RealVNC</primary>
</indexterm>
<indexterm>
<primary>TigerVNC</primary>
</indexterm>
<para>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.</para>
</section>
<section xml:id="tightvnc">
<title>TightVNC</title>
<indexterm>
<primary>TightVNC</primary>
</indexterm>
<para>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.</para>
</section>
<section xml:id="x11vnc">
<title>x11vnc</title>
<indexterm>
<primary>x11vnc</primary>
</indexterm>
<para>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.</para>
</section>
<section xml:id="vino">
<title>vino</title>
<indexterm>
<primary>vino</primary>
</indexterm>
<para>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.</para>
</section>
<section xml:id="qemu">
<title>QEMU or KVM</title>
<indexterm>
<primary>QEMU</primary>
</indexterm>
<indexterm>
<primary>KVM</primary>
</indexterm>
<para>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.</para>
<para>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.</para>
</section>
</section>
</section>
<section xml:id="rdp">
<title>RDP</title>
<indexterm>
<primary>RDP</primary>
</indexterm>
<para>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.</para>
<para>RDP support for Guacamole is provided by the <package>libguac-client-rdp</package>
library, which will be installed as part of guacamole-server if the required
dependencies are present during the build.</para>
<section xml:id="rdp-network-parameters">
<title>Network parameters</title>
<para>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.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>RDP</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>hostname</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>hostname</secondary>
</indexterm>The hostname or IP address of the RDP server
Guacamole should connect to.</para>
</entry>
</row>
<row>
<entry><parameter>port</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>port</secondary>
</indexterm>The port the RDP server is listening on, usually
3389. This parameter is optional. If this is not specified,
the default of 3389 will be used.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="rdp-authentication">
<title>Authentication and security</title>
<para>RDP provides authentication through the use of a username, password, and
optional domain.</para>
<para>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 <emphasis>must</emphasis> provide a username and password.</para>
<para>All RDP connections are encrypted. Higher-grade encryption is available in the
form of TLS, another possible security mode.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>RDP</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>username</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>username</secondary>
</indexterm>The username to use to authenticate, if any.
This parameter is optional.</para>
</entry>
</row>
<row>
<entry><parameter>password</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>password</secondary>
</indexterm>The password to use when attempting
authentication, if any. This parameter is optional.</para>
</entry>
</row>
<row>
<entry><parameter>domain</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>domain</secondary>
</indexterm>The domain to use when attempting
authentication, if any. This parameter is optional.</para>
</entry>
</row>
<row>
<entry><parameter>security</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>security</secondary>
</indexterm><indexterm>
<primary>RDP</primary>
<secondary>NLA</secondary>
</indexterm><indexterm>
<primary>RDP</primary>
<secondary>TLS</secondary>
</indexterm>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,
standard RDP encryption is requested, as it is the most
widely supported.</para>
<para>Possible values are:</para>
<variablelist>
<varlistentry>
<term><constant>rdp</constant></term>
<listitem>
<para>Standard RDP encryption. <emphasis>This is the
default</emphasis> and should be supported by all
RDP servers.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>nla</constant></term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>tls</constant></term>
<listitem>
<para>TLS encryption. TLS (Transport Layer Security)
is the successor to SSL.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>any</constant></term>
<listitem>
<para>Allow the server to choose the type of
security.</para>
</listitem>
</varlistentry>
</variablelist>
</entry>
</row>
<row>
<entry><parameter>ignore-cert</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>ignoring certificates</secondary>
</indexterm>If set to "true", the certificate returned by
the server will be ignored, even if that certificate cannot
be validated. This is useful if you universally trust the
server and your connection to the server, and you know that
the server's certificate cannot be validated (for example,
if it is self-signed).</para>
</entry>
</row>
<row>
<entry><parameter>disable-auth</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>disabling authentication</secondary>
</indexterm>If set to "true", authentication will be
disabled. Note that this refers to authentication that takes
place while connecting. Any authentication enforced by the
server over the remote desktop session (such as a login
dialog) will still take place. By default, authentication is
enabled and only used when requested by the server.</para>
<para>If you are using NLA, authentication must be enabled by
definition.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="rdp-session-settings">
<title>Session settings</title>
<para>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.</para>
<para>Although Guacamole is independent of keyboard layout, RDP is not. This is
because Guacamole represents keys based on what they <emphasis>do</emphasis>
("press the <keycap>Enter</keycap> 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.</para>
<para>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 <link xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="https://issues.apache.org/jira/browse/GUACAMOLE">opening an issue in
JIRA</link>.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>RDP</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>client-name</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>client-name</secondary>
</indexterm>When connecting to the RDP server, Guacamole
will normally provide its own hostname as the name of the
client. If this parameter is specified, Guacamole will use
its value instead.</para>
<para>On Windows RDP servers, this value is exposed within the
session as the <envar>CLIENTNAME</envar> environment
variable.</para>
</entry>
</row>
<row>
<entry><parameter>console</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>console</secondary>
</indexterm>If set to "true", you will be connected to the
console (admin) session of the RDP server.</para>
</entry>
</row>
<row>
<entry><parameter>initial-program</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>initial program</secondary>
</indexterm>The full path to the program to run immediately
upon connecting. This parameter is optional.</para>
</entry>
</row>
<row>
<entry><parameter>server-layout</parameter></entry>
<entry>
<para><indexterm>
<primary>keyboard layout</primary>
</indexterm><indexterm>
<primary>RDP</primary>
<secondary>keyboard layout</secondary>
</indexterm>The server-side keyboard layout. This is the
layout of the RDP server and has nothing to do with the
keyboard layout in use on the client. <emphasis>The
Guacamole client is independent of keyboard
layout.</emphasis> The RDP protocol, however, is
<emphasis>not</emphasis> 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.</para>
<para>Possible values are:</para>
<variablelist>
<varlistentry>
<term><constant>en-us-qwerty</constant></term>
<listitem>
<para>English (US) keyboard</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>en-gb-qwerty</constant></term>
<listitem>
<para>English (UK) keyboard</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>de-ch-qwertz</constant></term>
<listitem>
<para>Swiss German keyboard (qwertz)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>de-de-qwertz</constant></term>
<listitem>
<para>German keyboard (qwertz)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>fr-fr-azerty</constant></term>
<listitem>
<para>French keyboard (azerty)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>fr-ch-qwertz</constant></term>
<listitem>
<para>Swiss French keyboard (qwertz)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>hu-hu-qwertz</constant></term>
<listitem>
<para>Hungarian keyboard (qwertz)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>it-it-qwerty</constant></term>
<listitem>
<para>Italian keyboard</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>ja-jp-qwerty</constant></term>
<listitem>
<para>Japanese keyboard</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>pt-br-qwerty</constant></term>
<listitem>
<para>Portuguese Brazilian keyboard</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>es-es-qwerty</constant></term>
<listitem>
<para>Spanish keyboard</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>sv-se-qwerty</constant></term>
<listitem>
<para>Swedish keyboard</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>tr-tr-qwerty</constant></term>
<listitem>
<para>Turkish-Q keyboard</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>failsafe</constant></term>
<listitem>
<para>Unknown keyboard - this option sends only
Unicode events and should work for any keyboard,
though not necessarily all RDP servers or
applications.</para>
<para>If your server's keyboard layout is not yet
supported, this option should work in the
meantime.</para>
</listitem>
</varlistentry>
</variablelist>
</entry>
</row>
<row>
<entry><parameter>timezone</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>timezone</secondary>
</indexterm>The timezone that the client
should send to the server for configuring the
local time display of that server. The
format of the timezone is in the standard
IANA key zone format, which is the format
used in UNIX/Linux. This will be converted
by RDP into the correct format for Windows.
</para>
<para>The timezone is detected and will be
passed to the server during the handshake
phase of the connection, and may used by
protocols, like RDP, that support it. This
parameter can be used to override the value
detected and passed during the handshake, or
can be used in situations where guacd does
not support passing the timezone parameter
during the handshake phase (guacd versions
prior to 1.1.0).</para>
<para>Support for forwarding the client
timezone varies by RDP server implementation.
For example, with Windows, support for
forwarding timezones is only present in
Windows Server with Remote Desktop Services
(RDS, formerly known as Terminal Services)
installed. Windows Server installations in
admin mode, along with Windows workstation
versions, do not allow the timezone to be
forwarded. Other server implementations,
for example, xrdp, may not implement this
feature at all. Consult the documentation
for the RDP server to determine whether or
not this feature is supported.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="rdp-display-settings">
<title>Display settings</title>
<para>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.</para>
<para>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.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>RDP</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>color-depth</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>color depth</secondary>
</indexterm>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.</para>
</entry>
</row>
<row>
<entry><parameter>width</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>display size</secondary>
</indexterm>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.</para>
</entry>
</row>
<row>
<entry><parameter>height</parameter></entry>
<entry>
<para>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.</para>
</entry>
</row>
<row>
<entry><parameter>dpi</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>display resolution</secondary>
</indexterm>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.</para>
</entry>
</row>
<row>
<entry><parameter>resize-method</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>display size</secondary>
</indexterm>The method to use to update the RDP server when
the width or height of the client display changes. This
parameter is optional. If this value is not specified, no
action will be taken when the client display changes
size.</para>
<para>Normally, the display size of an RDP session is constant
and can only be changed when initially connecting. As of RDP
8.1, the "Display Update" channel can be used to request
that the server change the display size. For older RDP
servers, the only option is to disconnect and reconnect with
the new size.</para>
<para>Possible values are:</para>
<variablelist>
<varlistentry>
<term><constant>display-update</constant></term>
<listitem>
<para>Uses the "Display Update" channel added with
RDP 8.1 to signal the server when the client
display size has changed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>reconnect</constant></term>
<listitem>
<para>Automatically disconnects the RDP session when
the client display size has changed, and
reconnects with the new size.</para>
</listitem>
</varlistentry>
</variablelist>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="rdp-recording">
<title>Session recording</title>
<para>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 <command>guacenc</command> utility provided with
guacamole-server.</para>
<para>For example, to produce a video called "<replaceable>NAME</replaceable>.m4v"
from the recording "<replaceable>NAME</replaceable>", you would run:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>guacenc <replaceable>/path/to/recording/NAME</replaceable></userinput></screen>
</informalexample>
<para>The <command>guacenc</command> utility has additional options for overriding
default behavior, including tweaking the output format, which are documented in
detail within the manpage:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>man guacenc</userinput></screen>
</informalexample>
<para>If recording of key events is explicitly enabled using the
<parameter>recording-include-keys</parameter> parameter, recordings can also
be translated into human-readable interpretations of the keys pressed during the
session using the <command>guaclog</command> utility. The usage of
<command>guaclog</command> is analogous to <command>guacenc</command>, and
results in the creation of a new text file containing the interpreted
events:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>guaclog <replaceable>/path/to/recording/NAME</replaceable></userinput><computeroutput>
guaclog: INFO: Guacamole input log interpreter (guaclog) version 1.1.0
guaclog: INFO: 1 input file(s) provided.
guaclog: INFO: Writing input events from "<replaceable>/path/to/recording/NAME</replaceable>" to "<replaceable annotations="">/path/to/recording/NAME</replaceable>.txt" ...
guaclog: INFO: All files interpreted successfully.</computeroutput>
<prompt>$</prompt> </screen>
</informalexample>
<important>
<para>Guacamole will never overwrite an existing recording. If necessary, a
numeric suffix like ".1", ".2", ".3", etc. will be appended to
<replaceable>NAME</replaceable> to avoid overwriting an existing
recording. If even appending a numeric suffix does not help, the session
will simply not be recorded.</para>
</important>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>RDP</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>recording-path</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>graphical recording</secondary>
</indexterm>The directory in which screen recording files
should be created. <emphasis>If a graphical recording needs
to be created, then this parameter is
required.</emphasis> Specifying this parameter enables
graphical screen recording. If this parameter is omitted, no
graphical recording will be created.</para>
</entry>
</row>
<row>
<entry><parameter>create-recording-path</parameter></entry>
<entry>
<para>If set to "true", the directory specified by the
<parameter>recording-path</parameter> parameter will
automatically be created if it does not yet exist. Only the
final directory in the path will be created - if other
directories earlier in the path do not exist, automatic
creation will fail, and an error will be logged.</para>
<para><emphasis>This parameter is optional.</emphasis> By
default, the directory specified by the
<parameter>recording-path</parameter> parameter will not
automatically be created, and attempts to create recordings
within a non-existent directory will be logged as
errors.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-name</parameter></entry>
<entry>
<para>The filename to use for any created recordings.
<emphasis>This parameter is optional.</emphasis> If
omitted, the value "recording" will be used instead.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-exclude-output</parameter></entry>
<entry>
<para>If set to "true", graphical output and other data normally
streamed from server to client will be excluded from the
recording, producing a recording which contains only user
input events. <emphasis>This parameter is
optional.</emphasis> If omitted, graphical output will
be included in the recording.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-exclude-mouse</parameter></entry>
<entry>
<para>If set to "true", user mouse events will be excluded from
the recording, producing a recording which lacks a visible
mouse cursor. <emphasis>This parameter is
optional.</emphasis> If omitted, mouse events will be
included in the recording.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-include-keys</parameter></entry>
<entry>
<para>If set to "true", user key events will be included in the
recording. The recording can subsequently be passed through
the <command>guaclog</command> utility to produce a
human-readable interpretation of the keys pressed during the
session. <emphasis>This parameter is optional.</emphasis> If
omitted, key events will be not included in the
recording.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="rdp-device-redirection">
<title>Device redirection</title>
<para>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.</para>
<para>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.</para>
<para>Printing requires <application>GhostScript</application> 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.</para>
<para>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
<xref linkend="using-guacamole"/>.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>RDP</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>disable-audio</parameter></entry>
<entry><indexterm>
<primary>disabling audio</primary>
</indexterm><indexterm>
<primary>audio</primary>
</indexterm><indexterm>
<primary>RDP</primary>
<secondary>audio</secondary>
</indexterm>Audio is enabled by default in both the client and
in libguac-client-rdp. If you are concerned about bandwidth
usage, or sound is causing problems, you can explicitly disable
sound by setting this parameter to "true".</entry>
</row>
<row>
<entry><parameter>enable-audio-input</parameter></entry>
<entry>
<para><indexterm>
<primary>enabling audio input</primary>
</indexterm><indexterm>
<primary>audio input</primary>
</indexterm><indexterm>
<primary>RDP</primary>
<secondary>audio input</secondary>
</indexterm>If set to "true", audio input support
(microphone) will be enabled, leveraging the standard
"AUDIO_INPUT" channel of RDP. By default, audio input
support within RDP is disabled.</para>
</entry>
</row>
<row>
<entry><parameter>enable-printing</parameter></entry>
<entry>
<para><indexterm>
<primary>enabling printing</primary>
</indexterm><indexterm>
<primary>printing</primary>
</indexterm><indexterm>
<primary>RDP</primary>
<secondary>printing</secondary>
</indexterm>Printing is disabled by default, but with
printing enabled, RDP users can print to a virtual printer
that sends a PDF containing the document printed to the
Guacamole client. Enable printing by setting this parameter
to "true".</para>
<para><emphasis>Printing support requires
<application>GhostScript</application> to be
installed.</emphasis> If
<application>guacd</application> cannot find the
<filename>gs</filename> executable when printing, the
print attempt will fail.</para>
</entry>
</row>
<row>
<entry><parameter>printer-name</parameter></entry>
<entry>
<para>The name of the redirected printer device that is passed
through to the RDP session. This is the name that the user
will see in, for example, the Devices and Printers control
panel.</para>
<para>If printer redirection is not enabled, this option has no
effect.</para>
</entry>
</row>
<row>
<entry><parameter>enable-drive</parameter></entry>
<entry>
<para><indexterm>
<primary>enabling file transfer</primary>
</indexterm><indexterm>
<primary>file transfer</primary>
</indexterm><indexterm>
<primary>RDP</primary>
<secondary>file transfer</secondary>
</indexterm>File transfer is disabled by default, but with
file transfer enabled, RDP users can transfer files to and
from a virtual drive which persists on the Guacamole server.
Enable file transfer support by setting this parameter to
"true".</para>
<para>Files will be stored in the directory specified by the
"<parameter>drive-path</parameter>" parameter, which is
required if file transfer is enabled.</para>
</entry>
</row>
<row>
<entry><parameter>drive-name</parameter></entry>
<entry>
<para>The name of the filesystem used when passed through to
the RDP session. This is the name that users will see in their
Computer/My Computer area along with client name (for example,
"Guacamole on Guacamole RDP"), and is also the name of the share
when accessing the special <filename>\\tsclient</filename>
network location.</para>
<para>If file transfer is not enabled, this parameter is
ignored.</para>
</entry>
</row>
<row>
<entry><parameter>drive-path</parameter></entry>
<entry>
<para>The directory on the Guacamole server in which transferred
files should be stored. This directory must be accessible by
guacd and both readable and writable by the user that runs
guacd. <emphasis>This parameter does not refer to a
directory on the RDP server.</emphasis></para>
<para>If file transfer is not enabled, this parameter is
ignored.</para>
</entry>
</row>
<row>
<entry><parameter>create-drive-path</parameter></entry>
<entry>
<para>If set to "true", and file transfer is enabled, the
directory specified by the <parameter>drive-path</parameter>
parameter will automatically be created if it does not yet
exist. Only the final directory in the path will be created
- if other directories earlier in the path do not exist,
automatic creation will fail, and an error will be
logged.</para>
<para>By default, the directory specified by the
<parameter>drive-path</parameter> parameter will not
automatically be created, and attempts to transfer files to
a non-existent directory will be logged as errors.</para>
<para>If file transfer is not enabled, this parameter is
ignored.</para>
</entry>
</row>
<row>
<entry><parameter>console-audio</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>console audio</secondary>
</indexterm>If set to "true", audio will be explicitly
enabled in the console (admin) session of the RDP server.
Setting this option to "true" only makes sense if the
<parameter>console</parameter> parameter is also set to
"true".</para>
</entry>
</row>
<row>
<entry><parameter>static-channels</parameter></entry>
<entry>
<para>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.</para>
<para>Guacamole allows any number of static channels to be
opened, but protocol restrictions of RDP limit the size of
each channel name to 7 characters.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="rdp-preconnection-pdu">
<title>Preconnection PDU (Hyper-V)</title>
<para><indexterm>
<primary>preconnection PDU</primary>
</indexterm><indexterm>
<primary>Hyper-V</primary>
</indexterm>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 <link
xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="https://msdn.microsoft.com/en-us/library/cc242359.aspx">"Session
Selection Extension"</link> for the RDP protocol, and is implemented by
Microsoft's Hyper-V hypervisor.</para>
<para>If you are using Hyper-V, you will need to specify the ID of the destination
virtual machine within the <parameter>preconnection-blob</parameter> parameter.
This value can be determined using PowerShell:</para>
<informalexample>
<screen><computeroutput><prompt>PS C:\> </prompt></computeroutput><userinput>Get-VM <replaceable>VirtualMachineName</replaceable> | Select-Object Id
</userinput><computeroutput>
Id
--
ed272546-87bd-4db9-acba-e36e1a9ca20a
<prompt>PS C:\> </prompt></computeroutput></screen>
</informalexample>
<para>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.</para>
<para>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:</para>
<orderedlist>
<listitem>
<para>Set "<parameter>port</parameter>" to "<constant>2179</constant>", 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.</para>
</listitem>
<listitem>
<para>Specify both "<parameter>username</parameter>" and
"<parameter>password</parameter>" appropriately, and set
"<parameter>security</parameter>" to "<constant>nla</constant>" or
"<constant>any</constant>". 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.</para>
</listitem>
<listitem>
<para>If necessary, set "<parameter>ignore-cert</parameter>" to
"<constant>true</constant>". Hyper-V may use a self-signed
certificate.</para>
</listitem>
</orderedlist>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>RDP</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>preconnection-id</parameter></entry>
<entry>
<para><indexterm>
<primary>preconnection ID</primary>
</indexterm>The numeric ID of the RDP source. This is a
non-negative integer value dictating which of potentially
several logical RDP connections should be used. This
parameter is optional, and is only required if the RDP
server is documented as requiring it. <emphasis>If using
Hyper-V, this should be left blank.</emphasis></para>
</entry>
</row>
<row>
<entry><parameter>preconnection-blob</parameter></entry>
<entry>
<para><indexterm>
<primary>preconnection BLOB</primary>
</indexterm><indexterm>
<primary>Hyper-V</primary>
</indexterm>An arbitrary string which identifies the RDP
source - one of potentially several logical RDP connections
hosted by the same RDP server. This parameter is optional,
and is only required if the RDP server is documented as
requiring it, such as Hyper-V. In all cases, the meaning of
this parameter is opaque to the RDP protocol itself and is
dictated by the RDP server. <emphasis>For Hyper-V, this will
be the ID of the destination virtual
machine.</emphasis></para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="rdp-gateway">
<title>Remote desktop gateway</title>
<para><indexterm>
<primary>remote desktop gateway</primary>
</indexterm><indexterm>
<primary>TS gateway</primary>
</indexterm>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.</para>
<para><emphasis>This functionality is only available if Guacamole was built against
FreeRDP 1.1 or later.</emphasis> Older versions of FreeRDP do not have
support for RDP gateways.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>RDP</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>gateway-hostname</parameter></entry>
<entry>
<para><indexterm>
<primary>gateway hostname</primary>
</indexterm>The hostname of the remote desktop gateway that
should be used as an intermediary for the remote desktop
connection. <emphasis>If omitted, a gateway will not be
used.</emphasis></para>
</entry>
</row>
<row>
<entry><parameter>gateway-port</parameter></entry>
<entry>
<para><indexterm>
<primary>gateway port</primary>
</indexterm>The port of the remote desktop gateway that
should be used as an intermediary for the remote desktop
connection. By default, this will be "443".</para>
<para><emphasis>If using a version of FreeRDP prior to 1.2, this
setting has no effect.</emphasis> Older versions of
FreeRDP use a hard-coded value of "443". </para>
</entry>
</row>
<row>
<entry><parameter>gateway-username</parameter></entry>
<entry>
<para><indexterm>
<primary>gateway username</primary>
</indexterm>The username of the user authenticating with the
remote desktop gateway, if a gateway is being used. This is
not necessarily the same as the user actually using the
remote desktop connection.</para>
</entry>
</row>
<row>
<entry><parameter>gateway-password</parameter></entry>
<entry>
<para><indexterm>
<primary>gateway password</primary>
</indexterm>The password to provide when authenticating with
the remote desktop gateway, if a gateway is being
used.</para>
</entry>
</row>
<row>
<entry><parameter>gateway-domain</parameter></entry>
<entry>
<para><indexterm>
<primary>gateway domain</primary>
</indexterm>The domain of the user authenticating with the
remote desktop gateway, if a gateway is being used. This is
not necessarily the same domain as the user actually using
the remote desktop connection.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="rdp-connection-broker">
<title>Load balancing and RDP connection brokers</title>
<para><indexterm>
<primary>load balancing</primary>
</indexterm><indexterm>
<primary>connection broker</primary>
</indexterm>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.</para>
<para>If you are using a load balancer and are unsure whether such information is
required, <emphasis>you will need to check the documentation for your
balancer</emphasis>. If your balancer provides <filename>.rdp</filename>
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.</para>
<para><emphasis>This functionality is only available if Guacamole was built against
FreeRDP 1.1 or later.</emphasis> Older versions of FreeRDP do not have
support for load balancers which require additional information during the
connection process.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>RDP</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>load-balance-info</parameter></entry>
<entry>
<para><indexterm>
<primary>loadbalanceinfo</primary>
</indexterm>The load balancing information or cookie which
should be provided to the connection broker. <emphasis>If no
connection broker is being used, this should be left
blank.</emphasis></para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="rdp-sftp">
<title>RDP + SFTP</title>
<para>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 <xref linkend="using-guacamole"/>.</para>
<para>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.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>RDP</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>enable-sftp</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>file transfer</secondary>
</indexterm><indexterm>
<primary>SFTP</primary>
</indexterm>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.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-hostname</parameter></entry>
<entry>
<para>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
<parameter>hostname</parameter> parameter will be
used.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-port</parameter></entry>
<entry>
<para>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.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-host-key</parameter></entry>
<entry>
<para>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.</para>
<para>The format of this parameter is that of a single entry
from an OpenSSH <filename>known_hosts</filename> file.</para>
<para>For more information, please see <xref linkend="ssh-host-verification"/>.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-username</parameter></entry>
<entry>
<para>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 <parameter>username</parameter>
parameter will be use.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-password</parameter></entry>
<entry>
<para>The password to use when authenticating with the specified
SSH server for SFTP.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-private-key</parameter></entry>
<entry>
<para>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 <command>ssh-keygen</command> utility.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-passphrase</parameter></entry>
<entry>
<para>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.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-directory</parameter></entry>
<entry>
<para>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.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-root-directory</parameter></entry>
<entry>
<para>The directory to expose to connected users via Guacamole's
<link xmlns:xlink="http://www.w3.org/1999/xlink"
linkend="file-browser">file browser</link>. If omitted,
the root directory will be used by default.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-server-alive-interval</parameter></entry>
<entry>
<para>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.
</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="rdp-disable-clipboard">
<title>Disabling clipboard access</title>
<para>Guacamole provides bidirectional access to the clipboard by default for RDP
connections. This behavior can be overridden on a per-connection basis with the
<parameter>disable-copy</parameter> and <parameter>disable-paste</parameter>
parameters.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>RDP</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>disable-copy</parameter></entry>
<entry>
<para><indexterm>
<primary>disable clipboard</primary>
</indexterm><indexterm>
<primary>RDP</primary>
<secondary>disable clipboard</secondary>
</indexterm>If set to "true", text copied within the RDP
session will not be accessible by the user at the browser
side of the Guacamole session, and will be usable only
within the remote desktop. This parameter is optional. By
default, the user will be given access to the copied
text.</para>
</entry>
</row>
<row>
<entry><parameter>disable-paste</parameter></entry>
<entry>
<para><indexterm>
<primary>disable clipboard</primary>
</indexterm><indexterm>
<primary>RDP</primary>
<secondary>disable clipboard</secondary>
</indexterm>If set to "true", text copied at the browser
side of the Guacamole session will not be accessible within
the RDP session. This parameter is optional. By default, the
user will be able to paste data from outside the browser
within the RDP session.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="rdp-perf-flags">
<title>Performance flags</title>
<para>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.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>RDP</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="2.75*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>enable-wallpaper</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>wallpaper</secondary>
</indexterm>If set to "true", enables rendering of the
desktop wallpaper. By default, wallpaper will be disabled,
such that unnecessary bandwidth need not be spent redrawing
the desktop.</para>
</entry>
</row>
<row>
<entry><parameter>enable-theming</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>theming</secondary>
</indexterm>If set to "true", enables use of theming of
windows and controls. By default, theming within RDP
sessions is disabled.</para>
</entry>
</row>
<row>
<entry><parameter>enable-font-smoothing</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>font smoothing</secondary>
</indexterm><indexterm>
<primary>RDP</primary>
<secondary>ClearType</secondary>
</indexterm>If set to "true", text will be rendered with
smooth edges. Text over RDP is rendered with rough edges by
default, as this reduces the number of colors used by text,
and thus reduces the bandwidth required for the
connection.</para>
</entry>
</row>
<row>
<entry><parameter>enable-full-window-drag</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>full window drag</secondary>
</indexterm>If set to "true", the contents of windows will
be displayed as windows are moved. By default, the RDP
server will only draw the window border while windows are
being dragged.</para>
</entry>
</row>
<row>
<entry><parameter>enable-desktop-composition</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>desktop composition</secondary>
</indexterm><indexterm>
<primary>RDP</primary>
<secondary>Aero</secondary>
</indexterm>If set to "true", graphical effects such as
transparent windows and shadows will be allowed. By default,
such effects, if available, are disabled.</para>
</entry>
</row>
<row>
<entry><parameter>enable-menu-animations</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>menu animations</secondary>
</indexterm>If set to "true", menu open and close animations
will be allowed. Menu animations are disabled by
default.</para>
</entry>
</row>
<row>
<entry><parameter>disable-bitmap-caching</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>bitmap caching</secondary>
</indexterm>In certain situations, particularly with RDP server
implementations with known bugs, it is necessary to disable
RDP's built-in bitmap caching functionality. This parameter
allows that to be controlled in a Guacamole session. If set to
"true" the RDP bitmap cache will not be used.</para>
</entry>
</row>
<row>
<entry><parameter>disable-offscreen-caching</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>offscreen bitmap caching</secondary>
</indexterm>RDP normally maintains caches of regions of the screen
that are current not visible in the client in order to accelerate
retrieval of those regions when they come into view. This parameter,
when set to "true," will disable caching of those regions. This is
usually only useful when dealing with known bugs in RDP server
implementations and should remain enabled in most circumstances.</para>
</entry>
</row>
<row>
<entry><parameter>disable-glyph-caching</parameter></entry>
<entry>
<para><indexterm>
<primary>RDP</primary>
<secondary>glyph caching</secondary>
</indexterm>In addition to screen regions, RDP maintains caches of
frequently used symbols or fonts, collectively known as "glyphs." As
with bitmap and offscreen caching, certain known bugs in RDP implementations
can cause performance issues with this enabled, and setting this parameter
to "true" will disable that glyph caching in the RDP session.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="rdp-remoteapp">
<title>RemoteApp</title>
<para>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.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>RDP</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>remote-app</parameter></entry>
<entry>
<para><indexterm>
<primary>RemoteApp</primary>
</indexterm>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.</para>
<para>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
<filename>notepad.exe</filename> and have assigned it
the name "notepad", you would set this parameter to:
"||notepad".</para>
</entry>
</row>
<row>
<entry><parameter>remote-app-dir</parameter></entry>
<entry>
<para>The working directory, if any, for the remote application.
This parameter has no effect if RemoteApp is not in
use.</para>
</entry>
</row>
<row>
<entry><parameter>remote-app-args</parameter></entry>
<entry>
<para>The command-line arguments, if any, for the remote
application. This parameter has no effect if RemoteApp is
not in use.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="adding-rdp">
<title>Adding an RDP connection</title>
<indexterm>
<primary>RDP</primary>
<secondary>adding</secondary>
</indexterm>
<para>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
<code>&lt;authorize></code> section for that user within your
<filename>user-mapping.xml</filename>, and add a section like the following
within it:</para>
<programlisting>&lt;connection name="<replaceable>Unique Name</replaceable>">
&lt;protocol>rdp&lt;/protocol>
&lt;param name="hostname"><replaceable>localhost</replaceable>&lt;/param>
&lt;param name="port"><replaceable>3389</replaceable>&lt;/param>
&lt;/connection></programlisting>
<para>If added exactly as above, a new connection named "<replaceable>Unique
Name</replaceable>" will be available to the user associated with the
<code>&lt;authorize></code> section containing it. The connection will use
RDP to connect to <replaceable>localhost</replaceable> at port
<replaceable>3389</replaceable>. Naturally, you will want to change some or
all of these values.</para>
<para>If you want to login automatically rather than receive a login prompt upon
connecting, you can specify a username and password with additional
<code>&lt;param></code> tags. Other options are available for controlling
the color depth, size of the screen, etc.</para>
<para>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.</para>
</section>
</section>
<section xml:id="ssh">
<title>SSH</title>
<indexterm>
<primary>SSH</primary>
</indexterm>
<para>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.</para>
<para>SSH support for Guacamole is provided by the <package>libguac-client-ssh</package>
library, which will be installed as part of guacamole-server if the required
dependencies are present during the build.</para>
<section xml:id="ssh-host-verification">
<title>SSH Host Verification</title>
<para>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.</para>
<para>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
<varname>GUACAMOLE_HOME</varname> called <filename>ssh_known_hosts</filename>.
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.</para>
<para>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 <parameter>host-key</parameter> parameter is used for SSH connections,
while the SFTP connections associated with RDP and VNC use the
<parameter>sftp-host-key</parameter> 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.</para>
</section>
<section xml:id="ssh-network-parameters">
<title>Network parameters</title>
<para>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.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>SSH</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>hostname</parameter></entry>
<entry>
<para><indexterm>
<primary>SSH</primary>
<secondary>hostname</secondary>
</indexterm>The hostname or IP address of the SSH server
Guacamole should connect to.</para>
</entry>
</row>
<row>
<entry><parameter>port</parameter></entry>
<entry>
<para><indexterm>
<primary>SSH</primary>
<secondary>port</secondary>
</indexterm>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.</para>
</entry>
</row>
<row>
<entry><parameter>host-key</parameter></entry>
<entry>
<para><indexterm>
<primary>SSH</primary>
<secondary>host-key</secondary>
</indexterm>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.</para>
<para>The format of this parameter is that of a single entry from
an OpenSSH <filename>known_hosts</filename> file.</para>
<para>For more information, please see <xref linkend="ssh-host-verification"/>.</para>
</entry>
</row>
<row>
<entry><parameter>server-alive-interval</parameter></entry>
<entry>
<para>
<indexterm>
<primary>SSH</primary>
<secondary>server-alive-interval</secondary>
</indexterm>
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.
</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="ssh-authentication">
<title>Authentication</title>
<para>SSH provides authentication through passwords and public key
authentication, and also supports the NONE method.</para>
<para>SSH NONE authentication is seen occasionally in appliances
and items like network or SAN fabric switches. Generally
for this authentication method you need only provide a
username.</para>
<para>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.</para>
<para>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.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>SSH</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>username</parameter></entry>
<entry>
<para><indexterm>
<primary>SSH</primary>
<secondary>username</secondary>
</indexterm>The username to use to authenticate, if any.
This parameter is optional. If not specified, you will be
prompted for the username upon connecting.</para>
</entry>
</row>
<row>
<entry><parameter>password</parameter></entry>
<entry>
<para><indexterm>
<primary>SSH</primary>
<secondary>password</secondary>
</indexterm>The password to use when attempting
authentication, if any. This parameter is optional. If not
specified, you will be prompted for your password upon
connecting.</para>
</entry>
</row>
<row>
<entry><parameter>private-key</parameter></entry>
<entry>
<para><indexterm>
<primary>SSH</primary>
<secondary>public key authentication</secondary>
</indexterm>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 <command>ssh-keygen</command> utility.</para>
</entry>
</row>
<row>
<entry><parameter>passphrase</parameter></entry>
<entry>
<para><indexterm>
<primary>SSH</primary>
<secondary>passphrase</secondary>
</indexterm>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.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="ssh-display-settings">
<title>Display settings</title>
<para>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,
<emphasis>the chosen font must be installed on the server</emphasis>, as it
is the server that will handle rendering of characters to the terminal display,
not the client.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>SSH</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>color-scheme</parameter></entry>
<entry>
<para><indexterm>
<primary>SSH</primary>
<secondary>color scheme</secondary>
</indexterm>The color scheme to use for the terminal
emulator used by SSH connections. It consists of a
semicolon-separated series of name-value pairs. Each
name-value pair is separated by a colon and assigns a
value to a color in the terminal emulator palette. For
example, to use blue text on white background by default,
and change the red color to a purple shade, you would
specify:</para>
<informalexample>
<programlisting>foreground: rgb:00/00/ff;
background: rgb:ff/ff/ff;
color9: rgb:80/00/80</programlisting>
</informalexample>
<para>This format is similar to the color configuration format
used by Xterm, so Xterm color configurations can be easily
adapted for Guacamole. This parameter is optional. If not
specified, Guacamole will render text as gray over a black
background.</para>
<para>Possible color names are:</para>
<variablelist>
<varlistentry>
<term><constant>foreground</constant></term>
<listitem>
<para>Set the default foreground color.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>background</constant></term>
<listitem>
<para>Set the default background color.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>color&lt;n&gt;</constant></term>
<listitem>
<para>Set the color at index <code>&lt;n&gt;</code>
on the Xterm 256-color palette. For example,
<code>color9</code> refers to the red color.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>Possible color values are:</para>
<variablelist>
<varlistentry>
<term><constant>rgb:RR/GG/BB</constant></term>
<listitem>
<para>Use the specified color in RGB format, with
each component in hexadecimal. For example,
<code>rgb:ff/00/00</code> specifies the color
red. Note that each hexadecimal component can be
one to four digits, but the effective values are
always zero-extended or truncated to two digits;
for example, <code>rgb:f/8/0</code>,
<code>rgb:f0/80/00</code>, and
<code>rgb:f0f/808/00f</code> all refer to the
same effective color.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>color&lt;n&gt;</constant></term>
<listitem>
<para>Use the color currently assigned to index
<code>&lt;n&gt;</code> on the Xterm 256-color
palette. For example, <code>color9</code>
specifies the current red color. Note that the
color value is used rather than the color
reference, so if <code>color9</code> is changed
later in the color scheme configuration, that
new color will not be reflected in this
assignment.</para>
</listitem>
</varlistentry>
</variablelist>
<para>For backward compatibility, Guacamole will also accept
four special values as the color scheme parameter:</para>
<variablelist>
<varlistentry>
<term><constant>black-white</constant></term>
<listitem>
<para>Black text over a white background.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>gray-black</constant></term>
<listitem>
<para>Gray text over a black background. This is the
default color scheme.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>green-black</constant></term>
<listitem>
<para>Green text over a black background.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>white-black</constant></term>
<listitem>
<para>White text over a black background.</para>
</listitem>
</varlistentry>
</variablelist>
</entry>
</row>
<row>
<entry><parameter>font-name</parameter></entry>
<entry>
<para><indexterm>
<primary>SSH</primary>
<secondary>font</secondary>
</indexterm>The name of the font to use. This parameter is
optional. If not specified, the default of "monospace" will
be used instead.</para>
</entry>
</row>
<row>
<entry><parameter>font-size</parameter></entry>
<entry>
<para>The size of the font to use, in points. This parameter is
optional. If not specified, the default of 12 will be used
instead.</para>
</entry>
</row>
<row>
<entry><parameter>scrollback</parameter></entry>
<entry>
<para>The maximum number of rows to allow within the terminal
scrollback buffer. This parameter is optional. If not
specified, the scrollback buffer will be limited to a
maximum of 1000 rows.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="ssh-command">
<title>Running a command (instead of a shell)</title>
<para>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 <command>chsh</command> or within
<filename>/etc/passwd</filename>. 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.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>SSH</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>command</parameter></entry>
<entry>
<para><indexterm>
<primary>SSH</primary>
<secondary>command</secondary>
</indexterm>The command to execute over the SSH session, if
any. This parameter is optional. If not specified, the SSH
session will use the user's default shell.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section>
<title>Internationalization/Locale settings</title>
<para>The language of the session is normally set by the SSH server. If the SSH
server allows the relevant environment variable to be set, the language can be
overridden on a per-connection basis.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>SSH</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>locale</parameter></entry>
<entry>
<para><indexterm>
<primary>SSH</primary>
<secondary>locale</secondary>
</indexterm>The specific locale to request for the SSH
session. This parameter is optional and may be any value
accepted by the <envar>LANG</envar> environment variable of
the SSH server. If not specified, the SSH server's default
locale will be used.</para>
<para>As this parameter is sent to the SSH server using the
<envar>LANG</envar> environment variable, the parameter
will only have an effect if the SSH server allows the
<envar>LANG</envar> environment variable to be set by
SSH clients.</para>
</entry>
</row>
<row>
<entry><parameter>timezone</parameter></entry>
<entry>
<para>
<indexterm>
<primary>SSH</primary>
<secondary>timezone</secondary>
</indexterm>This parameter allows you
to control the timezone that is sent
to the server over the SSH connection,
which will change the way local time is
displayed on the server.</para>
<para>
The mechanism used to do this over SSH
connections is by setting the
<envar>TZ</envar> variable on the SSH
connection to the timezone specified by
this parameter. This means that the SSH
server must allow the <envar>TZ</envar>
variable to be set/overriden - many SSH
server implementations have this disabled
by default. To get this to work, you may
need to modify the configuration of the
SSH server and explicitly allow for
<envar>TZ</envar> to be set/overriden.
</para>
<para>
The available values of this parameter are
standard IANA key zone format timezones,
and the value will be sent directly to
the server in this format.
</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="ssh-terminal-behavior">
<title>Controlling terminal behavior</title>
<para>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.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>SSH</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>backspace</parameter></entry>
<entry>
<para><indexterm>
<primary>SSH</primary>
<secondary>backspace</secondary>
</indexterm>This parameter controls the ASCII code that
the backspace key sends to the remote system. Under most
circumstances this should not need to be adjusted; however,
if, when pressing the backspace key, you see control characters
(often either ^? or ^H) instead of seeing the text erased,
you may need to adjust this parameter. By default the terminal
sends ASCII code 127 (Delete) if this option is not set.</para>
</entry>
</row>
<row>
<entry><parameter>terminal-type</parameter></entry>
<entry>
<para><indexterm>
<primary>SSH</primary>
<secondary>terminal type</secondary>
</indexterm>This parameter sets the terminal emulator type
string that is passed to the SSH server. This parameter is
optional. If not specified, &quot;<code>linux</code>&quot;
is used as the terminal emulator type by default.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<section xml:id="ssh-stdin-pipe">
<title>Providing input directly from JavaScript</title>
<para>If Guacamole is being used in part to automate an SSH session, it can be
useful to provide input directly from JavaScript as a raw stream of data,
rather than attempting to translate data into keystrokes. This can be done
through opening a pipe stream named "STDIN" within the SSH connection using
the <link xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="../guacamole-common-js/Guacamole.Client.html#createPipeStream"
><function>createPipeStream()</function></link> function of <link
xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="../guacamole-common-js/Guacamole.Client.html"
><classname>Guacamole.Client</classname></link>:</para>
<informalexample>
<programlisting>var outputStream = client.createPipeStream('text/plain', 'STDIN');</programlisting>
</informalexample>
<para>The resulting <link xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="../guacamole-common-js/Guacamole.OutputStream.html"
><classname>Guacamole.OutputStream</classname></link> can then be
used to stream data directly to the input of the SSH session, as if typed by
the user:</para>
<informalexample>
<programlisting>// Wrap output stream in writer
var writer = new Guacamole.StringWriter(outputStream);
// Send text
writer.sendText("hello");
// Send more text
writer.sendText("world");
// Close writer and stream
writer.sendEnd();</programlisting>
</informalexample>
</section>
</section>
<section xml:id="ssh-typescripts">
<title>Text session recording (typescripts)</title>
<para>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 <parameter>typescript-path</parameter>:
<filename><replaceable>NAME</replaceable></filename>, which contains the
raw text data, and <filename><replaceable>NAME</replaceable>.timing</filename>,
which contains timing information, where <replaceable>NAME</replaceable> is the
value provided for the <parameter>typescript-name</parameter> parameter.</para>
<para>This format is compatible with the format used by the standard UNIX
<command>script</command> command, and can be replayed using
<command>scriptreplay</command> (if installed). For example, to replay a
typescript called "<replaceable>NAME</replaceable>", you would run:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>scriptreplay <replaceable>NAME</replaceable>.timing <replaceable>NAME</replaceable></userinput></screen>
</informalexample>
<important>
<para>Guacamole will never overwrite an existing recording. If necessary, a
numeric suffix like ".1", ".2", ".3", etc. will be appended to
<replaceable>NAME</replaceable> to avoid overwriting an existing
recording. If even appending a numeric suffix does not help, the session
will simply not be recorded.</para>
</important>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>SSH</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>typescript-path</parameter></entry>
<entry>
<para><indexterm>
<primary>SSH</primary>
<secondary>typescripts</secondary>
</indexterm><indexterm>
<primary>SSH</primary>
<secondary>text recording</secondary>
</indexterm>The directory in which typescript files should
be created. <emphasis>If a typescript needs to be recorded,
this parameter is required.</emphasis> Specifying this
parameter enables typescript recording. If this parameter is
omitted, no typescript will be recorded.</para>
</entry>
</row>
<row>
<entry><parameter>create-typescript-path</parameter></entry>
<entry>
<para>If set to "true", the directory specified by the
<parameter>typescript-path</parameter> parameter will
automatically be created if it does not yet exist. Only the
final directory in the path will be created - if other
directories earlier in the path do not exist, automatic
creation will fail, and an error will be logged.</para>
<para><emphasis>This parameter is optional.</emphasis> By
default, the directory specified by the
<parameter>typescript-path</parameter> parameter will
not automatically be created, and attempts to record
typescripts in a non-existent directory will be logged as
errors.</para>
<para>This parameter only has an effect if typescript recording
is enabled. If the <parameter>typescript-path</parameter> is
not specified, recording of typescripts will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>typescript-name</parameter></entry>
<entry>
<para>The base filename to use when determining the names for
the data and timing files of the typescript. <emphasis>This
parameter is optional.</emphasis> If omitted, the value
"typescript" will be used instead.</para>
<para>Each typescript consists of two files which are created
within the directory specified by
<parameter>typescript-path</parameter>:
<filename><replaceable>NAME</replaceable></filename>,
which contains the raw text data, and
<filename><replaceable>NAME</replaceable>.timing</filename>,
which contains timing information, where
<replaceable>NAME</replaceable> is the value provided
for the <parameter>typescript-name</parameter>
parameter.</para>
<para>This parameter only has an effect if typescript recording
is enabled. If the <parameter>typescript-path</parameter> is
not specified, recording of typescripts will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="ssh-recording">
<title>Graphical session recording</title>
<para>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 <command>guacenc</command> utility
provided with guacamole-server.</para>
<para>For example, to produce a video called "<replaceable>NAME</replaceable>.m4v"
from the recording "<replaceable>NAME</replaceable>", you would run:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>guacenc <replaceable>/path/to/recording/NAME</replaceable></userinput></screen>
</informalexample>
<para>The <command>guacenc</command> utility has additional options for overriding
default behavior, including tweaking the output format, which are documented in
detail within the manpage:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>man guacenc</userinput></screen>
</informalexample>
<para>If recording of key events is explicitly enabled using the
<parameter>recording-include-keys</parameter> parameter, recordings can also
be translated into human-readable interpretations of the keys pressed during the
session using the <command>guaclog</command> utility. The usage of
<command>guaclog</command> is analogous to <command>guacenc</command>, and
results in the creation of a new text file containing the interpreted
events:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>guaclog <replaceable>/path/to/recording/NAME</replaceable></userinput><computeroutput>
guaclog: INFO: Guacamole input log interpreter (guaclog) version 1.1.0
guaclog: INFO: 1 input file(s) provided.
guaclog: INFO: Writing input events from "<replaceable>/path/to/recording/NAME</replaceable>" to "<replaceable annotations="">/path/to/recording/NAME</replaceable>.txt" ...
guaclog: INFO: All files interpreted successfully.</computeroutput>
<prompt>$</prompt> </screen>
</informalexample>
<important>
<para>Guacamole will never overwrite an existing recording. If necessary, a
numeric suffix like ".1", ".2", ".3", etc. will be appended to
<replaceable>NAME</replaceable> to avoid overwriting an existing
recording. If even appending a numeric suffix does not help, the session
will simply not be recorded.</para>
</important>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>SSH</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>recording-path</parameter></entry>
<entry>
<para><indexterm>
<primary>SSH</primary>
<secondary>graphical recording</secondary>
</indexterm>The directory in which screen recording files
should be created. <emphasis>If a graphical recording needs
to be created, then this parameter is
required.</emphasis> Specifying this parameter enables
graphical screen recording. If this parameter is omitted, no
graphical recording will be created.</para>
</entry>
</row>
<row>
<entry><parameter>create-recording-path</parameter></entry>
<entry>
<para>If set to "true", the directory specified by the
<parameter>recording-path</parameter> parameter will
automatically be created if it does not yet exist. Only the
final directory in the path will be created - if other
directories earlier in the path do not exist, automatic
creation will fail, and an error will be logged.</para>
<para><emphasis>This parameter is optional.</emphasis> By
default, the directory specified by the
<parameter>recording-path</parameter> parameter will not
automatically be created, and attempts to create recordings
within a non-existent directory will be logged as
errors.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-name</parameter></entry>
<entry>
<para>The filename to use for any created recordings.
<emphasis>This parameter is optional.</emphasis> If
omitted, the value "recording" will be used instead.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-exclude-output</parameter></entry>
<entry>
<para>If set to "true", graphical output and other data normally
streamed from server to client will be excluded from the
recording, producing a recording which contains only user
input events. <emphasis>This parameter is
optional.</emphasis> If omitted, graphical output will
be included in the recording.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-exclude-mouse</parameter></entry>
<entry>
<para>If set to "true", user mouse events will be excluded from
the recording, producing a recording which lacks a visible
mouse cursor. <emphasis>This parameter is
optional.</emphasis> If omitted, mouse events will be
included in the recording.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-include-keys</parameter></entry>
<entry>
<para>If set to "true", user key events will be included in the
recording. The recording can subsequently be passed through
the <command>guaclog</command> utility to produce a
human-readable interpretation of the keys pressed during the
session. <emphasis>This parameter is optional.</emphasis> If
omitted, key events will be not included in the
recording.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="ssh-sftp">
<title>SFTP</title>
<para>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
<xref linkend="using-guacamole"/>.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>SSH</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>enable-sftp</parameter></entry>
<entry>
<para><indexterm>
<primary>SSH</primary>
<secondary>file transfer</secondary>
</indexterm><indexterm>
<primary>SFTP</primary>
</indexterm>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
<command>guacctl</command> utility which controls file
downloads and uploads when run on the SSH server by the user
over the SSH connection.</para>
</entry>
</row>
<row>
<entry><parameter>sftp-root-directory</parameter></entry>
<entry>
<para>The directory to expose to connected users via Guacamole's
<link xmlns:xlink="http://www.w3.org/1999/xlink"
linkend="file-browser">file browser</link>. If omitted,
the root directory will be used by default.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="ssh-disable-clipboard">
<title>Disabling clipboard access</title>
<para>Guacamole provides bidirectional access to the terminal clipboard by default
for SSH connections. This behavior can be overridden on a per-connection basis
with the <parameter>disable-copy</parameter> and
<parameter>disable-paste</parameter> parameters.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>SSH</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>disable-copy</parameter></entry>
<entry>
<para><indexterm>
<primary>disable clipboard</primary>
</indexterm><indexterm>
<primary>SSH</primary>
<secondary>disable clipboard</secondary>
</indexterm>If set to "true", text copied within the SSH
session will not be accessible by the user at the browser
side of the Guacamole session, and will be usable only
within the terminal. This parameter is optional. By default,
the user will be given access to the copied text.</para>
</entry>
</row>
<row>
<entry><parameter>disable-paste</parameter></entry>
<entry>
<para><indexterm>
<primary>disable clipboard</primary>
</indexterm><indexterm>
<primary>SSH</primary>
<secondary>disable clipboard</secondary>
</indexterm>If set to "true", text copied at the browser
side of the Guacamole session will not be accessible within
the SSH session. This parameter is optional. By default, the
user will be able to paste data from outside the browser
within the terminal.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="adding-ssh">
<title>Adding an SSH connection</title>
<indexterm>
<primary>SSH</primary>
<secondary>adding</secondary>
</indexterm>
<para>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
<code>&lt;authorize></code> section for that user within your
<filename>user-mapping.xml</filename>, and add a section like the following
within it:</para>
<programlisting>&lt;connection name="<replaceable>Unique Name</replaceable>">
&lt;protocol>ssh&lt;/protocol>
&lt;param name="hostname"><replaceable>localhost</replaceable>&lt;/param>
&lt;param name="port"><replaceable>22</replaceable>&lt;/param>
&lt;/connection></programlisting>
<para>If added exactly as above, a new connection named "<replaceable>Unique
Name</replaceable>" will be available to the user associated with the
<code>&lt;authorize></code> section containing it. The connection will use
SSH to connect to <replaceable>localhost</replaceable> at port
<replaceable>22</replaceable>. Naturally, you will want to change some or
all of these values.</para>
<para>If you want to login automatically rather than receive a login prompt upon
connecting, you can specify a username and password with additional
<code>&lt;param></code> tags. Other options are available for controlling
the font.</para>
<para>Other authentication methods will provide documentation describing how to
configure new connections.</para>
</section>
</section>
<section xml:id="telnet">
<title>Telnet</title>
<indexterm>
<primary>telnet</primary>
</indexterm>
<para>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.</para>
<para>Telnet support for Guacamole is provided by the
<package>libguac-client-telnet</package> library, which will be installed as
part of guacamole-server if the required dependencies are present during the
build.</para>
<section xml:id="telnet-network-parameters">
<title>Network parameters</title>
<para>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.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>telnet</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>hostname</parameter></entry>
<entry>
<para><indexterm>
<primary>telnet</primary>
<secondary>hostname</secondary>
</indexterm>The hostname or IP address of the telnet server
Guacamole should connect to.</para>
</entry>
</row>
<row>
<entry><parameter>port</parameter></entry>
<entry>
<para><indexterm>
<primary>telnet</primary>
<secondary>port</secondary>
</indexterm>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.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="telnet-authentication">
<title>Authentication</title>
<para>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.</para>
<para>The de-facto method for passing the username automatically via telnet is to
submit it via the <envar>USER</envar> environment variable, sent using the
<methodname>NEW-ENVIRON</methodname> option. This is the mechanism used by
most telnet clients, typically via the <option>-l</option> command-line
option.</para>
<para>Passwords cannot typically be sent automatically - at least not as reliably as
the username. There is no <envar>PASSWORD</envar> 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
<command>expect</command>. Guacamole provides similar functionality by
searching for the password prompt with a regular expression.</para>
<para>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.</para>
<para>If the password prompt is not being detected properly, you can try using your
own regular expression by specifying it within the
<parameter>password-regex</parameter> parameter. The regular expression must
be written in the POSIX ERE dialect (the dialect typically used by
<command>egrep</command>).</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>telnet</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>username</parameter></entry>
<entry>
<para><indexterm>
<primary>telnet</primary>
<secondary>username</secondary>
</indexterm>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
<methodname>NEW-ENVIRON</methodname> option, and the
telnet login process must pay attention to the
<envar>USER</envar> environment variable. Most telnet
servers satisfy this criteria.</para>
</entry>
</row>
<row>
<entry><parameter>password</parameter></entry>
<entry>
<para><indexterm>
<primary>telnet</primary>
<secondary>password</secondary>
</indexterm>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.</para>
</entry>
</row>
<row>
<entry><parameter>username-regex</parameter></entry>
<entry>
<para>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
<command>egrep</command>).</para>
</entry>
</row>
<row>
<entry><parameter>password-regex</parameter></entry>
<entry>
<para>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
<command>egrep</command>).</para>
</entry>
</row>
<row>
<entry><parameter>login-success-regex</parameter></entry>
<entry>
<para>The regular expression to use when detecting that the
login attempt has succeeded. This parameter is optional. If
specified, the terminal display will not be shown to the
user until text matching this regular expression has been
received from the telnet server. The regular expression must
be written in the POSIX ERE dialect (the dialect typically
used by <command>egrep</command>).</para>
</entry>
</row>
<row>
<entry><parameter>login-failure-regex</parameter></entry>
<entry>
<para>The regular expression to use when detecting that the
login attempt has failed. This parameter is optional. If
specified, the connection will be closed with an explicit
login failure error if text matching this regular expression
has been received from the telnet server. The regular
expression must be written in the POSIX ERE dialect (the
dialect typically used by <command>egrep</command>).</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="telnet-display-settings">
<title>Display settings</title>
<para>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,
<emphasis>the chosen font must be installed on the server</emphasis>, as it
is the server that will handle rendering of characters to the terminal display,
not the client.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>telnet</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>color-scheme</parameter></entry>
<entry>
<para><indexterm>
<primary>telnet</primary>
<secondary>color scheme</secondary>
</indexterm>The color scheme to use for the terminal
emulator used by telnet connections. It consists of a
semicolon-separated series of name-value pairs. Each
name-value pair is separated by a colon and assigns a
value to a color in the terminal emulator palette. For
example, to use blue text on white background by default,
and change the red color to a purple shade, you would
specify:</para>
<informalexample>
<programlisting>foreground: rgb:00/00/ff;
background: rgb:ff/ff/ff;
color9: rgb:80/00/80</programlisting>
</informalexample>
<para>This format is similar to the color configuration format
used by Xterm, so Xterm color configurations can be easily
adapted for Guacamole. This parameter is optional. If not
specified, Guacamole will render text as gray over a black
background.</para>
<para>Possible color names are:</para>
<variablelist>
<varlistentry>
<term><constant>foreground</constant></term>
<listitem>
<para>Set the default foreground color.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>background</constant></term>
<listitem>
<para>Set the default background color.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>color&lt;n&gt;</constant></term>
<listitem>
<para>Set the color at index <code>&lt;n&gt;</code>
on the Xterm 256-color palette. For example,
<code>color9</code> refers to the red color.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>Possible color values are:</para>
<variablelist>
<varlistentry>
<term><constant>rgb:RR/GG/BB</constant></term>
<listitem>
<para>Use the specified color in RGB format, with
each component in hexadecimal. For example,
<code>rgb:ff/00/00</code> specifies the color
red. Note that each hexadecimal component can be
one to four digits, but the effective values are
always zero-extended or truncated to two digits;
for example, <code>rgb:f/8/0</code>,
<code>rgb:f0/80/00</code>, and
<code>rgb:f0f/808/00f</code> all refer to the
same effective color.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>color&lt;n&gt;</constant></term>
<listitem>
<para>Use the color currently assigned to index
<code>&lt;n&gt;</code> on the Xterm 256-color
palette. For example, <code>color9</code>
specifies the current red color. Note that the
color value is used rather than the color
reference, so if <code>color9</code> is changed
later in the color scheme configuration, that
new color will not be reflected in this
assignment.</para>
</listitem>
</varlistentry>
</variablelist>
<para>For backward compatibility, Guacamole will also accept
four special values as the color scheme parameter:</para>
<variablelist>
<varlistentry>
<term><constant>black-white</constant></term>
<listitem>
<para>Black text over a white background.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>gray-black</constant></term>
<listitem>
<para>Gray text over a black background. This is the
default color scheme.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>green-black</constant></term>
<listitem>
<para>Green text over a black background.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>white-black</constant></term>
<listitem>
<para>White text over a black background.</para>
</listitem>
</varlistentry>
</variablelist>
</entry>
</row>
<row>
<entry><parameter>font-name</parameter></entry>
<entry>
<para><indexterm>
<primary>telnet</primary>
<secondary>font</secondary>
</indexterm>The name of the font to use. This parameter is
optional. If not specified, the default of "monospace" will
be used instead.</para>
</entry>
</row>
<row>
<entry><parameter>font-size</parameter></entry>
<entry>
<para>The size of the font to use, in points. This parameter is
optional. If not specified, the default of 12 will be used
instead.</para>
</entry>
</row>
<row>
<entry><parameter>scrollback</parameter></entry>
<entry>
<para>The maximum number of rows to allow within the terminal
scrollback buffer. This parameter is optional. If not
specified, the scrollback buffer will be limited to a
maximum of 1000 rows.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="telnet-terminal-behavior">
<title>Controlling terminal behavior</title>
<para>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.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>telnet</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>backspace</parameter></entry>
<entry>
<para><indexterm>
<primary>telnet</primary>
<secondary>backspace</secondary>
</indexterm>This parameter controls the ASCII code that
the backspace key sends to the remote system. Under most
circumstances this should not need to be adjusted; however,
if, when pressing the backspace key, you see control characters
(often either ^? or ^H) instead of seeing the text erased,
you may need to adjust this parameter. By default the terminal
sends ASCII code 127 (Delete) if this option is not set.</para>
</entry>
</row>
<row>
<entry><parameter>terminal-type</parameter></entry>
<entry>
<para><indexterm>
<primary>telnet</primary>
<secondary>terminal type</secondary>
</indexterm>This parameter sets the terminal emulator type
string that is passed to the telnet server. This parameter
is optional. If not specified,
&quot;<code>linux</code>&quot; is used as the terminal
emulator type by default.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<section xml:id="telnet-stdin-pipe">
<title>Providing input directly from JavaScript</title>
<para>If Guacamole is being used in part to automate a telnet session, it can be
useful to provide input directly from JavaScript as a raw stream of data,
rather than attempting to translate data into keystrokes. This can be done
through opening a pipe stream named "STDIN" within the telnet connection
using the <link xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="../guacamole-common-js/Guacamole.Client.html#createPipeStream"
><function>createPipeStream()</function></link> function of <link
xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="../guacamole-common-js/Guacamole.Client.html"
><classname>Guacamole.Client</classname></link>:</para>
<informalexample>
<programlisting>var outputStream = client.createPipeStream('text/plain', 'STDIN');</programlisting>
</informalexample>
<para>The resulting <link xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="../guacamole-common-js/Guacamole.OutputStream.html"
><classname>Guacamole.OutputStream</classname></link> can then be
used to stream data directly to the input of the telnet session, as if typed
by the user:</para>
<informalexample>
<programlisting>// Wrap output stream in writer
var writer = new Guacamole.StringWriter(outputStream);
// Send text
writer.sendText("hello");
// Send more text
writer.sendText("world");
// Close writer and stream
writer.sendEnd();</programlisting>
</informalexample>
</section>
</section>
<section xml:id="telnet-typescripts">
<title>Text session recording (typescripts)</title>
<para>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 <parameter>typescript-path</parameter>:
<filename><replaceable>NAME</replaceable></filename>, which contains the
raw text data, and <filename><replaceable>NAME</replaceable>.timing</filename>,
which contains timing information, where <replaceable>NAME</replaceable> is the
value provided for the <parameter>typescript-name</parameter> parameter.</para>
<para>This format is compatible with the format used by the standard UNIX
<command>script</command> command, and can be replayed using
<command>scriptreplay</command> (if installed). For example, to replay a
typescript called "<replaceable>NAME</replaceable>", you would run:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>scriptreplay <replaceable>NAME</replaceable>.timing <replaceable>NAME</replaceable></userinput></screen>
</informalexample>
<important>
<para>Guacamole will never overwrite an existing recording. If necessary, a
numeric suffix like ".1", ".2", ".3", etc. will be appended to
<replaceable>NAME</replaceable> to avoid overwriting an existing
recording. If even appending a numeric suffix does not help, the session
will simply not be recorded.</para>
</important>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>telnet</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>typescript-path</parameter></entry>
<entry>
<para><indexterm>
<primary>telnet</primary>
<secondary>typescripts</secondary>
</indexterm><indexterm>
<primary>telnet</primary>
<secondary>text recording</secondary>
</indexterm>The directory in which typescript files should
be created. <emphasis>If a typescript needs to be recorded,
this parameter is required.</emphasis> Specifying this
parameter enables typescript recording. If this parameter is
omitted, no typescript will be recorded.</para>
</entry>
</row>
<row>
<entry><parameter>create-typescript-path</parameter></entry>
<entry>
<para>If set to "true", the directory specified by the
<parameter>typescript-path</parameter> parameter will
automatically be created if it does not yet exist. Only the
final directory in the path will be created - if other
directories earlier in the path do not exist, automatic
creation will fail, and an error will be logged.</para>
<para><emphasis>This parameter is optional.</emphasis> By
default, the directory specified by the
<parameter>typescript-path</parameter> parameter will
not automatically be created, and attempts to record
typescripts in a non-existent directory will be logged as
errors.</para>
<para>This parameter only has an effect if typescript recording
is enabled. If the <parameter>typescript-path</parameter> is
not specified, recording of typescripts will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>typescript-name</parameter></entry>
<entry>
<para>The base filename to use when determining the names for
the data and timing files of the typescript. <emphasis>This
parameter is optional.</emphasis> If omitted, the value
"typescript" will be used instead.</para>
<para>Each typescript consists of two files which are created
within the directory specified by
<parameter>typescript-path</parameter>:
<filename><replaceable>NAME</replaceable></filename>,
which contains the raw text data, and
<filename><replaceable>NAME</replaceable>.timing</filename>,
which contains timing information, where
<replaceable>NAME</replaceable> is the value provided
for the <parameter>typescript-name</parameter>
parameter.</para>
<para>This parameter only has an effect if typescript recording
is enabled. If the <parameter>typescript-path</parameter> is
not specified, recording of typescripts will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="telnet-recording">
<title>Graphical session recording</title>
<para>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 <command>guacenc</command> utility
provided with guacamole-server.</para>
<para>For example, to produce a video called "<replaceable>NAME</replaceable>.m4v"
from the recording "<replaceable>NAME</replaceable>", you would run:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>guacenc <replaceable>/path/to/recording/NAME</replaceable></userinput></screen>
</informalexample>
<para>The <command>guacenc</command> utility has additional options for overriding
default behavior, including tweaking the output format, which are documented in
detail within the manpage:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>man guacenc</userinput></screen>
</informalexample>
<para>If recording of key events is explicitly enabled using the
<parameter>recording-include-keys</parameter> parameter, recordings can also
be translated into human-readable interpretations of the keys pressed during the
session using the <command>guaclog</command> utility. The usage of
<command>guaclog</command> is analogous to <command>guacenc</command>, and
results in the creation of a new text file containing the interpreted
events:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>guaclog <replaceable>/path/to/recording/NAME</replaceable></userinput><computeroutput>
guaclog: INFO: Guacamole input log interpreter (guaclog) version 1.1.0
guaclog: INFO: 1 input file(s) provided.
guaclog: INFO: Writing input events from "<replaceable>/path/to/recording/NAME</replaceable>" to "<replaceable annotations="">/path/to/recording/NAME</replaceable>.txt" ...
guaclog: INFO: All files interpreted successfully.</computeroutput>
<prompt>$</prompt> </screen>
</informalexample>
<important>
<para>Guacamole will never overwrite an existing recording. If necessary, a
numeric suffix like ".1", ".2", ".3", etc. will be appended to
<replaceable>NAME</replaceable> to avoid overwriting an existing
recording. If even appending a numeric suffix does not help, the session
will simply not be recorded.</para>
</important>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>telnet</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>recording-path</parameter></entry>
<entry>
<para><indexterm>
<primary>telnet</primary>
<secondary>graphical recording</secondary>
</indexterm>The directory in which screen recording files
should be created. <emphasis>If a graphical recording needs
to be created, then this parameter is
required.</emphasis> Specifying this parameter enables
graphical screen recording. If this parameter is omitted, no
graphical recording will be created.</para>
</entry>
</row>
<row>
<entry><parameter>create-recording-path</parameter></entry>
<entry>
<para>If set to "true", the directory specified by the
<parameter>recording-path</parameter> parameter will
automatically be created if it does not yet exist. Only the
final directory in the path will be created - if other
directories earlier in the path do not exist, automatic
creation will fail, and an error will be logged.</para>
<para><emphasis>This parameter is optional.</emphasis> By
default, the directory specified by the
<parameter>recording-path</parameter> parameter will not
automatically be created, and attempts to create recordings
within a non-existent directory will be logged as
errors.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-name</parameter></entry>
<entry>
<para>The filename to use for any created recordings.
<emphasis>This parameter is optional.</emphasis> If
omitted, the value "recording" will be used instead.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-exclude-output</parameter></entry>
<entry>
<para>If set to "true", graphical output and other data normally
streamed from server to client will be excluded from the
recording, producing a recording which contains only user
input events. <emphasis>This parameter is
optional.</emphasis> If omitted, graphical output will
be included in the recording.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-exclude-mouse</parameter></entry>
<entry>
<para>If set to "true", user mouse events will be excluded from
the recording, producing a recording which lacks a visible
mouse cursor. <emphasis>This parameter is
optional.</emphasis> If omitted, mouse events will be
included in the recording.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-include-keys</parameter></entry>
<entry>
<para>If set to "true", user key events will be included in the
recording. The recording can subsequently be passed through
the <command>guaclog</command> utility to produce a
human-readable interpretation of the keys pressed during the
session. <emphasis>This parameter is optional.</emphasis> If
omitted, key events will be not included in the
recording.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="telnet-disable-clipboard">
<title>Disabling clipboard access</title>
<para>Guacamole provides bidirectional access to the terminal clipboard by default
for telnet connections. This behavior can be overridden on a per-connection
basis with the <parameter>disable-copy</parameter> and
<parameter>disable-paste</parameter> parameters.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>telnet</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>disable-copy</parameter></entry>
<entry>
<para><indexterm>
<primary>disable clipboard</primary>
</indexterm><indexterm>
<primary>telnet</primary>
<secondary>disable clipboard</secondary>
</indexterm>If set to "true", text copied within the telnet
session will not be accessible by the user at the browser
side of the Guacamole session, and will be usable only
within the terminal. This parameter is optional. By default,
the user will be given access to the copied text.</para>
</entry>
</row>
<row>
<entry><parameter>disable-paste</parameter></entry>
<entry>
<para><indexterm>
<primary>disable clipboard</primary>
</indexterm><indexterm>
<primary>telnet</primary>
<secondary>disable clipboard</secondary>
</indexterm>If set to "true", text copied at the browser
side of the Guacamole session will not be accessible within
the telnet session. This parameter is optional. By default,
the user will be able to paste data from outside the browser
within the terminal.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="adding-telnet">
<title>Adding a telnet connection</title>
<indexterm>
<primary>telnet</primary>
<secondary>adding</secondary>
</indexterm>
<para>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 <code>&lt;authorize></code> section for that user within your
<filename>user-mapping.xml</filename>, and add a section like the following
within it:</para>
<programlisting>&lt;connection name="<replaceable>Unique Name</replaceable>">
&lt;protocol>telnet&lt;/protocol>
&lt;param name="hostname"><replaceable>localhost</replaceable>&lt;/param>
&lt;param name="port"><replaceable>23</replaceable>&lt;/param>
&lt;/connection></programlisting>
<para>If added exactly as above, a new connection named "<replaceable>Unique
Name</replaceable>" will be available to the user associated with the
<code>&lt;authorize></code> section containing it. The connection will use
telnet to connect to <replaceable>localhost</replaceable> at port
<replaceable>23</replaceable>. Naturally, you will want to change some or
all of these values.</para>
<para>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 <emphasis>client</emphasis> 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.</para>
</section>
</section>
<section xml:id="kubernetes">
<title>Kubernetes</title>
<indexterm>
<primary>Kubernetes</primary>
</indexterm>
<para>Kubernetes provides an API for attaching to the console of a container over the
network. As with SSH and telnet, Guacamole's Kubernetes support emulates a terminal
on the server side which renders to the Guacamole client's display.</para>
<para>Kubernetes support for Guacamole is provided by the
<package>libguac-client-kubernetes</package> library, which will be installed as
part of guacamole-server if the required dependencies are present during the
build.</para>
<section xml:id="kubernetes-network-parameters">
<title>Network/Container parameters</title>
<para>Attaching to a Kubernetes container requires the hostname or IP address of the
Kubernetes server and the name of the pod containing the container in question.
By default, Guacamole will attach to the first container in the pod. If there
are multiple containers in the pod, you may wish to also specify the container
name.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>Kubernetes</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>hostname</parameter></entry>
<entry>
<para><indexterm>
<primary>Kubernetes</primary>
<secondary>hostname</secondary>
</indexterm>The hostname or IP address of the Kubernetes
server that Guacamole should connect to.</para>
</entry>
</row>
<row>
<entry><parameter>port</parameter></entry>
<entry>
<para><indexterm>
<primary>Kubernetes</primary>
<secondary>port</secondary>
</indexterm>The port the Kubernetes server is listening on
for API connections. <emphasis>This parameter is
optional.</emphasis> If omitted, port 8080 will be used
by default.</para>
</entry>
</row>
<row>
<entry><parameter>namespace</parameter></entry>
<entry>
<para><indexterm>
<primary>Kubernetes</primary>
<secondary>namespace</secondary>
</indexterm>The name of the Kubernetes namespace of the pod
containing the container being attached to. <emphasis>This
parameter is optional.</emphasis> If omitted, the
namespace "default" will be used.</para>
</entry>
</row>
<row>
<entry><parameter>pod</parameter></entry>
<entry>
<para><indexterm>
<primary>Kubernetes</primary>
<secondary>pod</secondary>
</indexterm>The name of the Kubernetes pod containing with
the container being attached to.</para>
</entry>
</row>
<row>
<entry><parameter>container</parameter></entry>
<entry>
<para><indexterm>
<primary>Kubernetes</primary>
<secondary>container</secondary>
</indexterm>The name of the container to attach to.
<emphasis>This parameter is optional.</emphasis> If
omitted, the first container in the pod will be used.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="kubernetes-authentication">
<title>Authentication and SSL/TLS</title>
<para>If enabled, Kubernetes uses SSL/TLS for both encryption and authentication.
Standard SSL/TLS client authentication requires both a client certificate and
client key, which Guacamole will use to identify itself to the Kubernetes
server. If the certificate used by Kubernetes is self-signed or signed by a
non-standard certificate authority, the certificate for the certificate
authority will also be needed.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>Kubernetes</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>use-ssl</parameter></entry>
<entry>
<para>If set to "true", SSL/TLS will be used to connect to the
Kubernetes server. <emphasis>This parameter is
optional.</emphasis> By default, SSL/TLS will not be
used.</para>
</entry>
</row>
<row>
<entry><parameter>client-cert</parameter></entry>
<entry>
<para>The certificate to use if performing SSL/TLS client
authentication to authenticate with the Kubernetes server,
in PEM format. <emphasis>This parameter is
optional.</emphasis> If omitted, SSL client
authentication will not be performed.</para>
</entry>
</row>
<row>
<entry><parameter>client-key</parameter></entry>
<entry>
<para>The key to use if performing SSL/TLS client authentication
to authenticate with the Kubernetes server, in PEM format.
<emphasis>This parameter is optional.</emphasis> If
omitted, SSL client authentication will not be
performed</para>
</entry>
</row>
<row>
<entry><parameter>ca-cert</parameter></entry>
<entry>
<para>The certificate of the certificate authority that signed
the certificate of the Kubernetes server, in PEM format.
<emphasis>This parameter is optional.</emphasis> If
omitted, verification of the Kubernetes server certificate
will use only system-wide certificate authorities. </para>
</entry>
</row>
<row>
<entry><parameter>ignore-cert</parameter></entry>
<entry>
<para>If set to "true", the validity of the SSL/TLS certificate
used by the Kubernetes server will be ignored if it cannot
be validated. <emphasis>This parameter is
optional.</emphasis> By default, SSL/TLS certificates
are validated.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="kubernetes-display-settings">
<title>Display settings</title>
<para>Guacamole's Kubernetes 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, <emphasis>the chosen font must be installed on the
server</emphasis>, as it is the server that will handle rendering of
characters to the terminal display, not the client.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>Kubernetes</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>color-scheme</parameter></entry>
<entry>
<para><indexterm>
<primary>Kubernetes</primary>
<secondary>color scheme</secondary>
</indexterm>The color scheme to use for the terminal
emulator used by Kubernetes connections. It consists of a
semicolon-separated series of name-value pairs. Each
name-value pair is separated by a colon and assigns a value
to a color in the terminal emulator palette. For example, to
use blue text on white background by default, and change the
red color to a purple shade, you would specify:</para>
<informalexample>
<programlisting>foreground: rgb:00/00/ff;
background: rgb:ff/ff/ff;
color9: rgb:80/00/80</programlisting>
</informalexample>
<para>This format is similar to the color configuration format
used by Xterm, so Xterm color configurations can be easily
adapted for Guacamole. This parameter is optional. If not
specified, Guacamole will render text as gray over a black
background.</para>
<para>Possible color names are:</para>
<variablelist>
<varlistentry>
<term><constant>foreground</constant></term>
<listitem>
<para>Set the default foreground color.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>background</constant></term>
<listitem>
<para>Set the default background color.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>color&lt;n&gt;</constant></term>
<listitem>
<para>Set the color at index <code>&lt;n&gt;</code>
on the Xterm 256-color palette. For example,
<code>color9</code> refers to the red color.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>Possible color values are:</para>
<variablelist>
<varlistentry>
<term><constant>rgb:RR/GG/BB</constant></term>
<listitem>
<para>Use the specified color in RGB format, with
each component in hexadecimal. For example,
<code>rgb:ff/00/00</code> specifies the color red.
Note that each hexadecimal component can be one to
four digits, but the effective values are always
zero-extended or truncated to two digits; for
example, <code>rgb:f/8/0</code>,
<code>rgb:f0/80/00</code>, and
<code>rgb:f0f/808/00f</code> all refer to the same
effective color.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>color&lt;n&gt;</constant></term>
<listitem>
<para>Use the color currently assigned to index
<code>&lt;n&gt;</code> on the Xterm 256-color
palette. For example, <code>color9</code>
specifies the current red color. Note that the
color value is used rather than the color
reference, so if <code>color9</code> is changed
later in the color scheme configuration, that new
color will not be reflected in this
assignment.</para>
</listitem>
</varlistentry>
</variablelist>
<para>For backward compatibility, Guacamole will also accept
four special values as the color scheme parameter:</para>
<variablelist>
<varlistentry>
<term><constant>black-white</constant></term>
<listitem>
<para>Black text over a white background.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>gray-black</constant></term>
<listitem>
<para>Gray text over a black background. This is the
default color scheme.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>green-black</constant></term>
<listitem>
<para>Green text over a black background.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>white-black</constant></term>
<listitem>
<para>White text over a black background.</para>
</listitem>
</varlistentry>
</variablelist>
</entry>
</row>
<row>
<entry><parameter>font-name</parameter></entry>
<entry>
<para><indexterm>
<primary>Kubernetes</primary>
<secondary>font</secondary>
</indexterm>The name of the font to use. This parameter is
optional. If not specified, the default of "monospace" will
be used instead.</para>
</entry>
</row>
<row>
<entry><parameter>font-size</parameter></entry>
<entry>
<para>The size of the font to use, in points. This parameter is
optional. If not specified, the default of 12 will be used
instead.</para>
</entry>
</row>
<row>
<entry><parameter>read-only</parameter></entry>
<entry>
<para><indexterm>
<primary>Kubernetes</primary>
<secondary>read-only</secondary>
</indexterm>Whether this connection should be read-only. If
set to "true", no input will be accepted on the connection
at all. Users will only see the console of the Kubernetes
container. <emphasis>This parameter is optional.</emphasis>
If omitted, the connection will not be read-only.</para>
</entry>
</row>
<row>
<entry><parameter>scrollback</parameter></entry>
<entry>
<para><indexterm>
<primary>Kubernetes</primary>
<secondary>scrollback</secondary>
</indexterm>The maximum number of rows to allow within the
terminal scrollback buffer. This parameter is optional. If
not specified, the scrollback buffer will be limited to a
maximum of 1000 rows.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="kubernetes-terminal-behavior">
<title>Controlling terminal behavior</title>
<para>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.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>Kubernetes</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>backspace</parameter></entry>
<entry>
<para><indexterm>
<primary>Kubernetes</primary>
<secondary>backspace</secondary>
</indexterm>This parameter controls the ASCII code that the
backspace key sends to the remote system. Under most
circumstances this should not need to be adjusted; however,
if, when pressing the backspace key, you see control
characters (often either ^? or ^H) instead of seeing the
text erased, you may need to adjust this parameter. By
default the terminal sends ASCII code 127 (Delete) if this
option is not set.</para>
</entry>
</row>
<row>
<entry><parameter>terminal-type</parameter></entry>
<entry>
<para><indexterm>
<primary>Kubernetes</primary>
<secondary>terminal type</secondary>
</indexterm>This parameter sets the terminal emulator type
string that is passed to the Kubernetes server. This
parameter is optional. If not specified,
&quot;<code>linux</code>&quot; is used as the terminal
emulator type by default.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="kubernetes-typescripts">
<title>Text session recording (typescripts)</title>
<para>The full, raw text content of Kubernetes 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 <parameter>typescript-path</parameter>:
<filename><replaceable>NAME</replaceable></filename>, which contains the
raw text data, and <filename><replaceable>NAME</replaceable>.timing</filename>,
which contains timing information, where <replaceable>NAME</replaceable> is the
value provided for the <parameter>typescript-name</parameter> parameter.</para>
<para>This format is compatible with the format used by the standard UNIX
<command>script</command> command, and can be replayed using
<command>scriptreplay</command> (if installed). For example, to replay a
typescript called "<replaceable>NAME</replaceable>", you would run:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>scriptreplay <replaceable>NAME</replaceable>.timing <replaceable>NAME</replaceable></userinput></screen>
</informalexample>
<important>
<para>Guacamole will never overwrite an existing recording. If necessary, a
numeric suffix like ".1", ".2", ".3", etc. will be appended to
<replaceable>NAME</replaceable> to avoid overwriting an existing
recording. If even appending a numeric suffix does not help, the session
will simply not be recorded.</para>
</important>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>Kubernetes</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>typescript-path</parameter></entry>
<entry>
<para><indexterm>
<primary>Kubernetes</primary>
<secondary>typescripts</secondary>
</indexterm><indexterm>
<primary>Kubernetes</primary>
<secondary>text recording</secondary>
</indexterm>The directory in which typescript files should
be created. <emphasis>If a typescript needs to be recorded,
this parameter is required.</emphasis> Specifying this
parameter enables typescript recording. If this parameter is
omitted, no typescript will be recorded.</para>
</entry>
</row>
<row>
<entry><parameter>create-typescript-path</parameter></entry>
<entry>
<para>If set to "true", the directory specified by the
<parameter>typescript-path</parameter> parameter will
automatically be created if it does not yet exist. Only the
final directory in the path will be created - if other
directories earlier in the path do not exist, automatic
creation will fail, and an error will be logged.</para>
<para><emphasis>This parameter is optional.</emphasis> By
default, the directory specified by the
<parameter>typescript-path</parameter> parameter will
not automatically be created, and attempts to record
typescripts in a non-existent directory will be logged as
errors.</para>
<para>This parameter only has an effect if typescript recording
is enabled. If the <parameter>typescript-path</parameter> is
not specified, recording of typescripts will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>typescript-name</parameter></entry>
<entry>
<para>The base filename to use when determining the names for
the data and timing files of the typescript. <emphasis>This
parameter is optional.</emphasis> If omitted, the value
"typescript" will be used instead.</para>
<para>Each typescript consists of two files which are created
within the directory specified by
<parameter>typescript-path</parameter>:
<filename><replaceable>NAME</replaceable></filename>,
which contains the raw text data, and
<filename><replaceable>NAME</replaceable>.timing</filename>,
which contains timing information, where
<replaceable>NAME</replaceable> is the value provided
for the <parameter>typescript-name</parameter>
parameter.</para>
<para>This parameter only has an effect if typescript recording
is enabled. If the <parameter>typescript-path</parameter> is
not specified, recording of typescripts will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="kubernetes-recording">
<title>Graphical session recording</title>
<para>In addition to text-based recordings, Kubernetes 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 <command>guacenc</command> utility
provided with guacamole-server.</para>
<para>For example, to produce a video called "<replaceable>NAME</replaceable>.m4v"
from the recording "<replaceable>NAME</replaceable>", you would run:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>guacenc <replaceable>/path/to/recording/NAME</replaceable></userinput></screen>
</informalexample>
<para>The <command>guacenc</command> utility has additional options for overriding
default behavior, including tweaking the output format, which are documented in
detail within the manpage:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>man guacenc</userinput></screen>
</informalexample>
<para>If recording of key events is explicitly enabled using the
<parameter>recording-include-keys</parameter> parameter, recordings can also
be translated into human-readable interpretations of the keys pressed during the
session using the <command>guaclog</command> utility. The usage of
<command>guaclog</command> is analogous to <command>guacenc</command>, and
results in the creation of a new text file containing the interpreted
events:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>guaclog <replaceable>/path/to/recording/NAME</replaceable></userinput><computeroutput>
guaclog: INFO: Guacamole input log interpreter (guaclog) version 1.1.0
guaclog: INFO: 1 input file(s) provided.
guaclog: INFO: Writing input events from "<replaceable>/path/to/recording/NAME</replaceable>" to "<replaceable annotations="">/path/to/recording/NAME</replaceable>.txt" ...
guaclog: INFO: All files interpreted successfully.</computeroutput>
<prompt>$</prompt> </screen>
</informalexample>
<important>
<para>Guacamole will never overwrite an existing recording. If necessary, a
numeric suffix like ".1", ".2", ".3", etc. will be appended to
<replaceable>NAME</replaceable> to avoid overwriting an existing
recording. If even appending a numeric suffix does not help, the session
will simply not be recorded.</para>
</important>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
<secondary>Kubernetes</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.55*"/>
<thead>
<row>
<entry>Parameter name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>recording-path</parameter></entry>
<entry>
<para><indexterm>
<primary>Kubernetes</primary>
<secondary>graphical recording</secondary>
</indexterm>The directory in which screen recording files
should be created. <emphasis>If a graphical recording needs
to be created, then this parameter is
required.</emphasis> Specifying this parameter enables
graphical screen recording. If this parameter is omitted, no
graphical recording will be created.</para>
</entry>
</row>
<row>
<entry><parameter>create-recording-path</parameter></entry>
<entry>
<para>If set to "true", the directory specified by the
<parameter>recording-path</parameter> parameter will
automatically be created if it does not yet exist. Only the
final directory in the path will be created - if other
directories earlier in the path do not exist, automatic
creation will fail, and an error will be logged.</para>
<para><emphasis>This parameter is optional.</emphasis> By
default, the directory specified by the
<parameter>recording-path</parameter> parameter will not
automatically be created, and attempts to create recordings
within a non-existent directory will be logged as
errors.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-name</parameter></entry>
<entry>
<para>The filename to use for any created recordings.
<emphasis>This parameter is optional.</emphasis> If
omitted, the value "recording" will be used instead.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-exclude-output</parameter></entry>
<entry>
<para>If set to "true", graphical output and other data normally
streamed from server to client will be excluded from the
recording, producing a recording which contains only user
input events. <emphasis>This parameter is
optional.</emphasis> If omitted, graphical output will
be included in the recording.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-exclude-mouse</parameter></entry>
<entry>
<para>If set to "true", user mouse events will be excluded from
the recording, producing a recording which lacks a visible
mouse cursor. <emphasis>This parameter is
optional.</emphasis> If omitted, mouse events will be
included in the recording.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
<row>
<entry><parameter>recording-include-keys</parameter></entry>
<entry>
<para>If set to "true", user key events will be included in the
recording. The recording can subsequently be passed through
the <command>guaclog</command> utility to produce a
human-readable interpretation of the keys pressed during the
session. <emphasis>This parameter is optional.</emphasis> If
omitted, key events will be not included in the
recording.</para>
<para>This parameter only has an effect if graphical recording
is enabled. If the <parameter>recording-path</parameter> is
not specified, graphical session recording will be disabled,
and this parameter will be ignored.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="adding-kubernetes">
<title>Adding a Kubernetes connection</title>
<indexterm>
<primary>Kubernetes</primary>
<secondary>adding</secondary>
</indexterm>
<para>If you are using the default authentication built into Guacamole, and you wish
to grant access to a Kubernetes connection to a particular user, you need to
locate the <code>&lt;authorize></code> section for that user within your
<filename>user-mapping.xml</filename>, and add a section like the following
within it:</para>
<programlisting>&lt;connection name="<replaceable>Unique Name</replaceable>">
&lt;protocol>kubernetes&lt;/protocol>
&lt;param name="hostname"><replaceable>localhost</replaceable>&lt;/param>
&lt;param name="pod"><replaceable>mypod</replaceable>&lt;/param>
&lt;/connection></programlisting>
<para>If added exactly as above, a new connection named "<replaceable>Unique
Name</replaceable>" will be available to the user associated with the
<code>&lt;authorize></code> section containing it. The connection will
connect to the Kubernetes server running on <replaceable>localhost</replaceable>
and attach to the first container of the pod
<replaceable>mypod</replaceable>.</para>
</section>
</section>
<section xml:id="parameter-tokens">
<title>Parameter tokens</title>
<indexterm>
<primary>tokens</primary>
</indexterm>
<para>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.</para>
<para>Each token is of the form
<varname>${<replaceable>TOKEN_NAME</replaceable>}</varname>, where
<replaceable>TOKEN_NAME</replaceable> 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}".</para>
<variablelist>
<varlistentry>
<term><varname>${GUAC_USERNAME}</varname></term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>${GUAC_PASSWORD}</varname></term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>${GUAC_CLIENT_ADDRESS}</varname></term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>${GUAC_CLIENT_HOSTNAME}</varname></term>
<listitem>
<para>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 <varname>${GUAC_CLIENT_ADDRESS}</varname>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>${GUAC_DATE}</varname></term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>${GUAC_TIME}</varname></term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
</variablelist>
<para>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.</para>
<section xml:id="extension-tokens">
<title>Extension-specific tokens</title>
<indexterm>
<primary>tokens</primary>
<secondary>extension-specific</secondary>
</indexterm>
<para>Each extension can also implement its own arbitrary tokens that can dynamically
fill in values provided by the extension. Within these extensions, attribute
names are canonicalized into a standard format that consists of all capital
letters separated by underscores.</para>
<section xml:id="cas-tokens">
<title>CAS Extension Tokens</title>
<indexterm>
<primary>tokens</primary>
<secondary>cas</secondary>
</indexterm>
<para>The CAS extension will read attributes provided by the CAS server when
a user is authenticated and will make those attributes available as
tokens. The CAS server must be specifically configured to release certain
attributes to the client (Guacamole), and configuration of that is outside
the scope of this document. Any attribute that the CAS server is
configured to release should be available to Guacamole as a token for
use within a connection. The token name will be prepended with the
<constant>CAS_</constant> prefix. A CAS server configured to release
attributes <varname>firstname</varname>, <varname>lastname</varname>,
<varname>email</varname>, and <varname>mobile</varname> would produce the
following tokens:</para>
<itemizedlist>
<listitem>
<para>
<varname>${CAS_FIRSTNAME}</varname>
</para>
</listitem>
<listitem>
<para>
<varname>${CAS_LASTNAME}</varname>
</para>
</listitem>
<listitem>
<para>
<varname>${CAS_EMAIL}</varname>
</para>
</listitem>
<listitem>
<para>
<varname>${CAS_MOBILE}</varname>
</para>
</listitem>
</itemizedlist>
</section>
</section>
</section>
</section>
<section xml:id="guacd.conf">
<title>Configuring guacd</title>
<para><indexterm>
<primary>guacd.conf</primary>
</indexterm>guacd is configured with a configuration file called
<filename>guacd.conf</filename>, by default located in
<filename>/etc/guacamole</filename>. This file follows a simple, INI-like
format:</para>
<informalexample>
<programlisting>#
# 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</programlisting>
</informalexample>
<para>Configuration options are given as parameter/value pairs, where the name of the
parameter is specified on the left side of an "<code>=</code>", 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.</para>
<para>For the sake of documentation and readability, comments can be added anywhere within
guacd.conf using "<code>#</code>" symbols. All text following a "<code>#</code>" until
end-of-line will be ignored.</para>
<para>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:</para>
<informalexample>
<programlisting>[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"</programlisting>
</informalexample>
<para>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:</para>
<informalexample>
<programlisting># 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"</programlisting>
</informalexample>
<para>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:</para>
<orderedlist>
<listitem>
<para>If the value contains no special characters, just include it as-is.</para>
</listitem>
<listitem>
<para>If the value contains any special characters (whitespace, newlines,
<code>#</code>, <code>\</code>, or <code>"</code>), enclose the entire value
within double quotes.</para>
</listitem>
<listitem>
<para>If the value is enclosed within double quotes, escape newlines,
<code>\</code>, and <code>"</code> with a backslash.</para>
</listitem>
</orderedlist>
<table frame="all">
<title>guacd.conf parameters</title>
<indexterm>
<primary>parameters</primary>
<secondary>guacd.conf</secondary>
</indexterm>
<tgroup cols="3">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="1.85*"/>
<colspec colname="c3" colnum="3" colwidth="5.55*"/>
<thead>
<row>
<entry>Section</entry>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parameter>daemon</parameter></entry>
<entry><parameter>pid_file</parameter></entry>
<entry>
<para><indexterm>
<primary><parameter>pid_file</parameter></primary>
</indexterm>The name of the file in which the PID of the main guacd
process should be written. This is mainly needed for startup
scripts, which need to monitor the state of guacd, killing it if
necessary. If this parameter is specified, the user running guacd
must have sufficient permissions to create or modify the specified
file, or startup will fail.</para>
</entry>
</row>
<row>
<entry><parameter>daemon</parameter></entry>
<entry><parameter>log_level</parameter></entry>
<entry>
<para><indexterm>
<primary>logging</primary>
<secondary>guacd</secondary>
</indexterm><indexterm>
<primary>guacd</primary>
<secondary>logging</secondary>
</indexterm><indexterm>
<primary><parameter>log_level</parameter></primary>
</indexterm>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 <constant>info</constant> will be used.</para>
<para>Legal values are <constant>trace</constant>,
<constant>debug</constant>, <constant>info</constant>,
<constant>warning</constant>, and
<constant>error</constant>.</para>
</entry>
</row>
<row>
<entry><parameter>server</parameter></entry>
<entry><parameter>bind_host</parameter></entry>
<entry>
<para><indexterm>
<primary><parameter>bind_host</parameter></primary>
</indexterm>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.</para>
</entry>
</row>
<row>
<entry><parameter>server</parameter></entry>
<entry><parameter>bind_port</parameter></entry>
<entry>
<para><indexterm>
<primary><parameter>bind_port</parameter></primary>
</indexterm>The port that guacd should bind to when listening for
connections. If unspecified, port 4822 will be used.</para>
</entry>
</row>
<row>
<entry><parameter>ssl</parameter></entry>
<entry><parameter>server_certificate</parameter></entry>
<entry>
<para><indexterm>
<primary><parameter>server_certificate</parameter></primary>
</indexterm>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
<filename>guacamole.properties</filename> to use SSL as
well.</para>
</entry>
</row>
<row>
<entry><parameter>ssl</parameter></entry>
<entry><parameter>server_key</parameter></entry>
<entry>
<para><indexterm>
<primary><parameter>server_key</parameter></primary>
</indexterm>The filename of the private key to use for SSL
encryption of the Guacamole protocol. If this option is specified,
SSL encryption will be enabled, and the Guacamole web application
will need to be configured within
<filename>guacamole.properties</filename> to use SSL as
well.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>You can also affect the configuration of guacd with command-line options. If given,
these options take precendence over the system-wide configuration file:</para>
<variablelist>
<varlistentry>
<term><option>-b <replaceable>HOST</replaceable></option></term>
<listitem>
<para>Changes the host or address that guacd listens on.</para>
<para>This corresponds to the <parameter>bind_host</parameter> parameter within
the <parameter>server</parameter> section of
<filename>guacd.conf</filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-l <replaceable>PORT</replaceable></option></term>
<listitem>
<para>Changes the port that guacd listens on (the default is port 4822).</para>
<para>This corresponds to the <parameter>bind_port</parameter> parameter within
the <parameter>server</parameter> section of
<filename>guacd.conf</filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-p <replaceable>PIDFILE</replaceable></option></term>
<listitem>
<para>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.</para>
<para>This corresponds to the <parameter>pid_file</parameter> parameter within
the <parameter>daemon</parameter> section of
<filename>guacd.conf</filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-L <replaceable>LEVEL</replaceable></option></term>
<listitem>
<para>Sets the maximum level at which guacd will log messages to syslog and, if
running in the foreground, the console. Legal values are
<constant>trace</constant>, <constant>debug</constant>,
<constant>info</constant>, <constant>warning</constant>, and
<constant>error</constant>. The default value is
<constant>info</constant>.</para>
<para>This corresponds to the <parameter>log_level</parameter> parameter within
the <parameter>daemon</parameter> section of
<filename>guacd.conf</filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-f</option></term>
<listitem>
<para>Causes guacd to run in the foreground, rather than automatically forking
into the background.</para>
</listitem>
</varlistentry>
</variablelist>
<para>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:</para>
<variablelist>
<varlistentry>
<term><option>-C <replaceable>CERTIFICATE</replaceable></option></term>
<listitem>
<para>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
<filename>guacamole.properties</filename> to use SSL as well.</para>
<para>This corresponds to the <parameter>server_certificate</parameter>
parameter within the <parameter>ssl</parameter> section of
<filename>guacd.conf</filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-K <replaceable>KEY</replaceable></option></term>
<listitem>
<para>The filename of the private key to use for SSL encryption of the Guacamole
protocol. If this option is specified, SSL encryption will be enabled, and
the Guacamole web application will need to be configured within
<filename>guacamole.properties</filename> to use SSL as well.</para>
<para>This corresponds to the <parameter>server_key</parameter> parameter within
the <parameter>ssl</parameter> section of
<filename>guacd.conf</filename>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</chapter>