From: Andrei Pavel Date: Tue, 13 Jun 2023 13:33:13 +0000 (+0300) Subject: [#2554] address review comments X-Git-Tag: Kea-2.4.0~191 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7e1b388777d9602fddaf2119dbbed6afd069f3ad;p=thirdparty%2Fkea.git [#2554] address review comments --- diff --git a/doc/sphinx/arm/config-backend.rst b/doc/sphinx/arm/config-backend.rst index 8aab0923b1..30cf5f639b 100644 --- a/doc/sphinx/arm/config-backend.rst +++ b/doc/sphinx/arm/config-backend.rst @@ -243,8 +243,8 @@ servers. To differentiate between different Kea server configurations, a list of the server tags used by the servers must be stored in the database. For the DHCPv4 and DHCPv6 servers, it can be done using the -commands described in :ref:`command-remote-server4-set` and -:ref:`command-remote-server6-set`. The +:isccmd:`command-remote-server4-set` and +:isccmd:`command-remote-server6-set` commands. The server tags can then be used to associate the configuration information with the servers. However, it is important to note that some DHCP configuration elements may be associated with multiple server tags (known @@ -290,8 +290,9 @@ set to the same or different values. The renew timer parameter has no unique identifier by which it could be accessed, modified, or otherwise used. Global parameters like the renew timer can be accessed by the parameter name and the -tag of the server for which they are configured. For example: -the commands described in :ref:`command-remote-global-parameter4-get` allow +tag of the server for which they are configured. For example, the +:isccmd:`remote-global-parameter4-get` and +:isccmd:`remote-global-parameter6-get` commands allow the value of the global parameter to be fetched by the parameter name and the server name. Getting the global parameter only by its name (without specifying the server tag) is not possible, because there may be many diff --git a/doc/sphinx/arm/config.rst b/doc/sphinx/arm/config.rst index a0acd56b43..10e88751a7 100644 --- a/doc/sphinx/arm/config.rst +++ b/doc/sphinx/arm/config.rst @@ -211,7 +211,7 @@ to an existing subnet. } ] } -The same can be done with many other commands like lease6-add etc. +The same can be done with many other commands, like :isccmd:`lease6-add`, etc. Kea also uses user context to store non-standard data. Currently, only :ref:`dhcp4-store-extended-info` uses this feature. diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst index 49b6288486..0ee501849b 100644 --- a/doc/sphinx/arm/dhcp4-srv.rst +++ b/doc/sphinx/arm/dhcp4-srv.rst @@ -1587,7 +1587,7 @@ responses on subnet ``192.0.3.0/24``. ``never-send`` has precedence over .. note:: - The ``never-send`` flag is less powerful than :ref:`hooks-flex-option`; + The ``never-send`` flag is less powerful than :ischooklib:`libdhcp_flex_option.so`; for instance, it has no effect on options managed by the server itself. Both ``always-send`` and ``never-send`` have no effect on options which cannot be requested, for instance from a custom space. @@ -7488,8 +7488,8 @@ the DHCPv4 server parameters can be configured in the database. All other parameters must be specified in the JSON configuration file, if required. -All supported parameters can be configured via :ischooklib:`libdhcp_cb_cmds.so` -described in the :ref:`hooks-cb-cmds` section. The general rule is that +All supported parameters can be configured via :ischooklib:`libdhcp_cb_cmds.so`. +The general rule is that scalar global parameters are set using :isccmd:`remote-global-parameter4-set`; shared-network-specific parameters are set using :isccmd:`remote-network4-set`; and subnet-level and pool-level diff --git a/doc/sphinx/arm/dhcp6-srv.rst b/doc/sphinx/arm/dhcp6-srv.rst index 0b827aa343..655eed2f35 100644 --- a/doc/sphinx/arm/dhcp6-srv.rst +++ b/doc/sphinx/arm/dhcp6-srv.rst @@ -1511,7 +1511,7 @@ on subnet ``2001:db8:1::/64``. ``never-send`` has precedence over .. note:: - The ``never-send`` flag is less powerful than :ref:`hooks-flex-option`; + The ``never-send`` flag is less powerful than :ischooklib:`libdhcp_flex_option.so`; for instance, it has no effect on options managed by the server itself. Both ``always-send`` and ``never-send`` have no effect on options which cannot be requested, for instance from a custom space. @@ -7197,8 +7197,8 @@ the DHCPv6 server parameters can be configured in the database. All other parameters must be specified in the JSON configuration file, if required. -All supported parameters can be configured via :ischooklib:`libdhcp_cb_cmds.so` -described in the :ref:`hooks-cb-cmds` section. The general rule is that +All supported parameters can be configured via :ischooklib:`libdhcp_cb_cmds.so`. +The general rule is that scalar global parameters are set using :isccmd:`remote-global-parameter6-set`; shared-network-specific parameters are set using :isccmd:`remote-network6-set`; and subnet-level and pool-level diff --git a/doc/sphinx/arm/ext-gss-tsig.rst b/doc/sphinx/arm/ext-gss-tsig.rst index f8c66a2db0..e754d8911b 100644 --- a/doc/sphinx/arm/ext-gss-tsig.rst +++ b/doc/sphinx/arm/ext-gss-tsig.rst @@ -863,8 +863,7 @@ GSS-TSIG Automatic Key Removal The server periodically deletes keys after they have been expired more than three times the length of the maximum key lifetime (the ``tkey-lifetime`` parameter). The user has the option to purge keys on demand by using the :isccmd:`gss-tsig-purge-all` -command (see :ref:`command-gss-tsig-purge-all`) or the :isccmd:`gss-tsig-purge` command -(see :ref:`command-gss-tsig-purge`). +command or the :isccmd:`gss-tsig-purge` command. GSS-TSIG Configuration for Deployment diff --git a/doc/sphinx/arm/hooks-cb-cmds.rst b/doc/sphinx/arm/hooks-cb-cmds.rst index 6d8ad1e1ba..def9b5be92 100644 --- a/doc/sphinx/arm/hooks-cb-cmds.rst +++ b/doc/sphinx/arm/hooks-cb-cmds.rst @@ -44,7 +44,7 @@ There are 5 types of commands supported by this library: :isccmd:`remote-global-parameter4-del`. - ``get`` - fetch the selected object from the database, e.g. - ``remote-subnet4-get``. + :isccmd:`remote-subnet4-get`. - ``get-all`` - fetch all objects of the particular type from the database, e.g. :isccmd:`remote-option-def4-get-all`. @@ -1391,7 +1391,7 @@ DHCP option, the option code should be indicated instead of the name. .. isccmd:: remote-option6-pd-pool-del .. _command-remote-option6-pd-pool-del: -The remote-option6-pd-pool-del Command +The ``remote-option6-pd-pool-del`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command is used to delete a prefix delegation pool-specific DHCPv6 @@ -1435,7 +1435,7 @@ options belong. The ``server-tags`` parameter cannot be specified for this comma .. isccmd:: remote-option6-pd-pool-set .. _command-remote-option6-pd-pool-set: -The remote-option6-pd-pool-set Command +The ``remote-option6-pd-pool-set`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command creates a new prefix delegation pool-specific DHCPv6 option or diff --git a/doc/sphinx/arm/hooks-class-cmds.rst b/doc/sphinx/arm/hooks-class-cmds.rst index bb1baff335..2fe6c73b45 100644 --- a/doc/sphinx/arm/hooks-class-cmds.rst +++ b/doc/sphinx/arm/hooks-class-cmds.rst @@ -15,8 +15,8 @@ list the client classes configured for a given server. 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. +:ischooklib:`libdhcp_class_cmds.so` is only available to ISC customers with a +paid support contract. .. isccmd:: class-add .. _command-class-add: diff --git a/doc/sphinx/arm/hooks-ha.rst b/doc/sphinx/arm/hooks-ha.rst index c6a9738d0d..c81bd920f8 100644 --- a/doc/sphinx/arm/hooks-ha.rst +++ b/doc/sphinx/arm/hooks-ha.rst @@ -149,10 +149,10 @@ remove a name associated with this lease from the DNS, causing problems when the client later attempts to renew the lease. Each active server monitors the clock skew by comparing its current time with -the time returned by its partner in response to the heartbeat command. This +the time returned by its partner in response to the :isccmd:`ha-heartbeat` command. This gives a good approximation of the clock skew, although it does not take into account the time between the partner sending the response and the receipt of -this response by the server which sent the heartbeat command. If the clock skew +this response by the server which sent the :isccmd:`ha-heartbeat` command. If the clock skew exceeds 30 seconds, a warning log message is issued. The administrator may correct this problem by synchronizing the clocks (e.g. using NTP); the servers should notice the clock skew correction and stop issuing the warning. @@ -1306,7 +1306,7 @@ Controlling Lease-Page Size Limit An HA-enabled server initiates synchronization of the lease database after downtime or upon receiving the :isccmd:`ha-sync` command. The server uses commands -described in :ref:`command-lease4-get-page` and :ref:`command-lease6-get-page` +:isccmd:`lease4-get-page` and :isccmd:`lease6-get-page` to fetch leases from its partner server (lease queries). The size of the results page (the maximum number of leases to be returned in a single response to one of these commands) can be controlled via configuration of the HA hook library. @@ -2175,7 +2175,7 @@ about the remote server is reliable. The ``last-scopes`` and ``last-state`` parameters contain information about the HA scopes served by the partner and its state. This information is gathered -during the heartbeat command exchange, so it may not be accurate if a +during the :isccmd:`ha-heartbeat` command exchange, so it may not be accurate if a communication problem occurs between the partners and this status information is not refreshed. In such a case, it may be useful to send the :isccmd:`status-get` command to the partner server directly to check its current state. The ``age`` @@ -2349,7 +2349,7 @@ The ``ha-sync-complete-notify`` Command A server sends this command to its partner to signal that it has completed lease-database synchronization. The partner may enable its DHCP service if it can allocate new leases in its current state. The partner does not enable the -DHCP service in the ``partner-down`` state until it sends a successful heartbeat +DHCP service in the ``partner-down`` state until it sends a successful :isccmd:`ha-heartbeat` test to its partner server. If the connection is still unavailable, the server in the ``partner-down`` state enables its own DHCP service to continue responding to clients. diff --git a/doc/sphinx/arm/hooks-host-cmds.rst b/doc/sphinx/arm/hooks-host-cmds.rst index 93a0395122..0a76c27688 100644 --- a/doc/sphinx/arm/hooks-host-cmds.rst +++ b/doc/sphinx/arm/hooks-host-cmds.rst @@ -58,7 +58,7 @@ load, but any attempts to use :isccmd:`reservation-add`, :isccmd:`reservation-de These commands can also modify hosts from the JSON configuration independently from the hosts database. The changes provided in the JSON configuration are -volatile and can be made permanent by sending the config-write command. +volatile and can be made permanent by sending the :isccmd:`config-write` command. For a description of proposed future commands, see the `Control API Requirements `__ @@ -90,7 +90,7 @@ Before examining the individual commands, it is worth discussing the parameter ``subnet-id``. Currently this parameter is mandatory for all of the commands supplied by this library, with the exception of :isccmd:`reservation-get-by-hostname`, where it is optional. Since Kea 1.9.0, -:isccmd:``subnet-id`` is also optional in `reservation-get-page`, and +``subnet-id`` is also optional in :isccmd:`reservation-get-page`, and it is forbidden in :isccmd:`reservation-get-by-id`. Reservations can be specified globally, and are not necessarily specific to any @@ -425,8 +425,7 @@ The response returned by :isccmd:`reservation-get-all` can be very long. The DHCP server does not handle DHCP traffic while preparing a response to :isccmd:`reservation-get-all`, so if there are many reservations in a subnet, this may be disruptive; use with caution. For larger deployments, please -consider using :isccmd:`reservation-get-page` instead (see -:ref:`command-reservation-get-page`). +consider using :isccmd:`reservation-get-page` instead. The command accepts the ``operation-target`` argument. By default, it gets the reservation from both JSON configuration and the hosts database. @@ -572,7 +571,7 @@ The command doesn't accept the ``operation-target`` argument. This command is more complex than :isccmd:`reservation-get-all`, but lets users retrieve larger host reservations lists in smaller chunks. For small deployments with few reservations, it is easier to use -:isccmd:`reservation-get-all` (see :ref:`command-reservation-get-all`). +:isccmd:`reservation-get-all`. .. isccmd:: reservation-get-by-hostname .. _command-reservation-get-by-hostname: @@ -668,7 +667,7 @@ The ``reservation-get-by-id`` Command :isccmd:`reservation-get-by-id` can be used to query the host database and retrieve all reservations with a specified identifier (``identifier-type`` and ``identifier`` parameters), independently of subnets. The syntax for -parameters is the same as for ref:`command-reservation-get`. +parameters is the same as for :isccmd:`reservation-get`. The ``subnet-id`` parameter cannot be used, to avoid confusion. This command is available since Kea version 1.9.0. @@ -838,7 +837,7 @@ The ``reservation-update`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :isccmd:`reservation-update` allows for the update of an existing host. It takes the -same set of arguments as :ref:``command-reservation-add``, and just as well, +same set of arguments as :isccmd:`reservation-add`, and just as well, requires a host identifier and a subnet ID to identify the host that is being updated. The command can be as simple as having only the two mandatory entries: diff --git a/doc/sphinx/arm/hooks-lease-cmds.rst b/doc/sphinx/arm/hooks-lease-cmds.rst index c6a0d10047..ac3601602a 100644 --- a/doc/sphinx/arm/hooks-lease-cmds.rst +++ b/doc/sphinx/arm/hooks-lease-cmds.rst @@ -284,7 +284,7 @@ Example failure: .. isccmd:: lease6-bulk-apply .. _command-lease6-bulk-apply: -The lease6-bulk-apply Command +The ``lease6-bulk-apply`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The :isccmd:`lease6-bulk-apply` was implemented to address @@ -803,7 +803,7 @@ The ``lease4-del``, ``lease6-del`` Commands :isccmd:`lease4-del` and :isccmd:`lease6-del` can be used to delete a lease from the lease database. There are two types of parameters these commands support, similar to the -:isccmd::isccmd:`lease4-get` and `lease6-get` commands: (``address``) for both v4 and v6, (``subnet-id``, +:isccmd:`lease4-get` and :isccmd:`lease6-get` commands: (``address``) for both v4 and v6, (``subnet-id``, ``identifier-type``, ``identifier``) for v4, and (``subnet-id``, ``identifier-type``, ``identifier``, ``type``, ``IAID``) for v6. The first type of query is used when the address (either IPv4 or IPv6) is known, but the details of the lease are @@ -892,7 +892,7 @@ to ``false``, which indicates that the lease is not created if it does not exist. In such a case, an error is returned when trying to update a non-existing lease. If the ``"force-create"`` parameter is set to ``true`` and the updated lease does not exist, the new lease is created as a -result of receiving the :isccmd::isccmd:`lease4-update`/`lease6-update` command. +result of receiving the :isccmd:`lease4-update` / :isccmd:`lease6-update` command. An example of a command to update an IPv4 lease is: @@ -927,12 +927,12 @@ An example of a command to update an IPv6 lease is: As with other update commands, this command overwrites all the contents of the entry. If the lease previously had a resource assigned to it, and the -:isccmd::isccmd:`lease4-update`/`lease6-update` command is missing the resource, it is +:isccmd:`lease4-update` / :isccmd:`lease6-update` command is missing the resource, it is deleted from the lease database. If an incremental update of the lease is desired, then this can be achieved by doing a :isccmd:`lease4-get` / :isccmd:`lease6-get` command to get the current state of the lease, picking the lease out of the response, modifying it to the required outcome, and then issuing the -:isccmd::isccmd:`lease4-update`/`lease6-update` command with the resulting lease attached. +:isccmd:`lease4-update` / :isccmd:`lease6-update` command with the resulting lease attached. .. isccmd:: lease4-wipe .. _command-lease4-wipe: diff --git a/doc/sphinx/arm/hooks-stat-cmds.rst b/doc/sphinx/arm/hooks-stat-cmds.rst index eccbfaafa3..bc751b9005 100644 --- a/doc/sphinx/arm/hooks-stat-cmds.rst +++ b/doc/sphinx/arm/hooks-stat-cmds.rst @@ -54,7 +54,7 @@ parameters: In a deployment with multiple Kea DHCP servers sharing a common lease storage, this hook library may be loaded by any or all of the servers. However, a server's response to a :isccmd:`stat-lease4-get` / :isccmd:`stat-lease6-get` -``stat-lease[46]-get`` command will only contain data for subnets known to +command will only contain data for subnets known to that server. In other words, if a subnet does not appear in a server's configuration, Kea will not retrieve statistics for it. diff --git a/doc/sphinx/arm/hooks-subnet-cmds.rst b/doc/sphinx/arm/hooks-subnet-cmds.rst index 878a7dc025..c1e06cd95a 100644 --- a/doc/sphinx/arm/hooks-subnet-cmds.rst +++ b/doc/sphinx/arm/hooks-subnet-cmds.rst @@ -64,7 +64,7 @@ The following commands are currently supported: .. isccmd:: subnet4-list .. _command-subnet4-list: -The subnet4-list Command +The ``subnet4-list`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command is used to list all currently configured subnets. Each @@ -107,7 +107,7 @@ error description. .. isccmd:: subnet6-list .. _command-subnet6-list: -The subnet6-list Command +The ``subnet6-list`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command is used to list all currently configured subnets. Each @@ -150,7 +150,7 @@ error description. .. isccmd:: subnet4-get .. _command-subnet4-get: -The subnet4-get Command +The ``subnet4-get`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command is used to retrieve detailed information about the @@ -206,7 +206,7 @@ If the subnet exists, the response will be similar to this: .. isccmd:: subnet6-get .. _command-subnet6-get: -The subnet6-get Command +The ``subnet6-get`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command is used to retrieve detailed information about the @@ -262,7 +262,7 @@ If the subnet exists, the response will be similar to this: .. isccmd:: subnet4-add .. _command-subnet4-add: -The subnet4-add Command +The ``subnet4-add`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command is used to create and add a new subnet to the existing server @@ -310,7 +310,7 @@ The response to this command has the following structure: .. isccmd:: subnet6-add .. _command-subnet6-add: -The subnet6-add Command +The ``subnet6-add`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command is used to create and add a new subnet to the existing server @@ -383,7 +383,7 @@ automatic ``subnet-id`` generation works in Kea. .. isccmd:: subnet4-update .. _command-subnet4-update: -The subnet4-update Command +The ``subnet4-update`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command is used to update (overwrite) a single subnet in the existing @@ -437,7 +437,7 @@ this can be achieved with :isccmd:`subnet4-delta-add`. .. isccmd:: subnet6-update .. _command-subnet6-update: -The subnet6-update Command +The ``subnet6-update`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command is used to update (overwrite) a single subnet in the existing @@ -491,7 +491,7 @@ this can be achieved with :isccmd:`subnet6-delta-add`. .. isccmd:: subnet4-del .. _command-subnet4-del: -The subnet4-del Command +The ``subnet4-del`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command is used to remove a subnet from the server's configuration. @@ -547,7 +547,7 @@ A successful response may look like this: .. isccmd:: subnet6-del .. _command-subnet6-del: -The subnet6-del Command +The ``subnet6-del`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command is used to remove a subnet from the server's configuration. @@ -601,7 +601,7 @@ A successful response may look like this: .. isccmd:: subnet4-delta-add .. _command-subnet4-delta-add: -The subnet4-delta-add Command +The ``subnet4-delta-add`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command is used to update a subnet by adding or overwriting its parts in @@ -679,7 +679,7 @@ level option 4 ("time-servers"). .. isccmd:: subnet6-delta-add .. _command-subnet6-delta-add: -The subnet6-delta-add Command +The ``subnet6-delta-add`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command is used to update a subnet by adding or overwriting its parts in @@ -776,7 +776,7 @@ level option 22 ("sip-server-addr"). .. isccmd:: subnet4-delta-del .. _command-subnet4-delta-del: -The subnet4-delta-del Command +The ``subnet4-delta-del`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command is used to update a subnet by removing its parts in the existing @@ -853,7 +853,7 @@ be parsed. .. isccmd:: subnet6-delta-del .. _command-subnet6-delta-del: -The subnet6-delta-del Command +The ``subnet6-delta-del`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command is used to update a subnet by removing its parts in the existing