You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@guacamole.apache.org by jm...@apache.org on 2017/01/23 06:53:10 UTC
[04/52] [partial] incubator-guacamole-website git commit: Add
0.9.11-incubating documentation.
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/2441fd18/doc/0.9.11-incubating/gug/custom-auth.html
----------------------------------------------------------------------
diff --git a/doc/0.9.11-incubating/gug/custom-auth.html b/doc/0.9.11-incubating/gug/custom-auth.html
new file mode 100644
index 0000000..f6fc764
--- /dev/null
+++ b/doc/0.9.11-incubating/gug/custom-auth.html
@@ -0,0 +1,383 @@
+<?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�19.�Custom authentication</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.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�18.�Adding new protocols" /><link rel="next" href="writing-you-own-guacamole-app.html" title="Chapter�20.�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�19.�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" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="custom-auth"></a>Chapter�19.�Custom authentication</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="custom-auth.html#custom-auth-model">Guacamole's authentication model</a></span></dt><dt><span class="section"><a href="custom-auth.html#custom-auth-skeleton">A Guacamole extension skeleton</a></span></dt><dt><span class="section"><a href="custom-auth.html#custom-a
uth-building">Building the extension</a></span></dt><dt><span class="section"><a href="custom-auth.html#custom-auth-config">Configuration and authentication</a></span></dt><dt><span class="section"><a href="custom-auth.html#custom-auth-more-config">Parsing the configuration</a></span></dt><dt><span class="section"><a href="custom-auth.html#custom-auth-installing">Installing the extension</a></span></dt></dl></div><a id="idm140352907630400" 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. Extensions 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
+ extension 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 extensions for Guacamole will use the principles
+ demonstrated here. This tutorial demonstrates the simplest way to create an authentication
+ extension for Guacamole - an authentication extension that does not support management of
+ users and connections via the web interface.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="custom-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 designated classes called "authentication providers".
+ Given the set of credentials, authentication providers return a context object that
+ provides restricted access to other users and connections, if any.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="custom-auth-skeleton"></a>A Guacamole extension 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 extension.</p><p>The bare minimum required for a Guacamole authentication extension is a
+ <code class="filename">pom.xml</code> file listing guacamole-ext as a dependency, a single
+ .java file implementing our stub of an authentication provider, and a
+ <code class="filename">guac-manifest.json</code> file describing the extension and pointing
+ to our authentication provider class.</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="idm140352907838496"></a><p class="title"><strong>Example�19.1.�Barebones <code class="filename">pom.xml</code> required for a simple authentication
+ extension.</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.apache.guacamole</groupId>
+ <artifactId>guacamole-auth-tutorial</artifactId>
+ <packaging>jar</packaging>
+ <version>0.9.11-incubating</version>
+ <name>guacamole-auth-tutorial</name>
+
+ <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>
+ <version>3.3</version>
+ <configuration>
+ <source>1.6</source>
+ <target>1.6</target>
+ </configuration>
+ </plugin>
+
+ </plugins>
+ </build>
+
+ <dependencies>
+
+ <!-- Guacamole Extension API -->
+ <dependency>
+ <groupId>org.apache.guacamole</groupId>
+ <artifactId>guacamole-ext</artifactId>
+ <version>0.9.11-incubating</version>
+ <scope>provided</scope>
+ </dependency>
+
+ </dependencies>
+
+</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 extension 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.apache.guacamole.auth.TutorialAuthenticationProvider</code>.</p><div class="example"><a id="idm140352907715616"></a><p class="title"><strong>Example�19.2.�A skeleton <code class="classname">TutorialAuthenticationProvider</code></strong></p><div class="example-contents"><pre class="programlisting">package org.apache.guacamole.auth;
+
+import java.util.Map;
+import org.apache.guacamole.GuacamoleException;
+import org.apache.guacamole.net.auth.simple.SimpleAuthenticationProvider;
+import org.apache.guacamole.net.auth.Credentials;
+import org.apache.guacamole.protocol.GuacamoleConfiguration;
+
+/**
+ * Authentication provider implementation intended to demonstrate basic use
+ * of Guacamole's extension API. The credentials and connection information for
+ * a single user are stored directly in guacamole.properties.
+ */
+public class TutorialAuthenticationProvider extends SimpleAuthenticationProvider {
+
+ @Override
+ public String getIdentifier() {
+ return "tutorial";
+ }
+
+ @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/org/apache/guacamole/auth</code> as
+ <code class="filename">TutorialAuthenticationProvider.java</code>.</p><p>Notice how simple the authentication provider is. The
+ <code class="classname">SimpleAuthenticationProvider</code> base class simplifies the
+ <code class="classname">AuthenticationProvider</code> interface, requiring nothing more than
+ a unique identifier (we will use "tutorial") and 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, <code class="methodname">getAuthorizedConfigurations()</code> will just return
+ <code class="varname">null</code>. This 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><p>The only remaining piece for the overall skeleton to be complete is a
+ <code class="filename">guac-manifest.json</code> file. <span class="emphasis"><em>This file is absolutely
+ required for all Guacamole extensions.</em></span> The
+ <code class="filename">guac-manifest.json</code> format is described in more detail in <a class="xref" href="guacamole-ext.html" title="Chapter�17.�guacamole-ext">Chapter�17, <em>guacamole-ext</em></a>. It provides
+ for quite a few properties, but for our authentication extension we are mainly
+ interested in the Guacamole version sanity check (to make sure an extension built for
+ the API of Guacamole version X is not accidentally used against version Y) and telling
+ Guacamole where to find our authentication provider class.</p><p>The Guacamole extension format requires that <code class="filename">guac-manifest.json</code>
+ be placed in the root directory of the extension <code class="filename">.jar</code> file. To
+ accomplish this with Maven, we place it within the
+ <code class="filename">src/main/resources</code> directory. Maven will automatically pick it
+ up during the build and include it within the <code class="filename">.jar</code>.</p><div class="example"><a id="idm140352907746544"></a><p class="title"><strong>Example�19.3.�The required <code class="filename">guac-manifest.json</code></strong></p><div class="example-contents"><pre class="programlisting">{
+
+ "guacamoleVersion" : "0.9.11-incubating",
+
+ "name" : "Tutorial Authentication Extension",
+ "namespace" : "guac-auth-tutorial",
+
+ "authProviders" : [
+ "org.apache.guacamole.auth.TutorialAuthenticationProvider"
+ ]
+
+}</pre></div></div><br class="example-break" /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="custom-auth-building"></a>Building the extension</h2></div></div></div><p>Once all three of the above files are in place, the extension will build, and can even
+ be installed within Guacamole (see <a class="xref" href="custom-auth.html#custom-auth-installing" title="Installing the extension">the section called \u201cInstalling the extension\u201d</a> at the end of this chapter), even though it is
+ just a skeleton at this point. It won't do anything yet other than reject all
+ authentication attempts, but it's good to at least try building the extension to make
+ sure nothing is missing and that all steps have been followed correctly so far:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> mvn package
+<code class="computeroutput">[INFO] Scanning for projects...
+[INFO] ------------------------------------------------------------------------
+[INFO] Building guacamole-auth-tutorial 0.9.11-incubating
+[INFO] ------------------------------------------------------------------------
+...
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 2.345 s
+[INFO] Finished at: 2015-12-16T13:39:00-08:00
+[INFO] Final Memory: 14M/138M
+[INFO] ------------------------------------------------------------------------</code>
+<code class="prompt">$</code></pre></div><p>Assuming you see the "<code class="computeroutput">BUILD SUCCESS</code>" message when you
+ build the extension, there will be a new file,
+ <code class="filename">target/guacamole-auth-tutorial-0.9.11-incubating.jar</code>, which can be
+ installed within Guacamole and tested. If you changed the name or version of the project
+ in the <code class="filename">pom.xml</code> file, the name of this new <code class="filename">.jar</code>
+ file will be different, but it can still be found within
+ <code class="filename">target/</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="custom-auth-config"></a>Configuration and authentication</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 class="variablelist"><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="idm140352907698128"></a><p class="title"><strong>Example�19.4.�<code class="filename">TutorialProperties.java</code>, a class containing property
+ definitions</strong></p><div class="example-contents"><pre class="programlisting">package org.apache.guacamole.auth;
+
+import org.apache.guacamole.properties.StringGuacamoleProperty;
+
+/**
+ * Utility class containing all properties used by the custom authentication
+ * tutorial. The properties defined here must be specified within
+ * guacamole.properties to configure the tutorial authentication provider.
+ */
+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="idm140352907345456"></a><p class="title"><strong>Example�19.5.�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="idm140352907341248"></a><p class="title"><strong>Example�19.6.�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 the Guacamole server environment
+ Environment environment = new LocalEnvironment();
+
+ // Get username from guacamole.properties
+ String username = environment.getRequiredProperty(
+ TutorialGuacamoleProperties.TUTORIAL_USER
+ );
+
+ // If wrong username, fail
+ if (!username.equals(credentials.getUsername()))
+ return null;
+
+ // Get password from guacamole.properties
+ String password = environment.getRequiredProperty(
+ TutorialGuacamoleProperties.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"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="custom-auth-more-config"></a>Parsing the configuration</h2></div></div></div><p>The only remaining task before we have a fully-functioning authentication provider is
+ to actually parse the configuration from the <code class="filename">guacamole.properties</code>
+ file.</p><div class="example"><a id="idm140352907335456"></a><p class="title"><strong>Example�19.7.�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 the Guacamole server environment
+ Environment environment = new LocalEnvironment();
+
+ // Get username from guacamole.properties
+ String username = environment.getRequiredProperty(
+ TutorialGuacamoleProperties.TUTORIAL_USER
+ );
+
+ // If wrong username, fail
+ if (!username.equals(credentials.getUsername()))
+ return null;
+
+ // Get password from guacamole.properties
+ String password = environment.getRequiredProperty(
+ TutorialGuacamoleProperties.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(environment.getRequiredProperty(
+ TutorialGuacamoleProperties.TUTORIAL_PROTOCOL
+ ));
+
+ // Set all parameters, splitting at commas
+ for (String parameterValue : environment.getRequiredProperty(
+ TutorialGuacamoleProperties.TUTORIAL_PARAMETERS
+ ).split(",\\s*")) {
+
+ // Find the equals sign
+ int equals = parameterValue.indexOf('=');
+ if (equals == -1)
+ throw new GuacamoleServerException("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("Tutorial Connection", config);
+ return configs;
+
+}</pre></div></div><br class="example-break" /><p>The extension is now complete and can be built as described earlier in <a class="xref" href="custom-auth.html#custom-auth-building" title="Building the extension">the section called \u201cBuilding the extension\u201d</a>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="custom-auth-installing"></a>Installing the extension</h2></div></div></div><p>Guacamole extensions are self-contained <code class="filename">.jar</code> files which are
+ installed by being placed within <code class="filename">GUACAMOLE_HOME/extensions</code>, and
+ this extension is no different. As described in <a class="xref" href="configuring-guacamole.html" title="Chapter�5.�Configuring Guacamole">Chapter�5, <em>Configuring Guacamole</em></a>,
+ <code class="varname">GUACAMOLE_HOME</code> is a placeholder used to refer to the directory
+ that Guacamole uses to locate its configuration files and extensions. Typically, this
+ will be the <code class="filename">.guacamole</code> directory within the home directory of the
+ user running Tomcat.</p><p>To install your extension, ensure that the required properties have been added to your
+ <code class="filename">guacamole.properties</code>, copy the
+ <code class="filename">target/guacamole-auth-tutorial-0.9.11-incubating.jar</code> file into
+ <code class="filename">GUACAMOLE_HOME/extensions</code> and restart Tomcat. Guacamole will
+ automatically load your extension, logging an informative message that it has done
+ so:</p><div class="informalexample"><pre class="screen">Extension "Tutorial Authentication Extension" loaded.</pre></div></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�18.�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�20.�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>
+ </body></html>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/2441fd18/doc/0.9.11-incubating/gug/custom-protocols.html
----------------------------------------------------------------------
diff --git a/doc/0.9.11-incubating/gug/custom-protocols.html b/doc/0.9.11-incubating/gug/custom-protocols.html
new file mode 100644
index 0000000..7a5a219
--- /dev/null
+++ b/doc/0.9.11-incubating/gug/custom-protocols.html
@@ -0,0 +1,654 @@
+<?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�18.�Adding new protocols</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.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="guacamole-ext.html" title="Chapter�17.�guacamole-ext" /><link rel="next" href="custom-auth.html" title="Chapter�19.�Custom 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�18.�Adding new protocols</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="guacamole-ext.html">Prev</a>�</td><th width="60%" align="center">Part�II.�Developer's Guide</th><td width="20%" align="right">�<a accesskey="n" href="custom-auth.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="custom-protocols"></a>Chapter�18.�Adding new protocols</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="custom-protocols.html#libguac-client-ball-skeleton">Minimal skeleton client</a></span></dt><dt><span class="section"><a href="custom-protocols.html#libguac-client-ball-display-init">Initializing the remote display</a></span></dt><dt><span class="section"><a href="custom-protocols.h
tml#libguac-client-ball-layer">Adding the ball</a></span></dt><dt><span class="section"><a href="custom-protocols.html#libguac-client-ball-bounce">Making the ball bounce</a></span></dt><dt><span class="section"><a href="custom-protocols.html#libguac-client-ball-pretty">A prettier ball</a></span></dt><dt><span class="section"><a href="custom-protocols.html#libguac-client-ball-time">Handling the passage of time</a></span></dt></dl></div><a id="idm140352911490960" class="indexterm"></a><p>Guacamole's support for multiple remote desktop protocols is provided through plugins
+ which guacd loads dynamically. The Guacamole API has been designed such that protocol
+ support is easy to create, especially when a C library exists providing a basic client
+ implementation.</p><p>In this tutorial, we will implement a simple "client" which renders a bouncing ball using
+ the Guacamole protocol. After completing the tutorial and installing the result, you will be
+ able to add a connection to your Guacamole configuration using the "ball" protocol, and any
+ users using that connection will see a bouncing ball.</p><p>This example client plugin doesn't actually act as a client, but this isn't important. The
+ Guacamole client is really just a remote display, and this client plugin functions as a
+ simple example application which renders to this display, just as Guacamole's own VNC or RDP
+ plugins function as VNC or RDP clients which render to the remote display.</p><p>Each step of this tutorial is intended to exercise a new concept,
+ while also progressing towards the goal of a nifty bouncing ball. At the
+ end of each step, you will have a buildable and working client
+ plugin.</p><p>This tutorial will use the GNU Automake build system, which is the build system used by
+ Guacamole for libguac, guacd, etc. There will be four files involved:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">configure.ac</code></span></dt><dd><p>Used by GNU Automake to generate the <code class="filename">configure</code> script
+ which ultimately serves to generate the <code class="filename">Makefile</code> which
+ <span class="command"><strong>make</strong></span> will use when building.</p></dd><dt><span class="term"><code class="filename">Makefile.am</code></span></dt><dd><p>Used by GNU Automake and the <code class="filename">configure</code> script to generate
+ the <code class="filename">Makefile</code> which <span class="command"><strong>make</strong></span> will use when
+ building.</p></dd><dt><span class="term"><code class="filename">src/ball.c</code></span></dt><dd><p>The main body of code defining the bouncing ball "client".</p></dd><dt><span class="term"><code class="filename">src/ball.h</code></span></dt><dd><p>A header file defining the structure representing the state of the bouncing
+ ball (once it becomes necessary to do so).</p></dd></dl></div><p>All source files will be within the <code class="filename">src</code> subdirectory, as is common
+ with C projects, with build files being at the root level directory. The main
+ <code class="filename">src/ball.c</code> and the build-related <code class="filename">configure.ac</code>
+ and <code class="filename">Makefile.am</code> files will be created first, with each successive step
+ building upon those files iteratively, with <code class="filename">src/ball.h</code> being added when
+ it becomes necessary. After each step, you can build/rebuild the plugin by running
+ <span class="command"><strong>make</strong></span>, and then install it (such that guacd can find the plugin) by
+ running <span class="command"><strong>make install</strong></span> and <span class="command"><strong>ldconfig</strong></span> as root:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>make</code></strong>
+<code class="computeroutput"> CC src/ball.lo
+ CCLD libguac-client-ball.la</code>
+<code class="prompt">#</code> <strong class="userinput"><code>make install</code></strong>
+<code class="computeroutput">make[1]: Entering directory '/home/user/libguac-client-ball'
+ /usr/bin/mkdir -p '/usr/local/lib'
+ /bin/sh ./libtool --mode=install /usr/bin/install -c libguac-client-ball.la '/usr/local/lib'
+...
+----------------------------------------------------------------------
+Libraries have been installed in:
+ /usr/local/lib
+
+If you ever happen to want to link against installed libraries
+in a given directory, LIBDIR, you must either use libtool, and
+specify the full pathname of the library, or use the '-LLIBDIR'
+flag during linking and do at least one of the following:
+ - add LIBDIR to the 'LD_LIBRARY_PATH' environment variable
+ during execution
+ - add LIBDIR to the 'LD_RUN_PATH' environment variable
+ during linking
+ - use the '-Wl,-rpath -Wl,LIBDIR' linker flag
+ - have your system administrator add LIBDIR to '/etc/ld.so.conf'
+
+See any operating system documentation about shared libraries for
+more information, such as the ld(1) and ld.so(8) manual pages.
+----------------------------------------------------------------------
+make[1]: Nothing to be done for 'install-data-am'.
+make[1]: Leaving directory '/home/user/libguac-client-ball'</code>
+<code class="prompt">#</code> <strong class="userinput"><code>ldconfig</code></strong></pre></div><p>Prior to the first time <span class="command"><strong>make</strong></span> is invoked, you will need to run the
+ <code class="filename">configure</code> script, which will first need to be generated using
+ <span class="command"><strong>autoreconf</strong></span>:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>autoreconf -fi</code></strong>
+<code class="computeroutput">libtoolize: putting auxiliary files in '.'.
+libtoolize: copying file './ltmain.sh'
+libtoolize: putting macros in AC_CONFIG_MACRO_DIRS, 'm4'.
+libtoolize: copying file 'm4/libtool.m4'
+libtoolize: copying file 'm4/ltoptions.m4'
+libtoolize: copying file 'm4/ltsugar.m4'
+libtoolize: copying file 'm4/ltversion.m4'
+libtoolize: copying file 'm4/lt~obsolete.m4'
+configure.ac:10: installing './compile'
+configure.ac:4: installing './missing'
+Makefile.am: installing './depcomp'</code>
+<code class="prompt">$</code> <strong class="userinput"><code>./configure</code></strong>
+<code class="computeroutput">checking for a BSD-compatible install... /usr/bin/install -c
+checking whether build environment is sane... yes
+...
+configure: creating ./config.status
+config.status: creating Makefile
+config.status: executing depfiles commands
+config.status: executing libtool commands</code>
+<code class="prompt">$</code></pre></div><p>This process is almost identical to that of building guacamole-server from git, as
+ documented in <a class="xref" href="installing-guacamole.html#building-guacamole-server" title="Building guacamole-server">the section called \u201cBuilding <span class="package">guacamole-server</span>\u201d</a>.</p><div class="important"><h3 class="title">Important</h3><p>The libguac library which is part of guacamole-server is a required dependency of this
+ project. <span class="emphasis"><em>You must first install libguac, guacd, etc. by <a class="link" href="installing-guacamole.html#building-guacamole-server" title="Building guacamole-server">building and installing guacamole-server</a>.</em></span> If guacamole-server
+ has not been installed, and libguac is thus not present, the
+ <code class="filename">configure</code> script will fail with an error indicating that it
+ could not find libguac:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>./configure</code></strong>
+<code class="computeroutput">checking for a BSD-compatible install... /usr/bin/install -c
+checking whether build environment is sane... yes
+...
+checking for guac_client_stream_png in -lguac... no
+configure: error: "libguac is required for communication via "
+ "the Guacamole protocol"</code>
+<code class="prompt">$</code></pre></div><p>You will need to install guacamole-server and then rerun
+ <code class="filename">configure</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="libguac-client-ball-skeleton"></a>Minimal skeleton client</h2></div></div></div><p>Very little needs too be done to implement the most basic client plugin possible. We
+ begin with <code class="filename">src/ball.c</code>, containing the absolute minimum required for
+ a client plugin:</p><div class="informalexample"><a id="ball-01-ball_client.c"></a><pre xml:lang="en" class="programlisting" lang="en">#include <guacamole/client.h>
+
+#include <stdlib.h>
+
+/* Client plugin arguments (empty) */
+const char* TUTORIAL_ARGS[] = { NULL };
+
+int guac_client_init(guac_client* client) {
+
+ /* This example does not implement any arguments */
+ client->args = TUTORIAL_ARGS;
+
+ return 0;
+
+}</pre></div><p>Notice the structure of this file. There is exactly one function,
+ <code class="methodname">guac_client_init</code>, which is the entry
+ point for all Guacamole client plugins. Just as a typical C program
+ has a <code class="methodname">main</code> function which is executed when
+ the program is run, a Guacamole client plugin has
+ <code class="methodname">guac_client_init</code> which is called when
+ guacd loads the plugin when a new connection is made and your
+ protocol is selected.</p><p><code class="methodname">guac_client_init</code> receives a single
+ <code class="classname">guac_client</code> which it must initialize. Part of this
+ initialization process involves declaring the list of arguments that joining users can
+ specify. While we won't be using arguments in this tutorial, and thus the arguments
+ assigned above are simply an empty list, a typical client plugin implementation would
+ register arguments which define the remote desktop connection and its behavior. Examples
+ of such parameters can be seen in the connection parameters for the protocols supported
+ by Guacamole out-of-the-box (see <a class="xref" href="configuring-guacamole.html#connection-configuration" title="Configuring connections">the section called \u201cConfiguring connections\u201d</a>).</p><p>The <code class="classname">guac_client</code> instance given to
+ <code class="methodname">guac_client_init</code> will be shared by the user that starts the
+ connection, and any users which join the connection via screen sharing. It lives until
+ the connection is explicitly closed, or until all users leave the connection.</p><p>For this project to build with GNU Automake, we a <code class="filename">configure.ac</code>
+ file which describes the name of the project and what it needs configuration-wise. In
+ this case, the project is "libguac-client-ball", and it depends on the "libguac" library
+ used by guacd and all client plugins:</p><div class="informalexample"><a id="ball-01-configure.in"></a><pre xml:lang="en" class="programlisting" lang="en"># Project information
+AC_PREREQ([2.61])
+AC_INIT([libguac-client-ball], [0.1.0])
+AM_INIT_AUTOMAKE([-Wall -Werror foreign subdir-objects])
+AM_SILENT_RULES([yes])
+
+AC_CONFIG_MACRO_DIRS([m4])
+
+# Check for required build tools
+AC_PROG_CC
+AC_PROG_CC_C99
+AC_PROG_LIBTOOL
+
+# Check for libguac
+AC_CHECK_LIB([guac], [guac_client_stream_png],,
+ AC_MSG_ERROR("libguac is required for communication via "
+ "the Guacamole protocol"))
+
+AC_CONFIG_FILES([Makefile])
+AC_OUTPUT</pre></div><p>We also need a <code class="filename">Makefile.am</code>, describing which files should be
+ built and how when building
+ libguac-client-ball:<a id="ball-01-Makefile.am"></a></p><pre xml:lang="en" class="programlisting" lang="en">AUTOMAKE_OPTIONS = foreign
+
+ACLOCAL_AMFLAGS = -I m4
+AM_CFLAGS = -Werror -Wall -pedantic
+
+lib_LTLIBRARIES = libguac-client-ball.la
+
+# All source files of libguac-client-ball
+libguac_client_ball_la_SOURCES = src/ball.c
+
+# libtool versioning information
+libguac_client_ball_la_LDFLAGS = -version-info 0:0:0</pre><p>The GNU Automake files will remain largely unchanged throughout
+ the rest of the tutorial. </p><p>Once you have created all of the above files, you will have a functioning client
+ plugin. It doesn't do anything yet, and any connection will be extremely short-lived
+ (the lack of any data sent by the server will lead to the client disconnecting under the
+ assumption that the connection has stopped responding), but it does technically
+ work.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="libguac-client-ball-display-init"></a>Initializing the remote display</h2></div></div></div><p>Now that we have a basic functioning skeleton, we need to actually do something with
+ the remote display. A good first step would be simply initializing the display - setting
+ the remote display size and providing a basic background.</p><p>In this case, we'll set the display to a nice default of 1024x768, and fill the
+ background with gray. Though the size of the display <span class="emphasis"><em>can</em></span> be chosen
+ based on the size of the user's browser window (which is provided by the user during the
+ <a class="link" href="guacamole-protocol.html#guacamole-protocol-handshake" title="Handshake phase">Guacamole protocol handshake</a>), or even
+ updated when the window size changes (provided by the user via <a class="link" href="protocol-reference.html#size-event-instruction" title="size">"size"
+ instructions</a>), we won't be doing that here for the simplicity's sake:</p><div class="informalexample"><a id="ball-02-ball_client.c"></a><pre xml:lang="en" class="programlisting" lang="en">#include <guacamole/client.h>
+<span class="emphasis"><em>#include <guacamole/protocol.h>
+#include <guacamole/socket.h>
+#include <guacamole/user.h></em></span>
+
+#include <stdlib.h>
+
+...
+
+<span class="emphasis"><em>int ball_join_handler(guac_user* user, int argc, char** argv) {
+
+ /* Get client associated with user */
+ guac_client* client = user->client;
+
+ /* Get user-specific socket */
+ guac_socket* socket = user->socket;
+
+ /* Send the display size */
+ guac_protocol_send_size(socket, GUAC_DEFAULT_LAYER, 1024, 768);
+
+ /* Prepare a curve which covers the entire layer */
+ guac_protocol_send_rect(socket, GUAC_DEFAULT_LAYER,
+ 0, 0, 1024, 768);
+
+ /* Fill curve with solid color */
+ guac_protocol_send_cfill(socket,
+ GUAC_COMP_OVER, GUAC_DEFAULT_LAYER,
+ 0x80, 0x80, 0x80, 0xFF);
+
+ /* Mark end-of-frame */
+ guac_protocol_send_sync(socket, client->last_sent_timestamp);
+
+ /* Flush buffer */
+ guac_socket_flush(socket);
+
+ /* User successfully initialized */
+ return 0;
+
+}</em></span>
+
+int guac_client_init(guac_client* client) {
+
+ /* This example does not implement any arguments */
+ client->args = TUTORIAL_ARGS;
+<span class="emphasis"><em>
+ /* Client-level handlers */
+ client->join_handler = ball_join_handler;
+</em></span>
+ return 0;
+
+}</pre></div><p>The most important thing to notice here is the new
+ <code class="function">ball_join_handler()</code> function. As it is assigned to
+ <span class="property">join_handler</span> of the <code class="classname">guac_client</code> given to
+ <code class="function">guac_client_init</code>, users which join the connection (including
+ the user that opened the connection in the first place) will be passed to this function.
+ It is the duty of the join handler to initialize the provided
+ <code class="classname">guac_user</code>, taking into account any arguments received from
+ the user during the connection handshake (exposed through <code class="varname">argc</code> and
+ <code class="varname">argv</code> to the join handler). We aren't implementing any arguments,
+ so these values are simply ignored, but we do need to initialize the user with respect
+ to display state. In this case, we:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Send a <a class="link" href="protocol-reference.html#size-instruction" title="size">"size" instruction</a>, initializing the
+ display size to 1024x768.</p></li><li class="listitem"><p>Draw a 1024x768 gray rectangle over the display using the <a class="link" href="protocol-reference.html#rect-instruction" title="rect">"rect"</a> and <a class="link" href="protocol-reference.html#cfill-instruction" title="cfill">"cfill"</a> instructions.</p></li><li class="listitem"><p>Send a <a class="link" href="protocol-reference.html#server-sync-instruction" title="sync">"sync" instruction</a>, informing the
+ remote display that a frame has been completed.</p></li><li class="listitem"><p>Flush the socket, ensuring that all data written to the socket thus far is
+ immediately sent to the user.</p></li></ol></div><p>At this point, if you build, install, and connect using the plugin, you will see a
+ gray screen. The connection will still be extremely short-lived, however, since the only
+ data ever sent by the plugin is sent when the user first joins. The lack of any data
+ sent by the server over the remaining life of the connection will lead to the client
+ disconnecting under the assumption that the connection has stopped responding. This will
+ be rectified shortly once we add the bouncing ball.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="libguac-client-ball-layer"></a>Adding the ball</h2></div></div></div><p>This tutorial is about making a bouncing ball "client", so naturally we need a ball to
+ bounce. While we could repeatedly draw and erase a ball on the remote display, a more
+ efficient technique would be to leverage Guacamole's layers.</p><p>The remote display has a single root layer, <code class="varname">GUAC_DEFAULT_LAYER</code>, but
+ there can be infinitely many other child layers, which can themselves have child layers,
+ and so on. Each layer can be dynamically repositioned within and relative to another
+ layer. Because the compositing of these layers is handled by the remote display, and is
+ likely hardware-accelerated, this is a much better way to repeatedly reposition
+ something we expect to move a lot.</p><p>Since we're finally adding the ball, and there needs to be some structure which
+ maintains the state of the ball, we must create a header file,
+ <code class="filename">src/ball.h</code>, to define this:</p><div class="informalexample"><pre xml:lang="en" class="programlisting" lang="en">#ifndef BALL_H
+#define BALL_H
+
+#include <guacamole/layer.h>
+
+typedef struct ball_client_data {
+
+ guac_layer* ball;
+
+} ball_client_data;
+
+#endif</pre></div><p>To make the build system aware of the existence of the new
+ <code class="filename">src/ball.h</code> header file, <code class="filename">Makefile.am</code> must
+ be updated as well:</p><div class="informalexample"><pre xml:lang="en" class="programlisting" lang="en">...
+
+# All source files of libguac-client-ball
+<span class="emphasis"><em>noinst_HEADERS = src/ball.h</em></span>
+libguac_client_ball_la_SOURCES = src/ball.c
+
+...</pre></div><p>This new structure is intended to house the client-level state of the ball,
+ independent of any users which join or leave the connection. The structure must be
+ allocated when the client begins (within <code class="function">guac_client_init</code>), freed
+ when the client terminates (via a new client free handler), and must contain the layer
+ which represents the ball within the remote display. As this layer is part of the remote
+ display state, it must additionally be initialized when a user joins, in the same way
+ that the display overall was initialized in earlier steps:</p><div class="informalexample"><a id="ball-03-ball_client.c"></a><pre xml:lang="en" class="programlisting" lang="en"><span class="emphasis"><em>#include "ball.h"</em></span>
+
+#include <guacamole/client.h>
+<span class="emphasis"><em>#include <guacamole/layer.h></em></span>
+#include <guacamole/protocol.h>
+#include <guacamole/socket.h>
+#include <guacamole/user.h>
+
+#include <stdlib.h>
+
+...
+
+int ball_join_handler(guac_user* user, int argc, char** argv) {
+
+ /* Get client associated with user */
+ guac_client* client = user->client;
+<span class="emphasis"><em>
+ /* Get ball layer from client data */
+ ball_client_data* data = (ball_client_data*) client->data;
+ guac_layer* ball = data->ball;
+</em></span>
+ ...
+<span class="emphasis"><em>
+ /* Set up ball layer */
+ guac_protocol_send_size(socket, ball, 128, 128);
+
+ /* Prepare a curve which covers the entire layer */
+ guac_protocol_send_rect(socket, ball,
+ 0, 0, 128, 128);
+
+ /* Fill curve with solid color */
+ guac_protocol_send_cfill(socket,
+ GUAC_COMP_OVER, ball,
+ 0x00, 0x80, 0x80, 0xFF);
+</em></span>
+ /* Mark end-of-frame */
+ guac_protocol_send_sync(socket, client->last_sent_timestamp);
+
+ /* Flush buffer */
+ guac_socket_flush(socket);
+
+ /* User successfully initialized */
+ return 0;
+
+}
+
+<span class="emphasis"><em>int ball_free_handler(guac_client* client) {
+
+ ball_client_data* data = (ball_client_data*) client->data;
+
+ /* Free client-level ball layer */
+ guac_client_free_layer(client, data->ball);
+
+ /* Free client-specific data */
+ free(data);
+
+ /* Data successfully freed */
+ return 0;
+
+}</em></span>
+
+int guac_client_init(guac_client* client) {
+<span class="emphasis"><em>
+ /* Allocate storage for client-specific data */
+ ball_client_data* data = malloc(sizeof(ball_client_data));
+
+ /* Set up client data and handlers */
+ client->data = data;
+
+ /* Allocate layer at the client level */
+ data->ball = guac_client_alloc_layer(client);
+</em></span>
+ ...
+
+ /* Client-level handlers */
+ client->join_handler = ball_join_handler;
+ <span class="emphasis"><em>client->free_handler = ball_free_handler;</em></span>
+
+ return 0;
+
+}</pre></div><p>The allocate/free pattern for the client-specific data and layers should be pretty
+ straightforward - the allocation occurs when the objects (the layer and the structure
+ housing it) are first needed, and the allocated objects are freed once they are no
+ longer needed (when the client terminates) to avoid leaking memory. The initialization
+ of the ball layer using the Guacamole protocol should be familiar as well - it's
+ identical to the way the screen was initialized, and involves the same
+ instructions.</p><p>Beyond layers, Guacamole has the concept of buffers, which are identical in use to
+ layers except they are invisible. Buffers are used to store image data for the sake of
+ caching or drawing operations. We will use them later when we try to make this tutorial
+ prettier. If you build and install the ball client as-is now, you will see a large gray
+ rectangle (the root layer) with a small blue square in the upper left corner (the ball
+ layer).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="libguac-client-ball-bounce"></a>Making the ball bounce</h2></div></div></div><p>To make the ball bounce, we need to track the ball's state, including current position
+ and velocity, as well as a thread which updates the ball's state (and the remote
+ display) as time progresses. The ball state and thread can be stored alongside the ball
+ layer in the existing client-level data structure:</p><div class="informalexample"><a id="ball-04-ball_client.h"></a><pre xml:lang="en" class="programlisting" lang="en">...
+
+#include <guacamole/layer.h>
+
+<span class="emphasis"><em>#include <pthread.h></em></span>
+
+typedef struct ball_client_data {
+
+ guac_layer* ball;
+<span class="emphasis"><em>
+ int ball_x;
+ int ball_y;
+
+ int ball_velocity_x;
+ int ball_velocity_y;
+
+ pthread_t render_thread;
+</em></span>
+} ball_client_data;
+
+...</pre></div><p>The contents of the thread will update these values at a pre-defined rate, changing
+ ball position with respect to velocity, and changing velocity with respect to collisions
+ with the display boundaries:</p><div class="informalexample"><pre xml:lang="en" class="programlisting" lang="en">#include "ball.h"
+
+#include <guacamole/client.h>
+#include <guacamole/layer.h>
+#include <guacamole/protocol.h>
+#include <guacamole/socket.h>
+#include <guacamole/user.h>
+
+<span class="emphasis"><em>#include <pthread.h></em></span>
+#include <stdlib.h>
+
+...
+
+<span class="emphasis"><em>void* ball_render_thread(void* arg) {
+
+ /* Get data */
+ guac_client* client = (guac_client*) arg;
+ ball_client_data* data = (ball_client_data*) client->data;
+
+ /* Update ball position as long as client is running */
+ while (client->state == GUAC_CLIENT_RUNNING) {
+
+ /* Sleep a bit */
+ usleep(30000);
+
+ /* Update position */
+ data->ball_x += data->ball_velocity_x * 30 / 1000;
+ data->ball_y += data->ball_velocity_y * 30 / 1000;
+
+ /* Bounce if necessary */
+ if (data->ball_x < 0) {
+ data->ball_x = -data->ball_x;
+ data->ball_velocity_x = -data->ball_velocity_x;
+ }
+ else if (data->ball_x >= 1024 - 128) {
+ data->ball_x = (2 * (1024 - 128)) - data->ball_x;
+ data->ball_velocity_x = -data->ball_velocity_x;
+ }
+
+ if (data->ball_y < 0) {
+ data->ball_y = -data->ball_y;
+ data->ball_velocity_y = -data->ball_velocity_y;
+ }
+ else if (data->ball_y >= 768 - 128) {
+ data->ball_y = (2 * (768 - 128)) - data->ball_y;
+ data->ball_velocity_y = -data->ball_velocity_y;
+ }
+
+ guac_protocol_send_move(client->socket, data->ball,
+ GUAC_DEFAULT_LAYER, data->ball_x, data->ball_y, 0);
+
+ /* End frame and flush socket */
+ guac_client_end_frame(client);
+ guac_socket_flush(client->socket);
+
+ }
+
+ return NULL;
+
+}</em></span>
+
+...</pre></div><p>Just as with the join handler, this thread sends a "sync" instruction to denote the
+ end of each frame, though here this is accomplished with
+ <code class="function">guac_client_end_frame()</code>. This function sends a "sync"
+ containing the current timestamp, and updates the properties of the
+ <code class="classname">guac_client</code> with the last-sent timestamp (the value that our
+ join handler uses to send <span class="emphasis"><em>its</em></span> sync). Note that we don't redraw the
+ whole display with each frame - we simply update the position of the ball layer using a
+ <a class="link" href="protocol-reference.html#move-instruction" title="move">"move"
+ instruction</a>, and rely on the remote display to handle compositing on its
+ own.</p><p>We now need to update <code class="methodname">guac_client_init</code> to actually create
+ this thread, initialize the ball state within the structure, and store the thread for
+ future cleanup when the client terminates:</p><div class="informalexample"><a id="ball-04-ball_client.c"></a><pre xml:lang="en" class="programlisting" lang="en">...
+
+int ball_free_handler(guac_client* client) {
+
+ ball_client_data* data = (ball_client_data*) client->data;
+<span class="emphasis"><em>
+ /* Wait for render thread to terminate */
+ pthread_join(data->render_thread, NULL);
+</em></span>
+ ...
+
+}
+
+int guac_client_init(guac_client* client) {
+
+ ...
+<span class="emphasis"><em>
+ /* Start ball at upper left */
+ data->ball_x = 0;
+ data->ball_y = 0;
+
+ /* Move at a reasonable pace to the lower right */
+ data->ball_velocity_x = 200; /* pixels per second */
+ data->ball_velocity_y = 200; /* pixels per second */
+
+ /* Start render thread */
+ pthread_create(&data->render_thread, NULL, ball_render_thread, client);
+</em></span>
+ ...
+
+}</pre></div><p>The thread contains a render loop which continually checks the
+ <span class="property">state</span> property of the <code class="classname">guac_client</code>. This
+ property is set to <code class="constant">GUAC_CLIENT_RUNNING</code> when the connection begins,
+ and remains that way for the duration of the connection. When guacd needs to terminate
+ the connection (such as when the last user leaves), the value will change to
+ <code class="constant">GUAC_CLIENT_STOPPING</code>. The free handler we've written can thus
+ rely on <code class="function">pthread_join()</code> to block until the data previously used by
+ the plugin is no longer being used and can safely be freed.</p><p>Once built and installed, our ball client now has a bouncing ball, albeit a very
+ square and plain one. Now that the display is continually updating, and data is being
+ continually received from the server, connected clients will no longer automatically
+ disconnect.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="libguac-client-ball-pretty"></a>A prettier ball</h2></div></div></div><p>Now that we have our ball bouncing, we might as well try to make it actually look like
+ a ball, and try applying some of the fancier graphics features that Guacamole offers.
+ Guacamole provides instructions common to most 2D drawing APIs, including HTML5's canvas
+ and Cairo. This means you can draw arcs, curves, apply fill and stroke, and even use the
+ contents of another layer or buffer as the pattern for a fill or stroke. In complex
+ cases involving many draw operations, it will actually be more efficient to render to a
+ server-side Cairo surface and send only image data to the client, but it's perfect for
+ relatively simple cases like our ball.</p><p>We will try creating a simple gray checkerboard pattern in a buffer, using that for
+ the background instead of the previous gray rectangle, and will modify the ball by
+ replacing the rectangle with an arc, in this case a full circle, complete with stroke
+ (border) and translucent-blue fill:</p><div class="informalexample"><a id="ball-05-ball_client.c"></a><pre xml:lang="en" class="programlisting" lang="en">int ball_join_handler(guac_user* user, int argc, char** argv) {
+
+ ...
+<span class="emphasis"><em>
+ /* Create background tile */
+ guac_layer* texture = guac_client_alloc_buffer(client);
+
+ guac_protocol_send_rect(socket, texture, 0, 0, 64, 64);
+ guac_protocol_send_cfill(socket, GUAC_COMP_OVER, texture,
+ 0x88, 0x88, 0x88, 0xFF);
+
+ guac_protocol_send_rect(socket, texture, 0, 0, 32, 32);
+ guac_protocol_send_cfill(socket, GUAC_COMP_OVER, texture,
+ 0xDD, 0xDD, 0xDD, 0xFF);
+
+ guac_protocol_send_rect(socket, texture, 32, 32, 32, 32);
+ guac_protocol_send_cfill(socket, GUAC_COMP_OVER, texture,
+ 0xDD, 0xDD, 0xDD, 0xFF);
+</em></span>
+
+ /* Prepare a curve which covers the entire layer */
+ guac_protocol_send_rect(socket, GUAC_DEFAULT_LAYER,
+ 0, 0, 1024, 768);
+
+ /* Fill curve with <span class="emphasis"><em>texture</em></span> */
+ <span class="emphasis"><em>guac_protocol_send_lfill</em></span>(socket,
+ GUAC_COMP_OVER, GUAC_DEFAULT_LAYER,
+ <span class="emphasis"><em>texture</em></span>);
+
+ /* Set up ball layer */
+ guac_protocol_send_size(socket, ball, 128, 128);
+<span class="emphasis"><em>
+ /* Prepare a circular curve */
+ guac_protocol_send_arc(socket, data->ball,
+ 64, 64, 62, 0, 6.28, 0);
+
+ guac_protocol_send_close(socket, data->ball);
+
+ /* Draw a 4-pixel black border */
+ guac_protocol_send_cstroke(socket,
+ GUAC_COMP_OVER, data->ball,
+ GUAC_LINE_CAP_ROUND, GUAC_LINE_JOIN_ROUND, 4,
+ 0x00, 0x00, 0x00, 0xFF);
+
+ /* Fill the circle with color */
+ guac_protocol_send_cfill(socket,
+ GUAC_COMP_OVER, data->ball,
+ 0x00, 0x80, 0x80, 0x80);
+
+ /* Free texture (no longer needed) */
+ guac_client_free_buffer(client, texture);
+</em></span>
+ /* Mark end-of-frame */
+ guac_protocol_send_sync(socket, client->last_sent_timestamp);
+
+ ...
+
+}</pre></div><p>Again, because we put the ball in its own layer, we don't have to worry about
+ compositing it ourselves. The remote display will handle this, and will likely do so
+ with hardware acceleration, even though the ball is now translucent. Build and install
+ the ball client after this step, and you will have a rather nice-looking bouncing
+ ball.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="libguac-client-ball-time"></a>Handling the passage of time</h2></div></div></div><p>There are never any guarantees when it comes to timing, threads, and network
+ performance. We cannot necessarily rely on the remote display to handle updates in a
+ timely manner (it may be slow), nor can we rely on the network or server to give
+ priority to communication from guacd. </p><p>The render thread needs to be modified to take this into account, by tracking the
+ actual time spent within each frame, and estimating the amount of time the client spends
+ rendering each frame:</p><div class="informalexample"><pre xml:lang="en" class="programlisting" lang="en">#include "ball.h"
+
+#include <guacamole/client.h>
+#include <guacamole/layer.h>
+#include <guacamole/protocol.h>
+#include <guacamole/socket.h>
+<span class="emphasis"><em>#include <guacamole/timestamp.h></em></span>
+#include <guacamole/user.h>
+
+#include <pthread.h>
+#include <stdlib.h>
+
+...
+
+void* ball_render_thread(void* arg) {
+
+ ...
+<span class="emphasis"><em>
+ /* Init time of last frame to current time */
+ guac_timestamp last_frame = guac_timestamp_current();
+</em></span>
+ /* Update ball position as long as client is running */
+ while (client->state == CLIENT_RUNNING) {
+<span class="emphasis"><em>
+ /* Default to 30ms frames */
+ int frame_duration = 30;
+
+ /* Lengthen frame duration if client is lagging */
+ int processing_lag = guac_client_get_processing_lag(client);
+ if (processing_lag > frame_duration)
+ frame_duration = processing_lag;
+
+ /* Sleep for duration of frame, then get timestamp */
+ usleep(frame_duration);
+ guac_timestamp current = guac_timestamp_current();
+
+ /* Calculate change in time */
+ int delta_t = current - last_frame;
+</em></span>
+ /* Update position */
+ data->ball_x += data->ball_velocity_x * <span class="emphasis"><em>delta_t</em></span> / 1000;
+ data->ball_y += data->ball_velocity_y * <span class="emphasis"><em>delta_t</em></span> / 1000;
+
+ ...
+<span class="emphasis"><em>
+ /* Update timestamp */
+ last_frame = current;
+</em></span>
+ }
+
+ ...
+
+}</pre></div><p>The calculations are pretty simple. Rather than hard-code the duration of each frame,
+ we us a default of 30 milliseconds, lengthening the frame if Guacamole's built-in lag
+ estimation determines that the client is having trouble. The physics portion of the
+ update no longer assumes that the frame will be exactly 30 milliseconds, instead relying
+ on the actual time elapsed since the previous frame.</p><p>At this point, we now have a robust Guacamole client plugin. It handles
+ joining/leaving users correctly, continually updates the remote display state while
+ taking into account variable network/server/client conditions, and cleans up after
+ itself when the connection finally terminates.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="guacamole-ext.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="custom-auth.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter�17.�guacamole-ext�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�Chapter�19.�Custom 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>
+ </body></html>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/2441fd18/doc/0.9.11-incubating/gug/developers-guide.html
----------------------------------------------------------------------
diff --git a/doc/0.9.11-incubating/gug/developers-guide.html b/doc/0.9.11-incubating/gug/developers-guide.html
new file mode 100644
index 0000000..5bed0ac
--- /dev/null
+++ b/doc/0.9.11-incubating/gug/developers-guide.html
@@ -0,0 +1,21 @@
+<?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>Part�II.�Developer's Guide</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="index.html" title="Guacamole Manual" /><link rel="prev" href="troubleshooting.html" title="Chapter�12.�Troubleshooting" /><link rel="next" href="guacamole-protocol.html" title="Chapter�13.�The Guacamole protocol" />
+ <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">Part�II.�Developer's Guide</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="troubleshooting.html">Prev</a>�</td><th width="60%" align="center">�</th><td width="20%" align="right">�<a accesskey="n" href="guacamole-protocol.html">Next</a></td></tr></table><hr /></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a id="developers-guide"></a>Part�II.�Developer's Guide</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="chapter"><a href="guacamole-protocol.html">13. The Guacamole protocol</a></span></dt><dd><dl><dt><span class="section"><a href="guacamole-protocol.html#guacamole-protocol-design">Design</a></span></dt><dt><span class="section"><a href="guacamole-protocol.html#guacamole-protocol-handshake">Handshake phase</a></span></dt><dt><span class="section"><a href="
guacamole-protocol.html#guacamole-protocol-drawing">Drawing</a></span></dt><dt><span class="section"><a href="guacamole-protocol.html#guacamole-protocol-streaming">Streams and objects</a></span></dt><dt><span class="section"><a href="guacamole-protocol.html#guacamole-protocol-events">Events</a></span></dt><dt><span class="section"><a href="guacamole-protocol.html#guacamole-protocol-disconnecting">Disconnecting</a></span></dt></dl></dd><dt><span class="chapter"><a href="libguac.html">14. libguac</a></span></dt><dd><dl><dt><span class="section"><a href="libguac.html#libguac-error-handling">Error handling</a></span></dt><dt><span class="section"><a href="libguac.html#libguac-client-plugins">Client plugins</a></span></dt><dt><span class="section"><a href="libguac.html#libguac-layers">Layers and buffers</a></span></dt><dt><span class="section"><a href="libguac.html#libguac-streams">Streams</a></span></dt><dt><span class="section"><a href="libguac.html#libguac-sending-instructions">Sendin
g instructions</a></span></dt><dt><span class="section"><a href="libguac.html#libguac-event-handling">Event handling</a></span></dt></dl></dd><dt><span class="chapter"><a href="guacamole-common.html">15. <span class="package">guacamole-common</span></a></span></dt><dd><dl><dt><span class="section"><a href="guacamole-common.html#java-http-tunnel">HTTP tunnel</a></span></dt><dt><span class="section"><a href="guacamole-common.html#java-protocol-usage">Using the Guacamole protocol</a></span></dt></dl></dd><dt><span class="chapter"><a href="guacamole-common-js.html">16. guacamole-common-js</a></span></dt><dd><dl><dt><span class="section"><a href="guacamole-common-js.html#guacamole-client">Guacamole client</a></span></dt><dt><span class="section"><a href="guacamole-common-js.html#http-tunnel">HTTP tunnel</a></span></dt><dt><span class="section"><a href="guacamole-common-js.html#input-abstraction">Input abstraction</a></span></dt><dt><span class="section"><a href="guacamole-common-js.html#
on-screen-keyboard">On-screen keyboard</a></span></dt></dl></dd><dt><span class="chapter"><a href="guacamole-ext.html">17. guacamole-ext</a></span></dt><dd><dl><dt><span class="section"><a href="guacamole-ext.html#ext-file-format">Guacamole extension format</a></span></dt><dt><span class="section"><a href="guacamole-ext.html#ext-environment">Accessing the server configuration</a></span></dt><dt><span class="section"><a href="guacamole-ext.html#ext-auth-providers">Authentication providers</a></span></dt><dt><span class="section"><a href="guacamole-ext.html#ext-user-context">The <code class="classname">UserContext</code></a></span></dt><dt><span class="section"><a href="guacamole-ext.html#ext-object-directories"><code class="classname">Directory</code> classes</a></span></dt><dt><span class="section"><a href="guacamole-ext.html#ext-permissions">Permissions</a></span></dt><dt><span class="section"><a href="guacamole-ext.html#ext-connections">Connections</a></span></dt><dt><span class="
section"><a href="guacamole-ext.html#ext-active-connections">Managing/sharing active connections</a></span></dt></dl></dd><dt><span class="chapter"><a href="custom-protocols.html">18. Adding new protocols</a></span></dt><dd><dl><dt><span class="section"><a href="custom-protocols.html#libguac-client-ball-skeleton">Minimal skeleton client</a></span></dt><dt><span class="section"><a href="custom-protocols.html#libguac-client-ball-display-init">Initializing the remote display</a></span></dt><dt><span class="section"><a href="custom-protocols.html#libguac-client-ball-layer">Adding the ball</a></span></dt><dt><span class="section"><a href="custom-protocols.html#libguac-client-ball-bounce">Making the ball bounce</a></span></dt><dt><span class="section"><a href="custom-protocols.html#libguac-client-ball-pretty">A prettier ball</a></span></dt><dt><span class="section"><a href="custom-protocols.html#libguac-client-ball-time">Handling the passage of time</a></span></dt></dl></dd><dt><span clas
s="chapter"><a href="custom-auth.html">19. Custom authentication</a></span></dt><dd><dl><dt><span class="section"><a href="custom-auth.html#custom-auth-model">Guacamole's authentication model</a></span></dt><dt><span class="section"><a href="custom-auth.html#custom-auth-skeleton">A Guacamole extension skeleton</a></span></dt><dt><span class="section"><a href="custom-auth.html#custom-auth-building">Building the extension</a></span></dt><dt><span class="section"><a href="custom-auth.html#custom-auth-config">Configuration and authentication</a></span></dt><dt><span class="section"><a href="custom-auth.html#custom-auth-more-config">Parsing the configuration</a></span></dt><dt><span class="section"><a href="custom-auth.html#custom-auth-installing">Installing the extension</a></span></dt></dl></dd><dt><span class="chapter"><a href="writing-you-own-guacamole-app.html">20. Writing your own Guacamole application</a></span></dt><dd><dl><dt><span class="section"><a href="writing-you-own-guacam
ole-app.html#basic-guacamole-architecture">The basics</a></span></dt><dt><span class="section"><a href="writing-you-own-guacamole-app.html#web-app-skeleton">Web application skeleton</a></span></dt><dt><span class="section"><a href="writing-you-own-guacamole-app.html#guacamole-skeleton">Adding Guacamole</a></span></dt><dt><span class="section"><a href="writing-you-own-guacamole-app.html#next-steps">Where to go from here</a></span></dt></dl></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="troubleshooting.html">Prev</a>�</td><td width="20%" align="center">�</td><td width="40%" align="right">�<a accesskey="n" href="guacamole-protocol.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter�12.�Troubleshooting�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�Chapter�13.�The Gu
acamole protocol</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>
+ </body></html>
\ No newline at end of file