From: Suzanne Goldlust Date: Tue, 16 Jul 2019 18:35:04 +0000 (-0400) Subject: Additional edits, Sphinx formatting X-Git-Tag: Kea-1.6.1~10^2~85 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2c8cfbfc7c949764be7ae66e2800a9ca308ce40d;p=thirdparty%2Fkea.git Additional edits, Sphinx formatting --- diff --git a/doc/guide/classify.rst b/doc/guide/classify.rst index ddcd734230..244a037e9b 100644 --- a/doc/guide/classify.rst +++ b/doc/guide/classify.rst @@ -98,7 +98,7 @@ The classification process is conducted in several steps: .. - .. note:: +.. note:: Client classes in Kea follow the order in which they are specified in the configuration (vs. alphabetical order). Required classes follow @@ -120,7 +120,7 @@ the client requested. As the NTP server was defined twice, the server chooses only one of the values for the reply; the class from which the value is obtained is unspecified. - .. note:: +.. note:: Care should be taken with client classification, as it is easy for clients that do not meet any class criteria to be denied service @@ -413,7 +413,7 @@ Notes: than one appear. For the vendor.enterprise and vendor-class.enterprise expressions, the value from the first instance is returned. Please submit a feature request on the - `Kea GitLab site `__ if you need + `Kea GitLab site `__ to request support for multiple instances. .. table:: List of Classification Expressions @@ -517,7 +517,7 @@ digits separated by the separator, e.g ':', '-', '' (empty separator). .. - .. note:: +.. note:: The expression for each class is executed on each packet received. If the expressions are overly complex, the time taken to execute them @@ -543,7 +543,7 @@ The option data is a list which defines any options that should be assigned to members of this class. The option definition is for DHCPv4 option 43 -(:ref:`dhcp4-vendor-opts` and DHCPv4 private options +(:ref:`dhcp4-vendor-opts`) and DHCPv4 private options (:ref:`dhcp4-private-opts`). Usually the test expression is evaluated before subnet selection, but in @@ -889,17 +889,17 @@ The logging might then resemble this: :: - 2016-05-19 13:35:04.163 DEBUG [kea.eval/44478] EVAL_DEBUG_OPTION Pushing option 61 with value 0x666F6F626172 - 2016-05-19 13:35:04.164 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string '0' - 2016-05-19 13:35:04.165 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string '3' - 2016-05-19 13:35:04.166 DEBUG [kea.eval/44478] EVAL_DEBUG_SUBSTRING Popping length 3, start 0, string 0x666F6F626172 pushing result 0x666F6F - 2016-05-19 13:35:04.167 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string 'foo' - 2016-05-19 13:35:04.168 DEBUG [kea.eval/44478] EVAL_DEBUG_EQUAL Popping 0x666F6F and 0x666F6F pushing result 'true' + 2016-05-19 13:35:04.163 DEBUG [kea.eval/44478] EVAL_DEBUG_OPTION Pushing option 61 with value 0x666F6F626172 + 2016-05-19 13:35:04.164 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string '0' + 2016-05-19 13:35:04.165 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string '3' + 2016-05-19 13:35:04.166 DEBUG [kea.eval/44478] EVAL_DEBUG_SUBSTRING Popping length 3, start 0, string 0x666F6F626172 pushing result 0x666F6F + 2016-05-19 13:35:04.167 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string 'foo' + 2016-05-19 13:35:04.168 DEBUG [kea.eval/44478] EVAL_DEBUG_EQUAL Popping 0x666F6F and 0x666F6F pushing result 'true' .. - .. note:: +.. note:: The debug logging may be quite verbose if there are a number of expressions to evaluate; that is intended as an aid in helping diff --git a/doc/guide/congestion-handling.rst b/doc/guide/congestion-handling.rst index 9d700f3cf0..5f7e85b317 100644 --- a/doc/guide/congestion-handling.rst +++ b/doc/guide/congestion-handling.rst @@ -4,7 +4,7 @@ Congestion Handling in DHCPv4 and DHCPv6 **************************************** -.. _congeston-handling-background: +.. _congestion-handling-background: What is Congestion? =================== @@ -39,7 +39,7 @@ that were no longer relevant, or worse, were redundant. In other words, the packets waiting in the FIFO socket buffers became increasingly stale. -.. _congeston-handling-solution: +.. _congestion-handling-solution: Configuring Congestion Handling =============================== @@ -70,7 +70,8 @@ queue is implemented as a plug-in, which can replaced by a custom queue implementation via a hook library. This should make it straightforward for interested parties to experiment with their own solutions. (Developers can refer to isc::dhcp::PacketQueue and -isc::dhcp::PacketQueueMgr, described in the Kea Developer's Guide). +isc::dhcp::PacketQueueMgr, described in the +`Kea Developer's Guide `__.) Packet queue behavior is configured in both kea-dhcp4 and kea-dhcp6 servers through an optional, top-level, configuration element, diff --git a/doc/guide/ddns.rst b/doc/guide/ddns.rst index b1eade2229..c3399a6791 100644 --- a/doc/guide/ddns.rst +++ b/doc/guide/ddns.rst @@ -141,7 +141,7 @@ Upon startup, the module will load its configuration and begin listening for NCRs based on that configuration. During startup, the server will attempt to create a PID file of the form: -[localstatedir]/[conf name].kea-dhcp-ddns.pid where: +[**localstatedir**]/[**conf name**].kea-dhcp-ddns.pid where: - ``localstatedir`` - is the value as passed into the build configure script; it defaults to "/usr/local/var". Note that this value may be @@ -560,7 +560,7 @@ This section describes how to add Reverse DDNS Domains; repeat these steps for each Reverse DDNS Domain desired. Each Reverse DDNS Domain has the following parameters: -- ``name`` - the fully qualified reverse zone that this DDNS Domain can +- ``name`` - the fully qualified reverse zone that this DDNS domain can update. This is the value used during reverse matching, which will compare it with a reversed version of the request's lease address. The zone name should follow the appropriate standards; for example, diff --git a/doc/guide/dhcp6-srv.rst b/doc/guide/dhcp6-srv.rst index ca9b89d2a5..037bc455a5 100644 --- a/doc/guide/dhcp6-srv.rst +++ b/doc/guide/dhcp6-srv.rst @@ -58,7 +58,7 @@ configuration file. Since the DHCPv6 server opens privileged ports, it requires root access. This daemon must be run as root. During startup, the server will attempt to create a PID file of the -form: localstatedir]/[conf name].kea-dhcp6.pid where: +form: [**localstatedir**]/[**conf name**].kea-dhcp6.pid where: - ``localstatedir``: The value as passed into the build configure script; it defaults to "/usr/local/var". Note that this value may be @@ -571,7 +571,7 @@ be set to "mysql" or "postgresql". Next, the name of the database to hold the reservations must be set; this is the name used when the lease database was created (see -`:ref:`supported-databases` for instructions on how to set up the +:ref:`supported-databases` for instructions on how to set up the desired database type): :: @@ -1782,10 +1782,10 @@ last field is an array, i.e. it can contain more than one value, as in: ... } -The new option content is one IPv6 address followed by one or more 16- -bit unsigned integers. +The new option content is one IPv6 address followed by one or more 16-bit +unsigned integers. - .. note:: +.. note:: In general, boolean values are specified as ``true`` or ``false``, without quotes. Some specific boolean parameters may accept also @@ -2082,7 +2082,7 @@ Calculation of the values is controlled by the following three parameters: .. - .. note:: +.. note:: In the event that both explicit values are specified and calculate-tee-times is true, the server will use the explicit values. @@ -2332,7 +2332,7 @@ class list for the packet. The second specifies an expression that is evaluated for each packet. If the result is "true", the packet is a member of the class. - .. note:: +.. note:: Care should be taken with client classification, as it is easy for clients that do not meet class criteria to be denied all service. @@ -2614,7 +2614,7 @@ will generate NCRs and the configuration parameters that can be used to influence this decision. It assumes that the ``enable-updates`` parameter is true. - .. note:: +.. note:: Currently the interface between kea-dhcp6 and D2 only supports requests which update DNS entries for a single IP address. If a lease @@ -2753,7 +2753,7 @@ parameter, which provides the following modes of behavior: .. - .. note:: +.. note:: Note that in early versions of Kea, this parameter was a boolean and permitted only values of ``true`` and ``false``. @@ -2808,25 +2808,25 @@ are enabled. To set its value simply set it to the desired string: When qualifying a partial name, kea-dhcp6 will construct the name in the format: -[candidate-name].[qualifying-suffix]. +[**candidate-name**].[**qualifying-suffix**]. -where candidate-name is the partial name supplied in the DHCPREQUEST. +where **candidate-name** is the partial name supplied in the DHCPREQUEST. For example, if the FQDN domain name value is "some-computer" and the qualifying-suffix "example.com", the generated FQDN is: -some-computer.example.com. +**some-computer.example.com.** When generating the entire name, kea-dhcp6 will construct the name in the format: -[generated-prefix]-[address-text].[qualifying-suffix]. +[**generated-prefix**]-[**address-text**].[**qualifying-suffix**]. -where address-text is simply the lease IP address converted to a +where **address-text** is simply the lease IP address converted to a hyphenated string. For example, if the lease address is 3001:1::70E, the qualifying suffix "example.com", and the default value is used for ``generated-prefix``, the generated FQDN is: -myhost-3001-1--70E.example.com. +**myhost-3001-1--70E.example.com.** .. _host-name-sanitization: @@ -2870,7 +2870,7 @@ Thus, a client-supplied value of "myhost-$[123.org" would become name supplied by the client, and it is performed before applying a qualifying suffix (if one is defined and needed). - .. note:: +.. note:: The following are some considerations to keep in mind: Name sanitizing is meant to catch the more common cases of invalid @@ -2909,7 +2909,7 @@ cooperating DHCPv4 and DHCPv6 servers. This section is about the configuration of the DHCPv6 side (the DHCPv4 side is described in :ref:`dhcp4-dhcp4o6-config`). - .. note:: +.. note:: DHCPv4-over-DHCPv6 support is experimental and the details of the inter-process communication may change; both the DHCPv4 and DHCPv6 @@ -2980,7 +2980,7 @@ The following configuration was used during some tests: .. - .. note:: +.. note:: Relayed DHCPv4-QUERY DHCPv6 messages are not supported. @@ -3195,10 +3195,10 @@ global reservations defined. Typically, such reservations would be used to reserve hostnames for clients which may move from one subnet to another. - .. note:: +.. note:: Global reservations, while useful in certain circumstances, have aspects - that must be given due consideration when using them, please see + that must be given due consideration. Please see :ref:`reservation6-conflict` for more details. .. _reservation6-conflict: @@ -3250,7 +3250,7 @@ conflict with existing leases. Another recommendation is to use out-of-pool reservations. If the reserved address does not belong to a pool, there is no way that other clients can get it. - .. note:: +.. note:: The conflict-resolution mechanism does not work for global reservations. Although the global address reservations feature may be useful @@ -3437,7 +3437,7 @@ with classification, using expressions. The "KNOWN" or "UNKNOWN" built-in class is added to the packet and any class depending on it (directly or indirectly) and not only-if-required is evaluated. - .. note:: +.. note:: To force the evaluation of a class expression after the host reservation lookup, for instance because of a dependency on @@ -3459,7 +3459,7 @@ The `Kea wiki provides some examples of how to conduct common host reservations operations. - .. note:: +.. note:: In Kea, the maximum length of an option specified per-host is arbitrarily set to 4096 bytes. @@ -3723,7 +3723,7 @@ before the pools in the first subnet get exhausted; this sometimes occurs when the client provides a hint that belongs to another subnet, or the client has reservations in a subnet other than the default. - .. note:: +.. note:: Deployments should not assume that Kea waits until it has allocated all the addresses from the first subnet in a shared network before @@ -4168,7 +4168,7 @@ When a new DUID type is selected, the server generates its value and replaces any existing DUID in the file. The server then uses the new server identifier in all future interactions with the clients. - .. note:: +.. note:: If the new server identifier is created after some clients have obtained their leases, the clients using the old identifier are not @@ -4512,7 +4512,7 @@ selects that subnet for a relay with address 3000::1. If "relay" is specified, the "ip-addresses" parameter within it is mandatory. - .. note:: +.. note:: The current version of Kea uses the "ip-addresses" parameter, which supports specifying a list of addresses. @@ -4758,7 +4758,7 @@ back to the available pool. Statistics in the DHCPv6 Server =============================== - .. note:: +.. note:: This section describes DHCPv6-specific statistics. For a general overview and usage of statistics, see :ref:`stats`. @@ -5499,7 +5499,7 @@ The following standards are currently supported: - *Dynamic Host Configuration Protocol for IPv6 (DHCPv6)*, `RFC 8415 `__: New DHCPv6 protocol specification which obsoletes RFC 3315, RFC 3633, RFC 3736, RFC 4242, - RFC 7083, RFC 7283, and RFC 7550 + RFC 7083, RFC 7283, and RFC 7550. .. _dhcp6-limit: diff --git a/doc/guide/hooks-class-cmds.rst b/doc/guide/hooks-class-cmds.rst index d28d1a3e5e..653871820a 100644 --- a/doc/guide/hooks-class-cmds.rst +++ b/doc/guide/hooks-class-cmds.rst @@ -141,7 +141,7 @@ the specified client class has been found: "text": "Class 'ipxe_efi_x64' deleted." } -If the class doesn't exist, the result of 3 is returned. +If the class does not exist, the result of 3 is returned. .. _command-class-list: diff --git a/doc/guide/hooks-ha.rst b/doc/guide/hooks-ha.rst index e27ab9bc5b..5389c97bb6 100644 --- a/doc/guide/hooks-ha.rst +++ b/doc/guide/hooks-ha.rst @@ -9,7 +9,7 @@ of the DHCP service in the event of an outage of one of the servers. This library was previously only available to ISC's paid subscribers, but is now part of the open source Kea, available to all users. - .. note:: +.. note:: This library may only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6`` process. @@ -223,7 +223,7 @@ The following is the list of all possible server states: .. - .. note:: +.. note:: Currently, restarting the HA service from the ``terminated`` state requires restarting the DHCP server or reloading its configuration. @@ -295,7 +295,8 @@ in normal operation serves no scopes. The scope names can be used to associate pools, subnets, and networks with certain servers, so only these servers can allocate addresses or prefixes from those pools, subnets, or networks. This is done via the -client classification mechanism (see below). +client classification mechanism (see :ref:`ha-load-balancing-advanced-config` +for more details). .. _ha-scope-transition: @@ -394,13 +395,13 @@ with the only difference that ``this-server-name`` should be set to }] } -Two hook libraries must be loaded to enable HA: +Two hooks libraries must be loaded to enable HA: ``libdhcp_lease_cmds.so`` and ``libdhcp_ha.so``. The latter implements the HA feature, while the former enables control commands required by HA to fetch and manipulate leases on the remote servers. In the example provided above, it is assumed that Kea libraries are installed in the ``/usr/lib`` directory. If Kea is not installed in the /usr directory, -the hook libraries locations must be updated accordingly. +the hooks libraries locations must be updated accordingly. The HA configuration is specified within the scope of ``libdhcp_ha.so``. Note that the top-level parameter ``high-availability`` is a list, even @@ -803,8 +804,8 @@ less than 10000 lines. .. _ha-syncing-timeouts: -Discussion About Timeouts -------------------------- +Timeouts +-------- In deployments with a large number of clients connected to the network, lease-database synchronization after a server failure may be a @@ -881,10 +882,10 @@ the Kea source at: ``src/lib/config/timeouts.h``. .. _ha-pause-state-machine: -Pausing HA State Machine ------------------------- +Pausing the HA State Machine +---------------------------- -The high availability state machine includes many different states +The high-availability state machine includes many different states described in detail in :ref:`ha-server-states`. The server enters each state when certain conditions are met, most often taking into account the partner server's state. In some states the server @@ -1038,7 +1039,7 @@ states; however, it is not practical for the ``backup`` and ``terminated`` states because the server never transitions out of these states anyway. - .. note:: +.. note:: In the ``syncing`` state the server is paused before it makes an attempt to synchronize the lease database with a partner. To pause @@ -1047,7 +1048,7 @@ states anyway. .. - .. note:: +.. note:: The state of the HA state machine depends on the state of the cooperating server. Therefore, it must be taken into account that diff --git a/doc/guide/hooks-host-cache.rst b/doc/guide/hooks-host-cache.rst index 44168316ae..60aad0168f 100644 --- a/doc/guide/hooks-host-cache.rst +++ b/doc/guide/hooks-host-cache.rst @@ -44,7 +44,7 @@ any other hooks library; for example, this configuration could be used: } } ] -Once loaded, the Host Cache hook library provides a number of new +Once loaded, the Host Cache hooks library provides a number of new commands which can be used either over the control channel (see :ref:`ctrl-channel-client`) or the RESTful API (see :ref:`agent-overview`). An example RESTful API client is described in @@ -69,7 +69,7 @@ removed. An example usage looks as follows: This command will remove 1000 hosts. To delete all cached hosts, please use cache-clear instead. The hosts are stored in FIFO -order, so the oldest entries are always removed. +(first-in, first-out) order, so the oldest entries are always removed. .. _command-cache-clear: diff --git a/doc/guide/hooks-radius.rst b/doc/guide/hooks-radius.rst index d2f20939fc..0f9811ee75 100644 --- a/doc/guide/hooks-radius.rst +++ b/doc/guide/hooks-radius.rst @@ -3,7 +3,7 @@ radius: RADIUS Server Support ============================= -The RADIUS hook library allows Kea to interact with two types of RADIUS +The RADIUS hooks library allows Kea to interact with two types of RADIUS servers: access and accounting. Although the most common DHCP and RADIUS integration is done on the DHCP relay-agent level (DHCP clients send DHCP packets to DHCP relays; those relays contact the RADIUS server and @@ -538,8 +538,8 @@ received during the initial Discover/Offer exchanges and use it again later when sending accounting messages. This mechanism is implemented based on user context in host -reservations. (See :ref:`user-context` for details about user -context). The host cache mechanism allows the information retrieved by +reservations. (See :ref:`user-context` for details.) +The host cache mechanism allows the information retrieved by RADIUS to be stored and later used for sending accounting and access queries to the RADIUS server. In other words, the host-cache mechanism is mandatory, unless administrators do not want RADIUS communication for messages diff --git a/doc/guide/hooks.rst b/doc/guide/hooks.rst index fee00b4601..52256d3fab 100644 --- a/doc/guide/hooks.rst +++ b/doc/guide/hooks.rst @@ -127,7 +127,7 @@ some hooks may require their own dedicated switches, e.g. the RADIUS hook requires extra switches for FreeRADIUS. Please consult later sections of this chapter for details. -6. Rebuild Kea +6. Rebuild Kea. :: @@ -209,7 +209,9 @@ configuration would be: parameter entry for comments, as is the case with many configuration scopes. -.. note: +.. + +.. note:: In all versions of Kea since 1.1.0, libraries are reloaded even if their lists have not changed, @@ -238,7 +240,7 @@ Notes: - An empty list has the same effect as omitting the ``hooks-libraries`` configuration element altogether. - .. note:: + .. note:: There is one case where this is not true: if Kea is running with a configuration that contains a ``hooks-libraries`` item, and that @@ -1033,7 +1035,7 @@ client-id option) is ignored. The :ref:`lease-cmds` section describes commands used to retrieve, update, and delete leases using various identifiers, such as "hw-address" and -"client-id". The lease_cmds library doesn't natively support querying +"client-id". The lease_cmds library does not natively support querying for leases by flexible identifier. However, when ``replace-client-id`` is set to "true", it makes it possible to query for leases using a value derived from the flexible identifier. In the DHCPv4 case, the query will @@ -1528,7 +1530,7 @@ page is received. Its response will look like this: This command is more complex than ``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 -``reservation-get-all`` (see :ref:`command-reservation-get-all`. +``reservation-get-all`` (see :ref:`command-reservation-get-all`). .. note:: @@ -2085,7 +2087,7 @@ belonging to the subnet. The server may also be configured with static host reservations which are associated with this subnet. The current implementation of the ``subnet4-del`` command removes neither the leases nor the host reservations associated with a subnet. This is the safest approach -because the server doesn't lose track of leases assigned to the clients +because the server does not lose track of leases assigned to the clients from this subnet. However, removal of the subnet may still cause configuration errors and conflicts. For example: after removal of the subnet, the server administrator may update a new subnet with the ID @@ -2141,7 +2143,7 @@ belonging to the subnet. The server may also be configured with static host reservations which are associated with this subnet. The current implementation of the ``subnet6-del`` command removes neither the leases nor the host reservations associated with a subnet. This is the safest approach -because the server doesn't lose track of leases assigned to the clients +because the server does not lose track of leases assigned to the clients from this subnet. However, removal of the subnet may still cause configuration errors and conflicts. For example: after removal of the subnet, the server administrator may add a new subnet with the ID used diff --git a/doc/guide/index.rst b/doc/guide/index.rst index dbff406bd3..8ddb006d9f 100644 --- a/doc/guide/index.rst +++ b/doc/guide/index.rst @@ -75,7 +75,7 @@ project: `Afilias `__, `Google `__, `RIPE NCC `__, `Registro.br `__, `.nz Registry Services `__, and `Technical Center -of Internet `__ . +of Internet `__. .. |image0| image:: kea-logo-100x70.png diff --git a/doc/guide/lease-expiration.rst b/doc/guide/lease-expiration.rst index 09b0e26129..ae3e32c5db 100644 --- a/doc/guide/lease-expiration.rst +++ b/doc/guide/lease-expiration.rst @@ -155,8 +155,8 @@ by the following diagram: | c1 | | c2 | |c3| | c4 | - |<---->|<---------->|<-->|<---------->|<>|<---------->|<-->| - ----------------------------------------------------------------> + |<---->|<---------->|<-->|<---------->|<>|<---------->|<-->|<-- + ------------------------------------------------------------------> | | 5s | | 5s | | 5s | | time This diagram shows four lease-reclamation cycles (c1 through c4) of @@ -322,9 +322,9 @@ should consider using host reservations or leases with very long lifetimes. .. _leases-reclamation-using-command: -Reclaiming Expired Leases with Command -====================================== +Reclaiming Expired Leases via Command +===================================== -The *leases-reclaim* command can be used to trigger lease reclamation at +The ``leases-reclaim`` command can be used to trigger lease reclamation at any time. Please consult the :ref:`command-leases-reclaim` section for details about using this command.