Commit 4b82d088 authored by Marcin Siodelski's avatar Marcin Siodelski
Browse files

[3466] Created Administrator guide section for keactrl.

parent 87bc564b
......@@ -6,7 +6,7 @@ dist_doc_DATA = $(DOCS)
dist_html_DATA = $(HTMLDOCS) kea-guide.css
DOCBOOK = kea-guide.xml intro.xml quickstart.xml install.xml config.xml
DOCBOOK += dhcp4-srv.xml dhcp6-srv.xml logging.xml
DOCBOOK += keactrl.xml dhcp4-srv.xml dhcp6-srv.xml logging.xml
EXTRA_DIST = $(DOCBOOK)
DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml
......
......@@ -59,6 +59,8 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="config.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="keactrl.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp4-srv.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp6-srv.xml" />
......
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY mdash "&#x2014;" >
]>
<chapter id="keactrl">
<title>Managing Kea Servers With keactrl</title>
<section id="keactrl-overview">
<title>Overview</title>
<para>keactrl is a shell script which controls the startup, shutdown
and reconfiguration of the Kea servers, i.e. <command>kea-dhcp4</command>,
<command>kea-dhcp6</command> and <command>kea-dhcp-ddns</command>. It also
provides the means for checking the current status of the servers and
returns the information whether the servers are active or inactive
and also configuration data being used.
</para>
</section>
<section id="keactrl-usage">
<title>Command line options</title>
<para>The usage of the <command>keactrl</command> is:
<screen>
keactrl &lt;command&gt; [-c keactrl-config-file] [-s server[,server,..]]
</screen>
</para>
<para>
The <command>&lt;command&gt;</command> specifies the one of the commands
described in <xref linkend="keactrl-commands"/>.
</para>
<para>
The <command>[-c keactrl-config-file]</command> parameter overrides
the default location of the <command>keactrl</command> configuration
file.
</para>
<para>
The <command>[-s server[,server ...]]</command> parameter overrides
the list of servers to which the command is issued.
</para>
</section>
<section id="keactrl-config-file">
<title>keactrl Configuration File</title>
<para>
keactrl starts servers in background and returns. Depending on the
needs of the server's Administrator it is possible to select which
of them are started and which are not. This is specified in the
<filename>keactrl.conf</filename> file which by default is installed
in <filename>[kea-install-dir]/etc/kea/</filename>.
</para>
<para>
The default <filename>keactrl.conf</filename> file holds the following
configuration:
<screen>
# This is a configuration file for keactrl script which controls
# the startup, shutdown, reconfiguration and gathering the status
# of the Kea servers.
# prefix holds the location where the Kea is installed.
prefix=/home/marcin/devel/kea-build
# Location of Kea configuration file.
kea_config_file=${prefix}/etc/kea/kea.conf
# Location of Kea binaries.
exec_prefix=${prefix}
dhcp4_srv=${exec_prefix}/sbin/kea/b10-dhcp4
dhcp6_srv=${exec_prefix}/sin/kea/b10-dhcp6
dhcp_ddns_srv=${exec_prefix}/sbin/kea/b10-dhcp-ddns
# Start DHCPv4 server?
dhcp4=yes
# Start DHCPv6 server?
dhcp6=yes
# Start DHCP DDNS server?
dhcp_ddns=yes
# Be verbose?
kea_verbose=no
</screen>
</para>
<para>
The <parameter>dhcp4</parameter>, <parameter>dhcp6</parameter> and
<parameter>dhcp_ddns</parameter> parameters set to "yes" configure
<command>keactrl</command> to manage (start, reconfigure) all servers,
i.e. <command>kea-dhcp4</command>, <command>kea-dhcp6</command> and
<command>kea-dhcp-ddns</command>. When any of these parameters is set to
"no" the <command>keactrl</command> will skip starting or reconfiguring
the corresponding server.
</para>
<para>
By default, Kea processes managed by <command>keactrl</command> are
located in the <filename>[kea-install-dir]/sbin</filename>. This
should work for most of the installations. However, if the default
location needs to be altered for any reason, it can be achieved by
modifying the paths specified with the <parameter>dhcp4_srv</parameter>,
<parameter>dhcp6_srv</parameter> and <parameter>dhcp_ddns_srv</parameter>
parameters.
</para>
<para>
The <parameter>kea_verbose</parameter> parameter specifies the verbosity
of the servers being started. When <parameter>kea_verbose</parameter>
is set to "yes" the logging level of the server is set to DEBUG.
Otherwise, the default logging level is used.
</para>
<note>
<para>
The verbosity for the server is specified when it is started. Once
started, the verbosity can be only changed by stopping the server and
starting it again with the new value of the
<parameter>kea_verbose</parameter> parameter.
</para>
</note>
</section>
<section id="keactrl-commands">
<title>Commands</title>
<para>The following commands are supported by <command>keactrl</command>
to perform specific operations on the Kea servers:
<itemizedlist>
<listitem><simpara>
<command>start</command> - starts selected servers.
</simpara></listitem>
<listitem><simpara>
<command>stop</command> - stops all running servers.
</simpara></listitem>
<listitem><simpara>
<command>reload</command> - triggers reconfiguration of the
selected servers by sending the SIGHUP signal to them.
</simpara></listitem>
<listitem><simpara>
<command>status</command> - returns the status of the servers (active
or inactive) and the <command>keactrl</command> configuration data.
</simpara></listitem>
</itemizedlist>
</para>
<para>The typical output from the <command>keactrl</command> when starting
the servers looks similar to the following:
<screen>
<userinput>$ keactrl start</userinput>
INFO/keactrl: Starting b10-dhcp4 -c /usr/local/etc/kea/kea.conf
INFO/keactrl: Starting b10-dhcp6 -c /usr/local/etc/kea/kea.conf
INFO/keactrl: Starting b10-dhcp-ddns -c /usr/local/etc/kea/kea.conf
</screen>
</para>
<para>The following command stops all servers:
<screen>
<userinput>$ keactrl stop</userinput>
INFO/keactrl: Skip sending signal 15 to process kea-dhcp6: process is not running
</screen>
Note that the <command>stop</command> will attempt to stop all servers
regrdless if they are "enabled" in the <filename>keactrl.conf</filename>
or not. If any of the servers is not running, the informational message
is displayed as in the <command>stop</command> command output above.
</para>
<para>
As already mentioned, the reconfiguration of each Kea server is triggered
by the SIGHUP signal. The <command>reload</command> command sends
the SIGHUP signal to selected servers (running and "enabled" through the
<filename>keactrl.conf</filename> configuration file). When the server
receives the SIGHUP signal it re-reads its configuration file and if
the new configuration is valid it uses the new configuration. Use the
following command to trigger reconfiguration of the servers:
<screen>
<userinput>$ keactrl reload</userinput>
</screen>
</para>
<note>
<para>
Currently <command>keactrl</command> doesn't report configuration
failures when the server is started or reconfigured. In order to
check if the server's configuration succeeded the Kea log file
must be examined for errors. The default location of the log file is
<filename>[kea-install-dir]/var/kea/kea.log</filename>.
</para>
</note>
<para>
Sometimes it is useful to check which servers are running. One of the
cases is when one needs to verify if the server successfully started as
a result of executing <command>keactrl start</command> command. The
typical output from the <command>status</command> command looks like
this:
<screen>
<userinput>$ keactrl status</userinput>
DHCPv4 server: active
DHCPv6 server: inactive
DHCP DDNS: active
Kea configuration file: /usr/local/etc/kea/kea.conf
keactrl configuration file: /usr/local/etc/kea/keactrl.conf
</screen>
</para>
</section>
<section id="keactrl-overriding-servers">
<title>Overriding Servers Selection</title>
<para>
The <command>[-s server[,server]]</command> command line option
allows for selecting the servers to which the
<command>keactrl</command> command is issued. For example:
<screen>
<userinput>$ keactrl stop -s dhcp4,dhcp6</userinput>
</screen>
instructs the <command>keactrl</command> to only stop the
<command>kea-dhcp4</command> and <command>kea-dhcp6</command> servers
and leave the <command>kea-dhcp-ddns</command> running.
</para>
<para>
Similarly:
<screen>
<userinput>$ keactrl start -s dhcp4,dhcp_ddns</userinput>
</screen>
will only start the <command>kea-dhcp4</command> and
<command>kea-dhcp-ddns</command> servers and not
<command>kea-dhcp6</command>. Note that the <command>start</command>
and <command>reload</command> commands are different from
<command>stop</command> in such a way that for the former
<command>keactrl</command> will also check if the specified server
is enabled in the <filename>keactrl.conf</filename> configuration file.
If it is not enabled it will not be started (or reconfigured) even if
listed after the <command>-s</command> command line option. For the
<command>stop</command> command it is not checked if the server is
enabled in the configuration file and all the listed servers will be
stopped.
</para>
<para>
The following keywords can be used with the <command>-s</command>
command line option:
<itemizedlist>
<listitem><simpara>
<command>dhcp4</command> for <command>kea-dhcp4.</command>
</simpara></listitem>
<listitem><simpara>
<command>dhcp6</command> for <command>kea-dhcp6.</command>
</simpara></listitem>
<listitem><simpara>
<command>dhcp_ddns</command> for <command>kea-dhcp-ddns.</command>
</simpara></listitem>
<listitem><simpara>
<command>all</command> for all servers (default).
</simpara></listitem>
</itemizedlist>
</para>
</section>
</chapter>
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment