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.
</para></note>
<note>
are discussed in the following sections.
</para>
+ <note><para>
+ 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.
+ </para></note>
+
+ <para>Currently the following libraries are available or planned from ISC:
+
+ <table frame="all" id="hook-libs">
+ <title>List of available hook libraries</title>
+ <tgroup cols='3'>
+ <colspec colname='name' />
+ <colspec colname='avail' />
+ <colspec colname='description' />
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Availability</entry>
+ <entry>Since</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>user_chk</entry>
+ <entry>Kea sources</entry>
+ <entry>Kea 0.8</entry>
+ <entry>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.</entry>
+ </row>
+ <row>
+ <entry>Forensic Logging</entry>
+ <entry>Support customers</entry>
+ <entry>Kea 1.1.0</entry>
+ <entry>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.</entry>
+ </row>
+ <row>
+ <entry>Lightweight 4over6</entry>
+ <entry>Support customers</entry>
+ <entry>Autumn 2016</entry>
+ <entry>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.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </para>
<para>
- 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: <ulink
+ url="http://kea.isc.org/wiki/Hooks">http://kea.isc.org/wiki/Hooks</ulink>.
+ 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.
</para>
+ <section>
+ <title>user_chk: Checking user access</title>
+ <para>
+ User_chk library is the first hook library published by ISC. It
+ attempts to serve several purposes:
+
+ <itemizedlist>
+ <listitem>
+ <para>To assign "new" or "unregistered" users to a
+ restricted subnet, while "known" or "registered" users are assigned
+ to unrestricted subnets.</para>
+ </listitem>
+ <listitem>
+ <para>To allow DHCP response options or vendor option
+ values to be customized based upon user identity. </para>
+ </listitem>
+ <listitem>
+ <para>To provide a real time record of the user registration
+ activity which can be sampled by an external consumer.</para>
+ </listitem>
+ <listitem>
+ <para> To serve as a demonstration of various capabilities
+ possible using hook interface.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <note><para>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.
+ </para></note>
+
+ <para>
+ 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:
+
+ <itemizedlist>
+ <listitem><para>"type" whose value is "HW_ADDR" for IPv4 users or
+ "DUID" for IPv6 users</para></listitem>
+ <listitem><para>"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.</para></listitem>
+ </itemizedlist>
+
+and may have the zero or more of the following entries:
+
+ <itemizedlist>
+ <listitem><para>"bootfile" whose value is the pathname of the
+ desired file</para></listitem>
+ <listitem><para>"tftp_server" whose value is the hostname or IP
+ address of the desired server</para></listitem>
+ </itemizedlist>
+
+ Sample user registry file is shown below:
+
+<screen>{ "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" }</screen>
+
+ </para>
+
+ </section>
<section>
<title>Forensic Logging Hooks</title>
<para>
projects / thirdparty / kea.git / commitdiff
