-
- 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/.
+ - 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>
+ <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
+ DHCP and RADIUS integration is done on the DHCP relay-agent level
+ (DHCP clients send DHCP packets to DHCP relays; those relays contact
+ the RADIUS server and depending on the response either send the packet
+ to the DHCP server or drop it), it does require DHCP relay
hardware to support RADIUS communication. Also, even if the relay
- has necessary support it is often not flexible enough to send and
+ has the 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
+ looks more appealing: to extend the DHCP server to talk to RADIUS
directly. That is the goal this library intends to fulfill.
<note>
- <para>This library may only be loaded by <command>kea-dhcp4</command>
- or <command>kea-dhcp6</command> process.
+ <para>This library may only be loaded by the <command>kea-dhcp4</command>
+ or the <command>kea-dhcp6</command> process.
</para>
</note>
</para>
<para>
- The major feature of the library is the ability to use RADIUS
+ The major feature of the hook 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
+ sends an Access-Request to the RADIUS server and awaits
+ a response. The server then sends back either an Access-Accept
+ with specific client attributes, or an Access-Reject. There are two
+ cases supported here: first, the Access-Accept includes a
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.
+ means RADIUS can act as an 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
+ specific pools based on a RADIUS response. In this case, the RADIUS
+ server sends back an Access-Accept with Framed-Pool (IPv4) or
+ Framed-IPv6-Pool (IPv6). In both cases, Kea interprets those
+ attributes as client classes. With the 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,
+ linkend="classification-pools"/>), RADIUS can be used to force the client
+ to be assigned a dynamic address from a 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).
+ 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>
+ <title>Compilation and Installation of the 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 2: FreeRADIUS installation.
+ STEP 2: FreeRADIUS installation
</para>
<para>
- Kea RADIUS hook library uses FreeRadius client library to
+ The Kea RADIUS hook library uses the 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
+ 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
+ not offer asynchronous transmissions, which are 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 download and compile this version, please use
+ were addressed by ISC engineers, and the changes have been
+ reported to the FreeRADIUS client project. Acceptance of those
+ changes is outside of ISC responsibilities, so until those
+ are processed, it is strongly recommended to use the FreeRADIUS
+ client with ISC's patches. To download and compile this version, please use
the following steps:
<screen>
$ git clone https://github.com/fxdupont/freeradius-client.git
$ sudo make install
</screen>
- You may pass additional parameters to configure script, if you need
+ You may enter additional parameters to the 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.
+ it. You may install it in a different directory; if you choose to do
+ so, make sure you add that path to the configure script when compiling Kea.
</para>
<para>
</para>
<para>
- Kea requires reasonably recent Boost version. Unfortunately,
- the version available in CentOS 7 is too old. Therefore a
+ Kea requires a reasonably recent Boost version. Unfortunately,
+ the version available in CentOS 7 is too old, so 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
+ old version of the g++ compiler that does not handle the latest Boost
+ versions. Fortunately, Boost 1.65 meets both requirements; it is both
+ recent enough for Kea and able to be compiled using
the g++ 4.8 version in CentOS.
</para>
<para>
$ ./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
+ Note that the b2 script may optionally take extra parameters; one
+ of them specifies the destination path where the sources are to
be compiled.
</para>
<para>
- STEP 4: Compile and Install Kea
+ STEP 4: Compile and install Kea
</para>
<para>
- Obtain Kea sources either by downloading it from git repository or extract the tarball:
+ Obtain the Kea sources either by downloading them from the git repository or extracting the tarball:
<screen>
-# Use one of those commands to obtain Kea sources:
+# Use one of those commands to obtain the Kea sources:
# Choice 1: get from github
$ git clone https://github.com/isc-projects/kea
$ tar zxvf kea-&keaversion;.tar.gz
</screen>
-The next step is to extract premium Kea package that contains Radius repository
+The next step is to extract the premium Kea package that contains the RADIUS repository
into the Kea sources. After the tarball is extracted, the Kea sources should have
a premium/ subdirectory.
$ tar zxvf ../kea-premium-radius-&keaversion;.tar.gz
</screen>
-Once this is done, make sure the kea sources look similar to this:
+Once this is done, verify that the Kea sources look similar to this:
<screen>
$ ls -l
total 952
drwxr-xr-x 14 thomson staff 476 Apr 26 19:04 tools
</screen>
-The makefiles have to be regenerated using autoreconf.</para>
+The makefiles must be regenerated using autoreconf.</para>
-<para>The next step is to configure Kea. There are several essential steps necessary here.
-Running autoreconf -if 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>The next step is to configure Kea, and there are several essential steps necessary here.
+Running autoreconf -if is necessary to compile the premium package that contains
+RADIUS. Also, the --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 must be specified.</para>
<screen>
$ autoreconf -i
</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
+For example, assuming the FreeRADIUS client was installed in the default directory (/usr/local)
+and the Boost 1.65 sources were compiled in /home/thomson/devel/boost1_65_1, the configure path
should look as follows:</para>
<screen>
Please make sure that your compilation has the following:
<itemizedlist>
- <listitem>radius listed in Included Hooks</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
+ <listitem>RADIUS listed in Included Hooks;</listitem>
+ <listitem>FreeRADIUS client directories printed and pointing to the right
+ directories;</listitem>
+ <listitem>Boost version 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.
+ Once your configuration is complete, compile Kea using make. If your system has more than one core, it is recommended to use the -j N option.
<screen>
$ make -j5
$ sudo make install</screen>
<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
+ The RADIUS hook is a library that has to be loaded by either DHCPv4 or
+ DHCPv6 Kea servers. Unlike some other available hook libraries, this one
+ takes many parameters. For example, this configuration
could be used:
<screen>
</para>
<para>
- Radius is a complicated environment. As such, it's not really possible
+ 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
<para>
The RADIUS hook library supports the following global configuration
- flags, which corresponds to FreeRADIUS client library options:
+ 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>
+ servers. The "*" special value tells the kernel to choose
+ the address.</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
+ false) specifies whether MAC addresses in attributes follow 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
+ <listitem><simpara><command>client-id-pop0</command> (default false), used
+ with flex-id, removes the leading zero (or pair of zeroes 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
+ checks whether the client-id / duid content is printable and uses it as is
+ 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>
+ to try unresponsive servers after responsive servers. Its value
+ specifies the number of seconds after which a server is considered not to have answered,
+ 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>
+ at build time) is the attribute and value dictionary. Note that 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>
+ the embedded duid from an RFC 4361-compliant DHCPv4 client-id. 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
+ be the same as the host identifier, and when the flex-id hook library is
+ used the replace-client-id must be set to true; 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>
+ be the same as the host identifier, and when the flex-id hook library is
+ used the replace-client-id must be set to true; duid will be used with
+ client-id-pop0.</simpara></listitem>
<listitem><simpara><command>realm</command> (default "") is the default
- realm. </simpara></listitem>
+ 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>
+ 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>
+ 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>
+ retries before trying the next server. Note that 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>
+ history.</simpara></listitem>
<listitem><simpara><command>timeout</command> (default 10) is the number
- of seconds a response is waited for. </simpara></listitem>
+ of seconds during which a response is awaited.</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.
+ reception of RADIUS Access-Accept, the selected subnet is checked
+ against the client-class name or the reserved address; if it does
+ not match, another subnet is selected among matching subnets.
</para>
<para>
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>name</command>, which specifies the IP
+ address of the server (it is possible 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
+ 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
+ use 1645 (auth) and 1646 (acct). You may use the "port" parameter to
adjust as needed.</simpara></listitem>
- <listitem><simpara><command>secret</command> which authenticates
+ <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>
+ <simpara>There may be up to 8 servers. Note that when no server is
+ 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
+ be specified in 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
+ 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>
+ 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
+ <listitem><simpara><command>data</command> is the first 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
+ 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
+ <listitem><simpara><command>raw</command> is the second of three
+ ways to specify the attribute content; it specifies the content in
+ hexadecimal. Note that 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
+ 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>
</para>
<para>
For example, to specify a single access server available on localhost that
- uses "sekret" as a secret and tell Kea to send three additional attributes
- (Password, Connect-Info and Configuration-Token), the following snipped could
+ uses "secret" as a secret, and tell Kea to send three additional attributes
+ (Password, Connect-Info, and Configuration-Token), the following snippet could
be used:
<screen>
"parameters": {
// Additional access servers could be specified here
],
- // This define a list of additional attributes Kea will send to each
+ // This defines a list of additional attributes Kea will send to each
// access server in Access-Request.
"attributes": [
{
</screen>
</para>
-<para>For the RADIUS Hook library to operate properly in DHCPv4, it is necessary
+<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
+complex. In a typical deployment, the DHCP clients send their packets via
+DHCP relay which inserts certain Relay Agent Information options, such as
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
+Kea DHCP server to formulate the 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
+relays are not able to insert their RAI options and the 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
+incoming packets. Kea needs to keep the information received during the initial
+Discover/Offer exchanges and use it again later 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
+cache mechanism allows 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
+do not want RADIUS communication for messages other than
Discover and the first Request from each client.</para>
</section>
projects / thirdparty / kea.git / commitdiff
