Skip to content
GitLab
Projects
Groups
Snippets
/
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Menu
Open sidebar
ISC Open Source Projects
Kea
Commits
a080ae22
Commit
a080ae22
authored
Jun 18, 2015
by
Shawn Routhier
Browse files
[3800] Fix some typo level items in the documentation.
parent
f603a0db
Changes
3
Hide whitespace changes
Inline
Side-by-side
doc/guide/ctrl-channel.xml
View file @
a080ae22
...
...
@@ -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, whe
re
client traffic is not handled. Another risk
This approach has
the
significant disadvantage of introducing periods
of downtime, whe
n
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
C
ontrol
C
hannel is conducted using JSON
<para>
Communication over
c
ontrol
c
hannel 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 success
ful
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 issue
d
. 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>
...
...
doc/guide/stats.xml
View file @
a080ae22
...
...
@@ -11,16 +11,16 @@
<title>
Statistics Overview
</title>
<para>
Both Kea DHCP servers support statistics gathering since
0.9.2-beta version.
W
orking DHCP server encounters various events
that can
influenc
e certain statistics to be collected. For
0.9.2-beta version.
A w
orking DHCP server encounters various events
that can
caus
e certain statistics to be collected. For
example, a DHCPv4 server may receive a packet (pkt4-received
statistic increase
d
by one) that after parsing was identifier as
DHCPDISCOVER (pkt4-discover-received). Server processed it and
statistic increase
s
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 increase
d
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,
reco
r
ding 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.
reco
r
ding 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
work
ing
. When
It is useful to understand how
the
Statistics Manager module work
s
. 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
m
anipulating
s
tatistics
</title>
<title>
Commands for
M
anipulating
S
tatistics
</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.
R
eset 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 r
eset 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 indicat
es
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 indicat
ing
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 attempt
s
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 attempt
s
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 -->
...
...
src/lib/config/command-socket.dox
View file @
a080ae22
...
...
@@ -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 retri
e
val and manipulation,
and shutdown.
Communication over Control Channel is conducted using JSON structures.
...
...
Write
Preview
Supports
Markdown
0%
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment