Commit 2c8cfbfc authored by Suzanne Goldlust's avatar Suzanne Goldlust Committed by Michal Nowikowski
Browse files

Additional edits, Sphinx formatting

parent 8c15d974
......@@ -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 <https://gitlab.isc.org/isc-projects/kea>`__ if you need
`Kea GitLab site <https://gitlab.isc.org/isc-projects/kea>`__ 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
......
......@@ -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 <https://jenkins.isc.org/job/Kea_doc/doxygen/index.html>`__.)
Packet queue behavior is configured in both kea-dhcp4 and kea-dhcp6
servers through an optional, top-level, configuration element,
......
......@@ -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,
......
......@@ -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 <https://tools.ietf.org/html/rfc8415>`__: 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:
......
......@@ -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:
......
......@@ -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
......
......@@ -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:
......
......@@ -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
......
......@@ -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
......
......@@ -75,7 +75,7 @@ project: `Afilias <https://www.afilias.info/>`__,
`Google <https://www.google.com/>`__, `RIPE
NCC <https://www.ripe.net/>`__, `Registro.br <https://registro.br/>`__,
`.nz Registry Services <https://nzrs.net.nz/>`__, and `Technical Center
of Internet <https://www.tcinet.ru/>`__ .
of Internet <https://www.tcinet.ru/>`__.
.. |image0| image:: kea-logo-100x70.png
......
......@@ -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.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment