Adding upstream version 2.5.7.upstream/2.5.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.