You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@guacamole.apache.org by mj...@apache.org on 2016/05/05 23:36:42 UTC
[07/51] [abbrv] [partial] incubator-guacamole-website git commit:
Deploy first version of the Apache Guacamole website (reworded and restyled
from the old guac-dev.org).
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/af9b9c05/content/doc/0.8.3/gug/custom-protocols.html
----------------------------------------------------------------------
diff --git a/content/doc/0.8.3/gug/custom-protocols.html b/content/doc/0.8.3/gug/custom-protocols.html
new file mode 100644
index 0000000..33ff8a7
--- /dev/null
+++ b/content/doc/0.8.3/gug/custom-protocols.html
@@ -0,0 +1,522 @@
+<?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�14.�Adding new protocols</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-ext.html" title="Chapter�13.�guacamole-ext" /><link rel="next" href="custom-authentication.html" title="Chapter�15.�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�14.�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-authentication.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" title="Chapter�14.�Adding new protocols" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="custom-protocols"></a>Chapter�14.�Adding new protocols</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><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 cl
ass="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></div>
+
+ <a id="idp1821568" class="indexterm"></a>
+ <p>While Guacamole as a bundle ships with support for multiple remote
+ desktop protocols (VNC and RDP), this support 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 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 the VNC or RDP support 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>
+ <div class="section" title="Minimal skeleton client"><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: </p>
+ <div class="informalexample">
+ <a id="ball-01-ball_client.c"></a><pre xml:lang="en" class="programlisting" lang="en">#include <stdlib.h>
+#include <guacamole/client.h>
+
+/* Client plugin arguments */
+const char* GUAC_CLIENT_ARGS[] = { NULL };
+
+int guac_client_init(guac_client* client, int argc, char** argv) {
+
+ /* Do nothing ... for now */
+ 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> and the same
+ <code class="varname">argc</code> and <code class="varname">argv</code> arguments
+ that are typical of a C entry point. While we won't be using
+ arguments in this tutorial, a typical client plugin implementation
+ would register its arguments by specifying them in the
+ <code class="varname">GUAC_CLIENT_ARGS</code> static variable, and would
+ receive their values as received from the remote client through
+ <code class="varname">argv</code>.</p>
+ <p>The <code class="classname">guac_client</code> given will live until the
+ connection with the remote display closes. Your
+ <code class="methodname">guac_client_init</code> function is expected
+ to parse any arguments in <code class="varname">argv</code> and initialize the
+ given <code class="classname">guac_client</code>, returning a success code
+ (zero) if the client was initialized successfully.</p>
+ <p>Place this code in a file called
+ <code class="filename">ball_client.c</code> in a subdirectory called
+ <code class="filename">src</code>. The build files provided by this
+ tutorial assume this is the location of all source code.</p>
+ <p>This tutorial, as well as all other C-based Guacamole projects,
+ uses the GNU Automake build system due to its ubiquity and ease of
+ use. The minimal build files required for a libguac-based project
+ that uses GNU Automake are fairly simple. We need a file called
+ <code class="filename">configure.in</code> which describes the name of
+ the project and what it needs configuration-wise:</p>
+ <div class="informalexample">
+ <a id="ball-01-configure.in"></a><pre xml:lang="en" class="programlisting" lang="en"># Project information
+AC_INIT(src/ball_client.c)
+AM_INIT_AUTOMAKE([libguac-client-ball], 0.1.0)
+AC_CONFIG_MACRO_DIR([m4])
+
+# Checks for required build tools
+AC_PROG_CC
+AC_PROG_LIBTOOL
+
+# Check for libguac (http://guac-dev.org/)
+AC_CHECK_LIB([guac], [guac_client_plugin_open],,
+ AC_MSG_ERROR("libguac is required for communication via "
+ "the guacamole protocol"))
+
+# Check for Cairo (http://www.cairo-graphics.org)
+AC_CHECK_LIB([cairo], [cairo_create],,
+ AC_MSG_ERROR("cairo is required for drawing"))
+
+# Checks for header files.
+AC_CHECK_HEADERS([stdlib.h \
+ string.h \
+ syslog.h \
+ guacamole/client.h \
+ guacamole/socket.h \
+ guacamole/protocol.h])
+
+# Checks for library functions.
+AC_FUNC_MALLOC
+
+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_client.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, but it does
+ work, and guacd will load it when requested, and unload it when the
+ connection terminates.</p>
+ </div>
+ <div class="section" title="Initializing the remote display"><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
+ initializing the display - giving the connection a name, setting the
+ remote display size, and providing a basic background.</p>
+ <p>In this case, we name our connection "Bouncing Ball", set the
+ display to a nice default of 1024x768, and fill the background with
+ a simple gray:</p>
+ <div class="informalexample">
+ <a id="ball-02-ball_client.c"></a><pre xml:lang="en" class="programlisting" lang="en">int guac_client_init(guac_client* client, int argc, char** argv) {
+<span class="emphasis"><em>
+ /* Send the name of the connection */
+ guac_protocol_send_name(client->socket, "Bouncing Ball");
+
+ /* Send the display size */
+ guac_protocol_send_size(client->socket, GUAC_DEFAULT_LAYER, 1024, 768);
+
+ /* Fill with solid color */
+ guac_protocol_send_rect(client->socket, GUAC_DEFAULT_LAYER,
+ 0, 0, 1024, 768);
+
+ guac_protocol_send_cfill(client->socket,
+ GUAC_COMP_OVER, GUAC_DEFAULT_LAYER,
+ 0x80, 0x80, 0x80, 0xFF);
+
+ /* Flush buffer */
+ guac_socket_flush(client->socket);
+</em></span>
+ /* Done */
+ return 0;
+
+}</pre></div>
+ <p>Note how communication is done with the remote display. The
+ <code class="classname">guac_client</code> given to
+ <code class="methodname">guac_client_init</code> has a member,
+ <span class="property">socket</span>, which is used for bidirectional
+ communication. Guacamole protocol functions, all starting with
+ "<code class="methodname">guac_protocol_send_</code>", provide a
+ slightly high-level mechanism for sending specific Guacamole
+ protocol instructions to the remote display over the client's
+ socket.</p>
+ <p>Here, we set the name of the connection using a "name" instruction
+ (using <code class="methodname">guac_protocol_send_name</code>), we resize
+ the display using a "size" instruction (using
+ <code class="methodname">guac_protocol_send_size</code>), and we then
+ draw to the display using drawing instructions (rect and
+ cfill).</p>
+ </div>
+ <div class="section" title="Adding the ball"><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. </p>
+ <p>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 have 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>
+ <div class="informalexample">
+ <a id="ball-03-ball_client.c"></a><pre xml:lang="en" class="programlisting" lang="en">int guac_client_init(guac_client* client, int argc, char** argv) {
+<span class="emphasis"><em>
+ /* The layer which will contain our ball */
+ guac_layer* ball;
+</em></span>
+ ...
+<span class="emphasis"><em>
+ /* Set up our ball layer */
+ ball = guac_client_alloc_layer(client);
+ guac_protocol_send_size(client->socket, ball, 128, 128);
+
+ /* Fill with solid color */
+ guac_protocol_send_rect(client->socket, ball,
+ 0, 0, 128, 128);
+
+ guac_protocol_send_cfill(client->socket,
+ GUAC_COMP_OVER, ball,
+ 0x00, 0x80, 0x80, 0xFF);
+</em></span>
+ ...</pre></div>
+ <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.</p>
+ <p>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" title="Making the ball bounce"><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. This state information
+ needs to be stored with the client such that it becomes available to
+ all client handlers.</p>
+ <p>The best way to do this is to create a data structure that
+ contains all the information we need and store it in the
+ <code class="varname">data</code> member of the
+ <code class="classname">guac_client</code>. We create a header file to
+ declare the structure:</p>
+ <div class="informalexample">
+ <a id="ball-04-ball_client.h"></a><pre xml:lang="en" class="programlisting" lang="en">#ifndef _BALL_CLIENT_H
+#define _BALL_CLIENT_H
+
+#include <guacamole/client.h>
+
+typedef struct ball_client_data {
+
+ guac_layer* ball;
+
+ int ball_x;
+ int ball_y;
+
+ int ball_velocity_x;
+ int ball_velocity_y;
+
+} ball_client_data;
+
+int ball_client_handle_messages(guac_client* client);
+
+#endif</pre></div>
+ <p>We also need to implement an event handler for the handle_messages
+ event triggered by guacd when the client plugin needs to handle any
+ server messages received or, in this case, update the ball
+ position:</p>
+ <div class="informalexample">
+ <pre xml:lang="en" class="programlisting" lang="en">int ball_client_handle_messages(guac_client* client) {
+
+ /* Get data */
+ ball_client_data* data = (ball_client_data*) client->data;
+
+ /* 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);
+
+ return 0;
+
+}</pre></div>
+ <p>We also must update <code class="methodname">guac_client_init</code> to
+ initialize the structure, store it in the client, and register our
+ new event handler:</p>
+ <div class="informalexample">
+ <a id="ball-04-ball_client.c"></a><pre xml:lang="en" class="programlisting" lang="en"><span class="emphasis"><em>#include "ball_client.h"
+</em></span>
+...
+
+int guac_client_init(guac_client* client, int argc, char** argv) {
+
+<span class="emphasis"><em>
+ ball_client_data* data = malloc(sizeof(ball_client_data));
+</em></span>
+ ...
+<span class="emphasis"><em>
+ /* Set up client data and handlers */
+ client->data = data;
+ client->handle_messages = ball_client_handle_messages;
+
+ /* Set up our ball layer */
+ data->ball = guac_client_alloc_layer(client);
+
+ /* 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 */
+</em></span>
+ ...
+
+}</pre></div>
+ <p>guacd will call the <code class="methodname">handle_messages</code>
+ handler of the <code class="classname">guac_client</code> repeatedly, if
+ defined. It will stop calling
+ <code class="methodname">handle_messages</code> temporarily if the
+ remote display appears to be lagging behind due to a slow network or
+ slow browser or computer, so there is no guarantee that
+ <code class="methodname">handle_messages</code> will be called as
+ frequently as we would like, but for now, we assume there will be
+ essentially no delay between calls, and we include our own delay of
+ 30ms between frames</p>
+ <p>Because we now have header files, we need to update
+ <code class="filename">Makefile.am</code> to include our header and the
+ directory it's in:</p>
+ <div class="informalexample">
+ <a id="ball-04-Makefile.am"></a><pre xml:lang="en" class="programlisting" lang="en">...
+
+<span class="emphasis"><em>AM_CFLAGS = -Werror -Wall -pedantic -Iinclude</em></span>
+
+...
+
+<span class="emphasis"><em>noinst_HEADERS = include/ball_client.h</em></span></pre></div>
+ <p>Once built and installed, our ball client now has a bouncing ball,
+ albeit a very square and plain one.</p>
+ </div>
+ <div class="section" title="A prettier ball"><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.</p>
+ <p>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.</p>
+ <p>We will try creating a simple gray checkerboard pattern in a
+ buffer and use that for the background instead of the previous gray
+ rectangle.</p>
+ <p>We will also modify the ball by removing the rectangle and
+ replacing it with an arc, in this case a 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 guac_client_init(guac_client* client, int argc, char** argv) {
+
+ ...
+
+ guac_layer* texture;
+
+ ...
+<span class="emphasis"><em>
+ /* Create background tile */
+ texture = guac_client_alloc_buffer(client);
+
+ guac_protocol_send_rect(client->socket, texture, 0, 0, 64, 64);
+ guac_protocol_send_cfill(client->socket, GUAC_COMP_OVER, texture,
+ 0x88, 0x88, 0x88, 0xFF);
+
+ guac_protocol_send_rect(client->socket, texture, 0, 0, 32, 32);
+ guac_protocol_send_cfill(client->socket, GUAC_COMP_OVER, texture,
+ 0xDD, 0xDD, 0xDD, 0xFF);
+
+ guac_protocol_send_rect(client->socket, texture, 32, 32, 32, 32);
+ guac_protocol_send_cfill(client->socket, GUAC_COMP_OVER, texture,
+ 0xDD, 0xDD, 0xDD, 0xFF);
+</em></span>
+
+ /* Fill with solid color */
+ guac_protocol_send_rect(client->socket, GUAC_DEFAULT_LAYER,
+ 0, 0, 1024, 768);
+
+<span class="emphasis"><em>
+ guac_protocol_send_lfill(client->socket,
+ GUAC_COMP_OVER, GUAC_DEFAULT_LAYER,
+ texture);
+</em></span>
+ ...
+<span class="emphasis"><em>
+ /* Fill with solid color */
+ guac_protocol_send_arc(client->socket, data->ball,
+ 64, 64, 62, 0, 6.28, 0);
+
+ guac_protocol_send_close(client->socket, data->ball);
+
+ guac_protocol_send_cstroke(client->socket,
+ GUAC_COMP_OVER, data->ball,
+ GUAC_LINE_CAP_ROUND, GUAC_LINE_JOIN_ROUND, 4,
+ 0x00, 0x00, 0x00, 0xFF);
+
+ guac_protocol_send_cfill(client->socket,
+ GUAC_COMP_OVER, data->ball,
+ 0x00, 0x80, 0x80, 0x80);
+</em></span>
+ ...
+
+}</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.</p>
+ <p>Build and install the ball client after this step, and you will
+ have a rather nice-looking bouncing ball.</p>
+ </div>
+ <div class="section" title="Handling the passage of time"><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>Because the <code class="methodname">handle_messages</code> handler will
+ only be called as guacd deems appropriate, we cannot rely on
+ instantaneous return of control. The server may experience load,
+ causing guacd to lose priority and delay handling of messages, or
+ the remote display may lag due to network or software issues,
+ forcing guacd to temporarily pause updates.</p>
+ <p>We must modify our ball state to include the time the last update
+ took place:</p>
+ <div class="informalexample">
+ <a id="ball-06-ball_client.h"></a><pre xml:lang="en" class="programlisting" lang="en">typedef struct ball_client_data {
+
+ ...
+
+ <span class="emphasis"><em>guac_timestamp last_update;</em></span>
+
+} ball_client_data;</pre></div>
+ <p>Naturally, this new structure member must be initialized within
+ <code class="methodname">guac_client_init</code>:</p>
+ <div class="informalexample">
+ <a id="ball-06-ball_client.c"></a><pre xml:lang="en" class="programlisting" lang="en">int guac_client_init(guac_client* client, int argc, char** argv) {
+
+ ball_client_data* data = malloc(sizeof(ball_client_data));
+
+ ...
+
+<span class="emphasis"><em> data->last_update = guac_protocol_get_timestamp();</em></span>
+
+ ...
+
+}</pre></div>
+ <p>And we need to modify the message handler to check the last update
+ time, updating the ball's position based on its current velocity and
+ the elapsed time:</p>
+ <div class="informalexample">
+ <pre xml:lang="en" class="programlisting" lang="en">int ball_client_handle_messages(guac_client* client) {
+
+ /* Get data */
+ ball_client_data* data = (ball_client_data*) client->data;
+
+<span class="emphasis"><em>
+ guac_timestamp current;
+ int delta_t;
+
+ /* Sleep for a bit, then get timestamp */
+ usleep(30000);
+ current = guac_protocol_get_timestamp();
+
+ /* Calculate change in time */
+ delta_t = current - data->last_update;
+
+ /* Update position */
+ data->ball_x += data->ball_velocity_x * delta_t / 1000;
+ data->ball_y += data->ball_velocity_y * delta_t / 1000;
+</em></span>
+ ...
+<span class="emphasis"><em>
+ /* Update timestamp */
+ data->last_update = current;
+</em></span>
+
+ return 0;
+
+}</pre></div>
+ <p>At this point, we now have a robust Guacamole client plugin. It
+ properly handles the lack of time guarantees for message handler
+ calls, meanwhile providing the user with a seamlessly bouncing
+ ball.</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-authentication.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter�13.�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�15.�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>
+<!-- End Google Analytics -->
+ </body></html>
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/af9b9c05/content/doc/0.8.3/gug/developers-guide.html
----------------------------------------------------------------------
diff --git a/content/doc/0.8.3/gug/developers-guide.html b/content/doc/0.8.3/gug/developers-guide.html
new file mode 100644
index 0000000..8244c35
--- /dev/null
+++ b/content/doc/0.8.3/gug/developers-guide.html
@@ -0,0 +1,36 @@
+<?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 Stylesheets V1.76.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�8.�Troubleshooting" /><link rel="next" href="guacamole-protocol.html" title="Chapter�9.�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" title="Part�II.�Developer's Guide"><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><dt><span class="chapter"><a href="guacamole-protocol.html">9. 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 c
lass="section"><a href="guacamole-protocol.html#guacamole-protocol-nesting">Nesting and interleaving</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-audio-video">Audio and video</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">10. 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 hre
f="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></dl></dd><dt><span class="chapter"><a href="guacamole-common.html">11. <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><dt><span class="section"><a href="guacamole-common.html#reading-properties">Reading properties</a></span></dt></dl></dd><dt><span class="chapter"><a href="guacamole-common-js.html">12. 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">13. guacamole-ext</a></span></dt><dd><dl><dt><span class="section"><a href="guacamole-ext.html#idp1691712">Common configuration</a></span></dt><dt><span class="section"><a href="guacamole-ext.html#auth-providers">Authentication providers</a></span></dt><dt><span class="section"><a href="guacamole-ext.html#event-listeners">Event listeners</a></span></dt></dl></dd><dt><span class="chapter"><a href="custom-protocols.html">14. 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 cl
ass="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 class="chapter"><a href="custom-authentication.html">15. Custom authentication</a></span></dt><dd><dl><dt><span class="section"><a href="custom-authentication.html#auth-model">Guacamole's authentication model</a></span></dt><dt><span class="section"><a href="custom-authentication.html#client-plugin-skeleton">A Guacamole plugin skeleton</a></span></dt><dt><span class="
section"><a href="custom-authentication.html#user-auth-example">Actually authenticating the user</a></span></dt><dt><span class="section"><a href="custom-authentication.html#parse-conf-example">Parsing the configuration</a></span></dt></dl></dd><dt><span class="chapter"><a href="writing-you-own-guacamole-app.html">16. Writing your own Guacamole application</a></span></dt><dd><dl><dt><span class="section"><a href="writing-you-own-guacamole-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�8.�Troubleshooting�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�Chapter�9.�The Guacamole 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>
+<!-- End Google Analytics -->
+ </body></html>
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/af9b9c05/content/doc/0.8.3/gug/faq.html
----------------------------------------------------------------------
diff --git a/content/doc/0.8.3/gug/faq.html b/content/doc/0.8.3/gug/faq.html
new file mode 100644
index 0000000..6f389a9
--- /dev/null
+++ b/content/doc/0.8.3/gug/faq.html
@@ -0,0 +1,124 @@
+<?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>Appendix�A.�FAQ</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="appendices.html" title="Part�III.�Appendices" /><link rel="prev" href="appendices.html" title="Part�III.�Appendices" /><link rel="next" href="protocol-reference.html" title="Appendix�B.�Guacamole protocol reference" />
+ <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">Appendix�A.�FAQ</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="appendices.html">Prev</a>�</td><th width="60%" align="center">Part�III.�Appendices</th><td width="20%" align="right">�<a accesskey="n" href="protocol-reference.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="appendix" title="Appendix�A.�FAQ" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="faq"></a>Appendix�A.�FAQ</h2></div></div></div>
+
+
+
+ <div class="qandaset" title="Frequently Asked Questions"><a id="idp2057920"></a><dl><dt>A.1. <a href="faq.html#idp2058512">Where does the name "Guacamole" come from? </a></dt><dt>A.2. <a href="faq.html#idp2062800">What is does "clientless" mean? </a></dt><dt>A.3. <a href="faq.html#idp2065984">Why does Guacamole not use WebSocket? </a></dt><dt>A.4. <a href="faq.html#idp2069824">I have Tomcat (or some other servlet container) set up behind a proxy (like
+ mod_proxy) and cannot connect to Guacamole. Why? How do I solve this? </a></dt><dt>A.5. <a href="faq.html#idp2074752">I connect to the internet through a web proxy, and cannot connect to
+ Guacamole. I cannot reconfigure the proxy. How do I solve this? </a></dt><dt>A.6. <a href="faq.html#idp2078064">Can I buy special licensing of the Guacamole code base, such that I can use it
+ in my own product, without providing the source to my users, without
+ contributing back, and without acknowledging the project? </a></dt><dt>A.7. <a href="faq.html#idp2081024">Can I pay for custom Guacamole work, or for help integrating Guacamole into my
+ product, if the open source nature and licenses are preserved?</a></dt><dt>A.8. <a href="faq.html#idp2083376">How can I contribute to the project? </a></dt><dt>A.9. <a href="faq.html#idp2086640">How can I become an official member of the project? </a></dt><dt>A.10. <a href="faq.html#idp2090304">I think I've found a bug. How do I report it? </a></dt><dt>A.11. <a href="faq.html#idp2093584">I need help! Where can I find some? </a></dt></dl><table border="0" width="100%" summary="Q and A Set"><col align="left" width="1%" /><col /><tbody>
+ <tr class="question" title="A.1."><td align="left" valign="top"><a id="idp2058512"></a><a id="idp2058768"></a><p><strong>A.1.</strong></p></td><td align="left" valign="top"><p>Where does the name "Guacamole" come from? </p></td></tr>
+ <tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>The name was chosen arbitrarily from a random utterance in a conversation with
+ a member of the project. </p><p>When the project reached the point where it was growing out of the
+ proof-of-concept phase, and needed a real home on the internet, we needed to
+ think of a name to register the project under. </p><p>Several acronyms were toyed with and discarded. We tried anagrams, but all
+ were too wordy and complex. We considered naming the project after a fish or an
+ animal, and after suggesting the guanaco, James Muehlner, a developer of the
+ project, suggested (randomly): "guacamole". </p><p>The name had a nice ring, we weren't embarrassed to use it, and it stuck. </p></td></tr>
+
+ <tr class="question" title="A.2."><td align="left" valign="top"><a id="idp2062800"></a><a id="idp2063056"></a><p><strong>A.2.</strong></p></td><td align="left" valign="top"><p>What is does "clientless" mean? </p></td></tr>
+ <tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>The term "clientless" means that no specific client is needed. A Guacamole
+ user needs only have an HTML5 web browser installed, which is exceedingly
+ common; virtually all modern computers and mobile devices have such a browser
+ installed by default. </p><p>In this sense, Guacamole is "clientless" in that it does not require any
+ additional software to be installed beyond what is considered standard for any
+ computer. </p></td></tr>
+
+ <tr class="question" title="A.3."><td align="left" valign="top"><a id="idp2065984"></a><a id="idp2066240"></a><p><strong>A.3.</strong></p></td><td align="left" valign="top"><p>Why does Guacamole not use WebSocket? </p></td></tr>
+ <tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>The main technical answer here is that there is no need. The tunnel used by
+ Guacamole is exactly equivalent to WebSocket in terms of efficiency and latency,
+ and is more compatible with proxies and existing browsers. </p><p>The historical reason for not going with WebSocket initially was lack of
+ browser support and lack of a true standard. </p><p>Now that WebSocket is standardized, support for WebSocket is present in
+ Guacamole, but it is largely unused because the existing tunnel works just as
+ well and with more browsers. </p></td></tr>
+
+ <tr class="question" title="A.4."><td align="left" valign="top"><a id="idp2069824"></a><a id="idp2070144"></a><p><strong>A.4.</strong></p></td><td align="left" valign="top"><p>I have Tomcat (or some other servlet container) set up behind a proxy (like
+ mod_proxy) and cannot connect to Guacamole. Why? How do I solve this? </p></td></tr>
+ <tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>You need to enable automatic flushing of the proxy's buffer as it receives
+ packets. </p><p>Most proxies, including mod_proxy, buffer data received from the server, and
+ will not flush this data in real-time. Each proxy has an option to force
+ flushing of each packet automatically, as this is necessary for streaming
+ applications like Guacamole, but this is usually not enabled by default. </p><p>Because Guacamole depends on streaming to function, a proxy configured to not
+ automatically flush packets will disrupt the stream to the point that the
+ connection seems unreasonably slow, or just fails to establish altogether. </p><p>In the case of mod_proxy, this option is <code class="code">flushpackets=on</code>. </p></td></tr>
+
+ <tr class="question" title="A.5."><td align="left" valign="top"><a id="idp2074752"></a><a id="idp2075008"></a><p><strong>A.5.</strong></p></td><td align="left" valign="top"><p>I connect to the internet through a web proxy, and cannot connect to
+ Guacamole. I cannot reconfigure the proxy. How do I solve this? </p></td></tr>
+ <tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>You need to enable automatic flushing of your proxy's buffer to avoid
+ disrupting the stream used by Guacamole. </p><p>If you cannot change the settings of your proxy, using HTTPS instead of HTTP
+ should solve the problem. Proxies are required to stream HTTPS because of the
+ nature of SSL. Using HTTPS will allow Guacamole traffic to stream through
+ proxies unencumbered, even if you cannot access the proxy settings directly. </p></td></tr>
+
+ <tr class="question" title="A.6."><td align="left" valign="top"><a id="idp2078064"></a><a id="idp2078320"></a><p><strong>A.6.</strong></p></td><td align="left" valign="top"><p>Can I buy special licensing of the Guacamole code base, such that I can use it
+ in my own product, without providing the source to my users, without
+ contributing back, and without acknowledging the project? </p></td></tr>
+ <tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>Usually, no. Previous requests for such licensing have been very one-sided and
+ there would be no direct or indirect benefit to the community and the project.
+ That said, we handle requests for licensing on a case-by-case basis. In general,
+ any special licensing has to somehow provide for the community and the
+ open-source project.</p></td></tr>
+
+ <tr class="question" title="A.7."><td align="left" valign="top"><a id="idp2081024"></a><a id="idp2081280"></a><p><strong>A.7.</strong></p></td><td align="left" valign="top"><p>Can I pay for custom Guacamole work, or for help integrating Guacamole into my
+ product, if the open source nature and licenses are preserved?</p></td></tr>
+ <tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>Yes. We love to be paid to work on Guacamole, especially if that work remains
+ open source. </p></td></tr>
+
+ <tr class="question" title="A.8."><td align="left" valign="top"><a id="idp2083376"></a><a id="idp2083632"></a><p><strong>A.8.</strong></p></td><td align="left" valign="top"><p>How can I contribute to the project? </p></td></tr>
+ <tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>If you are a programmer and want to contribute code, Guacamole is open-source
+ and you are welcome to do so! Just send us your patches. There is no guarantee
+ that your patch will be added to the upstream source, and all changes are
+ carefully reviewed. </p><p>If you are not a programmer, but want to help out, feel free to look through
+ the documentation or try installing Guacamole and test it out. General editing,
+ documentation contributions, and testing are always helpful. </p></td></tr>
+
+ <tr class="question" title="A.9."><td align="left" valign="top"><a id="idp2086640"></a><a id="idp2086896"></a><p><strong>A.9.</strong></p></td><td align="left" valign="top"><p>How can I become an official member of the project? </p></td></tr>
+ <tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>The short answer is: "by being asked." </p><p>People are only added as official members of the Guacamole project after their
+ work has been proven. This usually means you will have contributed code in the
+ form of patches before, or we know you from extensive testing work, or you
+ frequently help with documentation, and we are impressed enough that we want you
+ as part of the project. </p><p>All that said, you do not need to be a member of the project to help out. Feel
+ free to contribute anything. </p></td></tr>
+
+ <tr class="question" title="A.10."><td align="left" valign="top"><a id="idp2090304"></a><a id="idp2090624"></a><p><strong>A.10.</strong></p></td><td align="left" valign="top"><p>I think I've found a bug. How do I report it? </p></td></tr>
+ <tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>The project hosts a bug tracking tool called Trac at
+ http://guac-dev.org/trac/. All bugs should be reported there as new tickets.
+ This is also where you would request a new feature. </p><p>If the bug you found is security-related, we would prefer to be contacted
+ personally via email, such that the bug can be fixed before becoming dangerously
+ widely known. </p></td></tr>
+
+ <tr class="question" title="A.11."><td align="left" valign="top"><a id="idp2093584"></a><a id="idp2093840"></a><p><strong>A.11.</strong></p></td><td align="left" valign="top"><p>I need help! Where can I find some? </p></td></tr>
+ <tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>The project hosts forums at http://sourceforge.net/projects/guacamole/forums.
+ If you have a SourceForge username (or don't mind registering one), this is a
+ good place to start. </p><p>Otherwise, there are Guacamole-specific official IRC channels on freenode.net:
+ #guacamole, #guacamole-dev, and #guacamole-help. </p><p>If none of those options suffice, you can always email any of the project
+ members directly. You will usually get a personal response, time permitting. </p></td></tr>
+ </tbody></table></div>
+
+</div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="appendices.html">Prev</a>�</td><td width="20%" align="center"><a accesskey="u" href="appendices.html">Up</a></td><td width="40%" align="right">�<a accesskey="n" href="protocol-reference.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part�III.�Appendices�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�Appendix�B.�Guacamole protocol reference</td></tr></table></div>
+
+ </div></div>
+
+
+<!-- Google Analytics -->
+<script type="text/javascript">
+ (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+ })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+
+ ga('create', 'UA-75289145-1', 'auto');
+ ga('send', 'pageview');
+
+</script>
+<!-- End Google Analytics -->
+ </body></html>
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/af9b9c05/content/doc/0.8.3/gug/guacamole-architecture.html
----------------------------------------------------------------------
diff --git a/content/doc/0.8.3/gug/guacamole-architecture.html b/content/doc/0.8.3/gug/guacamole-architecture.html
new file mode 100644
index 0000000..cfe9489
--- /dev/null
+++ b/content/doc/0.8.3/gug/guacamole-architecture.html
@@ -0,0 +1,141 @@
+<?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�1.�Implementation and architecture</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="users-guide.html" title="Part�I.�User's Guide" /><link rel="next" href="installing-guacamole.html" title="Chapter�2.�Installing Guacamole" />
+ <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�1.�Implementation and architecture</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="users-guide.html">Prev</a>�</td><th width="60%" align="center">Part�I.�User's Guide</th><td width="20%" align="right">�<a accesskey="n" href="installing-guacamole.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" title="Chapter�1.�Implementation and architecture" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="guacamole-architecture"></a>Chapter�1.�Implementation and architecture</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="guacamole-architecture.html#guacamole-protocol-architecture">The Guacamole protocol </a></span></dt><dt><span class="section"><a href="guacamole-architecture.html#guacd">guacd</a></span></dt><dt><span class="sectio
n"><a href="guacamole-architecture.html#web-application">The web application</a></span></dt><dt><span class="section"><a href="guacamole-architecture.html#idp104768">RealMint</a></span></dt><dt><span class="section"><a href="guacamole-architecture.html#idp109168">VNC Client</a></span></dt><dt><span class="section"><a href="guacamole-architecture.html#idp112672">Remote Desktop Gateway</a></span></dt></dl></div>
+
+ <a id="idm5388560" class="indexterm"></a>
+ <a id="idm5390544" class="indexterm"></a>
+ <a id="idp85120" class="indexterm"></a>
+ <p>Guacamole is not a self-contained web application and is made up of many parts. The web
+ application is actually intended to be simple and minimal, with the majority of the
+ gruntwork performed by lower-level components.</p><div class="informalfigure">
+ <div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="225"><tr><td><img src="../images/guac-arch.png" width="225" /></td></tr></table></div>
+ </div>
+ <p>Users connect to a Guacamole server with their web browser. The Guacamole client, written
+ in JavaScript, is served to users by a webserver within the Guacamole server. Once loaded,
+ this client connects back to the server over HTTP using the Guacamole protocol.</p>
+ <p>The web application deployed to the Guacamole server reads the Guacamole protocol and
+ forwards it to guacd, the native Guacamole proxy. This proxy actually interprets the
+ contents of the Guacamole protocol, connecting to any number of remote desktop servers on
+ behalf of the user.</p>
+ <p>The Guacamole protocol combined with guacd provide protocol agnosticism: neither the
+ Guacamole client nor the web application need to be aware of what remote desktop protocol is
+ actually being used.</p>
+ <div class="section" title="The Guacamole protocol"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="guacamole-protocol-architecture"></a>The Guacamole protocol </h2></div></div></div>
+
+ <a id="idp90992" class="indexterm"></a>
+ <a id="idp91760" class="indexterm"></a>
+ <p>The web application does not understand any remote desktop protocol at all. It does
+ not contain support for VNC or RDP or any other protocol supported by the Guacamole
+ stack. It actually only understands the Guacamole protocol, which is a protocol for
+ remote display rendering and event transport. While a protocol with those properties
+ would naturally have the same abilities as a remote desktop protocol, the design
+ principles behind a remote desktop protocol and the Guacamole protocol are different:
+ the Guacamole protocol is not intended to implement the features of a specific desktop
+ environment.</p>
+ <p>As a remote display and interaction protocol, Guacamole implements a superset of
+ existing remote desktop protocols. Adding support for a particular remote desktop
+ protocol (like RDP) to Guacamole thus involves writing a middle layer which "translates"
+ between the remote desktop protocol and the Guacamole protocol. Implementing such a
+ translation is no different than implementing any native client, except that this
+ particular implementation renders to a remote display rather than a local one.</p>
+ <p>The middle layer that handles this translation is guacd.</p>
+ </div>
+ <div class="section" title="guacd"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="guacd"></a>guacd</h2></div></div></div>
+
+ <a id="idp95904" class="indexterm"></a>
+ <a id="idp96672" class="indexterm"></a>
+ <p>guacd is the heart of Guacamole which dynamically loads support for remote desktop
+ protocols (called "client plugins") and connects them to remote desktops based on
+ instructions received from the web application.</p>
+ <p>guacd is a daemon process which is installed along with Guacamole and runs in the
+ background, listening for TCP connections from the web application. guacd also does not
+ understand any specific remote desktop protocol, but rather implements just enough of
+ the Guacamole protocol to determine which protocol support needs to be loaded and what
+ arguments must be passed to it. Once a client plugin is loaded, it runs independently of
+ guacd and has full control of the communication between itself and the web application
+ until the client plugin terminates.</p>
+ <a id="idp99104" class="indexterm"></a>
+ <p>guacd and all client plugins depend on a common library, libguac, which makes
+ communication via the Guacamole protocol easier and a bit more abstract.</p>
+ </div>
+ <div class="section" title="The web application"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="web-application"></a>The web application</h2></div></div></div>
+
+ <a id="idp102256" class="indexterm"></a>
+ <p>The part of Guacamole that a user actually interacts with is the web
+ application.</p>
+ <p>The web application, as mentioned before, does not implement any remote desktop
+ protocol. It relies on guacd, and implements nothing more than a spiffy web interface
+ and authentication layer.</p>
+ <p>We chose to implement the server side of the web application in Java, but there's no
+ reason that it can't be written in a different language. In fact, because Guacamole is
+ intended be an API, we encourage this.</p>
+ </div>
+ <div class="section" title="RealMint"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idp104768"></a>RealMint</h2></div></div></div>
+
+ <a id="idp105584" class="indexterm"></a>
+ <p>Guacamole is now a generalized remote desktop gateway, but this was not always the
+ case. Guacamole began as a purely text-based Telnet client written in JavaScript called
+ <span class="application"><a class="application" href="http://sourceforge.net/projects/realmint" target="_top">RealMint</a></span> ("RealMint" is an anagram for "terminal"). It was written
+ mainly as a demonstration and, while intended to be useful, its main claim to fame was
+ only that it was pure JavaScript.</p>
+ <p>The tunnel used by RealMint was written in PHP. In contrast to Guacamole's HTTP
+ tunnel, RealMint's tunnel used only simple long-polling and was inefficient. RealMint
+ had a decent keyboard implementation which lives on now in parts of Guacamole's keyboard
+ code, but this was really the extent of RealMint's features and usability.</p>
+ <p>Given that it was just an implementation of a legacy protocol, and that several other
+ JavaScript terminal emulators exist, most of which well-established and stable, the
+ project was dropped.</p>
+ </div>
+ <div class="section" title="VNC Client"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idp109168"></a>VNC Client</h2></div></div></div>
+
+ <p>Once the developers learned of the HTML5 canvas tag, and saw that it was already
+ implemented in Firefox and Chrome, work started instead on a proof-of-concept JavaScript
+ VNC client.</p>
+ <p>This client was purely JavaScript with a Java server component, and worked by
+ translating VNC into an XML-based version of the same. Its development was naturally
+ driven by VNC's features, and its scope was limited to forwarding a single connection to
+ a set of users. Although relatively slow, the proof-of-concept worked well enough that
+ the project needed an online place to live, and was registered with SourceForge as
+ "Guacamole" - an HTML5 VNC client.</p>
+ <p>As Guacamole grew and became more than a proof-of-concept, the need for speed
+ increased, and the old RealMint-style long polling was dropped, as was the use of
+ XML.</p>
+ <p>As WebSocket could not be trusted to be supported at the time, and Java had no
+ WebSocket standard for servlets, an equivalent HTTP-based tunnel was developed.</p>
+ </div>
+ <div class="section" title="Remote Desktop Gateway"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idp112672"></a>Remote Desktop Gateway</h2></div></div></div>
+
+ <p>A faster text-based protocol was developed which could present the features of
+ multiple remote desktop protocols, not just VNC. The entire system was rearchitected
+ into a standard daemon, guacd, and a common library, libguac, which drove both the
+ daemon and protocol support, which became extendable.</p>
+ <p>The scope of the project expanded from an adequate VNC client to a performant HTML5
+ remote desktop gateway and general API. In its current state, Guacamole can be used as a
+ central gateway to access any number of machines running different remote desktop
+ servers. It provides extendable authentication, and in the case you need something more
+ specialized, a general API for HTML5-based remote access.</p>
+ </div>
+</div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="users-guide.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="installing-guacamole.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part�I.�User's Guide�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�Chapter�2.�Installing Guacamole</td></tr></table></div>
+
+ </div></div>
+
+
+<!-- Google Analytics -->
+<script type="text/javascript">
+ (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+ })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+
+ ga('create', 'UA-75289145-1', 'auto');
+ ga('send', 'pageview');
+
+</script>
+<!-- End Google Analytics -->
+ </body></html>