From: Suzanne Goldlust Date: Mon, 31 Dec 2018 20:13:05 +0000 (-0500) Subject: Update hooks-radius.xml X-Git-Tag: 481-remote-subnet4-set-inconsistent-work-when-id-subnet-is-duplicated_base~55 X-Git-Url: http://git.ipfire.org/gitweb/gitweb.cgi?a=commitdiff_plain;h=1ba5a7caeb952dd4b50ea5e0e91ec4986601c878;p=thirdparty%2Fkea.git Update hooks-radius.xml --- diff --git a/doc/guide/hooks-radius.xml b/doc/guide/hooks-radius.xml index eef6fb7ecb..bb1819a6ac 100644 --- a/doc/guide/hooks-radius.xml +++ b/doc/guide/hooks-radius.xml @@ -3,7 +3,7 @@ - - This Source Code Form is subject to the terms of the Mozilla Public - License, v. 2.0. If a copy of the MPL was not distributed with this - - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - file, you can obtain one at http://mozilla.org/MPL/2.0/. - - This license applies to the documentation itself, not the software. --> @@ -15,54 +15,54 @@ ]>
- radius: RADIUS server support + radius: RADIUS Server Support The RADIUS hook library allows Kea to interact with two types of RADIUS servers: access and accounting. Although the most common - DHCP and RADIUS integration is done on DHCP relay agent level - (DHCP clients send DHCP packets to DHCP relays; relays contact - RADIUS server and depending on the response either send the packet - to the DHCP server or drop it), it does require a DHCP relay + DHCP and RADIUS integration is done on the DHCP relay-agent level + (DHCP clients send DHCP packets to DHCP relays; those relays contact + the RADIUS server and depending on the response either send the packet + to the DHCP server or drop it), it does require DHCP relay hardware to support RADIUS communication. Also, even if the relay - has necessary support it is often not flexible enough to send and + has the necessary support, it is often not flexible enough to send and receive additional RADIUS attributes. As such, the alternative - looks more appealing: to extend DHCP server to talk to RADIUS + looks more appealing: to extend the DHCP server to talk to RADIUS directly. That is the goal this library intends to fulfill. - This library may only be loaded by kea-dhcp4 - or kea-dhcp6 process. + This library may only be loaded by the kea-dhcp4 + or the kea-dhcp6 process. - The major feature of the library is the ability to use RADIUS + The major feature of the hook library is the ability to use RADIUS authorization. When a DHCP packet is received, the Kea server - will send send Access-Request to the RADIUS server and will await - a response. The server will then send back either Access-Accept - with specific client attributes or Access-Reject. There are two - cases supported here. First, the Access-Accept includes + sends an Access-Request to the RADIUS server and awaits + a response. The server then sends back either an Access-Accept + with specific client attributes, or an Access-Reject. There are two + cases supported here: first, the Access-Accept includes a Framed-IP-Address (for DHCPv4) or Framed-IPv6-Address (for DHCPv6), which will be interpreted by Kea as an instruction to assign that specified IPv4 or IPv6 address. This effectively - means RADIUS can act as address reservation database. + means RADIUS can act as an address-reservation database. The second case supported is the ability to assign clients to - specific pools based on RADIUS response. In this case RADIUS - server sends back Access-Accept with Framed-Pool (IPv4) or - Framed-IPv6-Pool (IPv6). In both cases, Kea will interpret those - attributes as client classes. With the recent addition of the + specific pools based on a RADIUS response. In this case, the RADIUS + server sends back an Access-Accept with Framed-Pool (IPv4) or + Framed-IPv6-Pool (IPv6). In both cases, Kea interprets those + attributes as client classes. With the addition of the ability to limit access to pools to specific classes (see ), it can be used to force client - to be assigned a dynamic address from specific pool. Furthermore, + linkend="classification-pools"/>), RADIUS can be used to force the client + to be assigned a dynamic address from a specific pool. Furthermore, the same mechanism can be used to control what kind of options the - client will get (if there are DHCP options specified for a - particular class). + client will get if there are DHCP options specified for a + particular class.
- Compilation and Installation of RADIUS Hook + Compilation and Installation of the RADIUS Hook The following section describes how to compile and install the software on CentOS 7.0. Other systems may differ slightly. @@ -81,23 +81,23 @@ $ sudo yum install gcc-g++ openssl-devel log4cplus-devel wget git - STEP 2: FreeRADIUS installation. + STEP 2: FreeRADIUS installation - Kea RADIUS hook library uses FreeRadius client library to + The Kea RADIUS hook library uses the FreeRADIUS client library to conduct RADIUS communication. Unfortunately, the standard 1.1.7 release available from the project website http://freeradius.org/sub_projects/ - has several serious deficiencies. ISC engineers observed a segmentation + has several serious deficiencies; ISC engineers observed a segmentation fault during testing. Also, the base version of the library does - not offer asynchronous transmissions, which is essential for + not offer asynchronous transmissions, which are essential for effective accounting implementation. Both of these issues - were addressed by ISC engineers. The changes have been - reported to FreeRadius client project. Acceptance of those - changes is outside of ISC responsibilities. Until those - are processed, it is strongly recommended to use FreeRadius - client with ISC patches. To download and compile this version, please use + were addressed by ISC engineers, and the changes have been + reported to the FreeRADIUS client project. Acceptance of those + changes is outside of ISC responsibilities, so until those + are processed, it is strongly recommended to use the FreeRADIUS + client with ISC's patches. To download and compile this version, please use the following steps: $ git clone https://github.com/fxdupont/freeradius-client.git @@ -108,11 +108,11 @@ $ make $ sudo make install - You may pass additional parameters to configure script, if you need + You may enter additional parameters to the configure script, if you need to. Once installed, the FreeRADIUS client will be installed in /usr/local. This is the default path where Kea will be looking for - it. You may install it in a different directory. If you choose to do - so, make sure you pass that path to configure script when compiling kea. + it. You may install it in a different directory; if you choose to do + so, make sure you add that path to the configure script when compiling Kea. @@ -120,12 +120,12 @@ $ sudo make install - Kea requires reasonably recent Boost version. Unfortunately, - the version available in CentOS 7 is too old. Therefore a + Kea requires a reasonably recent Boost version. Unfortunately, + the version available in CentOS 7 is too old, so a newer Boost version is necessary. Furthermore, CentOS 7 has an - old version of g++ compiler that does not handle latest Boost - versions. Fortunately, Boost 1.65 meets both requirements: is - recent enough for Kea and is still able to be compiled using + old version of the g++ compiler that does not handle the latest Boost + versions. Fortunately, Boost 1.65 meets both requirements; it is both + recent enough for Kea and able to be compiled using the g++ 4.8 version in CentOS. @@ -139,19 +139,19 @@ $ ./bootstrap.sh $ ./b2 --without-python $ sudo ./b2 install - Note that b2 script may optionally take extra parameters. One - of them specify the destination path where the sources are to + Note that the b2 script may optionally take extra parameters; one + of them specifies the destination path where the sources are to be compiled. - STEP 4: Compile and Install Kea + STEP 4: Compile and install Kea - Obtain Kea sources either by downloading it from git repository or extract the tarball: + Obtain the Kea sources either by downloading them from the git repository or extracting the tarball: -# Use one of those commands to obtain Kea sources: +# Use one of those commands to obtain the Kea sources: # Choice 1: get from github $ git clone https://github.com/isc-projects/kea @@ -160,7 +160,7 @@ $ git clone https://github.com/isc-projects/kea $ tar zxvf kea-&keaversion;.tar.gz -The next step is to extract premium Kea package that contains Radius repository +The next step is to extract the premium Kea package that contains the RADIUS repository into the Kea sources. After the tarball is extracted, the Kea sources should have a premium/ subdirectory. @@ -169,7 +169,7 @@ a premium/ subdirectory. $ tar zxvf ../kea-premium-radius-&keaversion;.tar.gz -Once this is done, make sure the kea sources look similar to this: +Once this is done, verify that the Kea sources look similar to this: $ ls -l total 952 @@ -191,13 +191,13 @@ 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 have to be regenerated using autoreconf. +The makefiles must be regenerated using autoreconf. -The next step is to configure Kea. There are several essential steps necessary here. -Running autoreconf -if is necessary to compile premium package that contains -RADIUS. Also, --with-freeradius option is necessary to tell Kea where the FreeRADIUS -client sources can be found. Also, since the non-standard boost is used, the path -to it has to be specified. +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. $ autoreconf -i @@ -205,8 +205,8 @@ $ ./configure --with-freeradius=/path/to/freeradius --with-boost-include=/path/t -For example, assuming FreeRadius client was installed in the default directory (/usr/local) -and Boost 1.65 sources were compiled in /home/thomson/devel/boost1_65_1, the configure path +For example, assuming the FreeRADIUS client was installed in the default directory (/usr/local) +and the Boost 1.65 sources were compiled in /home/thomson/devel/boost1_65_1, the configure path should look as follows: @@ -305,17 +305,17 @@ Developer: Please make sure that your compilation has the following: - radius listed in Included Hooks - FreeRadius client directories printed and pointing to the right - directories - Boost version is at least 1.65.1. The versions available + RADIUS listed in Included Hooks; + FreeRADIUS client directories printed and pointing to the right + directories; + Boost version at least 1.65.1. The versions available in CentOS 7 (1.48 and and 1.53) are too old. - After that compile kea using make. If your system has more than one core, it is recommended to use -j N option. + Once your configuration is complete, compile Kea using make. If your system has more than one core, it is recommended to use the -j N option. $ make -j5 $ sudo make install @@ -328,9 +328,9 @@ Please make sure that your compilation has the following: RADIUS Hook Configuration - The RADIUS Hook is a library that has to be loaded by either DHCPv4 or - DHCPv6 Kea servers. Compared to other available hook libraries, this one - takes many parameters to actually run. For example, this configuration + The RADIUS hook is a library that has to be loaded by either DHCPv4 or + DHCPv6 Kea servers. Unlike some other available hook libraries, this one + takes many parameters. For example, this configuration could be used: @@ -360,7 +360,7 @@ Please make sure that your compilation has the following: - Radius is a complicated environment. As such, it's not really possible + RADIUS is a complicated environment. As such, it's not really possible to provide a default configuration that would work out of the box. However, we do have one example that showcases some of the more common features. Please see doc/examples/kea4/hooks-radius.json in your @@ -369,88 +369,88 @@ Please make sure that your compilation has the following: The RADIUS hook library supports the following global configuration - flags, which corresponds to FreeRADIUS client library options: + flags, which correspond to FreeRADIUS client library options: bindaddr (default "*") specifies the address to be used by the hook library in communication with RADIUS - servers. The "*" special value means to leave the kernel to choose - it. + servers. The "*" special value tells the kernel to choose + the address. canonical-mac-address (default - false) specifies whether MAC addresses in attributes follows the canonical - Radius format (lowercase pairs of hexadecimal digits separated by + false) specifies whether MAC addresses in attributes follow the canonical + RADIUS format (lowercase pairs of hexadecimal digits separated by '-'). - client-id-pop0 (default false) used - with flex-id removes the leading zero (or pair of zero in DHCPv6) type in + client-id-pop0 (default false), used + with flex-id, removes the leading zero (or pair of zeroes in DHCPv6) type in client-id (aka duid in DHCPv6). Implied by client-id-printable. client-id-printable (default false) - checks if the client-id / duid content is printable and uses it as it - instead of in hexadecimal. Implies client-id-pop0 and extract-duid as 0 + checks whether the client-id / duid content is printable and uses it as is + instead of in hexadecimal. Implies client-id-pop0 and extract-duid as 0 and 255 are not printable. deadtime (default 0) is a mechanism - to try not responding servers after responding servers. Its value - specifies the number of seconds the fact a server did not answer is kept, - so 0 disables the mechanism. As the asynchronous communication does not - use locks or atomics it is not recommended to use this feature with this - mode. + to try unresponsive servers after responsive servers. Its value + specifies the number of seconds after which a server is considered not to have answered, + so 0 disables the mechanism. As the asynchronous communication does not + use locks or atomics, it is not recommended to use this feature with this + mode. dictionary (default set by configure - at build time) is the attribute and value dictionary. Note it is a - critical parameter. + at build time) is the attribute and value dictionary. Note that it is a + critical parameter. extract-duid (default true) extracts - from RFC 4361 compliant DHCPv4 client-id the embedded duid. Implied by - client-id-printable. + the embedded duid from an RFC 4361-compliant DHCPv4 client-id. Implied by + client-id-printable. identifier-type4 (default client-id) specifies the identifier type to build the User-Name attribute. It should - be the same than host identifier and when the flex-id hook library is - used the replace-client-id must be set to true and client-id will be used + be the same as the host identifier, and when the flex-id hook library is + used the replace-client-id must be set to true; client-id will be used with client-id-pop0. identifier-type6 (default duid) specifies the identifier type to build the User-Name attribute. It should - be the same than host identifier and when the flex-id hook librairy is - used the replace-client-id must be set to true and duid will be used with - client-id-pop0. + be the same as the host identifier, and when the flex-id hook library is + used the replace-client-id must be set to true; duid will be used with + client-id-pop0. realm (default "") is the default - realm. + realm. reselect-subnet-address (default false) uses the Kea reserved address / RADIUS Framed-IP-Address or Framed-IPv6-Address to reselect subnets where the address is not in - the subnet range. + the subnet range. reselect-subnet-pool (default false) uses the Kea client-class / RADIUS Frame-Pool to reselect - subnets where no available pool can be found. + subnets where no available pool can be found. retries (default 3) is the number of - retries before trying the next server. Note it is not supported for - asynchronous communication. + retries before trying the next server. Note that it is not supported for + asynchronous communication. session-history (default "") is the name of the file providing persistent storage for accounting session - history. + history. timeout (default 10) is the number - of seconds a response is waited for. + of seconds during which a response is awaited. When reselect-subnet-pool or reselect-subnet-address is set to true at the - reception of RADIUS Access-Accept the selected subnet is checked - against the client-class name or the reserved address and if it does - not matched another subnet is selected among matching subnets. + reception of RADIUS Access-Accept, the selected subnet is checked + against the client-class name or the reserved address; if it does + not match, another subnet is selected among matching subnets. @@ -469,57 +469,58 @@ Please make sure that your compilation has the following: contact. Each server may have the following items specified: - name which specifies the IP - address of the server (it is allowed to use a name which will be - resolved but it is not recommended). + name, which specifies the IP + address of the server (it is possible to use a name which will be + resolved, but it is not recommended). port (default RADIUS - authentication or accounting service) which specifies the UDP port + authentication or accounting service), which specifies the UDP port of the server. Note that the FreeRADIUS client library by default uses ports 1812 (auth) and 1813 (acct). Some server implementations - use 1645 (auth) ns 1646 (acct). You may use the "port" parameter to + use 1645 (auth) and 1646 (acct). You may use the "port" parameter to adjust as needed. - secret which authenticates + secret, which authenticates messages. - There may be up to 8 servers. Note when no server was - specified the service is disabled. + There may be up to 8 servers. Note that when no server is + specified, the service is disabled. attributes which define additional attributes that the Kea server will send to a RADIUS server. The parameter must be identified either by a name or type. Its value can - be specified using one of three possible ways: data (which + be specified in one of three possible ways: data (which defines a plain text value), raw (which defines the value in - hex) or expr (which defines an expression, which will be + hex), or expr (which defines an expression, which will be evaluated for each incoming packet independently). name of the - attribute. + attribute. + type of the attribute. Type or name is required, and the attribute must be defined in the dictionary. - data is the first out of three + data is the first of three ways to specify the attribute content. The data entry is parsed by - the FreeRADIUS library so values defined in the dictionary of the + the FreeRADIUS library, so values defined in the dictionary of the attribute may be used. - raw is the second out of three - way to specify the attribute content. It specifies the content in - hexadecimal. Note it does not work with integer content attributes - (date, integer and IPv4 address), a string content attribute - (string. IPv6 address and IPv6 prefix) is + raw is the second of three + ways to specify the attribute content; it specifies the content in + hexadecimal. Note that it does not work with integer-content attributes + (date, integer, and IPv4 address); a string-content attribute + (string, IPv6 address, and IPv6 prefix) is required. expr is the last way to specify the attribute content. It specifies an evaluation expression - which must return a not empty string when evaluated with the DHCP - query packet. Currently this is restricted to the access + which must return a not-empty string when evaluated with the DHCP + query packet. Currently this is restricted to the access service. @@ -527,8 +528,8 @@ Please make sure that your compilation has the following: For example, to specify a single access server available on localhost that - uses "sekret" as a secret and tell Kea to send three additional attributes - (Password, Connect-Info and Configuration-Token), the following snipped could + uses "secret" as a secret, and tell Kea to send three additional attributes + (Password, Connect-Info, and Configuration-Token), the following snippet could be used: "parameters": { @@ -548,7 +549,7 @@ Please make sure that your compilation has the following: // Additional access servers could be specified here ], - // This define a list of additional attributes Kea will send to each + // This defines a list of additional attributes Kea will send to each // access server in Access-Request. "attributes": [ { @@ -595,26 +596,26 @@ Please make sure that your compilation has the following: -For the RADIUS Hook library to operate properly in DHCPv4, it is necessary +For the RADIUS hook library to operate properly in DHCPv4, it is necessary to also load the Host Cache hook library. The reason for this is somewhat -complex. In a typical deployment the DHCP clients send their packets via -DHCP relay which inserts certain Relay Agent Information options, such are +complex. In a typical deployment, the DHCP clients send their packets via +DHCP relay which inserts certain Relay Agent Information options, such as circuit-id or remote-id. The values of those options are then used by the -Kea DHCP server to formulate necessary attributes in the Access-Request message +Kea DHCP server to formulate the necessary attributes in the Access-Request message sent to the RADIUS server. However, once the DHCP client gets its address, it then renews by sending packets directly to the DHCP server. As a result, the -relays are not able to insert their RAI options and DHCP server can't send the +relays are not able to insert their RAI options and the DHCP server can't send the Access-Request queries to the RADIUS server by using just the information from -incoming packets. Kea needs to keep the information received during initial -Discover/Offer exchanges and later use it when sending accounting +incoming packets. Kea needs to keep the information received during the initial +Discover/Offer exchanges and use it again later when sending accounting messages. This mechanism is implemented based on user context in host reservations. (See for details about user context). The host -cache mechanism allows to retain the information retrieved by RADIUS to be +cache mechanism allows the information retrieved by RADIUS to be stored and later used for sending accounting and access queries to the RADIUS server. In other words, the host-cache mechanism is mandatory, unless you -don't want the RADIUS communication for messages other than +do not want RADIUS communication for messages other than Discover and the first Request from each client.