--- /dev/null
+<!--
+ - 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>
+
projects / thirdparty / kea.git / commitdiff
