mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-09-05 08:25:16 +00:00
2828 lines
110 KiB
XML
2828 lines
110 KiB
XML
<!--
|
|
- Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
|
|
-
|
|
- This Source Code Form is subject to the terms of the Mozilla Public
|
|
- License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
- file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
|
-->
|
|
<!-- Converted by db4-upgrade version 1.1 -->
|
|
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="hooks-libraries">
|
|
|
|
<title>Hooks Libraries</title>
|
|
<section xml:id="hooks-libraries-introduction">
|
|
<title>Introduction</title>
|
|
<para>
|
|
Although Kea offers a lot of flexibility, there may be cases where
|
|
its behavior needs customization. To accommodate this possibility,
|
|
Kea includes the idea of "Hooks". This feature lets Kea load one
|
|
or more dynamically-linked libraries (known as "hooks libraries")
|
|
and, at various points in its processing ("hook points"), call
|
|
functions in them. Those functions perform whatever custom
|
|
processing is required.
|
|
</para>
|
|
<para>
|
|
Hooks libraries are attached to individual Kea processes, not to
|
|
Kea as a whole. This means (for example) that it is possible
|
|
to associate one set of libraries with the DHCP4 server and a
|
|
different set to the DHCP6 server.
|
|
</para>
|
|
<para>
|
|
Another point to note is that it is possible for a process to
|
|
load multiple libraries. When processing reaches a hook point,
|
|
Kea calls the hooks library functions attached to it. If multiple
|
|
libraries have attached a function to a given hook point, Kea calls
|
|
all of them, in the order in which the libraries are specified in
|
|
the configuration file. The order may be important: consult the
|
|
documentation of the libraries to see if this is the case.
|
|
</para>
|
|
<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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://jenkins.isc.org/job/Fedora20_32_doxygen_doc/doxygen/">Kea
|
|
Developer's Guide</link>.
|
|
</para>
|
|
</section> <!-- end Introduction -->
|
|
<section>
|
|
<title>Configuring Hooks Libraries</title>
|
|
<para>
|
|
The hooks libraries for a given process are configured using the
|
|
<command>hooks-libraries</command> keyword in the
|
|
configuration for that process. (Note that
|
|
the word "hooks" is plural). The value of the keyword
|
|
is an array of map structures, each structure corresponding to a hooks
|
|
library. For example, to set up two hooks libraries for the DHCPv4
|
|
server, the configuration would be:
|
|
<screen>
|
|
<userinput>"Dhcp4": {
|
|
:
|
|
"hooks-libraries": [
|
|
{
|
|
"library": "/opt/charging.so"
|
|
},
|
|
{
|
|
"library": "/opt/local/notification.so",
|
|
"parameters": {
|
|
"mail": "spam@example.com",
|
|
"floor": 13,
|
|
"debug": false,
|
|
"users": [ "alice", "bob", "charlie" ],
|
|
"languages": {
|
|
"french": "bonjour",
|
|
"klingon": "yl'el"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
:
|
|
}</userinput>
|
|
</screen>
|
|
</para>
|
|
|
|
<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 was made in Kea 1.0 to facilitate the
|
|
specification of library-specific parameters, a capability
|
|
available in Kea 1.1.0 onwards. Libraries should allow a parameter
|
|
entry where to put comments as it is done for many configuration
|
|
scopes with comment and user context.
|
|
</para></note>
|
|
|
|
<note>
|
|
<para>
|
|
The library reloading behavior has changed in Kea 1.1. Libraries are
|
|
reloaded, even if their list hasn't changed. Kea does that, because
|
|
the parameters specified for the library (or the files those
|
|
parameters point to) may have changed.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
Libraries may have additional parameters. Those are not mandatory in the
|
|
sense that there may be libraries that don't require them. However, for
|
|
specific library there is often specific requirement for specify certain
|
|
set of parameters. Please consult the documentation for your library
|
|
for details. In the example above, the first library has no parameters.
|
|
The second library has five parameters, specifying mail (string
|
|
parameter), floor (integer parameter), debug (boolean parameter) and
|
|
even lists (list of strings) and maps (containing strings). Nested
|
|
parameters could be used if the library supports it. This topic is
|
|
explained in detail in the Hooks Developer's Guide in the "Configuring
|
|
Hooks Libraries" section.
|
|
</para>
|
|
|
|
<para>
|
|
Notes:
|
|
<itemizedlist mark="bullet">
|
|
<listitem><para>
|
|
The full path to each library should be given.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
As noted above, order may be important - consult the documentation for
|
|
each library.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
An empty list has the same effect as omitting the
|
|
<command>hooks-libraries</command> configuration element all together.
|
|
</para>
|
|
<note><para>
|
|
There is one case where this is not true: if Kea
|
|
is running with a configuration that contains a
|
|
<command>hooks-libraries</command> item, and that item is
|
|
removed and the configuration reloaded, the removal will be
|
|
ignored and the libraries remain loaded. As a workaround,
|
|
instead of removing the <command>hooks-libraries</command>
|
|
item, change it to an empty list. This will be fixed in a
|
|
future version of Kea.
|
|
</para></note>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
At the present time, only the kea-dhcp4 and kea-dhcp6 processes support
|
|
hooks libraries.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Available Hooks Libraries</title>
|
|
<para>
|
|
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 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" xml: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>Flexible Identifier</entry>
|
|
<entry>Support customers</entry>
|
|
<entry>Kea 1.2.0</entry>
|
|
<entry>Kea software provides a way to handle host reservations
|
|
that include addresses, prefixes, options, client classes and
|
|
other features. The reservation can be based on hardware address,
|
|
DUID, circuit-id or client-id in DHCPv4 and using hardware address
|
|
or DUID in DHCPv6. However, there are sometimes scenarios where the
|
|
reservation is more complex, e.g. uses other options that
|
|
mentioned above, uses part of specific options or perhaps even a
|
|
combination of several options and fields to uniquely identify a
|
|
client. Those scenarios are addressed by the Flexible Identifiers
|
|
hook application. It allows defining an expression, similar to
|
|
the one used in client classification,
|
|
e.g. substring(relay6[0].option[37],0,6). Each incoming packet is
|
|
evaluated against that expression and its value is then searched
|
|
in the reservations database.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Host Commands</entry>
|
|
<entry>Support customers</entry>
|
|
<entry>Kea 1.2.0</entry>
|
|
<entry>Kea provides a way to store host reservations in a
|
|
database. In many larger deployments it is useful to be able to
|
|
manage that information while the server is running. This library
|
|
provides management commands for adding, querying and deleting
|
|
host reservations in a safe way without restarting the server.
|
|
In particular, it validates the parameters, so an attempt to
|
|
insert incorrect data, e.g. add a host with conflicting identifier
|
|
in the same subnet will be rejected. Those commands are
|
|
exposed via command channel (JSON over unix sockets) and Control
|
|
Agent (JSON over RESTful interface). Additional commands and
|
|
capabilities related to host reservations will be added in the
|
|
future.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Subnet Commands</entry>
|
|
<entry>Support customers</entry>
|
|
<entry>Kea 1.3.0</entry>
|
|
<entry>In deployments in which subnet configuration needs to
|
|
be frequently updated, it is a hard requirement that such updates be
|
|
performed without the need for a full DHCP server reconfiguration
|
|
or restart. This hooks library allows for incremental changes
|
|
to the subnet configuration such as: adding a subnet, removing
|
|
a subnet. It also allows for listing all available subnets and
|
|
fetching detailed information about a selected subnet. The
|
|
commands exposed by this library do not affect other subnets
|
|
or configuration parameters currently used by the server.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>High Availability</entry>
|
|
<entry>Support customers</entry>
|
|
<entry>Kea 1.4.0</entry>
|
|
<entry>Minimizing a risk of DHCP service unavailability is achieved
|
|
by setting up multiple instances of the DHCP servers in a network.
|
|
Each server can serve selected group of clients in this network
|
|
(load balancing) or all clients, if it detects that its partner has
|
|
crashed or cannot be providing DHCP service for any other reason.
|
|
It is also possible to designate one server to serve all DHCP clients,
|
|
and leave another server as "standby". This server will activate its
|
|
DHCP function when it detects that its partner is not available.
|
|
Such cooperation between the DHCP servers requires that these
|
|
servers constantly communicate with each other to send updates about
|
|
allocated leases and to periodically test whether their partners are still
|
|
operational. The "libdhcp_ha" library provides such functionality for
|
|
Kea DHCP.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
</para>
|
|
<para>
|
|
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: <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://kea.isc.org/wiki/Hooks">http://kea.isc.org/wiki/Hooks</link>.
|
|
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 incoming 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 request
|
|
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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="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</link>
|
|
that discusses how the code works internally. That, together with
|
|
our general entries in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://jenkins.isc.org/job/Fedora20_32_doxygen_doc/doxygen/">Hooks
|
|
Framework section</link> should give you some pointers how to extend
|
|
this library and perhaps even write your own from scratch.</para>
|
|
|
|
</section>
|
|
<section>
|
|
<title>legal_log: Forensic Logging Hooks</title>
|
|
<para>
|
|
This section describes the forensic log hooks library. This library
|
|
provides hooks that record a detailed log of lease assignments
|
|
and renewals into a set of log files. Currently this library
|
|
is only available to ISC customers with a support contract.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
This logging is done as a set of hooks to allow it to be customized
|
|
to any particular need. Modifying a hooks library is easier and
|
|
safer than updating the core code. In addition by using the hooks
|
|
features those users who don't need to log this information can
|
|
leave it out and avoid any performance penalties.
|
|
</para>
|
|
<section>
|
|
<title>Log File Naming</title>
|
|
<para>
|
|
The names for the log files have the following form:
|
|
</para>
|
|
<screen>
|
|
path/base-name.CCYYMMDD.txt
|
|
</screen>
|
|
<para>
|
|
The "path" and "base-name" are supplied in the
|
|
configuration as described below see
|
|
<xref linkend="forensic-log-configuration"/>. The next part of the name is
|
|
the date the log file was started, with four digits for year, two digits
|
|
for month and two digits for day. The file is rotated on a daily basis.
|
|
</para>
|
|
<note><para>
|
|
When running Kea servers for both DHCPv4 and DHCPv6 the log names must
|
|
be distinct. See the examples in <xref linkend="forensic-log-configuration"/>.
|
|
</para></note>
|
|
</section>
|
|
<section>
|
|
<title>DHCPv4 Log Entries</title>
|
|
<para>
|
|
For DHCPv4 the library creates entries based on DHCPREQUEST messages
|
|
and corresponding DHCPv4 leases intercepted by lease4_select
|
|
(for new leases) and lease4_renew (for renewed leases) hooks.
|
|
</para>
|
|
<para>
|
|
An entry is a single string with no embedded end-of-line markers,
|
|
a prepended timestamp and has the following sections:
|
|
<screen>
|
|
timestamp address duration device-id {client-info} {relay-info}
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
Where:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
timestamp - the current date and time the log entry was written
|
|
in "%Y-%m-%d %H:%M:%S %Z" strftime format ("%Z" is the time zone
|
|
name).
|
|
</para></listitem>
|
|
<listitem><para>
|
|
address - the leased IPv4 address given out and whether it was
|
|
assigned or renewed.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
duration - the lease lifetime expressed in days (if present),
|
|
hours, minutes and seconds. A lease lifetime of 0xFFFFFFFF will be
|
|
denoted with the text "infinite duration".
|
|
</para></listitem>
|
|
<listitem><para>
|
|
device-id - the client's hardware address shown as numerical type
|
|
and hex digit string.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
client-info - the DHCP client id option (61) if present, shown as
|
|
a hex string.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
relay-info - for relayed packets the giaddr and the RAI circuit-id,
|
|
remote-id and subscriber-id options (option 82 sub
|
|
options: 1, 2 and 6) if present.
|
|
The circuit id and remote id are presented as hex strings
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
For instance (line breaks added for readability, they would not
|
|
be present in the log file).
|
|
<screen>
|
|
2018-01-06 01:02:03 CET Address: 192.2.1.100 has been renewed for 1 hrs 52 min 15 secs to a device with hardware address: hwtype=1 08:00:2b:02:3f:4e, client-id: 17:34:e2:ff:09:92:54 connected via relay at address: 192.2.16.33, identified by circuit-id: 68:6f:77:64:79 and remote-id: 87:f6:79:77:ef
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
In addition to logging lease activity driven by DHCPv4 client traffic, it also
|
|
logs entries for the following lease management control channel commands:
|
|
lease4-add, lease4-update, and lease4-del. Each entry is a single string
|
|
with no embedded end-of-line markers and they will typically have the following
|
|
forms:
|
|
</para>
|
|
<para>
|
|
<command>lease4-add:</command>
|
|
<screen>
|
|
*timestamp* Administrator added a lease of address: *address* to a device with hardware address: *device-id*
|
|
</screen>
|
|
Dependent on the arguments of the add command, it may also include the
|
|
client-id and duration.
|
|
</para>
|
|
<para>
|
|
Example:
|
|
<screen>
|
|
2018-01-06 01:02:03 CET Administrator added a lease of address: 192.0.2.202 to a device with hardware address: 1a:1b:1c:1d:1e:1f for 1 days 0 hrs 0 mins 0 secs
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
<command>lease4-update:</command>
|
|
<screen>
|
|
*timestamp* Administrator updated information on the lease of address: *address* to a device with hardware address: *device-id*
|
|
</screen>
|
|
Dependent on the arguments of the update command, it may also include the
|
|
client-id and lease duration.
|
|
</para>
|
|
<para>
|
|
Example:
|
|
<screen>
|
|
2018-01-06 01:02:03 CET Administrator updated information on the lease of address: 192.0.2.202 to a device with hardware address: 1a:1b:1c:1d:1e:1f, client-id: 1234567890
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
<command>lease4-del:</command>
|
|
Deletes have two forms, one by address and one by identifier and identifier type:
|
|
<screen>
|
|
*timestamp* Administrator deleted the lease for address: *address*
|
|
</screen>
|
|
or
|
|
<screen>
|
|
*timestamp* Administrator deleted a lease for a device identified by: *identifier-type* of *identifier*
|
|
</screen>
|
|
Currently only a type of @b hw-address (hardware address) is supported.
|
|
</para>
|
|
<para>
|
|
Examples:
|
|
<screen>
|
|
2018-01-06 01:02:03 CET Administrator deleted the lease for address: 192.0.2.202
|
|
|
|
2018-01-06 01:02:12 CET Administrator deleted a lease for a device identified by: hw-address of 1a:1b:1c:1d:1e:1f
|
|
</screen>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>DHCPv6 Log Entries</title>
|
|
<para>
|
|
For DHCPv6 the library creates entries based on lease management
|
|
actions intercepted by the lease6_select (for new leases), lease6_renew
|
|
(for renewed leases) and lease6_rebind (for rebound leases).
|
|
</para>
|
|
<para>
|
|
An entry is a single string with no embedded end-of-line markers,
|
|
a prepended timestamp and has the following sections:
|
|
<screen>
|
|
timestamp address duration device-id {relay-info}*
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
Where:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
timestamp - the current date and time the log entry was written
|
|
in "%Y-%m-%d %H:%M:%S %Z" strftime format ("%Z" is the time zone
|
|
name).
|
|
</para></listitem>
|
|
<listitem><para>
|
|
address - the leased IPv6 address or prefix given out and whether
|
|
it was assigned or renewed.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
duration - the lease lifetime expressed in days (if present),
|
|
hours, minutes and seconds. A lease lifetime of 0xFFFFFFFF will be
|
|
denoted with the text "infinite duration".
|
|
</para></listitem>
|
|
<listitem><para>
|
|
device-id - the client's DUID and hardware address (if present).
|
|
</para></listitem>
|
|
<listitem><para>
|
|
relay-info - for relayed packets the content of relay agent
|
|
messages, remote-id (code 37), subscriber-id (code 38) and
|
|
interface-id (code 18) options if present. Note that
|
|
interface-id option, if present, identifies the whole interface the
|
|
relay agent received the message on. This typically translates to a
|
|
single link in your network, but it depends on your specific network
|
|
topology. Nevertheless, this is useful information to better scope
|
|
down the location of the device, so it is being recorded, if present.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
For instance (line breaks added for readability, they would not
|
|
be present in the log file).
|
|
<screen>
|
|
2018-01-06 01:02:03 PST Address:2001:db8:1:: has been assigned for 0 hrs 11 mins 53 secs to a device with DUID: 17:34:e2:ff:09:92:54 and hardware address: hwtype=1 08:00:2b:02:3f:4e (from Raw Socket) connected via relay at address: fe80::abcd for client on link address: 3001::1, hop count: 1, identified by remote-id: 01:02:03:04:0a:0b:0c:0d:0e:0f and subscriber-id: 1a:2b:3c:4d:5e:6f
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
In addition to logging lease activity driven by DHCPv6 client traffic, it also
|
|
logs entries for the following lease management control channel commands:
|
|
lease6-add, lease6-update, and lease6-del. Each entry is a single string
|
|
with no embedded end-of-line markers and they will typically have the following
|
|
forms:
|
|
</para>
|
|
<para>
|
|
<command>lease6-add:</command>
|
|
<screen>
|
|
*timestamp* Administrator added a lease of address: *address* to a device with DUID: *DUID*
|
|
</screen>
|
|
Dependent on the arguments of the add command, it may also include the hardware address and duration.
|
|
</para>
|
|
<para>
|
|
Example:
|
|
<screen>
|
|
2018-01-06 01:02:03 PST Administrator added a lease of address: 2001:db8::3 to a device with DUID: 1a:1b:1c:1d:1e:1f:20:21:22:23:24 for 1 days 0 hrs 0 mins 0 secs
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
<command>lease6-update:</command>
|
|
<screen>
|
|
*timestamp* Administrator updated information on the lease of address: *address* to a device with DUID: *DUID*
|
|
</screen>
|
|
Dependent on the arguments of the update command, it may also include the hardware address and lease duration.
|
|
</para>
|
|
<para>
|
|
Example:
|
|
<screen>
|
|
2018-01-06 01:02:03 PST Administrator updated information on the lease of address: 2001:db8::3 to a device with DUID: 1a:1b:1c:1d:1e:1f:20:21:22:23:24, hardware address: 1a:1b:1c:1d:1e:1f
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
<command>lease6-del:</command>
|
|
Deletes have two forms, one by address and one by identifier and identifier type:
|
|
<screen>
|
|
*timestamp* Administrator deleted the lease for address: *address*
|
|
</screen>
|
|
or
|
|
<screen>
|
|
*timestamp* Administrator deleted a lease for a device identified by: *identifier-type* of *identifier*
|
|
</screen>
|
|
Currently only a type of DUID is supported.
|
|
</para>
|
|
<para>
|
|
Examples:
|
|
<screen>
|
|
2018-01-06 01:02:03 PST Administrator deleted the lease for address: 2001:db8::3
|
|
|
|
2018-01-06 01:02:11 PST Administrator deleted a lease for a device identified by: duid of 1a:1b:1c:1d:1e:1f:20:21:22:23:24
|
|
</screen>
|
|
</para>
|
|
</section>
|
|
<section xml:id="forensic-log-configuration">
|
|
<title>Configuring the Forensic Log Hooks</title>
|
|
<para>
|
|
To use this functionality the hook library must be included in the
|
|
configuration of the desired DHCP server modules. The legal_log
|
|
library is installed alongside the Kea libraries in
|
|
<filename>[kea-install-dir]/lib</filename> where
|
|
<filename>kea-install-dir</filename> is determined by the
|
|
"--prefix" option of the configure script. It defaults to
|
|
<filename>/usr/local</filename>. Assuming the
|
|
default value then, configuring kea-dhcp4 to load the legal_log
|
|
library could be done with the following Kea4 configuration:
|
|
<screen>
|
|
"Dhcp4": { <userinput>
|
|
"hooks-libraries": [
|
|
{
|
|
"library": "/usr/local/lib/libdhcp_legal_log.so",
|
|
"parameters": {
|
|
"path": "/var/kea/var",
|
|
"base-name": "kea-forensic4"
|
|
}
|
|
},
|
|
...
|
|
] </userinput>
|
|
}
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
To configure it for kea-dhcp6, the commands are simply as shown below:
|
|
<screen>
|
|
"Dhcp6": { <userinput>
|
|
"hooks-libraries": [
|
|
{
|
|
"library": "/usr/local/lib/libdhcp_legal_log.so",
|
|
"parameters": {
|
|
"path": "/var/kea/var",
|
|
"base-name": "kea-forensic6"
|
|
}
|
|
},
|
|
...
|
|
] </userinput>
|
|
}
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
Two Hook Library parameters are supported:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
path - the directory in which the forensic file(s) will be written. The
|
|
default value is
|
|
<filename>[prefix]/kea/var</filename>. The directory must exist.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
base-name - an arbitrary value which is used in conjunction with
|
|
the current system date to form the current forensic file name. It defaults
|
|
to <filename>kea-legal</filename>.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
If it is desired to restrict forensic logging to certain subnets, the
|
|
"legal-logging" boolean parameter can be specified within a user context of
|
|
these subnets. For example:
|
|
<screen>
|
|
"Dhcpv4" {
|
|
"subnet4": [
|
|
{
|
|
"subnet": "192.0.2.0/24",
|
|
"pools": [
|
|
{
|
|
"pool": "192.0.2.1 - 192.0.2.200"
|
|
}
|
|
],
|
|
<userinput>"user-context": {
|
|
"legal-logging": false
|
|
}</userinput>
|
|
}
|
|
]
|
|
}
|
|
</screen>
|
|
disables legal logging for the subnet "192.0.2.0/24". If this parameter
|
|
is not specified, it defaults to 'true', which enables legal logging for
|
|
the subnet.
|
|
</para>
|
|
|
|
<para>
|
|
The following example demonstrates how to selectively disable legal logging
|
|
for an IPv6 subnet.
|
|
<screen>
|
|
"Dhcpv6": {
|
|
"subnet6": [
|
|
{
|
|
"subnet": "2001:db8:1::/64",
|
|
"pools": [
|
|
{
|
|
"pool": "2001:db8:1::1-2001:db8:1::ffff"
|
|
}
|
|
],
|
|
<userinput>"user-context": {
|
|
"legal-logging": false
|
|
}</userinput>
|
|
}
|
|
]
|
|
}
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
See <xref linkend="dhcp4-user-contexts"/> and <xref linkend="dhcp6-user-contexts"/>
|
|
to learn more about user contexts in Kea configuration.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="forensic-log-database">
|
|
<title>Database backend</title>
|
|
<para>
|
|
Log entries can be inserted into a database when Kea is configured
|
|
with database backend support: a table named 'logs' is used with a
|
|
timestamp (timeuuid for Cassandra CQL) generated by the database
|
|
software and a text log with the same format than for files
|
|
without the timestamp.
|
|
</para>
|
|
<para>
|
|
Please refer to <xref linkend="mysql-database"/> for MySQL,
|
|
to <xref linkend="pgsql-database"/> for PostgreSQL or
|
|
to <xref linkend="cql-database"/> for Cassandra CQL.
|
|
Scripts are in
|
|
<filename><replaceable>path-to-kea</replaceable>/share/kea/legal_log/scripts</filename> directory, for instance the PostgreSQL create schema
|
|
command is:
|
|
<screen>
|
|
$ <userinput>psql -d <replaceable>database-name</replaceable> -U <replaceable>user-name</replaceable> -f <replaceable>path-to-kea</replaceable>/share/kea/legal_log/scripts/pgsql/legldb_create.pgsql</userinput>
|
|
Password for user <replaceable>user-name</replaceable>:
|
|
START TRANSACTION
|
|
CREATE TABLE
|
|
CREATE INDEX
|
|
CREATE TABLE
|
|
INSERT 0 1
|
|
COMMIT
|
|
$
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
Configuration parameters are extended by standard lease database
|
|
parameters as defined in <xref linkend="database-configuration4"/>.
|
|
The "type" parameter should be "mysql", "postgresql", "cql" or
|
|
be "logfile". When it is absent or set to "logfile" files are
|
|
used.
|
|
</para>
|
|
<para>
|
|
This database feature is experimental and will be likely
|
|
improved, for instance to add an address / prefix index (currently
|
|
the only index is the timestamp). No specific tools is provided
|
|
to operate the database but standard tools are applicable,
|
|
for instance to dump the logs table from a CQL database:
|
|
<screen>
|
|
$ <userinput>echo 'SELECT dateOf(timeuuid), log FROM logs;' | cqlsh -k <replaceable>database-name</replaceable></userinput>
|
|
|
|
system.dateof(timeuuid) | log
|
|
---------------------------------+---------------------------------------
|
|
2018-01-06 01:02:03.227000+0000 | Address: 192.2.1.100 has been renewed ...
|
|
...
|
|
(12 rows)
|
|
$
|
|
</screen>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="flex-id">
|
|
<title>flex_id: Flexible Identifiers for Host Reservations</title>
|
|
<para>
|
|
This section describes a hook application dedicated to generate
|
|
flexible identifiers for host reservation. Kea software provides a way
|
|
to handle host reservations that include addresses, prefixes, options,
|
|
client classes and other features. The reservation can be based on
|
|
hardware address, DUID, circuit-id or client-id in DHCPv4 and using
|
|
hardware address or DUID in DHCPv6. However, there are sometimes
|
|
scenarios where the reservation is more complex, e.g. uses other
|
|
options that mentioned above, uses part of specific options or perhaps
|
|
even a combination of several options and fields to uniquely identify
|
|
a client. Those scenarios are addressed by the Flexible Identifiers
|
|
hook application.</para>
|
|
|
|
<para>Currently this library is only available to ISC customers with a
|
|
support contract.</para>
|
|
|
|
<para>The library allows for defining an expression, using notation
|
|
initially used for client classification only. See <xref linkend="classification-using-expressions"/> for detailed description
|
|
of the syntax available. One notable difference is that for client
|
|
classification the expression currently has to evaluate to either true
|
|
or false, while the flexible identifier expression is expected to
|
|
evaluate to a string that will be used as identifier. It is a valid case
|
|
for the expression to evaluate to empty string (e.g. in cases where a
|
|
client does not sent specific options). This expression is then
|
|
evaluated for each incoming packet. This evaluation generates an
|
|
identifier that is used to identify the client. In particular, there may
|
|
be host reservations that are tied to specific values of the flexible
|
|
identifier.</para>
|
|
|
|
<para>
|
|
The library can be loaded in similar way as other hook libraries. It
|
|
takes a mandatory parameter identifier-expression and optional
|
|
boolean parameter replace-client-id:
|
|
<screen>
|
|
"Dhcp6": { <userinput>
|
|
"hooks-libraries": [
|
|
{
|
|
"library": "/path/libdhcp_flex_id.so",
|
|
"parameters": {
|
|
"identifier-expression": "<userinput>expression</userinput>",
|
|
"replace-client-id": "<userinput>false</userinput>"
|
|
}
|
|
},
|
|
...
|
|
] </userinput>
|
|
}
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
The flexible identifier library supports both DHCPv4 and DHCPv6.
|
|
</para>
|
|
|
|
<para>
|
|
EXAMPLE: Let's consider a case of an IPv6 network that has an
|
|
independent interface for each of the connected customers. Customers
|
|
are able to plug in whatever device they want, so any type of
|
|
identifier (e.g. a client-id) is unreliable. Therefore the operator
|
|
may decide to use an option inserted by a relay agent to differentiate
|
|
between clients. In this particular deployment, the operator verified
|
|
that the interface-id is unique for each customer facing
|
|
interface. Therefore it is suitable for usage as reservation. However,
|
|
only the first 6 bytes of the interface-id are interesting, because
|
|
remaining bytes are either randomly changed or not unique between
|
|
devices. Therefore the customer decided to use first 6 bytes of the
|
|
interface-id option inserted by the relay agent. After adding "flex-id"
|
|
host-reservation-identifiers goal can be achieved by using the
|
|
following configuration:
|
|
<screen>
|
|
"Dhcp6": {
|
|
"subnet6": [{ ..., // subnet definition starts here
|
|
"reservations": [
|
|
<userinput>"flex-id": "'port1234'"</userinput>, // value of the first 8 bytes of the interface-id
|
|
"ip-addresses": [ "2001:db8::1" ]
|
|
],
|
|
}], // end of subnet definitions
|
|
"host-reservation-identifiers": ["duid", "flex-id"], // add "flex-id" to reservation identifiers
|
|
"hooks-libraries": [
|
|
{
|
|
"library": "/path/libdhcp_flex_id.so",
|
|
"parameters": {
|
|
"identifier-expression": "<userinput>substring(relay6[0].option[18].hex,0,8)</userinput>"
|
|
}
|
|
},
|
|
...
|
|
]
|
|
}
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
NOTE: Care should be taken when adjusting the expression. If the
|
|
expression changes, then all the flex-id values may change, possibly
|
|
rendering all reservations based on flex-id unusable until they're
|
|
manually updated. Therefore it is strongly recommended to start with
|
|
the expression and a handful reservations, adjust the expression as
|
|
needed and only after it was confirmed the expression does exactly
|
|
what is expected out of it go forward with host reservations on any
|
|
broader scale.
|
|
</para>
|
|
|
|
<para>
|
|
flex-id values in host reservations can be specified in two
|
|
ways. First, they can be expressed as hex string, e.g. bar string
|
|
can be represented as 626174. Alternatively, it can be expressed
|
|
as quoted value (using double and single quotes), e.g. "'bar'".
|
|
The former is more convenient for printable characters, while hex
|
|
string values are more convenient for non-printable characters.
|
|
</para>
|
|
<screen>
|
|
"Dhcp6": {
|
|
"subnet6": [{ ..., // subnet definition starts here
|
|
"reservations": [
|
|
<userinput>"flex-id": "01:02:03:04:05:06"</userinput>, // value of the first 8 bytes of the interface-id
|
|
"ip-addresses": [ "2001:db8::1" ]
|
|
],
|
|
}], // end of subnet definitions
|
|
"host-reservation-identifiers": ["duid", "flex-id"], // add "flex-id" to reservation identifiers
|
|
"hooks-libraries": [
|
|
{
|
|
"library": "/path/libdhcp_flex_id.so",
|
|
"parameters": {
|
|
"identifier-expression": "<userinput>vendor[4491].option[1026].hex</userinput>"
|
|
}
|
|
},
|
|
...
|
|
]
|
|
}
|
|
</screen>
|
|
|
|
<para>
|
|
When "replace-client-id" is set to false (which is the default setting),
|
|
the flex-id hook library uses evaluated flexible identifier solely for
|
|
identifying host reservations, i.e. searching for reservations within a
|
|
database. This is a functional equivalent of other identifiers,
|
|
similar to hardware address or circuit-id. However,
|
|
this mode of operation has an implication that if a client device is
|
|
replaced, it may cause a conflict between an existing lease (allocated
|
|
for old device) and the new lease being allocated for the new device. The
|
|
conflict arises because the same flexible identifier is computed for the
|
|
replaced device and the server will try to allocate the same lease. The
|
|
mismatch between client identifiers sent by new device and old device causes
|
|
the server to refuse this new allocation until the old lease expires.
|
|
A manifestation of this problem is dependant on specific expression
|
|
used as flexible identifier and is likely to appear if you only use options
|
|
and other parameters that are identifying where the device is
|
|
connected (e.g. circuit-id), rather than the device identification
|
|
itself (e.g. MAC address).
|
|
</para>
|
|
|
|
<para>
|
|
The flex-id library offers a way to overcome the problem with lease conflicts
|
|
by dynamically replacing client identifier (or DUID in DHCPv6 case) with a
|
|
value derived from flexible identifier. The server processes the client's
|
|
query as if flexible identifier was sent in the client identifier (or DUID)
|
|
option. This guarantees that returning client (for which the same flexible
|
|
identifier is evaluated) will be assigned the same lease despite the client
|
|
identifier and/or MAC address change.
|
|
</para>
|
|
|
|
<para>
|
|
The following is a stub configuration that enables this behavior:
|
|
<screen>
|
|
"Dhcp4": { <userinput>
|
|
"hooks-libraries": [
|
|
{
|
|
"library": "/path/libdhcp_flex_id.so",
|
|
"parameters": {
|
|
"identifier-expression": "<userinput>expression</userinput>",
|
|
"replace-client-id": "<userinput>true</userinput>"
|
|
}
|
|
},
|
|
...
|
|
] </userinput>
|
|
}
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
In the DHCPv4 case, the value derived from the flexible identifier is formed
|
|
by prepending 1 byte with a value of zero to flexible identifier. In the IPv6
|
|
case, it is formed by prepanding two zero bytes before the flexible identifier.
|
|
</para>
|
|
|
|
<para>
|
|
Note that for this mechanism to take effect, the DHCPv4 server must be configured
|
|
to respect the client identifier option value during lease allocation, i.e.
|
|
"match-client-id" must be set to true. See
|
|
<xref linkend="dhcp4-match-client-id"/> for details. No additional settings
|
|
are required for DHCPv6.
|
|
</para>
|
|
<para>
|
|
If "replace-client-id" option is set to true, the value of "echo-client-id"
|
|
parameter (that governs whether to send back a client-id option or
|
|
not) is ignored.
|
|
</para>
|
|
|
|
<para>
|
|
The <xref linkend="lease-cmds"/> section describes commands used to retrieve,
|
|
update and delete leases using various identifiers, e.g. "hw-address",
|
|
"client-id". The lease_cmds library doesn't natively support querying for
|
|
leases by flexible identifier. However, when "replace-client-id" is set to
|
|
true, it makes it possible to query for leases using a value derived from
|
|
the flexible identifier. In the DHCPv4 case, the query will look similar to this:
|
|
<screen>
|
|
{
|
|
"command": "lease4-get",
|
|
"arguments": {
|
|
"identifier-type": "client-id",
|
|
"identifier": "00:<userinput>54:64:45:66</userinput>",
|
|
"subnet-id": 44
|
|
}
|
|
}
|
|
</screen>
|
|
|
|
where hexadecimal value of "54:64:45:66" is a flexible identifier computed
|
|
for the client.
|
|
</para>
|
|
|
|
<para>
|
|
In the DHCPv6 case, the corresponding query will look similar to this:
|
|
<screen>
|
|
{
|
|
"command": "lease6-get",
|
|
"arguments": {
|
|
"identifier-type": "duid",
|
|
"identifier": "00:00:<userinput>54:64:45:66</userinput>",
|
|
"subnet-id": 10
|
|
}
|
|
}</screen>
|
|
|
|
</para>
|
|
</section>
|
|
|
|
<section xml:id="host-cmds">
|
|
<title>host_cmds: Host Commands</title>
|
|
<para>
|
|
This section describes a hook application that offers a number of new
|
|
commands used to query and manipulate host reservations. Kea provides
|
|
a way to store host reservations in a database. In many larger
|
|
deployments it is useful to be able to manage that information while
|
|
the server is running. This library provides management commands for
|
|
adding, querying and deleting host reservations in a safe way without
|
|
restarting the server. In particular, it validates the parameters, so
|
|
an attempt to insert incorrect data e.g. add a host with conflicting
|
|
identifier in the same subnet will be rejected. Those commands are
|
|
exposed via command channel (JSON over unix sockets) and Control Agent
|
|
(JSON over RESTful interface). Additional commands and capabilities
|
|
related to host reservations will be added in the future.
|
|
</para>
|
|
|
|
<para>Currently this library is only available to ISC customers with a
|
|
support contract.</para>
|
|
|
|
<para>
|
|
Currently three commands are supported: reservation-add (which adds
|
|
new host reservation), reservation-get (which returns existing
|
|
reservation if specified criteria are matched) and reservation-del
|
|
(which attempts to delete a reservation matching specified
|
|
criteria). To use commands that change the reservation information
|
|
(currently these are reservation-add and reservation-del, but this
|
|
rule applies to other commands that may be implemented in the future),
|
|
hosts database must be specified (see hosts-databases description in
|
|
<xref linkend="hosts-databases-configuration4"/> and <xref linkend="hosts-databases-configuration6"/>) and it must not operate in
|
|
read-only mode. If the hosts-databases are not specified or are running
|
|
in read-only mode, the host_cmds library will load, but any attempts
|
|
to use reservation-add or reservation-del will fail.
|
|
</para>
|
|
|
|
<para>
|
|
Additional host reservation commands are planned in the future. For
|
|
a description of envisaged commands, see
|
|
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://kea.isc.org/wiki/ControlAPIRequirements">Control API
|
|
Requirements </link> document.</para>
|
|
|
|
<para>
|
|
All commands are using JSON syntax. They can be issued either using
|
|
control channel (see <xref linkend="ctrl-channel"/>) or via Control
|
|
Agent (see <xref linkend="kea-ctrl-agent"/>).
|
|
</para>
|
|
|
|
<para>
|
|
The library can be loaded in similar way as other hook libraries. It
|
|
does not take any parameters. It supports both DHCPv4 and DHCPv6
|
|
servers.
|
|
<screen>
|
|
"Dhcp6": { <userinput>
|
|
"hooks-libraries": [
|
|
{
|
|
"library": "/path/libdhcp_host_cmds.so"
|
|
}
|
|
...
|
|
] </userinput>
|
|
}
|
|
</screen>
|
|
</para>
|
|
|
|
<section>
|
|
<title>reservation-add command</title>
|
|
<para>
|
|
<command>reservation-add</command> allows for the insertion of a new host. It
|
|
takes a set of arguments that vary depending on the nature of the host
|
|
reservation. Any parameters allowed in the configuration file that
|
|
pertain to host reservation are permitted here. For details regarding
|
|
IPv4 reservations, see <xref linkend="host-reservation-v4"/> and <xref linkend="host-reservation-v6"/>. There is one notable addition. A
|
|
<command>subnet-id</command> must be specified. This parameter is
|
|
mandatory, because reservations specified in the configuration file
|
|
are always defined within a subnet, so the subnet they belong to is
|
|
clear. This is not the case with reservation-add, therefore the
|
|
subnet-id must be specified explicitly. An example command can be as
|
|
simple as:
|
|
<screen>{
|
|
"command": "reservation-add",
|
|
"arguments": {
|
|
<userinput>"reservation": {
|
|
"subnet-id": 1,
|
|
"hw-address": "1a:1b:1c:1d:1e:1f",
|
|
"ip-address": "192.0.2.202"
|
|
}</userinput>
|
|
}
|
|
}</screen> but can also take many more parameters, for example:
|
|
|
|
<screen>
|
|
{
|
|
"command": "reservation-add",
|
|
"arguments": {
|
|
<userinput>"reservation":
|
|
{
|
|
"subnet-id":1,
|
|
"client-id": "01:0a:0b:0c:0d:0e:0f",
|
|
"ip-address": "192.0.2.205",
|
|
"next-server": "192.0.2.1",
|
|
"server-hostname": "hal9000",
|
|
"boot-file-name": "/dev/null",
|
|
"option-data": [
|
|
{
|
|
"name": "domain-name-servers",
|
|
"data": "10.1.1.202,10.1.1.203"
|
|
}
|
|
],
|
|
"client-classes": [ "special_snowflake", "office" ]
|
|
}</userinput>
|
|
}
|
|
}</screen>
|
|
|
|
Here is an example of complex IPv6 reservation:
|
|
<screen>
|
|
{
|
|
"command": "reservation-add",
|
|
"arguments": {
|
|
<userinput>"reservation":
|
|
{
|
|
"subnet-id":1,
|
|
"duid": "01:02:03:04:05:06:07:08:09:0A",
|
|
"ip-addresses": [ "2001:db8:1:cafe::1" ],
|
|
"prefixes": [ "2001:db8:2:abcd::/64" ],
|
|
"hostname": "foo.example.com",
|
|
"option-data": [
|
|
{
|
|
"name": "vendor-opts",
|
|
"data": "4491"
|
|
},
|
|
{
|
|
"name": "tftp-servers",
|
|
"space": "vendor-4491",
|
|
"data": "3000:1::234"
|
|
}
|
|
]
|
|
}</userinput>
|
|
}
|
|
}</screen>
|
|
</para>
|
|
|
|
<para>
|
|
The command returns a status that indicates either a success (result
|
|
0) or a failure (result 1). Failed command always includes text
|
|
parameter that explains the cause of failure. Example results:
|
|
<screen>{ "result": 0, "text": "Host added." }</screen> Example failure:
|
|
<screen>{ "result": 1, "text": "Mandatory 'subnet-id' parameter missing." }</screen>
|
|
</para>
|
|
|
|
<para>
|
|
As <command>reservation-add</command> is expected to store the host,
|
|
hosts-databases parameter must be specified in your configuration and
|
|
databases must not run in read-only mode. In the future versions
|
|
it will be possible to modify the reservations read from a
|
|
configuration file. Please contact ISC if you are interested in this
|
|
functionality.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>reservation-get command</title>
|
|
<para><command>reservation-get</command> can be used to query the host
|
|
database and retrieve existing reservations. There are two types of
|
|
parameters this command supports: (subnet-id, address) or (subnet-id,
|
|
identifier-type, identifier). The first type of query is used when the
|
|
address (either IPv4 or IPv6) is known, but the details of the
|
|
reservation aren't. One common use case of this type of query is to
|
|
find out whether a given address is reserved or not. The second query
|
|
uses identifiers. For maximum flexibility, Kea stores the host
|
|
identifying information as a pair of values: type and the actual
|
|
identifier. Currently supported identifiers are "hw-address", "duid",
|
|
"circuit-id", "client-id" and "flex-id", but additional types may be
|
|
added in the future. If any new identifier types are defined in the
|
|
future, reservation-get command will support them
|
|
automatically.</para>
|
|
|
|
<para>
|
|
An example command for getting a host reservation by (subnet-id,
|
|
address) pair looks as follows:
|
|
<screen>
|
|
{
|
|
"command": "reservation-get",
|
|
"arguments": {
|
|
"subnet-id": 1,
|
|
"ip-address": "192.0.2.202"
|
|
}
|
|
}</screen>
|
|
|
|
An example query by (subnet-id, identifier-type, identifier) looks as follows:
|
|
<screen>
|
|
{
|
|
"command": "reservation-get",
|
|
"arguments":
|
|
"subnet-id": 4,
|
|
"identifier-type": "hw-address",
|
|
"identifier": "01:02:03:04:05:06"
|
|
}
|
|
}</screen>
|
|
|
|
</para>
|
|
<para><command>reservation-get</command> typically returns result 0
|
|
when the query was conducted properly. In particular, 0 is returned
|
|
when the host was not found. If the query was successful a number
|
|
of host parameters will be returned. An example of a query that
|
|
did not find the host looks as follows:
|
|
<screen>{ "result": 0, "text": "Host not found." }</screen>
|
|
|
|
An example result returned when the host was found:
|
|
<screen>{
|
|
"arguments": {
|
|
"boot-file-name": "bootfile.efi",
|
|
"client-classes": [
|
|
|
|
],
|
|
"hostname": "somehost.example.org",
|
|
"hw-address": "01:02:03:04:05:06",
|
|
"ip-address": "192.0.2.100",
|
|
"next-server": "192.0.0.2",
|
|
"option-data": [
|
|
|
|
],
|
|
"server-hostname": "server-hostname.example.org"
|
|
},
|
|
"result": 0,
|
|
"text": "Host found."
|
|
}</screen>
|
|
|
|
An example result returned when the query was malformed:<screen>
|
|
{ "result": 1, "text": "No 'ip-address' provided and 'identifier-type'
|
|
is either missing or not a string." }</screen>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>reservation-del command</title>
|
|
<para><command>reservation-del</command> can be used to delete a
|
|
reservation from the host database. There are two types of parameters
|
|
this command supports: (subnet-id, address) or (subnet-id,
|
|
identifier-type, identifier). The first type of query is used when the
|
|
address (either IPv4 or IPv6) is known, but the details of the
|
|
reservation aren't. One common use case of this type of query is to
|
|
remove a reservation (e.g. you want a specific address to no longer be
|
|
reserved). The second query uses identifiers. For maximum flexibility,
|
|
Kea stores the host identifying information as a pair of values: type
|
|
and the actual identifier. Currently supported identifiers are
|
|
"hw-address", "duid", "circuit-id", "client-id" and "flex-id", but
|
|
additional types may be added in the future. If any new identifier
|
|
types are defined in the future, reservation-get command will support
|
|
them automatically.</para>
|
|
|
|
<para>
|
|
An example command for deleting a host reservation by (subnet-id,
|
|
address) pair looks as follows:
|
|
<screen>
|
|
{
|
|
"command": "reservation-del",
|
|
"arguments": {
|
|
"subnet-id": 1,
|
|
"ip-address": "192.0.2.202"
|
|
}
|
|
}</screen>
|
|
|
|
An example deletion by (subnet-id, identifier-type, identifier) looks as follows:
|
|
<screen>
|
|
{
|
|
"command": "reservation-del",
|
|
"arguments":
|
|
"subnet-id": 4,
|
|
"identifier-type": "hw-address",
|
|
"identifier": "01:02:03:04:05:06"
|
|
}
|
|
}</screen>
|
|
</para>
|
|
<para>
|
|
<command>reservation-del</command> returns result 0 when the host
|
|
deletion was successful or 1 if it was not. A descriptive text is
|
|
provided in case of error. Example results look as follows:
|
|
<screen>
|
|
{
|
|
"result": 1,
|
|
"text": "Host not deleted (not found)."
|
|
}</screen>
|
|
|
|
<screen>
|
|
{
|
|
"result": 0,
|
|
"text": "Host deleted."
|
|
}</screen>
|
|
|
|
<screen>
|
|
{
|
|
"result": 1,
|
|
"text": "Unable to delete a host because there is no hosts-database
|
|
configured."
|
|
}</screen>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<!-- ================================================================= -->
|
|
<!-- === lease_cmds ================================================== -->
|
|
<!-- ================================================================= -->
|
|
|
|
<section xml:id="lease-cmds">
|
|
<title>lease_cmds: Lease Commands</title>
|
|
<para>
|
|
This section describes the hook library that offers a number of new
|
|
commands used to manage leases. Kea provides a way to store lease
|
|
information in several backends (memfile, MySQL, PostgreSQL and
|
|
Cassandra). This library provides a unified interface that can
|
|
manipulate leases in an unified, safe way. In particular, it allows
|
|
things previously impossible: manipulate leases in memfile while Kea
|
|
is running, sanity check changes, check lease existence and remove all
|
|
leases belonging to specific subnet. It can also catch more obscure
|
|
errors, like adding a lease with subnet-id that does not exist in the
|
|
configuration or configuring a lease to use an address that is outside
|
|
of the subnet to which it is supposed to belong.
|
|
</para>
|
|
|
|
<para>There are many use cases when an administrative command may be
|
|
useful: during migration between servers (possibly even between
|
|
different vendors), when a certain network is being retired, when a
|
|
device has been disconnected and the sysadmin knows for sure that it
|
|
will not be coming back. The "get" queries may be useful for automating
|
|
certain management and monitoring tasks. They can also act as
|
|
preparatory steps for lease updates and removals.</para>
|
|
|
|
<para>
|
|
This library provides the following commands:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><command>lease4-add</command> - adds new IPv4 lease;</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>lease6-add</command> - adds new IPv6 lease;</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>lease4-get</command> - checks if an IPv4 lease with
|
|
the specified parameters exists and returns it if it does;</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>lease6-get</command> - checks if an IPv6 lease with
|
|
the specified parameters exists and returns it if it does;</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>lease4-get-all</command> - returns all IPv4 leases
|
|
or IPv4 leases for specified subnets;</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>lease6-get-all</command> - returns all IPv6 leases
|
|
or IPv6 leases for specified subnets;</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>lease4-del</command> - attempts to delete an IPv4
|
|
lease with the specified parameters;</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>lease6-del</command> - attempts to delete an IPv6
|
|
lease with the specified parameters;</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>lease4-update</command> - updates an IPv4 lease;</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>lease6-update</command> - updates an IPv6 lease;</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>lease4-wipe</command> - removes all leases from a
|
|
specific IPv4 subnet;</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>lease6-wipe</command> - removes all leases from a
|
|
specific IPv6 subnet;</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
<para>Lease commands library is part of the open source code and is
|
|
available to every Kea user.</para>
|
|
|
|
<para>
|
|
All commands are using JSON syntax. They can be issued either using
|
|
control channel (see <xref linkend="ctrl-channel"/>) or via Control
|
|
Agent (see <xref linkend="kea-ctrl-agent"/>).
|
|
</para>
|
|
|
|
<para>
|
|
The library can be loaded in the same way as other hook libraries. It
|
|
does not take any parameters. It supports both DHCPv4 and DHCPv6
|
|
servers.
|
|
<screen>
|
|
"Dhcp6": { <userinput>
|
|
"hooks-libraries": [
|
|
{
|
|
"library": "/path/libdhcp_lease_cmds.so"
|
|
}
|
|
...
|
|
] </userinput>
|
|
}
|
|
</screen>
|
|
</para>
|
|
|
|
<section>
|
|
<title>lease4-add, lease6-add commands</title>
|
|
<para>
|
|
<command>lease4-add</command> and <command>lease6-add</command>
|
|
commands allow for the creation of a new lease. Typically Kea creates a lease
|
|
on its own, when it first sees a new device. However, sometimes it may
|
|
be convenient to create the lease administratively. The
|
|
<command>lease4-add</command> command requires at least three
|
|
parameters: an IPv4 address, a subnet-id and an identifier: hardware
|
|
(MAC) address. The simplest successful call might look as follows:
|
|
<screen>
|
|
{
|
|
"command": "lease4-add",
|
|
"arguments": {
|
|
"subnet-id": 44,
|
|
"ip-address": "192.0.2.202",
|
|
"hw-address": "1a:1b:1c:1d:1e:1f"
|
|
}
|
|
}
|
|
</screen>
|
|
</para>
|
|
|
|
<para><command>lease6-add</command> command requires four
|
|
parameters: an IPv6 address, a subnet-id, and IAID value
|
|
(identity association identifier, a value sent by clients) and
|
|
a DUID:
|
|
<screen>
|
|
{
|
|
"command": "lease6-add",
|
|
"arguments": {
|
|
"subnet-id": 66,
|
|
"ip-address": "2001:db8::3",
|
|
"duid": "1a:1b:1c:1d:1e:1f:20:21:22:23:24",
|
|
"iaid": 1234
|
|
}
|
|
}</screen>
|
|
|
|
<command>lease6-add</command> can be also used to add leases for IPv6
|
|
prefixes. In this case there are two parameters that must be
|
|
specified: type (set to value of "IA_PD") and a prefix
|
|
length. The actual prefix is set using ip-address field. For example,
|
|
to configure a lease for prefix 2001:db8:abcd::/48, the following
|
|
command can be used:
|
|
|
|
<screen>
|
|
{
|
|
"command": "lease6-add",
|
|
"arguments": {
|
|
"subnet-id": 66,
|
|
"type": "IA_PD",
|
|
"ip-address": "2001:db8:abcd::",
|
|
"prefix-len": 48,
|
|
"duid": "1a:1b:1c:1d:1e:1f:20:21:22:23:24",
|
|
"iaid": 1234
|
|
}
|
|
}</screen>
|
|
|
|
The commands can take a number of additional optional parameters:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><command>valid-lft</command> - specifies the lifetime of the
|
|
lease, expressed in seconds. If not specified, the value
|
|
configured in the subnet related to specified subnet-id is
|
|
used.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>expire</command> - timestamp of the lease
|
|
expiration time, expressed in unix format (seconds since 1 Jan
|
|
1970). If not specified, the default value is now + valid
|
|
lifetime.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>fqdn-fwd</command> - specifies whether the lease
|
|
should be marked as if forward DNS update was conducted. Note this
|
|
only affects the lease parameter and the actual DNS update will
|
|
not be conducted at the lease insertion time. If configured, a DNS
|
|
update to remove the A or AAAA records will be conducted when the
|
|
lease is removed due to expiration or being released by a
|
|
client. If not specified, the default value is false. Hostname
|
|
parameter must be specified in fqdn-fwd is set to true.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>fqdn-rev</command> - specifies whether the lease
|
|
should be marked as if reverse DNS update was conducted. Note this
|
|
only affects the lease parameter and the actual DNS update will
|
|
not be conducted at the lease insertion time. If configured, a DNS
|
|
update to remove the PTR record will be conducted when the lease
|
|
is removed due to expiration or being released by a client. If not
|
|
specified, the default value is false. Hostname parameter must be
|
|
specified in fqdn-fwd is set to true.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>hostname</command> - specifies the hostname to be
|
|
associated with this lease. Its value must be non-empty if either
|
|
fqdn-fwd or fwdn-rev are set to true. If not specified, the
|
|
default value is an empty string.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>hw-address</command> - hardware (MAC) address can
|
|
be optionally specified for IPv6 lease. It is mandatory parameter
|
|
for IPv4 lease.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>client-id</command> - client identifier is an
|
|
optional parameter that can be specified for IPv4 lease.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><command>preferred-lft</command> - Preferred lifetime is an
|
|
optional parameter for IPv6 leases. If not specified, the value
|
|
configured for the subnet corresponding to the specified subnet-id
|
|
is used. This parameter is not used in IPv4.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>Here's an example of more complex lease addition:
|
|
|
|
<screen>
|
|
{
|
|
"command": "lease6-add",
|
|
"arguments": {
|
|
"subnet-id": 66,
|
|
"ip-address": "2001:db8::3",
|
|
"duid": "01:02:03:04:05:06:07:08",
|
|
"iaid": 1234,
|
|
"hw-address": "1a:1b:1c:1d:1e:1f",
|
|
"preferred-lft": 500,
|
|
"valid-lft": 1000,
|
|
"expire": 12345678,
|
|
"fqdn-fwd": true,
|
|
"fqdn-rev": true,
|
|
"hostname": "urania.example.org"
|
|
}
|
|
}
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
The command returns a status that indicates either a success (result
|
|
0) or a failure (result 1). Failed command always includes text
|
|
parameter that explains the cause of failure. Example results:
|
|
<screen>{ "result": 0, "text": "Lease added." }</screen> Example failure:
|
|
<screen>{ "result": 1, "text": "missing parameter 'ip-address' (<string>:3:19)" }</screen>
|
|
</para>
|
|
|
|
|
|
<section>
|
|
<title>lease4-get, lease6-get commands</title>
|
|
<para><command>lease4-get</command> or <command>lease6-get</command>
|
|
can be used to query the lease database and retrieve existing
|
|
leases. There are two types of parameters the
|
|
<command>lease4-get</command> supports: (address) or (subnet-id,
|
|
identifier-type, identifier). There are two types for
|
|
<command>lease6-get</command>: (address,type) or (subnet-id,
|
|
identifier-type, identifier, IAID, type). The first type of query is
|
|
used when the address (either IPv4 or IPv6) is known, but the details
|
|
of the lease aren't. One common use case of this type of query is to
|
|
find out whether a given address is being used or not. The second
|
|
query uses identifiers. Currently supported identifiers for leases are:
|
|
"hw-address" (IPv4 only), "client-id" (IPv4 only) and "duid" (IPv6 only).
|
|
</para>
|
|
|
|
<para>
|
|
An example <command>lease4-get</command> command for getting a lease
|
|
by an IPv4 address looks as follows:
|
|
<screen>
|
|
{
|
|
"command": "lease4-get",
|
|
"arguments": {
|
|
"ip-address": "192.0.2.1"
|
|
}
|
|
}
|
|
</screen>
|
|
</para>
|
|
|
|
<para>An example of the <command>lease6-get</command> query
|
|
looks as follows:
|
|
<screen>
|
|
{
|
|
"command": "lease6-get",
|
|
"arguments": {
|
|
"ip-address": "2001:db8:1234:ab::",
|
|
"type": "IA_PD"
|
|
}
|
|
}</screen>
|
|
</para>
|
|
|
|
<para>An example query by "hw-address" for IPv4 lease looks
|
|
as follows:
|
|
<screen>
|
|
{
|
|
"command": "lease4-get",
|
|
"arguments": {
|
|
"identifier-type": "hw-address",
|
|
"identifier": "08:08:08:08:08:08",
|
|
"subnet-id": 44
|
|
}
|
|
}</screen>
|
|
|
|
</para>
|
|
|
|
<para>An example query by "client-id" for IPv4 lease looks
|
|
as follows:
|
|
<screen>
|
|
{
|
|
"command": "lease4-get",
|
|
"arguments": {
|
|
"identifier-type": "client-id",
|
|
"identifier": "01:01:02:03:04:05:06",
|
|
"subnet-id": 44
|
|
}
|
|
}</screen>
|
|
|
|
</para>
|
|
|
|
<para>An example query by (subnet-id, identifier-type,
|
|
identifier, iaid, type) for IPv6 lease looks as follows:
|
|
<screen>
|
|
{
|
|
"command": "lease4-get",
|
|
"arguments": {
|
|
"identifier-type": "duid",
|
|
"identifier": "08:08:08:08:08:08",
|
|
"iaid": 1234567,
|
|
"type": "IA_NA",
|
|
"subnet-id": 44
|
|
}
|
|
}</screen>
|
|
The type is an optional parameter. Supported values are: IA_NA
|
|
(non-temporary address) and IA_PD (IPv6 prefix) are supported.
|
|
If not specified, IA_NA is assumed.
|
|
</para>
|
|
|
|
<para><command>leaseX-get</command> returns a result that indicates a
|
|
result of the operation and lease details, if found. It has one of the
|
|
following values: 0 (success), 1 (error) or 2 (empty). The empty
|
|
result means that a query has been completed properly, but the object
|
|
(a lease in this case) has not been found. The lease parameters, if
|
|
found, are returned as arguments.
|
|
</para>
|
|
|
|
<para>
|
|
An example result returned when the host was found:
|
|
<screen>{
|
|
"arguments": {
|
|
"client-id": "42:42:42:42:42:42:42:42",
|
|
"cltt": 12345678,
|
|
"fqdn-fwd": false,
|
|
"fqdn-rev": true,
|
|
"hostname": "myhost.example.com.",
|
|
"hw-address": "08:08:08:08:08:08",
|
|
"ip-address": "192.0.2.1",
|
|
"state": 0,
|
|
"subnet-id": 44,
|
|
"valid-lft": 3600
|
|
},
|
|
"result": 0,
|
|
"text": "IPv4 lease found."
|
|
}</screen>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>lease4-get-all, lease6-get-all commands</title>
|
|
<para><command>lease4-get-all</command> and
|
|
<command>lease6-get-all</command> are used to retrieve all
|
|
IPv4 or IPv6 leases or all leases for the specified set of
|
|
subnets. All leases are returned when there are no arguments
|
|
specified with the command as in the following example:
|
|
<screen>
|
|
{
|
|
"command": "lease4-get-all"
|
|
}
|
|
</screen>
|
|
</para>
|
|
|
|
<para>If the arguments are provided, it is expected that they contain
|
|
"subnets" parameter, being a list of subnet identifiers for which the
|
|
leases should be returned. For example, in order to retrieve all IPv6
|
|
leases belonging to the subnets with identifiers 1, 2, 3 and 4:
|
|
<screen>
|
|
{
|
|
"command": "lease6-get-all",
|
|
"arguments": {
|
|
"subnets": [ 1, 2, 3, 4 ]
|
|
}
|
|
}
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
The returned response contains a detailed list of leases in the
|
|
following format:
|
|
<screen>{
|
|
"arguments": {
|
|
"leases": [
|
|
{
|
|
"cltt": 12345678,
|
|
"duid": "42:42:42:42:42:42:42:42",
|
|
"fqdn-fwd": false,
|
|
"fqdn-rev": true,
|
|
"hostname": "myhost.example.com.",
|
|
"hw-address": "08:08:08:08:08:08",
|
|
"iaid": 1,
|
|
"ip-address": "2001:db8:2::1",
|
|
"preferred-lft": 500,
|
|
"state": 0,
|
|
"subnet-id": 44,
|
|
"type": "IA_NA",
|
|
"valid-lft": 3600
|
|
},
|
|
{
|
|
"cltt": 12345678,
|
|
"duid": "21:21:21:21:21:21:21:21",
|
|
"fqdn-fwd": false,
|
|
"fqdn-rev": true,
|
|
"hostname": "",
|
|
"iaid": 1,
|
|
"ip-address": "2001:db8:0:0:2::",
|
|
"preferred-lft": 500,
|
|
"prefix-len": 80,
|
|
"state": 0,
|
|
"subnet-id": 44,
|
|
"type": "IA_PD",
|
|
"valid-lft": 3600
|
|
}
|
|
]
|
|
},
|
|
"result": 0,
|
|
"text": "2 IPv6 lease(s) found."
|
|
}</screen>
|
|
</para>
|
|
|
|
<warning>
|
|
<para>The <command>lease4-get-command</command> and
|
|
<command>lease6-get-command</command> may result in very
|
|
large responses. This may have negative impact on the DHCP server
|
|
responsiveness while the response is generated and transmitted
|
|
over the control channel, as the server imposes no restriction
|
|
on the number of leases returned as a result of this command.
|
|
</para>
|
|
</warning>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>lease4-del, lease6-del commands</title>
|
|
<para><command>leaseX-del</command> can be used to delete a lease from
|
|
the lease database. There are two types of parameters this command
|
|
supports, similar to leaseX-get commands: (address) for both v4 and
|
|
v6, (subnet-id, identifier-type, identifier) for v4 and (subnet-id,
|
|
identifier-type, identifier, type, IAID) for v6. The first type of
|
|
query is used when the address (either IPv4 or IPv6) is known, but the
|
|
details of the lease are not. One common use case of this type of query
|
|
is to remove a lease (e.g. you want a specific address to no longer be
|
|
used, no matter who may use it). The second query uses
|
|
identifiers. For maximum flexibility, this interface uses identifiers
|
|
as a pair of values: type and the actual identifier. Currently
|
|
supported identifiers are "hw-address" (IPv4 only), "client-id"
|
|
(IPv4 only) and "duid" (IPv6 only), but additional types may be added
|
|
in the future. </para>
|
|
|
|
<para>
|
|
An example command for deleting a host reservation by address looks
|
|
as follows:
|
|
<screen>
|
|
{
|
|
"command": "lease4-del",
|
|
"arguments": {
|
|
"ip-address": "192.0.2.202"
|
|
}
|
|
}</screen>
|
|
|
|
An example IPv4 lease deletion by "hw-address" looks as follows:
|
|
|
|
<screen>{
|
|
"command": "lease4-del",
|
|
"arguments": {
|
|
"identifier": "08:08:08:08:08:08",
|
|
"identifier-type": "hw-address",
|
|
"subnet-id": 44
|
|
}
|
|
}</screen>
|
|
</para>
|
|
|
|
<para><command>leaseX-del</command> returns a result that
|
|
indicates a outcome of the operation. It has one of the
|
|
following values: 0 (success), 1 (error) or 3 (empty). The
|
|
empty result means that a query has been completed properly,
|
|
but the object (a lease in this case) has not been found.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>lease4-update, lease6-update commands</title>
|
|
<para><command>lease4-update</command> and
|
|
<command>lease6-update</command> commands can be used to update
|
|
existing leases. Since all lease database backends are indexed by IP
|
|
addresses, it is not possible to update an address. All other fields
|
|
may be updated. If an address needs to be changed, please use
|
|
<command>leaseX-del</command> followed by
|
|
<command>leaseX-add</command> commands.</para>
|
|
|
|
<para>The optional boolean parameter "force-create" specifies
|
|
if the lease should be created if it doesn't exist in the database.
|
|
It defaults to false, which indicates that the lease is not created
|
|
if it doesn't exist. In such case, an error is returned as a result
|
|
of trying to update a non-existing lease. If the "force-create" parameter
|
|
is set to true and the updated lease doesn't exist, the new lease is
|
|
created as a result of receiving the <command>leaseX-update</command>.
|
|
</para>
|
|
|
|
<para>
|
|
An example command updating IPv4 lease looks as follows:
|
|
<screen>{
|
|
"command": "lease4-update",
|
|
"arguments": {
|
|
"ip-address": "192.0.2.1",
|
|
"hostname": "newhostname.example.org",
|
|
"hw-address": "1a:1b:1c:1d:1e:1f",
|
|
"subnet-id": 44,
|
|
"force-create": true
|
|
}
|
|
}</screen>
|
|
</para>
|
|
|
|
<para>
|
|
An example command updating IPv6 lease looks as follows:
|
|
<screen>{
|
|
"command": "lease6-update",
|
|
"arguments": {
|
|
"ip-address": "2001:db8::1",
|
|
"duid": "88:88:88:88:88:88:88:88",
|
|
"iaid": 7654321,
|
|
"hostname": "newhostname.example.org",
|
|
"subnet-id": 66,
|
|
"force-create": false
|
|
}
|
|
}</screen>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>lease4-wipe, lease6-wipe commands</title>
|
|
<para><command>lease4-wipe</command> and
|
|
<command>lease6-wipe</command> are designed to remove all
|
|
leases associated with a given subnet. This administrative
|
|
task is expected to be used when existing subnet is being
|
|
retired. Note that the leases are not properly expired,
|
|
there are no DNS updates conducted, no log messages and
|
|
hooks are not called for leases being removed.</para>
|
|
|
|
<para>An example of <command>lease4-wipe</command> looks as follows:
|
|
<screen>{
|
|
"command": "lease4-wipe",
|
|
"arguments": {
|
|
"subnet-id": 44
|
|
}
|
|
}</screen>
|
|
</para>
|
|
|
|
<para>An example of <command>lease6-wipe</command> looks as follows:
|
|
<screen>{
|
|
"command": "lease6-wipe",
|
|
"arguments": {
|
|
"subnet-id": 66
|
|
}
|
|
}</screen>
|
|
</para>
|
|
|
|
<para>The commands return a textual description of the
|
|
number of leases removed and 0 (success) status code if any
|
|
leases were removed and 2 (empty) if there were no
|
|
leases. Status code 1 (error) may be returned in case the
|
|
parameters are incorrect or some other exception is
|
|
encountered.</para>
|
|
|
|
<para>Note: not all backends support this command.</para>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="subnet-cmds">
|
|
<title>subnet_cmds: Subnet Commands</title>
|
|
<para>
|
|
This section describes a hook application that offers a number of new
|
|
commands used to query and manipulate subnet and shared network
|
|
configurations in Kea. This application is very useful in deployments
|
|
with a large number of subnets being managed by the DHCP servers and
|
|
when the subnets are frequently updated. The commands offer
|
|
lightweight approach for manipulating subnets without a need to fully
|
|
reconfigure the server and without affecting existing servers'
|
|
configurations. An ability to manage shared networks (listing,
|
|
retrieving details, adding new ones, removing existing ones, adding
|
|
subnets to and removing from shared networks) is also provided.
|
|
</para>
|
|
|
|
<para>Currently this library is only available to ISC customers with a
|
|
support contract.</para>
|
|
|
|
<para>The following commands are currently supported:
|
|
<itemizedlist mark="bullet">
|
|
<listitem>
|
|
<simpara><command>subnet4-list/subnet6-list</command>: lists all configured subnets
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<command>subnet4-get/subnet6-get</command>: retrieves detailed information about a specified subnet
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<command>subnet4-add/subnet6-add</command>: adds new subnet into server's configuration
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<command>subnet4-del/subnet6-del</command>: removes a subnet from the server's configuration
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
<command>network4-list/network6-list</command>: lists all configured
|
|
shared networks
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<command>network4-get/network6-get</command>: retrieves detailed
|
|
information about specified shared network
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<command>network4-add/network6-add</command>: adds a new shared
|
|
network to the server's configuration
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<command>network4-del/network6-del</command>: removes a shared
|
|
network from the server's configuration
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<command>network4-subnet-add/network6-subnet-add</command>: adds
|
|
existing subnet to existing shared network
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<command>network4-subnet-del/network6-subnet-del</command>: removes
|
|
a subnet from existing shared network and demotes it to a plain
|
|
subnet.
|
|
</simpara>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<section>
|
|
<title>subnet4-list command</title>
|
|
<para>
|
|
This command is used to list all currently configured subnets. The
|
|
subnets are returned in a brief form, i.e. a subnet identifier
|
|
and subnet prefix is included for each subnet. In order to retrieve
|
|
the detailed information about the subnet the
|
|
<command>subnet4-get</command> should be used.
|
|
</para>
|
|
<para>
|
|
This command has the simple structure:
|
|
<screen>
|
|
{
|
|
"command": "subnet4-list"
|
|
}
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
The list of subnets returned as a result of this command is returned
|
|
in the following format:
|
|
<screen>
|
|
{
|
|
"result": 0,
|
|
"text": "2 IPv4 subnets found",
|
|
"arguments": {
|
|
"subnets": [
|
|
{
|
|
"id": 10,
|
|
"subnet": "10.0.0.0/8"
|
|
},
|
|
{
|
|
"id": 100,
|
|
"subnet": "192.0.2.0/24"
|
|
}
|
|
]
|
|
}
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
If no IPv4 subnets are found, an error code is returned along with
|
|
the error description.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>subnet6-list command</title>
|
|
<para>
|
|
This command is used to list all currently configured subnets. The
|
|
subnets are returned in a brief form, i.e. a subnet identifier
|
|
and subnet prefix is included for each subnet. In order to retrieve
|
|
the detailed information about the subnet the
|
|
<command>subnet6-get</command> should be used.
|
|
</para>
|
|
<para>
|
|
This command has the simple structure:
|
|
<screen>
|
|
{
|
|
"command": "subnet6-list"
|
|
}
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
The list of subnets returned as a result of this command is returned
|
|
in the following format:
|
|
<screen>
|
|
{
|
|
"result": 0,
|
|
"text": "2 IPv6 subnets found",
|
|
"arguments": {
|
|
"subnets": [
|
|
{
|
|
"id": 11,
|
|
"subnet": "2001:db8:1::/64"
|
|
},
|
|
{
|
|
"id": 233,
|
|
"subnet": "3000::/16"
|
|
}
|
|
]
|
|
}
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
If no IPv6 subnets are found, an error code is returned along with
|
|
the error description.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>subnet4-get command</title>
|
|
<para>This command is used to retrieve detailed information about the
|
|
specified subnet. This command usually follows the
|
|
<command>subnet4-list</command>, which is used to discover available
|
|
subnets with their respective subnet identifiers and prefixes. Any of
|
|
those parameters can be then used in <command>subnet4-get</command>
|
|
to fetch subnet information:
|
|
<screen>
|
|
{
|
|
"command": "subnet4-get",
|
|
"arguments": {
|
|
"id": 10
|
|
}
|
|
}</screen>
|
|
|
|
or
|
|
|
|
<screen>
|
|
{
|
|
"command": "subnet4-get",
|
|
"arguments": {
|
|
"subnet": "10.0.0.0/8"
|
|
}
|
|
}
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
If the subnet exists the response will be similar to this:
|
|
<screen>
|
|
{
|
|
"result": 0,
|
|
"text": "Info about IPv4 subnet 10.0.0.0/8 (id 10) returned",
|
|
"arguments": {
|
|
"subnets": [
|
|
{
|
|
"subnet": "10.0.0.0/8",
|
|
"id": 1,
|
|
"option-data": [
|
|
....
|
|
]
|
|
...
|
|
}
|
|
]
|
|
}
|
|
}
|
|
|
|
</screen>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>subnet6-get command</title>
|
|
<para>This command is used to retrieve detailed information about the
|
|
specified subnet. This command usually follows the
|
|
<command>subnet6-list</command>, which is used to discover available
|
|
subnets with their respective subnet identifiers and prefixes. Any of
|
|
those parameters can be then used in <command>subnet6-get</command>
|
|
to fetch subnet information:
|
|
<screen>
|
|
{
|
|
"command": "subnet6-get",
|
|
"arguments": {
|
|
"id": 11
|
|
}
|
|
}
|
|
</screen>
|
|
|
|
or
|
|
|
|
<screen>
|
|
{
|
|
"command": "subnet6-get",
|
|
"arguments": {
|
|
"subnet": "2001:db8:1::/64"
|
|
}
|
|
}</screen>
|
|
|
|
If the subnet exists the response will be similar to this:
|
|
<screen>
|
|
{
|
|
"result": 0,
|
|
"text": "Info about IPv6 subnet 2001:db8:1::/64 (id 11) returned",
|
|
"arguments": {
|
|
"subnets": [
|
|
{
|
|
"subnet": "2001:db8:1::/64",
|
|
"id": 1,
|
|
"option-data": [
|
|
...
|
|
]
|
|
....
|
|
}
|
|
]
|
|
}
|
|
}
|
|
</screen>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>subnet4-add</title>
|
|
<para>
|
|
This command is used to create and add new subnet to the existing
|
|
server configuration. This operation has no impact on other
|
|
subnets. The subnet identifier must be specified and must be
|
|
unique among all subnets. If the identifier or a subnet prefix is
|
|
not unique an error is reported and the subnet is not added.
|
|
</para>
|
|
<para>
|
|
The subnet information within this command has the same structure
|
|
as the subnet information in the server configuration file with the
|
|
exception that static host reservations must not be specified
|
|
within <command>subnet4-add</command>. The commands described in
|
|
<xref linkend="host-cmds"/> should be used to add, remove and
|
|
modify static reservations.
|
|
<screen>
|
|
{
|
|
"command": "subnet4-add",
|
|
"arguments": {
|
|
"subnets": [ {
|
|
"id": 123,
|
|
"subnet": "10.20.30.0/24",
|
|
...
|
|
} ]
|
|
}
|
|
}
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
The response to this command has the following structure:
|
|
<screen>
|
|
{
|
|
"result": 0,
|
|
"text": "IPv4 subnet added",
|
|
"arguments": {
|
|
"subnets": [
|
|
{
|
|
"id": 123,
|
|
"subnet": "10.20.30.0/24"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
</screen>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>subnet6-add</title>
|
|
<para>
|
|
This command is used to create and add new subnet to the existing
|
|
server configuration. This operation has no impact on other
|
|
subnets. The subnet identifier must be specified and must be
|
|
unique among all subnets. If the identifier or a subnet prefix is
|
|
not unique an error is reported and the subnet is not added.
|
|
</para>
|
|
<para>
|
|
The subnet information within this command has the same structure
|
|
as the subnet information in the server configuration file with the
|
|
exception that static host reservations must not be specified
|
|
within <command>subnet6-add</command>. The commands described in
|
|
<xref linkend="host-cmds"/> should be used to add, remove and
|
|
modify static reservations.
|
|
<screen>
|
|
{
|
|
"command": "subnet6-add",
|
|
"arguments": {
|
|
"subnet6": [ {
|
|
"id": 234,
|
|
"subnet": "2001:db8:1::/64",
|
|
...
|
|
} ]
|
|
}
|
|
}
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
The response to this command has the following structure:
|
|
<screen>
|
|
{
|
|
"result": 0,
|
|
"text": "IPv6 subnet added",
|
|
"arguments": {
|
|
"subnet6": [
|
|
{
|
|
"id": 234,
|
|
"subnet": "2001:db8:1::/64"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
It is recommended, but not mandatory to specify subnet
|
|
id. If not specified, Kea will try to assign the next
|
|
subnet-id value. This automatic ID value generator is
|
|
simple. It returns a previously automatically assigned value
|
|
increased by 1. This works well, unless you manually create
|
|
a subnet with a value bigger than previously used. For
|
|
example, if you call subnet4-add five times, each without
|
|
id, Kea will assign IDs: 1,2,3,4 and 5 and it will work just
|
|
fine. However, if you try to call subnet4-add five times,
|
|
with the first subnet having subnet-id of value 3 and
|
|
remaining ones having no subnet-id, it will fail. The first
|
|
command (with explicit value) will use subnet-id 3, the
|
|
second command will create a subnet with id of 1, the third
|
|
will use value of 2 and finally the fourth will have the
|
|
subnet-id value auto-generated as 3. However, since there is
|
|
already a subnet with that id, it will fail.
|
|
</para>
|
|
<para>
|
|
The general recommendation is to either: never use explicit
|
|
values (so the auto-generated values will always work) or
|
|
always use explicit values (so the auto-generation is never
|
|
used). You can mix those two approaches only if you
|
|
understand how the internal automatic subnet-id generation works.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>subnet4-del command</title>
|
|
<para>
|
|
This command is used to remove a subnet from the server's configuration.
|
|
This command has no effect on other configured subnets but removing
|
|
a subnet has certain implications which the server's administrator
|
|
should be aware of.
|
|
</para>
|
|
<para>
|
|
In most cases the server has assigned some leases to the clients
|
|
belonging to the subnet. The server may also be configured with
|
|
static host reservations which are associated with this subnet.
|
|
The current implementation of the <command>subnet4-del</command>
|
|
removes neither the leases nor host reservations associated with
|
|
a subnet. This is the safest approach because the server doesn't
|
|
loose track of leases assigned to the clients from this subnet.
|
|
However, removal of the subnet may still cause configuration
|
|
errors and conflicts. For example: after removal of the subnet,
|
|
the server administrator may add a new subnet with the ID used
|
|
previously for the removed subnet. This means that the existing
|
|
leases and static reservations will be in conflict with this
|
|
new subnet. Thus, we recommend that this command is used with extreme
|
|
caution.
|
|
</para>
|
|
<para>
|
|
This command can also be used to completely delete an IPv4 subnet that
|
|
is part of a shared network. If you want to simply remove the subnet
|
|
from a shared network and keep the subnet configuration, use
|
|
<command>network4-subnet-del</command> command instead.
|
|
</para>
|
|
|
|
<para>The command has the following structure:
|
|
<screen>
|
|
{
|
|
"command": "subnet4-del",
|
|
"arguments": {
|
|
"id": 123
|
|
}
|
|
}
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
The example successful response may look like this:
|
|
<screen>
|
|
{
|
|
"result": 0,
|
|
"text": "IPv4 subnet 192.0.2.0/24 (id 123) deleted",
|
|
"arguments": {
|
|
"subnets": [
|
|
{
|
|
"id": 123,
|
|
"subnet": "192.0.2.0/24"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
</screen>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>subnet6-del command</title>
|
|
<para>
|
|
This command is used to remove a subnet from the server's configuration.
|
|
This command has no effect on other configured subnets but removing
|
|
a subnet has certain implications which the server's administrator
|
|
should be aware of.
|
|
</para>
|
|
<para>
|
|
In most cases the server has assigned some leases to the clients
|
|
belonging to the subnet. The server may also be configured with
|
|
static host reservations which are associated with this subnet.
|
|
The current implementation of the <command>subnet6-del</command>
|
|
removes neither the leases nor host reservations associated with
|
|
a subnet. This is the safest approach because the server doesn't
|
|
loose track of leases assigned to the clients from this subnet.
|
|
However, removal of the subnet may still cause configuration
|
|
errors and conflicts. For example: after removal of the subnet,
|
|
the server administrator may add a new subnet with the ID used
|
|
previously for the removed subnet. This means that the existing
|
|
leases and static reservations will be in conflict with this
|
|
new subnet. Thus, we recommend that this command is used with extreme
|
|
caution.
|
|
</para>
|
|
<para>
|
|
This command can also be used to completely delete an IPv6 subnet that
|
|
is part of a shared network. If you want to simply remove the subnet
|
|
from a shared network and keep the subnet configuration, use
|
|
<command>network6-subnet-del</command> command instead.
|
|
</para>
|
|
|
|
<para>The command has the following structure:
|
|
<screen>
|
|
{
|
|
"command": "subnet6-del",
|
|
"arguments": {
|
|
"id": 234
|
|
}
|
|
}
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
The example successful response may look like this:
|
|
<screen>
|
|
{
|
|
"result": 0,
|
|
"text": "IPv6 subnet 2001:db8:1::/64 (id 234) deleted",
|
|
"subnets": [
|
|
{
|
|
"id": 234,
|
|
"subnet": "2001:db8:1::/64"
|
|
}
|
|
]
|
|
}
|
|
</screen>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>network4-list, network6-list commands</title>
|
|
<para>
|
|
These commands are used to retrieve full list of currently configured
|
|
shared networks. The list contains only very basic information about
|
|
each shared network. If more details are needed, please use
|
|
<command>network4-get</command> or <command>network6-get</command> to
|
|
retrieve all information available. This command does not require any
|
|
parameters and its invocation is very simple:
|
|
<screen>
|
|
{
|
|
"command": "network4-list"
|
|
}
|
|
</screen>
|
|
An example response for <command>network4-list</command> looks as follows:
|
|
<screen>
|
|
{
|
|
"arguments": {
|
|
"shared-networks": [
|
|
{ "name": "floor1" },
|
|
{ "name": "office" }
|
|
]
|
|
},
|
|
"result": 0,
|
|
"text": "2 IPv4 network(s) found"
|
|
}</screen>
|
|
<command>network6-list</command> follows exactly the same syntax for
|
|
both the query and the response.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>network4-get, network6-get commands</title>
|
|
<para>
|
|
These commands are used to retrieve detailed information
|
|
about shared networks, including subnets currently
|
|
being part of a given network. Both commands take one
|
|
mandatory parameter <command>name</command>, which specify
|
|
the name of shared network. An example command to retrieve
|
|
details about IPv4 shared network with a name "floor13"
|
|
looks as follows:
|
|
<screen>
|
|
{
|
|
"command": "network4-get",
|
|
"arguments": {
|
|
"name": "floor13"
|
|
}
|
|
}</screen>
|
|
An example response could look as follows:
|
|
<screen>
|
|
{
|
|
"result": 0,
|
|
"text": "Info about IPv4 shared network 'floor13' returned",
|
|
"arguments": {
|
|
"shared-networks": [
|
|
{
|
|
"match-client-id": true,
|
|
"name": "floor13",
|
|
"option-data": [ ],
|
|
"rebind-timer": 90,
|
|
"relay": {
|
|
"ip-address": "0.0.0.0"
|
|
},
|
|
"renew-timer": 60,
|
|
"reservation-mode": "all",
|
|
"subnet4": [
|
|
{
|
|
"subnet": "192.0.2.0/24",
|
|
"id": 5,
|
|
// many other subnet specific details here
|
|
},
|
|
{
|
|
"id": 6,
|
|
"subnet": "192.0.3.0/31",
|
|
// many other subnet specific details here
|
|
}
|
|
],
|
|
"valid-lifetime": 120
|
|
}
|
|
]
|
|
}
|
|
}
|
|
</screen>
|
|
Note that actual response contains many additional fields that are
|
|
omitted here for clarity. The response format is exactly the same as
|
|
used in <command>config-get</command>, just is limited to returning
|
|
shared networks information.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>network4-add, network6-add commands</title>
|
|
<para>
|
|
These commands are used to add a new shared network. New
|
|
network has to have unique name. This command requires one parameter
|
|
<command>shared-networks</command>, which is a list and
|
|
should contain exactly one entry that defines the
|
|
network. The only mandatory element for a network is its
|
|
name. Although it does not make operational sense, it is
|
|
allowed to add an empty shared network that does not have
|
|
any subnets in it. That is allowed for testing purposes, but
|
|
having empty networks (or with only one subnet) is
|
|
discouraged in production environments. For details regarding
|
|
syntax, see <xref linkend="shared-network4"/> and <xref
|
|
linkend="shared-network6"/>.
|
|
</para>
|
|
<note><para>As opposed to parameter inheritance during full
|
|
new configuration processing, this command does not fully handle
|
|
parameter inheritance and any missing parameters will be
|
|
filled with default values, rather than inherited from
|
|
global scope.</para></note>
|
|
<para>
|
|
An example that showcases how to add a new IPv4 shared network looks
|
|
as follows:
|
|
<screen>
|
|
{
|
|
"command": "network4-add",
|
|
"arguments": {
|
|
"shared-networks": [ {
|
|
"name": "floor13",
|
|
"subnet4": [
|
|
{
|
|
"id": 100,
|
|
"pools": [ { "pool": "192.0.2.2-192.0.2.99" } ],
|
|
"subnet": "192.0.2.0/24",
|
|
"option-data": [
|
|
{
|
|
"name": "routers",
|
|
"data": "192.0.2.1"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"id": 101,
|
|
"pools": [ { "pool": "192.0.3.2-192.0.3.99" } ],
|
|
"subnet": "192.0.3.0/24",
|
|
"option-data": [
|
|
{
|
|
"name": "routers",
|
|
"data": "192.0.3.1"
|
|
}
|
|
]
|
|
} ]
|
|
} ]
|
|
}
|
|
}
|
|
</screen>
|
|
Assuming there was no shared network with a name floor13 and no subnets with id
|
|
100 and 101 previously configured, the command will be successful and will
|
|
return the following response:
|
|
<screen>
|
|
{
|
|
"arguments": {
|
|
"shared-networks": [ { "name": "floor13" } ]
|
|
},
|
|
"result": 0,
|
|
"text": "A new IPv4 shared network 'floor13' added"
|
|
}
|
|
</screen>
|
|
The <command>network6-add</command> uses the same syntax for both the query and
|
|
the response. However, there are some parameters that are IPv4-only
|
|
(e.g. match-client-id) and some are IPv6-only (e.g. interface-id). The same
|
|
applies to subnets within the network.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>network4-del, network6-del commands</title>
|
|
<para>
|
|
These commands are used to delete existing shared
|
|
networks. Both commands take exactly one parameter 'name' that
|
|
specifies the name of the network to be removed. An example invocation
|
|
of <command>network4-del</command> command looks as follows:
|
|
<screen>
|
|
{
|
|
"command": "network4-del",
|
|
"arguments": {
|
|
"name": "floor13"
|
|
}
|
|
}
|
|
</screen>
|
|
Assuming there was such a network configured, the response will look similar to
|
|
the following:
|
|
<screen>
|
|
{
|
|
"arguments": {
|
|
"shared-networks": [
|
|
{
|
|
"name": "floor13"
|
|
}
|
|
]
|
|
},
|
|
"result": 0,
|
|
"text": "IPv4 shared network 'floor13' deleted"
|
|
}</screen>
|
|
The <command>network6-del</command> command uses exactly the same syntax for
|
|
both the command and the response.
|
|
</para>
|
|
|
|
<para>If there are any subnets belonging to the shared network
|
|
being deleted, they will be demoted to a plain subnet. There
|
|
is an optional parameter called
|
|
<command>subnets-action</command> that, if specified, takes
|
|
one of two possible values: <command>keep</command> (which is
|
|
the default) and <command>delete</command>. It controls
|
|
whether the subnets be demoted to plain subnets or removed. An
|
|
example usage in network6-del command that deletes the shared
|
|
network and all subnets in it could looks like as follows:
|
|
<screen>
|
|
{
|
|
"command": "network4-del",
|
|
"arguments": {
|
|
"name": "floor13",
|
|
"subnets-action": "delete"
|
|
}
|
|
}
|
|
</screen>
|
|
</para>
|
|
|
|
<para>Alternatively, if you want to completely remove the
|
|
subnets, you may use <command>subnet4-del</command> or
|
|
<command>subnet6-del</command> commands.</para>
|
|
|
|
</section>
|
|
<section>
|
|
<title>network4-subnet-add, network6-subnet-add commands</title>
|
|
<para>
|
|
These commands are used to add existing subnets to existing shared
|
|
networks. There are several ways to add new shared network. System
|
|
administrator can add the whole shared network at once, either by
|
|
editing a configuration file or by calling
|
|
<command>network4-add</command> or <command>network6-add</command>
|
|
commands with desired subnets in it. This approach works better for completely
|
|
new shared subnets. However, there may be cases when an existing
|
|
subnet is running out of addresses and needs to be extended with
|
|
additional address space. In other words another subnet has to be
|
|
added on top of it. For this scenario, a system administrator can use
|
|
<command>network4-add</command> or <command>network6-add</command> and
|
|
then add existing subnet to this newly created shared network using
|
|
<command>network4-subnet-add</command> or
|
|
<command>network6-subnet-add</command>.
|
|
</para>
|
|
<para>
|
|
The <command>network4-subnet-add</command> and
|
|
<command>network6-subnet-add</command> commands take two parameters:
|
|
<command>id</command>, which is an integer and specifies subnet-id of existing subnet to
|
|
be added to a shared network; and <command>name</command>, which
|
|
specifies name of the shared network the subnet will be added to. The
|
|
subnet must not belong to any existing network. In case you want to
|
|
reassign a subnet from one shared network to another, please use
|
|
<command>network4-subnet-del</command> or
|
|
<command>network6-subnet-del</command> commands first.
|
|
</para>
|
|
<para>
|
|
An example invocation of <command>network4-subnet-add</command>
|
|
command looks as follows:
|
|
<screen>
|
|
{
|
|
"command": "network4-subnet-add",
|
|
"arguments": {
|
|
"name": "floor13",
|
|
"id": 5
|
|
}
|
|
}</screen>
|
|
Assuming there is a network named 'floor13', there is a subnet with subnet-id 5
|
|
and it is not a part of existing network, the command will return a response
|
|
similar to the following:
|
|
<screen>
|
|
{
|
|
"result": 0,
|
|
"text": "IPv4 subnet 10.0.0.0/8 (id 5) is now part of shared network 'floor1'"
|
|
}</screen>
|
|
The <command>network6-subnet-add</command> command uses exactly the same syntax for
|
|
both the command and the response.
|
|
</para>
|
|
|
|
<note><para>As opposed to parameter inheritance during full
|
|
new configuration processing or when adding a new shared network with
|
|
new subnets, this command does not fully handle
|
|
parameter inheritance and any missing parameters will be
|
|
filled with default values, rather than inherited from
|
|
global scope or from the shared network.</para></note>
|
|
</section>
|
|
<section>
|
|
<title>network4-subnet-del, network6-subnet-del commands</title>
|
|
<para>
|
|
These commands are used to remove a subnet that is part of existing shared
|
|
network and demote it to a plain, stand-alone subnet. If you want to
|
|
remove a subnet completely, use <command>subnet4-del</command> or
|
|
<command>subnet6-del</command> commands instead.
|
|
The <command>network4-subnet-del</command> and
|
|
<command>network6-subnet-del</command> commands take two parameters:
|
|
<command>id</command>, which is an integer and specifies subnet-id of
|
|
existing subnet to be removed from a shared network; and
|
|
<command>name</command>, which specifies name of the shared network
|
|
the subnet will be removed from.
|
|
</para>
|
|
<para>An example invocation of the
|
|
<command>network4-subnet-del</command> command looks as follows:
|
|
<screen>
|
|
{
|
|
"command": "network4-subnet-del",
|
|
"arguments": {
|
|
"name": "floor13",
|
|
"id": 5
|
|
}
|
|
}</screen>
|
|
Assuming there was a subnet with subnet-id equal to 5 that was part of a shared
|
|
network named 'floor13', the response would look similar to the following:
|
|
<screen>
|
|
{
|
|
"result": 0,
|
|
"text": "IPv4 subnet 10.0.0.0/8 (id 5) is now removed from shared network 'floor13'"
|
|
}</screen>
|
|
The <command>network6-subnet-del</command> command uses exactly the same syntax for
|
|
both the command and the response.
|
|
</para>
|
|
</section>
|
|
|
|
</section> <!-- end of subnet commands -->
|
|
|
|
<section id="high-availability-library">
|
|
<title>libdhcp_ha: High Availability</title>
|
|
<para>
|
|
This section will describe the <command>libdhcp_ha</command> hook library
|
|
being developed for the Kea 1.4.0 release.
|
|
</para>
|
|
</section> <!-- end of high-availability-library -->
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section xml:id="user-context">
|
|
<title>User contexts</title>
|
|
<para>Hook libraries can have their own configuration parameters. That is
|
|
convenient if the parameter applies to the whole library. However,
|
|
sometimes it is very useful if certain configuration entities are extended
|
|
with additional configuration data. This is where the concept of user
|
|
contexts comes in. A sysadmin can define an arbitrary set of data and
|
|
attach it to Kea structures, as long as the data is specified as JSON map.
|
|
In particular, it is possible to define fields that are integers, strings,
|
|
boolean, lists and maps. It is possible to define nested structures of
|
|
arbitrary complexity. Kea does not use that data on its own, simply stores
|
|
and makes it available for the hook libraries.
|
|
</para>
|
|
<para>
|
|
Another use case for user contexts may be storing comments and other
|
|
information that will be retained by Kea. Regular comments are discarded
|
|
when configuration is loaded, but user contexts are retained. This is
|
|
useful if you want your comments to survive config-set, config-get
|
|
operations for example.
|
|
</para>
|
|
<para>
|
|
If user context is supported in a given context, the parser translates
|
|
"comment" entries into user context with a "comment" entry. The pretty
|
|
print of a configuration does the opposite operation and puts "comment"
|
|
entries at the beginning of maps as it seems to be the common usage.
|
|
</para>
|
|
<para>
|
|
As of Kea 1.3, the structures that allow user contexts are
|
|
pools of all types (addresses and prefixes) and subnets. Kea
|
|
1.4 extended user context support to the global scope, interfaces config,
|
|
shared networks, subnets, client classes, option datas and definitions,
|
|
host reservations, control socket, dhcp ddns, loggers and server id.
|
|
These are supported in both DHCPv4 and DHCPv6 at the exception
|
|
of server id which is DHCPv6 only.
|
|
</para>
|
|
</section>
|
|
|
|
|
|
|
|
</chapter>
|