diff options
| author | Andrei Pavel <andrei@isc.org> | 2023-06-06 12:43:11 +0200 |
|---|---|---|
| committer | Andrei Pavel <andrei@isc.org> | 2023-06-14 19:26:11 +0200 |
| commit | f936be322227a7851d47f0bf10b152c260138258 (patch) | |
| tree | a8fe2f83dd44e1b76ce7d703da8c817280f4f099 /doc/sphinx/arm | |
| parent | [#2554] add 'iscman' anchor to all manpages (diff) | |
| download | kea-f936be322227a7851d47f0bf10b152c260138258.tar.xz kea-f936be322227a7851d47f0bf10b152c260138258.zip | |
[#2554] add 'iscman' references
The commands used were:
- find doc/sphinx/man -name '*.rst' | xargs grep -F '.. iscman' | cut -d ' ' -f 3 > /tmp/binaries
- for i in $(cat /tmp/binaries); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/:iscman:\`${i}\`/g"; done
Manual adjustment was required in a few places to:
- extend title lines
- realign table lines
Diffstat (limited to 'doc/sphinx/arm')
38 files changed, 320 insertions, 320 deletions
diff --git a/doc/sphinx/arm/admin.rst b/doc/sphinx/arm/admin.rst index d29b0f6e43..dbf83f6397 100644 --- a/doc/sphinx/arm/admin.rst +++ b/doc/sphinx/arm/admin.rst @@ -37,14 +37,14 @@ version, it will fail; administrative action is required to upgrade the schema. .. _kea-admin: -The ``kea-admin`` Tool -====================== +The :iscman:`kea-admin` Tool +============================ -To manage the databases, Kea provides the ``kea-admin`` tool. It can +To manage the databases, Kea provides the :iscman:`kea-admin` tool. It can initialize a new backend, check its version number, perform a backend upgrade, and dump lease data to a text file. -``kea-admin`` takes two mandatory parameters: ``command`` and +:iscman:`kea-admin` takes two mandatory parameters: ``command`` and ``backend``. Additional, non-mandatory options may be specified. The currently supported commands are: @@ -135,7 +135,7 @@ configuration file. (There are no plans to add a host reservations storage capability to this backend.) No special initialization steps are necessary for the memfile backend. -During the first run, both ``kea-dhcp4`` and ``kea-dhcp6`` create +During the first run, both :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` create an empty lease file if one is not present. Necessary disk-write permission is required. @@ -220,7 +220,7 @@ Usually the setting is configured in the [mysqld] section in ``/etc/mysql/my.cnf When setting up the MySQL database for the first time, the database area must be created within MySQL, and the MySQL user ID under which Kea will access the database must be set up. This needs to be done manually, -rather than via ``kea-admin``. +rather than via :iscman:`kea-admin`. To create the database: @@ -261,14 +261,14 @@ To create the database: mysql> quit Bye - Then use the ``kea-admin`` tool to create the database. + Then use the :iscman:`kea-admin` tool to create the database. .. code-block:: console $ kea-admin db-init mysql -u database-user -p database-password -n database-name While it is possible to create the database from within the MySQL client, we recommend - using the ``kea-admin`` tool as it performs some necessary validations to ensure Kea can + using the :iscman:`kea-admin` tool as it performs some necessary validations to ensure Kea can access the database at runtime. Among those checks is verification that the schema does not contain any pre-existing tables; any pre-existing tables must be removed manually. An additional check examines the user's ability to create functions and @@ -322,18 +322,18 @@ To create the database: mysql> quit Bye -If the tables were not created in Step 4, run the ``kea-admin`` tool +If the tables were not created in Step 4, run the :iscman:`kea-admin` tool to create them now: .. code-block:: console $ kea-admin db-init mysql -u database-user -p database-password -n database-name -Do not do this if the tables were created in Step 4. ``kea-admin`` +Do not do this if the tables were created in Step 4. :iscman:`kea-admin` implements rudimentary checks; it will refuse to initialize a database that contains any existing tables. To start from scratch, all data must be removed manually. (This process is a manual operation -on purpose, to avoid accidentally irretrievable mistakes by ``kea-admin``.) +on purpose, to avoid accidentally irretrievable mistakes by :iscman:`kea-admin`.) .. _mysql-upgrade: @@ -499,7 +499,7 @@ which the servers will access it. A number of steps are required: $ 5. At this point, create the database tables either - using the ``kea-admin`` tool, as explained in the next section + using the :iscman:`kea-admin` tool, as explained in the next section (recommended), or manually. To create the tables manually, enter the following command. PostgreSQL will prompt the administrator to enter the new user's password that was specified in Step 3. When the command @@ -561,21 +561,21 @@ which the servers will access it. A number of steps are required: may be necessary to restart PostgreSQL for the changes to take effect. -Initialize the PostgreSQL Database Using ``kea-admin`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Initialize the PostgreSQL Database Using :iscman:`kea-admin` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the tables were not created manually, do so now by -running the ``kea-admin`` tool: +running the :iscman:`kea-admin` tool: .. code-block:: console $ kea-admin db-init pgsql -u database-user -p database-password -n database-name -Do not do this if the tables were already created manually. ``kea-admin`` +Do not do this if the tables were already created manually. :iscman:`kea-admin` implements rudimentary checks; it will refuse to initialize a database that contains any existing tables. To start from scratch, all data must be removed manually. (This process is a manual operation -on purpose, to avoid accidentally irretrievable mistakes by ``kea-admin``.) +on purpose, to avoid accidentally irretrievable mistakes by :iscman:`kea-admin`.) .. _pgsql-upgrade: diff --git a/doc/sphinx/arm/agent.rst b/doc/sphinx/arm/agent.rst index b29fe3e804..b9671908c2 100644 --- a/doc/sphinx/arm/agent.rst +++ b/doc/sphinx/arm/agent.rst @@ -198,7 +198,7 @@ should be loaded by the CA, along with their configuration information specified with ``parameters``. Please consult :ref:`logging` for the details on 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 :iscman:`kea-ctrl-agent`, as given in the example above. .. _agent-secure-connection: @@ -244,14 +244,14 @@ Configuring only one or two string parameters results in an error. mutually authenticated, but there is no proof they are the same as for the HTTP authentication. -The ``kea-shell`` tool also supports TLS. +The :iscman:`kea-shell` tool also supports TLS. .. _agent-launch: Starting and Stopping the Control Agent ======================================= -``kea-ctrl-agent`` accepts the following command-line switches: +:iscman:`kea-ctrl-agent` accepts the following command-line switches: - ``-c file`` - specifies the configuration file. @@ -263,15 +263,15 @@ Starting and Stopping the Control Agent verbosity, e.g. when debugging. - ``-t file`` - specifies the configuration file to be tested. - ``kea-netconf`` attempts to load it and conducts sanity checks; + :iscman:`kea-netconf` attempts to load it and conducts sanity checks; certain checks are possible only while running the actual server. The actual status is reported with exit code (0 = configuration appears valid, 1 = error encountered). Kea prints out log messages to standard output and error to standard error when testing the configuration. -- ``-v`` - displays the version of ``kea-ctrl-agent`` and exits. +- ``-v`` - displays the version of :iscman:`kea-ctrl-agent` and exits. -- ``-V`` - displays the extended version information for ``kea-ctrl-agent`` +- ``-V`` - displays the extended version information for :iscman:`kea-ctrl-agent` and exits. The listing includes the versions of the libraries dynamically linked to Kea. @@ -303,7 +303,7 @@ file it should use. For example: $ ./kea-ctrl-agent -c /usr/local/etc/kea/kea-ctrl-agent.conf -It can be started by ``keactrl`` as well (see :ref:`keactrl`). +It can be started by :iscman:`keactrl` as well (see :ref:`keactrl`). .. _agent-clients: diff --git a/doc/sphinx/arm/config-backend.rst b/doc/sphinx/arm/config-backend.rst index 58d6b1afb7..f13dcf2a35 100644 --- a/doc/sphinx/arm/config-backend.rst +++ b/doc/sphinx/arm/config-backend.rst @@ -175,7 +175,7 @@ C client libraries must be installed, as explained in :ref:`dhcp-install-configu .. note:: An existing database schema must be upgraded to the latest schema - required by the particular Kea version using the ``kea-admin`` tool, + required by the particular Kea version using the :iscman:`kea-admin` tool, as described in :ref:`kea-admin`. The ``cb_cmds`` premium hook library, which is available to ISC's paid support diff --git a/doc/sphinx/arm/config.rst b/doc/sphinx/arm/config.rst index 0d7f1c8034..2ae6e5043e 100644 --- a/doc/sphinx/arm/config.rst +++ b/doc/sphinx/arm/config.rst @@ -19,7 +19,7 @@ commands over the Management API (see :ref:`ctrl-channel`) and for communicating between DHCP servers and the DDNS update daemon. Typical usage assumes that the servers are started from the command -line, either directly or using a script, e.g. ``keactrl``. The +line, either directly or using a script, e.g. :iscman:`keactrl`. The configuration file is specified upon startup using the ``-c`` parameter. .. _json-format: diff --git a/doc/sphinx/arm/congestion-handling.rst b/doc/sphinx/arm/congestion-handling.rst index dd6cdd2e94..68b7913036 100644 --- a/doc/sphinx/arm/congestion-handling.rst +++ b/doc/sphinx/arm/congestion-handling.rst @@ -43,7 +43,7 @@ configurable layer has been introduced which can make decisions on which packets to process, how to store them, and the order in which they are processed by the server. -The default packet queue implementation for both ``kea-dhcp4`` and ``kea-dhcp6`` +The default packet queue implementation for both :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` is a simple ring buffer. Once it reaches capacity, new packets get added to the back of the queue by discarding packets from the front of the queue. Rather than always discarding the newest packets, Kea now always @@ -62,7 +62,7 @@ for interested parties to experiment with their own solutions. ``isc::dhcp::PacketQueueMgr``, described in the `Kea Developer's Guide <https://reports.kea.isc.org/dev_guide/index.html>`__.) -Packet queue behavior is configured in both ``kea-dhcp4`` and ``kea-dhcp6`` +Packet queue behavior is configured in both :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` servers through an optional, top-level, configuration element, ``dhcp-queue-control``. Omitting this element disables packet queueing: @@ -86,14 +86,14 @@ where: exists so that custom implementations can be registered (via a hook library) and then selected. There is a default packet queue implementation that is pre-registered during server start up: - "kea-ring4" for ``kea-dhcp4`` and "kea-ring6" for ``kea-dhcp6``. + "kea-ring4" for :iscman:`kea-dhcp4` and "kea-ring6" for :iscman:`kea-dhcp6`. - ``capacity`` - this is the maximum number of packets the queue can hold before packets are discarded. The optimal value for this is extremely site-dependent. The default value is 64 for both "kea-ring4" and "kea-ring6". -The following example enables the default packet queue for ``kea-dhcp4``, +The following example enables the default packet queue for :iscman:`kea-dhcp4`, with a queue capacity of 250 packets: :: @@ -108,7 +108,7 @@ with a queue capacity of 250 packets: ... } -The following example enables the default packet queue for ``kea-dhcp6``, +The following example enables the default packet queue for :iscman:`kea-dhcp6`, with a queue capacity of 300 packets: :: diff --git a/doc/sphinx/arm/ctrl-channel.rst b/doc/sphinx/arm/ctrl-channel.rst index 5f0dd67913..7bd43bdb74 100644 --- a/doc/sphinx/arm/ctrl-channel.rst +++ b/doc/sphinx/arm/ctrl-channel.rst @@ -130,11 +130,11 @@ The following list shows the mapping of the values carried within the ``service`` parameter to the servers to which the commands are forwarded: -- ``dhcp4`` - the command is forwarded to the ``kea-dhcp4`` server. +- ``dhcp4`` - the command is forwarded to the :iscman:`kea-dhcp4` server. -- ``dhcp6`` - the command is forwarded to the ``kea-dhcp6`` server. +- ``dhcp6`` - the command is forwarded to the :iscman:`kea-dhcp6` server. -- ``d2`` - the command is forwarded to the ``kea-dhcp-ddns`` server. +- ``d2`` - the command is forwarded to the :iscman:`kea-dhcp-ddns` server. The server processing the incoming command sends a response of the form: diff --git a/doc/sphinx/arm/database-connectivity.rst b/doc/sphinx/arm/database-connectivity.rst index 6ece2686de..9a8cab9a17 100644 --- a/doc/sphinx/arm/database-connectivity.rst +++ b/doc/sphinx/arm/database-connectivity.rst @@ -3,7 +3,7 @@ ********************* Database Connectivity ********************* -The Kea servers (``kea-dhcp4`` and ``kea-dhcp6``) can be configured to use a variety of +The Kea servers (:iscman:`kea-dhcp4` and :iscman:`kea-dhcp6`) can be configured to use a variety of database backends for leases, hosts, and configuration. They can be configured to support automatic recovery when connectivity is lost, via the ``on-fail`` parameter. (The ``reconnect-wait-time`` and diff --git a/doc/sphinx/arm/ddns.rst b/doc/sphinx/arm/ddns.rst index 8bd1001dde..5ccac7ee62 100644 --- a/doc/sphinx/arm/ddns.rst +++ b/doc/sphinx/arm/ddns.rst @@ -9,10 +9,10 @@ The DHCP-DDNS Server Overview ======== -The DHCP-DDNS Server (``kea-dhcp-ddns``, known informally as D2) conducts +The DHCP-DDNS Server (:iscman:`kea-dhcp-ddns`, known informally as D2) conducts the client side of the Dynamic DNS protocol (DDNS, defined in `RFC 2136 <https://tools.ietf.org/html/rfc2136>`__) on behalf of the DHCPv4 -and DHCPv6 servers (``kea-dhcp4`` and ``kea-dhcp6`` respectively). The DHCP +and DHCPv6 servers (:iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` respectively). The DHCP servers construct DDNS update requests, known as NameChangeRequests (NCRs), based on DHCP lease change events and then post them to D2. D2 attempts to match each request to the appropriate DNS server(s) and @@ -76,7 +76,7 @@ or at the behest of that client. Conflict resolution can be indirectly enabled or disabled via the configuration parameter ``ddns-use-conflict-resolution``, supported -by both ``kea-dhcp4`` and ``kea-dhcp6``. These servers use this parameter to +by both :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6`. These servers use this parameter to set a flag within each NameChangeRequest they send that tells D2 whether conflict resolution should be employed for that request. By default, conflict resolution is enabled. For more details, please refer @@ -106,11 +106,11 @@ is supported by Kea beginning with release 2.1.2. Starting and Stopping the DHCP-DDNS Server ========================================== -``kea-dhcp-ddns`` is the Kea DHCP-DDNS server and, due to the nature of +:iscman:`kea-dhcp-ddns` is the Kea DHCP-DDNS server and, due to the nature of DDNS, it runs alongside either the DHCPv4 or DHCPv6 component (or both). Like other parts of Kea, it is a separate binary that can be run on its -own or through ``keactrl`` (see :ref:`keactrl`). In normal -operation, controlling ``kea-dhcp-ddns`` with ``keactrl`` is +own or through :iscman:`keactrl` (see :ref:`keactrl`). In normal +operation, controlling :iscman:`kea-dhcp-ddns` with :iscman:`keactrl` is recommended; however, it is also possible to run the DHCP-DDNS server directly. It accepts the following command-line switches: @@ -131,7 +131,7 @@ directly. It accepts the following command-line switches: it is embedded in the executable binary. - ``-t file`` - specifies the configuration file to be tested. - ``kea-dhcp-ddns`` attempts to load it and conducts sanity checks. + :iscman:`kea-dhcp-ddns` attempts to load it and conducts sanity checks. Certain checks are possible only while running the actual server. The actual status is reported with an exit code (0 = configuration looks okay, 1 = error encountered). Kea prints out log @@ -182,7 +182,7 @@ such a case it is necessary to manually delete the PID file. Configuring the DHCP-DDNS Server ================================ -Before starting the ``kea-dhcp-ddns`` module for the first time, a +Before starting the :iscman:`kea-dhcp-ddns` module for the first time, a configuration file must be created. The following default configuration is a template that can be customized to individual requirements. diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst index b1537eb8de..9ca294fb42 100644 --- a/doc/sphinx/arm/dhcp4-srv.rst +++ b/doc/sphinx/arm/dhcp4-srv.rst @@ -10,8 +10,8 @@ Starting and Stopping the DHCPv4 Server ======================================= It is recommended that the Kea DHCPv4 server be started and stopped -using ``keactrl`` (described in :ref:`keactrl`); however, it is also -possible to run the server directly via the ``kea-dhcp4`` command, which accepts +using :iscman:`keactrl` (described in :ref:`keactrl`); however, it is also +possible to run the server directly via the :iscman:`kea-dhcp4` command, which accepts the following command-line switches: - ``-c file`` - specifies the configuration file. This is the only @@ -34,7 +34,7 @@ the following command-line switches: as a DHCPv4 server sending responses to ports other than the standard ones is not able to handle regular DHCPv4 queries. -- ``-t file`` - specifies a configuration file to be tested. ``kea-dhcp4`` +- ``-t file`` - specifies a configuration file to be tested. :iscman:`kea-dhcp4` loads it, checks it, and exits. During the test, log messages are printed to standard output and error messages to standard error. The result of the test is reported through the exit code (0 = @@ -42,7 +42,7 @@ the following command-line switches: comprehensive; certain checks are possible only when running the server. -- ``-T file`` - specifies a configuration file to be tested. ``kea-dhcp4`` +- ``-T file`` - specifies a configuration file to be tested. :iscman:`kea-dhcp4` loads it, checks it, and exits. It performs extra checks beyond what ``-t`` offers, such as establishing database connections (for the lease backend, host reservations backend, configuration backend, and forensic logging @@ -1379,7 +1379,7 @@ Sending T1 (Option 58) and T2 (Option 59) According to `RFC 2131 <https://tools.ietf.org/html/rfc2131>`__, servers should send values for T1 and T2 that are 50% and 87.5% of the -lease lifetime, respectively. By default, ``kea-dhcp4`` does not send +lease lifetime, respectively. By default, :iscman:`kea-dhcp4` does not send either value; it can be configured to send values that are either specified explicitly or that are calculated as percentages of the lease time. The server's behavior is governed by a combination of configuration @@ -2921,7 +2921,7 @@ specified: Support for Long Options ------------------------ -The ``kea-dhcp4`` server partially supports long options (RFC3396). +The :iscman:`kea-dhcp4` server partially supports long options (RFC3396). Since Kea 2.1.6, the server accepts configuring long options and sub-options (longer than 255 bytes). The options and sub-options are stored internally in their unwrapped form and they can be processed as usual using the parser @@ -3346,8 +3346,8 @@ two instances of the ``vivco-suboptions`` option, each for a different vendor. DDNS for DHCPv4 --------------- -As mentioned earlier, ``kea-dhcp4`` can be configured to generate requests -to the DHCP-DDNS server, ``kea-dhcp-ddns``, (referred to herein as "D2") to +As mentioned earlier, :iscman:`kea-dhcp4` can be configured to generate requests +to the DHCP-DDNS server, :iscman:`kea-dhcp-ddns`, (referred to herein as "D2") to update DNS entries. These requests are known as NameChangeRequests or NCRs. Each NCR contains the following information: @@ -3363,9 +3363,9 @@ DDNS-related parameters are split into two groups: 1. Connectivity Parameters - These are parameters which specify where and how ``kea-dhcp4`` connects to + These are parameters which specify where and how :iscman:`kea-dhcp4` connects to and communicates with D2. These parameters can only be specified - within the top-level ``dhcp-ddns`` section in the ``kea-dhcp4`` + within the top-level ``dhcp-ddns`` section in the :iscman:`kea-dhcp4` configuration. The connectivity parameters are listed below: - ``enable-updates`` @@ -3440,9 +3440,9 @@ The default configuration and values would appear as follows: ... } -There are two parameters which determine if ``kea-dhcp4`` +There are two parameters which determine if :iscman:`kea-dhcp4` can generate DDNS requests to D2: the existing ``dhcp-ddns:enable-updates`` -parameter, which now only controls whether ``kea-dhcp4`` connects to D2; +parameter, which now only controls whether :iscman:`kea-dhcp4` connects to D2; and the new behavioral parameter, ``ddns-send-updates``, which determines whether DDNS updates are enabled at a given level (i.e. global, shared-network, or subnet). The following table shows how the two parameters function @@ -3481,7 +3481,7 @@ to add DNS entries or they were somehow lost by the DNS server. for servers with numerous clients that renew often. The second parameter added in Kea 1.9.1 is ``ddns-use-conflict-resolution``. -The value of this parameter is passed by ``kea-dhcp4`` to D2 with each DNS update +The value of this parameter is passed by :iscman:`kea-dhcp4` to D2 with each DNS update request. When ``true`` (the default value), D2 employs conflict resolution, as described in `RFC 4703 <https://tools.ietf.org/html/rfc4703>`__, when attempting to fulfill the update request. When ``false``, D2 simply attempts @@ -3516,11 +3516,11 @@ conflict with existing entries owned by other DHCPv4 clients. specific use cases. The best way to avoid unwanted DNS entries is to always ensure lease changes are processed through Kea, whether they are released, expire, or are deleted via the ``lease-del4`` command, prior to - reassigning either FQDNs or IP addresses. Doing so causes ``kea-dhcp4`` + reassigning either FQDNs or IP addresses. Doing so causes :iscman:`kea-dhcp4` to generate DNS removal requests to D2. The DNS entries Kea creates contain a value for TTL (time to live). -The ``kea-dhcp4`` server calculates that value based on +The :iscman:`kea-dhcp4` server calculates that value based on `RFC 4702, Section 5 <https://tools.ietf.org/html/rfc4702#section-5>`__, which suggests that the TTL value be 1/3 of the lease's lifetime, with a minimum value of 10 minutes. @@ -3536,11 +3536,11 @@ global, shared-network, and subnet levels. By default it is unspecified. DHCP-DDNS Server Connectivity ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For NCRs to reach the D2 server, ``kea-dhcp4`` must be able to communicate -with it. ``kea-dhcp4`` uses the following configuration parameters to +For NCRs to reach the D2 server, :iscman:`kea-dhcp4` must be able to communicate +with it. :iscman:`kea-dhcp4` uses the following configuration parameters to control this communication: -- ``enable-updates`` - Enables connectivity to ``kea-dhcp-ddns`` such that DDNS +- ``enable-updates`` - Enables connectivity to :iscman:`kea-dhcp-ddns` such that DDNS updates can be constructed and sent. It must be ``true`` for NCRs to be generated and sent to D2. It defaults to ``false``. @@ -3552,12 +3552,12 @@ control this communication: - ``server-port`` - This is the port on which D2 listens for requests. The default value is ``53001``. -- ``sender-ip`` - This is the IP address which ``kea-dhcp4`` uses to send requests to - D2. The default value is blank, which instructs ``kea-dhcp4`` to select a +- ``sender-ip`` - This is the IP address which :iscman:`kea-dhcp4` uses to send requests to + D2. The default value is blank, which instructs :iscman:`kea-dhcp4` to select a suitable address. -- ``sender-port`` - This is the port which ``kea-dhcp4`` uses to send requests to D2. - The default value of ``0`` instructs ``kea-dhcp4`` to select a suitable port. +- ``sender-port`` - This is the port which :iscman:`kea-dhcp4` uses to send requests to D2. + The default value of ``0`` instructs :iscman:`kea-dhcp4` to select a suitable port. - ``max-queue-size`` - This is the maximum number of requests allowed to queue while waiting to be sent to D2. This value guards against requests @@ -3565,7 +3565,7 @@ control this communication: they can be delivered. If the number of requests queued for transmission reaches this value, DDNS updating is turned off until the queue backlog has been sufficiently reduced. The intent is - to allow the ``kea-dhcp4`` server to continue lease operations without + to allow the :iscman:`kea-dhcp4` server to continue lease operations without running the risk that its memory usage grows without limit. The default value is ``1024``. @@ -3575,8 +3575,8 @@ control this communication: - ``ncr-format`` - This specifies the packet format to use when sending requests to D2. Currently only JSON format is supported. -By default, ``kea-dhcp-ddns`` is assumed to be running on the same machine -as ``kea-dhcp4``, and all of the default values mentioned above should be +By default, :iscman:`kea-dhcp-ddns` is assumed to be running on the same machine +as :iscman:`kea-dhcp4`, and all of the default values mentioned above should be sufficient. If, however, D2 has been configured to listen on a different address or port, these values must be altered accordingly. For example, if D2 has been configured to listen on 192.168.1.10 port 900, the @@ -3595,22 +3595,22 @@ following configuration is required: .. _dhcpv4-d2-rules-config: -When Does the ``kea-dhcp4`` Server Generate a DDNS Request? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +When Does the :iscman:`kea-dhcp4` Server Generate a DDNS Request? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The ``kea-dhcp4`` server follows the behavior prescribed for DHCP servers in +The :iscman:`kea-dhcp4` server follows the behavior prescribed for DHCP servers in `RFC 4702 <https://tools.ietf.org/html/rfc4702>`__. It is important to keep -in mind that ``kea-dhcp4`` makes the initial decision of when and what to +in mind that :iscman:`kea-dhcp4` makes the initial decision of when and what to update and forwards that information to D2 in the form of NCRs. Carrying out the actual DNS updates and dealing with such things as conflict resolution are within the purview of D2 itself -(see :ref:`dhcp-ddns-server`). This section describes when ``kea-dhcp4`` +(see :ref:`dhcp-ddns-server`). This section describes when :iscman:`kea-dhcp4` generates NCRs and the configuration parameters that can be used to influence this decision. It assumes that both the connectivity parameter ``enable-updates`` and the behavioral parameter ``ddns-send-updates``, are ``true``. -In general, ``kea-dhcp4`` generates DDNS update requests when: +In general, :iscman:`kea-dhcp4` generates DDNS update requests when: 1. A new lease is granted in response to a DHCPREQUEST; @@ -3625,10 +3625,10 @@ add entries for the new FQDN. In the third case, a lease release - a single DDNS request - to remove its entries will be made. As for the first case, the decisions involved when granting a new lease are -more complex. When a new lease is granted, ``kea-dhcp4`` generates a +more complex. When a new lease is granted, :iscman:`kea-dhcp4` generates a DDNS update request if the DHCPREQUEST contains either the FQDN option (code 81) or the Host Name option (code 12). If both are present, the -server uses the FQDN option. By default, ``kea-dhcp4`` respects the +server uses the FQDN option. By default, :iscman:`kea-dhcp4` respects the FQDN N and S flags specified by the client as shown in the following table: @@ -3657,19 +3657,19 @@ table: The first row in the table above represents "client delegation." Here the DHCP client states that it intends to do the forward DNS updates and -the server should do the reverse updates. By default, ``kea-dhcp4`` +the server should do the reverse updates. By default, :iscman:`kea-dhcp4` honors the client's wishes and generates a DDNS request to the D2 server to update only reverse DNS data. The parameter ``ddns-override-client-update`` can be used to instruct the server to override client delegation requests. When this parameter is ``true``, -``kea-dhcp4`` disregards requests for client delegation and generates a +:iscman:`kea-dhcp4` disregards requests for client delegation and generates a DDNS request to update both forward and reverse DNS data. In this case, the N-S-O flags in the server's response to the client will be 0-1-1 respectively. (Note that the flag combination N=1, S=1 is prohibited according to `RFC 4702 <https://tools.ietf.org/html/rfc4702>`__. If such a combination is -received from the client, the packet will be dropped by ``kea-dhcp4``.) +received from the client, the packet will be dropped by :iscman:`kea-dhcp4`.) To override client delegation, set the following values in the configuration file: @@ -3684,8 +3684,8 @@ configuration file: The third row in the table above describes the case in which the client requests that no DNS updates be done. The parameter ``ddns-override-no-update`` can be used to instruct the server to disregard -the client's wishes. When this parameter is ``true``, ``kea-dhcp4`` -generates DDNS update requests to ``kea-dhcp-ddns`` even if the client +the client's wishes. When this parameter is ``true``, :iscman:`kea-dhcp4` +generates DDNS update requests to :iscman:`kea-dhcp-ddns` even if the client requests that no updates be done. The N-S-O flags in the server's response to the client will be 0-1-1. @@ -3698,7 +3698,7 @@ To override client delegation, issue the following commands: ... } -The ``kea-dhcp4`` server always generates DDNS update requests if the +The :iscman:`kea-dhcp4` server always generates DDNS update requests if the client request only contains the Host Name option. In addition, it includes an FQDN option in the response to the client with the FQDN N-S-O flags set to 0-1-0, respectively. The domain name portion of the FQDN option @@ -3706,11 +3706,11 @@ is the name submitted to D2 in the DDNS update request. .. _dhcpv4-fqdn-name-generation: -``kea-dhcp4`` Name Generation for DDNS Update Requests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +:iscman:`kea-dhcp4` Name Generation for DDNS Update Requests +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Each NameChangeRequest must of course include the fully qualified domain -name whose DNS entries are to be affected. ``kea-dhcp4`` can be configured +name whose DNS entries are to be affected. :iscman:`kea-dhcp4` can be configured to supply a portion or all of that name, based on what it receives from the client in the DHCPREQUEST. @@ -3752,7 +3752,7 @@ parameter, which provides the following modes of behavior: must replace them with the desired mode name. A value of ``true`` maps to ``when-present``, while ``false`` maps to ``never``. -For example, to instruct ``kea-dhcp4`` to always generate the FQDN for a +For example, to instruct :iscman:`kea-dhcp4` to always generate the FQDN for a client, set the parameter ``ddns-replace-client-name`` to ``always`` as follows: @@ -3787,7 +3787,7 @@ meaningful default. ... } -When generating a name, ``kea-dhcp4`` constructs the name in the format: +When generating a name, :iscman:`kea-dhcp4` constructs the name in the format: ``[ddns-generated-prefix]-[address-text].[ddns-qualifying-suffix].`` @@ -3805,7 +3805,7 @@ Sanitizing Client Host Name and FQDN Names Some DHCP clients may provide values in the Host Name option (option code 12) or FQDN option (option code 81) that contain -undesirable characters. It is possible to configure ``kea-dhcp4`` to +undesirable characters. It is possible to configure :iscman:`kea-dhcp4` to sanitize these values. The most typical use case is ensuring that only characters that are permitted by RFC 1035 be included: A-Z, a-z, 0-9, and "-". This may be accomplished with the following two parameters: @@ -4404,7 +4404,7 @@ current results. After enabling multi-threading, the number of threads is set by the ``thread-pool-size`` parameter. Results from our experiments show that the best settings for -``kea-dhcp4`` are: +:iscman:`kea-dhcp4` are: - ``thread-pool-size``: 4 when using ``memfile`` for storing leases. @@ -4533,10 +4533,10 @@ also depend on the reusable lifetime. Temporary Allocation on DHCPDISCOVER ------------------------------------ -By default, ``kea-dhcp4`` does not allocate or store a lease when offering an address -to a client in response to a DHCPDISCOVER. In general, ``kea-dhcp4`` can fulfill client +By default, :iscman:`kea-dhcp4` does not allocate or store a lease when offering an address +to a client in response to a DHCPDISCOVER. In general, :iscman:`kea-dhcp4` can fulfill client demands faster by deferring lease allocation and storage until it receives DHCPREQUESTs -for them. Release 2.3.6 added a new parameter to ``kea-dhcp4``, ``offer-lifetime``, which +for them. Release 2.3.6 added a new parameter to :iscman:`kea-dhcp4`, ``offer-lifetime``, which (when not zero) instructs the server to allocate and persist a lease when generating a DHCPOFFER. In addition: @@ -4557,7 +4557,7 @@ DHCPOFFER. In addition: - Lease caching, if enabled, is honored. -- In sites running multiple instances of ``kea-dhcp4`` against a single, shared lease store, races +- In sites running multiple instances of :iscman:`kea-dhcp4` against a single, shared lease store, races for given address values are lost during DHCPDISCOVER processing rather than during DHCPREQUEST processing. Servers that lose the race for the address simply do not respond to the client, rather than NAK them. The client in turn simply retries its DHCPDISCOVER. This should reduce @@ -4583,7 +4583,7 @@ An example subnet configuration is shown below: } Here ``offer-lifetime`` has been configured to be 60 seconds, with a ``valid-lifetime`` -of 2000 seconds. This instructs ``kea-dhcp4`` to persist leases for 60 seconds when +of 2000 seconds. This instructs :iscman:`kea-dhcp4` to persist leases for 60 seconds when sending them back in DHCPOFFERs, and then extend them to 2000 seconds when clients DHCPREQUEST them. @@ -7380,7 +7380,7 @@ The following standards are currently supported in Kea: - *The Dynamic Host Configuration Protocol (DHCP) Client Fully Qualified Domain Name (FQDN) Option*, `RFC 4702 <https://tools.ietf.org/html/rfc4702>`__: The Kea server is able to handle - the Client FQDN option. Also, it is able to use the ``kea-dhcp-ddns`` + the Client FQDN option. Also, it is able to use the :iscman:`kea-dhcp-ddns` component to initiate appropriate DNS Update operations. - *Resolution of Fully Qualified Domain Name (FQDN) Conflicts among Dynamic diff --git a/doc/sphinx/arm/dhcp6-srv.rst b/doc/sphinx/arm/dhcp6-srv.rst index 6c5c7a4c9e..7a21da0e9a 100644 --- a/doc/sphinx/arm/dhcp6-srv.rst +++ b/doc/sphinx/arm/dhcp6-srv.rst @@ -10,8 +10,8 @@ Starting and Stopping the DHCPv6 Server ======================================= It is recommended that the Kea DHCPv6 server be started and stopped -using ``keactrl`` (described in :ref:`keactrl`); however, it is also -possible to run the server directly via the ``kea-dhcp6`` command, which accepts +using :iscman:`keactrl` (described in :ref:`keactrl`); however, it is also +possible to run the server directly via the :iscman:`kea-dhcp6` command, which accepts the following command-line switches: - ``-c file`` - specifies the configuration file. This is the only @@ -34,7 +34,7 @@ the following command-line switches: as a DHCPv6 server sending responses to ports other than the standard ones is not able to handle regular DHCPv6 queries. -- ``-t file`` - specifies a configuration file to be tested. ``kea-dhcp6`` +- ``-t file`` - specifies a configuration file to be tested. :iscman:`kea-dhcp6` loads it, checks it, and exits. During the test, log messages are printed to standard output and error messages to standard error. The result of the test is reported through the exit code (0 = @@ -42,7 +42,7 @@ the following command-line switches: comprehensive; certain checks are possible only when running the server. -- ``-T file`` - specifies a configuration file to be tested. ``kea-dhcp6`` +- ``-T file`` - specifies a configuration file to be tested. :iscman:`kea-dhcp6` loads it, checks it, and exits. It performs extra checks beyond what ``-t`` offers, such as establishing database connections (for the lease backend, host reservations backend, configuration backend, and forensic logging @@ -2926,8 +2926,8 @@ way in which ``option-data`` is processed. DDNS for DHCPv6 --------------- -As mentioned earlier, ``kea-dhcp6`` can be configured to generate requests -to the DHCP-DDNS server, ``kea-dhcp-ddns``, (referred to herein as "D2") to +As mentioned earlier, :iscman:`kea-dhcp6` can be configured to generate requests +to the DHCP-DDNS server, :iscman:`kea-dhcp-ddns`, (referred to herein as "D2") to update DNS entries. These requests are known as NameChangeRequests or NCRs. Each NCR contains the following information: @@ -2943,9 +2943,9 @@ DDNS-related parameters are split into two groups: 1. Connectivity Parameters - These are parameters which specify where and how ``kea-dhcp6`` connects to + These are parameters which specify where and how :iscman:`kea-dhcp6` connects to and communicates with D2. These parameters can only be specified - within the top-level ``dhcp-ddns`` section in the ``kea-dhcp6`` + within the top-level ``dhcp-ddns`` section in the :iscman:`kea-dhcp6` configuration. The connectivity parameters are listed below: - ``enable-updates`` @@ -3020,9 +3020,9 @@ The default configuration and values would appear as follows: ... } -There are two parameters which determine if ``kea-dhcp6`` +There are two parameters which determine if :iscman:`kea-dhcp6` can generate DDNS requests to D2: the existing ``dhcp-ddns:enable-updates`` -parameter, which now only controls whether ``kea-dhcp6`` connects to D2; +parameter, which now only controls whether :iscman:`kea-dhcp6` connects to D2; and the new behavioral parameter, ``ddns-send-updates``, which determines whether DDNS updates are enabled at a given level (i.e. global, shared-network, or subnet). The following table shows how the two parameters function @@ -3061,7 +3061,7 @@ to add DNS entries or they were somehow lost by the DNS server. for servers with numerous clients that renew often. The second parameter added in Kea 1.9.1 is ``ddns-use-conflict-resolution``. -The value of this parameter is passed by ``kea-dhcp6`` to D2 with each DNS update +The value of this parameter is passed by :iscman:`kea-dhcp6` to D2 with each DNS update request. When ``true`` (the default value), D2 employs conflict resolution, as described in `RFC 4703 <https://tools.ietf.org/html/rfc4703>`__, when attempting to fulfill the update request. When ``false``, D2 simply attempts @@ -3096,11 +3096,11 @@ conflict with existing entries owned by other DHCPv6 clients. specific use cases. The best way to avoid unwanted DNS entries is to always ensure lease changes are processed through Kea, whether they are released, expire, or are deleted via the ``lease-del6`` command, prior to - reassigning either FQDNs or IP addresses. Doing so causes ``kea-dhcp6`` + reassigning either FQDNs or IP addresses. Doing so causes :iscman:`kea-dhcp6` to generate DNS removal requests to D2. The DNS entries Kea creates contain a value for TTL (time to live). -``kea-dhcp6`` calculates that value based on +:iscman:`kea-dhcp6` calculates that value based on `RFC 4702, Section 5 <https://tools.ietf.org/html/rfc4702#section-5>`__, which suggests that the TTL value be 1/3 of the lease's lifetime, with a minimum value of 10 minutes. @@ -3116,11 +3116,11 @@ global, shared-network, and subnet levels. By default it is unspecified. DHCP-DDNS Server Connectivity ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For NCRs to reach the D2 server, ``kea-dhcp6`` must be able to communicate -with it. ``kea-dhcp6`` uses the following configuration parameters to +For NCRs to reach the D2 server, :iscman:`kea-dhcp6` must be able to communicate +with it. :iscman:`kea-dhcp6` uses the following configuration parameters to control this communication: -- ``enable-updates`` - Enables connectivity to ``kea-dhcp-ddns`` such that DDNS +- ``enable-updates`` - Enables connectivity to :iscman:`kea-dhcp-ddns` such that DDNS updates can be constructed and sent. It must be ``true`` for NCRs to be generated and sent to D2. It defaults to ``false``. @@ -3132,12 +3132,12 @@ control this communication: - ``server-port`` - This is the port on which D2 listens for requests. The default value is ``53001``. -- ``sender-ip`` - This is the IP address which ``kea-dhcp6`` uses to send requests to - D2. The default value is blank, which instructs ``kea-dhcp6`` to select a +- ``sender-ip`` - This is the IP address which :iscman:`kea-dhcp6` uses to send requests to + D2. The default value is blank, which instructs :iscman:`kea-dhcp6` to select a suitable address. -- ``sender-port`` - This is the port which ``kea-dhcp6`` uses to send requests to D2. - The default value of ``0`` instructs ``kea-dhcp6`` to select a suitable port. +- ``sender-port`` - This is the port which :iscman:`kea-dhcp6` uses to send requests to D2. + The default value of ``0`` instructs :iscman:`kea-dhcp6` to select a suitable port. - ``max-queue-size`` - This is the maximum number of requests allowed to queue while waiting to be sent to D2. This value guards against requests @@ -3145,7 +3145,7 @@ control this communication: they can be delivered. If the number of requests queued for transmission reaches this value, DDNS updating is turned off until the queue backlog has been sufficiently reduced. The intent is - to allow the ``kea-dhcp4`` server to continue lease operations without + to allow the :iscman:`kea-dhcp4` server to continue lease operations without running the risk that its memory usage grows without limit. The default value is ``1024``. @@ -3155,8 +3155,8 @@ control this communication: - ``ncr-format`` - This specifies the packet format to use when sending requests to D2. Currently only JSON format is supported. -By default, ``kea-dhcp-ddns`` is assumed to be running on the same machine -as ``kea-dhcp6``, and all of the default values mentioned above should be +By default, :iscman:`kea-dhcp-ddns` is assumed to be running on the same machine +as :iscman:`kea-dhcp6`, and all of the default values mentioned above should be sufficient. If, however, D2 has been configured to listen on a different address or port, these values must be altered accordingly. For example, if D2 has been configured to listen on 2001:db8::5 port 900, the following @@ -3175,28 +3175,28 @@ configuration is required: .. _dhcpv6-d2-rules-config: -When Does the ``kea-dhcp6`` Server Generate a DDNS Request? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +When Does the :iscman:`kea-dhcp6` Server Generate a DDNS Request? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The ``kea-dhcp6`` server follows the behavior prescribed for DHCP servers in +The :iscman:`kea-dhcp6` server follows the behavior prescribed for DHCP servers in `RFC 4704 <https://tools.ietf.org/html/rfc4704>`__. It is important to keep -in mind that ``kea-dhcp6`` makes the initial decision of when and what to +in mind that :iscman:`kea-dhcp6` makes the initial decision of when and what to update and forwards that information to D2 in the form of NCRs. Carrying out the actual DNS updates and dealing with such things as conflict resolution are within the purview of D2 itself -(see :ref:`dhcp-ddns-server`). This section describes when ``kea-dhcp6`` +(see :ref:`dhcp-ddns-server`). This section describes when :iscman:`kea-dhcp6` generates NCRs and the configuration parameters that can be used to influence this decision. It assumes that the ``enable-updates`` parameter is ``true``. .. note:: - Currently the interface between ``kea-dhcp6`` and D2 only supports + Currently the interface between :iscman:`kea-dhcp6` and D2 only supports requests which update DNS entries for a single IP address. If a lease - grants more than one address, ``kea-dhcp6`` creates the DDNS update + grants more than one address, :iscman:`kea-dhcp6` creates the DDNS update request for only the first of these addresses. -In general, ``kea-dhcp6`` generates DDNS update requests when: +In general, :iscman:`kea-dhcp6` generates DDNS update requests when: 1. A new lease is granted in response to a DHCPREQUEST; @@ -3211,9 +3211,9 @@ add entries for the new FQDN. In the third case, a lease release - a single DDNS request - to remove its entries will be made. As for the first case, the decisions involved when granting a new lease are -more complex. When a new lease is granted, ``kea-dhcp6`` generates a +more complex. When a new lease is granted, :iscman:`kea-dhcp6` generates a DDNS update request only if the DHCPREQUEST contains the FQDN option -(code 39). By default, ``kea-dhcp6`` respects the FQDN N and S flags +(code 39). By default, :iscman:`kea-dhcp6` respects the FQDN N and S flags specified by the client as shown in the following table: .. table:: Default FQDN flag behavior @@ -3241,18 +3241,18 @@ specified by the client as shown in the following table: The first row in the table above represents "client delegation." Here the DHCP client states that it intends to do the forward DNS updates and -the server should do the reverse updates. By default, ``kea-dhcp6`` +the server should do the reverse updates. By default, :iscman:`kea-dhcp6` honors the client's wishes and generates a DDNS request to D2 to update only reverse DNS data. The parameter ``ddns-override-client-update`` can be used to instruct the server to override client delegation requests. When -this parameter is ``true``, ``kea-dhcp6`` disregards requests for client +this parameter is ``true``, :iscman:`kea-dhcp6` disregards requests for client delegation and generates a DDNS request to update both forward and reverse DNS data. In this case, the N-S-O flags in the server's response to the client will be 0-1-1 respectively. (Note that the flag combination N=1, S=1 is prohibited according to `RFC 4702 <https://tools.ietf.org/html/rfc4702>`__. If such a combination is -received from the client, the packet will be dropped by ``kea-dhcp6``.) +received from the client, the packet will be dropped by :iscman:`kea-dhcp6`.) To override client delegation, set the following values in the configuration file: @@ -3267,8 +3267,8 @@ configuration file: The third row in the table above describes the case in which the client requests that no DNS updates be done. The parameter ``ddns-override-no-update`` can be used to instruct the server to disregard -the client's wishes. When this parameter is ``true``, ``kea-dhcp6`` -generates DDNS update requests to ``kea-dhcp-ddns`` even if the client +the client's wishes. When this parameter is ``true``, :iscman:`kea-dhcp6` +generates DDNS update requests to :iscman:`kea-dhcp-ddns` even if the client requests that no updates be done. The N-S-O flags in the server's response to the client will be 0-1-1. @@ -3281,7 +3281,7 @@ To override client delegation, issue the following commands: ... } -The ``kea-dhcp6`` server always generates DDNS update requests if the +The :iscman:`kea-dhcp6` server always generates DDNS update requests if the client request only contains the Host Name option. In addition, it includes an FQDN option in the response to the client with the FQDN N-S-O flags set to 0-1-0, respectively. The domain name portion of the FQDN option @@ -3289,11 +3289,11 @@ is the name submitted to D2 in the DDNS update request. .. _dhcpv6-fqdn-name-generation: -``kea-dhcp6`` Name Generation for DDNS Update Requests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +:iscman:`kea-dhcp6` Name Generation for DDNS Update Requests +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Each NameChangeRequest must of course include the fully qualified -domain name whose DNS entries are to be affected. ``kea-dhcp6`` can be +domain name whose DNS entries are to be affected. :iscman:`kea-dhcp6` can be configured to supply a portion or all of that name, based upon what it receives from the client in the DHCPREQUEST. @@ -3335,7 +3335,7 @@ parameter, which provides the following modes of behavior: desired mode name. A value of ``true`` maps to ``when-present``, while ``false`` maps to ``never``. -For example, to instruct ``kea-dhcp6`` to always generate the FQDN for a +For example, to instruct :iscman:`kea-dhcp6` to always generate the FQDN for a client, set the parameter ``ddns-replace-client-name`` to ``always`` as follows: @@ -3369,7 +3369,7 @@ are enabled. To set its value simply set it to the desired string: ... } -When qualifying a partial name, ``kea-dhcp6`` constructs the name in the +When qualifying a partial name, :iscman:`kea-dhcp6` constructs the name in the format: ``[candidate-name].[ddns-qualifying-suffix].`` @@ -3380,7 +3380,7 @@ For example, if the FQDN domain name value is "some-computer" and the ``some-computer.example.com.`` -When generating the entire name, ``kea-dhcp6`` constructs the name in +When generating the entire name, :iscman:`kea-dhcp6` constructs the name in the format: ``[ddns-generated-prefix]-[address-text].[ddns-qualifying-suffix].`` @@ -3399,7 +3399,7 @@ Sanitizing Client FQDN Names Some DHCP clients may provide values in the name component of the FQDN option (option code 39) that contain undesirable -characters. It is possible to configure ``kea-dhcp6`` to sanitize these +characters. It is possible to configure :iscman:`kea-dhcp6` to sanitize these values. The most typical use case is ensuring that only characters that are permitted by RFC 1035 be included: A-Z, a-z, 0-9, and "-". This may be accomplished with the following two parameters: @@ -3765,7 +3765,7 @@ current results. After enabling multi-threading, the number of threads is set by the ``thread-pool-size`` parameter. Results from our experiments show that the best settings for -``kea-dhcp6`` are: +:iscman:`kea-dhcp6` are: - ``thread-pool-size``: 4 when using ``memfile`` for storing leases. diff --git a/doc/sphinx/arm/ext-netconf.rst b/doc/sphinx/arm/ext-netconf.rst index 2f5467e0bc..83673a29eb 100644 --- a/doc/sphinx/arm/ext-netconf.rst +++ b/doc/sphinx/arm/ext-netconf.rst @@ -12,7 +12,7 @@ The Network Configuration Protocol, or NETCONF, is a network management protocol in `RFC 4741 <https://tools.ietf.org/html/rfc4741>`__. It uses the YANG modeling language, defined in `RFC 6020 <https://tools.ietf.org/html/rfc6020>`__, to provide a uniform way of handling the configuration syntax of various networking devices. Kea provides optional -support for a YANG/NETCONF interface with the ``kea-netconf`` agent. +support for a YANG/NETCONF interface with the :iscman:`kea-netconf` agent. .. _netconf-install: @@ -40,7 +40,7 @@ Sysrepo. The specific versions that have been thoroughly tested with Kea are: .. note:: - ``kea-netconf`` may be compatible with later versions of libyang and + :iscman:`kea-netconf` may be compatible with later versions of libyang and Sysrepo, but only the versions listed above have been thoroughly tested by ISC. @@ -354,7 +354,7 @@ Supported YANG Models The currently supported models are ``kea-dhcp4-server`` and ``kea-dhcp6-server``. There is partial support for ``ietf-dhcpv6-server``, but the primary focus of testing has been on Kea DHCP -servers. Other models (``kea-dhcp-ddns`` and ``kea-ctrl-agent``) +servers. Other models (:iscman:`kea-dhcp-ddns` and :iscman:`kea-ctrl-agent`) are currently not supported. .. _using-netconf: @@ -437,7 +437,7 @@ making them manageable. For instance, for the DHCPv4 server: } } -With module change subscriptions enabled, the ``kea-netconf`` daemon +With module change subscriptions enabled, the :iscman:`kea-netconf` daemon monitors any configuration changes as they appear in the Sysrepo. Such changes can be done using the ``sysrepocfg`` tool or remotely using any NETCONF client. For details, please see the Sysrepo documentation or @@ -475,7 +475,7 @@ be incorrect: credentials but the database refuses the connection. The first case is handled by Sysrepo. The second and third cases are -handled by ``kea-netconf`` in the validation phase (if not disabled by +handled by :iscman:`kea-netconf` in the validation phase (if not disabled by setting ``validate-changes`` to ``true``). The last case causes the application phase to fail without a sensible report to Sysrepo. @@ -500,7 +500,7 @@ A control socket is specified by: - ``socket-type`` - the socket type is either ``stdout``, ``unix``, or ``http``. ``stdout`` is the default; - it is not really a socket, but it allows ``kea-netconf`` to run in + it is not really a socket, but it allows :iscman:`kea-netconf` to run in debugging mode where everything is printed on stdout, and it can also be used to redirect commands easily. ``unix`` is the standard direct server control channel, which uses UNIX sockets; ``http`` uses @@ -521,17 +521,17 @@ entry scopes. Hook libraries can be loaded by the NETCONF agent just as with other servers or agents; however, currently no hook points are defined. The ``hooks-libraries`` list contains the list of hook libraries that -should be loaded by ``kea-netconf``, along with their configuration +should be loaded by :iscman:`kea-netconf`, along with their configuration information specified with ``parameters``. Please consult :ref:`logging` for details on how to configure -logging. The name of the NETCONF agent's main logger is ``kea-netconf``, as +logging. The name of the NETCONF agent's main logger is :iscman:`kea-netconf`, as given in the example above. .. _netconf-example: -A ``kea-netconf`` Configuration Example ---------------------------------------- +A :iscman:`kea-netconf` Configuration Example +--------------------------------------------- The following example demonstrates the basic NETCONF configuration. More examples are available in the ``doc/examples/netconf`` directory in the @@ -659,7 +659,7 @@ Kea sources. Starting and Stopping the NETCONF Agent --------------------------------------- -``kea-netconf`` accepts the following command-line switches: +:iscman:`kea-netconf` accepts the following command-line switches: - ``-c file`` - specifies the configuration file. @@ -671,15 +671,15 @@ Starting and Stopping the NETCONF Agent verbosity, e.g. when debugging. - ``-t file`` - specifies the configuration file to be tested. - ``kea-netconf`` attempts to load it and conducts sanity checks; + :iscman:`kea-netconf` attempts to load it and conducts sanity checks; certain checks are possible only while running the actual server. The actual status is reported with exit code (0 = configuration appears valid, 1 = error encountered). Kea prints out log messages to standard output and error to standard error when testing the configuration. -- ``-v`` - displays the version of ``kea-netconf`` and exits. +- ``-v`` - displays the version of :iscman:`kea-netconf` and exits. -- ``-V`` - displays the extended version information for ``kea-netconf`` +- ``-V`` - displays the extended version information for :iscman:`kea-netconf` and exits. The listing includes the versions of the libraries dynamically linked to Kea. @@ -737,7 +737,7 @@ The interface must have an address in the test prefix: # ip -6 addr add 2001:db8::1/64 dev eth1 The Kea DHCPv6 server must be launched with the configuration specifying -a control socket used to receive control commands. The ``kea-netconf`` +a control socket used to receive control commands. The :iscman:`kea-netconf` process uses this socket to communicate with the DHCPv6 server, i.e. it pushes translated configurations to that server using control commands. The following is an example control socket specification for the Kea @@ -769,7 +769,7 @@ socket by running: # echo '{ "command": "config-get" }' | socat UNIX:/tmp/kea-dhcp6-ctrl.sock '-,ignoreeof' The following is the example ``netconf.json`` configuration for -``kea-netconf``, to manage the Kea DHCPv6 server: +:iscman:`kea-netconf`, to manage the Kea DHCPv6 server: .. code-block:: json @@ -806,7 +806,7 @@ The Kea NETCONF agent is launched by: # kea-netconf -d -c netconf.json -Now that both ``kea-netconf`` and ``kea-dhcp6`` are running, it is +Now that both :iscman:`kea-netconf` and :iscman:`kea-dhcp6` are running, it is possible to populate updates to the configuration to the DHCPv6 server. The following is the configuration extracted from ``startup.xml``: @@ -837,7 +837,7 @@ To populate this new configuration: $ sysrepocfg -d startup -f xml -m kea-dhcp6-server --edit=startup.xml -``kea-netconf`` pushes the configuration found in the Sysrepo startup +:iscman:`kea-netconf` pushes the configuration found in the Sysrepo startup datastore to all Kea servers during its initialization phase, after it subscribes to module changes in the Sysrepo running datastore. This action copies the configuration from the startup datastore to the @@ -850,10 +850,10 @@ datastore, i.e. changes are not permanent. .. note:: - ``kea-netconf`` fetches the entire configuration from any Sysrepo datastore in a + :iscman:`kea-netconf` fetches the entire configuration from any Sysrepo datastore in a single ``get-config`` NETCONF operation. Prior to Kea 2.3.2, a ``get-config`` operation was done for each leaf and leaf-list node. Because of the significant changes, - ``kea-netconf`` is considered experimental. + :iscman:`kea-netconf` is considered experimental. .. _operation-example-errors: @@ -902,7 +902,7 @@ It is directly rejected by ``sysrepocfg``: $ sysrepocfg -d running -f xml -m kea-dhcp6-server --edit=BAD-schema.xml -In the second case, the configuration is rejected by ``kea-netconf``. +In the second case, the configuration is rejected by :iscman:`kea-netconf`. For example, consider this ``BAD-translator.xml`` file: .. code-block:: xml @@ -1129,7 +1129,7 @@ or by using a NETCONF client like ``netopeer2-cli`` from the Migrating YANG Data From a Prior Sysrepo Version ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1. Shut down ``kea-netconf``. This ensures that backups for both datastores +1. Shut down :iscman:`kea-netconf`. This ensures that backups for both datastores are done at the same configuration state and that no change happens between exporting them. 2. Make data backups for all YANG modules, with one XML for each datastore. diff --git a/doc/sphinx/arm/hooks-bootp.rst b/doc/sphinx/arm/hooks-bootp.rst index 629d429111..53460c11fa 100644 --- a/doc/sphinx/arm/hooks-bootp.rst +++ b/doc/sphinx/arm/hooks-bootp.rst @@ -15,7 +15,7 @@ the server's responses; responses shorter than the BOOTP minimum size of 300 octets are padded to this size. This open source library is loaded -similarly to other hook libraries by the ``kea-dhcp4`` process, and +similarly to other hook libraries by the :iscman:`kea-dhcp4` process, and it takes no parameters. :: @@ -30,7 +30,7 @@ it takes no parameters. .. note:: - This library can only be loaded by the ``kea-dhcp4`` process, + This library can only be loaded by the :iscman:`kea-dhcp4` process, as there is no BOOTP protocol for IPv6. .. note:: diff --git a/doc/sphinx/arm/hooks-cb-cmds.rst b/doc/sphinx/arm/hooks-cb-cmds.rst index f7ab62e8ed..be9b668545 100644 --- a/doc/sphinx/arm/hooks-cb-cmds.rst +++ b/doc/sphinx/arm/hooks-cb-cmds.rst @@ -26,8 +26,8 @@ support contract. .. note:: - This library may only be loaded by the ``kea-dhcp4`` or - ``kea-dhcp6`` process. + This library may only be loaded by the :iscman:`kea-dhcp4` or + :iscman:`kea-dhcp6` process. .. note:: @@ -84,8 +84,8 @@ support contract. .. note:: - This library can only be loaded by the ``kea-dhcp4`` or - ``kea-dhcp6`` process. + This library can only be loaded by the :iscman:`kea-dhcp4` or + :iscman:`kea-dhcp6` process. .. note:: diff --git a/doc/sphinx/arm/hooks-class-cmds.rst b/doc/sphinx/arm/hooks-class-cmds.rst index 4eb4d057e3..68148114fb 100644 --- a/doc/sphinx/arm/hooks-class-cmds.rst +++ b/doc/sphinx/arm/hooks-class-cmds.rst @@ -11,8 +11,8 @@ list the client classes configured for a given server. .. note:: - This library can only be loaded by the ``kea-dhcp4`` or - ``kea-dhcp6`` process. + This library can only be loaded by the :iscman:`kea-dhcp4` or + :iscman:`kea-dhcp6` process. The Class Commands hook library is currently available only to ISC customers with a paid support contract. diff --git a/doc/sphinx/arm/hooks-ddns-tuning.rst b/doc/sphinx/arm/hooks-ddns-tuning.rst index 38864f51e8..5576f69dc4 100644 --- a/doc/sphinx/arm/hooks-ddns-tuning.rst +++ b/doc/sphinx/arm/hooks-ddns-tuning.rst @@ -10,8 +10,8 @@ performing DDNS updates for select clients. The DDNS Tuning hook library is only available to ISC customers with a paid support contract. -The library, which was added in Kea 2.1.5, can be loaded by the ``kea-dhcp4`` -and ``kea-dhcp6`` daemons by adding it to the ``hooks-libraries`` element of the +The library, which was added in Kea 2.1.5, can be loaded by the :iscman:`kea-dhcp4` +and :iscman:`kea-dhcp6` daemons by adding it to the ``hooks-libraries`` element of the server's configuration: .. code-block:: javascript @@ -102,7 +102,7 @@ global expression for that subnet. An example subnet expression is shown below: DHCPv4 Host-Name Generation --------------------------- -With this library installed, the behavior for ``kea-dhcp4`` when forming host names in +With this library installed, the behavior for :iscman:`kea-dhcp4` when forming host names in response to a client query (e.g. DISCOVER, REQUEST) is as follows: 1. If a host name is supplied via a host reservation, use it with the DDNS @@ -126,7 +126,7 @@ response to a client query (e.g. DISCOVER, REQUEST) is as follows: DHCPv6 Host-Name Generation --------------------------- -With this library installed, the behavior for ``kea-dhcp6`` when forming host names in +With this library installed, the behavior for :iscman:`kea-dhcp6` when forming host names in response to a client query (e.g. SOLICIT, REQUEST, RENEW, REBIND) is as follows: 1. If the client supplied an FQDN option (option 39), use the domain name value @@ -159,8 +159,8 @@ Skipping DDNS Updates The ``ddns-tuning`` library also provides the ability to skip DDNS updates on a per-client basis. The library recognizes a special client class, "SKIP_DDNS"; when a -client is matched to this class, the Kea servers (``kea-dhcp4`` and ``kea-dhcp6``) do not -send DDNS update requests (NCRs) to ``kea-dhcp-ddns``. A common use case would be +client is matched to this class, the Kea servers (:iscman:`kea-dhcp4` and :iscman:`kea-dhcp6`) do not +send DDNS update requests (NCRs) to :iscman:`kea-dhcp-ddns`. A common use case would be to skip DDNS updates for fixed-address host reservations. This is done easily by simply assigning the class to the host reservation as shown below: @@ -177,8 +177,8 @@ simply assigning the class to the host reservation as shown below: The ``ddns-tuning`` library notes the presence of the "SKIP_DDNS" class in the client's class list each time the client requests, renews, or releases its lease, -and instructs ``kea-dhcp4`` to bypass sending DDNS updates. A similar workflow is -supported for ``kea-dhcp6``: +and instructs :iscman:`kea-dhcp4` to bypass sending DDNS updates. A similar workflow is +supported for :iscman:`kea-dhcp6`: .. code-block:: javascript diff --git a/doc/sphinx/arm/hooks-flex-id.rst b/doc/sphinx/arm/hooks-flex-id.rst index 47278f1845..eab5e48aeb 100644 --- a/doc/sphinx/arm/hooks-flex-id.rst +++ b/doc/sphinx/arm/hooks-flex-id.rst @@ -18,7 +18,7 @@ contract. .. note:: - This library can only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6`` + This library can only be loaded by the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6` process. The ``flex_id`` library allows the definition of an expression, using notation initially diff --git a/doc/sphinx/arm/hooks-flex-option.rst b/doc/sphinx/arm/hooks-flex-option.rst index 369bbbe977..06824c0ed2 100644 --- a/doc/sphinx/arm/hooks-flex-option.rst +++ b/doc/sphinx/arm/hooks-flex-option.rst @@ -34,7 +34,7 @@ specified. The option space is DHCPv4 or DHCPv6, depending on the server where the hook library is loaded. Similar to other hook libraries, the ``flex_option`` library can be loaded -by either the ``kea-dhcp4`` or `kea-dhcp6`` +by either the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6` process. It takes a mandatory ``options`` parameter with a list of per-option parameter maps, with ``code``, ``name``, ``add``, ``supersede``, and ``remove`` actions. Action entries take a string value representing an diff --git a/doc/sphinx/arm/hooks-gss-tsig.rst b/doc/sphinx/arm/hooks-gss-tsig.rst index 651b7c924a..89260eda38 100644 --- a/doc/sphinx/arm/hooks-gss-tsig.rst +++ b/doc/sphinx/arm/hooks-gss-tsig.rst @@ -3,6 +3,6 @@ ``gss-tsig``: Sign DNS Updates With GSS-TSIG ============================================ -This hook library allows the ``kea-dhcp-ddns`` server to use +This hook library allows the :iscman:`kea-dhcp-ddns` server to use GSS-TSIG to sign DNS updates. For a full discussion of GSS-TSIG in Kea, please see :ref:`gss-tsig`. diff --git a/doc/sphinx/arm/hooks-ha.rst b/doc/sphinx/arm/hooks-ha.rst index 53ec9169e0..91f29691c6 100644 --- a/doc/sphinx/arm/hooks-ha.rst +++ b/doc/sphinx/arm/hooks-ha.rst @@ -10,7 +10,7 @@ but is now part of the open source Kea, available to all users. .. note:: - This library can only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6`` process. + This library can only be loaded by the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6` process. High Availability (HA) of the DHCP service is provided by running multiple cooperating server instances. If any of these instances becomes unavailable for @@ -1602,7 +1602,7 @@ Multi-Threaded Configuration (HA+MT) HA peer communication consists of specialized API commands sent between HA peers. Prior to Kea 1.9.7, each peer had to be paired with a local instance of -``kea-ctrl-agent`` in order to exchange commands. The agent received HA commands +:iscman:`kea-ctrl-agent` in order to exchange commands. The agent received HA commands via HTTP, communicated via Linux socket with the local peer to carry out the command, and then sent the response back to the requesting peer via HTTP. To send HA commands, each peer opened its own HTTP client connection to the URL of @@ -1623,16 +1623,16 @@ HA+MT operation: - ``enable-multi-threading`` - enables or disables multi-threading HA peer communication (HA+MT). Kea core multi-threading must be enabled for HA+MT to - operate. When ``false``, the server relies on ``kea-ctrl-agent`` for + operate. When ``false``, the server relies on :iscman:`kea-ctrl-agent` for communication with its peer, and uses single-threaded HTTP client processing. The default is ``true``. - ``http-dedicated-listener`` - enables or disables the creation of a dedicated, internal HTTP listener through which the server receives HA messages from its - peers. The internal listener replaces the role of ``kea-ctrl-agent`` traffic, + peers. The internal listener replaces the role of :iscman:`kea-ctrl-agent` traffic, allowing peers to send their HA commands directly to each other. The listener listens on the peer's ``url``. When ``false``, the server - relies on ``kea-ctrl-agent``. This parameter has been provided largely for + relies on :iscman:`kea-ctrl-agent`. This parameter has been provided largely for flexibility and testing; running HA+MT without dedicated listeners enabled will substantially limit HA throughput. The default is ``true``. diff --git a/doc/sphinx/arm/hooks-host-cache.rst b/doc/sphinx/arm/hooks-host-cache.rst index ad7f3d2d39..f9aca4589b 100644 --- a/doc/sphinx/arm/hooks-host-cache.rst +++ b/doc/sphinx/arm/hooks-host-cache.rst @@ -13,8 +13,8 @@ information in the database. .. note:: - This library can only be loaded by the ``kea-dhcp4`` or - ``kea-dhcp6`` process. + This library can only be loaded by the :iscman:`kea-dhcp4` or + :iscman:`kea-dhcp6` process. In principle, this hook library can be used with any backend that may introduce performance degradation (MySQL, PostgreSQL or RADIUS). Host Cache diff --git a/doc/sphinx/arm/hooks-host-cmds.rst b/doc/sphinx/arm/hooks-host-cmds.rst index 02f1bdf278..3815a16b31 100644 --- a/doc/sphinx/arm/hooks-host-cmds.rst +++ b/doc/sphinx/arm/hooks-host-cmds.rst @@ -18,7 +18,7 @@ contract. .. note:: - This library can only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6`` + This library can only be loaded by the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6` process. Currently, the following commands are supported: diff --git a/doc/sphinx/arm/hooks-lease-cmds.rst b/doc/sphinx/arm/hooks-lease-cmds.rst index 5af6debf8e..11f7884f43 100644 --- a/doc/sphinx/arm/hooks-lease-cmds.rst +++ b/doc/sphinx/arm/hooks-lease-cmds.rst @@ -21,8 +21,8 @@ available to every Kea user. .. note:: - This library can only be loaded by the ``kea-dhcp4`` or the - ``kea-dhcp6`` process. + This library can only be loaded by the :iscman:`kea-dhcp4` or the + :iscman:`kea-dhcp6` process. There are many situations where an administrative command may be useful; for example, during migration between servers or different vendors, when @@ -836,7 +836,7 @@ An example IPv4 lease deletion by ``"hw-address"`` is: Another parameter called ``update-ddns``, when ``true``, instructs the server to -queue a request to ``kea-dhcp-ddns`` to remove DNS entries after the lease is +queue a request to :iscman:`kea-dhcp-ddns` to remove DNS entries after the lease is successfully deleted if: - DDNS updating is enabled (i.e. ``"dhcp-ddns":{ "enable-updates": true }``). @@ -989,7 +989,7 @@ The ``lease4-resend-ddns``, ``lease6-resend-ddns`` Commands ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``lease4-resend-ddns`` and ``lease6-resend-ddns`` can be used to generate -a request to ``kea-dhcp-ddns`` to update the DNS entries for an existing +a request to :iscman:`kea-dhcp-ddns` to update the DNS entries for an existing lease. The desired lease is selected by a single parameter, ``"ip-address"``. For an update request to be generated, DDNS updating must be enabled and DNS entries must have already been made (or attempted) for the lease. @@ -1029,7 +1029,7 @@ object (a lease in this case) has not been found. A successful result does not mean that DNS has been successfully updated; it indicates that a request to update DNS has been successfully created and -queued for transmission to ``kea-dhcp-ddns``. +queued for transmission to :iscman:`kea-dhcp-ddns`. Here's an example of a result returned when the lease was found: diff --git a/doc/sphinx/arm/hooks-lease-query.rst b/doc/sphinx/arm/hooks-lease-query.rst index 4f917a55bd..04f21888fb 100644 --- a/doc/sphinx/arm/hooks-lease-query.rst +++ b/doc/sphinx/arm/hooks-lease-query.rst @@ -9,8 +9,8 @@ Leasequery as described in (`RFC 5007 <https://tools.ietf.org/html/rfc5007>`__). .. note:: - This library can only be loaded by the ``kea-dhcp4`` or - ``kea-dhcp6`` process. + This library can only be loaded by the :iscman:`kea-dhcp4` or + :iscman:`kea-dhcp6` process. Kea version 2.3.4 added support for DHCPv6 Bulk Leasequery (`RFC 5460 <https://tools.ietf.org/html/rfc5460>`__); diff --git a/doc/sphinx/arm/hooks-legal-log.rst b/doc/sphinx/arm/hooks-legal-log.rst index 68d0d315ab..6555ddbc81 100644 --- a/doc/sphinx/arm/hooks-legal-log.rst +++ b/doc/sphinx/arm/hooks-legal-log.rst @@ -12,7 +12,7 @@ contract. .. note:: - This library may only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6`` + This library may only be loaded by the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6` process. In many legal jurisdictions, companies - especially ISPs - must record @@ -78,11 +78,11 @@ Configuring the Forensic Logging Hooks To use this functionality, the hook library must be included in the configuration of the desired DHCP server modules. The ``legal_log`` library can save logs to a text file or to a database (created using -``kea-admin``; see :ref:`mysql-database-create` and :ref:`pgsql-database-create`). +:iscman:`kea-admin`; see :ref:`mysql-database-create` and :ref:`pgsql-database-create`). The library is installed alongside the Kea libraries in ``[kea-install-dir]/var/lib/kea``, where ``kea-install-dir`` is determined by the ``--prefix`` option of the configure script; it defaults to -``/usr/local``. Assuming the default value, ``kea-dhcp4`` can be configured to load +``/usr/local``. Assuming the default value, :iscman:`kea-dhcp4` can be configured to load the ``legal_log`` library like this: .. code-block:: json @@ -101,7 +101,7 @@ the ``legal_log`` library like this: } } -For ``kea-dhcp6``, the configuration is: +For :iscman:`kea-dhcp6`, the configuration is: .. code-block:: json diff --git a/doc/sphinx/arm/hooks-limits.rst b/doc/sphinx/arm/hooks-limits.rst index 25cf91602f..f7bf8be58b 100644 --- a/doc/sphinx/arm/hooks-limits.rst +++ b/doc/sphinx/arm/hooks-limits.rst @@ -15,12 +15,12 @@ The Limits hook library is only available to ISC customers with a paid support c Configuration ~~~~~~~~~~~~~ -The following examples are for ``kea-dhcp6``, but they apply equally to -``kea-dhcp4``. The wildcards ``"<limit-type>"`` and ``"<limit-value>"`` need to be replaced +The following examples are for :iscman:`kea-dhcp6`, but they apply equally to +:iscman:`kea-dhcp4`. The wildcards ``"<limit-type>"`` and ``"<limit-value>"`` need to be replaced with the respective keys and values for each limit type described in the sections following this one. -The library can be loaded by both ``kea-dhcp4`` and ``kea-dhcp6`` servers by adding its path in the +The library can be loaded by both :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` servers by adding its path in the ``"hooks-libraries"`` element of the server's configuration. .. code-block:: json diff --git a/doc/sphinx/arm/hooks-radius.rst b/doc/sphinx/arm/hooks-radius.rst index c9275cec26..cdf156a26d 100644 --- a/doc/sphinx/arm/hooks-radius.rst +++ b/doc/sphinx/arm/hooks-radius.rst @@ -16,8 +16,8 @@ DHCP server to talk to RADIUS directly. That is the goal of this library. .. note:: - This library can only be loaded by the ``kea-dhcp4`` or the - ``kea-dhcp6`` process. + This library can only be loaded by the :iscman:`kea-dhcp4` or the + :iscman:`kea-dhcp6` process. The major feature of this hook library is the ability to use RADIUS authorization. When a DHCP packet is received, the Kea server sends an diff --git a/doc/sphinx/arm/hooks-run-script.rst b/doc/sphinx/arm/hooks-run-script.rst index 7eade152b6..8fc894fac6 100644 --- a/doc/sphinx/arm/hooks-run-script.rst +++ b/doc/sphinx/arm/hooks-run-script.rst @@ -7,8 +7,8 @@ The Run Script hook library adds support for calling an external script for spec packet-processing hook points. The library, which was added in Kea 1.9.5, can be loaded in a -similar way to other hook libraries by the ``kea-dhcp4`` and -``kea-dhcp6`` processes. +similar way to other hook libraries by the :iscman:`kea-dhcp4` and +:iscman:`kea-dhcp6` processes. .. code-block:: json diff --git a/doc/sphinx/arm/hooks-stat-cmds.rst b/doc/sphinx/arm/hooks-stat-cmds.rst index cdd23b402f..7474ccd6c0 100644 --- a/doc/sphinx/arm/hooks-stat-cmds.rst +++ b/doc/sphinx/arm/hooks-stat-cmds.rst @@ -9,7 +9,7 @@ an issue with obtaining accurate lease statistics in deployments running multiple Kea servers that use a shared lease backend. The in-memory statistics kept by individual servers only track lease changes made by that server; thus, in a deployment with multiple servers (e.g. two -``kea-dhcp6`` servers using the same PostgreSQL database for lease storage), +:iscman:`kea-dhcp6` servers using the same PostgreSQL database for lease storage), these statistics are incomplete. The MySQL and PostgreSQL backends in Kea track lease allocation changes as they occur via database triggers. Additionally, all the lease backends were extended to support @@ -19,8 +19,8 @@ for retrieving these statistics. .. note:: - This library can only be loaded by the ``kea-dhcp4`` or - ``kea-dhcp6`` process. + This library can only be loaded by the :iscman:`kea-dhcp4` or + :iscman:`kea-dhcp6` process. The commands provided by this library are: @@ -35,7 +35,7 @@ All commands use JSON syntax and can be issued directly to the servers via either the control channel (see :ref:`ctrl-channel`) or the Control Agent (see :ref:`kea-ctrl-agent`). -This library may be loaded by both the ``kea-dhcp4`` and ``kea-dhcp6`` servers. It +This library may be loaded by both the :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` servers. It is loaded in the same way as other libraries and currently has no parameters: @@ -92,7 +92,7 @@ subnets. Note that in configurations with many subnets, this can result in a large response. The following command fetches lease statistics for all known subnets -from a ``kea-dhcp4`` server: +from a :iscman:`kea-dhcp4` server: :: @@ -101,7 +101,7 @@ from a ``kea-dhcp4`` server: } The following command fetches lease statistics for subnet ID 10 from a -``kea-dhcp6`` server: +:iscman:`kea-dhcp6` server: :: @@ -113,7 +113,7 @@ The following command fetches lease statistics for subnet ID 10 from a } The following command fetches lease statistics for all subnets with IDs -in the range 10 through 50 from a ``kea-dhcp4`` server: +in the range 10 through 50 from a :iscman:`kea-dhcp4` server: .. code-block:: json diff --git a/doc/sphinx/arm/hooks-subnet-cmds.rst b/doc/sphinx/arm/hooks-subnet-cmds.rst index 7dedb04f45..6c4f81beaa 100644 --- a/doc/sphinx/arm/hooks-subnet-cmds.rst +++ b/doc/sphinx/arm/hooks-subnet-cmds.rst @@ -18,7 +18,7 @@ contract. .. note:: - This library can only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6`` + This library can only be loaded by the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6` process. The following commands are currently supported: diff --git a/doc/sphinx/arm/hooks.rst b/doc/sphinx/arm/hooks.rst index 99d4301bb7..8fc645baf1 100644 --- a/doc/sphinx/arm/hooks.rst +++ b/doc/sphinx/arm/hooks.rst @@ -249,7 +249,7 @@ Notes: instead of removing the ``hooks-libraries`` item, change it to an empty list. -At the moment, only the ``kea-dhcp4`` and ``kea-dhcp6`` processes support +At the moment, only the :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` processes support hook libraries. .. _order-of-configuration-hooks: @@ -389,8 +389,8 @@ libraries, discussed in the following sections. The following table provides a list of hook libraries currently available from ISC. It is important to pay attention to which libraries may be loaded by which Kea processes. It is a common mistake to configure the -``kea-ctrl-agent`` process to load libraries that should, in fact, be -loaded by the ``kea-dhcp4`` or ``kea-dhcp6`` processes. If a library +:iscman:`kea-ctrl-agent` process to load libraries that should, in fact, be +loaded by the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6` processes. If a library from ISC does not work as expected, please make sure that it has been loaded by the correct process per the table below. @@ -519,10 +519,10 @@ loaded by the correct process per the table below. | | customers | Leasequery as described in RFC 4388; and for DHCPv6 | | | | Leasequery as described in RFC 5007. | +-----------------------------------------------------------+--------------+--------------------------------------------------------------+ - | :ref:`Limits <hooks-limits>` | ISC support | With this hook library, ``kea-dhcp4`` and ``kea-dhcp6`` | - | | customers | servers can apply a limit to the rate at which packets | - | | | receive a response. The limit can be applied per-client | - | | | class or per-subnet. | + | :ref:`Limits <hooks-limits>` | ISC support | With this hook library, :iscman:`kea-dhcp4` and | + | | customers | :iscman:`kea-dhcp6` servers can apply a limit to the rate at | + | | | which packets receive a response. The limit can be applied | + | | | per-client class or per-subnet. | +-----------------------------------------------------------+--------------+--------------------------------------------------------------+ | :ref:`MySQL Configuration Backend <hooks-cb-mysql>` | Kea open | This hook library is an implementation of the Kea | | | source | Configuration Backend for MySQL. It uses a MySQL database as | diff --git a/doc/sphinx/arm/install.rst b/doc/sphinx/arm/install.rst index c5b078a997..f2b5d7b562 100644 --- a/doc/sphinx/arm/install.rst +++ b/doc/sphinx/arm/install.rst @@ -46,8 +46,8 @@ For ISC customers with access to the premium hooks, those packages have the ``isc-kea-premium-`` prefix. Once installed, the services can be managed through the distribution's -service manager. The services are named: ``kea-dhcp4``, ``kea-dhcp6``, -``kea-dhcp-ddns``, and ``kea-ctrl-agent``. +service manager. The services are named: :iscman:`kea-dhcp4`, :iscman:`kea-dhcp6`, +:iscman:`kea-dhcp-ddns`, and :iscman:`kea-ctrl-agent`. .. note:: The real service names on Debian and Ubuntu follow the names of the older @@ -300,11 +300,11 @@ options. Some commonly used options are: found, Kea searches for OpenSSL. Normally this is not necessary. - ``--enable-shell`` - Build the optional ``kea-shell`` tool (more in :ref:`kea-shell`). + Build the optional :iscman:`kea-shell` tool (more in :ref:`kea-shell`). The default is to not build it. - ``--with-site-packages`` - Only useful when ``kea-shell`` is enabled, this switch causes the kea-shell + Only useful when :iscman:`kea-shell` is enabled, this switch causes the kea-shell Python packages to be installed in the specified directory. This is mostly useful for Debian-related distributions. While most systems store Python packages in ``${prefix}/usr/lib/pythonX/site-packages``, Debian @@ -313,7 +313,7 @@ options. Some commonly used options are: ``/usr/lib/python3/dist-packages``. - ``--enable-perfdhcp`` - Build the optional ``perfdhcp`` DHCP benchmarking tool. The default + Build the optional :iscman:`perfdhcp` DHCP benchmarking tool. The default is to not build it. - ``--with-freeradius`` @@ -395,7 +395,7 @@ If ``configure`` fails, it may be due to missing or old dependencies. When ``configure`` succeeds, it displays a report with the parameters used to build the code. This report is saved into the file ``config.report`` -and is also embedded into the executable binaries, e.g., ``kea-dhcp4``. +and is also embedded into the executable binaries, e.g., :iscman:`kea-dhcp4`. Build ----- diff --git a/doc/sphinx/arm/intro.rst b/doc/sphinx/arm/intro.rst index b9f221d0e9..f5c82f5a45 100644 --- a/doc/sphinx/arm/intro.rst +++ b/doc/sphinx/arm/intro.rst @@ -23,38 +23,38 @@ Kea is a modular DHCP server solution. This modularity is accomplished using mul cooperating processes which, together, provide the server functionality. The following software is included with Kea: -- ``keactrl`` — This tool starts, stops, reconfigures, and reports the status of +- :iscman:`keactrl` — This tool starts, stops, reconfigures, and reports the status of the Kea servers. -- ``kea-dhcp4`` — The DHCPv4 server process. This process responds to +- :iscman:`kea-dhcp4` — The DHCPv4 server process. This process responds to DHCPv4 queries from clients. -- ``kea-dhcp6`` — The DHCPv6 server process. This process responds to +- :iscman:`kea-dhcp6` — The DHCPv6 server process. This process responds to DHCPv6 queries from clients. -- ``kea-dhcp-ddns`` — The DHCP Dynamic DNS process. This process acts +- :iscman:`kea-dhcp-ddns` — The DHCP Dynamic DNS process. This process acts as an intermediary between the DHCP servers and external DNS servers. It receives name update requests from the DHCP servers and sends DNS update messages to the DNS servers. -- ``kea-admin`` — This is a useful tool for database backend maintenance +- :iscman:`kea-admin` — This is a useful tool for database backend maintenance (creating a new database, checking versions, upgrading, etc.). -- ``kea-lfc`` — This process removes redundant information from the +- :iscman:`kea-lfc` — This process removes redundant information from the files used to provide persistent storage for the memfile database backend. While it can be run standalone, it is normally run as and when required by the Kea DHCP servers. -- ``kea-ctrl-agent`` — The Kea Control Agent (CA) is a daemon that exposes +- :iscman:`kea-ctrl-agent` — The Kea Control Agent (CA) is a daemon that exposes a RESTful control interface for managing Kea servers. -- ``kea-netconf`` - kea-netconf is an agent that provides a +- :iscman:`kea-netconf` - kea-netconf is an agent that provides a YANG/NETCONF interface for configuring Kea. -- ``kea-shell`` — This simple text client uses the REST interface to +- :iscman:`kea-shell` — This simple text client uses the REST interface to connect to the Kea Control Agent. -- ``perfdhcp`` — This is a DHCP benchmarking tool which simulates multiple +- :iscman:`perfdhcp` — This is a DHCP benchmarking tool which simulates multiple clients to test both DHCPv4 and DHCPv6 server performance. The tools and modules are covered in full detail in this guide. In diff --git a/doc/sphinx/arm/keactrl.rst b/doc/sphinx/arm/keactrl.rst index 5a89168091..93768c3754 100644 --- a/doc/sphinx/arm/keactrl.rst +++ b/doc/sphinx/arm/keactrl.rst @@ -1,21 +1,21 @@ .. _keactrl: -***************************** -Managing Kea with ``keactrl`` -***************************** +*********************************** +Managing Kea with :iscman:`keactrl` +*********************************** .. _keactrl-overview: Overview ======== -``keactrl`` is a shell script which controls the startup, shutdown, and -reconfiguration of the Kea servers (``kea-dhcp4``, ``kea-dhcp6``, -``kea-dhcp-ddns``, ``kea-ctrl-agent``, and ``kea-netconf``). It also +: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. -``keactrl`` is available only when Kea is built from sources. When installing +: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. @@ -24,7 +24,7 @@ Kea using native packages, the native ``systemd`` scripts are provided. See Command Line Options ==================== -``keactrl`` is run as follows: +:iscman:`keactrl` is run as follows: .. code-block:: console @@ -33,24 +33,24 @@ Command Line Options ``<command>`` is one of the commands described in :ref:`keactrl-commands`. 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`` uses the +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 ``keactrl`` +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 ``keactrl`` Configuration 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 ``keactrl`` configuration file sets which servers are enabled and +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. @@ -105,14 +105,14 @@ The contents of ``keactrl.conf`` are: the appropriate values when Kea is installed. Setting the ``dhcp4``, ``dhcp6``, ``dhcp_ddns``, ``ctrl_agent``, and ``netconf`` -parameters set to "yes" configures ``keactrl`` to manage (start, -reconfigure) all servers, i.e. ``kea-dhcp4``, ``kea-dhcp6``, -``kea-dhcp-ddns``, ``kea-ctrl-agent``, and ``kea-netconf``. When any of -these parameters is set to "no", ``keactrl`` ignores the +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 ``keactrl`` are located in +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``, @@ -138,7 +138,7 @@ default settings are used. Commands ======== -The following commands are supported by ``keactrl``: +The following commands are supported by :iscman:`keactrl`: - ``start`` - starts the selected servers. @@ -150,10 +150,10 @@ The following commands are supported by ``keactrl``: - ``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 ``keactrl`` tool itself, +- ``version`` - prints out the version of the :iscman:`keactrl` tool itself, together with the versions of the Kea daemons. -Typical output from ``keactrl`` when starting the servers looks similar +Typical output from :iscman:`keactrl` when starting the servers looks similar to the following: .. code-block:: console @@ -166,7 +166,7 @@ to the following: 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 -``keactrl`` to determine whether a given server is running. If one or more +: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: @@ -183,8 +183,8 @@ 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 ``keactrl`` to decide that the servers are running, when in fact they -are not. In such a case the PID files listed in the ``keactrl`` output +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: @@ -214,7 +214,7 @@ in the ``stop`` command output below. 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 ``keactrl`` configuration +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. @@ -235,7 +235,7 @@ A reload is executed as follows: If any of the servers are not running, an informational message is displayed as in the ``reload`` command output below. -``kea-netconf`` does not support the SIGHUP signal. If its +: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. @@ -252,14 +252,14 @@ take effect. NETCONF is an optional feature that is disabled by default and can be enabled during compilation. If Kea was compiled without NETCONF - support, ``keactrl`` does not provide + 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 ``keactrl`` does not report configuration failures when the + 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. @@ -292,16 +292,16 @@ Overriding the Server Selection =============================== The optional ``-s`` switch allows the selection of the server(s) to which -the ``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: +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 ``kea-dhcp4`` and -``kea-dhcp-ddns`` servers, but not ``kea-dhcp6`` or ``kea-ctrl-agent``. +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 @@ -309,24 +309,24 @@ Similarly, the following starts only the ``kea-dhcp4`` and 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``, ``keactrl`` checks whether the +command. On ``start`` and ``reload``, :iscman:`keactrl` checks whether the servers given as parameters to the ``-s`` switch are enabled in the -``keactrl`` configuration file; if not, the server is ignored. For +: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 ``kea-dhcp4``. +- ``dhcp4`` for :iscman:`kea-dhcp4`. -- ``dhcp6`` for ``kea-dhcp6``. +- ``dhcp6`` for :iscman:`kea-dhcp6`. -- ``dhcp_ddns`` for ``kea-dhcp-ddns``. +- ``dhcp_ddns`` for :iscman:`kea-dhcp-ddns`. -- ``ctrl_agent`` for ``kea-ctrl-agent``. +- ``ctrl_agent`` for :iscman:`kea-ctrl-agent`. -- ``netconf`` for ``kea-netconf``. +- ``netconf`` for :iscman:`kea-netconf`. - ``all`` for all servers (default). @@ -335,7 +335,7 @@ The following keywords can be used with the ``-s`` command-line option: Native Packages and ``systemd`` =============================== -``keactrl`` is a script that was developed to assist in managing Kea processes. +: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 @@ -347,7 +347,7 @@ the ability to enable or disable services using commands, and the ability to tem service. Thus, it is recommended to use ``systemctl`` commands if they are available. Native -Kea packages do not provide ``keactrl``; ``systemctl`` service definitions are +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: diff --git a/doc/sphinx/arm/lfc.rst b/doc/sphinx/arm/lfc.rst index dfe3e24c8f..f28756ad16 100644 --- a/doc/sphinx/arm/lfc.rst +++ b/doc/sphinx/arm/lfc.rst @@ -9,12 +9,12 @@ The LFC Process Overview ======== -``kea-lfc`` is a service process that removes redundant information from +:iscman:`kea-lfc` is a service process that removes redundant information from the files used to provide persistent storage for the memfile database backend. This service is written to run as a standalone process. -While ``kea-lfc`` can be started externally, there is usually no need to -do so. ``kea-lfc`` is run on a periodic basis by the Kea DHCP servers. +While :iscman:`kea-lfc` can be started externally, there is usually no need to +do so. :iscman:`kea-lfc` is run on a periodic basis by the Kea DHCP servers. The process operates on a set of files, using them to receive input and output of the lease entries and to indicate what stage the process is @@ -26,7 +26,7 @@ names for all of the files. Command-Line Options ==================== -``kea-lfc`` is run as follows: +:iscman:`kea-lfc` is run as follows: :: @@ -38,32 +38,32 @@ files. The ``-c`` argument specifies the configuration file. This is required, but is not currently used by the process. -The ``-p`` argument specifies the PID file. When the ``kea-lfc`` process +The ``-p`` argument specifies the PID file. When the :iscman:`kea-lfc` process starts, it attempts to determine whether another instance of the process is already running by examining the PID file. If one is already running, the new process is terminated; if one is not running, Kea writes its PID into the PID file. -The other filenames specify where the ``kea-lfc`` process should look +The other filenames specify where the :iscman:`kea-lfc` process should look for input, write its output, and perform its bookkeeping: -- ``previous`` — when ``kea-lfc`` starts, this is the result of any - previous run of ``kea-lfc``. When ``kea-lfc`` finishes, it is the - result of this run. If ``kea-lfc`` is interrupted before completing, +- ``previous`` — when :iscman:`kea-lfc` starts, this is the result of any + previous run of :iscman:`kea-lfc`. When :iscman:`kea-lfc` finishes, it is the + result of this run. If :iscman:`kea-lfc` is interrupted before completing, this file may not exist. -- ``input`` — before the DHCP server invokes ``kea-lfc``, it moves - the current lease file here and then calls ``kea-lfc`` with this file. +- ``input`` — before the DHCP server invokes :iscman:`kea-lfc`, it moves + the current lease file here and then calls :iscman:`kea-lfc` with this file. -- ``output`` — this is the temporary file where ``kea-lfc`` writes the +- ``output`` — this is the temporary file where :iscman:`kea-lfc` writes the leases. Once the file has finished writing, it is moved to the ``finish`` file (see below). -- ``finish`` — this is another temporary file ``kea-lfc`` uses for - bookkeeping. When ``kea-lfc`` completes writing the ``output`` file, it - moves the contents to the file of this name. After ``kea-lfc`` finishes deleting the +- ``finish`` — this is another temporary file :iscman:`kea-lfc` uses for + bookkeeping. When :iscman:`kea-lfc` completes writing the ``output`` file, it + moves the contents to the file of this name. After :iscman:`kea-lfc` finishes deleting the other files (``previous`` and ``input``), it moves this file to the ``previous`` - lease file. By moving the files in this fashion, ``kea-lfc`` and + lease file. By moving the files in this fashion, :iscman:`kea-lfc` and the DHCP server processes can determine the correct file to use even if one of the processes is interrupted before completing its task. diff --git a/doc/sphinx/arm/logging.rst b/doc/sphinx/arm/logging.rst index 351d9c0fa7..0ccd9b35d8 100644 --- a/doc/sphinx/arm/logging.rst +++ b/doc/sphinx/arm/logging.rst @@ -85,8 +85,8 @@ loggers. For example, the DHCPv4 server binary contains separate loggers for packet parsing, dropped packets, callouts, etc. The loggers form a hierarchy. For each program in Kea, there is a "root" -logger, named after the program (e.g. the root logger for ``kea-dhcp4``, the -DHCPv4 server, is named ``kea-dhcp4``). All other loggers are children of +logger, named after the program (e.g. the root logger for :iscman:`kea-dhcp4`, the +DHCPv4 server, is named :iscman:`kea-dhcp4`). All other loggers are children of this logger and are named accordingly, e.g. the allocation engine in the DHCPv4 server logs messages using a logger called ``kea-dhcp4.alloc-engine``. @@ -99,7 +99,7 @@ for a given logger, any attributes specified override those of the root logger, whereas any not specified are inherited from it. To illustrate this, suppose we are using the DHCPv4 server with the -root logger ``kea-dhcp4`` logging at the INFO level. In order to enable +root logger :iscman:`kea-dhcp4` logging at the INFO level. In order to enable DEBUG verbosity for DHCPv4 packet drops, we must create a configuration entry for the logger with ``"name": "kea-dhcp4.bad-packets”``, ``"severity": "DEBUG"``, and an explicit debug level. All other configuration @@ -117,10 +117,10 @@ mechanism. If there are multiple logger specifications in the configuration that might match a particular logger, the specification with the more specific logger name takes precedence. For example, if there are entries -for both ``kea-dhcp4`` and ``kea-dhcp4.dhcpsrv``, the main DHCPv4 server +for both :iscman:`kea-dhcp4` and ``kea-dhcp4.dhcpsrv``, the main DHCPv4 server program — and all libraries it uses other than the ``dhcpsrv`` library (libdhcpsrv) — logs messages according to the configuration in the -first entry (``kea-dhcp4``). Messages generated by the ``dhcpsrv`` library +first entry (:iscman:`kea-dhcp4`). Messages generated by the ``dhcpsrv`` library are logged according to the configuration set by the second entry. Currently defined loggers are listed in the following table. The @@ -419,7 +419,7 @@ libraries), or hook libraries (open source or premium). | | | library. | +----------------------------------+------------------------+--------------------------------+ | ``kea-dhcp-ddns`` | core | The root logger for | - | | | the ``kea-dhcp-ddns`` | + | | | the :iscman:`kea-dhcp-ddns` | | | | daemon. All | | | | components used by | | | | this daemon inherit | @@ -431,7 +431,7 @@ libraries), or hook libraries (open source or premium). | | | loggers. | +----------------------------------+------------------------+--------------------------------+ | ``kea-dhcp-ddns.dctl`` | core | Used by | - | | | the ``kea-dhcp-ddns`` | + | | | the :iscman:`kea-dhcp-ddns` | | | | daemon to log | | | | basic information | | | | about the process, | @@ -440,13 +440,13 @@ libraries), or hook libraries (open source or premium). | | | reconfigurations. | +----------------------------------+------------------------+--------------------------------+ | ``kea-dhcp-ddns.dhcpddns`` | core | Used by | - | | | the ``kea-dhcp-ddns`` | + | | | the :iscman:`kea-dhcp-ddns` | | | | daemon to log | | | | events related to | | | | DDNS operations. | +----------------------------------+------------------------+--------------------------------+ | ``kea-dhcp-ddns.dhcp-to-d2`` | core | Used by the | - | | | ``kea-dhcp-ddns`` daemon | + | | | :iscman:`kea-dhcp-ddns` daemon | | | | to log | | | | information about | | | | events dealing with | @@ -457,7 +457,7 @@ libraries), or hook libraries (open source or premium). | | | processing. | +----------------------------------+------------------------+--------------------------------+ | ``kea-dhcp-ddns.d2-to-dns`` | core | Used by the | - | | | ``kea-dhcp-ddns`` daemon | + | | | :iscman:`kea-dhcp-ddns` daemon | | | | to log | | | | information about | | | | events dealing with | @@ -527,14 +527,14 @@ logger are inhibited. .. note:: - The ``keactrl`` tool, described in :ref:`keactrl`, can be configured + The :iscman:`keactrl` tool, described in :ref:`keactrl`, can be configured to start the servers in verbose mode. If this is the case, the settings of the logging severity in the configuration file have no effect; the servers use a logging severity of DEBUG regardless of the logging settings specified in the configuration file. To control severity via the configuration file, please make sure that the ``kea_verbose`` value is set to "no" within - the ``keactrl`` configuration. + the :iscman:`keactrl` configuration. .. _debuglevel: @@ -734,7 +734,7 @@ That breaks down to: - ``%c`` The log source. This includes two elements: the Kea process generating the - message, in this case, ``kea-dhcp4``; and the component within the program + message, in this case, :iscman:`kea-dhcp4`; and the component within the program from which the message originated, ``dhcpsrv`` (e.g. the name of the library used by DHCP server implementations). diff --git a/doc/sphinx/arm/quickstart.rst b/doc/sphinx/arm/quickstart.rst index 1fbb76d380..cf0360e28e 100644 --- a/doc/sphinx/arm/quickstart.rst +++ b/doc/sphinx/arm/quickstart.rst @@ -158,7 +158,7 @@ easier to install Kea using native packages. # service kea-dhcp6 restart .. note:: - ``keactrl`` is not available in packages, as similar functionality is provided + :iscman:`keactrl` is not available in packages, as similar functionality is provided by the native systemctl scripts. 7. On CentOS, Fedora, and Alpine, the service must be enabled at boot @@ -235,7 +235,7 @@ For system-specific instructions, please read the available in the Kea section of `ISC's Knowledgebase <https://kb.isc.org/docs>`__. -The details of ``keactrl`` script usage can be found in :ref:`keactrl`. +The details of :iscman:`keactrl` script usage can be found in :ref:`keactrl`. Once Kea services are up and running, consider deploying a dashboard solution to monitor running services. For more details, see :ref:`stork`. @@ -246,7 +246,7 @@ Running the Kea Servers Directly ================================ The Kea servers can be started directly, without the need to use -``keactrl`` or ``systemctl``. To start the DHCPv4 server run the following command: +:iscman:`keactrl` or ``systemctl``. To start the DHCPv4 server run the following command: .. code-block:: console diff --git a/doc/sphinx/arm/security.rst b/doc/sphinx/arm/security.rst index 0be39a86f0..3063fb0667 100644 --- a/doc/sphinx/arm/security.rst +++ b/doc/sphinx/arm/security.rst @@ -221,8 +221,8 @@ file cleanup; MySQL and or PostgreSQL databases, run either locally on the appli servers or accessed over the internal network; and a Stork monitoring system. This modular architecture allows the administrator to minimize the attack surface by minimizing the code that is loaded and running. -For example, ``kea-dhcp-ddns`` should not be run unless DNS updates are required. -Similarly, ``kea-lfc`` is never triggered (and can be safely removed or never installed) if memfile is not used. +For example, :iscman:`kea-dhcp-ddns` should not be run unless DNS updates are required. +Similarly, :iscman:`kea-lfc` is never triggered (and can be safely removed or never installed) if memfile is not used. Potential Kea security issues can be minimized by running only those processes required in the local environment. Limiting Application Permissions @@ -239,7 +239,7 @@ does not require privileged access. Securing Kea Administrative Access ---------------------------------- -The three primary Kea daemons (``kea-dhcp4``, ``kea-dhcp6`` and ``kea-dhcp-ddns``) all support a control +The three primary Kea daemons (:iscman:`kea-dhcp4`, :iscman:`kea-dhcp6` and :iscman:`kea-dhcp-ddns`) all support a control channel, which is implemented as a UNIX socket. The control channel, which opens a UNIX socket, is disabled by default; however, many configuration examples have it enabled, as it is a very popular feature. To read from or write to this socket, root access is generally required, although if Kea is configured diff --git a/doc/sphinx/arm/shell.rst b/doc/sphinx/arm/shell.rst index 4f6a7e3700..9e4cfdfd54 100644 --- a/doc/sphinx/arm/shell.rst +++ b/doc/sphinx/arm/shell.rst @@ -27,7 +27,7 @@ Kea 1.9.0 introduced basic HTTP authentication support. Shell Usage =========== -``kea-shell`` is run as follows: +:iscman:`kea-shell` is run as follows: .. code-block:: console @@ -140,7 +140,7 @@ tool. TLS Support =========== -Since Kea 1.9.6, ``kea-shell`` supports HTTPS connections. The TLS/HTTPS +Since Kea 1.9.6, :iscman:`kea-shell` supports HTTPS connections. The TLS/HTTPS support requires Python 3. The additional command-line arguments are: - ``--ca`` specifies the file or directory name of the Certification |