keactrl.xml 10.3 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
14
15
16
      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.
17
18
19
20
      </para>
    </section>

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

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

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

      <para>
43
        The optional <command>-s server[,server ...]</command> switch selects
44
45
46
47
48
        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
49
        should be separated by commas with no intervening spaces.
50
51
52
53
      </para>
    </section>

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

      <para>
65
66
        The contents of <filename>keactrl.conf</filename> are:
<screen>
67
68
69
70
71
# 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.
72
prefix=/usr/local
73
74
75
76
77
78

# Location of Kea configuration file.
kea_config_file=${prefix}/etc/kea/kea.conf

# Location of Kea binaries.
exec_prefix=${prefix}
79
dhcp4_srv=${exec_prefix}/sbin/kea/kea-dhcp4
80
dhcp6_srv=${exec_prefix}/sbin/kea/kea-dhcp6
81
dhcp_ddns_srv=${exec_prefix}/sbin/kea/kea-dhcp-ddns
82
83
84
85
86
87
88
89
90
91
92
93

# Start DHCPv4 server?
dhcp4=yes

# Start DHCPv6 server?
dhcp6=yes

# Start DHCP DDNS server?
dhcp_ddns=yes

# Be verbose?
kea_verbose=no
94
</screen>
95
96
97
98
99
100
      </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,
101
        i.e. <command>kea-dhcp4</command>, <command>kea-dhcp6</command> and
102
        <command>kea-dhcp-ddns</command>. When any of these parameters is set to
103
104
        "no" the <command>keactrl</command> will ignore
        the corresponding server when starting or reconfiguring Kea.
105
106
107
      </para>

      <para>
108
109
110
111
112
        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>,
113
        <parameter>dhcp6_srv</parameter> and <parameter>dhcp_ddns_srv</parameter>
114
        parameters should be modified.
115
116
117
118
119
120
121
122
123
124
125
      </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>
126
          The verbosity for the server is set  when it is started. Once
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
          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
151
          or inactive) and the names of the configuration files in use.
152
153
154
155
        </simpara></listitem>
      </itemizedlist>
      </para>

156
      <para>Typical output from <command>keactrl</command> when starting
157
      the servers looks similar to the following:
158
<screen>
159
<userinput>$ keactrl start</userinput>
160
161
162
163
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>
164
165
166
      </para>

      <para>The following command stops all servers:
167
<screen>
168
169
<userinput>$ keactrl stop</userinput>
INFO/keactrl: Skip sending signal 15 to process kea-dhcp6: process is not running
170
</screen>
171
      Note that the <command>stop</command> will attempt to stop all servers
172
      regardless of whether they are "enabled" in the <filename>keactrl.conf</filename>.
173
      If any of the servers is not running, an informational message
174
175
176
177
      is displayed as in the <command>stop</command> command output above.
      </para>

      <para>
178
179
180
181
182
183
184
185
        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>
186
<userinput>$ keactrl reload</userinput>
187
</screen>
188
189
190
191
      </para>

      <note>
        <para>
192
193
194
195
          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.
196
197
198
199
        </para>
      </note>

      <para>
200
201
202
        Sometimes it is useful to check which servers are running. The
        <command>status</command> reports this, typical output looking like:
<screen>
203
204
205
206
207
208
<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
209
</screen>
210
211
212
213
      </para>
    </section>

    <section id="keactrl-overriding-servers">
214
      <title>Overriding the Server Selection</title>
215
      <para>
216
217
        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
218
219
220
221
        command is issued.  For example, the following
        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> server running:
222
<screen>
223
<userinput>$ keactrl stop -s dhcp4,dhcp6</userinput>
224
</screen>
225
226
227
      </para>

      <para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
228
229
230
231
        Similarly, the following
        will only start the <command>kea-dhcp4</command> and
        <command>kea-dhcp-ddns</command> servers and not
        <command>kea-dhcp6</command>.
232
<screen>
233
<userinput>$ keactrl start -s dhcp4,dhcp_ddns</userinput>
234
235
236
237
238
239
240
241
242
243
244
245
246
</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.
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
      </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>