keactrl.xml 13.2 KB
Newer Older
1 2 3 4 5 6 7
<?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">
8
    <title>Managing Kea with keactrl</title>
9 10 11 12

    <section id="keactrl-overview">
      <title>Overview</title>
      <para>keactrl is a shell script which controls the startup, shutdown
13
      and reconfiguration of the Kea servers (<command>kea-dhcp4</command>,
14 15 16 17
      <command>kea-dhcp6</command>, <command>kea-dhcp-ddns</command> and
      <command>kea-ctrl-agent</command>). It also provides the means for
      checking the current status of the servers and determining the
      configuration files in use.
18 19 20 21
      </para>
    </section>

    <section id="keactrl-usage">
22 23 24
      <title>Command Line Options</title>
      <para><command>keactrl</command> is run as follows:
<screen>
25
keactrl &lt;command&gt; [-c keactrl-config-file] [-s server[,server,..]]
26
</screen>
27 28 29
      </para>

      <para>
30
        <command>&lt;command&gt;</command> is the one of the commands
31 32 33 34
        described in <xref linkend="keactrl-commands"/>.
      </para>

      <para>
35 36 37 38 39 40
        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>.
41 42 43
      </para>

      <para>
44
        The optional <command>-s server[,server ...]</command> switch selects
45 46 47 48 49
        the servers to which the command is issued.
        (<command>--server</command> is a synonym for <command>-s</command>.)
        If absent, the command is sent to all servers enabled in the keactrl
        configuration file.
        If multiple servers are specified, they
50
        should be separated by commas with no intervening spaces.
51 52 53 54
      </para>
    </section>

    <section id="keactrl-config-file">
55
      <title>The keactrl Configuration File</title>
56
      <para>
57 58 59 60 61 62
        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.
63 64 65
      </para>

      <para>
66 67
        The contents of <filename>keactrl.conf</filename> are:
<screen>
68 69
# This is a configuration file for keactrl script which controls
# the startup, shutdown, reconfiguration and gathering the status
70
# of the Kea's processes.
71 72

# prefix holds the location where the Kea is installed.
73
prefix=@prefix@
74 75

# Location of Kea configuration file.
76
kea_config_file=@sysconfdir@/@PACKAGE@/kea.conf
77 78

# Location of Kea binaries.
79 80 81 82 83
exec_prefix=@exec_prefix@
dhcp4_srv=@sbindir@/kea-dhcp4
dhcp6_srv=@sbindir@/kea-dhcp6
dhcp_ddns_srv=@sbindir@/kea-dhcp-ddns
ctrl_agent_srv=@sbindir@/kea-ctrl-agent
84 85 86 87 88 89 90 91

# Start DHCPv4 server?
dhcp4=yes

# Start DHCPv6 server?
dhcp6=yes

# Start DHCP DDNS server?
92 93 94 95
dhcp_ddns=no

# Start Control Agent?
ctrl_agent=yes
96 97 98

# Be verbose?
kea_verbose=no
99
</screen>
100 101 102
      </para>

      <para>
103 104 105 106 107 108 109
        The <parameter>dhcp4</parameter>, <parameter>dhcp6</parameter>,
        <parameter>dhcp_ddns</parameter> and <parameter>ctrl_agent</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>, <command>kea-dhcp-ddns</command> and
        <command>kea-ctrl-agent</command>. When any of these parameters is set
        to "no" the <command>keactrl</command> will ignore
110
        the corresponding server when starting or reconfiguring Kea.
111 112 113
      </para>

      <para>
114 115
        By default, Kea servers managed by <command>keactrl</command> are
        located in <filename>[kea-install-dir]/sbin</filename>. This
116
        should work for most installations. If the default
117 118
        location needs to be altered for any reason, the paths
        specified with the <parameter>dhcp4_srv</parameter>,
119 120
        <parameter>dhcp6_srv</parameter>, <parameter>dhcp_ddns_srv</parameter>
        and <parameter>ctrl_agent_srv</parameter> parameters should be modified.
121 122 123 124 125 126
      </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.
127 128 129 130 131 132 133
        Modification of the logging severity in a configuration file, as
        described in <xref linkend="logging"/>, will have no effect as long
        as the <parameter>kea_verbose</parameter> is set to "yes". Setting
        it to "no" will cause the server to use the logging levels specified
        in the Kea configuration file for respective loggers. If no
        logging configuration is specified, the default settings will be
        used.
134 135 136 137
      </para>

      <note>
        <para>
138
          The verbosity for the server is set  when it is started. Once
139 140 141 142 143 144 145 146 147
          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>
148
      <para>The following commands are supported by <command>keactrl</command>:
149 150 151 152 153 154 155 156 157 158 159 160 161
      <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
162
          or inactive) and the names of the configuration files in use.
163 164 165 166
        </simpara></listitem>
      </itemizedlist>
      </para>

167
      <para>Typical output from <command>keactrl</command> when starting
168
      the servers looks similar to the following:
169
<screen>
170
<userinput>$ keactrl start</userinput>
171 172 173
INFO/keactrl: Starting kea-dhcp4 -c /usr/local/etc/kea/kea.conf -d
INFO/keactrl: Starting kea-dhcp6 -c /usr/local/etc/kea/kea.conf -d
INFO/keactrl: Starting kea-dhcp-ddns -c /usr/local/etc/kea/kea.conf -d
174
INFO/keactrl: Starting kea-ctrl-agent -c /usr/local/etc/kea/kea.conf -d
175
</screen>
176 177
      </para>

178
      <para>Kea's servers create PID files upon startup. These files are used
179
      by keactrl to determine whether or not a given server is running.  If
180
      one or more servers are running when the start command is issued, the
181
      output will look similar to the following:
182 183 184 185 186
<screen>
<userinput>$ keactrl start</userinput>
INFO/keactrl: kea-dhcp4 appears to be running, see: PID 10918, PID file: /usr/local/var/kea/kea.kea-dhcp4.pid.
INFO/keactrl: kea-dhcp6 appears to be running, see: PID 10924, PID file: /usr/local/var/kea/kea.kea-dhcp6.pid.
INFO/keactrl: kea-dhcp-ddns appears to be running, see: PID 10930, PID file: /usr/local/var/kea/kea.kea-dhcp-ddns.pid.
187
INFO/keactrl: kea-ctrl-agent appears to be running, see: PID 10931, PID file: /usr/local/var/kea/kea.kea-ctrl-agent.pid.
188 189 190 191 192 193 194 195 196 197
</screen>
      During normal shutdowns these PID files are deleted. They may, however,
      be left over as remnants following a system crash.  It is possible,
      though highly unlikely, that upon system restart the PIDs they contain
      actually refer to processes unrelated to Kea.  This condition will cause
      keactrl to decide that the servers are running, when in fact they are
      not.  In such a case the PID files as listed in the keactrl output
      must be manually deleted.
      </para>

198
      <para>The following command stops all servers:
199
<screen>
200
<userinput>$ keactrl stop</userinput>
201 202 203
INFO/keactrl: Stopping kea-dhcp4...
INFO/keactrl: Stopping kea-dhcp6...
INFO/keactrl: Stopping kea-dhcp-ddns...
204
INFO/keactrl: Stopping kea-ctrl-agent...
205
</screen>
206
      Note that the <command>stop</command> will attempt to stop all servers
207
      regardless of whether they are "enabled" in the <filename>keactrl.conf</filename>.
208 209 210 211 212 213 214
      If any of the servers are not running, an informational message
      is displayed as in the <command>stop</command> command output below.
<screen>
<userinput>$ keactrl stop</userinput>
INFO/keactrl: kea-dhcp4 isn't running.
INFO/keactrl: kea-dhcp6 isn't running.
INFO/keactrl: kea-dhcp-ddns isn't running.
215
INFO/keactrl: kea-ctrl-agent isn't running.
216
</screen>
217 218 219
      </para>

      <para>
220 221 222 223 224 225 226 227
        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>
228
<userinput>$ keactrl reload</userinput>
229 230 231
INFO/keactrl: Reloading kea-dhcp4...
INFO/keactrl: Reloading kea-dhcp6...
INFO/keactrl: Reloading kea-dhcp-ddns...
232
INFO/keactrl: Reloading kea-ctrl-agent...
233 234 235 236 237 238 239 240
</screen>
      If any of the servers are not running, an informational message
      is displayed as in the <command>reload</command> command output below.
<screen>
<userinput>$ keactrl stop</userinput>
INFO/keactrl: kea-dhcp4 isn't running.
INFO/keactrl: kea-dhcp6 isn't running.
INFO/keactrl: kea-dhcp-ddns isn't running.
241
INFO/keactrl: kea-ctrl-agent isn't running.
242
</screen>
243 244 245 246
      </para>

      <note>
        <para>
247 248 249 250
          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.
251 252 253 254
        </para>
      </note>

      <para>
255 256 257
        Sometimes it is useful to check which servers are running. The
        <command>status</command> reports this, typical output looking like:
<screen>
258 259 260 261
<userinput>$ keactrl status</userinput>
DHCPv4 server: active
DHCPv6 server: inactive
DHCP DDNS: active
262
Control Agent: active
263 264
Kea configuration file: /usr/local/etc/kea/kea.conf
keactrl configuration file: /usr/local/etc/kea/keactrl.conf
265
</screen>
266 267 268 269
      </para>
    </section>

    <section id="keactrl-overriding-servers">
270
      <title>Overriding the Server Selection</title>
271
      <para>
272 273
        The optional <command>-s</command> switch allows
        the selection of the servers to which <command>keactrl</command>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
274 275 276
        command is issued.  For example, the following
        instructs <command>keactrl</command> to stop the
        <command>kea-dhcp4</command> and <command>kea-dhcp6</command> servers
277 278
        and leave the <command>kea-dhcp-ddns</command> and
        <command>kea-ctrl-agent</command> running:
279
<screen>
280
<userinput>$ keactrl stop -s dhcp4,dhcp6</userinput>
281
</screen>
282 283 284
      </para>

      <para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
285 286
        Similarly, the following
        will only start the <command>kea-dhcp4</command> and
287 288
        <command>kea-dhcp-ddns</command> servers and not:
        <command>kea-dhcp6</command>, <command>kea-ctrl-agent</command>.
289
<screen>
290
<userinput>$ keactrl start -s dhcp4,dhcp_ddns</userinput>
291 292 293 294 295 296 297 298 299 300 301 302 303
</screen>
      </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.
304 305 306 307 308 309 310 311 312 313 314 315 316 317 318
      </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>
319 320 321
          <listitem><simpara>
            <command>ctrl_agent</command> for <command>kea-ctrl-agent.</command>
          </simpara></listitem>
322 323 324 325 326 327 328
          <listitem><simpara>
            <command>all</command> for all servers (default).
          </simpara></listitem>
        </itemizedlist>
      </para>
    </section>
  </chapter>