Commit fa9570d1 authored by Marcin Siodelski's avatar Marcin Siodelski

[master] Merge branch 'trac3466'

parents 2065805e ea3e3f04
......@@ -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 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 (<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 determining the configuration files in use.
</para>
</section>
<section id="keactrl-usage">
<title>Command Line Options</title>
<para><command>keactrl</command> is run as follows:
<screen>
keactrl &lt;command&gt; [-c keactrl-config-file] [-s server[,server,..]]
</screen>
</para>
<para>
<command>&lt;command&gt;</command> is the one of the commands
described in <xref linkend="keactrl-commands"/>.
</para>
<para>
The optional <command>-c keactrl-config-file</command> switch
allows specification of an alternate <command>keactrl</command>
configuration file. (<command>--ctrl-config</command> is a synonym for
<command>-c</command>.) In the absence of <command>-c</command>,
<command>keactrl</command> will use the default configuration
file <filename>[kea-install-dir]/etc/kea/keactrl.conf</filename>.
</para>
<para>
The optional <command>-s server[,server ...]</command> switch selects
the servers to which the command is issued. If absent,
the command is sent to all servers enabled in the keactrl
configuration file. (<command>--server</command> is a synonym for
<command>-s</command>.) If multiple servers are specified, they
should be separated by commas with no intervening spaces.
</para>
</section>
<section id="keactrl-config-file">
<title>The keactrl Configuration File</title>
<para>
Depending on requirements, not all of the available servers need
be run. The keactrl configuration file sets which servers are
enabled and which are disabled. The default configuration
file is <filename>[kea-install-dir]/etc/kea/keactrl.conf</filename>,
but this can be overridden on a per-command basis using the
<command>-c</command> switch.
</para>
<para>
The contents of <filename>keactrl.conf</filename> are:
<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=/usr/local
# 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/kea-dhcp4
dhcp6_srv=${exec_prefix}/sin/kea/kea-dhcp6
dhcp_ddns_srv=${exec_prefix}/sbin/kea/kea-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 ignore
the corresponding server when starting or reconfiguring Kea.
</para>
<para>
By default, Kea servers managed by <command>keactrl</command> are
located in <filename>[kea-install-dir]/sbin</filename>. This
should work for most of the installations. If the default
location needs to be altered for any reason, the paths
specified with the <parameter>dhcp4_srv</parameter>,
<parameter>dhcp6_srv</parameter> and <parameter>dhcp_ddns_srv</parameter>
parameters should be modified.
</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 set 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 names of the configuration files in use.
</simpara></listitem>
</itemizedlist>
</para>
<para>Typical output from <command>keactrl</command> when starting
the servers looks similar to the following:
<screen>
<userinput>$ keactrl start</userinput>
INFO/keactrl: Starting kea-dhcp4 -c /usr/local/etc/kea/kea.conf
INFO/keactrl: Starting kea-dhcp6 -c /usr/local/etc/kea/kea.conf
INFO/keactrl: Starting kea-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 of whether they are "enabled" in the <filename>keactrl.conf</filename>.
If any of the servers is not running, an 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 the servers that are enabled in
the <command>keactrl</command> configuration file and are
currently running. When a server receives the SIGHUP signal it
re-reads its configuration file and, if the new configuration is
valid, uses the new configuration. A reload is executed as follows:
<screen>
<userinput>$ keactrl reload</userinput>
</screen>
</para>
<note>
<para>
Currently <command>keactrl</command> does not report configuration
failures when the server is started or reconfigured. To check if
the server's configuration succeeded the Kea log must be examined
for errors. By default, this is written to the syslog file.
</para>
</note>
<para>
Sometimes it is useful to check which servers are running. The
<command>status</command> reports this, typical output looking like:
<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 the Server Selection</title>
<para>
The optional <command>-s</command> switch allows
the selection of the servers to which <command>keactrl</command>
command is issued. For example,
<screen>
<userinput>$ keactrl stop -s dhcp4,dhcp6</userinput>
</screen>
... instructs <command>keactrl</command> to 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>.
</para>
<para>
Note that the behavior of the <command>-s</command> switch
with the <command>start</command> and <command>reload</command> commands
is different to its behavior with the <command>stop</command> command.
On <command>start</command> and <command>reload</command>,
<command>keactrl</command> will check if the servers given as
parameters to the <command>-s</command> switch are
enabled in the <command>keactrl</command> configuration file:
if not, the server will be ignored. For <command>stop</command> however,
this check is not made: the command is applied to all listed servers,
regardless of whether they have been enabled in the file.
</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>
/keactrl
/kea.conf
/keactrl.conf
/keactrl.8
......@@ -7,8 +7,22 @@ SUBDIRS = . tests
sbin_SCRIPTS = keactrl
CONFIGFILES = keactrl.conf kea.conf
DISTCLEANFILES = keactrl $(CONFIGFILES)
EXTRA_DIST = keactrl.in keactrl.conf.in kea.conf.in
man_MANS = keactrl.8
DISTCLEANFILES = keactrl $(CONFIGFILES) $(man_MANS)
EXTRA_DIST = keactrl.in keactrl.conf.in kea.conf.in $(man_MANS) keactrl.xml
if GENERATE_DOCS
keactrl.8: keactrl.xml
@XSLTPROC@ --novalid --xinclude --nonet -o $@ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $(builddir)/keactrl.xml
else
$(man_MANS):
@echo Man generation disabled. Creating dummy $@. Configure with --enable-generate-docs to enable it.
@echo Man generation disabled. Remove this file, configure with --enable-generate-docs, and rebuild Kea > $@
endif
if INSTALL_CONFIGURATIONS
......
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2014 Internet Systems Consortium, Inc. ("ISC")
-
- Permission to use, copy, modify, and/or distribute this software for any
- purpose with or without fee is hereby granted, provided that the above
- copyright notice and this permission notice appear in all copies.
-
- THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
- REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
- AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
- LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<refentry>
<refentryinfo>
<date>July 3, 2014</date>
</refentryinfo>
<refmeta>
<refentrytitle>keactrl</refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo>Kea</refmiscinfo>
</refmeta>
<refnamediv>
<refname>keactrl</refname>
<refpurpose>Shell script for managing Kea</refpurpose>
</refnamediv>
<docinfo>
<copyright>
<year>2014</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
</docinfo>
<refsynopsisdiv>
<cmdsynopsis>
<command>keactrl</command>
<arg>command</arg>
<arg><option>-c <replaceable class="parameter">keactrl-config-file</replaceable></option></arg>
<arg><option>-s <replaceable class="parameter">server[,server,...]</replaceable></option></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>
keactrl is a shell script which controls the startup, shutdown
and reconfiguration of the Kea servers (<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 determining the configuration files in use.
</para>
</refsect1>
<refsect1>
<title>CONFIGURATION FILE</title>
<para>
Depending on requirements, not all of the available servers need
be run. The keactrl configuration file sets which servers are
enabled and which are disabled. By default the configuration
file is <filename>[kea-install-dir]/etc/kea/keactrl.conf</filename>.
</para>
<para>
See the Kea Administrator's Guide for the documentation of the parameters
in the <command>keactrl</command> configuration file.
</para>
</refsect1>
<refsect1>
<title>OPTIONS</title>
<variablelist>
<varlistentry>
<term><option><replaceable class="parameter">command</replaceable></option></term>
<listitem>
<para>
Command to be issued to the servers. It can be one of the following:
</para>
<variablelist>
<varlistentry>
<term>start</term>
<listitem>
<para>Start the servers.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>stop</term>
<listitem>
<para>Stop the servers.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>reload</term>
<listitem>
<para>Instructs the servers to re-read the kea configuration file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>status</term>
<listitem>
<para>Print the status of the servers.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-c|--ctrl-config <replaceable class="parameter">keactrl-config-file</replaceable></option></term>
<listitem>
<para>
Specify the <command>keactrl</command> configuration file. Without
this switch, the <command>keactrl</command> will attempt to use the
file <filename>[kea-install-dir]/etc/kea/keactrl.conf</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-s|--server <replaceable class="parameter">server[,server,...]</replaceable></option></term>
<listitem>
<para>
Specifies a subset of the enabled servers to which the command should be issued.
The list of servers should be separated by commas with no intervening spaces.
Acceptable values are:
</para>
<variablelist>
<varlistentry>
<term>dhcp4</term>
<listitem>
<para>DHCPv4 server (<command>kea-dhcp4</command>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>dhcp6</term>
<listitem>
<para>DHCPv6 server (<command>kea-dhcp6</command>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>dhcp_ddns</term>
<listitem>
<para>DHCP DDNS server (<command>kea-dhcp-ddns</command>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>all</term>
<listitem>
<para>All servers (default).</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>kea-dhcp4</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>
<citerefentry>
<refentrytitle>kea-dhcp6</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>
<citerefentry>
<refentrytitle>kea-dhcp-ddns</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>
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