doc/gug/guacamole-protocol.html

<!DOCTYPE html> <html class="writer-html5" lang="en" > <head> <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>The Guacamole protocol — Apache Guacamole Manual v1.5.5</title> <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 src="_static/jquery.js?v=5d32c60e"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="_static/documentation_options.js?v=5929fcd5"></script> <script src="_static/doctools.js?v=888ff710"></script> <script src="_static/sphinx_highlight.js?v=dc90522c"></script> <script src="_static/tabs.js?v=3ee01567"></script> <script 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="libguac" href="libguac.html" /> <link rel="prev" title="Troubleshooting" href="troubleshooting.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.5.5 </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" aria-label="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="Navigation menu"> <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> <li class="toctree-l1"><a class="reference internal" href="guacamole-architecture.html">Implementation and architecture</a></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="vault.html">Retrieving secrets from a vault</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="recording-playback.html">Viewing session recordings in-browser</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 class="current"> <li class="toctree-l1 current"><a class="current reference internal" href="#">The Guacamole protocol</a><ul> <li class="toctree-l2"><a class="reference internal" href="#design">Design</a></li> <li class="toctree-l2"><a class="reference internal" href="#handshake-phase">Handshake phase</a><ul> <li class="toctree-l3"><a class="reference internal" href="#joining-an-existing-connection">Joining an existing connection</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#drawing">Drawing</a><ul> <li class="toctree-l3"><a class="reference internal" href="#compositing">Compositing</a></li> <li class="toctree-l3"><a class="reference internal" href="#image-data">Image data</a></li> <li class="toctree-l3"><a class="reference internal" href="#copying-image-data-between-layers">Copying image data between layers</a></li> <li class="toctree-l3"><a class="reference internal" href="#graphical-primitives">Graphical primitives</a></li> <li class="toctree-l3"><a class="reference internal" href="#buffers-and-layers">Buffers and layers</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#streams-and-objects">Streams and objects</a></li> <li class="toctree-l2"><a class="reference internal" href="#events">Events</a></li> <li class="toctree-l2"><a class="reference internal" href="#disconnecting">Disconnecting</a></li> </ul> </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="Mobile navigation menu" > <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="Page navigation"> <ul class="wy-breadcrumbs"> <li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li> <li class="breadcrumb-item active">The Guacamole protocol</li> <li class="wy-breadcrumbs-aside"> <a href="_sources/guacamole-protocol.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"> <section id="the-guacamole-protocol"> <h1>The Guacamole protocol<a class="headerlink" href="#the-guacamole-protocol" title="Link to this heading"></a></h1> <p>This chapter is an overview of the Guacamole protocol, describing its design and general use. While a few instructions and their syntax will be described here, this is not an exhaustive list of all available instructions. The intent is only to list the general types and usage. If you are looking for the syntax or purpose of a specific instruction, consult the protocol reference included with the appendices.</p> <section id="design"> <span id="guacamole-protocol-design"></span><h2>Design<a class="headerlink" href="#design" title="Link to this heading"></a></h2> <p>The Guacamole protocol consists of instructions. Each instruction is a comma-delimited list followed by a terminating semicolon, where the first element of the list is the instruction opcode, and all following elements are the arguments for that instruction:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>OPCODE,ARG1,ARG2,ARG3,...; </pre></div> </div> <p>Each element of the list has a positive decimal integer length prefix separated by the value of the element by a period. This length denotes the number of Unicode characters in the value of the element, which is encoded in UTF-8:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>LENGTH.VALUE </pre></div> </div> <p>Any number of complete instructions make up a message which is sent from client to server or from server to client. Client to server instructions are generally control instructions (for connecting or disconnecting) and events (mouse and keyboard). Server to client instructions are generally drawing instructions (caching, clipping, drawing images), using the client as a remote display.</p> <p>For example, a complete and valid instruction for setting the display size to 1024x768 would be:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>4.size,1.0,4.1024,3.768; </pre></div> </div> <p>Here, the instruction would be decoded into four elements: “size”, the opcode of the size instruction, “0”, the index of the default layer, “1024”, the desired width in pixels, and “768”, the desired height in pixels.</p> <p>The structure of the Guacamole protocol is important as it allows the protocol to be streamed while also being easily parsable by JavaScript. JavaScript does have native support for conceptually-similar structures like XML or JSON, but neither of those formats is natively supported in a way that can be streamed; JavaScript requires the entirety of the XML or JSON message to be available at the time of decoding. The Guacamole protocol, on the other hand, can be parsed as it is received, and the presence of length prefixes within each instruction element means that the parser can quickly skip around from instruction to instruction without having to iterate over every character.</p> </section> <section id="handshake-phase"> <span id="guacamole-protocol-handshake"></span><h2>Handshake phase<a class="headerlink" href="#handshake-phase" title="Link to this heading"></a></h2> <p>The handshake phase is the phase of the protocol entered immediately upon connection. It begins with a “select” instruction sent by the client which tells the server which protocol will be loaded:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>6.select,3.vnc; </pre></div> </div> <p>After receiving the “select” instruction, the server will load the associated client support and respond with its protocol version and a list of accepted parameter names using an “args” instruction:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>4.args,13.VERSION_1_1_0,8.hostname,4.port,8.password,13.swap-red-blue,9.read-only; </pre></div> </div> <p>The protocol version is used to negotiate compatibility between differing versions of client and server, allowing the two sides to negotiate the highest supported version and enable or disable features associated with that version. Older implementations of the Guacamole protocol that do not support version negotiation will silently ignore it as if it were an unspecified connection parameter.</p> <p>Valid protocol versions are as follows:</p> <dl class="simple myst"> <dt><code class="docutils literal notranslate"><span class="pre">VERSION_1_5_0</span></code></dt><dd><p>Protocol version 1.5.0 introduced two new instructions - the <code class="docutils literal notranslate"><span class="pre">msg</span></code> instruction, which is used to send arbitrary messages to the client, and the <code class="docutils literal notranslate"><span class="pre">name</span></code> handshake instruction, which allows the client to set the human-readable name of the user joining a connection.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">VERSION_1_3_0</span></code></dt><dd><p>Protocol version 1.3.0 introduced the <code class="docutils literal notranslate"><span class="pre">require</span></code> instruction, used by the server to indicate that the client must provide additional arguments (such as a username and password).</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">VERSION_1_1_0</span></code></dt><dd><p>Protocol version 1.1.0 introduced support for protocol version negotiation, arbitrary order of the handshake instructions, and support for passing the timezone instruction during the handshake.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">VERSION_1_0_0</span></code></dt><dd><p>This is the default version and applies to any versions prior to 1.1.0. Version 1.0.0 of the protocol does not support protocol negotiation, and requires that the handshake instructions are delivered in a certain order, and that they are present (even if empty).</p> </dd> </dl> <p>After receiving the list of arguments, the client is required to respond with the list of supported audio, video, and image mimetypes, the optimal display size and resolution, and the values for all arguments available, even if blank.</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>4.size,4.1024,3.768,2.96; 5.audio,9.audio/ogg; 5.video; 5.image,9.image/png,10.image/jpeg; 8.timezone,16.America/New_York; 7.connect,13.VERSION_1_1_0,9.localhost,4.5900,0.,0.,0.; </pre></div> </div> <p>For clarity, we’ve put each instruction on its own line, but in the real protocol, no newlines exist between instructions. In fact, if there is anything after an instruction other than the start of a new instruction, the connection is closed.</p> <p>The following are valid instructions during the handshake:</p> <dl class="simple myst"> <dt><code class="docutils literal notranslate"><span class="pre">audio</span></code></dt><dd><p>The audio codec(s) supported by the client. In the example above the client is specifying audio/ogg as the supported codec.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">connect</span></code></dt><dd><p>This is the final instruction of the handshake, terminating the handshake and indicating that the connection should continue. This instruction has as its parameters values for the connection parameters sent by the server in the <code class="docutils literal notranslate"><span class="pre">args</span></code> instruction. In the example above, this is connection to localhost on port 5900, with no values for the last three connection parameters.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">image</span></code></dt><dd><p>The image formats that the client supports, in order of preference. The client in the example above is supporting both PNG and JPEG.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">name</span></code></dt><dd><p>The human-readable name of the user joining the connection.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">timezone</span></code></dt><dd><p>The timezone of the client, in IANA zone key format. More information on this instruction is available in <a class="reference internal" href="configuring-guacamole.html"><span class="doc std std-doc">Configuring Guacamole</span></a>, under documentation related to the <code class="docutils literal notranslate"><span class="pre">timezone</span></code> connection parameters for the protocols that support it.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">video</span></code></dt><dd><p>The video codec(s) supported by the client. The above example is a client that does not support any video codecs.</p> </dd> </dl> <p>The order of the instructions sent by the client in the handshake is arbitrary, with the exception that the final instruction, connect, will end the handshake and attempt to start the connection.</p> <p>Once these instructions have been sent by the client, the server will attempt to initialize the connection with the parameters received and, if successful, respond with a “ready” instruction. This instruction contains the ID of the new client connection and marks the beginning of the interactive phase. The ID is an arbitrary string, but is guaranteed to be unique from all other active connections, as well as from the names of all supported protocols:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>5.ready,37.$260d01da-779b-4ee9-afc1-c16bae885cc7; </pre></div> </div> <p>The actual interactive phase begins immediately after the “ready” instruction is sent. Drawing and event instructions pass back and forth until the connection is closed.</p> <section id="joining-an-existing-connection"> <span id="guacamole-protocol-joining"></span><h3>Joining an existing connection<a class="headerlink" href="#joining-an-existing-connection" title="Link to this heading"></a></h3> <p>Once the handshake phase has completed, that connection is considered active and can be joined by other connections if the ID is provided instead of a protocol name via the “select” instruction:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>6.select,37.$260d01da-779b-4ee9-afc1-c16bae885cc7; </pre></div> </div> <p>The rest of the handshake phase for a joining connection is identical. Just as with a new connection, the restrictions or features which apply to the joining connection are dictated by the parameter values supplied during the handshake.</p> </section> </section> <section id="drawing"> <span id="guacamole-protocol-drawing"></span><h2>Drawing<a class="headerlink" href="#drawing" title="Link to this heading"></a></h2> <section id="compositing"> <span id="guacamole-protocol-compositing"></span><h3>Compositing<a class="headerlink" href="#compositing" title="Link to this heading"></a></h3> <p>The Guacamole protocol provides compositing operations through the use of “channel masks”. The term “channel mask” is simply a description of the mechanism used while designing the protocol to conceptualize and fully enumerate all possible compositing operations based on four different sources of image data: source image data where the destination is opaque, source image data where the destination is transparent, destination image data where the source is opaque, and destination image data where the source is transparent. Assigning a binary value to each of these “channels” creates a unique integer ID for every possible compositing operation, where these operations parallel the operations described by Porter and Duff in their paper. As the HTML5 canvas tag also uses Porter/Duff to describe their compositing operations (as do other graphical APIs), the Guacamole protocol is conveniently similar to the compositing support already present in web browsers, with some operations not yet supported. The following operations are all implemented and known to work correctly in all browsers:</p> <dl class="simple myst"> <dt>B out A (0x02)</dt><dd><p>Clears the destination where the source is opaque, but otherwise draws nothing. This is useful for masking.</p> </dd> <dt>A atop B (0x06)</dt><dd><p>Fills with the source where the destination is opaque only.</p> </dd> <dt>A xor B (0x0A)</dt><dd><p>As with logical XOR. Note that this is a compositing operation, not a bitwise operation. It draws the source where the destination is transparent, and draws the destination where the source is transparent.</p> </dd> <dt>B over A (0x0B)</dt><dd><p>What you would typically expect when drawing, but reversed. The source appears only where the destination is transparent, as if you were attempting to draw the destination over the source, rather than the source over the destination.</p> </dd> <dt>A over B (0x0E)</dt><dd><p>The most common and sensible compositing operation, this draws the source everywhere, but includes the destination where the source is transparent.</p> </dd> <dt>A + B (0x0F)</dt><dd><p>Simply adds the components of the source image to the destination image, capping the result at pure white.</p> </dd> </dl> <p>The following operations are all implemented, but may work incorrectly in WebKit browsers which always include the destination image where the source is transparent:</p> <dl class="simple myst"> <dt>B in A (0x01)</dt><dd><p>Draws the destination only where the source is opaque, clearing anywhere the source or destination are transparent.</p> </dd> <dt>A in B (0x04)</dt><dd><p>Draws the source only where the destination is opaque, clearing anywhere the source or destination are transparent.</p> </dd> <dt>A out B (0x08)</dt><dd><p>Draws the source only where the destination is transparent, clearing anywhere the source or destination are opaque.</p> </dd> <dt>B atop A (0x09)</dt><dd><p>Fills with the destination where the source is opaque only.</p> </dd> <dt>A (0x0C)</dt><dd><p>Fills with the source, ignoring the destination entirely.</p> </dd> </dl> <p>The following operations are defined, but not implemented, and do not exist as operations within the HTML5 canvas:</p> <dl class="simple myst"> <dt>Clear (0x00)</dt><dd><p>Clears all existing image data in the destination.</p> </dd> <dt>B (0x03)</dt><dd><p>Does nothing.</p> </dd> <dt>A xnor B (0x05)</dt><dd><p>Adds the source to the destination where the destination or source are opaque, clearing anywhere the source or destination are transparent. This is similar to A + B except the aspect of transparency is also additive.</p> </dd> <dt>(A + B) atop B (0x07)</dt><dd><p>Adds the source to the destination where the destination is opaque, preserving the destination otherwise.</p> </dd> <dt>(A + B) atop A (0x0D)</dt><dd><p>Adds the destination to the source where the source is opaque, copying the source otherwise.</p> </dd> </dl> </section> <section id="image-data"> <span id="guacamole-protocol-images"></span><h3>Image data<a class="headerlink" href="#image-data" title="Link to this heading"></a></h3> <p>The Guacamole protocol, like many remote desktop protocols, provides a method of sending an arbitrary rectangle of image data and placing it either within a buffer or in a visible rectangle of the screen. Raw image data in the Guacamole protocol is streamed as PNG, JPEG, or WebP data over a stream allocated with the “img” instruction. Depending on the format used, image updates sent in this manner can be RGB or RGBA (alpha transparency) and are automatically palettized if sent using libguac. The streaming system used for image data is generalized and used by Guacamole for other types of streams, including audio and file transfer. For more information about streams in the Guacamole protocol, see <a class="reference internal" href="#guacamole-protocol-streaming"><span class="std std-ref">Streams and objects</span></a>.</p> <p>Image data can be sent to any specified rectangle within a layer or buffer. Sending the data to a layer means that the image becomes immediately visible, while sending the data to a buffer allows that data to be reused later.</p> </section> <section id="copying-image-data-between-layers"> <span id="guacamole-protocol-copying-images"></span><h3>Copying image data between layers<a class="headerlink" href="#copying-image-data-between-layers" title="Link to this heading"></a></h3> <p>Image data can be copied from one layer or buffer into another layer or buffer. This is often used for scrolling (where most of the result of the graphical update is identical to the previous state) or for caching parts of an image.</p> <p>Both VNC and RDP provide a means of copying a region of screen data and placing it somewhere else within the same screen. RDP provides an additional means of copying data to a cache, or recalling data from that cache and placing it on the screen. Guacamole takes this concept and reduces it further, as both on-screen and off-screen image storage is the same. The Guacamole “copy” instruction allows you to copy a rectangle of image data, and place it within another layer, whether that layer is the same as the source layer, a different visible layer, or an off-screen buffer.</p> </section> <section id="graphical-primitives"> <span id="guacamole-graphical-primitives"></span><h3>Graphical primitives<a class="headerlink" href="#graphical-primitives" title="Link to this heading"></a></h3> <p>The Guacamole protocol provides basic graphics operations similar to those of Cairo or the HTML5 canvas. In many cases, these primitives are useful for remote drawing, and desirable in that they take up less bandwidth than sending corresponding PNG images. Beware that excessive use of primitives leads to an increase in client-side processing, which may reduce the performance of a connected client, especially if that client is on a lower-performance machine like a mobile phone or tablet.</p> </section> <section id="buffers-and-layers"> <span id="guacamole-protocol-layers"></span><h3>Buffers and layers<a class="headerlink" href="#buffers-and-layers" title="Link to this heading"></a></h3> <p>All drawing operations in the Guacamole protocol affect a layer, and each layer has an integer index which identifies it. When this integer is negative, the layer is not visible, and can be used for storage or caching of image data. In this case, the layer is referred to within the code and within documentation as a “buffer”. Layers are created automatically when they are first referenced in an instruction.</p> <p>There is one main layer which is always present called the “default layer”. This layer has an index of 0. Resizing this layer resizes the entire remote display. Other layers default to the size of the default layer upon creation, while buffers are always created with a size of 0x0, automatically resizing themselves to fit their contents.</p> <p>Non-buffer layers can be moved and nested within each other. In this way, layers provide a simple means of hardware-accelerated compositing. If you need a window to appear above others, or you have some object which will be moving or you need the data beneath it automatically preserved, a layer is a good way of accomplishing this. If a layer is nested within another layer, its position is relative to that of its parent. When the parent is moved or reordered, the child moves with it. If the child extends beyond the parents bounds, it will be clipped.</p> </section> </section> <section id="streams-and-objects"> <span id="guacamole-protocol-streaming"></span><h2>Streams and objects<a class="headerlink" href="#streams-and-objects" title="Link to this heading"></a></h2> <p>Guacamole supports transfer of clipboard contents, audio, video, and image data, as well as files and arbitrary named pipes.</p> <p>Streams are allocated directly with instructions that associate the new stream with particular semantics and metadata, such as the “audio” or “video” instructions used for playing media, the “file” instruction used for file transfer, and the “pipe” instruction for transfer of completely arbitrary data between client and server. In some cases, the availability and semantics of streams may be explicitly advertised using structured sets of named streams known as “objects”.</p> <p>Once a stream is allocated, data is sent along the stream in chunks using “blob” instructions, which may be acknowledged by the receiving end by “ack” instructions. The end of the stream is finally signalled with an “end” instruction.</p> </section> <section id="events"> <span id="guacamole-protocol-events"></span><h2>Events<a class="headerlink" href="#events" title="Link to this heading"></a></h2> <p>When something changes on either side, client or server, such as a key being pressed, the mouse moving, or clipboard data changing, an instruction describing the event is sent.</p> </section> <section id="disconnecting"> <span id="guacamole-protocol-disconnecting"></span><h2>Disconnecting<a class="headerlink" href="#disconnecting" title="Link to this heading"></a></h2> <p>The server and client can end the connection at any time. There is no requirement for the server or the client to communicate that the connection needs to terminate. When the client or server wish to end the connection, and the reason is known, they can use the “disconnect” or “error” instructions.</p> <p>The disconnect instruction is sent by the client when it is disconnecting. This is largely out of politeness, and the server must be written knowing that the disconnect instruction may not always be sent in time (guacd is written this way).</p> <p>If the client does something wrong, or the server detects a problem with the client plugin, the server sends an error instruction, including a description of the problem in the parameters. This informs the client that the connection is being closed.</p> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="troubleshooting.html" class="btn btn-neutral float-left" title="Troubleshooting" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> <a href="libguac.html" class="btn btn-neutral float-right" title="libguac" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> </div> <hr/> <div role="contentinfo"> <p>Copyright © 2024 <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> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>

doc/gug/guacamole-protocol.html (487 lines of code) (raw):