|
|
@@ -35,7 +35,7 @@
|
|
|
<para>
|
|
|
The next section describes how to configure hooks libraries. If you
|
|
|
are interested in writing your own hooks library, information can be
|
|
|
- found in the <ulink url="http://git.kea.isc.org/~tester/kea/doxygen">Kea
|
|
|
+ found in the <ulink url="https://jenkins.isc.org/job/Fedora20_32_doxygen_doc/doxygen/">Kea
|
|
|
Developer's Guide</ulink>.
|
|
|
</para>
|
|
|
</section> <!-- end Introduction -->
|
|
|
@@ -78,9 +78,9 @@
|
|
|
<note><para>
|
|
|
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.
|
|
|
+ a library. The change was made in Kea 1.0 to facilitate the
|
|
|
+ specification of library-specific parameters, a capability
|
|
|
+ available in Kea 1.1.0 onwards.
|
|
|
</para></note>
|
|
|
|
|
|
<note>
|
|
|
@@ -142,24 +142,211 @@
|
|
|
<section>
|
|
|
<title>Available Hooks Libraries</title>
|
|
|
<para>
|
|
|
- As described above the hooks functionality provides a way to customize
|
|
|
+ As described above, the hooks functionality provides a way to customize
|
|
|
a Kea server without modifying the core code. ISC has chosen to take
|
|
|
- advantage of this feature to provide functions that may not be useful
|
|
|
- to all users. To this end ISC has created some hooks libraries which
|
|
|
- are discussed in the following sections.
|
|
|
+ advantage of this feature to provide functions that may only be useful
|
|
|
+ to a subset of Kea users. To this end ISC has created some hooks
|
|
|
+ libraries; these 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 Kea
|
|
|
+ , 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 taking out a support contract: this includes
|
|
|
+ professional support, advance security notifications, input into our
|
|
|
+ roadmap planning, 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 hooks 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. Unknown users
|
|
|
+ will be assigned a
|
|
|
+ lease from the last subnet defined in the configuration file,
|
|
|
+ e.g. to redirect them a captive portal. This demonstrates how an
|
|
|
+ external source of information can be used to influence the Kea
|
|
|
+ allocation engine. This hook is part of the Kea source code and is
|
|
|
+ available in the 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 provides 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
|
|
|
+ (<ulink url="http://tools.ietf.org/html/rfc7596">RFC 7596</ulink>)
|
|
|
+ is a new IPv6 transition
|
|
|
+ technology that provides IPv4 as a service in IPv6-only
|
|
|
+ network. It assumes that dual-stack clients will get a regular IPv6
|
|
|
+ address and IPv6 prefix, but only a fraction of an 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 within the 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 lightweight 4over6 options
|
|
|
+ (<ulink url="http://tools.ietf.org/html/rfc7598">RFC 7598</ulink>),
|
|
|
+ that include the 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 hooks
|
|
|
+ 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 hooks libraries become available as time
|
|
|
+ progresses, both developed internally and externally. Since
|
|
|
+ this list may evolve 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 hooks libraries not
|
|
|
+ listed there, please send a note to the kea-users or kea-dev
|
|
|
+ mailing lists and someone will update it.
|
|
|
</para>
|
|
|
<section>
|
|
|
+ <title>user_chk: Checking User Access</title>
|
|
|
+ <para>
|
|
|
+ The user_chk library is the first hooks 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 the hooks 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>
|
|
|
+ As an example of use, 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 was developed several years before the host
|
|
|
+ reservation mechanism has become available. Currently host reservation is
|
|
|
+ much more
|
|
|
+ powerful and flexible, but nevertheless the user_chk capability to consult
|
|
|
+ and external source of information about clients and alter Kea's
|
|
|
+ behavior is useful and remains of educational value.
|
|
|
+ </para></note>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ The library reads the /tmp/user_chk_registry.txt file while being
|
|
|
+ loaded and each time an incoming packet is processed. The file is expected
|
|
|
+ to have each line contain a self-contained JSON snippet which must
|
|
|
+ have the following two entries:
|
|
|
+
|
|
|
+ <itemizedlist>
|
|
|
+ <listitem><para><command>type</command>, whose value
|
|
|
+ is "HW_ADDR" for IPv4 users or "DUID" for IPv6
|
|
|
+ users</para></listitem>
|
|
|
+ <listitem><para><command>id</command>, 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><command>bootfile</command> whose value
|
|
|
+ is the pathname of the desired file</para></listitem>
|
|
|
+ <listitem><para><command>tftp_server</command> whose
|
|
|
+ value is the hostname or IP address of the desired
|
|
|
+ server</para></listitem>
|
|
|
+ </itemizedlist>
|
|
|
+
|
|
|
+ A 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>
|
|
|
+
|
|
|
+ <para>As with any other hooks libraries provided by ISC, internals of the
|
|
|
+ user_chk code are well documented. You can take a look at the <ulink
|
|
|
+ url="https://jenkins.isc.org/job/Fedora20_32_doxygen_doc/doxygen/d8/db2/libdhcp_user_chk.html">Kea Developer's Guide section dedicated to the user_chk library</ulink>
|
|
|
+ that discusses how the code works internally. That, together with
|
|
|
+ our general entries in <ulink
|
|
|
+ url="https://jenkins.isc.org/job/Fedora20_32_doxygen_doc/doxygen/">Hooks
|
|
|
+ Framework section</ulink> should give you some pointers how to extend
|
|
|
+ this library and perhaps even write your own from scratch.</para>
|
|
|
+
|
|
|
+ </section>
|
|
|
+ <section>
|
|
|
<title>Forensic Logging Hooks</title>
|
|
|
<para>
|
|
|
This section describes the forensic log hooks library. This library
|
|
|
povides hooks that record a detailed log of lease assignments
|
|
|
and renewals into a set of log files. Currently this library
|
|
|
- is only available to customers with a support contract.
|
|
|
+ is only available to ISC customers with a support contract.
|
|
|
</para>
|
|
|
<para>
|
|
|
In many legal jurisdictions companies, especially ISPs, must record
|
Tomek Mrugalski