GUACAMOLE-197: Merge documentation for RADIUS support.
diff --git a/src/chapters/radius-auth.xml b/src/chapters/radius-auth.xml
new file mode 100644
index 0000000..db2b38b
--- /dev/null
+++ b/src/chapters/radius-auth.xml
@@ -0,0 +1,255 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<chapter xml:id="radius-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>RADIUS Authentication</title>
+ <indexterm>
+ <primary>RADIUS Authentication</primary>
+ </indexterm>
+ <para>Guacamole supports delegating authentication to a RADIUS service, such as FreeRADIUS, to
+ validate username and password combinations, and to support multi-factor authentication. This
+ authentication method must be layered on top of some other authentication extension, such as
+ those available from the main project website, in order to provide access to actual
+ connections.</para>
+ <section xml:id="radius-downloading">
+ <title>Downloading the RADIUS authentication extension</title>
+ <para>The RADIUS extension depends on software that is covered by a LGPL license, which is
+ incompatible with the Apache 2.0 license under which Guacamole is licensed. Due to this
+ dependency, the Guacamole project cannot distribute binary versions of the RADIUS extension.
+ If you want to use this extension you will need to build the code - or at least the RADIUS
+ extension yourself. Build instructions can be found in the section
+ <xref linkend="installing-guacamole"/>.</para>
+ </section>
+ <section xml:id="installing-radius-auth">
+ <title>Installing RADIUS authentication</title>
+ <para>The RADIUS extension must be explicitly enabled during build time in order to generate
+ the binaries and resulting JAR file. This is done by adding the flag <option>-Plgpl-extensions</option>
+ to the Maven command line during the build, and should result in the output below:</para>
+ <informalexample>
+ <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-0.9.14.tar.gz
+[INFO] ------------------------------------------------------------------------
+[INFO] Reactor Summary:
+[INFO]
+[INFO] guacamole-common .................................. SUCCESS [6.037s]
+[INFO] guacamole-ext ..................................... SUCCESS [5.382s]
+[INFO] guacamole-common-js ............................... SUCCESS [0.751s]
+[INFO] guacamole ......................................... SUCCESS [9.767s]
+[INFO] guacamole-auth-cas ................................ SUCCESS [2.811s]
+[INFO] guacamole-auth-duo ................................ SUCCESS [2.441s]
+[INFO] guacamole-auth-header ............................. SUCCESS [1.875s]
+[INFO] guacamole-auth-jdbc ............................... SUCCESS [0.277s]
+[INFO] guacamole-auth-jdbc-base .......................... SUCCESS [2.144s]
+[INFO] guacamole-auth-jdbc-mysql ......................... SUCCESS [5.637s]
+[INFO] guacamole-auth-jdbc-postgresql .................... SUCCESS [5.465s]
+[INFO] guacamole-auth-jdbc-sqlserver ..................... SUCCESS [5.398s]
+[INFO] guacamole-auth-jdbc-dist .......................... SUCCESS [0.824s]
+[INFO] guacamole-auth-ldap ............................... SUCCESS [2.743s]
+[INFO] guacamole-auth-noauth ............................. SUCCESS [0.964s]
+[INFO] guacamole-auth-openid ............................. SUCCESS [2.533s]
+[INFO] guacamole-example ................................. SUCCESS [0.888s]
+[INFO] guacamole-playback-example ........................ SUCCESS [0.628s]
+[INFO] guacamole-auth-radius ............................. SUCCESS [17.729s]
+[INFO] guacamole-client .................................. SUCCESS [5.645s]
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 1:20.134s
+[INFO] Finished at: Wed Jan 31 09:45:41 EST 2018
+[INFO] Final Memory: 47M/749M
+[INFO] ------------------------------------------------------------------------</computeroutput>
+<prompt>$</prompt></screen>
+ </informalexample>
+
+ <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-0.9.14.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
+ proceeding.</emphasis></para>
+
+ <para>Extensions are loaded in alphabetical order, and authentication is performed
+ in the order in which the extensions were loaded. If you are stacking the
+ RADIUS extension with another extension, like the JDBC extension, in order to
+ store connection information, you may need to change the name of the RADIUS
+ extension such that it is evaluated prior to the JDBC extension - otherwise
+ an authentication failure in one of the previous modules may block the RADIUS
+ module from ever being evaluated.</para>
+
+ <para>To install the RADIUS 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-radius-0.9.14.jar</filename> into
+ <filename>GUACAMOLE_HOME/extensions</filename>.</para>
+ </step>
+ <step>
+ <para>Configure Guacamole to use RADIUS authentication, as described
+ below.</para>
+ </step>
+ </procedure>
+ </section>
+ <section xml:id="guac-radius-config">
+ <title>Configuring Guacamole for RADIUS authentication</title>
+ <indexterm>
+ <primary>configuring RADIUS authentication</primary>
+ </indexterm>
+ <indexterm>
+ <primary>RADIUS authentication</primary>
+ <secondary>configuration</secondary>
+ </indexterm>
+ <para>This extension provides several configuration properties in order
+ to communicate properly with the RADIUS server to which it needs to authenticate. It is
+ important that you know several key pieces of information about the RADIUS server -
+ at a minimum, the server name or IP, the authentication port, the authentication
+ protocol in use by the server, and the shared secret for the RADIUS client. If you
+ are responsible for the RADIUS server, you'll need to properly configure these items
+ to get Guacamole to authenticate properly. If you're not responsible for the RADIUS
+ server you will need to work with the administrator to get all of the necessary
+ configuration items for the server. These items will need to be configured in the
+ <link linkend="initial-setup"><filename>guacamole.properties</filename></link>
+ file.</para>
+ <variablelist>
+ <varlistentry>
+ <term><property>radius-hostname</property></term>
+ <listitem>
+ <para>The RADIUS server to authenticate against. If not specified,
+ localhost will be used.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-auth-port</property></term>
+ <listitem>
+ <para>The RADIUS authentication port on which the RADIUS service is
+ is listening. If not specified, the default of 1812 will be
+ used.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-shared-secret</property></term>
+ <listitem>
+ <para>The shared secret to use when talking to the RADIUS server. This
+ parameter is required and the extension will not load if this is not
+ specified.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-auth-protocol</property></term>
+ <listitem>
+ <para>The authentication protocol to use when talking to the RADIUS server.
+ This parameter is required for the extension to operate. Supported
+ values are: pap, chap, mschapv1, mschapv2, eap-md5, eap-tls, and eap-ttls.
+ Support for PEAP is implemented inside the extension, but, due to a regression
+ in the JRadius implementation, it is currently broken. Also, if you specify
+ eap-ttls you will also need to specify the
+ <property>radius-eap-ttls-inner-protocol</property> parameter in order to
+ properly configure the protocol used inside the EAP TTLS tunnel.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-key-file</property></term>
+ <listitem>
+ <para>The combination certificate and private key pair to use for TLS-based
+ RADIUS protocols that require a client-side certificate. This parameter
+ should specify the absolute path to the file. By default the extension
+ will look for a file called radius.key in the GUACAMOLE_HOME directory.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-key-type</property></term>
+ <listitem>
+ <para>The file type of the keystore specified by the <property>radius-key-file</property>
+ parameter. Valid keystore types are pem, jceks, jks, and pkcs12.
+ If not specified, this defaults to pkcs12, the default used by
+ the JRadius library.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-key-password</property></term>
+ <listitem>
+ <para>The password of the private key specified in the
+ <property>radius-key-file</property> parameter. By default the extension
+ will not use any password when trying to open the key file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-ca-file</property></term>
+ <listitem>
+ <para>The absolute path to the file that stores the certificate authority
+ certificates for encrypted connections to the RADIUS server. By default
+ a file with the name ca.crt in the GUACAMOLE_HOME directory will be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-ca-type</property></term>
+ <listitem>
+ <para>The file type of keystore used for the certificate authority. Valid formats are
+ pem, jceks, jks, and pkcs12. If not specified this defaults to pem.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-ca-password</property></term>
+ <listitem>
+ <para>The password used to protect the certificate authority store, if
+ any. If unspecified the extension will attempt to read the CA
+ store without any password.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-trust-all</property></term>
+ <listitem>
+ <para>This parameter controls whether or not the RADIUS extension
+ should trust all certificates or verify them against known good
+ certificate authorities. Set to true to allow the RADIUS server
+ to connect without validating certificates. The default is false,
+ which causes certificates to be validated.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-retries</property></term>
+ <listitem>
+ <para>The number of times the client will retry the connection to the
+ RADIUS server and not receive a response before giving up. By default
+ the client will try the connection at most 5 times.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-timeout</property></term>
+ <listitem>
+ <para>The timeout for a RADIUS connection in seconds. By default the client
+ will wait for a response from the server for at most 60 seconds.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><property>radius-eap-ttls-inner-protocol</property></term>
+ <listitem>
+ <para>When EAP-TTLS is used, this parameter specifies the inner (tunneled)
+ protocol to use talking to the RADIUS server. It is required when the
+ <property>radius-auth-protocol</property> parameter is set to eap-ttls.
+ If the <property>radius-auth-protocol</property> value is set to something
+ other than eap-ttls, this parameter has no effect and will be ignored. Valid
+ options for this are any of the values for
+ <property>radius-auth-protocol</property>, except for eap-ttls.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ <section xml:id="completing-radius-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 HTTP header 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>
+</chapter>
diff --git a/src/gug.xml b/src/gug.xml
index a953f40..fc39401 100644
--- a/src/gug.xml
+++ b/src/gug.xml
@@ -164,6 +164,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/radius-auth.xml"/>
<xi:include href="chapters/using.xml"/>
<xi:include href="chapters/administration.xml"/>
<xi:include href="chapters/troubleshooting.xml"/>
