| <?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, it will be minimally configured to use the default |
| authentication, which reads all users and connections from a single, monolithic |
| <filename>user-mapping.xml</filename> file. You can modify this configuration if you |
| need to use a different authentication module (such as the MySQL authentication, which is |
| discussed in a separate chapter) or if you need to veer from the defaults.</para> |
| <para>Guacamole's configuration 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></title> |
| <indexterm xmlns:xl="http://www.w3.org/1999/xlink"> |
| <primary><varname>GUACAMOLE_HOME</varname></primary> |
| </indexterm> |
| <para>Guacamole reads files from its own configuration directory by default, resorting to |
| the classpath only when this directory cannot be found. When locating this directory, |
| Guacamole will try, in order:</para> |
| <orderedlist> |
| <listitem> |
| <para>The directory specified within the system property |
| <property>guacamole.home</property>.</para> |
| </listitem> |
| <listitem> |
| <para>The directory specified within the environment variable |
| <varname>GUACAMOLE_HOME</varname>.</para> |
| </listitem> |
| <listitem> |
| <para>The directory <filename>.guacamole</filename>, located |
| within the home directory of the user running the servlet |
| container.</para> |
| </listitem> |
| </orderedlist> |
| <para>This directory will be referred to as |
| <varname>GUACAMOLE_HOME</varname> elsewhere in the |
| documentation.</para> |
| <para>Guacamole uses <varname>GUACAMOLE_HOME</varname> as the primary |
| search location for configuration file like |
| <filename>guacamole.properties</filename>.</para> |
| </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>At the bare minimum, the <filename>guacamole.properties</filename> file contains at |
| least three basic properties, required in all deployments of Guacamole: </para> |
| <variablelist> |
| <varlistentry> |
| <term><indexterm xmlns:xl="http://www.w3.org/1999/xlink"> |
| <primary>guacd-host</primary> |
| </indexterm><parameter>guacd-host</parameter></term> |
| <listitem> |
| <para>The host the Guacamole proxy daemon (<package>guacd</package>) is |
| listening on. This is most likely 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. This is port 4822 by default. </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><indexterm xmlns:xl="http://www.w3.org/1999/xlink"> |
| <primary>auth-provider</primary> |
| </indexterm><parameter>auth-provider</parameter></term> |
| <listitem> |
| <para>The authentication provider to use when authenticating. Normally, this |
| will be set to <classname>BasicFileAuthenticationProvider</classname> which |
| is the default authentication provider provided with Guacamole. No |
| extensions are needed if you use the default authentication provider.</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| <para>If you need custom authentication or wish to enable optional features of Guacamole, |
| such as WebSocket or HTTP Basic authentication support, you will need to specify |
| additional properties:</para> |
| <variablelist> |
| <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", requires SSL/TLS encryption between the web application |
| and guacd. This property is not required. By default, communication between |
| the web application and guacd will be unencrypted.</para> |
| <para>Note that if you enable this option, you must also configure guacd to use |
| SSL via command line options. These options are documented in the manpage of |
| guacd. You will need an SSL certificate and private key.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><indexterm xmlns:xl="http://www.w3.org/1999/xlink"> |
| <primary>lib-directory</primary> |
| </indexterm><parameter>lib-directory</parameter></term> |
| <listitem> |
| <para>The directory to load extensions to Guacamole from. If you wish to use a |
| custom authentication provider or custom hooks, the |
| <filename>.jar</filename> file and all dependencies must be placed in |
| the directory specified here. On most systems, |
| <filename>/var/lib/guacamole/classpath</filename> is an appropriate |
| choice.</para> |
| <para>Note that this property is only needed if you are using an |
| extension.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><indexterm xmlns:xl="http://www.w3.org/1999/xlink"> |
| <primary>event-listeners</primary> |
| </indexterm><parameter>event-listeners</parameter></term> |
| <listitem> |
| <para>A comma-delimited list of event listeners which should be loaded and |
| installed such that they are informed of Guacamole-related events. These |
| classes must be in the classpath, preferably by having their corresponding |
| <filename>.jar</filename> files placed within the directory specified by |
| the <property>lib-directory</property> property.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><indexterm xmlns:xl="http://www.w3.org/1999/xlink"> |
| <primary>enable-websocket</primary> |
| </indexterm><indexterm> |
| <primary>WebSocket</primary> |
| </indexterm><parameter>enable-websocket</parameter></term> |
| <listitem> |
| <para><constant>true</constant> if WebSocket support should be enabled, |
| <constant>false</constant> (or simply leave the property out) |
| otherwise.</para> |
| <para>WebSocket is supported in Guacamole for Tomcat 7 and Jetty 8. Note that if |
| Tomcat is used, it must be version 7.0.37 or newer. Older versions of Tomcat |
| are only supported for HTTP. Guacamole does not yet support Tomcat 8 for |
| WebSocket.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><indexterm xmlns:xl="http://www.w3.org/1999/xlink"> |
| <primary>enable-http-auth</primary> |
| </indexterm><indexterm> |
| <primary>HTTP Basic authentication</primary> |
| </indexterm><parameter>enable-http-auth</parameter></term> |
| <listitem> |
| <para><constant>true</constant> if HTTP Basic authentication support should be |
| enabled, <constant>false</constant> (or simply leave the property out) |
| otherwise. This will <emphasis>not</emphasis> cause Guacamole to require |
| HTTP Basic authentication; it simply tells Guacamole to inspect the HTTP |
| "Authorization" header when authenticating users, if present.</para> |
| <para>When HTTP Basic authentication is in use, the web browser submits the |
| username/password pair with each HTTP request in an "Authorization" header. |
| If you have an upstream authentication system or proxy which uses HTTP Basic |
| authentication, setting this property causes Guacamole to read and use these |
| credentials if the username and password are not given through other |
| means.</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| <example> |
| <title>Minimal <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 |
| |
| # Authentication provider class |
| auth-provider: net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider |
| |
| # Properties used by BasicFileAuthenticationProvider |
| basic-user-mapping: /etc/guacamole/user-mapping.xml</programlisting> |
| </example> |
| <section> |
| <title>Should I use WebSocket?</title> |
| <indexterm> |
| <primary>WebSocket</primary> |
| </indexterm> |
| <para>Yes, if you can.</para> |
| <para>WebSocket has performance benefits and a much lower overhead on the client, so |
| enabling WebSocket is beneficial if you know your servlet container supports it. In |
| the event that Guacamole cannot connect using WebSocket, it will immediately and |
| transparently fall back to using HTTP. If things are regularly not working as |
| expected, and you suspect it's the WebSocket support, you can always disable it by |
| editing <filename>guacamole.properties</filename>.</para> |
| <para>When eventually WebSocket is widely supported across servlet containers and |
| network hardware, it will likely be enabled by default.</para> |
| </section> |
| </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. If you wish to use this authentication mechanism, |
| you must ensure the <property>auth-provider</property> property is |
| set to the fully-qualified name of |
| <classname>BasicFileAuthenticationProvider</classname><footnote> |
| <para><classname>net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider</classname></para> |
| </footnote>This is the case within the example |
| <filename>guacamole.properties</filename> file shown above, and |
| in the <filename>guacamole.properties</filename> file included with |
| Guacamole. Unless you have already tried another authentication |
| module, you will not need to edit this value yourself if you are |
| using the configuration files that come with Guacamole.</para> |
| <para>There are other authentication modules available. The Guacamole |
| project now provides a MySQL-backed authentication module with extra |
| features (like the ability to manage connections and users from the |
| web interface), and other authentication modules can be created |
| using the extension API provided along with the Guacamole web |
| application, <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" (typically named |
| <filename>user-mapping.xml</filename>). An example of this |
| 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="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, installed by default.</para> |
| <table frame="all" xml:id="vnc-parameters"> |
| <title>VNC configuration parameters</title> |
| <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>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>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> |
| <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> |
| <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>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>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.</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> |
| <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>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> |
| <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", <emphasis>experimental</emphasis> |
| sound support will be enabled. VNC does not support sound, but |
| Guacamole's VNC support can include sound using PulseAudio.</para> |
| <para>Most Linux systems provide audio through a service called |
| PulseAudio. This service is capable of communicating over the |
| network. If PulseAudio is configured to allow TCP connections, |
| Guacamole can connect to your PulseAudio server and combine its |
| audio with the graphics coming over VNC.</para> |
| <para>Beware that you must disable authentication within PulseAudio in |
| order to allow Guacamole to connect, as Guacamole does not yet |
| support this. The amount of latency you will see depends largely on |
| the network and how PulseAudio is configured.</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> |
| <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> |
| </table> |
| <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> |
| <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> |
| <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> |
| <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> |
| <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> |
| <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> |
| <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 depends on a recent version of FreeRDP (version 1.0 or higher). If your |
| distribution does not have a recent enough version of FreeRDP, the Guacamole project |
| will not build a <package>libguac-client-rdp</package> package for you. You will need to |
| build and install a recent version of FreeRDP, and then build and install |
| <package>libguac-client-rdp</package> from source.</para> |
| <table frame="all"> |
| <title>RDP configuration parameters</title> |
| <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>Name</entry> |
| <entry>Description</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry><parameter>hostname</parameter></entry> |
| <entry> |
| <para><indexterm> |
| <primary>RDP</primary> |
| <secondary>hostname</secondary> |
| </indexterm>The hostname or IP address of the RDP server Guacamole |
| should connect to.</para> |
| </entry> |
| </row> |
| <row> |
| <entry><parameter>port</parameter></entry> |
| <entry> |
| <para><indexterm> |
| <primary>RDP</primary> |
| <secondary>port</secondary> |
| </indexterm>The port the RDP server is listening on, usually 3389. |
| This parameter is optional. If this is not specified, the default of |
| 3389 will be used.</para> |
| </entry> |
| </row> |
| <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>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>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-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>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-path</parameter></entry> |
| <entry> |
| <para>The directory on the Guacamole server in which transfered files |
| should be stored. This directory must be accessible by guacd and |
| both readable and writable by the user that runs guacd. |
| <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>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>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>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>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>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>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, the server is |
| allowed to control what type of security is used.</para> |
| <para>Possible values are:</para> |
| <variablelist> |
| <varlistentry> |
| <term><constant>rdp</constant></term> |
| <listitem> |
| <para>Standard RDP encryption. This mode should be supported |
| by all RDP servers.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><constant>nla</constant></term> |
| <listitem> |
| <para>Network Level Authentication. This mode requires the |
| username and password, and performs an authentication |
| step before the remote desktop session actually starts. |
| If the username and password are not given, the |
| connection cannot be made.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><constant>tls</constant></term> |
| <listitem> |
| <para>TLS encryption. TLS (Transport Layer Security) is the |
| successor to SSL.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><constant>any</constant></term> |
| <listitem> |
| <para>Allow the server to choose the type of security. This |
| is the default.</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> |
| <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> |
| <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> |
| </table> |
| <section> |
| <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 depends on libssh2 and libssl.</para> |
| <table frame="all"> |
| <title>SSH configuration parameters</title> |
| <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>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>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>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>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>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> |
| </table> |
| <section> |
| <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 depends on libtelnet.</para> |
| <table frame="all"> |
| <title>Telnet configuration parameters</title> |
| <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>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> |
| <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>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</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>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>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> |
| </tbody> |
| </tgroup> |
| </table> |
| <section> |
| <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> |
| <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> |
| </section> |
| </section> |
| <section> |
| <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 |
| |
| [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>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>-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> |
