]>

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

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. (--server is a synonym for -s.) If absent, the command is sent to all servers enabled in the keactrl configuration file. If multiple servers are specified, they should be separated by commas with no intervening spaces.

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's processes. # prefix holds the location where the Kea is installed. prefix=@prefix@ # Location of Kea configuration file. kea_config_file=@sysconfdir@/@PACKAGE@/kea.conf # Location of Kea binaries. 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 # Start DHCPv4 server? dhcp4=yes # Start DHCPv6 server? dhcp6=yes # Start DHCP DDNS server? dhcp_ddns=no # Start Control Agent? ctrl_agent=yes # Be verbose? kea_verbose=no The dhcp4, dhcp6, dhcp_ddns and ctrl_agent parameters set to "yes" configure keactrl to manage (start, reconfigure) all servers, i.e. kea-dhcp4, kea-dhcp6, kea-dhcp-ddns and kea-ctrl-agent. 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 installations. If the default location needs to be altered for any reason, the paths specified with the dhcp4_srv, dhcp6_srv, dhcp_ddns_srv and ctrl_agent_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. Modification of the logging severity in a configuration file, as described in , will have no effect as long as the kea_verbose 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. 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.

The following commands are supported by keactrl: 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 -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 INFO/keactrl: Starting kea-ctrl-agent -c /usr/local/etc/kea/kea.conf -d Kea's servers create PID files upon startup. These files are used by keactrl to determine whether or not a given server is running. If one or more servers are running when the start command is issued, the output will look similar to the following: $ keactrl start 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. INFO/keactrl: kea-ctrl-agent appears to be running, see: PID 10931, PID file: /usr/local/var/kea/kea.kea-ctrl-agent.pid. 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. The following command stops all servers: $ keactrl stop INFO/keactrl: Stopping kea-dhcp4... INFO/keactrl: Stopping kea-dhcp6... INFO/keactrl: Stopping kea-dhcp-ddns... INFO/keactrl: Stopping kea-ctrl-agent... 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 are not running, an informational message is displayed as in the stop command output below. $ keactrl stop INFO/keactrl: kea-dhcp4 isn't running. INFO/keactrl: kea-dhcp6 isn't running. INFO/keactrl: kea-dhcp-ddns isn't running. INFO/keactrl: kea-ctrl-agent isn't running. 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 INFO/keactrl: Reloading kea-dhcp4... INFO/keactrl: Reloading kea-dhcp6... INFO/keactrl: Reloading kea-dhcp-ddns... INFO/keactrl: Reloading kea-ctrl-agent... If any of the servers are not running, an informational message is displayed as in the reload command output below. $ keactrl stop INFO/keactrl: kea-dhcp4 isn't running. INFO/keactrl: kea-dhcp6 isn't running. INFO/keactrl: kea-dhcp-ddns isn't running. INFO/keactrl: kea-ctrl-agent isn't running. 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 Control Agent: active Kea configuration file: /usr/local/etc/kea/kea.conf keactrl configuration file: /usr/local/etc/kea/keactrl.conf

The optional -s switch allows the selection of the servers to which keactrl command is issued. For example, the following instructs keactrl to stop the kea-dhcp4 and kea-dhcp6 servers and leave the kea-dhcp-ddns and kea-ctrl-agent running: $ keactrl stop -s dhcp4,dhcp6 Similarly, the following will only start the kea-dhcp4 and kea-dhcp-ddns servers and not: kea-dhcp6, kea-ctrl-agent. $ keactrl start -s dhcp4,dhcp_ddns 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. ctrl_agent for kea-ctrl-agent. all for all servers (default).