GUACAMOLE-540: Merge documentation for configuring Tomcat's RemoteIpValve.
diff --git a/src/chapters/adhoc-connections.xml b/src/chapters/adhoc-connections.xml
new file mode 100644
index 0000000..04a730f
--- /dev/null
+++ b/src/chapters/adhoc-connections.xml
@@ -0,0 +1,118 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<chapter xml:id="adhoc-connections" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en"
+ xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>Ad-hoc Connections</title>
+ <indexterm>
+ <primary>adhoc-connections</primary>
+ <secondary>adhoc</secondary>
+ <secondary>quickconnect</secondary>
+ </indexterm>
+ <para>The quickconnect extension provides a connection bar on the Guacamole Client home page
+ that allows users to type in the URI of a server to which they want to connect and the client
+ will parse the URI and immediately establish the connection. The purpose of the extension is
+ to allow situations where administrators want to allow users the flexibility of establishing
+ their own connections without having to grant them access to edit connections or even to have
+ to create the connections at all, aside from typing the URI.</para>
+ <important>
+ <para>There are several implications of using this extension that should be well-understood
+ by administrators prior to implementing it:</para>
+ <itemizedlist>
+ <listitem><para>Connections established with this extension are created in-memory
+ and only persist until the Guacamole session ends.</para></listitem>
+ <listitem><para>Connections created with this extension are not accessible to other users, and
+ cannot be shared with other users.</para></listitem>
+ <listitem><para>This extension provides no functionality for authenticating users - it does
+ not allow anonymous logins, and requires that users are successfully authenticated
+ by another authentication module before it can be used.</para></listitem>
+ <listitem><para>The extension provides users the ability not only to establish connections, but
+ also to set any of the parameters for a connection. There are security implications for
+ this - for example, RDP file sharing can be used to pass through any directory available
+ on the server running guacd to the remote desktop. This should be taken into consideration
+ when enabling this extension and making sure that guacd is configured in a way that
+ does not compromise sensitive system files by allowing access to them.</para></listitem>
+ </itemizedlist>
+ </important>
+ <section xml:id="quickconnect-downloading">
+ <title>Downloading the quickconnect extension</title>
+ <para>The quickconnect extension is available separately from the main
+ <filename>guacamole.war</filename>. The link for this and all other
+ officially-supported and compatible extensions for a particular version of Guacamole are
+ provided in the release notes for that version. You can find the release notes for
+ current versions of Guacamole here: <link
+ xlink:href="http://guacamole.apache.org/releases/"
+ >http://guacamole.apache.org/releases/</link>.</para>
+ <para>The quickconnect extension is packaged as a <filename>.tar.gz</filename> file containing
+ only the extension itself, <filename>guacamole-auth-quickconnect-0.9.14.jar</filename>, which must
+ ultimately be placed in <filename>GUACAMOLE_HOME/extensions</filename>.</para>
+ </section>
+ <section xml:id="installing-quickconnect">
+ <title>Installing the quickconnect extension</title>
+ <para>Guacamole extensions are self-contained <filename>.jar</filename> files which are
+ located within the <filename>GUACAMOLE_HOME/extensions</filename> directory.
+ <emphasis>If you are unsure where <varname>GUACAMOLE_HOME</varname> is located on
+ your system, please consult <xref linkend="configuring-guacamole"/> before
+ proceeding.</emphasis></para>
+ <para>To install the extension, you must:</para>
+ <procedure>
+ <step>
+ <para>Create the <filename>GUACAMOLE_HOME/extensions</filename> directory, if it
+ does not already exist.</para>
+ </step>
+ <step>
+ <para>Place the <filename>guacamole-auth-quickconnect-0.9.14.jar</filename> file in
+ the <filename>GUACAMOLE_HOME/extensions</filename> directory.</para>
+ </step>
+ </procedure>
+ <section xml:id="guac-quickconnect-config">
+ <title>Configuring Guacamole for the quickconnect extension</title>
+ <indexterm>
+ <primary>configuring quickconnect</primary>
+ </indexterm>
+ <para>This module has no configuration options.</para>
+ </section>
+ <section xml:id="completing-quickconnect-install">
+ <title>Completing the installation</title>
+ <para>Guacamole will only load newly-installed extensions during startup, so your
+ servlet container will need to be restarted before the quickconnect extension
+ can be used. <emphasis>Doing this will disconnect all active users, so be sure
+ that it is safe to do so prior to attempting installation.</emphasis>
+ When ready, restart your servlet container and give the extension a try.</para>
+ </section>
+ </section>
+ <section xml:id="using-quickconnect">
+ <title>Using the quickconnect extension</title>
+ <para>The quickconnect extension provides a field on the home page that allows you to enter
+ a Uniform Resource Identifier (URI) to create a connection. A URI is in the form:</para>
+ <informalexample><uri>
+<replaceable>protocol</replaceable>://<replaceable>username</replaceable>:<replaceable>password</replaceable>@<replaceable>host</replaceable>:<replaceable>port</replaceable>/?<replaceable>parameters</replaceable>
+</uri></informalexample>
+ <para>The <replaceable>protocol</replaceable> field can have any of the protocols supported by
+ Guacamole, as documented in <xref linkend="configuring-guacamole"/>. Many of the
+ protocols define a default <replaceable>port</replaceable> value, with the exception of VNC.
+ The <replaceable>parameters</replaceable> field can specify any of the protocol-specific
+ parameters as documented on the configuration page.</para>
+ <para>To establish a connection, simply type in a valid URI and either press "Enter" or click
+ the connect button. This extension will parse the URI and create a new connection, and
+ immediately start that connection in the current browser.</para>
+ <para>Here are a few examples of URIs:</para>
+ <itemizedlist>
+ <listitem><informalexample><uri>ssh://linux1.example.com/</uri></informalexample>
+ <para>Connect to the server linux1.example.com using the SSH protocol on the default SSH port (22).
+ This will result in prompting for both username and password.</para></listitem>
+ <listitem><informalexample><uri>vnc://linux1.example.com:5900/</uri></informalexample>
+ <para>Connect to the server linux1.example.com using the VNC protocol and specifying the
+ port as 5900.</para></listitem>
+ <listitem><informalexample><uri>
+rdp://localuser@windows1.example.com/?security=rdp&ignore-cert=true&disable-audio=true&enable-drive=true&drive-path=/mnt/usb
+ </uri>
+ </informalexample>
+ <para>Connect to the server windows1.example.com using the RDP protocol and the user
+ "localuser". This URI also specifies several RDP-specific parameters on the
+ connection, including forcing security mode to RDP (security=rdp),
+ ignoring any certificate errors (ignore-cert=true), disabling audio pass-through
+ (disable-audio=true), and enabling filesystem redirection (enable-drive=true)
+ to the /mnt/usb folder on the system running guacd (drive-path=/mnt/usb).</para></listitem>
+ </itemizedlist>
+ </section>
+</chapter>
diff --git a/src/chapters/configuring.xml b/src/chapters/configuring.xml
index 7d78a5a..7d24eeb 100644
--- a/src/chapters/configuring.xml
+++ b/src/chapters/configuring.xml
@@ -2040,6 +2040,17 @@
</entry>
</row>
<row>
+ <entry><parameter>printer-name</parameter></entry>
+ <entry>
+ <para>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.</para>
+ <para>If printer redirection is not enabled, this option has no
+ effect.</para>
+ </entry>
+ </row>
+ <row>
<entry><parameter>enable-drive</parameter></entry>
<entry>
<para><indexterm>
@@ -2060,6 +2071,19 @@
</entry>
</row>
<row>
+ <entry><parameter>drive-name</parameter></entry>
+ <entry>
+ <para>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 <filename>\\tsclient</filename>
+ network location.</para>
+ <para>If file transfer is not enabled, this parameter is
+ ignored.</para>
+ </entry>
+ </row>
+ <row>
<entry><parameter>drive-path</parameter></entry>
<entry>
<para>The directory on the Guacamole server in which transferred
@@ -2594,6 +2618,46 @@
default.</para>
</entry>
</row>
+ <row>
+ <entry><parameter>disable-bitmap-caching</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>RDP</primary>
+ <secondary>bitmap caching</secondary>
+ </indexterm>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.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>disable-offscreen-caching</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>RDP</primary>
+ <secondary>offscreen bitmap caching</secondary>
+ </indexterm>RDP normally maintains caches of regions of the screen
+ that are current 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.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>disable-glyph-caching</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>RDP</primary>
+ <secondary>glyph caching</secondary>
+ </indexterm>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.</para>
+ </entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
@@ -2974,6 +3038,46 @@
</tgroup>
</informaltable>
</section>
+ <section xml:id="ssh-terminal-behavior">
+ <title>Controlling terminal behavior</title>
+ <para>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.</para>
+ <informaltable frame="all">
+ <indexterm>
+ <primary>parameters</primary>
+ <secondary>SSH</secondary>
+ </indexterm>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="1*"/>
+ <colspec colname="c2" colnum="2" colwidth="3.55*"/>
+ <thead>
+ <row>
+ <entry>Parameter name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><parameter>backspace</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>SSH</primary>
+ <secondary>backspace</secondary>
+ </indexterm>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.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
<section xml:id="ssh-typescripts">
<title>Text session recording (typescripts)</title>
<para>The full, raw text content of SSH sessions, including timing information, can
@@ -3559,6 +3663,46 @@
</tgroup>
</informaltable>
</section>
+ <section xml:id="telnet-terminal-behavior">
+ <title>Controlling terminal behavior</title>
+ <para>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.</para>
+ <informaltable frame="all">
+ <indexterm>
+ <primary>parameters</primary>
+ <secondary>telnet</secondary>
+ </indexterm>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="1*"/>
+ <colspec colname="c2" colnum="2" colwidth="3.55*"/>
+ <thead>
+ <row>
+ <entry>Parameter name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><parameter>backspace</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>telnet</primary>
+ <secondary>backspace</secondary>
+ </indexterm>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.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
<section xml:id="telnet-typescripts">
<title>Text session recording (typescripts)</title>
<para>The full, raw text content of telnet sessions, including timing information,
@@ -3586,7 +3730,7 @@
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
- <secondary>SSH</secondary>
+ <secondary>telnet</secondary>
</indexterm>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
diff --git a/src/chapters/docker.xml b/src/chapters/docker.xml
index c58cee8..58e4ea3 100644
--- a/src/chapters/docker.xml
+++ b/src/chapters/docker.xml
@@ -64,6 +64,12 @@
port 4822, but this port will only be available to Docker containers that have been
explicitly linked to
<varname><replaceable>some-guacd</replaceable></varname>.</para>
+ <para>The log level of guacd can be controlled with the <varname>GUACD_LOG_LEVEL</varname> environment variable. The
+ default value is <varname><replaceable>info</replaceable></varname>, and can be set to any of the
+ valid settings for the guacd log flag (-L).</para>
+ <informalexample>
+ <screen><prompt>$</prompt> <command>docker</command> run -e GUACD_LOG_LEVEL=<replaceable>debug</replaceable> -d guacamole/guacd</screen>
+ </informalexample>
</section>
<section xml:id="guacd-docker-external">
<title>Running <package>guacd</package> for use by services outside Docker</title>
diff --git a/src/gug.xml b/src/gug.xml
index fc39401..424df7b 100644
--- a/src/gug.xml
+++ b/src/gug.xml
@@ -165,6 +165,7 @@
<xi:include href="chapters/cas-auth.xml"/>
<xi:include href="chapters/openid-auth.xml"/>
<xi:include href="chapters/radius-auth.xml"/>
+ <xi:include href="chapters/adhoc-connections.xml"/>
<xi:include href="chapters/using.xml"/>
<xi:include href="chapters/administration.xml"/>
<xi:include href="chapters/troubleshooting.xml"/>
