From 06e9ca33ed50431f472e979fcb65e8948037047c Mon Sep 17 00:00:00 2001 From: Andrei Pavel Date: Tue, 6 Oct 2020 18:24:39 +0300 Subject: [PATCH] [#1299] document host reservations --- ChangeLog | 7 +++ doc/sphinx/arm/dhcp4-srv.rst | 78 ++++++++++++++++++++++++++++-- doc/sphinx/arm/dhcp6-srv.rst | 78 ++++++++++++++++++++++++++++-- src/lib/database/dbaccess_parser.h | 2 +- src/share/api/reservation-get.json | 2 +- 5 files changed, 159 insertions(+), 8 deletions(-) diff --git a/ChangeLog b/ChangeLog index 640276eb58..6051e70b11 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +1818. [doc] andrei + Add to the reservation documentation: + * instructions on how to choose "reservation-mode" + * priority of "reservation-mode" specified at all levels + * priority of file reservations vs database reservations + (Gitlab #1299) + 1817. [func] fdupont Redact control agent logs to hide basic HTTP authentication passwords from the configuration files. Note that when HTTP diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst index b4027bbc79..538f2c6b01 100644 --- a/doc/sphinx/arm/dhcp4-srv.rst +++ b/doc/sphinx/arm/dhcp4-srv.rst @@ -732,6 +732,11 @@ entry, as in: For additional Cassandra-specific parameters, see :ref:`cassandra-database-configuration4`. +If the same host is configured both in-file and in-database, Kea won't warn of +the duplicate like it would if you specified them both in the same data source. +Instead the host configured in-file will have priority over the one configured +in-database. + .. _read-only-database-configuration4: Using Read-Only Databases for Host Reservations with DHCPv4 @@ -3941,7 +3946,7 @@ DHCPv4 message such as siaddr, sname, or file. .. note:: - Kea requires that reserved address must be within the subnet. + Kea requires that the reserved address must be within the subnet. Kea 1.7.10 is the last release that does not enforce this. The following example shows how to reserve addresses for specific hosts @@ -4441,8 +4446,75 @@ allocating or renewing a lease for the client. Allowed values are: defined will be completely ignored. As the checks are skipped, the server may operate faster in this mode. -The parameter can be specified at global, subnet, and shared-network -levels. +The ``reservation-mode`` parameter can be specified at: + +- global level: ``.Dhcp4["reservation-mode"]`` (lowest priority: gets overridden + by all others) + +- subnet level: ``.Dhcp4.subnet4[]["reservation-mode"]`` (low priority) + +- shared-network level: ``.Dhcp4["shared-networks"][]["reservation-mode"]`` + (high priority) + +- shared-network subnet-level: + ``.Dhcp4["shared-networks"][].subnet4[]["reservation-mode"]`` (highest + priority: overrides all others) + +For deciding what ``"reservation-mode"`` to choose, you may refer to the +following decision diagram: + +:: + + + O + | + v + +-----------------------------+------------------------------+ + | Is per-host configuration needed, such as | + | reserving specific addresses, | + | assigning specific options or | + | assigning packets to specific classes on per-device basis? | + +-+-----------------+----------------------------------------+ + | | + no| yes| + | | +--------------------------------------+ + | | | For all given hosts, | + +--> "disabled" +-->+ can the reserved resources | + | be used in all configured subnets? | + +--------+---------------------------+-+ + | | + +----------------------------+ |no |yes + | Is | | | + | at least one reservation +<--+ "global" <--+ + | used to reserve addresses? | + +-+------------------------+-+ + | | + no| yes| +---------------------------+ + | | | Is high leases-per-second | + +--> "out-of-pool" +-->+ performance or efficient | + ^ | resource usage | + | | (CPU ticks, RAM usage, | + | | database roundtrips) | + | | important to your setup? | + | +-+----------------+--------+ + | | | + | yes| no| + | | | + | +-------------+ | + | | | + | | +----------------------+ | + | | | Can it be guaranteed | | + | +-->+ that the reserved | | + | | addresses | | + | | aren't part of the | | + | | pools configured | | + | | in the respective | | + | | subnet? | | + | +-+------------------+-+ | + | | | | + | yes| no| | + | | | V + +----------------+ +--> "all" An example configuration that disables reservation looks as follows: diff --git a/doc/sphinx/arm/dhcp6-srv.rst b/doc/sphinx/arm/dhcp6-srv.rst index 0113dc930e..d2eecd0e38 100644 --- a/doc/sphinx/arm/dhcp6-srv.rst +++ b/doc/sphinx/arm/dhcp6-srv.rst @@ -613,7 +613,7 @@ specified: :: - "Dhcp6": { "host-database": { "max-reconnect-tries" : number-of-tries, ... }, ... } + "Dhcp6": { "hosts-database": { "max-reconnect-tries" : number-of-tries, ... }, ... } If the server is unable to reconnect to the database after making the maximum number of attempts, the server will exit. A value of zero (the @@ -670,6 +670,11 @@ entry, as in: For additional Cassandra-specific parameters, see :ref:`cassandra-database-configuration4`. +If the same host is configured both in-file and in-database, Kea won't warn of +the duplicate like it would if you specified them both in the same data source. +Instead the host configured in-file will have priority over the one configured +in-database. + .. _read-only-database-configuration6: Using Read-Only Databases for Host Reservations with DHCPv6 @@ -3840,8 +3845,75 @@ allocating or renewing a lease for the client. Allowed values are: defined will be completely ignored. As the checks are skipped, the server may operate faster in this mode. -The parameter can be specified at global, subnet, and shared-network -levels. +The ``reservation-mode`` parameter can be specified at: + +- global level: ``.Dhcp6["reservation-mode"]`` (lowest priority: gets overridden + by all others) + +- subnet level: ``.Dhcp6.subnet6[]["reservation-mode"]`` (low priority) + +- shared-network level: ``.Dhcp6["shared-networks"][]["reservation-mode"]`` + (high priority) + +- shared-network subnet-level: + ``.Dhcp6["shared-networks"][].subnet6[]["reservation-mode"]`` (highest + priority: overrides all others) + +For deciding what ``"reservation-mode"`` to choose, you may refer to the +following decision diagram: + +:: + + O + | + v + +-----------------------------+------------------------------+ + | Is per-host configuration needed, such as | + | reserving specific addresses, | + | assigning specific options or | + | assigning packets to specific classes on per-device basis? | + +-+-----------------+----------------------------------------+ + | | + no| yes| + | | +--------------------------------------+ + | | | For all given hosts, | + +--> "disabled" +-->+ can the reserved resources | + | be used in all configured subnets? | + +--------+---------------------------+-+ + | | + +----------------------------+ |no |yes + | Is | | | + | at least one reservation +<--+ "global" <--+ + | used to reserve addresses | + | or prefixes? | + +-+------------------------+-+ + | | + no| yes| +---------------------------+ + | | | Is high leases-per-second | + +--> "out-of-pool" +-->+ performance or efficient | + ^ | resource usage | + | | (CPU ticks, RAM usage, | + | | database roundtrips) | + | | important to your setup? | + | +-+----------------+--------+ + | | | + | yes| no| + | | | + | +-------------+ | + | | | + | | +----------------------+ | + | | | Can it be guaranteed | | + | +-->+ that the reserved | | + | | addresses/prefixes | | + | | aren't part of the | | + | | pools configured | | + | | in the respective | | + | | subnet? | | + | +-+------------------+-+ | + | | | | + | yes| no| | + | | | V + +----------------+ +--> "all" An example configuration that disables reservation looks as follows: diff --git a/src/lib/database/dbaccess_parser.h b/src/lib/database/dbaccess_parser.h index 2e55d20ea6..bf25234597 100644 --- a/src/lib/database/dbaccess_parser.h +++ b/src/lib/database/dbaccess_parser.h @@ -20,7 +20,7 @@ namespace db { /// @brief Parse Database Parameters /// /// This class is the parser for the database configuration. This is a -/// map under the top-level "lease-database", "host-database" and +/// map under the top-level "lease-database", "hosts-database" and /// "config-database" elements, and comprises a map of strings. class DbAccessParser: public isc::data::SimpleParser { public: diff --git a/src/share/api/reservation-get.json b/src/share/api/reservation-get.json index 5ff39f5b09..e221097825 100644 --- a/src/share/api/reservation-get.json +++ b/src/share/api/reservation-get.json @@ -40,7 +40,7 @@ " \"next-server\": ,", " \"option-data-list\": [ ],", " \"prefixes\": [ ],", - " \"reservation-client-classes\": [ ],", + " \"client-classes\": [ ],", " \"server-hostname\": ,", " \"subnet-id\": ,", " \"user-context\": ",