|
|
@@ -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
|
|
|
+ a library. The change was made in Kea 1.0 to facilitate the
|
|
|
specification of library-specific parameters, a capability
|
|
|
- available since Kea 1.1.0-beta.
|
|
|
+ available in Kea 1.1.0 onwards.
|
|
|
</para></note>
|
|
|
|
|
|
<note>
|
|
|
@@ -142,28 +142,28 @@
|
|
|
<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 the Kea
|
|
|
- project, possibly as a 'benefit' or 'thank you' for helping to sustain
|
|
|
+ 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 signing up a support contract. It also features a
|
|
|
+ libraries, please consider taking out a support contract: this includes
|
|
|
professional support, advance security notifications, input into our
|
|
|
- roadmap planning, consulting hours and many other benefits, while helping
|
|
|
+ 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 hook libraries</title>
|
|
|
+ <title>List of available hooks libraries</title>
|
|
|
<tgroup cols='3'>
|
|
|
<colspec colname='name' />
|
|
|
<colspec colname='avail' />
|
|
|
@@ -182,44 +182,48 @@
|
|
|
<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
|
|
|
+ <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 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>
|
|
|
+ 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 povides hooks that record a detailed log of
|
|
|
+ <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
|
|
|
+ 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
|
|
|
+ <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 regular IPv6
|
|
|
- address and IPv6 prefix, but only a fraction of IPv4 address. The
|
|
|
+ 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 withing operator's network. The
|
|
|
+ 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 lw4over6 options
|
|
|
- (RFC7598), that include IPv4 address (shared among several
|
|
|
+ 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 hook
|
|
|
+ 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.
|
|
|
@@ -231,19 +235,19 @@
|
|
|
|
|
|
</para>
|
|
|
<para>
|
|
|
- ISC hopes to see more hook libraries become available as time
|
|
|
+ ISC hopes to see more hooks libraries become available as time
|
|
|
progresses, both developed internally and externally. Since
|
|
|
- this list may eveolve dynamically, we decided to keep it on a
|
|
|
+ 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 hook libraries not
|
|
|
- listed there, please send a note to kea-users or kea-dev
|
|
|
+ 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>
|
|
|
+ <title>user_chk: Checking User Access</title>
|
|
|
<para>
|
|
|
- User_chk library is the first hook library published by ISC. It
|
|
|
+ The user_chk library is the first hooks library published by ISC. It
|
|
|
attempts to serve several purposes:
|
|
|
|
|
|
<itemizedlist>
|
|
|
@@ -262,7 +266,7 @@
|
|
|
</listitem>
|
|
|
<listitem>
|
|
|
<para> To serve as a demonstration of various capabilities
|
|
|
- possible using hook interface.</para>
|
|
|
+ possible using the hooks interface.</para>
|
|
|
</listitem>
|
|
|
</itemizedlist>
|
|
|
</para>
|
|
|
@@ -276,44 +280,48 @@
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- For example this behavior may be used to put unknown users into a
|
|
|
+ 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
|
|
|
+ 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
|
|
|
+ <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 to have educational value.
|
|
|
+ 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 processing every incoming packet. The file is expected
|
|
|
+ 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>"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>
|
|
|
+ <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>"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>
|
|
|
+ <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>
|
|
|
|
|
|
- Sample user registry file is shown below:
|
|
|
+ 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" }
|
|
|
@@ -322,7 +330,7 @@ and may have the zero or more of the following entries:
|
|
|
|
|
|
</para>
|
|
|
|
|
|
- <para>As with any other hook libraries provided by ISC, internals of the
|
|
|
+ <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
|
|
|
@@ -338,7 +346,7 @@ and may have the zero or more of the following entries:
|
|
|
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
|
Stephen Morris