<?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="idm46227498194112" class="indexterm"></a><a id="idm46227498193216" class="indexterm"></a><a id="idm46227498192320" 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="idm46227498100096" class="indexterm"></a><a id="idm46227498099200" 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="idm46227498186960" class="indexterm"></a><a id="idm46227498186064" 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="idm46227498184336" 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="idm46227498180896" 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="idm46227498176896" 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>
        <!-- Google Analytics -->
        <script type="text/javascript">
          (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
          (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
          m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
          })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

          ga('create', 'UA-75289145-1', 'auto');
          ga('send', 'pageview');
        </script>
        </body></html>