path: root/doc/guide/hooks-radius.xml

<!--
 - 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
    authorization. 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 engineers observed a segmentation
      fault during testing. 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
$ sudo ./b2 install
</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 version 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. Compared to other available hook libraries, this one
      takes many parameters to actually run. For example, this configuration
      could be used:

<screen>
  "Dhcp4": {

  // Your regular DHCPv4 configuration parameters here.

  "hooks-libraries": [
  {
      // Note that RADIUS requires host-cache for proper operation,
      // so that library is loaded as well.
      "library": "/usr/local/lib/hooks/libdhcp_host_cache.so"
  },
  {
      "library": "/usr/local/lib/hooks/libdhc_radius.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>
      Radius is a complicated environment. As such, it's not really possible
      to provide a default configuration that would work out of the box.
      However, we do have one example that showcases some of the more
      common features. Please see doc/examples/kea4/hooks-radius.json in your
      Kea sources.
    </para>

    <para>
      The RADIUS hook library supports the following global configuration
      flags, which corresponds 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 library 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)
      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 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>reselect-subnet-address</command> (default
      false) uses the Kea reserved address / RADIUS Framed-IP-Address or
      Framed-IPv6-Address to reselect subnets where the address is not in
      the subnet range. </simpara></listitem>

      <listitem><simpara><command>reselect-subnet-pool</command> (default
      false) uses the Kea client-class / RADIUS Frame-Pool to reselect
      subnets where no available pool can be found. </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> When <command>reselect-subnet-pool</command> or
    <command>reselect-subnet-address</command> is set to true at the
    reception of RADIUS Access-Accept the selected subnet is checked
    against the client-class name or the reserved address and if it does
    not matched another subnet is selected among matching subnets.
    </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. Note that the FreeRADIUS client library by default
            uses ports 1812 (auth) and 1813 (acct). Some server implementations
            use 1645 (auth) ns 1646 (acct). You may use the "port" parameter to
            adjust as needed.</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 additional attributes that
          the Kea server will send to a RADIUS server. The parameter
          must be identified either by a name or type. Its value can
          be specified using one of three possible ways: data (which
          defines a plain text value), raw (which defines the value in
          hex) or expr (which defines an expression, which will be
          evaluated for each incoming packet independently).
          </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 the first out of 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> is the second out of three
            way to specify the attribute content. It 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> is the last way to
            specify the attribute content. It specifies an evaluation expression
            which must return a not empty string when evaluated with the DHCP
            query packet.  Currently this is restricted to the access
            service. </simpara></listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>
    </para>
<para>
  For example, to specify a single access server available on localhost that
  uses "secret" as a secret and tell Kea to send three additional attributes
  (Password, Connect-Info and Configuration-Token), the following snipped could
  be used:
  <screen>
"parameters": {

    // Other RADIUS parameters here

    "access": {

        // This starts the list of access servers
        "servers": [
        {
            // These are parameters for the first (and only) access server
            "server": "127.0.0.1",
            "port": 1812,
            "secret": "secret"
        }
        // Additional access servers could be specified here
        ],

        // This define a list of additional attributes Kea will send to each
        // access server in Access-Request.
        "attributes": [
        {
            // This attribute is identified by name (must be present in the
            // dictionary) and has static value (i.e. the same value will be
            // sent to every server for every packet)
            "name": "Password",
            "data": "mysecretpassword"
        },
        {
            // It's also possible to specify an attribute using its type,
            // rather than a name. 77 is Connect-Info. The value is specified
            // using hex. Again, this is a static value. It will be sent the
            // same for every packet and to every server.
            "type": 77,
            "raw": "65666a6a71"
        },
        {
            // This example shows how an expression can be used to send dynamic
            // value. The expression (see Section 13) may take any value from
            // the incoming packet or even its metadata (e.g. the interface
            // it was received over from)
            "name": "Configuration-Token",
            "expr": "pkt.iface"
        }
        ] // End of attributes
    } // End of access

    // accounting could be specified here.

    }
</screen>
</para>

<para>For the RADIUS Hook library to operate properly in DHCPv4, it is necessary
to also load the Host Cache hook library. The reason for this is somewhat
complex. In a typical deployment the DHCP clients send their packets via
DHCP relay which inserts certain Relay Agent Information options, such are
circuit-id or remote-id. The values of those options are then used by the
Kea DHCP server to formulate necessary attributes in the Access-Request message
sent to the RADIUS server. However, once the DHCP client gets its address, it
then renews by sending packets directly to the DHCP server. As a result, the
relays are not able to insert their RAI options and DHCP server can't send the
Access-Request queries to the RADIUS server by using just the information from
incoming packets. Kea needs to keep the information received during initial
Discover/Offer exchanges and later use it when sending accounting
messages.</para>

<para>This mechanism is implemented based on user context in host reservations.
(See <xref linkend="user-context"/> for details about user context). The host
cache mechanism allows to retain the information retrieved by RADIUS to be
stored and later used for sending accounting and access queries to the RADIUS
server. In other words, the host-cache mechanism is mandatory, unless you
don't want the RADIUS communication for messages other than
Discover and the first Request from each client.</para>

</section>

</section>