mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-09-02 15:05:16 +00:00
Code Issues Releases Wiki Activity

Fixing links, updating text for conversion from docbook to sphinx; dhcp4-srv.rst is only partially done, and the links within the other files (including those committed yesterday) need to be changed to the correct format

Browse Source
This commit is contained in:
Suzanne Goldlust
2019-06-18 20:07:02 -04:00
committed by Michal Nowikowski
parent 0fa5e85a51
commit 30eaa6f2a6
3 changed files with 349 additions and 463 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
doc/guide/agent.rst
View File

@@ -17,14 +17,14 @@ whether the command should be handled by the CA or forwarded is made by
checking the value of the "service" parameter, which may be included in checking the value of the "service" parameter, which may be included in
the command from the controlling client. The details of the supported the command from the controlling client. The details of the supported
commands, as well as their structures, are provided in commands, as well as their structures, are provided in
`??? <#ctrl-channel>`__. :ref:`Management API <ctrl-channel>`.
The CA can use hook libraries to provide support for additional commands The CA can use hook libraries to provide support for additional commands
or custom behavior of existing commands. Such hook libraries must or custom behavior of existing commands. Such hook libraries must
implement callouts for the "control_command_receive" hook point. Details implement callouts for the "control_command_receive" hook point. Details
about creating new hook libraries and supported hook points can be found about creating new hook libraries and supported hook points can be found
in the `Kea Developer's in the :ref:`Kea Developer's
Guide <https://jenkins.isc.org/job/Kea_doc/doxygen/>`__. Guide <https://jenkins.isc.org/job/Kea_doc/doxygen/>`.
The CA processes received commands according to the following algorithm: The CA processes received commands according to the following algorithm:
@@ -89,15 +89,15 @@ provided above, the RESTful service will be available under the URL of
``http://10.20.30.40:8080/``. If these parameters are not specified, the ``http://10.20.30.40:8080/``. If these parameters are not specified, the
default URL is http://127.0.0.1:8000/ default URL is http://127.0.0.1:8000/
As mentioned in `Overview <#agent-overview>`__, the CA can forward As mentioned in :ref:`Overview <agent-overview>`, the CA can forward
received commands to the Kea servers for processing. For example, received commands to the Kea servers for processing. For example,
``config-get`` is sent to retrieve the configuration of one of the Kea ``config-get`` is sent to retrieve the configuration of one of the Kea
services. When the CA receives this command, including a ``service`` services. When the CA receives this command, including a ``service``
parameter indicating that the client desires to retrieve the parameter indicating that the client wishes to retrieve the
configuration of the DHCPv4 server, the CA forwards this command to that configuration of the DHCPv4 server, the CA forwards the command to that
server and passes the received response back to the client. More about server and passes the received response back to the client. More about
the ``service`` parameter and the general structure of commands can be the ``service`` parameter and the general structure of commands can be
found in `??? <#ctrl-channel>`__. found in :ref:`Management API <ctrl-channel>`.
The CA uses UNIX domain sockets to forward control commands and receive The CA uses UNIX domain sockets to forward control commands and receive
responses from other Kea services. The ``dhcp4``, ``dhcp6``, and ``d2`` responses from other Kea services. The ``dhcp4``, ``dhcp6``, and ``d2``
@@ -107,14 +107,14 @@ configuration above, the CA will connect to the DHCPv4 server via
Obviously, the DHCPv4 server must be configured to listen to connections Obviously, the DHCPv4 server must be configured to listen to connections
via this same socket. In other words, the command socket configuration via this same socket. In other words, the command socket configuration
for the DHCPv4 server and the CA (for this server) must match. Consult for the DHCPv4 server and the CA (for this server) must match. Consult
`??? <#dhcp4-ctrl-channel>`__, `??? <#dhcp6-ctrl-channel>`__ and :ref:`Management API for the DHCPv4 Server <dhcp4-ctrl-channel>`, :ref:`Management API for the DHCPv6 Server <dhcp6-ctrl-channel>` and
`??? <#d2-ctrl-channel>`__ to learn how the socket configuration is :ref:`Management API for the D2 Server <d2-ctrl-channel>` to learn how the socket configuration is
specified for the DHCPv4, DHCPv6 and D2 services. specified for the DHCPv4, DHCPv6, and D2 services.
**Warning** **Warning**
"dhcp4-server", "dhcp6-server" and "d2-server" were renamed to "dhcp4-server", "dhcp6-server", and "d2-server" were renamed to
"dhcp4", "dhcp6" and "d2" respectively in Kea 1.2. If you are "dhcp4", "dhcp6", and "d2" respectively in Kea 1.2. If you are
migrating from Kea 1.2, you must modify your CA configuration to use migrating from Kea 1.2, you must modify your CA configuration to use
this new naming convention. this new naming convention.
@@ -138,7 +138,7 @@ The ``hooks-libraries`` list contains the list of hooks libraries that
should be loaded by the CA, along with their configuration information should be loaded by the CA, along with their configuration information
specified with ``parameters``. specified with ``parameters``.
Please consult `??? <#logging>`__ for the details how to configure Please consult :ref:`Logging <logging>` for the details how to configure
logging. The CA's root logger's name is ``kea-ctrl-agent``, as given in logging. The CA's root logger's name is ``kea-ctrl-agent``, as given in
the example above. the example above.
@@ -198,7 +198,7 @@ server enables authentication of the clients using certificates.
# for the CA certificate. # for the CA certificate.
# #
# The client certificate must be deployed on the client system. # The client certificate must be deployed on the client system.
# In order to test the proxy configuration with 'curl' run # In order to test the proxy configuration with 'curl' run a
# command similar to the following: # command similar to the following:
# #
# curl -k --key kea-client.key --cert kea-client.crt -X POST \ # curl -k --key kea-client.key --cert kea-client.crt -X POST \
@@ -263,7 +263,7 @@ file it should use. For example:
$ ./kea-ctrl-agent -c /usr/local/etc/kea/kea-ctrl-agent.conf $ ./kea-ctrl-agent -c /usr/local/etc/kea/kea-ctrl-agent.conf
It can be started by keactrl as well (see `??? <#keactrl>`__). It can be started by keactrl as well (see :ref:`Managing Kea with keactrl <keactrl>`).
.. _agent-clients: .. _agent-clients:
@@ -271,4 +271,4 @@ Connecting to the Control Agent
=============================== ===============================
For an example of a tool that can take advantage of the RESTful API, see For an example of a tool that can take advantage of the RESTful API, see
`??? <#kea-shell>`__. :ref:`The Kea Shell <kea-shell>`.

758
doc/guide/dhcp4-srv.rst
View File

File diff suppressed because it is too large Load Diff

22
doc/guide/keactrl.rst
View File

@@ -26,7 +26,7 @@ Command Line Options
keactrl <command> [-c keactrl-config-file] [-s server[,server,...]] keactrl <command> [-c keactrl-config-file] [-s server[,server,...]]
``<command>`` is the one of the commands described in ``<command>`` is one of the commands described in
`Commands <#keactrl-commands>`__. `Commands <#keactrl-commands>`__.
The optional ``-c keactrl-config-file`` switch allows specification of The optional ``-c keactrl-config-file`` switch allows specification of
@@ -107,20 +107,20 @@ The ``dhcp4``, ``dhcp6``, ``dhcp_ddns``, ``ctrl_agent``, and ``netconf``
parameters set to "yes" will configure ``keactrl`` to manage (start, parameters set to "yes" will configure ``keactrl`` to manage (start,
reconfigure) all servers, i.e. ``kea-dhcp4``, ``kea-dhcp6``, reconfigure) all servers, i.e. ``kea-dhcp4``, ``kea-dhcp6``,
``kea-dhcp-ddns``, ``kea-ctrl-agent``, and ``kea-netconf``. When any of ``kea-dhcp-ddns``, ``kea-ctrl-agent``, and ``kea-netconf``. When any of
these parameters is set to "no," the ``keactrl`` will ignore the these parameters is set to "no", the ``keactrl`` will ignore the
corresponding server when starting or reconfiguring Kea. Some daemons corresponding server when starting or reconfiguring Kea. Some daemons
(ddns and netconf) are disabled by default. (ddns and netconf) are disabled by default.
By default, Kea servers managed by ``keactrl`` are located in By default, Kea servers managed by ``keactrl`` are located in
``[kea-install-dir]/sbin``. This should work for most installations. If ``[kea-install-dir]/sbin``. This should work for most installations. If
the default location needs to be altered for any reason, the paths the default location needs to be altered for any reason, the paths
specified with the ``dhcp4_srv``, ``dhcp6_srv``, ``dhcp_ddns_srv`` specified with the ``dhcp4_srv``, ``dhcp6_srv``, ``dhcp_ddns_srv``,
``ctrl_agent_srv``, and ``netconf_srv`` parameters should be modified. ``ctrl_agent_srv``, and ``netconf_srv`` parameters should be modified.
The ``kea_verbose`` parameter specifies the verbosity of the servers The ``kea_verbose`` parameter specifies the verbosity of the servers
being started. When ``kea_verbose`` is set to "yes" the logging level of 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 the server is set to DEBUG. Modification of the logging severity in a
configuration file, as described in `??? <#logging>`__, will have no configuration file, as described in :ref:`Logging <logging>`, will have no
effect as long as the ``kea_verbose`` is set to "yes." Setting it to 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 "no" will cause the server to use the logging levels specified in the
Kea configuration file. If no logging configuration is specified, the Kea configuration file. If no logging configuration is specified, the
@@ -183,7 +183,7 @@ be left over as remnants following a system crash. It is possible,
though highly unlikely, that upon system restart the PIDs they contain though highly unlikely, that upon system restart the PIDs they contain
may actually refer to processes unrelated to Kea. This condition will may actually refer to processes unrelated to Kea. This condition will
cause keactrl to decide that the servers are running, when in fact they 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 are not. In such a case the PID files listed in the keactrl output
must be manually deleted. must be manually deleted.
The following command stops all servers: The following command stops all servers:
@@ -198,7 +198,7 @@ The following command stops all servers:
INFO/keactrl: Stopping kea-netconf... INFO/keactrl: Stopping kea-netconf...
Note that the ``stop`` command will attempt to stop all servers Note that the ``stop`` command will attempt to stop all servers
regardless of whether they are "enabled" in the ``keactrl.conf``. If any regardless of whether they are "enabled" in ``keactrl.conf``. If any
of the servers are not running, an informational message is displayed as of the servers are not running, an informational message is displayed as
in the ``stop`` command output below. in the ``stop`` command output below.
@@ -213,8 +213,8 @@ in the ``stop`` command output below.
As already mentioned, the reconfiguration of each Kea server is As already mentioned, the reconfiguration of each Kea server is
triggered by the SIGHUP signal. The ``reload`` command sends the SIGHUP triggered by the SIGHUP signal. The ``reload`` command sends the SIGHUP
signal to the servers that are enabled in the ``keactrl`` configuration signal to any servers that are enabled in the ``keactrl`` configuration
file and are currently running. When a server receives the SIGHUP signal file and that are currently running. When a server receives the SIGHUP signal
it re-reads its configuration file and, if the new configuration is it re-reads its configuration file and, if the new configuration is
valid, uses the new configuration. A reload is executed as follows: valid, uses the new configuration. A reload is executed as follows:
@@ -260,7 +260,7 @@ take effect. This limitation will be removed in a future release.
default, this is written to the syslog file. default, this is written to the syslog file.
Sometimes it is useful to check which servers are running. The Sometimes it is useful to check which servers are running. The
``status`` reports this, with typical output that looks like: ``status`` command reports this, with typical output that looks like:
:: ::
@@ -283,7 +283,7 @@ Sometimes it is useful to check which servers are running. The
Overriding the Server Selection Overriding the Server Selection
=============================== ===============================
The optional ``-s`` switch allows the selection of the servers to which The optional ``-s`` switch allows the selection of the server(s) to which
the ``keactrl`` command is issued. For example, the following instructs the ``keactrl`` command is issued. For example, the following instructs
``keactrl`` to stop the ``kea-dhcp4`` and ``kea-dhcp6`` servers and ``keactrl`` to stop the ``kea-dhcp4`` and ``kea-dhcp6`` servers and
leave the ``kea-dhcp-ddns`` and ``kea-ctrl-agent`` running: leave the ``kea-dhcp-ddns`` and ``kea-ctrl-agent`` running:
@@ -300,7 +300,7 @@ Similarly, the following will start only the ``kea-dhcp4`` and
$ keactrl start -s dhcp4,dhcp_ddns $ keactrl start -s dhcp4,dhcp_ddns
Note that the behavior of the ``-s`` switch with the ``start`` and Note that the behavior of the ``-s`` switch with the ``start`` and
``reload`` commands is different to its behavior with the ``stop`` ``reload`` commands is different from its behavior with the ``stop``
command. On ``start`` and ``reload``, ``keactrl`` will check if the command. On ``start`` and ``reload``, ``keactrl`` will check if the
servers given as parameters to the ``-s`` switch are enabled in the servers given as parameters to the ``-s`` switch are enabled in the
``keactrl`` configuration file; if not, the server will be ignored. For ``keactrl`` configuration file; if not, the server will be ignored. For