Skip to content
GitLab
Projects
Groups
Snippets
/
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Menu
Open sidebar
Sebastian Schrader
Kea
Commits
ea3e3f04
Commit
ea3e3f04
authored
Jul 10, 2014
by
Stephen Morris
Browse files
[3466] Edits to the documentation made as part of the review.
parent
38835b62
Changes
2
Hide whitespace changes
Inline
Side-by-side
doc/guide/keactrl.xml
View file @
ea3e3f04
...
...
@@ -5,73 +5,79 @@
]>
<chapter
id=
"keactrl"
>
<title>
Managing Kea
Servers W
ith keactrl
</title>
<title>
Managing Kea
w
ith 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.
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
l
ine
o
ptions
</title>
<para>
The usage of the
<command>
keactrl
</command>
is:
<screen>
<title>
Command
L
ine
O
ptions
</title>
<para><command>
keactrl
</command>
is
run as follows
:
<screen>
keactrl
<
command
>
[-c keactrl-config-file] [-s server[,server,..]]
</screen>
</screen>
</para>
<para>
The
<command>
<
command
>
</command>
specifie
s the one of the commands
<command>
<
command
>
</command>
i
s 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.
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
<command>
[-s server[,server ...]]
</command>
parameter overrides
the list of servers to which the command is issued.
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>
keactrl Configuration File
</title>
<title>
The
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>
.
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 default
<filename>
keactrl.conf
</filename>
file holds the following
configuration:
<screen>
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=/
home/marcin/devel/kea-build
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/
b10
-dhcp4
dhcp6_srv=${exec_prefix}/sin/kea/
b10
-dhcp6
dhcp_ddns_srv=${exec_prefix}/sbin/kea/
b10
-dhcp-ddns
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
...
...
@@ -84,27 +90,27 @@ dhcp_ddns=yes
# Be verbose?
kea_verbose=no
</screen>
</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
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.
"no" the
<command>
keactrl
</command>
will
ignore
the corresponding server
when starting or reconfiguring Kea
.
</para>
<para>
By default, Kea
processe
s managed by
<command>
keactrl
</command>
are
located in
the
<filename>
[kea-install-dir]/sbin
</filename>
. This
should work for most of the installations.
However, i
f 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>
,
By default, Kea
server
s managed by
<command>
keactrl
</command>
are
located in
<filename>
[kea-install-dir]/sbin
</filename>
. This
should work for most of the installations.
I
f 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.
parameters
should be modified
.
</para>
<para>
...
...
@@ -116,7 +122,7 @@ kea_verbose=no
<note>
<para>
The verbosity for the server is s
pecified
when it is started. Once
The verbosity for the server is s
et
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.
...
...
@@ -141,103 +147,102 @@ kea_verbose=no
</simpara></listitem>
<listitem><simpara>
<command>
status
</command>
- returns the status of the servers (active
or inactive) and the
<command>
keactrl
</command>
configuration
data
.
or inactive) and the
names of the
configuration
files in use
.
</simpara></listitem>
</itemizedlist>
</para>
<para>
T
he t
ypical output from
the
<command>
keactrl
</command>
when starting
<para>
Typical output from
<command>
keactrl
</command>
when starting
the servers looks similar to the following:
<screen>
<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>
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>
<screen>
<userinput>
$ keactrl stop
</userinput>
INFO/keactrl: Skip sending signal 15 to process kea-dhcp6: process is not running
</screen>
</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
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
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 server
s:
<screen>
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 follow
s:
<screen>
<userinput>
$ keactrl reload
</userinput>
</screen>
</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>
.
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. 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>
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>
</screen>
</para>
</section>
<section
id=
"keactrl-overriding-servers"
>
<title>
Overriding Server
s
Selection
</title>
<title>
Overriding
the
Server Selection
</title>
<para>
The
<command>
[
-s
server[,server]]
</command>
command line option
allows for
selecti
ng
the servers to which
the
<command>
keactrl
</command>
command is issued. For example
:
<screen>
The
optional
<command>
-s
</command>
switch allows
the
selecti
on of
the servers to which
<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
</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>
Similarly
,
<screen>
<userinput>
$ keactrl start -s dhcp4,dhcp_ddns
</userinput>
</screen>
will only start the
<command>
kea-dhcp4
</command>
and
</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.
<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>
...
...
src/bin/keactrl/keactrl.xml
View file @
ea3e3f04
...
...
@@ -30,7 +30,7 @@
<refnamediv>
<refname>
keactrl
</refname>
<refpurpose>
Shell script for managing
the Kea servers
</refpurpose>
<refpurpose>
Shell script for managing
Kea
</refpurpose>
</refnamediv>
<docinfo>
...
...
@@ -52,24 +52,21 @@
<refsect1>
<title>
DESCRIPTION
</title>
<para>
<command>
keactrl
</command>
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.
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>
<command>
keactrl
</command>
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 [kea-install-dir]/etc/kea/.
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
...
...
@@ -91,21 +88,21 @@
<varlistentry>
<term>
start
</term>
<listitem>
<para>
Start servers.
</para>
<para>
Start
the
servers.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
stop
</term>
<listitem>
<para>
Stop servers.
</para>
<para>
Stop
the
servers.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
reload
</term>
<listitem>
<para>
Reconfigure servers
.
</para>
<para>
Instructs the servers to re-read the kea configuration file
.
</para>
</listitem>
</varlistentry>
...
...
@@ -126,8 +123,9 @@
<term><option>
-c|--ctrl-config
<replaceable
class=
"parameter"
>
keactrl-config-file
</replaceable></option></term>
<listitem>
<para>
Override the default location of the
<command>
keactrl
</command>
configuration file.
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>
...
...
@@ -136,8 +134,9 @@
<term><option>
-s|--server
<replaceable
class=
"parameter"
>
server[,server,...]
</replaceable></option></term>
<listitem>
<para>
Specify a comma separated list of servers to which the command
should be issued. The acceptable values are:
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>
...
...
Write
Preview
Supports
Markdown
0%
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment