diff --git a/doc/guide/Makefile.am b/doc/guide/Makefile.am index b969ca5b01..7dca16a228 100644 --- a/doc/guide/Makefile.am +++ b/doc/guide/Makefile.am @@ -8,6 +8,7 @@ dist_html_DATA = $(HTMLDOCS) kea-guide.css kea-logo-100x70.png DOCBOOK = kea-guide.xml intro.xml quickstart.xml install.xml admin.xml config.xml DOCBOOK += keactrl.xml dhcp4-srv.xml dhcp6-srv.xml lease-expiration.xml logging.xml DOCBOOK += ddns.xml hooks.xml libdhcp.xml lfc.xml stats.xml ctrl-channel.xml faq.xml +DOCBOOK += hooks-host-cache.xml hooks-radius.xml DOCBOOK += classify.xml shell.xml agent.xml EXTRA_DIST = $(DOCBOOK) diff --git a/doc/guide/hooks-host-cache.xml b/doc/guide/hooks-host-cache.xml new file mode 100644 index 0000000000..f4dafbdb30 --- /dev/null +++ b/doc/guide/hooks-host-cache.xml @@ -0,0 +1,4 @@ +
+ host_cache: Caching Host Reservations + todo +
diff --git a/doc/guide/hooks-radius.xml b/doc/guide/hooks-radius.xml new file mode 100644 index 0000000000..e04ddf7aa1 --- /dev/null +++ b/doc/guide/hooks-radius.xml @@ -0,0 +1,493 @@ + + + + +
+ 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 + hardware to support RADIUS communication. Also, even if the relay + has 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 + directly. That is the goal this library intends to fulfill. + + + The major feature of the library is the ability to use RADIUS + authentication. 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 + 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. + + + 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 + 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, + 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). + + +
+ Compilation and Installation of RADIUS Hook + + The following section describes how to compile and install the + software on CentOS 7.0. Other systems may differ slightly. + + + + STEP 1: Install dependencies + + + Several tools are needed to build dependencies and Kea + itself. The following commands should install them: + +$ sudo rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm +$ sudo yum install gcc-g++ openssl-devel log4cplus-devel wget git + + + + + STEP 2: FreeRADIUS installation. + + + Kea RADIUS hook library uses 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 observed a segmentation + fault during teting. Also, the base version of the library does + not offer asynchronous transmissions, which is 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 and compile this version, please use + the following steps: + +$ git clone https://github.com/fxdupont/freeradius-client.git +$ cd freeradius-client/ +$ git checkout iscdev +$ ./configure +$ make +$ sudo make install + + + You may pass additional parameters to 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. + + + + STEP 3: Install recent BOOST version + + + + Kea requires reasonably recent Boost version. Unfortunately, + the version available in CentOS 7 is too old. Therefore 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 + the g++ 4.8 version in CentOS. + + + To download and compile Boost 1.65, please use the following + commands: + +wget -nd https://dl.bintray.com/boostorg/release/1.65.1/source/boost_1_65_1.tar.gz +tar zxvf boost_1_65_1.tar.gz +cd boost_1_65_1/ +./bootstrap.sh +./b2 --without-python + + Note that b2 script may optionally take extra parameters. One + of them specify the destination path where the sources are to + be compiled. Boost is different compared to other software in + the sense that there is no explicit make install step. + + + + STEP 4: Compile and Install Kea + + + + Obtain Kea sources either by downloading it from git repository or extract the tarball: + +# Use one of those commands to obtain Kea sources: + +# Choice 1: get from github +$ git clone https://github.com/isc-projects/kea + +# Get a tarball and extract it +$ tar zxvf kea-1.4.0-beta.tar.gz + + +The next step is to extract premium Kea package that contains Radius repository +into the Kea sources. After the tarball is extracted, the Kea sources should have +a premium/ subdirectory. + + + $ cd kea + $ tar zxvf ../kea-premium-radius-1.4.0-beta.tar.gz + + +Once this is done, make sure the kea sources look similar to this: + +$ 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 +drwxr-xr-x 5 thomson staff 170 Apr 26 19:04 compatcheck +-rw-r--r-- 1 thomson staff 62323 Apr 25 17:38 configure.ac +-rw-r--r-- 1 thomson staff 300 Apr 25 17:38 dns++.pc.in +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 next step is to configure Kea. There are several essential steps necessary here. +The --with-tier2=yes flag 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. + +If the sources are not from a tarball release, makefiles have to be regenerated +using autoreconf. + + +$ autoreconf -i +$ ./configure --with-freeradius=/path/to/freeradius --with-boost-include=/path/to/boost --with-boost-lib-dir=/path/to/boost/state/lib + + + +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 +should look as follows: + + +./configure --with-freeradius=/usr/local \ + --with-boost-include=/home/thomson/devel/boost_1_65_1 \ + --with-boost-lib-dir=/home/thomson/devel/boost_1_65_1/stage/lib \ + --with-tier2=yes + + + + After some checks, the configure script should print a report similar to the + following: + + + + Kea source configure results: + -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- + +Package: + Name: kea + Version: 1.3.0-git + Extended version: 1.3.0-git (git c494c28cc958bb21a9c6cb0f8dc805a721c69893) + OS Family: Linux + Using GNU sed: yes + Premium package: yes + Tier1 Packages: host_cmds flex_id legal_log + Tier2 Packages: high_availability subnet_cmds radius + Included Packages: host_cmds flex_id legal_log high_availability subnet_cmds radius + +C++ Compiler: + CXX: g++ --std=c++11 + CXX_VERSION: g++ (GCC) 4.8.5 20150623 (Red Hat 4.8.5-16) + CXX_STANDARD: 201103 + DEFS: -DHAVE_CONFIG_H + CPPFLAGS: -DOS_LINUX -DBOOST_ASIO_HEADER_ONLY -DBOOST_ASIO_DISABLE_THREADS=1 + 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.65.1 + BOOST_INCLUDES: -I/home/thomson/devel/boost_1_65_1 + BOOST_LIBS: -L/home/thomson/devel/boost_1_65_1/stage/lib -lboost_system + +OpenSSL: + CRYPTO_VERSION: OpenSSL 1.0.2k 26 Jan 2017 + CRYPTO_CFLAGS: + CRYPTO_INCLUDES: + CRYPTO_LDFLAGS: + CRYPTO_LIBS: -lcrypto + +Botan: no + +Log4cplus: + LOG4CPLUS_VERSION: 1.1.3 + LOG4CPLUS_INCLUDES: -I/usr/include + LOG4CPLUS_LIBS: -L/usr/lib -L/usr/lib64 -llog4cplus + +Flex/bison: + FLEX: flex + BISON: bison -y + +MySQL: + no + +PostgreSQL: + no + +Cassandra CQL: + no +Google Test: + no +Google Benchmark: + 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: not found + C++ Code Coverage: no + Logger checks: no + Generate Documentation: no + Parser Generation: no + Kea-shell: no + + + + +Please make sure that your compilation has the following: + + + radius listed in tier 2 packages + FreeRadius client directories printed and pointing to the right + directories + Boost ersion is 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. + + $ make -j5 + $ sudo make install + + +
+ + +
+ RADIUS Hook Configuration + + + The RADIUS Hook is a library that has to be loaded by either DHCPv4 or + DHCPv6 Kea servers. What is different in this library is that it takes + many parameters to actually run. For example, this configuration could + be used: + + + "Dhcp4": { + + // Your regular DHCPv4 configuration parameters here. + + "hooks-libraries": [ + { + "library": "/usr/local/lib/hooks/libdhc_radio.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 + } + } ] + + + + 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 means to leave the kernel to choose + it. + + canonical-mac-address (default + false) specifies whether MAC addresses in attributes follows 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 (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 + 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. + + dictionary (default set by configure + at build time) is the attribute and value dictionary. Note 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. + + 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 librairy is + used the replace-client-id must be set to true and client-id will be used + with client-id-pop0. + + identifier-type6 (default duid) + pecifies 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. + + realm (default "") is the default + realm. + + retries (default 3) is the number of + retries before trying the next server. Note it is 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 a response is waited for. + + + + + + Two services are supported: + + access - the authentication service + accounting - the accounting service + + + + + Configuration of services is divided into two parts: + + + servers that define RADIUS servers the library is expected to + 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). + + port (default RADIUS + authentication or accounting service) which specifies the UDP port + of the server. + + secret which authenticates + messages. + + + There may be up to 8 servers. Note when no server was + specified the service is disabled. + + + + attributes which define attributes which are used by the + service with: + + name of the + attribute. + type of the attribute. Type or + name is required, and the attribute must be defined in the + dictionary. + + data is one of the 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 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 + required. + + expr specifies an evaluation + expression which must return a not empty string when evaluated with + the DHCP query packet. A priori this is restricted to the access + service. + + + + + + + + +TODO: Describe that RADIUS backend must be configured. + +TODO: Describe that host-cache library must also be loaded for the +accounting to work. + +TODO: Add configuration file example here. +
+ +
+ diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml index adb6f467d4..4aaeddbeb8 100644 --- a/doc/guide/hooks.xml +++ b/doc/guide/hooks.xml @@ -21,6 +21,12 @@ functions in them. Those functions perform whatever custom processing is required. + + The hooks concept also allows keeping the core Kea code reasonably small + by moving features that some, but not all users find useful to external + libraries. People who don't need specific functionality simply don't + load the libraries. + Hooks libraries are attached to individual Kea processes, not to Kea as a whole. This means (for example) that it is possible @@ -42,6 +48,17 @@ found in the Kea Developer's Guide. + + + Note that some libraries are available under different licenses. + + + Note that some libraries may require additional dependencies and/or + compilation switches to be enabled, e.g. Radius library introduced in + Kea 1.4 requires FreeRadius-client library to be present. If + --with-free-radius option is not specified, the Radius library will not + be built. +
Configuring Hooks Libraries @@ -281,6 +298,33 @@ Kea DHCP. + + Radius + Support customers + Kea 1.4.0 + The RADIUS Hook library allows Kea to interact with the + RADIUS servers using access and accounting mechanisms. The access + mechanism may be used for access control, assigning specific IPv4 + or IPv6 addresses reserved by RADIUS, dynamically assigning + addresses from designated pools chosen by RADIUS or rejecting + the client's messages altogether. The accounting mechanism allows + RADIUS server to keep track of device activity over time. + + + + Host Cache + Support customers + Kea 1.4.0 + Some of the database backends, such as RADIUS, are + considered slow and may take a long time to respond. Since Kea in + general is synchronous, the backend performance directly affects + the DHCP performance. To minimize the impact and improve + performance, the Host Cache library provides a way to cache + responses from other hosts. This includes negative caching, + i.e. the ability to remember that there is no client information + in the database. + + @@ -295,6 +339,9 @@ listed there, please send a note to the kea-users or kea-dev mailing lists and someone will update it. + + The libraries developed by ISC are described in detail in the following sections. +
user_chk: Checking User Access @@ -2787,6 +2834,10 @@ both the command and the response.
+ + + +