[5538] RADIUS hook documentation added.

doc/guide/Makefile.am

@@ -8,6 +8,7 @@ dist_html_DATA = $(HTMLDOCS) kea-guide.css kea-logo-100x70.png
 DOCBOOK = kea-guide.xml intro.xml quickstart.xml install.xml admin.xml config.xml
 DOCBOOK += keactrl.xml dhcp4-srv.xml dhcp6-srv.xml lease-expiration.xml logging.xml
 DOCBOOK += ddns.xml hooks.xml libdhcp.xml lfc.xml stats.xml ctrl-channel.xml faq.xml
+DOCBOOK += hooks-host-cache.xml hooks-radius.xml
 DOCBOOK += classify.xml shell.xml agent.xml
 
 EXTRA_DIST = $(DOCBOOK)

doc/guide/hooks-host-cache.xml

@@ -0,0 +1,4 @@
+<section xml:id="hooks-host-cache">
+  <title>host_cache: Caching Host Reservations</title>
+  <para>todo</para>
+</section>

doc/guide/hooks-radius.xml

@@ -0,0 +1,493 @@
+<!--
+ - Copyright (C) 2018 Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ -
+ - This license applies to the documentation itself, not the software.
+-->
+
+
+
+<section xml:id="hooks-radius">
+  <title>radius: RADIUS server support</title>
+  <para>
+    The RADIUS hook library allows Kea to interact with two types of
+    RADIUS servers: access and accounting. Although the most common
+    DHCP and RADIUS integration is done on DHCP relay agent level
+    (DHCP clients send DHCP packets to DHCP relays; relays contact
+    RADIUS server and depending on the response either send the packet
+    to the DHCP server or drop it), it does require a DHCP relay
+    hardware to support RADIUS communication. Also, even if the relay
+    has necessary support it is often not flexible enough to send and
+    receive additional RADIUS attributes. As such, the alternative
+    looks more appealing: to extend DHCP server to talk to RADIUS
+    directly. That is the goal this library intends to fulfill.
+  </para>
+  <para>
+    The major feature of the library is the ability to use RADIUS
+    authentication. When a DHCP packet is received, the Kea server
+    will send send Access-Request to the RADIUS server and will await
+    a response. The server will then send back either Access-Accept
+    with specific client attributes or Access-Reject. There are two
+    cases supported here. First, the Access-Accept includes
+    Framed-IP-Address (for DHCPv4) or Framed-IPv6-Address (for
+    DHCPv6), which will be interpreted by Kea as an instruction to
+    assign that specified IPv4 or IPv6 address. This effectively
+    means RADIUS can act as address reservation database.
+  </para>
+  <para>
+    The second case supported is the ability to assign clients to
+    specific pools based on RADIUS response. In this case RADIUS
+    server sends back Access-Accept with Framed-Pool (IPv4) or
+    Framed-IPv6-Pool (IPv6). In both cases, Kea will interpret those
+    attributes as client classes. With the recent addition of the
+    ability to limit access to pools to specific classes (see <xref
+    linkend="classification-pools"/>), it can be used to force client
+    to be assigned a dynamic address from specific pool. Furthermore,
+    the same mechanism can be used to control what kind of options the
+    client will get (if there are DHCP options specified for a
+    particular class).
+  </para>
+
+  <section id="hooks-radius-install">
+    <title>Compilation and Installation of RADIUS Hook</title>
+    <para>
+      The following section describes how to compile and install the
+      software on CentOS 7.0. Other systems may differ slightly.
+    </para>
+
+    <para>
+      STEP 1: Install dependencies
+    </para>
+    <para>
+      Several tools are needed to build dependencies and Kea
+      itself. The following commands should install them:
+<screen>
+$ sudo rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
+$ sudo yum install gcc-g++ openssl-devel log4cplus-devel wget git
+</screen>
+    </para>
+    
+    <para>
+      STEP 2: FreeRADIUS installation.
+    </para>
+      <para>
+      Kea RADIUS hook library uses FreeRadius client library to
+      conduct RADIUS communication. Unfortunately, the standard
+      1.1.7 release available from the project website
+      <uri xmlns:xlink="http://www.w3.org/1999/xlink"
+           xlink:href="http://freeradius.org/sub_projects/">http://freeradius.org/sub_projects/</uri>
+      has several serious deficiencies. ISC observed a segmentation
+      fault during teting. Also, the base version of the library does
+      not offer asynchronous transmissions, which is essential for
+      effective accounting implementation. Both of these issues
+      were addressed by ISC engineers. The changes have been
+      reported to FreeRadius client project. Acceptance of those
+      changes is outside of ISC responsibilities. Until those
+      are processed, it is strongly recommended to use FreeRadius
+      client with ISC patches. To and compile this version, please use
+      the following steps:
+<screen>
+$ git clone https://github.com/fxdupont/freeradius-client.git
+$ cd freeradius-client/
+$ git checkout iscdev
+$ ./configure
+$ make
+$ sudo make install
+</screen>
+
+      You may pass additional parameters to configure script, if you need
+      to. Once installed, the FreeRADIUS client will be installed in
+      /usr/local. This is the default path where Kea will be looking for
+      it. You may install it in a different directory. If you choose to do
+      so, make sure you pass that path to configure script when compiling kea.
+      </para>
+
+      <para>
+        STEP 3: Install recent BOOST version
+      </para>
+
+      <para>
+        Kea requires reasonably recent Boost version. Unfortunately,
+        the version available in CentOS 7 is too old. Therefore a
+        newer Boost version is necessary. Furthermore, CentOS 7 has an
+        old version of g++ compiler that does not handle latest Boost
+        versions. Fortunately, Boost 1.65 meets both requirements: is
+        recent enough for Kea and is still able to be compiled using
+        the g++ 4.8 version in CentOS.
+      </para>
+      <para>
+        To download and compile Boost 1.65, please use the following
+        commands:
+<screen>
+wget -nd https://dl.bintray.com/boostorg/release/1.65.1/source/boost_1_65_1.tar.gz
+tar zxvf boost_1_65_1.tar.gz
+cd boost_1_65_1/
+./bootstrap.sh
+./b2 --without-python
+</screen>
+        Note that b2 script may optionally take extra parameters. One
+        of them specify the destination path where the sources are to
+        be compiled. Boost is different compared to other software in
+        the sense that there is no explicit make install step.
+      </para>
+
+      <para>
+        STEP 4: Compile and Install Kea
+      </para>
+
+      <para>
+        Obtain Kea sources either by downloading it from git repository or extract the tarball:
+<screen>
+# Use one of those commands to obtain Kea sources:
+
+# Choice 1: get from github
+$ git clone https://github.com/isc-projects/kea
+
+# Get a tarball and extract it
+$ tar zxvf kea-1.4.0-beta.tar.gz
+</screen>
+
+The next step is to extract premium Kea package that contains Radius repository
+into the Kea sources. After the tarball is extracted, the Kea sources should have
+a premium/ subdirectory.
+
+<screen>
+  $ cd kea
+  $ tar zxvf ../kea-premium-radius-1.4.0-beta.tar.gz
+</screen>
+
+Once this is done, make sure the kea sources look similar to this:
+<screen>
+$ ls -l
+total 952
+-rw-r--r--   1 thomson  staff    6192 Apr 25 17:38 AUTHORS
+-rw-r--r--   1 thomson  staff   29227 Apr 25 17:38 COPYING
+-rw-r--r--   1 thomson  staff  360298 Apr 25 20:00 ChangeLog
+-rw-r--r--   1 thomson  staff     645 Apr 25 17:38 INSTALL
+-rw-r--r--   1 thomson  staff    5015 Apr 25 17:38 Makefile.am
+-rw-r--r--   1 thomson  staff     587 Apr 25 17:38 README
+drwxr-xr-x   5 thomson  staff     170 Apr 26 19:04 compatcheck
+-rw-r--r--   1 thomson  staff   62323 Apr 25 17:38 configure.ac
+-rw-r--r--   1 thomson  staff     300 Apr 25 17:38 dns++.pc.in
+drwxr-xr-x  12 thomson  staff     408 Apr 26 19:04 doc
+drwxr-xr-x   7 thomson  staff     238 Apr 25 17:38 examples
+drwxr-xr-x   5 thomson  staff     170 Apr 26 19:04 ext
+drwxr-xr-x   8 thomson  staff     272 Apr 26 19:04 m4macros
+drwxr-xr-x  20 thomson  staff     680 Apr 26 11:22 <userinput>premium</userinput>
+drwxr-xr-x  10 thomson  staff     340 Apr 26 19:04 src
+drwxr-xr-x  14 thomson  staff     476 Apr 26 19:04 tools
+</screen>
+
+The next step is to configure Kea. There are several essential steps necessary here.
+The --with-tier2=yes flag is necessary to compile premium package that contains
+RADIUS. Also, --with-freeradius option is necessary to tell Kea where the FreeRADIUS
+client sources can be found. Also, since the non-standard boost is used, the path
+to it has to be specified.</para>
+
+<para>If the sources are not from a tarball release, makefiles have to be regenerated
+using autoreconf.</para>
+
+<screen>
+$ autoreconf -i
+$ ./configure --with-freeradius=/path/to/freeradius --with-boost-include=/path/to/boost --with-boost-lib-dir=/path/to/boost/state/lib
+</screen>
+
+<para>
+For example, assuming FreeRadius client was installed in the default directory (/usr/local)
+and Boost 1.65 sources were compiled in /home/thomson/devel/boost1_65_1, the configure path
+should look as follows:</para>
+
+<screen>
+./configure --with-freeradius=/usr/local \
+            --with-boost-include=/home/thomson/devel/boost_1_65_1 \
+            --with-boost-lib-dir=/home/thomson/devel/boost_1_65_1/stage/lib \
+            --with-tier2=yes
+</screen>
+
+<para>
+  After some checks, the configure script should print a report similar to the
+  following:
+
+<screen>  
+  
+       Kea source configure results:
+    -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+
+Package:
+  Name:              kea
+  Version:           1.3.0-git
+  Extended version:  1.3.0-git (git c494c28cc958bb21a9c6cb0f8dc805a721c69893)
+  OS Family:         Linux
+  Using GNU sed:     yes
+  Premium package:   yes
+  Tier1 Packages:    host_cmds flex_id legal_log
+  Tier2 Packages:    high_availability subnet_cmds radius
+  Included Packages: host_cmds flex_id legal_log high_availability subnet_cmds radius
+
+C++ Compiler:
+  CXX:             g++ --std=c++11
+  CXX_VERSION:     g++ (GCC) 4.8.5 20150623 (Red Hat 4.8.5-16)
+  CXX_STANDARD:    201103
+  DEFS:            -DHAVE_CONFIG_H
+  CPPFLAGS:         -DOS_LINUX  -DBOOST_ASIO_HEADER_ONLY -DBOOST_ASIO_DISABLE_THREADS=1
+  CXXFLAGS:        -g -O2
+  LDFLAGS:          -lpthread
+  KEA_CXXFLAGS:     -Wall -Wextra -Wnon-virtual-dtor -Wwrite-strings -Woverloaded-virtual -Wno-sign-compare -pthread -Wno-missing-field-initializers -fPIC
+
+Python:
+  PYTHON_VERSION:  not needed (because kea-shell is disabled)
+
+Boost:
+  BOOST_VERSION:   1.65.1
+  BOOST_INCLUDES:  -I/home/thomson/devel/boost_1_65_1
+  BOOST_LIBS:      -L/home/thomson/devel/boost_1_65_1/stage/lib  -lboost_system
+
+OpenSSL:
+  CRYPTO_VERSION:  OpenSSL 1.0.2k  26 Jan 2017
+  CRYPTO_CFLAGS:   
+  CRYPTO_INCLUDES: 
+  CRYPTO_LDFLAGS:  
+  CRYPTO_LIBS:     -lcrypto
+
+Botan: no
+
+Log4cplus:
+  LOG4CPLUS_VERSION:  1.1.3
+  LOG4CPLUS_INCLUDES: -I/usr/include
+  LOG4CPLUS_LIBS:     -L/usr/lib -L/usr/lib64 -llog4cplus
+
+Flex/bison:
+  FLEX:  flex
+  BISON: bison -y
+
+MySQL:
+  no
+
+PostgreSQL:
+  no
+
+Cassandra CQL:
+  no
+Google Test:
+  no
+Google Benchmark:
+  no
+
+FreeRADIUS client:
+  FREERADIUS_INCLUDE:    -I/usr/local/include
+  FREERADIUS_LIB:        -L/usr/local/lib -lfreeradius-client
+  FREERADIUS_DICTIONARY: /usr/local/etc/radiusclient/dictionary
+
+Developer:
+  Enable Debugging:       no
+  Google Tests:           no
+  Valgrind:               not found
+  C++ Code Coverage:      no
+  Logger checks:          no
+  Generate Documentation: no
+  Parser Generation:      no
+  Kea-shell:              no
+</screen>
+</para>
+
+<para>
+Please make sure that your compilation has the following:
+
+<itemizedlist>
+  <listitem>radius listed in tier 2 packages</listitem>
+  <listitem>FreeRadius client directories printed and pointing to the right
+  directories</listitem>
+  <listitem>Boost ersion is at least 1.65.1. The versions available
+  in CentOS 7 (1.48 and and 1.53) are too old.</listitem>
+</itemizedlist>
+
+</para>
+
+<para>
+  After that compile kea using make. If your system has more than one core, it is recommended to use -j N option.
+  <screen>
+    $ make -j5
+    $ sudo make install</screen>
+
+      </para>
+  </section>
+
+
+  <section id="hooks-radius-config">
+    <title>RADIUS Hook Configuration</title>
+
+    <para>
+      The RADIUS Hook is a library that has to be loaded by either DHCPv4 or
+      DHCPv6 Kea servers. What is different in this library is that it takes
+      many parameters to actually run. For example, this configuration could
+      be used:
+
+<screen>
+  "Dhcp4": {
+
+  // Your regular DHCPv4 configuration parameters here.
+  
+  "hooks-libraries": [
+  {
+      "library": "/usr/local/lib/hooks/libdhc_radio.so",
+      "parameters": {
+
+          // Specify where FreeRADIUS dictionary could be located
+          "dictionary: "/usr/local/etc/freeradius/dictionary",
+
+          // Specify which address to use to communicate with RADIUS servers
+          "bindaddr": "*",
+
+          // more RADIUS parameters here
+      }
+  } ]</screen>
+    </para>
+
+    <para>
+      The RADIUS hook library supports the following global configuration
+      flags, which correspond to FreeRADIUS client library options:
+
+      <itemizedlist>
+
+        <listitem><simpara><command>bindaddr</command> (default "*") specifies
+        the address to be used by the hook library in communication with RADIUS
+        servers. The "*" special value means to leave the kernel to choose
+        it.</simpara></listitem>
+
+      <listitem><simpara><command>canonical-mac-address</command> (default
+      false) specifies whether MAC addresses in attributes follows the canonical
+      Radius format (lowercase pairs of hexadecimal digits separated by
+      '-').</simpara></listitem>
+
+      <listitem><simpara><command>client-id-pop0</command> (default false) used
+      with flex-id removes the leading zero (or pair of zero in DHCPv6) type in
+      client-id (aka duid in DHCPv6). Implied by
+      client-id-printable.</simpara></listitem>
+
+      <listitem><simpara><command>client-id-printable</command> (default false)
+      checks if the client-id / duid content is printable and uses it as it
+      instead of in hexadecimal.  Implies client-id-pop0 and extract-duid as 0
+      and 255 are not printable.</simpara></listitem>
+
+      <listitem><simpara><command>deadtime</command> (default 0) is a mechanism
+      to try not responding servers after responding servers. Its value
+      specifies the number of seconds the fact a server did not answer is kept,
+      so 0 disables the mechanism.  As the asynchronous communication does not
+      use locks or atomics it is not recommended to use this feature with this
+      mode. </simpara></listitem>
+
+      <listitem><simpara><command>dictionary</command> (default set by configure
+      at build time) is the attribute and value dictionary. Note it is a
+      critical parameter. </simpara></listitem>
+
+      <listitem><simpara><command>extract-duid</command> (default true) extracts
+      from RFC 4361 compliant DHCPv4 client-id the embedded duid. Implied by
+      client-id-printable. </simpara></listitem>
+
+      <listitem><simpara><command>identifier-type4</command> (default client-id)
+      specifies the identifier type to build the User-Name attribute. It should
+      be the same than host identifier and when the flex-id hook librairy is
+      used the replace-client-id must be set to true and client-id will be used
+      with client-id-pop0. </simpara></listitem>
+
+      <listitem><simpara><command>identifier-type6</command> (default duid)
+      pecifies the identifier type to build the User-Name attribute. It should
+      be the same than host identifier and when the flex-id hook librairy is
+      used the replace-client-id must be set to true and duid will be used with
+      client-id-pop0. </simpara></listitem>
+      
+      <listitem><simpara><command>realm</command> (default "") is the default
+      realm. </simpara></listitem>
+
+      <listitem><simpara><command>retries</command> (default 3) is the number of
+      retries before trying the next server. Note it is not supported for
+      asynchronous communication. </simpara></listitem>
+
+      <listitem><simpara><command>session-history</command> (default "") is the
+      name of the file providing persistent storage for accounting session
+      history. </simpara></listitem>
+
+      <listitem><simpara><command>timeout</command> (default 10) is the number
+      of seconds a response is waited for. </simpara></listitem>
+      </itemizedlist>
+
+    </para>
+
+    <para>
+      Two services are supported:
+      <itemizedlist>
+        <listitem><simpara><command>access</command> - the authentication service </simpara></listitem>
+        <listitem><simpara><command>accounting</command> - the accounting service</simpara></listitem>
+      </itemizedlist>
+    </para>
+
+    <para>
+      Configuration of services is divided into two parts:
+      <itemizedlist>
+        <listitem>
+          <simpara>servers that define RADIUS servers the library is expected to
+          contact. Each server may have the following items specified:</simpara>
+          <itemizedlist>
+
+            <listitem><simpara><command>name</command> which specifies the IP
+            address of the server (it is allowed to use a name which will be
+            resolved but it is not recommended).</simpara></listitem>
+
+            <listitem><simpara><command>port</command> (default RADIUS
+            authentication or accounting service) which specifies the UDP port
+            of the server.</simpara></listitem>
+
+            <listitem><simpara><command>secret</command> which authenticates
+            messages.</simpara></listitem>
+
+          </itemizedlist>
+          <simpara>There may be up to 8 servers. Note when no server was
+          specified the service is disabled.</simpara>
+        </listitem>
+
+        <listitem>
+          <simpara>attributes which define attributes which are used by the
+          service with:</simpara>
+          <itemizedlist>
+            <listitem><simpara><command>name</command> of the
+            attribute. </simpara></listitem>
+            <listitem><simpara><command>type</command> of the attribute. Type or
+            name is required, and the attribute must be defined in the
+            dictionary.</simpara></listitem>
+            
+            <listitem><simpara><command>data</command> is one of the three ways
+            to specify the attribute content.  The data entry is parsed by the
+            FreeRADIUS library so values defined in the dictionary of the
+            attribute may be used.</simpara></listitem>
+
+            <listitem><simpara><command>raw</command> specifies the content in
+            hexadecimal. Note it does not work with integer content attributes
+            (date, integer and IPv4 address), a string content attribute
+            (string. IPv6 address and IPv6 prefix) is
+            required.</simpara></listitem>
+            
+            <listitem><simpara><command>expr</command> specifies an evaluation
+            expression which must return a not empty string when evaluated with
+            the DHCP query packet.  A priori this is restricted to the access
+            service. </simpara></listitem>
+          </itemizedlist>
+        </listitem>
+      </itemizedlist>
+        
+    </para>
+<para>
+
+</para>
+<para>TODO: Describe that RADIUS backend must be configured.</para>
+
+<para>TODO: Describe that host-cache library must also be loaded for the
+accounting to work.</para>
+
+<para>TODO: Add configuration file example here.</para>
+</section>
+    
+</section>
+

doc/guide/hooks.xml

@@ -21,6 +21,12 @@
       functions in them.  Those functions perform whatever custom
       processing is required.
       </para>
+      <para>
+        The hooks concept also allows keeping the core Kea code reasonably small
+        by moving features that some, but not all users find useful to external
+        libraries. People who don't need specific functionality simply don't
+        load the libraries.
+      </para>
       <para>
       Hooks libraries are attached to individual Kea processes, not to
       Kea as a whole.  This means (for example) that it is possible
@@ -42,6 +48,17 @@
       found in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://jenkins.isc.org/job/Fedora20_32_doxygen_doc/doxygen/">Kea
       Developer's Guide</link>.
       </para>
+
+      <para>
+        Note that some libraries are available under different licenses.
+      </para>
+      <para>
+        Note that some libraries may require additional dependencies and/or
+        compilation switches to be enabled, e.g. Radius library introduced in
+        Kea 1.4 requires FreeRadius-client library to be present. If
+        --with-free-radius option is not specified, the Radius library will not
+        be built.
+      </para>
     </section> <!-- end Introduction -->
     <section>
       <title>Configuring Hooks Libraries</title>
@@ -281,6 +298,33 @@
               Kea DHCP.
               </entry>
             </row>
+            <row>
+              <entry>Radius</entry>
+              <entry>Support customers</entry>
+              <entry>Kea 1.4.0</entry>
+              <entry>The RADIUS Hook library allows Kea to interact with the
+              RADIUS servers using access and accounting mechanisms. The access
+              mechanism may be used for access control, assigning specific IPv4
+              or IPv6 addresses reserved by RADIUS, dynamically assigning
+              addresses from designated pools chosen by RADIUS or rejecting
+              the client's messages altogether. The accounting mechanism allows
+              RADIUS server to keep track of device activity over time.
+              </entry>
+            </row>
+            <row>
+              <entry>Host Cache</entry>
+              <entry>Support customers</entry>
+              <entry>Kea 1.4.0</entry>
+              <entry>Some of the database backends, such as RADIUS, are
+              considered slow and may take a long time to respond. Since Kea in
+              general is synchronous, the backend performance directly affects
+              the DHCP performance. To minimize the impact and improve
+              performance, the Host Cache library provides a way to cache
+              responses from other hosts. This includes negative caching,
+              i.e. the ability to remember that there is no client information
+              in the database.
+              </entry>
+            </row>
           </tbody>
           </tgroup>
           </table>
@@ -295,6 +339,9 @@
         listed there, please send a note to the kea-users or kea-dev
         mailing lists and someone will update it.
       </para>
+      <para>
+        The libraries developed by ISC are described in detail in the following sections.
+      </para>
       <section>
         <title>user_chk: Checking User Access</title>
         <para>
@@ -2787,6 +2834,10 @@ both the command and the response.
       </para>
     </section> <!-- end of high-availability-library -->
 
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hooks-radius.xml"/>
+
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hooks-host-cache.xml"/>
+
   </section>