| <?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 Vsnapshot" /><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 natively" /> |
| <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" 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 class="toc"><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="section"><a href="guacamole-architecture.html#web-application">The web application</a></span></dt><dt><span class="section"><a href="guacamole-architecture.html#realmint">RealMint</a></span></dt><dt><span class="section"><a href="guacamole-architecture.html#vnc-client">VNC Client</a></span></dt><dt><span class="section"><a href="guacamole-architecture.html#gateway">Remote Desktop Gateway</a></span></dt></dl></div><a id="idm46420849713184" class="indexterm"></a><a id="idm46420849712288" class="indexterm"></a><a id="idm46420849711392" 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"><img src="images/guac-arch.png" width="225" /></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"><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="idm46420849615680" class="indexterm"></a><a id="idm46420849614784" 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"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="guacd"></a>guacd</h2></div></div></div><a id="idm46420849706560" class="indexterm"></a><a id="idm46420849705664" 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="idm46420849703680" 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"><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="idm46420849700240" 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"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="realmint"></a>RealMint</h2></div></div></div><a id="idm46420849696240" 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"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="vnc-client"></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. This |
| tunnel is still used today if WebSocket cannot be used for any reason.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="gateway"></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 natively</td></tr></table></div> |
| |
| </div></div> |
| </body></html> |
