guacamole-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mjum...@apache.org
Subject [08/58] [abbrv] [partial] incubator-guacamole-website git commit: Add doc/ and pub/ directories from old site. Remove Piwik tracking.
Date Sun, 24 Apr 2016 01:02:22 GMT
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/f9d5dedf/doc/0.8.3/gug/configuring-guacamole.html
----------------------------------------------------------------------
diff --git a/doc/0.8.3/gug/configuring-guacamole.html b/doc/0.8.3/gug/configuring-guacamole.html
new file mode 100644
index 0000000..4dbe601
--- /dev/null
+++ b/doc/0.8.3/gug/configuring-guacamole.html
@@ -0,0 +1,645 @@
+<?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.76.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" title="Chapter 3. Configuring Guacamole" 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><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><
 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#idp543232">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#idp662656">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#idp703584">Adding an SSH
  connection</a></span></dt></dl></dd></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" title="GUACAMOLE_HOME"><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="idp400992" 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" title="guacamole.properties"><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="idp412800" class="indexterm"></a>
+        <a id="idp413696" 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 provides five
+            basic properties: </p>
+        <div class="variablelist"><dl><dt><span class="term"><a id="idp422112" 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="idp425280" 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="idp428336" 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="idp432032" 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. </p>
+                </dd><dt><span class="term"><a id="idp435312" 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. </p>
+                </dd><dt><span class="term"><a id="idp437344" 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></dl></div>
+        <div class="example"><a id="idp442176"></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
+
+# 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</pre>
+        </div></div><br class="example-break" />
+    </div>
+    <div class="section" title="Using the default authentication"><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="idp446016" 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><sup>[<a id="idp448336" href="#ftn.idp448336" class="footnote">1</a>]</sup>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" title="user-mapping.xml"><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="idp451936" 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">&lt;user-mapping&gt;
+	
+    &lt;!-- Per-user authentication and config information --&gt;
+    &lt;authorize username="USERNAME" password="PASSWORD"&gt;
+        &lt;protocol&gt;vnc&lt;/protocol&gt;
+        &lt;param name="hostname"&gt;localhost&lt;/param&gt;
+        &lt;param name="port"&gt;5900&lt;/param&gt;
+        &lt;param name="password"&gt;VNCPASS&lt;/param&gt;
+    &lt;/authorize&gt;
+
+    &lt;!-- Another user, but using md5 to hash the password
+         (example below uses the md5 hash of "PASSWORD") --&gt;
+    &lt;authorize 
+            username="USERNAME2"
+            password="319f4d26e3c536b5dd871bb2c52e3178"
+            encoding="md5"&gt;
+
+        &lt;!-- First authorized connection --&gt;
+        &lt;connection name="localhost"&gt;
+            &lt;protocol&gt;vnc&lt;/protocol&gt;
+            &lt;param name="hostname"&gt;localhost&lt;/param&gt;
+            &lt;param name="port"&gt;5901&lt;/param&gt;
+            &lt;param name="password"&gt;VNCPASS&lt;/param&gt;
+        &lt;/connection&gt;
+
+        &lt;!-- Second authorized connection --&gt;
+        &lt;connection name="otherhost"&gt;
+            &lt;protocol&gt;vnc&lt;/protocol&gt;
+            &lt;param name="hostname"&gt;otherhost&lt;/param&gt;
+            &lt;param name="port"&gt;5900&lt;/param&gt;
+            &lt;param name="password"&gt;VNCPASS&lt;/param&gt;
+        &lt;/connection&gt;
+
+    &lt;/authorize&gt;
+
+&lt;/user-mapping&gt;</pre>
+            <p>Each user is specified with a corresponding
+                    <code class="code">&lt;authorize&gt;</code> tag. This tag contains all
+                authorized connections for that user, each denoted with a
+                    <code class="code">&lt;connection&gt;</code> tag. Each
+                    <code class="code">&lt;connection&gt;</code> tag contains a corresponding
+                protocol and set of protocol-specific parameters, specified with
+                the <code class="code">&lt;protocol&gt;</code> and <code class="code">&lt;param&gt;</code> tags
+                respectively.</p>
+            <div class="section" title="Adding users"><div class="titlepage"><div><div><h4 class="title"><a id="user-setup"></a>Adding users</h4></div></div></div>
+                
+                <a id="idp461232" class="indexterm"></a>
+                <p>When using
+                        <code class="classname">BasicFileAuthenticationProvider</code>,
+                    username/password pairs are specified with
+                        <code class="code">&lt;authorize&gt;</code> tags, which each have a
+                        <code class="code">username</code> and <code class="code">password</code>
+                    attribute. Each <code class="code">&lt;authorize&gt;</code> tag authorizes a
+                    specific username/password pair to access all connections
+                    within the tag:</p>
+                <pre class="programlisting">&lt;authorize username="<em class="replaceable"><code>USER</code></em>" password="<em class="replaceable"><code>PASS</code></em>"&gt;
+    ...
+&lt;/authorize&gt;</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">&lt;authorize username="<em class="replaceable"><code>USER</code></em>"
+           password="<em class="replaceable"><code>319f4d26e3c536b5dd871bb2c52e3178</code></em>"
+           encoding="md5"&gt;
+    ...
+&lt;/authorize&gt;</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" title="Adding connections to a user"><div class="titlepage"><div><div><h4 class="title"><a id="connection-setup"></a>Adding connections to a user</h4></div></div></div>
+                
+                <a id="idp470688" class="indexterm"></a>
+                <p>To specify a connection within an
+                        <code class="code">&lt;authorize&gt;</code> tag, you can either list a
+                    single protocol and set of parameters (specified with a
+                        <code class="code">&lt;protocol&gt;</code> tag and any number of
+                        <code class="code">&lt;param&gt;</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">&lt;connection&gt;</code> tags, each of which can be
+                    named and contains a <code class="code">&lt;protocol&gt;</code> tag and any
+                    number of <code class="code">&lt;param&gt;</code> tags.</p>
+            </div>
+        </div>
+    </div>
+    <div class="section" title="VNC"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="vnc"></a>VNC</h2></div></div></div>
+        
+        <a id="idp476912" 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="idp480880" 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="idp489152" 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="idp492128" 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="idp496352" 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="idp500064" 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="idp506048" 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>encodings</code></em></td><td>
+                            <p><a id="idp509648" 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="idp511056" class="indexterm"></a><a id="idp514032" class="indexterm"></a><a id="idp515360" 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="idp519520" class="indexterm"></a><a id="idp520816" 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="idp524384" class="indexterm"></a><a id="idp524192" 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></tbody></table>
+        </div></div><br class="table-break" />
+        <div class="section" title="Adding a VNC connection"><div class="titlepage"><div><div><h3 class="title"><a id="adding-vnc"></a>Adding a VNC connection</h3></div></div></div>
+            
+            <a id="idp534336" 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">&lt;authorize&gt;</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">&lt;connection name="<em class="replaceable"><code>Unique Name</code></em>"&gt;
+    &lt;protocol&gt;vnc&lt;/protocol&gt;
+    &lt;param name="hostname"&gt;<em class="replaceable"><code>localhost</code></em>&lt;/param&gt;
+    &lt;param name="port"&gt;<em class="replaceable"><code>5901</code></em>&lt;/param&gt;
+&lt;/connection&gt;</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">&lt;authorize&gt;</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">&lt;param&gt;</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 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.</p>
+        </div>
+        <div class="section" title="Which VNC server?"><div class="titlepage"><div><div><h3 class="title"><a id="idp543232"></a>Which VNC server?</h3></div></div></div>
+            
+            <a id="idp544048" 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" title="RealVNC or TigerVNC"><div class="titlepage"><div><div><h4 class="title"><a id="idp545760"></a>RealVNC or TigerVNC</h4></div></div></div>
+                
+                <a id="idp546592" class="indexterm"></a>
+                <a id="idp547664" 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" title="TightVNC"><div class="titlepage"><div><div><h4 class="title"><a id="idp549584"></a>TightVNC</h4></div></div></div>
+                
+                <a id="idp550224" 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" title="x11vnc"><div class="titlepage"><div><div><h4 class="title"><a id="idp552416"></a>x11vnc</h4></div></div></div>
+                
+                <a id="idp553184" 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" title="vino"><div class="titlepage"><div><div><h4 class="title"><a id="idp555008"></a>vino</h4></div></div></div>
+                
+                <a id="idp555824" 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" title="QEMU or KVM"><div class="titlepage"><div><div><h4 class="title"><a id="idp556080"></a>QEMU or KVM</h4></div></div></div>
+                
+                <a id="idp558960" class="indexterm"></a>
+                <a id="idp559728" 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" title="RDP"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="rdp"></a>RDP</h2></div></div></div>
+        
+        <a id="idp563712" 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="idp567376"></a><p class="title"><strong>Table 3.2. RDP configuration parameters</strong></p><div class="table-contents">
+            
+            <a id="idp568432" 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="idp576608" 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="idp579904" 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="idp583200" 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="idp586560" 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="idp589872" 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="idp593184" 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="idp596784" 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="idp601968" class="indexterm"></a><a id="idp602816" class="indexterm"></a><a id="idp603600" 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="idp606640" class="indexterm"></a><a id="idp607184" class="indexterm"></a><a id="idp608000" 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>console</code></em></td><td>
+                            <p><a id="idp614224" 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="idp617360" 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="idp621760" 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="idp625040" class="indexterm"></a><a id="idp624848" 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><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="idp640240" class="indexterm"></a><a id="idp641632" class="indexterm"></a><a id="idp642832" 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><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="idp656224" 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="idp659824" 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></tbody></table>
+        </div></div><br class="table-break" />
+        <div class="section" title="Adding an RDP connection"><div class="titlepage"><div><div><h3 class="title"><a id="idp662656"></a>Adding an RDP connection</h3></div></div></div>
+            
+            <a id="idp663472" 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">&lt;authorize&gt;</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">&lt;connection name="<em class="replaceable"><code>Unique Name</code></em>"&gt;
+    &lt;protocol&gt;rdp&lt;/protocol&gt;
+    &lt;param name="hostname"&gt;<em class="replaceable"><code>localhost</code></em>&lt;/param&gt;
+    &lt;param name="port"&gt;<em class="replaceable"><code>3389</code></em>&lt;/param&gt;
+&lt;/connection&gt;</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">&lt;authorize&gt;</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">&lt;param&gt;</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 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.</p>
+        </div>
+    </div>
+    <div class="section" title="SSH"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssh"></a>SSH</h2></div></div></div>
+        
+        <a id="idp674016" 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 libssh.</p>
+        <div class="table"><a id="idp676448"></a><p class="title"><strong>Table 3.3. SSH configuration parameters</strong></p><div class="table-contents">
+            
+            <a id="idp677744" 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="idp685808" 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="idp689168" 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="idp692544" 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="idp695584" 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="idp699408" 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" title="Adding an SSH connection"><div class="titlepage"><div><div><h3 class="title"><a id="idp703584"></a>Adding an SSH connection</h3></div></div></div>
+            
+            <a id="idp704400" 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">&lt;authorize&gt;</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">&lt;connection name="<em class="replaceable"><code>Unique Name</code></em>"&gt;
+    &lt;protocol&gt;ssh&lt;/protocol&gt;
+    &lt;param name="hostname"&gt;<em class="replaceable"><code>localhost</code></em>&lt;/param&gt;
+    &lt;param name="port"&gt;<em class="replaceable"><code>22</code></em>&lt;/param&gt;
+&lt;/connection&gt;</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">&lt;authorize&gt;</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">&lt;param&gt;</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="footnotes"><br /><hr width="100" align="left" /><div class="footnote">
+                <p><sup>[<a id="ftn.idp448336" href="#idp448336" class="para">1</a>] </sup><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>

http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/f9d5dedf/doc/0.8.3/gug/custom-authentication.html
----------------------------------------------------------------------
diff --git a/doc/0.8.3/gug/custom-authentication.html b/doc/0.8.3/gug/custom-authentication.html
new file mode 100644
index 0000000..c4f2731
--- /dev/null
+++ b/doc/0.8.3/gug/custom-authentication.html
@@ -0,0 +1,396 @@
+<?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 15. Custom authentication</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="developers-guide.html" title="Part II. Developer's Guide" /><link rel="prev" href="custom-protocols.html" title="Chapter 14. Adding new protocols" /><link rel="next" href="writing-you-own-guacamole-app.html" title="Chapter 16. Writing your own Guacamole application" />
+            <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 15. Custom authentication</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="custom-protocols.html">Prev</a> </td><th width="60%" align="center">Part II. Developer's Guide</th><td width="20%" align="right"> <a accesskey="n" href="writing-you-own-guacamole-app.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" title="Chapter 15. Custom authentication" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="custom-authentication"></a>Chapter 15. Custom authentication</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="custom-authentication.html#auth-model">Guacamole's authentication model</a></span></dt><dt><span class="section"><a href="custom-authentication.html#client-plugin-skeleton">A Guacamole plugin skeleton</a></span></dt><dt><s
 pan class="section"><a href="custom-authentication.html#user-auth-example">Actually authenticating the user</a></span></dt><dt><span class="section"><a href="custom-authentication.html#parse-conf-example">Parsing the configuration</a></span></dt></dl></div>
+    
+    <a id="idp1904736" class="indexterm"></a>
+    <p>Guacamole's authentication layer is designed to be extendable such that users can
+        integrate Guacamole into existing authentication systems without having to resort to writing
+        their own web application around the Guacamole API.</p>
+    <p>The web application comes with a default authentication mechanism which uses an XML file
+        to associate users with connections. Plugins for Guacamole that provide LDAP-based
+        authentication or database-based authentication have also been developed.</p>
+    <p>To demonstrate the principles involved, we will implement a very simple authentication
+        plugin which associates a single user/password pair with a single connection, with all this
+        information saved in properties inside the <code class="filename">guacamole.properties</code>
+        file.</p>
+    <p>In general, all other authentication plugins for Guacamole will use the principles
+        demonstrated here. However, as of Guacamole 0.8.0, the authentication model has been
+        significantly enhanced, and supports more than simply translating a username/password pair
+        into a set of authorized configurations. This tutorial demonstrates the simplest way to
+        create an authentication plugin for Guacamole - an authentication plugin that does not
+        support management of users and connections via the web interface.</p>
+    <div class="section" title="Guacamole's authentication model"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="auth-model"></a>Guacamole's authentication model</h2></div></div></div>
+        
+        <p>When you view any page in Guacamole, whether that be the login screen or the client
+            interface, the page makes an authentication attempt with the web application, sending
+            all available credentials. After entering your username and password, the exact same
+            process occurs, except the web application receives the username and password as
+            well.</p>
+        <p>The web application handles this authentication attempt by collecting all credentials
+            available and passing them to a designated class called the "authentication provider".
+            This class is designated via a property in the <code class="filename">guacamole.properties</code>
+            file. Given the set of credentials, the specified authentication provider returns a
+            context object that provides restricted access to other users and connections, if
+            any.</p>
+    </div>
+    <div class="section" title="A Guacamole plugin skeleton"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="client-plugin-skeleton"></a>A Guacamole plugin skeleton</h2></div></div></div>
+        
+        <p>For simplicity's sake, and because this is how things are done upstream in the
+            Guacamole project, we will use Maven to build our plugin.</p>
+        <p>The bare minimum required for a Guacamole authentication plugin is a
+                <code class="filename">pom.xml</code> file listing guacamole-ext as a dependency, and a
+            single .java file implementing our stub of an authentication provider.</p>
+        <p>In our stub, we won't actually do any authentication yet; we'll just universally
+            reject all authentication attempts by returning <code class="varname">null</code> for any
+            credentials given. You can verify that this is what happens by checking the server
+            logs.</p>
+        <div class="example"><a id="idp1917040"></a><p class="title"><strong>Example 15.1. Barebones <code class="filename">pom.xml</code> required for a simple authentication
+                plugin.</strong></p><div class="example-contents">
+            
+            <pre class="programlisting">&lt;project xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+                        http://maven.apache.org/maven-v4_0_0.xsd"&gt;
+
+    &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
+    &lt;groupId&gt;org.glyptodon.guacamole&lt;/groupId&gt;
+    &lt;artifactId&gt;guacamole-auth-tutorial&lt;/artifactId&gt;
+    &lt;packaging&gt;jar&lt;/packaging&gt;
+    &lt;version&gt;0.8.0&lt;/version&gt;
+    &lt;name&gt;guacamole-auth-tutorial&lt;/name&gt;
+    &lt;url&gt;http://guac-dev.org/&lt;/url&gt;
+
+    &lt;properties&gt;
+        &lt;project.build.sourceEncoding&gt;UTF-8&lt;/project.build.sourceEncoding&gt;
+    &lt;/properties&gt;
+
+    &lt;build&gt;
+        &lt;plugins&gt;
+
+            &lt;!-- Written for 1.6 --&gt;
+            &lt;plugin&gt;
+                &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
+                &lt;artifactId&gt;maven-compiler-plugin&lt;/artifactId&gt;
+                &lt;configuration&gt;
+                    &lt;source&gt;1.6&lt;/source&gt;
+                    &lt;target&gt;1.6&lt;/target&gt;
+                &lt;/configuration&gt;
+            &lt;/plugin&gt;
+
+        &lt;/plugins&gt;
+    &lt;/build&gt;
+
+    &lt;dependencies&gt;
+
+        &lt;!-- Guacamole Java API --&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;org.glyptodon.guacamole&lt;/groupId&gt;
+            &lt;artifactId&gt;guacamole-common&lt;/artifactId&gt;
+            &lt;version&gt;0.8.0&lt;/version&gt;
+        &lt;/dependency&gt;
+
+        &lt;!-- Guacamole Extension API --&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;org.glyptodon.guacamole&lt;/groupId&gt;
+            &lt;artifactId&gt;guacamole-ext&lt;/artifactId&gt;
+            &lt;version&gt;0.8.0&lt;/version&gt;
+        &lt;/dependency&gt;
+
+    &lt;/dependencies&gt;
+
+    &lt;repositories&gt;
+        
+        &lt;!-- Central Guacamole repository --&gt;
+        &lt;repository&gt;
+            &lt;id&gt;guac-dev&lt;/id&gt;
+            &lt;url&gt;http://guac-dev.org/repo&lt;/url&gt;
+        &lt;/repository&gt;
+        
+    &lt;/repositories&gt;
+
+&lt;/project&gt;</pre>
+        </div></div><br class="example-break" />
+        <p>We won't need to update this <code class="filename">pom.xml</code> throughout the rest of the
+            tutorial. Even after adding new files, Maven will just find them and compile as
+            necessary.</p>
+        <p>Naturally, we need the actual authentication plugin skeleton code. While you can put
+            this in whatever file and package you want, for the sake of this tutorial, we will
+            assume you are using
+                <code class="classname">org.glyptodon.guacamole.auth.TutorialAuthenticationProvider</code>.</p>
+        <div class="example"><a id="idp1922640"></a><p class="title"><strong>Example 15.2. A skeleton <code class="classname">TutorialAuthenticationProvider</code></strong></p><div class="example-contents">
+            
+            <pre class="programlisting">package org.glyptodon.guacamole.auth;
+
+import java.util.Map;
+import org.glyptodon.guacamole.GuacamoleException;
+import org.glyptodon.guacamole.net.auth.simple.SimpleAuthenticationProvider;
+import org.glyptodon.guacamole.net.auth.Credentials;
+import org.glyptodon.guacamole.protocol.GuacamoleConfiguration;
+
+public class TutorialAuthenticationProvider extends SimpleAuthenticationProvider {
+       
+    @Override
+    public Map&lt;String, GuacamoleConfiguration&gt;
+        getAuthorizedConfigurations(Credentials credentials)
+        throws GuacamoleException {
+
+        // Do nothing ... yet
+        return null;        
+
+    }
+
+}</pre>
+        </div></div><br class="example-break" />
+        <p>To conform with Maven, this skeleton file must be placed within
+                <code class="filename">src/main/java/net/sourceforge/guacamole/auth</code> as
+                <code class="filename">TutorialAuthenticationProvider.java</code>.</p>
+        <p>Notice how simple the authentication provider is. The
+                <code class="classname">AuthenticationProvider</code> interface requires nothing more than a
+            single <code class="methodname">getAuthorizedConfigurations()</code> implementation, which must
+            return a <code class="classname">Map</code> of <code class="classname">GuacamoleConfiguration</code>
+            each associated with some arbitrary unique ID. This unique ID will be presented to the
+            user in the connection list after they log in.</p>
+        <p>For now, we just return <code class="varname">null</code>, which will cause Guacamole to report
+            an invalid login for every attempt. Note that there is a difference in semantics between
+            returning an empty map and returning <code class="varname">null</code>, as the former indicates
+            the credentials are authorized but simply have no associated configurations, while the
+            latter indicates the credentials are not authorized at all.</p>
+    </div>
+    <div class="section" title="Actually authenticating the user"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="user-auth-example"></a>Actually authenticating the user</h2></div></div></div>
+        
+        <p>Once we receive credentials, we need to validate those credentials against the
+            associated properties in <code class="filename">guacamole.properties</code> (our source of
+            authentication information for the sake of this tutorial).</p>
+        <p>We will define four properties:</p><div class="variablelist"><dl><dt><span class="term"><span class="property">tutorial-user</span></span></dt><dd>
+                        <p>The name of the only user we accept.</p>
+                    </dd><dt><span class="term"><span class="property">tutorial-password</span></span></dt><dd>
+                        <p>The password we require for the user specified to be
+                            authenticated.</p>
+                    </dd><dt><span class="term"><span class="property">tutorial-protocol</span></span></dt><dd>
+                        <p>The protocol of the configuration this user is authorized to use,
+                            which will be sent to guacd when the user logs in and selects their
+                            connection.</p>
+                    </dd><dt><span class="term"><span class="property">tutorial-parameters</span></span></dt><dd>
+                        <p>A comma-delimited list of
+                                    <code class="code"><em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em></code>
+                            pairs. For the sake of simplicity, we'll assume there will never be any
+                            commas in the values.</p>
+                    </dd></dl></div>
+        <p>If the username and password match what is stored in the file, we read the
+            configuration information, store it in a <code class="classname">GuacamoleConfiguration</code>,
+            and return the configuration within a set, telling Guacamole that this user is
+            authorized but only to access the configurations returned.</p>
+        <p>Upstream, we always place the properties of authentication providers in their own
+            class, and so we will also do that here in this tutorial, as it keeps things
+            organized.</p>
+        <div class="example"><a id="idp1944848"></a><p class="title"><strong>Example 15.3. <code class="filename">TutorialProperties.java</code>, a class containing property
+                definitions</strong></p><div class="example-contents">
+            
+            <pre class="programlisting">package org.glyptodon.guacamole.auth;
+
+import org.glyptodon.guacamole.properties.StringGuacamoleProperty;
+
+public class TutorialGuacamoleProperties {
+
+    /**
+     * This class should not be instantiated.
+     */
+    private TutorialGuacamoleProperties() {}
+
+    /**
+     * The only user to allow.
+     */
+    public static final StringGuacamoleProperty TUTORIAL_USER = 
+        new StringGuacamoleProperty() {
+
+        @Override
+        public String getName() { return "tutorial-user"; }
+
+    };
+
+    /**
+     * The password required for the specified user.
+     */
+    public static final StringGuacamoleProperty TUTORIAL_PASSWORD = 
+        new StringGuacamoleProperty() {
+
+        @Override
+        public String getName() { return "tutorial-password"; }
+
+    };
+
+
+    /**
+     * The protocol to use when connecting.
+     */
+    public static final StringGuacamoleProperty TUTORIAL_PROTOCOL = 
+        new StringGuacamoleProperty() {
+
+        @Override
+        public String getName() { return "tutorial-protocol"; }
+
+    };
+
+
+    /**
+     * All parameters associated with the connection, as a comma-delimited
+     * list of name="value" 
+     */
+    public static final StringGuacamoleProperty TUTORIAL_PARAMETERS = 
+        new StringGuacamoleProperty() {
+
+        @Override
+        public String getName() { return "tutorial-parameters"; }
+
+    };
+
+}</pre>
+        </div></div><br class="example-break" />
+        <p>Normally, we would define a new type of <code class="classname">GuacamoleProperty</code> to
+            handle the parsing of the parameters required by <code class="varname">TUTORIAL_PARAMETERS</code>,
+            but for the sake of simplicity, parsing of this parameter will be embedded in the
+            authentication function later.</p>
+        <p>You will need to modify your existing <code class="filename">guacamole.properties</code> file,
+            adding each of the above properties to describe one of your available
+            connections.</p>
+        <div class="example"><a id="idp1950256"></a><p class="title"><strong>Example 15.4. Properties describing a user and connection, as required by this tutorial</strong></p><div class="example-contents">
+            
+            <pre class="programlisting"># Username and password
+tutorial-user:     <em class="replaceable"><code>tutorial</code></em>
+tutorial-password: <em class="replaceable"><code>password</code></em>
+
+# Connection information
+tutorial-protocol:   <em class="replaceable"><code>vnc</code></em>
+tutorial-parameters: <em class="replaceable"><code>hostname=localhost, port=5900</code></em></pre>
+        </div></div><br class="example-break" />
+        <p>Once these properties and their accessor class are in place, it's simple enough to
+            read the properties within <code class="methodname">getAuthorizedConfigurations()</code> and
+            authenticate the user based on their username and password.</p>
+        <div class="example"><a id="idp1954400"></a><p class="title"><strong>Example 15.5. Checking the credentials against the properties</strong></p><div class="example-contents">
+            
+            <pre class="programlisting">@Override
+public Map&lt;String, GuacamoleConfiguration&gt;
+    getAuthorizedConfigurations(Credentials credentials)
+    throws GuacamoleException {
+
+    // Get username
+    String username = GuacamoleProperties.getRequiredProperty(
+        TutorialProperties.TUTORIAL_USER
+    );      
+
+    // If wrong username, fail
+    if (!username.equals(credentials.getUsername()))
+        return null;
+
+    // Get password
+    String password = GuacamoleProperties.getRequiredProperty(
+        TutorialProperties.TUTORIAL_PASSWORD
+    );      
+
+    // If wrong password, fail
+    if (!password.equals(credentials.getPassword()))
+        return null;
+
+    // Successful login. Return configurations (STUB)
+    return new HashMap&lt;String, GuacamoleConfiguration&gt;();
+
+}</pre>
+        </div></div><br class="example-break" />
+        <p>As is, the authentication provider will work in its current state in that the correct
+            username and password will authenticate the user, while an incorrect username or
+            password will not, but we still aren't returning an actual map of configurations. We
+            need to construct the configuration based on the properties in the
+                <code class="filename">guacamole.properties</code> file after the user has been
+            authenticated, and return that configuration to the web application.</p>
+    </div>
+    <div class="section" title="Parsing the configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="parse-conf-example"></a>Parsing the configuration</h2></div></div></div>
+        
+        <p>The only remaining task before we have a fully-functioning authentication provider is
+            to parse the configuration from the <code class="filename">guacamole.properties</code>
+            file.</p>
+        <div class="example"><a id="idp1959952"></a><p class="title"><strong>Example 15.6. Parsing and returning a <code class="classname">GuacamoleConfiguration</code></strong></p><div class="example-contents">
+            
+            <pre class="programlisting">@Override
+public Map&lt;String, GuacamoleConfiguration&gt;
+    getAuthorizedConfigurations(Credentials credentials)
+    throws GuacamoleException {
+
+    // Get username
+    String username = GuacamoleProperties.getRequiredProperty(
+        TutorialProperties.TUTORIAL_USER
+    );      
+
+    // If wrong username, fail
+    if (!username.equals(credentials.getUsername()))
+        return null;
+
+    // Get password
+    String password = GuacamoleProperties.getRequiredProperty(
+        TutorialProperties.TUTORIAL_PASSWORD
+    );      
+
+    // If wrong password, fail
+    if (!password.equals(credentials.getPassword()))
+        return null;
+
+    // Successful login. Return configurations.
+    Map&lt;String, GuacamoleConfiguration&gt; configs = 
+        new HashMap&lt;String, GuacamoleConfiguration&gt;();
+
+    // Create new configuration
+    GuacamoleConfiguration config = new GuacamoleConfiguration();
+
+    // Set protocol specified in properties
+    config.setProtocol(GuacamoleProperties.getRequiredProperty(
+        TutorialProperties.TUTORIAL_PROTOCOL
+    ));
+
+    // Set all parameters, splitting at commas
+    for (String parameterValue : GuacamoleProperties.getRequiredProperty(
+        TutorialProperties.TUTORIAL_PARAMETERS
+    ).split(",\\s*")) {
+
+        // Find the equals sign
+        int equals = parameterValue.indexOf('=');
+        if (equals == -1)
+            throw new GuacamoleException("Required equals sign missing");
+
+        // Get name and value from parameter string
+        String name = parameterValue.substring(0, equals);
+        String value = parameterValue.substring(equals+1);
+
+        // Set parameter as specified
+        config.setParameter(name, value);
+
+    }
+
+    configs.put("DEFAULT", config);
+    return configs;
+
+}</pre>
+        </div></div><br class="example-break" />
+    </div>
+</div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="custom-protocols.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="developers-guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="writing-you-own-guacamole-app.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 14. Adding new protocols </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 16. Writing your own Guacamole application</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>


Mime
View raw message