From: Suzanne Goldlust Date: Tue, 12 Jul 2022 11:08:37 +0000 (+0000) Subject: Apply 17 suggestion(s) to 3 file(s) X-Git-Tag: Kea-2.2.0~53 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bc5b42b541ae075b64dde14ce2cba27173c96170;p=thirdparty%2Fkea.git Apply 17 suggestion(s) to 3 file(s) --- diff --git a/doc/sphinx/arm/classify.rst b/doc/sphinx/arm/classify.rst index 40facc3540..04cc95c611 100644 --- a/doc/sphinx/arm/classify.rst +++ b/doc/sphinx/arm/classify.rst @@ -70,7 +70,7 @@ The classification process is conducted in several steps: .. note:: - pkt4_receive, pkt6_receive callouts are called here. + The ``pkt4_receive`` and ``pkt6_receive`` callouts are called here. 6. When the ``early-global-reservations-lookup`` global parameter is configured to true global reservations are looked for and the 8, 9 @@ -88,7 +88,7 @@ The classification process is conducted in several steps: .. note:: - subnet4_select, subnet6_select callouts are called here. + The ``subnet4_select`` and ``subnet6_select`` callouts are called here. 8. The server looks for host reservations. If an identifier from the incoming packet matches a host reservation in the subnet or shared @@ -119,7 +119,7 @@ The classification process is conducted in several steps: .. note:: - lease4_select, lease4_renew, lease6_select, lease6_renew, lease6_rebind + The ``lease4_select``, ``lease4_renew``, ``lease6_select``, ``lease6_renew``, and ``lease6_rebind`` callouts are called here. 12. Classes marked as "required" are evaluated in the order in which diff --git a/doc/sphinx/arm/hooks-limits.rst b/doc/sphinx/arm/hooks-limits.rst index 79562d4e7d..2c7cee987f 100644 --- a/doc/sphinx/arm/hooks-limits.rst +++ b/doc/sphinx/arm/hooks-limits.rst @@ -5,8 +5,8 @@ This hook library enables two types of limits: -1. Lease limiting: allow a maximum of `n` leases assigned at any one time. -2. Rate limiting: allow a maximum of `n` packets per `time_unit` to receive a response. +1. Lease limiting: allow a maximum of ``n`` leases assigned at any one time. +2. Rate limiting: allow a maximum of ``n`` packets per ``time_unit`` to receive a response. The Limits hook library is only available to ISC customers with a paid support contract. @@ -15,8 +15,8 @@ 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 can be easily extrapolated to its -``kea-dhcp4`` counterpart. Wildcards ``""`` and ``""`` need be replaced +The following examples are for ``kea-dhcp6``, but they apply equally to +``kea-dhcp4``. The wildcards ``""`` and ``""`` need to be replaced with the respective keys and values for each limit type described in the sections following this one. @@ -126,11 +126,10 @@ A trick to enforce a global limit (same limit for all clients) is to define the .. note:: - The Limits hook library uses the name to identify a client class and the ID to identify a subnet. + The Limits hook library uses the class name to identify a client class and the subnet ID to identify a subnet. Changing a test expression in a client class or the network range of a subnet while leaving the - name, or the ID respectively, unchanged will not reset the limit for the respective client class - or subnet. What counted towards the limit prior to the change will continue to take effect. - To start over, consider changing the client class name or the subnet ID. + name or ID unchanged does not reset the lease count for the respective client class + or subnet. To reset the lease count, change the client class name or the subnet ID. .. _hooks-limits-lease-limiting: @@ -140,7 +139,7 @@ Lease Limiting It is possible to limit the number of leases that a group of clients can get from a Kea DHCP server or from a set of collaborating Kea DHCP servers. -The value of a lease limit can be specified as an unsigned integer on 32 bits i.e. between ``0`` and +The value of a lease limit can be specified as an unsigned integer in 32 bits, i.e. between ``0`` and ``4,294,967,295``. Each lease type can be limited individually. IPv4 leases and IPv6 IA_NA leases are limited through the ``"address-limit"`` configuration entry. IPv6 IA_PD leases are limited through the ``"prefix-limit"`` configuration entry. Here are some examples: @@ -148,8 +147,8 @@ through the ``"prefix-limit"`` configuration entry. Here are some examples: * ``"address-limit": 4`` * ``"prefix-limit": 2`` -Inasmuch as lease limiting is regarded, client classes and the associated lease counts that are -checked against the configued limits, are updated for each lease in the following hook callouts: +For lease limiting, client classes and the associated lease counts - which are +checked against the configured limits - are updated for each lease in the following hook callouts: * ``lease4_select`` * ``lease4_renew`` @@ -157,22 +156,16 @@ checked against the configued limits, are updated for each lease in the followin * ``lease6_renew`` * ``lease6_rebind`` -As a result, packets that are marked with ``"only-if-required": true`` cannot be lease limited. -See :ref:`the classification steps ` to have the full picture on what +As a result, classes for which ``"only-if-required"`` is "true" cannot be lease-limited. +Please refer to :ref:`the classification steps ` for more information on which client classes can be used to limit the number of leases. .. warning:: - Due to technical conveniences, lease limits are not strictly enforced. Occasionally, a Kea DHCP - server may allocate more leases than the limit would strictly allow. This only has a chance of - happening during high traffic surges coming from clients belonging to the same class or to the - same subnet (based on what is limited). Even in those scenarios and other circumstances that - would favor the race condition that causes surpassing the limit e.g. a global rate of inbound - packets that matches the server's response rate performance, and a thread count close to the - the number of cores, empirically, it seems that the unfortunate event is rare and only results - in one lease past the limit. One hard guarantee is that the race can only happen again after the - lease count has retreated below the limit. For an airtight solution, follow the development of - `GitLab issue #2449 atomic lease limits `__. + Under load, a Kea DHCP server may allocate more leases than the limit strictly allows. This only has a chance of + happening during high traffic surges, coming from clients belonging to the same class or the + same subnet, depending on what is limited. Users may be interested in following the development of + `atomic lease limits `__ in ISC's GitLab instance. .. _hooks-limits-rate-limiting: @@ -182,12 +175,13 @@ Rate Limiting It is possible to limit the frequency or rate at which inbound packets receive a response. The value of a rate limit can be specified in the format ``"

packets per "``. ``

`` -is any number that can be represented by an unsigned integer on 32 bits i.e. between ``0`` and +is any number that can be represented by an unsigned integer in 32 bits, i.e. between ``0`` and ``4,294,967,295``. ```` can be any of ``second``, ``minute``, ``hour``, ``day``, -``week``, ``month``, ``year``. ``month`` is considered to be 30 days for simplicity. Similarly, -``year`` is 365 days for all intents and purposes of limiting. This syntax covers a high range of -rates from one lease per year to four billion leases per second. This vaue is assigned to the -``"rate-limit"`` configuration entry. Here are some examples: +``week``, ``month``, or ``year``. A ``month`` is considered to be 30 days for +simplicity; similarly, a ``year`` is 365 days for limiting purposes. This syntax +covers a wide range of rates, from one lease per year to four billion leases per +second. This value is assigned to the ``"rate-limit"`` configuration entry. +Here are some examples: * ``"rate-limit": 1 packet per second`` * ``"rate-limit": 4 packets per minute`` @@ -195,30 +189,30 @@ rates from one lease per year to four billion leases per second. This vaue is as The configured value of ``0`` packets is a convenient way of disabling packet processing for certain clients entirely. As such, it means its literal value and is not a special value for disabling -limiting altogether as it might be imagined. Disabling limiting altogether is achieved by removing -the ``"rate-limit"`` leaf configuration entry, the ``"limits"`` map around it or the user context -around it or the hook library configuration. The same can be said about the value of ``0`` in lease -limiting. However, that use case is best achieved with rate limiting as it puts less computational -strain on Kea since the action of dropping the request or sending a NAK is decided earlier on. - -Inasmuch as rate limiting is regarded, client classes are evalated at the ``pkt4_receive`` and the -``pkt6_receive`` callout respectively so that rate limits are checked as early as possible in the -packet processing cycle. Thus, only those classes which are assigned to the packet solely via an +limiting altogether, as might be imagined. Disabling limiting entirely is achieved by removing +the ``"rate-limit"`` leaf configuration entry, the ``"limits"`` map or user context +around it, or the hook library configuration. The same applies to the value of ``0`` in lease +limiting. However, that use case is best achieved with rate limiting; it puts less computational +strain on Kea, since the action of dropping the request or sending a NAK is decided earlier. + +In terms of rate limiting, client classes are evalated at the ``pkt4_receive`` and the +``pkt6_receive`` callout, respectively, so that rate limits are checked as early as possible in the +packet-processing cycle. Thus, only those classes which are assigned to the packet solely via an independent test expression can be used. Classes that depend on host reservations or the special ``BOOTP`` or ``KNOWN`` classes, and classes that are marked with ``"only-if-required": true``, -cannot be rate limited. See :ref:`the classification steps ` to -have the full picture on what client classes can be used to limit packet rate. +cannot be rate limited. See :ref:`the classification steps ` for +more details on which client classes can be used to limit the packet rate. Rate limits based on subnet are enforced only on the initially selected subnet for a given packet. If the selected subnet is subsequently changed, as may be the case for subnets in a -shared-network or when reselection is enabled in libraries such as the RADIUS hook, rate -limits on the newly selected subnet will be ignored. In other words, packets are gated only by +shared network or when reselection is enabled in libraries such as the RADIUS hook, rate +limits on the newly selected subnet are ignored. In other words, packets are gated only by the rate limit on the original subnet. .. note:: - It can be tempting to think that assigning a rate limit of ``n`` packets per time unit results - in ``n`` DORA or ``n`` SARR exchanges. By default, all inbound packets are counted. That means - that a full message exchange accounts for 2 packets. To achieve the desired effect of counting an - exchange only once, you may use client class rate limiting with a test expression that binds + It may seem logical to think that assigning a rate limit of ``n`` packets per time unit results + in ``n`` DORA or ``n`` SARR exchanges. However, by default, all inbound packets are counted - meaning + that a full message exchange accounts for two packets. To achieve the effect of counting an + exchange only once, use client-class rate-limiting with a test expression that binds ``pkt4.msgtype`` to DHCPDISCOVER messages or ``pkt6.msgtype`` to SOLICIT messages. diff --git a/doc/sphinx/arm/hooks.rst b/doc/sphinx/arm/hooks.rst index eb8468ae09..6d4b5a253e 100644 --- a/doc/sphinx/arm/hooks.rst +++ b/doc/sphinx/arm/hooks.rst @@ -306,7 +306,7 @@ The DDNS-Tuning Hook uses user-context to configure per subnet behavior. Example }] -The Limits hook uses user-context in classes and subnets to set parameters. Example: +The Limits hook uses user-context in classes and subnets to set parameters. For example: .. code-block:: json