mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-29 04:57:52 +00:00
Code Issues Releases Wiki Activity

[#2442] move RADIUS documentation to integrations

Browse Source
This commit is contained in:
Andrei Pavel 2023-11-08 17:21:29 +02:00
parent 2450fe4ab9
commit 32569799db
No known key found for this signature in database
GPG Key ID: D4E804481939CB21
5 changed files with 367 additions and 624 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

360
doc/sphinx/arm/ext-radius.rst Normal file
View File

@ -0,0 +1,360 @@
.. _radius:
RADIUS
======
.. _radius-overview:
Overview
--------
This hook library allows Kea to interact with two types of RADIUS
services: access and accounting. Although the most common 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 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 the
DHCP server to talk to RADIUS directly. That is the goal of this library.
.. note::
This library can only be loaded by the :iscman:`kea-dhcp4` or the
:iscman:`kea-dhcp6` process.
The major feature of this hook library is the ability to use RADIUS
authorization. When a DHCP packet is received, the Kea server sends an
Access-Request to the RADIUS server and waits for 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 attribute (for DHCPv4) or a
Framed-IPv6-Address attribute (for DHCPv6), which are interpreted by Kea as
instructions to assign the specified IPv4 or IPv6 address. This
effectively means RADIUS can act as an address-reservation database.
The second supported case is the ability to assign clients to specific
pools based on a RADIUS response. In this case, the RADIUS server sends
back an Access-Accept with a Framed-Pool attribute.
For both DHCPv4 and DHCPv6, Kea interprets this attribute as a client class.
With the addition of the ability to limit access to pools to
specific classes (see :ref:`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 gets if there are DHCP options
specified for a particular class.
.. _hooks-radius-config:
RADIUS Hook Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~
The RADIUS hook is a library that must be loaded by either :iscman:`kea-dhcp4` or
:iscman:`kea-dhcp6` servers. Unlike some other available hook libraries, this one
takes many parameters. For example, this configuration could be used:
::
"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/kea/hooks/libdhcp_host_cache.so"
},
{
"library": "/usr/local/lib/kea/hooks/libdhcp_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
}
} ],
...
}
RADIUS is a complicated environment. As such, it is not feasible
to provide a default configuration that works for everyone.
However, we do have an example that showcases some of the more common
features. Please see ``doc/examples/kea4/hooks-radius.json`` in the Kea
sources.
The RADIUS hook library supports the following global configuration
flags, which correspond to FreeRADIUS client library options:
- ``bindaddr`` (default ``"*"``) - specifies the address to be used by the
hook library in communication with RADIUS servers. The ``"*"`` special
value tells the kernel to choose the address.
- ``canonical-mac-address`` (default ``false``) - specifies whether MAC
addresses in attributes follow the canonical RADIUS format (lowercase
pairs of hexadecimal digits separated by ``-``).
- ``client-id-pop0`` (default ``false``) - is used with
:ischooklib:`libdhcp_flex_id.so`. Removes the leading zero (or pair of zeroes
in DHCPv6) type in the client id (duid in DHCPv6). See
``client-id-printable`` for any value implications when used in conjunction
with it.
- ``client-id-printable`` (default ``false``) - 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.
- ``deadtime`` (default ``0``) - is a mechanism that helps in sorting the
servers such that the servers that have proved responsive so far are inquired
first, and the servers that have proved unresponsive are left at the end. The
deadtime value specifies the number of seconds after which a server is
considered unresponsive. 0 disables the mechanism.
- ``dictionary`` (default set by configure at build time) - is the
attribute and value dictionary. Note that it is a critical parameter.
Dictionary examples can be found in the FreeRADIUS repository under the etc/
directory.
- ``extract-duid`` (default ``true``) - extracts the embedded duid from an
RFC-4361-compliant DHCPv4 client id. See ``client-id-printable`` for any
value implications when used in conjunction with it.
- ``identifier-type4`` (default ``"client-id"``) - specifies the identifier
type to build the User-Name attribute. It should be the same as the
host identifier. When :ischooklib:`libdhcp_flex_id.so` is used, then
``replace-client-id`` must be set to ``true`` and ``client-id`` must be used
with ``client-id-pop0`` enabled.
- ``identifier-type6`` (default ``"duid"``) - specifies the identifier type to
build the User-Name attribute. It should be the same as the host
identifier. When :ischooklib:`libdhcp_flex_id.so` is used, then
``replace-client-id`` must be set to ``true`` and ``duid`` must be used with
``client-id-pop0`` enabled.
- ``reselect-subnet-address`` (default ``false``) - enables subnet reselection
according to the value of the Framed-IP-Address or, respectively,
the Framed-IPv6-Address attribute from the RADIUS access response. With this
flag enabled, if the IP address is not in range of the currently selected
subnet, but is in range of another subnet that is selectable with regards to
other criteria, the latter subnet is selected and used further in the lease
assignment process.
- ``reselect-subnet-pool`` (default ``false``) - enables subnet reselection
according to the value of the Framed-Pool attribute from the RADIUS access
response. With this flag enabled, if the currently selected subnet is not
guarded by the client class represented by the attribute value, but there is
another selectable subnet that is guarded by it, the latter subnet is
selected and used further in the lease assignment process.
This reselection is attempted first, and if successful, it prevents the
function of reselect-subnet-address from coming into effect.
- ``retries`` (default ``3``) - is the number of retries before trying the
next server. Not supported for asynchronous communication.
- ``session-history`` (default ``""``) - is the name of the file providing
persistent storage for accounting session history.
- ``timeout`` (default ``10``) - is the number of seconds during which a
response is awaited.
Two services are supported:
- access - the authorization service.
- accounting - the accounting service.
Configuration of services is divided into two parts:
- Servers that define RADIUS services that the library is expected to
contact. Each server may have the following items specified:
- ``name`` - specifies the IP address of the server. A domain name may be
used and will be resolved at runtime.
- ``port`` - specifies the UDP port of the server. By default, it is 1812
for access and 1813 for accounting.
- ``secret`` - authenticates messages.
There may be up to eight servers. Note that when no server is
specified, the service is disabled.
- Attributes which define additional information that the Kea server
sends to a RADIUS server. The parameter must be identified either
by a name or type. Its value can 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
that is evaluated for each incoming packet independently).
- ``name`` - the name of the attribute.
- ``type`` - the type of the attribute. Either the type or the name must be
provided, and the attribute must be defined in the dictionary.
- ``data`` - 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 attribute may be used.
- ``raw`` - 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.
- ``expr`` - 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.
For example, to specify a single access server available on localhost
that uses "xyz123" as a secret, and tell Kea to send three additional
attributes (Password, Connect-Info, and Configuration-Token), the
following snippet could be used:
::
{
"parameters": {
// Other RADIUS parameters here
"access": {
// This starts the list of access servers
"servers": [
{
// These are parameters for the first (and only) access server
"name": "127.0.0.1",
"port": 1812,
"secret": "xyz123"
}
// Additional access servers could be specified here
],
// This defines 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 is 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": "hexstring(pkt4.mac,':')"
}
] // End of attributes
}, // End of access
// Accounting parameters.
"accounting": {
// This starts the list of accounting servers
"servers": [
{
// These are parameters for the first (and only) accounting server
"name": "127.0.0.1",
"port": 1813,
"secret": "sekret"
}
// Additional accounting servers could be specified here
]
}
}
}
Customization is sometimes required for certain attributes by devices belonging
to various vendors. This is a great way to leverage the expression evaluation
mechanism. For example, MAC addresses which might be used as a convenience
value for the User-Name attribute are most likely to appear in colon-hexadecimal
notation (``de:ad:be:ef:ca:fe``), but they might need to be expressed in
hyphen-hexadecimal notation (``de-ad-be-ef-ca-fe``). Here's how to specify that:
.. code-block:: json
{
"parameters": {
"access": {
"attributes": [
{
"name": "User-Name",
"expr": "hexstring(pkt4.mac, '-')"
}
]
}
}
}
And here's how to specify period-separated hexadecimal notation (``dead.beef.cafe``), preferred by Cisco devices:
.. code-block:: json
{
"parameters": {
"access": {
"attributes": [
{
"name": "User-Name",
"expr": "concat(concat(concat(substring(hexstring(pkt4.mac, ''), 0, 4), '.'), concat(substring(hexstring(pkt4.mac, ''), 4, 4), '.'), concat(substring(hexstring(pkt4.mac, ''), 8, 4), '.'))"
}
]
}
}
}
For :ischooklib:`libdhcp_radius.so` to operate properly in DHCPv4,
:ischooklib:`libdhcp_host_cache.so` must also be loaded. 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 as ``circuit-id`` or ``remote-id``. The values of
those options are then used by the 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 the DHCP server cannot 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 the initial Discover/Offer exchanges and use it again
later when sending accounting messages.
This mechanism is implemented based on user context in host
reservations. (See :ref:`user-context` and :ref:`user-context-hooks` for
details.) The host-cache mechanism allows the information retrieved by
RADIUS to be stored and later used for sending access and accounting
queries to the RADIUS server. In other words, the host-cache mechanism
is mandatory, unless administrators do not want RADIUS communication for messages
other than Discover and the first Request from each client.
.. note::
Currently the RADIUS hook library is incompatible with the
``early-global-reservations-lookup`` global parameter i.e.
setting the parameter to ``true`` raises an error when the
hook library is loaded.
.. note::
Currently the RADIUS hook library is incompatible with the
multi-subnet shared networks that have host reservations other
than global. Loading the RADIUS hook library in a Kea DHCP server
that has this configuration raises an error.

628
doc/sphinx/arm/hooks-radius.rst
View File

@ -4,633 +4,13 @@
``libdhcp_radius.so``: RADIUS Server Support ``libdhcp_radius.so``: RADIUS Server Support
============================================ ============================================
This hook library allows Kea to interact with two types of RADIUS This hook library allows the Kea DHCP servers to use the RADIUS protocol to
servers: access and accounting. Although the most common DHCP and RADIUS authorize DHCP clients for access to client classes or leases or to keep a
integration is done on the DHCP relay-agent level (DHCP clients send journal of DHCP traffic through the accounting service. For details on RADIUS
DHCP packets to DHCP relays; those relays contact the RADIUS server and in Kea, please see :ref:`radius`.
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 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 the
DHCP server to talk to RADIUS directly. That is the goal of this library.
.. note:: .. note::
:ischooklib:`libdhcp_radius.so` is available only to ISC customers with :ischooklib:`libdhcp_radius.so` is available only to ISC customers with
a paid support contract. For more information on subscription options, a paid support contract. For more information on subscription options,
please complete the form at https://www.isc.org/contact. please complete the form at https://www.isc.org/contact.
.. note::
This library can only be loaded by the :iscman:`kea-dhcp4` or the
:iscman:`kea-dhcp6` process.
The major feature of this hook library is the ability to use RADIUS
authorization. When a DHCP packet is received, the Kea server sends an
Access-Request to the RADIUS server and waits for 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 attribute (for DHCPv4) or a
Framed-IPv6-Address attribute (for DHCPv6), which are interpreted by Kea as
instructions to assign the specified IPv4 or IPv6 address. This
effectively means RADIUS can act as an address-reservation database.
The second supported case is the ability to assign clients to specific
pools based on a RADIUS response. In this case, the RADIUS server sends
back an Access-Accept with a Framed-Pool attribute.
For both DHCPv4 and DHCPv6, Kea interprets this attribute as a client class.
With the addition of the ability to limit access to pools to
specific classes (see :ref:`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 gets if there are DHCP options
specified for a particular class.
.. _hooks-radius-pkg-install:
Installation from packages
~~~~~~~~~~~~~~~~~~~~~~~~~~
ISC offers a FreeRADIUS client library using packages (rpm, deb) that contain
the necessary code for the radius hook. Instructions how to setup Kea repository
hosted by `Cloudsmith <https://cloudsmith.io/~isc/repos/>`_ can be found
`on KB <https://kb.isc.org/docs/isc-kea-packages>`_
The packages provided by ISC are based on the official freeradius packages
and always have a version that includes ``1.1.7-isc``. Ones that contains compiled
libraries need to run Kea are e.g. ``libfreeradius-client_1.1.7-isc20200318122047_amd64.deb``,
and those which contains development (``-dev`` in deb and ``-devel`` in rpm)
header files e.g. ``libfreeradius-client-dev_1.1.7-isc20200318122047_amd64.deb``.
When listed (deb):
.. code-block:: console
$ dpkg -l | grep libfreeradius
ii libfreeradius-client 1.1.7-isc20200318122047 amd64 Enhanced RADIUS client library
ii libfreeradius-client-dev 1.1.7-isc20200318122047 amd64 Enhanced RADIUS client library development files
When listed (rpm):
.. code-block:: console
$ dnf list installed | grep freeradius
freeradius-client.x86_64 1.1.7-isc20200318134606.el8 @isc-kea-2-2-prv
freeradius-client-devel.x86_64 1.1.7-isc20200318134606.el8 @isc-kea-2-2-prv
If official freeradius packages will be installed Kea will return error
on startup, typically displaying:
.. code-block:: console
HOOKS_OPEN_ERROR failed to open hook library /usr/lib64/kea/hooks/libdhcp_radius.so: /usr/lib64/kea/hooks/libdhcp_radius.so: undefined symbol: rc_acct_async
.. _hooks-radius-install:
Compilation and Installation of the RADIUS Hook
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following section describes how to compile and install the software
on Ubuntu 22.04. Other systems may differ slightly.
.. note::
ISC provides Kea software and hooks in convenient-to-use native DEB, and RPM
packages. This includes the RADIUS hook and the required patched version of
the FreeRADIUS client library. The software compilation for RADIUS is
complicated; unless there are specific reasons to compile it, administrators
should seriously consider using native packages.
STEP 1: Install dependencies
Several tools are needed to build the dependencies and Kea itself. The following
commands should install them:
.. code-block:: console
$ apt-get install tar git gcc g++ make autoconf automake libtool libssl-dev liblog4cplus-dev libboost-system-dev
STEP 2: Install FreeRADIUS
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 https://freeradius.org/sub_projects/
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 are essential for effective
accounting implementation. Both of these issues were addressed by ISC
engineers, and the changes have been reported to the FreeRADIUS client
project. Acceptance of those changes is outside of ISC's control, 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:
.. code-block:: console
$ git clone https://github.com/fxdupont/freeradius-client.git
$ cd freeradius-client/
$ git checkout iscdev
$ ./configure
$ make
$ sudo make install
Additional parameters may be passed to the configure script, if needed.
The FreeRADIUS client will be installed in /usr/local, which is the default path
where Kea will look for it. It can be installed in a different directory; if so,
make sure to add that path to the configure script when compiling Kea.
STEP 3: Compile and install Kea
Obtain the Kea sources either by downloading them from the git
repository or extracting the tarball. Use one of these commands
to obtain the Kea sources.
Choice 1: Retrieve from GitHub
.. code-block:: console
$ git clone https://github.com/isc-projects/kea.git
Choice 2: Retrieve a tarball and extract it
.. parsed-literal::
$ tar -zxvf kea-|release|.tar.gz
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.
.. parsed-literal::
$ cd kea
$ tar -zxvf ../kea-premium-radius-|release|.tar.gz
Once this is done, verify that the Kea sources look similar to this:
.. code-block:: console
$ 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
-rw-r--r-- 1 thomson staff 62323 Apr 25 17:38 configure.ac
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 premium
drwxr-xr-x 10 thomson staff 340 Apr 26 19:04 src
drwxr-xr-x 14 thomson staff 476 Apr 26 19:04 tools
The makefiles must be regenerated using ``autoreconf``.
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.
.. code-block:: console
$ autoreconf -i
$ ./configure --with-freeradius=/path/to/freeradius
After some checks, the configure script should print a report similar to
the following:
.. parsed-literal::
Kea source configure results:
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Package:
Name: kea
Version: 2.4.0
Extended version: 2.4.0 (tarball)
Version type: stable
OS Family: Linux
Prefix: /usr/local
Hooks directory: /usr/local/lib/kea/hooks
Premium hooks: yes
Included Hooks: ddns_tuning forensic_log flex_id host_cmds limits subnet_cmds radius host_cache class_cmds cb_cmds lease_query gss_tsig rbac
Configure arguments:
'--with-freeradius'
C++ Compiler:
CXX: g++
CXX_VERSION: g++ (Ubuntu 12.3.0-1ubuntu1~22.04) 12.3.0
CXX_STANDARD: 201703
DEFS: -DHAVE_CONFIG_H
CPPFLAGS: -DOS_LINUX -I$(top_srcdir) -I$(top_builddir)
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.74
BOOST_INCLUDES:
BOOST_LIBS: -lboost_system
OpenSSL:
CRYPTO_VERSION: OpenSSL 3.0.2 15 Mar 2022
CRYPTO_CFLAGS:
CRYPTO_INCLUDES:
CRYPTO_LDFLAGS:
CRYPTO_LIBS: -lssl -lcrypto
TLS support: yes
Botan: no
Log4cplus:
LOG4CPLUS_VERSION: 2.0.5
LOG4CPLUS_INCLUDES: -I/usr/include
LOG4CPLUS_LIBS: -L/usr/lib -L/usr/lib64 -llog4cplus
Flex/bison:
FLEX: flex
BISON: /usr/bin/bison
MySQL:
no
PostgreSQL:
no
NETCONF:
no
libyang:
no
libyang-cpp:
no
sysrepo:
no
sysrepo-cpp:
no
Google Test:
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: no
C++ Code Coverage: no
Logger checks: no
Install existing manuals: no
Generate Documentation: no
Generate Parser: no
Generate Messages Files: no
Perfdhcp: no
Kea-shell: no
Enable fuzzing: no
Please make sure that the compilation includes the following:
- RADIUS listed in Included Hooks;
- FreeRADIUS client directories printed and pointing to the right
directories;
- Boost version at least 1.65.1.
Once the configuration is complete, compile Kea using ``make``. If the
system has more than one core, using the ``-jN``
option is recommended to speed up the build.
.. code-block:: console
$ make -j5
$ sudo make install
.. _hooks-radius-config:
RADIUS Hook Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~
The RADIUS hook is a library that must be loaded by either :iscman:`kea-dhcp4` or
:iscman:`kea-dhcp6` servers. Unlike some other available hook libraries, this one
takes many parameters. For example, this configuration could be used:
::
"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/kea/hooks/libdhcp_host_cache.so"
},
{
"library": "/usr/local/lib/kea/hooks/libdhcp_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
}
} ],
...
}
RADIUS is a complicated environment. As such, it is not feasible
to provide a default configuration that works for everyone.
However, we do have an example that showcases some of the more common
features. Please see ``doc/examples/kea4/hooks-radius.json`` in the Kea
sources.
The RADIUS hook library supports the following global configuration
flags, which correspond to FreeRADIUS client library options:
- ``bindaddr`` (default ``"*"``) - specifies the address to be used by the
hook library in communication with RADIUS servers. The ``"*"`` special
value tells the kernel to choose the address.
- ``canonical-mac-address`` (default ``false``) - specifies whether MAC
addresses in attributes follow the canonical RADIUS format (lowercase
pairs of hexadecimal digits separated by ``-``).
- ``client-id-pop0`` (default ``false``) - is used with
:ischooklib:`libdhcp_flex_id.so`. Removes the leading zero (or pair of zeroes
in DHCPv6) type in the client id (duid in DHCPv6). See
``client-id-printable`` for any value implications when used in conjunction
with it.
- ``client-id-printable`` (default ``false``) - 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.
- ``deadtime`` (default ``0``) - is a mechanism that helps in sorting the
servers such that the servers that have proved responsive so far are inquired
first, and the servers that have proved unresponsive are left at the end. The
deadtime value specifies the number of seconds after which a server is
considered unresponsive. 0 disables the mechanism.
- ``dictionary`` (default set by configure at build time) - is the
attribute and value dictionary. Note that it is a critical parameter.
Dictionary examples can be found in the FreeRADIUS repository under the etc/
directory.
- ``extract-duid`` (default ``true``) - extracts the embedded duid from an
RFC-4361-compliant DHCPv4 client id. See ``client-id-printable`` for any
value implications when used in conjunction with it.
- ``identifier-type4`` (default ``"client-id"``) - specifies the identifier
type to build the User-Name attribute. It should be the same as the
host identifier. When :ischooklib:`libdhcp_flex_id.so` is used, then
``replace-client-id`` must be set to ``true`` and ``client-id`` must be used
with ``client-id-pop0`` enabled.
- ``identifier-type6`` (default ``"duid"``) - specifies the identifier type to
build the User-Name attribute. It should be the same as the host
identifier. When :ischooklib:`libdhcp_flex_id.so` is used, then
``replace-client-id`` must be set to ``true`` and ``duid`` must be used with
``client-id-pop0`` enabled.
- ``reselect-subnet-address`` (default ``false``) - enables subnet reselection
according to the value of the Framed-IP-Address or, respectively,
the Framed-IPv6-Address attribute from the RADIUS access response. With this
flag enabled, if the IP address is not in range of the currently selected
subnet, but is in range of another subnet that is selectable with regards to
other criteria, the latter subnet is selected and used further in the lease
assignment process.
- ``reselect-subnet-pool`` (default ``false``) - enables subnet reselection
according to the value of the Framed-Pool attribute from the RADIUS access
response. With this flag enabled, if the currently selected subnet is not
guarded by the client class represented by the attribute value, but there is
another selectable subnet that is guarded by it, the latter subnet is
selected and used further in the lease assignment process.
This reselection is attempted first, and if successful, it prevents the
function of reselect-subnet-address from coming into effect.
- ``retries`` (default ``3``) - is the number of retries before trying the
next server. Not supported for asynchronous communication.
- ``session-history`` (default ``""``) - is the name of the file providing
persistent storage for accounting session history.
- ``timeout`` (default ``10``) - is the number of seconds during which a
response is awaited.
Two services are supported:
- access - the authorization service.
- accounting - the accounting service.
Configuration of services is divided into two parts:
- Servers that define RADIUS services that the library is expected to
contact. Each server may have the following items specified:
- ``name`` - specifies the IP address of the server. A domain name may be
used and will be resolved at runtime.
- ``port`` - specifies the UDP port of the server. By default, it is 1812
for access and 1813 for accounting.
- ``secret`` - authenticates messages.
There may be up to eight servers. Note that when no server is
specified, the service is disabled.
- Attributes which define additional information that the Kea server
sends to a RADIUS server. The parameter must be identified either
by a name or type. Its value can 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
that is evaluated for each incoming packet independently).
- ``name`` - the name of the attribute.
- ``type`` - the type of the attribute. Either the type or the name must be
provided, and the attribute must be defined in the dictionary.
- ``data`` - 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 attribute may be used.
- ``raw`` - 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.
- ``expr`` - 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.
For example, to specify a single access server available on localhost
that uses "xyz123" as a secret, and tell Kea to send three additional
attributes (Password, Connect-Info, and Configuration-Token), the
following snippet could be used:
::
{
"parameters": {
// Other RADIUS parameters here
"access": {
// This starts the list of access servers
"servers": [
{
// These are parameters for the first (and only) access server
"name": "127.0.0.1",
"port": 1812,
"secret": "xyz123"
}
// Additional access servers could be specified here
],
// This defines 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 is 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": "hexstring(pkt4.mac,':')"
}
] // End of attributes
}, // End of access
// Accounting parameters.
"accounting": {
// This starts the list of accounting servers
"servers": [
{
// These are parameters for the first (and only) accounting server
"name": "127.0.0.1",
"port": 1813,
"secret": "sekret"
}
// Additional accounting servers could be specified here
]
}
}
}
Customization is sometimes required for certain attributes by devices belonging
to various vendors. This is a great way to leverage the expression evaluation
mechanism. For example, MAC addresses which might be used as a convenience
value for the User-Name attribute are most likely to appear in colon-hexadecimal
notation (``de:ad:be:ef:ca:fe``), but they might need to be expressed in
hyphen-hexadecimal notation (``de-ad-be-ef-ca-fe``). Here's how to specify that:
.. code-block:: json
{
"parameters": {
"access": {
"attributes": [
{
"name": "User-Name",
"expr": "hexstring(pkt4.mac, '-')"
}
]
}
}
}
And here's how to specify period-separated hexadecimal notation (``dead.beef.cafe``), preferred by Cisco devices:
.. code-block:: json
{
"parameters": {
"access": {
"attributes": [
{
"name": "User-Name",
"expr": "concat(concat(concat(substring(hexstring(pkt4.mac, ''), 0, 4), '.'), concat(substring(hexstring(pkt4.mac, ''), 4, 4), '.'), concat(substring(hexstring(pkt4.mac, ''), 8, 4), '.'))"
}
]
}
}
}
For :ischooklib:`libdhcp_radius.so` to operate properly in DHCPv4,
:ischooklib:`libdhcp_host_cache.so` must also be loaded. 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 as ``circuit-id`` or ``remote-id``. The values of
those options are then used by the 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 the DHCP server cannot 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 the initial Discover/Offer exchanges and use it again
later when sending accounting messages.
This mechanism is implemented based on user context in host
reservations. (See :ref:`user-context` and :ref:`user-context-hooks` for
details.) The host-cache mechanism allows the information retrieved by
RADIUS to be stored and later used for sending access and accounting
queries to the RADIUS server. In other words, the host-cache mechanism
is mandatory, unless administrators do not want RADIUS communication for messages
other than Discover and the first Request from each client.
.. note::
Currently the RADIUS hook library is incompatible with the
``early-global-reservations-lookup`` global parameter i.e.
setting the parameter to ``true`` raises an error when the
hook library is loaded.
.. note::
Currently the RADIUS hook library is incompatible with the
multi-subnet shared networks that have host reservations other
than global. Loading the RADIUS hook library in a Kea DHCP server
that has this configuration raises an error.

1
doc/sphinx/arm/integrations.rst
View File

@ -8,3 +8,4 @@ capabilities and how to configure them.
.. include:: ext-netconf.rst .. include:: ext-netconf.rst
.. include:: ext-gss-tsig.rst .. include:: ext-gss-tsig.rst
.. include:: ext-radius.rst

1
doc/sphinx/arm/rst_arm_sources.mk
View File

@ -13,6 +13,7 @@ rst_arm_sources += arm/dhcp4-srv.rst
rst_arm_sources += arm/dhcp6-srv.rst rst_arm_sources += arm/dhcp6-srv.rst
rst_arm_sources += arm/ext-gss-tsig.rst rst_arm_sources += arm/ext-gss-tsig.rst
rst_arm_sources += arm/ext-netconf.rst rst_arm_sources += arm/ext-netconf.rst
rst_arm_sources += arm/ext-radius.rst
rst_arm_sources += arm/hammer.rst rst_arm_sources += arm/hammer.rst
rst_arm_sources += arm/hooks-bootp.rst rst_arm_sources += arm/hooks-bootp.rst
rst_arm_sources += arm/hooks-cb-cmds.rst rst_arm_sources += arm/hooks-cb-cmds.rst

1
doc/sphinx/conf.py
View File

@ -105,6 +105,7 @@ exclude_patterns = [
'arm/hammer.rst', 'arm/hammer.rst',
'arm/ext-netconf.rst', 'arm/ext-netconf.rst',
'arm/ext-gss-tsig.rst', 'arm/ext-gss-tsig.rst',
'arm/ext-radius.rst',
'grammar/grammar-ca-parser.rst', 'grammar/grammar-ca-parser.rst',
'grammar/grammar-d2-parser.rst', 'grammar/grammar-d2-parser.rst',
'grammar/grammar-dhcp4-parser.rst', 'grammar/grammar-dhcp4-parser.rst',