doc/1.5.5/gug/configuring-guacamole.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>Configuring Guacamole — 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="Database authentication" href="jdbc-auth.html" /> <link rel="prev" title="Proxying Guacamole" href="reverse-proxy.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"> Overview <ul> <li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction</a></li> </ul> User's Guide <ul class="current"> <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 current"><a class="current reference internal" href="#">Configuring Guacamole</a><ul> <li class="toctree-l2"><a class="reference internal" href="#guacamole-home-etc-guacamole"><code class="docutils literal notranslate">GUACAMOLE_HOME</code> (<code class="docutils literal notranslate">/etc/guacamole</code>)</a><ul> <li class="toctree-l3"><a class="reference internal" href="#overriding-guacamole-home">Overriding <code class="docutils literal notranslate">GUACAMOLE_HOME</code></a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#guacamole-properties"><code class="docutils literal notranslate">guacamole.properties</code></a></li> <li class="toctree-l2"><a class="reference internal" href="#logging-within-the-web-application">Logging within the web application</a></li> <li class="toctree-l2"><a class="reference internal" href="#using-the-default-authentication">Using the default authentication</a><ul> <li class="toctree-l3"><a class="reference internal" href="#user-mapping-xml"><code class="docutils literal notranslate">user-mapping.xml</code></a><ul> <li class="toctree-l4"><a class="reference internal" href="#adding-users">Adding users</a></li> <li class="toctree-l4"><a class="reference internal" href="#adding-connections-to-a-user">Adding connections to a user</a></li> </ul> </li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#configuring-connections">Configuring connections</a><ul> <li class="toctree-l3"><a class="reference internal" href="#vnc">VNC</a><ul> <li class="toctree-l4"><a class="reference internal" href="#network-parameters">Network parameters</a></li> <li class="toctree-l4"><a class="reference internal" href="#authentication">Authentication</a></li> <li class="toctree-l4"><a class="reference internal" href="#display-settings">Display settings</a></li> <li class="toctree-l4"><a class="reference internal" href="#vnc-repeater">VNC Repeater</a></li> <li class="toctree-l4"><a class="reference internal" href="#reverse-vnc-connections">Reverse VNC connections</a></li> <li class="toctree-l4"><a class="reference internal" href="#audio-support-via-pulseaudio">Audio support (via PulseAudio)</a></li> <li class="toctree-l4"><a class="reference internal" href="#clipboard-encoding">Clipboard encoding</a></li> <li class="toctree-l4"><a class="reference internal" href="#adding-a-vnc-connection">Adding a VNC connection</a></li> <li class="toctree-l4"><a class="reference internal" href="#which-vnc-server">Which VNC server?</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#rdp">RDP</a><ul> <li class="toctree-l4"><a class="reference internal" href="#rdp-network-parameters">Network parameters</a></li> <li class="toctree-l4"><a class="reference internal" href="#authentication-and-security">Authentication and security</a></li> <li class="toctree-l4"><a class="reference internal" href="#clipboard-normalization">Clipboard normalization</a></li> <li class="toctree-l4"><a class="reference internal" href="#session-settings">Session settings</a></li> <li class="toctree-l4"><a class="reference internal" href="#rdp-display-settings">Display settings</a></li> <li class="toctree-l4"><a class="reference internal" href="#device-redirection">Device redirection</a></li> <li class="toctree-l4"><a class="reference internal" href="#preconnection-pdu-hyper-v-vmconnect">Preconnection PDU (Hyper-V / VMConnect)</a></li> <li class="toctree-l4"><a class="reference internal" href="#remote-desktop-gateway">Remote desktop gateway</a></li> <li class="toctree-l4"><a class="reference internal" href="#load-balancing-and-rdp-connection-brokers">Load balancing and RDP connection brokers</a></li> <li class="toctree-l4"><a class="reference internal" href="#performance-flags">Performance flags</a></li> <li class="toctree-l4"><a class="reference internal" href="#remoteapp">RemoteApp</a></li> <li class="toctree-l4"><a class="reference internal" href="#adding-an-rdp-connection">Adding an RDP connection</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#ssh">SSH</a><ul> <li class="toctree-l4"><a class="reference internal" href="#ssh-host-verification">SSH Host Verification</a></li> <li class="toctree-l4"><a class="reference internal" href="#ssh-network-parameters">Network parameters</a></li> <li class="toctree-l4"><a class="reference internal" href="#ssh-authentication">Authentication</a></li> <li class="toctree-l4"><a class="reference internal" href="#running-a-command-instead-of-a-shell">Running a command (instead of a shell)</a></li> <li class="toctree-l4"><a class="reference internal" href="#internationalization-locale-settings">Internationalization/Locale settings</a></li> <li class="toctree-l4"><a class="reference internal" href="#sftp">SFTP</a></li> <li class="toctree-l4"><a class="reference internal" href="#adding-an-ssh-connection">Adding an SSH connection</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#telnet">Telnet</a><ul> <li class="toctree-l4"><a class="reference internal" href="#telnet-network-parameters">Network parameters</a></li> <li class="toctree-l4"><a class="reference internal" href="#telnet-authentication">Authentication</a></li> <li class="toctree-l4"><a class="reference internal" href="#adding-a-telnet-connection">Adding a telnet connection</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#kubernetes">Kubernetes</a><ul> <li class="toctree-l4"><a class="reference internal" href="#network-container-parameters">Network/Container parameters</a></li> <li class="toctree-l4"><a class="reference internal" href="#authentication-and-ssl-tls">Authentication and SSL/TLS</a></li> <li class="toctree-l4"><a class="reference internal" href="#adding-a-kubernetes-connection">Adding a Kubernetes connection</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#common-configuration-options">Common configuration options</a><ul> <li class="toctree-l4"><a class="reference internal" href="#disabling-clipboard-access">Disabling clipboard access</a></li> <li class="toctree-l4"><a class="reference internal" href="#file-transfer-via-sftp">File transfer via SFTP</a></li> <li class="toctree-l4"><a class="reference internal" href="#graphical-session-recording">Graphical session recording</a></li> <li class="toctree-l4"><a class="reference internal" href="#text-session-recording-typescripts">Text session recording (typescripts)</a></li> <li class="toctree-l4"><a class="reference internal" href="#controlling-terminal-behavior">Controlling terminal behavior</a></li> <li class="toctree-l4"><a class="reference internal" href="#terminal-display-settings">Terminal display settings</a></li> <li class="toctree-l4"><a class="reference internal" href="#wake-on-lan">Wake-on-LAN</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#parameter-tokens">Parameter tokens</a><ul> <li class="toctree-l4"><a class="reference internal" href="#token-modifiers">Token modifiers</a></li> <li class="toctree-l4"><a class="reference internal" href="#extension-specific-tokens">Extension-specific tokens</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#parameter-prompting">Parameter prompting</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#configuring-guacd">Configuring guacd</a><ul> <li class="toctree-l3"><a class="reference internal" href="#id12"><code class="docutils literal notranslate">guacd.conf</code></a><ul> <li class="toctree-l4"><a class="reference internal" href="#daemon-section"><code class="docutils literal notranslate">[daemon]</code> section</a></li> <li class="toctree-l4"><a class="reference internal" href="#server-section"><code class="docutils literal notranslate">[server]</code> section</a></li> <li class="toctree-l4"><a class="reference internal" href="#ssl-section"><code class="docutils literal notranslate">[ssl]</code> section</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#command-line-options">Command-line options</a></li> </ul> </li> </ul> </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> Developer's Guide <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> Appendices <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" > <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">Configuring Guacamole</li> <li class="wy-breadcrumbs-aside"> <a href="_sources/configuring-guacamole.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="configuring-guacamole"> <h1>Configuring Guacamole<a class="headerlink" href="#configuring-guacamole" title="Link to this heading"></a></h1> After installing Guacamole, you need to configure users and connections before Guacamole will work. This chapter covers general configuration of Guacamole and the use of its default authentication method. Guacamole’s default authentication method reads all users and connections from a single file called <code class="docutils literal notranslate">user-mapping.xml</code>. This authentication method is intended to be: <ol class="arabic simple"> <li>Sufficient for small deployments of Guacamole.</li> <li>A relatively-easy means of verifying that Guacamole has been properly set up.</li> </ol> Other, more complex authentication methods which use backend databases, LDAP, etc. are discussed in a separate, dedicated chapters. Regardless of the authentication method you use, Guacamole’s configuration always consists of two main pieces: a directory referred to as <code class="docutils literal notranslate">GUACAMOLE_HOME</code>, which is the primary search location for configuration files, and <code class="docutils literal notranslate">guacamole.properties</code>, the main configuration file used by Guacamole and its extensions. <section id="guacamole-home-etc-guacamole"> <h2><code class="docutils literal notranslate">GUACAMOLE_HOME</code> (<code class="docutils literal notranslate">/etc/guacamole</code>)<a class="headerlink" href="#guacamole-home-etc-guacamole" title="Link to this heading"></a></h2> <code class="docutils literal notranslate">GUACAMOLE_HOME</code> is the name given to Guacamole’s configuration directory, which is located at <code class="docutils literal notranslate">/etc/guacamole</code> by default. All configuration files, extensions, etc. reside within this directory. The structure of <code class="docutils literal notranslate">GUACAMOLE_HOME</code> is rigorously defined, and consists of the following optional files: <dl class="simple myst"> <dt><code class="docutils literal notranslate">guacamole.properties</code></dt><dd>The main Guacamole configuration file. Properties within this file dictate how Guacamole will connect to guacd, and may configure the behavior of installed authentication extensions. </dd> <dt><code class="docutils literal notranslate">logback.xml</code></dt><dd>Guacamole uses a logging system called Logback for all messages. By default, Guacamole will log to the console only, but you can change this by providing your own Logback configuration file. </dd> <dt><code class="docutils literal notranslate">extensions/</code></dt><dd>The install location for all Guacamole extensions. Guacamole will automatically load all <code class="docutils literal notranslate">.jar</code> files within this directory on startup. </dd> <dt><code class="docutils literal notranslate">lib/</code></dt><dd>The search directory for libraries required by any Guacamole extensions. Guacamole will make the <code class="docutils literal notranslate">.jar</code> files within this directory available to all extensions. If your extensions require additional libraries, such as database drivers, this is the proper place to put them. </dd> </dl> <section id="overriding-guacamole-home"> <h3>Overriding <code class="docutils literal notranslate">GUACAMOLE_HOME</code><a class="headerlink" href="#overriding-guacamole-home" title="Link to this heading"></a></h3> If you cannot or do not wish to use <code class="docutils literal notranslate">/etc/guacamole</code> for <code class="docutils literal notranslate">GUACAMOLE_HOME</code>, the location can be overridden through any of the following methods: <ol class="arabic simple"> <li>Creating a directory named <code class="docutils literal notranslate">.guacamole</code>, within the home directory of the user running the servlet container. This directory will automatically be used for <code class="docutils literal notranslate">GUACAMOLE_HOME</code> if it exists.</li> <li>Specifying the full path to an alternative directory with the environment variable <code class="docutils literal notranslate">GUACAMOLE_HOME</code>. Be sure to consult the documentation for your servlet container to determine how to properly set environment variables.</li> <li>Specifying the full path to an alternative directory with the system property guacamole.home.</li> </ol> </section> </section> <section id="guacamole-properties"> <h2><code class="docutils literal notranslate">guacamole.properties</code><a class="headerlink" href="#guacamole-properties" title="Link to this heading"></a></h2> The Guacamole web application uses one main configuration file called <code class="docutils literal notranslate">guacamole.properties</code>. This file is the common location for all configuration properties read by Guacamole or any extension of Guacamole, including authentication providers. In previous releases, this file had to be in the classpath of your servlet container. Now, the location of <code class="docutils literal notranslate">guacamole.properties</code> can be explicitly defined with environment variables or system properties, and the classpath is only used as a last resort. When searching for <code class="docutils literal notranslate">guacamole.properties</code>, Guacamole will check, in order: <ol class="arabic simple"> <li>Within <code class="docutils literal notranslate">GUACAMOLE_HOME</code>, as defined above.</li> <li>The classpath of the servlet container.</li> </ol> The <code class="docutils literal notranslate">guacamole.properties</code> file is optional and is used to configure Guacamole in situations where the defaults are insufficient, or to provide additional configuration information for extensions. There are several standard properties that are always available for use: <dl class="simple myst"> <dt><code class="docutils literal notranslate">api-session-timeout</code></dt><dd>The amount of time, in minutes, to allow Guacamole sessions (authentication tokens) to remain valid despite inactivity. If omitted, Guacamole sessions will expire after 60 minutes of inactivity. </dd> <dt><code class="docutils literal notranslate">api-max-request-size</code></dt><dd>The maximum number of bytes to accept within the entity body of any particular HTTP request, where 0 indicates that no limit should be applied. If omitted, requests will be limited to 2097152 bytes (2 MB) by default. This limit does not apply to file uploads. If using a reverse proxy for SSL termination, keep in mind that reverse proxies may enforce their own limits independently of this. For example, <a class="reference internal" href="reverse-proxy.html#nginx-file-upload-size">Nginx will enforce a 1 MB request size limit by default</a>. </dd> <dt><code class="docutils literal notranslate">allowed-languages</code></dt><dd>A comma-separated whitelist of language keys to allow as display language choices within the Guacamole interface. For example, to restrict Guacamole to only English and German, you would specify: <div class="highlight-none notranslate"><div class="highlight"><pre>allowed-languages: en, de </pre></div> </div> As English is the fallback language, used whenever a translation key is missing from the chosen language, English should only be omitted from this list if you are absolutely positive that no strings are missing. The corresponding JSON of any built-in languages not listed here will still be available over HTTP, but the Guacamole interface will not use them, nor will they be used automatically based on local browser language. If omitted, all defined languages will be available. </dd> <dt><code class="docutils literal notranslate">enable-environment-properties</code></dt><dd>If set to “true”, Guacamole will first evaluate its environment to obtain the value for any given configuration property, before using a value specified in <code class="docutils literal notranslate">guacamole.properties</code> or falling back to a default value. By enabling this option, you can easily override any other configuration property using an environment variable. <div class="highlight-none notranslate"><div class="highlight"><pre>enable-environment-properties: true </pre></div> </div> When searching for a configuration property in the environment, the name of the property is first transformed by converting all lower case characters to their upper case equivalents, and by replacing all hyphen characters (<code class="docutils literal notranslate">-</code>) with underscore characters (<code class="docutils literal notranslate">_</code>). For example, the <code class="docutils literal notranslate">guacd-hostname</code> property would be transformed to <code class="docutils literal notranslate">GUACD_HOSTNAME</code> when searching the environment. </dd> <dt><code class="docutils literal notranslate">extension-priority</code></dt><dd>A comma-separated list of the namespaces of all extensions that should be loaded in a specific order. The special value <code class="docutils literal notranslate">*</code> can be used in lieu of a namespace to represent all extensions that are not listed. All extensions explicitly listed will be sorted in the order given, while all extensions not explicitly listed will be sorted by their filenames. For example, to ensure support for SAML is loaded first: <div class="highlight-none notranslate"><div class="highlight"><pre>extension-priority: saml </pre></div> </div> Or to ensure support for SAML is loaded last: <div class="highlight-none notranslate"><div class="highlight"><pre>extension-priority: *, saml </pre></div> </div> If unsure which namespaces apply or the order that your extensions are loaded, check the Guacamole logs. The namespaces and load order of all installed extensions are logged by Guacamole during startup: <div class="highlight-none notranslate"><div class="highlight"><pre>... 23:32:06.467 [main] INFO o.a.g.extension.ExtensionModule - Multiple extensions are installed and will be loaded in order of decreasing priority: 23:32:06.468 [main] INFO o.a.g.extension.ExtensionModule - - [postgresql] "PostgreSQL Authentication" (/etc/guacamole/extensions/guacamole-auth-jdbc-postgresql-1.5.5.jar) 23:32:06.468 [main] INFO o.a.g.extension.ExtensionModule - - [ldap] "LDAP Authentication" (/etc/guacamole/extensions/guacamole-auth-ldap-1.5.5.jar) 23:32:06.468 [main] INFO o.a.g.extension.ExtensionModule - - [openid] "OpenID Authentication Extension" (/etc/guacamole/extensions/guacamole-auth-sso-openid-1.5.5.jar) 23:32:06.468 [main] INFO o.a.g.extension.ExtensionModule - - [saml] "SAML Authentication Extension" (/etc/guacamole/extensions/guacamole-auth-sso-saml-1.5.5.jar) 23:32:06.468 [main] INFO o.a.g.extension.ExtensionModule - To change this order, set the "extension-priority" property or rename the extension files. The default priority of extensions is dictated by the sort order of their filenames. ... </pre></div> </div> </dd> <dt><code class="docutils literal notranslate">guacd-hostname</code></dt><dd>The host the Guacamole proxy daemon (guacd) is listening on. If omitted, Guacamole will assume guacd is listening on localhost. </dd> <dt><code class="docutils literal notranslate">guacd-port</code></dt><dd>The port the Guacamole proxy daemon (guacd) is listening on. If omitted, Guacamole will assume guacd is listening on port 4822. </dd> <dt><code class="docutils literal notranslate">guacd-ssl</code></dt><dd>If set to “true”, Guacamole will require SSL/TLS encryption between the web application and guacd. By default, communication between the web application and guacd will be unencrypted. Note that if you enable this option, you must also configure guacd to use SSL via command line options. These options are documented in the manpage of guacd. You will need an SSL certificate and private key. </dd> <dt><code class="docutils literal notranslate">skip-if-unavailable</code></dt><dd>A comma-separated list of the identifiers of authentication providers that should be allowed to fail internally without aborting the authentication process. For example, to request that Guacamole ignore failures due to the LDAP directory or MySQL server being unexpectedly down, allowing other authentication providers to continue functioning: <div class="highlight-none notranslate"><div class="highlight"><pre>skip-if-unavailable: mysql, ldap </pre></div> </div> By default, Guacamole takes a conservative approach to internal failures, aborting the authentication process if an internal error occurs within any authentication provider. Depending on the nature of the error, this may mean that no users can log in until the cause of the failure is dealt with. The <code class="docutils literal notranslate">skip-if-unavailable</code> property may be used to explicitly inform Guacamole that one or more underlying systems are expected to occasionally experience failures, and that other functioning systems should be relied upon if they do fail. </dd> </dl> A typical <code class="docutils literal notranslate">guacamole.properties</code> that defines explicit values for the <code class="docutils literal notranslate">guacd-hostname</code> and <code class="docutils literal notranslate">guacd-port</code> properties would look like: <div class="highlight-none notranslate"><div class="highlight"><pre># Hostname and port of guacamole proxy guacd-hostname: localhost guacd-port: 4822 </pre></div> </div> </section> <section id="logging-within-the-web-application"> <h2>Logging within the web application<a class="headerlink" href="#logging-within-the-web-application" title="Link to this heading"></a></h2> By default, Guacamole logs all messages to the console. Servlet containers like Tomcat will automatically redirect these messages to a log file, <code class="docutils literal notranslate">catalina.out</code> in the case of Tomcat, which you can read through while Guacamole runs. Messages are logged at four different log levels, depending on message importance and severity: <dl class="simple myst"> <dt><code class="docutils literal notranslate">error</code></dt><dd>Errors are fatal conditions. An operation, described in the log message, was attempted but could not proceed, and the failure of this operation is a serious problem that needs to be addressed. </dd> <dt><code class="docutils literal notranslate">warn</code></dt><dd>Warnings are generally non-fatal conditions. The operation continued, but encountered noteworthy problems. </dd> <dt><code class="docutils literal notranslate">info</code></dt><dd>“Info” messages are purely informational. They may be useful or interesting to administrators, but are not generally critical to proper operation of a Guacamole server. </dd> <dt><code class="docutils literal notranslate">debug</code></dt><dd>Debug messages are highly detailed and oriented toward development. Most debug messages will contain stack traces and internal information that is useful when investigating problems within code. It is expected that debug messages, though verbose, will not affect performance. </dd> <dt><code class="docutils literal notranslate">trace</code></dt><dd>Trace messages are similar to debug messages in intent and verbosity, but are so low-level that they may affect performance due to their frequency. Trace-level logging is rarely necessary, and is mainly useful in providing highly detailed context around issues being investigated. </dd> </dl> Guacamole logs messages using a logging framework called <a class="reference external" href="http://logback.qos.ch/">Logback</a> and, by default, will only log messages at the “<code class="docutils literal notranslate">info</code>” level or higher. If you wish to change the log level, or configure how or where Guacamole logs messages, you can do so by providing your own <code class="docutils literal notranslate">logback.xml</code> file within <code class="docutils literal notranslate">GUACAMOLE_HOME</code>. For example, to log all messages to the console, even “<code class="docutils literal notranslate">debug</code>” messages, you might use the following <code class="docutils literal notranslate">logback.xml</code>: <div class="highlight-xml notranslate"><div class="highlight"><pre><configuration>  <appender name="GUAC-DEBUG" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> </encoder> </appender>  <root level="debug"> <appender-ref ref="GUAC-DEBUG"/> </root> </configuration> </pre></div> </div> Guacamole and the above example configure only one appender which logs to the console, but Logback is extremely flexible and allows any number of appenders which can each log to separate files, the console, etc. based on a number of criteria, including the log level and the source of the message. More thorough <a class="reference external" href="http://logback.qos.ch/manual/configuration.html">documentation on configuring Logback</a> is provided on the Logback project’s web site. </section> <section id="using-the-default-authentication"> <h2>Using the default authentication<a class="headerlink" href="#using-the-default-authentication" title="Link to this heading"></a></h2> Guacamole’s default authentication module is simple and consists of a mapping of usernames to configurations. This authentication module comes with Guacamole and simply reads usernames and passwords from an XML file. It is always enabled, but will only read from the XML file if it exists, and is always last in priority relative to any other authentication extensions. There are other authentication modules available. The Guacamole project provides database-backed authentication modules with the ability to manage connections and users from the web interface, and other authentication modules can be created using the extension API provided along with the Guacamole web application, guacamole-ext. <section id="user-mapping-xml"> <h3><code class="docutils literal notranslate">user-mapping.xml</code><a class="headerlink" href="#user-mapping-xml" title="Link to this heading"></a></h3> The default authentication provider used by Guacamole reads all username, password, and configuration information from a file called the “user mapping” located at <code class="docutils literal notranslate">GUACAMOLE_HOME/user-mapping.xml</code>. An example of a user mapping file is included with Guacamole, and looks something like this: <div class="highlight-xml notranslate"><div class="highlight"><pre><user-mapping>  <authorize username="USERNAME" password="PASSWORD"> <protocol>vnc</protocol> <param name="hostname">localhost</param> <param name="port">5900</param> <param name="password">VNCPASS</param> </authorize>  <authorize username="USERNAME2" password="319f4d26e3c536b5dd871bb2c52e3178" encoding="md5">  <connection name="localhost"> <protocol>vnc</protocol> <param name="hostname">localhost</param> <param name="port">5901</param> <param name="password">VNCPASS</param> </connection>  <connection name="otherhost"> <protocol>vnc</protocol> <param name="hostname">otherhost</param> <param name="port">5900</param> <param name="password">VNCPASS</param> </connection> </authorize> </user-mapping> </pre></div> </div> Each user is specified with a corresponding <code class="docutils literal notranslate"><authorize></code> tag. This tag contains all authorized connections for that user, each denoted with a <code class="docutils literal notranslate"><connection></code> tag. Each <code class="docutils literal notranslate"><connection></code> tag contains a corresponding protocol and set of protocol-specific parameters, specified with the <code class="docutils literal notranslate"><protocol></code> and <code class="docutils literal notranslate"><param></code> tags respectively. <section id="adding-users"> <h4>Adding users<a class="headerlink" href="#adding-users" title="Link to this heading"></a></h4> When using <code class="docutils literal notranslate">user-mapping.xml</code>, username/password pairs are specified with <code class="docutils literal notranslate"><authorize></code> tags, which each have a <code class="docutils literal notranslate">username</code> and <code class="docutils literal notranslate">password</code> attribute. Each <code class="docutils literal notranslate"><authorize></code> tag authorizes a specific username/password pair to access all connections within the tag: <div class="highlight-xml notranslate"><div class="highlight"><pre><authorize username="USER" password="PASS"> ... </authorize> </pre></div> </div> In the example above, the password would be listed in plaintext. If you don’t want to do this, you can also specify your password hashed with MD5: <div class="highlight-xml notranslate"><div class="highlight"><pre><authorize username="USER" password="319f4d26e3c536b5dd871bb2c52e3178" encoding="md5"> ... </authorize> </pre></div> </div> After modifying <code class="docutils literal notranslate">user-mapping.xml</code>, the file will be automatically reread by Guacamole, and your changes will take effect immediately. The newly-added user will be able to log in - no restart of the servlet container is needed. </section> <section id="adding-connections-to-a-user"> <h4>Adding connections to a user<a class="headerlink" href="#adding-connections-to-a-user" title="Link to this heading"></a></h4> To specify a connection within an <code class="docutils literal notranslate"><authorize></code> tag, you can either list a single protocol and set of parameters (specified with a <code class="docutils literal notranslate"><protocol></code> tag and any number of <code class="docutils literal notranslate"><param></code> tags), in which case that user will have access to only one connection named “DEFAULT”, or you can specify one or more connections with one or more <code class="docutils literal notranslate"><connection></code> tags, each of which can be named and contains a <code class="docutils literal notranslate"><protocol></code> tag and any number of <code class="docutils literal notranslate"><param></code> tags. </section> </section> </section> <section id="configuring-connections"> <h2>Configuring connections<a class="headerlink" href="#configuring-connections" title="Link to this heading"></a></h2> Each protocol supported by Guacamole has its own set of configuration parameters. These parameters typically describe the hostname and port of the remote desktop server, the credentials to use when connecting, if any, and the size and color depth of the display. If the protocol supports file transfer, options for enabling that functionality will be provided as well. <section id="vnc"> <h3>VNC<a class="headerlink" href="#vnc" title="Link to this heading"></a></h3> The VNC protocol is the simplest and first protocol supported by Guacamole. Although generally not as fast as RDP, many VNC servers are adequate, and VNC over Guacamole tends to be faster than VNC by itself due to decreased bandwidth usage. VNC support for Guacamole is provided by the libguac-client-vnc library, which will be installed as part of guacamole-server if the required dependencies are present during the build. <div class="admonition note"> Note In addition to the VNC-specific parameters below, Guacamole’s VNC support also accepts the parameters of several features that Guacamole provides for multiple protocols: <ul class="simple"> <li><a class="reference internal" href="#disable-clipboard">Disabling clipboard access</a></li> <li><a class="reference internal" href="#common-sftp">File transfer via SFTP</a></li> <li><a class="reference internal" href="#graphical-recording">Graphical session recording</a></li> <li><a class="reference internal" href="#wake-on-lan">Wake-on-LAN</a></li> </ul> </div> <section id="network-parameters"> <h4>Network parameters<a class="headerlink" href="#network-parameters" title="Link to this heading"></a></h4> With the exception of reverse-mode VNC connections, VNC works by making outbound network connections to a particular host which runs one or more VNC servers. Each VNC server is associated with a display number, from which the appropriate port number is derived. <dl class="simple myst"> <dt><code class="docutils literal notranslate">hostname</code></dt><dd>The hostname or IP address of the VNC server Guacamole should connect to. </dd> <dt><code class="docutils literal notranslate">port</code></dt><dd>The port the VNC server is listening on, usually 5900 or 5900 + display number. For example, if your VNC server is serving display number 1 (sometimes written as <code class="docutils literal notranslate">:1</code>), your port number here would be 5901. </dd> <dt><code class="docutils literal notranslate">autoretry</code></dt><dd>The number of times to retry connecting before giving up and returning an error. In the case of a reverse connection, this is the number of times the connection process is allowed to time out. </dd> </dl> </section> <section id="authentication"> <h4>Authentication<a class="headerlink" href="#authentication" title="Link to this heading"></a></h4> The VNC standard defines only password based authentication. Other authentication mechanisms exist, but are non-standard or proprietary. Guacamole currently supports both standard password-only based authentication, as well as username and password authentication. <dl class="simple myst"> <dt><code class="docutils literal notranslate">username</code></dt><dd>The username to use when attempting authentication, if any. This parameter is optional. </dd> <dt><code class="docutils literal notranslate">password</code></dt><dd>The password to use when attempting authentication, if any. This parameter is optional. </dd> </dl> </section> <section id="display-settings"> <h4>Display settings<a class="headerlink" href="#display-settings" title="Link to this heading"></a></h4> VNC servers do not allow the client to request particular display sizes, so you are at the mercy of your VNC server with respect to display width and height. However, to reduce bandwidth usage, you may request that the VNC server reduce its color depth. Guacamole will automatically detect 256-color images, but this can be guaranteed for absolutely all graphics sent over the connection by forcing the color depth to 8-bit. Color depth is otherwise dictated by the VNC server. If you are noticing problems with your VNC display, such as the lack of a mouse cursor, the presence of multiple mouse cursors, or strange colors (such as blue colors appearing more like orange or red), these are typically the result of bugs or limitations within the VNC server, and additional parameters are available to work around such issues. <dl class="simple myst"> <dt><code class="docutils literal notranslate">color-depth</code></dt><dd>The color depth to request, in bits-per-pixel. This parameter is optional. If specified, this must be either 8, 16, 24, or 32. Regardless of what value is chosen here, if a particular update uses less than 256 colors, Guacamole will always send that update as a 256-color PNG. </dd> <dt><code class="docutils literal notranslate">swap-red-blue</code></dt><dd>If the colors of your display appear wrong (blues appear orange or red, etc.), it may be that your VNC server is sending image data incorrectly, and the red and blue components of each color are swapped. If this is the case, set this parameter to “true” to work around the problem. This parameter is optional. </dd> <dt><code class="docutils literal notranslate">cursor</code></dt><dd>If set to “remote”, the mouse pointer will be rendered remotely, and the local position of the mouse pointer will be indicated by a small dot. A remote mouse cursor will feel slower than a local cursor, but may be necessary if the VNC server does not support sending the cursor image to the client. </dd> <dt><code class="docutils literal notranslate">encodings</code></dt><dd>A space-delimited list of VNC encodings to use. The format of this parameter is dictated by libvncclient and thus doesn’t really follow the form of other Guacamole parameters. This parameter is optional, and libguac-client-vnc will use any supported encoding by default. Beware that this parameter is intended to be replaced with individual, encoding-specific parameters in a future release. </dd> <dt><code class="docutils literal notranslate">read-only</code></dt><dd>Whether this connection should be read-only. If set to “true”, no input will be accepted on the connection at all. Users will only see the desktop and whatever other users using that same desktop are doing. This parameter is optional. </dd> <dt><code class="docutils literal notranslate">force-lossless</code></dt><dd>Whether this connection should only use lossless compression for graphical updates. If set to “true”, lossy compression will not be used. This parameter is optional. By default, lossy compression will be used when heuristics determine that it would likely outperform lossless compression. </dd> </dl> </section> <section id="vnc-repeater"> <h4>VNC Repeater<a class="headerlink" href="#vnc-repeater" title="Link to this heading"></a></h4> There exist VNC repeaters, such as UltraVNC Repeater, which act as intermediaries or proxies, providing a single logical VNC connection which is then routed to another VNC server elsewhere. Additional parameters are required to select which VNC host behind the repeater will receive the connection. <dl class="simple myst"> <dt><code class="docutils literal notranslate">dest-host</code></dt><dd>The destination host to request when connecting to a VNC proxy such as UltraVNC Repeater. This is only necessary if the VNC proxy in use requires the connecting user to specify which VNC server to connect to. If the VNC proxy automatically connects to a specific server, this parameter is not necessary. </dd> <dt><code class="docutils literal notranslate">dest-port</code></dt><dd>The destination port to request when connecting to a VNC proxy such as UltraVNC Repeater. This is only necessary if the VNC proxy in use requires the connecting user to specify which VNC server to connect to. If the VNC proxy automatically connects to a specific server, this parameter is not necessary. </dd> </dl> </section> <section id="reverse-vnc-connections"> <h4>Reverse VNC connections<a class="headerlink" href="#reverse-vnc-connections" title="Link to this heading"></a></h4> Guacamole supports “reverse” VNC connections, where the VNC client listens for an incoming connection from the VNC server. When reverse VNC connections are used, the VNC client and server switch network roles, but otherwise function as they normally would. The VNC server still provides the remote display, and the VNC client still provides all keyboard and mouse input. <dl class="simple myst"> <dt><code class="docutils literal notranslate">reverse-connect</code></dt><dd>Whether reverse connection should be used. If set to “true”, instead of connecting to a server at a given hostname and port, guacd will listen on the given port for inbound connections from a VNC server. </dd> <dt><code class="docutils literal notranslate">listen-timeout</code></dt><dd>If reverse connection is in use, the maximum amount of time to wait for an inbound connection from a VNC server, in milliseconds. If blank, the default value is 5000 (five seconds). </dd> </dl> </section> <section id="audio-support-via-pulseaudio"> <h4>Audio support (via PulseAudio)<a class="headerlink" href="#audio-support-via-pulseaudio" title="Link to this heading"></a></h4> VNC does not provide its own support for audio, but Guacamole’s VNC support can obtain audio through a secondary network connection to a PulseAudio server running on the same machine as the VNC server. Most Linux systems provide audio through a service called PulseAudio. This service is capable of communicating over the network, and if PulseAudio is configured to allow TCP connections, Guacamole can connect to your PulseAudio server and combine its audio with the graphics coming over VNC. Configuring PulseAudio for network connections requires an additional line within the PulseAudio configuration file, usually <code class="docutils literal notranslate">/etc/pulse/default.pa</code>: <div class="highlight-none notranslate"><div class="highlight"><pre>load-module module-native-protocol-tcp auth-ip-acl=192.168.1.0/24 auth-anonymous=1 </pre></div> </div> This loads the TCP module for PulseAudio, configuring it to accept connections without authentication and only from the <code class="docutils literal notranslate">192.168.1.0/24</code> subnet. You will want to replace this value with the subnet or IP address from which guacd will be connecting. It is possible to allow connections from absolutely anywhere, but beware that you should only do so if the nature of your network prevents unauthorized access: <div class="highlight-none notranslate"><div class="highlight"><pre>load-module module-native-protocol-tcp auth-anonymous=1 </pre></div> </div> In either case, the <code class="docutils literal notranslate">auth-anonymous=1</code> parameter is strictly required. Guacamole does not currently support the cookie-based authentication used by PulseAudio for non-anonymous connections. If this parameter is omitted, Guacamole will not be able to connect to PulseAudio. Once the PulseAudio configuration file has been modified appropriately, restart the PulseAudio service. PulseAudio should then begin listening on port 4713 (the default PulseAudio port) for incoming TCP connections. You can verify this using a utility like netstat: <div class="highlight-console notranslate"><div class="highlight"><pre>$ netstat -ln | grep 4713 tcp 0 0 0.0.0.0:4713 0.0.0.0:* LISTEN tcp6 0 0 :::4713 :::* LISTEN $ </pre></div> </div> The following parameters are available for configuring the audio support for VNC: <dl class="simple myst"> <dt><code class="docutils literal notranslate">enable-audio</code></dt><dd>If set to “true”, audio support will be enabled, and a second connection for PulseAudio will be made in addition to the VNC connection. By default, audio support within VNC is disabled. </dd> <dt><code class="docutils literal notranslate">audio-servername</code></dt><dd>The name of the PulseAudio server to connect to. This will be the hostname of the computer providing audio for your connection via PulseAudio, most likely the same as the value given for the <code class="docutils literal notranslate">hostname</code> parameter. If this parameter is omitted, the default PulseAudio device will be used, which will be the PulseAudio server running on the same machine as guacd. </dd> </dl> </section> <section id="clipboard-encoding"> <h4>Clipboard encoding<a class="headerlink" href="#clipboard-encoding" title="Link to this heading"></a></h4> While Guacamole will always use UTF-8 for its own clipboard data, the VNC standard requires that clipboard data be encoded in ISO 8859-1. As most VNC servers will not accept data in any other format, Guacamole will translate between UTF-8 and ISO 8859-1 when exchanging clipboard data with the VNC server, but this behavior can be overridden with the <code class="docutils literal notranslate">clipboard-encoding</code> parameter. <div class="admonition important"> Important The only clipboard encoding guaranteed to be supported by VNC servers is ISO 8859-1. You should only override the clipboard encoding using the <code class="docutils literal notranslate">clipboard-encoding</code> parameter of you are absolutely positive your VNC server supports other encodings. </div> <dl class="simple myst"> <dt><code class="docutils literal notranslate">clipboard-encoding</code></dt><dd>The encoding to assume for the VNC clipboard. This parameter is optional. By default, the standard encoding ISO 8859-1 will be used. Only use this parameter if you are sure your VNC server supports other encodings beyond the standard ISO 8859-1. Possible values are: <dl class="simple myst"> <dt>ISO8859-1</dt><dd>ISO 8859-1 is the clipboard encoding mandated by the VNC standard, and supports only basic Latin characters. Unless your VNC server specifies otherwise, this encoding is the only encoding guaranteed to work. </dd> <dt>UTF-8</dt><dd>UTF-8 - the most common encoding used for Unicode. Using this encoding for the VNC clipboard violates the VNC specification, but some servers do support this. This parameter value should only be used if you know your VNC server supports this encoding. </dd> <dt>UTF-16</dt><dd>UTF-16 - a 16-bit encoding for Unicode which is not as common as UTF-8, but still widely used. Using this encoding for the VNC clipboard violates the VNC specification. This parameter value should only be used if you know your VNC server supports this encoding. </dd> <dt>CP1252</dt><dd>Code page 1252 - a Windows-specific encoding for Latin characters which is mostly a superset of ISO 8859-1, mapping some additional displayable characters onto what would otherwise be control characters. Using this encoding for the VNC clipboard violates the VNC specification. This parameter value should only be used if you know your VNC server supports this encoding. </dd> </dl> </dd> </dl> </section> <section id="adding-a-vnc-connection"> <h4>Adding a VNC connection<a class="headerlink" href="#adding-a-vnc-connection" title="Link to this heading"></a></h4> If you are using the default authentication built into Guacamole, and you wish to grant access to a VNC connection to a particular user, you need to locate the <code class="docutils literal notranslate"><authorize></code> section for that user within your <code class="docutils literal notranslate">user-mapping.xml</code>, and add a section like the following within it: <div class="highlight-xml notranslate"><div class="highlight"><pre><connection name="Unique Name"> <protocol>vnc</protocol> <param name="hostname">localhost</param> <param name="port">5901</param> </connection> </pre></div> </div> If added exactly as above, a new connection named “<code class="docutils literal notranslate">Unique Name</code>” will be available to the user associated with the <code class="docutils literal notranslate"><authorize></code> section containing it. The connection will use VNC to connect to localhost at port 5901. Naturally, you will want to change some or all of these values. If your VNC server requires a password, or you wish to specify other configuration parameters (to reduce the color depth, for example), you will need to add additional <code class="docutils literal notranslate"><param></code> tags accordingly. Other authentication methods will provide documentation describing how to configure new connections. If the authentication method in use fully implements the features of Guacamole’s authentication API, you will be able to add a new VNC connection easily and intuitively using the administration interface built into Guacamole. You will not need to edit configuration files. </section> <section id="which-vnc-server"> <h4>Which VNC server?<a class="headerlink" href="#which-vnc-server" title="Link to this heading"></a></h4> The choice of VNC server can make a big difference when it comes to performance, especially over slower networks. While many systems provide VNC access by default, using this is often not the fastest method. <section id="realvnc-or-tigervnc"> <h5>RealVNC or TigerVNC<a class="headerlink" href="#realvnc-or-tigervnc" title="Link to this heading"></a></h5> RealVNC, and its derivative TigerVNC, perform quite well. In our testing, they perform the best with Guacamole. If you are okay with having a desktop that can only be accessed via VNC, one of these is likely your best choice. Both optimize window movement and (depending on the application) scrolling, giving a very responsive user experience. </section> <section id="tightvnc"> <h5>TightVNC<a class="headerlink" href="#tightvnc" title="Link to this heading"></a></h5> TightVNC is widely-available and performs generally as well as RealVNC or TigerVNC. If you wish to use TightVNC with Guacamole, performance should be just fine, but we highly recommend disabling its JPEG encoding. This is because images transmitted to Guacamole are always encoded losslessly as PNG images. When this operation is performed on a JPEG image, the artifacts present from JPEG’s lossy compression reduce the compressibility of the image for PNG, thus leading to a slower experience overall than if JPEG was simply not used to begin with. </section> <section id="x11vnc"> <h5>x11vnc<a class="headerlink" href="#x11vnc" title="Link to this heading"></a></h5> The main benefit of using x11vnc is that it allows you to continue using your desktop normally, while simultaneously exposing control of your desktop via VNC. Performance of x11vnc is comparable to RealVNC, TigerVNC, and TightVNC. If you need to use your desktop locally as well as via VNC, you will likely be quite happy with x11vnc. </section> <section id="vino"> <h5>vino<a class="headerlink" href="#vino" title="Link to this heading"></a></h5> vino is the VNC server that comes with the Gnome desktop environment, and is enabled if you enable “desktop sharing” via the system preferences available within Gnome. If you need to share your local desktop, we recommend using x11vnc rather vino, as it has proven more performant and feature-complete in our testing. If you don’t need to share a local desktop but simply need an environment you can access remotely, using a VNC server like RealVNC, TigerVNC, or TightVNC is a better choice. </section> <section id="qemu-or-kvm"> <h5>QEMU or KVM<a class="headerlink" href="#qemu-or-kvm" title="Link to this heading"></a></h5> QEMU (and thus KVM) expose the displays of virtual machines using VNC. If you need to see the virtual monitor of your virtual machine, using this VNC connection is really your only choice. As the VNC server built into QEMU cannot be aware of higher-level operations like window movement, resizing, or scrolling, those operations will tend to be sent suboptimally, and will not be as fast as a VNC server running within the virtual machine. If you wish to use a virtual machine for desktop access, we recommend installing a native VNC server inside the virtual machine after the virtual machine is set up. This will give a more responsive desktop. </section> </section> </section> <section id="rdp"> <h3>RDP<a class="headerlink" href="#rdp" title="Link to this heading"></a></h3> The RDP protocol is more complicated than VNC and was the second protocol officially supported by Guacamole. RDP tends to be faster than VNC due to the use of caching, which Guacamole does take advantage of. RDP support for Guacamole is provided by the libguac-client-rdp library, which will be installed as part of guacamole-server if the required dependencies are present during the build. <div class="admonition note"> Note In addition to the RDP-specific parameters below, Guacamole’s RDP support also accepts the parameters of several features that Guacamole provides for multiple protocols: <ul class="simple"> <li><a class="reference internal" href="#disable-clipboard">Disabling clipboard access</a></li> <li><a class="reference internal" href="#common-sftp">File transfer via SFTP</a></li> <li><a class="reference internal" href="#graphical-recording">Graphical session recording</a></li> <li><a class="reference internal" href="#wake-on-lan">Wake-on-LAN</a></li> </ul> </div> <section id="rdp-network-parameters"> <h4>Network parameters<a class="headerlink" href="#rdp-network-parameters" title="Link to this heading"></a></h4> RDP connections require a hostname or IP address defining the destination machine. The RDP port is defined to be 3389, and will be this value in most cases. You only need to specify the RDP port if you are not using port 3389. <dl class="simple myst"> <dt><code class="docutils literal notranslate">hostname</code></dt><dd>The hostname or IP address of the RDP server Guacamole should connect to. </dd> <dt><code class="docutils literal notranslate">port</code></dt><dd>The port the RDP server is listening on. This parameter is optional. If this is not specified, the standard port for RDP (3389) or Hyper-V’s default port for VMConnect (2179) will be used, depending on the security mode selected. </dd> </dl> </section> <section id="authentication-and-security"> <h4>Authentication and security<a class="headerlink" href="#authentication-and-security" title="Link to this heading"></a></h4> RDP provides authentication through the use of a username, password, and optional domain. All RDP connections are encrypted. Most RDP servers will provide a graphical login if the username, password, and domain parameters are omitted. One notable exception to this is Network Level Authentication, or NLA, which performs all authentication outside of a desktop session, and thus in the absence of a graphical interface. Servers that require NLA can be handled by Guacamole in one of two ways. The first is to provide the username and password within the connection configuration, either via static values or by passing through the Guacamole credentials with <a class="reference internal" href="#parameter-tokens">parameter tokens</a> and <a class="reference internal" href="ldap-auth.html">LDAP authentication</a>. Alternatively, if credentials are not configured within the connection configuration, Guacamole will attempt to prompt the user for the credentials interactively, if the versions of both guacd and Guacamole Client in use support it. If either component does not support prompting and the credentials are not configured, NLA-based connections will fail. <dl class="simple myst"> <dt><code class="docutils literal notranslate">username</code></dt><dd>The username to use to authenticate, if any. This parameter is optional. </dd> <dt><code class="docutils literal notranslate">password</code></dt><dd>The password to use when attempting authentication, if any. This parameter is optional. </dd> <dt><code class="docutils literal notranslate">domain</code></dt><dd>The domain to use when attempting authentication, if any. This parameter is optional. </dd> <dt><code class="docutils literal notranslate">security</code></dt><dd>The security mode to use for the RDP connection. This mode dictates how data will be encrypted and what type of authentication will be performed, if any. By default, a security mode is selected based on a negotiation process which determines what both the client and the server support. Possible values are: <dl class="simple myst"> <dt>any</dt><dd>Automatically select the security mode based on the security protocols supported by both the client and the server. This is the default. </dd> <dt>nla</dt><dd>Network Level Authentication, sometimes also referred to as “hybrid” or CredSSP (the protocol that drives NLA). This mode uses TLS encryption and requires the username and password to be given in advance. Unlike RDP mode, the authentication step is performed before the remote desktop session actually starts, avoiding the need for the Windows server to allocate significant resources for users that may not be authorized. If the versions of guacd and Guacamole Client in use support prompting and the username, password, and domain are not specified, the user will be interactively prompted to enter credentials to complete NLA and continue the connection. Otherwise, when prompting is not supported and credentials are not provided, NLA connections will fail. </dd> <dt>nla-ext</dt><dd>Extended Network Level Authentication. This mode is identical to NLA except that an additional “<a class="reference external" href="https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-rdpbcgr/d0e560a3-25cb-4563-8bdc-6c4cc625bbfc">Early User Authorization Result</a>” is required to be sent from the server to the client immediately after the NLA handshake is completed. </dd> <dt>tls</dt><dd>RDP authentication and encryption implemented via TLS (Transport Layer Security). Also referred to as RDSTLS, the TLS security mode is primarily used in load balanced configurations where the initial RDP server may redirect the connection to a different RDP server. </dd> <dt>vmconnect</dt><dd>Automatically select the security mode based on the security protocols supported by both the client and the server, limiting that negotiation to only the protocols known to be supported by <a class="reference internal" href="#rdp-preconnection-pdu">Hyper-V / VMConnect</a>. </dd> <dt>rdp</dt><dd>Legacy RDP encryption. This mode is generally only used for older Windows servers or in cases where a standard Windows login screen is desired. Newer versions of Windows have this mode disabled by default and will only accept NLA unless explicitly configured otherwise. </dd> </dl> </dd> <dt><code class="docutils literal notranslate">ignore-cert</code></dt><dd>If set to “true”, the certificate returned by the server will be ignored, even if that certificate cannot be validated. This is useful if you universally trust the server and your connection to the server, and you know that the server’s certificate cannot be validated (for example, if it is self-signed). </dd> <dt><code class="docutils literal notranslate">disable-auth</code></dt><dd>If set to “true”, authentication will be disabled. Note that this refers to authentication that takes place while connecting. Any authentication enforced by the server over the remote desktop session (such as a login dialog) will still take place. By default, authentication is enabled and only used when requested by the server. If you are using NLA, authentication must be enabled by definition. </dd> </dl> </section> <section id="clipboard-normalization"> <h4>Clipboard normalization<a class="headerlink" href="#clipboard-normalization" title="Link to this heading"></a></h4> Windows uses a different sequence of characters at the end of each line compared to other operating systems. As RDP preserves the format of line endings within the clipboard, this can cause trouble when using a non-Windows machine to access Windows or vice versa. If clipboard normalization is used, Guacamole will automatically translate the line endings within clipboard data to compensate for the expectations of the remote system. <dl class="simple myst"> <dt><code class="docutils literal notranslate">normalize-clipboard</code></dt><dd>The type of line ending normalization to apply to text within the clipboard, if any. By default, line ending normalization is not applied. Possible values are: <dl class="simple myst"> <dt>preserve</dt><dd>Preserve all line endings within the clipboard exactly as they are, performing no normalization whatsoever. This is the default. </dd> <dt>unix</dt><dd>Automatically transform all line endings within the clipboard to Unix-style line endings (LF). This format of line ending is the format used by both Linux and Mac. </dd> <dt>windows</dt><dd>Automatically transform all line endings within the clipboard to Windows-style line endings (CRLF). </dd> </dl> </dd> </dl> </section> <section id="session-settings"> <h4>Session settings<a class="headerlink" href="#session-settings" title="Link to this heading"></a></h4> RDP sessions will typically involve the full desktop environment of a normal user. Alternatively, you can manually specify a program to use instead of the RDP server’s default shell, or connect to the administrative console. Although Guacamole is independent of keyboard layout, RDP is not. This is because Guacamole represents keys based on what they do (“press the Enter key”), while RDP uses identifiers based on the key’s location (“press the rightmost key in the second row”). To translate between a Guacamole key event and an RDP key event, Guacamole must know ahead of time the keyboard layout of the RDP server. By default, the US English qwerty keyboard will be used. If this does not match the keyboard layout of your RDP server, keys will not be properly translated, and you will need to explicitly choose a different layout in your connection settings. If your keyboard layout is not supported, please notify the Guacamole team by <a class="reference external" href="https://issues.apache.org/jira/browse/GUACAMOLE">opening an issue in JIRA</a>. <dl class="simple myst"> <dt><code class="docutils literal notranslate">client-name</code></dt><dd>When connecting to the RDP server, Guacamole will normally provide its own hostname as the name of the client. If this parameter is specified, Guacamole will use its value instead. On Windows RDP servers, this value is exposed within the session as the <code class="docutils literal notranslate">CLIENTNAME</code> environment variable. </dd> <dt><code class="docutils literal notranslate">console</code></dt><dd>If set to “true”, you will be connected to the console (admin) session of the RDP server. </dd> <dt><code class="docutils literal notranslate">initial-program</code></dt><dd>The full path to the program to run immediately upon connecting. This parameter is optional. </dd> <dt><code class="docutils literal notranslate">server-layout</code></dt><dd>The server-side keyboard layout. This is the layout of the RDP server and has nothing to do with the keyboard layout in use on the client. The Guacamole client is independent of keyboard layout. The RDP protocol, however, is not independent of keyboard layout, and Guacamole needs to know the keyboard layout of the server in order to send the proper keys when a user is typing. Possible values are generally in the format <code class="samp docutils literal notranslate">LANGUAGE-REGION-VARIANT</code>, where <code class="docutils literal notranslate">LANGUAGE</code> is the standard two-letter language code for the primary language associated with the layout, <code class="docutils literal notranslate">REGION</code> is a standard representation of the location that the keyboard is used (the two-letter country code, when possible), and <code class="docutils literal notranslate">VARIANT</code> is the specific keyboard layout variant (such as “qwerty”, “qwertz”, or “azerty”): <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">Keyboard layout</th> <th class="head">Parameter value</th> </tr> </thead> <tbody> <tr class="row-even"><td>Brazilian (Portuguese)</td> <td><code class="docutils literal notranslate">pt-br-qwerty</code></td> </tr> <tr class="row-odd"><td>English (UK)</td> <td><code class="docutils literal notranslate">en-gb-qwerty</code></td> </tr> <tr class="row-even"><td>English (US)</td> <td><code class="docutils literal notranslate">en-us-qwerty</code></td> </tr> <tr class="row-odd"><td>French</td> <td><code class="docutils literal notranslate">fr-fr-azerty</code></td> </tr> <tr class="row-even"><td>French (Belgian)</td> <td><code class="docutils literal notranslate">fr-be-azerty</code></td> </tr> <tr class="row-odd"><td>French (Swiss)</td> <td><code class="docutils literal notranslate">fr-ch-qwertz</code></td> </tr> <tr class="row-even"><td>German</td> <td><code class="docutils literal notranslate">de-de-qwertz</code></td> </tr> <tr class="row-odd"><td>German (Swiss)</td> <td><code class="docutils literal notranslate">de-ch-qwertz</code></td> </tr> <tr class="row-even"><td>Hungarian</td> <td><code class="docutils literal notranslate">hu-hu-qwertz</code></td> </tr> <tr class="row-odd"><td>Italian</td> <td><code class="docutils literal notranslate">it-it-qwerty</code></td> </tr> <tr class="row-even"><td>Japanese</td> <td><code class="docutils literal notranslate">ja-jp-qwerty</code></td> </tr> <tr class="row-odd"><td>Norwegian</td> <td><code class="docutils literal notranslate">no-no-qwerty</code></td> </tr> <tr class="row-even"><td>Spanish</td> <td><code class="docutils literal notranslate">es-es-qwerty</code></td> </tr> <tr class="row-odd"><td>Spanish (Latin American)</td> <td><code class="docutils literal notranslate">es-latam-qwerty</code></td> </tr> <tr class="row-even"><td>Swedish</td> <td><code class="docutils literal notranslate">sv-se-qwerty</code></td> </tr> <tr class="row-odd"><td>Turkish-Q</td> <td><code class="docutils literal notranslate">tr-tr-qwerty</code></td> </tr> </tbody> </table> If you server’s keyboard layout is not yet supported, and it is not possible to set your server to use a supported layout, the <code class="docutils literal notranslate">failsafe</code> layout may be used to force Unicode events to be used for all input, however beware that doing so may prevent keyboard shortcuts from working as expected. </dd> <dt><code class="docutils literal notranslate">timezone</code></dt><dd>The timezone that the client should send to the server for configuring the local time display of that server. The format of the timezone is in the standard IANA key zone format, which is the format used in UNIX/Linux. This will be converted by RDP into the correct format for Windows. The timezone is detected and will be passed to the server during the handshake phase of the connection, and may used by protocols, like RDP, that support it. This parameter can be used to override the value detected and passed during the handshake, or can be used in situations where guacd does not support passing the timezone parameter during the handshake phase (guacd versions prior to 1.3.0). Support for forwarding the client timezone varies by RDP server implementation. For example, with Windows, support for forwarding timezones is only present in Windows Server with Remote Desktop Services (RDS, formerly known as Terminal Services) installed. Windows Server installations in admin mode, along with Windows workstation versions, do not allow the timezone to be forwarded. Other server implementations, for example, xrdp, may not implement this feature at all. Consult the documentation for the RDP server to determine whether or not this feature is supported. </dd> </dl> </section> <section id="rdp-display-settings"> <h4>Display settings<a class="headerlink" href="#rdp-display-settings" title="Link to this heading"></a></h4> Guacamole will automatically choose an appropriate display size for RDP connections based on the size of the browser window and the DPI of the device. The size of the display can be forced by specifying explicit width or height values. To reduce bandwidth usage, you may also request that the server reduce its color depth. Guacamole will automatically detect 256-color images, but this can be guaranteed for absolutely all graphics sent over the connection by forcing the color depth to 8-bit. Color depth is otherwise dictated by the RDP server. <dl class="simple myst"> <dt><code class="docutils literal notranslate">color-depth</code></dt><dd>The color depth to request, in bits-per-pixel. This parameter is optional. If specified, this must be either 8, 16, or 24. Regardless of what value is chosen here, if a particular update uses less than 256 colors, Guacamole will always send that update as a 256-color PNG. </dd> <dt><code class="docutils literal notranslate">width</code></dt><dd>The width of the display to request, in pixels. This parameter is optional. If this value is not specified, the width of the connecting client display will be used instead. </dd> <dt><code class="docutils literal notranslate">height</code></dt><dd>The height of the display to request, in pixels. This parameter is optional. If this value is not specified, the height of the connecting client display will be used instead. </dd> <dt><code class="docutils literal notranslate">dpi</code></dt><dd>The desired effective resolution of the client display, in DPI. This parameter is optional. If this value is not specified, the resolution and size of the client display will be used together to determine, heuristically, an appropriate resolution for the RDP session. </dd> <dt><code class="docutils literal notranslate">resize-method</code></dt><dd>The method to use to update the RDP server when the width or height of the client display changes. This parameter is optional. If this value is not specified, no action will be taken when the client display changes size. Normally, the display size of an RDP session is constant and can only be changed when initially connecting. As of RDP 8.1, the “Display Update” channel can be used to request that the server change the display size. For older RDP servers, the only option is to disconnect and reconnect with the new size. Possible values are: <dl class="simple myst"> <dt>display-update</dt><dd>Uses the “Display Update” channel added with RDP 8.1 to signal the server when the client display size has changed. </dd> <dt>reconnect</dt><dd>Automatically disconnects the RDP session when the client display size has changed, and reconnects with the new size. </dd> </dl> </dd> <dt><code class="docutils literal notranslate">force-lossless</code></dt><dd>Whether this connection should only use lossless compression for graphical updates. If set to “true”, lossy compression will not be used. This parameter is optional. By default, lossy compression will be used when heuristics determine that it would likely outperform lossless compression. </dd> </dl> </section> <section id="device-redirection"> <h4>Device redirection<a class="headerlink" href="#device-redirection" title="Link to this heading"></a></h4> Device redirection refers to the use of non-display devices over RDP. Guacamole’s RDP support currently allows redirection of audio, printing, and disk access, some of which require additional configuration in order to function properly. Audio redirection will be enabled by default. If Guacamole was correctly installed, and audio redirection is supported by your RDP server, sound should play within remote connections without manual intervention. Printing requires GhostScript to be installed on the Guacamole server, and allows users to print arbitrary documents directly to PDF. When documents are printed to the redirected printer, the user will receive a PDF of that document within their web browser. Guacamole provides support for file transfer over RDP by emulating a virtual disk drive. This drive will persist on the Guacamole server, confined within the drive path specified. If drive redirection is enabled on a Guacamole RDP connection, users will be able to upload and download files as described in <a class="reference internal" href="using-guacamole.html">Using Guacamole</a>. <dl class="simple myst"> <dt><code class="docutils literal notranslate">disable-audio</code></dt><dd>Audio is enabled by default in both the client and in libguac-client-rdp. If you are concerned about bandwidth usage, or sound is causing problems, you can explicitly disable sound by setting this parameter to “true”. </dd> <dt><code class="docutils literal notranslate">enable-audio-input</code></dt><dd>If set to “true”, audio input support (microphone) will be enabled, leveraging the standard “<code class="docutils literal notranslate">AUDIO_INPUT</code>” channel of RDP. By default, audio input support within RDP is disabled. </dd> <dt><code class="docutils literal notranslate">enable-touch</code></dt><dd>If set to “true”, support for multi-touch events will be enabled, leveraging the standard “<code class="docutils literal notranslate">RDPEI</code>” channel of RDP. By default, direct RDP support for multi-touch events is disabled. Enabling support for multi-touch allows touch interaction with applications inside the RDP session, however the touch gestures available will depend on the level of touch support of those applications and the OS. If multi-touch support is not enabled, pointer-type interaction with applications inside the RDP session will be limited to mouse or emulated mouse events. </dd> <dt><code class="docutils literal notranslate">enable-printing</code></dt><dd>Printing is disabled by default, but with printing enabled, RDP users can print to a virtual printer that sends a PDF containing the document printed to the Guacamole client. Enable printing by setting this parameter to “true”. Printing support requires GhostScript to be installed. If guacd cannot find the <code class="docutils literal notranslate">gs</code> executable when printing, the print attempt will fail. </dd> <dt><code class="docutils literal notranslate">printer-name</code></dt><dd>The name of the redirected printer device that is passed through to the RDP session. This is the name that the user will see in, for example, the Devices and Printers control panel. If printer redirection is not enabled, this option has no effect. </dd> <dt><code class="docutils literal notranslate">enable-drive</code></dt><dd>File transfer is disabled by default, but with file transfer enabled, RDP users can transfer files to and from a virtual drive which persists on the Guacamole server. Enable file transfer support by setting this parameter to “true”. Files will be stored in the directory specified by the “<code class="docutils literal notranslate">drive-path</code>” parameter, which is required if file transfer is enabled. </dd> <dt><code class="docutils literal notranslate">disable-download</code></dt><dd>If set to true downloads from the remote server to client (browser) will be disabled. This includes both downloads done via the hidden Guacamole menu, as well as using the special “Download” folder presented to the remote server. The default is false, which means that downloads will be allowed. If file transfer is not enabled, this parameter is ignored. </dd> <dt><code class="docutils literal notranslate">disable-upload</code></dt><dd>If set to true, uploads from the client (browser) to the remote server location will be disabled. The default is false, which means uploads will be allowed if file transfer is enabled. If file transfer is not enabled, this parameter is ignored. </dd> <dt><code class="docutils literal notranslate">drive-name</code></dt><dd>The name of the filesystem used when passed through to the RDP session. This is the name that users will see in their Computer/My Computer area along with client name (for example, “Guacamole on Guacamole RDP”), and is also the name of the share when accessing the special <code class="docutils literal notranslate">\\tsclient</code> network location. If file transfer is not enabled, this parameter is ignored. </dd> <dt><code class="docutils literal notranslate">drive-path</code></dt><dd>The directory on the Guacamole server in which transferred files should be stored. This directory must be accessible by guacd and both readable and writable by the user that runs guacd. This parameter does not refer to a directory on the RDP server. If file transfer is not enabled, this parameter is ignored. </dd> <dt><code class="docutils literal notranslate">create-drive-path</code></dt><dd>If set to “true”, and file transfer is enabled, the directory specified by the <code class="docutils literal notranslate">drive-path</code> parameter will automatically be created if it does not yet exist. Only the final directory in the path will be created - if other directories earlier in the path do not exist, automatic creation will fail, and an error will be logged. By default, the directory specified by the <code class="docutils literal notranslate">drive-path</code> parameter will not automatically be created, and attempts to transfer files to a non-existent directory will be logged as errors. If file transfer is not enabled, this parameter is ignored. </dd> <dt><code class="docutils literal notranslate">console-audio</code></dt><dd>If set to “true”, audio will be explicitly enabled in the console (admin) session of the RDP server. Setting this option to “true” only makes sense if the <code class="docutils literal notranslate">console</code> parameter is also set to “true”. </dd> <dt><code class="docutils literal notranslate">static-channels</code></dt><dd>A comma-separated list of static channel names to open and expose as pipes. If you wish to communicate between an application running on the remote desktop and JavaScript, this is the best way to do it. Guacamole will open an outbound pipe with the name of the static channel. If JavaScript needs to communicate back in the other direction, it should respond by opening another pipe with the same name. Guacamole allows any number of static channels to be opened, but protocol restrictions of RDP limit the size of each channel name to 7 characters. </dd> </dl> </section> <section id="preconnection-pdu-hyper-v-vmconnect"> <h4>Preconnection PDU (Hyper-V / VMConnect)<a class="headerlink" href="#preconnection-pdu-hyper-v-vmconnect" title="Link to this heading"></a></h4> Some RDP servers host multiple logical RDP connections behind a single server listening on a single TCP port. To select between these logical connections, an RDP client must send the “preconnection PDU” - a message which contains values that uniquely identify the destination, referred to as the “RDP source”. This mechanism is defined by the <a class="reference external" href="https://msdn.microsoft.com/en-us/library/cc242359.aspx">“Session Selection Extension</a> for the RDP protocol, and is implemented by Microsoft’s Hyper-V hypervisor. If you are using Hyper-V, you will need to specify the ID of the destination virtual machine within the <code class="docutils literal notranslate">preconnection-blob</code> parameter. This value can be determined using PowerShell: <div class="highlight-ps1con notranslate"><div class="highlight"><pre>PS C:\> Get-VM VirtualMachineName | Select-Object Id Id -- ed272546-87bd-4db9-acba-e36e1a9ca20a PS C:\> </pre></div> </div> The preconnection PDU is intentionally generic. While its primary use is as a means for selecting virtual machines behind Hyper-V, other RDP servers may use it as well. It is up to the RDP server itself to determine whether the preconnection ID, BLOB, or both will be used, and what their values mean. If you do intend to use Hyper-V, beware that its built-in RDP server requires different parameters for authentication and Guacamole’s defaults will not work. In most cases, you will need to do the following when connecting to Hyper-V: <ol class="arabic simple"> <li>Specify both “<code class="docutils literal notranslate">username</code>” and “<code class="docutils literal notranslate">password</code>” appropriately, and set “<code class="docutils literal notranslate">security</code>” to “<code class="docutils literal notranslate">vmconnect</code>”. Selecting the “<code class="docutils literal notranslate">vmconnect</code>” security mode will configure Guacamole to automatically negotiate security modes known to be supported by Hyper-V, and will automatically select Hyper-V’s default RDP port (2179).</li> <li>If necessary, set “<code class="docutils literal notranslate">ignore-cert</code>” to “<code class="docutils literal notranslate">true</code>”. Hyper-V may use a self-signed certificate.</li> </ol> <dl class="simple myst"> <dt><code class="docutils literal notranslate">preconnection-id</code></dt><dd>The numeric ID of the RDP source. This is a non-negative integer value dictating which of potentially several logical RDP connections should be used. This parameter is optional, and is only required if the RDP server is documented as requiring it. If using Hyper-V, this should be left blank. </dd> <dt><code class="docutils literal notranslate">preconnection-blob</code></dt><dd>An arbitrary string which identifies the RDP source - one of potentially several logical RDP connections hosted by the same RDP server. This parameter is optional, and is only required if the RDP server is documented as requiring it, such as Hyper-V. In all cases, the meaning of this parameter is opaque to the RDP protocol itself and is dictated by the RDP server. For Hyper-V, this will be the ID of the destination virtual machine. </dd> </dl> </section> <section id="remote-desktop-gateway"> <h4>Remote desktop gateway<a class="headerlink" href="#remote-desktop-gateway" title="Link to this heading"></a></h4> Microsoft’s remote desktop server provides an additional gateway service which allows external connections to be forwarded to internal RDP servers which are otherwise not accessible. If you will be using Guacamole to connect through such a gateway, you will need to provide additional parameters describing the connection to that gateway, as well as any required credentials. <dl class="simple myst"> <dt><code class="docutils literal notranslate">gateway-hostname</code></dt><dd>The hostname of the remote desktop gateway that should be used as an intermediary for the remote desktop connection. If omitted, a gateway will not be used. </dd> <dt><code class="docutils literal notranslate">gateway-port</code></dt><dd>The port of the remote desktop gateway that should be used as an intermediary for the remote desktop connection. By default, this will be “443”. </dd> <dt><code class="docutils literal notranslate">gateway-username</code></dt><dd>The username of the user authenticating with the remote desktop gateway, if a gateway is being used. This is not necessarily the same as the user actually using the remote desktop connection. </dd> <dt><code class="docutils literal notranslate">gateway-password</code></dt><dd>The password to provide when authenticating with the remote desktop gateway, if a gateway is being used. </dd> <dt><code class="docutils literal notranslate">gateway-domain</code></dt><dd>The domain of the user authenticating with the remote desktop gateway, if a gateway is being used. This is not necessarily the same domain as the user actually using the remote desktop connection. </dd> </dl> </section> <section id="load-balancing-and-rdp-connection-brokers"> <h4>Load balancing and RDP connection brokers<a class="headerlink" href="#load-balancing-and-rdp-connection-brokers" title="Link to this heading"></a></h4> If your remote desktop servers are behind a load balancer, sometimes referred to as a “connection broker” or “TS session broker”, that balancer may require additional information during the connection process to determine how the incoming connection should be routed. RDP does not dictate the format of this information; it is specific to the balancer in use. If you are using a load balancer and are unsure whether such information is required, you will need to check the documentation for your balancer. If your balancer provides <code class="docutils literal notranslate">.rdp</code> files for convenience, look through the contents of those files for a string field called “loadbalanceinfo”, as that field is where the required information/cookie would be specified. <dl class="simple myst"> <dt><code class="docutils literal notranslate">load-balance-info</code></dt><dd>The load balancing information or cookie which should be provided to the connection broker. If no connection broker is being used, this should be left blank. </dd> </dl> </section> <section id="performance-flags"> <h4>Performance flags<a class="headerlink" href="#performance-flags" title="Link to this heading"></a></h4> RDP provides several flags which control the availability of features that decrease performance and increase bandwidth for the sake of aesthetics, such as wallpaper, window theming, menu effects, and smooth fonts. These features are all disabled by default within Guacamole such that bandwidth usage is minimized, but you can manually re-enable them on a per-connection basis if desired. <dl class="simple myst"> <dt><code class="docutils literal notranslate">enable-wallpaper</code></dt><dd>If set to “true”, enables rendering of the desktop wallpaper. By default, wallpaper will be disabled, such that unnecessary bandwidth need not be spent redrawing the desktop. </dd> <dt><code class="docutils literal notranslate">enable-theming</code></dt><dd>If set to “true”, enables use of theming of windows and controls. By default, theming within RDP sessions is disabled. </dd> <dt><code class="docutils literal notranslate">enable-font-smoothing</code></dt><dd>If set to “true”, text will be rendered with smooth edges. Text over RDP is rendered with rough edges by default, as this reduces the number of colors used by text, and thus reduces the bandwidth required for the connection. </dd> <dt><code class="docutils literal notranslate">enable-full-window-drag</code></dt><dd>If set to “true”, the contents of windows will be displayed as windows are moved. By default, the RDP server will only draw the window border while windows are being dragged. </dd> <dt><code class="docutils literal notranslate">enable-desktop-composition</code></dt><dd>If set to “true”, graphical effects such as transparent windows and shadows will be allowed. By default, such effects, if available, are disabled. </dd> <dt><code class="docutils literal notranslate">enable-menu-animations</code></dt><dd>If set to “true”, menu open and close animations will be allowed. Menu animations are disabled by default. </dd> <dt><code class="docutils literal notranslate">disable-bitmap-caching</code></dt><dd>In certain situations, particularly with RDP server implementations with known bugs, it is necessary to disable RDP’s built-in bitmap caching functionality. This parameter allows that to be controlled in a Guacamole session. If set to “true” the RDP bitmap cache will not be used. </dd> <dt><code class="docutils literal notranslate">disable-offscreen-caching</code></dt><dd>RDP normally maintains caches of regions of the screen that are currently not visible in the client in order to accelerate retrieval of those regions when they come into view. This parameter, when set to “true,” will disable caching of those regions. This is usually only useful when dealing with known bugs in RDP server implementations and should remain enabled in most circumstances. </dd> <dt><code class="docutils literal notranslate">disable-glyph-caching</code></dt><dd>In addition to screen regions, RDP maintains caches of frequently used symbols or fonts, collectively known as “glyphs.” As with bitmap and offscreen caching, certain known bugs in RDP implementations can cause performance issues with this enabled, and setting this parameter to “true” will disable that glyph caching in the RDP session. Glyph caching is currently universally disabled, regardless of the value of this parameter, as glyph caching support is not considered stable by FreeRDP as of the FreeRDP 2.0.0 release. See: <a class="reference external" href="https://issues.apache.org/jira/browse/GUACAMOLE-1191">GUACAMOLE-1191</a>. </dd> </dl> </section> <section id="remoteapp"> <h4>RemoteApp<a class="headerlink" href="#remoteapp" title="Link to this heading"></a></h4> Recent versions of Windows provide a feature called RemoteApp which allows individual applications to be used over RDP, without providing access to the full desktop environment. If your RDP server has this feature enabled and configured, you can configure Guacamole connections to use those individual applications. <dl class="simple myst"> <dt><code class="docutils literal notranslate">remote-app</code></dt><dd>Specifies the RemoteApp to start on the remote desktop. If supported by your remote desktop server, this application, and only this application, will be visible to the user. Windows requires a special notation for the names of remote applications. The names of remote applications must be prefixed with two vertical bars. For example, if you have created a remote application on your server for <code class="docutils literal notranslate">notepad.exe</code> and have assigned it the name “notepad”, you would set this parameter to: “<code class="docutils literal notranslate">||notepad</code>”. </dd> <dt><code class="docutils literal notranslate">remote-app-dir</code></dt><dd>The working directory, if any, for the remote application. This parameter has no effect if RemoteApp is not in use. </dd> <dt><code class="docutils literal notranslate">remote-app-args</code></dt><dd>The command-line arguments, if any, for the remote application. This parameter has no effect if RemoteApp is not in use. </dd> </dl> </section> <section id="adding-an-rdp-connection"> <h4>Adding an RDP connection<a class="headerlink" href="#adding-an-rdp-connection" title="Link to this heading"></a></h4> If you are using the default authentication built into Guacamole, and you wish to grant access to a RDP connection to a particular user, you need to locate the <code class="docutils literal notranslate"><authorize></code> section for that user within your <code class="docutils literal notranslate">user-mapping.xml</code>, and add a section like the following within it: <div class="highlight-xml notranslate"><div class="highlight"><pre><connection name="Unique Name"> <protocol>rdp</protocol> <param name="hostname">localhost</param> <param name="port">3389</param> </connection> </pre></div> </div> If added exactly as above, a new connection named “<code class="docutils literal notranslate">Unique Name</code>” will be available to the user associated with the <code class="docutils literal notranslate"><authorize></code> section containing it. The connection will use RDP to connect to localhost at port 3389. Naturally, you will want to change some or all of these values. If you want to login automatically rather than receive a login prompt upon connecting, you can specify a username and password with additional <code class="docutils literal notranslate"><param></code> tags. Other options are available for controlling the color depth, size of the screen, etc. Other authentication methods will provide documentation describing how to configure new connections. If the authentication method in use fully implements the features of Guacamole’s authentication API, you will be able to add a new RDP connection easily and intuitively using the administration interface built into Guacamole. You will not need to edit configuration files. </section> </section> <section id="ssh"> <h3>SSH<a class="headerlink" href="#ssh" title="Link to this heading"></a></h3> Unlike VNC or RDP, SSH is a text protocol. Its implementation in Guacamole is actually a combination of a terminal emulator and SSH client, because the SSH protocol isn’t inherently graphical. Guacamole’s SSH support emulates a terminal on the server side, and draws the screen of this terminal remotely on the client. SSH support for Guacamole is provided by the libguac-client-ssh library, which will be installed as part of guacamole-server if the required dependencies are present during the build. <div class="admonition note"> Note In addition to the SSH-specific parameters below, Guacamole’s SSH support also accepts the parameters of several features that Guacamole provides for multiple protocols: <ul class="simple"> <li><a class="reference internal" href="#disable-clipboard">Disabling clipboard access</a></li> <li><a class="reference internal" href="#graphical-recording">Graphical session recording</a></li> <li><a class="reference internal" href="#typescripts">Text session recording (typescripts)</a></li> <li><a class="reference internal" href="#stdin-pipe">Providing terminal input directly from JavaScript</a></li> <li><a class="reference internal" href="#terminal-behavior">Controlling terminal behavior</a></li> <li><a class="reference internal" href="#terminal-display-settings">Terminal display settings</a></li> <li><a class="reference internal" href="#wake-on-lan">Wake-on-LAN</a></li> </ul> </div> <section id="ssh-host-verification"> <h4>SSH Host Verification<a class="headerlink" href="#ssh-host-verification" title="Link to this heading"></a></h4> By default, Guacamole does not do any verification of host identity before establishing SSH connections. While this may be safe for private and trusted networks, it is not ideal for large networks with unknown/untrusted systems, or for SSH connections that traverse the Internet. The potential exists for Man-in-the-Middle (MitM) attacks when connecting to these hosts. Guacamole includes two methods for verifying SSH (and SFTP) server identity that can be used to make sure that the host you are connecting to is a host that you know and trust. The first method is by reading a file in <code class="docutils literal notranslate">GUACAMOLE_HOME</code> called <code class="docutils literal notranslate">ssh_known_hosts</code>. This file should be in the format of a standard OpenSSH <code class="docutils literal notranslate">known_hosts</code> file. If the file is not present, no verification is done. If the file is present, it is read in at connection time and remote host identities are verified against the keys present in the file. The second method for verifying host identity is by passing a connection parameter that contains an OpenSSH known hosts entry for that specific host. The <code class="docutils literal notranslate">host-key</code> parameter is used for SSH connections, while the SFTP connections associated with RDP and VNC use the <code class="docutils literal notranslate">sftp-host-key</code> parameter. If these parameters are not present on their respective connections no host identity verification is performed. If the parameter is present then the identity of the remote host is verified against the identity provided in the parameter before a connection is established. </section> <section id="ssh-network-parameters"> <h4>Network parameters<a class="headerlink" href="#ssh-network-parameters" title="Link to this heading"></a></h4> SSH connections require a hostname or IP address defining the destination machine. SSH is standardized to use port 22 and this will be the proper value in most cases. You only need to specify the SSH port if you are not using the standard port. <dl class="simple myst"> <dt><code class="docutils literal notranslate">hostname</code></dt><dd>The hostname or IP address of the SSH server Guacamole should connect to. </dd> <dt><code class="docutils literal notranslate">port</code></dt><dd>The port the SSH server is listening on, usually 22. This parameter is optional. If this is not specified, the default of 22 will be used. </dd> <dt><code class="docutils literal notranslate">host-key</code></dt><dd>The known hosts entry for the SSH server. This parameter is optional, and, if not provided, no verification of host identity will be done. If the parameter is provided the identity of the server will be checked against the data. The format of this parameter is that of a single entry from an OpenSSH <code class="docutils literal notranslate">known_hosts</code> file. For more information, please see <a class="reference internal" href="#ssh-host-verification">SSH Host Verification</a>. </dd> <dt><code class="docutils literal notranslate">server-alive-interval</code></dt><dd>By default the SSH client does not send keepalive requests to the server. This parameter allows you to configure the the interval in seconds at which the client connection sends keepalive packets to the server. The default is 0, which disables sending the packets. The minimum value is 2. </dd> </dl> </section> <section id="ssh-authentication"> <h4>Authentication<a class="headerlink" href="#ssh-authentication" title="Link to this heading"></a></h4> SSH provides authentication through passwords and public key authentication, and also supports the “NONE” method. SSH “NONE” authentication is seen occasionally in appliances and items like network or SAN fabric switches. Generally for this authentication method you need only provide a username. For Guacamole to use public key authentication, it must have access to your private key and, if applicable, its passphrase. If the private key requires a passphrase, but no passphrase is provided, you will be prompted for the passphrase upon connecting. If no private key is provided, Guacamole will attempt to authenticate using a password, reading that password from the connection parameters, if provided, or by prompting the user directly. <dl class="simple myst"> <dt><code class="docutils literal notranslate">username</code></dt><dd>The username to use to authenticate, if any. This parameter is optional. If not specified, you will be prompted for the username upon connecting. </dd> <dt><code class="docutils literal notranslate">password</code></dt><dd>The password to use when attempting authentication, if any. This parameter is optional. If not specified, you will be prompted for your password upon connecting. </dd> <dt><code class="docutils literal notranslate">private-key</code></dt><dd>The entire contents of the private key to use for public key authentication. If this parameter is not specified, public key authentication will not be used. The private key must be in OpenSSH format, as would be generated by the OpenSSH ssh-keygen utility. </dd> <dt><code class="docutils literal notranslate">passphrase</code></dt><dd>The passphrase to use to decrypt the private key for use in public key authentication. This parameter is not needed if the private key does not require a passphrase. If the private key requires a passphrase, but this parameter is not provided, the user will be prompted for the passphrase upon connecting. </dd> </dl> </section> <section id="running-a-command-instead-of-a-shell"> <h4>Running a command (instead of a shell)<a class="headerlink" href="#running-a-command-instead-of-a-shell" title="Link to this heading"></a></h4> By default, SSH sessions will start an interactive shell. The shell which will be used is determined by the SSH server, normally by reading the user’s default shell previously set with <code class="docutils literal notranslate">chsh</code> or within <code class="docutils literal notranslate">/etc/passwd</code>. If you wish to override this and instead run a specific command, you can do so by specifying that command in the configuration of the Guacamole SSH connection. <dl class="simple myst"> <dt><code class="docutils literal notranslate">command</code></dt><dd>The command to execute over the SSH session, if any. This parameter is optional. If not specified, the SSH session will use the user’s default shell. </dd> </dl> </section> <section id="internationalization-locale-settings"> <h4>Internationalization/Locale settings<a class="headerlink" href="#internationalization-locale-settings" title="Link to this heading"></a></h4> The language of the session is normally set by the SSH server. If the SSH server allows the relevant environment variable to be set, the language can be overridden on a per-connection basis. <dl class="simple myst"> <dt><code class="docutils literal notranslate">locale</code></dt><dd>The specific locale to request for the SSH session. This parameter is optional and may be any value accepted by the <code class="docutils literal notranslate">LANG</code> environment variable of the SSH server. If not specified, the SSH server’s default locale will be used. As this parameter is sent to the SSH server using the <code class="docutils literal notranslate">LANG</code> environment variable, the parameter will only have an effect if the SSH server allows the <code class="docutils literal notranslate">LANG</code> environment variable to be set by SSH clients. </dd> <dt><code class="docutils literal notranslate">timezone</code></dt><dd>This parameter allows you to control the timezone that is sent to the server over the SSH connection, which will change the way local time is displayed on the server. The mechanism used to do this over SSH connections is by setting the <code class="docutils literal notranslate">TZ</code> variable on the SSH connection to the timezone specified by this parameter. This means that the SSH server must allow the <code class="docutils literal notranslate">TZ</code> variable to be set/overriden - many SSH server implementations have this disabled by default. To get this to work, you may need to modify the configuration of the SSH server and explicitly allow for <code class="docutils literal notranslate">TZ</code> to be set/overriden. The available values of this parameter are standard IANA key zone format timezones, and the value will be sent directly to the server in this format. </dd> </dl> </section> <section id="sftp"> <h4>SFTP<a class="headerlink" href="#sftp" title="Link to this heading"></a></h4> Guacamole provides support for file transfer over SSH using SFTP, the file transfer protocol built into most SSH servers. If SFTP is enabled on a Guacamole SSH connection, users will be able to upload and download files as described in <a class="reference internal" href="using-guacamole.html">Using Guacamole</a> <dl class="simple myst"> <dt><code class="docutils literal notranslate">enable-sftp</code></dt><dd>Whether file transfer should be enabled. If set to “true”, the user will be allowed to upload or download files from the SSH server using SFTP. Guacamole includes the guacctl utility which controls file downloads and uploads when run on the SSH server by the user over the SSH connection. </dd> <dt><code class="docutils literal notranslate">sftp-root-directory</code></dt><dd>The directory to expose to connected users via Guacamole’s <a class="reference internal" href="using-guacamole.html#file-browser">file browser</a>. If omitted, the root directory will be used by default. </dd> <dt><code class="docutils literal notranslate">sftp-disable-download</code></dt><dd>If set to true downloads from the remote system to the client (browser) will be disabled. The default is false, which means that downloads will be enabled. If SFTP is not enabled, this parameter will be ignored. </dd> <dt><code class="docutils literal notranslate">sftp-disable-upload</code></dt><dd>If set to true uploads from the client (browser) to the remote system will be disabled. The default is false, which means that uploads will be enabled. If SFTP is not enabled, this parameter will be ignored. </dd> </dl> </section> <section id="adding-an-ssh-connection"> <h4>Adding an SSH connection<a class="headerlink" href="#adding-an-ssh-connection" title="Link to this heading"></a></h4> If you are using the default authentication built into Guacamole, and you wish to grant access to a SSH connection to a particular user, you need to locate the <code class="docutils literal notranslate"><authorize></code> section for that user within your <code class="docutils literal notranslate">user-mapping.xml</code>, and add a section like the following within it: <div class="highlight-xml notranslate"><div class="highlight"><pre><connection name="Unique Name"> <protocol>ssh</protocol> <param name="hostname">localhost</param> <param name="port">22</param> </connection> </pre></div> </div> If added exactly as above, a new connection named “<code class="docutils literal notranslate">Unique Name</code>” will be available to the user associated with the <code class="docutils literal notranslate"><authorize></code> section containing it. The connection will use SSH to connect to localhost at port 22. Naturally, you will want to change some or all of these values. If you want to login automatically rather than receive a login prompt upon connecting, you can specify a username and password with additional <code class="docutils literal notranslate"><param></code> tags. Other options are available for controlling the font. Other authentication methods will provide documentation describing how to configure new connections. </section> </section> <section id="telnet"> <h3>Telnet<a class="headerlink" href="#telnet" title="Link to this heading"></a></h3> Telnet is a text protocol and provides similar functionality to SSH. By nature, it is not encrypted, and does not provide support for file transfer. As far as graphics are concerned, Guacamole’s telnet support works in the same manner as SSH: it emulates a terminal on the server side which renders to the Guacamole client’s display. Telnet support for Guacamole is provided by the libguac-client-telnet library, which will be installed as part of guacamole-server if the required dependencies are present during the build. <div class="admonition note"> Note In addition to the telnet-specific parameters below, Guacamole’s telnet support also accepts the parameters of several features that Guacamole provides for multiple protocols: <ul class="simple"> <li><a class="reference internal" href="#disable-clipboard">Disabling clipboard access</a></li> <li><a class="reference internal" href="#graphical-recording">Graphical session recording</a></li> <li><a class="reference internal" href="#typescripts">Text session recording (typescripts)</a></li> <li><a class="reference internal" href="#stdin-pipe">Providing terminal input directly from JavaScript</a></li> <li><a class="reference internal" href="#terminal-behavior">Controlling terminal behavior</a></li> <li><a class="reference internal" href="#terminal-display-settings">Terminal display settings</a></li> <li><a class="reference internal" href="#wake-on-lan">Wake-on-LAN</a></li> </ul> </div> <section id="telnet-network-parameters"> <h4>Network parameters<a class="headerlink" href="#telnet-network-parameters" title="Link to this heading"></a></h4> Telnet connections require a hostname or IP address defining the destination machine. Telnet is standardized to use port 23 and this will be the proper value in most cases. You only need to specify the telnet port if you are not using the standard port. <dl class="simple myst"> <dt><code class="docutils literal notranslate">hostname</code></dt><dd>The hostname or IP address of the telnet server Guacamole should connect to. </dd> <dt><code class="docutils literal notranslate">port</code></dt><dd>The port the telnet server is listening on, usually 23. This parameter is optional. If this is not specified, the default of 23 will be used. </dd> </dl> </section> <section id="telnet-authentication"> <h4>Authentication<a class="headerlink" href="#telnet-authentication" title="Link to this heading"></a></h4> Telnet does not actually provide any standard means of authentication. Authentication over telnet depends entirely on the login process running on the server and is interactive. To cope with this, Guacamole provides non-standard mechanisms for automatically passing the username and entering password. Whether these mechanisms work depends on specific login process used by your telnet server. The de-facto method for passing the username automatically via telnet is to submit it via the <code class="docutils literal notranslate">USER</code> environment variable, sent using the NEW-ENVIRON option. This is the mechanism used by most telnet clients, typically via the <code class="docutils literal notranslate">-l</code> command-line option. Passwords cannot typically be sent automatically - at least not as reliably as the username. There is no <code class="docutils literal notranslate">PASSWORD</code> environment variable (this would actually be a horrible idea) nor any similar mechanism for passing the password to the telnet login process, and most telnet clients provide no built-in support for automatically entering the password. The best that can be done is to heuristically detect the password prompt, and type the password on behalf of the user when the prompt appears. The prescribed method for doing this with a traditional command-line telnet is to use a utility like <code class="docutils literal notranslate">expect</code>. Guacamole provides similar functionality by searching for the password prompt with a regular expression. If Guacamole receives a line of text which matches the regular expression, the password is automatically sent. If no such line is ever received, the password is not sent, and the user must type the password manually. Pressing any key during this process cancels the heuristic password prompt detection. If the password prompt is not being detected properly, you can try using your own regular expression by specifying it within the <code class="docutils literal notranslate">password-regex</code> parameter. The regular expression must be written in the POSIX ERE dialect (the dialect typically used by <code class="docutils literal notranslate">egrep</code>). <dl class="simple myst"> <dt><code class="docutils literal notranslate">username</code></dt><dd>The username to use to authenticate, if any. This parameter is optional. If not specified, or not supported by the telnet server, the login process on the telnet server will prompt you for your credentials. For this to work, your telnet server must support the NEW-ENVIRON option, and the telnet login process must pay attention to the <code class="docutils literal notranslate">USER</code> environment variable. Most telnet servers satisfy this criteria. </dd> <dt><code class="docutils literal notranslate">password</code></dt><dd>The password to use when attempting authentication, if any. This parameter is optional. If specified, your password will be typed on your behalf when the password prompt is detected. </dd> <dt><code class="docutils literal notranslate">username-regex</code></dt><dd>The regular expression to use when waiting for the username prompt. This parameter is optional. If not specified, a reasonable default built into Guacamole will be used. The regular expression must be written in the POSIX ERE dialect (the dialect typically used by <code class="docutils literal notranslate">egrep</code>). </dd> <dt><code class="docutils literal notranslate">password-regex</code></dt><dd>The regular expression to use when waiting for the password prompt. This parameter is optional. If not specified, a reasonable default built into Guacamole will be used. The regular expression must be written in the POSIX ERE dialect (the dialect typically used by <code class="docutils literal notranslate">egrep</code>). </dd> <dt><code class="docutils literal notranslate">login-success-regex</code></dt><dd>The regular expression to use when detecting that the login attempt has succeeded. This parameter is optional. If specified, the terminal display will not be shown to the user until text matching this regular expression has been received from the telnet server. The regular expression must be written in the POSIX ERE dialect (the dialect typically used by <code class="docutils literal notranslate">egrep</code>). </dd> <dt><code class="docutils literal notranslate">login-failure-regex</code></dt><dd>The regular expression to use when detecting that the login attempt has failed. This parameter is optional. If specified, the connection will be closed with an explicit login failure error if text matching this regular expression has been received from the telnet server. The regular expression must be written in the POSIX ERE dialect (the dialect typically used by <code class="docutils literal notranslate">egrep</code>). </dd> </dl> </section> <section id="adding-a-telnet-connection"> <h4>Adding a telnet connection<a class="headerlink" href="#adding-a-telnet-connection" title="Link to this heading"></a></h4> If you are using the default authentication built into Guacamole, and you wish to grant access to a telnet connection to a particular user, you need to locate the <code class="docutils literal notranslate"><authorize></code> section for that user within your <code class="docutils literal notranslate">user-mapping.xml</code>, and add a section like the following within it: <div class="highlight-xml notranslate"><div class="highlight"><pre><connection name="Unique Name"> <protocol>telnet</protocol> <param name="hostname">localhost</param> <param name="port">23</param> </connection> </pre></div> </div> If added exactly as above, a new connection named “<code class="docutils literal notranslate">Unique Name</code>” will be available to the user associated with the <code class="docutils literal notranslate"><authorize></code> section containing it. The connection will use telnet to connect to localhost at port 23. Naturally, you will want to change some or all of these values. As telnet is inherently insecure compared to SSH, you should use SSH instead wherever possible. If Guacamole is set up to use HTTPS then communication with the Guacamole client will be encrypted, but communication between guacd and the telnet server will still be unencrypted. You should not use telnet unless the network between guacd and the telnet server is trusted. </section> </section> <section id="kubernetes"> <h3>Kubernetes<a class="headerlink" href="#kubernetes" title="Link to this heading"></a></h3> Kubernetes provides an API for attaching to the console of a container over the network. As with SSH and telnet, Guacamole’s Kubernetes support emulates a terminal on the server side which renders to the Guacamole client’s display. Kubernetes support for Guacamole is provided by the libguac-client-kubernetes library, which will be installed as part of guacamole-server if the required dependencies are present during the build. <div class="admonition note"> Note In addition to the Kubernetes-specific parameters below, Guacamole’s Kubernetes support also accepts the parameters of several features that Guacamole provides for multiple protocols: <ul class="simple"> <li><a class="reference internal" href="#disable-clipboard">Disabling clipboard access</a></li> <li><a class="reference internal" href="#graphical-recording">Graphical session recording</a></li> <li><a class="reference internal" href="#typescripts">Text session recording (typescripts)</a></li> <li><a class="reference internal" href="#stdin-pipe">Providing terminal input directly from JavaScript</a></li> <li><a class="reference internal" href="#terminal-behavior">Controlling terminal behavior</a></li> <li><a class="reference internal" href="#terminal-display-settings">Terminal display settings</a></li> <li><a class="reference internal" href="#wake-on-lan">Wake-on-LAN</a></li> </ul> </div> <section id="network-container-parameters"> <h4>Network/Container parameters<a class="headerlink" href="#network-container-parameters" title="Link to this heading"></a></h4> Attaching to a Kubernetes container requires the hostname or IP address of the Kubernetes server and the name of the pod containing the container in question. By default, Guacamole will attach to the first container in the pod. If there are multiple containers in the pod, you may wish to also specify the container name. <dl class="simple myst"> <dt><code class="docutils literal notranslate">hostname</code></dt><dd>The hostname or IP address of the Kubernetes server that Guacamole should connect to. </dd> <dt><code class="docutils literal notranslate">port</code></dt><dd>The port the Kubernetes server is listening on for API connections. This parameter is optional. If omitted, port 8080 will be used by default. </dd> <dt><code class="docutils literal notranslate">namespace</code></dt><dd>The name of the Kubernetes namespace of the pod containing the container being attached to. This parameter is optional. If omitted, the namespace “default” will be used. </dd> <dt><code class="docutils literal notranslate">pod</code></dt><dd>The name of the Kubernetes pod containing with the container being attached to. </dd> <dt><code class="docutils literal notranslate">container</code></dt><dd>The name of the container to attach to. This parameter is optional. If omitted, the first container in the pod will be used. </dd> <dt><code class="docutils literal notranslate">exec-command</code></dt><dd>The command to run within the container, with input and output attached to this command’s process. This parameter is optional. If omitted, no command will be run, and input/output will instead be attached to the main process of the container. When this parameter is specified, the behavior of the connection is analogous to running kubectl exec. When omitted, the behavior is analogous to running kubectl attach. </dd> </dl> </section> <section id="authentication-and-ssl-tls"> <h4>Authentication and SSL/TLS<a class="headerlink" href="#authentication-and-ssl-tls" title="Link to this heading"></a></h4> If enabled, Kubernetes uses SSL/TLS for both encryption and authentication. Standard SSL/TLS client authentication requires both a client certificate and client key, which Guacamole will use to identify itself to the Kubernetes server. If the certificate used by Kubernetes is self-signed or signed by a non-standard certificate authority, the certificate for the certificate authority will also be needed. <dl class="simple myst"> <dt><code class="docutils literal notranslate">use-ssl</code></dt><dd>If set to “true”, SSL/TLS will be used to connect to the Kubernetes server. This parameter is optional. By default, SSL/TLS will not be used. </dd> <dt><code class="docutils literal notranslate">client-cert</code></dt><dd>The certificate to use if performing SSL/TLS client authentication to authenticate with the Kubernetes server, in PEM format. This parameter is optional. If omitted, SSL client authentication will not be performed. </dd> <dt><code class="docutils literal notranslate">client-key</code></dt><dd>The key to use if performing SSL/TLS client authentication to authenticate with the Kubernetes server, in PEM format. This parameter is optional. If omitted, SSL client authentication will not be performed. </dd> <dt><code class="docutils literal notranslate">ca-cert</code></dt><dd>The certificate of the certificate authority that signed the certificate of the Kubernetes server, in PEM format. This parameter is optional. If omitted, verification of the Kubernetes server certificate will use only system-wide certificate authorities. </dd> <dt><code class="docutils literal notranslate">ignore-cert</code></dt><dd>If set to “true”, the validity of the SSL/TLS certificate used by the Kubernetes server will be ignored if it cannot be validated. This parameter is optional. By default, SSL/TLS certificates are validated. </dd> </dl> </section> <section id="adding-a-kubernetes-connection"> <h4>Adding a Kubernetes connection<a class="headerlink" href="#adding-a-kubernetes-connection" title="Link to this heading"></a></h4> If you are using the default authentication built into Guacamole, and you wish to grant access to a Kubernetes connection to a particular user, you need to locate the <code class="docutils literal notranslate"><authorize></code> section for that user within your <code class="docutils literal notranslate">user-mapping.xml</code>, and add a section like the following within it: <div class="highlight-xml notranslate"><div class="highlight"><pre><connection name="Unique Name"> <protocol>kubernetes</protocol> <param name="hostname">localhost</param> <param name="pod">mypod</param> </connection> </pre></div> </div> If added exactly as above, a new connection named “<code class="docutils literal notranslate">Unique Name</code>” will be available to the user associated with the <code class="docutils literal notranslate"><authorize></code> section containing it. The connection will connect to the Kubernetes server running on localhost and attach to the first container of the pod “mypod”. </section> </section> <section id="common-configuration-options"> <h3>Common configuration options<a class="headerlink" href="#common-configuration-options" title="Link to this heading"></a></h3> <section id="disabling-clipboard-access"> <h4>Disabling clipboard access<a class="headerlink" href="#disabling-clipboard-access" title="Link to this heading"></a></h4> Guacamole provides bidirectional access to the clipboard by default for all supported protocols. For protocols that don’t inherently provide a clipboard, Guacamole implements its own clipboard. This behavior can be overridden on a per-connection basis with the <code class="docutils literal notranslate">disable-copy</code> and <code class="docutils literal notranslate">disable-paste</code> parameters. <dl class="simple myst"> <dt><code class="docutils literal notranslate">disable-copy</code></dt><dd>If set to “true”, text copied within the remote desktop session will not be accessible by the user at the browser side of the Guacamole session, and will be usable only within the remote desktop. This parameter is optional. By default, the user will be given access to the copied text. </dd> <dt><code class="docutils literal notranslate">disable-paste</code></dt><dd>If set to “true”, text copied at the browser side of the Guacamole session will not be accessible within the remote ddesktop session. This parameter is optional. By default, the user will be able to paste data from outside the browser within the remote desktop session. </dd> </dl> </section> <section id="file-transfer-via-sftp"> <h4>File transfer via SFTP<a class="headerlink" href="#file-transfer-via-sftp" title="Link to this heading"></a></h4> Guacamole can provide file transfer over SFTP even when the remote desktop is otherwise being accessed through a different protocol, like VNC or RDP. If SFTP is enabled on a Guacamole RDP connection, users will be able to upload and download files as described in <a class="reference internal" href="using-guacamole.html">Using Guacamole</a>. This support is independent of the file transfer that may be provided by the protocol in use, like RDP’s own “drive redirection” (RDPDR), and is particularly useful for remote desktop servers which do not support file transfer features. <dl class="simple myst"> <dt><code class="docutils literal notranslate">enable-sftp</code></dt><dd>Whether file transfer should be enabled. If set to “true”, the user will be allowed to upload or download files from the specified server using SFTP. If omitted, SFTP will be disabled. </dd> <dt><code class="docutils literal notranslate">sftp-hostname</code></dt><dd>The hostname or IP address of the server hosting SFTP. This parameter is optional. If omitted, the hostname of the remote desktop server associated with the connection will be used. </dd> <dt><code class="docutils literal notranslate">sftp-port</code></dt><dd>The port the SSH server providing SFTP is listening on, usually 22. This parameter is optional. If omitted, the standard port of 22 will be used. </dd> <dt><code class="docutils literal notranslate">sftp-host-key</code></dt><dd>The known hosts entry for the SFTP server. This parameter is optional, and, if not provided, no verification of SFTP host identity will be done. If the parameter is provided the identity of the server will be checked against the data. The format of this parameter is that of a single entry from an OpenSSH <code class="docutils literal notranslate">known_hosts</code> file. For more information, please see <a class="reference internal" href="#ssh-host-verification">SSH Host Verification</a>. </dd> <dt><code class="docutils literal notranslate">sftp-username</code></dt><dd>The username to authenticate as when connecting to the specified SSH server for SFTP. This parameter is optional if a username is specified for the remote desktop connection. If omitted, the username specified for the remote desktop connection will be used. </dd> <dt><code class="docutils literal notranslate">sftp-password</code></dt><dd>The password to use when authenticating with the specified SSH server for SFTP. </dd> <dt><code class="docutils literal notranslate">sftp-private-key</code></dt><dd>The entire contents of the private key to use for public key authentication. If this parameter is not specified, public key authentication will not be used. The private key must be in OpenSSH format, as would be generated by the OpenSSH ssh-keygen utility. </dd> <dt><code class="docutils literal notranslate">sftp-passphrase</code></dt><dd>The passphrase to use to decrypt the private key for use in public key authentication. This parameter is not needed if the private key does not require a passphrase. </dd> <dt><code class="docutils literal notranslate">sftp-directory</code></dt><dd>The directory to upload files to if they are simply dragged and dropped, and thus otherwise lack a specific upload location. This parameter is optional. If omitted, the default upload location of the SSH server providing SFTP will be used. </dd> <dt><code class="docutils literal notranslate">sftp-root-directory</code></dt><dd>The directory to expose to connected users via Guacamole’s <a class="reference internal" href="using-guacamole.html#file-browser">Using the file browser</a>. If omitted, the root directory will be used by default. </dd> <dt><code class="docutils literal notranslate">sftp-server-alive-interval</code></dt><dd>The interval in seconds at which to send keepalive packets to the SSH server for the SFTP connection. This parameter is optional. If omitted, the default of 0 will be used, disabling sending keepalive packets. The minimum value is 2. </dd> <dt><code class="docutils literal notranslate">sftp-disable-download</code></dt><dd>If set to true downloads from the remote system to the client (browser) will be disabled. The default is false, which means that downloads will be enabled. If sftp is not enabled, this parameter will be ignored. </dd> <dt><code class="docutils literal notranslate">sftp-disable-upload</code></dt><dd>If set to true uploads from the client (browser) to the remote system will be disabled. The default is false, which means that uploads will be enabled. If sftp is not enabled, this parameter will be ignored. </dd> </dl> </section> <section id="graphical-session-recording"> <h4>Graphical session recording<a class="headerlink" href="#graphical-session-recording" title="Link to this heading"></a></h4> Sessions of all supported protocols can be recorded graphically. These recordings take the form of Guacamole protocol dumps and are recorded automatically to a specified directory. Recordings can be subsequently <a class="reference internal" href="recording-playback.html">played back directly in the browser from the connection history screen</a> or translated to a normal video stream using the guacenc utility provided with guacamole-server. For example, to produce a video called <code class="samp docutils literal notranslate">NAME.m4v</code> from the recording “<code class="docutils literal notranslate">NAME</code>”, you would run: <div class="highlight-console notranslate"><div class="highlight"><pre>$ guacenc /path/to/recording/NAME </pre></div> </div> The guacenc utility has additional options for overriding default behavior, including tweaking the output format, which are documented in detail within the manpage: <div class="highlight-console notranslate"><div class="highlight"><pre>$ man guacenc </pre></div> </div> If recording of key events is explicitly enabled using the <code class="docutils literal notranslate">recording-include-keys</code> parameter, recordings can also be translated into human-readable interpretations of the keys pressed during the session using the guaclog utility. The usage of guaclog is analogous to guacenc, and results in the creation of a new text file containing the interpreted events: <div class="highlight-console notranslate"><div class="highlight"><pre>$ guaclog /path/to/recording/NAME guaclog: INFO: Guacamole input log interpreter (guaclog) version 1.5.5 guaclog: INFO: 1 input file(s) provided. guaclog: INFO: Writing input events from "/path/to/recording/NAME" to "/path/to/recording/NAME.txt" ... guaclog: INFO: All files interpreted successfully. $ </pre></div> </div> <div class="admonition important"> Important Guacamole will never overwrite an existing recording. If necessary, a numeric suffix like “.1”, “.2”, “.3”, etc. will be appended to <NAME> to avoid overwriting an existing recording. If even appending a numeric suffix does not help, the session will simply not be recorded. </div> <dl class="simple myst"> <dt><code class="docutils literal notranslate">recording-path</code></dt><dd>The directory in which screen recording files should be created. If a graphical recording needs to be created, then this parameter is required. Specifying this parameter enables graphical screen recording. If this parameter is omitted, no graphical recording will be created. </dd> <dt><code class="docutils literal notranslate">create-recording-path</code></dt><dd>If set to “true”, the directory specified by the <code class="docutils literal notranslate">recording-path</code> parameter will automatically be created if it does not yet exist. Only the final directory in the path will be created - if other directories earlier in the path do not exist, automatic creation will fail, and an error will be logged. This parameter is optional. By default, the directory specified by the <code class="docutils literal notranslate">recording-path</code> parameter will not automatically be created, and attempts to create recordings within a non-existent directory will be logged as errors. This parameter only has an effect if graphical recording is enabled. If the <code class="docutils literal notranslate">recording-path</code> is not specified, graphical session recording will be disabled, and this parameter will be ignored. </dd> <dt><code class="docutils literal notranslate">recording-name</code></dt><dd>The filename to use for any created recordings. This parameter is optional. If omitted, the value “recording” will be used instead. This parameter only has an effect if graphical recording is enabled. If the <code class="docutils literal notranslate">recording-path</code> is not specified, graphical session recording will be disabled, and this parameter will be ignored. </dd> <dt><code class="docutils literal notranslate">recording-exclude-output</code></dt><dd>If set to “true”, graphical output and other data normally streamed from server to client will be excluded from the recording, producing a recording which contains only user input events. This parameter is optional. If omitted, graphical output will be included in the recording. This parameter only has an effect if graphical recording is enabled. If the <code class="docutils literal notranslate">recording-path</code> is not specified, graphical session recording will be disabled, and this parameter will be ignored. </dd> <dt><code class="docutils literal notranslate">recording-exclude-mouse</code></dt><dd>If set to “true”, user mouse events will be excluded from the recording, producing a recording which lacks a visible mouse cursor. This parameter is optional. If omitted, mouse events will be included in the recording. This parameter only has an effect if graphical recording is enabled. If the <code class="docutils literal notranslate">recording-path</code> is not specified, graphical session recording will be disabled, and this parameter will be ignored. </dd> <dt><code class="docutils literal notranslate">recording-include-keys</code></dt><dd>If set to “true”, user key events will be included in the recording. The recording can subsequently be passed through the guaclog utility to produce a human-readable interpretation of the keys pressed during the session. This parameter is optional. If omitted, key events will be not included in the recording. This parameter only has an effect if graphical recording is enabled. If the <code class="docutils literal notranslate">recording-path</code> is not specified, graphical session recording will be disabled, and this parameter will be ignored. </dd> </dl> </section> <section id="text-session-recording-typescripts"> <h4>Text session recording (typescripts)<a class="headerlink" href="#text-session-recording-typescripts" title="Link to this heading"></a></h4> The full, raw text content of SSH sessions, including timing information, can be recorded automatically to a specified directory. This recording, also known as a “typescript”, will be written to two files within the directory specified by <code class="docutils literal notranslate">typescript-path</code>: <code class="samp docutils literal notranslate">NAME</code>, which contains the raw text data, and <code class="samp docutils literal notranslate">NAME.timing</code>, which contains timing information, where <code class="docutils literal notranslate">NAME</code> is the value provided for the <code class="docutils literal notranslate">typescript-name</code> parameter. This format is compatible with the format used by the standard UNIX script command, and can be replayed using scriptreplay (if installed). For example, to replay a typescript called “<code class="docutils literal notranslate">NAME</code>”, you would run: <div class="highlight-console notranslate"><div class="highlight"><pre>$ scriptreplay NAME.timing NAME </pre></div> </div> <div class="admonition important"> Important Guacamole will never overwrite an existing recording. If necessary, a numeric suffix like “.1”, “.2”, “.3”, etc. will be appended to <code class="docutils literal notranslate">NAME</code> to avoid overwriting an existing recording. If even appending a numeric suffix does not help, the session will simply not be recorded. </div> <dl class="simple myst"> <dt><code class="docutils literal notranslate">typescript-path</code></dt><dd>The directory in which typescript files should be created. If a typescript needs to be recorded, this parameter is required. Specifying this parameter enables typescript recording. If this parameter is omitted, no typescript will be recorded. </dd> <dt><code class="docutils literal notranslate">create-typescript-path</code></dt><dd>If set to “true”, the directory specified by the <code class="docutils literal notranslate">typescript-path</code> parameter will automatically be created if it does not yet exist. Only the final directory in the path will be created - if other directories earlier in the path do not exist, automatic creation will fail, and an error will be logged. This parameter is optional. By default, the directory specified by the <code class="docutils literal notranslate">typescript-path</code> parameter will not automatically be created, and attempts to record typescripts in a non-existent directory will be logged as errors. This parameter only has an effect if typescript recording is enabled. If the <code class="docutils literal notranslate">typescript-path</code> is not specified, recording of typescripts will be disabled, and this parameter will be ignored. </dd> <dt><code class="docutils literal notranslate">typescript-name</code></dt><dd>The base filename to use when determining the names for the data and timing files of the typescript. This parameter is optional. If omitted, the value “typescript” will be used instead. Each typescript consists of two files which are created within the directory specified by <code class="docutils literal notranslate">typescript-path</code>: <code class="samp docutils literal notranslate">NAME</code>, which contains the raw text data, and <code class="samp docutils literal notranslate">NAME.timing</code>, which contains timing information, where <code class="docutils literal notranslate">NAME</code> is the value provided for the <code class="docutils literal notranslate">typescript-name</code> parameter. This parameter only has an effect if typescript recording is enabled. If the <code class="docutils literal notranslate">typescript-path</code> is not specified, recording of typescripts will be disabled, and this parameter will be ignored. </dd> </dl> </section> <section id="controlling-terminal-behavior"> <h4>Controlling terminal behavior<a class="headerlink" href="#controlling-terminal-behavior" title="Link to this heading"></a></h4> In most cases, the default behavior for a terminal works without modification. However, when connecting to certain systems, particularly operating systems other than Linux, the terminal behavior may need to be tweaked to allow it to operate properly. The settings in this section control that behavior. <dl class="simple myst"> <dt><code class="docutils literal notranslate">backspace</code></dt><dd>This parameter controls the ASCII code that the backspace key sends to the remote system. Under most circumstances this should not need to be adjusted; however, if, when pressing the backspace key, you see control characters (often either ^? or ^H) instead of seeing the text erased, you may need to adjust this parameter. By default the terminal sends ASCII code 127 (Delete) if this option is not set. </dd> <dt><code class="docutils literal notranslate">terminal-type</code></dt><dd>This parameter sets the terminal emulator type string that is passed to the server. This parameter is optional. If not specified, “<code class="docutils literal notranslate">linux</code>” is used as the terminal emulator type by default. </dd> </dl> <section id="providing-terminal-input-directly-from-javascript"> <h5>Providing terminal input directly from JavaScript<a class="headerlink" href="#providing-terminal-input-directly-from-javascript" title="Link to this heading"></a></h5> If Guacamole is being used in part to automate an SSH, telnet, or other terminal session, it can be useful to provide input directly from JavaScript as a raw stream of data, rather than attempting to translate data into keystrokes. This can be done through opening a pipe stream named “STDIN” within the connection using the <a class="reference external" href="http://guacamole.apache.org/doc/guacamole-common-js/Guacamole.Client.html#createPipeStream"><code class="docutils literal notranslate">createPipeStream()</code></a> function of <a class="reference external" href="http://guacamole.apache.org/doc/guacamole-common-js/Guacamole.Client.html"><code class="docutils literal notranslate">Guacamole.Client</code></a>: <div class="highlight-javascript notranslate"><div class="highlight"><pre>var outputStream = client.createPipeStream('text/plain', 'STDIN'); </pre></div> </div> The resulting <a class="reference external" href="http://guacamole.apache.org/doc/guacamole-common-js/Guacamole.OutputStream.html"><code class="docutils literal notranslate">Guacamole.OutputStream</code></a> can then be used to stream data directly to the input of the terminal session, as if typed by the user: <div class="highlight-javascript notranslate"><div class="highlight"><pre>// Wrap output stream in writer var writer = new Guacamole.StringWriter(outputStream); // Send text writer.sendText("hello"); // Send more text writer.sendText("world"); // Close writer and stream writer.sendEnd(); </pre></div> </div> </section> </section> <section id="terminal-display-settings"> <h4>Terminal display settings<a class="headerlink" href="#terminal-display-settings" title="Link to this heading"></a></h4> Guacamole’s terminal emulator (used by SSH, telnet, and Kubernetes support) provides options for configuring the font used and its size. In this case, the chosen font must be installed on the server, as it is the server that will handle rendering of characters to the terminal display, not the client. <dl class="simple myst"> <dt><code class="docutils literal notranslate">color-scheme</code></dt><dd>The color scheme to use for the terminal session. It consists of a semicolon-separated series of name-value pairs. Each name-value pair is separated by a colon and assigns a value to a color in the terminal emulator palette. For example, to use blue text on white background by default, and change the red color to a purple shade, you would specify: <div class="highlight-none notranslate"><div class="highlight"><pre>foreground: rgb:00/00/ff; background: rgb:ff/ff/ff; color9: rgb:80/00/80 </pre></div> </div> This format is similar to the color configuration format used by Xterm, so Xterm color configurations can be easily adapted for Guacamole. This parameter is optional. If not specified, Guacamole will render text as gray over a black background. Possible color names are: <dl class="simple myst"> <dt><code class="docutils literal notranslate">foreground</code></dt><dd>Set the default foreground color. </dd> <dt><code class="docutils literal notranslate">background</code></dt><dd>Set the default background color. </dd> <dt><code class="samp docutils literal notranslate">colorN</code></dt><dd>Set the color at index <code class="docutils literal notranslate">N</code> on the Xterm 256-color palette. For example, <code class="docutils literal notranslate">color9</code> refers to the red color. </dd> </dl> Possible color values are: <dl class="simple myst"> <dt><code class="samp docutils literal notranslate">rgb:RR/GG/BB</code></dt><dd>Use the specified color in RGB format, with each component in hexadecimal. For example, <code class="docutils literal notranslate">rgb:ff/00/00</code> specifies the color red. Note that each hexadecimal component can be one to four digits, but the effective values are always zero-extended or truncated to two digits; for example, <code class="docutils literal notranslate">rgb:f/8/0</code>, <code class="docutils literal notranslate">rgb:f0/80/00</code>, and <code class="docutils literal notranslate">rgb:f0f/808/00f</code> all refer to the same effective color. </dd> <dt><code class="samp docutils literal notranslate">colorN</code></dt><dd>Use the color currently assigned to index <code class="docutils literal notranslate">N</code> on the Xterm 256-color palette. For example, <code class="docutils literal notranslate">color9</code> specifies the current red color. Note that the color value is used rather than the color reference, so if <code class="docutils literal notranslate">color9</code> is changed later in the color scheme configuration, that new color will not be reflected in this assignment. </dd> </dl> For backward compatibility, Guacamole will also accept four special values as the color scheme parameter: <dl class="simple myst"> <dt><code class="docutils literal notranslate">black-white</code></dt><dd>Black text over a white background. </dd> <dt><code class="docutils literal notranslate">gray-black</code></dt><dd>Gray text over a black background. This is the default color scheme. </dd> <dt><code class="docutils literal notranslate">green-black</code></dt><dd>Green text over a black background. </dd> <dt><code class="docutils literal notranslate">white-black</code></dt><dd>White text over a black background. </dd> </dl> </dd> <dt><code class="docutils literal notranslate">font-name</code></dt><dd>The name of the font to use. This parameter is optional. If not specified, the default of “monospace” will be used instead. </dd> <dt><code class="docutils literal notranslate">font-size</code></dt><dd>The size of the font to use, in points. This parameter is optional. If not specified, the default of 12 will be used instead. </dd> <dt><code class="docutils literal notranslate">scrollback</code></dt><dd>The maximum number of rows to allow within the terminal scrollback buffer. This parameter is optional. If not specified, the scrollback buffer will be limited to a maximum of 1000 rows. </dd> </dl> </section> <section id="wake-on-lan"> <h4>Wake-on-LAN<a class="headerlink" href="#wake-on-lan" title="Link to this heading"></a></h4> Guacamole implements the support to send a “magic wake-on-lan packet” to a remote host prior to attempting to establish a connection with the host. The below parameters control the behavior of this functionality, which is disabled by default. <div class="admonition important"> Important There are several factors that can impact the ability of Wake-on-LAN (WoL) to function correctly, many of which are outside the scope of Guacamole configuration. If you are configuring WoL within Guacamole you should also be familiar with the other components that need to be configured in order for it to function correctly. </div> <dl class="simple myst"> <dt><code class="docutils literal notranslate">wol-send-packet</code></dt><dd>If set to “true”, Guacamole will attempt to send the Wake-On-LAN packet prior to establishing a connection. This parameter is optional. By default, Guacamole will not send the WoL packet. Enabling this option requires that the <code class="docutils literal notranslate">wol-mac-addr</code> parameter also be configured, otherwise the WoL packet will not be sent. </dd> <dt><code class="docutils literal notranslate">wol-mac-addr</code></dt><dd>This parameter configures the MAC address that Guacamole will use in the magic WoL packet to attempt to wake the remote system. If <code class="docutils literal notranslate">wol-send-packet</code> is enabled, this parameter is required or else the WoL packet will not be sent. </dd> <dt><code class="docutils literal notranslate">wol-broadcast-addr</code></dt><dd>This parameter configures the IPv4 broadcast address or IPv6 multicast address that Guacamole will send the WoL packet to in order to wake the host. This parameter is optional. If no value is provided, the default local IPv4 broadcast address (255.255.255.255) will be used. </dd> <dt><code class="docutils literal notranslate">wol-udp-port</code></dt><dd>This parameter configures the UDP port that will be set in the WoL packet. In most cases the UDP port isn’t processed by the system that will be woken up; however, there are certain cases where it is useful for the port to be set, as in situations where a router is listening for the packet and can make routing decisions depending upon the port that is used. If not configured the default UDP port 9 will be used. </dd> <dt><code class="docutils literal notranslate">wol-wait-time</code></dt><dd>By default after the WoL packet is sent Guacamole will attempt immediately to connect to the remote host. It may be desirable in certain scenarios to have Guacamole wait before the initial connection in order to give the remote system time to boot. Setting this parameter to a positive value will cause Guacamole to wait the specified number of seconds before attempting the initial connection. This parameter is optional. </dd> </dl> </section> </section> <section id="parameter-tokens"> <h3>Parameter tokens<a class="headerlink" href="#parameter-tokens" title="Link to this heading"></a></h3> The values of connection parameters can contain “tokens” which will be replaced by Guacamole when used. These tokens allow the values of connection parameters to vary dynamically by the user using the connection, and provide a simple means of forwarding authentication information without storing that information in the connection configuration itself, so long as the remote desktop connection uses the same credentials as Guacamole. Each token is of the form <code class="samp docutils literal notranslate">${TOKEN_NAME}</code> or <code class="samp docutils literal notranslate">${TOKEN_NAME:MODIFIER}</code>, where <code class="docutils literal notranslate">TOKEN_NAME</code> is some descriptive name for the value the token represents, and the optional <code class="docutils literal notranslate">MODIFIER</code> is one of the modifiers documented below to dynamically modify the token. Tokens with no corresponding value will never be replaced, but should you need such text within your connection parameters, and wish to guarantee that this text will not be replaced with a token value, you can escape the token by adding an additional leading “$”, as in “<code class="samp docutils literal notranslate">$${TOKEN_NAME}</code>”. <dl class="simple myst"> <dt><code class="docutils literal notranslate">${GUAC_USERNAME}</code></dt><dd>The username of the current Guacamole user. When a user accesses a connection, this token will be dynamically replaced with the username they provided when logging in to Guacamole. </dd> <dt><code class="docutils literal notranslate">${GUAC_PASSWORD}</code></dt><dd>The password of the current Guacamole user. When a user accesses a connection, this token will be dynamically replaced with the password they used when logging in to Guacamole. </dd> <dt><code class="docutils literal notranslate">${GUAC_CLIENT_ADDRESS}</code></dt><dd>The IPv4 or IPv6 address of the current Guacamole user. This will be the address of the client side of the HTTP connection to the Guacamole server at the time the current user logged in. </dd> <dt><code class="docutils literal notranslate">${GUAC_CLIENT_HOSTNAME}</code></dt><dd>The hostname of the current Guacamole user. This will be the hostname of the client side of the HTTP connection to the Guacamole server at the time the current user logged in. If no such hostname can be determined, the IPv4 or IPv6 address will be used instead, and this token will be equivalent to <code class="docutils literal notranslate">${GUAC_CLIENT_ADDRESS}</code>. </dd> <dt><code class="docutils literal notranslate">${GUAC_DATE}</code></dt><dd>The current date in the local time zone of the Guacamole server. This will be written in “YYYYMMDD” format, where “YYYY” is the year, “MM” is the month number, and “DD” is the day of the month, all zero-padded. When a user accesses a connection, this token will be dynamically replaced with the date that the connection began. </dd> <dt><code class="docutils literal notranslate">${GUAC_TIME}</code></dt><dd>The current time in the local time zone of the Guacamole server. This will be written in “HHMMSS” format, where “HH” is hours in 24-hour time, “MM” is minutes, and “SS” is seconds, all zero-padded. When a user accesses a connection, this token will be dynamically replaced with the time that the connection began. </dd> </dl> Note that these tokens are replaced dynamically each time a connection is used. If two different users access the same connection at the same time, both users will be connected independently of each other using different sets of connection parameters. <section id="token-modifiers"> <h4>Token modifiers<a class="headerlink" href="#token-modifiers" title="Link to this heading"></a></h4> At times it can be useful to use the value provided by a token, but with slight modifications. These modifers are optionally specified at the end of the token, separated from the token name by a colon (<code class="docutils literal notranslate">:</code>), in the format <code class="samp docutils literal notranslate">${TOKEN_NAME:MODIFIER}</code>. The following modifiers are currently supported: <dl class="simple myst"> <dt><code class="docutils literal notranslate">LOWER</code></dt><dd>Convert the entire value of the token to lower-case. This can be useful in situations where users log in to Guacamole with a mixed-case username, but a remote system requires the username be lower-case. </dd> <dt><code class="docutils literal notranslate">UPPER</code></dt><dd>Convert the entire value of the token to upper-case. </dd> </dl> </section> <section id="extension-specific-tokens"> <h4>Extension-specific tokens<a class="headerlink" href="#extension-specific-tokens" title="Link to this heading"></a></h4> Each extension can also implement its own arbitrary tokens that can dynamically fill in values provided by the extension. Within these extensions, attribute names are canonicalized into a standard format that consists of all capital letters separated by underscores. <section id="cas-extension-tokens"> <h5>CAS Extension Tokens<a class="headerlink" href="#cas-extension-tokens" title="Link to this heading"></a></h5> The CAS extension will read attributes provided by the CAS server when a user is authenticated and will make those attributes available as tokens. The CAS server must be specifically configured to release certain attributes to the client (Guacamole), and configuration of that is outside the scope of this document. Any attribute that the CAS server is configured to release should be available to Guacamole as a token for use within a connection. The token name will be prepended with the <code class="docutils literal notranslate">CAS_</code> prefix. A CAS server configured to release attributes <code class="docutils literal notranslate">firstname</code>, <code class="docutils literal notranslate">lastname</code>, <code class="docutils literal notranslate">email</code>, and <code class="docutils literal notranslate">mobile</code> would produce the following tokens: <ul class="simple"> <li><code class="docutils literal notranslate">${CAS_FIRSTNAME}</code></li> <li><code class="docutils literal notranslate">${CAS_LASTNAME}</code></li> <li><code class="docutils literal notranslate">${CAS_EMAIL}</code></li> <li><code class="docutils literal notranslate">${CAS_MOBILE}</code></li> </ul> </section> <section id="ldap-extension-tokens"> <h5>LDAP Extension Tokens<a class="headerlink" href="#ldap-extension-tokens" title="Link to this heading"></a></h5> The LDAP extension will read user attributes provided by the LDAP server and specified in the <code class="docutils literal notranslate">guacamole.properties</code> file. The attributes retrieved for a user are configured using the <code class="docutils literal notranslate">ldap-user-attributes</code> parameter. The user must be able to read the attribute values from their own LDAP object. The token name will be prepended with the <code class="docutils literal notranslate">LDAP_</code> prefix. As an example, configuring the following line in <code class="docutils literal notranslate">guacamole.properties</code>: <div class="highlight-none notranslate"><div class="highlight"><pre>ldap-user-attributes: cn, givenName, sn, mobile, mail </pre></div> </div> will produce the below tokens that can be used in connection parameters: <ul class="simple"> <li><code class="docutils literal notranslate">${LDAP_CN}</code></li> <li><code class="docutils literal notranslate">${LDAP_GIVENNAME}</code></li> <li><code class="docutils literal notranslate">${LDAP_SN}</code></li> <li><code class="docutils literal notranslate">${LDAP_MOBILE}</code></li> <li><code class="docutils literal notranslate">${LDAP_MAIL}</code></li> </ul> </section> </section> </section> <section id="parameter-prompting"> <h3>Parameter prompting<a class="headerlink" href="#parameter-prompting" title="Link to this heading"></a></h3> In certain situations Guacamole may determine that additional information is required in order to successfully open or continue a connection. In these scenarios guacd will send an instruction back to the client to retrieve that information, which will result in the user being prompted for those additional parameters. Currently the only parameters that will trigger this prompt to the user are authentication requests for the RDP and VNC protocols where authenticators were not provided as part of the connection configuration. <div class="admonition important"> Important It is important to note that requests for parameters will only be generated in the case where that information has not already been provided as part of the connection. The user will never be asked for parameters that replace or override connection parameters where values have been provided, including authentication information. For example, if the configuration of a connection to a RDP server specifies a username and password, and that username or password is incorrect and results in an authentication failure, Guacamole will not prompt the user for additional credentials. For RDP servers where NLA is enforced, this will result in a connection failure. Other RDP servers may behave differently and give the user the ability to try other credentials, but this is outside the control of Guacamole - Guacamole will not override pre-configured authentication values with input from the user. </div> </section> </section> <section id="configuring-guacd"> <h2>Configuring guacd<a class="headerlink" href="#configuring-guacd" title="Link to this heading"></a></h2> <section id="id12"> <h3><code class="docutils literal notranslate">guacd.conf</code><a class="headerlink" href="#id12" title="Link to this heading"></a></h3> guacd is configured with a configuration file called <code class="docutils literal notranslate">guacd.conf</code>, by default located in <code class="docutils literal notranslate">/etc/guacamole</code>. This file follows a simple, INI-like format: <div class="highlight-none notranslate"><div class="highlight"><pre># # guacd configuration file # [daemon] pid_file = /var/run/guacd.pid log_level = info [server] bind_host = localhost bind_port = 4822 # # The following parameters are valid only if # guacd was built with SSL support. # [ssl] server_certificate = /etc/ssl/certs/guacd.crt server_key = /etc/ssl/private/guacd.key </pre></div> </div> Configuration options are given as parameter/value pairs, where the name of the parameter is specified on the left side of an “<code class="docutils literal notranslate">=</code>”, and the value is specified on the right. Each parameter must occur within a proper section, indicated by a section name within brackets. The names of these sections are important; it is the pairing of a section name with a parameter that constitutes the fully-qualified parameter being set. For the sake of documentation and readability, comments can be added anywhere within guacd.conf using “<code class="docutils literal notranslate">#</code>” symbols. All text following a “<code class="docutils literal notranslate">#</code>” until end-of-line will be ignored. If you need to include special characters within the value of a parameter, such as whitespace or any of the above symbols, you can do so by placing the parameter within double quotes: <div class="highlight-none notranslate"><div class="highlight"><pre>[ssl] # Whitespace is legal within double quotes ... server_certificate = "/etc/ssl/my certs/guacd.crt" # ... as are other special symbols server_key = "/etc/ssl/#private/guacd.key" </pre></div> </div> Note that even within double quotes, some characters still have special meaning, such as the double quote itself or newline characters. If you need to include these, they must be “escaped” with a backslash: <div class="highlight-none notranslate"><div class="highlight"><pre># Parameter value containing a double quote parameter = "some\"value" # Parameter value containing newline characters parameter2 = "line1\ line2\ line3" # Parameter value containing backslashes parameter3 = "c:\\windows\\path\\to\\file.txt" </pre></div> </div> Don’t worry too much about the more complex formatting examples - they are only rarely necessary, and guacd will complain with parsing errors if the configuration file is somehow invalid. To ensure parameter values are entered correctly, just follow the following guidelines: <ol class="arabic simple"> <li>If the value contains no special characters, just include it as-is.</li> <li>If the value contains any special characters (whitespace, newlines, <code class="docutils literal notranslate">#</code>, <code class="docutils literal notranslate">\</code>, or <code class="docutils literal notranslate">"</code>), enclose the entire value within double quotes.</li> <li>If the value is enclosed within double quotes, escape newlines, <code class="docutils literal notranslate">\</code>, and <code class="docutils literal notranslate">"</code> with a backslash.</li> </ol> <section id="daemon-section"> <h4><code class="docutils literal notranslate">[daemon]</code> section<a class="headerlink" href="#daemon-section" title="Link to this heading"></a></h4> <dl class="simple myst"> <dt><code class="docutils literal notranslate">pid_file</code></dt><dd>The name of the file in which the PID of the main guacd process should be written. This is mainly needed for startup scripts, which need to monitor the state of guacd, killing it if necessary. If this parameter is specified, the user running guacd must have sufficient permissions to create or modify the specified file, or startup will fail. </dd> <dt><code class="docutils literal notranslate">log_level</code></dt><dd>The maximum level at which guacd will log messages to syslog and, if running in the foreground, the console. If omitted, the default level of <code class="docutils literal notranslate">info</code> will be used. Legal values are <code class="docutils literal notranslate">trace</code>, <code class="docutils literal notranslate">debug</code>, <code class="docutils literal notranslate">info</code>, <code class="docutils literal notranslate">warning</code>, and <code class="docutils literal notranslate">error</code>. </dd> </dl> </section> <section id="server-section"> <h4><code class="docutils literal notranslate">[server]</code> section<a class="headerlink" href="#server-section" title="Link to this heading"></a></h4> <dl class="simple myst"> <dt><code class="docutils literal notranslate">bind_host</code></dt><dd>The host that guacd should bind to when listening for connections. If unspecified, guacd will bind to localhost, and only connections from within the server hosting guacd will succeed. </dd> <dt><code class="docutils literal notranslate">bind_port</code></dt><dd>The port that guacd should bind to when listening for connections. If unspecified, port 4822 will be used. </dd> </dl> </section> <section id="ssl-section"> <h4><code class="docutils literal notranslate">[ssl]</code> section<a class="headerlink" href="#ssl-section" title="Link to this heading"></a></h4> <dl class="simple myst"> <dt><code class="docutils literal notranslate">server_certificate</code></dt><dd>The filename of the certificate to use for SSL encryption of the Guacamole protocol. If this option is specified, SSL encryption will be enabled, and the Guacamole web application will need to be configured within <code class="docutils literal notranslate">guacamole.properties</code> to use SSL as well. </dd> <dt><code class="docutils literal notranslate">server_key</code></dt><dd>The filename of the private key to use for SSL encryption of the Guacamole protocol. If this option is specified, SSL encryption will be enabled, and the Guacamole web application will need to be configured within <code class="docutils literal notranslate">guacamole.properties</code> to use SSL as well. </dd> </dl> </section> </section> <section id="command-line-options"> <h3>Command-line options<a class="headerlink" href="#command-line-options" title="Link to this heading"></a></h3> You can also affect the configuration of guacd with command-line options. If given, these options take precendence over the system-wide configuration file: <dl class="simple myst"> <dt><code class="samp docutils literal notranslate">-b HOST</code></dt><dd>Changes the host or address that guacd listens on. This corresponds to the <code class="docutils literal notranslate">bind_host</code> parameter within the <a class="reference internal" href="#guacd-conf-server"><code class="docutils literal notranslate">[server]</code> section of <code class="docutils literal notranslate">guacd.conf</code></a>. </dd> <dt><code class="samp docutils literal notranslate">-l PORT</code></dt><dd>Changes the port that guacd listens on (the default is port 4822). This corresponds to the <code class="docutils literal notranslate">bind_port</code> parameter within the <a class="reference internal" href="#guacd-conf-server"><code class="docutils literal notranslate">[server]</code> section of <code class="docutils literal notranslate">guacd.conf</code></a>. </dd> <dt><code class="samp docutils literal notranslate">-p PIDFILE</code></dt><dd>Causes guacd to write the PID of the daemon process to the specified file. This is useful for init scripts and is used by the provided init script. This corresponds to the <code class="docutils literal notranslate">pid_file</code> parameter within the <a class="reference internal" href="#guacd-conf-daemon"><code class="docutils literal notranslate">[daemon]</code> section of <code class="docutils literal notranslate">guacd.conf</code></a>. </dd> <dt><code class="samp docutils literal notranslate">-L LEVEL</code></dt><dd>Sets the maximum level at which guacd will log messages to syslog and, if running in the foreground, the console. Legal values are <code class="docutils literal notranslate">trace</code>, <code class="docutils literal notranslate">debug</code>, <code class="docutils literal notranslate">info</code>, <code class="docutils literal notranslate">warning</code>, and <code class="docutils literal notranslate">error</code>. The default value is <code class="docutils literal notranslate">info</code>. This corresponds to the <code class="docutils literal notranslate">log_level</code> parameter within the <a class="reference internal" href="#guacd-conf-daemon"><code class="docutils literal notranslate">[daemon]</code> section of <code class="docutils literal notranslate">guacd.conf</code></a>. </dd> <dt><code class="docutils literal notranslate">-f</code></dt><dd>Causes guacd to run in the foreground, rather than automatically forking into the background. </dd> </dl> If guacd was built with support for SSL, data sent via the Guacamole protocol can be encrypted with SSL if an SSL certificate and private key are given with the following options: <dl class="simple myst"> <dt><code class="samp docutils literal notranslate">-C CERTIFICATE</code></dt><dd>The filename of the certificate to use for SSL encryption of the Guacamole protocol. If this option is specified, SSL encryption will be enabled, and the Guacamole web application will need to be configured within <code class="docutils literal notranslate">guacamole.properties</code> to use SSL as well. This corresponds to the <code class="docutils literal notranslate">server_certificate</code> parameter within the <a class="reference internal" href="#guacd-conf-ssl"><code class="docutils literal notranslate">[ssl]</code> section of <code class="docutils literal notranslate">guacd.conf</code></a>. </dd> <dt><code class="samp docutils literal notranslate">-K KEY</code></dt><dd>The filename of the private key to use for SSL encryption of the Guacamole protocol. If this option is specified, SSL encryption will be enabled, and the Guacamole web application will need to be configured within <code class="docutils literal notranslate">guacamole.properties</code> to use SSL as well. This corresponds to the <code class="docutils literal notranslate">server_key</code> parameter within the <a class="reference internal" href="#guacd-conf-ssl"><code class="docutils literal notranslate">[ssl]</code> section of <code class="docutils literal notranslate">guacd.conf</code></a>. </dd> </dl> </section> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="reverse-proxy.html" class="btn btn-neutral float-left" title="Proxying Guacamole" accesskey="p" rel="prev"> Previous</a> <a href="jdbc-auth.html" class="btn btn-neutral float-right" title="Database authentication" accesskey="n" rel="next">Next </a> </div> <hr/> <div role="contentinfo"> 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. </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/1.5.5/gug/configuring-guacamole.html (2,701 lines of code) (raw):