mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-22 01:49:48 +00:00
[#2442] move RADIUS documentation to integrations
This commit is contained in:
Andrei Pavel
parent
2450fe4ab9
commit
32569799db
360
doc/sphinx/arm/ext-radius.rst
Normal file
360
doc/sphinx/arm/ext-radius.rst
Normal 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.
|
||||
@ -4,633 +4,13 @@
|
||||
``libdhcp_radius.so``: RADIUS Server Support
|
||||
============================================
|
||||
|
||||
This 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 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.
|
||||
This hook library allows the Kea DHCP servers to use the RADIUS protocol to
|
||||
authorize DHCP clients for access to client classes or leases or to keep a
|
||||
journal of DHCP traffic through the accounting service. For details on RADIUS
|
||||
in Kea, please see :ref:`radius`.
|
||||
|
||||
.. note::
|
||||
|
||||
:ischooklib:`libdhcp_radius.so` is available only to ISC customers with
|
||||
a paid support contract. For more information on subscription options,
|
||||
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.
|
||||
|
||||
@ -8,3 +8,4 @@ capabilities and how to configure them.
|
||||
|
||||
.. include:: ext-netconf.rst
|
||||
.. include:: ext-gss-tsig.rst
|
||||
.. include:: ext-radius.rst
|
||||
|
||||
@ -13,6 +13,7 @@ rst_arm_sources += arm/dhcp4-srv.rst
|
||||
rst_arm_sources += arm/dhcp6-srv.rst
|
||||
rst_arm_sources += arm/ext-gss-tsig.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/hooks-bootp.rst
|
||||
rst_arm_sources += arm/hooks-cb-cmds.rst
|
||||
|
||||
@ -105,6 +105,7 @@ exclude_patterns = [
|
||||
'arm/hammer.rst',
|
||||
'arm/ext-netconf.rst',
|
||||
'arm/ext-gss-tsig.rst',
|
||||
'arm/ext-radius.rst',
|
||||
'grammar/grammar-ca-parser.rst',
|
||||
'grammar/grammar-d2-parser.rst',
|
||||
'grammar/grammar-dhcp4-parser.rst',
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user