You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@guacamole.apache.org by mj...@apache.org on 2016/05/05 23:36:43 UTC
[08/51] [abbrv] [partial] incubator-guacamole-website git commit:
Deploy first version of the Apache Guacamole website (reworded and restyled
from the old guac-dev.org).
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/af9b9c05/content/doc/0.8.3/gug/configuring-guacamole.html
----------------------------------------------------------------------
diff --git a/content/doc/0.8.3/gug/configuring-guacamole.html b/content/doc/0.8.3/gug/configuring-guacamole.html
new file mode 100644
index 0000000..4dbe601
--- /dev/null
+++ b/content/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"><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" 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"><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" 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"><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" 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"><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 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"><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 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"><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="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/af9b9c05/content/doc/0.8.3/gug/custom-authentication.html
----------------------------------------------------------------------
diff --git a/content/doc/0.8.3/gug/custom-authentication.html b/content/doc/0.8.3/gug/custom-authentication.html
new file mode 100644
index 0000000..c4f2731
--- /dev/null
+++ b/content/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"><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">
+
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.glyptodon.guacamole</groupId>
+ <artifactId>guacamole-auth-tutorial</artifactId>
+ <packaging>jar</packaging>
+ <version>0.8.0</version>
+ <name>guacamole-auth-tutorial</name>
+ <url>http://guac-dev.org/</url>
+
+ <properties>
+ <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+ </properties>
+
+ <build>
+ <plugins>
+
+ <!-- Written for 1.6 -->
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <source>1.6</source>
+ <target>1.6</target>
+ </configuration>
+ </plugin>
+
+ </plugins>
+ </build>
+
+ <dependencies>
+
+ <!-- Guacamole Java API -->
+ <dependency>
+ <groupId>org.glyptodon.guacamole</groupId>
+ <artifactId>guacamole-common</artifactId>
+ <version>0.8.0</version>
+ </dependency>
+
+ <!-- Guacamole Extension API -->
+ <dependency>
+ <groupId>org.glyptodon.guacamole</groupId>
+ <artifactId>guacamole-ext</artifactId>
+ <version>0.8.0</version>
+ </dependency>
+
+ </dependencies>
+
+ <repositories>
+
+ <!-- Central Guacamole repository -->
+ <repository>
+ <id>guac-dev</id>
+ <url>http://guac-dev.org/repo</url>
+ </repository>
+
+ </repositories>
+
+</project></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<String, GuacamoleConfiguration>
+ 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<String, GuacamoleConfiguration>
+ 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<String, GuacamoleConfiguration>();
+
+}</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<String, GuacamoleConfiguration>
+ 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<String, GuacamoleConfiguration> configs =
+ new HashMap<String, GuacamoleConfiguration>();
+
+ // 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>