guacamole-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [03/51] [abbrv] [partial] incubator-guacamole-website git commit: Deploy first version of the Apache Guacamole website (reworded and restyled from the old
Date Thu, 05 May 2016 23:36:38 GMT
diff --git a/content/doc/0.8.3/gug/ldap-auth.html b/content/doc/0.8.3/gug/ldap-auth.html
new file mode 100644
index 0000000..54a8eac
--- /dev/null
+++ b/content/doc/0.8.3/gug/ldap-auth.html
@@ -0,0 +1,249 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "">
+<html xmlns=""><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 5. LDAP 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="users-guide.html" title="Part I. User's Guide" /><link rel="prev" href="mysql-auth.html" title="Chapter 4. MySQL authentication" /><link rel="next" href="noauth.html" title="Chapter 6. Disabling 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 5. LDAP authentication</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="mysql-auth.html">Prev</a> </td><th width="60%" align="center">Part I. User's Guide</th><td width="20%" align="right"> <a accesskey="n" href="noauth.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" title="Chapter 5. LDAP authentication" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="ldap-auth"></a>Chapter 5. LDAP authentication</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="ldap-auth.html#installing-ldap-auth">Installing LDAP authentication</a></span></dt><dd><dl><dt><span class="section"><a href="ldap-auth.html#idp955248">Configuring Guacamole</a></span></dt><dt><span class="section"><a href="ldap-auth.html#idp978416">Installing the schema</a></s
 pan></dt></dl></dd><dt><span class="section"><a href="ldap-auth.html#ldap-auth-schema">The LDAP schema</a></span></dt><dd><dl><dt><span class="section"><a href="ldap-auth.html#idp996016">Users</a></span></dt><dt><span class="section"><a href="ldap-auth.html#idp997920">Connections and parameters</a></span></dt></dl></dd></dl></div>
+    <a id="idp935648" class="indexterm"></a>
+    <p>Guacamole supports LDAP authentication via an extension available from the main project
+        website. This extension allows users and connections to be stored directly within an LDAP
+        directory.</p>
+    <p>The LDAP authentication module will need an LDAP directory as storage for all
+        authentication data, and the instructions here assume you already have an LDAP directory
+        installed and working. The schema-related directions are further specific to the OpenLDAP
+        implementation of LDAP. Other LDAP implementations will have their own methods for updating
+        the schema. For such situations, a standards-compliant file describing the schema required
+        by Guacamole's LDAP support is included.</p>
+    <div class="section" title="Installing LDAP authentication"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="installing-ldap-auth"></a>Installing LDAP authentication</h2></div></div></div>
+        <p>The LDAP authentication module is not included in the main Guacamole bundle nor is it
+            enabled by default. You must use the download link provided in the downloads section of
+            the main Guacamole site.</p>
+        <p>The downloaded <code class="filename">.tar.gz</code> file will contain several
+            directories:</p>
+        <div class="variablelist"><dl><dt><span class="term"><code class="filename">lib/</code></span></dt><dd>
+                    <p>Contains all <code class="filename">.jar</code> files required for the LDAP
+                        authentication module to work, including the module itself and the LDAP
+                        library driving it.</p>
+                </dd><dt><span class="term"><code class="filename">schema/</code></span></dt><dd>
+                    <p>Contains an <code class="filename">.ldif</code> file which describes the LDAP
+                        schema changes as required for an OpenLDAP server, as well as a
+                            <code class="filename">.schema</code> file compliant with RFC-2252. The
+                            <code class="filename">.schema</code> file can be transformed into the
+                            <code class="filename">.ldif</code> file automatically.</p>
+                </dd></dl></div>
+        <p>The contents of <code class="filename">lib/</code> must be copied into the classpath of
+            Guacamole, which is the directory specified by the <span class="property">lib-directory</span>
+            property in <code class="filename"></code>. If this property is not
+            specified, simply add it. On Linux servers,
+                <code class="filename">/var/lib/guacamole/classpath</code> is a good choice, but it can be
+            whatever you like.</p>
+        <p>After copying the files in place, check to make sure all files are present, and there
+            are no conflicts in between multiple versions of <span class="package">guacamole-auth-ldap</span>.
+            The contents should match at least the files shown here:</p>
+        <pre class="screen"><code class="prompt">$</code> ls <em class="replaceable"><code>/var/lib/guacamole/classpath</code></em>
+<code class="computeroutput">guacamole-auth-ldap-0.8.0.jar  jldap-4.3.jar</code>
+<code class="prompt">$</code></pre>
+        <p>Each of the <code class="filename">.jar</code> files above is either the LDAP authentication
+            module itself (<code class="filename">guacamole-auth-ldap-0.8.0.jar</code>) or a dependency. They
+            must all be placed in Guacamole's <span class="property">lib-directory</span> for the LDAP
+            authentication to work.</p>
+        <div class="section" title="Configuring Guacamole"><div class="titlepage"><div><div><h3 class="title"><a id="idp955248"></a>Configuring Guacamole</h3></div></div></div>
+            <a id="idp956160" class="indexterm"></a>
+            <a id="idp957008" class="indexterm"></a>
+            <p>Additional properties must be added to <code class="filename"></code>
+                for Guacamole to load the LDAP support and for the LDAP support to properly connect
+                to your LDAP server:</p>
+            <pre class="programlisting"># Auth provider class
+# LDAP properties
+ldap-hostname:           <em class="replaceable"><code>localhost</code></em>
+ldap-port:               <em class="replaceable"><code>389</code></em>
+ldap-user-base-dn:       <em class="replaceable"><code>ou=people,dc=example,dc=net</code></em>
+ldap-username-attribute: <em class="replaceable"><code>uid</code></em>
+ldap-config-base-dn:     <em class="replaceable"><code>ou=groups,dc=example,dc=net</code></em></pre>
+            <p>The LDAP support depends on the following properties, as shown in the example
+                above:</p>
+            <div class="variablelist"><dl><dt><span class="term"><span class="property">ldap-hostname</span></span></dt><dd>
+                        <p>The hostname of your LDAP server. In the example above, this is given
+                            as "localhost" - the same machine as the web server hosting Guacamole,
+                            but this can be anything.</p>
+                    </dd><dt><span class="term"><span class="property">ldap-port</span></span></dt><dd>
+                        <p>The port your LDAP server listens on. Unless you altered the
+                            configuration somehow, your LDAP server probably listens on the standard
+                            port of 389.</p>
+                    </dd><dt><span class="term"><span class="property">ldap-user-base-dn</span></span></dt><dd>
+                        <p>The base of the DN (Distinguished Name) for all Guacamole users. This
+                            will be appended to the username when a user logs in.</p>
+                    </dd><dt><span class="term"><span class="property">ldap-username-attribute</span></span></dt><dd>
+                        <p>The attribute which contains the username which is part of the DN for
+                            all Guacamole users. Usually, this is <span class="property">uid</span>. This
+                            works together with the user base DN to determine the full DN of each
+                            user logging in.</p>
+                        <p>For example, if the base DN is
+                                "<code class="systemitem">ou=people,dc=example,dc=net</code>" (like the
+                            example above) and the username attribute is "<span class="property">uid</span>",
+                            then a person attempting to login as "<code class="systemitem">user</code>"
+                            would effectively bind with the LDAP directory as
+                                "<code class="systemitem">uid=user,ou=people,dc=example,dc=net</code>".</p>
+                    </dd><dt><span class="term"><span class="property">ldap-config-base-dn</span></span></dt><dd>
+                        <p>The base of the DN for all Guacamole configurations. Each
+                            configuration is analogous to a connection. Within Guacamole's LDAP
+                            support, each configuration functions as a group, having user members. A
+                            user which is a member of a particular configuration group will have
+                            access to that configuration.</p>
+                        <p>This base DN will be used when querying all configurations accessible
+                            by a user once they have successfully logged in.</p>
+                    </dd></dl></div>
+            <p>With the above properties properly set, Guacamole will connect to your LDAP server
+                after you restart Tomcat (or whatever servlet container you are using). You will
+                still need to install the schema modifications to your LDAP server such that you can
+                create new configurations and associated them with users.</p>
+        </div>
+        <div class="section" title="Installing the schema"><div class="titlepage"><div><div><h3 class="title"><a id="idp978416"></a>Installing the schema</h3></div></div></div>
+            <p>Guacamole's LDAP support requires modifications to the standard LDAP schema, adding
+                support for an additional object called <code class="classname">guacConfigGroup</code>. This
+                object and its use will be explained in more detail later. For now, we must add
+                support for this object to the LDAP directory through the provided schema
+                file.</p>
+            <p>The <code class="filename">schema/</code> directory contains two files:
+                    <code class="filename">guacConfigGroup.schema</code>, a standards-compliant file
+                describing the schema, and <code class="filename">guacConfigGroup.ldif</code>, an LDIF file
+                which was automatically generated from the <code class="filename">.schema</code> file
+                specifically for update the schema of an OpenLDAP server. We will be working with
+                    <code class="filename">guacConfigGroup.ldif</code>. If you are not using OpenLDAP, your
+                LDAP server should provide documentation for modifying its schema.</p>
+            <p>The <code class="classname">guacConfigGroup</code> object can be created using the
+                    <span class="command"><strong>ldapadd</strong></span> utility and the provided <code class="filename">.ldif</code>
+                file:</p>
+            <div class="informalexample">
+                <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>ldapadd -Q -Y EXTERNAL -H ldapi:/// -f schema/guacConfigGroup.ldif</code></strong>
+<code class="computeroutput">adding new entry "cn=guacConfigGroup,cn=schema,cn=config"
+<code class="prompt">#</code></pre>
+            </div>
+            <p>If the <code class="classname">guacConfigGroup</code> object was added successfully, you
+                should see output as above. You can confirm the presence of the new object class
+                using the <span class="command"><strong>ldapsearch</strong></span> utility:</p>
+            <div class="informalexample">
+                <pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=schema,cn=config dn</code></strong>
+<code class="computeroutput">dn: cn=schema,cn=config
+dn: cn={0}core,cn=schema,cn=config
+dn: cn={1}cosine,cn=schema,cn=config
+dn: cn={2}nis,cn=schema,cn=config
+dn: cn={3}inetorgperson,cn=schema,cn=config
+dn: cn={4}guacConfigGroup,cn=schema,cn=config
+<code class="prompt">#</code></pre>
+            </div>
+        </div>
+    </div>
+    <div class="section" title="The LDAP schema"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ldap-auth-schema"></a>The LDAP schema</h2></div></div></div>
+        <a id="idp993488" class="indexterm"></a>
+        <p>Guacamole's LDAP support allows users and connections to be managed purely within an
+            LDAP directory defined in <code class="filename"></code>. This is
+            accomplished with a minimum of changes to the standard LDAP schema - all Guacamole users
+            are traditional LDAP users and share the same mechanism of authentication. The only new
+            type of object required is a representation for Guacamole connections,
+                <code class="classname">guacConfigGroup</code>, which was added to your server's schema
+            during the install process above.</p>
+        <div class="section" title="Users"><div class="titlepage"><div><div><h3 class="title"><a id="idp996016"></a>Users</h3></div></div></div>
+            <p>All Guacamole users, as far as the LDAP support is concerned, are LDAP users with
+                standard LDAP credentials. When a user signs in to Guacamole, their username and
+                password will be used to bind to the LDAP server. If this bind operation is
+                successful, the available connections are queried from the directory and the user is
+                allowed in.</p>
+        </div>
+        <div class="section" title="Connections and parameters"><div class="titlepage"><div><div><h3 class="title"><a id="idp997920"></a>Connections and parameters</h3></div></div></div>
+            <p>Each connection is represented by an instance of the
+                    <code class="classname">guacConfigGroup</code> object class, which is simply an extended
+                version of the standard LDAP <code class="classname">groupOfNames</code> which provides a
+                protocol and set of parameters. Only members of the
+                    <code class="classname">guacConfigGroup</code> will have access to the corresponding
+                connection.</p>
+            <p>The <code class="classname">guacConfigGroup</code> object class provides two new
+                attributes in addition to those provided by
+                <code class="classname">groupOfNames</code>:</p>
+            <div class="variablelist"><dl><dt><span class="term"><span class="property">guacConfigProtocol</span></span></dt><dd>
+                        <p>The protocol associated with the connection, such as "vnc" or "rdp".
+                            This attribute is required for every
+                                <code class="classname">guacConfigGroup</code> and can be given only
+                            once.</p>
+                    </dd><dt><span class="term"><span class="property">guacConfigParameter</span></span></dt><dd>
+                        <p>The name and value of a parameter for the specified protocol. This is
+                            given as
+                                    <code class="code"><em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em></code>,
+                            where "name" is the name of the parameter as defined by the
+                            documentation for the protocol specified, and "value" is any allowed
+                            value for that parameter.</p>
+                        <p>This attribute can be given multiple times for the same
+                            connection.</p>
+                    </dd></dl></div>
+            <p>For example, to create a new VNC connection which connects to localhost at port
+                5900, while granting access to <code class="systemitem">user1</code> and
+                    <code class="systemitem">user2</code>, you could create an <code class="filename">.ldif</code>
+                file like the following:</p>
+            <div class="informalexample">
+                <pre class="programlisting">dn: cn=Example Connection,ou=groups,dc=example,dc=net
+objectClass: guacConfigGroup
+objectClass: groupOfNames
+cn: Example Connection
+guacConfigProtocol: vnc
+guacConfigParameter: hostname=localhost
+guacConfigParameter: port=5900
+guacConfigParameter: password=secret
+member: cn=user1,ou=people,dc=example,dc=net
+member: cn=user2,ou=people,dc=example,dc=net</pre>
+            </div>
+            <p>The new connection can then be created using the <span class="command"><strong>ldapadd</strong></span>
+                utility:</p>
+            <div class="informalexample">
+                <pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>ldapadd -x -D <em class="replaceable"><code>cn=admin,dc=example,dc=net</code></em> -W -f <em class="replaceable"><code>example-connection.ldif</code></em></code></strong>
+<code class="computeroutput">Enter LDAP Password: 
+adding new entry "cn=Example Connection,ou=groups,dc=example,dc=net"
+<code class="prompt">$</code></pre>
+            </div>
+            <p>Where <code class="systemitem">cn=admin,dc=example,dc=net</code> is an administrator
+                account with permission to create new entries, and
+                    <code class="filename">example-connection.ldif</code> is the name of the
+                    <code class="filename">.ldif</code> file you just created.</p>
+            <p>There is, of course, no need to use only the standard LDAP utilities to create
+                connections and users. There are useful graphical environments for manipulating LDAP
+                directories, such as Apache Directory Studio, which make many of the tasks given
+                above much easier.</p>
+        </div>
+    </div>
+</div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="mysql-auth.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="noauth.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 4. MySQL authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 6. Disabling 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','//','ga');
+  ga('create', 'UA-75289145-1', 'auto');
+  ga('send', 'pageview');
+<!-- End Google Analytics -->
+        </body></html>
diff --git a/content/doc/0.8.3/gug/libguac.html b/content/doc/0.8.3/gug/libguac.html
new file mode 100644
index 0000000..7735040
--- /dev/null
+++ b/content/doc/0.8.3/gug/libguac.html
@@ -0,0 +1,368 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "">
+<html xmlns=""><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 10. libguac</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="guacamole-protocol.html" title="Chapter 9. The Guacamole protocol" /><link rel="next" href="guacamole-common.html" title="Chapter 11. guacamole-common" />
+            <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 10. libguac</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="guacamole-protocol.html">Prev</a> </td><th width="60%" align="center">Part II. Developer's Guide</th><td width="20%" align="right"> <a accesskey="n" href="guacamole-common.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" title="Chapter 10. libguac" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="libguac"></a>Chapter 10. libguac</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><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="secti
 on"><a href="libguac.html#libguac-sending-instructions">Sending instructions</a></span></dt><dt><span class="section"><a href="libguac.html#libguac-protocol-nesting">Protocol nesting</a></span></dt><dt><span class="section"><a href="libguac.html#libguac-event-handling">Event handling</a></span></dt><dd><dl><dt><span class="section"><a href="libguac.html#libguac-key-events">Key events</a></span></dt><dt><span class="section"><a href="libguac.html#libguac-mouse-events">Mouse events</a></span></dt><dt><span class="section"><a href="libguac.html#libguac-clipboard-events">Clipboard events</a></span></dt><dt><span class="section"><a href="libguac.html#libguac-message-handling">Handling server messages</a></span></dt></dl></dd></dl></div>
+    <a id="idp1432208" class="indexterm"></a>
+    <a id="idp1433472" class="indexterm"></a>
+    <p>The C API for extending and developing with Guacamole is libguac. All
+        native components produced by the Guacamole project link with this
+        library, and this library provides the common basis for extending the
+        native functionality of those native components (by implementing client
+        plugins).</p>
+    <p>libguac is used mainly for developing client plugins like
+        libguac-client-vnc or libguac-client-rdp, or for developing a proxy
+        supporting the Guacamole protocol like guacd. This chapter is intended
+        to give an overview of how libguac is used, and how to use it for
+        general communication with the Guacamole protocol.</p>
+    <div class="section" title="Error handling"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="libguac-error-handling"></a>Error handling</h2></div></div></div>
+        <p>Most functions within libguac handle errors by returning a zero or
+            non-zero value, whichever is appropriate for the function at hand.
+            If an error is encountered, the <code class="varname">guac_error</code>
+            variable is set appropriately, and
+                <code class="varname">guac_error_message</code> contains a
+            statically-allocated human-readable string describing the context of
+            the error. These variables intentionally mimic the functionality
+            provided by <code class="varname">errno</code> and
+                <code class="filename">errno.h</code>.</p>
+        <p>Both <code class="varname">guac_error</code> and
+                <code class="varname">guac_error_message</code> are defined within
+                <code class="filename">error.h</code>. A human-readable string describing
+            the error indicated by <code class="varname">guac_error</code> can be
+            retrieved using <code class="methodname">guac_status_string()</code>, which
+            is also statically allocated.</p>
+        <p>If functions defined within client plugins set
+                <code class="varname">guac_error</code> and
+                <code class="varname">guac_error_message</code> appropriately when errors
+            are encountered, the messages logged to syslog by guacd will be more
+            meaningful for both users and developers.</p>
+    </div>
+    <div class="section" title="Client plugins"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="libguac-client-plugins"></a>Client plugins</h2></div></div></div>
+        <p>Client plugins are libraries loaded dynamically using the
+            functions of libdl. Each client plugin is required to follow a
+            naming convention, where the name of the library is
+                    <span class="package">libguac-client-<em class="replaceable"><code>PROTOCOL</code></em></span>.
+            Failing to do this means that guacd will be unable to find the
+            library when the client plugin needs to be loaded.</p>
+        <p>To load a client plugin, guacd calls the guac_client_plugin_open()
+            function with the name of the protocol corresponding to the plugin
+            to be loaded. Upon success,
+                <code class="methodname">guac_client_plugin_open()</code> returns a
+            handle to the library containing the client plugin within an
+            instance of <code class="classname">guac_client_plugin</code>. This instance
+            will eventually be cleaned up by
+                <code class="methodname">guac_client_plugin_close()</code> when guacd
+            is finished using it. While these functions are intended to be used
+            by guacd, there is no reason they cannot be used in another proxy
+            implementation, even if that proxy implementation resides within
+            another client plugin.</p>
+        <p>Once the client plugin is successfully loaded, guacd makes a call
+            to <code class="methodname">guac_client_plugin_init_client()</code> to
+            initialize the client. This function calls the
+                <code class="methodname">guac_client_init()</code> function within the
+            client plugin which absolutely all client plugins must define. This
+            function is the entry point of all client plugins, similar to the
+                <code class="methodname">main()</code> function of a C program.</p>
+        <p>As guacd handles the handshake procedure required by the Guacamole
+            protocol, it reads a statically-allocated,
+            <code class="constant">NULL</code>-terminated set of argument names declared
+            within the client plugin: <code class="varname">GUAC_CLIENT_ARGS</code>. As
+            with <code class="methodname">guac_client_init()</code>, all client plugins
+            must define this variable if they are to work. As the handshake
+            procedure is completed, guacd will initialize and populate a
+                <code class="classname">guac_client</code> structure, including the
+                <code class="classname">guac_client_info</code> structure contained
+            within it, and pass it to
+                <code class="methodname">guac_client_init()</code> along with the
+            argument count and argument values received by the connecting
+            client.</p>
+        <p>It is the duty of the client plugin implementation to populate the
+            event handlers of the <code class="classname">guac_client</code> it receives
+            as applicable. Once this is done, and the
+                <code class="methodname">guac_client_init()</code> function returns
+            successfully, communication with the connected client begins, and
+            guacd will invoke the event handlers of the
+                <code class="classname">guac_client</code> as necessary for any
+            instruction received.</p>
+    </div>
+    <div class="section" title="Layers and buffers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="libguac-layers"></a>Layers and buffers</h2></div></div></div>
+        <p>The main operand of all drawing instructions is the layer,
+            represented within libguac by the <code class="classname">guac_layer</code>
+            structure. Each <code class="classname">guac_layer</code> is normally
+            allocated using <code class="methodname">guac_client_alloc_layer()</code>
+            or <code class="methodname">guac_client_alloc_buffer()</code>, depending on
+            whether a layer or buffer is desired, and freed with
+                <code class="methodname">guac_client_free_layer()</code> or
+                <code class="methodname">guac_client_free_buffer()</code>.</p>
+        <div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3>
+            <p>Care must be taken to invoke the allocate and free pairs of
+                each type of layer correctly.
+                    <code class="methodname">guac_client_free_layer()</code> should
+                only be used to free layers allocated with
+                    <code class="methodname">guac_client_alloc_layer()</code>, and
+                    <code class="methodname">guac_client_free_buffer()</code> should
+                only be used to free layers allocated with
+                    <code class="methodname">guac_client_alloc_buffer()</code>, all
+                called using the same instance of
+                    <code class="classname">guac_client</code>.</p>
+            <p>If these restrictions are not observed, the effect of invoking
+                these functions is undefined.</p>
+        </div>
+        <p>Using these layer management functions allows you to reuse
+            existing layers or buffers after their original purpose has expired,
+            thus conserving resources on the client side, as allocation of new
+            layers within the remote client is a relatively expensive
+            operation.</p>
+        <p>It is through layers and buffers that Guacamole provides support
+            for hardware-accelerated compositing and cached updates. Creative
+            use of layers and buffers leads to efficient updates on the client
+            side, which usually translates into speed and responsiveness.</p>
+        <p>Regardless of whether you allocate new layers or buffers, there is
+            always one layer guaranteed to be present: the default layer,
+            represented by libguac as <code class="varname">GUAC_DEFAULT_LAYER</code>. If
+            you only wish to affect to the main display of the connected client
+            somehow, this is the layer you want to use as the operand of your
+            drawing instruction.</p>
+    </div>
+    <div class="section" title="Sending instructions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="libguac-sending-instructions"></a>Sending instructions</h2></div></div></div>
+        <p>All drawing in Guacamole is accomplished through the sending of
+            instructions to the connected client using the Guacamole protocol.
+            The same goes for streaming audio, video, or file content. All
+            features and content supported by Guacamole ultimately reduces to
+            one or more instructions which are part of the documented
+            protocol.</p>
+        <p>Most drawing using libguac is done using Cairo functions on a
+                <code class="classname">cairo_surface_t</code> (see the Cairo API
+            documentation) which is later used in a png instruction, sent via
+                <code class="methodname">guac_protocol_send_png()</code>. Cairo was
+            chosen as a dependency of libguac to provide developers an existing
+            and stable means of drawing to image buffers which will ultimately
+            be sent as easy-to-digest PNG images.</p>
+        <p>The Guacamole protocol also supports drawing primitives similar to
+            those present in the Cairo API and HTML5's canvas tag. These
+            instructions are documented individually in the Guacamole Protocol
+            Reference in a section dedicated to drawing instructions, and like
+            all Guacamole protocol instructions, each instruction has a
+            corresponding function in libguac following the naming convention
+                    <code class="methodname">guac_protocol_send_<em class="replaceable"><code>OPCODE</code></em>()</code>.</p>
+        <p>Each protocol function takes a <code class="classname">guac_socket</code>
+            as an argument, which is the buffered I/O object used by libguac.
+            The <code class="classname">guac_socket</code> corresponding to the
+            connected client is stored within the socket member of the
+                <code class="classname">guac_client</code> object in use, for
+            example:</p>
+        <div class="informalexample">
+            <pre class="programlisting">guac_protocol_send_size(client-&gt;socket, GUAC_DEFAULT_LAYER, 1024, 768);</pre>
+        </div>
+    </div>
+    <div class="section" title="Protocol nesting"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="libguac-protocol-nesting"></a>Protocol nesting</h2></div></div></div>
+        <p>When large instructions need to be sent, particularly those
+            associated with audio or video, it is best to send those
+            instructions broken into individual packets using nest instructions,
+            such that the larger instruction can be interleaved with the smaller
+            instructions such that normal responsiveness is not lessened. As
+            future instructions cannot be parsed until the earlier instructions
+            finish parsing, avoiding large instructions is important if the user
+            is expected to interact with their display in real-time.</p>
+        <p>libguac provides rudimentary means of automatically nesting
+            instructions using the <code class="methodname">guac_socket_nest()</code>
+            function. This function returns a new
+                <code class="classname">guac_socket</code> which writes data to nest
+            instructions to its parent <code class="classname">guac_socket</code>,
+            rather than to the client's stream directly. By using this and the
+            piecemeal versions of the instruction-sending functions required,
+            audio or video data can be stretched over multiple instructions
+            rather than one single instruction:</p>
+        <div class="informalexample">
+            <pre class="programlisting">/* Get nested socket */
+guac_socket* nested_socket = guac_socket_nest(client-&gt;socket, 0);
+/* Write audio header */
+    0, "audio/ogg", 250, buffer_size);
+/* Write data packets */
+guac_protocol_send_audio_data(nested_socket, data, sizeof(data));
+/* Finish audio instruction */
+/* When done, close the socket */
+        </div>
+        <p>Providing that calls to guac_protocol_send_audio_data() (or the
+            similar video functions) are made interleaved with calls to smaller
+            instructions, those smaller instructions will not be blocked by the
+            size of the audio data that must be sent.</p>
+        <div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3>
+            <p>Because of the nature of the Guacamole protocol, the size and
+                duration of audio or video data must be known beforehand. If
+                audio or video data must be streamed in real-time, it will need
+                to be divided into individual self-contained chunks. Smaller
+                chunks have a greater chance of causing noticeable gaps due to
+                network hiccups, but are more responsive and will seem more
+                in-line with what is happening from the user's perspective,
+                while larger chunks will be less vulnerable to network issues,
+                but obviously will require the client to wait for a longer time
+                before the audio or video actually starts playing.</p>
+            <p>Note that the size of each audio or video packet is not
+                related to the size of each nest instruction. Choosing larger
+                audio or video packets does not mean that the nest instruction
+                cannot be used; in fact, this is the purpose of the nest
+                instruction: to allow larger instructions to be broken up into
+                smaller instructions.</p>
+        </div>
+    </div>
+    <div class="section" title="Event handling"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="libguac-event-handling"></a>Event handling</h2></div></div></div>
+        <p>Generally, as guacd receives instructions from the connected
+            client, it invokes event handlers if set within the associated
+                <code class="classname">guac_client</code> instance. These handlers
+            correspond to the instructions received, which in turn correspond to
+            events which occur on the client side. The only exception to this is
+            when guacd wishes to give the client plugin control and allow it to
+            handle any messages that may have arrived from the remote desktop
+            server, in which case it invokes a specific event handler dedicated
+            to this purpose.</p>
+        <div class="section" title="Key events"><div class="titlepage"><div><div><h3 class="title"><a id="libguac-key-events"></a>Key events</h3></div></div></div>
+            <p>When keys are pressed or released on the client side, the
+                client sends key instructions to the server. These instructions
+                are parsed and handled by calling the key event handler
+                installed in the <span class="property">key_handler</span> member of the
+                    <code class="classname">guac_client</code>. This key handler is
+                given the keysym of the key that was changed, and a boolean
+                value indicating whether the key was pressed or released.</p>
+            <div class="informalexample">
+                <pre class="programlisting">int key_handler(guac_client* client, int keysym, int pressed) {
+    /* Do something */
+/* Within guac_client_init */
+client-&gt;key_handler = key_handler;</pre>
+            </div>
+        </div>
+        <div class="section" title="Mouse events"><div class="titlepage"><div><div><h3 class="title"><a id="libguac-mouse-events"></a>Mouse events</h3></div></div></div>
+            <p>When the mouse is moved, and buttons are pressed or released,
+                the client sends mouse instructions to the server. These
+                instructions are parsed and handled by calling the mouse event
+                handler installed in the <span class="property">mouse_handler</span>
+                member of the <code class="classname">guac_client</code>. This mouse
+                handler is given the current X and Y coordinates of the mouse
+                pointer, as well as a mask indicating which buttons are pressed
+                and which are released.</p>
+            <div class="informalexample">
+                <pre class="programlisting">int mouse_handler(guac_client* client, int x, int y, int button_mask) {
+    /* Do something */
+/* Within guac_client_init */
+client-&gt;mouse_handler = mouse_handler;</pre>
+            </div>
+            <p>The file <code class="filename">client.h</code> also defines the mask
+                of each button for convenience:</p>
+            <div class="variablelist"><dl><dt><span class="term"><code class="constant">GUAC_CLIENT_MOUSE_LEFT</code></span></dt><dd>
+                        <p>The left mouse button, set when pressed.</p>
+                    </dd><dt><span class="term"><code class="constant">GUAC_CLIENT_MOUSE_MIDDLE</code></span></dt><dd>
+                        <p>The middle mouse button, set when pressed.</p>
+                    </dd><dt><span class="term"><code class="constant">GUAC_CLIENT_MOUSE_RIGHT</code></span></dt><dd>
+                        <p>The right mouse button, set when pressed.</p>
+                    </dd><dt><span class="term"><code class="constant">GUAC_CLIENT_MOUSE_UP</code></span></dt><dd>
+                        <p>The button corresponding to one scroll in the
+                            upwards direction of the mouse scroll wheel, set
+                            when scrolled.</p>
+                    </dd><dt><span class="term"><code class="constant">GUAC_CLIENT_MOUSE_DOWN</code></span></dt><dd>
+                        <p>The button corresponding to one scroll in the
+                            downwards direction of the mouse scroll wheel, set
+                            when scrolled.</p>
+                    </dd></dl></div>
+        </div>
+        <div class="section" title="Clipboard events"><div class="titlepage"><div><div><h3 class="title"><a id="libguac-clipboard-events"></a>Clipboard events</h3></div></div></div>
+            <p>If the client sends data which should be sent to the clipboard
+                of the remote desktop, guacd will trigger the clipboard handler
+                installed in the <span class="property">clipboard_handler</span> member
+                of the <code class="classname">guac_client</code>.</p>
+            <div class="informalexample">
+                <pre class="programlisting">int clipboard_handler(guac_client* client, char* text) {
+    /* Do something */
+/* Within guac_client_init */
+client-&gt;clipboard_handler = clipboard_handler;</pre>
+            </div>
+            <p>The data given will always be a
+                <code class="constant">NULL</code>-terminated string of UTF8-encoded
+                text. The Guacamole protocol does not yet support clipboard data
+                in other formats.</p>
+        </div>
+        <div class="section" title="Handling server messages"><div class="titlepage"><div><div><h3 class="title"><a id="libguac-message-handling"></a>Handling server messages</h3></div></div></div>
+            <p>A client plugin implementation is expected to only handle
+                server messages when control is given to it via a call to the
+                message handler installed in the
+                    <span class="property">handle_messages</span> member of the
+                    <code class="classname">guac_client</code>. While it might seem
+                intuitive to simply create a thread which handles server message
+                in the background, it is important that you do not do this, as
+                guacd pays attention to the exchange of sync instructions back
+                and forth between itself and the client to determine if the
+                client is under load or falling behind due to network problems,
+                and will restrict how frequently the message handler is called
+                accordingly. Ignoring this can lead to the client being
+                overwhelmed with instructions, leading to a bad user
+                experience.</p>
+            <p>The message handler is simpler than all the other handlers,
+                receiving only a pointer to the current
+                    <code class="classname">guac_client</code>:</p>
+            <div class="informalexample">
+                <pre class="programlisting">int message_handler(guac_client* client) {
+    /* Handle server messages */
+/* Within guac_client_init */
+client-&gt;handle_messages = message_handler;</pre>
+            </div>
+        </div>
+    </div>
+</div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="guacamole-protocol.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="guacamole-common.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 9. The Guacamole protocol </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 11. <span class="package">guacamole-common</span></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','//','ga');
+  ga('create', 'UA-75289145-1', 'auto');
+  ga('send', 'pageview');
+<!-- End Google Analytics -->
+        </body></html>

View raw message