| <?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 provides five |
| basic properties: </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>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>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. </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. </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> |
| </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 |
| |
| # Location to read extra .jar's from |
| lib-directory: /var/lib/guacamole/classpath |
| |
| # 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> |
| <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>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> |
| </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 0.8.0, 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>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> |
| </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 0.8.0, 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 libssh.</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> |
| </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> |
| |
| </chapter> |
