| <?xml version="1.0" encoding="UTF-8" standalone="no"?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 3. Configuring Guacamole</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="users-guide.html" title="Part I. User's Guide" /><link rel="prev" href="installing-guacamole.html" title="Chapter 2. Installing Guacamole" /><link rel="next" href="mysql-auth.html" title="Chapter 4. MySQL authentication" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/> |
| </head><body> |
| <!-- CONTENT --> |
| |
| <div id="page"><div id="content"> |
| <div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 3. Configuring Guacamole</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="installing-guacamole.html">Prev</a> </td><th width="60%" align="center">Part I. User's Guide</th><td width="20%" align="right"> <a accesskey="n" href="mysql-auth.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="configuring-guacamole"></a>Chapter 3. Configuring Guacamole</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="configuring-guacamole.html#guacamole-home"><code class="varname">GUACAMOLE_HOME</code></a></span></dt><dt><span class="section"><a href="configuring-guacamole.html#initial-setup"><code class="filename">guacamole.properties</code></a></span></dt><dd><dl><dt><span class="section"><a href="configuring-guacamole.html#idm139993936183616">Should I use WebSocket?</a></span></dt></dl></dd><dt><span class="section"><a href="configuring-guacamole.html#basic-auth">Using the default authentication</a></span></dt><dd><dl><dt><span class="section"><a href="configuring-guacamole.html#user-mapping"><code class="filename">user-mapping.xml</code></a></span></dt></dl></dd><dt><span class="section"><a href="configuring-guacamole.html#vnc">VNC</a></span></dt><dd><dl><dt><span class="section"><a href="configuring-guacamole.html#adding-vnc">Adding a VNC connection</a></span></dt><dt><span class="section"><a href="configuring-guacamole.html#idm139993936067440">Which VNC server?</a></span></dt></dl></dd><dt><span class="section"><a href="configuring-guacamole.html#rdp">RDP</a></span></dt><dd><dl><dt><span class="section"><a href="configuring-guacamole.html#idm139993936035520">Adding an RDP connection</a></span></dt></dl></dd><dt><span class="section"><a href="configuring-guacamole.html#ssh">SSH</a></span></dt><dd><dl><dt><span class="section"><a href="configuring-guacamole.html#idm139993935872944">Adding an SSH connection</a></span></dt></dl></dd><dt><span class="section"><a href="configuring-guacamole.html#telnet">Telnet</a></span></dt><dd><dl><dt><span class="section"><a href="configuring-guacamole.html#idm139993935825472">Adding a telnet connection</a></span></dt><dt><span class="section"><a href="configuring-guacamole.html#idm139993935818944">Authentication</a></span></dt></dl></dd><dt><span class="section"><a href="configuring-guacamole.html#idm139993935807904">Configuring guacd</a></span></dt></dl></div> |
| |
| |
| <p>After installing Guacamole, it will be minimally configured to use the default |
| authentication, which reads all users and connections from a single, monolithic |
| <code class="filename">user-mapping.xml</code> 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.</p> |
| <p>Guacamole's configuration consists of two main pieces: a directory |
| referred to as <code class="varname">GUACAMOLE_HOME</code>, which is the primary |
| search location for configuration files, and |
| <code class="filename">guacamole.properties</code>, the main configuration |
| file used by Guacamole and its extensions.</p> |
| <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="guacamole-home"></a><code class="varname">GUACAMOLE_HOME</code></h2></div></div></div> |
| |
| <a id="idm139993936238848" class="indexterm"></a> |
| <p>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:</p> |
| <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> |
| <p>The directory specified within the system property |
| <span class="property">guacamole.home</span>.</p> |
| </li><li class="listitem"> |
| <p>The directory specified within the environment variable |
| <code class="varname">GUACAMOLE_HOME</code>.</p> |
| </li><li class="listitem"> |
| <p>The directory <code class="filename">.guacamole</code>, located |
| within the home directory of the user running the servlet |
| container.</p> |
| </li></ol></div> |
| <p>This directory will be referred to as |
| <code class="varname">GUACAMOLE_HOME</code> elsewhere in the |
| documentation.</p> |
| <p>Guacamole uses <code class="varname">GUACAMOLE_HOME</code> as the primary |
| search location for configuration file like |
| <code class="filename">guacamole.properties</code>.</p> |
| </div> |
| |
| <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="initial-setup"></a><code class="filename">guacamole.properties</code></h2></div></div></div> |
| |
| <a id="idm139993936228656" class="indexterm"></a> |
| <a id="idm139993936227728" class="indexterm"></a> |
| <p>The Guacamole web application uses one main configuration file called |
| <code class="filename">guacamole.properties</code>. This file is the common location for all |
| configuration properties read by Guacamole or any extension of Guacamole, including |
| authentication providers.</p> |
| <p>In previous releases, this file had to be in the classpath of your servlet container. |
| Now, the location of <code class="filename">guacamole.properties</code> can be explicitly defined |
| with environment variables or system properties, and the classpath is only used as a |
| last resort. When searching for <code class="filename">guacamole.properties</code>, Guacamole |
| will check, in order:</p> |
| <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> |
| <p>Within <code class="varname">GUACAMOLE_HOME</code>, as defined above.</p> |
| </li><li class="listitem"> |
| <p>The classpath of the servlet container.</p> |
| </li></ol></div> |
| <p>At the bare minimum, the <code class="filename">guacamole.properties</code> file contains at |
| least three basic properties, required in all deployments of Guacamole: </p> |
| <div class="variablelist"><dl class="variablelist"><dt><span class="term"><a id="idm139993936219520" class="indexterm"></a><em class="parameter"><code>guacd-host</code></em></span></dt><dd> |
| <p>The host the Guacamole proxy daemon (<span class="package">guacd</span>) is |
| listening on. This is most likely localhost. </p> |
| </dd><dt><span class="term"><a id="idm139993936216416" class="indexterm"></a><em class="parameter"><code>guacd-port</code></em></span></dt><dd> |
| <p>The port the Guacamole proxy daemon (<span class="package">guacd</span>) is |
| listening on. This is port 4822 by default. </p> |
| </dd><dt><span class="term"><a id="idm139993936213280" class="indexterm"></a><em class="parameter"><code>auth-provider</code></em></span></dt><dd> |
| <p>The authentication provider to use when authenticating. Normally, this |
| will be set to <code class="classname">BasicFileAuthenticationProvider</code> which |
| is the default authentication provider provided with Guacamole. No |
| extensions are needed if you use the default authentication provider.</p> |
| </dd></dl></div> |
| <p>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:</p> |
| <div class="variablelist"><dl class="variablelist"><dt><span class="term"><a id="idm139993936208656" class="indexterm"></a><em class="parameter"><code>guacd-ssl</code></em></span></dt><dd> |
| <p>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.</p> |
| <p>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.</p> |
| </dd><dt><span class="term"><a id="idm139993936205024" class="indexterm"></a><em class="parameter"><code>lib-directory</code></em></span></dt><dd> |
| <p>The directory to load extensions to Guacamole from. If you wish to use a |
| custom authentication provider or custom hooks, the |
| <code class="filename">.jar</code> file and all dependencies must be placed in |
| the directory specified here. On most systems, |
| <code class="filename">/var/lib/guacamole/classpath</code> is an appropriate |
| choice.</p> |
| <p>Note that this property is only needed if you are using an |
| extension.</p> |
| </dd><dt><span class="term"><a id="idm139993936200592" class="indexterm"></a><em class="parameter"><code>event-listeners</code></em></span></dt><dd> |
| <p>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 |
| <code class="filename">.jar</code> files placed within the directory specified by |
| the <span class="property">lib-directory</span> property.</p> |
| </dd><dt><span class="term"><a id="idm139993936196624" class="indexterm"></a><a id="idm139993936195888" class="indexterm"></a><em class="parameter"><code>enable-websocket</code></em></span></dt><dd> |
| <p><code class="constant">true</code> if WebSocket support should be enabled, |
| <code class="constant">false</code> (or simply leave the property out) |
| otherwise.</p> |
| <p>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.</p> |
| </dd><dt><span class="term"><a id="idm139993936191584" class="indexterm"></a><a id="idm139993936190816" class="indexterm"></a><em class="parameter"><code>enable-http-auth</code></em></span></dt><dd> |
| <p><code class="constant">true</code> if HTTP Basic authentication support should be |
| enabled, <code class="constant">false</code> (or simply leave the property out) |
| otherwise. This will <span class="emphasis"><em>not</em></span> cause Guacamole to require |
| HTTP Basic authentication; it simply tells Guacamole to inspect the HTTP |
| "Authorization" header when authenticating users, if present.</p> |
| <p>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.</p> |
| </dd></dl></div> |
| <div class="example"><a id="idm139993936186272"></a><p class="title"><strong>Example 3.1. Minimal <code class="filename">guacamole.properties</code></strong></p><div class="example-contents"> |
| |
| <a id="guacamole.properties"></a><pre xml:lang="en" class="programlisting" 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</pre> |
| </div></div><br class="example-break" /> |
| <div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm139993936183616"></a>Should I use WebSocket?</h3></div></div></div> |
| |
| <a id="idm139993936182688" class="indexterm"></a> |
| <p>Yes, if you can.</p> |
| <p>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 <code class="filename">guacamole.properties</code>.</p> |
| <p>When eventually WebSocket is widely supported across servlet containers and |
| network hardware, it will likely be enabled by default.</p> |
| </div> |
| </div> |
| <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="basic-auth"></a>Using the default authentication</h2></div></div></div> |
| |
| <a id="idm139993936178224" class="indexterm"></a> |
| <p>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 <span class="property">auth-provider</span> property is |
| set to the fully-qualified name of |
| <code class="classname">BasicFileAuthenticationProvider</code><a href="#ftn.idm139993936176208" class="footnote" id="idm139993936176208"><sup class="footnote">[1]</sup></a>This is the case within the example |
| <code class="filename">guacamole.properties</code> file shown above, and |
| in the <code class="filename">guacamole.properties</code> 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.</p> |
| <p>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, <span class="package">guacamole-ext</span>.</p> |
| <div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="user-mapping"></a><code class="filename">user-mapping.xml</code></h3></div></div></div> |
| |
| <a id="idm139993936171040" class="indexterm"></a> |
| <p>The default authentication provider used by Guacamole reads |
| all username, password, and configuration information from a |
| file called the "user mapping" (typically named |
| <code class="filename">user-mapping.xml</code>). An example of this |
| file is included with Guacamole, and looks something like |
| this:</p> |
| <pre class="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></pre> |
| <p>Each user is specified with a corresponding |
| <code class="code"><authorize></code> tag. This tag contains all |
| authorized connections for that user, each denoted with a |
| <code class="code"><connection></code> tag. Each |
| <code class="code"><connection></code> tag contains a corresponding |
| protocol and set of protocol-specific parameters, specified with |
| the <code class="code"><protocol></code> and <code class="code"><param></code> tags |
| respectively.</p> |
| <div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="user-setup"></a>Adding users</h4></div></div></div> |
| |
| <a id="idm139993936163104" class="indexterm"></a> |
| <p>When using |
| <code class="classname">BasicFileAuthenticationProvider</code>, |
| username/password pairs are specified with |
| <code class="code"><authorize></code> tags, which each have a |
| <code class="code">username</code> and <code class="code">password</code> |
| attribute. Each <code class="code"><authorize></code> tag authorizes a |
| specific username/password pair to access all connections |
| within the tag:</p> |
| <pre class="programlisting"><authorize username="<em class="replaceable"><code>USER</code></em>" password="<em class="replaceable"><code>PASS</code></em>"> |
| ... |
| </authorize></pre> |
| <p>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:</p> |
| <pre class="programlisting"><authorize username="<em class="replaceable"><code>USER</code></em>" |
| password="<em class="replaceable"><code>319f4d26e3c536b5dd871bb2c52e3178</code></em>" |
| encoding="md5"> |
| ... |
| </authorize></pre> |
| <p>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.</p> |
| </div> |
| <div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="connection-setup"></a>Adding connections to a user</h4></div></div></div> |
| |
| <a id="idm139993936153504" class="indexterm"></a> |
| <p>To specify a connection within an |
| <code class="code"><authorize></code> tag, you can either list a |
| single protocol and set of parameters (specified with a |
| <code class="code"><protocol></code> tag and any number of |
| <code class="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 class="code"><connection></code> tags, each of which can be |
| named and contains a <code class="code"><protocol></code> tag and any |
| number of <code class="code"><param></code> tags.</p> |
| </div> |
| </div> |
| </div> |
| <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="vnc"></a>VNC</h2></div></div></div> |
| |
| <a id="idm139993936147072" class="indexterm"></a> |
| <p>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.</p> |
| <p>VNC support for Guacamole is provided by the <span class="package">libguac-client-vnc</span> |
| library, installed by default.</p> |
| <div class="table"><a id="vnc-parameters"></a><p class="title"><strong>Table 3.1. VNC configuration parameters</strong></p><div class="table-contents"> |
| |
| <a id="idm139993936143232" class="indexterm"></a> |
| <table summary="VNC configuration parameters" border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>hostname</code></em></td><td> |
| <p><a id="idm139993936135024" class="indexterm"></a>The hostname or IP address of the VNC server Guacamole |
| should connect to.</p> |
| </td></tr><tr><td><em class="parameter"><code>port</code></em></td><td> |
| <p><a id="idm139993936131840" class="indexterm"></a>The port the VNC server is listening on, usually 5900 or |
| 5900 + <em class="replaceable"><code>display number</code></em>. For example, if |
| your VNC server is serving display number 1 (sometimes written as |
| <code class="constant">:1</code>), your port number here would be |
| 5901.</p> |
| </td></tr><tr><td><em class="parameter"><code>password</code></em></td><td> |
| <p><a id="idm139993936127520" class="indexterm"></a>The password to use when attempting authentication, if |
| any. This parameter is optional.</p> |
| </td></tr><tr><td><em class="parameter"><code>read-only</code></em></td><td> |
| <p><a id="idm139993936124208" class="indexterm"></a>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.</p> |
| </td></tr><tr><td><em class="parameter"><code>swap-red-blue</code></em></td><td> |
| <p>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.</p> |
| </td></tr><tr><td><em class="parameter"><code>color-depth</code></em></td><td> |
| <p><a id="idm139993936118240" class="indexterm"></a>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.</p> |
| </td></tr><tr><td><em class="parameter"><code>cursor</code></em></td><td> |
| <p><a id="idm139993936114640" class="indexterm"></a>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.</p> |
| </td></tr><tr><td><em class="parameter"><code>autoretry</code></em></td><td> |
| <p><a id="idm139993936111216" class="indexterm"></a>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.</p> |
| </td></tr><tr><td><em class="parameter"><code>encodings</code></em></td><td> |
| <p><a id="idm139993936107712" class="indexterm"></a>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 <span class="package">libguac-client-vnc</span> |
| will use any supported encoding by default.</p> |
| <p>Beware that this parameter is intended to be replaced with |
| individual, encoding-specific parameters in a future release.</p> |
| </td></tr><tr><td><em class="parameter"><code>dest-host</code></em></td><td><a id="idm139993936103488" class="indexterm"></a><a id="idm139993936102192" class="indexterm"></a><a id="idm139993936100944" class="indexterm"></a>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.</td></tr><tr><td><em class="parameter"><code>dest-port</code></em></td><td><a id="idm139993936097888" class="indexterm"></a><a id="idm139993936096864" class="indexterm"></a>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.</td></tr><tr><td><em class="parameter"><code>enable-audio</code></em></td><td> |
| <p><a id="idm139993936093328" class="indexterm"></a><a id="idm139993936091984" class="indexterm"></a>If set to "true", <span class="emphasis"><em>experimental</em></span> |
| sound support will be enabled. VNC does not support sound, but |
| Guacamole's VNC support can include sound using PulseAudio.</p> |
| <p>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.</p> |
| <p>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.</p> |
| </td></tr><tr><td><em class="parameter"><code>audio-servername</code></em></td><td> |
| <p>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 |
| <em class="parameter"><code>hostname</code></em> parameter.</p> |
| <p>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.</p> |
| </td></tr><tr><td><em class="parameter"><code>reverse-connect</code></em></td><td> |
| <p><a id="idm139993936083168" class="indexterm"></a>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.</p> |
| </td></tr><tr><td><em class="parameter"><code>listen-timeout</code></em></td><td> |
| <p><a id="idm139993936079664" class="indexterm"></a>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).</p> |
| </td></tr></tbody></table> |
| </div></div><br class="table-break" /> |
| <div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="adding-vnc"></a>Adding a VNC connection</h3></div></div></div> |
| |
| <a id="idm139993936076272" class="indexterm"></a> |
| <p>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 class="code"><authorize></code> section for that user within your |
| <code class="filename">user-mapping.xml</code>, and add a section like the following |
| within it:</p> |
| <pre class="programlisting"><connection name="<em class="replaceable"><code>Unique Name</code></em>"> |
| <protocol>vnc</protocol> |
| <param name="hostname"><em class="replaceable"><code>localhost</code></em></param> |
| <param name="port"><em class="replaceable"><code>5901</code></em></param> |
| </connection></pre> |
| <p>If added exactly as above, a new connection named "<em class="replaceable"><code>Unique |
| Name</code></em>" will be available to the user associated with the |
| <code class="code"><authorize></code> section containing it. The connection will use VNC |
| to connect to <em class="replaceable"><code>localhost</code></em> at port |
| <em class="replaceable"><code>5901</code></em>. Naturally, you will want to change some or all |
| of these values.</p> |
| <p>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 class="code"><param></code> tags accordingly.</p> |
| <p>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.</p> |
| </div> |
| <div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm139993936067440"></a>Which VNC server?</h3></div></div></div> |
| |
| <a id="idm139993936066624" class="indexterm"></a> |
| <p>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.</p> |
| <div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="idm139993936064960"></a>RealVNC or TigerVNC</h4></div></div></div> |
| |
| <a id="idm139993936064224" class="indexterm"></a> |
| <a id="idm139993936063168" class="indexterm"></a> |
| <p>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.</p> |
| </div> |
| <div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="idm139993936061328"></a>TightVNC</h4></div></div></div> |
| |
| <a id="idm139993936060624" class="indexterm"></a> |
| <p>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.</p> |
| </div> |
| <div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="idm139993936058320"></a>x11vnc</h4></div></div></div> |
| |
| <a id="idm139993936057680" class="indexterm"></a> |
| <p>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.</p> |
| </div> |
| <div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="idm139993936055680"></a>vino</h4></div></div></div> |
| |
| <a id="idm139993936055040" class="indexterm"></a> |
| <p>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.</p> |
| </div> |
| <div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="idm139993936052848"></a>QEMU or KVM</h4></div></div></div> |
| |
| <a id="idm139993936052032" class="indexterm"></a> |
| <a id="idm139993936051168" class="indexterm"></a> |
| <p>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.</p> |
| <p>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.</p> |
| </div> |
| </div> |
| </div> |
| <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="rdp"></a>RDP</h2></div></div></div> |
| |
| <a id="idm139993936048592" class="indexterm"></a> |
| <p>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.</p> |
| <p>RDP support for Guacamole is provided by the <span class="package">libguac-client-rdp</span> |
| 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 <span class="package">libguac-client-rdp</span> package for you. You will need to |
| build and install a recent version of FreeRDP, and then build and install |
| <span class="package">libguac-client-rdp</span> from source.</p> |
| <div class="table"><a id="idm139993936043616"></a><p class="title"><strong>Table 3.2. RDP configuration parameters</strong></p><div class="table-contents"> |
| |
| <a id="idm139993936042496" class="indexterm"></a> |
| <table summary="RDP configuration parameters" border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>hostname</code></em></td><td> |
| <p><a id="idm139993936034032" class="indexterm"></a>The hostname or IP address of the RDP server Guacamole |
| should connect to.</p> |
| </td></tr><tr><td><em class="parameter"><code>port</code></em></td><td> |
| <p><a id="idm139993936030704" class="indexterm"></a>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.</p> |
| </td></tr><tr><td><em class="parameter"><code>username</code></em></td><td> |
| <p><a id="idm139993936027152" class="indexterm"></a>The username to use to authenticate, if any. This |
| parameter is optional.</p> |
| </td></tr><tr><td><em class="parameter"><code>password</code></em></td><td> |
| <p><a id="idm139993936023824" class="indexterm"></a>The password to use when attempting authentication, if |
| any. This parameter is optional.</p> |
| </td></tr><tr><td><em class="parameter"><code>domain</code></em></td><td> |
| <p><a id="idm139993936020496" class="indexterm"></a>The domain to use when attempting authentication, if |
| any. This parameter is optional.</p> |
| </td></tr><tr><td><em class="parameter"><code>color-depth</code></em></td><td> |
| <p><a id="idm139993936017168" class="indexterm"></a>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.</p> |
| </td></tr><tr><td><em class="parameter"><code>width</code></em></td><td> |
| <p><a id="idm139993936013552" class="indexterm"></a>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.</p> |
| </td></tr><tr><td><em class="parameter"><code>height</code></em></td><td> |
| <p>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.</p> |
| </td></tr><tr><td><em class="parameter"><code>disable-audio</code></em></td><td><a id="idm139993936008176" class="indexterm"></a><a id="idm139993936007440" class="indexterm"></a><a id="idm139993936006656" class="indexterm"></a>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".</td></tr><tr><td><em class="parameter"><code>enable-printing</code></em></td><td> |
| <p><a id="idm139993936003264" class="indexterm"></a><a id="idm139993936002400" class="indexterm"></a><a id="idm139993936001712" class="indexterm"></a>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".</p> |
| <p><span class="emphasis"><em>Printing support requires |
| <span class="application">GhostScript</span> to be |
| installed.</em></span> If <span class="application">guacd</span> cannot |
| find the <code class="filename">gs</code> executable when printing, the print |
| attempt will fail.</p> |
| </td></tr><tr><td><em class="parameter"><code>enable-drive</code></em></td><td> |
| <p><a id="idm139993935995984" class="indexterm"></a><a id="idm139993935995072" class="indexterm"></a><a id="idm139993935994336" class="indexterm"></a>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".</p> |
| <p>Files will be stored in the directory specified by the |
| "<em class="parameter"><code>drive-path</code></em>" parameter, which is required |
| if file transfer is enabled.</p> |
| </td></tr><tr><td><em class="parameter"><code>drive-path</code></em></td><td> |
| <p>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. |
| <span class="emphasis"><em>This parameter does not refer to a directory on the |
| RDP server.</em></span></p> |
| <p>If file transfer is not enabled, this parameter is ignored.</p> |
| </td></tr><tr><td><em class="parameter"><code>console</code></em></td><td> |
| <p><a id="idm139993935986560" class="indexterm"></a>If set to "true", you will be connected to the console |
| (admin) session of the RDP server.</p> |
| </td></tr><tr><td><em class="parameter"><code>console-audio</code></em></td><td> |
| <p><a id="idm139993935983216" class="indexterm"></a>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 <em class="parameter"><code>console</code></em> |
| parameter is also set to "true".</p> |
| </td></tr><tr><td><em class="parameter"><code>initial-program</code></em></td><td> |
| <p><a id="idm139993935979296" class="indexterm"></a>The full path to the program to run immediately upon |
| connecting. This parameter is optional.</p> |
| </td></tr><tr><td><em class="parameter"><code>server-layout</code></em></td><td> |
| <p><a id="idm139993935975968" class="indexterm"></a><a id="idm139993935975136" class="indexterm"></a>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. <span class="emphasis"><em>The Guacamole client is independent of |
| keyboard layout.</em></span> The RDP protocol, however, is |
| <span class="emphasis"><em>not</em></span> 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.</p> |
| <p>Possible values are:</p> |
| <div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="constant">en-us-qwerty</code></span></dt><dd> |
| <p>English (US) keyboard</p> |
| </dd><dt><span class="term"><code class="constant">de-de-qwertz</code></span></dt><dd> |
| <p>German keyboard (qwertz)</p> |
| </dd><dt><span class="term"><code class="constant">fr-fr-azerty</code></span></dt><dd> |
| <p>French keyboard (azerty)</p> |
| </dd><dt><span class="term"><code class="constant">failsafe</code></span></dt><dd> |
| <p>Unknown keyboard - this option sends only Unicode |
| events and should work for any keyboard, though not |
| necessarily all RDP servers or applications.</p> |
| <p>If your server's keyboard layout is not yet supported, |
| this option should work in the meantime.</p> |
| </dd></dl></div> |
| </td></tr><tr><td><em class="parameter"><code>security</code></em></td><td> |
| <p><a id="idm139993935960736" class="indexterm"></a><a id="idm139993935959392" class="indexterm"></a><a id="idm139993935958144" class="indexterm"></a>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.</p> |
| <p>Possible values are:</p> |
| <div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="constant">rdp</code></span></dt><dd> |
| <p>Standard RDP encryption. This mode should be supported |
| by all RDP servers.</p> |
| </dd><dt><span class="term"><code class="constant">nla</code></span></dt><dd> |
| <p>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.</p> |
| </dd><dt><span class="term"><code class="constant">tls</code></span></dt><dd> |
| <p>TLS encryption. TLS (Transport Layer Security) is the |
| successor to SSL.</p> |
| </dd><dt><span class="term"><code class="constant">any</code></span></dt><dd> |
| <p>Allow the server to choose the type of security. This |
| is the default.</p> |
| </dd></dl></div> |
| </td></tr><tr><td><em class="parameter"><code>ignore-cert</code></em></td><td> |
| <p><a id="idm139993935944800" class="indexterm"></a>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).</p> |
| </td></tr><tr><td><em class="parameter"><code>disable-auth</code></em></td><td> |
| <p><a id="idm139993935941216" class="indexterm"></a>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.</p> |
| <p>If you are using NLA, authentication must be enabled by |
| definition.</p> |
| </td></tr><tr><td><em class="parameter"><code>remote-app</code></em></td><td> |
| <p><a id="idm139993935936928" class="indexterm"></a>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.</p> |
| <p>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 <code class="filename">notepad.exe</code> and |
| have assigned it the name "notepad", you would set this parameter |
| to: "||notepad".</p> |
| </td></tr><tr><td><em class="parameter"><code>remote-app-dir</code></em></td><td> |
| <p>The working directory, if any, for the remote application. This |
| parameter has no effect if RemoteApp is not in use.</p> |
| </td></tr><tr><td><em class="parameter"><code>remote-app-args</code></em></td><td> |
| <p>The command-line arguments, if any, for the remote application. |
| This parameter has no effect if RemoteApp is not in use.</p> |
| </td></tr><tr><td><em class="parameter"><code>static-channels</code></em></td><td> |
| <p>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.</p> |
| <p>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.</p> |
| </td></tr></tbody></table> |
| </div></div><br class="table-break" /> |
| <div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm139993936035520"></a>Adding an RDP connection</h3></div></div></div> |
| |
| <a id="idm139993935926048" class="indexterm"></a> |
| <p>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 class="code"><authorize></code> section for that user within your |
| <code class="filename">user-mapping.xml</code>, and add a section like the following |
| within it:</p> |
| <pre class="programlisting"><connection name="<em class="replaceable"><code>Unique Name</code></em>"> |
| <protocol>rdp</protocol> |
| <param name="hostname"><em class="replaceable"><code>localhost</code></em></param> |
| <param name="port"><em class="replaceable"><code>3389</code></em></param> |
| </connection></pre> |
| <p>If added exactly as above, a new connection named "<em class="replaceable"><code>Unique |
| Name</code></em>" will be available to the user associated with the |
| <code class="code"><authorize></code> section containing it. The connection will use RDP |
| to connect to <em class="replaceable"><code>localhost</code></em> at port |
| <em class="replaceable"><code>3389</code></em>. Naturally, you will want to change some or all |
| of these values.</p> |
| <p>If you want to login automatically rather than receive a login prompt upon |
| connecting, you can specify a username and password with additional |
| <code class="code"><param></code> tags. Other options are available for controlling the |
| color depth, size of the screen, etc.</p> |
| <p>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.</p> |
| </div> |
| </div> |
| <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssh"></a>SSH</h2></div></div></div> |
| |
| <a id="idm139993935915680" class="indexterm"></a> |
| <p>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.</p> |
| <p>SSH support for Guacamole is provided by the <span class="package">libguac-client-ssh</span> |
| library, which depends on libssh2 and libssl.</p> |
| <div class="table"><a id="idm139993935913040"></a><p class="title"><strong>Table 3.3. SSH configuration parameters</strong></p><div class="table-contents"> |
| |
| <a id="idm139993935911808" class="indexterm"></a> |
| <table summary="SSH configuration parameters" border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>hostname</code></em></td><td> |
| <p><a id="idm139993935903712" class="indexterm"></a>The hostname or IP address of the SSH server Guacamole |
| should connect to.</p> |
| </td></tr><tr><td><em class="parameter"><code>port</code></em></td><td> |
| <p><a id="idm139993935900368" class="indexterm"></a>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.</p> |
| </td></tr><tr><td><em class="parameter"><code>username</code></em></td><td> |
| <p><a id="idm139993935896816" class="indexterm"></a>The username to use to authenticate, if any. This |
| parameter is optional. If not specified, you will be prompted for |
| the username upon connecting.</p> |
| </td></tr><tr><td><em class="parameter"><code>password</code></em></td><td> |
| <p><a id="idm139993935893392" class="indexterm"></a>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.</p> |
| </td></tr><tr><td><em class="parameter"><code>font-name</code></em></td><td> |
| <p><a id="idm139993935889952" class="indexterm"></a>The name of the font to use. This parameter is optional. |
| If not specified, the default of "monospace" will be used |
| instead.</p> |
| </td></tr><tr><td><em class="parameter"><code>font-size</code></em></td><td> |
| <p>The size of the font to use, in points. This parameter is |
| optional. If not specified, the default of 12 will be used |
| instead.</p> |
| </td></tr><tr><td><em class="parameter"><code>enable-sftp</code></em></td><td> |
| <p><a id="idm139993935884368" class="indexterm"></a><a id="idm139993935883072" class="indexterm"></a>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 |
| <span class="command"><strong>guacctl</strong></span> utility which controls file downloads |
| and uploads when run on the SSH server by the user over the SSH |
| connection.</p> |
| </td></tr><tr><td><em class="parameter"><code>private-key</code></em></td><td> |
| <p><a id="idm139993935879520" class="indexterm"></a>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 |
| <span class="command"><strong>ssh-keygen</strong></span> utility.</p> |
| </td></tr><tr><td><em class="parameter"><code>passphrase</code></em></td><td> |
| <p><a id="idm139993935875472" class="indexterm"></a>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.</p> |
| </td></tr></tbody></table> |
| </div></div><br class="table-break" /> |
| <div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm139993935872944"></a>Adding an SSH connection</h3></div></div></div> |
| |
| <a id="idm139993935872128" class="indexterm"></a> |
| <p>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 class="code"><authorize></code> section for that user within your |
| <code class="filename">user-mapping.xml</code>, and add a section like the following |
| within it:</p> |
| <pre class="programlisting"><connection name="<em class="replaceable"><code>Unique Name</code></em>"> |
| <protocol>ssh</protocol> |
| <param name="hostname"><em class="replaceable"><code>localhost</code></em></param> |
| <param name="port"><em class="replaceable"><code>22</code></em></param> |
| </connection></pre> |
| <p>If added exactly as above, a new connection named "<em class="replaceable"><code>Unique |
| Name</code></em>" will be available to the user associated with the |
| <code class="code"><authorize></code> section containing it. The connection will use SSH |
| to connect to <em class="replaceable"><code>localhost</code></em> at port |
| <em class="replaceable"><code>22</code></em>. Naturally, you will want to change some or all of |
| these values.</p> |
| <p>If you want to login automatically rather than receive a login prompt upon |
| connecting, you can specify a username and password with additional |
| <code class="code"><param></code> tags. Other options are available for controlling the |
| font.</p> |
| <p>Other authentication methods will provide documentation describing how to |
| configure new connections.</p> |
| </div> |
| </div> |
| <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="telnet"></a>Telnet</h2></div></div></div> |
| |
| <a id="idm139993935861920" class="indexterm"></a> |
| <p>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.</p> |
| <p>Telnet support for Guacamole is provided by the |
| <span class="package">libguac-client-telnet</span> library, which depends on libtelnet.</p> |
| <div class="table"><a id="idm139993935859520"></a><p class="title"><strong>Table 3.4. Telnet configuration parameters</strong></p><div class="table-contents"> |
| |
| <a id="idm139993935858464" class="indexterm"></a> |
| <table summary="Telnet configuration parameters" border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>hostname</code></em></td><td> |
| <p><a id="idm139993935850336" class="indexterm"></a>The hostname or IP address of the telnet server |
| Guacamole should connect to.</p> |
| </td></tr><tr><td><em class="parameter"><code>port</code></em></td><td> |
| <p><a id="idm139993935846880" class="indexterm"></a>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.</p> |
| </td></tr><tr><td><em class="parameter"><code>username</code></em></td><td> |
| <p><a id="idm139993935843456" class="indexterm"></a>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 <code class="methodname">NEW-ENVIRON</code> option, and the |
| telnet login process must pay attention to the <code class="envar">USER</code> |
| environment variable. Most telnet servers satisfy this |
| criteria.</p> |
| </td></tr><tr><td><em class="parameter"><code>username-regex</code></em></td><td> |
| <p>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 <span class="command"><strong>egrep</strong></span>).</p> |
| </td></tr><tr><td><em class="parameter"><code>password</code></em></td><td> |
| <p><a id="idm139993935835952" class="indexterm"></a>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.</p> |
| </td></tr><tr><td><em class="parameter"><code>password-regex</code></em></td><td> |
| <p>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 <span class="command"><strong>egrep</strong></span>).</p> |
| </td></tr><tr><td><em class="parameter"><code>font-name</code></em></td><td> |
| <p><a id="idm139993935830032" class="indexterm"></a>The name of the font to use. This parameter is optional. |
| If not specified, the default of "monospace" will be used |
| instead.</p> |
| </td></tr><tr><td><em class="parameter"><code>font-size</code></em></td><td> |
| <p>The size of the font to use, in points. This parameter is |
| optional. If not specified, the default of 12 will be used |
| instead.</p> |
| </td></tr></tbody></table> |
| </div></div><br class="table-break" /> |
| <div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm139993935825472"></a>Adding a telnet connection</h3></div></div></div> |
| |
| <a id="idm139993935824656" class="indexterm"></a> |
| <p>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 class="code"><authorize></code> section for that user within your |
| <code class="filename">user-mapping.xml</code>, and add a section like the following |
| within it:</p> |
| <pre class="programlisting"><connection name="<em class="replaceable"><code>Unique Name</code></em>"> |
| <protocol>telnet</protocol> |
| <param name="hostname"><em class="replaceable"><code>localhost</code></em></param> |
| <param name="port"><em class="replaceable"><code>23</code></em></param> |
| </connection></pre> |
| <p>If added exactly as above, a new connection named "<em class="replaceable"><code>Unique |
| Name</code></em>" will be available to the user associated with the |
| <code class="code"><authorize></code> section containing it. The connection will use |
| telnet to connect to <em class="replaceable"><code>localhost</code></em> at port |
| <em class="replaceable"><code>23</code></em>. Naturally, you will want to change some or all of |
| these values.</p> |
| <p>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 <span class="emphasis"><em>client</em></span> 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.</p> |
| </div> |
| <div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm139993935818944"></a>Authentication</h3></div></div></div> |
| |
| <p>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.</p> |
| <p>The de-facto method for passing the username automatically via telnet is to submit |
| it via the <code class="envar">USER</code> environment variable, sent using the |
| <code class="methodname">NEW-ENVIRON</code> option. This is the mechanism used by most |
| telnet clients, typically via the <code class="option">-l</code> command-line option.</p> |
| <p>Passwords cannot typically be sent automatically - at least not as reliably as the |
| username. There is no <code class="envar">PASSWORD</code> 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 <span class="command"><strong>expect</strong></span>. Guacamole provides |
| similar functionality by searching for the password prompt with a regular |
| expression.</p> |
| <p>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.</p> |
| <p>If the password prompt is not being detected properly, you can try using your own |
| regular expression by specifying it within the <em class="parameter"><code>password-regex</code></em> |
| parameter. The regular expression must be written in the POSIX ERE dialect (the |
| dialect typically used by <span class="command"><strong>egrep</strong></span>).</p> |
| </div> |
| </div> |
| <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139993935807904"></a>Configuring guacd</h2></div></div></div> |
| |
| <p><a id="idm139993935806800" class="indexterm"></a>guacd is configured with a configuration file called |
| <code class="filename">guacd.conf</code>, by default located in |
| <code class="filename">/etc/guacamole</code>. This file follows a simple, INI-like |
| format:</p> |
| <div class="informalexample"> |
| <pre class="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</pre> |
| </div> |
| <p>Configuration options are given as parameter/value pairs, where the name of the |
| parameter is specified on the left side of an "<code class="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.</p> |
| <p>For the sake of documentation and readability, comments can be added anywhere within |
| guacd.conf using "<code class="code">#</code>" symbols. All text following a "<code class="code">#</code>" until |
| end-of-line will be ignored.</p> |
| <p>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:</p> |
| <div class="informalexample"> |
| <pre class="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"</pre> |
| </div> |
| <p>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:</p> |
| <div class="informalexample"> |
| <pre class="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"</pre> |
| </div> |
| <p>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:</p> |
| <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> |
| <p>If the value contains no special characters, just include it as-is.</p> |
| </li><li class="listitem"> |
| <p>If the value contains any special characters (whitespace, newlines, |
| <code class="code">#</code>, <code class="code">\</code>, or <code class="code">"</code>), enclose the entire value |
| within double quotes.</p> |
| </li><li class="listitem"> |
| <p>If the value is enclosed within double quotes, escape newlines, |
| <code class="code">\</code>, and <code class="code">"</code> with a backslash.</p> |
| </li></ol></div> |
| <div class="table"><a id="idm139993935790400"></a><p class="title"><strong>Table 3.5. guacd.conf parameters</strong></p><div class="table-contents"> |
| |
| <a id="idm139993935789264" class="indexterm"></a> |
| <table summary="guacd.conf parameters" border="1"><colgroup><col class="c1" /><col class="c2" /><col class="c3" /></colgroup><thead><tr><th>Section</th><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>daemon</code></em></td><td><em class="parameter"><code>pid_file</code></em></td><td> |
| <p><a id="idm139993935779264" class="indexterm"></a>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.</p> |
| </td></tr><tr><td><em class="parameter"><code>server</code></em></td><td><em class="parameter"><code>bind_host</code></em></td><td> |
| <p><a id="idm139993935775216" class="indexterm"></a>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.</p> |
| </td></tr><tr><td><em class="parameter"><code>server</code></em></td><td><em class="parameter"><code>bind_port</code></em></td><td> |
| <p><a id="idm139993935771456" class="indexterm"></a>The port that guacd should bind to when listening for |
| connections. If unspecified, port 4822 will be used.</p> |
| </td></tr><tr><td><em class="parameter"><code>ssl</code></em></td><td><em class="parameter"><code>server_certificate</code></em></td><td> |
| <p><a id="idm139993935767680" class="indexterm"></a>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 |
| <code class="filename">guacamole.properties</code> to use SSL as |
| well.</p> |
| </td></tr><tr><td><em class="parameter"><code>ssl</code></em></td><td><em class="parameter"><code>server_key</code></em></td><td> |
| <p><a id="idm139993935763360" class="indexterm"></a>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 |
| <code class="filename">guacamole.properties</code> to use SSL as |
| well.</p> |
| </td></tr></tbody></table> |
| </div></div><br class="table-break" /> |
| <p>You can also affect the configuration of guacd with command-line options. If given, |
| these options take precendence over the system-wide configuration file:</p> |
| <div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-b <em class="replaceable"><code>HOST</code></em></code></span></dt><dd> |
| <p>Changes the host or address that guacd listens on.</p> |
| <p>This corresponds to the <em class="parameter"><code>bind_host</code></em> parameter within |
| the <em class="parameter"><code>server</code></em> section of |
| <code class="filename">guacd.conf</code>.</p> |
| </dd><dt><span class="term"><code class="option">-l <em class="replaceable"><code>PORT</code></em></code></span></dt><dd> |
| <p>Changes the port that guacd listens on (the default is port 4822).</p> |
| <p>This corresponds to the <em class="parameter"><code>bind_port</code></em> parameter within |
| the <em class="parameter"><code>server</code></em> section of |
| <code class="filename">guacd.conf</code>.</p> |
| </dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>PIDFILE</code></em></code></span></dt><dd> |
| <p>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.</p> |
| <p>This corresponds to the <em class="parameter"><code>pid_file</code></em> parameter within |
| the <em class="parameter"><code>daemon</code></em> section of |
| <code class="filename">guacd.conf</code>.</p> |
| </dd><dt><span class="term"><code class="option">-f</code></span></dt><dd> |
| <p>Causes guacd to run in the foreground, rather than automatically forking |
| into the background.</p> |
| </dd></dl></div> |
| <p>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:</p> |
| <div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-C <em class="replaceable"><code>CERTIFICATE</code></em></code></span></dt><dd> |
| <p>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 |
| <code class="filename">guacamole.properties</code> to use SSL as well.</p> |
| <p>This corresponds to the <em class="parameter"><code>server_certificate</code></em> |
| parameter within the <em class="parameter"><code>ssl</code></em> section of |
| <code class="filename">guacd.conf</code>.</p> |
| </dd><dt><span class="term"><code class="option">-K <em class="replaceable"><code>KEY</code></em></code></span></dt><dd> |
| <p>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 |
| <code class="filename">guacamole.properties</code> to use SSL as well.</p> |
| <p>This corresponds to the <em class="parameter"><code>server_key</code></em> parameter within |
| the <em class="parameter"><code>ssl</code></em> section of |
| <code class="filename">guacd.conf</code>.</p> |
| </dd></dl></div> |
| </div> |
| |
| <div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idm139993936176208" class="footnote"> |
| <p><a href="#idm139993936176208" class="para"><sup class="para">[1] </sup></a><code class="classname">net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider</code></p> |
| </div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="installing-guacamole.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="users-guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="mysql-auth.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. Installing Guacamole </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 4. MySQL authentication</td></tr></table></div> |
| |
| </div></div> |
| |
| |
| <!-- Google Analytics --> |
| <script type="text/javascript"> |
| (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ |
| (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), |
| m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) |
| })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); |
| |
| ga('create', 'UA-75289145-1', 'auto'); |
| ga('send', 'pageview'); |
| |
| </script> |
| <!-- End Google Analytics --> |
| </body></html> |
