diff --git a/doc/sphinx/arm/ext-radius.rst b/doc/sphinx/arm/ext-radius.rst new file mode 100644 index 0000000000..d3a131b22e --- /dev/null +++ b/doc/sphinx/arm/ext-radius.rst @@ -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. diff --git a/doc/sphinx/arm/hooks-radius.rst b/doc/sphinx/arm/hooks-radius.rst index a2f630a67d..e863715a55 100644 --- a/doc/sphinx/arm/hooks-radius.rst +++ b/doc/sphinx/arm/hooks-radius.rst @@ -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 `_ can be found -`on KB `_ - -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. diff --git a/doc/sphinx/arm/integrations.rst b/doc/sphinx/arm/integrations.rst index 84365882b9..57f5734000 100644 --- a/doc/sphinx/arm/integrations.rst +++ b/doc/sphinx/arm/integrations.rst @@ -8,3 +8,4 @@ capabilities and how to configure them. .. include:: ext-netconf.rst .. include:: ext-gss-tsig.rst +.. include:: ext-radius.rst diff --git a/doc/sphinx/arm/rst_arm_sources.mk b/doc/sphinx/arm/rst_arm_sources.mk index 6a359e4c3b..6ed67efbca 100644 --- a/doc/sphinx/arm/rst_arm_sources.mk +++ b/doc/sphinx/arm/rst_arm_sources.mk @@ -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 diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py index 117d125cf3..ed5025217c 100644 --- a/doc/sphinx/conf.py +++ b/doc/sphinx/conf.py @@ -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',