mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-30 05:27:55 +00:00
Code Issues Releases Wiki Activity

[5538] RADIUS hook documentation added.

Browse Source
This commit is contained in:
Tomek Mrugalski 2018-04-26 20:11:22 +01:00
parent a5a992e09d
commit e74afe42c0
4 changed files with 549 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/guide/Makefile.am
View File

@ -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)

4
doc/guide/hooks-host-cache.xml Normal file
View File

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

493
doc/guide/hooks-radius.xml Normal file
View File

@ -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>

51
doc/guide/hooks.xml
View File

@ -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>