guacamole-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jmuehl...@apache.org
Subject [05/52] [partial] incubator-guacamole-website git commit: Add 0.9.11-incubating documentation.
Date Mon, 23 Jan 2017 06:53:11 GMT
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/2441fd18/doc/0.9.11-incubating/gug/configuring-guacamole.html
----------------------------------------------------------------------
diff --git a/doc/0.9.11-incubating/gug/configuring-guacamole.html b/doc/0.9.11-incubating/gug/configuring-guacamole.html
new file mode 100644
index 0000000..b1cc286
--- /dev/null
+++ b/doc/0.9.11-incubating/gug/configuring-guacamole.html
@@ -0,0 +1,1523 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 5. Configuring Guacamole</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="users-guide.html" title="Part I. User's Guide" /><link rel="prev" href="proxying-guacamole.html" title="Chapter 4. Proxying Guacamole" /><link rel="next" href="jdbc-auth.html" title="Chapter 6. Database authentication" />
+            <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/>
+        </head><body>
+            <!-- CONTENT -->
+
+            <div id="page"><div id="content">
+        <div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 5. Configuring Guacamole</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="proxying-guacamole.html">Prev</a> </td><th width="60%" align="center">Part I. User's Guide</th><td width="20%" align="right"> <a accesskey="n" href="jdbc-auth.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="configuring-guacamole"></a>Chapter 5. Configuring Guacamole</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="configuring-guacamole.html#guacamole-home"><code class="varname">GUACAMOLE_HOME</code></a></span></dt><dt><span class="section"><a href="configuring-guacamole.html#initial-setup"><code class="filename">guacamole.properties</code></a></span></dt><dt><span class="section"><a href="
 configuring-guacamole.html#webapp-logging">Logging within the web application</a></span></dt><dt><span class="section"><a href="configuring-guacamole.html#basic-auth">Using the default authentication</a></span></dt><dd><dl><dt><span class="section"><a href="configuring-guacamole.html#user-mapping"><code class="filename">user-mapping.xml</code></a></span></dt></dl></dd><dt><span class="section"><a href="configuring-guacamole.html#connection-configuration">Configuring connections</a></span></dt><dd><dl><dt><span class="section"><a href="configuring-guacamole.html#vnc">VNC</a></span></dt><dt><span class="section"><a href="configuring-guacamole.html#rdp">RDP</a></span></dt><dt><span class="section"><a href="configuring-guacamole.html#ssh">SSH</a></span></dt><dt><span class="section"><a href="configuring-guacamole.html#telnet">Telnet</a></span></dt><dt><span class="section"><a href="configuring-guacamole.html#parameter-tokens">Parameter tokens</a></span></dt></dl></dd><dt><span class="se
 ction"><a href="configuring-guacamole.html#guacd.conf">Configuring guacd</a></span></dt></dl></div><p>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.</p><p>Guacamole's default authentication method reads all users and connections from a single
+        file called <code class="filename">user-mapping.xml</code>. This authentication method is intended to
+        be:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Sufficient for small deployments of Guacamole.</p></li><li class="listitem"><p>A relatively-easy means of verifying that Guacamole has been properly set
+                up.</p></li></ol></div><p>Other, more complex authentication methods which use backend databases, LDAP, etc. are
+        discussed in a separate, dedicated chapters.</p><p>Regardless of the authentication method you use, Guacamole's configuration always consists
+        of two main pieces: a directory referred to as <code class="varname">GUACAMOLE_HOME</code>, which is
+        the primary search location for configuration files, and
+            <code class="filename">guacamole.properties</code>, the main configuration file used by Guacamole
+        and its extensions.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="guacamole-home"></a><code class="varname">GUACAMOLE_HOME</code></h2></div></div></div><a id="idm140352911061936" class="indexterm"></a><p>Guacamole reads files from its own configuration directory by default, resorting to
+            the classpath only when this directory cannot be found. When locating this directory,
+            Guacamole will try, in order:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>The directory specified within the system property
+                        <span class="property">guacamole.home</span>.</p></li><li class="listitem"><p>The directory specified within the environment variable
+                        <code class="varname">GUACAMOLE_HOME</code>.</p></li><li class="listitem"><p>The directory <code class="filename">.guacamole</code>, located
+                    within the home directory of the user running the servlet
+                    container.</p></li></ol></div><p>This directory will be referred to as
+                <code class="varname">GUACAMOLE_HOME</code> elsewhere in the
+            documentation.</p><p>Guacamole uses <code class="varname">GUACAMOLE_HOME</code> as the primary search location for
+            configuration file like <code class="filename">guacamole.properties</code>. The structure of
+                <code class="varname">GUACAMOLE_HOME</code> is rigorously defined, and consists of the
+            following optional files:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">guacamole.properties</code></span></dt><dd><p>The main Guacamole configuration file. Properties within this file dictate
+                        how Guacamole will connect to <span class="package">guacd</span>, and may configure
+                        the behavior of installed authentication extensions.</p></dd><dt><span class="term"><code class="filename">logback.xml</code></span></dt><dd><p>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.</p></dd><dt><span class="term"><code class="filename">extensions/</code></span></dt><dd><p>The install location for all Guacamole extensions. Guacamole will
+                        automatically load all <code class="filename">.jar</code> files within this directory
+                        on startup.</p></dd><dt><span class="term"><code class="filename">lib/</code></span></dt><dd><p>The search directory for libraries required by any Guacamole extensions.
+                        Guacamole will make the <code class="filename">.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.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="initial-setup"></a><code class="filename">guacamole.properties</code></h2></div></div></div><a id="idm140352910209312" class="indexterm"></a><a id="idm140352910208144" class="indexterm"></a><p>The Guacamole web application uses one main configuration file called
+                <code class="filename">guacamole.properties</code>. This file is the common location for all
+            configuration properties read by Guacamole or any extension of Guacamole, including
+            authentication providers.</p><p>In previous releases, this file had to be in the classpath of your servlet container.
+            Now, the location of <code class="filename">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="filename">guacamole.properties</code>, Guacamole
+            will check, in order:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Within <code class="varname">GUACAMOLE_HOME</code>, as defined above.</p></li><li class="listitem"><p>The classpath of the servlet container.</p></li></ol></div><p>The <code class="filename">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:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><a id="idm140352911272784" class="indexterm"></a><em class="parameter"><code>api-session-timeout</code></em></span></dt><dd><p>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.</p></dd><dt><span class="term"><a id="idm140352911269744" class="indexterm"></a><em class="parameter"><code>available-languages</code></em></span></dt><dd><p>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:</p><div class="informalexample"><pre class="programlisting">available-languages: en, de</pre></div><p>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.</p><p>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.</p></dd><dt><span class="term"><a id="idm140352911264320" class="indexterm"></a><em class="parameter"><code>guacd-host</code></em></span></dt><dd><p>The host the Guacamole proxy daemon (<span class="package">guacd</span>) is
+                        listening on. If omitted, Guacamole will assume <span class="package">guacd</span> is
+                        listening on localhost.</p></dd><dt><span class="term"><a id="idm140352909515696" class="indexterm"></a><em class="parameter"><code>guacd-port</code></em></span></dt><dd><p>The port the Guacamole proxy daemon (<span class="package">guacd</span>) is
+                        listening on. If omitted, Guacamole will assume <span class="package">guacd</span> is
+                        listening on port 4822.</p></dd><dt><span class="term"><a id="idm140352909511872" class="indexterm"></a><em class="parameter"><code>guacd-ssl</code></em></span></dt><dd><p>If set to "true", Guacamole will require SSL/TLS encryption between the
+                        web application and <span class="package">guacd</span>. By default, communication
+                        between the web application and <span class="package">guacd</span> will be
+                        unencrypted.</p><p>Note that if you enable this option, you must also configure
+                            <span class="package">guacd</span> to use SSL via command line options. These
+                        options are documented in the manpage of <span class="package">guacd</span>. You will
+                        need an SSL certificate and private key.</p></dd></dl></div><div class="example"><a id="idm140352909506640"></a><p class="title"><strong>Example 5.1. Example <code class="filename">guacamole.properties</code></strong></p><div class="example-contents"><a id="guacamole.properties"></a><pre xml:lang="en" class="programlisting" lang="en"># Hostname and port of guacamole proxy
+guacd-hostname: localhost
+guacd-port:     4822</pre></div></div><br class="example-break" /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="webapp-logging"></a>Logging within the web application</h2></div></div></div><a id="idm140352909502688" class="indexterm"></a><p>By default, Guacamole logs all messages to the console. Servlet containers like Tomcat
+            will automatically redirect these messages to a log file,
+                <code class="filename">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:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><a id="idm140352909499856" class="indexterm"></a><code class="constant">error</code></span></dt><dd><p>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.</p></dd><dt><span class="term"><a id="idm140352909496496" class="indexterm"></a><code class="constant">warn</code></span></dt><dd><p>Warnings are generally non-fatal conditions. The operation continued, but
+                        encountered noteworthy problems.</p></dd><dt><span class="term"><a id="idm140352909493248" class="indexterm"></a><code class="constant">info</code></span></dt><dd><p>"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.</p></dd><dt><span class="term"><a id="idm140352909489904" class="indexterm"></a><code class="constant">debug</code></span></dt><dd><p>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.</p></dd></dl></div><p>Guacamole logs messages using a logging framework called <a class="link" href="http://logback.qos.ch/" target="_top">Logback</a> and, by default, will only log messages at the
+                "<code class="constant">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="filename">logback.xml</code> file within <code class="varname">GUACAMOLE_HOME</code>. For
+            example, to log all messages to the console, even "<code class="constant">debug</code>" messages,
+            you might use the following <code class="filename">logback.xml</code>:</p><div class="informalexample"><pre class="programlisting">&lt;configuration&gt;
+
+    &lt;!-- Appender for debugging --&gt;
+    &lt;appender name="GUAC-DEBUG" class="ch.qos.logback.core.ConsoleAppender"&gt;
+        &lt;encoder&gt;
+            &lt;pattern&gt;%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n&lt;/pattern&gt;
+        &lt;/encoder&gt;
+    &lt;/appender&gt;
+
+    &lt;!-- Log at DEBUG level --&gt;
+    &lt;root level="debug"&gt;
+        &lt;appender-ref ref="GUAC-DEBUG"/&gt;
+    &lt;/root&gt;
+
+&lt;/configuration&gt;</pre></div><p>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.</p><p>More thorough <a class="link" href="http://logback.qos.ch/manual/configuration.html" target="_top">documentation on
+                configuring Logback</a> is provided on the Logback project's web site.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="basic-auth"></a>Using the default authentication</h2></div></div></div><a id="idm140352909478256" class="indexterm"></a><p>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.</p><p>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,
+                <span class="package">guacamole-ext</span>.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="user-mapping"></a><code class="filename">user-mapping.xml</code></h3></div></div></div><a id="idm140352909474032" class="indexterm"></a><p>The default authentication provider used by Guacamole reads all username,
+                password, and configuration information from a file called the "user mapping". By
+                default, Guacamole will look for this file at
+                    <code class="filename">GUACAMOLE_HOME/user-mapping.xml</code>, but this can be overridden
+                by specifying the location with the <span class="property">user-mapping</span> property
+                within <code class="filename">guacamole.properties</code>:</p><div class="informalexample"><pre class="programlisting">user-mapping: <em class="replaceable"><code>/path/to/user-mapping.xml</code></em></pre></div><p>An example of a user mapping file is included with Guacamole, and looks something
+                like this:</p><pre class="programlisting">&lt;user-mapping&gt;
+	
+    &lt;!-- Per-user authentication and config information --&gt;
+    &lt;authorize username="USERNAME" password="PASSWORD"&gt;
+        &lt;protocol&gt;vnc&lt;/protocol&gt;
+        &lt;param name="hostname"&gt;localhost&lt;/param&gt;
+        &lt;param name="port"&gt;5900&lt;/param&gt;
+        &lt;param name="password"&gt;VNCPASS&lt;/param&gt;
+    &lt;/authorize&gt;
+
+    &lt;!-- Another user, but using md5 to hash the password
+         (example below uses the md5 hash of "PASSWORD") --&gt;
+    &lt;authorize 
+            username="USERNAME2"
+            password="319f4d26e3c536b5dd871bb2c52e3178"
+            encoding="md5"&gt;
+
+        &lt;!-- First authorized connection --&gt;
+        &lt;connection name="localhost"&gt;
+            &lt;protocol&gt;vnc&lt;/protocol&gt;
+            &lt;param name="hostname"&gt;localhost&lt;/param&gt;
+            &lt;param name="port"&gt;5901&lt;/param&gt;
+            &lt;param name="password"&gt;VNCPASS&lt;/param&gt;
+        &lt;/connection&gt;
+
+        &lt;!-- Second authorized connection --&gt;
+        &lt;connection name="otherhost"&gt;
+            &lt;protocol&gt;vnc&lt;/protocol&gt;
+            &lt;param name="hostname"&gt;otherhost&lt;/param&gt;
+            &lt;param name="port"&gt;5900&lt;/param&gt;
+            &lt;param name="password"&gt;VNCPASS&lt;/param&gt;
+        &lt;/connection&gt;
+
+    &lt;/authorize&gt;
+
+&lt;/user-mapping&gt;</pre><p>Each user is specified with a corresponding
+                    <code class="code">&lt;authorize&gt;</code> tag. This tag contains all
+                authorized connections for that user, each denoted with a
+                    <code class="code">&lt;connection&gt;</code> tag. Each
+                    <code class="code">&lt;connection&gt;</code> tag contains a corresponding
+                protocol and set of protocol-specific parameters, specified with
+                the <code class="code">&lt;protocol&gt;</code> and <code class="code">&lt;param&gt;</code> tags
+                respectively.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="user-setup"></a>Adding users</h4></div></div></div><a id="idm140352909463552" class="indexterm"></a><p>When using
+                        <code class="classname">BasicFileAuthenticationProvider</code>,
+                    username/password pairs are specified with
+                        <code class="code">&lt;authorize&gt;</code> tags, which each have a
+                        <code class="code">username</code> and <code class="code">password</code>
+                    attribute. Each <code class="code">&lt;authorize&gt;</code> tag authorizes a
+                    specific username/password pair to access all connections
+                    within the tag:</p><pre class="programlisting">&lt;authorize username="<em class="replaceable"><code>USER</code></em>" password="<em class="replaceable"><code>PASS</code></em>"&gt;
+    ...
+&lt;/authorize&gt;</pre><p>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:</p><pre class="programlisting">&lt;authorize username="<em class="replaceable"><code>USER</code></em>"
+           password="<em class="replaceable"><code>319f4d26e3c536b5dd871bb2c52e3178</code></em>"
+           encoding="md5"&gt;
+    ...
+&lt;/authorize&gt;</pre><p>After modifying user-mapping.xml, 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.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="connection-setup"></a>Adding connections to a user</h4></div></div></div><a id="idm140352909453808" class="indexterm"></a><p>To specify a connection within an
+                        <code class="code">&lt;authorize&gt;</code> tag, you can either list a
+                    single protocol and set of parameters (specified with a
+                        <code class="code">&lt;protocol&gt;</code> tag and any number of
+                        <code class="code">&lt;param&gt;</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="code">&lt;connection&gt;</code> tags, each of which can be
+                    named and contains a <code class="code">&lt;protocol&gt;</code> tag and any
+                    number of <code class="code">&lt;param&gt;</code> tags.</p></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="connection-configuration"></a>Configuring connections</h2></div></div></div><p>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.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="vnc"></a>VNC</h3></div></div></div><a id="idm140352909444816" class="indexterm"></a><p>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.</p><p>VNC support for Guacamole is provided by the <span class="package">libguac-client-vnc</span>
+                library, which will be installed as part of guacamole-server if the required
+                dependencies are present during the build.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="vnc-network-parameters"></a>Network parameters</h4></div></div></div><p>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.</p><div class="informaltable"><a id="vnc-parameters"></a><a id="idm140352909439344" class="indexterm"></a><table border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Parameter name</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>hostname</code></em></td><td>
+                                    <p><a id="idm140352909431680" class="indexterm"></a>The hostname or IP address of the VNC server
+                                        Guacamole should connect to.</p>
+                                </td></tr><tr><td><em class="parameter"><code>port</code></em></td><td>
+                                    <p><a id="idm140352909428288" class="indexterm"></a>The port the VNC server is listening on, usually
+                                        5900 or 5900 + <em class="replaceable"><code>display number</code></em>.
+                                        For example, if your VNC server is serving display number 1
+                                        (sometimes written as <code class="constant">:1</code>), your port
+                                        number here would be 5901.</p>
+                                </td></tr><tr><td><em class="parameter"><code>autoretry</code></em></td><td>
+                                    <p><a id="idm140352909423792" class="indexterm"></a>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.</p>
+                                </td></tr></tbody></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="vnc-authentication"></a>Authentication</h4></div></div></div><p>The VNC standard defines only password based authentication. Other
+                    authentication mechanisms exist, but are non-standard or proprietary. Guacamole
+                    supports only the password method.</p><div class="informaltable"><a id="idm140352909418560" class="indexterm"></a><table border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Parameter name</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>password</code></em></td><td>
+                                    <p><a id="idm140352909410848" class="indexterm"></a>The password to use when attempting
+                                        authentication, if any. This parameter is optional.</p>
+                                </td></tr></tbody></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="vnc-display-settings"></a>Display settings</h4></div></div></div><p>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.</p><p>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.</p><div class="informaltable"><a id="idm140352909404512" class="indexterm"></a><table border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Parameter name</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>color-depth</code></em></td><td>
+                                    <p><a id="idm140352909396800" class="indexterm"></a>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.</p>
+                                </td></tr><tr><td><em class="parameter"><code>swap-red-blue</code></em></td><td>
+                                    <p>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.</p>
+                                </td></tr><tr><td><em class="parameter"><code>cursor</code></em></td><td>
+                                    <p><a id="idm140352909390528" class="indexterm"></a>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.</p>
+                                </td></tr><tr><td><em class="parameter"><code>encodings</code></em></td><td>
+                                    <p><a id="idm140352909386752" class="indexterm"></a>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
+                                            <span class="package">libguac-client-vnc</span> will use any
+                                        supported encoding by default.</p>
+                                    <p>Beware that this parameter is intended to be replaced with
+                                        individual, encoding-specific parameters in a future
+                                        release.</p>
+                                </td></tr><tr><td><em class="parameter"><code>read-only</code></em></td><td>
+                                    <p><a id="idm140352909381936" class="indexterm"></a>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.</p>
+                                </td></tr></tbody></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="vnc-recording"></a>Session recording</h4></div></div></div><p>VNC sessions 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 translated to a normal video stream
+                    using the <span class="command"><strong>guacenc</strong></span> utility provided with
+                    guacamole-server.</p><p>For example, to produce a video called "<em class="replaceable"><code>NAME</code></em>.m4v"
+                    from the recording "<em class="replaceable"><code>NAME</code></em>", you would run:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>guacenc <em class="replaceable"><code>/path/to/recording/NAME</code></em></code></strong></pre></div><p>The <span class="command"><strong>guacenc</strong></span> utility has additional options for overriding
+                    default behavior, including tweaking the output format, which are documented in
+                    detail within the manpage:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>man guacenc</code></strong></pre></div><div class="important"><h3 class="title">Important</h3><p>Guacamole will never overwrite an existing recording. If necessary, a
+                        numeric suffix like ".1", ".2", ".3", etc. will be appended to
+                            <em class="replaceable"><code>NAME</code></em> to avoid overwriting an existing
+                        recording. If even appending a numeric suffix does not help, the session
+                        will simply not be recorded.</p></div><div class="informaltable"><a id="idm140352909368608" class="indexterm"></a><table border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Parameter name</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>recording-path</code></em></td><td>
+                                    <p><a id="idm140352909360896" class="indexterm"></a>The directory in which screen recording files
+                                        should be created. <span class="emphasis"><em>If a graphical recording needs
+                                            to be created, then this parameter is
+                                            required.</em></span> Specifying this parameter enables
+                                        graphical screen recording. If this parameter is omitted, no
+                                        graphical recording will be created.</p>
+                                </td></tr><tr><td><em class="parameter"><code>create-recording-path</code></em></td><td>
+                                    <p>If set to "true", the directory specified by the
+                                            <em class="parameter"><code>recording-path</code></em> 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.</p>
+                                    <p><span class="emphasis"><em>This parameter is optional.</em></span> By
+                                        default, the directory specified by the
+                                            <em class="parameter"><code>recording-path</code></em> parameter will not
+                                        automatically be created, and attempts to create recordings
+                                        within a non-existent directory will be logged as
+                                        errors.</p>
+                                    <p>This parameter only has an effect if graphical recording
+                                        is enabled. If the <em class="parameter"><code>recording-path</code></em> is
+                                        not specified, graphical session recording will be disabled,
+                                        and this parameter will be ignored.</p>
+                                </td></tr><tr><td><em class="parameter"><code>recording-name</code></em></td><td>
+                                    <p>The filename to use for any created recordings.
+                                            <span class="emphasis"><em>This parameter is optional.</em></span> If
+                                        omitted, the value "recording" will be used instead.</p>
+                                    <p>This parameter only has an effect if graphical recording
+                                        is enabled. If the <em class="parameter"><code>recording-path</code></em> is
+                                        not specified, graphical session recording will be disabled,
+                                        and this parameter will be ignored.</p>
+                                </td></tr></tbody></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="vnc-sftp"></a>File transfer (via SFTP)</h4></div></div></div><p>VNC does not normally support file transfer, but Guacamole can provide file
+                    transfer over SFTP even when the remote desktop is otherwise being accessed
+                    through VNC and not SSH. If SFTP is enabled on a Guacamole VNC connection, users
+                    will be able to upload and download files as described in <a class="xref" href="using-guacamole.html" title="Chapter 10. Using Guacamole">Chapter 10, <em>Using Guacamole</em></a>.</p><div class="informaltable"><a id="idm140352909344912" class="indexterm"></a><table border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Parameter name</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>enable-sftp</code></em></td><td>
+                                    <p><a id="idm140352909337200" class="indexterm"></a><a id="idm140352909335920" class="indexterm"></a>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.</p>
+                                </td></tr><tr><td><em class="parameter"><code>sftp-hostname</code></em></td><td>
+                                    <p>The hostname or IP address of the server hosting SFTP.
+                                        This parameter is optional. If omitted, the hostname of the
+                                        VNC server specified with the
+                                            <em class="parameter"><code>hostname</code></em> parameter will be
+                                        used.</p>
+                                </td></tr><tr><td><em class="parameter"><code>sftp-port</code></em></td><td>
+                                    <p>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.</p>
+                                </td></tr><tr><td><em class="parameter"><code>sftp-username</code></em></td><td>
+                                    <p>The username to authenticate as when connecting to the
+                                        specified SSH server for SFTP. This parameter is
+                                        required.</p>
+                                </td></tr><tr><td><em class="parameter"><code>sftp-password</code></em></td><td>
+                                    <p>The password to use when authenticating with the specified
+                                        SSH server for SFTP.</p>
+                                </td></tr><tr><td><em class="parameter"><code>sftp-private-key</code></em></td><td>
+                                    <p>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 <span class="command"><strong>ssh-keygen</strong></span> utility.</p>
+                                </td></tr><tr><td><em class="parameter"><code>sftp-passphrase</code></em></td><td>
+                                    <p>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.</p>
+                                </td></tr><tr><td><em class="parameter"><code>sftp-directory</code></em></td><td>
+                                    <p>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.</p>
+                                </td></tr></tbody></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="vnc-repeater"></a>VNC Repeater</h4></div></div></div><p>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.</p><div class="informaltable"><a id="idm140352909314272" class="indexterm"></a><table border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Parameter name</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>dest-host</code></em></td><td><a id="idm140352909306864" class="indexterm"></a><a id="idm140352909305600" class="indexterm"></a><a id="idm140352909304336" class="indexterm"></a>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.</td></tr><tr><td><em class="parameter"><code>dest-port</code></em></td><td><a id="idm140352909301072" class="indexterm"></a><a id="idm140352909299808" class="indexterm"></a>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.</td></tr></tbody></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="vnc-reverse-connections"></a>Reverse VNC connections</h4></div></div></div><p>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.</p><div class="informaltable"><a id="idm140352909294384" class="indexterm"></a><table border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Parameter name</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>reverse-connect</code></em></td><td>
+                                    <p><a id="idm140352909286672" class="indexterm"></a>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.</p>
+                                </td></tr><tr><td><em class="parameter"><code>listen-timeout</code></em></td><td>
+                                    <p><a id="idm140352909283072" class="indexterm"></a>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).</p>
+                                </td></tr></tbody></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="vnc-audio"></a>Audio support (via PulseAudio)</h4></div></div></div><p>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.</p><p>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.</p><p>Configuring PulseAudio for network connections requires an additional line
+                    within the PulseAudio configuration file, usually
+                        <code class="filename">/etc/pulse/default.pa</code>:</p><div class="informalexample"><pre class="programlisting">load-module module-native-protocol-tcp auth-ip-acl=<em class="replaceable"><code>192.168.1.0/24</code></em> auth-anonymous=1</pre></div><p>This loads the TCP module for PulseAudio, configuring it to accept connections
+                    without authentication and <span class="emphasis"><em>only</em></span> from the
+                        <em class="replaceable"><code>192.168.1.0/24</code></em> 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:</p><div class="informalexample"><pre class="programlisting">load-module module-native-protocol-tcp auth-anonymous=1</pre></div><p>In either case, the <code class="code">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.</p><p>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 <span class="command"><strong>netstat</strong></span>:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>netstat -ln | grep 4713</code></strong>
+<code class="computeroutput">tcp        0      0 0.0.0.0:4713            0.0.0.0:*               LISTEN
+tcp6       0      0 :::4713                 :::*                    LISTEN</code>
+<code class="prompt">$</code></pre></div><p>The following parameters are available for configuring the audio support for
+                    VNC:</p><div class="informaltable"><a id="idm140352909266416" class="indexterm"></a><table border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Parameter name</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>enable-audio</code></em></td><td>
+                                    <p><a id="idm140352909258704" class="indexterm"></a><a id="idm140352909257424" class="indexterm"></a>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.</p>
+                                </td></tr><tr><td><em class="parameter"><code>audio-servername</code></em></td><td>
+                                    <p>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 <em class="parameter"><code>hostname</code></em>
+                                        parameter.</p>
+                                    <p>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.</p>
+                                </td></tr></tbody></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="vnc-clipboard-encoding"></a>Clipboard encoding</h4></div></div></div><p>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
+                        <em class="parameter"><code>clipboard-encoding</code></em> parameter.</p><div class="important"><h3 class="title">Important</h3><p><span class="emphasis"><em>The only clipboard encoding guaranteed to be supported by VNC
+                            servers is ISO 8859-1.</em></span> You should only override the clipboard
+                        encoding using the <em class="parameter"><code>clipboard-encoding</code></em> parameter of
+                        you are absolutely positive your VNC server supports other encodings.</p></div><div class="informaltable"><a id="idm140352909246192" class="indexterm"></a><table border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Parameter name</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>clipboard-encoding</code></em></td><td>
+                                    <p><a id="idm140352909238480" class="indexterm"></a><a id="idm140352909237680" class="indexterm"></a>The encoding to assume for the VNC clipboard.
+                                        This parameter is optionl. By default, the standard encoding
+                                        ISO 8859-1 will be used. <span class="emphasis"><em>Only use this parameter
+                                            if you are sure your VNC server supports other encodings
+                                            beyond the standard ISO 8859-1.</em></span></p>
+                                    <p>Possible values are:</p>
+                                    <div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="constant">ISO8859-1</code></span></dt><dd><p>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.</p></dd><dt><span class="term"><code class="constant">UTF-8</code></span></dt><dd><p>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.</p></dd><dt><span class="term"><code class="constant">UTF-16</code></span></dt><dd><p>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.</p></dd><dt><span class="term"><code class="constant">CP1252</code></span></dt><dd><p>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.</p></dd></dl></div>
+                                </td></tr></tbody></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="adding-vnc"></a>Adding a VNC connection</h4></div></div></div><a id="idm140352909221824" class="indexterm"></a><p>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="code">&lt;authorize&gt;</code> section for that user within your
+                        <code class="filename">user-mapping.xml</code>, and add a section like the following
+                    within it:</p><pre class="programlisting">&lt;connection name="<em class="replaceable"><code>Unique Name</code></em>"&gt;
+    &lt;protocol&gt;vnc&lt;/protocol&gt;
+    &lt;param name="hostname"&gt;<em class="replaceable"><code>localhost</code></em>&lt;/param&gt;
+    &lt;param name="port"&gt;<em class="replaceable"><code>5901</code></em>&lt;/param&gt;
+&lt;/connection&gt;</pre><p>If added exactly as above, a new connection named "<em class="replaceable"><code>Unique
+                        Name</code></em>" will be available to the user associated with the
+                        <code class="code">&lt;authorize&gt;</code> section containing it. The connection will use
+                    VNC to connect to <em class="replaceable"><code>localhost</code></em> at port
+                        <em class="replaceable"><code>5901</code></em>. Naturally, you will want to change some or
+                    all of these values.</p><p>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="code">&lt;param&gt;</code> tags accordingly.</p><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="vnc-servers"></a>Which VNC server?</h4></div></div></div><a id="idm140352909211264" class="indexterm"></a><p>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.</p><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="realvnc"></a>RealVNC or TigerVNC</h5></div></div></div><a id="idm140352909208592" class="indexterm"></a><a id="idm140352909207680" class="indexterm"></a><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="tightvnc"></a>TightVNC</h5></div></div></div><a id="idm140352909204576" class="indexterm"></a><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="x11vnc"></a>x11vnc</h5></div></div></div><a id="idm140352909201248" class="indexterm"></a><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="vino"></a>vino</h5></div></div></div><a id="idm140352909198144" class="indexterm"></a><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="qemu"></a>QEMU or KVM</h5></div></div></div><a id="idm140352909194896" class="indexterm"></a><a id="idm140352909193984" class="indexterm"></a><p>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.</p><p>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.</p></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="rdp"></a>RDP</h3></div></div></div><a id="idm140352909189744" class="indexterm"></a><p>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.</p><p>RDP support for Guacamole is provided by the <span class="package">libguac-client-rdp</span>
+                library, which will be installed as part of guacamole-server if the required
+                dependencies are present during the build.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="rdp-network-parameters"></a>Network parameters</h4></div></div></div><p>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.</p><div class="informaltable"><a id="idm140352909184720" class="indexterm"></a><table border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Parameter name</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>hostname</code></em></td><td>
+                                    <p><a id="idm140352909177008" class="indexterm"></a>The hostname or IP address of the RDP server
+                                        Guacamole should connect to.</p>
+                                </td></tr><tr><td><em class="parameter"><code>port</code></em></td><td>
+                                    <p><a id="idm140352909173616" class="indexterm"></a>The port the RDP server is listening on, usually
+                                        3389. This parameter is optional. If this is not specified,
+                                        the default of 3389 will be used.</p>
+                                </td></tr></tbody></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="rdp-authentication"></a>Authentication and security</h4></div></div></div><p>RDP provides authentication through the use of a username, password, and
+                    optional domain.</p><p>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. If your server
+                    requires NLA, you will need to manually choose this as your security mode, and
+                    you <span class="emphasis"><em>must</em></span> provide a username and password.</p><p>All RDP connections are encrypted. Higher-grade encryption is available in the
+                    form of TLS, another possible security mode.</p><div class="informaltable"><a id="idm140352909166608" class="indexterm"></a><table border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Parameter name</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>username</code></em></td><td>
+                                    <p><a id="idm140352909158896" class="indexterm"></a>The username to use to authenticate, if any.
+                                        This parameter is optional.</p>
+                                </td></tr><tr><td><em class="parameter"><code>password</code></em></td><td>
+                                    <p><a id="idm140352909155504" class="indexterm"></a>The password to use when attempting
+                                        authentication, if any. This parameter is optional.</p>
+                                </td></tr><tr><td><em class="parameter"><code>domain</code></em></td><td>
+                                    <p><a id="idm140352909152096" class="indexterm"></a>The domain to use when attempting
+                                        authentication, if any. This parameter is optional.</p>
+                                </td></tr><tr><td><em class="parameter"><code>security</code></em></td><td>
+                                    <p><a id="idm140352909148688" class="indexterm"></a><a id="idm140352909147408" class="indexterm"></a><a id="idm140352909146128" class="indexterm"></a>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,
+                                        standard RDP encryption is requested, as it is the most
+                                        widely supported.</p>
+                                    <p>Possible values are:</p>
+                                    <div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="constant">rdp</code></span></dt><dd><p>Standard RDP encryption. <span class="emphasis"><em>This is the
+                                                  default</em></span> and should be supported by all
+                                                  RDP servers.</p></dd><dt><span class="term"><code class="constant">nla</code></span></dt><dd><p>Network Level Authentication. This mode
+                                                  requires the username and password, and performs
+                                                  an authentication step before the remote desktop
+                                                  session actually starts. If the username and
+                                                  password are not given, the connection cannot be
+                                                  made.</p></dd><dt><span class="term"><code class="constant">tls</code></span></dt><dd><p>TLS encryption. TLS (Transport Layer Security)
+                                                  is the successor to SSL.</p></dd><dt><span class="term"><code class="constant">any</code></span></dt><dd><p>Allow the server to choose the type of
+                                                  security.</p></dd></dl></div>
+                                </td></tr><tr><td><em class="parameter"><code>ignore-cert</code></em></td><td>
+                                    <p><a id="idm140352909131808" class="indexterm"></a>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).</p>
+                                </td></tr><tr><td><em class="parameter"><code>disable-auth</code></em></td><td>
+                                    <p><a id="idm140352909128016" class="indexterm"></a>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.</p>
+                                    <p>If you are using NLA, authentication must be enabled by
+                                        definition.</p>
+                                </td></tr></tbody></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="rdp-session-settings"></a>Session settings</h4></div></div></div><p>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.</p><p>Although Guacamole is independent of keyboard layout, RDP is not. This is
+                    because Guacamole represents keys based on what they <span class="emphasis"><em>do</em></span>
+                    ("press the <span class="keycap"><strong>Enter</strong></span> 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.</p><p>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="link" href="https://glyptodon.org/jira/" target="_top">opening an issue in
+                    JIRA</a>.</p><div class="informaltable"><a id="idm140352909118368" class="indexterm"></a><table border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Parameter name</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>client-name</code></em></td><td>
+                                    <p><a id="idm140352909110656" class="indexterm"></a>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.</p>
+                                    <p>On Windows RDP servers, this value is exposed within the
+                                        session as the <code class="envar">CLIENTNAME</code> environment
+                                        variable.</p>
+                                </td></tr><tr><td><em class="parameter"><code>console</code></em></td><td>
+                                    <p><a id="idm140352909106016" class="indexterm"></a>If set to "true", you will be connected to the
+                                        console (admin) session of the RDP server.</p>
+                                </td></tr><tr><td><em class="parameter"><code>initial-program</code></em></td><td>
+                                    <p><a id="idm140352909102608" class="indexterm"></a>The full path to the program to run immediately
+                                        upon connecting. This parameter is optional.</p>
+                                </td></tr><tr><td><em class="parameter"><code>server-layout</code></em></td><td>
+                                    <p><a id="idm140352909099200" class="indexterm"></a><a id="idm140352909098400" class="indexterm"></a>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. <span class="emphasis"><em>The
+                                            Guacamole client is independent of keyboard
+                                            layout.</em></span> The RDP protocol, however, is
+                                            <span class="emphasis"><em>not</em></span> 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.</p>
+                                    <p>Possible values are:</p>
+                                    <div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="constant">en-us-qwerty</code></span></dt><dd><p>English (US) keyboard</p></dd><dt><span class="term"><code class="constant">de-de-qwertz</code></span></dt><dd><p>German keyboard (qwertz)</p></dd><dt><span class="term"><code class="constant">fr-fr-azerty</code></span></dt><dd><p>French keyboard (azerty)</p></dd><dt><span class="term"><code class="constant">it-it-qwerty</code></span></dt><dd><p>Italian keyboard</p></dd><dt><span class="term"><code class="constant">ja-jp-qwerty</code></span></dt><dd><p>Japanese keyboard</p></dd><dt><span class="term"><code class="constant">sv-se-qwerty</code></span></dt><dd><p>Swedish keyboard</p></dd><dt><span class="term"><code class="constant">failsafe</code></span></dt><dd><p>Unknown keyboard - this option sends only
+                                                  Unicode events and should work for any keyboard,
+                                                  though not necessarily all RDP servers or
+                                                  applications.</p><p>If your server's keyboard layout is not yet
+                                                  supported, this option should work in the
+                                                  meantime.</p></dd></dl></div>
+                                </td></tr></tbody></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="rdp-display-settings"></a>Display settings</h4></div></div></div><p>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.</p><p>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.</p><div class="informaltable"><a id="idm140352909074336" class="indexterm"></a><table border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Parameter name</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>color-depth</code></em></td><td>
+                                    <p><a id="idm140352909066624" class="indexterm"></a>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.</p>
+                                </td></tr><tr><td><em class="parameter"><code>width</code></em></td><td>
+                                    <p><a id="idm140352909062864" class="indexterm"></a>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.</p>
+                                </td></tr><tr><td><em class="parameter"><code>height</code></em></td><td>
+                                    <p>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.</p>
+                                </td></tr><tr><td><em class="parameter"><code>dpi</code></em></td><td>
+                                    <p><a id="idm140352909057008" class="indexterm"></a>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.</p>
+                                </td></tr><tr><td><em class="parameter"><code>resize-method</code></em></td><td>
+                                    <p><a id="idm140352909053296" class="indexterm"></a>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.</p>
+                                    <p>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.</p>
+                                    <p>Possible values are:</p>
+                                    <div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="constant">display-update</code></span></dt><dd><p>Uses the "Display Update" channel added with
+                                                  RDP 8.1 to signal the server when the client
+                                                  display size has changed.</p></dd><dt><span class="term"><code class="constant">reconnect</code></span></dt><dd><p>Automatically disconnects the RDP session when
+                                                  the client display size has changed, and
+                                                  reconnects with the new size.</p></dd></dl></div>
+                                </td></tr></tbody></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="rdp-recording"></a>Session recording</h4></div></div></div><p>RDP sessions 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 translated to a normal video stream
+                    using the <span class="command"><strong>guacenc</strong></span> utility provided with
+                    guacamole-server.</p><p>For example, to produce a video called "<em class="replaceable"><code>NAME</code></em>.m4v"
+                    from the recording "<em class="replaceable"><code>NAME</code></em>", you would run:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>guacenc <em class="replaceable"><code>/path/to/recording/NAME</code></em></code></strong></pre></div><p>The <span class="command"><strong>guacenc</strong></span> utility has additional options for overriding
+                    default behavior, including tweaking the output format, which are documented in
+                    detail within the manpage:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>man guacenc</code></strong></pre></div><div class="important"><h3 class="title">Important</h3><p>Guacamole will never overwrite an existing recording. If necessary, a
+                        numeric suffix like ".1", ".2", ".3", etc. will be appended to
+                            <em class="replaceable"><code>NAME</code></em> to avoid overwriting an existing
+                        recording. If even appending a numeric suffix does not help, the session
+                        will simply not be recorded.</p></div><div class="informaltable"><a id="idm140352909033456" class="indexterm"></a><table border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Parameter name</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>recording-path</code></em></td><td>
+                                    <p><a id="idm140352909025744" class="indexterm"></a>The directory in which screen recording files
+                                        should be created. <span class="emphasis"><em>If a graphical recording needs
+                                            to be created, then this parameter is
+                                            required.</em></span> Specifying this parameter enables
+                                        graphical screen recording. If this parameter is omitted, no
+                                        graphical recording will be created.</p>
+                                </td></tr><tr><td><em class="parameter"><code>create-recording-path</code></em></td><td>
+                                    <p>If set to "true", the directory specified by the
+                                            <em class="parameter"><code>recording-path</code></em> 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.</p>
+                                    <p><span class="emphasis"><em>This parameter is optional.</em></span> By
+                                        default, the directory specified by the
+                                            <em class="parameter"><code>recording-path</code></em> parameter will not
+                                        automatically be created, and attempts to create recordings
+                                        within a non-existent directory will be logged as
+                                        errors.</p>
+                                    <p>This parameter only has an effect if graphical recording
+                                        is enabled. If the <em class="parameter"><code>recording-path</code></em> is
+                                        not specified, graphical session recording will be disabled,
+                                        and this parameter will be ignored.</p>
+                                </td></tr><tr><td><em class="parameter"><code>recording-name</code></em></td><td>
+                                    <p>The filename to use for any created recordings.
+                                            <span class="emphasis"><em>This parameter is optional.</em></span> If
+                                        omitted, the value "recording" will be used instead.</p>
+                                    <p>This parameter only has an effect if graphical recording
+                                        is enabled. If the <em class="parameter"><code>recording-path</code></em> is
+                                        not specified, graphical session recording will be disabled,
+                                        and this parameter will be ignored.</p>
+                                </td></tr></tbody></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="rdp-device-redirection"></a>Device redirection</h4></div></div></div><p>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.</p><p>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.</p><p>Printing requires <span class="application">GhostScript</span> to be installed on
+                    the Guacamole server, and allows users to print arbitrary documents directly to
+                    PDF. When documents are printed to the 

<TRUNCATED>


Mime
View raw message