GUACAMOLE-912: Merge correction regarding Docker links and support for LDAP.
diff --git a/NOTICE b/NOTICE
index 39de3ec..c5fc0d3 100644
--- a/NOTICE
+++ b/NOTICE
@@ -1,5 +1,5 @@
Apache Guacamole
-Copyright 2019 The Apache Software Foundation
+Copyright 2020 The Apache Software Foundation
This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).
diff --git a/src/chapters/adhoc-connections.xml b/src/chapters/adhoc-connections.xml
index 397e9b2..277b792 100644
--- a/src/chapters/adhoc-connections.xml
+++ b/src/chapters/adhoc-connections.xml
@@ -48,7 +48,7 @@
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-1.1.0.jar</filename>, which must
+ only the extension itself, <filename>guacamole-auth-quickconnect-1.2.0.jar</filename>, which must
ultimately be placed in <filename>GUACAMOLE_HOME/extensions</filename>.</para>
</section>
<section xml:id="installing-quickconnect">
@@ -65,7 +65,7 @@
does not already exist.</para>
</step>
<step>
- <para>Place the <filename>guacamole-auth-quickconnect-1.1.0.jar</filename> file in
+ <para>Place the <filename>guacamole-auth-quickconnect-1.2.0.jar</filename> file in
the <filename>GUACAMOLE_HOME/extensions</filename> directory.</para>
</step>
</procedure>
diff --git a/src/chapters/cas-auth.xml b/src/chapters/cas-auth.xml
index c66d6bd..1331935 100644
--- a/src/chapters/cas-auth.xml
+++ b/src/chapters/cas-auth.xml
@@ -23,7 +23,7 @@
>http://guacamole.apache.org/releases/</link>.</para>
<para>The CAS authentication extension is packaged as a <filename>.tar.gz</filename>
file containing only the extension itself,
- <filename>guacamole-auth-cas-1.1.0.jar</filename>, which must
+ <filename>guacamole-auth-cas-1.2.0.jar</filename>, which must
ultimately be placed in <filename>GUACAMOLE_HOME/extensions</filename>.</para>
</section>
<section xml:id="installing-cas-auth">
@@ -40,7 +40,7 @@
does not already exist.</para>
</step>
<step>
- <para>Copy <filename>guacamole-auth-cas-1.1.0.jar</filename> within
+ <para>Copy <filename>guacamole-auth-cas-1.2.0.jar</filename> within
<filename>GUACAMOLE_HOME/extensions</filename>.</para>
</step>
<step>
diff --git a/src/chapters/configuring.xml b/src/chapters/configuring.xml
index 651bb66..d09037d 100644
--- a/src/chapters/configuring.xml
+++ b/src/chapters/configuring.xml
@@ -141,14 +141,14 @@
</varlistentry>
<varlistentry>
<term><indexterm xmlns:xl="http://www.w3.org/1999/xlink">
- <primary>available-languages</primary>
- </indexterm><parameter>available-languages</parameter></term>
+ <primary>allowed-languages</primary>
+ </indexterm><parameter>allowed-languages</parameter></term>
<listitem>
<para>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:</para>
<informalexample>
- <programlisting>available-languages: en, de</programlisting>
+ <programlisting>allowed-languages: en, de</programlisting>
</informalexample>
<para>As English is the fallback language, used whenever a translation key is
missing from the chosen language, English should only be omitted from this
@@ -719,7 +719,7 @@
events:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>guaclog <replaceable>/path/to/recording/NAME</replaceable></userinput><computeroutput>
-guaclog: INFO: Guacamole input log interpreter (guaclog) version 1.1.0
+guaclog: INFO: Guacamole input log interpreter (guaclog) version 1.2.0
guaclog: INFO: 1 input file(s) provided.
guaclog: INFO: Writing input events from "<replaceable>/path/to/recording/NAME</replaceable>" to "<replaceable annotations="">/path/to/recording/NAME</replaceable>.txt" ...
guaclog: INFO: All files interpreted successfully.</computeroutput>
@@ -974,6 +974,26 @@
</para>
</entry>
</row>
+ <row>
+ <entry><parameter>sftp-disable-download</parameter></entry>
+ <entry>
+ <para>If set to true downloads from the remote system to
+ the client (browser) will be disabled. The default is
+ false, which means that downloads will be enabled.</para>
+ <para>If sftp is not enabled, this parameter will be
+ ignored.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>sftp-disable-upload</parameter></entry>
+ <entry>
+ <para>If set to true uploads from the client (browser) to
+ the remote system will be disabled. The default is
+ false, which means that uploads will be enabled.</para>
+ <para>If sftp is not enabled, this parameter will be
+ ignored.</para>
+ </entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
@@ -1326,6 +1346,117 @@
</tgroup>
</informaltable>
</section>
+ <section xml:id="vnc-wake-on-lan">
+ <title>Wake-on-LAN Configuration</title>
+ <para>Guacamole implements the support to send a "magic wake-on-lan
+ packet" to a remote host prior to attempting to establish a
+ connection with the host. The below parameters control the
+ behavior of this functionality, which is disabled by default.
+ </para>
+ <important>
+ <para>There are several factors that can impact the ability
+ of Wake-on-LAN (WoL) to function correctly, many of which
+ are outside the scope of Guacamole configuration. If you
+ are configuring WoL within Guacamole you should also be
+ familiar with the other components that need to be
+ configured in order for it to function correctly.</para>
+ </important>
+ <informaltable frame="all">
+ <indexterm>
+ <primary>parameters</primary>
+ <secondary>VNC</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>wol-send-packet</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>wol-send-packet</primary>
+ </indexterm><indexterm>
+ <primary>VNC</primary>
+ <secondary>wol-send-packet</secondary>
+ </indexterm>If set to "true", Guacamole will
+ attempt to send the Wake-On-LAN packet prior
+ to establishing a connection. This parameter
+ is optional. By default, Guacamole will
+ not send the WoL packet. Enabling this
+ option requires that the
+ <parameter>wol-mac-addr</parameter>
+ parameter also be configured, otherwise
+ the WoL packet will not be sent.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>wol-mac-addr</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>wol-mac-addr</primary>
+ </indexterm><indexterm>
+ <primary>VNC</primary>
+ <secondary>wol-mac-addr</secondary>
+ </indexterm>This parameter configures the
+ MAC address that Guacamole will use in
+ the magic WoL packet to attempt to wake
+ the remote system. If
+ <parameter>wol-send-packet</parameter>
+ is enabled, this parameter is required
+ or else the WoL packet will not be sent.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>wol-broadcast-addr</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>wol-broadcast-addr</primary>
+ </indexterm><indexterm>
+ <primary>VNC</primary>
+ <secondary>wol-broadcast-addr</secondary>
+ </indexterm>This parameter configures the
+ IPv4 broadcast address or IPv6 multicast
+ address that Guacamole will send the
+ WoL packet to in order to wake the host.
+ This parameter is optional. If no value
+ is provided, the default local IPv4 broadcast
+ address (255.255.255.255) will be used.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>wol-wait-time</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>wol-wait-time</primary>
+ </indexterm><indexterm>
+ <primary>VNC</primary>
+ <secondary>wol-wait-time</secondary>
+ </indexterm>By default after the WoL packet
+ is sent Guacamole will attempt immediately
+ to connect to the remote host. It may be
+ desirable in certain scenarios to have
+ Guacamole wait before the initial connection
+ in order to give the remote system time to
+ boot. Setting this parameter to a positive
+ value will cause Guacamole to wait the specified
+ number of seconds before attempting the initial
+ connection. This parameter is optional.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
<section xml:id="adding-vnc">
<title>Adding a VNC connection</title>
<indexterm>
@@ -1485,9 +1616,11 @@
<para><indexterm>
<primary>RDP</primary>
<secondary>port</secondary>
- </indexterm>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.</para>
+ </indexterm>The port the RDP server is listening on. This
+ parameter is optional. If this is not specified, the
+ standard port for RDP (3389) or Hyper-V's default port for
+ VMConnect (2179) will be used, depending on the security
+ mode selected.</para>
</entry>
</row>
</tbody>
@@ -1497,15 +1630,20 @@
<section xml:id="rdp-authentication">
<title>Authentication and security</title>
<para>RDP provides authentication through the use of a username, password, and
- optional domain.</para>
+ optional domain. All RDP connections are encrypted.</para>
<para>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 <emphasis>must</emphasis> provide a username and password.</para>
- <para>All RDP connections are encrypted. Higher-grade encryption is available in the
- form of TLS, another possible security mode.</para>
+ session, and thus in the absence of a graphical interface.</para>
+ <important>
+ <para>If your server requires NLA, you <emphasis>must</emphasis> provide a
+ username and password. Leveraging Guacamole's <link
+ xmlns:xlink="http://www.w3.org/1999/xlink" linkend="parameter-tokens"
+ >parameter tokens</link> and <link
+ xmlns:xlink="http://www.w3.org/1999/xlink" linkend="ldap-auth">LDAP
+ support</link> to integrate with Active Directory and automatically pass
+ through credentials is a common configuration.</para>
+ </important>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
@@ -1565,42 +1703,80 @@
<secondary>TLS</secondary>
</indexterm>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.</para>
+ of authentication will be performed, if any. By default, a
+ security mode is selected based on a negotiation process
+ which determines what both the client and the server
+ support.</para>
<para>Possible values are:</para>
<variablelist>
<varlistentry>
- <term><constant>rdp</constant></term>
+ <term><constant>any</constant></term>
<listitem>
- <para>Standard RDP encryption. <emphasis>This is the
- default</emphasis> and should be supported by all
- RDP servers.</para>
+ <para>Automatically select the security mode based
+ on the security protocols supported by both the
+ client and the server. <emphasis>This is the
+ default</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>nla</constant></term>
<listitem>
- <para>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.</para>
+ <para>Network Level Authentication, sometimes also
+ referred to as "hybrid" or CredSSP (the protocol
+ that drives NLA). This mode uses TLS encryption
+ and requires the username and password to be given
+ in advance. Unlike RDP mode, the authentication
+ step is performed before the remote desktop
+ session actually starts, avoiding the need for the
+ Windows server to allocate significant resources
+ for users that may not be authorized.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>nla-ext</constant></term>
+ <listitem>
+ <para>Extended Network Level Authentication. This
+ mode is identical to NLA except that an additional
+ "<link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-rdpbcgr/d0e560a3-25cb-4563-8bdc-6c4cc625bbfc"
+ >Early User Authorization Result</link>" is
+ required to be sent from the server to the client
+ immediately after the NLA handshake is
+ completed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>tls</constant></term>
<listitem>
- <para>TLS encryption. TLS (Transport Layer Security)
- is the successor to SSL.</para>
+ <para>RDP authentication and encryption implemented
+ via TLS (Transport Layer Security). Also referred
+ to as RDSTLS, the TLS security mode is primarily
+ used in load balanced configurations where the
+ initial RDP server may redirect the connection to
+ a different RDP server.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><constant>any</constant></term>
+ <term><constant>vmconnect</constant></term>
<listitem>
- <para>Allow the server to choose the type of
- security.</para>
+ <para>Automatically select the security mode based
+ on the security protocols supported by both the
+ client and the server, limiting that negotiation
+ to only the protocols known to be supported by
+ <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ linkend="rdp-preconnection-pdu">Hyper-V /
+ VMConnect</link>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>rdp</constant></term>
+ <listitem>
+ <para>Standard RDP encryption. This mode is
+ generally only used for older Windows servers or
+ in cases where a standard Windows login screen is
+ desired. Newer versions of Windows have this mode
+ disabled by default and will only accept NLA
+ unless explicitly configured otherwise.</para>
</listitem>
</varlistentry>
</variablelist>
@@ -1752,6 +1928,12 @@
</listitem>
</varlistentry>
<varlistentry>
+ <term><constant>fr-be-azerty</constant></term>
+ <listitem>
+ <para>Belgian French keyboard (azerty)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term><constant>fr-fr-azerty</constant></term>
<listitem>
<para>French keyboard (azerty)</para>
@@ -1794,6 +1976,12 @@
</listitem>
</varlistentry>
<varlistentry>
+ <term><constant>es-latam-qwerty</constant></term>
+ <listitem>
+ <para>Latin American keyboard</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term><constant>sv-se-qwerty</constant></term>
<listitem>
<para>Swedish keyboard</para>
@@ -1843,7 +2031,7 @@
can be used in situations where guacd does
not support passing the timezone parameter
during the handshake phase (guacd versions
- prior to 1.1.0).</para>
+ prior to 1.2.0).</para>
<para>Support for forwarding the client
timezone varies by RDP server implementation.
For example, with Windows, support for
@@ -2007,7 +2195,7 @@
events:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>guaclog <replaceable>/path/to/recording/NAME</replaceable></userinput><computeroutput>
-guaclog: INFO: Guacamole input log interpreter (guaclog) version 1.1.0
+guaclog: INFO: Guacamole input log interpreter (guaclog) version 1.2.0
guaclog: INFO: 1 input file(s) provided.
guaclog: INFO: Writing input events from "<replaceable>/path/to/recording/NAME</replaceable>" to "<replaceable annotations="">/path/to/recording/NAME</replaceable>.txt" ...
guaclog: INFO: All files interpreted successfully.</computeroutput>
@@ -2249,6 +2437,30 @@
</entry>
</row>
<row>
+ <entry><parameter>disable-download</parameter></entry>
+ <entry>
+ <para>If set to true downloads from the remote server to
+ client (browser) will be disabled. This includes both
+ downloads down via the hidden Guacamole menu, as well
+ as using the special "Download" folder presented to
+ the remote server. The default is false, which means
+ that downloads will be allowed.</para>
+ <para>If file transfer is not enabled, this parameter is
+ ignored.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>disable-upload</parameter></entry>
+ <entry>
+ <para>If set to true, uploads from the client (browser)
+ to the remote server location will be disabled. The
+ default is false, which means uploads will be allowed
+ if file transfer is enabled.</para>
+ <para>If file transfer is not enabled, this parameter is
+ ignored.</para>
+ </entry>
+ </row>
+ <row>
<entry><parameter>drive-name</parameter></entry>
<entry>
<para>The name of the filesystem used when passed through to
@@ -2325,11 +2537,13 @@
</informaltable>
</section>
<section xml:id="rdp-preconnection-pdu">
- <title>Preconnection PDU (Hyper-V)</title>
+ <title>Preconnection PDU (Hyper-V / VMConnect)</title>
<para><indexterm>
<primary>preconnection PDU</primary>
</indexterm><indexterm>
<primary>Hyper-V</primary>
+ </indexterm><indexterm>
+ <primary>VMConnect</primary>
</indexterm>Some RDP servers host multiple logical RDP connections behind a
single server listening on a single TCP port. To select between these logical
connections, an RDP client must send the "preconnection PDU" - a message which
@@ -2356,25 +2570,20 @@
means for selecting virtual machines behind Hyper-V, other RDP servers may use
it as well. It is up to the RDP server itself to determine whether the
preconnection ID, BLOB, or both will be used, and what their values mean.</para>
- <para>If you do intend to use Hyper-V, beware that its built-in RDP server uses
- slightly different parameters for both authentication and the port number, and
- Guacamole's defaults will not work. In most cases, you will need to do the
- following when connecting to Hyper-V:</para>
+ <para><emphasis>If you do intend to use Hyper-V, beware that its built-in RDP server
+ requires different parameters for authentication and Guacamole's defaults
+ will not work.</emphasis> In most cases, you will need to do the following
+ when connecting to Hyper-V:</para>
<orderedlist>
<listitem>
- <para>Set "<parameter>port</parameter>" to "<constant>2179</constant>", as
- this is the default port used by Hyper-V. The standard RDP port is 3389,
- and Guacamole will use port 3389 unless a different value is
- specified.</para>
- </listitem>
- <listitem>
<para>Specify both "<parameter>username</parameter>" and
"<parameter>password</parameter>" appropriately, and set
- "<parameter>security</parameter>" to "<constant>nla</constant>" or
- "<constant>any</constant>". Hyper-V requires Network Level
- Authentication from connecting clients. Guacamole's default is to use
- standard RDP encryption without Network Level Authentication, which
- Hyper-V does not support.</para>
+ "<parameter>security</parameter>" to
+ "<constant>vmconnect</constant>". Selecting the
+ "<constant>vmconnect</constant>" security mode will configure
+ Guacamole to automatically negotiate security modes known to be
+ supported by Hyper-V, and will automatically select Hyper-V's default
+ RDP port (2179).</para>
</listitem>
<listitem>
<para>If necessary, set "<parameter>ignore-cert</parameter>" to
@@ -2444,9 +2653,6 @@
connect through such a gateway, you will need to provide additional parameters
describing the connection to that gateway, as well as any required
credentials.</para>
- <para><emphasis>This functionality is only available if Guacamole was built against
- FreeRDP 1.1 or later.</emphasis> Older versions of FreeRDP do not have
- support for RDP gateways.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
@@ -2481,9 +2687,6 @@
</indexterm>The port of the remote desktop gateway that
should be used as an intermediary for the remote desktop
connection. By default, this will be "443".</para>
- <para><emphasis>If using a version of FreeRDP prior to 1.2, this
- setting has no effect.</emphasis> Older versions of
- FreeRDP use a hard-coded value of "443". </para>
</entry>
</row>
<row>
@@ -2539,10 +2742,6 @@
files for convenience, look through the contents of those files for a string
field called "loadbalanceinfo", as that field is where the required
information/cookie would be specified.</para>
- <para><emphasis>This functionality is only available if Guacamole was built against
- FreeRDP 1.1 or later.</emphasis> Older versions of FreeRDP do not have
- support for load balancers which require additional information during the
- connection process.</para>
<informaltable frame="all">
<indexterm>
<primary>parameters</primary>
@@ -2707,6 +2906,26 @@
</para>
</entry>
</row>
+ <row>
+ <entry><parameter>sftp-disable-download</parameter></entry>
+ <entry>
+ <para>If set to true downloads from the remote system to
+ the client (browser) will be disabled. The default is
+ false, which means that downloads will be enabled.</para>
+ <para>If sftp is not enabled, this parameter will be
+ ignored.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>sftp-disable-upload</parameter></entry>
+ <entry>
+ <para>If set to true uploads from the client (browser) to
+ the remote system will be disabled. The default is
+ false, which means that uploads will be enabled.</para>
+ <para>If sftp is not enabled, this parameter will be
+ ignored.</para>
+ </entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
@@ -2969,6 +3188,117 @@
</tgroup>
</informaltable>
</section>
+ <section xml:id="rdp-wake-on-lan">
+ <title>Wake-on-LAN Configuration</title>
+ <para>Guacamole implements the support to send a "magic wake-on-lan
+ packet" to a remote host prior to attempting to establish a
+ connection with the host. The below parameters control the
+ behavior of this functionality, which is disabled by default.
+ </para>
+ <important>
+ <para>There are several factors that can impact the ability
+ of Wake-on-LAN (WoL) to function correctly, many of which
+ are outside the scope of Guacamole configuration. If you
+ are configuring WoL within Guacamole you should also be
+ familiar with the other components that need to be
+ configured in order for it to function correctly.</para>
+ </important>
+ <informaltable frame="all">
+ <indexterm>
+ <primary>parameters</primary>
+ <secondary>RDP</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>wol-send-packet</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>wol-send-packet</primary>
+ </indexterm><indexterm>
+ <primary>RDP</primary>
+ <secondary>wol-send-packet</secondary>
+ </indexterm>If set to "true", Guacamole will
+ attempt to send the Wake-On-LAN packet prior
+ to establishing a connection. This parameter
+ is optional. By default, Guacamole will
+ not send the WoL packet. Enabling this
+ option requires that the
+ <parameter>wol-mac-addr</parameter>
+ parameter also be configured, otherwise
+ the WoL packet will not be sent.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>wol-mac-addr</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>wol-mac-addr</primary>
+ </indexterm><indexterm>
+ <primary>RDP</primary>
+ <secondary>wol-mac-addr</secondary>
+ </indexterm>This parameter configures the
+ MAC address that Guacamole will use in
+ the magic WoL packet to attempt to wake
+ the remote system. If
+ <parameter>wol-send-packet</parameter>
+ is enabled, this parameter is required
+ or else the WoL packet will not be sent.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>wol-broadcast-addr</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>wol-broadcast-addr</primary>
+ </indexterm><indexterm>
+ <primary>RDP</primary>
+ <secondary>wol-broadcast-addr</secondary>
+ </indexterm>This parameter configures the
+ IPv4 broadcast address or IPv6 multicast
+ address that Guacamole will send the
+ WoL packet to in order to wake the host.
+ This parameter is optional. If no value
+ is provided, the default local IPv4 broadcast
+ address (255.255.255.255) will be used.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>wol-wait-time</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>wol-wait-time</primary>
+ </indexterm><indexterm>
+ <primary>RDP</primary>
+ <secondary>wol-wait-time</secondary>
+ </indexterm>By default after the WoL packet
+ is sent Guacamole will attempt immediately
+ to connect to the remote host. It may be
+ desirable in certain scenarios to have
+ Guacamole wait before the initial connection
+ in order to give the remote system time to
+ boot. Setting this parameter to a positive
+ value will cause Guacamole to wait the specified
+ number of seconds before attempting the initial
+ connection. This parameter is optional.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
<section xml:id="adding-rdp">
<title>Adding an RDP connection</title>
<indexterm>
@@ -3699,7 +4029,7 @@
events:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>guaclog <replaceable>/path/to/recording/NAME</replaceable></userinput><computeroutput>
-guaclog: INFO: Guacamole input log interpreter (guaclog) version 1.1.0
+guaclog: INFO: Guacamole input log interpreter (guaclog) version 1.2.0
guaclog: INFO: 1 input file(s) provided.
guaclog: INFO: Writing input events from "<replaceable>/path/to/recording/NAME</replaceable>" to "<replaceable annotations="">/path/to/recording/NAME</replaceable>.txt" ...
guaclog: INFO: All files interpreted successfully.</computeroutput>
@@ -3869,6 +4199,26 @@
the root directory will be used by default.</para>
</entry>
</row>
+ <row>
+ <entry><parameter>sftp-disable-download</parameter></entry>
+ <entry>
+ <para>If set to true downloads from the remote system to
+ the client (browser) will be disabled. The default is
+ false, which means that downloads will be enabled.</para>
+ <para>If sftp is not enabled, this parameter will be
+ ignored.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>sftp-disable-upload</parameter></entry>
+ <entry>
+ <para>If set to true uploads from the client (browser) to
+ the remote system will be disabled. The default is
+ false, which means that uploads will be enabled.</para>
+ <para>If sftp is not enabled, this parameter will be
+ ignored.</para>
+ </entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
@@ -3928,6 +4278,117 @@
</tgroup>
</informaltable>
</section>
+ <section xml:id="ssh-wake-on-lan">
+ <title>Wake-on-LAN Configuration</title>
+ <para>Guacamole implements the support to send a "magic wake-on-lan
+ packet" to a remote host prior to attempting to establish a
+ connection with the host. The below parameters control the
+ behavior of this functionality, which is disabled by default.
+ </para>
+ <important>
+ <para>There are several factors that can impact the ability
+ of Wake-on-LAN (WoL) to function correctly, many of which
+ are outside the scope of Guacamole configuration. If you
+ are configuring WoL within Guacamole you should also be
+ familiar with the other components that need to be
+ configured in order for it to function correctly.</para>
+ </important>
+ <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>wol-send-packet</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>wol-send-packet</primary>
+ </indexterm><indexterm>
+ <primary>SSH</primary>
+ <secondary>wol-send-packet</secondary>
+ </indexterm>If set to "true", Guacamole will
+ attempt to send the Wake-On-LAN packet prior
+ to establishing a connection. This parameter
+ is optional. By default, Guacamole will
+ not send the WoL packet. Enabling this
+ option requires that the
+ <parameter>wol-mac-addr</parameter>
+ parameter also be configured, otherwise
+ the WoL packet will not be sent.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>wol-mac-addr</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>wol-mac-addr</primary>
+ </indexterm><indexterm>
+ <primary>SSH</primary>
+ <secondary>wol-mac-addr</secondary>
+ </indexterm>This parameter configures the
+ MAC address that Guacamole will use in
+ the magic WoL packet to attempt to wake
+ the remote system. If
+ <parameter>wol-send-packet</parameter>
+ is enabled, this parameter is required
+ or else the WoL packet will not be sent.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>wol-broadcast-addr</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>wol-broadcast-addr</primary>
+ </indexterm><indexterm>
+ <primary>SSH</primary>
+ <secondary>wol-broadcast-addr</secondary>
+ </indexterm>This parameter configures the
+ IPv4 broadcast address or IPv6 multicast
+ address that Guacamole will send the
+ WoL packet to in order to wake the host.
+ This parameter is optional. If no value
+ is provided, the default local IPv4 broadcast
+ address (255.255.255.255) will be used.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>wol-wait-time</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>wol-wait-time</primary>
+ </indexterm><indexterm>
+ <primary>SSH</primary>
+ <secondary>wol-wait-time</secondary>
+ </indexterm>By default after the WoL packet
+ is sent Guacamole will attempt immediately
+ to connect to the remote host. It may be
+ desirable in certain scenarios to have
+ Guacamole wait before the initial connection
+ in order to give the remote system time to
+ boot. Setting this parameter to a positive
+ value will cause Guacamole to wait the specified
+ number of seconds before attempting the initial
+ connection. This parameter is optional.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
<section xml:id="adding-ssh">
<title>Adding an SSH connection</title>
<indexterm>
@@ -4527,7 +4988,7 @@
events:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>guaclog <replaceable>/path/to/recording/NAME</replaceable></userinput><computeroutput>
-guaclog: INFO: Guacamole input log interpreter (guaclog) version 1.1.0
+guaclog: INFO: Guacamole input log interpreter (guaclog) version 1.2.0
guaclog: INFO: 1 input file(s) provided.
guaclog: INFO: Writing input events from "<replaceable>/path/to/recording/NAME</replaceable>" to "<replaceable annotations="">/path/to/recording/NAME</replaceable>.txt" ...
guaclog: INFO: All files interpreted successfully.</computeroutput>
@@ -4706,6 +5167,117 @@
</tgroup>
</informaltable>
</section>
+ <section xml:id="telnet-wake-on-lan">
+ <title>Wake-on-LAN Configuration</title>
+ <para>Guacamole implements the support to send a "magic wake-on-lan
+ packet" to a remote host prior to attempting to establish a
+ connection with the host. The below parameters control the
+ behavior of this functionality, which is disabled by default.
+ </para>
+ <important>
+ <para>There are several factors that can impact the ability
+ of Wake-on-LAN (WoL) to function correctly, many of which
+ are outside the scope of Guacamole configuration. If you
+ are configuring WoL within Guacamole you should also be
+ familiar with the other components that need to be
+ configured in order for it to function correctly.</para>
+ </important>
+ <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>wol-send-packet</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>wol-send-packet</primary>
+ </indexterm><indexterm>
+ <primary>telnet</primary>
+ <secondary>wol-send-packet</secondary>
+ </indexterm>If set to "true", Guacamole will
+ attempt to send the Wake-On-LAN packet prior
+ to establishing a connection. This parameter
+ is optional. By default, Guacamole will
+ not send the WoL packet. Enabling this
+ option requires that the
+ <parameter>wol-mac-addr</parameter>
+ parameter also be configured, otherwise
+ the WoL packet will not be sent.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>wol-mac-addr</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>wol-mac-addr</primary>
+ </indexterm><indexterm>
+ <primary>telnet</primary>
+ <secondary>wol-mac-addr</secondary>
+ </indexterm>This parameter configures the
+ MAC address that Guacamole will use in
+ the magic WoL packet to attempt to wake
+ the remote system. If
+ <parameter>wol-send-packet</parameter>
+ is enabled, this parameter is required
+ or else the WoL packet will not be sent.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>wol-broadcast-addr</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>wol-broadcast-addr</primary>
+ </indexterm><indexterm>
+ <primary>telnet</primary>
+ <secondary>wol-broadcast-addr</secondary>
+ </indexterm>This parameter configures the
+ IPv4 broadcast address or IPv6 multicast
+ address that Guacamole will send the
+ WoL packet to in order to wake the host.
+ This parameter is optional. If no value
+ is provided, the default local IPv4 broadcast
+ address (255.255.255.255) will be used.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>wol-wait-time</parameter></entry>
+ <entry>
+ <para><indexterm>
+ <primary>wol-wait-time</primary>
+ </indexterm><indexterm>
+ <primary>telnet</primary>
+ <secondary>wol-wait-time</secondary>
+ </indexterm>By default after the WoL packet
+ is sent Guacamole will attempt immediately
+ to connect to the remote host. It may be
+ desirable in certain scenarios to have
+ Guacamole wait before the initial connection
+ in order to give the remote system time to
+ boot. Setting this parameter to a positive
+ value will cause Guacamole to wait the specified
+ number of seconds before attempting the initial
+ connection. This parameter is optional.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
<section xml:id="adding-telnet">
<title>Adding a telnet connection</title>
<indexterm>
@@ -5270,7 +5842,7 @@
events:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>guaclog <replaceable>/path/to/recording/NAME</replaceable></userinput><computeroutput>
-guaclog: INFO: Guacamole input log interpreter (guaclog) version 1.1.0
+guaclog: INFO: Guacamole input log interpreter (guaclog) version 1.2.0
guaclog: INFO: 1 input file(s) provided.
guaclog: INFO: Writing input events from "<replaceable>/path/to/recording/NAME</replaceable>" to "<replaceable annotations="">/path/to/recording/NAME</replaceable>.txt" ...
guaclog: INFO: All files interpreted successfully.</computeroutput>
diff --git a/src/chapters/custom-auth.xml b/src/chapters/custom-auth.xml
index 28961eb..3b65c56 100644
--- a/src/chapters/custom-auth.xml
+++ b/src/chapters/custom-auth.xml
@@ -58,7 +58,7 @@
<groupId>org.apache.guacamole</groupId>
<artifactId>guacamole-auth-tutorial</artifactId>
<packaging>jar</packaging>
- <version>1.1.0</version>
+ <version>1.2.0</version>
<name>guacamole-auth-tutorial</name>
<properties>
@@ -88,7 +88,7 @@
<dependency>
<groupId>org.apache.guacamole</groupId>
<artifactId>guacamole-ext</artifactId>
- <version>1.1.0</version>
+ <version>1.2.0</version>
<scope>provided</scope>
</dependency>
@@ -172,7 +172,7 @@
<title>The required <filename>guac-manifest.json</filename></title>
<programlisting>{
- "guacamoleVersion" : "1.1.0",
+ "guacamoleVersion" : "1.2.0",
"name" : "Tutorial Authentication Extension",
"namespace" : "guac-auth-tutorial",
@@ -196,7 +196,7 @@
<screen><prompt>$</prompt> mvn package
<computeroutput>[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
-[INFO] Building guacamole-auth-tutorial 1.1.0
+[INFO] Building guacamole-auth-tutorial 1.2.0
[INFO] ------------------------------------------------------------------------
...
[INFO] ------------------------------------------------------------------------
@@ -210,7 +210,7 @@
</informalexample>
<para>Assuming you see the "<computeroutput>BUILD SUCCESS</computeroutput>" message when you
build the extension, there will be a new file,
- <filename>target/guacamole-auth-tutorial-1.1.0.jar</filename>, which can be
+ <filename>target/guacamole-auth-tutorial-1.2.0.jar</filename>, which can be
installed within Guacamole and tested. If you changed the name or version of the project
in the <filename>pom.xml</filename> file, the name of this new <filename>.jar</filename>
file will be different, but it can still be found within
@@ -472,7 +472,7 @@
user running Tomcat.</para>
<para>To install your extension, ensure that the required properties have been added to your
<filename>guacamole.properties</filename>, copy the
- <filename>target/guacamole-auth-tutorial-1.1.0.jar</filename> file into
+ <filename>target/guacamole-auth-tutorial-1.2.0.jar</filename> file into
<filename>GUACAMOLE_HOME/extensions</filename> and restart Tomcat. Guacamole will
automatically load your extension, logging an informative message that it has done
so:</para>
diff --git a/src/chapters/docker.xml b/src/chapters/docker.xml
index bd5ed24..c294226 100644
--- a/src/chapters/docker.xml
+++ b/src/chapters/docker.xml
@@ -646,6 +646,44 @@
</tbody>
</tgroup>
</informaltable>
+ <para>Optional environment variables may also be used to override Guacamole's
+ default behavior with respect to timeouts at the database and network level:</para>
+ <informaltable frame="all">
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="1*"/>
+ <colspec colname="c2" colnum="2" colwidth="1.15*"/>
+ <thead>
+ <row>
+ <entry>Variable</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><envar>POSTGRES_DEFAULT_STATEMENT_TIMEOUT</envar></entry>
+ <entry>
+ <para>The number of seconds the driver will wait for a
+ response from the database, before aborting the query.
+ A value of 0 (the default) means the timeout is disabled.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><envar>POSTGRES_SOCKET_TIMEOUT</envar></entry>
+ <entry>
+ <para>The number of seconds to wait for socket read
+ operations. If reading from the server takes longer than
+ this value, the connection will be closed. This can be used
+ to handle network problems such as a dropped connection to
+ the database. Similar to
+ <envar>POSTGRES_DEFAULT_STATEMENT_TIMEOUT</envar>,
+ it will also abort queries that take too long. A value of 0
+ (the default) means the timeout is disabled.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
</section>
</section>
<section xml:id="guacamole-docker-ldap">
diff --git a/src/chapters/duo-auth.xml b/src/chapters/duo-auth.xml
index d08cc3b..680e104 100644
--- a/src/chapters/duo-auth.xml
+++ b/src/chapters/duo-auth.xml
@@ -55,7 +55,7 @@
>http://guacamole.apache.org/releases/</link>.</para>
<para>The Duo authentication extension is packaged as a <filename>.tar.gz</filename> file
containing only the extension itself,
- <filename>guacamole-auth-duo-1.1.0.jar</filename>, which must ultimately
+ <filename>guacamole-auth-duo-1.2.0.jar</filename>, which must ultimately
be placed in <filename>GUACAMOLE_HOME/extensions</filename>.</para>
</section>
<section xml:id="installing-duo-auth">
@@ -69,7 +69,7 @@
does not already exist.</para>
</step>
<step>
- <para>Copy <filename>guacamole-auth-duo-1.1.0.jar</filename> within
+ <para>Copy <filename>guacamole-auth-duo-1.2.0.jar</filename> within
<filename>GUACAMOLE_HOME/extensions</filename>.</para>
</step>
<step>
@@ -167,7 +167,7 @@
been generated by Duo when you added Guacamole as an "Web SDK"
application, and can be found within the application details in the
"Secret key" field. <emphasis>This value is required and must be EXACTLY
- 20 characters.</emphasis></para>
+ 40 characters.</emphasis></para>
</listitem>
</varlistentry>
</variablelist>
diff --git a/src/chapters/event-listeners.xml b/src/chapters/event-listeners.xml
index 12dabf7..63706c3 100644
--- a/src/chapters/event-listeners.xml
+++ b/src/chapters/event-listeners.xml
@@ -52,7 +52,7 @@
<groupId>org.apache.guacamole</groupId>
<artifactId>guacamole-listener-tutorial</artifactId>
<packaging>jar</packaging>
- <version>1.1.0</version>
+ <version>1.2.0</version>
<name>guacamole-listener-tutorial</name>
<properties>
@@ -82,7 +82,7 @@
<dependency>
<groupId>org.apache.guacamole</groupId>
<artifactId>guacamole-ext</artifactId>
- <version>1.1.0</version>
+ <version>1.2.0</version>
<scope>provided</scope>
</dependency>
@@ -159,7 +159,7 @@
<title>The required <filename>guac-manifest.json</filename></title>
<programlisting>{
- "guacamoleVersion" : "1.1.0",
+ "guacamoleVersion" : "1.2.0",
"name" : "Tutorial Listener Extension",
"namespace" : "guac-listener-tutorial",
@@ -179,7 +179,7 @@
<screen><prompt>$</prompt> mvn package
<computeroutput>[INFO] Scanning for projects...
[INFO] ---------------------------------------------------------------
-[INFO] Building guacamole-listener-tutorial 1.1.0
+[INFO] Building guacamole-listener-tutorial 1.2.0
[INFO] ---------------------------------------------------------------
...
[INFO] ---------------------------------------------------------------
@@ -193,7 +193,7 @@
</informalexample>
<para>Assuming you see the "<computeroutput>BUILD SUCCESS</computeroutput>" message when you
build the extension, there will be a new file,
- <filename>target/guacamole-listener-tutorial-1.1.0.jar</filename>, which can be
+ <filename>target/guacamole-listener-tutorial-1.2.0.jar</filename>, which can be
installed within Guacamole (see <xref xmlns:xlink="http://www.w3.org/1999/xlink"
linkend="custom-listener-installing"/> at the end of this chapter). It should log
event notifications that occur during, for example, authentication attempts.
@@ -341,7 +341,7 @@
will be the <filename>.guacamole</filename> directory within the home directory of the
user running Tomcat.</para>
<para>To install your extension, copy the
- <filename>target/guacamole-listener-tutorial-1.1.0.jar</filename> file into
+ <filename>target/guacamole-listener-tutorial-1.2.0.jar</filename> file into
<filename>GUACAMOLE_HOME/extensions</filename> and restart Tomcat. Guacamole will
automatically load your extension, logging an informative message that it has done
so:</para>
diff --git a/src/chapters/guacamole-ext.xml b/src/chapters/guacamole-ext.xml
index 6f041cd..799a16c 100644
--- a/src/chapters/guacamole-ext.xml
+++ b/src/chapters/guacamole-ext.xml
@@ -186,7 +186,7 @@
<filename>guac-manifest.json</filename> will look something like this:</para>
<informalexample>
<programlisting>{
- "guacamoleVersion" : "1.1.0",
+ "guacamoleVersion" : "1.2.0",
"name" : "My Extension",
"namespace" : "my-extension"
}</programlisting>
@@ -198,7 +198,7 @@
<informalexample>
<programlisting>{
- "guacamoleVersion" : "1.1.0",
+ "guacamoleVersion" : "1.2.0",
"name" : "My Extension",
"namespace" : "my-extension",
diff --git a/src/chapters/header-auth.xml b/src/chapters/header-auth.xml
index ab9c11d..16a5a36 100644
--- a/src/chapters/header-auth.xml
+++ b/src/chapters/header-auth.xml
@@ -29,7 +29,7 @@
>http://guacamole.apache.org/releases/</link>.</para>
<para>The HTTP header authentication extension is packaged as a <filename>.tar.gz</filename>
file containing only the extension itself,
- <filename>guacamole-auth-header-1.1.0.jar</filename>, which must
+ <filename>guacamole-auth-header-1.2.0.jar</filename>, which must
ultimately be placed in <filename>GUACAMOLE_HOME/extensions</filename>.</para>
</section>
<section xml:id="installing-header-auth">
@@ -46,7 +46,7 @@
does not already exist.</para>
</step>
<step>
- <para>Copy <filename>guacamole-auth-header-1.1.0.jar</filename> within
+ <para>Copy <filename>guacamole-auth-header-1.2.0.jar</filename> within
<filename>GUACAMOLE_HOME/extensions</filename>.</para>
</step>
<step>
diff --git a/src/chapters/installing.xml b/src/chapters/installing.xml
index 54de3b2..ba94a32 100644
--- a/src/chapters/installing.xml
+++ b/src/chapters/installing.xml
@@ -288,8 +288,9 @@
<para>The <command>guacenc</command> utility, provided by
<package>guacamole-server</package> to translate screen recordings into video,
depends on FFmpeg, and will only be built if at least the
- <package>libavcodec</package>, <package>libavutil</package>, and
- <package>libswscale</package> libraries provided by FFmpeg are installed.</para>
+ <package>libavcodec</package>, <package>libavformat</package>,
+ <package>libavutil</package>, and <package>libswscale</package> libraries
+ provided by FFmpeg are installed.</para>
<important>
<para>If you lack these dependencies, <emphasis>then the features or protocols which
depend on them will not be enabled</emphasis>. Please read this section
@@ -310,12 +311,13 @@
<entry><link xl:href="https://ffmpeg.org/">FFmpeg</link></entry>
<entry>
<para>The <package>libavcodec</package>,
- <package>libavutil</package>, and
- <package>libswscale</package> libraries provided by FFmpeg
- are used by <command>guacenc</command> to encode video streams
- when translating recordings of Guacamole sessions. Without
- FFmpeg, the <command>guacenc</command> utility will simply not
- be built.</para>
+ <package>libavformat</package>,
+ <package>libavutil</package>, and <package>libswscale</package>
+ libraries provided by FFmpeg are used by
+ <command>guacenc</command> to encode video streams when
+ translating recordings of Guacamole sessions. Without FFmpeg,
+ the <command>guacenc</command> utility will simply not be
+ built.</para>
<para>If you do not wish to make graphical recordings of Guacamole
sessions, or do not wish to translate such recordings into
video, then FFmpeg is not needed.</para>
@@ -328,6 +330,7 @@
<entry>Debian / Ubuntu package</entry>
<entry>
<para><package>libavcodec-dev</package>,
+ <package>libavformat-dev</package>,
<package>libavutil-dev</package>,
<package>libswscale-dev</package></para>
</entry>
@@ -344,8 +347,9 @@
<row>
<entry><link xl:href="http://www.freerdp.com/">FreeRDP</link></entry>
<entry>
- <para>FreeRDP is required for RDP support. If you do not wish to
- build RDP support, this library is not needed.</para>
+ <para>FreeRDP 2.0.0 or later is required for RDP support. If you do
+ not wish to build RDP support, this library is not
+ needed.</para>
<informaltable frame="none" rowheader="firstcol">
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1.0*"/>
@@ -353,7 +357,7 @@
<tbody>
<row>
<entry>Debian / Ubuntu package</entry>
- <entry><package>libfreerdp-dev</package></entry>
+ <entry><package>freerdp2-dev</package></entry>
</row>
<row>
<entry>Fedora / CentOS / RHEL package</entry>
@@ -614,8 +618,8 @@
of a <filename>.tar.gz</filename> archive which you can extract from the command
line:</para>
<informalexample>
- <screen><prompt>$</prompt> <userinput>tar -xzf guacamole-server-1.1.0.tar.gz</userinput>
-<prompt>$</prompt> <userinput>cd guacamole-server-1.1.0/</userinput>
+ <screen><prompt>$</prompt> <userinput>tar -xzf guacamole-server-1.2.0.tar.gz</userinput>
+<prompt>$</prompt> <userinput>cd guacamole-server-1.2.0/</userinput>
<prompt>$</prompt></screen>
</informalexample>
<para>If you want the absolute latest code, and don't care that the code hasn't been as
@@ -667,14 +671,15 @@
...
------------------------------------------------
-guacamole-server version 1.1.0
+guacamole-server version 1.2.0
------------------------------------------------
Library status:
- freerdp ............. yes
+ freerdp2 ............ yes
pango ............... yes
libavcodec .......... yes
+ libavformat ......... yes
libavutil ........... yes
libssh2 ............. yes
libssl .............. yes
@@ -849,8 +854,8 @@
<filename>.tar.gz</filename> archive which you can extract from the command
line:</para>
<informalexample>
- <screen><prompt>$</prompt> <userinput>tar -xzf guacamole-client-1.1.0.tar.gz</userinput>
-<prompt>$</prompt> <userinput>cd guacamole-client-1.1.0/</userinput>
+ <screen><prompt>$</prompt> <userinput>tar -xzf guacamole-client-1.2.0.tar.gz</userinput>
+<prompt>$</prompt> <userinput>cd guacamole-client-1.2.0/</userinput>
<prompt>$</prompt></screen>
</informalexample>
<para>As with <package>guacamole-server</package>, if you want the absolute latest code, and
@@ -962,7 +967,7 @@
application from the name of the <filename>.war</filename> file, you will likely want to
rename this to simply <filename>guacamole.war</filename> while copying:</para>
<informalexample>
- <screen><prompt>#</prompt> <userinput>cp guacamole/target/guacamole-1.1.0.war <replaceable>/var/lib/tomcat/webapps</replaceable>/guacamole.war</userinput>
+ <screen><prompt>#</prompt> <userinput>cp guacamole/target/guacamole-1.2.0.war <replaceable>/var/lib/tomcat/webapps</replaceable>/guacamole.war</userinput>
<prompt>#</prompt></screen>
</informalexample>
<para>Again, if you are using a different servlet container or if Tomcat is installed to a
@@ -980,7 +985,7 @@
Starting Tomcat... OK</computeroutput>
<prompt>#</prompt> <userinput>/etc/init.d/guacd start</userinput>
<computeroutput>Starting guacd: SUCCESS
-guacd[6229]: INFO: Guacamole proxy daemon (guacd) version 1.1.0 started</computeroutput>
+guacd[6229]: INFO: Guacamole proxy daemon (guacd) version 1.2.0 started</computeroutput>
<prompt>#</prompt></screen>
</informalexample>
<important>
diff --git a/src/chapters/jdbc-auth.xml b/src/chapters/jdbc-auth.xml
index 0e5c2bb..83fbcc4 100644
--- a/src/chapters/jdbc-auth.xml
+++ b/src/chapters/jdbc-auth.xml
@@ -62,30 +62,173 @@
<term><filename>mysql/</filename></term>
<listitem>
<para>Contains the MySQL/MariaDB authentication extension,
- <filename>guacamole-auth-jdbc-mysql-1.1.0.jar</filename>, along with a
+ <filename>guacamole-auth-jdbc-mysql-1.2.0.jar</filename>, along with a
<filename>schema/</filename> directory containing MySQL-specific SQL
scripts required to set up the database. The
- <filename>guacamole-auth-jdbc-mysql-1.1.0.jar</filename> file will
+ <filename>guacamole-auth-jdbc-mysql-1.2.0.jar</filename> file will
ultimately need to be placed within
<filename>GUACAMOLE_HOME/extensions</filename>, while the MySQL JDBC
driver must be placed within <filename>GUACAMOLE_HOME/lib</filename>.</para>
<para><emphasis>The MySQL JDBC driver is not included with the
- extension.</emphasis> You must obtain the JDBC driver
- <filename>.jar</filename> yourself from <link
- xlink:href="http://dev.mysql.com/downloads/connector/j/">MySQL's
- website</link>. The driver is known as "Connector/J", and the required
+ extension.</emphasis> You must obtain a supported JDBC driver
+ <filename>.jar</filename> yourself. The MySQL driver can be downloaded
+ from <link xlink:href="http://dev.mysql.com/downloads/connector/j/">MySQL's
+ website</link>, and is known as "Connector/J". The required
<filename>.jar</filename> will be within a <filename>.tar.gz</filename>
archive.</para>
+ <para>In addition to the parameters below that are common to all database
+ extensions, the MySQL extension supports the <property>mysql-driver</property>
+ property, which controls which JDBC driver the extension attempts to load
+ and its compatibility with various target database implementations.
+ The extension currently supports the following values for the
+ <property>mysql-driver</property> property:
+ <variablelist>
+ <varlistentry>
+ <term>mysql</term>
+ <listitem>
+ <para>The MySQL JDBC driver, known as Connector/J.
+ This is the default.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>mariadb</term>
+ <listitem>
+ <para>The MariaDB JDBC driver.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <para>The MySQL Driver implements several parameters specific to configuring
+ SSL for secure connections to MySQL servers that support or require
+ encrypted communications. <emphasis>Older versions of MySQL Connector/J
+ have known issues with SSL verification - if you experience problems
+ connecting to SSL-secured MySQL databases it is recommended that
+ you update to a current version of the driver.</emphasis></para>
+ <para>Configuration parameters for MySQL-compatible SSL support are as
+ follows:</para>
+ <informaltable frame="all">
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="1*"/>
+ <colspec colname="c2" colnum="2" colwidth="3.55*"/>
+ <thead>
+ <row>
+ <entry>Property</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><property>mysql-ssl-mode</property></entry>
+ <entry>
+ <para>This property sets the SSL mode that the JDBC
+ driver will attempt to use when communicating
+ with the remote MySQL server. The values for
+ this property match the standard values supported
+ by the MySQL and MariaDB JDBC drivers:</para>
+ <variablelist>
+ <varlistentry>
+ <term>disabled</term>
+ <listitem>
+ <para>Do not use SSL, and fail if the
+ server requires it. For compatibility
+ this will also set the legacy JDBC
+ driver property
+ <property>useSSL</property> to false.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>preferred</term>
+ <listitem>
+ <para>Prefer SSL, but fall back to
+ plain-text if an SSL connection
+ cannot be negotiated. This
+ is the default.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>required</term>
+ <listitem>
+ <para>Require SSL connections, and fail
+ if SSL cannot be negotiated. This mode
+ does not perform any validition checks
+ on the certificate in use by the server,
+ the issuer, etc.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>verify-ca</term>
+ <listitem>
+ <para>Require SSL connections, and check
+ to make sure that the certificate issuer
+ is known to be valid.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>verify-identity</term>
+ <listitem>
+ <para>Require SSL connections, and check
+ to make sure that the server certificate
+ is issued by a known authority, and that
+ the identity of the server matches the
+ identity on the certificate.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </entry>
+ </row>
+ <row>
+ <entry><property>mysql-ssl-trust-store</property></entry>
+ <entry>
+ <para>The file that will store trusted SSL certificates
+ for the JDBC driver to use when validating CA and
+ server certificates. This should be a JKS-formatted
+ certificate store. This property is optional and
+ defaults to Java's normal trusted certificate
+ locations, which vary based on the version of
+ Java in use.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><property>mysql-ssl-trust-password</property></entry>
+ <entry>
+ <para>The password to use to access the SSL trusted
+ certificate store, if one is required. By default
+ no password will be used.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><property>mysql-ssl-client-store</property></entry>
+ <entry>
+ <para>The file that contains the client certificate to
+ use when making SSL connections to the MySQL server.
+ This should be a JKS-formatted certificate store that
+ contains a private key and certificate pair. This
+ property is optional, and by default no client
+ certificate will be used for the SSL connection.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><property>mysql-ssl-client-password</property></entry>
+ <entry>
+ <para>The password to use to access the client
+ certificate store, if one is required. By default
+ no password will be used.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>postgresql/</filename></term>
<listitem>
<para>Contains the PostgreSQL authentication extension,
- <filename>guacamole-auth-jdbc-postgresql-1.1.0.jar</filename>, along
+ <filename>guacamole-auth-jdbc-postgresql-1.2.0.jar</filename>, along
with a <filename>schema/</filename> directory containing PostgreSQL-specific
SQL scripts required to set up the database. The
- <filename>guacamole-auth-jdbc-postgresql-1.1.0.jar</filename> file will
+ <filename>guacamole-auth-jdbc-postgresql-1.2.0.jar</filename> file will
ultimately need to be placed within
<filename>GUACAMOLE_HOME/extensions</filename>, while the PostgreSQL
JDBC driver must be placed within
@@ -96,13 +239,185 @@
xlink:href="https://jdbc.postgresql.org/download.html#current"
>PostgreSQL's website</link>. The proper <filename>.jar</filename> file
depends on the version of Java you have installed. </para>
+ <para>The PostgreSQL extension implements several parameters specific to
+ conifiguring SSL for secure connections to Postgres servers that support
+ or require encrypted communications. The parameters are as follows:</para>
+ <informaltable frame="all">
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="1*"/>
+ <colspec colname="c2" colnum="2" colwidth="3.55*"/>
+ <thead>
+ <row>
+ <entry>Property</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><property>postgresql-ssl-mode</property></entry>
+ <entry>
+ <para>This property sets the SSL mode that the JDBC
+ extension will attempt to use when communicating
+ with the remote Postgres server. The values for
+ this property match the standard values supported
+ by the Postgres JDBC driver:</para>
+ <variablelist>
+ <varlistentry>
+ <term>disable</term>
+ <listitem>
+ <para>Do not use SSL, and fail if the
+ server requires it.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>allow</term>
+ <listitem>
+ <para>If the server requires encryption
+ use it, otherwise prefer unencrypted
+ connections.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>prefer</term>
+ <listitem>
+ <para>Try SSL connections, first, but
+ allow unencrypted connections if
+ the server does not support SSL or
+ if SSL negotiations fail. This is
+ the default.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>require</term>
+ <listitem>
+ <para>Require SSL connections, but
+ implicitly trust all server
+ certificates and authoritiers.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>verify-ca</term>
+ <listitem>
+ <para>Require SSL connections, and
+ verify that the server certificate
+ is issued by a known certificate
+ authority.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>verify-full</term>
+ <listitem>
+ <para>Require SSL connections,
+ verifying that the server certificate
+ is issued by a known authority, and
+ that the name on the certificate
+ matches the name of the server.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </entry>
+ </row>
+ <row>
+ <entry><property>postgresql-ssl-cert-file</property></entry>
+ <entry>
+ <para>The file containing the client certificate
+ to be used when making an SSL-encrtyped connection
+ to the Postgres server, in PEM format. This
+ property is optional, and will be ignored if the
+ SSL mode is set to disable.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><property>postgresql-ssl-key-file</property></entry>
+ <entry>
+ <para>The file containing the client private key
+ to be used when making an SSL-encrypted connection
+ to the Postgres server, in PEM format. This
+ property is optional, and will be ignore if the
+ SSL mode is set to disable.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><property>postgresql-ssl-root-cert-file</property></entry>
+ <entry>
+ <para>The file containing the root and intermedidate
+ certificates against which the server certificate
+ will be verified when making an SSL-encrypted
+ connection to the Postgres server. This file should
+ contain one or more PEM-formatted authority
+ certificates. This property is optional, and will
+ only be used if SSL mode is set to verify-ca or
+ verify-full.</para>
+ <para>If SSL is set to one of the verification modes
+ and this property is not specified, the JDBC driver
+ will attempt to use the
+ <filename>.postgresql/root.crt</filename> file
+ from the home directory of the user running the
+ web application server (e.g. Tomcat). If this
+ property is not specified and the default file
+ does not exist, the Postgres JDBC driver will
+ fail to connect to the server.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><property>postgresql-ssl-key-password</property></entry>
+ <entry>
+ <para>The password that will be used to access the
+ client private key file, if the client private
+ key is encrypted. This property is optional,
+ and is only used if the
+ <property>postgresql-ssl-key-file</property>
+ property is set and SSL is enabled.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>The PostgreSQL extension also implements some parameters to
+ configure timeouts at the database and network level.
+ The parameters are as follows:</para>
+ <informaltable frame="all">
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="1*"/>
+ <colspec colname="c2" colnum="2" colwidth="3.55*"/>
+ <thead>
+ <row>
+ <entry>Property</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><property>postgresql-default-statement-timeout</property></entry>
+ <entry>
+ <para>The number of seconds the driver will wait for a
+ response from the database, before aborting the query.
+ A value of 0 (the default) means the timeout is disabled.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><property>postgresql-socket-timeout</property></entry>
+ <entry>
+ <para>The number of seconds to wait for socket read
+ operations. If reading from the server takes longer than
+ this value, the connection will be closed. This can be used
+ to handle network problems such as a dropped connection to
+ the database. Similar to
+ <property>postgresql-default-statement-timeout</property>,
+ it will also abort queries that take too long. A value of 0
+ (the default) means the timeout is disabled.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>sqlserver/</filename></term>
<listitem>
<para>Contains the SQL Server authentication extension,
- <filename>guacamole-auth-jdbc-sqlserver-1.1.0.jar</filename>, along with
+ <filename>guacamole-auth-jdbc-sqlserver-1.2.0.jar</filename>, along with
a <filename>schema/</filename> directory contains SQL Server-specific
scripts requires to set up the database. The JAR extension file will need to
be placed within the <filename>GUACAMOLE_HOME/extensions</filename> folder,
@@ -116,12 +431,18 @@
directory. Microsoft's JDBC driver can be downloaded from Microsoft's <link
xlink:href="https://docs.microsoft.com/en-us/sql/connect/sql-connection-libraries#anchor-20-drivers-relational-access">
SQL Connection Libraries</link> page.</para>
- <para>In addition to the various parameters mentioned below, the SQL Server driver has a
- unique parameter available to control the driver compatibility of the JDBC module:
- <property>sqlserver-driver</property>. This parameter allows you to choose the compatibility
- mode of the module with various TDS-comptabile drivers such that it can be used with different
- versions of SQL Server and even non-Microsoft SQL Server databases. The following options are available
- for the <property>sqlserver-driver</property> property:
+ <para>In addition to the various parameters mentioned below, the SQL Server driver implements
+ two parameters to control SQL Server-specific configuration items:
+ <property>sqlserver-driver</property> and <property>sqlserver-instance</property>.</para>
+ <para>The <property>sqlserver-instance</property> property controls the instance name that the
+ SQL Server driver should attempt to connect to, if it is something other than the default
+ SQL Server instance. This instance name is configured during the SQL Server installation.
+ This property is optional, and most installations should work without the need to specify
+ an instance name.</para>
+ <para>The <property>sqlserver-driver</property> allows you to choose the compatibility mode of
+ of the module with various TDS-compatible drivers such that it can be used with different
+ versions of SQL Server and even non-Microsoft SQL Server TDS-compatible databases. The
+ following options are available for the <property>sqlserver-driver</property> property:
<variablelist>
<varlistentry>
<term>microsoft2005</term>
@@ -355,11 +676,11 @@
does not already exist.</para>
</step>
<step>
- <para>Copy <filename>guacamole-auth-jdbc-mysql-1.1.0.jar</filename>
+ <para>Copy <filename>guacamole-auth-jdbc-mysql-1.2.0.jar</filename>
<emphasis>or</emphasis>
- <filename>guacamole-auth-jdbc-postgresql-1.1.0.jar</filename>
+ <filename>guacamole-auth-jdbc-postgresql-1.2.0.jar</filename>
<emphasis>or</emphasis>
- <filename>guacamole-auth-jdbc-sqlserver-1.1.0.jar</filename> within
+ <filename>guacamole-auth-jdbc-sqlserver-1.2.0.jar</filename> within
<filename>GUACAMOLE_HOME/extensions</filename>, depending on whether you are
using MySQL/MariaDB, PostgreSQL, or SQL Server.</para>
</step>
@@ -692,6 +1013,32 @@
Guacamole will report that the login is invalid, as if the user does not exist at
all.</para>
</section>
+ <section xml:id="jdbc-auth-auto-create">
+ <title>Auto-creating database users</title>
+ <para>Guacamole supports the ability to layer authentication modules on top of one another
+ such that users successfully authenticated from one extension (e.g. LDAP) can be assigned
+ permissions to connections in another extension (e.g. JDBC). Other extensions, like the
+ TOTP extension, rely on the database extension to be able to store information for
+ various user accounts. In these situations it can be difficult to have to manually
+ create user accounts within the database extension.</para>
+ <para>The database extension provides a mechanism for enabling auto-creation of user
+ accounts that successfully authenticate from other extensions. This functionality
+ is disabled by default, but can be enabled in each of the supported database
+ extensions by enabling the appropriate option in guacamole.properties. The
+ resulting accounts will only have READ access to themselves until additional
+ permissions are granted, either explicitly by the administrator or by
+ permissions assigned to groups of which the user is a member.</para>
+ <informalexample>
+ <programlisting># MySQL
+mysql-auto-create-accounts: true
+
+# PostgreSQL
+postgresql-auto-create-accounts: true
+
+# SQL Server
+sqlserver-auto-create-accounts: true</programlisting>
+ </informalexample>
+ </section>
<section>
<title>Completing the installation</title>
<para>Guacamole will only reread <filename>guacamole.properties</filename> and load
diff --git a/src/chapters/ldap-auth.xml b/src/chapters/ldap-auth.xml
index 52ee98f..c4c2410 100644
--- a/src/chapters/ldap-auth.xml
+++ b/src/chapters/ldap-auth.xml
@@ -83,7 +83,7 @@
containing:</para>
<variablelist>
<varlistentry>
- <term><filename>guacamole-auth-ldap-1.1.0.jar</filename></term>
+ <term><filename>guacamole-auth-ldap-1.2.0.jar</filename></term>
<listitem>
<para>The Guacamole LDAP support extension itself, which must be placed in
<filename>GUACAMOLE_HOME/extensions</filename>.</para>
@@ -214,7 +214,7 @@
does not already exist.</para>
</step>
<step>
- <para>Copy <filename>guacamole-auth-ldap-1.1.0.jar</filename> within
+ <para>Copy <filename>guacamole-auth-ldap-1.2.0.jar</filename> within
<filename>GUACAMOLE_HOME/extensions</filename>.</para>
</step>
<step>
@@ -370,6 +370,44 @@
</listitem>
</varlistentry>
<varlistentry>
+ <term><property>ldap-member-attribute-type</property></term>
+ <listitem>
+ <para>Specify whether the attribute defined in
+ "<property>ldap-member-attribute</property>" (Usually
+ "<property>member</property>") identifies a group member by DN or by
+ usercode. Possible values: "<property>dn</property>" (the default, if
+ not specified) or "<property>uid</property>".</para>
+ <para>Example: an LDAP server may present groups using the
+ <classname>groupOfNames</classname> scheme
+ <informalexample>
+ <programlisting>dn: cn=group1,ou=Groups,dc=example,dc=net
+objectClass: groupOfNames
+cn: group1
+gidNumber: 12345
+member: user1,ou=People,dc=example,dc=net
+member: user2,ou=People,dc=example,dc=net</programlisting>
+ </informalexample>
+ <property>ldap-member-attribute</property> is
+ <systemitem>member</systemitem> and
+ <property>ldap-member-attribute-type</property> is
+ <systemitem>dn</systemitem></para>
+ <para>Example: an LDAP server may present groups using the
+ <classname>posixGroup</classname> scheme
+ <informalexample>
+ <programlisting>dn: cn=group1,ou=Groups,dc=example,dc=net
+objectClass: posixGroup
+cn: group1
+gidNumber: 12345
+memberUid: user1
+memberUid: user2</programlisting>
+ </informalexample>
+ <property>ldap-member-attribute</property> is
+ <systemitem>memberUid</systemitem> and
+ <property>ldap-member-attribute-type</property> is
+ <systemitem>uid</systemitem></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term><property>ldap-user-attributes</property></term>
<listitem>
<para>The attribute or attributes to retrieve from the LDAP directory for
diff --git a/src/chapters/openid-auth.xml b/src/chapters/openid-auth.xml
index 78c43d2..dd98f86 100644
--- a/src/chapters/openid-auth.xml
+++ b/src/chapters/openid-auth.xml
@@ -31,7 +31,7 @@
>http://guacamole.apache.org/releases/</link>.</para>
<para>The OpenID Connect authentication extension is packaged as a
<filename>.tar.gz</filename> file containing only the extension itself,
- <filename>guacamole-auth-openid-1.1.0.jar</filename>, which must ultimately be
+ <filename>guacamole-auth-openid-1.2.0.jar</filename>, which must ultimately be
placed in <filename>GUACAMOLE_HOME/extensions</filename>.</para>
</section>
<section xml:id="installing-openid-auth">
@@ -48,7 +48,7 @@
does not already exist.</para>
</step>
<step>
- <para>Copy <filename>guacamole-auth-openid-1.1.0.jar</filename> within
+ <para>Copy <filename>guacamole-auth-openid-1.2.0.jar</filename> within
<filename>GUACAMOLE_HOME/extensions</filename>.</para>
</step>
<step>
diff --git a/src/chapters/radius-auth.xml b/src/chapters/radius-auth.xml
index d48b9e5..e226493 100644
--- a/src/chapters/radius-auth.xml
+++ b/src/chapters/radius-auth.xml
@@ -29,7 +29,7 @@
<screen><prompt>$</prompt> <userinput>mvn clean package -Plgpl-extensions</userinput>
<computeroutput>[INFO] --- maven-assembly-plugin:2.5.3:single (make-source-archive) @ guacamole-client ---
[INFO] Reading assembly descriptor: project-assembly.xml
-[INFO] Building tar: /home/guac/guacamole-client/target/guacamole-client-1.1.0.tar.gz
+[INFO] Building tar: /home/guac/guacamole-client/target/guacamole-client-1.2.0.tar.gz
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
@@ -65,7 +65,7 @@
<para>After the build completes successfully, the extension will be in the
<filename>extensions/guacamole-auth-radius/target/</filename> directory, and will be
- called guacamole-auth-radius-1.1.0.jar. This extension file can be copied to
+ called guacamole-auth-radius-1.2.0.jar. This extension file can be copied to
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
@@ -86,7 +86,7 @@
does not already exist.</para>
</step>
<step>
- <para>Copy <filename>guacamole-auth-radius-1.1.0.jar</filename> into
+ <para>Copy <filename>guacamole-auth-radius-1.2.0.jar</filename> into
<filename>GUACAMOLE_HOME/extensions</filename>.</para>
</step>
<step>
diff --git a/src/chapters/saml-auth.xml b/src/chapters/saml-auth.xml
new file mode 100644
index 0000000..1fa89d3
--- /dev/null
+++ b/src/chapters/saml-auth.xml
@@ -0,0 +1,179 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<chapter xml:id="saml-auth" 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>SAML Authentication</title>
+ <indexterm>
+ <primary>SAML Authentication</primary>
+ </indexterm>
+ <para>SAML is a widely implemented and used Single Sign On (SSO) provider that allows
+ applications and services to authenticate in a standard way, and brokers those
+ authentication requests to one or more back-end authentication providers. The SAML
+ authentication extension allows Guacamole to redirect to a SAML Identity Provider (IdP)
+ for authentication and user services. This module does not provide any capability
+ for storing or retrieving connections, and must be layered with other authentication
+ extensions that provide connection management.</para>
+ <section xml:id="saml-downloading">
+ <title>Downloading the SAML authentication extension</title>
+ <para>The SAML authentication 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 on 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 SAML authentication extension is packaged as a <filename>.tar.gz</filename>
+ file containing only the extension itself,
+ <filename>guacamole-auth-saml-1.2.0.jar</filename>, which must
+ ultimately be placed in <filename>GUACAMOLE_HOME/extensions</filename>.</para>
+ </section>
+ <section xml:id="installing-saml-auth">
+ <title>Installing SAML authentication</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 SAML authentication 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>Copy <filename>guacamole-auth-saml-1.2.0.jar</filename> within
+ <filename>GUACAMOLE_HOME/extensions</filename>.</para>
+ </step>
+ <step>
+ <para>Configure Guacamole to use SAML authentication, as described
+ below.</para>
+ </step>
+ </procedure>
+ <section xml:id="guac-saml-config">
+ <title>Configuring Guacamole for SAML Authentication</title>
+ <indexterm>
+ <primary>configuring SAML authentication</primary>
+ </indexterm>
+ <indexterm>
+ <primary>SAML authentication</primary>
+ <secondary>configuration</secondary>
+ </indexterm>
+ <para>The SAML authentication extension provides several configuration properties
+ to set it up to talk to the IdP. The SAML IdP also must be configured with
+ Guacamole as a Service Provider (SP). Configuration of the SAML IdP is beyond
+ the scope of this document, and will vary widely based on the IdP in use.</para>
+ <variablelist>
+ <varlistentry>
+ <term><property>saml-idp-metadata-url</property></term>
+ <listitem>
+ <para>The URI of the XML metadata file that from the
+ SAML Identity Provider that contains all of the
+ information the SAML extension needs in order to
+ know how to authenticate with the IdP. This URI can
+ either be a remote server (e.g. https://) or a local
+ file on the filesystem (e.g. file://). Often the
+ metadata file contains most of the required
+ properties for SAML authentication and the other
+ parameters are not required.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>saml-idp-url</property></term>
+ <listitem>
+ <para>The base URL of the SAML IdP. This is the URL that
+ the SAML authentication extension will use to redirect
+ when requesting SAML authentication. If the
+ <property>saml-idp-metadata</property> property is
+ provided, this parameter will be ignored. If the metadata
+ file is not provided this property is required.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>saml-entity-id</property></term>
+ <listitem>
+ <para>The entity ID of the Guacamole SAML client, which is
+ generally the URL of the Guacamole server, but is not
+ required to be so. This property is required if
+ either the <property>saml-idp-metadata-url</property>
+ property is not specified, or if the provided
+ metadata file does not contain the SAML SP Entity
+ ID for Guacamole Client.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>saml-callback-url</property></term>
+ <listitem>
+ <para>The URL that the IdP will use once authentication has
+ succeeded to return to the Guacamole web application and
+ provide the authentication details to the SAML extension.
+ The SAML extension currently only supports callback as a
+ POST operation to this callback URL. This property
+ is required.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>saml-strict</property></term>
+ <listitem>
+ <para>Require strict security checks during SAML logins.
+ This will insure that valid certificates are
+ present for all interactions with SAML servers and
+ fail SAML authentication if security restrictions
+ are violated. This property is optional, and will
+ default to true, requiring strict security checks.
+ This property should only be set to false in
+ non-production environments during testing of
+ SAML authentication.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>saml-debug</property></term>
+ <listitem>
+ <para>Enable additional logging within the supporting
+ SAML library that can assist in tracking down issues
+ during SAML logins. This property is optional, and
+ will default to false (no debugging).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>saml-compress-request</property></term>
+ <listitem>
+ <para>Enable compression of the HTTP requests sent to
+ the SAML IdP. This property is optional and will
+ default to true (compression enabled).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>saml-compress-response</property></term>
+ <listitem>
+ <para>Request that the SAML response returned by the
+ IdP be compressed. This property is optional and
+ will default to true (compression will be requested).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>saml-group-attribute</property></term>
+ <listitem>
+ <para>The name of the attribute provided by the SAML IdP
+ that contains group membership of the user. These
+ groups will be parsed and used to map group
+ membership of the user logging in, which can be used
+ for permissions management within Guacamole Client,
+ particularly when layered with other authentication
+ modules. This property is optional, and defaults to
+ "groups".</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ <section xml:id="completing-saml-install">
+ <title>Completing the installation</title>
+ <para>Guacamole will only reread <filename>guacamole.properties</filename> and load
+ newly-installed extensions during startup, so your servlet container will need to be
+ restarted before SAML authentication 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 new authentication a try.</para>
+ </section>
+ </section>
+</chapter>
diff --git a/src/chapters/totp-auth.xml b/src/chapters/totp-auth.xml
index b5e923b..ca9bd53 100644
--- a/src/chapters/totp-auth.xml
+++ b/src/chapters/totp-auth.xml
@@ -21,28 +21,11 @@
<section xml:id="totp-prerequisites">
<title>Prerequisites</title>
<para>The enrollment process used by Guacamole's TOTP support needs to be able to store an
- automatically-generated key within the user's account, and will be operating with the
- privileges of that user when it does so. With this in mind, there are requirements which
- must be satisfied for TOTP to work as expected:</para>
- <itemizedlist>
- <listitem>
- <para>Another extension must be installed which supports storage of arbitrary data
- from other extensions. <emphasis>Currently the only extensions provided with
- Guacamole which support this kind of storage are the <link
- linkend="jdbc-auth">database authentication
- extensions</link>.</emphasis></para>
- </listitem>
- <listitem>
- <para>Within whichever extension provides the storage described above, users
- requiring TOTP must be granted permission to update their own accounts (to
- update their passwords, etc.). This privilege is managed within the <link
- linkend="user-management">administrative web interface</link> with a
- checkbox labeled "change own password". <emphasis>If a user lacks this
- permission, the TOTP extension will not be able to generate and store the
- user's TOTP key during enrollment, and TOTP will be disabled for that
- user.</emphasis></para>
- </listitem>
- </itemizedlist>
+ automatically-generated key within the user's account. Another extension must be
+ installed which supports storage of arbitrary data from other extensions.
+ <emphasis>Currently the only extensions provided with Guacamole which support this
+ kind of storage are the <link linkend="jdbc-auth">database authentication
+ extensions</link>.</emphasis></para>
<para>It is thus recommended that authentication against a database be fully configured
prior to setting up TOTP. Instructions walking through the setup of database
authentication for Guacamole are provided in <xref linkend="jdbc-auth"/>.</para>
@@ -110,7 +93,7 @@
>http://guacamole.apache.org/releases/</link>.</para>
<para>The TOTP authentication extension is packaged as a <filename>.tar.gz</filename> file
containing only the extension itself,
- <filename>guacamole-auth-totp-1.1.0.jar</filename>, which must ultimately be placed in
+ <filename>guacamole-auth-totp-1.2.0.jar</filename>, which must ultimately be placed in
<filename>GUACAMOLE_HOME/extensions</filename>.</para>
</section>
<section xml:id="installing-totp-auth">
@@ -124,7 +107,7 @@
does not already exist.</para>
</step>
<step>
- <para>Copy <filename>guacamole-auth-totp-1.1.0.jar</filename> within
+ <para>Copy <filename>guacamole-auth-totp-1.2.0.jar</filename> within
<filename>GUACAMOLE_HOME/extensions</filename>.</para>
</step>
<step>
diff --git a/src/chapters/troubleshooting.xml b/src/chapters/troubleshooting.xml
index 31c0787..3d253bd 100644
--- a/src/chapters/troubleshooting.xml
+++ b/src/chapters/troubleshooting.xml
@@ -427,22 +427,30 @@
connection in use and try again.</para>
</section>
<section>
- <title>Failed to load cliprdr plugin</title>
- <para>FreeRDP provides a plugin called "cliprdr" which provides
- clipboard support for RDP. libguac-client-rdp loads this
- plugin in order to support clipboard, as well. If this
- plugin could not be loaded, then clipboard support will not
- be available, and the reason will be logged.</para>
+ <title>Support for the CLIPRDR channel (clipboard redirection) could not be
+ loaded</title>
+ <para>FreeRDP provides a plugin which provides clipboard support for RDP. This
+ plugin is typically built into FreeRDP, but some distributions may bundle this
+ separately. libguac-client-rdp loads this plugin in order to support clipboard,
+ as well. If this plugin could not be loaded, then clipboard support will not be
+ available, and the reason will be logged.</para>
</section>
<section>
- <title>Failed to load guac_rdpsnd plugin</title>
- <para>In order to support sound, libguac-client-rdp builds a
- plugin for FreeRDP called "guac_rdpsnd" which must be loaded
- for sound to be available. If libguac-client-rdp cannot load
- this plugin, sound will not work, and the reason will be
- logged. A likely explanation is that libguac-client-rdp was
- built from source, and the directory specified for FreeRDP's
- installation location was incorrect.</para>
+ <title>Cannot create static channel "<replaceable>name</replaceable>": failed to
+ load "guac-common-svc" plugin for FreeRDP</title>
+ <para>RDP provides support for much of its feature set through static virtual
+ channels. Sound support, for example is provided through the "RDPSND" channel.
+ Device redirection for printers and drives is provided through "RDPDR". To
+ support these and other static virtual channels, libguac-client-rdp builds a
+ plugin for FreeRDP called "guac-common-svc" which allows Guacamole to hook into
+ the parts of FreeRDP that support virtual channels.</para>
+ <para>If libguac-client-rdp cannot load this plugin, support for any features which
+ leverage static virtual channels will not work, and the reason will be logged. A
+ likely explanation is that libguac-client-rdp was built from source, and the
+ directory specified for FreeRDP's installation location was incorrect. For
+ FreeRDP to be able to find plugins, those plugins must be placed in the
+ <filename>freerdp2/</filename> subdirectory of whichever directory contains
+ the <filename>libfreerdp2.so</filename> library.</para>
</section>
<section>
<title>Server requested unsupported clipboard data type</title>
diff --git a/src/chapters/yourown.xml b/src/chapters/yourown.xml
index 6b07048..daa41c6 100644
--- a/src/chapters/yourown.xml
+++ b/src/chapters/yourown.xml
@@ -112,7 +112,7 @@
<groupId>org.apache.guacamole</groupId>
<artifactId>guacamole-tutorial</artifactId>
<packaging>war</packaging>
- <version>1.1.0</version>
+ <version>1.2.0</version>
<name>guacamole-tutorial</name>
<properties>
@@ -201,7 +201,7 @@
</informalexample>
<para>Assuming you see the "<computeroutput>BUILD SUCCESSFUL</computeroutput>" message
when you build the web application, there will be a new file,
- <filename>target/guacamole-tutorial-1.1.0.war</filename>, which
+ <filename>target/guacamole-tutorial-1.2.0.war</filename>, which
can be deployed to your servlet container and tested. If you changed the name or
version of the project in the <filename>pom.xml</filename> file, the name of this new
<filename>.war</filename> file will be different, but it can still be found
@@ -312,7 +312,7 @@
<dependency>
<groupId>org.apache.guacamole</groupId>
<artifactId>guacamole-common-js</artifactId>
- <version>1.1.0</version>
+ <version>1.2.0</version>
<type>zip</type>
<scope>runtime</scope>
</dependency>
@@ -331,7 +331,7 @@
web application should build successfully, and the Guacamole JavaScript API should
be accessible in the <filename>guacamole-common-js/</filename> subdirectory of your
web application after it is deployed. A quick check that you can access
- <uri>/guacamole-tutorial-1.1.0/guacamole-common-js/all.min.js</uri>
+ <uri>/guacamole-tutorial-1.2.0/guacamole-common-js/all.min.js</uri>
is probably worth the effort.</para>
</section>
<section xml:id="simple-tunnel">
@@ -430,7 +430,7 @@
to the URL we wish to use when making HTTP requests to the servlet:
<uri>/tunnel</uri>. This URL is relative to the context root of the web
application. In the case of this web application, the final absolute URL will be
- <uri>/guacamole-tutorial-1.1.0/tunnel</uri>.</para>
+ <uri>/guacamole-tutorial-1.2.0/tunnel</uri>.</para>
</section>
<section xml:id="simple-client">
<title>Adding the client</title>
diff --git a/src/gug.xml b/src/gug.xml
index c0c930c..f09ba87 100644
--- a/src/gug.xml
+++ b/src/gug.xml
@@ -3,7 +3,7 @@
xmlns:xi="http://www.w3.org/2001/XInclude">
<info>
<title>Guacamole Manual</title>
- <edition>1.1.0</edition>
+ <edition>1.2.0</edition>
<legalnotice>
<para>Licensed to the Apache Software Foundation (ASF) under one or more contributor
license agreements. See the <link xmlns:xlink="http://www.w3.org/1999/xlink"
@@ -42,7 +42,7 @@
application, etc.) to give a good starting point beyond simply looking at the Guacamole
codebase.</para>
<para>This particular edition of the <citetitle>Guacamole Manual</citetitle> covers
- Guacamole version 1.1.0. New releases which create new features or break
+ Guacamole version 1.2.0. New releases which create new features or break
compatibility will result in new editions of the user's guide, as will any necessary
corrections. As the official documentation for the project, this book will always be
freely available in its entirety online.</para>
@@ -165,6 +165,7 @@
<xi:include href="chapters/header-auth.xml"/>
<xi:include href="chapters/cas-auth.xml"/>
<xi:include href="chapters/openid-auth.xml"/>
+ <xi:include href="chapters/saml-auth.xml"/>
<xi:include href="chapters/radius-auth.xml"/>
<xi:include href="chapters/adhoc-connections.xml"/>
<xi:include href="chapters/using.xml"/>
diff --git a/tutorials/guacamole-auth-tutorial/pom.xml b/tutorials/guacamole-auth-tutorial/pom.xml
index 9dd5f00..1ee80c9 100644
--- a/tutorials/guacamole-auth-tutorial/pom.xml
+++ b/tutorials/guacamole-auth-tutorial/pom.xml
@@ -7,7 +7,7 @@
<groupId>org.apache.guacamole</groupId>
<artifactId>guacamole-auth-tutorial</artifactId>
<packaging>jar</packaging>
- <version>1.1.0</version>
+ <version>1.2.0</version>
<name>guacamole-auth-tutorial</name>
<properties>
@@ -37,7 +37,7 @@
<dependency>
<groupId>org.apache.guacamole</groupId>
<artifactId>guacamole-ext</artifactId>
- <version>1.1.0</version>
+ <version>1.2.0</version>
<scope>provided</scope>
</dependency>
diff --git a/tutorials/guacamole-auth-tutorial/src/main/resources/guac-manifest.json b/tutorials/guacamole-auth-tutorial/src/main/resources/guac-manifest.json
index af7ca26..2e02cc4 100644
--- a/tutorials/guacamole-auth-tutorial/src/main/resources/guac-manifest.json
+++ b/tutorials/guacamole-auth-tutorial/src/main/resources/guac-manifest.json
@@ -1,6 +1,6 @@
{
- "guacamoleVersion" : "1.1.0",
+ "guacamoleVersion" : "1.2.0",
"name" : "Tutorial Authentication Extension",
"namespace" : "guac-auth-tutorial",
diff --git a/tutorials/guacamole-tutorial/pom.xml b/tutorials/guacamole-tutorial/pom.xml
index 02e13aa..fb3977c 100644
--- a/tutorials/guacamole-tutorial/pom.xml
+++ b/tutorials/guacamole-tutorial/pom.xml
@@ -7,7 +7,7 @@
<groupId>org.apache.guacamole</groupId>
<artifactId>guacamole-tutorial</artifactId>
<packaging>war</packaging>
- <version>1.1.0</version>
+ <version>1.2.0</version>
<name>guacamole-tutorial</name>
<properties>
@@ -70,7 +70,7 @@
<dependency>
<groupId>org.apache.guacamole</groupId>
<artifactId>guacamole-common-js</artifactId>
- <version>1.1.0</version>
+ <version>1.2.0</version>
<type>zip</type>
<scope>runtime</scope>
</dependency>
