From: Tomek Mrugalski Date: Tue, 20 Sep 2016 17:09:03 +0000 (+0200) Subject: [3209] user_chk hook lib documented. X-Git-Tag: trac5049_base~6^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8a2c95cda162cd29e63c7598feba1c0d7241feed;p=thirdparty%2Fkea.git [3209] user_chk hook lib documented. --- diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml index 3aeefebfb9..715f0424d8 100644 --- a/doc/guide/hooks.xml +++ b/doc/guide/hooks.xml @@ -79,8 +79,8 @@ This is a change to the syntax used in Kea 0.9.2 and earlier, where hooks-libraries was a list of strings, each string being the name of a library. The change has been made in Kea 1.0 to facilitate the - specification of library-specific parameters, a feature that will be - added to a future version of Kea. + specification of library-specific parameters, a capability + available since Kea 1.1.0-beta. @@ -149,10 +149,180 @@ are discussed in the following sections. + + Some of these libraries will be available with the base code while others + will be shared with organizations supporting development of the Kea + project, possibly as a 'benefit' or 'thank you' for helping to sustain + the larger Kea project. If you would like to get access to those + libraries, please consider signing up a support contract. It also features a + professional support, advance security notifications, input into our + roadmap planning, consulting hours and many other benefits, while helping + making Kea sustainable in the long term. + + + Currently the following libraries are available or planned from ISC: + + + List of available hook libraries + + + + + + + Name + Availability + Since + Description + + + + + + user_chk + Kea sources + Kea 0.8 + Reads known users list from a file. it will be assigned a + lease from the last subnet defined in the configuration file, + e.g. to redirect him into a captive portal. This showcases how + externals source of information can be used to influence Kea + allocation engine. This hook is part of the Kea sources and is + available in src/hooks/dhcp/user_chk directory. + + + Forensic Logging + Support customers + Kea 1.1.0 + This library povides hooks that record a detailed log of + lease assignments and renewals into a set of log files. In many + legal jurisdictions companies, especially ISPs, must record + information about the addresses they have leased to DHCP + clients. This library is designed to help with that + requirement. If the information that it records is sufficient it + may be used directly. If your jurisdiction requires that you save + a different set of information you may use it as a template or + example and create your own custom logging hooks. + + + Lightweight 4over6 + Support customers + Autumn 2016 + Lightweight 4over6 (RFC7596) is a new IPv6 transition + technology that provides IPv4 as a service in IPv6-only + network. It assumes that dual-stack clients will get regular IPv6 + address and IPv6 prefix, but only a fraction of IPv4 address. The + fraction is specified as port-set, which is essentially a range of + TCP and UDP ports a client can use. By doing the transition on the + client side, this technology eliminates the need to deploy + expensive Carrier Grade NATs withing operator's network. The + problem on the DHCP side is the non-trivial logic behind it: each + client needs to receive an unique set of lw4over6 options + (RFC7598), that include IPv4 address (shared among several + clients), port-set (which is unique among clients sharing the same + IPv4 address and a number of additional parameters. This hook + library will generate values of those options dynamically, thus + eliminating the need to manually configure values for each client + separately. + + + + +
+ + - Some of these libraries will be available with the base code while - others will only be available via a support contract. + ISC hopes to see more hook libraries become available as time + progresses, both developed internally and externally. Since + this list may eveolve dynamically, we decided to keep it on a + wiki page, available at this link: http://kea.isc.org/wiki/Hooks. + If you are a developer or are aware of any hook libraries not + listed there, please send a note to kea-users or kea-dev + mailing lists and someone will update it. +
+ user_chk: Checking user access + + User_chk library is the first hook library published by ISC. It + attempts to serve several purposes: + + + + To assign "new" or "unregistered" users to a + restricted subnet, while "known" or "registered" users are assigned + to unrestricted subnets. + + + To allow DHCP response options or vendor option + values to be customized based upon user identity. + + + To provide a real time record of the user registration + activity which can be sampled by an external consumer. + + + To serve as a demonstration of various capabilities + possible using hook interface. + + + + + Once loaded, the library allows segregating incomings requests into + known and unknown clients. For known clients, the packets are + processed mostly as usual, except it is possible to override certain + options being sent. That can be done on a per host basis. Clients + that are not on the known hosts list will be treated as unknown and + will be assigned to the last subnet defined in the configuration file. + + + + For example this behavior may be used to put unknown users into a + separate subnet that leads to a walled garden, where they can only + access a registration portal. Once they fill in necessary data, their + details are added to the known clients file, and they get a proper + address after their device is restarted. + + + This library has been developed several years before host + reservation mechanism has become available. Currently HR is much more + powerful and flexible, but nevertheless user_chk capability to consult + and external source of information about clients and alter Kea's + behavior is useful and remains to have educational value. + + + + The library reads the /tmp/user_chk_registry.txt file while being + loaded and processing every incoming packet. The file is expected + to have each line contain a self-contained JSON snippet which must + have the following two entries: + + + "type" whose value is "HW_ADDR" for IPv4 users or + "DUID" for IPv6 users + "id" whose value is either the hardware address or + the DUID from the equest formatted as a string of hex digits, with + or without ":" delimiters. + + +and may have the zero or more of the following entries: + + + "bootfile" whose value is the pathname of the + desired file + "tftp_server" whose value is the hostname or IP + address of the desired server + + + Sample user registry file is shown below: + +{ "type" : "HW_ADDR", "id" : "0c:0e:0a:01:ff:04", "bootfile" : "/tmp/v4bootfile" } +{ "type" : "HW_ADDR", "id" : "0c:0e:0a:01:ff:06", "tftp_server" : "tftp.v4.example.com" } +{ "type" : "DUID", "id" : "00:01:00:01:19:ef:e6:3b:00:0c:01:02:03:04", "bootfile" : "/tmp/v6bootfile" } +{ "type" : "DUID", "id" : "00:01:00:01:19:ef:e6:3b:00:0c:01:02:03:06", "tftp_server" : "tftp.v6.example.com" } + + + +
Forensic Logging Hooks