# Managing Kea with keactrl

## Overview

keactrl is a shell script which controls the startup, shutdown and reconfiguration of the Kea servers (`kea-dhcp4`, `kea-dhcp6` and `kea-dhcp-ddns`). It also provides the means for checking the current status of the servers and determining the configuration files in use.

## Command Line Options

`keactrl` is run as follows:

    keactrl <command> [-c keactrl-config-file] [-s server[,server,..]]

`<command>` is the one of the commands described in .

The optional `-c keactrl-config-file` switch allows specification of an alternate `keactrl` configuration file. (`--ctrl-config` is a synonym for `-c`.) In the absence of `-c`, `keactrl` will use the default configuration file `[kea-install-dir]/etc/kea/keactrl.conf`.

The optional `-s server[,server ...]` 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. (`--server` is a synonym for `-s`.) If multiple servers are specified, they should be separated by commas with no intervening spaces.

## The keactrl Configuration File

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 `[kea-install-dir]/etc/kea/keactrl.conf`, but this can be overridden on a per-command basis using the `-c` switch.

The contents of `keactrl.conf` are:

    # 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=/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/kea-dhcp4
    dhcp6_srv=${exec_prefix}/sbin/kea/kea-dhcp6
    dhcp_ddns_srv=${exec_prefix}/sbin/kea/kea-dhcp-ddns

    # Start DHCPv4 server?
    dhcp4=yes

    # Start DHCPv6 server?
    dhcp6=yes

    # Start DHCP DDNS server?
    dhcp_ddns=yes

    # Be verbose?
    kea_verbose=no

The `dhcp4`, `dhcp6` and `dhcp_ddns` parameters set to "yes" configure `keactrl` to manage (start, reconfigure) all servers, i.e. `kea-dhcp4`, `kea-dhcp6` and `kea-dhcp-ddns`. When any of these parameters is set to "no" the `keactrl` will ignore the corresponding server when starting or reconfiguring Kea.

By default, Kea servers managed by `keactrl` are located in `[kea-install-dir]/sbin`. This should work for most of the installations. If the default location needs to be altered for any reason, the paths specified with the `dhcp4_srv`, `dhcp6_srv` and `dhcp_ddns_srv` parameters should be modified.

The `kea_verbose` parameter specifies the verbosity of the servers being started. When `kea_verbose` is set to "yes" the logging level of the server is set to DEBUG. Otherwise, the default logging level is used.

The verbosity for the server is set 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 `kea_verbose` parameter.

## Commands

The following commands are supported by `keactrl` to perform specific operations on the Kea servers:

- `start` - starts selected servers.

- `stop` - stops all running servers.

- `reload` - triggers reconfiguration of the selected servers by sending the SIGHUP signal to them.

- `status` - returns the status of the servers (active or inactive) and the names of the configuration files in use.

Typical output from `keactrl` when starting the servers looks similar to the following:

    $ keactrl start
    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

The following command stops all servers:

    $ keactrl stop
    INFO/keactrl: Skip sending signal 15 to process kea-dhcp6: process is not running

Note that the `stop` will attempt to stop all servers regardless of whether they are "enabled" in the `keactrl.conf`. If any of the servers is not running, an informational message is displayed as in the `stop` command output above.

As already mentioned, the reconfiguration of each Kea server is triggered by the SIGHUP signal. The `reload` command sends the SIGHUP signal to the servers that are enabled in the `keactrl` 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:

    $ keactrl reload

Currently `keactrl` 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.

Sometimes it is useful to check which servers are running. The `status` reports this, typical output looking like:

    $ keactrl status
    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

## Overriding the Server Selection

The optional `-s` switch allows the selection of the servers to which `keactrl` command is issued. For example,

    $ keactrl stop -s dhcp4,dhcp6

... instructs `keactrl` to stop the `kea-dhcp4` and `kea-dhcp6` servers and leave the `kea-dhcp-ddns` running.

Similarly,

    $ keactrl start -s dhcp4,dhcp_ddns

... will only start the `kea-dhcp4` and `kea-dhcp-ddns` servers and not `kea-dhcp6`.

Note that the behavior of the `-s` switch with the `start` and `reload` commands is different to its behavior with the `stop` command. On `start` and `reload`, `keactrl` will check if the servers given as parameters to the `-s` switch are enabled in the `keactrl` configuration file: if not, the server will be ignored. For `stop` however, this check is not made: the command is applied to all listed servers, regardless of whether they have been enabled in the file.

The following keywords can be used with the `-s` command line option:

- `dhcp4` for `kea-dhcp4.`

- `dhcp6` for `kea-dhcp6.`

- `dhcp_ddns` for `kea-dhcp-ddns.`

- `all` for all servers (default).