kea/doc/guide/keactrl.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>