mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-30 05:27:55 +00:00
[3800] Fix some typo level items in the documentation.
This commit is contained in:
Shawn Routhier
parent
f603a0dbce
commit
a080ae22d6
@ -9,17 +9,17 @@
|
||||
<chapter id="ctrl-channel">
|
||||
<title>Management API</title>
|
||||
|
||||
<para>A classic approach to the daemon configuration assumes that
|
||||
<para>A classic approach to daemon configuration assumes that
|
||||
the server's configuration is stored in the configuration files
|
||||
and when the configuration is changed, the daemon is restarted.
|
||||
This approach has significant disadvantage of introducing periods
|
||||
of downtime, where client traffic is not handled. Another risk
|
||||
This approach has the significant disadvantage of introducing periods
|
||||
of downtime, when client traffic is not handled. Another risk
|
||||
is that if the new configuration is invalid for whatever reason,
|
||||
the server may refuse to start, which will further extend the
|
||||
downtime period, until the issue is resolved.</para>
|
||||
|
||||
<para>To avoid such problems, both DHCPv4 and DHCPv6 servers
|
||||
support introduced support for a mechanism that will allow
|
||||
introduced support for a mechanism that will allow
|
||||
on-line reconfiguration, without requiring server shutdown.
|
||||
Both servers can be instructed to open control sockets, which
|
||||
is a communication channel. The server is able to receive
|
||||
@ -36,7 +36,7 @@
|
||||
|
||||
<section id="ctrl-channel-syntax">
|
||||
<title>Data syntax</title>
|
||||
<para>Communication over Control Channel is conducted using JSON
|
||||
<para>Communication over control channel is conducted using JSON
|
||||
structures. If configured, Kea will open a socket and will listen
|
||||
for any incoming connections. A process connecting to this socket
|
||||
is expected to send JSON commands structured as follows:
|
||||
@ -71,13 +71,13 @@
|
||||
}
|
||||
</screen>
|
||||
<command>result</command> indicates the outcome of the command. A value of 0
|
||||
means a success while any non-zero value designates an error. Currently 1 is
|
||||
means success while any non-zero value designates an error. Currently 1 is
|
||||
used as a generic error, but additional error codes may be added in the
|
||||
future.<command>text</command> field typically appears when result is
|
||||
non-zero and contains description of the error encountered, but it may also
|
||||
appear for success results. That's command specific.
|
||||
non-zero and contains a description of the error encountered, but it may
|
||||
also appear for successful results. That's command specific.
|
||||
<command>arguments</command> is a map of additional data values returned by
|
||||
the server, specific to the command issue. The map is always present, even
|
||||
the server, specific to the command issued. The map is always present, even
|
||||
if it contains no data values.</para>
|
||||
</section>
|
||||
|
||||
@ -87,24 +87,24 @@
|
||||
<para>ISC does not provide a client for using control channel. The primary
|
||||
reason for that is the expectation is that the entity using control channel
|
||||
is typically an IPAM or similar network management/monitoring software which
|
||||
may have quite varied expectations regarding the client and even likely to
|
||||
may have quite varied expectations regarding the client and is even likely to
|
||||
be written in languages different than C or C++. Therefore we only provide
|
||||
examples how one can take advantage of the API.</para>
|
||||
|
||||
<para>The easiest way is to use a tool called <command>socat</command>,
|
||||
a tool available from <ulink url="http://www.dest-unreach.org/socat/">socat
|
||||
homepage</ulink>, but is also widely available in Linux and BSD
|
||||
homepage</ulink>, but it is also widely available in Linux and BSD
|
||||
distributions. Once Kea is started, one could connect to the control
|
||||
interface using the following command:
|
||||
<screen>
|
||||
$ socat UNIX:/path/to/the/kea/socket -
|
||||
</screen>
|
||||
where <command>/path/to/the/kea/socket</command> is the path specified in
|
||||
<command>Dhcp4/control-socket/socket-name</command> parameter in Kea
|
||||
where <command>/path/to/the/kea/socket</command> is the path specified in the
|
||||
<command>Dhcp4/control-socket/socket-name</command> parameter in the Kea
|
||||
configuration file.</para>
|
||||
|
||||
<para>It is also easy to open UNIX socket programmatically. An example of
|
||||
such simplistic client written in C is available in the Kea Developer's
|
||||
such a simplistic client written in C is available in the Kea Developer's
|
||||
Guide, chapter Control Channel Overview, section Using Control Channel.</para>
|
||||
|
||||
</section>
|
||||
@ -117,7 +117,7 @@ configuration file.</para>
|
||||
|
||||
<para>
|
||||
<emphasis>list-commands</emphasis> command retrieves a list of all
|
||||
supported commands by the server. It does not take any arguments.
|
||||
commands supported by the server. It does not take any arguments.
|
||||
An example command may look like this:
|
||||
<screen>
|
||||
{
|
||||
@ -128,7 +128,7 @@ configuration file.</para>
|
||||
</para>
|
||||
<para>
|
||||
The server will respond with a list of all supported commands. The
|
||||
arguments element will be a list strings. Each string will convey
|
||||
arguments element will be a list of strings. Each string will convey
|
||||
one supported command.
|
||||
</para>
|
||||
</section> <!-- end of command-list-commands -->
|
||||
@ -138,7 +138,7 @@ configuration file.</para>
|
||||
|
||||
<para>
|
||||
<emphasis>shutdown</emphasis> command instructs the server to initiate
|
||||
its shutdown procedure. It is an equivalent of sending SIGTERM singal
|
||||
its shutdown procedure. It is the equivalent of sending a SIGTERM singal
|
||||
to the process. This command does not take any arguments. An example
|
||||
command may look like this:
|
||||
<screen>
|
||||
|
||||
@ -11,16 +11,16 @@
|
||||
<title>Statistics Overview</title>
|
||||
|
||||
<para>Both Kea DHCP servers support statistics gathering since
|
||||
0.9.2-beta version. Working DHCP server encounters various events
|
||||
that can influence certain statistics to be collected. For
|
||||
0.9.2-beta version. A working DHCP server encounters various events
|
||||
that can cause certain statistics to be collected. For
|
||||
example, a DHCPv4 server may receive a packet (pkt4-received
|
||||
statistic increased by one) that after parsing was identifier as
|
||||
DHCPDISCOVER (pkt4-discover-received). Server processed it and
|
||||
statistic increases by one) that after parsing was identifier as
|
||||
DHCPDISCOVER (pkt4-discover-received). The Server processed it and
|
||||
decided to send DHCPOFFER representing its answer (pkt4-offer-sent
|
||||
and pkt4-sent statistics increased by one). Such events happen
|
||||
and pkt4-sent statistics increase by one). Such events happen
|
||||
frequently, so it is not uncommon for the statistics to have
|
||||
values in high thousands. They can serve as an easy and powerful
|
||||
tool for observing server's and network's health. For example,
|
||||
tool for observing a server's and network's health. For example,
|
||||
if pkt4-received statistic stops growing, it means that the
|
||||
clients' packets are not reaching the server.</para>
|
||||
|
||||
@ -38,12 +38,12 @@
|
||||
</listitem>
|
||||
<listitem>
|
||||
<simpara><emphasis>duration</emphasis> - this type is intended for
|
||||
recoding time periods. It uses boost::posix_time::time_duration type,
|
||||
recording time periods. It uses boost::posix_time::time_duration type,
|
||||
which stores hours, minutes, seconds and microseconds.</simpara>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<simpara><emphasis>string</emphasis> - this type is intended for
|
||||
recoding statistics in textual forma. It uses std::string C++ type.
|
||||
recording statistics in textual forma. It uses std::string C++ type.
|
||||
</simpara>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
@ -51,14 +51,14 @@
|
||||
|
||||
<para>
|
||||
During normal operation, DHCPv4 and DHCPv6 servers gather statistics.
|
||||
For a DHCPv4 and DHCPv6 list of statistics, see <xref
|
||||
For a list of DHCPv4 and DHCPv6 statistics, see <xref
|
||||
linkend="dhcp4-stats"/> and <xref linkend="dhcp6-stats"/>, respectively.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To extract data from the statistics module, the control channel can be
|
||||
used. See <xref linkend="ctrl-channel" /> for details. It is possible to
|
||||
retrieve a single statistic, all statistics, reset (i.e. set to neutral
|
||||
retrieve a single or all statistics, reset statistics (i.e. set to neutral
|
||||
value, typically zero) or even remove completely a single or all
|
||||
statistics. See section <xref linkend="command-stats"/> for a list of
|
||||
statistic oriented commands.
|
||||
@ -68,14 +68,14 @@
|
||||
<section id="stats-lifecycle">
|
||||
<title>Statistics Lifecycle</title>
|
||||
<para>
|
||||
It is useful to understand how Statistics Manager module is working. When
|
||||
It is useful to understand how the Statistics Manager module works. When
|
||||
the server starts operation, the manager is empty and does not have any
|
||||
statistics. When <command>statistic-get-all</command> is executed, an
|
||||
empty list is returned. Once the server performs an operation that causes
|
||||
statistic change, related statistic will be created. In a general case
|
||||
once a statistic is recorded even once, it is kept in the manager, until
|
||||
a statistic to change, the related statistic will be created. In the general
|
||||
case once a statistic is recorded even once, it is kept in the manager, until
|
||||
explicitly removed, by <command>statistic-remove</command> or
|
||||
<command>statistic-remove-all</command> is called or the server is shut
|
||||
<command>statistic-remove-all</command> being called or the server is shut
|
||||
down. Per subnet statistics are explicitly removed when reconfiguration
|
||||
takes place.
|
||||
</para>
|
||||
@ -85,28 +85,29 @@
|
||||
</para>
|
||||
<para>
|
||||
Removing a statistic that is updated frequently makes little sense as it
|
||||
will be re-added when the server code records a given statistic the next
|
||||
time. <command>statistic-remove</command> and
|
||||
will be re-added when the server code next records that statistic.
|
||||
The <command>statistic-remove</command> and
|
||||
<command>statistic-remove-all</command> commands are intended to remove
|
||||
statistics that is not expected to be observed in the near future. For
|
||||
statistics that are not expected to be observed in the near future. For
|
||||
example, a misconfigured device in a network may cause clients to report
|
||||
duplicate addresses, so the server will report increasing values of
|
||||
pkt4-decline-received. Once the problem is found and the device is
|
||||
removed, system administrator may want to remove pkt4-decline-received
|
||||
statistic, so it won't be reported anymore. If duplicate address is
|
||||
detected ever again, the server will add this statistic back.
|
||||
removed, the system administrator may want to remove the
|
||||
pkt4-decline-received statistic, so it won't be reported anymore. If a
|
||||
duplicate address is detected ever again, the server will add this
|
||||
statistic back.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="command-stats">
|
||||
<title>Commands for manipulating statistics</title>
|
||||
<title>Commands for Manipulating Statistics</title>
|
||||
<para>
|
||||
There are several commands defined that can be used for accessing (-get),
|
||||
resetting to zero or neutral value (-reset) or even removing a statistic
|
||||
completely (-remove). The difference between reset and remove is somewhat
|
||||
subtle. Reset command sets value of the statistic to zero or neutral
|
||||
value. After this operation, statistic will have value of 0 (integer), 0.0
|
||||
(float), 0h0m0s0us (duration) or "" (string). When asked for, statistic
|
||||
subtle. The reset command sets the value of the statistic to zero or neutral
|
||||
value. After this operation, the statistic will have a value of 0 (integer),
|
||||
0.0 (float), 0h0m0s0us (duration) or "" (string). When asked for, a statistic
|
||||
with the values metioned will be returned. Remove removes a statistic
|
||||
completely, so the statistic will not be reported anymore. Please note
|
||||
that
|
||||
@ -130,9 +131,9 @@
|
||||
</screen>
|
||||
</para>
|
||||
<para>
|
||||
The server will respond with details of requested statistic, with result
|
||||
set to 0 indicates success and specified statistic as the value of
|
||||
"arguments" parameter. If requested statistic is not found, the response
|
||||
The server will respond with details of the requested statistic, with result
|
||||
set to 0 indicating success and the specified statistic as the value of
|
||||
"arguments" parameter. If the requested statistic is not found, the response
|
||||
will contain an empty map, i.e. only { } as argument, but the status
|
||||
code will still be set to success (0).
|
||||
</para>
|
||||
@ -142,8 +143,8 @@
|
||||
<title>statistic-reset command</title>
|
||||
|
||||
<para>
|
||||
<emphasis>statistic-reset</emphasis> command sets specified statistic to
|
||||
its neutral value: 0 for integer, 0.0 for float, 0h0m0s0us for time
|
||||
<emphasis>statistic-reset</emphasis> command sets the specified statistic
|
||||
to its neutral value: 0 for integer, 0.0 for float, 0h0m0s0us for time
|
||||
duration and "" for string type. It takes a single string parameter
|
||||
called <command>name</command> that specifies the statistic name. An
|
||||
example command may look like this:
|
||||
@ -157,11 +158,11 @@
|
||||
</screen>
|
||||
</para>
|
||||
<para>
|
||||
If specific statistic is found and reset was successful,
|
||||
the server will respond with status of 0, indicating success and empty
|
||||
parameters field. If error is encountered (e.g. requested statistic
|
||||
was not found), the server will return status code of 1 (error)
|
||||
and text field will contain the error description.
|
||||
If the specific statistic is found and reset was successful, the
|
||||
server will respond with a status of 0, indicating success and an empty
|
||||
parameters field. If an error is encountered (e.g. requested statistic
|
||||
was not found), the server will return a status code of 1 (error)
|
||||
and the text field will contain the error description.
|
||||
</para>
|
||||
</section> <!-- end of command-statistic-reset -->
|
||||
|
||||
@ -169,7 +170,7 @@
|
||||
<title>statistic-remove command</title>
|
||||
|
||||
<para>
|
||||
<emphasis>statistic-remove</emphasis> command attempt to delete a single
|
||||
<emphasis>statistic-remove</emphasis> command attempts to delete a single
|
||||
statistic. It takes a single string parameter called
|
||||
<command>name</command> that specifies the statistic name. An example
|
||||
command may look like this:
|
||||
@ -183,11 +184,11 @@
|
||||
</screen>
|
||||
</para>
|
||||
<para>
|
||||
If specific statistic is found and its removal was successful,
|
||||
the server will respond with status of 0, indicating success and empty
|
||||
parameters field. If error is encountered (e.g. requested statistic
|
||||
was not found), the server will return status code of 1 (error)
|
||||
and text field will contain the error description.
|
||||
If the specific statistic is found and its removal was successful, the
|
||||
server will respond with a status of 0, indicating success and an empty
|
||||
parameters field. If an error is encountered (e.g. requested statistic
|
||||
was not found), the server will return a status code of 1 (error)
|
||||
and the text field will contain the error description.
|
||||
</para>
|
||||
</section> <!-- end of command-statistic-reset -->
|
||||
|
||||
@ -227,9 +228,9 @@
|
||||
</screen>
|
||||
</para>
|
||||
<para>
|
||||
If the operation is successful, the server will respond with status of
|
||||
0, indicating success and empty parameters field. If error is
|
||||
encountered, the server will return status code of 1 (error) and text
|
||||
If the operation is successful, the server will respond with a status of
|
||||
0, indicating success and an empty parameters field. If an error is
|
||||
encountered, the server will return a status code of 1 (error) and the text
|
||||
field will contain the error description.
|
||||
</para>
|
||||
</section> <!-- end of command-statistic-reset-all -->
|
||||
@ -238,7 +239,7 @@
|
||||
<title>statistic-remove-all command</title>
|
||||
|
||||
<para>
|
||||
<emphasis>statistic-remove-all</emphasis> command attempt to delete all
|
||||
<emphasis>statistic-remove-all</emphasis> command attempts to delete all
|
||||
statistics. An example command may look like this:
|
||||
<screen>
|
||||
{
|
||||
@ -248,10 +249,10 @@
|
||||
</screen>
|
||||
</para>
|
||||
<para>
|
||||
If removal of all statistics was successful, the server will respond
|
||||
with status of 0, indicating success and empty parameters field. If
|
||||
error is encountered, the server will return status code of 1 (error)
|
||||
and text field will contain the error description.
|
||||
If the removal of all statistics was successful, the server will respond
|
||||
with a status of 0, indicating success and an empty parameters field. If
|
||||
an error is encountered, the server will return a status code of 1 (error)
|
||||
and the text field will contain the error description.
|
||||
</para>
|
||||
</section> <!-- end of command-statistic-remove-all -->
|
||||
|
||||
|
||||
@ -20,9 +20,9 @@
|
||||
In many cases it is useful to manage certain aspects of the DHCP servers
|
||||
while they are running. In Kea, this may be done via the Control Channel.
|
||||
Control Channel allows an external entity (e.g. a tool run by a sysadmin
|
||||
or a script) to issue commands to the server which can influence the its
|
||||
or a script) to issue commands to the server which can influence its
|
||||
behavior or retreive information from it. Several notable examples
|
||||
envisioned are: reconfiguration, statistics retrival and manipulation,
|
||||
envisioned are: reconfiguration, statistics retrieval and manipulation,
|
||||
and shutdown.
|
||||
|
||||
Communication over Control Channel is conducted using JSON structures.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user