mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-29 04:57:52 +00:00
Code Issues Releases Wiki Activity

[3209] user_chk hook lib documented.

Browse Source
This commit is contained in:
Tomek Mrugalski 2016-09-20 19:09:03 +02:00
parent 06507e6264
commit 8a2c95cda1
1 changed files with 175 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

180
doc/guide/hooks.xml
View File

@ -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.
</para></note>
<note>
@ -149,10 +149,180 @@
are discussed in the following sections.
</para>
<para>
Some of these libraries will be available with the base code while
others will only be available via a support contract.
<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>
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>