1.. _keactrl: 2 3***************************** 4Managing Kea with ``keactrl`` 5***************************** 6 7.. _keactrl-overview: 8 9Overview 10======== 11 12``keactrl`` is a shell script which controls the startup, shutdown, and 13reconfiguration of the Kea servers (``kea-dhcp4``, ``kea-dhcp6``, 14``kea-dhcp-ddns``, ``kea-ctrl-agent``, and ``kea-netconf``). It also 15provides the means for checking the current status of the servers and 16determining the configuration files in use. 17 18``keactrl`` is available only when Kea is built from sources. When installing 19Kea using native packages, the native ``systemd`` scripts are provided. See 20:ref:`systemd` Section for details. 21 22.. _keactrl-usage: 23 24Command Line Options 25==================== 26 27``keactrl`` is run as follows: 28 29.. code-block:: console 30 31 # keactrl <command> [-c keactrl-config-file] [-s server[,server,...]] 32 33``<command>`` is one of the commands described in :ref:`keactrl-commands`. 34 35The optional ``-c keactrl-config-file`` switch allows specification of 36an alternate ``keactrl`` configuration file. (``--ctrl-config`` is a 37synonym for ``-c``.) In the absence of ``-c``, ``keactrl`` uses the 38default configuration file ``[kea-install-dir]/etc/kea/keactrl.conf``. 39 40The optional ``-s server[,server,...]`` switch selects the servers to 41which the command is issued. (``--server`` is a synonym for ``-s``.) If 42absent, the command is sent to all servers enabled in the ``keactrl`` 43configuration file. If multiple servers are specified, they should be 44separated by commas with no intervening spaces. 45 46.. _keactrl-config-file: 47 48The ``keactrl`` Configuration File 49================================== 50 51Depending on the administrator's requirements, it may not be 52necessary to run all of the available servers. 53The ``keactrl`` configuration file sets which servers are enabled and 54which are disabled. The default configuration file is 55``[kea-install-dir]/etc/kea/keactrl.conf``, but this can be overridden 56on a per-command basis using the ``-c`` switch. 57 58The contents of ``keactrl.conf`` are: 59 60.. code-block:: bash 61 62 # This is a configuration file for keactrl script which controls 63 # the startup, shutdown, reconfiguration and gathering the status 64 # of the Kea processes. 65 66 # prefix holds the location where the Kea is installed. 67 prefix=@prefix@ 68 69 # Location of Kea configuration file. 70 kea_dhcp4_config_file=@sysconfdir@/@PACKAGE@/kea-dhcp4.conf 71 kea_dhcp6_config_file=@sysconfdir@/@PACKAGE@/kea-dhcp6.conf 72 kea_dhcp_ddns_config_file=@sysconfdir@/@PACKAGE@/kea-dhcp-ddns.conf 73 kea_ctrl_agent_config_file=@sysconfdir@/@PACKAGE@/kea-ctrl-agent.conf 74 kea_netconf_config_file=@sysconfdir@/@PACKAGE@/kea-netconf.conf 75 76 # Location of Kea binaries. 77 exec_prefix=@exec_prefix@ 78 dhcp4_srv=@sbindir@/kea-dhcp4 79 dhcp6_srv=@sbindir@/kea-dhcp6 80 dhcp_ddns_srv=@sbindir@/kea-dhcp-ddns 81 ctrl_agent_srv=@sbindir@/kea-ctrl-agent 82 netconf_srv=@sbindir@/kea-netconf 83 84 # Start DHCPv4 server? 85 dhcp4=yes 86 87 # Start DHCPv6 server? 88 dhcp6=yes 89 90 # Start DHCP DDNS server? 91 dhcp_ddns=no 92 93 # Start Control Agent? 94 ctrl_agent=yes 95 96 # Start Netconf? 97 netconf=no 98 99 # Be verbose? 100 kea_verbose=no 101 102.. 103 104 .. note:: 105 106 In the example above, strings of the form @something@ are replaced by 107 the appropriate values when Kea is installed. 108 109Setting the ``dhcp4``, ``dhcp6``, ``dhcp_ddns``, ``ctrl_agent``, and ``netconf`` 110parameters set to "yes" configures ``keactrl`` to manage (start, 111reconfigure) all servers, i.e. ``kea-dhcp4``, ``kea-dhcp6``, 112``kea-dhcp-ddns``, ``kea-ctrl-agent``, and ``kea-netconf``. When any of 113these parameters is set to "no", ``keactrl`` ignores the 114corresponding server when starting or reconfiguring Kea. Some daemons 115(dhcp_ddns and netconf) are disabled by default. 116 117By default, Kea servers managed by ``keactrl`` are located in 118``[kea-install-dir]/sbin``. This should work for most installations. If 119the default location needs to be altered, the paths 120specified with the ``dhcp4_srv``, ``dhcp6_srv``, ``dhcp_ddns_srv``, 121``ctrl_agent_srv``, and ``netconf_srv`` parameters should be modified. 122 123The ``kea_verbose`` parameter specifies the verbosity of the servers 124being started. When ``kea_verbose`` is set to "yes," the logging level of 125the server is set to DEBUG. Modification of the logging severity in a 126configuration file, as described in :ref:`logging`, will have no 127effect as long as ``kea_verbose`` is set to "yes." Setting it to 128"no" causes the server to use the logging levels specified in the 129Kea configuration file. If no logging configuration is specified, the 130default settings are used. 131 132 .. note:: 133 134 The verbosity for the server is set when it is started. Once started, 135 the verbosity can only be changed by stopping the server and starting 136 it again with the new value of the ``kea_verbose`` parameter. 137 138.. _keactrl-commands: 139 140Commands 141======== 142 143The following commands are supported by ``keactrl``: 144 145- ``start`` - starts the selected servers. 146 147- ``stop`` - stops all running servers. 148 149- ``reload`` - triggers reconfiguration of the selected servers by 150 sending the SIGHUP signal to them. 151 152- ``status`` - returns the status of the servers (active or inactive) 153 and the names of the configuration files in use. 154 155- ``version`` - prints out the version of the ``keactrl`` tool itself, 156 together with the versions of the Kea daemons. 157 158Typical output from ``keactrl`` when starting the servers looks similar 159to the following: 160 161.. code-block:: console 162 163 $ keactrl start 164 INFO/keactrl: Starting kea-dhcp4 -c /usr/local/etc/kea/kea-dhcp4.conf -d 165 INFO/keactrl: Starting kea-dhcp6 -c /usr/local/etc/kea/kea-dhcp6.conf -d 166 INFO/keactrl: Starting kea-dhcp-ddns -c /usr/local/etc/kea/kea-dhcp-ddns.conf -d 167 INFO/keactrl: Starting kea-ctrl-agent -c /usr/local/etc/kea/kea-ctrl-agent.conf -d 168 INFO/keactrl: Starting kea-netconf -c /usr/local/etc/kea/kea-netconf.conf -d 169 170Kea's servers create PID files upon startup. These files are used by 171``keactrl`` to determine whether a given server is running. If one or more 172servers are running when the start command is issued, the output 173looks similar to the following: 174 175.. code-block:: console 176 177 $ keactrl start 178 INFO/keactrl: kea-dhcp4 appears to be running, see: PID 10918, PID file: /usr/local/var/run/kea/kea.kea-dhcp4.pid. 179 INFO/keactrl: kea-dhcp6 appears to be running, see: PID 10924, PID file: /usr/local/var/run/kea/kea.kea-dhcp6.pid. 180 INFO/keactrl: kea-dhcp-ddns appears to be running, see: PID 10930, PID file: /usr/local/var/run/kea/kea.kea-dhcp-ddns.pid. 181 INFO/keactrl: kea-ctrl-agent appears to be running, see: PID 10931, PID file: /usr/local/var/run/kea/kea.kea-ctrl-agent.pid. 182 INFO/keactrl: kea-netconf appears to be running, see: PID 10123, PID file: /usr/local/var/run/kea/kea.kea-netconf.pid. 183 184During normal shutdowns, these PID files are deleted; they may, however, 185be left over as remnants following a system crash. It is possible, 186though highly unlikely, that upon system restart the PIDs they contain 187may actually refer to processes unrelated to Kea. This condition will 188cause ``keactrl`` to decide that the servers are running, when in fact they 189are not. In such a case the PID files listed in the ``keactrl`` output 190must be manually deleted. 191 192The following command stops all servers: 193 194.. code-block:: console 195 196 $ keactrl stop 197 INFO/keactrl: Stopping kea-dhcp4... 198 INFO/keactrl: Stopping kea-dhcp6... 199 INFO/keactrl: Stopping kea-dhcp-ddns... 200 INFO/keactrl: Stopping kea-ctrl-agent... 201 INFO/keactrl: Stopping kea-netconf... 202 203Note that the ``stop`` command attempts to stop all servers 204regardless of whether they are "enabled" in ``keactrl.conf``. If any 205of the servers are not running, an informational message is displayed as 206in the ``stop`` command output below. 207 208.. code-block:: console 209 210 $ keactrl stop 211 INFO/keactrl: kea-dhcp4 isn't running. 212 INFO/keactrl: kea-dhcp6 isn't running. 213 INFO/keactrl: kea-dhcp-ddns isn't running. 214 INFO/keactrl: kea-ctrl-agent isn't running. 215 INFO/keactrl: kea-netconf isn't running. 216 217As already mentioned, the reconfiguration of each Kea server is 218triggered by the SIGHUP signal. The ``reload`` command sends the SIGHUP 219signal to any servers that are enabled in the ``keactrl`` configuration 220file and that are currently running. When a server receives the SIGHUP signal 221it rereads its configuration file and, if the new configuration is 222valid, uses the new configuration. A reload is executed as follows: 223 224.. code-block:: console 225 226 $ keactrl reload 227 INFO/keactrl: Reloading kea-dhcp4... 228 INFO/keactrl: Reloading kea-dhcp6... 229 INFO/keactrl: Reloading kea-dhcp-ddns... 230 INFO/keactrl: Reloading kea-ctrl-agent... 231 232If any of the servers are not running, an informational message is 233displayed as in the ``reload`` command output below. As of 234version 1.5.0, ``kea-netconf`` does not support the SIGHUP signal. If its 235configuration has changed, please stop and restart it for the change to 236take effect. 237 238.. code-block:: console 239 240 $ keactrl stop 241 INFO/keactrl: kea-dhcp4 isn't running. 242 INFO/keactrl: kea-dhcp6 isn't running. 243 INFO/keactrl: kea-dhcp-ddns isn't running. 244 INFO/keactrl: kea-ctrl-agent isn't running. 245 INFO/keactrl: kea-netconf isn't running. 246 247.. 248 249.. note:: 250 251 NETCONF is an optional feature that is disabled by default and can be 252 enabled during compilation. If Kea was compiled without NETCONF 253 support, ``keactrl`` does not provide 254 information about it. The NETCONF entries are still present in 255 the ``keactrl.conf`` file, but NETCONF status is not shown and other 256 commands ignore it. 257 258.. note:: 259 260 Currently ``keactrl`` does not report configuration failures when the 261 server is started or reconfigured. To check if the server's 262 configuration succeeded, the Kea log must be examined for errors. By 263 default, the log is written to the `syslog` file. 264 265Sometimes it is useful to check which servers are running. The 266``status`` command reports this, with typical output that looks like: 267 268.. code-block:: console 269 270 $ keactrl status 271 DHCPv4 server: active 272 DHCPv6 server: inactive 273 DHCP DDNS: active 274 Control Agent: active 275 Netconf agent: inactive 276 Kea configuration file: /usr/local/etc/kea/kea.conf 277 Kea DHCPv4 configuration file: /usr/local/etc/kea/kea-dhcp4.conf 278 Kea DHCPv6 configuration file: /usr/local/etc/kea/kea-dhcp6.conf 279 Kea DHCP DDNS configuration file: /usr/local/etc/kea/kea-dhcp-ddns.conf 280 Kea Control Agent configuration file: /usr/local/etc/kea/kea-ctrl-agent.conf 281 Kea Netconf configuration file: /usr/local/etc/kea/kea-netconf.conf 282 keactrl configuration file: /usr/local/etc/kea/keactrl.conf 283 284``keactrl status`` offers basic reporting capabilities. For more extensive insight 285into Kea's health and status, consider deploying Stork. For details, see :ref:`stork`. 286 287.. _keactrl-overriding-servers: 288 289Overriding the Server Selection 290=============================== 291 292The optional ``-s`` switch allows the selection of the server(s) to which 293the ``keactrl`` command is issued. For example, the following instructs 294``keactrl`` to stop the ``kea-dhcp4`` and ``kea-dhcp6`` servers and 295leave the ``kea-dhcp-ddns`` and ``kea-ctrl-agent`` running: 296 297.. code-block:: console 298 299 $ keactrl stop -s dhcp4,dhcp6 300 301Similarly, the following starts only the ``kea-dhcp4`` and 302``kea-dhcp-ddns`` servers, but not ``kea-dhcp6`` or ``kea-ctrl-agent``. 303 304.. code-block:: console 305 306 $ keactrl start -s dhcp4,dhcp_ddns 307 308Note that the behavior of the ``-s`` switch with the ``start`` and 309``reload`` commands is different from its behavior with the ``stop`` 310command. On ``start`` and ``reload``, ``keactrl`` checks whether the 311servers given as parameters to the ``-s`` switch are enabled in the 312``keactrl`` configuration file; if not, the server is ignored. For 313``stop``, however, this check is not made; the command is applied to all 314listed servers, regardless of whether they have been enabled in the 315file. 316 317The following keywords can be used with the ``-s`` command-line option: 318 319- ``dhcp4`` for ``kea-dhcp4``. 320 321- ``dhcp6`` for ``kea-dhcp6``. 322 323- ``dhcp_ddns`` for ``kea-dhcp-ddns``. 324 325- ``ctrl_agent`` for ``kea-ctrl-agent``. 326 327- ``netconf`` for ``kea-netconf``. 328 329- ``all`` for all servers (default). 330 331.. _systemd: 332 333Native Packages and ``systemd`` 334=============================== 335 336``keactrl`` is a script that was developed to assist in managing Kea processes. 337However, all modern operating systems have their own process-management scripts, 338such as ``systemd``. In general, these native scripts should be used, 339as they have several advantages. ``systemd`` scripts handle processes in a uniform 340way, so Kea is handled in a similar fashion to HTTP or a mail 341server. Second and more importantly, ``systemd`` allows dependencies to be defined 342between services. For example, it is easy to specify that the Kea server should not start 343until the network interfaces are operational. Using native scripts also has other benefits, such as 344the ability to enable or disable services using commands, and the ability to temporarily start a disabled 345service. 346 347Thus, it is recommended to use ``systemctl`` commands if they are available. Native 348Kea packages do not provide ``keactrl``; ``systemctl`` service definitions are 349provided instead. Consult the system documentation for details. 350 351Briefly, here are example commands to check status, start, stop, and restart various Kea daemons: 352 353.. code-block:: console 354 355 # systemctl status isc-kea-ctrl-agent 356 # systemctl start isc-kea-dhcp4-server 357 # systemctl stop isc-kea-dhcp6-server 358 # systemctl restart isc-kea-dhcp-ddns-server 359 360Note that the service names may be slightly different between Linux distributions; in general, 361we have followed the naming conventions in third-party packages. In particular, 362some systems may not have the `isc-` prefix. 363