mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-22 18:08:16 +00:00
80 lines
3.3 KiB
ReStructuredText
80 lines
3.3 KiB
ReStructuredText
.. _hooks-user-chk:
|
|
|
|
``user_chk``: User Check
|
|
========================
|
|
|
|
This library serves 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 on user identity.
|
|
|
|
- To provide a real-time record of user registration activity, which
|
|
can be sampled by an external consumer.
|
|
|
|
- To serve as a demonstration of various capabilities possible using
|
|
the hooks interface.
|
|
|
|
This library is part of the Kea open source and is available to all users.
|
|
|
|
Once loaded, the library allows the separation of incoming requests into known
|
|
and unknown clients. For known clients, packets are processed
|
|
as usual, although it is possible to override the sending of certain options
|
|
on a per-host basis. Clients that are not on the known
|
|
hosts list are treated as unknown and are assigned to the last
|
|
subnet defined in the configuration file.
|
|
|
|
As an example of a use case, this behavior may be implemented 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.
|
|
|
|
.. note::
|
|
|
|
This library was developed several years before the host reservation
|
|
mechanism became available. Host reservation is much
|
|
more powerful and flexible, but the ability of ``user_chk``
|
|
to consult an external source of information about clients and alter
|
|
Kea's behavior remains useful and of educational value.
|
|
|
|
The library reads the ``/tmp/user_chk_registry.txt`` file while being loaded
|
|
and each time an incoming packet is processed. Each line of the file is expected to
|
|
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 request formatted as a string of hex digits, with or without ":"
|
|
delimiters.
|
|
|
|
and may have 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.
|
|
|
|
A 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" }
|
|
|
|
As with any other hook libraries provided by ISC, internals of the
|
|
``user_chk`` code are well-documented. Users may refer to the `user_chk
|
|
library section of the Kea Developer's Guide
|
|
<https://reports.kea.isc.org/dev_guide/d8/db2/libdhcp_user_chk.html>`__
|
|
for information on how the code works internally. That, together with the
|
|
`Hooks Framework section of the Kea Developer's Guide
|
|
<https://reports.kea.isc.org/dev_guide/index.html#hooksFramework>`__ should give users
|
|
some pointers on how to extend this library and perhaps even write one
|
|
from scratch.
|