doc/1.4.0/gug/guacamole-architecture.html

<!DOCTYPE html> <html class="writer-html5" lang="en" > <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Implementation and architecture — Apache Guacamole Manual v1.4.0</title> <link rel="stylesheet" href="_static/css/theme.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <link rel="stylesheet" href="_static/css/theme.css" type="text/css" /> <link rel="stylesheet" href="_static/tabs.css" type="text/css" /> <link rel="stylesheet" href="_static/gug.css" type="text/css" />  <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script> <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script src="_static/jquery.js"></script> <script src="_static/underscore.js"></script> <script src="_static/doctools.js"></script> <script src="_static/tabs.js"></script> <script type="text/javascript" src="_static/js/theme.js"></script> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="Installing Guacamole natively" href="installing-guacamole.html" /> <link rel="prev" title="Introduction" href="introduction.html" /> </head> <body class="wy-body-for-nav"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search" > <a href="index.html" class="icon icon-home"> Apache Guacamole </a> <div class="version"> 1.4.0 </div> <div role="search"> <form id="rtd-search-form" class="wy-form" action="search.html" method="get"> <input type="text" name="q" placeholder="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div> <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation"> <p class="caption" role="heading"><span class="caption-text">Overview</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">User's Guide</span></p> <ul class="current"> <li class="toctree-l1 current"><a class="current reference internal" href="#">Implementation and architecture</a><ul> <li class="toctree-l2"><a class="reference internal" href="#the-guacamole-protocol">The Guacamole protocol</a></li> <li class="toctree-l2"><a class="reference internal" href="#guacd">guacd</a></li> <li class="toctree-l2"><a class="reference internal" href="#the-web-application">The web application</a></li> <li class="toctree-l2"><a class="reference internal" href="#realmint">RealMint</a></li> <li class="toctree-l2"><a class="reference internal" href="#vnc-client">VNC Client</a></li> <li class="toctree-l2"><a class="reference internal" href="#remote-desktop-gateway">Remote Desktop Gateway</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="installing-guacamole.html">Installing Guacamole natively</a></li> <li class="toctree-l1"><a class="reference internal" href="guacamole-docker.html">Installing Guacamole with Docker</a></li> <li class="toctree-l1"><a class="reference internal" href="reverse-proxy.html">Proxying Guacamole</a></li> <li class="toctree-l1"><a class="reference internal" href="configuring-guacamole.html">Configuring Guacamole</a></li> <li class="toctree-l1"><a class="reference internal" href="jdbc-auth.html">Database authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="ldap-auth.html">LDAP authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="duo-auth.html">Duo two-factor authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="totp-auth.html">TOTP two-factor authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="header-auth.html">HTTP header authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="json-auth.html">Encrypted JSON authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="cas-auth.html">CAS Authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="openid-auth.html">OpenID Connect Authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="saml-auth.html">SAML Authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="radius-auth.html">RADIUS Authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="adhoc-connections.html">Ad-hoc Connections</a></li> <li class="toctree-l1"><a class="reference internal" href="using-guacamole.html">Using Guacamole</a></li> <li class="toctree-l1"><a class="reference internal" href="administration.html">Administration</a></li> <li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Developer's Guide</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="guacamole-protocol.html">The Guacamole protocol</a></li> <li class="toctree-l1"><a class="reference internal" href="libguac.html">libguac</a></li> <li class="toctree-l1"><a class="reference internal" href="guacamole-common.html">guacamole-common</a></li> <li class="toctree-l1"><a class="reference internal" href="guacamole-common-js.html">guacamole-common-js</a></li> <li class="toctree-l1"><a class="reference internal" href="guacamole-ext.html">guacamole-ext</a></li> <li class="toctree-l1"><a class="reference internal" href="custom-protocols.html">Adding new protocols</a></li> <li class="toctree-l1"><a class="reference internal" href="custom-auth.html">Custom authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="event-listeners.html">Event listeners</a></li> <li class="toctree-l1"><a class="reference internal" href="writing-you-own-guacamole-app.html">Writing your own Guacamole application</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Appendices</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="protocol-reference.html">Guacamole protocol reference</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> <nav class="wy-nav-top" aria-label="top navigation"> <i data-toggle="wy-nav-top" class="fa fa-bars"></i> <a href="index.html">Apache Guacamole</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="breadcrumbs navigation"> <ul class="wy-breadcrumbs"> <li><a href="index.html" class="icon icon-home"></a> »</li> <li>Implementation and architecture</li> <li class="wy-breadcrumbs-aside"> <a href="_sources/guacamole-architecture.md.txt" rel="nofollow"> View page source</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <div class="section" id="implementation-and-architecture"> <h1>Implementation and architecture<a class="headerlink" href="#implementation-and-architecture" title="Permalink to this headline">¶</a></h1> <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> <a class="reference internal image-reference" href="_images/guac-arch.png"><img alt="_images/guac-arch.png" src="_images/guac-arch.png" style="width: 2.5in;" /></a> <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" id="the-guacamole-protocol"> <span id="guacamole-protocol-architecture"></span><h2>The Guacamole protocol<a class="headerlink" href="#the-guacamole-protocol" title="Permalink to this headline">¶</a></h2> <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" id="guacd"> <h2>guacd<a class="headerlink" href="#guacd" title="Permalink to this headline">¶</a></h2> <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> <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" id="the-web-application"> <span id="web-application"></span><h2>The web application<a class="headerlink" href="#the-web-application" title="Permalink to this headline">¶</a></h2> <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" id="realmint"> <h2>RealMint<a class="headerlink" href="#realmint" title="Permalink to this headline">¶</a></h2> <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 RealMint (“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" id="vnc-client"> <h2>VNC Client<a class="headerlink" href="#vnc-client" title="Permalink to this headline">¶</a></h2> <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" id="remote-desktop-gateway"> <span id="gateway"></span><h2>Remote Desktop Gateway<a class="headerlink" href="#remote-desktop-gateway" title="Permalink to this headline">¶</a></h2> <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> </div> <footer> <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation"> <a href="installing-guacamole.html" class="btn btn-neutral float-right" title="Installing Guacamole natively" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> <a href="introduction.html" class="btn btn-neutral float-left" title="Introduction" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> </div> <hr/> <div role="contentinfo"> <p>Copyright © 2021 <a href="http://www.apache.org/">The Apache Software Foundation</a>, Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>. Apache Guacamole, Guacamole, Apache, the Apache feather logo, and the Apache Guacamole project logo are trademarks of The Apache Software Foundation.</p> </div> Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. </footer> </div> </div> </section> </div> <script type="text/javascript"> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>

doc/1.4.0/gug/guacamole-architecture.html (255 lines of code) (raw):