| <?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><configuration> |
| |
| <!-- Appender for debugging --> |
| <appender name="GUAC-DEBUG" class="ch.qos.logback.core.ConsoleAppender"> |
| <encoder> |
| <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> |
| </encoder> |
| </appender> |
| |
| <!-- Log at DEBUG level --> |
| <root level="debug"> |
| <appender-ref ref="GUAC-DEBUG"/> |
| </root> |
| |
| </configuration></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><user-mapping> |
| |
| <!-- Per-user authentication and config information --> |
| <authorize username="USERNAME" password="PASSWORD"> |
| <protocol>vnc</protocol> |
| <param name="hostname">localhost</param> |
| <param name="port">5900</param> |
| <param name="password">VNCPASS</param> |
| </authorize> |
| |
| <!-- Another user, but using md5 to hash the password |
| (example below uses the md5 hash of "PASSWORD") --> |
| <authorize |
| username="USERNAME2" |
| password="319f4d26e3c536b5dd871bb2c52e3178" |
| encoding="md5"> |
| |
| <!-- First authorized connection --> |
| <connection name="localhost"> |
| <protocol>vnc</protocol> |
| <param name="hostname">localhost</param> |
| <param name="port">5901</param> |
| <param name="password">VNCPASS</param> |
| </connection> |
| |
| <!-- Second authorized connection --> |
| <connection name="otherhost"> |
| <protocol>vnc</protocol> |
| <param name="hostname">otherhost</param> |
| <param name="port">5900</param> |
| <param name="password">VNCPASS</param> |
| </connection> |
| |
| </authorize> |
| |
| </user-mapping></programlisting> |
| <para>Each user is specified with a corresponding |
| <code><authorize></code> tag. This tag contains all |
| authorized connections for that user, each denoted with a |
| <code><connection></code> tag. Each |
| <code><connection></code> tag contains a corresponding |
| protocol and set of protocol-specific parameters, specified with |
| the <code><protocol></code> and <code><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><authorize></code> tags, which each have a |
| <code>username</code> and <code>password</code> |
| attribute. Each <code><authorize></code> tag authorizes a |
| specific username/password pair to access all connections |
| within the tag:</para> |
| <programlisting><authorize username="<replaceable>USER</replaceable>" password="<replaceable>PASS</replaceable>"> |
| ... |
| </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><authorize username="<replaceable>USER</replaceable>" |
| password="<replaceable>319f4d26e3c536b5dd871bb2c52e3178</replaceable>" |
| encoding="md5"> |
| ... |
| </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><authorize></code> tag, you can either list a |
| single protocol and set of parameters (specified with a |
| <code><protocol></code> tag and any number of |
| <code><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><connection></code> tags, each of which can be |
| named and contains a <code><protocol></code> tag and any |
| number of <code><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.2.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><authorize></code> section for that user within your |
| <filename>user-mapping.xml</filename>, and add a section like the following |
| within it:</para> |
| <programlisting><connection name="<replaceable>Unique Name</replaceable>"> |
| <protocol>vnc</protocol> |
| <param name="hostname"><replaceable>localhost</replaceable></param> |
| <param name="port"><replaceable>5901</replaceable></param> |
| </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><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><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. This |
| parameter is optional. If this is not specified, the |
| standard port for RDP (3389) or Hyper-V's default port for |
| VMConnect (2179) will be used, depending on the security |
| mode selected.</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. All RDP connections are encrypted.</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.</para> |
| <important> |
| <para>If your server requires NLA, you <emphasis>must</emphasis> provide a |
| username and password. Leveraging Guacamole's <link |
| xmlns:xlink="http://www.w3.org/1999/xlink" linkend="parameter-tokens" |
| >parameter tokens</link> and <link |
| xmlns:xlink="http://www.w3.org/1999/xlink" linkend="ldap-auth">LDAP |
| support</link> to integrate with Active Directory and automatically pass |
| through credentials is a common configuration.</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>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, a |
| security mode is selected based on a negotiation process |
| which determines what both the client and the server |
| support.</para> |
| <para>Possible values are:</para> |
| <variablelist> |
| <varlistentry> |
| <term><constant>any</constant></term> |
| <listitem> |
| <para>Automatically select the security mode based |
| on the security protocols supported by both the |
| client and the server. <emphasis>This is the |
| default</emphasis>.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><constant>nla</constant></term> |
| <listitem> |
| <para>Network Level Authentication, sometimes also |
| referred to as "hybrid" or CredSSP (the protocol |
| that drives NLA). This mode uses TLS encryption |
| and requires the username and password to be given |
| in advance. Unlike RDP mode, the authentication |
| step is performed before the remote desktop |
| session actually starts, avoiding the need for the |
| Windows server to allocate significant resources |
| for users that may not be authorized.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><constant>nla-ext</constant></term> |
| <listitem> |
| <para>Extended Network Level Authentication. This |
| mode is identical to NLA except that an additional |
| "<link xmlns:xlink="http://www.w3.org/1999/xlink" |
| xlink:href="https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-rdpbcgr/d0e560a3-25cb-4563-8bdc-6c4cc625bbfc" |
| >Early User Authorization Result</link>" is |
| required to be sent from the server to the client |
| immediately after the NLA handshake is |
| completed.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><constant>tls</constant></term> |
| <listitem> |
| <para>RDP authentication and encryption implemented |
| via TLS (Transport Layer Security). Also referred |
| to as RDSTLS, the TLS security mode is primarily |
| used in load balanced configurations where the |
| initial RDP server may redirect the connection to |
| a different RDP server.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><constant>vmconnect</constant></term> |
| <listitem> |
| <para>Automatically select the security mode based |
| on the security protocols supported by both the |
| client and the server, limiting that negotiation |
| to only the protocols known to be supported by |
| <link xmlns:xlink="http://www.w3.org/1999/xlink" |
| linkend="rdp-preconnection-pdu">Hyper-V / |
| VMConnect</link>.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><constant>rdp</constant></term> |
| <listitem> |
| <para>Standard RDP encryption. This mode is |
| generally only used for older Windows servers or |
| in cases where a standard Windows login screen is |
| desired. Newer versions of Windows have this mode |
| disabled by default and will only accept NLA |
| unless explicitly configured otherwise.</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.2.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.2.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 / VMConnect)</title> |
| <para><indexterm> |
| <primary>preconnection PDU</primary> |
| </indexterm><indexterm> |
| <primary>Hyper-V</primary> |
| </indexterm><indexterm> |
| <primary>VMConnect</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><emphasis>If you do intend to use Hyper-V, beware that its built-in RDP server |
| requires different parameters for authentication and Guacamole's defaults |
| will not work.</emphasis> In most cases, you will need to do the following |
| when connecting to Hyper-V:</para> |
| <orderedlist> |
| <listitem> |
| <para>Specify both "<parameter>username</parameter>" and |
| "<parameter>password</parameter>" appropriately, and set |
| "<parameter>security</parameter>" to |
| "<constant>vmconnect</constant>". Selecting the |
| "<constant>vmconnect</constant>" security mode will configure |
| Guacamole to automatically negotiate security modes known to be |
| supported by Hyper-V, and will automatically select Hyper-V's default |
| RDP port (2179).</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> |
| <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> |
| </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> |
| <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><authorize></code> section for that user within your |
| <filename>user-mapping.xml</filename>, and add a section like the following |
| within it:</para> |
| <programlisting><connection name="<replaceable>Unique Name</replaceable>"> |
| <protocol>rdp</protocol> |
| <param name="hostname"><replaceable>localhost</replaceable></param> |
| <param name="port"><replaceable>3389</replaceable></param> |
| </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><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><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<n></constant></term> |
| <listitem> |
| <para>Set the color at index <code><n></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<n></constant></term> |
| <listitem> |
| <para>Use the color currently assigned to index |
| <code><n></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, "<code>linux</code>" |
| 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.2.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><authorize></code> section for that user within your |
| <filename>user-mapping.xml</filename>, and add a section like the following |
| within it:</para> |
| <programlisting><connection name="<replaceable>Unique Name</replaceable>"> |
| <protocol>ssh</protocol> |
| <param name="hostname"><replaceable>localhost</replaceable></param> |
| <param name="port"><replaceable>22</replaceable></param> |
| </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><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><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<n></constant></term> |
| <listitem> |
| <para>Set the color at index <code><n></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<n></constant></term> |
| <listitem> |
| <para>Use the color currently assigned to index |
| <code><n></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, |
| "<code>linux</code>" 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.2.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><authorize></code> section for that user within your |
| <filename>user-mapping.xml</filename>, and add a section like the following |
| within it:</para> |
| <programlisting><connection name="<replaceable>Unique Name</replaceable>"> |
| <protocol>telnet</protocol> |
| <param name="hostname"><replaceable>localhost</replaceable></param> |
| <param name="port"><replaceable>23</replaceable></param> |
| </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><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<n></constant></term> |
| <listitem> |
| <para>Set the color at index <code><n></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<n></constant></term> |
| <listitem> |
| <para>Use the color currently assigned to index |
| <code><n></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, |
| "<code>linux</code>" 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.2.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><authorize></code> section for that user within your |
| <filename>user-mapping.xml</filename>, and add a section like the following |
| within it:</para> |
| <programlisting><connection name="<replaceable>Unique Name</replaceable>"> |
| <protocol>kubernetes</protocol> |
| <param name="hostname"><replaceable>localhost</replaceable></param> |
| <param name="pod"><replaceable>mypod</replaceable></param> |
| </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><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 xml:id="ldap-tokens"> |
| <title>LDAP Extension Tokens</title> |
| <indexterm> |
| <primary>tokens</primary> |
| <secondary>ldap</secondary> |
| </indexterm> |
| <para>The LDAP extension will read user attributes provided by the LDAP |
| server and specified in the <filename>guacamole.properties</filename> |
| file. The attributes retrieved for a user are configured using the |
| <parameter>ldap-user-attributes</parameter> parameter. The user must |
| be able to read the attribute values from their own LDAP object. |
| The token name will be prepended with the <constant>LDAP_</constant> |
| prefix. As an example, configuring the following line in |
| <filename>guacamole.properties</filename>:</para> |
| <informalexample><programlisting>ldap-user-attributes: cn, givenName, sn, mobile, mail |
| </programlisting></informalexample> |
| <para>will produce the below tokens that can be used in connection |
| parameters:</para> |
| <itemizedlist> |
| <listitem> |
| <para> |
| <varname>${LDAP_CN}</varname> |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <varname>${LDAP_GIVENNAME}</varname> |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <varname>${LDAP_SN}</varname> |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <varname>${LDAP_MOBILE}</varname> |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <varname>${LDAP_MAIL}</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> |