Commit 4c0bc7f8 authored by Suzanne Goldlust's avatar Suzanne Goldlust Committed by Michal Nowikowski
Browse files

Add `.. note:` and `..warning:` directives for Sphinx conversion

parent 87220ab1
......@@ -111,7 +111,7 @@ for the DHCPv4 server and the CA (for this server) must match. Consult
:ref:`d2-ctrl-channel` to learn how the socket configuration is
specified for the DHCPv4, DHCPv6, and D2 services.
**Warning**
.. warning::
"dhcp4-server", "dhcp6-server", and "d2-server" were renamed to
"dhcp4", "dhcp6", and "d2" respectively in Kea 1.2. If you are
......@@ -240,7 +240,7 @@ server enables authentication of the clients using certificates.
..
**Note**
.. note::
Note that the configuration snippet provided above is for testing
purposes only. It should be modified according to the security
......
......@@ -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
......@@ -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
......@@ -899,7 +899,7 @@ The logging might then resemble this:
..
**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
......
......@@ -90,7 +90,7 @@ CB in the current Kea 1.6.0 release:
..
**Note**
.. note::
We strongly recommend against duplication of the configuration information
in the file and the database. For example, when specifying subnets
......@@ -102,7 +102,7 @@ CB in the current Kea 1.6.0 release:
so it is possible that parts of the configuration specified in the
file may be overridden if contradicted by information in the database.
**Note**
.. note::
It is recommended that the ``subnet_cmds`` hooks library not be used to
manage the subnets when the configuration backend is used as a source
......@@ -122,7 +122,7 @@ configuration switch is used during the Kea build. The MySQL C client
libraries must be installed, as explained in
:ref:`DHCP Database Installation and Configuration <dhcp-install-configure>`.
**Note**
.. note::
Any existing MySQL schema must be upgraded to the latest schema
required by the particular Kea version using the ``kea-admin`` tool,
......
......@@ -85,7 +85,7 @@ A very simple configuration for DHCPv4 could look like this:
More examples are available in the installed ``share/doc/kea/examples``
directory.
**Note**
.. note::
The "Logging" element is removed in Kea 1.6.0 and its contents (the
"loggers" object) moved inside the configuration objects (maps) for the
......
......@@ -165,7 +165,7 @@ in general uses plain English to describe the outcome of the command.
which are specific to the command issued. The map may be present, but
that depends on the specific command.
**Note**
.. note::
When sending commands via the Control Agent, it is possible to specify
multiple services at which the command is targeted. CA forwards this
......
......@@ -238,7 +238,7 @@ illustrates how to change D2's global parameters so it will listen at
..
**Warning**
.. warning::
It is possible for a malicious attacker to send bogus
NameChangeRequests to the DHCP-DDNS server. Addresses other than the
......@@ -246,7 +246,7 @@ illustrates how to change D2's global parameters so it will listen at
used for testing purposes; note that local users may still
communicate with the DHCP-DDNS server.
**Note**
.. note::
If the ip-address and port are changed, the corresponding values in
the DHCP servers' "dhcp-ddns" configuration section must be changed.
......@@ -516,7 +516,7 @@ running at "172.88.99.10", set the Forward DNS Server as follows:
..
**Note**
.. note::
Since "hostname" is not yet supported, the parameter "ip-address"
must be set to the address of the DNS server.
......@@ -653,7 +653,7 @@ service is running at "172.88.99.10", then set it as follows:
..
**Note**
.. note::
Since "hostname" is not yet supported, the parameter "ip-address"
must be set to the address of the DNS server.
......@@ -663,7 +663,7 @@ service is running at "172.88.99.10", then set it as follows:
User Contexts in DDNS
---------------------
**Note**
.. note::
User contexts were designed for hook libraries, which are not yet
supported for DHCP-DDNS server configuration.
......
......@@ -144,7 +144,7 @@ curly bracket (or brace). Each configuration must contain an object
specifying the configuration of the Kea module using it. In the example
above this object is called ``Dhcp4``.
**Note**
.. note::
In the current Kea release it is possible to specify configurations
of multiple modules within a single configuration file, but this is
......@@ -183,7 +183,7 @@ quotes around them.) ``renew-timer`` and ``rebind-timer`` are values
(also in seconds) that define T1 and T2 timers that govern when the
client will begin the renewal and rebind procedures.
**Note**
.. note::
Both ``renew-timer`` and ``rebind-timer``
are optional. The server will only send ``rebind-timer`` to the client,
......@@ -376,7 +376,7 @@ in this Kea Administrator's Reference Manual: :ref:`kea-lfc`.
Lease Database Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Note**
.. note::
Lease database access information must be configured for the DHCPv4
server, even if it has already been configured for the DHCPv6 server.
......@@ -468,7 +468,7 @@ The default value for MySQL and PostgreSQL is 0, which disables automatic
recovery and causes the server to exit immediately upon detecting the
loss of connectivity. The default value for Cassandra is 2000 ms.
**Note**
.. note::
Automatic reconnection to database backends is configured
individually per backend. This allows users to tailor the recovery
......@@ -481,7 +481,7 @@ loss of connectivity. The default value for Cassandra is 2000 ms.
..
**Note**
.. note::
Note that the host parameter is used by the MySQL and PostgreSQL backends.
Cassandra has a concept of contact points that can be used to
......@@ -680,7 +680,7 @@ The default value for MySQL and PostgreSQL is 0, which disables automatic
recovery and causes the server to exit immediately upon detecting the
loss of connectivity. The default value for Cassandra is 2000 ms.
**Note**
.. note::
Automatic reconnection to database backends is configured
individually per backend. This allows users to tailor the recovery
......@@ -747,7 +747,7 @@ Setting this parameter to ``false`` configures the database backend to
operate in "read-write" mode, which is also the default configuration if
the parameter is not specified.
**Note**
.. note::
The ``readonly`` parameter is currently only supported for MySQL and
PostgreSQL databases.
......@@ -890,7 +890,7 @@ should not be used when the directly connected clients are operating on
that link. To use a single address on such interface, the
"interface-name/address" notation should be used.
**Note**
.. note::
Specifying the value ``raw`` as the socket type doesn't guarantee
that the raw sockets will be used! The use of raw sockets to handle
......@@ -1026,7 +1026,7 @@ subnet 3 are now associated with subnet 4, something that may have
unexpected consequences. The only remedy for this issue at present is to
manually specify a unique identifier for each subnet.
**Note**
.. note::
Subnet IDs must be greater than zero and less than 4294967295.
......@@ -1184,7 +1184,7 @@ Calculating 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.
......@@ -1933,7 +1933,7 @@ last field is an array, i.e. it can contain more than one value, as in:
The new option content is one IPv4 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 also accept
......@@ -1941,7 +1941,7 @@ bit unsigned integers.
..
**Note**
.. note::
Numbers can be specified in decimal or hexadecimal format. The
hexadecimal format can be either plain (e.g. abcd) or prefixed with
......@@ -2067,7 +2067,7 @@ The definition used to decode a VSI option is:
..
**Note**
.. note::
This last-resort definition for the Vendor-Specific Information
option (code 43) is not compatible with a raw binary value. When
......@@ -2076,7 +2076,7 @@ The definition used to decode a VSI option is:
matching these cases and an option definition for the VSI option with
a binary type and no encapsulation.
**Note**
.. note::
Option definitions in client classes are allowed only for this
limited option set (codes 43 and from 224 to 254), and only for
......@@ -2537,7 +2537,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.
......@@ -2581,7 +2581,7 @@ client documentation for specific values.
If there are multiple classes defined and an incoming packet is matched
to multiple classes, the class that is evaluated first is used.
**Note**
.. note::
The classes are ordered as specified in the configuration.
......@@ -2595,7 +2595,7 @@ example, modern cable modems will send this option with value
"docsis3.0" and as a result the packet will belong to class
"VENDOR_CLASS_docsis3.0".
**Note**
.. note::
Certain special actions for clients in VENDOR_CLASS_docsis3.0 can be
achieved by defining VENDOR_CLASS_docsis3.0 and setting its
......@@ -3011,7 +3011,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``. Boolean values have been deprecated
......@@ -3115,7 +3115,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
......@@ -3399,7 +3399,7 @@ cooperating DHCPv4 and DHCPv6 servers. This section is about the
configuration of the DHCPv4 side (the DHCPv6 side is described in
:ref:`dhcp6-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
......@@ -3651,7 +3651,7 @@ 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
......@@ -3717,7 +3717,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
......@@ -3948,7 +3948,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
......@@ -3970,7 +3970,7 @@ The `Kea wiki
provides some examples of how to conduct common host reservation
operations.
**Note**
.. note::
In Kea, the maximum length of an option specified per-host is
arbitrarily set to 4096 bytes.
......@@ -4234,7 +4234,7 @@ exhausted; this sometimes occurs when the client provides a hint that belongs to
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
......@@ -4694,7 +4694,7 @@ It is also possible to specify a relay IPv4 address for a given subnet.
It can be used to match incoming packets into a subnet in uncommon
configurations, e.g. shared networks. See :ref:`dhcp4-relay-override` for details.
**Note**
.. note::
The subnet selection mechanism described in this section is based on
the assumption that client classification is not used. The
......@@ -4749,7 +4749,7 @@ selects that subnet for a relay with address 10.0.0.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.
......@@ -4872,7 +4872,7 @@ back to the available pool.
Statistics in the DHCPv4 Server
===============================
**Note**
.. note::
This section describes DHCPv4-specific statistics. For a general
overview and usage of statistics, see :ref:`stats`.
......@@ -5643,7 +5643,7 @@ during the startup or reconfiguration, and will fetch the configuration
available for this server from the database. This configuration is
merged into the configuration read from the configuration file.
**Note**
.. note::
Whenever there is a conflict between the parameters specified in the
configuration file and the database, the parameters from the database
......
......@@ -145,7 +145,7 @@ curly bracket (or brace). Each configuration must contain an object
specifying the configuration of the Kea module using it. In the example
above this object is called ``Dhcp6``.
**Note**
.. note::
In the current Kea release it is possible to specify configurations
of multiple modules within a single configuration file, but this is
......@@ -362,7 +362,7 @@ in this Kea Administrator's Reference Manual: :ref:`kea-lfc`.
Lease Database Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Note**
.. note::
Lease database access information must be configured for the DHCPv6
server, even if it has already been configured for the DHCPv4 server.
......@@ -464,7 +464,7 @@ The default value for MySQL and PostgreSQL is 0, which disables automatic
recovery and causes the server to exit immediately upon detecting the
loss of connectivity. The default value for Cassandra is 2000 ms.
**Note**
.. note::
Automatic reconnection to database backends is configured
individually per backend. This allows users to tailor the recovery
......@@ -477,7 +477,7 @@ loss of connectivity. The default value for Cassandra is 2000 ms.
..
**Note**
.. note::
Note that the host parameter is used by the MySQL and PostgreSQL backends.
Cassandra has a concept of contact points that can be used to
......@@ -626,7 +626,7 @@ The default value for MySQL and PostgreSQL is 0, which disables automatic
recovery and causes the server to exit immediately upon detecting the
loss of connectivity. The default value for Cassandra is 2000 ms.
**Note**
.. note::
Automatic reconnection to database backends is configured
individually per backend. This allows users to tailor the recovery
......@@ -693,7 +693,7 @@ Setting this parameter to ``false`` configures the database backend to
operate in "read-write" mode, which is also the default configuration if
the parameter is not specified.
**Note**
.. note::
The ``readonly`` parameter is currently only supported for MySQL and
PostgreSQL databases.
......@@ -799,7 +799,7 @@ subnet 3 are now associated with subnet 4, something that may have
unexpected consequences. The only remedy for this issue at present is to
manually specify a unique identifier for each subnet.
**Note**
.. note::
Subnet IDs must be greater than zero and less than 4294967295.
......@@ -1114,7 +1114,7 @@ with the following addresses: 2001:db8:1::cafe and 2001:db8:1::babe.
..
**Note**
.. note::
The value for the setting of the "data" element is split across two
lines in this example for clarity; when entering the command, the
......@@ -1785,7 +1785,7 @@ 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.
**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``.
......@@ -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,7 +3195,7 @@ 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
......@@ -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.
......@@ -3721,7 +3721,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
......@@ -4174,7 +4174,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
......@@ -4518,7 +4518,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.
......@@ -4764,7 +4764,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`.
......
......@@ -13,7 +13,7 @@ git repository. This tool was developed primarily for internal purposes
and ISC cannot guarantee its proper operation. If you decide to use it,
please do so with care.
**Note**
.. note::
Use of this tool is completely optional. Everything it does can be
done manually.
......@@ -88,7 +88,7 @@ To exclude the installation and generation of docs, type:
The basic scope can be extended by: mysql, pgsql, cql, native-pkg,
radius, shell, and forge.
**Note**
.. note::
To build Kea locally, Hammer dependencies like Vagrant are
not needed.
......@@ -123,7 +123,7 @@ operating system.
..
**Note**
.. note::
ccache is currently only supported for LXC in Hammer; support
for VirtualBox may be added later.
......
......@@ -16,7 +16,7 @@ loaded by the server used for the configuration management.
The ``cb_cmds`` library is only available to ISC customers with a paid
support contract.
**Note**
.. note::
This library may only be loaded by the ``kea-dhcp4`` or
``kea-dhcp6`` process.
......@@ -66,7 +66,7 @@ be specified, the parameter should be omitted. In this case, the server
will use the first backend listed in the ``config-control`` map within
the configuration of the server receiving the command.
**Note**
.. note::
As of the Kea 1.6.0 release, it is possible to configure the Kea server
to use only one configuration backend. Strictly speaking, it is
......@@ -456,7 +456,7 @@ which are not specified with the command, will be marked as
values for unspecified parameters or, if the global values are not
specified, the default values will be used.
**Note**
.. note::
As with other "set" commands, this command replaces all the
information about the given shared network in the database, if the
......@@ -882,7 +882,7 @@ subnet having the same parameters, but it becomes global.
The ``shared-network-name`` parameter is mandatory for the
``remote-subnet4-set`` command.
**Note**
.. note::
As with other "set" commands, this command replaces all the
information about the particular subnet in the database, if the
......
......@@ -9,7 +9,7 @@ Kea DHCP servers' configurations) without the need to restart those
servers. Using these commands it is possible to add, update, delete, and
list client classes configured for a given server.
**Note**
.. note::