|
|
@@ -0,0 +1,262 @@
|
|
|
+<?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 "—" >
|
|
|
+]>
|
|
|
+
|
|
|
+ <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 <command> [-c keactrl-config-file] [-s server[,server,..]]
|
|
|
+ </screen>
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ The <command><command></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>
|
Marcin Siodelski