Github user mike-jumper commented on a diff in the pull request:
https://github.com/apache/guacamole-manual/pull/33#discussion_r165735697
--- Diff: src/chapters/radius-auth.xml ---
@@ -0,0 +1,251 @@
+<?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 type of the key file specified by the
<property>radius-key-file</property>
+ parameter. 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 type of file store used for the certificate
authority. 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>A boolean value indicating whether or not the
RADIUS extension
--- End diff --
Similar to the problem with telling users the default is "null",
documenting that the property is a boolean value is not necessarily sufficient
to inform users that the property can be set to "true" or "false". The default
is nicely documented here, but the fact that this should be set to "true" to
trust all certificates needs to be explicit.
---
