From: Suzanne Goldlust Date: Mon, 1 Jul 2019 18:20:05 +0000 (-0400) Subject: Add `.. note:` and `..warning:` directives for Sphinx conversion X-Git-Tag: Kea-1.6.1~10^2~91 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=4c0bc7f80e14116f62bcc28ea78a0a7d2e485298;p=thirdparty%2Fkea.git Add `.. note:` and `..warning:` directives for Sphinx conversion --- diff --git a/doc/guide/agent.rst b/doc/guide/agent.rst index 85c5707449..d17e3dc394 100644 --- a/doc/guide/agent.rst +++ b/doc/guide/agent.rst @@ -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 diff --git a/doc/guide/classify.rst b/doc/guide/classify.rst index ffa3fc1612..ddcd734230 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 @@ -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 diff --git a/doc/guide/config-backend.rst b/doc/guide/config-backend.rst index 9c3eab9580..53fe09b285 100644 --- a/doc/guide/config-backend.rst +++ b/doc/guide/config-backend.rst @@ -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 `. - **Note** +.. note:: Any existing MySQL schema must be upgraded to the latest schema required by the particular Kea version using the ``kea-admin`` tool, diff --git a/doc/guide/config.rst b/doc/guide/config.rst index 375d9d2a50..c02c98987f 100644 --- a/doc/guide/config.rst +++ b/doc/guide/config.rst @@ -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 diff --git a/doc/guide/ctrl-channel.rst b/doc/guide/ctrl-channel.rst index 722318194d..af353b29e7 100644 --- a/doc/guide/ctrl-channel.rst +++ b/doc/guide/ctrl-channel.rst @@ -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 diff --git a/doc/guide/ddns.rst b/doc/guide/ddns.rst index a3a36064ff..b1eade2229 100644 --- a/doc/guide/ddns.rst +++ b/doc/guide/ddns.rst @@ -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. diff --git a/doc/guide/dhcp4-srv.rst b/doc/guide/dhcp4-srv.rst index e5cd4ea865..e05acaa76f 100644 --- a/doc/guide/dhcp4-srv.rst +++ b/doc/guide/dhcp4-srv.rst @@ -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 diff --git a/doc/guide/dhcp6-srv.rst b/doc/guide/dhcp6-srv.rst index da9c82ee31..6b5fd0e860 100644 --- a/doc/guide/dhcp6-srv.rst +++ b/doc/guide/dhcp6-srv.rst @@ -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`. diff --git a/doc/guide/hammer.rst b/doc/guide/hammer.rst index f4b2c10c2d..3a9e2479f4 100644 --- a/doc/guide/hammer.rst +++ b/doc/guide/hammer.rst @@ -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. diff --git a/doc/guide/hooks-cb-cmds.rst b/doc/guide/hooks-cb-cmds.rst index 19a7b8e27c..4b7f6a9a7d 100644 --- a/doc/guide/hooks-cb-cmds.rst +++ b/doc/guide/hooks-cb-cmds.rst @@ -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 diff --git a/doc/guide/hooks-class-cmds.rst b/doc/guide/hooks-class-cmds.rst index 03a7faf7e2..d28d1a3e5e 100644 --- a/doc/guide/hooks-class-cmds.rst +++ b/doc/guide/hooks-class-cmds.rst @@ -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:: This library may only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6`` process. diff --git a/doc/guide/hooks-ha.rst b/doc/guide/hooks-ha.rst index 8b01901bf1..f1a9836593 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. @@ -1111,7 +1111,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 @@ -1120,7 +1120,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 f6bb4337a2..230acf67ae 100644 --- a/doc/guide/hooks-host-cache.rst +++ b/doc/guide/hooks-host-cache.rst @@ -11,7 +11,7 @@ cache information from the database locally. This includes negative caching, i.e. the ability to remember that there is no client information in the database. - **Note** +.. note:: This library may only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6`` process. diff --git a/doc/guide/hooks-lease-cmds.rst b/doc/guide/hooks-lease-cmds.rst index 07a24bfb4d..d329755e08 100644 --- a/doc/guide/hooks-lease-cmds.rst +++ b/doc/guide/hooks-lease-cmds.rst @@ -17,7 +17,7 @@ of the subnet to which it is supposed to belong. The library also provides a non-programmatic way to manage user contexts associated with leases. - **Note** +.. note:: This library may only be loaded by the ``kea-dhcp4`` or the ``kea-dhcp6`` process. @@ -433,7 +433,7 @@ following format: .. - **Warning** +.. warning:: The ``lease4-get-all`` and ``lease6-get-all`` commands may result in very large responses. This may have a negative impact on the DHCP diff --git a/doc/guide/hooks-radius.rst b/doc/guide/hooks-radius.rst index a26fd2635a..59b6e65606 100644 --- a/doc/guide/hooks-radius.rst +++ b/doc/guide/hooks-radius.rst @@ -15,7 +15,7 @@ attributes. As such, the alternative looks more appealing: to extend the DHCP server to talk to RADIUS directly. That is the goal this library intends to fulfill. - **Note** +.. note:: This library may only be loaded by the ``kea-dhcp4`` or the ``kea-dhcp6`` process. diff --git a/doc/guide/hooks-stat-cmds.rst b/doc/guide/hooks-stat-cmds.rst index b8d76db401..1a36628c17 100644 --- a/doc/guide/hooks-stat-cmds.rst +++ b/doc/guide/hooks-stat-cmds.rst @@ -17,7 +17,7 @@ retrieving lease statistics for all subnets, a single subnet, or a range of subnets. Finally, this library was constructed to provide commands for retrieving these statistics. - **Note** +.. note:: This library may only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6`` process. diff --git a/doc/guide/hooks.rst b/doc/guide/hooks.rst index 51b7f18dd5..ed28efd97b 100644 --- a/doc/guide/hooks.rst +++ b/doc/guide/hooks.rst @@ -49,7 +49,7 @@ be built. Installing Hook Packages ======================== - **Note** +.. note:: For more details about installing the Kea Premium Hooks package, please read `this Knowledgebase article `__. @@ -202,14 +202,14 @@ configuration would be: .. - **Note** +.. note:: This syntax is effective as of Kea 1.1.0, to facilitate the specification of library-specific parameters. Libraries should allow a 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 +238,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 @@ -259,7 +259,7 @@ advantage of this feature to provide functions that may only be useful to a subset of Kea users. To this end, ISC has created some hooks libraries, discussed in the following sections. - **Note** +.. note:: Some of these libraries are available with the base code, while others will be shared with organizations supporting development of @@ -277,7 +277,7 @@ loaded by the ``kea-dhcp4`` or ``kea-dhcp6`` processes. If a library from ISC does not work as expected, please make sure that it has been loaded by the correct process per the table below. - **Warning** +.. warning:: While the Kea Control Agent includes the "hooks" functionality, (i.e. hooks libraries can be loaded by this process), none of ISC's current @@ -373,7 +373,7 @@ only access a registration portal. Once they fill in necessary data, their details are added to the known clients file and they get a proper address after their device is restarted. - **Note** +.. note:: This library was developed several years before the host reservation mechanism became available. Host reservation is much @@ -429,7 +429,7 @@ renewals into a set of log files. Currently this 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. @@ -462,7 +462,7 @@ described below; see :ref:`forensic-log-configuration`. The next part of the nam date the log file was started, with four digits for year, two digits for month, and two digits for day. The file is rotated on a daily basis. - **Note** +.. note:: When running Kea servers for both DHCPv4 and DHCPv6, the log names must be distinct. See the examples in :ref:`forensic-log-configuration`. @@ -845,7 +845,7 @@ scenarios are addressed by the Flexible Identifiers hook application. Currently this 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. @@ -920,13 +920,15 @@ can be achieved by using the following configuration: ] } -Note that care should be taken when adjusting the expression. If the expression -changes, then all the ``flex-id`` values may change, possibly rendering -all reservations based on ``flex-id`` unusable until they are manually updated. -It is strongly recommended that administrators start with the expression and a -handful of reservations, and then adjust the expression as needed. Once -the expression is confirmed to do what is desired of it, host reservations -can be deployed on a broader scale. +.. note:: + + Care should be taken when adjusting the expression. If the expression + changes, then all the ``flex-id`` values may change, possibly rendering + all reservations based on ``flex-id`` unusable until they are manually updated. + It is strongly recommended that administrators start with the expression and a + handful of reservations, and then adjust the expression as needed. Once + the expression is confirmed to do what is desired of it, host reservations + can be deployed on a broader scale. ``flex-id`` values in host reservations can be specified in two ways. First, they can be expressed as a hex string, e.g. bar string can be represented @@ -1072,7 +1074,7 @@ reservations will be added in the future. Currently this 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. @@ -1409,7 +1411,7 @@ reservations are returned. The end is reached once the returned list is empty, the count is 0, no next map is present, and result status 3 (empty) is returned. - **Note** +.. note:: The from and source-index parameters are reflecting the internal state of the search. There is no need to understand what they represent; it is @@ -1478,7 +1480,7 @@ Some hosts are returned with information to get the next page: "text": "72 IPv4 host(s) found." } -Note that the from and source-index fields were specified in the response in +Note that the "from" and "source-index" fields were specified in the response in the next map. Those two must be copied to the next command, so Kea continues from the place where the last command finished. To get the next page the following command can be sent: @@ -1515,7 +1517,7 @@ 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`. - **Note** +.. note:: Currently ``reservation-get-page`` is not supported by the Cassandra host backend. @@ -1618,7 +1620,7 @@ shared networks) is also provided. Currently this 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. @@ -1957,7 +1959,7 @@ values, so the auto-generation is never used. The two approaches can be mixed only if the administrator understands how internal automatic subnet-id generation works in Kea. - **Note** +.. note:: Subnet IDs must be greater than zero and less than 4294967295. @@ -2279,7 +2281,7 @@ only one subnet) is discouraged in production environments. For details regarding syntax, see :ref:`shared-network4` and :ref:`shared-network6`. - **Note** +.. note:: As opposed to parameter inheritance during the processing of a full new configuration, this command does not fully handle parameter inheritance. @@ -2455,7 +2457,7 @@ return a response similar to the following: The ``network6-subnet-add`` command uses exactly the same syntax for both the command and the response. - **Note** +.. note:: As opposed to parameter inheritance during the processing of a full new configuration or when adding a new shared network with new subnets, diff --git a/doc/guide/install.rst b/doc/guide/install.rst index d56840b19b..b7cabd24f1 100644 --- a/doc/guide/install.rst +++ b/doc/guide/install.rst @@ -1,4 +1,4 @@ -.. _installation: +.. note::.. _installation: ************ Installation @@ -49,7 +49,7 @@ In addition to the run-time requirements (listed in :ref:`required-software`), building Kea from source code requires various development include headers and program development tools. - **Note** +.. note:: Some operating systems have split their distribution packages into a run-time and a development package. You will need to install the @@ -139,7 +139,7 @@ Downloading this "bleeding edge" code is recommended only for developers or advanced users. Using development code in a production environment is not recommended. - **Note** +.. note:: When building from source code retrieved via git, additional software will be required: automake (v1.11 or later), libtoolize, and autoconf @@ -228,7 +228,7 @@ options. Some commonly used options are: .. - **Note** +.. note:: For instructions concerning the installation and configuration of database backends for Kea, see :ref:`dhcp-install-configure`. @@ -334,7 +334,7 @@ Do not use any form of parallel or job server options (such as GNU make's ``-j`` option) when performing this step; doing so may cause errors. - **Note** +.. note:: The install step may require superuser privileges. @@ -348,7 +348,7 @@ relevant linker cache configuration file for your OS): .. - **Note** +.. note:: If you do not run ``ldconfig`` where it is required, you may see errors like the following: @@ -374,7 +374,7 @@ optional external database backend must be explicitly included when Kea is built. This section covers the building of Kea with one of the optional backends and the creation of the lease database. - **Note** +.. note:: When unit tests are built with Kea (i.e. the --with-gtest configuration option is specified), the databases must be manually pre-configured diff --git a/doc/guide/keactrl.rst b/doc/guide/keactrl.rst index 2794950e94..c9f1e1f959 100644 --- a/doc/guide/keactrl.rst +++ b/doc/guide/keactrl.rst @@ -98,7 +98,7 @@ The contents of ``keactrl.conf`` are: .. - **Note** + .. note:: In the example above, strings of the form @something@ are replaced by the appropriate values when Kea is installed. @@ -126,7 +126,7 @@ effect as long as the ``kea_verbose`` is set to "yes." Setting it to Kea configuration file. If no logging configuration is specified, the default settings will be used. - **Note** + .. note:: The verbosity for the server is set when it is started. Once started, the verbosity can be only changed by stopping the server and starting @@ -243,7 +243,7 @@ take effect. This limitation will be removed in a future release. .. - **Note** + .. note:: NETCONF is an optional feature that is disabled by default and can be enabled during compilation. If Kea was compiled without NETCONF @@ -252,7 +252,7 @@ take effect. This limitation will be removed in a future release. the keactrl.conf file, but NETCONF status will not be shown and other commands will ignore it. - **Note** + .. note:: Currently ``keactrl`` does not report configuration failures when the server is started or reconfigured. To check if the server's diff --git a/doc/guide/logging.rst b/doc/guide/logging.rst index e9606c02e7..d2ea69cde5 100644 --- a/doc/guide/logging.rst +++ b/doc/guide/logging.rst @@ -500,7 +500,7 @@ severity to INFO will log INFO, WARN, ERROR, and FATAL messages). The severity may also be set to NONE, in which case all messages from that logger are inhibited. - **Note** + .. note:: The ``keactrl`` tool, described in :ref:`keactrl`, can be configured to start the servers in verbose mode. If this is the case, the @@ -555,7 +555,7 @@ The default value is 10240000 (10MB). The smallest value that can be specified without disabling rotation is 204800. Any value less than this, including 0, disables rotation. - **Note** + .. note:: Due to a limitation of the underlying logging library (log4cplus), rolling over the log files (from ".1" to ".2", etc) may show odd diff --git a/doc/guide/stats.rst b/doc/guide/stats.rst index 614f3b39e5..139504774f 100644 --- a/doc/guide/stats.rst +++ b/doc/guide/stats.rst @@ -93,7 +93,7 @@ returned. ``Remove`` removes a statistic completely, so the statistic will no longer be reported. Please note that the server code may add it back if there is a reason to record it. - **Note** +.. note:: The following sections describe commands that can be sent to the server; the examples are not fragments of a configuration file. For