diff options
Diffstat (limited to 'doc/sphinx/arm/keactrl.rst')
| -rw-r--r-- | doc/sphinx/arm/keactrl.rst | 364 |
1 files changed, 364 insertions, 0 deletions
diff --git a/doc/sphinx/arm/keactrl.rst b/doc/sphinx/arm/keactrl.rst new file mode 100644 index 0000000..93768c3 --- /dev/null +++ b/doc/sphinx/arm/keactrl.rst @@ -0,0 +1,364 @@ +.. _keactrl: + +*********************************** +Managing Kea with :iscman:`keactrl` +*********************************** + +.. _keactrl-overview: + +Overview +======== + +:iscman:`keactrl` is a shell script which controls the startup, shutdown, and +reconfiguration of the Kea servers (:iscman:`kea-dhcp4`, :iscman:`kea-dhcp6`, +:iscman:`kea-dhcp-ddns`, :iscman:`kea-ctrl-agent`, and :iscman:`kea-netconf`). It also +provides the means for checking the current status of the servers and +determining the configuration files in use. + +:iscman:`keactrl` is available only when Kea is built from sources. When installing +Kea using native packages, the native ``systemd`` scripts are provided. See +:ref:`systemd` Section for details. + +.. _keactrl-usage: + +Command Line Options +==================== + +:iscman:`keactrl` is run as follows: + +.. code-block:: console + + # keactrl <command> [-c keactrl-config-file] [-s server[,server,...]] + +``<command>`` is one of the commands described in :ref:`keactrl-commands`. + +The optional ``-c keactrl-config-file`` switch allows specification of +an alternate :iscman:`keactrl` configuration file. (``--ctrl-config`` is a +synonym for ``-c``.) In the absence of ``-c``, :iscman:`keactrl` uses 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 :iscman:`keactrl` +configuration file. If multiple servers are specified, they should be +separated by commas with no intervening spaces. + +.. _keactrl-config-file: + +The :iscman:`keactrl` Configuration File +======================================== + +Depending on the administrator's requirements, it may not be +necessary to run all of the available servers. +The :iscman:`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: + +.. code-block:: bash + + # This is a configuration file for keactrl script which controls + # the startup, shutdown, reconfiguration and gathering the status + # of the Kea processes. + + # prefix holds the location where the Kea is installed. + prefix=@prefix@ + + # Location of Kea configuration file. + kea_dhcp4_config_file=@sysconfdir@/@PACKAGE@/kea-dhcp4.conf + kea_dhcp6_config_file=@sysconfdir@/@PACKAGE@/kea-dhcp6.conf + kea_dhcp_ddns_config_file=@sysconfdir@/@PACKAGE@/kea-dhcp-ddns.conf + kea_ctrl_agent_config_file=@sysconfdir@/@PACKAGE@/kea-ctrl-agent.conf + kea_netconf_config_file=@sysconfdir@/@PACKAGE@/kea-netconf.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 + netconf_srv=@sbindir@/kea-netconf + + # Start DHCPv4 server? + dhcp4=yes + + # Start DHCPv6 server? + dhcp6=yes + + # Start DHCP DDNS server? + dhcp_ddns=no + + # Start Control Agent? + ctrl_agent=yes + + # Start Netconf? + netconf=no + + # Be verbose? + kea_verbose=no + +.. note:: + + In the example above, strings of the form @something@ are replaced by + the appropriate values when Kea is installed. + +Setting the ``dhcp4``, ``dhcp6``, ``dhcp_ddns``, ``ctrl_agent``, and ``netconf`` +parameters set to "yes" configures :iscman:`keactrl` to manage (start, +reconfigure) all servers, i.e. :iscman:`kea-dhcp4`, :iscman:`kea-dhcp6`, +:iscman:`kea-dhcp-ddns`, :iscman:`kea-ctrl-agent`, and :iscman:`kea-netconf`. When any of +these parameters is set to "no", :iscman:`keactrl` ignores the +corresponding server when starting or reconfiguring Kea. Some daemons +(dhcp_ddns and netconf) are disabled by default. + +By default, Kea servers managed by :iscman:`keactrl` are located in +``[kea-install-dir]/sbin``. This should work for most installations. If +the default location needs to be altered, the paths +specified with the ``dhcp4_srv``, ``dhcp6_srv``, ``dhcp_ddns_srv``, +``ctrl_agent_srv``, and ``netconf_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 :ref:`logging`, will have no +effect as long as ``kea_verbose`` is set to "yes." Setting it to +"no" causes the server to use the logging levels specified in the +Kea configuration file. If no logging configuration is specified, the +default settings are used. + +.. note:: + + The verbosity for the server is set when it is started. Once started, + the verbosity can only be changed by stopping the server and starting + it again with the new value of the ``kea_verbose`` parameter. + +.. _keactrl-commands: + +Commands +======== + +The following commands are supported by :iscman:`keactrl`: + +- ``start`` - starts the 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. + +- ``version`` - prints out the version of the :iscman:`keactrl` tool itself, + together with the versions of the Kea daemons. + +Typical output from :iscman:`keactrl` when starting the servers looks similar +to the following: + +.. code-block:: console + + $ keactrl start + INFO/keactrl: Starting kea-dhcp4 -c /usr/local/etc/kea/kea-dhcp4.conf -d + INFO/keactrl: Starting kea-dhcp6 -c /usr/local/etc/kea/kea-dhcp6.conf -d + INFO/keactrl: Starting kea-dhcp-ddns -c /usr/local/etc/kea/kea-dhcp-ddns.conf -d + INFO/keactrl: Starting kea-ctrl-agent -c /usr/local/etc/kea/kea-ctrl-agent.conf -d + INFO/keactrl: Starting kea-netconf -c /usr/local/etc/kea/kea-netconf.conf -d + +Kea's servers create PID files upon startup. These files are used by +:iscman:`keactrl` to determine whether a given server is running. If one or more +servers are running when the start command is issued, the output +looks similar to the following: + +.. code-block:: console + + $ keactrl start + INFO/keactrl: kea-dhcp4 appears to be running, see: PID 10918, PID file: /usr/local/var/run/kea/kea.kea-dhcp4.pid. + INFO/keactrl: kea-dhcp6 appears to be running, see: PID 10924, PID file: /usr/local/var/run/kea/kea.kea-dhcp6.pid. + INFO/keactrl: kea-dhcp-ddns appears to be running, see: PID 10930, PID file: /usr/local/var/run/kea/kea.kea-dhcp-ddns.pid. + INFO/keactrl: kea-ctrl-agent appears to be running, see: PID 10931, PID file: /usr/local/var/run/kea/kea.kea-ctrl-agent.pid. + INFO/keactrl: kea-netconf appears to be running, see: PID 10123, PID file: /usr/local/var/run/kea/kea.kea-netconf.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 +may actually refer to processes unrelated to Kea. This condition will +cause :iscman:`keactrl` to decide that the servers are running, when in fact they +are not. In such a case the PID files listed in the :iscman:`keactrl` output +must be manually deleted. + +The following command stops all servers: + +.. code-block:: console + + $ keactrl stop + INFO/keactrl: Stopping kea-dhcp4... + INFO/keactrl: Stopping kea-dhcp6... + INFO/keactrl: Stopping kea-dhcp-ddns... + INFO/keactrl: Stopping kea-ctrl-agent... + INFO/keactrl: Stopping kea-netconf... + +Note that the ``stop`` command attempts to stop all servers +regardless of whether they are "enabled" in ``keactrl.conf``. If any +of the servers are not running, an informational message is displayed as +in the ``stop`` command output below. + +.. code-block:: console + + $ 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. + INFO/keactrl: kea-netconf 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 any servers that are enabled in the :iscman:`keactrl` configuration +file and that are currently running. When a server receives the SIGHUP signal +it rereads its configuration file and, if the new configuration is +valid, uses the new configuration. +If the new configuration proves to be invalid, the server retains its +current configuration; however, in some cases a fatal error message is logged +indicating that the server is no longer providing any service: a working +configuration must be loaded as soon as possible. + +A reload is executed as follows: + +.. code-block:: console + + $ 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. +:iscman:`kea-netconf` does not support the SIGHUP signal. If its +configuration has changed, please stop and restart it for the change to +take effect. + +.. code-block:: console + + $ 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. + INFO/keactrl: kea-netconf isn't running. + +.. note:: + + NETCONF is an optional feature that is disabled by default and can be + enabled during compilation. If Kea was compiled without NETCONF + support, :iscman:`keactrl` does not provide + information about it. The NETCONF entries are still present in + the ``keactrl.conf`` file, but NETCONF status is not shown and other + commands ignore it. + +.. note:: + + Currently :iscman:`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, the log is written to the `syslog` file. + +Sometimes it is useful to check which servers are running. The +``status`` command reports this, with typical output that looks like: + +.. code-block:: console + + $ keactrl status + DHCPv4 server: active + DHCPv6 server: inactive + DHCP DDNS: active + Control Agent: active + Netconf agent: inactive + Kea configuration file: /usr/local/etc/kea/kea.conf + Kea DHCPv4 configuration file: /usr/local/etc/kea/kea-dhcp4.conf + Kea DHCPv6 configuration file: /usr/local/etc/kea/kea-dhcp6.conf + Kea DHCP DDNS configuration file: /usr/local/etc/kea/kea-dhcp-ddns.conf + Kea Control Agent configuration file: /usr/local/etc/kea/kea-ctrl-agent.conf + Kea Netconf configuration file: /usr/local/etc/kea/kea-netconf.conf + keactrl configuration file: /usr/local/etc/kea/keactrl.conf + +``keactrl status`` offers basic reporting capabilities. For more extensive insight +into Kea's health and status, consider deploying Stork. For details, see :ref:`stork`. + +.. _keactrl-overriding-servers: + +Overriding the Server Selection +=============================== + +The optional ``-s`` switch allows the selection of the server(s) to which +the :iscman:`keactrl` command is issued. For example, the following instructs +:iscman:`keactrl` to stop the :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` servers and +leave the :iscman:`kea-dhcp-ddns` and :iscman:`kea-ctrl-agent` running: + +.. code-block:: console + + $ keactrl stop -s dhcp4,dhcp6 + +Similarly, the following starts only the :iscman:`kea-dhcp4` and +:iscman:`kea-dhcp-ddns` servers, but not :iscman:`kea-dhcp6` or :iscman:`kea-ctrl-agent`. + +.. code-block:: console + + $ keactrl start -s dhcp4,dhcp_ddns + +Note that the behavior of the ``-s`` switch with the ``start`` and +``reload`` commands is different from its behavior with the ``stop`` +command. On ``start`` and ``reload``, :iscman:`keactrl` checks whether the +servers given as parameters to the ``-s`` switch are enabled in the +:iscman:`keactrl` configuration file; if not, the server is 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 :iscman:`kea-dhcp4`. + +- ``dhcp6`` for :iscman:`kea-dhcp6`. + +- ``dhcp_ddns`` for :iscman:`kea-dhcp-ddns`. + +- ``ctrl_agent`` for :iscman:`kea-ctrl-agent`. + +- ``netconf`` for :iscman:`kea-netconf`. + +- ``all`` for all servers (default). + +.. _systemd: + +Native Packages and ``systemd`` +=============================== + +:iscman:`keactrl` is a script that was developed to assist in managing Kea processes. +However, all modern operating systems have their own process-management scripts, +such as ``systemd``. In general, these native scripts should be used, +as they have several advantages. ``systemd`` scripts handle processes in a uniform +way, so Kea is handled in a similar fashion to HTTP or a mail +server. Second and more importantly, ``systemd`` allows dependencies to be defined +between services. For example, it is easy to specify that the Kea server should not start +until the network interfaces are operational. Using native scripts also has other benefits, such as +the ability to enable or disable services using commands, and the ability to temporarily start a disabled +service. + +Thus, it is recommended to use ``systemctl`` commands if they are available. Native +Kea packages do not provide :iscman:`keactrl`; ``systemctl`` service definitions are +provided instead. Consult the system documentation for details. + +Briefly, here are example commands to check status, start, stop, and restart various Kea daemons: + +.. code-block:: console + + # systemctl status kea-ctrl-agent + # systemctl start kea-dhcp4 + # systemctl stop kea-dhcp6 + # systemctl restart kea-dhcp-ddns + +Note that the service names may be slightly different between Linux distributions; in general, +we have followed the naming conventions in third-party packages. In particular, +some systems may not have the `isc-` prefix. |