1.. _dhcp4: 2 3***************** 4The DHCPv4 Server 5***************** 6 7.. _dhcp4-start-stop: 8 9Starting and Stopping the DHCPv4 Server 10======================================= 11 12It is recommended that the Kea DHCPv4 server be started and stopped 13using ``keactrl`` (described in :ref:`keactrl`); however, it is also 14possible to run the server directly. It accepts the following 15command-line switches: 16 17- ``-c file`` - specifies the configuration file. This is the only 18 mandatory switch. 19 20- ``-d`` - specifies whether the server logging should be switched to 21 debug/verbose mode. In verbose mode, the logging severity and 22 debuglevel specified in the configuration file are ignored; 23 "debug" severity and the maximum debuglevel (99) are assumed. The 24 flag is convenient for temporarily switching the server into maximum 25 verbosity, e.g. when debugging. 26 27- ``-p server-port`` - specifies the local UDP port on which the server 28 will listen. This is only useful during testing, as a DHCPv4 server 29 listening on ports other than the standard ones is not able to 30 handle regular DHCPv4 queries. 31 32- ``-P client-port`` - specifies the remote UDP port to which the 33 server will send all responses. This is only useful during testing, 34 as a DHCPv4 server sending responses to ports other than the standard 35 ones is not able to handle regular DHCPv4 queries. 36 37- ``-t file`` - specifies a configuration file to be tested. ``kea-dhcp4`` 38 loads it, checks it, and exits. During the test, log messages are 39 printed to standard output and error messages to standard error. The 40 result of the test is reported through the exit code (0 = 41 configuration looks OK, 1 = error encountered). The check is not 42 comprehensive; certain checks are possible only when running the 43 server. 44 45- ``-v`` - displays the Kea version and exits. 46 47- ``-V`` - displays the Kea extended version with additional parameters 48 and exits. The listing includes the versions of the libraries 49 dynamically linked to Kea. 50 51- ``-W`` - displays the Kea configuration report and exits. The report 52 is a copy of the ``config.report`` file produced by ``./configure``; 53 it is embedded in the executable binary. 54 55On startup, the server detects available network interfaces and 56attempts to open UDP sockets on all interfaces mentioned in the 57configuration file. Since the DHCPv4 server opens privileged ports, 58this daemon must be run as root. 59 60During startup, the server attempts to create a PID file of the 61form ``[runstatedir]/kea/[conf name].kea-dhcp4.pid``, where: 62 63- ``runstatedir`` is the value as passed into the build configure 64 script; it defaults to ``/usr/local/var/run``. Note that this value may be 65 overridden at runtime by setting the environment variable 66 ``KEA_PIDFILE_DIR``, although this is intended primarily for testing 67 purposes. 68 69- ``conf name`` is the configuration file name used to start the server, 70 minus all preceding paths and the file extension. For example, given 71 a pathname of ``/usr/local/etc/kea/myconf.txt``, the portion used would 72 be ``myconf``. 73 74If the file already exists and contains the PID of a live process, the 75server issues a DHCP4_ALREADY_RUNNING log message and exits. It is 76possible, though unlikely, that the file is a remnant of a system crash 77and the process to which the PID belongs is unrelated to Kea. In such a 78case, it would be necessary to manually delete the PID file. 79 80The server can be stopped using the ``kill`` command. When running in a 81console, the server can also be shut down by pressing ctrl-c. Kea detects 82the key combination and shuts down gracefully. 83 84.. _dhcp4-configuration: 85 86DHCPv4 Server Configuration 87=========================== 88 89Introduction 90------------ 91 92This section explains how to configure the Kea DHCPv4 server using a 93configuration file. 94 95Before DHCPv4 is started, its configuration file must 96be created. The basic configuration is as follows: 97 98:: 99 100 { 101 # DHCPv4 configuration starts on the next line 102 "Dhcp4": { 103 104 # First we set up global values 105 "valid-lifetime": 4000, 106 "renew-timer": 1000, 107 "rebind-timer": 2000, 108 109 # Next we set up the interfaces to be used by the server. 110 "interfaces-config": { 111 "interfaces": [ "eth0" ] 112 }, 113 114 # And we specify the type of lease database 115 "lease-database": { 116 "type": "memfile", 117 "persist": true, 118 "name": "/var/lib/kea/dhcp4.leases" 119 }, 120 121 # Finally, we list the subnets from which we will be leasing addresses. 122 "subnet4": [ 123 { 124 "subnet": "192.0.2.0/24", 125 "pools": [ 126 { 127 "pool": "192.0.2.1 - 192.0.2.200" 128 } 129 ] 130 } 131 ] 132 # DHCPv4 configuration ends with the next line 133 } 134 135 } 136 137The following paragraphs provide a brief overview of the parameters in 138the above example, along with their format. Subsequent sections of this 139chapter go into much greater detail for these and other parameters. 140 141The lines starting with a hash (#) are comments and are ignored by the 142server; they do not impact its operation in any way. 143 144The configuration starts in the first line with the initial opening 145curly bracket (or brace). Each configuration must contain an object 146specifying the configuration of the Kea module using it. In the example 147above, this object is called ``Dhcp4``. 148 149.. note:: 150 151 In the current Kea release it is possible to specify configurations 152 of multiple modules within a single configuration file, but this is 153 not recommended. Support for this type of configuration was removed in the 1.7.10 release, 154 including the ``Logging`` object; its previous content, the list 155 of loggers, must now be inside the ``Dhcp4`` object. 156 157The Dhcp4 configuration starts with the ``"Dhcp4": {`` line and ends 158with the corresponding closing brace (in the above example, the brace 159after the last comment). Everything defined between those lines is 160considered to be the Dhcp4 configuration. 161 162In general, the order in which those parameters appear does not 163matter, but there are two caveats. The first one is that the 164configuration file must be well-formed JSON, meaning that the 165parameters for any given scope must be separated by a comma, and there 166must not be a comma after the last parameter. When reordering a 167configuration file, keep in mind that moving a parameter to or from the 168last position in a given scope may also require moving the comma. The 169second caveat is that it is uncommon — although legal JSON — to repeat 170the same parameter multiple times. If that happens, the last occurrence 171of a given parameter in a given scope is used, while all previous 172instances are ignored. This is unlikely to cause any confusion as there 173are no real-life reasons to keep multiple copies of the same parameter 174in the configuration file. 175 176The first few DHCPv4 configuration elements 177define some global parameters. ``valid-lifetime`` defines how long the 178addresses (leases) given out by the server are valid; the default 179is for a client to be allowed to use a given address for 4000 180seconds. (Note that integer numbers are specified as is, without any 181quotes around them.) ``renew-timer`` and ``rebind-timer`` are values 182(also in seconds) that define the T1 and T2 timers that govern when the 183client begins the renewal and rebind processes. 184 185.. note:: 186 187 Beginning with Kea 1.6.0, the lease valid-lifetime is extended from a 188 single value to a triplet with minimum, default, and maximum values using 189 ``min-valid-lifetime``, ``valid-lifetime``, and ``max-valid-lifetime``. 190 As of Kea 1.9.5, these values may be specified in client classes. The procedure 191 the server uses to select which lifetime value to use is as follows: 192 193 If the client query is a BOOTP query, the server always uses the 194 infinite lease time (e.g. 0xffffffff). Otherwise, the server must 195 determine which configured triplet to use by first searching all 196 classes assigned to the query, and then the subnet selected for 197 the query. 198 199 Classes are searched in the order they were assigned to the query; the 200 server uses the triplet from the first class that specifies it. 201 If no classes specify the triplet, the server uses the triplet 202 specified by the subnet selected for the client. If the subnet does not 203 explicitly specify it, the server next looks at the subnet's 204 shared-network (if one exists), then for a global specification, and 205 finally the global default. 206 207 If the client requested a lifetime value via DHCP option 51, then the 208 lifetime value used is the requested value bounded by the configured 209 triplet. In other words, if the requested lifetime is less than the 210 configured minimum, the configured minimum is used; if it is more 211 than the configured maximum, the configured maximum is used. If 212 the client did not provide a requested value, the lifetime value used 213 is the triplet default value. 214 215.. note:: 216 217 Both ``renew-timer`` and ``rebind-timer`` 218 are optional. The server only sends ``rebind-timer`` to the client, 219 via DHCPv4 option code 59, if it is less than ``valid-lifetime``; and it 220 only sends ``renew-timer``, via DHCPv4 option code 58, if it is less 221 than ``rebind-timer`` (or ``valid-lifetime`` if ``rebind-timer`` was not 222 specified). In their absence, the client should select values for T1 223 and T2 timers according to `RFC 2131 <https://tools.ietf.org/html/rfc2131>`_. 224 See section :ref:`dhcp4-t1-t2-times` 225 for more details on generating T1 and T2. 226 227The ``interfaces-config`` map specifies the server configuration 228concerning the network interfaces on which the server should listen to 229the DHCP messages. The ``interfaces`` parameter specifies a list of 230network interfaces on which the server should listen. Lists are opened 231and closed with square brackets, with elements separated by commas. To 232listen on two interfaces, the ``interfaces-config`` command should look 233like this: 234 235:: 236 237 "interfaces-config": { 238 "interfaces": [ "eth0", "eth1" ] 239 }, 240 241The next couple of lines define the lease database, the place where the 242server stores its lease information. This particular example tells the 243server to use ``memfile``, which is the simplest and fastest database 244backend. It uses an in-memory database and stores leases on disk in a 245CSV (comma-separated values) file. This is a very simple configuration example; usually the lease 246database configuration is more extensive and contains additional 247parameters. Note that ``lease-database`` is an object and opens up a new 248scope, using an opening brace. Its parameters (just one in this example: 249``type``) follow. If there were more than one, they would be separated 250by commas. This scope is closed with a closing brace. As more parameters 251for the Dhcp4 definition follow, a trailing comma is present. 252 253Finally, we need to define a list of IPv4 subnets. This is the most 254important DHCPv4 configuration structure, as the server uses that 255information to process clients' requests. It defines all subnets from 256which the server is expected to receive DHCP requests. The subnets are 257specified with the ``subnet4`` parameter. It is a list, so it starts and 258ends with square brackets. Each subnet definition in the list has 259several attributes associated with it, so it is a structure and is 260opened and closed with braces. At a minimum, a subnet definition has to 261have at least two parameters: ``subnet``, which defines the whole 262subnet; and ``pools``, which is a list of dynamically allocated pools 263that are governed by the DHCP server. 264 265The example contains a single subnet. If more than one were defined, 266additional elements in the ``subnet4`` parameter would be specified and 267separated by commas. For example, to define three subnets, the following 268syntax would be used: 269 270:: 271 272 "subnet4": [ 273 { 274 "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ], 275 "subnet": "192.0.2.0/24" 276 }, 277 { 278 "pools": [ { "pool": "192.0.3.100 - 192.0.3.200" } ], 279 "subnet": "192.0.3.0/24" 280 }, 281 { 282 "pools": [ { "pool": "192.0.4.1 - 192.0.4.254" } ], 283 "subnet": "192.0.4.0/24" 284 } 285 ] 286 287Note that indentation is optional and is used for aesthetic purposes 288only. In some cases it may be preferable to use more compact notation. 289 290After all the parameters have been specified, there are two contexts open: 291global and Dhcp4; thus, two closing curly brackets are needed to close 292them. 293 294Lease Storage 295------------- 296 297All leases issued by the server are stored in the lease database. 298Currently there are four database backends available: memfile 299(the default), MySQL, PostgreSQL, and Cassandra (deprecated). 300 301Memfile - Basic Storage for Leases 302~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 303 304The server is able to store lease data in different repositories. Larger 305deployments may elect to store leases in a database; 306:ref:`database-configuration4` describes this option. In 307typical smaller deployments, though, the server stores lease 308information in a CSV file rather than a database. As well as requiring 309less administration, an advantage of using a file for storage is that it 310eliminates a dependency on third-party database software. 311 312The configuration of the memfile backend is controlled through 313the Dhcp4/lease-database parameters. The ``type`` parameter is mandatory 314and specifies which storage for leases the server should use, through 315the ``memfile`` value. The following list gives additional optional parameters that 316can be used to configure the memfile backend. 317 318- ``persist``: controls whether the new leases and updates to existing 319 leases are written to the file. It is strongly recommended that the 320 value of this parameter be set to ``true`` at all times during the 321 server's normal operation. Not writing leases to disk means that if a 322 server is restarted (e.g. after a power failure), it will not know 323 which addresses have been assigned. As a result, it may assign new clients 324 addresses that are already in use. The value of 325 ``false`` is mostly useful for performance-testing purposes. The 326 default value of the ``persist`` parameter is ``true``, which enables 327 writing lease updates to the lease file. 328 329- ``name``: specifies an absolute location of the lease file in which 330 new leases and lease updates will be recorded. The default value for 331 this parameter is ``"[kea-install-dir]/var/lib/kea/kea-leases4.csv"``. 332 333- ``lfc-interval``: specifies the interval, in seconds, at which the 334 server will perform a lease file cleanup (LFC). This removes 335 redundant (historical) information from the lease file and 336 effectively reduces the lease file size. The cleanup process is 337 described in more detail later in this section. The default 338 value of the ``lfc-interval`` is ``3600``. A value of 0 disables the 339 LFC. 340 341- ``max-row-errors``: specifies the number of row errors before the server 342 stops attempting to load a lease file. When the server loads a lease file, it is processed 343 row by row, each row containing a single lease. If a row is flawed and 344 cannot be processed correctly the server logs it, discards the row, 345 and goes on to the next row. This parameter can be used to set a limit on 346 the number of such discards that can occur, after which the server 347 abandons the effort and exits. The default value of 0 disables the limit 348 and allows the server to process the entire file, regardless of how many 349 rows are discarded. 350 351:: 352 353 "Dhcp4": { 354 "lease-database": { 355 "type": "memfile", 356 "persist": true, 357 "name": "/tmp/kea-leases4.csv", 358 "lfc-interval": 1800, 359 "max-row-errors": 100 360 } 361 } 362 363This configuration selects ``/tmp/kea-leases4.csv`` as the storage 364for lease information and enables persistence (writing lease updates to 365this file). It also configures the backend to perform a periodic cleanup 366of the lease file every 1800 seconds (30 minutes) and sets the maximum number of row 367errors to 100. 368 369Why Is Lease File Cleanup Necessary? 370~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 371 372It is important to know how the lease file contents are organized to 373understand why the periodic lease file cleanup is needed. Every time the 374server updates a lease or creates a new lease for a client, the new 375lease information must be recorded in the lease file. For performance 376reasons, the server does not update the existing client's lease in the 377file, as this would potentially require rewriting the entire file. 378Instead, it simply appends the new lease information to the end of the 379file; the previous lease entries for the client are not removed. When 380the server loads leases from the lease file, e.g. at server startup, 381it assumes that the latest lease entry for the client is the valid one. 382Previous entries are discarded, meaning that the server can 383reconstruct accurate information about the leases even though there 384may be many lease entries for each client. However, storing many entries 385for each client results in a bloated lease file and impairs the 386performance of the server's startup and reconfiguration, as it needs to 387process a larger number of lease entries. 388 389Lease file cleanup (LFC) removes all previous entries for each client 390and leaves only the latest ones. The interval at which the cleanup is 391performed is configurable, and it should be selected according to the 392frequency of lease renewals initiated by the clients. The more frequent 393the renewals, the smaller the value of ``lfc-interval`` should be. Note, 394however, that the LFC takes time and thus it is possible (although 395unlikely) that, if the ``lfc-interval`` is too short, a new cleanup may 396be started while the previous one is still running. The server would 397recover from this by skipping the new cleanup when it detected that the 398previous cleanup was still in progress, but it implies that the actual 399cleanups will be triggered more rarely than the configured interval. Moreover, 400triggering a new cleanup adds overhead to the server, which is not 401able to respond to new requests for a short period of time when the new 402cleanup process is spawned. Therefore, it is recommended that the 403``lfc-interval`` value be selected in a way that allows the LFC 404to complete the cleanup before a new cleanup is triggered. 405 406Lease file cleanup is performed by a separate process (in the 407background) to avoid a performance impact on the server process. To 408avoid conflicts between two processes using the same lease 409files, the LFC process starts with Kea opening a new lease file; the 410actual LFC process operates on the lease file that is no longer used by 411the server. There are also other files created as a side effect of the 412lease file cleanup. The detailed description of the LFC process is located later 413in this Kea Administrator's Reference Manual: :ref:`kea-lfc`. 414 415.. _database-configuration4: 416 417Lease Database Configuration 418~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 419 420.. note:: 421 422 Lease database access information must be configured for the DHCPv4 423 server, even if it has already been configured for the DHCPv6 server. 424 The servers store their information independently, so each server can 425 use a separate database or both servers can use the same database. 426 427.. note:: 428 429 Kea requires the database timezone to match the system timezone. 430 For more details, see :ref:`mysql-database-create` and 431 :ref:`pgsql-database-create`. 432 433Lease database configuration is controlled through the 434Dhcp4/``lease-database`` parameters. The database type must be set to 435``memfile``, ``mysql``, ``postgresql``, or `cql``, e.g.: 436 437:: 438 439 "Dhcp4": { "lease-database": { "type": "mysql", ... }, ... } 440 441Next, the name of the database to hold the leases must be set; this is 442the name used when the database was created (see 443:ref:`mysql-database-create`, :ref:`pgsql-database-create`, or 444:ref:`cql-database-create`). 445 446For MySQL or PostgreSQL: 447 448:: 449 450 "Dhcp4": { "lease-database": { "name": "database-name" , ... }, ... } 451 452For Cassandra: 453 454:: 455 456 "Dhcp4": { "lease-database": { "keyspace": "database-name" , ... }, ... } 457 458If the database is located on a different system from the DHCPv4 server, 459the database host name must also be specified: 460 461:: 462 463 "Dhcp4": { "lease-database": { "host": "remote-host-name", ... }, ... } 464 465(It should be noted that this configuration may have a severe impact on server performance.) 466 467Normally, the database is on the same machine as the DHCPv4 server. 468In this case, set the value to the empty string: 469 470:: 471 472 "Dhcp4": { "lease-database": { "host" : "", ... }, ... } 473 474Should the database use a port other than the default, it may be 475specified as well: 476 477:: 478 479 "Dhcp4": { "lease-database": { "port" : 12345, ... }, ... } 480 481Should the database be located on a different system, the administrator may need to 482specify a longer interval for the connection timeout: 483 484:: 485 486 "Dhcp4": { "lease-database": { "connect-timeout" : timeout-in-seconds, ... }, ... } 487 488The default value of five seconds should be more than adequate for local 489connections. If a timeout is given, though, it should be an integer 490greater than zero. 491 492The maximum number of times the server automatically attempts to 493reconnect to the lease database after connectivity has been lost may be 494specified: 495 496:: 497 498 "Dhcp4": { "lease-database": { "max-reconnect-tries" : number-of-tries, ... }, ... } 499 500If the server is unable to reconnect to the database after making the 501maximum number of attempts, the server will exit. A value of zero (the 502default) disables automatic recovery and the server will exit 503immediately upon detecting a loss of connectivity (MySQL and PostgreSQL 504only). For Cassandra, Kea uses an interface that connects to 505all nodes in a cluster at the same time. Any connectivity issues should 506be handled by internal Cassandra mechanisms. 507 508The number of milliseconds the server waits between attempts to 509reconnect to the lease database after connectivity has been lost may 510also be specified: 511 512:: 513 514 "Dhcp4": { "lease-database": { "reconnect-wait-time" : number-of-milliseconds, ... }, ... } 515 516The default value for MySQL and PostgreSQL is 0, which disables automatic 517recovery and causes the server to exit immediately upon detecting the 518loss of connectivity. The default value for Cassandra is 2000 ms. 519 520:: 521 522 "Dhcp4": { "lease-database": { "on-fail" : "stop-retry-exit", ... }, ... } 523 524The possible values are: 525 526- ``stop-retry-exit`` - disables the DHCP service while trying to automatically 527 recover lost connections. Shuts down the server on failure after exhausting 528 ``max-reconnect-tries``. This is the default value for MySQL and PostgreSQL. 529 530- ``serve-retry-exit`` - continues the DHCP service while trying to automatically 531 recover lost connections. Shuts down the server on failure after exhausting 532 ``max-reconnect-tries``. 533 534- ``serve-retry-continue`` - continues the DHCP service and does not shut down the 535 server even if the recovery fails. 536 537.. note:: 538 539 Automatic reconnection to database backends is configured individually per 540 backend. This allows users to tailor the recovery parameters to each backend 541 they use. We do suggest that users enable it either for all backends or none, 542 so behavior is consistent. 543 544 Losing connectivity to a backend for which reconnect is disabled results 545 (if configured) in the server shutting itself down. This includes cases when 546 the lease database backend and the hosts database backend are connected to 547 the same database instance. 548 549 It is highly recommended not to change the ``stop-retry-exit`` default 550 setting for the lease manager, as it is critical for the connection to be 551 active while processing DHCP traffic. Change this only if the server is used 552 exclusively as a configuration tool. 553 554The host parameter is used by the MySQL and PostgreSQL backends. 555Cassandra has a concept of contact points that can be used to 556contact the cluster, instead of a single IP or hostname. It takes a 557list of comma-separated IP addresses, which may be specified as: 558 559:: 560 561 "Dhcp4": { "lease-database": { "contact-points" : "192.0.2.1,192.0.2.2", ... }, ... } 562 563Finally, the credentials of the account under which the server will 564access the database should be set: 565 566:: 567 568 "Dhcp4": { "lease-database": { "user": "user-name", 569 "password": "password", 570 ... }, 571 ... } 572 573If there is no password to the account, set the password to the empty 574string ``""``. (This is the default.) 575 576.. _cassandra-database-configuration4: 577 578Cassandra-Specific Parameters 579~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 580 581The Cassandra backend is configured slightly differently. Cassandra has 582a concept of contact points that can be used to contact the cluster, 583instead of a single IP or hostname. It takes a list of comma-separated 584IP addresses, which may be specified as: 585 586:: 587 588 "Dhcp4": { 589 "lease-database": { 590 "type": "cql", 591 "contact-points": "ip-address1, ip-address2 [,...]", 592 ... 593 }, 594 ... 595 } 596 597Cassandra also supports a number of optional parameters: 598 599- ``reconnect-wait-time`` - governs how long Kea waits before 600 attempting to reconnect. Expressed in milliseconds. The default is 601 2000 [ms]. 602 603- ``connect-timeout`` - sets the timeout for connecting to a node. 604 Expressed in milliseconds. The default is 5000 [ms]. 605 606- ``request-timeout`` - sets the timeout for waiting for a response 607 from a node. Expressed in milliseconds. The default is 12000 [ms]. 608 609- ``tcp-keepalive`` - governs the TCP keep-alive mechanism. Expressed 610 in seconds of delay. If the parameter is not present, the mechanism 611 is disabled. 612 613- ``tcp-nodelay`` - enables/disables Nagle's algorithm on connections. 614 The default is ``true``. 615 616- ``consistency`` - configures the consistency level. The default is 617 "quorum". Supported values: any, one, two, three, quorum, all, 618 local-quorum, each-quorum, serial, local-serial, local-one. See 619 `Cassandra 620 consistency <https://docs.datastax.com/en/cassandra/3.0/cassandra/dml/dmlConfigConsistency.html>`__ 621 for more details. 622 623- ``serial-consistency`` - configures the serial consistency level, which 624 manages lightweight transaction isolation. The default is "serial". 625 Supported values: any, one, two, three, quorum, all, local-quorum, 626 each-quorum, serial, local-serial, local-one. See `Cassandra serial 627 consistency <https://docs.datastax.com/en/cassandra/3.0/cassandra/dml/dmlConfigSerialConsistency.html>`__ 628 for more details. 629 630For example, a complex Cassandra configuration with most parameters 631specified could look as follows: 632 633:: 634 635 "Dhcp4": { 636 "lease-database": { 637 "type": "cql", 638 "keyspace": "keatest", 639 "contact-points": "192.0.2.1, 192.0.2.2, 192.0.2.3", 640 "port": 9042, 641 "reconnect-wait-time": 2000, 642 "connect-timeout": 5000, 643 "request-timeout": 12000, 644 "tcp-keepalive": 1, 645 "tcp-nodelay": true 646 }, 647 ... 648 } 649 650Similar parameters can be specified for the hosts database. 651 652.. _hosts4-storage: 653 654Hosts Storage 655------------- 656 657Kea is also able to store information about host reservations in the 658database. The hosts database configuration uses the same syntax as the 659lease database. In fact, the Kea server opens independent connections for 660each purpose, be it lease or hosts information, which gives 661the most flexibility. Kea can keep leases and host reservations 662separately, but can also point to the same database. Currently the 663supported hosts database types are MySQL, PostgreSQL, and Cassandra. 664 665The following configuration can be used to configure a 666connection to MySQL: 667 668:: 669 670 "Dhcp4": { 671 "hosts-database": { 672 "type": "mysql", 673 "name": "kea", 674 "user": "kea", 675 "password": "secret123", 676 "host": "localhost", 677 "port": 3306 678 } 679 } 680 681Please note that usage of hosts storage is optional. A user can define 682all host reservations in the configuration file, and that is the 683recommended way if the number of reservations is small. However, when 684the number of reservations grows, it is more convenient to use host 685storage. Please note that both storage methods (the configuration file and 686one of the supported databases) can be used together. If hosts are 687defined in both places, the definitions from the configuration file are 688checked first and external storage is checked later, if necessary. 689 690Host information can be placed in multiple stores. Operations 691are performed on the stores in the order they are defined in the 692configuration file, although this leads to a restriction in ordering 693in the case of a host reservation addition; read-only stores must be 694configured after a (required) read-write store, or the addition will 695fail. 696 697.. note:: 698 699 Kea requires the database timezone to match the system timezone. 700 For more details, see :ref:`mysql-database-create` and 701 :ref:`pgsql-database-create`. 702 703.. _hosts-databases-configuration4: 704 705DHCPv4 Hosts Database Configuration 706~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 707 708Hosts database configuration is controlled through the 709Dhcp4/``hosts-database`` parameters. If enabled, the type of database must 710be set to ``mysql`` or ``postgresql``. 711 712:: 713 714 "Dhcp4": { "hosts-database": { "type": "mysql", ... }, ... } 715 716Next, the name of the database to hold the reservations must be set; 717this is the name used when the lease database was created (see 718:ref:`supported-databases` for instructions on how to set up the 719desired database type): 720 721:: 722 723 "Dhcp4": { "hosts-database": { "name": "database-name" , ... }, ... } 724 725If the database is located on a different system than the DHCPv4 server, 726the database host name must also be specified: 727 728:: 729 730 "Dhcp4": { "hosts-database": { "host": remote-host-name, ... }, ... } 731 732(Again, it should be noted that this configuration may have a severe impact on server performance.) 733 734Normally, the database is on the same machine as the DHCPv4 server. 735In this case, set the value to the empty string: 736 737:: 738 739 "Dhcp4": { "hosts-database": { "host" : "", ... }, ... } 740 741Should the database use a port different than the default, it may be 742specified as well: 743 744:: 745 746 "Dhcp4": { "hosts-database": { "port" : 12345, ... }, ... } 747 748The maximum number of times the server automatically attempts to 749reconnect to the host database after connectivity has been lost may be 750specified: 751 752:: 753 754 "Dhcp4": { "hosts-database": { "max-reconnect-tries" : number-of-tries, ... }, ... } 755 756If the server is unable to reconnect to the database after making the 757maximum number of attempts, the server will exit. A value of zero (the 758default) disables automatic recovery and the server will exit 759immediately upon detecting a loss of connectivity (MySQL and PostgreSQL 760only). 761 762The number of milliseconds the server waits between attempts to 763reconnect to the host database after connectivity has been lost may also 764be specified: 765 766:: 767 768 "Dhcp4": { "hosts-database": { "reconnect-wait-time" : number-of-milliseconds, ... }, ... } 769 770The default value for MySQL and PostgreSQL is 0, which disables automatic 771recovery and causes the server to exit immediately upon detecting the 772loss of connectivity. The default value for Cassandra is 2000 ms. 773 774:: 775 776 "Dhcp4": { "hosts-database": { "on-fail" : "stop-retry-exit", ... }, ... } 777 778The possible values are: 779 780- ``stop-retry-exit`` - disables the DHCP service while trying to automatically 781 recover lost connections. Shuts down the server on failure after exhausting 782 ``max-reconnect-tries``. This is the default value for MySQL and PostgreSQL. 783 784- ``serve-retry-exit`` - continues the DHCP service while trying to automatically 785 recover lost connections. Shuts down the server on failure after exhausting 786 ``max-reconnect-tries``. 787 788- ``serve-retry-continue`` - continues the DHCP service and does not shut down the 789 server even if the recovery fails. 790 791.. note:: 792 793 Automatic reconnection to database backends is configured individually per 794 backend. This allows users to tailor the recovery parameters to each backend 795 they use. We do suggest that users enable it either for all backends or none, 796 so behavior is consistent. 797 798 Losing connectivity to a backend for which reconnect is disabled results 799 (if configured) in the server shutting itself down. This includes cases when 800 the lease database backend and the hosts database backend are connected to 801 the same database instance. 802 803Finally, the credentials of the account under which the server will 804access the database should be set: 805 806:: 807 808 "Dhcp4": { "hosts-database": { "user": "user-name", 809 "password": "password", 810 ... }, 811 ... } 812 813If there is no password to the account, set the password to the empty 814string ``""``. (This is the default.) 815 816The multiple storage extension uses a similar syntax; a configuration is 817placed into a ``hosts-databases`` list instead of into a ``hosts-database`` 818entry, as in: 819 820:: 821 822 "Dhcp4": { "hosts-databases": [ { "type": "mysql", ... }, ... ], ... } 823 824For Cassandra-specific parameters, see :ref:`cassandra-database-configuration4`. 825 826If the same host is configured both in-file and in-database, Kea does not issue a warning, 827as it would if both were specified in the same data source. 828Instead, the host configured in-file has priority over the one configured 829in-database. 830 831.. _read-only-database-configuration4: 832 833Using Read-Only Databases for Host Reservations With DHCPv4 834~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 835 836In some deployments, the user whose name is specified in the 837database backend configuration may not have write privileges to the 838database. This is often required by the policy within a given network to 839secure the data from being unintentionally modified. In many cases 840administrators have deployed inventory databases, which contain 841substantially more information about the hosts than just the static 842reservations assigned to them. The inventory database can be used to 843create a view of a Kea hosts database and such a view is often 844read-only. 845 846Kea host-database backends operate with an implicit configuration to 847both read from and write to the database. If the database user does not 848have write access to the host database, the backend will fail to start 849and the server will refuse to start (or reconfigure). However, if access 850to a read-only host database is required for retrieving reservations 851for clients and/or assigning specific addresses and options, it is 852possible to explicitly configure Kea to start in "read-only" mode. This 853is controlled by the ``readonly`` boolean parameter as follows: 854 855:: 856 857 "Dhcp4": { "hosts-database": { "readonly": true, ... }, ... } 858 859Setting this parameter to ``false`` configures the database backend to 860operate in "read-write" mode, which is also the default configuration if 861the parameter is not specified. 862 863.. note:: 864 865 The ``readonly`` parameter is only supported for MySQL and 866 PostgreSQL databases. 867 868.. _dhcp4-interface-configuration: 869 870Interface Configuration 871----------------------- 872 873The DHCPv4 server must be configured to listen on specific network 874interfaces. The simplest network interface configuration tells the 875server to listen on all available interfaces: 876 877:: 878 879 "Dhcp4": { 880 "interfaces-config": { 881 "interfaces": [ "*" ] 882 } 883 ... 884 }, 885 886 887The asterisk plays the role of a wildcard and means "listen on all 888interfaces." However, it is usually a good idea to explicitly specify 889interface names: 890 891:: 892 893 "Dhcp4": { 894 "interfaces-config": { 895 "interfaces": [ "eth1", "eth3" ] 896 }, 897 ... 898 } 899 900 901It is possible to use an interface wildcard (*) concurrently 902with explicit interface names: 903 904:: 905 906 "Dhcp4": { 907 "interfaces-config": { 908 "interfaces": [ "eth1", "eth3", "*" ] 909 }, 910 ... 911 } 912 913 914This form of usage should only be used when it is 915desired to temporarily override a list of interface names and listen on 916all interfaces. 917 918Some deployments of DHCP servers require that the servers listen on 919interfaces with multiple IPv4 addresses configured. In these situations, 920the address to use can be selected by appending an IPv4 address to the 921interface name in the following manner: 922 923:: 924 925 "Dhcp4": { 926 "interfaces-config": { 927 "interfaces": [ "eth1/10.0.0.1", "eth3/192.0.2.3" ] 928 }, 929 ... 930 } 931 932 933Should the server be required to listen on multiple IPv4 addresses 934assigned to the same interface, multiple addresses can be specified for 935an interface as in the example below: 936 937:: 938 939 "Dhcp4": { 940 "interfaces-config": { 941 "interfaces": [ "eth1/10.0.0.1", "eth1/10.0.0.2" ] 942 }, 943 ... 944 } 945 946 947Alternatively, if the server should listen on all addresses for the 948particular interface, an interface name without any address should be 949specified. 950 951Kea supports responding to directly connected clients which do not have 952an address configured. This requires the server to inject the hardware 953address of the destination into the data-link layer of the packet 954being sent to the client. The DHCPv4 server uses raw sockets to 955achieve this, and builds the entire IP/UDP stack for the outgoing 956packets. The downside of raw socket use, however, is that incoming and 957outgoing packets bypass the firewalls (e.g. iptables). 958 959Handling traffic on multiple IPv4 addresses assigned to the same 960interface can be a challenge, as raw sockets are bound to the 961interface. When the DHCP server is configured to use the raw socket on 962an interface to receive DHCP traffic, advanced packet filtering 963techniques (e.g. the BPF) must be used to receive unicast traffic on 964the desired addresses assigned to the interface. Whether clients use 965the raw socket or the UDP socket depends on whether they are directly 966connected (raw socket) or relayed (either raw or UDP socket). 967 968Therefore, in deployments where the server does not need to provision 969the directly connected clients and only receives the unicast packets 970from the relay agents, the Kea server should be configured to use UDP 971sockets instead of raw sockets. The following configuration 972demonstrates how this can be achieved: 973 974:: 975 976 "Dhcp4": { 977 "interfaces-config": { 978 "interfaces": [ "eth1", "eth3" ], 979 "dhcp-socket-type": "udp" 980 }, 981 ... 982 } 983 984 985The ``dhcp-socket-type`` parameter specifies that the IP/UDP sockets will be 986opened on all interfaces on which the server listens, i.e. "eth1" and 987"eth3" in this example. If ``dhcp-socket-type`` is set to ``raw``, it 988configures the server to use raw sockets instead. If the 989``dhcp-socket-type`` value is not specified, the default value ``raw`` 990is used. 991 992Using UDP sockets automatically disables the reception of broadcast 993packets from directly connected clients. This effectively means that UDP 994sockets can be used for relayed traffic only. When using raw sockets, 995both the traffic from the directly connected clients and the relayed 996traffic are handled. 997 998Caution should be taken when configuring the server 999to open multiple raw sockets on the interface with several IPv4 1000addresses assigned. If the directly connected client sends the message 1001to the broadcast address, all sockets on this link will receive this 1002message and multiple responses will be sent to the client. Therefore, 1003the configuration with multiple IPv4 addresses assigned to the interface 1004should not be used when the directly connected clients are operating on 1005that link. To use a single address on such an interface, the 1006"interface-name/address" notation should be used. 1007 1008.. note:: 1009 1010 Specifying the value ``raw`` as the socket type does not guarantee 1011 that raw sockets will be used! The use of raw sockets to handle 1012 traffic from the directly connected clients is currently 1013 supported on Linux and BSD systems only. If raw sockets are not 1014 supported on the particular OS in use, the server will issue a warning and 1015 fall back to using IP/UDP sockets. 1016 1017In a typical environment, the DHCP server is expected to send back a 1018response on the same network interface on which the query was received. 1019This is the default behavior. However, in some deployments it is desired 1020that the outbound (response) packets be sent as regular traffic and 1021the outbound interface be determined by the routing tables. This 1022kind of asymmetric traffic is uncommon, but valid. Kea supports a 1023parameter called ``outbound-interface`` that controls this behavior. It 1024supports two values: the first one, ``same-as-inbound``, tells Kea to 1025send back the response on the same interface where the query packet was 1026received. This is the default behavior. The second parameter, ``use-routing``, 1027tells Kea to send regular UDP packets and let the kernel's routing table 1028determine the most appropriate interface. This only works when 1029``dhcp-socket-type`` is set to ``udp``. An example configuration looks 1030as follows: 1031 1032:: 1033 1034 "Dhcp4": { 1035 "interfaces-config": { 1036 "interfaces": [ "eth1", "eth3" ], 1037 "dhcp-socket-type": "udp", 1038 "outbound-interface": "use-routing" 1039 }, 1040 ... 1041 } 1042 1043Interfaces are re-detected at each reconfiguration. This behavior can be 1044disabled by setting the ``re-detect`` value to ``false``, for instance: 1045 1046:: 1047 1048 "Dhcp4": { 1049 "interfaces-config": { 1050 "interfaces": [ "eth1", "eth3" ], 1051 "re-detect": false 1052 }, 1053 ... 1054 } 1055 1056 1057Note that interfaces are not re-detected during ``config-test``. 1058 1059Usually loopback interfaces (e.g. the `lo` or `lo0` interface) are not 1060configured, but if a loopback interface is explicitly configured and 1061IP/UDP sockets are specified, the loopback interface is accepted. 1062 1063For example, this setup can be used to run Kea in a FreeBSD jail having only a 1064loopback interface, to service a relayed DHCP request: 1065 1066:: 1067 1068 "Dhcp4": { 1069 "interfaces-config": { 1070 "interfaces": [ "lo0" ], 1071 "dhcp-socket-type": "udp" 1072 }, 1073 ... 1074 } 1075 1076.. _dhcpinform-unicast-issues: 1077 1078Issues With Unicast Responses to DHCPINFORM 1079------------------------------------------- 1080 1081The use of UDP sockets has certain benefits in deployments where the 1082server receives only relayed traffic; these benefits are mentioned in 1083:ref:`dhcp4-interface-configuration`. From the 1084administrator's perspective it is often desirable to configure the 1085system's firewall to filter out unwanted traffic, and the use of UDP 1086sockets facilitates this. However, the administrator must also be aware 1087of the implications related to filtering certain types of traffic, as it 1088may impair the DHCP server's operation. 1089 1090In this section we focus on the case when the server receives the 1091DHCPINFORM message from the client via a relay. According to `RFC 10922131 <https://tools.ietf.org/html/rfc2131>`__, the server should unicast 1093the DHCPACK response to the address carried in the ``ciaddr`` field. When 1094the UDP socket is in use, the DHCP server relies on the low-level 1095functions of an operating system to build the data link, IP, and UDP 1096layers of the outgoing message. Typically, the OS first uses ARP to 1097obtain the client's link-layer address to be inserted into the frame's 1098header, if the address is not cached from a previous transaction that 1099the client had with the server. When the ARP exchange is successful, the 1100DHCP message can be unicast to the client, using the obtained address. 1101 1102Some system administrators block ARP messages in their network, which 1103causes issues for the server when it responds to the DHCPINFORM 1104messages because the server is unable to send the DHCPACK if the 1105preceding ARP communication fails. Since the OS is entirely responsible 1106for the ARP communication and then sending the DHCP packet over the 1107wire, the DHCP server has no means to determine that the ARP exchange 1108failed and the DHCP response message was dropped. Thus, the server does 1109not log any error messages when the outgoing DHCP response is dropped. 1110At the same time, all hooks pertaining to the packet-sending operation 1111will be called, even though the message never reaches its destination. 1112 1113Note that the issue described in this section is not observed when 1114raw sockets are in use, because, in this case, the DHCP server builds 1115all the layers of the outgoing message on its own and does not use ARP. 1116Instead, it inserts the value carried in the ``chaddr`` field of the 1117DHCPINFORM message into the link layer. 1118 1119Server administrators willing to support DHCPINFORM messages via relays 1120should not block ARP traffic in their networks, or should use raw sockets 1121instead of UDP sockets. 1122 1123.. _ipv4-subnet-id: 1124 1125IPv4 Subnet Identifier 1126---------------------- 1127 1128The subnet identifier (subnet ID) is a unique number associated with a particular 1129subnet. In principle, it is used to associate clients' leases with their 1130respective subnets. When a subnet identifier is not specified for a 1131subnet being configured, it is automatically assigned by the 1132configuration mechanism. The identifiers are assigned starting at 1 and are 1133monotonically increased for each subsequent subnet: 1, 2, 3 .... 1134 1135If there are multiple subnets configured with auto-generated identifiers 1136and one of them is removed, the subnet identifiers may be renumbered. 1137For example: if there are four subnets and the third is removed, the 1138last subnet will be assigned the identifier that the third subnet had 1139before removal. As a result, the leases stored in the lease database for 1140subnet 3 are now associated with subnet 4, something that may have 1141unexpected consequences. The only remedy for this issue at present is to 1142manually specify a unique identifier for each subnet. 1143 1144.. note:: 1145 1146 Subnet IDs must be greater than zero and less than 4294967295. 1147 1148The following configuration assigns the specified subnet identifier 1149to a newly configured subnet: 1150 1151:: 1152 1153 "Dhcp4": { 1154 "subnet4": [ 1155 { 1156 "subnet": "192.0.2.0/24", 1157 "id": 1024, 1158 ... 1159 } 1160 ] 1161 } 1162 1163This identifier will not change for this subnet unless the ``id`` 1164parameter is removed or set to 0. The value of 0 forces auto-generation 1165of the subnet identifier. 1166 1167.. _ipv4-subnet-prefix: 1168 1169IPv4 Subnet Prefix 1170------------------ 1171 1172The subnet prefix is the second way to identify a subnet. It does not 1173need to have the address part to match the prefix length; for instance, 1174this configuration is accepted: 1175 1176:: 1177 1178 "Dhcp4": { 1179 "subnet4": [ 1180 { 1181 "subnet": "192.0.2.1/24", 1182 ... 1183 } 1184 ] 1185 } 1186 1187This works even if there is another subnet with the "192.0.2.0/24" prefix; only the 1188textual form of subnets are compared to avoid duplicates. 1189 1190.. note:: 1191 1192 Abuse of this feature can lead to incorrect subnet selection 1193 (see :ref:`dhcp4-subnet-selection`). 1194 1195.. _dhcp4-address-config: 1196 1197Configuration of IPv4 Address Pools 1198----------------------------------- 1199 1200The main role of a DHCPv4 server is address assignment. For this, the 1201server must be configured with at least one subnet and one pool of 1202dynamic addresses to be managed. For example, assume that the server is 1203connected to a network segment that uses the 192.0.2.0/24 prefix. The 1204administrator of that network decides that addresses from range 1205192.0.2.10 to 192.0.2.20 are going to be managed by the Dhcp4 server. 1206Such a configuration can be achieved in the following way: 1207 1208:: 1209 1210 "Dhcp4": { 1211 "subnet4": [ 1212 { 1213 "subnet": "192.0.2.0/24", 1214 "pools": [ 1215 { "pool": "192.0.2.10 - 192.0.2.20" } 1216 ], 1217 ... 1218 } 1219 ] 1220 } 1221 1222Note that ``subnet`` is defined as a simple string, but the ``pools`` 1223parameter is actually a list of pools; for this reason, the pool 1224definition is enclosed in square brackets, even though only one range of 1225addresses is specified. 1226 1227Each ``pool`` is a structure that contains the parameters that describe 1228a single pool. Currently there is only one parameter, ``pool``, which 1229gives the range of addresses in the pool. 1230 1231It is possible to define more than one pool in a subnet; continuing the 1232previous example, further assume that 192.0.2.64/26 should also be 1233managed by the server. It could be written as 192.0.2.64 to 192.0.2.127, 1234or it can be expressed more simply as 192.0.2.64/26. Both 1235formats are supported by Dhcp4 and can be mixed in the pool list. For 1236example, one could define the following pools: 1237 1238:: 1239 1240 "Dhcp4": { 1241 "subnet4": [ 1242 { 1243 "subnet": "192.0.2.0/24", 1244 "pools": [ 1245 { "pool": "192.0.2.10-192.0.2.20" }, 1246 { "pool": "192.0.2.64/26" } 1247 ], 1248 ... 1249 } 1250 ], 1251 ... 1252 } 1253 1254White space in pool definitions is ignored, so spaces before and after 1255the hyphen are optional. They can be used to improve readability. 1256 1257The number of pools is not limited, but for performance reasons it is 1258recommended to use as few as possible. 1259 1260The server may be configured to serve more than one subnet: 1261 1262:: 1263 1264 "Dhcp4": { 1265 "subnet4": [ 1266 { 1267 "subnet": "192.0.2.0/24", 1268 "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ], 1269 ... 1270 }, 1271 { 1272 "subnet": "192.0.3.0/24", 1273 "pools": [ { "pool": "192.0.3.100 - 192.0.3.200" } ], 1274 ... 1275 }, 1276 { 1277 "subnet": "192.0.4.0/24", 1278 "pools": [ { "pool": "192.0.4.1 - 192.0.4.254" } ], 1279 ... 1280 } 1281 ] 1282 } 1283 1284When configuring a DHCPv4 server using prefix/length notation, please 1285pay attention to the boundary values. When specifying that the server 1286can use a given pool, it is also able to allocate the first 1287(typically a network address) and the last (typically a broadcast 1288address) address from that pool. In the aforementioned example of pool 1289192.0.3.0/24, both the 192.0.3.0 and 192.0.3.255 addresses may be 1290assigned as well. This may be invalid in some network configurations. To 1291avoid this, use the "min-max" notation. 1292 1293.. _dhcp4-t1-t2-times: 1294 1295Sending T1 (Option 58) and T2 (Option 59) 1296----------------------------------------- 1297 1298According to `RFC 2131 <https://tools.ietf.org/html/rfc2131>`__, 1299servers should send values for T1 and T2 that are 50% and 87.5% of the 1300lease lifetime, respectively. By default, ``kea-dhcp4`` does not send 1301either value; it can be configured to send values that are either specified 1302explicitly or that are calculated as percentages of the lease time. The 1303server's behavior is governed by a combination of configuration 1304parameters, two of which have already been mentioned. 1305To send specific, fixed values use the following two parameters: 1306 1307- ``renew-timer`` - specifies the value of T1 in seconds. 1308 1309- ``rebind-timer`` - specifies the value of T2 in seconds. 1310 1311The server only sends T2 if it is less than the valid lease time. T1 1312is only sent if T2 is being sent and T1 is less than T2; or T2 1313is not being sent and T1 is less than the valid lease time. 1314 1315Calculating the values is controlled by the following three parameters. 1316 1317- ``calculate-tee-times`` - when true, T1 and T2 are calculated as 1318 percentages of the valid lease time. It defaults to false. 1319 1320- ``t1-percent`` - the percentage of the valid lease time to use for 1321 T1. It is expressed as a real number between 0.0 and 1.0 and must be 1322 less than ``t2-percent``. The default value is 0.50, per RFC 2131. 1323 1324- ``t2-percent`` - the percentage of the valid lease time to use for 1325 T2. It is expressed as a real number between 0.0 and 1.0 and must be 1326 greater than ``t1-percent``. The default value is .875, per RFC 2131. 1327 1328.. 1329 1330.. note:: 1331 1332 In the event that both explicit values are specified and 1333 ``calculate-tee-times`` is true, the server will use the explicit values. 1334 Administrators with a setup where some subnets or shared-networks 1335 use explicit values and some use calculated values must 1336 not define the explicit values at any level higher than where they 1337 will be used. Inheriting them from too high a scope, such as 1338 global, will cause them to have explicit values at every level underneath 1339 (shared-networks and subnets), effectively disabling calculated 1340 values. 1341 1342.. _dhcp4-std-options: 1343 1344Standard DHCPv4 Options 1345----------------------- 1346 1347One of the major features of the DHCPv4 server is the ability to provide 1348configuration options to clients. Most of the options are sent by the 1349server only if the client explicitly requests them using the Parameter 1350Request List option. Those that do not require inclusion in the 1351Parameter Request List option are commonly used options, e.g. "Domain 1352Server", and options which require special behavior, e.g. "Client FQDN", 1353which is returned to the client if the client has included this option 1354in its message to the server. 1355 1356:ref:`dhcp4-std-options-list` comprises the list of the 1357standard DHCPv4 options whose values can be configured using the 1358configuration structures described in this section. This table excludes 1359the options which require special processing and thus cannot be 1360configured with fixed values. The last column of the table 1361indicates which options can be sent by the server even when they are not 1362requested in the Parameter Request List option, and those which are sent 1363only when explicitly requested. 1364 1365The following example shows how to configure the addresses of DNS 1366servers, which is one of the most frequently used options. Options 1367specified in this way are considered global and apply to all configured 1368subnets. 1369 1370:: 1371 1372 "Dhcp4": { 1373 "option-data": [ 1374 { 1375 "name": "domain-name-servers", 1376 "code": 6, 1377 "space": "dhcp4", 1378 "csv-format": true, 1379 "data": "192.0.2.1, 192.0.2.2" 1380 }, 1381 ... 1382 ] 1383 } 1384 1385 1386Note that either ``name`` or ``code`` is required; there is no need to 1387specify both. ``space`` has a default value of "dhcp4", so this can be skipped 1388as well if a regular (not encapsulated) DHCPv4 option is defined. 1389Finally, ``csv-format`` defaults to "true", so it too can be skipped, unless 1390the option value is specified as a hexadecimal string. Therefore, 1391the above example can be simplified to: 1392 1393:: 1394 1395 "Dhcp4": { 1396 "option-data": [ 1397 { 1398 "name": "domain-name-servers", 1399 "data": "192.0.2.1, 192.0.2.2" 1400 }, 1401 ... 1402 ] 1403 } 1404 1405 1406Defined options are added to the response when the client requests them, 1407with a few exceptions which are always added. To enforce the addition of 1408a particular option, set the ``always-send`` flag to "true" as in: 1409 1410:: 1411 1412 "Dhcp4": { 1413 "option-data": [ 1414 { 1415 "name": "domain-name-servers", 1416 "data": "192.0.2.1, 192.0.2.2", 1417 "always-send": true 1418 }, 1419 ... 1420 ] 1421 } 1422 1423 1424The effect is the same as if the client added the option code in the 1425Parameter Request List option (or its equivalent for vendor options): 1426 1427:: 1428 1429 "Dhcp4": { 1430 "option-data": [ 1431 { 1432 "name": "domain-name-servers", 1433 "data": "192.0.2.1, 192.0.2.2", 1434 "always-send": true 1435 }, 1436 ... 1437 ], 1438 "subnet4": [ 1439 { 1440 "subnet": "192.0.3.0/24", 1441 "option-data": [ 1442 { 1443 "name": "domain-name-servers", 1444 "data": "192.0.3.1, 192.0.3.2" 1445 }, 1446 ... 1447 ], 1448 ... 1449 }, 1450 ... 1451 ], 1452 ... 1453 } 1454 1455 1456The ``domain-name-servers`` option is always added to responses (the 1457always-send is "sticky"), but the value is the subnet one when the client 1458is localized in the subnet. 1459 1460The ``name`` parameter specifies the option name. For a list of 1461currently supported names, see :ref:`dhcp4-std-options-list` 1462below. The ``code`` parameter specifies the option code, which must 1463match one of the values from that list. The next line specifies the 1464option space, which must always be set to "dhcp4" as these are standard 1465DHCPv4 options. For other option spaces, including custom option spaces, 1466see :ref:`dhcp4-option-spaces`. The next line specifies the format in 1467which the data will be entered; use of CSV (comma-separated values) is 1468recommended. The sixth line gives the actual value to be sent to 1469clients. The data parameter is specified as normal text, with values separated by 1470commas if more than one value is allowed. 1471 1472Options can also be configured as hexadecimal values. If ``csv-format`` 1473is set to "false", option data must be specified as a hexadecimal string. 1474The following commands configure the ``domain-name-servers`` option for all 1475subnets with the following addresses: 192.0.3.1 and 192.0.3.2. Note that 1476``csv-format`` is set to "false". 1477 1478:: 1479 1480 "Dhcp4": { 1481 "option-data": [ 1482 { 1483 "name": "domain-name-servers", 1484 "code": 6, 1485 "space": "dhcp4", 1486 "csv-format": false, 1487 "data": "C0 00 03 01 C0 00 03 02" 1488 }, 1489 ... 1490 ], 1491 ... 1492 } 1493 1494Kea supports the following formats when specifying hexadecimal data: 1495 1496- ``Delimited octets`` - one or more octets separated by either colons or 1497 spaces (':' or ' '). While each octet may contain one or two digits, 1498 we strongly recommend always using two digits. Valid examples are 1499 `ab:cd:ef` and `ab cd ef`. 1500 1501- ``String of digits`` - a continuous string of hexadecimal digits with 1502 or without a `0x` prefix. Valid examples are `0xabcdef` and `abcdef`. 1503 1504Care should be taken to use proper encoding when using hexadecimal 1505format; Kea's ability to validate data correctness in hexadecimal is 1506limited. 1507 1508As of Kea 1.6.0, it is also possible to specify data for binary options as 1509a single-quoted text string within double quotes as shown (note that 1510``csv-format`` must be set to false): 1511 1512:: 1513 1514 "Dhcp4": { 1515 "option-data": [ 1516 { 1517 "name": "user-class", 1518 "code": 77, 1519 "space": "dhcp4", 1520 "csv-format": false, 1521 "data": "'convert this text to binary'" 1522 }, 1523 ... 1524 ], 1525 ... 1526 } 1527 1528Most of the parameters in the ``option-data`` structure are optional and 1529can be omitted in some circumstances, as discussed in :ref:`dhcp4-option-data-defaults`. 1530 1531It is possible to specify or override options on a per-subnet basis. If 1532clients connected to most subnets are expected to get the same 1533values of a given option, administrators should use global options. On the other 1534hand, if different values are used in each subnet, it does not make sense 1535to specify global option values; rather, only 1536subnet-specific ones should be set. 1537 1538The following commands override the global DNS servers option for a 1539particular subnet, setting a single DNS server with address 192.0.2.3: 1540 1541:: 1542 1543 "Dhcp4": { 1544 "subnet4": [ 1545 { 1546 "option-data": [ 1547 { 1548 "name": "domain-name-servers", 1549 "code": 6, 1550 "space": "dhcp4", 1551 "csv-format": true, 1552 "data": "192.0.2.3" 1553 }, 1554 ... 1555 ], 1556 ... 1557 }, 1558 ... 1559 ], 1560 ... 1561 } 1562 1563In some cases it is useful to associate some options with an address 1564pool from which a client is assigned a lease. Pool-specific option 1565values override subnet-specific and global option values; it 1566is not possible to prioritize assignment of pool-specific 1567options via the order of pool declarations in the server 1568configuration. 1569 1570The following configuration snippet demonstrates how to specify the DNS 1571servers option, which is assigned to a client only if the client 1572obtains an address from the given pool: 1573 1574:: 1575 1576 "Dhcp4": { 1577 "subnet4": [ 1578 { 1579 "pools": [ 1580 { 1581 "pool": "192.0.2.1 - 192.0.2.200", 1582 "option-data": [ 1583 { 1584 "name": "domain-name-servers", 1585 "data": "192.0.2.3" 1586 }, 1587 ... 1588 ], 1589 ... 1590 }, 1591 ... 1592 ], 1593 ... 1594 }, 1595 ... 1596 ], 1597 ... 1598 } 1599 1600Options can also be specified in class or host reservation scope. The 1601current Kea options precedence order is (from most important to least): host 1602reservation, pool, subnet, shared network, class, global. 1603 1604The currently supported standard DHCPv4 options are listed in 1605:ref:`dhcp4-std-options-list`. "Name" and "Code" are the 1606values that should be used as a name/code in the option-data structures. 1607"Type" designates the format of the data; the meanings of the various 1608types are given in :ref:`dhcp-types`. 1609 1610When a data field is a string and that string contains the comma (,; 1611U+002C) character, the comma must be escaped with two backslashes (\; 1612U+005C). This double escape is required because both the routine 1613splitting of CSV data into fields and JSON use the same escape character; a 1614single escape (\,) would make the JSON invalid. For example, the string 1615"foo,bar" must be represented as: 1616 1617:: 1618 1619 "Dhcp4": { 1620 "subnet4": [ 1621 { 1622 "pools": [ 1623 { 1624 "option-data": [ 1625 { 1626 "name": "boot-file-name", 1627 "data": "foo\\,bar" 1628 } 1629 ] 1630 }, 1631 ... 1632 ], 1633 ... 1634 }, 1635 ... 1636 ], 1637 ... 1638 } 1639 1640Some options are designated as arrays, which means that more than one 1641value is allowed. For example, the option ``time-servers`` 1642allows the specification of more than one IPv4 address, enabling clients 1643to obtain the addresses of multiple NTP servers. 1644 1645:ref:`dhcp4-custom-options` describes the 1646configuration syntax to create custom option definitions (formats). 1647Creation of custom definitions for standard options is generally not 1648permitted, even if the definition being created matches the actual 1649option format defined in the RFCs. There is an exception to this rule 1650for standard options for which Kea currently does not provide a 1651definition. To use such options, a server administrator must 1652create a definition as described in 1653:ref:`dhcp4-custom-options` in the "dhcp4" option space. This 1654definition should match the option format described in the relevant RFC, 1655but the configuration mechanism will allow any option format as it 1656currently has no means to validate it. 1657 1658.. _dhcp4-std-options-list: 1659 1660.. table:: List of Standard DHCPv4 Options Configurable by an Administrator 1661 1662 +----------------------------------------+------+---------------------------+-------------+-------------+ 1663 | Name | Code | Type | Array? | Returned if | 1664 | | | | | not | 1665 | | | | | requested? | 1666 +========================================+======+===========================+=============+=============+ 1667 | time-offset | 2 | int32 | false | false | 1668 +----------------------------------------+------+---------------------------+-------------+-------------+ 1669 | routers | 3 | ipv4-address | true | true | 1670 +----------------------------------------+------+---------------------------+-------------+-------------+ 1671 | time-servers | 4 | ipv4-address | true | false | 1672 +----------------------------------------+------+---------------------------+-------------+-------------+ 1673 | name-servers | 5 | ipv4-address | true | false | 1674 +----------------------------------------+------+---------------------------+-------------+-------------+ 1675 | domain-name-servers | 6 | ipv4-address | true | true | 1676 +----------------------------------------+------+---------------------------+-------------+-------------+ 1677 | log-servers | 7 | ipv4-address | true | false | 1678 +----------------------------------------+------+---------------------------+-------------+-------------+ 1679 | cookie-servers | 8 | ipv4-address | true | false | 1680 +----------------------------------------+------+---------------------------+-------------+-------------+ 1681 | lpr-servers | 9 | ipv4-address | true | false | 1682 +----------------------------------------+------+---------------------------+-------------+-------------+ 1683 | impress-servers | 10 | ipv4-address | true | false | 1684 +----------------------------------------+------+---------------------------+-------------+-------------+ 1685 | resource-location-servers | 11 | ipv4-address | true | false | 1686 +----------------------------------------+------+---------------------------+-------------+-------------+ 1687 | boot-size | 13 | uint16 | false | false | 1688 +----------------------------------------+------+---------------------------+-------------+-------------+ 1689 | merit-dump | 14 | string | false | false | 1690 +----------------------------------------+------+---------------------------+-------------+-------------+ 1691 | domain-name | 15 | fqdn | false | true | 1692 +----------------------------------------+------+---------------------------+-------------+-------------+ 1693 | swap-server | 16 | ipv4-address | false | false | 1694 +----------------------------------------+------+---------------------------+-------------+-------------+ 1695 | root-path | 17 | string | false | false | 1696 +----------------------------------------+------+---------------------------+-------------+-------------+ 1697 | extensions-path | 18 | string | false | false | 1698 +----------------------------------------+------+---------------------------+-------------+-------------+ 1699 | ip-forwarding | 19 | boolean | false | false | 1700 +----------------------------------------+------+---------------------------+-------------+-------------+ 1701 | non-local-source-routing | 20 | boolean | false | false | 1702 +----------------------------------------+------+---------------------------+-------------+-------------+ 1703 | policy-filter | 21 | ipv4-address | true | false | 1704 +----------------------------------------+------+---------------------------+-------------+-------------+ 1705 | max-dgram-reassembly | 22 | uint16 | false | false | 1706 +----------------------------------------+------+---------------------------+-------------+-------------+ 1707 | default-ip-ttl | 23 | uint8 | false | false | 1708 +----------------------------------------+------+---------------------------+-------------+-------------+ 1709 | path-mtu-aging-timeout | 24 | uint32 | false | false | 1710 +----------------------------------------+------+---------------------------+-------------+-------------+ 1711 | path-mtu-plateau-table | 25 | uint16 | true | false | 1712 +----------------------------------------+------+---------------------------+-------------+-------------+ 1713 | interface-mtu | 26 | uint16 | false | false | 1714 +----------------------------------------+------+---------------------------+-------------+-------------+ 1715 | all-subnets-local | 27 | boolean | false | false | 1716 +----------------------------------------+------+---------------------------+-------------+-------------+ 1717 | broadcast-address | 28 | ipv4-address | false | false | 1718 +----------------------------------------+------+---------------------------+-------------+-------------+ 1719 | perform-mask-discovery | 29 | boolean | false | false | 1720 +----------------------------------------+------+---------------------------+-------------+-------------+ 1721 | mask-supplier | 30 | boolean | false | false | 1722 +----------------------------------------+------+---------------------------+-------------+-------------+ 1723 | router-discovery | 31 | boolean | false | false | 1724 +----------------------------------------+------+---------------------------+-------------+-------------+ 1725 | router-solicitation-address | 32 | ipv4-address | false | false | 1726 +----------------------------------------+------+---------------------------+-------------+-------------+ 1727 | static-routes | 33 | ipv4-address | true | false | 1728 +----------------------------------------+------+---------------------------+-------------+-------------+ 1729 | trailer-encapsulation | 34 | boolean | false | false | 1730 +----------------------------------------+------+---------------------------+-------------+-------------+ 1731 | arp-cache-timeout | 35 | uint32 | false | false | 1732 +----------------------------------------+------+---------------------------+-------------+-------------+ 1733 | ieee802-3-encapsulation | 36 | boolean | false | false | 1734 +----------------------------------------+------+---------------------------+-------------+-------------+ 1735 | default-tcp-ttl | 37 | uint8 | false | false | 1736 +----------------------------------------+------+---------------------------+-------------+-------------+ 1737 | tcp-keepalive-interval | 38 | uint32 | false | false | 1738 +----------------------------------------+------+---------------------------+-------------+-------------+ 1739 | tcp-keepalive-garbage | 39 | boolean | false | false | 1740 +----------------------------------------+------+---------------------------+-------------+-------------+ 1741 | nis-domain | 40 | string | false | false | 1742 +----------------------------------------+------+---------------------------+-------------+-------------+ 1743 | nis-servers | 41 | ipv4-address | true | false | 1744 +----------------------------------------+------+---------------------------+-------------+-------------+ 1745 | ntp-servers | 42 | ipv4-address | true | false | 1746 +----------------------------------------+------+---------------------------+-------------+-------------+ 1747 | vendor-encapsulated-options | 43 | empty | false | false | 1748 +----------------------------------------+------+---------------------------+-------------+-------------+ 1749 | netbios-name-servers | 44 | ipv4-address | true | false | 1750 +----------------------------------------+------+---------------------------+-------------+-------------+ 1751 | netbios-dd-server | 45 | ipv4-address | true | false | 1752 +----------------------------------------+------+---------------------------+-------------+-------------+ 1753 | netbios-node-type | 46 | uint8 | false | false | 1754 +----------------------------------------+------+---------------------------+-------------+-------------+ 1755 | netbios-scope | 47 | string | false | false | 1756 +----------------------------------------+------+---------------------------+-------------+-------------+ 1757 | font-servers | 48 | ipv4-address | true | false | 1758 +----------------------------------------+------+---------------------------+-------------+-------------+ 1759 | x-display-manager | 49 | ipv4-address | true | false | 1760 +----------------------------------------+------+---------------------------+-------------+-------------+ 1761 | dhcp-option-overload | 52 | uint8 | false | false | 1762 +----------------------------------------+------+---------------------------+-------------+-------------+ 1763 | dhcp-server-identifier | 54 | ipv4-address | false | true | 1764 +----------------------------------------+------+---------------------------+-------------+-------------+ 1765 | dhcp-message | 56 | string | false | false | 1766 +----------------------------------------+------+---------------------------+-------------+-------------+ 1767 | dhcp-max-message-size | 57 | uint16 | false | false | 1768 +----------------------------------------+------+---------------------------+-------------+-------------+ 1769 | vendor-class-identifier | 60 | string | false | false | 1770 +----------------------------------------+------+---------------------------+-------------+-------------+ 1771 | nwip-domain-name | 62 | string | false | false | 1772 +----------------------------------------+------+---------------------------+-------------+-------------+ 1773 | nwip-suboptions | 63 | binary | false | false | 1774 +----------------------------------------+------+---------------------------+-------------+-------------+ 1775 | nisplus-domain-name | 64 | string | false | false | 1776 +----------------------------------------+------+---------------------------+-------------+-------------+ 1777 | nisplus-servers | 65 | ipv4-address | true | false | 1778 +----------------------------------------+------+---------------------------+-------------+-------------+ 1779 | tftp-server-name | 66 | string | false | false | 1780 +----------------------------------------+------+---------------------------+-------------+-------------+ 1781 | boot-file-name | 67 | string | false | false | 1782 +----------------------------------------+------+---------------------------+-------------+-------------+ 1783 | mobile-ip-home-agent | 68 | ipv4-address | true | false | 1784 +----------------------------------------+------+---------------------------+-------------+-------------+ 1785 | smtp-server | 69 | ipv4-address | true | false | 1786 +----------------------------------------+------+---------------------------+-------------+-------------+ 1787 | pop-server | 70 | ipv4-address | true | false | 1788 +----------------------------------------+------+---------------------------+-------------+-------------+ 1789 | nntp-server | 71 | ipv4-address | true | false | 1790 +----------------------------------------+------+---------------------------+-------------+-------------+ 1791 | www-server | 72 | ipv4-address | true | false | 1792 +----------------------------------------+------+---------------------------+-------------+-------------+ 1793 | finger-server | 73 | ipv4-address | true | false | 1794 +----------------------------------------+------+---------------------------+-------------+-------------+ 1795 | irc-server | 74 | ipv4-address | true | false | 1796 +----------------------------------------+------+---------------------------+-------------+-------------+ 1797 | streettalk-server | 75 | ipv4-address | true | false | 1798 +----------------------------------------+------+---------------------------+-------------+-------------+ 1799 | streettalk-directory-assistance-server | 76 | ipv4-address | true | false | 1800 +----------------------------------------+------+---------------------------+-------------+-------------+ 1801 | user-class | 77 | binary | false | false | 1802 +----------------------------------------+------+---------------------------+-------------+-------------+ 1803 | slp-directory-agent | 78 | record (boolean, | true | false | 1804 | | | ipv4-address) | | | 1805 +----------------------------------------+------+---------------------------+-------------+-------------+ 1806 | slp-service-scope | 79 | record (boolean, string) | false | false | 1807 +----------------------------------------+------+---------------------------+-------------+-------------+ 1808 | nds-server | 85 | ipv4-address | true | false | 1809 +----------------------------------------+------+---------------------------+-------------+-------------+ 1810 | nds-tree-name | 86 | string | false | false | 1811 +----------------------------------------+------+---------------------------+-------------+-------------+ 1812 | nds-context | 87 | string | false | false | 1813 +----------------------------------------+------+---------------------------+-------------+-------------+ 1814 | bcms-controller-names | 88 | fqdn | true | false | 1815 +----------------------------------------+------+---------------------------+-------------+-------------+ 1816 | bcms-controller-address | 89 | ipv4-address | true | false | 1817 +----------------------------------------+------+---------------------------+-------------+-------------+ 1818 | client-system | 93 | uint16 | true | false | 1819 +----------------------------------------+------+---------------------------+-------------+-------------+ 1820 | client-ndi | 94 | record (uint8, uint8, | false | false | 1821 | | | uint8) | | | 1822 +----------------------------------------+------+---------------------------+-------------+-------------+ 1823 | uuid-guid | 97 | record (uint8, binary) | false | false | 1824 +----------------------------------------+------+---------------------------+-------------+-------------+ 1825 | uap-servers | 98 | string | false | false | 1826 +----------------------------------------+------+---------------------------+-------------+-------------+ 1827 | geoconf-civic | 99 | binary | false | false | 1828 +----------------------------------------+------+---------------------------+-------------+-------------+ 1829 | pcode | 100 | string | false | false | 1830 +----------------------------------------+------+---------------------------+-------------+-------------+ 1831 | tcode | 101 | string | false | false | 1832 +----------------------------------------+------+---------------------------+-------------+-------------+ 1833 | v6-only-preferred | 108 | uint32 | false | false | 1834 +----------------------------------------+------+---------------------------+-------------+-------------+ 1835 | netinfo-server-address | 112 | ipv4-address | true | false | 1836 +----------------------------------------+------+---------------------------+-------------+-------------+ 1837 | netinfo-server-tag | 113 | string | false | false | 1838 +----------------------------------------+------+---------------------------+-------------+-------------+ 1839 | default-url | 114 | string | false | false | 1840 +----------------------------------------+------+---------------------------+-------------+-------------+ 1841 | auto-config | 116 | uint8 | false | false | 1842 +----------------------------------------+------+---------------------------+-------------+-------------+ 1843 | name-service-search | 117 | uint16 | true | false | 1844 +----------------------------------------+------+---------------------------+-------------+-------------+ 1845 | domain-search | 119 | fqdn | true | false | 1846 +----------------------------------------+------+---------------------------+-------------+-------------+ 1847 | vivco-suboptions | 124 | record (uint32, binary) | false | false | 1848 +----------------------------------------+------+---------------------------+-------------+-------------+ 1849 | vivso-suboptions | 125 | uint32 | false | false | 1850 +----------------------------------------+------+---------------------------+-------------+-------------+ 1851 | pana-agent | 136 | ipv4-address | true | false | 1852 +----------------------------------------+------+---------------------------+-------------+-------------+ 1853 | v4-lost | 137 | fqdn | false | false | 1854 +----------------------------------------+------+---------------------------+-------------+-------------+ 1855 | capwap-ac-v4 | 138 | ipv4-address | true | false | 1856 +----------------------------------------+------+---------------------------+-------------+-------------+ 1857 | sip-ua-cs-domains | 141 | fqdn | true | false | 1858 +----------------------------------------+------+---------------------------+-------------+-------------+ 1859 | rdnss-selection | 146 | record (uint8, | true | false | 1860 | | | ipv4-address, | | | 1861 | | | ipv4-address, fqdn) | | | 1862 +----------------------------------------+------+---------------------------+-------------+-------------+ 1863 | v4-portparams | 159 | record (uint8, psid) | false | false | 1864 +----------------------------------------+------+---------------------------+-------------+-------------+ 1865 | v4-captive-portal | 160 | string | false | false | 1866 +----------------------------------------+------+---------------------------+-------------+-------------+ 1867 | option-6rd | 212 | record (uint8, uint8, | true | false | 1868 | | | ipv6-address, | | | 1869 | | | ipv4-address) | | | 1870 +----------------------------------------+------+---------------------------+-------------+-------------+ 1871 | v4-access-domain | 213 | fqdn | false | false | 1872 +----------------------------------------+------+---------------------------+-------------+-------------+ 1873 1874Kea also supports other options than those listed above; the following options 1875are returned by the Kea engine itself and in general should not be configured 1876manually. 1877 1878.. table:: List of Standard DHCPv4 Options Managed by Kea on Its Own and Not Directly Configurable by an Administrator 1879 1880 +--------------------------------+-------+---------------------------------------+-------------------------------------------------------------------+ 1881 | Name | Code | Type | Description | 1882 +================================+=======+=======================================+===================================================================+ 1883 | subnet-mask | 1 | ipv4-address | calculated automatically, based on subnet definition. | 1884 +--------------------------------+-------+---------------------------------------+-------------------------------------------------------------------+ 1885 | host-name | 12 | string | sent by client, generally governed by the DNS configuration. | 1886 +--------------------------------+-------+---------------------------------------+-------------------------------------------------------------------+ 1887 | dhcp-requested-address | 50 | ipv6-address | may be sent by the client and the server should not set it. | 1888 +--------------------------------+-------+---------------------------------------+-------------------------------------------------------------------+ 1889 | dhcp-lease-time | 51 | uint32 | set automatically based on the ``valid-lifetime`` parameter. | 1890 +--------------------------------+-------+---------------------------------------+-------------------------------------------------------------------+ 1891 | dhcp-message-type | 53 | string | sent by clients and servers. Set by the Kea engine depending on | 1892 | | | | the situation and should never be configured explicitly. | 1893 +--------------------------------+-------+---------------------------------------+-------------------------------------------------------------------+ 1894 | dhcp-parameter-request-list | 55 | uint8 array | sent by clients and should never be sent by the server. | 1895 +--------------------------------+-------+---------------------------------------+-------------------------------------------------------------------+ 1896 | dhcp-renewal-time | 58 | uint32 | governed by ``renew-timer`` parameter. | 1897 +--------------------------------+-------+---------------------------------------+-------------------------------------------------------------------+ 1898 | dhcp-rebinding-time | 59 | uint32 | governed by ``rebind-timer`` parameter. | 1899 +--------------------------------+-------+---------------------------------------+-------------------------------------------------------------------+ 1900 | dhcp-client-identifier | 61 | binary | sent by client, echoed back with the value sent by the client. | 1901 +--------------------------------+-------+---------------------------------------+-------------------------------------------------------------------+ 1902 | fqdn | 81 | record (uint8, uint8, uint8, fqdn) | part of the DDNS and D2 configuration. | 1903 +--------------------------------+-------+---------------------------------------+-------------------------------------------------------------------+ 1904 | dhcp-agent-options | 82 | empty | sent by the relay agent. This is an empty container option; see | 1905 | | | | RAI option detail in later part of this section. | 1906 +--------------------------------+-------+---------------------------------------+-------------------------------------------------------------------+ 1907 | authenticate | 90 | binary | sent by client, kea does not validate it yet. | 1908 +--------------------------------+-------+---------------------------------------+-------------------------------------------------------------------+ 1909 | client-last-transaction-time | 91 | uint32 | sent by client, server does not set it. | 1910 +--------------------------------+-------+---------------------------------------+-------------------------------------------------------------------+ 1911 | associated-ip | 92 | ipv4-address array | sent by client, server responds with list of addresses. | 1912 +--------------------------------+-------+---------------------------------------+-------------------------------------------------------------------+ 1913 | subnet-selection | 118 | ipv4-address | if present in client's messages, will be used in the subnet | 1914 | | | | selection process. | 1915 +--------------------------------+-------+---------------------------------------+-------------------------------------------------------------------+ 1916 1917The following table lists all option types used in the previous two tables with a description of 1918what values are accepted for them. 1919 1920.. _dhcp-types: 1921 1922.. table:: List of Standard DHCP Option Types 1923 1924 +-----------------+-------------------------------------------------------+ 1925 | Name | Meaning | 1926 +=================+=======================================================+ 1927 | binary | An arbitrary string of bytes, specified as a set | 1928 | | of hexadecimal digits. | 1929 +-----------------+-------------------------------------------------------+ 1930 | boolean | A boolean value with allowed | 1931 | | values true or false. | 1932 +-----------------+-------------------------------------------------------+ 1933 | empty | No value; data is carried in | 1934 | | sub-options. | 1935 +-----------------+-------------------------------------------------------+ 1936 | fqdn | Fully qualified domain name (e.g. | 1937 | | www.example.com). | 1938 +-----------------+-------------------------------------------------------+ 1939 | ipv4-address | IPv4 address in the usual | 1940 | | dotted-decimal notation (e.g. | 1941 | | 192.0.2.1). | 1942 +-----------------+-------------------------------------------------------+ 1943 | ipv6-address | IPv6 address in the usual colon | 1944 | | notation (e.g. 2001:db8::1). | 1945 +-----------------+-------------------------------------------------------+ 1946 | ipv6-prefix | IPv6 prefix and prefix length | 1947 | | specified using CIDR notation, | 1948 | | e.g. 2001:db8:1::/64. This data | 1949 | | type is used to represent an | 1950 | | 8-bit field conveying a prefix | 1951 | | length and the variable length | 1952 | | prefix value. | 1953 +-----------------+-------------------------------------------------------+ 1954 | psid | PSID and PSID length separated by | 1955 | | a slash, e.g. 3/4 specifies | 1956 | | PSID=3 and PSID length=4. In the | 1957 | | wire format it is represented by | 1958 | | an 8-bit field carrying PSID | 1959 | | length (in this case equal to 4) | 1960 | | and the 16-bits-long PSID value | 1961 | | field (in this case equal to | 1962 | | "0011000000000000b" using binary | 1963 | | notation). Allowed values for a | 1964 | | PSID length are 0 to 16. See `RFC | 1965 | | 7597 <https://tools.ietf.org/html/rfc7597>`__ | 1966 | | for details about the PSID wire | 1967 | | representation. | 1968 +-----------------+-------------------------------------------------------+ 1969 | record | Structured data that may be | 1970 | | comprised of any types (except | 1971 | | "record" and "empty"). The array | 1972 | | flag applies to the last field | 1973 | | only. | 1974 +-----------------+-------------------------------------------------------+ 1975 | string | Any text. Please note that Kea | 1976 | | silently discards any | 1977 | | terminating/trailing nulls from | 1978 | | the end of 'string' options when | 1979 | | unpacking received packets. This | 1980 | | is in keeping with `RFC 2132, | 1981 | | Section | 1982 | | 2 <https://tools.ietf.org/html/rfc2132#section-2>`__. | 1983 +-----------------+-------------------------------------------------------+ 1984 | tuple | A length encoded as an 8- (16- | 1985 | | for DHCPv6) bit unsigned integer | 1986 | | followed by a string of this | 1987 | | length. | 1988 +-----------------+-------------------------------------------------------+ 1989 | uint8 | 8-bit unsigned integer with | 1990 | | allowed values 0 to 255. | 1991 +-----------------+-------------------------------------------------------+ 1992 | uint16 | 16-bit unsigned integer with | 1993 | | allowed values 0 to 65535. | 1994 +-----------------+-------------------------------------------------------+ 1995 | uint32 | 32-bit unsigned integer with | 1996 | | allowed values 0 to 4294967295. | 1997 +-----------------+-------------------------------------------------------+ 1998 | int8 | 8-bit signed integer with allowed | 1999 | | values -128 to 127. | 2000 +-----------------+-------------------------------------------------------+ 2001 | int16 | 16-bit signed integer with | 2002 | | allowed values -32768 to 32767. | 2003 +-----------------+-------------------------------------------------------+ 2004 | int32 | 32-bit signed integer with | 2005 | | allowed values -2147483648 to | 2006 | | 2147483647. | 2007 +-----------------+-------------------------------------------------------+ 2008 2009Kea also supports the Relay Agent Information (RAI) option, sometimes referred to as the relay option, agent 2010option, or simply option 82. The option itself is just a container and does not convey any information 2011on its own. The following table contains a list of RAI sub-options that Kea can understand. The RAI 2012and its sub-options are inserted by the relay agent and received by Kea; there is no need for Kea 2013to be configured with those options. 2014 2015.. table:: List of RAI Sub-options That Kea Can Understand. 2016 2017 +--------------------+------+----------------------------------------------------------------------+ 2018 | Name | Code | Comment | 2019 +====================+======+======================================================================+ 2020 | circuit-id | 1 | Used when host-reservation-identifiers is set to `circuit-id`. | 2021 +--------------------+------+----------------------------------------------------------------------+ 2022 | remote-id | 2 | Can be used with flex-id to identify hosts. | 2023 +--------------------+------+----------------------------------------------------------------------+ 2024 | link selection | 5 | If present, is used to select the appropriate subnet. | 2025 +--------------------+------+----------------------------------------------------------------------+ 2026 | subscriber-id | 6 | Can be used with flex-id to identify hosts. | 2027 +--------------------+------+----------------------------------------------------------------------+ 2028 | relay-source-port | 19 | If sent by the relay, Kea sends back its responses to this port. | 2029 +--------------------+------+----------------------------------------------------------------------+ 2030 2031All other RAI sub-options can be used in client classification to classify incoming packets to specific classes 2032and/or by flex-id to construct a unique device identifier. 2033 2034.. _dhcp4-custom-options: 2035 2036Custom DHCPv4 Options 2037--------------------- 2038 2039Kea supports custom (non-standard) DHCPv4 options. Let's say that we want 2040to define a new DHCPv4 option called "foo", which will have code 222 2041and will convey a single, unsigned, 32-bit integer value. We can define 2042such an option by putting the following entry in the configuration file: 2043 2044:: 2045 2046 "Dhcp4": { 2047 "option-def": [ 2048 { 2049 "name": "foo", 2050 "code": 222, 2051 "type": "uint32", 2052 "array": false, 2053 "record-types": "", 2054 "space": "dhcp4", 2055 "encapsulate": "" 2056 }, ... 2057 ], 2058 ... 2059 } 2060 2061The ``false`` value of the ``array`` parameter determines that the 2062option does NOT comprise an array of "uint32" values but is, instead, a 2063single value. Two other parameters have been left blank: 2064``record-types`` and ``encapsulate``. The former specifies the 2065comma-separated list of option data fields, if the option comprises a 2066record of data fields. The ``record-types`` value should be non-empty if 2067``type`` is set to "record"; otherwise it must be left blank. The latter 2068parameter specifies the name of the option space being encapsulated by 2069the particular option. If the particular option does not encapsulate any 2070option space, the parameter should be left blank. Note that the ``option-def`` 2071configuration statement only defines the format of an option and does 2072not set its value(s). 2073 2074The ``name``, ``code``, and ``type`` parameters are required; all others 2075are optional. The ``array`` default value is ``false``. The 2076``record-types`` and ``encapsulate`` default values are blank (``""``). 2077The default ``space`` is "dhcp4". 2078 2079Once the new option format is defined, its value is set in the same way 2080as for a standard option. For example, the following commands set a 2081global value that applies to all subnets. 2082 2083:: 2084 2085 "Dhcp4": { 2086 "option-data": [ 2087 { 2088 "name": "foo", 2089 "code": 222, 2090 "space": "dhcp4", 2091 "csv-format": true, 2092 "data": "12345" 2093 }, ... 2094 ], 2095 ... 2096 } 2097 2098New options can take more complex forms than the simple use of primitives 2099(uint8, string, ipv4-address, etc.); it is possible to define an option 2100comprising a number of existing primitives. 2101 2102For example, say we want to define a new option that will consist of 2103an IPv4 address, followed by an unsigned 16-bit integer, followed by a 2104boolean value, followed by a text string. Such an option could be 2105defined in the following way: 2106 2107:: 2108 2109 "Dhcp4": { 2110 "option-def": [ 2111 { 2112 "name": "bar", 2113 "code": 223, 2114 "space": "dhcp4", 2115 "type": "record", 2116 "array": false, 2117 "record-types": "ipv4-address, uint16, boolean, string", 2118 "encapsulate": "" 2119 }, ... 2120 ], 2121 ... 2122 } 2123 2124The ``type`` is set to "record" to indicate that the option contains 2125multiple values of different types. These types are given as a 2126comma-separated list in the ``record-types`` field and should be ones 2127from those listed in :ref:`dhcp-types`. 2128 2129The values of the option are set in an ``option-data`` statement as follows: 2130 2131:: 2132 2133 "Dhcp4": { 2134 "option-data": [ 2135 { 2136 "name": "bar", 2137 "space": "dhcp4", 2138 "code": 223, 2139 "csv-format": true, 2140 "data": "192.0.2.100, 123, true, Hello World" 2141 } 2142 ], 2143 ... 2144 } 2145 2146``csv-format`` is set to ``true`` to indicate that the ``data`` field 2147comprises a comma-separated list of values. The values in ``data`` 2148must correspond to the types set in the ``record-types`` field of the 2149option definition. 2150 2151When ``array`` is set to ``true`` and ``type`` is set to "record", the 2152last field is an array, i.e. it can contain more than one value, as in: 2153 2154:: 2155 2156 "Dhcp4": { 2157 "option-def": [ 2158 { 2159 "name": "bar", 2160 "code": 223, 2161 "space": "dhcp4", 2162 "type": "record", 2163 "array": true, 2164 "record-types": "ipv4-address, uint16", 2165 "encapsulate": "" 2166 }, ... 2167 ], 2168 ... 2169 } 2170 2171The new option content is one IPv4 address followed by one or more 16- 2172bit unsigned integers. 2173 2174.. note:: 2175 2176 In general, boolean values are specified as ``true`` or ``false``, 2177 without quotes. Some specific boolean parameters may also accept 2178 ``"true"``, ``"false"``, ``0``, ``1``, ``"0"``, and ``"1"``. 2179 2180.. note:: 2181 2182 Numbers can be specified in decimal or hexadecimal format. The 2183 hexadecimal format can be either plain (e.g. abcd) or prefixed with 2184 0x (e.g. 0xabcd). 2185 2186.. _dhcp4-private-opts: 2187 2188DHCPv4 Private Options 2189---------------------- 2190 2191Options with a code between 224 and 254 are reserved for private use. 2192They can be defined at the global scope or at the client-class local 2193scope; this allows option definitions to be used depending on context, 2194and option data to be set accordingly. For instance, to configure an old 2195PXEClient vendor: 2196 2197:: 2198 2199 "Dhcp4": { 2200 "client-classes": [ 2201 { 2202 "name": "pxeclient", 2203 "test": "option[vendor-class-identifier].text == 'PXEClient'", 2204 "option-def": [ 2205 { 2206 "name": "configfile", 2207 "code": 209, 2208 "type": "string" 2209 } 2210 ], 2211 ... 2212 }, ... 2213 ], 2214 ... 2215 } 2216 2217As the Vendor-Specific Information (VSI) option (code 43) has vendor-specific 2218format, i.e. can carry either raw binary value or sub-options, this 2219mechanism is also available for this option. 2220 2221In the following example taken from a real configuration, two vendor 2222classes use option 43 for different and incompatible purposes: 2223 2224:: 2225 2226 "Dhcp4": { 2227 "option-def": [ 2228 { 2229 "name": "cookie", 2230 "code": 1, 2231 "type": "string", 2232 "space": "APC" 2233 }, 2234 { 2235 "name": "mtftp-ip", 2236 "code": 1, 2237 "type": "ipv4-address", 2238 "space": "PXE" 2239 }, 2240 ... 2241 ], 2242 "client-classes": [ 2243 { 2244 "name": "APC", 2245 "test": "option[vendor-class-identifier].text == 'APC'", 2246 "option-def": [ 2247 { 2248 "name": "vendor-encapsulated-options", 2249 "type": "empty", 2250 "encapsulate": "APC" 2251 } 2252 ], 2253 "option-data": [ 2254 { 2255 "name": "cookie", 2256 "space": "APC", 2257 "data": "1APC" 2258 }, 2259 { 2260 "name": "vendor-encapsulated-options" 2261 }, 2262 ... 2263 ], 2264 ... 2265 }, 2266 { 2267 "name": "PXE", 2268 "test": "option[vendor-class-identifier].text == 'PXE'", 2269 "option-def": [ 2270 { 2271 "name": "vendor-encapsulated-options", 2272 "type": "empty", 2273 "encapsulate": "PXE" 2274 } 2275 ], 2276 "option-data": [ 2277 { 2278 "name": "mtftp-ip", 2279 "space": "PXE", 2280 "data": "0.0.0.0" 2281 }, 2282 { 2283 "name": "vendor-encapsulated-options" 2284 }, 2285 ... 2286 ], 2287 ... 2288 }, 2289 ... 2290 ], 2291 ... 2292 } 2293 2294The definition used to decode a VSI option is: 2295 22961. The local definition of a client class the incoming packet belongs 2297 to; 2298 22992. If none, the global definition; 2300 23013. If none, the last-resort definition described in the next section, 2302 :ref:`dhcp4-vendor-opts` (backward-compatible with previous Kea versions). 2303 2304.. note:: 2305 2306 This last-resort definition for the Vendor-Specific Information 2307 option (code 43) is not compatible with a raw binary value. When 2308 there are known cases where a raw binary value will be used, a 2309 client class must be defined with both a classification expression 2310 matching these cases and an option definition for the VSI option with 2311 a binary type and no encapsulation. 2312 2313.. note:: 2314 2315 By default, in the Vendor-Specific Information option (code 43), 2316 sub-option code 0 and 255 mean PAD and END respectively, according to 2317 `RFC 2132 <https://tools.ietf.org/html/rfc2132>`_. In other words, the 2318 sub-option code values of 0 and 255 are reserved. Kea does, however, 2319 allow users to define sub-option codes from 0 to 255. If 2320 sub-options with codes 0 and/or 255 are defined, bytes with that value are 2321 no longer treated as a PAD or an END, but as the sub-option code 2322 when parsing a VSI option in an incoming query. 2323 2324 Option 43 input processing (also called unpacking) is deferred so that it 2325 happens after classification. This means clients cannot be classified 2326 using option 43 sub-options. The definition used to unpack option 43 2327 is determined as follows: 2328 2329 - If defined at the global scope, this definition is used. 2330 - If defined at client class scope and the packet belongs to this 2331 class, the client class definition is used. 2332 - If not defined at global scope nor in a client class to which the 2333 packet belongs, the built-in last resort definition is used. This 2334 definition only says the sub-option space is 2335 "vendor-encapsulated-options-space". 2336 2337 The output definition selection is a bit simpler: 2338 2339 - If the packet belongs to a client class which defines the option 2340 43, use this definition. 2341 - If defined at the global scope, use this definition. 2342 - Otherwise, use the built-in last-resort definition. 2343 2344 Since they use a specific/per vendor option space, sub-options 2345 are defined at the global scope. 2346 2347.. note:: 2348 2349 Option definitions in client classes are allowed only for this 2350 limited option set (codes 43 and from 224 to 254), and only for 2351 DHCPv4. 2352 2353.. _dhcp4-vendor-opts: 2354 2355DHCPv4 Vendor-Specific Options 2356------------------------------ 2357 2358Currently there are two option spaces defined for the DHCPv4 daemon: 2359"dhcp4" (for the top-level DHCPv4 options) and 2360"vendor-encapsulated-options-space", which is empty by default but in 2361which options can be defined. Those options are carried in the 2362Vendor-Specific Information option (code 43). The following examples 2363show how to define an option "foo" with code 1 that 2364comprises an IPv4 address, an unsigned 16-bit integer, and a string. The 2365"foo" option is conveyed in a Vendor-Specific Information option. 2366 2367The first step is to define the format of the option: 2368 2369:: 2370 2371 "Dhcp4": { 2372 "option-def": [ 2373 { 2374 "name": "foo", 2375 "code": 1, 2376 "space": "vendor-encapsulated-options-space", 2377 "type": "record", 2378 "array": false, 2379 "record-types": "ipv4-address, uint16, string", 2380 "encapsulate": "" 2381 } 2382 ], 2383 ... 2384 } 2385 2386(Note that the option space is set to 2387``vendor-encapsulated-options-space``.) Once the option format is defined, 2388the next step is to define actual values for that option: 2389 2390:: 2391 2392 "Dhcp4": { 2393 "option-data": [ 2394 { 2395 "name": "foo", 2396 "space": "vendor-encapsulated-options-space", 2397 "code": 1, 2398 "csv-format": true, 2399 "data": "192.0.2.3, 123, Hello World" 2400 } 2401 ], 2402 ... 2403 } 2404 2405In this example, we also include the Vendor-Specific Information option, which 2406conveys our sub-option "foo". This is required; otherwise, the option 2407will not be included in messages sent to the client. 2408 2409:: 2410 2411 "Dhcp4": { 2412 "option-data": [ 2413 { 2414 "name": "vendor-encapsulated-options" 2415 } 2416 ], 2417 ... 2418 } 2419 2420Alternatively, the option can be specified using its code. 2421 2422:: 2423 2424 "Dhcp4": { 2425 "option-data": [ 2426 { 2427 "code": 43 2428 } 2429 ], 2430 ... 2431 } 2432 2433Another popular option that is often somewhat imprecisely called the "vendor 2434option" is option 125. Its proper name is the "vendor-independent 2435vendor-specific information option" or "vivso". The idea behind vivso 2436options is that each vendor has its own unique set of options with their 2437own custom formats. The vendor is identified by a 32-bit unsigned integer 2438called `enterprise-id` or `vendor-id`. For example, vivso with vendor-id 24394491 represents DOCSIS options, and they are often seen 2440when dealing with cable modems. 2441 2442In Kea each vendor is represented by its own vendor space. Since there 2443are hundreds of vendors and sometimes they use different option 2444definitions for different hardware, it is impossible for Kea to support 2445them all natively. Fortunately, it's easy to define support for 2446new vendor options. Let's take an example of the Genexis home gateway. This 2447device requires sending the vivso 125 option with a sub-option 2 that 2448contains a string with the TFTP server URL. To support such a device, three 2449steps are needed: first, we need to define option definitions that will 2450explain how the option is supposed to be formed. Second, we need to 2451define option values. Third, we need to tell Kea when to send those 2452specific options, which we can do via client classification. 2453 2454An example snippet of a configuration could look similar to the 2455following: 2456 2457:: 2458 2459 { 2460 // First, we need to define that the suboption 2 in vivso option for 2461 // vendor-id 25167 has a specific format (it's a plain string in this example). 2462 // After this definition, we can specify values for option tftp. 2463 "option-def": [ 2464 { 2465 // We define a short name, so the option can be referenced by name. 2466 // The option has code 2 and resides within vendor space 25167. 2467 // Its data is a plain string. 2468 "name": "tftp", 2469 "code": 2, 2470 "space": "vendor-25167", 2471 "type": "string" 2472 } ], 2473 2474 "client-classes": [ 2475 { 2476 // We now need to tell Kea how to recognize when to use vendor space 25167. 2477 // Usually we can use a simple expression, such as checking if the device 2478 // sent a vivso option with specific vendor-id, e.g. "vendor[4491].exists". 2479 // Unfortunately, Genexis is a bit unusual in this aspect, because it 2480 // doesn't send vivso. In this case we need to look into the vendor class 2481 // (option code 60) and see if there's a specific string that identifies 2482 // the device. 2483 "name": "cpe_genexis", 2484 "test": "substring(option[60].hex,0,7) == 'HMC1000'", 2485 2486 // Once the device is recognized, we want to send two options: 2487 // the vivso option with vendor-id set to 25167, and a suboption 2. 2488 "option-data": [ 2489 { 2490 "name": "vivso-suboptions", 2491 "data": "25167" 2492 }, 2493 2494 // The suboption 2 value is defined as any other option. However, 2495 // we want to send this suboption 2, even when the client didn't 2496 // explicitly request it (often there is no way to do that for 2497 // vendor options). Therefore we use always-send to force Kea 2498 // to always send this option when 25167 vendor space is involved. 2499 { 2500 "name": "tftp", 2501 "space": "vendor-25167", 2502 "data": "tftp://192.0.2.1/genexis/HMC1000.v1.3.0-R.img", 2503 "always-send": true 2504 } 2505 ] 2506 } ] 2507 } 2508 2509By default Kea sends back 2510only those options that are requested by a client, unless there are 2511protocol rules that tell the DHCP server to always send an option. This 2512approach works nicely in most cases and avoids problems with clients 2513refusing responses with options they don't understand. Unfortunately, 2514this is more complex when we consider vendor options. Some vendors (such 2515as DOCSIS, identified by vendor option 4491) have a mechanism to 2516request specific vendor options and Kea is able to honor those. 2517Unfortunately, for many other vendors, such as Genexis (25167) as discussed 2518above, Kea does not have such a mechanism, so it cannot send any 2519sub-options on its own. To solve this issue, we came up with the concept of 2520persistent options. Kea can be told to always send options, even if the 2521client did not request them. This can be achieved by adding 2522``"always-send": true`` to the option definition. Note that in this 2523particular case an option is defined in vendor space 25167. With 2524``always-send`` enabled, the option is sent every time there is a 2525need to deal with vendor space 25167. 2526 2527Another possibility is to redefine the option; see :ref:`dhcp4-private-opts`. 2528 2529Kea comes with several example configuration files. Some of them showcase 2530how to configure options 60 and 43. See ``doc/examples/kea4/vendor-specific.json`` 2531and ``doc/examples/kea6/vivso.json`` in the Kea sources. 2532 2533.. note:: 2534 2535 Currently only one vendor is supported for vivco-suboptions (code 124) 2536 and vivso-suboptions (code 125) options. Specifying 2537 multiple enterprise numbers within a single option instance or multiple 2538 options with different enterprise numbers is not supported. 2539 2540.. _dhcp4-option-spaces: 2541 2542Nested DHCPv4 Options (Custom Option Spaces) 2543-------------------------------------------- 2544 2545It is sometimes useful to define a completely new option space, such as 2546when a user creates a new option in the standard option space 2547("dhcp4") and wants this option to convey sub-options. Since they are in 2548a separate space, sub-option codes have a separate numbering scheme 2549and may overlap with the codes of standard options. 2550 2551Note that the creation of a new option space is not required when 2552defining sub-options for a standard option, because one is created by 2553default if the standard option is meant to convey any sub-options (see 2554:ref:`dhcp4-vendor-opts`). 2555 2556If we want a DHCPv4 option called "container" with code 2557222, that conveys two sub-options with codes 1 and 2, we first need to 2558define the new sub-options: 2559 2560:: 2561 2562 "Dhcp4": { 2563 "option-def": [ 2564 { 2565 "name": "subopt1", 2566 "code": 1, 2567 "space": "isc", 2568 "type": "ipv4-address", 2569 "record-types": "", 2570 "array": false, 2571 "encapsulate": "" 2572 }, 2573 { 2574 "name": "subopt2", 2575 "code": 2, 2576 "space": "isc", 2577 "type": "string", 2578 "record-types": "", 2579 "array": false, 2580 "encapsulate": "" 2581 } 2582 ], 2583 ... 2584 } 2585 2586Note that we have defined the options to belong to a new option space 2587(in this case, ``"isc"``). 2588 2589The next step is to define a regular DHCPv4 option with the desired code 2590and specify that it should include options from the new option space: 2591 2592:: 2593 2594 "Dhcp4": { 2595 "option-def": [ 2596 ..., 2597 { 2598 "name": "container", 2599 "code": 222, 2600 "space": "dhcp4", 2601 "type": "empty", 2602 "array": false, 2603 "record-types": "", 2604 "encapsulate": "isc" 2605 } 2606 ], 2607 ... 2608 } 2609 2610The name of the option space in which the sub-options are defined is set 2611in the ``encapsulate`` field. The ``type`` field is set to ``empty``, to 2612indicate that this option does not carry any data other than 2613sub-options. 2614 2615Finally, we can set values for the new options: 2616 2617:: 2618 2619 "Dhcp4": { 2620 "option-data": [ 2621 { 2622 "name": "subopt1", 2623 "code": 1, 2624 "space": "isc", 2625 "data": "192.0.2.3" 2626 }, 2627 } 2628 "name": "subopt2", 2629 "code": 2, 2630 "space": "isc", 2631 "data": "Hello world" 2632 }, 2633 { 2634 "name": "container", 2635 "code": 222, 2636 "space": "dhcp4" 2637 } 2638 ], 2639 ... 2640 } 2641 2642It is possible to create an option which carries some data in 2643addition to the sub-options defined in the encapsulated option space. 2644For example, if the ``"container"`` option from the previous example were 2645required to carry a uint16 value as well as the sub-options, the 2646``type`` value would have to be set to ``"uint16"`` in the option 2647definition. (Such an option would then have the following data 2648structure: DHCP header, uint16 value, sub-options.) The value specified 2649with the ``data`` parameter — which should be a valid integer enclosed 2650in quotes, e.g. ``"123"`` — would then be assigned to the uint16 field in 2651the ``"container"`` option. 2652 2653.. _dhcp4-option-data-defaults: 2654 2655Unspecified Parameters for DHCPv4 Option Configuration 2656------------------------------------------------------ 2657 2658In many cases it is not required to specify all parameters for an option 2659configuration, and the default values can be used. However, it is 2660important to understand the implications of not specifying some of them, 2661as it may result in configuration errors. The list below explains the 2662behavior of the server when a particular parameter is not explicitly 2663specified: 2664 2665- ``name`` - the server requires either an option name or an option code to 2666 identify an option. If this parameter is unspecified, the option code 2667 must be specified. 2668 2669- ``code`` - the server requires either an option name or an option code to 2670 identify an option. This parameter may be left unspecified if the 2671 ``name`` parameter is specified. However, this also requires that the 2672 particular option has a definition (either as a standard option or 2673 an administrator-created definition for the option using an 2674 ``'option-def'`` structure), as the option definition associates an 2675 option with a particular name. It is possible to configure an option 2676 for which there is no definition (unspecified option format). 2677 Configuration of such options requires the use of the option code. 2678 2679- ``space`` - if the option space is unspecified it defaults to 2680 ``'dhcp4'``, which is an option space holding standard DHCPv4 options. 2681 2682- ``data`` - if the option data is unspecified it defaults to an empty 2683 value. The empty value is mostly used for the options which have no 2684 payload (boolean options), but it is legal to specify empty values 2685 for some options which carry variable-length data and for which the 2686 specification allows a length of 0. For such options, the data 2687 parameter may be omitted in the configuration. 2688 2689- ``csv-format`` - if this value is not specified, the server 2690 assumes that the option data is specified as a list of comma-separated 2691 values to be assigned to individual fields of the DHCP option. 2692 2693.. _dhcp4-stateless-configuration: 2694 2695Stateless Configuration of DHCPv4 Clients 2696----------------------------------------- 2697 2698The DHCPv4 server supports stateless client configuration, whereby 2699the client has an IP address configured (e.g. using manual 2700configuration) and only contacts the server to obtain other 2701configuration parameters, such as addresses of DNS servers. To 2702obtain the stateless configuration parameters, the client sends the 2703DHCPINFORM message to the server with the ``ciaddr`` set to the address 2704that the client is currently using. The server unicasts the DHCPACK 2705message to the client that includes the stateless configuration 2706(`"yiaddr"` not set). 2707 2708The server responds to the DHCPINFORM when the client is associated 2709with a subnet defined in the server's configuration. An example subnet 2710configuration looks like this: 2711 2712:: 2713 2714 "Dhcp4": { 2715 "subnet4": [ 2716 { 2717 "subnet": "192.0.2.0/24" 2718 "option-data": [ { 2719 "name": "domain-name-servers", 2720 "code": 6, 2721 "data": "192.0.2.200,192.0.2.201", 2722 "csv-format": true, 2723 "space": "dhcp4" 2724 } ] 2725 } 2726 ] 2727 } 2728 2729This subnet specifies the single option which will be included in the 2730DHCPACK message to the client in response to DHCPINFORM. The 2731subnet definition does not require the address pool configuration if it 2732will be used solely for stateless configuration. 2733 2734This server will associate the subnet with the client if one of the 2735following conditions is met: 2736 2737- The DHCPINFORM is relayed and the ``giaddr`` matches the configured 2738 subnet. 2739 2740- The DHCPINFORM is unicast from the client and the ``ciaddr`` matches the 2741 configured subnet. 2742 2743- The DHCPINFORM is unicast from the client and the ``ciaddr`` is not set, 2744 but the source address of the IP packet matches the configured 2745 subnet. 2746 2747- The DHCPINFORM is not relayed and the IP address on the interface on 2748 which the message is received matches the configured subnet. 2749 2750.. _dhcp4-client-classifier: 2751 2752Client Classification in DHCPv4 2753------------------------------- 2754 2755The DHCPv4 server includes support for client classification. For a 2756deeper discussion of the classification process, see :ref:`classify`. 2757 2758In certain cases it is useful to configure the server to differentiate 2759between DHCP client types and treat them accordingly. Client 2760classification can be used to modify the behavior of almost any part of 2761DHCP message processing. Kea currently offers client classification 2762via private options and option 43 deferred unpacking; subnet selection; 2763pool selection; assignment of different options; and, for cable modems, 2764specific options for use with the TFTP server address and the boot file 2765field. 2766 2767Kea can be instructed to limit access to given subnets based on class 2768information. This is particularly useful for cases where two types of 2769devices share the same link and are expected to be served from two 2770different subnets. The primary use case for such a scenario is cable 2771networks, where there are two classes of devices: the cable modem 2772itself, which should be handed a lease from subnet A; and all other 2773devices behind the modem, which should get a lease from subnet B. That 2774segregation is essential to prevent overly curious end-users from playing 2775with their cable modems. For details on how to set up class restrictions 2776on subnets, see :ref:`classification-subnets`. 2777 2778When subnets belong to a shared network, the classification applies to 2779subnet selection but not to pools; that is, a pool in a subnet limited to a 2780particular class can still be used by clients which do not belong to the 2781class, if the pool they are expected to use is exhausted. So the limit 2782on access based on class information is also available at the pool 2783level within a subnet: see :ref:`classification-pools`. This is 2784useful when segregating clients belonging to the same subnet into 2785different address ranges. 2786 2787In a similar way, a pool can be constrained to serve only known clients, 2788i.e. clients which have a reservation, using the built-in ``KNOWN`` or 2789``UNKNOWN`` classes. Addresses can be assigned to registered clients 2790without giving a different address per reservation, for instance when 2791there are not enough available addresses. The determination whether 2792there is a reservation for a given client is made after a subnet is 2793selected, so it is not possible to use ``KNOWN``/``UNKNOWN`` classes to select a 2794shared network or a subnet. 2795 2796The process of classification is conducted in five steps. The first step 2797is to assess an incoming packet and assign it to zero or more classes. 2798The second step is to choose a subnet, possibly based on the class 2799information. When the incoming packet is in the special class ``DROP``, 2800it is dropped and a debug message logged. 2801The next step is to evaluate class expressions depending on 2802the built-in ``KNOWN``/``UNKNOWN`` classes after host reservation lookup, 2803using them for pool selection and assigning classes from host 2804reservations. The list of required classes is then built and each class 2805of the list has its expression evaluated; when it returns ``true`` the 2806packet is added as a member of the class. The last step is to assign 2807options, again possibly based on the class information. More complete 2808and detailed information is available in :ref:`classify`. 2809 2810There are two main methods of classification. The first is automatic and 2811relies on examining the values in the vendor class options or the 2812existence of a host reservation. Information from these options is 2813extracted, and a class name is constructed from it and added to the 2814class list for the packet. The second specifies an expression that is 2815evaluated for each packet. If the result is ``true``, the packet is a 2816member of the class. 2817 2818.. note:: 2819 2820 Care should be taken with client classification, as it is easy for 2821 clients that do not meet class criteria to be denied all service. 2822 2823Setting Fixed Fields in Classification 2824~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2825 2826It is possible to specify that clients belonging to a particular class 2827should receive packets with specific values in certain fixed fields. In 2828particular, three fixed fields are supported: ``next-server`` (conveys 2829an IPv4 address, which is set in the ``siaddr`` field), ``server-hostname`` 2830(conveys a server hostname, can be up to 64 bytes long, and is sent in 2831the ``sname`` field) and ``boot-file-name`` (conveys the configuration file, 2832can be up to 128 bytes long, and is sent using the ``file`` field). 2833 2834Obviously, there are many ways to assign clients to specific classes, 2835but for PXE clients the client architecture type option (code 93) 2836seems to be particularly suited to make the distinction. The following 2837example checks whether the client identifies itself as a PXE device with 2838architecture EFI x86-64, and sets several fields if it does. See 2839`Section 2.1 of RFC 28404578 <https://tools.ietf.org/html/rfc4578#section-2.1>`__) or the 2841client documentation for specific values. 2842 2843:: 2844 2845 "Dhcp4": { 2846 "client-classes": [ 2847 { 2848 "name": "ipxe_efi_x64", 2849 "test": "option[93].hex == 0x0009", 2850 "next-server": "192.0.2.254", 2851 "server-hostname": "hal9000", 2852 "boot-file-name": "/dev/null" 2853 }, 2854 ... 2855 ], 2856 ... 2857 } 2858 2859If an incoming packet is matched to multiple classes, then the 2860value used for each field will come from the first class that 2861specifies the field, in the order the classes are assigned to the 2862packet. 2863 2864.. note:: 2865 2866 The classes are ordered as specified in the configuration. 2867 2868Using Vendor Class Information in Classification 2869~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2870 2871The server checks whether an incoming packet includes the vendor class 2872identifier option (60). If it does, the content of that option is 2873prepended with ``VENDOR_CLASS\_``, and it is interpreted as a class. For 2874example, modern cable modems send this option with value 2875``docsis3.0``, so the packet belongs to the class 2876``VENDOR_CLASS_docsis3.0``. 2877 2878.. note:: 2879 2880 Certain special actions for clients in `VENDOR_CLASS_docsis3.0` can be 2881 achieved by defining `VENDOR_CLASS_docsis3.0` and setting its 2882 ``next-server`` and ``boot-file-name`` values appropriately. 2883 2884This example shows a configuration using an automatically generated 2885``VENDOR_CLASS\_`` class. The administrator of the network has decided that 2886addresses from the range 192.0.2.10 to 192.0.2.20 are going to be managed by 2887the Dhcp4 server and only clients belonging to the DOCSIS 3.0 client 2888class are allowed to use that pool. 2889 2890:: 2891 2892 "Dhcp4": { 2893 "subnet4": [ 2894 { 2895 "subnet": "192.0.2.0/24", 2896 "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ], 2897 "client-class": "VENDOR_CLASS_docsis3.0" 2898 } 2899 ], 2900 ... 2901 } 2902 2903Defining and Using Custom Classes 2904~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2905 2906The following example shows how to configure a class using an expression 2907and a subnet using that class. This configuration defines the class 2908named ``Client_foo``. It is comprised of all clients whose client IDs 2909(option 61) start with the string ``foo``. Members of this class will be 2910given addresses from 192.0.2.10 to 192.0.2.20 and the addresses of their 2911DNS servers set to 192.0.2.1 and 192.0.2.2. 2912 2913:: 2914 2915 "Dhcp4": { 2916 "client-classes": [ 2917 { 2918 "name": "Client_foo", 2919 "test": "substring(option[61].hex,0,3) == 'foo'", 2920 "option-data": [ 2921 { 2922 "name": "domain-name-servers", 2923 "code": 6, 2924 "space": "dhcp4", 2925 "csv-format": true, 2926 "data": "192.0.2.1, 192.0.2.2" 2927 } 2928 ] 2929 }, 2930 ... 2931 ], 2932 "subnet4": [ 2933 { 2934 "subnet": "192.0.2.0/24", 2935 "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ], 2936 "client-class": "Client_foo" 2937 }, 2938 ... 2939 ], 2940 ... 2941 } 2942 2943.. _dhcp4-required-class: 2944 2945Required Classification 2946~~~~~~~~~~~~~~~~~~~~~~~ 2947 2948In some cases it is useful to limit the scope of a class to a 2949shared network, subnet, or pool. There are two parameters which are used 2950to limit the scope of the class by instructing the server to evaluate test 2951expressions when required. 2952 2953The first one is the per-class ``only-if-required`` flag, which is ``false`` 2954by default. When it is set to ``true``, the test expression of the class 2955is not evaluated at the reception of the incoming packet but later, and 2956only if the class evaluation is required. 2957 2958The second is ``require-client-classes``, which takes a list of class 2959names and is valid in shared-network, subnet, and pool scope. Classes in 2960these lists are marked as required and evaluated after selection of this 2961specific shared network/subnet/pool and before output-option processing. 2962 2963In this example, a class is assigned to the incoming packet when the 2964specified subnet is used: 2965 2966:: 2967 2968 "Dhcp4": { 2969 "client-classes": [ 2970 { 2971 "name": "Client_foo", 2972 "test": "member('ALL')", 2973 "only-if-required": true 2974 }, 2975 ... 2976 ], 2977 "subnet4": [ 2978 { 2979 "subnet": "192.0.2.0/24", 2980 "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ], 2981 "require-client-classes": [ "Client_foo" ], 2982 ... 2983 }, 2984 ... 2985 ], 2986 ... 2987 } 2988 2989Required evaluation can be used to express complex dependencies like 2990subnet membership. It can also be used to reverse the 2991precedence; if ``option-data`` is set in a subnet, it takes precedence 2992over ``option-data`` in a class. If ``option-data`` is moved to a 2993required class and required in the subnet, a class evaluated earlier 2994may take precedence. 2995 2996Required evaluation is also available at the shared-network and pool levels. 2997The order in which required classes are considered is: shared-network, 2998subnet, and pool, i.e. in the reverse order from the way in which ``option-data`` is 2999processed. 3000 3001.. _dhcp4-ddns-config: 3002 3003DDNS for DHCPv4 3004--------------- 3005 3006As mentioned earlier, ``kea-dhcp4`` can be configured to generate requests 3007to the DHCP-DDNS server, ``kea-dhcp-ddns``, (referred to herein as "D2") to 3008update DNS entries. These requests are known as Name Change Requests or 3009NCRs. Each NCR contains the following information: 3010 30111. Whether it is a request to add (update) or remove DNS entries. 3012 30132. Whether the change requests forward DNS updates (A records), reverse 3014 DNS updates (PTR records), or both. 3015 30163. The Fully Qualified Domain Name (FQDN), lease address, and DHCID 3017 (information identifying the client associated with the FQDN). 3018 3019Prior to Kea 1.7.1, all parameters for controlling DDNS were within the 3020global ``dhcp-ddns`` section of ``kea-dhcp4``. Beginning with Kea 1.7.1, 3021DDNS-related parameters were split into two groups: 3022 30231. Connectivity Parameters 3024 3025 These are parameters which specify where and how ``kea-dhcp4`` connects to 3026 and communicates with D2. These parameters can only be specified 3027 within the top-level ``dhcp-ddns`` section in the ``kea-dhcp4`` 3028 configuration. The connectivity parameters are listed below: 3029 3030 - ``enable-updates`` 3031 - ``server-ip`` 3032 - ``server-port`` 3033 - ``sender-ip`` 3034 - ``sender-port`` 3035 - ``max-queue-size`` 3036 - ``ncr-protocol`` 3037 - ``ncr-format"`` 3038 30392. Behavioral Parameters 3040 3041 These parameters influence behavior such as how client host names and 3042 FQDN options are handled. They have been moved out of the ``dhcp-ddns`` 3043 section so that they may be specified at the global, shared-network, 3044 and/or subnet levels. Furthermore, they are inherited downward from global to 3045 shared-network to subnet. In other words, if a parameter is not specified at 3046 a given level, the value for that level comes from the level above it. 3047 The behavioral parameters are as follows: 3048 3049 - ``ddns-send-updates`` 3050 - ``ddns-override-no-update`` 3051 - ``ddns-override-client-update`` 3052 - ``ddns-replace-client-name"`` 3053 - ``ddns-generated-prefix`` 3054 - ``ddns-qualifying-suffix`` 3055 - ``ddns-update-on-renew`` 3056 - ``ddns-use-conflict-resolution`` 3057 - ``hostname-char-set`` 3058 - ``hostname-char-replacement`` 3059 3060.. note:: 3061 3062 For backward compatibility, configuration parsing still recognizes 3063 the original behavioral parameters specified in ``dhcp-ddns``. It 3064 does so by translating the parameter into its global equivalent. If a 3065 parameter is specified both globally and in ``dhcp-ddns``, the latter 3066 value is ignored. In either case, a log is emitted explaining 3067 what has occurred. Specifying these values within ``dhcp-ddns`` is 3068 deprecated and support for it will be removed. 3069 3070The default configuration and values would appear as follows: 3071 3072:: 3073 3074 "Dhcp4": { 3075 "dhcp-ddns": { 3076 // Connectivity parameters 3077 "enable-updates": false, 3078 "server-ip": "127.0.0.1", 3079 "server-port":53001, 3080 "sender-ip":"", 3081 "sender-port":0, 3082 "max-queue-size":1024, 3083 "ncr-protocol":"UDP", 3084 "ncr-format":"JSON" 3085 }, 3086 3087 // Behavioral parameters (global) 3088 "ddns-send-updates": true, 3089 "ddns-override-no-update": false, 3090 "ddns-override-client-update": false, 3091 "ddns-replace-client-name": "never", 3092 "ddns-generated-prefix": "myhost", 3093 "ddns-qualifying-suffix": "", 3094 "ddns-update-on-renew": false, 3095 "ddns-use-conflict-resolution": true, 3096 "hostname-char-set": "", 3097 "hostname-char-replacement": "" 3098 ... 3099 } 3100 3101As of Kea 1.7.1, there are two parameters which determine if ``kea-dhcp4`` 3102can generate DDNS requests to D2: the existing ``dhcp-ddns:enable-updates`` 3103parameter, which now only controls whether ``kea-dhcp4`` connects to D2; 3104and the new behavioral parameter, ``ddns-send-updates``, which determines 3105whether DDNS updates are enabled at a given level (i.e. global, shared-network, 3106or subnet). The following table shows how the two parameters function 3107together: 3108 3109.. table:: Enabling and Disabling DDNS Updates 3110 3111 +-----------------+--------------------+-------------------------------+ 3112 | dhcp-ddns: | Global | Outcome | 3113 | enable-updates | ddns-send-updates | | 3114 +=================+====================+===============================+ 3115 | false (default) | false | no updates at any scope | 3116 +-----------------+--------------------+-------------------------------+ 3117 | false | true (default) | no updates at any scope | 3118 +-----------------+--------------------+-------------------------------+ 3119 | true | false | updates only at scopes with | 3120 | | | a local value of true for | 3121 | | | ddns-enable-updates | 3122 +-----------------+--------------------+-------------------------------+ 3123 | true | true | updates at all scopes except | 3124 | | | those with a local value of | 3125 | | | false for ddns-enable-updates | 3126 +-----------------+--------------------+-------------------------------+ 3127 3128Kea 1.9.1 added two new parameters; the first is ``ddns-update-on-renew``. 3129Normally, when leases are renewed the server only updates DNS if the DNS 3130information for the lease (e.g. FQDN, DNS update direction flags) has changed. 3131Setting ``ddns-update-on-renew`` to `true` instructs the server to always update 3132the DNS information when a lease is renewed, even if its DNS information has not 3133changed. This allows Kea to "self-heal" if it was previously unable 3134to add DNS entries or they were somehow lost by the DNS server. 3135 3136.. note:: 3137 3138 Setting ``ddns-update-on-renew`` to `true` may impact performance, especially 3139 for servers with numerous clients that renew often. 3140 3141The second parameter added in Kea 1.9.1 is ``ddns-use-conflict-resolution``. 3142The value of this parameter is passed by ``kea-dhcp4`` to D2 with each DNS update 3143request. When `true`, (the default value), D2 employs conflict resolution, 3144as described in `RFC 4703 <https://tools.ietf.org/html/rfc4703>`__, when 3145attempting to fulfill the update request. When false, D2 simply attempts 3146to update the DNS entries per the request, regardless of whether they 3147conflict with existing entries owned by other DHCP4 clients. 3148 3149.. note:: 3150 3151 Setting ``ddns-use-conflict-resolution`` to `false` disables the overwrite 3152 safeguards that the rules of conflict resolution ( 3153 `RFC 4703 <https://tools.ietf.org/html/rfc4703>`__) are intended to 3154 prevent. This means that existing entries for a FQDN or an 3155 IP address made for Client-A can be deleted or replaced by entries 3156 for Client-B. Furthermore, there are two scenarios by which entries 3157 for multiple clients for the same key (e.g. FQDN or IP) can be created. 3158 3159 1. Client-B uses the same FQDN as Client-A but a different IP address. 3160 In this case, the forward DNS entries (A and DHCID RRs) for 3161 Client-A will be deleted as they match the FQDN and new entries for 3162 Client-B will be added. The reverse DNS entries (PTR and DHCID RRs) 3163 for Client-A, however, will not be deleted as they belong to a different 3164 IP address, while new entries for Client-B will still be added. 3165 3166 2. Client-B uses the same IP address as Client-A but a different FQDN. 3167 In this case the reverse DNS entries (PTR and DHCID RRs) for Client-A 3168 will be deleted as they match the IP address and new entries for 3169 Client-B will be added. The forward DNS entries (A and DHCID RRs) 3170 for Client-A, however, will not be deleted, as they belong to a different 3171 FQDN while new entries for Client-B will still be added. 3172 3173 Disabling conflict resolution should be done only after careful review of 3174 specific use cases. The best way to avoid unwanted DNS entries is to 3175 always ensure lease changes are processed through Kea, whether they are 3176 released, expire, or are deleted via the ``lease-del4`` command, prior to 3177 reassigning either FQDNs or IP addresses. Doing so causes ``kea-dhcp4`` 3178 to generate DNS removal requests to D2. 3179 3180.. note:: 3181 3182 The DNS entries Kea creates contain a value for TTL (time to live). As of 3183 Kea 1.9.3, kea-dhcp4 calculates that value based on 3184 `RFC 4702, Section 5 <https://tools.ietf.org/html/rfc4702#section-5>`__, 3185 which suggests that the TTL value be 1/3 of the lease's lifetime, with 3186 a minimum value of 10 minutes. In earlier versions, the server set the TTL value 3187 equal to the lease's valid lifetime. 3188 3189.. _dhcpv4-d2-io-config: 3190 3191DHCP-DDNS Server Connectivity 3192~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3193 3194For NCRs to reach the D2 server, ``kea-dhcp4`` must be able to communicate 3195with it. ``kea-dhcp4`` uses the following configuration parameters to 3196control this communication: 3197 3198- ``enable-updates`` - As of Kea 1.7.1, this parameter only enables 3199 connectivity to ``kea-dhcp-ddns`` such that DDNS updates can be constructed 3200 and sent. It must be `true` for NCRs to be generated and sent to D2. 3201 It defaults to `false`. 3202 3203- ``server-ip`` - This is the IP address on which D2 listens for requests. The 3204 default is the local loopback interface at address 127.0.0.1. 3205 Either an IPv4 or IPv6 address may be specified. 3206 3207- ``server-port`` - This is the port on which D2 listens for requests. The default 3208 value is 53001. 3209 3210- ``sender-ip`` - This is the IP address which ``kea-dhcp4`` uses to send requests to 3211 D2. The default value is blank, which instructs ``kea-dhcp4`` to select a 3212 suitable address. 3213 3214- ``sender-port`` - This is the port which ``kea-dhcp4`` uses to send requests to D2. 3215 The default value of 0 instructs ``kea-dhcp4`` to select a suitable port. 3216 3217- ``max-queue-size`` - This is the maximum number of requests allowed to queue 3218 waiting to be sent to D2. This value guards against requests 3219 accumulating uncontrollably if they are being generated faster than 3220 they can be delivered. If the number of requests queued for 3221 transmission reaches this value, DDNS updating will be turned off 3222 until the queue backlog has been sufficiently reduced. The intent is 3223 to allow the ``kea-dhcp4`` server to continue lease operations without 3224 running the risk that its memory usage grows without limit. The 3225 default value is 1024. 3226 3227- ``ncr-protocol`` - This specifies the socket protocol to use when sending requests to 3228 D2. Currently only UDP is supported. 3229 3230- ``ncr-format`` - This specifies the packet format to use when sending requests to D2. 3231 Currently only JSON format is supported. 3232 3233By default, ``kea-dhcp-ddns`` is assumed to be running on the same machine 3234as ``kea-dhcp4``, and all of the default values mentioned above should be 3235sufficient. If, however, D2 has been configured to listen on a different 3236address or port, these values must be altered accordingly. For example, 3237if D2 has been configured to listen on 192.168.1.10 port 900, the 3238following configuration is required: 3239 3240:: 3241 3242 "Dhcp4": { 3243 "dhcp-ddns": { 3244 "server-ip": "192.168.1.10", 3245 "server-port": 900, 3246 ... 3247 }, 3248 ... 3249 } 3250 3251.. _dhcpv4-d2-rules-config: 3252 3253When Does the ``kea-dhcp4`` Server Generate a DDNS Request? 3254~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3255 3256``kea-dhcp4`` follows the behavior prescribed for DHCP servers in `RFC 32574702 <https://tools.ietf.org/html/rfc4702>`__. It is important to keep in 3258mind that ``kea-dhcp4`` makes the initial decision of when and what to 3259update and forwards that information to D2 in the form of NCRs. Carrying 3260out the actual DNS updates and dealing with such things as conflict 3261resolution are within the purview of D2 itself 3262(see :ref:`dhcp-ddns-server`). This section describes when ``kea-dhcp4`` 3263generates NCRs and the configuration parameters that can be used to 3264influence this decision. It assumes that both the connectivity parameter 3265``enable-updates`` and the behavioral parameter ``ddns-send-updates``, 3266are `true`. 3267 3268In general, ``kea-dhcp4`` generates DDNS update requests when: 3269 32701. A new lease is granted in response to a DHCPREQUEST; 3271 32722. An existing lease is renewed but the FQDN associated with it has 3273 changed; or 3274 32753. An existing lease is released in response to a DHCPRELEASE. 3276 3277In the second case, lease renewal, two DDNS requests are issued: one 3278request to remove entries for the previous FQDN, and a second request to 3279add entries for the new FQDN. In the third case, a lease release - a 3280single DDNS request - to remove its entries will be made. 3281 3282As for the first case, the decisions involved when granting a new lease are 3283more complex. When a new lease is granted, ``kea-dhcp4`` generates a 3284DDNS update request if the DHCPREQUEST contains either the FQDN option 3285(code 81) or the Host Name option (code 12). If both are present, the 3286server uses the FQDN option. By default, ``kea-dhcp4`` respects the 3287FQDN N and S flags specified by the client as shown in the following 3288table: 3289 3290.. table:: Default FQDN Flag Behavior 3291 3292 +------------+---------------------+-----------------+-------------+ 3293 | Client | Client Intent | Server Response | Server | 3294 | Flags:N-S | | | Flags:N-S-O | 3295 +============+=====================+=================+=============+ 3296 | 0-0 | Client wants to | Server | 1-0-0 | 3297 | | do forward | generates | | 3298 | | updates, server | reverse-only | | 3299 | | should do | request | | 3300 | | reverse updates | | | 3301 +------------+---------------------+-----------------+-------------+ 3302 | 0-1 | Server should | Server | 0-1-0 | 3303 | | do both forward | generates | | 3304 | | and reverse | request to | | 3305 | | updates | update both | | 3306 | | | directions | | 3307 +------------+---------------------+-----------------+-------------+ 3308 | 1-0 | Client wants no | Server does not | 1-0-0 | 3309 | | updates done | generate a | | 3310 | | | request | | 3311 +------------+---------------------+-----------------+-------------+ 3312 3313The first row in the table above represents "client delegation." Here 3314the DHCP client states that it intends to do the forward DNS updates and 3315the server should do the reverse updates. By default, ``kea-dhcp4`` 3316honors the client's wishes and generates a DDNS request to the D2 server 3317to update only reverse DNS data. The parameter 3318``ddns-override-client-update`` can be used to instruct the server to 3319override client delegation requests. When this parameter is `"true"`, 3320``kea-dhcp4`` disregards requests for client delegation and generates a 3321DDNS request to update both forward and reverse DNS data. In this case, 3322the N-S-O flags in the server's response to the client will be 0-1-1 3323respectively. 3324 3325(Note that the flag combination N=1, S=1 is prohibited according to `RFC 33264702 <https://tools.ietf.org/html/rfc4702>`__. If such a combination is 3327received from the client, the packet will be dropped by ``kea-dhcp4``.) 3328 3329To override client delegation, set the following values in the 3330configuration file: 3331 3332:: 3333 3334 "Dhcp4": { 3335 ... 3336 "ddns-override-client-update": true, 3337 ... 3338 } 3339 3340The third row in the table above describes the case in which the client 3341requests that no DNS updates be done. The parameter 3342``ddns-override-no-update`` can be used to instruct the server to disregard 3343the client's wishes. When this parameter is true, ``kea-dhcp4`` 3344generates DDNS update requests to ``kea-dhcp-ddns`` even if the client 3345requests that no updates be done. The N-S-O flags in the server's 3346response to the client will be 0-1-1. 3347 3348To override client delegation, issue the following commands: 3349 3350:: 3351 3352 "Dhcp4": { 3353 ... 3354 "ddns-override-no-update": true, 3355 ... 3356 } 3357 3358``kea-dhcp4`` always generates DDNS update requests if the client 3359request only contains the Host Name option. In addition, it includes 3360an FQDN option in the response to the client with the FQDN N-S-O flags 3361set to 0-1-0, respectively. The domain name portion of the FQDN option 3362is the name submitted to D2 in the DDNS update request. 3363 3364.. _dhcpv4-fqdn-name-generation: 3365 3366``kea-dhcp4`` Name Generation for DDNS Update Requests 3367~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3368 3369Each Name Change Request must of course include the fully qualified domain 3370name whose DNS entries are to be affected. ``kea-dhcp4`` can be configured 3371to supply a portion or all of that name, based on what it receives 3372from the client in the DHCPREQUEST. 3373 3374The default rules for constructing the FQDN that will be used for DNS 3375entries are: 3376 33771. If the DHCPREQUEST contains the client FQDN option, take the 3378 candidate name from there; otherwise, take it from the Host Name 3379 option. 3380 33812. If the candidate name is a partial (i.e. unqualified) name, then add 3382 a configurable suffix to the name and use the result as the FQDN. 3383 33843. If the candidate name provided is empty, generate an FQDN using a 3385 configurable prefix and suffix. 3386 33874. If the client provides neither option, then take no DNS action. 3388 3389These rules can be amended by setting the ``ddns-replace-client-name`` 3390parameter, which provides the following modes of behavior: 3391 3392- ``never`` - use the name the client sent. If the client sent no name, 3393 do not generate one. This is the default mode. 3394 3395- ``always`` - replace the name the client sent. If the client sent no 3396 name, generate one for the client. 3397 3398- ``when-present`` - replace the name the client sent. If the client 3399 sent no name, do not generate one. 3400 3401- ``when-not-present`` - use the name the client sent. If the client 3402 sent no name, generate one for the client. 3403 3404.. note:: 3405 3406 In early versions of Kea, this parameter was a boolean and permitted only 3407 values of ``true`` and ``false``. Boolean values have been deprecated 3408 and are no longer accepted. Administrators currently using booleans 3409 must replace them with the desired mode name. A value of ``true`` 3410 maps to ``"when-present"``, while ``false`` maps to ``"never"``. 3411 3412For example, to instruct ``kea-dhcp4`` to always generate the FQDN for a 3413client, set the parameter ``ddns-replace-client-name`` to ``always`` as 3414follows: 3415 3416:: 3417 3418 "Dhcp4": { 3419 ... 3420 "ddns-replace-client-name": "always", 3421 ... 3422 } 3423 3424The prefix used in the generation of an FQDN is specified by the 3425``generated-prefix`` parameter. The default value is `"myhost"`. To alter 3426its value, simply set it to the desired string: 3427 3428:: 3429 3430 "Dhcp4": { 3431 ... 3432 "ddns-generated-prefix": "another.host", 3433 ... 3434 } 3435 3436The suffix used when generating an FQDN, or when qualifying a partial 3437name, is specified by the ``ddns-qualifying-suffix`` parameter. It is 3438strongly recommended that the user supply a value for the qualifying prefix when 3439DDNS updates are enabled. For obvious reasons, we cannot supply a 3440meaningful default. 3441 3442:: 3443 3444 "Dhcp4": { 3445 ... 3446 "ddns-qualifying-suffix": "foo.example.org", 3447 ... 3448 } 3449 3450When generating a name, ``kea-dhcp4`` constructs the name in the format: 3451 3452``[ddns-generated-prefix]-[address-text].[ddns-qualifying-suffix]`` 3453 3454where ``address-text`` is simply the lease IP address converted to a 3455hyphenated string. For example, if the lease address is 172.16.1.10, the 3456qualifying suffix "example.com", and the default value is used for 3457``ddns-generated-prefix``, the generated FQDN is: 3458 3459``myhost-172-16-1-10.example.com.`` 3460 3461.. _dhcp4-host-name-sanitization: 3462 3463Sanitizing Client Host Name and FQDN Names 3464~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3465 3466Some DHCP clients may provide values in the Host Name 3467option (option code 12) or FQDN option (option code 81) that contain 3468undesirable characters. It is possible to configure ``kea-dhcp4`` to 3469sanitize these values. The most typical use case is ensuring that only 3470characters that are permitted by RFC 1035 be included: A-Z, a-z, 0-9, 3471and "-". This may be accomplished with the following two parameters: 3472 3473- ``hostname-char-set`` - a regular expression describing the invalid 3474 character set. This can be any valid, regular expression using POSIX 3475 extended expression syntax. Embedded nulls (0x00) are always 3476 considered an invalid character to be replaced (or omitted). 3477 3478- ``hostname-char-replacement`` - a string of zero or more characters 3479 with which to replace each invalid character in the host name. An empty 3480 string causes invalid characters to be OMITTED rather than replaced. 3481 3482.. note:: 3483 3484 Starting with Kea 1.7.5, the default values are as follows: 3485 3486 - "hostname-char-set": "[^A-Za-z0-9.-]", 3487 - "hostname-char-replacement": "" 3488 3489 This enables sanitizing and omits any character that is not 3490 a letter, digit, hyphen, dot, or null. 3491 3492The following configuration replaces anything other than a letter, 3493digit, hyphen, or dot with the letter 'x': 3494:: 3495 3496 "Dhcp4": { 3497 ... 3498 "hostname-char-set": "[^A-Za-z0-9.-]", 3499 "hostname-char-replacement": "x", 3500 ... 3501 } 3502 3503Thus, a client-supplied value of "myhost-$[123.org" would become 3504"myhost-xx123.org". Sanitizing is performed only on the portion of the 3505name supplied by the client, and it is performed before applying a 3506qualifying suffix (if one is defined and needed). 3507 3508.. note:: 3509 3510 The following are some considerations to keep in mind: 3511 Name sanitizing is meant to catch the more common cases of invalid 3512 characters through a relatively simple character-replacement scheme. 3513 It is difficult to devise a scheme that works well in all cases, for 3514 both Host Name and FQDN options. Administrators who find they have clients 3515 with odd corner cases of character combinations that cannot be 3516 readily handled with this mechanism should consider writing a 3517 hook that can carry out sufficiently complex logic to address their 3518 needs. 3519 3520 If clients include domain names in the Host Name option and the administrator 3521 wants these preserved, they need to make sure that the dot, ".", 3522 is considered a valid character by the ``hostname-char-set`` expression, 3523 such as this: `"[^A-Za-z0-9.-]"`. This does not affect dots in FQDN 3524 Option values. When scrubbing FQDNs, dots are treated as delimiters 3525 and used to separate the option value into individual domain labels 3526 that are scrubbed and then re-assembled. 3527 3528 If clients are sending values that differ only by characters 3529 considered as invalid by the hostname-char-set, be aware that 3530 scrubbing them will yield identical values. In such cases, DDNS 3531 conflict rules will permit only one of them to register the name. 3532 3533 Finally, given the latitude clients have in the values they send, it 3534 is virtually impossible to guarantee that a combination of these two 3535 parameters will always yield a name that is valid for use in DNS. For 3536 example, using an empty value for ``hostname-char-replacement`` could 3537 yield an empty domain label within a name, if that label consists 3538 only of invalid characters. 3539 3540.. note:: 3541 3542 Since the 1.6.0 Kea release, it is possible to specify ``hostname-char-set`` 3543 and/or ``hostname-char-replacement`` at the global scope. This allows 3544 host names to be sanitized without requiring a ``dhcp-ddns`` entry. When 3545 a ``hostname-char`` parameter is defined at both the global scope and 3546 in a ``dhcp-ddns`` entry, the second (local) value is used. 3547 3548.. _dhcp4-next-server: 3549 3550Next Server (``siaddr``) 3551------------------------ 3552 3553In some cases, clients want to obtain configuration from a TFTP server. 3554Although there is a dedicated option for it, some devices may use the 3555``siaddr`` field in the DHCPv4 packet for that purpose. That specific field 3556can be configured using the ``next-server`` directive. It is possible to 3557define it in the global scope or for a given subnet only. If both are 3558defined, the subnet value takes precedence. The value in the subnet can be 3559set to `0.0.0.0`, which means that ``next-server`` should not be sent. It 3560can also be set to an empty string, which is equivalent to it 3561not being defined at all; that is, it uses the global value. 3562 3563The ``server-hostname`` (which conveys a server hostname, can be up to 356464 bytes long, and is in the sname field) and 3565``boot-file-name`` (which conveys the configuration file, can be up to 3566128 bytes long, and is sent using the file field) directives are 3567handled the same way as ``next-server``. 3568 3569:: 3570 3571 "Dhcp4": { 3572 "next-server": "192.0.2.123", 3573 "boot-file-name": "/dev/null", 3574 ..., 3575 "subnet4": [ 3576 { 3577 "next-server": "192.0.2.234", 3578 "server-hostname": "some-name.example.org", 3579 "boot-file-name": "bootfile.efi", 3580 ... 3581 } 3582 ] 3583 } 3584 3585.. _dhcp4-echo-client-id: 3586 3587Echoing Client-ID (RFC 6842) 3588---------------------------- 3589 3590The original DHCPv4 specification (`RFC 35912131 <https://tools.ietf.org/html/rfc2131>`__) states that the DHCPv4 3592server must not send back client-id options when responding to clients. 3593However, in some cases that results in confused clients that do not have a MAC 3594address or client-id; see `RFC 35956842 <https://tools.ietf.org/html/rfc6842>`__ for details. That behavior 3596changed with the publication of `RFC 35976842 <https://tools.ietf.org/html/rfc6842>`__, which updated `RFC 35982131 <https://tools.ietf.org/html/rfc2131>`__. That update states that 3599the server must send the client-id if the client sent it, and that is Kea's 3600default behavior. However, in some cases older devices that do not 3601support `RFC 6842 <https://tools.ietf.org/html/rfc6842>`__ may refuse to 3602accept responses that include the client-id option. To enable backward 3603compatibility, an optional configuration parameter has been introduced. 3604To configure it, use the following configuration statement: 3605 3606:: 3607 3608 "Dhcp4": { 3609 "echo-client-id": false, 3610 ... 3611 } 3612 3613.. _dhcp4-match-client-id: 3614 3615Using Client Identifier and Hardware Address 3616-------------------------------------------- 3617 3618The DHCP server must be able to identify the client from which it 3619receives the message and distinguish it from other clients. There are 3620many reasons why this identification is required; the most important 3621ones are: 3622 3623- When the client contacts the server to allocate a new lease, the 3624 server must store the client identification information in the lease 3625 database as a search key. 3626 3627- When the client tries to renew or release the existing lease, the 3628 server must be able to find the existing lease entry in the database 3629 for this client, using the client identification information as a 3630 search key. 3631 3632- Some configurations use static reservations for the IP addresses and 3633 other configuration information. The server's administrator uses 3634 client identification information to create these static assignments. 3635 3636- In dual-stack networks there is often a need to correlate the lease 3637 information stored in DHCPv4 and DHCPv6 servers for a particular 3638 host. Using common identification information by the DHCPv4 and 3639 DHCPv6 clients allows the network administrator to achieve this 3640 correlation and better administer the network. 3641 3642DHCPv4 uses two distinct identifiers which are placed by the client in 3643the queries sent to the server and copied by the server to its responses 3644to the client: ``chaddr`` and ``client-identifier``. The former was 3645introduced as a part of the BOOTP specification and it is also used by 3646DHCP to carry the hardware address of the interface used to send the 3647query to the server (MAC address for the Ethernet). The latter is 3648carried in the client-identifier option, introduced in `RFC 36492132 <https://tools.ietf.org/html/rfc2132>`__. 3650 3651`RFC 2131 <https://tools.ietf.org/html/rfc2131>`__ indicates that the 3652server may use both of these identifiers to identify the client but the 3653client identifier, if present, takes precedence over ``chaddr``. One of 3654the reasons for this is that the client identifier is independent from the 3655hardware used by the client to communicate with the server. For example, 3656if the client obtained the lease using one network card and then the 3657network card is moved to another host, the server will wrongly identify 3658this host as the one which obtained the lease. Moreover, `RFC 36594361 <https://tools.ietf.org/html/rfc4361>`__ gives the recommendation 3660to use a DUID (see `RFC 8415 <https://tools.ietf.org/html/rfc8415>`__, 3661the DHCPv6 specification) carried as a client identifier when dual-stack 3662networks are in use to provide consistent identification information for 3663the client, regardless of the type of protocol it is using. Kea adheres to 3664these specifications, and the client identifier by default takes 3665precedence over the value carried in the ``chaddr`` field when the server 3666searches, creates, updates, or removes the client's lease. 3667 3668When the server receives a DHCPDISCOVER or DHCPREQUEST message from the 3669client, it tries to find out if the client already has a lease in the 3670database; if it does, the server hands out that lease rather than allocates a new one. 3671Each lease in the lease database is associated with the client 3672identifier and/or ``chaddr``. The server first uses the client 3673identifier (if present) to search for the lease; if one is found, the 3674server treats this lease as belonging to the client, even if the 3675current ``chaddr`` and the ``chaddr`` associated with the lease do not 3676match. This facilitates the scenario when the network card on the client 3677system has been replaced and thus the new MAC address appears in the 3678messages sent by the DHCP client. If the server fails to find the lease 3679using the client identifier, it performs another lookup using the 3680``chaddr``. If this lookup returns no result, the client is considered to 3681not have a lease and a new lease is created. 3682 3683A common problem reported by network operators is that poor client 3684implementations do not use stable client identifiers, instead generating 3685a new client identifier each time the client connects to the network. 3686Another well-known case is when the client changes its client 3687identifier during the multi-stage boot process (PXE). In such cases, 3688the MAC address of the client's interface remains stable, and using the 3689``chaddr`` field to identify the client guarantees that the particular 3690system is considered to be the same client, even though its client 3691identifier changes. 3692 3693To address this problem, Kea includes a configuration option which 3694enables client identification using ``chaddr`` only. This instructs the 3695server to ignore the client identifier during lease lookups and allocations 3696for a particular subnet. Consider the following simplified server configuration: 3697 3698:: 3699 3700 "Dhcp4": { 3701 ... 3702 "match-client-id": true, 3703 ... 3704 "subnet4": [ 3705 { 3706 "subnet": "192.0.10.0/24", 3707 "pools": [ { "pool": "192.0.2.23-192.0.2.87" } ], 3708 "match-client-id": false 3709 }, 3710 { 3711 "subnet": "10.0.0.0/8", 3712 "pools": [ { "pool": "10.0.0.23-10.0.2.99" } ], 3713 } 3714 ] 3715 } 3716 3717The ``match-client-id`` is a boolean value which controls this behavior. 3718The default value of ``true`` indicates that the server will use the 3719client identifier for lease lookups and ``chaddr`` if the first lookup 3720returns no results. ``false`` means that the server will only use 3721the ``chaddr`` to search for the client's lease. Whether the DHCID for DNS 3722updates is generated from the client identifier or ``chaddr`` is 3723controlled through the same parameter. 3724 3725The ``match-client-id`` parameter may appear both in the global 3726configuration scope and/or under any subnet declaration. In the example 3727shown above, the effective value of the ``match-client-id`` will be 3728``false`` for the subnet 192.0.10.0/24, because the subnet-specific 3729setting of the parameter overrides the global value of the parameter. 3730The effective value of the ``match-client-id`` for the subnet 10.0.0.0/8 3731will be set to ``true``, because the subnet declaration lacks this 3732parameter and the global setting is by default used for this subnet. In 3733fact, the global entry for this parameter could be omitted in this case, 3734because ``true`` is the default value. 3735 3736It is important to understand what happens when the client obtains its 3737lease for one setting of the ``match-client-id`` and then renews it when 3738the setting has been changed. First, consider the case when the client 3739obtains the lease and the ``match-client-id`` is set to ``true``. The 3740server stores the lease information, including the client identifier 3741(if supplied) and ``chaddr``, in the lease database. When the setting is 3742changed and the client renews the lease, the server will determine that 3743it should use the ``chaddr`` to search for the existing lease. If the 3744client has not changed its MAC address, the server should successfully 3745find the existing lease. The client identifier associated with the 3746returned lease will be ignored and the client will be allowed to use this lease. 3747When the lease is renewed only the ``chaddr`` will be recorded for this lease, 3748according to the new server setting. 3749 3750In the second case, the client has the lease with only a ``chaddr`` value 3751recorded. When the ``match-client-id`` setting is changed to ``true``, 3752the server will first try to use the client identifier to find the 3753existing client's lease. This will return no results because the client 3754identifier was not recorded for this lease. The server will then use 3755the ``chaddr`` and the lease will be found. If the lease appears to have 3756no client identifier recorded, the server will assume that this lease 3757belongs to the client and that it was created with the previous setting 3758of the ``match-client-id``. However, if the lease contains a client 3759identifier which is different from the client identifier used by the 3760client, the lease will be assumed to belong to another client and a 3761new lease will be allocated. 3762 3763.. _dhcp4-authoritative: 3764 3765Authoritative DHCPv4 Server Behavior 3766------------------------------------ 3767 3768The original DHCPv4 specification (`RFC 37692131 <https://tools.ietf.org/html/rfc2131>`__) states that if a client 3770requests an address in the INIT-REBOOT state of which the server has no 3771knowledge, the server must remain silent, except if the server knows 3772that the client has requested an IP address from the wrong network. By 3773default, Kea follows the behavior of the ISC ``dhcpd`` daemon instead of the 3774specification and also remains silent if the client requests an IP 3775address from the wrong network, because configuration information about 3776a given network segment is not known to be correct. Kea only rejects a 3777client's DHCPREQUEST with a DHCPNAK message if it already has a lease 3778for the client with a different IP address. Administrators can 3779override this behavior through the boolean ``authoritative`` (``false`` 3780by default) setting. 3781 3782In authoritative mode, ``authoritative`` set to ``true``, Kea always 3783rejects INIT-REBOOT requests from unknown clients with DHCPNAK messages. 3784The ``authoritative`` setting can be specified in global, 3785shared-network, and subnet configuration scope and is automatically 3786inherited from the parent scope, if not specified. All subnets in a 3787shared-network must have the same ``authoritative`` setting. 3788 3789.. _dhcp4-dhcp4o6-config: 3790 3791DHCPv4-over-DHCPv6: DHCPv4 Side 3792------------------------------- 3793 3794The support of DHCPv4-over-DHCPv6 transport is described in `RFC 37957341 <https://tools.ietf.org/html/rfc7341>`__ and is implemented using 3796cooperating DHCPv4 and DHCPv6 servers. This section is about the 3797configuration of the DHCPv4 side (the DHCPv6 side is described in 3798:ref:`dhcp6-dhcp4o6-config`). 3799 3800.. note:: 3801 3802 DHCPv4-over-DHCPv6 support is experimental and the details of the 3803 inter-process communication may change; both the DHCPv4 and DHCPv6 3804 sides should be running the same version of Kea. For instance, the 3805 support of port relay (RFC 8357) introduced an incompatible change. 3806 3807The ``dhcp4o6-port`` global parameter specifies the first of the two 3808consecutive ports of the UDP sockets used for the communication between 3809the DHCPv6 and DHCPv4 servers. The DHCPv4 server is bound to ::1 on 3810``port`` + 1 and connected to ::1 on ``port``. 3811 3812With DHCPv4-over-DHCPv6, the DHCPv4 server does not have access to 3813several of the identifiers it would normally use to select a subnet. To 3814address this issue, three new configuration entries are available; the 3815presence of any of these allows the subnet to be used with 3816DHCPv4-over-DHCPv6. These entries are: 3817 3818- ``4o6-subnet``: takes a prefix (i.e., an IPv6 address followed by a 3819 slash and a prefix length) which is matched against the source 3820 address. 3821 3822- ``4o6-interface-id``: takes a relay interface ID option value. 3823 3824- ``4o6-interface``: takes an interface name which is matched against 3825 the incoming interface name. 3826 3827The following configuration was used during some tests: 3828 3829:: 3830 3831 { 3832 3833 # DHCPv4 conf 3834 "Dhcp4": { 3835 3836 "interfaces-config": { 3837 "interfaces": [ "eno33554984" ] 3838 }, 3839 3840 "lease-database": { 3841 "type": "memfile", 3842 "name": "leases4" 3843 }, 3844 3845 "valid-lifetime": 4000, 3846 3847 "subnet4": [ { 3848 "subnet": "10.10.10.0/24", 3849 "4o6-interface": "eno33554984", 3850 "4o6-subnet": "2001:db8:1:1::/64", 3851 "pools": [ { "pool": "10.10.10.100 - 10.10.10.199" } ] 3852 } ], 3853 3854 "dhcp4o6-port": 6767, 3855 3856 "loggers": [ { 3857 "name": "kea-dhcp4", 3858 "output_options": [ { 3859 "output": "/tmp/kea-dhcp4.log" 3860 } ], 3861 "severity": "DEBUG", 3862 "debuglevel": 0 3863 } ] 3864 } 3865 3866 } 3867 3868.. _sanity-checks4: 3869 3870Sanity Checks in DHCPv4 3871----------------------- 3872 3873An important aspect of a well-running DHCP system is an assurance that 3874the data remain consistent. However, in some cases it may be convenient 3875to tolerate certain inconsistent data. For example, a network 3876administrator that temporarily removes a subnet from a configuration 3877would not want all the leases associated with it to disappear from the 3878lease database. Kea has a mechanism to control sanity checks such 3879as this. 3880 3881Kea supports a configuration scope called ``sanity-checks``. It 3882currently allows only a single parameter, called ``lease-checks``, which 3883governs the verification carried out when a new lease is loaded from a 3884lease file. This mechanism permits Kea to attempt to correct inconsistent data. 3885 3886Every subnet has a ``subnet-id`` value; this is how Kea internally 3887identifies subnets. Each lease has a ``subnet-id`` parameter as well, which 3888identifies which subnet it belongs to. However, if the configuration has 3889changed, it is possible that a lease could exist with a ``subnet-id``, but 3890without any subnet that matches it. Also, it is possible that the 3891subnet's configuration has changed and the ``subnet-id`` now belongs to a 3892subnet that does not match the lease. 3893 3894Kea's corrective algorithm first 3895checks to see if there is a subnet with the ``subnet-id`` specified by the 3896lease. If there is, it verifies whether the lease belongs to that 3897subnet. If not, depending on the ``lease-checks`` setting, the lease is 3898discarded, a warning is displayed, or a new subnet is selected for the 3899lease that matches it topologically. 3900 3901There are five levels which are supported: 3902 3903- ``none`` - do no special checks; accept the lease as is. 3904 3905- ``warn`` - if problems are detected display a warning, but 3906 accept the lease data anyway. This is the default value. 3907 3908- ``fix`` - if a data inconsistency is discovered, try to 3909 correct it. If the correction is not successful, insert the incorrect data 3910 anyway. 3911 3912- ``fix-del`` - if a data inconsistency is discovered, try to 3913 correct it. If the correction is not successful, reject the lease. 3914 This setting ensures the data's correctness, but some 3915 incorrect data may be lost. Use with care. 3916 3917- ``del`` - if any inconsistency is 3918 detected, reject the lease. This is the strictest mode; use with care. 3919 3920This feature is currently implemented for the memfile backend. The 3921sanity check applies to the lease database in memory, not to the lease file, 3922i.e. inconsistent leases will stay in the lease file. 3923 3924An example configuration that sets this parameter looks as follows: 3925 3926:: 3927 3928 "Dhcp4": { 3929 "sanity-checks": { 3930 "lease-checks": "fix-del" 3931 }, 3932 ... 3933 } 3934 3935.. _dhcp4-store-extended-info: 3936 3937Storing Extended Lease Information 3938---------------------------------- 3939 3940To support such features as DHCP Leasequery 3941(`RFC 4388 <https://tools.ietf.org/html/rfc4388>`__) 3942additional information must be stored with each lease. Kea does not 3943currently offer a Leasequery hook library, but other hook libraries 3944may already be using ``user-context``. 3945 3946Because the amount 3947of information for each lease has ramifications in terms of 3948performance and system resource consumption, storing this additional 3949information is configurable through the ``store-extended-info`` parameter. 3950It defaults to ``false`` and may be set at the global, shared-network, and 3951subnet levels. 3952 3953:: 3954 3955 "Dhcp4": { 3956 "store-extended-info": true, 3957 ... 3958 } 3959 3960When set to ``true``, information relevant to the DHCPREQUEST asking for the lease is 3961added into the lease's user-context as a map element labeled `"ISC"`. Currently, 3962the map contains a single value, the ``relay-agent-info`` option (DHCP Option 82), 3963when the DHCPREQUEST received contains it. Since DHCPREQUESTs sent as renewals will likely not contain this 3964information, the values taken from the last DHCPREQUEST that did contain it will 3965be retained on the lease. The lease's user-context will look something like this: 3966 3967:: 3968 3969 { "ISC": { "relay-agent-info": "0x52050104AABBCCDD" } } 3970 3971.. note:: 3972 As mentioned above, it is possible that other hook libraries are already using ``user-context``. 3973 Enabling ``store-extended-info`` should not interfere with any other ``user-context`` 3974 content, as long as it does not also use an element labeled `"ISC"`. In other 3975 words, ``user-context`` is intended to be a flexible container serving multiple 3976 purposes. As long as no other purpose also writes an `"ISC"` element to 3977 user-context there should not be a conflict. 3978 3979.. _dhcp4-multi-threading-settings: 3980 3981Multi-Threading Settings 3982------------------------ 3983 3984The Kea server can be configured to process packets in parallel using multiple 3985threads. These settings can be found under the ``multi-threading`` structure and are 3986represented by: 3987 3988- ``enable-multi-threading`` - use multiple threads to process packets in 3989 parallel (default false). 3990 3991- ``thread-pool-size`` - specify the number of threads to process packets in 3992 parallel. It may be set to 0 (auto-detect), or any positive number explicitly sets 3993 the thread count. The default is 0. 3994 3995- ``packet-queue-size`` - specify the size of the queue used by the thread 3996 pool to process packets. It may be set to 0 (unlimited), or any positive 3997 number explicitly sets the queue size. The default is 64. 3998 3999An example configuration that sets these parameters looks as follows: 4000 4001:: 4002 4003 "Dhcp4": { 4004 "multi-threading": { 4005 "enable-multi-threading": true, 4006 "thread-pool-size": 4, 4007 "packet-queue-size": 16 4008 } 4009 ... 4010 } 4011 4012Multi-Threading Settings in Different Backends 4013---------------------------------------------- 4014 4015Both ``kea-dhcp4`` and ``kea-dhcp6`` are tested internally to determine which settings 4016give the best performance. Although this section describes our results, they are just 4017recommendations and are very dependent on the particular hardware that was used 4018for testing. We strongly advise that administrators run their own performance tests. 4019 4020A full report of performance results for the latest stable Kea can be found 4021`here <https://reports.kea.isc.org/>`_. 4022This includes hardware and test scenario descriptions, as well as 4023current results. 4024 4025After enabling multi-threading, the number of threads is set by the ``thread-pool-size`` 4026parameter. Results from our tests show that the best settings for 4027``kea-dhcp4`` are: 4028 4029- ``thread-pool-size``: 4 when using ``memfile`` for storing leases. 4030 4031- ``thread-pool-size``: 12 or more when using ``mysql`` for storing leases. 4032 4033- ``thread-pool-size``: 8 when using ``postgresql``. 4034 4035Another very important parameter is ``packet-queue-size``; in our tests we 4036used it as a multiplier of ``thread-pool-size``. So the actual setting strongly depends 4037on ``thread-pool-size``. 4038 4039We saw the best results in our tests with the following settings: 4040 4041- ``packet-queue-size``: 7 * ``thread-pool-size`` when using ``memfile`` for 4042 storing leases; in our case it was 7 * 4 = 28. This means that at any given 4043 time, up to 28 packets could be queued. 4044 4045- ``packet-queue-size``: 66 * ``thread-pool-size`` when using ``mysql`` for 4046 storing leases; in our case it was 66 * 12 = 792. This means that up to 4047 792 packets could be queued. 4048 4049- ``packet-queue-size``: 11 * ``thread-pool-size`` when using ``postgresql`` for 4050 storing leases; in our case it was 11 * 8 = 88. 4051 4052IPv6-Only Preferred Networks 4053---------------------------- 4054 4055`RFC8925 <https://tools.ietf.org/html/rfc8925>`_, recently published by the IETF, 4056specifies a DHCPv4 option to indicate that a host supports an IPv6-only mode and is willing to 4057forgo obtaining an IPv4 address if the network provides IPv6 connectivity. The general idea is that 4058a network administrator can enable this option to signal to compatible dual-stack devices that 4059IPv6 connectivity is available and they can shut down their IPv4 stack. The new option 4060``v6-only-preferred`` content is a 32-bit unsigned integer and specifies for how long the device 4061should disable its stack. The value is expressed in seconds. 4062 4063The RFC mentions the ``V6ONLY_WAIT`` timer. This is implemented in Kea by setting the value of 4064the ``v6-only-preferred`` option. This follows the usual practice of setting options; the 4065option value can be specified on the pool, subnet, shared network, or global levels, or even 4066via host reservations. 4067 4068There is no special processing involved; it follows the standard Kea option processing 4069regime. The option is not sent back unless the client explicitly requests it. For example, to 4070enable the option for the whole subnet, the following configuration can be used: 4071 4072:: 4073 4074 "subnet4": [ 4075 { 4076 "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ], 4077 "subnet": "192.0.2.0/24", 4078 "option-data": [ 4079 { 4080 // This will make the v6-only capable devices to disable their 4081 // v4 stack for half an hour and then try again 4082 "name": "v6-only-preferred", 4083 "data": "1800" 4084 } 4085 ] 4086 } 4087 ], 4088 4089Lease Caching 4090------------- 4091 4092Clients that attempt multiple renewals in a short period can cause the server to update 4093and write to the database frequently, resulting in a performance impact 4094on the server. The cache parameters instruct the DHCP server to avoid 4095updating leases too frequently, thus avoiding this behavior. Instead, 4096the server assigns the same lease (i.e. reuses it) with no 4097modifications except for CLTT (Client Last Transmission Time), which 4098does not require disk operations. 4099 4100The two parameters are the ``cache-threshold`` double and the 4101``cache-max-age`` integer; they have no default setting, i.e. the lease caching 4102feature must be explicitly enabled. These parameters can be configured 4103at the global, shared network, and subnet levels. The subnet level has 4104precedence over the shared network level, while the global level is used 4105as a last resort. For example: 4106 4107:: 4108 4109 "subnet4": [ 4110 { 4111 "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ], 4112 "subnet": "192.0.2.0/24", 4113 "cache-threshold": .25, 4114 "cache-max-age": 600, 4115 "valid-lifetime": 2000, 4116 ... 4117 } 4118 ], 4119 4120When an already assigned lease can fulfill a client query: 4121 4122 - any important change, e.g. for DDNS parameter, hostname, or 4123 valid lifetime reduction, makes the lease not reusable. 4124 4125 - lease age, i.e. the difference between the creation or last modification 4126 time and the current time, is computed (elapsed duration). 4127 4128 - if ``cache-max-age`` is explicitly configured, it is compared with the lease age; 4129 leases that are too old are not reusable. This means that the value 0 4130 for ``cache-max-age`` disables the lease cache feature. 4131 4132 - if ``cache-threshold`` is explicitly configured and is between 0.0 and 1.0, 4133 it expresses the percentage of the lease valid lifetime which is 4134 allowed for the lease age. Values below and including 0.0 and 4135 values greater than 1.0 disable the lease cache feature. 4136 4137In our example, a lease with a valid lifetime of 2000 seconds can be 4138reused if it was committed less than 500 seconds ago. With a lifetime 4139of 3000 seconds, the maximum age of 600 seconds applies. 4140 4141In outbound client responses (e.g. DHCPACK messages), the 4142``dhcp-lease-time`` option is set to the reusable valid lifetime, 4143i.e. the expiration date does not change. Other options based on the 4144valid lifetime e.g. ``dhcp-renewal-time`` and ``dhcp-rebinding-time``, 4145also depend on the reusable lifetime. 4146 4147.. _host-reservation-v4: 4148 4149Host Reservation in DHCPv4 4150========================== 4151 4152There are many cases where it is useful to provide a configuration on a 4153per-host basis. The most obvious one is to reserve a specific, static 4154address for exclusive use by a given client (host); the returning client 4155receives the same address from the server every time, and other 4156clients generally do not receive that address. Another situation when 4157host reservations are applicable is when a host has 4158specific requirements, e.g. a printer that needs additional DHCP 4159options. Yet another possible use case is to define unique names for 4160hosts. 4161 4162There may be cases when a new reservation has been made for a 4163client for an address currently in use by another client. We call this 4164situation a "conflict." 4165These conflicts get resolved automatically over time as described in 4166subsequent sections. Once the conflict is resolved, the correct client will 4167receive the reserved configuration when it renews. 4168 4169Host reservations are defined as parameters for each subnet. Each host 4170must have its own unique identifier, such as the hardware/MAC 4171address. There is an optional ``reservations`` array in the ``subnet4`` 4172structure; each element in that array is a structure that holds 4173information about reservations for a single host. In particular, the 4174structure must have a unique host identifier. In 4175the DHCPv4 context, the identifier is usually a hardware or MAC address. 4176In most cases an IP address will be specified. It is also possible to 4177specify a hostname, host-specific options, or fields carried within the 4178DHCPv4 message such as ``siaddr``, ``sname``, or ``file``. 4179 4180.. note:: 4181 4182 Kea versions 1.7.10 and newer require that the reserved address must 4183 be within the subnet. 4184 4185The following example shows how to reserve addresses for specific hosts 4186in a subnet: 4187 4188:: 4189 4190 "subnet4": [ 4191 { 4192 "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ], 4193 "subnet": "192.0.2.0/24", 4194 "interface": "eth0", 4195 "reservations": [ 4196 { 4197 "hw-address": "1a:1b:1c:1d:1e:1f", 4198 "ip-address": "192.0.2.202" 4199 }, 4200 { 4201 "duid": "0a:0b:0c:0d:0e:0f", 4202 "ip-address": "192.0.2.100", 4203 "hostname": "alice-laptop" 4204 }, 4205 { 4206 "circuit-id": "'charter950'", 4207 "ip-address": "192.0.2.203" 4208 }, 4209 { 4210 "client-id": "01:11:22:33:44:55:66", 4211 "ip-address": "192.0.2.204" 4212 } 4213 ] 4214 } 4215 ] 4216 4217The first entry reserves the 192.0.2.202 address for the client that 4218uses a MAC address of 1a:1b:1c:1d:1e:1f. The second entry reserves the 4219address 192.0.2.100 and the hostname of `alice-laptop` for the client 4220using a DUID 0a:0b:0c:0d:0e:0f. (If DNS updates are planned, 4221it is strongly recommended that the hostnames be unique.) The 4222third example reserves address 192.0.3.203 for a client whose request 4223would be relayed by a relay agent that inserts a ``circuit-id`` option with 4224the value `"charter950"`. The fourth entry reserves address 192.0.2.204 4225for a client that uses a client identifier with value 422601:11:22:33:44:55:66. 4227 4228The above example is used for illustrational purposes only; in actual 4229deployments it is recommended to use as few types as possible 4230(preferably just one). See :ref:`reservations4-tuning` for a detailed discussion of this 4231point. 4232 4233Making a reservation for a mobile host that may visit multiple subnets 4234requires a separate host definition in each subnet that host is expected to 4235visit. It is not possible to define multiple host definitions with the 4236same hardware address in a single subnet. Multiple host definitions with 4237the same hardware address are valid if each is in a different subnet. 4238 4239Adding host reservations incurs a performance penalty. In principle, when 4240a server that does not support host reservation responds to a query, it 4241needs to check whether there is a lease for a given address being 4242considered for allocation or renewal. The server that does support host 4243reservation has to perform additional checks: not only whether the 4244address is currently used (i.e., if there is a lease for it), but also 4245whether the address could be used by someone else (i.e., if there is a 4246reservation for it). That additional check incurs extra overhead. 4247 4248.. _reservation4-types: 4249 4250Address Reservation Types 4251------------------------- 4252 4253In a typical scenario there is an IPv4 subnet defined, e.g. 4254192.0.2.0/24, with a certain part of it dedicated for dynamic allocation 4255by the DHCPv4 server. That dynamic part is referred to as a dynamic pool 4256or simply a pool. In principle, a host reservation can reserve any 4257address that belongs to the subnet. The reservations that specify 4258addresses that belong to configured pools are called "in-pool 4259reservations." In contrast, those that do not belong to dynamic pools 4260are called "out-of-pool reservations." There is no formal difference in 4261the reservation syntax and both reservation types are handled uniformly. 4262 4263Kea supports global host reservations. These are reservations that are 4264specified at the global level within the configuration and that do not 4265belong to any specific subnet. Kea will still match inbound client 4266packets to a subnet as before, but when the subnet's reservation mode is 4267set to ``"global"``, Kea looks for host reservations only among the 4268global reservations defined. Typically, such reservations would be used 4269to reserve hostnames for clients which may move from one subnet to 4270another. 4271 4272.. note:: 4273 4274 Global reservations, while useful in certain circumstances, have aspects 4275 that must be given due consideration when using them. Please see 4276 :ref:`reservation4-conflict` for more details. 4277 4278.. note:: 4279 4280 Since Kea 1.9.1, reservation mode has been replaced by three 4281 boolean flags, ``"reservations-global"``, ``"reservations-in-subnet"``, 4282 and ``"reservations-out-of-pool"``, which allow the configuration of 4283 host reservations both globally and in a subnet. In such cases a subnet 4284 host reservation has preference over a global reservation 4285 when both exist for the same client. 4286 4287.. _reservation4-conflict: 4288 4289Conflicts in DHCPv4 Reservations 4290-------------------------------- 4291 4292As reservations and lease information are stored separately, conflicts 4293may arise. Consider the following series of events: the server has 4294configured the dynamic pool of addresses from the range of 192.0.2.10 to 4295192.0.2.20. Host A requests an address and gets 192.0.2.10. Now the 4296system administrator decides to reserve address 192.0.2.10 for Host B. 4297In general, reserving an address that is currently assigned to someone 4298else is not recommended, but there are valid use cases where such an 4299operation is warranted. 4300 4301The server now has a conflict to resolve. If Host B boots up and 4302requests an address, the server is not able to assign the reserved 4303address 192.0.2.10. A naive approach would to be immediately remove the 4304existing lease for Host A and create a new one for Host B. That would 4305not solve the problem, though, because as soon as Host B gets the 4306address, it will detect that the address is already in use (by Host A) and 4307will send a DHCPDECLINE message. Therefore, in this situation, the 4308server has to temporarily assign a different address from the dynamic 4309pool (not matching what has been reserved) to Host B. 4310 4311When Host A renews its address, the server will discover that the 4312address being renewed is now reserved for another host - Host B. 4313The server will inform Host A that it is no longer allowed to 4314use it by sending a DHCPNAK message. The server will not remove the 4315lease, though, as there's a small chance that the DHCPNAK will not be delivered if 4316the network is lossy. If that happens, the client will not receive any 4317responses, so it will retransmit its DHCPREQUEST packet. Once the 4318DHCPNAK is received by Host A, it will revert to server discovery and 4319will eventually get a different address. Besides allocating a new lease, 4320the server will also remove the old one. As a result, address 192.0.2.10 4321will become free. 4322 4323When Host B tries to renew its temporarily assigned 4324address, the server will detect that it has a valid lease, but will note 4325that there is a reservation for a different address. The server will 4326send DHCPNAK to inform Host B that its address is no longer usable, but 4327will keep its lease (again, the DHCPNAK may be lost, so the server will 4328keep it until the client returns for a new address). Host B will revert 4329to the server discovery phase and will eventually send a DHCPREQUEST 4330message. This time the server will find that there is a reservation for 4331that host and that the reserved address 192.0.2.10 is not used, so it 4332will be granted. It will also remove the lease for the temporarily 4333assigned address that Host B previously obtained. 4334 4335This recovery will succeed, even if other hosts attempt to get the 4336reserved address. If Host C requests the address 192.0.2.10 after the 4337reservation is made, the server will either offer a different address 4338(when responding to DHCPDISCOVER) or send DHCPNAK (when responding to 4339DHCPREQUEST). 4340 4341This mechanism allows the server to fully recover from a case 4342where reservations conflict with existing leases; however, this procedure 4343takes roughly as long as the value set for ``renew-timer``. The 4344best way to avoid such a recovery is not to define new reservations that 4345conflict with existing leases. Another recommendation is to use 4346out-of-pool reservations. If the reserved address does not belong to a 4347pool, there is no way that other clients can get it. 4348 4349.. note:: 4350 4351 The conflict-resolution mechanism does not work for global 4352 reservations. Although the global address reservations feature may be useful 4353 in certain settings, it is generally recommended not to use 4354 global reservations for addresses. Administrators who do choose 4355 to use global reservations must manually ensure that the reserved 4356 addresses are not in dynamic pools. 4357 4358.. _reservation4-hostname: 4359 4360Reserving a Hostname 4361-------------------- 4362 4363When the reservation for a client includes the ``hostname``, the server 4364returns this hostname to the client in the Client FQDN or Hostname 4365option. The server responds with the Client FQDN option only if the 4366client has included the Client FQDN option in its message to the server. The 4367server responds with the Hostname option if the client included 4368the Hostname option in its message to the server, or if the client 4369requested the Hostname option using the Parameter Request List option. 4370The server returns the Hostname option even if it is not configured 4371to perform DNS updates. The reserved hostname always takes precedence 4372over the hostname supplied by the client or the autogenerated (from the 4373IPv4 address) hostname. 4374 4375The server qualifies the reserved hostname with the value of the 4376``ddns-qualifying-suffix`` parameter. For example, the following subnet 4377configuration: 4378 4379:: 4380 4381 { 4382 "subnet4": [ { 4383 "subnet": "10.0.0.0/24", 4384 "pools": [ { "pool": "10.0.0.10-10.0.0.100" } ], 4385 "ddns-qualifying-suffix": "example.isc.org.", 4386 "reservations": [ 4387 { 4388 "hw-address": "aa:bb:cc:dd:ee:ff", 4389 "hostname": "alice-laptop" 4390 } 4391 ] 4392 }], 4393 "dhcp-ddns": { 4394 "enable-updates": true, 4395 } 4396 } 4397 4398will result in assigning the `"alice-laptop.example.isc.org."` hostname to 4399the client using the MAC address "aa:bb:cc:dd:ee:ff". If the 4400``ddns-qualifying-suffix`` is not specified, the default (empty) value will 4401be used, and in this case the value specified as a ``hostname`` will be 4402treated as a fully qualified name. Thus, by leaving the 4403``ddns-qualifying-suffix`` empty it is possible to qualify hostnames for 4404different clients with different domain names: 4405 4406:: 4407 4408 { 4409 "subnet4": [ { 4410 "subnet": "10.0.0.0/24", 4411 "pools": [ { "pool": "10.0.0.10-10.0.0.100" } ], 4412 "reservations": [ 4413 { 4414 "hw-address": "aa:bb:cc:dd:ee:ff", 4415 "hostname": "alice-laptop.isc.org." 4416 }, 4417 { 4418 "hw-address": "12:34:56:78:99:AA", 4419 "hostname": "mark-desktop.example.org." 4420 } 4421 4422 ] 4423 }], 4424 "dhcp-ddns": { 4425 "enable-updates": true, 4426 } 4427 } 4428 4429.. _reservation4-options: 4430 4431Including Specific DHCPv4 Options in Reservations 4432------------------------------------------------- 4433 4434Kea offers the ability to specify options on a per-host basis. These 4435options follow the same rules as any other options. These can be 4436standard options (see :ref:`dhcp4-std-options`), 4437custom options (see :ref:`dhcp4-custom-options`), 4438or vendor-specific options (see :ref:`dhcp4-vendor-opts`). The following 4439example demonstrates how standard options can be defined: 4440 4441:: 4442 4443 { 4444 "subnet4": [ { 4445 "reservations": [ 4446 { 4447 "hw-address": "aa:bb:cc:dd:ee:ff", 4448 "ip-address": "192.0.2.1", 4449 "option-data": [ 4450 { 4451 "name": "cookie-servers", 4452 "data": "10.1.1.202,10.1.1.203" 4453 }, 4454 { 4455 "name": "log-servers", 4456 "data": "10.1.1.200,10.1.1.201" 4457 } ] 4458 } ] 4459 } ] 4460 } 4461 4462Vendor-specific options can be reserved in a similar manner: 4463 4464:: 4465 4466 { 4467 "subnet4": [ { 4468 "reservations": [ 4469 { 4470 "hw-address": "aa:bb:cc:dd:ee:ff", 4471 "ip-address": "10.0.0.7", 4472 "option-data": [ 4473 { 4474 "name": "vivso-suboptions", 4475 "data": "4491" 4476 }, 4477 { 4478 "name": "tftp-servers", 4479 "space": "vendor-4491", 4480 "data": "10.1.1.202,10.1.1.203" 4481 } ] 4482 } ] 4483 } ] 4484 } 4485 4486Options defined at the host level have the highest priority. In other words, 4487if there are options defined with the same type on the global, subnet, 4488class, and host levels, the host-specific values are used. 4489 4490.. _reservation4-message-fields: 4491 4492Reserving Next Server, Server Hostname, and Boot File Name 4493---------------------------------------------------------- 4494 4495BOOTP/DHCPv4 messages include `"siaddr"`, `"sname"`, and `"file"` fields. Even 4496though DHCPv4 includes corresponding options, such as option 66 and 4497option 67, some clients may not support these options. For this reason, 4498server administrators often use the `"siaddr"`, `"sname"`, and `"file"` fields 4499instead. 4500 4501With Kea, it is possible to make static reservations for these DHCPv4 4502message fields: 4503 4504:: 4505 4506 { 4507 "subnet4": [ { 4508 "reservations": [ 4509 { 4510 "hw-address": "aa:bb:cc:dd:ee:ff", 4511 "next-server": "10.1.1.2", 4512 "server-hostname": "server-hostname.example.org", 4513 "boot-file-name": "/tmp/bootfile.efi" 4514 } ] 4515 } ] 4516 } 4517 4518Note that those parameters can be specified in combination with other 4519parameters for a reservation, such as a reserved IPv4 address. These 4520parameters are optional; a subset of them can be specified, or all 4521of them can be omitted. 4522 4523.. _reservation4-client-classes: 4524 4525Reserving Client Classes in DHCPv4 4526---------------------------------- 4527 4528:ref:`classification-using-expressions` explains how to configure 4529the server to assign classes to a client, based on the content of the 4530options that this client sends to the server. Host reservation 4531mechanisms also allow for the static assignment of classes to clients. 4532The definitions of these classes are placed in the Kea configuration or 4533a database. The following configuration snippet shows how to specify that 4534a client belongs to the classes ``reserved-class1`` and ``reserved-class2``. Those 4535classes are associated with specific options sent to the clients which belong 4536to them. 4537 4538:: 4539 4540 { 4541 "client-classes": [ 4542 { 4543 "name": "reserved-class1", 4544 "option-data": [ 4545 { 4546 "name": "routers", 4547 "data": "10.0.0.200" 4548 } 4549 ] 4550 }, 4551 { 4552 "name": "reserved-class2", 4553 "option-data": [ 4554 { 4555 "name": "domain-name-servers", 4556 "data": "10.0.0.201" 4557 } 4558 ] 4559 } 4560 ], 4561 "subnet4": [ { 4562 "subnet": "10.0.0.0/24", 4563 "pools": [ { "pool": "10.0.0.10-10.0.0.100" } ], 4564 "reservations": [ 4565 { 4566 "hw-address": "aa:bb:cc:dd:ee:ff", 4567 4568 "client-classes": [ "reserved-class1", "reserved-class2" ] 4569 4570 } 4571 ] 4572 } ] 4573 } 4574 4575In some cases the host reservations can be used in conjunction with client 4576classes specified within the Kea configuration. In particular, when a 4577host reservation exists for a client within a given subnet, the `"KNOWN"` 4578built-in class is assigned to the client. Conversely, when there is no 4579static assignment for the client, the `"UNKNOWN"` class is assigned to the 4580client. Class expressions within the Kea configuration file can 4581refer to `"KNOWN"` or `"UNKNOWN"` classes using the `"member"` operator. 4582For example: 4583 4584:: 4585 4586 { 4587 "client-classes": [ 4588 { 4589 "name": "dependent-class", 4590 "test": "member('KNOWN')", 4591 "only-if-required": true 4592 } 4593 ] 4594 } 4595 4596Note that the ``only-if-required`` parameter is needed here to force 4597evaluation of the class after the lease has been allocated and thus the 4598reserved class has been also assigned. 4599 4600.. note:: 4601 The classes specified in non-global host reservations 4602 are assigned to the processed packet after all classes with the 4603 ``only-if-required`` parameter set to ``false`` have been evaluated. 4604 This means that these classes must not depend on the 4605 statically assigned classes from the host reservations. If there 4606 is a need to create such a dependency, the ``only-if-required`` parameter must 4607 be set to ``true`` for the dependent classes. Such classes are 4608 evaluated after the static classes have been assigned to the packet. 4609 This, however, imposes additional configuration overhead, because 4610 all classes marked as ``only-if-required`` must be listed in the 4611 ``require-client-classes`` list for every subnet where they are used. 4612 4613.. note:: 4614 Client classes specified within the Kea configuration file may 4615 depend on the classes specified within the global host reservations. 4616 In such a case the ``only-if-required`` parameter is not needed. 4617 Refer to :ref:`pool-selection-with-class-reservations4` and 4618 :ref:`subnet-selection-with-class-reservations4` 4619 for the specific use cases. 4620 4621.. _reservations4-mysql-pgsql-cql: 4622 4623Storing Host Reservations in MySQL, PostgreSQL, or Cassandra 4624------------------------------------------------------------ 4625 4626Kea can store host reservations in MySQL, PostgreSQL, or 4627Cassandra. See :ref:`hosts4-storage` for information on how to 4628configure Kea to use reservations stored in MySQL, PostgreSQL, or 4629Cassandra. Kea provides a dedicated hook for managing reservations in a 4630database; section :ref:`host-cmds` provides detailed information. 4631The `Kea wiki 4632<https://gitlab.isc.org/isc-projects/kea/wikis/designs/commands#23-host-reservations-hr-management>`__ 4633provides some examples of how to conduct common host reservation 4634operations. 4635 4636.. note:: 4637 4638 In Kea, the maximum length of an option specified per-host is 4639 arbitrarily set to 4096 bytes. 4640 4641.. _reservations4-tuning: 4642 4643Fine-Tuning DHCPv4 Host Reservation 4644----------------------------------- 4645 4646The host reservation capability introduces additional restrictions for 4647the allocation engine (the component of Kea that selects an address for 4648a client) during lease selection and renewal. In particular, three major 4649checks are necessary. First, when selecting a new lease, it is not 4650sufficient for a candidate lease to simply not be in use by another DHCP 4651client; it also must not be reserved for another client. Second, when 4652renewing a lease, an additional check must be performed to see whether 4653the address being renewed is reserved for another client. Finally, when 4654a host renews an address, the server must check whether there is a 4655reservation for this host, which would mean the existing (dynamically allocated) 4656address should be revoked and the reserved one be used instead. 4657 4658Some of those checks may be unnecessary in certain deployments, and not 4659performing them may improve performance. The Kea server provides the 4660``reservation-mode`` configuration parameter to select the types of 4661reservations allowed for a particular subnet. Each reservation type has 4662different constraints for the checks to be performed by the server when 4663allocating or renewing a lease for the client. Allowed values are: 4664 4665- ``all`` - enables both in-pool and out-of-pool host reservation 4666 types. This setting is the default value, and is the safest and most 4667 flexible. However, as all checks are conducted, it is also the slowest. 4668 It does not check against global reservations. 4669 4670- ``out-of-pool`` - allows only out-of-pool host reservations. With 4671 this setting in place, the server may assume that all host 4672 reservations are for addresses that do not belong to the dynamic 4673 pool. Therefore, it can skip the reservation checks when dealing with 4674 in-pool addresses, thus improving performance. Do not use this mode 4675 if any reservations use in-pool addresses. Caution is advised 4676 when using this setting; Kea does not sanity-check the reservations 4677 against ``reservation-mode`` and misconfiguration may cause problems. 4678 4679- ``global`` - allows only global host reservations. With this setting 4680 in place, the server searches for reservations for a client only 4681 among the defined global reservations. If an address is specified, 4682 the server skips the reservation checks carried out when dealing in 4683 other modes, thus improving performance. Caution is advised when 4684 using this setting; Kea does not sanity-check reservations when 4685 ``global`` is set, and misconfiguration may cause problems. 4686 4687- ``disabled`` - host reservation support is disabled. As there are no 4688 reservations, the server skips all checks. Any reservations 4689 defined are completely ignored. As checks are skipped, the 4690 server may operate faster in this mode. 4691 4692Since Kea 1.9.1, the ``reservation-mode`` parameter is replaced by the 4693``reservations-global``, ``reservations-in-subnet``, and 4694``reservations-out-of-pool`` flags. 4695The flags can be activated independently and can produce various combinations, 4696some of which were not supported by the deprecated ``reservation-mode``. 4697 4698The ``reservation-mode`` parameter can be specified at: 4699 4700- global level: ``.Dhcp4["reservation-mode"]`` (lowest priority: gets overridden 4701 by all others) 4702 4703- subnet level: ``.Dhcp4.subnet4[]["reservation-mode"]`` (low priority) 4704 4705- shared-network level: ``.Dhcp4["shared-networks"][]["reservation-mode"]`` 4706 (high priority) 4707 4708- shared-network subnet-level: 4709 ``.Dhcp4["shared-networks"][].subnet4[]["reservation-mode"]`` (highest 4710 priority: overrides all others) 4711 4712To decide which ``"reservation-mode"`` to choose, the 4713following decision diagram may be useful: 4714 4715:: 4716 4717 O 4718 | 4719 v 4720 +-----------------------------+------------------------------+ 4721 | Is per-host configuration needed, such as | 4722 | reserving specific addresses, | 4723 | assigning specific options or | 4724 | assigning packets to specific classes on per-device basis? | 4725 +-+-----------------+----------------------------------------+ 4726 | | 4727 no| yes| 4728 | | +--------------------------------------+ 4729 | | | For all given hosts, | 4730 +--> "disabled" +-->+ can the reserved resources | 4731 | be used in all configured subnets? | 4732 +--------+---------------------------+-+ 4733 | | 4734 +----------------------------+ |no |yes 4735 | Is | | | 4736 | at least one reservation +<--+ "global" <--+ 4737 | used to reserve addresses? | 4738 +-+------------------------+-+ 4739 | | 4740 no| yes| +---------------------------+ 4741 | | | Is high leases-per-second | 4742 +--> "out-of-pool" +-->+ performance or efficient | 4743 ^ | resource usage | 4744 | | (CPU ticks, RAM usage, | 4745 | | database roundtrips) | 4746 | | important to your setup? | 4747 | +-+----------------+--------+ 4748 | | | 4749 | yes| no| 4750 | | | 4751 | +-------------+ | 4752 | | | 4753 | | +----------------------+ | 4754 | | | Can it be guaranteed | | 4755 | +-->+ that the reserved | | 4756 | | addresses | | 4757 | | aren't part of the | | 4758 | | pools configured | | 4759 | | in the respective | | 4760 | | subnet? | | 4761 | +-+------------------+-+ | 4762 | | | | 4763 | yes| no| | 4764 | | | V 4765 +----------------+ +--> "all" 4766 4767An example configuration that disables reservations looks as follows: 4768 4769.. code-block:: json 4770 4771 { 4772 "Dhcp4": { 4773 "subnet4": [ 4774 { 4775 "pools": [ 4776 { 4777 "pool": "192.0.2.10-192.0.2.100" 4778 } 4779 ], 4780 "reservation-mode": "disabled", 4781 "subnet": "192.0.2.0/24" 4782 } 4783 ] 4784 } 4785 } 4786 4787An example configuration using global reservations is shown below: 4788 4789.. code-block:: json 4790 4791 { 4792 "Dhcp4": { 4793 "reservation-mode": "global", 4794 "reservations": [ 4795 { 4796 "hostname": "host-one", 4797 "hw-address": "01:bb:cc:dd:ee:ff" 4798 }, 4799 { 4800 "hostname": "host-two", 4801 "hw-address": "02:bb:cc:dd:ee:ff" 4802 } 4803 ], 4804 "subnet4": [ 4805 { 4806 "pools": [ 4807 { 4808 "pool": "192.0.2.10-192.0.2.100" 4809 } 4810 ], 4811 "subnet": "192.0.2.0/24" 4812 } 4813 ] 4814 } 4815 } 4816 4817The meaning of the reservation flags are: 4818 4819- ``reservations-global``: fetch global reservations. 4820 4821- ``reservations-in-subnet``: fetch subnet reservations. For a shared network 4822 this includes all subnet members of the shared network. 4823 4824- ``reservations-out-of-pool``: this makes sense only when the 4825 ``reservations-in-subnet`` flag is ``true``. When ``reservations-out-of-pool`` 4826 is ``true``, the server may assume that all host reservations are for addresses 4827 that do not belong to the dynamic pool. Therefore, it can skip the reservation 4828 checks when dealing with in-pool addresses, thus improving performance. 4829 The server will not assign reserved addresses that are inside the dynamic 4830 pools to the respective clients. This also means that the addresses matching 4831 the respective reservations from inside the dynamic pools (if any) can be 4832 dynamically assigned to any client. 4833 4834The ``disabled`` value from the deprecated ``reservation-mode`` corresponds to: 4835 4836.. code-block:: json 4837 4838 { 4839 "Dhcp4": { 4840 "reservations-global": false, 4841 "reservations-in-subnet": false 4842 } 4843 } 4844 4845The ``global`` value from the deprecated ``reservation-mode`` corresponds to: 4846 4847.. code-block:: json 4848 4849 { 4850 "Dhcp4": { 4851 "reservations-global": true, 4852 "reservations-in-subnet": false 4853 } 4854 } 4855 4856The ``out-of-pool`` value from the deprecated ``reservation-mode`` corresponds to: 4857 4858.. code-block:: json 4859 4860 { 4861 "Dhcp4": { 4862 "reservations-global": false, 4863 "reservations-in-subnet": true, 4864 "reservations-out-of-pool": true 4865 } 4866 } 4867 4868And the ``all`` value from the deprecated ``reservation-mode`` corresponds to: 4869 4870.. code-block:: json 4871 4872 { 4873 "Dhcp4": { 4874 "reservations-global": false, 4875 "reservations-in-subnet": true, 4876 "reservations-out-of-pool": false 4877 } 4878 } 4879 4880To activate both ``global`` and ``all``, the following combination can be used: 4881 4882.. code-block:: json 4883 4884 { 4885 "Dhcp4": { 4886 "reservations-global": true, 4887 "reservations-in-subnet": true, 4888 "reservations-out-of-pool": false 4889 } 4890 } 4891 4892To activate both ``global`` and ``out-of-pool``, the following combination can 4893be used: 4894 4895.. code-block:: json 4896 4897 { 4898 "Dhcp4": { 4899 "reservations-global": true, 4900 "reservations-in-subnet": true, 4901 "reservations-out-of-pool": true 4902 } 4903 } 4904 4905Note that enabling ``out-of-pool`` and disabling ``in-subnet`` at the same time 4906is not recommended because ``out-of-pool`` applies to host reservations in a 4907subnet, which are fetched only when the ``in-subnet`` flag is true. 4908 4909The parameter can be specified at the global, subnet, and shared-network 4910levels. 4911 4912An example configuration that disables reservations looks as follows: 4913 4914.. code-block:: json 4915 4916 { 4917 "Dhcp4": { 4918 "subnet4": [ 4919 { 4920 "reservations-global": false, 4921 "reservations-in-subnet": false, 4922 "subnet": "192.0.2.0/24" 4923 } 4924 ] 4925 } 4926 } 4927 4928An example configuration using global reservations is shown below: 4929 4930.. code-block:: json 4931 4932 { 4933 "Dhcp4": { 4934 "reservations": [ 4935 { 4936 "hostname": "host-one", 4937 "hw-address": "01:bb:cc:dd:ee:ff" 4938 }, 4939 { 4940 "hostname": "host-two", 4941 "hw-address": "02:bb:cc:dd:ee:ff" 4942 } 4943 ], 4944 "reservations-global": true, 4945 "reservations-in-subnet": false, 4946 "subnet4": [ 4947 { 4948 "pools": [ 4949 { 4950 "pool": "192.0.2.10-192.0.2.100" 4951 } 4952 ], 4953 "subnet": "192.0.2.0/24" 4954 } 4955 ] 4956 } 4957 } 4958 4959For more details regarding global reservations, see :ref:`global-reservations4`. 4960 4961Another aspect of host reservations is the different types of 4962identifiers. Kea currently supports four types of identifiers: 4963``hw-address``, ``duid``, ``client-id``, and ``circuit-id``. This is beneficial from a 4964usability perspective; however, there is one drawback. For each incoming 4965packet, Kea has to extract each identifier type and then query the 4966database to see if there is a reservation by this particular identifier. 4967If nothing is found, the next identifier is extracted and the next query 4968is issued. This process continues until either a reservation is found or 4969all identifier types have been checked. Over time, with an increasing 4970number of supported identifier types, Kea would become slower and 4971slower. 4972 4973To address this problem, a parameter called 4974``host-reservation-identifiers`` is available. It takes a list of 4975identifier types as a parameter. Kea checks only those identifier 4976types enumerated in ``host-reservation-identifiers``. From a performance 4977perspective, the number of identifier types should be kept to a minimum, 4978ideally one. If the deployment uses several reservation types, please 4979enumerate them from most- to least-frequently used, as this increases 4980the chances of Kea finding the reservation using the fewest queries. An 4981example of a ``host-reservation-identifiers`` configuration looks as follows: 4982 4983:: 4984 4985 "host-reservation-identifiers": [ "circuit-id", "hw-address", "duid", "client-id" ], 4986 "subnet4": [ 4987 { 4988 "subnet": "192.0.2.0/24", 4989 ... 4990 } 4991 ] 4992 4993If not specified, the default value is: 4994 4995:: 4996 4997 "host-reservation-identifiers": [ "hw-address", "duid", "circuit-id", "client-id" ] 4998 4999.. _global-reservations4: 5000 5001Global Reservations in DHCPv4 5002----------------------------- 5003 5004In some deployments, such as mobile, clients can roam within the network 5005and certain parameters must be specified regardless of the client's 5006current location. To meet such a need, Kea offers a global reservation 5007mechanism. The idea behind it is that regular host 5008reservations are tied to specific subnets, by using a specific 5009subnet ID. Kea can specify a global reservation that can be used in 5010every subnet that has global reservations enabled. 5011 5012This feature can be used to assign certain parameters, such as hostname 5013or other dedicated, host-specific options. It can also be used to assign 5014addresses. However, global reservations that assign addresses bypass the 5015whole topology determination provided by the DHCP logic implemented in Kea. 5016It is very easy to misuse this feature and get a configuration that is 5017inconsistent. To give a specific example, imagine a global reservation 5018for address 192.0.2.100 and two subnets 192.0.2.0/24 and 192.0.5.0/24. 5019If global reservations are used in both subnets and a device matching 5020global host reservations visits part of the network that is serviced by 5021192.0.5.0/24, it will get an IP address 192.0.2.100, a subnet 192.0.5.0, 5022and a default router 192.0.5.1. Obviously, such a configuration is 5023unusable, as the client will not be able to reach its default gateway. 5024 5025To use global host reservations, a configuration similar to the 5026following can be used: 5027 5028:: 5029 5030 "Dhcp4:" { 5031 # This specifies global reservations. 5032 # They will apply to all subnets that 5033 # have global reservations enabled. 5034 5035 "reservations": [ 5036 { 5037 "hw-address": "aa:bb:cc:dd:ee:ff", 5038 "hostname": "hw-host-dynamic" 5039 }, 5040 { 5041 "hw-address": "01:02:03:04:05:06", 5042 "hostname": "hw-host-fixed", 5043 5044 # Use of IP addresses in global reservations is risky. 5045 # If used outside of a matching subnet, such as 192.0.1.0/24, 5046 # it will result in a broken configuration being handed 5047 # to the client. 5048 "ip-address": "192.0.1.77" 5049 }, 5050 { 5051 "duid": "01:02:03:04:05", 5052 "hostname": "duid-host" 5053 }, 5054 { 5055 "circuit-id": "'charter950'", 5056 "hostname": "circuit-id-host" 5057 }, 5058 { 5059 "client-id": "01:11:22:33:44:55:66", 5060 "hostname": "client-id-host" 5061 } 5062 ], 5063 "valid-lifetime": 600, 5064 "subnet4": [ { 5065 "subnet": "10.0.0.0/24", 5066 # It is replaced by the "reservations-global" 5067 # "reservations-in-subnet" and "reservations-out-of-pool" 5068 # parameters. 5069 # "reservation-mode": "global", 5070 # Specify if the server should lookup global reservations. 5071 "reservations-global": true, 5072 # Specify if the server should lookup in-subnet reservations. 5073 "reservations-in-subnet": false, 5074 # Specify if the server can assume that all reserved addresses 5075 # are out-of-pool. It can be ignored because "reservations-in-subnet" 5076 # is false. 5077 # "reservations-out-of-pool": false, 5078 "pools": [ { "pool": "10.0.0.10-10.0.0.100" } ] 5079 } ] 5080 } 5081 5082When using database backends, the global host reservations are 5083distinguished from regular reservations by using a ``subnet-id`` value of 5084zero. 5085 5086.. _pool-selection-with-class-reservations4: 5087 5088Pool Selection with Client Class Reservations 5089--------------------------------------------- 5090 5091Client classes can be specified in the Kea configuration file and/or via 5092host reservations. The classes specified in the Kea configuration file are 5093evaluated immediately after receiving the DHCP packet and therefore can be 5094used to influence subnet selection using the ``client-class`` parameter 5095specified in the subnet scope. The classes specified within the host 5096reservations are fetched and assigned to the packet after the server has 5097already selected a subnet for the client. This means that the client 5098class specified within a host reservation cannot be used to influence 5099subnet assignment for this client, unless the subnet belongs to a 5100shared network. If the subnet belongs to a shared network, the server may 5101dynamically change the subnet assignment while trying to allocate a lease. 5102If the subnet does not belong to a shared network, the subnet 5103is not changed once selected. 5104 5105If the subnet does not belong to a shared network, it is possible to 5106use host reservation-based client classification to select an address pool 5107within the subnet as follows: 5108 5109:: 5110 5111 "Dhcp4": { 5112 "client-classes": [ 5113 { 5114 "name": "reserved_class" 5115 }, 5116 { 5117 "name": "unreserved_class", 5118 "test": "not member('reserved_class')" 5119 } 5120 ], 5121 "subnet4": [ 5122 { 5123 "subnet": "192.0.2.0/24", 5124 "reservations": [{" 5125 "hw-address": "aa:bb:cc:dd:ee:fe", 5126 "client-classes": [ "reserved_class" ] 5127 }], 5128 "pools": [ 5129 { 5130 "pool": "192.0.2.10-192.0.2.20", 5131 "client-class": "reserved_class" 5132 }, 5133 { 5134 "pool": "192.0.2.30-192.0.2.40", 5135 "client-class": "unreserved_class" 5136 } 5137 ] 5138 } 5139 ] 5140 } 5141 5142The ``reserved_class`` is declared without the ``test`` parameter because 5143it may only be assigned to the client via the host reservation mechanism. The 5144second class, ``unreserved_class``, is assigned to the clients which do not 5145belong to the ``reserved_class``. The first pool within the subnet is only 5146used for clients having a reservation for the ``reserved_class``. The 5147second pool is used for clients not having such a reservation. The 5148configuration snippet includes one host reservation which causes the client 5149with the MAC address aa:bb:cc:dd:ee:fe to be assigned to the 5150``reserved_class``. Thus, this client will be given an IP address from the 5151first address pool. 5152 5153.. _subnet-selection-with-class-reservations4: 5154 5155Subnet Selection with Client Class Reservations 5156----------------------------------------------- 5157 5158There is one specific use case when subnet selection may be influenced by 5159client classes specified within host reservations: when the 5160client belongs to a shared network. In such a case it is possible to use 5161classification to select a subnet within this shared network. Consider the 5162following example: 5163 5164:: 5165 5166 "Dhcp4": { 5167 "client-classes": [ 5168 { 5169 "name": "reserved_class" 5170 }, 5171 { 5172 "name: "unreserved_class", 5173 "test": "not member('reserved_class')" 5174 } 5175 ], 5176 "reservations": [{" 5177 "hw-address": "aa:bb:cc:dd:ee:fe", 5178 "client-classes": [ "reserved_class" ] 5179 }], 5180 # It is replaced by the "reservations-global" 5181 # "reservations-in-subnet" and "reservations-out-of-pool" parameters. 5182 # Specify if the server should lookup global reservations. 5183 "reservations-global": true, 5184 # Specify if the server should lookup in-subnet reservations. 5185 "reservations-in-subnet": false, 5186 # Specify if the server can assume that all reserved addresses 5187 # are out-of-pool. It can be ignored because "reservations-in-subnet" 5188 # is false, but if specified, it is inherited by "shared-networks" 5189 # and "subnet4" levels. 5190 # "reservations-out-of-pool": false, 5191 "shared-networks": [{ 5192 "subnet4": [ 5193 { 5194 "subnet": "192.0.2.0/24", 5195 "pools": [ 5196 { 5197 "pool": "192.0.2.10-192.0.2.20", 5198 "client-class": "reserved_class" 5199 } 5200 ] 5201 }, 5202 { 5203 "subnet": "192.0.3.0/24", 5204 "pools": [ 5205 { 5206 "pool": "192.0.3.10-192.0.3.20", 5207 "client-class": "unreserved_class" 5208 } 5209 ] 5210 } 5211 ] 5212 }] 5213 } 5214 5215This is similar to the example described in 5216:ref:`pool-selection-with-class-reservations4`. This time, however, there 5217are two subnets, each of which has a pool associated with a different 5218class. The clients that do not have a reservation for the ``reserved_class`` 5219are assigned an address from the subnet 192.0.3.0/24. Clients with 5220a reservation for the ``reserved_class`` are assigned an address from 5221the subnet 192.0.2.0/24. The subnets must belong to the same shared network. 5222In addition, the reservation for the client class must be specified at the 5223global scope (global reservation) and ``reservations-global`` must be 5224set to ``true``. 5225 5226In the example above, the ``client-class`` could also be specified at the 5227subnet level rather than the pool level, and would yield the same effect. 5228 5229.. _multiple-reservations-same-ip4: 5230 5231Multiple Reservations for the Same IP 5232------------------------------------- 5233 5234Host reservations were designed to preclude the creation of multiple 5235reservations for the same IP address within a particular subnet, to avoid 5236having two different clients compete for the same address. 5237When using the default settings, the server returns a configuration error 5238when it finds two or more reservations for the same IP address within 5239a subnet in the Kea configuration file. The :ref:`host-cmds` hook 5240library returns an error in response to the ``reservation-add`` command 5241when it detects that the reservation exists in the database for the IP 5242address for which the new reservation is being added. 5243 5244In some deployments a single host can select one of several network 5245interfaces to communicate with the DHCP server, and the server must assign 5246the same IP address to the host regardless of the interface used. Since 5247each interface is assigned a different MAC address, it implies that 5248several host reservations must be created to associate all of the MAC 5249addresses present on this host with IP addresses. Using different 5250IP addresses for each interface is impractical and is considered a waste 5251of the IPv4 address space, especially since the host typically uses only one 5252interface for communication with the server, hence only one IP address 5253is in use. 5254 5255This causes a need to create multiple host reservations for a single 5256IP address within a subnet; this is supported beginning with the Kea 1.9.1 5257release as an optional mode of operation, enabled with the 5258``ip-reservations-unique`` global parameter. 5259 5260``ip-reservations-unique`` is a boolean parameter that defaults to 5261``true``, which forbids the specification of more than one reservation 5262for the same IP address within a given subnet. Setting this parameter to 5263``false`` allows such reservations to be created both in the Kea configuration 5264file and in the host database backend, via the ``host-cmds`` hook library. 5265 5266This setting is currently supported by the most popular host database 5267backends, i.e. MySQL and PostgreSQL. It is not supported for Cassandra, 5268Host Cache (see :ref:`hooks-host-cache`), or the RADIUS backend 5269(see :ref:`hooks-radius`). An attempt to set ``ip-reservations-unique`` 5270to ``false`` when any of these three backends is in use yields a 5271configuration error. 5272 5273.. note:: 5274 5275 When ``ip-reservations-unique`` is set to ``true`` (the default value), 5276 the server ensures that IP reservations are unique for a subnet within 5277 a single host backend and/or Kea configuration file. It does not 5278 guarantee that the reservations are unique across multiple backends. 5279 5280The following is an example configuration with two reservations for 5281the same IP address but different MAC addresses: 5282 5283:: 5284 5285 "Dhcp4": { 5286 "ip-reservations-unique": false, 5287 "subnet4": [ 5288 { 5289 "subnet": "192.0.2.0/24", 5290 "reservations": [ 5291 { 5292 "hw-address": "1a:1b:1c:1d:1e:1f", 5293 "ip-address": "192.0.2.11" 5294 }, 5295 { 5296 "hw-address": "2a:2b:2c:2d:2e:2f", 5297 "ip-address": "192.0.2.11" 5298 } 5299 ] 5300 } 5301 ] 5302 } 5303 5304It is possible to control the ``ip-reservations-unique`` parameter via the 5305:ref:`dhcp4-cb`. If the new setting of this parameter conflicts with 5306the currently used backends (backends do not support the new setting), 5307the new setting is ignored and a warning log message is generated. 5308The backends continue to use the default setting, expecting that 5309IP reservations are unique within each subnet. To allow the 5310creation of non-unique IP reservations, the administrator must remove 5311the backends which lack support for them from the configuration file. 5312 5313Administrators must be careful when they have been using multiple 5314reservations for the same IP address and later decide to return to 5315the default mode in which this is no longer allowed. Admins 5316must make sure that at most one reservation for a given IP address 5317exists within a subnet, prior to switching back to the default mode. 5318If such duplicates are left in the configuration file, the server 5319reports a configuration error. Leaving such reservations in the host 5320databases does not cause configuration errors but may lead to lease 5321allocation errors during the server's operation, when it unexpectedly 5322finds multiple reservations for the same IP address. 5323 5324.. note:: 5325 5326 Currently the server does not verify whether multiple reservations for 5327 the same IP address exist in MySQL and/or 5328 PostgreSQL host databases when ``ip-reservations-unique`` is updated from 5329 ``true`` to ``false``. This may cause issues with lease allocations. 5330 The administrator must ensure that there is at most one reservation 5331 for each IP address within each subnet, prior to the configuration 5332 update. 5333 5334.. _shared-network4: 5335 5336Shared Networks in DHCPv4 5337========================= 5338 5339DHCP servers use subnet information in two ways. It is used to 5340both determine the point of attachment, i.e. where the client is 5341connected to the network, and to 5342group information pertaining to a specific location in the network. 5343However, it is sometimes useful to have more than one 5344logical IP subnet deployed on the same physical link. 5345Understanding that two or more subnets are used on the same link requires 5346additional logic in the DHCP server. This capability is called "shared 5347networks" in Kea, and sometimes also 5348"shared subnets"; in Microsoft's nomenclature it is called "multinet." 5349 5350There are many use cases where the feature is useful; here we 5351explain just a handful of the most common ones. The first and by far 5352most common use case is an existing network that has grown and is 5353running out of available address space. Rather than migrating all 5354devices to a new, larger subnet, it is easier to simply configure 5355additional subnets on top of the existing one. Sometimes, due to address 5356space fragmentation (e.g. only many disjointed /24s are available), this 5357is the only choice. Also, configuring additional subnets has the 5358advantage of not disrupting the operation of existing devices. 5359 5360Another very frequent use case comes from cable networks. There are two 5361types of devices in cable networks: cable modems and the end-user 5362devices behind them. It is a common practice to use different subnets 5363for cable modems to prevent users from tinkering with them. In this 5364case, the distinction is based on the type of device, rather than 5365on address-space exhaustion. 5366 5367A client connected to a shared network may be assigned an address from 5368any of the pools defined within the subnets belonging to the shared 5369network. Internally, the server selects one of the subnets belonging to 5370a shared network and tries to allocate an address from this subnet. If 5371the server is unable to allocate an address from the selected subnet 5372(e.g., due to address-pool exhaustion), it uses another subnet from 5373the same shared network and tries to allocate an address from this subnet. 5374The server typically allocates all 5375addresses available in a given subnet before it starts allocating 5376addresses from other subnets belonging to the same shared network. 5377However, in certain situations the client can be allocated an address 5378from another subnet before the address pools in the first subnet get 5379exhausted; this sometimes occurs when the client provides a hint that belongs to another 5380subnet, or the client has reservations in a subnet other than the 5381default. 5382 5383.. note:: 5384 5385 Deployments should not assume that Kea waits until it has allocated 5386 all the addresses from the first subnet in a shared network before 5387 allocating addresses from other subnets. 5388 5389In order to define a shared network an additional configuration scope is 5390introduced: 5391 5392:: 5393 5394 { 5395 "Dhcp4": { 5396 "shared-networks": [ 5397 { 5398 # Name of the shared network. It may be an arbitrary string 5399 # and it must be unique among all shared networks. 5400 "name": "my-secret-lair-level-1", 5401 5402 # The subnet selector can be specified at the shared network level. 5403 # Subnets from this shared network will be selected for directly 5404 # connected clients sending requests to the server's "eth0" interface. 5405 "interface": "eth0", 5406 5407 # This starts a list of subnets in this shared network. 5408 # There are two subnets in this example. 5409 "subnet4": [ 5410 { 5411 "subnet": "10.0.0.0/8", 5412 "pools": [ { "pool": "10.0.0.1 - 10.0.0.99" } ], 5413 }, 5414 { 5415 "subnet": "192.0.2.0/24", 5416 "pools": [ { "pool": "192.0.2.100 - 192.0.2.199" } ] 5417 } 5418 ], 5419 } ], # end of shared-networks 5420 5421 # It is likely that in the network there will be a mix of regular, 5422 # "plain" subnets and shared networks. It is perfectly valid to mix 5423 # them in the same configuration file. 5424 # 5425 # This is a regular subnet. It is not part of any shared network. 5426 "subnet4": [ 5427 { 5428 "subnet": "192.0.3.0/24", 5429 "pools": [ { "pool": "192.0.3.1 - 192.0.3.200" } ], 5430 "interface": "eth1" 5431 } 5432 ] 5433 5434 } # end of Dhcp4 5435 } 5436 5437As demonstrated in the example, it is possible to mix shared and regular 5438("plain") subnets. Each shared network must have a unique name. This is 5439similar to the ID for subnets, but gives administrators more 5440flexibility. It is used for logging, but also internally for identifying 5441shared networks. 5442 5443In principle it makes sense to define only shared networks that consist 5444of two or more subnets. However, for testing purposes, an empty subnet 5445or a network with just a single subnet is allowed. This is not a 5446recommended practice in production networks, as the shared network logic 5447requires additional processing and thus lowers the server's performance. 5448To avoid unnecessary performance degradation, the shared subnets should 5449only be defined when required by the deployment. 5450 5451Shared networks provide the ability to specify many parameters in the 5452shared network scope that apply to all subnets within it. If 5453necessary, it is possible to specify a parameter in the shared network scope and 5454then override its value in the subnet scope. For example: 5455 5456:: 5457 5458 "shared-networks": [ 5459 { 5460 "name": "lab-network3", 5461 5462 "interface": "eth0", 5463 5464 # This applies to all subnets in this shared network, unless 5465 # values are overridden on subnet scope. 5466 "valid-lifetime": 600, 5467 5468 # This option is made available to all subnets in this shared 5469 # network. 5470 "option-data": [ { 5471 "name": "log-servers", 5472 "data": "1.2.3.4" 5473 } ], 5474 5475 "subnet4": [ 5476 { 5477 "subnet": "10.0.0.0/8", 5478 "pools": [ { "pool": "10.0.0.1 - 10.0.0.99" } ], 5479 5480 # This particular subnet uses different values. 5481 "valid-lifetime": 1200, 5482 "option-data": [ 5483 { 5484 "name": "log-servers", 5485 "data": "10.0.0.254" 5486 }, 5487 { 5488 "name": "routers", 5489 "data": "10.0.0.254" 5490 } ] 5491 }, 5492 { 5493 "subnet": "192.0.2.0/24", 5494 "pools": [ { "pool": "192.0.2.100 - 192.0.2.199" } ], 5495 5496 # This subnet does not specify its own valid-lifetime value, 5497 # so it is inherited from shared network scope. 5498 "option-data": [ 5499 { 5500 "name": "routers", 5501 "data": "192.0.2.1" 5502 } ] 5503 } 5504 ] 5505 } ] 5506 5507In this example, there is a `"log-servers"` option defined that is available 5508to clients in both subnets in this shared network. Also, the valid 5509lifetime is set to 10 minutes (600s). However, the first subnet 5510overrides some of the values (the valid lifetime is 20 minutes, there is a different IP 5511address for `"log-servers"`), but also adds its own option (the router address). 5512Assuming a client asking for router and `"log-servers"` options is assigned 5513a lease from this subnet, it will get a lease for 20 minutes and a 5514`"log-servers"` and routers value of 10.0.0.254. If the same client is 5515assigned to the second subnet, it will get a 10-minute lease, a 5516`"log-servers"` value of 1.2.3.4, and routers set to 192.0.2.1. 5517 5518Local and Relayed Traffic in Shared Networks 5519-------------------------------------------- 5520 5521It is possible to specify an interface name at the shared network level, 5522to tell the server that this specific shared network is reachable 5523directly (not via relays) using the local network interface. As all 5524subnets in a shared network are expected to be used on the same physical 5525link, it is a configuration error to attempt to define a shared network 5526using subnets that are reachable over different interfaces. In other 5527words, all subnets within the shared network must have the same value 5528of the `"interface"` parameter. The following configuration is an 5529example of what **NOT** to do: 5530 5531:: 5532 5533 "shared-networks": [ 5534 { 5535 "name": "office-floor-2", 5536 "subnet4": [ 5537 { 5538 "subnet": "10.0.0.0/8", 5539 "pools": [ { "pool": "10.0.0.1 - 10.0.0.99" } ], 5540 "interface": "eth0" 5541 }, 5542 { 5543 "subnet": "192.0.2.0/24", 5544 "pools": [ { "pool": "192.0.2.100 - 192.0.2.199" } ], 5545 5546 # Specifying the different interface name is a configuration 5547 # error. This value should rather be "eth0" or the interface 5548 # name in the other subnet should be "eth1". 5549 "interface": "eth1" 5550 } 5551 ] 5552 } ] 5553 5554To minimize the chance of configuration errors, it is often more convenient 5555to simply specify the interface name once, at the shared network level, as 5556shown in the example below. 5557 5558:: 5559 5560 "shared-networks": [ 5561 { 5562 "name": "office-floor-2", 5563 5564 # This tells Kea that the whole shared network is reachable over a 5565 # local interface. This applies to all subnets in this network. 5566 "interface": "eth0", 5567 5568 "subnet4": [ 5569 { 5570 "subnet": "10.0.0.0/8", 5571 "pools": [ { "pool": "10.0.0.1 - 10.0.0.99" } ], 5572 }, 5573 { 5574 "subnet": "192.0.2.0/24", 5575 "pools": [ { "pool": "192.0.2.100 - 192.0.2.199" } ] 5576 } 5577 ] 5578 } ] 5579 5580 5581With relayed traffic, subnets are typically selected using 5582the relay agents' addresses. If the subnets are used independently (not 5583grouped within a shared network), a different relay 5584address can be specified for each of these subnets. When multiple subnets belong to a 5585shared network they must be selected via the same relay address and, 5586similarly to the case of the local traffic described above, it is a 5587configuration error to specify different relay addresses for the respective 5588subnets in the shared network. The following configuration is another example 5589of what **NOT** to do: 5590 5591:: 5592 5593 "shared-networks": [ 5594 { 5595 "name": "kakapo", 5596 "subnet4": [ 5597 { 5598 "subnet": "192.0.2.0/26", 5599 "relay": { 5600 "ip-addresses": [ "192.1.1.1" ] 5601 }, 5602 "pools": [ { "pool": "192.0.2.63 - 192.0.2.63" } ] 5603 }, 5604 { 5605 "subnet": "10.0.0.0/24", 5606 "relay": { 5607 # Specifying a different relay address for this 5608 # subnet is a configuration error. In this case 5609 # it should be 192.1.1.1 or the relay address 5610 # in the previous subnet should be 192.2.2.2. 5611 "ip-addresses": [ "192.2.2.2" ] 5612 }, 5613 "pools": [ { "pool": "10.0.0.16 - 10.0.0.16" } ] 5614 } 5615 ] 5616 } 5617 ] 5618 5619Again, it is better to specify the relay address at the shared network 5620level; this value will be inherited by all subnets belonging to the 5621shared network. 5622 5623:: 5624 5625 "shared-networks": [ 5626 { 5627 "name": "kakapo", 5628 "relay": { 5629 # This relay address is inherited by both subnets. 5630 "ip-addresses": [ "192.1.1.1" ] 5631 }, 5632 "subnet4": [ 5633 { 5634 "subnet": "192.0.2.0/26", 5635 "pools": [ { "pool": "192.0.2.63 - 192.0.2.63" } ] 5636 }, 5637 { 5638 "subnet": "10.0.0.0/24", 5639 "pools": [ { "pool": "10.0.0.16 - 10.0.0.16" } ] 5640 } 5641 ] 5642 } 5643 ] 5644 5645Even though it is technically possible to configure two (or more) subnets 5646within the shared network to use different relay addresses, this will almost 5647always lead to a different behavior than what the user expects. In this 5648case, the Kea server will initially select one of the subnets by matching 5649the relay address in the client's packet with the subnet's configuration. 5650However, it MAY end up using the other subnet (even though it does not match 5651the relay address) if the client already has a lease in this subnet or has a 5652host reservation in this subnet, or simply if the initially selected subnet has no 5653more addresses available. Therefore, it is strongly recommended to always 5654specify subnet selectors (interface or relay address) at the shared-network 5655level if the subnets belong to a shared network, as it is rarely useful to 5656specify them at the subnet level and it may lead to the configuration errors 5657described above. 5658 5659Client Classification in Shared Networks 5660---------------------------------------- 5661 5662Sometimes it is desirable to segregate clients into specific subnets 5663based on certain properties. This mechanism is called client 5664classification and is described in :ref:`classify`. Client 5665classification can be applied to subnets belonging to shared networks in 5666the same way as it is used for subnets specified outside of shared 5667networks. It is important to understand how the server selects subnets 5668for clients when client classification is in use, to ensure that the 5669appropriate subnet is selected for a given client type. 5670 5671If a subnet is associated with a class, only the clients belonging to 5672this class can use this subnet. If there are no classes specified for a 5673subnet, any client connected to a given shared network can use this 5674subnet. A common mistake is to assume that a subnet including a client 5675class is preferred over subnets without client classes. Consider the 5676following example: 5677 5678:: 5679 5680 { 5681 "client-classes": [ 5682 { 5683 "name": "b-devices", 5684 "test": "option[93].hex == 0x0002" 5685 } 5686 ], 5687 "shared-networks": [ 5688 { 5689 "name": "galah", 5690 "interface": "eth0", 5691 "subnet4": [ 5692 { 5693 "subnet": "192.0.2.0/26", 5694 "pools": [ { "pool": "192.0.2.1 - 192.0.2.63" } ], 5695 }, 5696 { 5697 "subnet": "10.0.0.0/24", 5698 "pools": [ { "pool": "10.0.0.2 - 10.0.0.250" } ], 5699 "client-class": "b-devices" 5700 } 5701 ] 5702 } 5703 ] 5704 } 5705 5706If the client belongs to the `"b-devices"` class (because it includes 5707option 93 with a value of 0x0002), that does not guarantee that the 5708subnet 10.0.0.0/24 will be used (or preferred) for this client. The 5709server can use either of the two subnets, because the subnet 192.0.2.0/26 5710is also allowed for this client. The client classification used in this 5711case should be perceived as a way to restrict access to certain subnets, 5712rather than a way to express subnet preference. For example, if the 5713client does not belong to the `"b-devices"` class, it may only use the 5714subnet 192.0.2.0/26 and will never use the subnet 10.0.0.0/24. 5715 5716A typical use case for client classification is in a cable network, 5717where cable modems should use one subnet and other devices should use 5718another subnet within the same shared network. In this case it is 5719necessary to apply classification on all subnets. The following example 5720defines two classes of devices, and the subnet selection is made based 5721on option 93 values. 5722 5723:: 5724 5725 { 5726 "client-classes": [ 5727 { 5728 5729 "name": "a-devices", 5730 "test": "option[93].hex == 0x0001" 5731 }, 5732 { 5733 "name": "b-devices", 5734 "test": "option[93].hex == 0x0002" 5735 } 5736 ], 5737 "shared-networks": [ 5738 { 5739 "name": "galah", 5740 "interface": "eth0", 5741 "subnet4": [ 5742 { 5743 "subnet": "192.0.2.0/26", 5744 "pools": [ { "pool": "192.0.2.1 - 192.0.2.63" } ], 5745 "client-class": "a-devices" 5746 }, 5747 { 5748 "subnet": "10.0.0.0/24", 5749 "pools": [ { "pool": "10.0.0.2 - 10.0.0.250" } ], 5750 "client-class": "b-devices" 5751 } 5752 ] 5753 } 5754 ] 5755 } 5756 5757In this example each class has its own restriction. Only clients that 5758belong to class `"a-devices"` are able to use subnet 192.0.2.0/26 and 5759only clients belonging to `"b-devices"` are able to use subnet 576010.0.0.0/24. Care should be taken not to define too-restrictive 5761classification rules, as clients that are unable to use any subnets will 5762be refused service. However, this may be a desired outcome if one wishes 5763to provide service only to clients with known properties (e.g. only VoIP 5764phones allowed on a given link). 5765 5766Note that it is possible to achieve an effect similar to the one 5767presented in this section without the use of shared networks. If the 5768subnets are placed in the global subnets scope, rather than in the 5769shared network, the server will still use classification rules to pick 5770the right subnet for a given class of devices. The major benefit of 5771placing subnets within the shared network is that common parameters for 5772the logically grouped subnets can be specified once in the 5773shared-network scope, e.g. the `"interface"` or `"relay"` parameter. All subnets 5774belonging to this shared network will inherit those parameters. 5775 5776Host Reservations in Shared Networks 5777------------------------------------ 5778 5779Subnets that are part of a shared network allow host reservations, 5780similar to regular subnets: 5781 5782:: 5783 5784 { 5785 "shared-networks": [ 5786 { 5787 "name": "frog", 5788 "interface": "eth0", 5789 "subnet4": [ 5790 { 5791 "subnet": "192.0.2.0/26", 5792 "id": 100, 5793 "pools": [ { "pool": "192.0.2.1 - 192.0.2.63" } ], 5794 "reservations": [ 5795 { 5796 "hw-address": "aa:bb:cc:dd:ee:ff", 5797 "ip-address": "192.0.2.28" 5798 } 5799 ] 5800 }, 5801 { 5802 "subnet": "10.0.0.0/24", 5803 "id": 101, 5804 "pools": [ { "pool": "10.0.0.1 - 10.0.0.254" } ], 5805 "reservations": [ 5806 { 5807 "hw-address": "11:22:33:44:55:66", 5808 "ip-address": "10.0.0.29" 5809 } 5810 ] 5811 } 5812 ] 5813 } 5814 ] 5815 } 5816 5817 5818It is worth noting that Kea conducts additional checks when processing a 5819packet if shared networks are defined. First, instead of simply checking 5820whether there is a reservation for a given client in its initially 5821selected subnet, Kea looks through all subnets in a shared network for a 5822reservation. This is one of the reasons why defining a shared network 5823may impact performance. If there is a reservation for a client in any 5824subnet, that particular subnet is selected for the client. Although 5825it is technically not an error, it is considered bad practice to define 5826reservations for the same host in multiple subnets belonging to the same 5827shared network. 5828 5829While not strictly mandatory, it is strongly recommended to use explicit 5830`"id"` values for subnets if database storage will be used for host 5831reservations. If an ID is not specified, the values for it are 5832auto-generated, i.e. Kea assigns increasing integer values starting from 58331. Thus, the auto-generated IDs are not stable across configuration 5834changes. 5835 5836.. _dhcp4-serverid: 5837 5838Server Identifier in DHCPv4 5839=========================== 5840 5841The DHCPv4 protocol uses a "server identifier" to allow clients to 5842discriminate between several servers present on the same link; this 5843value is an IPv4 address of the server. The server chooses the IPv4 5844address of the interface on which the message from the client (or relay) 5845has been received. A single server instance uses multiple server 5846identifiers if it is receiving queries on multiple interfaces. 5847 5848It is possible to override the default server identifier values by specifying 5849the `"dhcp-server-identifier"` option. This option configuration is only 5850supported at the subnet, shared network, client class, and global levels. It 5851must not be specified at the host-reservation level. 5852When configuring the `"dhcp-server-identifier"` option at client-class level, the 5853class must not set the ``only-if-required`` flag, because this class would not 5854be evaluated before the server determines if the received DHCP message should 5855be accepted for processing. Such classes are evaluated after subnet selection. 5856See :ref:`dhcp4-required-class` for details. 5857 5858The following example demonstrates how to override the server identifier 5859for a subnet: 5860 5861:: 5862 5863 "subnet4": [ 5864 { 5865 "subnet": "192.0.2.0/24", 5866 "option-data": [ 5867 { 5868 "name": "dhcp-server-identifier", 5869 "data": "10.2.5.76" 5870 } 5871 ], 5872 ... 5873 } 5874 ] 5875 5876.. _dhcp4-subnet-selection: 5877 5878How the DHCPv4 Server Selects a Subnet for the Client 5879===================================================== 5880 5881The DHCPv4 server differentiates between directly connected clients, 5882clients trying to renew leases, and clients sending their messages 5883through relays. For directly connected clients, the server checks 5884the configuration for the interface on which the message has been 5885received and, if the server configuration does not match any configured 5886subnet, the message is discarded. 5887 5888Assuming that the server's interface is configured with the IPv4 address 5889192.0.2.3, the server only processes messages received through this 5890interface from a directly connected client if there is a subnet 5891configured to which this IPv4 address belongs, such as 192.0.2.0/24. The 5892server uses this subnet to assign an IPv4 address for the client. 5893 5894The rule above does not apply when the client unicasts its message, i.e. 5895is trying to renew its lease; such a message is accepted through any 5896interface. The renewing client sets ``ciaddr`` to the currently used IPv4 5897address, and the server uses this address to select the subnet for the 5898client (in particular, to extend the lease using this address). 5899 5900If the message is relayed it is accepted through any interface. The 5901``giaddr`` set by the relay agent is used to select the subnet for the 5902client. 5903 5904It is also possible to specify a relay IPv4 address for a given subnet. 5905It can be used to match incoming packets into a subnet in uncommon 5906configurations, e.g. shared networks. See :ref:`dhcp4-relay-override` for details. 5907 5908.. note:: 5909 5910 The subnet selection mechanism described in this section is based on 5911 the assumption that client classification is not used. The 5912 classification mechanism alters the way in which a subnet is selected 5913 for the client, depending on the classes to which the client belongs. 5914 5915.. note:: 5916 5917 Starting with Kea 1.7.9, the order used to find a subnet which matches 5918 required conditions to be selected is the ascending subnet identifier 5919 order. When the selected subnet is a member of a shared network, the 5920 whole shared network is selected. 5921 5922.. _dhcp4-relay-override: 5923 5924Using a Specific Relay Agent for a Subnet 5925----------------------------------------- 5926 5927A relay must have an interface connected to the link on which the 5928clients are being configured. Typically the relay has an IPv4 address 5929configured on that interface, which belongs to the subnet from which the 5930server assigns addresses. Normally, the server is able to use the 5931IPv4 address inserted by the relay (in the ``giaddr`` field of the DHCPv4 5932packet) to select the appropriate subnet. 5933 5934However, that is not always the case. In certain uncommon — but valid — 5935deployments, the relay address may not match the subnet. This usually 5936means that there is more than one subnet allocated for a given link. The 5937two most common examples where this is the case are long-lasting network 5938renumbering (where both old and new address space is still being used) 5939and a cable network. In a cable network, both cable modems and the 5940devices behind them are physically connected to the same link, yet they 5941use distinct addressing. In such a case, the DHCPv4 server needs 5942additional information (the IPv4 address of the relay) to properly 5943select an appropriate subnet. 5944 5945The following example assumes that there is a subnet 192.0.2.0/24 that 5946is accessible via a relay that uses 10.0.0.1 as its IPv4 address. The 5947server is able to select this subnet for any incoming packets that come 5948from a relay that has an address in the 192.0.2.0/24 subnet. It also 5949selects that subnet for a relay with address 10.0.0.1. 5950 5951:: 5952 5953 "Dhcp4": { 5954 "subnet4": [ 5955 { 5956 "subnet": "192.0.2.0/24", 5957 "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ], 5958 "relay": { 5959 "ip-addresses": [ "10.0.0.1" ] 5960 }, 5961 } 5962 ], 5963 } 5964 5965If `"relay"` is specified, the `"ip-addresses"` parameter within it is 5966mandatory. The `"ip-addresses"` parameter supports specifying a list of addresses. 5967 5968.. _dhcp4-srv-example-client-class-relay: 5969 5970Segregating IPv4 Clients in a Cable Network 5971------------------------------------------- 5972 5973In certain cases, it is useful to mix relay address information 5974(introduced in :ref:`dhcp4-relay-override`), with client classification (explained 5975in :ref:`classify`). One specific example is in a cable network, 5976where modems typically get addresses from a different subnet than all 5977the devices connected behind them. 5978 5979Let us assume that there is one Cable Modem Termination System (CMTS)) 5980with one CM MAC (a physical link that modems are connected to). We want 5981the modems to get addresses from the 10.1.1.0/24 subnet, while 5982everything connected behind the modems should get addresses from the 5983192.0.2.0/24 subnet. The CMTS that acts as a relay uses address 598410.1.1.1. The following configuration can serve that configuration: 5985 5986:: 5987 5988 "Dhcp4": { 5989 "subnet4": [ 5990 { 5991 "subnet": "10.1.1.0/24", 5992 "pools": [ { "pool": "10.1.1.2 - 10.1.1.20" } ], 5993 "client-class" "docsis3.0", 5994 "relay": { 5995 "ip-addresses": [ "10.1.1.1 ]" 5996 } 5997 }, 5998 { 5999 "subnet": "192.0.2.0/24", 6000 "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ], 6001 "relay": { 6002 "ip-addresses": [ "10.1.1.1" ] 6003 } 6004 } 6005 ], 6006 ... 6007 } 6008 6009.. _dhcp4-decline: 6010 6011Duplicate Addresses (DHCPDECLINE Support) 6012========================================= 6013 6014The DHCPv4 server is configured with a certain pool of addresses that it 6015is expected to hand out to DHCPv4 clients. It is assumed that the server 6016is authoritative and has complete jurisdiction over those addresses. 6017However, for various reasons such as misconfiguration or a faulty 6018client implementation that retains its address beyond the valid 6019lifetime, there may be devices connected that use those addresses 6020without the server's approval or knowledge. 6021 6022Such an unwelcome event can be detected by legitimate clients (using ARP 6023or ICMP Echo Request mechanisms) and reported to the DHCPv4 server using 6024a DHCPDECLINE message. The server does a sanity check (to see whether 6025the client declining an address really was supposed to use it) and then 6026conducts a clean-up operation. Any DNS entries related to that 6027address are removed, the event is logged, and hooks are 6028triggered. After that is complete, the address is marked as 6029declined (which indicates that it is used by an unknown entity and thus 6030not available for assignment) and a probation time is set on it. 6031Unless otherwise configured, the probation period lasts 24 hours; after 6032that period, the server will recover the lease (i.e. put it back into 6033the available state) and the address will be available for assignment 6034again. It should be noted that if the underlying issue of a 6035misconfigured device is not resolved, the duplicate-address scenario 6036will repeat. If reconfigured correctly, this mechanism provides an 6037opportunity to recover from such an event automatically, without any 6038system administrator intervention. 6039 6040To configure the decline probation period to a value other than the 6041default, the following syntax can be used: 6042 6043:: 6044 6045 "Dhcp4": { 6046 "decline-probation-period": 3600, 6047 "subnet4": [ ... ], 6048 ... 6049 } 6050 6051The parameter is expressed in seconds, so the example above 6052instructs the server to recycle declined leases after one hour. 6053 6054There are several statistics and hook points associated with the decline 6055handling procedure. The ``lease4_decline`` hook is triggered after the 6056incoming DHCPDECLINE message has been sanitized and the server is about 6057to decline the lease. The ``declined-addresses`` statistic is increased 6058after the hook returns (both the global and subnet-specific variants). (See 6059:ref:`dhcp4-stats` and :ref:`hooks-libraries` 6060for more details on DHCPv4 statistics and Kea hook points.) 6061 6062Once the probation time elapses, the declined lease is recovered using 6063the standard expired-lease reclamation procedure, with several 6064additional steps. In particular, both ``declined-addresses`` statistics 6065(global and subnet-specific) are decreased. At the same time, 6066``reclaimed-declined-addresses`` statistics (again in two variants, global 6067and subnet-specific) are increased. 6068 6069A note about statistics: The server does not decrease the 6070``assigned-addresses`` statistics when a DHCPDECLINE is received and 6071processed successfully. While technically a declined address is no 6072longer assigned, the primary usage of the ``assigned-addresses`` statistic 6073is to monitor pool utilization. Most people would forget to include 6074``declined-addresses`` in the calculation, and simply use 6075``assigned-addresses``/``total-addresses``. This would cause a bias towards 6076under-representing pool utilization. As this has a potential to cause major 6077issues, ISC decided not to decrease ``assigned-addresses`` immediately after 6078receiving DHCPDECLINE, but to do it later when Kea recovers the address 6079back to the available pool. 6080 6081.. _dhcp4-stats: 6082 6083Statistics in the DHCPv4 Server 6084=============================== 6085 6086The DHCPv4 server supports the following statistics: 6087 6088.. tabularcolumns:: |p{0.2\linewidth}|p{0.1\linewidth}|p{0.7\linewidth}| 6089 6090.. table:: DHCPv4 Statistics 6091 :class: longtable 6092 :widths: 20 10 70 6093 6094 6095 +-------------------------------------------+----------------+------------------------------------+ 6096 | Statistic | Data Type | Description | 6097 +===========================================+================+====================================+ 6098 | pkt4-received | integer | Number of DHCPv4 packets | 6099 | | | received. This includes all | 6100 | | | packets: valid, bogus, | 6101 | | | corrupted, rejected, etc. This | 6102 | | | statistic is expected to grow | 6103 | | | rapidly. | 6104 +-------------------------------------------+----------------+------------------------------------+ 6105 | pkt4-discover-received | integer | Number of | 6106 | | | DHCPDISCOVER packets | 6107 | | | received. This | 6108 | | | statistic is expected | 6109 | | | to grow; its increase | 6110 | | | means that clients | 6111 | | | that just booted | 6112 | | | started their | 6113 | | | configuration process | 6114 | | | and their initial | 6115 | | | packets reached the | 6116 | | | Kea server. | 6117 +-------------------------------------------+----------------+------------------------------------+ 6118 | pkt4-offer-received | integer | Number of DHCPOFFER | 6119 | | | packets received. | 6120 | | | This statistic is | 6121 | | | expected to remain | 6122 | | | zero at all times, as | 6123 | | | DHCPOFFER packets are | 6124 | | | sent by the server | 6125 | | | and the server is | 6126 | | | never expected to | 6127 | | | receive them. A | 6128 | | | non-zero value | 6129 | | | indicates an error. | 6130 | | | One likely cause | 6131 | | | would be a | 6132 | | | misbehaving relay | 6133 | | | agent that | 6134 | | | incorrectly forwards | 6135 | | | DHCPOFFER messages | 6136 | | | towards the server, | 6137 | | | rather than back to | 6138 | | | the clients. | 6139 +-------------------------------------------+----------------+------------------------------------+ 6140 | pkt4-request-received | integer | Number of DHCPREQUEST | 6141 | | | packets received. | 6142 | | | This statistic is | 6143 | | | expected to grow. Its | 6144 | | | increase means that | 6145 | | | clients that just | 6146 | | | booted received the | 6147 | | | server's response | 6148 | | | (DHCPOFFER) and | 6149 | | | accepted it, and are | 6150 | | | now requesting an | 6151 | | | address | 6152 | | | (DHCPREQUEST). | 6153 +-------------------------------------------+----------------+------------------------------------+ 6154 | pkt4-ack-received | integer | Number of DHCPACK | 6155 | | | packets received. | 6156 | | | This statistic is | 6157 | | | expected to remain | 6158 | | | zero at all times, as | 6159 | | | DHCPACK packets are | 6160 | | | sent by the server | 6161 | | | and the server is | 6162 | | | never expected to | 6163 | | | receive them. A | 6164 | | | non-zero value | 6165 | | | indicates an error. | 6166 | | | One likely cause | 6167 | | | would be a | 6168 | | | misbehaving relay | 6169 | | | agent that | 6170 | | | incorrectly forwards | 6171 | | | DHCPACK messages | 6172 | | | towards the server, | 6173 | | | rather than back to | 6174 | | | the clients. | 6175 +-------------------------------------------+----------------+------------------------------------+ 6176 | pkt4-nak-received | integer | Number of DHCPNAK | 6177 | | | packets received. | 6178 | | | This statistic is | 6179 | | | expected to remain | 6180 | | | zero at all times, as | 6181 | | | DHCPNAK packets are | 6182 | | | sent by the server | 6183 | | | and the server is | 6184 | | | never expected to | 6185 | | | receive them. A | 6186 | | | non-zero value | 6187 | | | indicates an error. | 6188 | | | One likely cause | 6189 | | | would be a | 6190 | | | misbehaving relay | 6191 | | | agent that | 6192 | | | incorrectly forwards | 6193 | | | DHCPNAK messages | 6194 | | | towards the server, | 6195 | | | rather than back to | 6196 | | | the clients. | 6197 +-------------------------------------------+----------------+------------------------------------+ 6198 | pkt4-release-received | integer | Number of DHCPRELEASE | 6199 | | | packets received. | 6200 | | | This statistic is | 6201 | | | expected to grow. Its | 6202 | | | increase means that | 6203 | | | clients that had an | 6204 | | | address are shutting | 6205 | | | down or ceasing to | 6206 | | | use their addresses. | 6207 +-------------------------------------------+----------------+------------------------------------+ 6208 | pkt4-decline-received | integer | Number of DHCPDECLINE | 6209 | | | packets received. | 6210 | | | This statistic is | 6211 | | | expected to remain | 6212 | | | close to zero. Its | 6213 | | | increase means that a | 6214 | | | client leased an | 6215 | | | address, but | 6216 | | | discovered that the | 6217 | | | address is currently | 6218 | | | used by an unknown | 6219 | | | device elsewhere in the | 6220 | | | network. | 6221 +-------------------------------------------+----------------+------------------------------------+ 6222 | pkt4-inform-received | integer | Number of DHCPINFORM | 6223 | | | packets received. | 6224 | | | This statistic is | 6225 | | | expected to grow. Its | 6226 | | | increase means that | 6227 | | | there are clients | 6228 | | | that either do not | 6229 | | | need an address or | 6230 | | | already have an | 6231 | | | address and are | 6232 | | | interested only in | 6233 | | | getting additional | 6234 | | | configuration | 6235 | | | parameters. | 6236 +-------------------------------------------+----------------+------------------------------------+ 6237 | pkt4-unknown-received | integer | Number of packets | 6238 | | | received of an | 6239 | | | unknown type. A | 6240 | | | non-zero value of | 6241 | | | this statistic | 6242 | | | indicates that the | 6243 | | | server received a | 6244 | | | packet that it was not | 6245 | | | able to recognize, | 6246 | | | either with an | 6247 | | | unsupported type or | 6248 | | | possibly malformed | 6249 | | | (without a message-type | 6250 | | | option). | 6251 +-------------------------------------------+----------------+------------------------------------+ 6252 | pkt4-sent | integer | Number of DHCPv4 | 6253 | | | packets sent. This | 6254 | | | statistic is expected | 6255 | | | to grow every time | 6256 | | | the server transmits | 6257 | | | a packet. In general, | 6258 | | | it should roughly | 6259 | | | match pkt4-received, | 6260 | | | as most incoming | 6261 | | | packets cause the | 6262 | | | server to respond. | 6263 | | | There are exceptions | 6264 | | | (e.g. DHCPRELEASE), | 6265 | | | so do not worry if it | 6266 | | | is less than | 6267 | | | pkt4-received. | 6268 +-------------------------------------------+----------------+------------------------------------+ 6269 | pkt4-offer-sent | integer | Number of DHCPOFFER | 6270 | | | packets sent. This | 6271 | | | statistic is expected | 6272 | | | to grow in most cases | 6273 | | | after a DHCPDISCOVER | 6274 | | | is processed. There | 6275 | | | are certain uncommon, | 6276 | | | but valid, cases | 6277 | | | where incoming | 6278 | | | DHCPDISCOVER packets | 6279 | | | are dropped, but in | 6280 | | | general this | 6281 | | | statistic is expected | 6282 | | | to be close to | 6283 | | | pkt4-discover-received. | 6284 +-------------------------------------------+----------------+------------------------------------+ 6285 | pkt4-ack-sent | integer | Number of DHCPACK | 6286 | | | packets sent. This | 6287 | | | statistic is expected | 6288 | | | to grow in most cases | 6289 | | | after a DHCPREQUEST | 6290 | | | is processed. There | 6291 | | | are certain cases | 6292 | | | where DHCPNAK is sent | 6293 | | | instead. In general, | 6294 | | | the sum of | 6295 | | | pkt4-ack-sent and | 6296 | | | pkt4-nak-sent should | 6297 | | | be close to | 6298 | | | pkt4-request-received. | 6299 +-------------------------------------------+----------------+------------------------------------+ 6300 | pkt4-nak-sent | integer | Number of DHCPNAK | 6301 | | | packets sent. This | 6302 | | | statistic is expected | 6303 | | | to grow when the | 6304 | | | server chooses not to | 6305 | | | honor the address | 6306 | | | requested by a | 6307 | | | client. In general, | 6308 | | | the sum of | 6309 | | | pkt4-ack-sent and | 6310 | | | pkt4-nak-sent should | 6311 | | | be close to | 6312 | | | pkt4-request-received. | 6313 +-------------------------------------------+----------------+------------------------------------+ 6314 | pkt4-parse-failed | integer | Number of incoming | 6315 | | | packets that could | 6316 | | | not be parsed. A | 6317 | | | non-zero value of | 6318 | | | this statistic | 6319 | | | indicates that the | 6320 | | | server received a | 6321 | | | malformed or | 6322 | | | truncated packet. | 6323 | | | This may indicate | 6324 | | | problems in the | 6325 | | | network, faulty | 6326 | | | clients, or a bug in | 6327 | | | the server. | 6328 +-------------------------------------------+----------------+------------------------------------+ 6329 | pkt4-receive-drop | integer | Number of incoming | 6330 | | | packets that were | 6331 | | | dropped. The exact | 6332 | | | reason for dropping | 6333 | | | packets is logged, | 6334 | | | but the most common | 6335 | | | reasons may be: an | 6336 | | | unacceptable packet | 6337 | | | type was received, direct | 6338 | | | responses are | 6339 | | | forbidden, or the | 6340 | | | server-id sent by the | 6341 | | | client does not match | 6342 | | | the server's | 6343 | | | server-id. | 6344 +-------------------------------------------+----------------+------------------------------------+ 6345 | subnet[id].total-addresses | integer | Total number of | 6346 | | | addresses available | 6347 | | | for DHCPv4 | 6348 | | | management; in other | 6349 | | | words, this is the | 6350 | | | sum of all addresses | 6351 | | | in all configured | 6352 | | | pools. This statistic | 6353 | | | changes only during | 6354 | | | configuration | 6355 | | | updates. It does | 6356 | | | not take into account | 6357 | | | any addresses that | 6358 | | | may be reserved due | 6359 | | | to host reservation. | 6360 | | | The *id* is the | 6361 | | | subnet-id of a given | 6362 | | | subnet. This | 6363 | | | statistic is exposed | 6364 | | | for each subnet | 6365 | | | separately, and is | 6366 | | | reset during a | 6367 | | | reconfiguration | 6368 | | | event. | 6369 +-------------------------------------------+----------------+------------------------------------+ 6370 | cumulative-assigned-addresses | integer | Cumulative number of | 6371 | | | addresses that have been | 6372 | | | assigned since | 6373 | | | server startup. It is | 6374 | | | incremented each time | 6375 | | | an address is assigned and | 6376 | | | is not reset when the server | 6377 | | | is reconfigured. | 6378 +-------------------------------------------+----------------+------------------------------------+ 6379 | subnet[id].cumulative-assigned-addresses | integer | Cumulative number of assigned | 6380 | | | addresses in a given | 6381 | | | subnet. It increases | 6382 | | | every time a new | 6383 | | | lease is allocated | 6384 | | | (as a result of | 6385 | | | receiving a | 6386 | | | DHCPREQUEST message) | 6387 | | | and never decreases. | 6388 | | | The *id* is the subnet-id | 6389 | | | of the subnet. This | 6390 | | | statistic is exposed | 6391 | | | for each subnet | 6392 | | | separately, and is | 6393 | | | reset during a | 6394 | | | reconfiguration | 6395 | | | event. | 6396 +-------------------------------------------+----------------+------------------------------------+ 6397 | subnet[id].assigned-addresses | integer | Number of assigned | 6398 | | | addresses in a given | 6399 | | | subnet. It increases | 6400 | | | every time a new | 6401 | | | lease is allocated | 6402 | | | (as a result of | 6403 | | | receiving a | 6404 | | | DHCPREQUEST message) | 6405 | | | and decreases | 6406 | | | every time a lease is | 6407 | | | released (a | 6408 | | | DHCPRELEASE message | 6409 | | | is received) or | 6410 | | | expires. The *id* is | 6411 | | | the subnet-id of the | 6412 | | | subnet. This | 6413 | | | statistic is exposed | 6414 | | | for each subnet | 6415 | | | separately, and is | 6416 | | | reset during a | 6417 | | | reconfiguration | 6418 | | | event. | 6419 +-------------------------------------------+----------------+------------------------------------+ 6420 | reclaimed-leases | integer | Number of expired | 6421 | | | leases that have been | 6422 | | | reclaimed since | 6423 | | | server startup. It is | 6424 | | | incremented each time | 6425 | | | an expired lease is | 6426 | | | reclaimed and never | 6427 | | | decreases. It can be | 6428 | | | used as a long-term | 6429 | | | indicator of how many | 6430 | | | actual leases have been | 6431 | | | reclaimed. | 6432 | | | This is a global | 6433 | | | statistic that covers | 6434 | | | all subnets. | 6435 +-------------------------------------------+----------------+------------------------------------+ 6436 | subnet[id].reclaimed-leases | integer | Number of expired | 6437 | | | leases associated | 6438 | | | with a given subnet | 6439 | | | (*id* is the | 6440 | | | subnet-id) that have | 6441 | | | been reclaimed since | 6442 | | | server startup. It is | 6443 | | | incremented each time | 6444 | | | an expired lease is | 6445 | | | reclaimed. | 6446 | | | The *id* is the | 6447 | | | subnet-id of a | 6448 | | | given subnet. This | 6449 | | | statistic is exposed | 6450 | | | for each subnet | 6451 | | | separately. | 6452 +-------------------------------------------+----------------+------------------------------------+ 6453 | declined-addresses | integer | Number of IPv4 | 6454 | | | addresses that are | 6455 | | | currently declined; a | 6456 | | | count of the number | 6457 | | | of leases currently | 6458 | | | unavailable. Once a | 6459 | | | lease is recovered, | 6460 | | | this statistic is | 6461 | | | decreased; | 6462 | | | ideally, this | 6463 | | | statistic should be | 6464 | | | zero. If this | 6465 | | | statistic is non-zero | 6466 | | | or increasing, a | 6467 | | | network administrator | 6468 | | | should investigate | 6469 | | | whether there is a | 6470 | | | misbehaving device in | 6471 | | | the network. This is | 6472 | | | a global statistic | 6473 | | | that covers all | 6474 | | | subnets. | 6475 +-------------------------------------------+----------------+------------------------------------+ 6476 | subnet[id].declined-addresses | integer | Number of IPv4 | 6477 | | | addresses that are | 6478 | | | currently declined in | 6479 | | | a given subnet; a | 6480 | | | count of the number | 6481 | | | of leases currently | 6482 | | | unavailable. Once a | 6483 | | | lease is recovered, | 6484 | | | this statistic is | 6485 | | | decreased; | 6486 | | | ideally, this | 6487 | | | statistic should be | 6488 | | | zero. If this | 6489 | | | statistic is non-zero | 6490 | | | or increasing, a | 6491 | | | network administrator | 6492 | | | should investigate | 6493 | | | whether there is a | 6494 | | | misbehaving device in | 6495 | | | the network. The *id* | 6496 | | | is the subnet-id of a | 6497 | | | given subnet. This | 6498 | | | statistic is exposed | 6499 | | | for each subnet | 6500 | | | separately. | 6501 +-------------------------------------------+----------------+------------------------------------+ 6502 | reclaimed-declined-addresses | integer | Number of IPv4 | 6503 | | | addresses that were | 6504 | | | declined, but have | 6505 | | | now been recovered. | 6506 | | | Unlike | 6507 | | | declined-addresses, | 6508 | | | this statistic never | 6509 | | | decreases. It can be | 6510 | | | used as a long-term | 6511 | | | indicator of how many | 6512 | | | actual valid declines | 6513 | | | were processed and | 6514 | | | recovered from. This | 6515 | | | is a global statistic | 6516 | | | that covers all | 6517 | | | subnets. | 6518 +-------------------------------------------+----------------+------------------------------------+ 6519 | subnet[id].reclaimed-declined-addresses | integer | Number of IPv4 | 6520 | | | addresses that were | 6521 | | | declined, but have | 6522 | | | now been recovered. | 6523 | | | Unlike | 6524 | | | declined-addresses, | 6525 | | | this statistic never | 6526 | | | decreases. It can be | 6527 | | | used as a long-term | 6528 | | | indicator of how many | 6529 | | | actual valid declines | 6530 | | | were processed and | 6531 | | | recovered from. The | 6532 | | | *id* is the subnet-id | 6533 | | | of a given subnet. | 6534 | | | This statistic is | 6535 | | | exposed for each | 6536 | | | subnet separately. | 6537 +-------------------------------------------+----------------+------------------------------------+ 6538 | pkt4-lease-query-received | integer | Number of IPv4 DHCPLEASEQUERY | 6539 | | | packets received. (Only exists if | 6540 | | | Leasequery hook library is | 6541 | | | loaded.) | 6542 +-------------------------------------------+----------------+------------------------------------+ 6543 | pkt4-lease-query-response-unknown-sent | integer | Number of IPv4 DHCPLEASEUNKNOWN | 6544 | | | responses sent. (Only exists if | 6545 | | | Leasequery hook library is | 6546 | | | loaded.) | 6547 +-------------------------------------------+----------------+------------------------------------+ 6548 | pkt4-lease-query-response-unassigned-sent | integer | Number of IPv4 DHCPLEASEUNASSIGNED | 6549 | | | responses sent. (Only exists if | 6550 | | | Leasequery hook library is | 6551 | | | loaded.) | 6552 +-------------------------------------------+----------------+------------------------------------+ 6553 | pkt4-lease-query-response-active-sent | integer | Number of IPv4 DHCPLEASEACTIVE | 6554 | | | responses sent. (Only exists if | 6555 | | | Leasequery hook library is | 6556 | | | loaded.) | 6557 +-------------------------------------------+----------------+------------------------------------+ 6558 6559.. note:: 6560 6561 This section describes DHCPv4-specific statistics. For a general 6562 overview and usage of statistics, see :ref:`stats`. 6563 6564Since Kea 1.7.7, the DHCPv4 server provides two global 6565parameters to control statistics default sample limits: 6566 6567- ``statistic-default-sample-count`` - determines the default maximum 6568 number of samples which are kept. The special value of zero 6569 indicates that a default maximum age should be used. 6570 6571- ``statistic-default-sample-age`` - determines the default maximum 6572 age in seconds of samples which are kept. 6573 6574For instance, to reduce the statistic-keeping overhead, set 6575the default maximum sample count to 1 so only one sample is kept: 6576 6577:: 6578 6579 "Dhcp4": { 6580 "statistic-default-sample-count": 1, 6581 "subnet4": [ ... ], 6582 ... 6583 } 6584 6585Statistics can be retrieved periodically to gain more insight into Kea operations. One tool that 6586leverages that capability is ISC Stork. See :ref:`stork` for details. 6587 6588 6589.. _dhcp4-ctrl-channel: 6590 6591Management API for the DHCPv4 Server 6592==================================== 6593 6594The management API allows the issuing of specific management commands, 6595such as statistics retrieval, reconfiguration, or shutdown. For more 6596details, see :ref:`ctrl-channel`. Currently, the only supported 6597communication channel type is the UNIX stream socket. By default there are 6598no sockets open; to instruct Kea to open a socket, the following entry 6599in the configuration file can be used: 6600 6601:: 6602 6603 "Dhcp4": { 6604 "control-socket": { 6605 "socket-type": "unix", 6606 "socket-name": "/path/to/the/unix/socket" 6607 }, 6608 6609 "subnet4": [ 6610 ... 6611 ], 6612 ... 6613 } 6614 6615The length of the path specified by the ``socket-name`` parameter is 6616restricted by the maximum length for the UNIX socket name on the administrator's 6617operating system, i.e. the size of the ``sun_path`` field in the 6618``sockaddr_un`` structure, decreased by 1. This value varies on 6619different operating systems, between 91 and 107 characters. Typical 6620values are 107 on Linux and 103 on FreeBSD. 6621 6622Communication over the control channel is conducted using JSON 6623structures. See the 6624`Control Channel section in the Kea Developer's Guide 6625<https://reports.kea.isc.org/dev_guide/d2/d96/ctrlSocket.html>`__ 6626for more details. 6627 6628The DHCPv4 server supports the following operational commands: 6629 6630- build-report 6631- config-get 6632- config-reload 6633- config-set 6634- config-test 6635- config-write 6636- dhcp-disable 6637- dhcp-enable 6638- leases-reclaim 6639- list-commands 6640- shutdown 6641- status-get 6642- version-get 6643 6644as described in :ref:`commands-common`. In addition, it supports the 6645following statistics-related commands: 6646 6647- statistic-get 6648- statistic-reset 6649- statistic-remove 6650- statistic-get-all 6651- statistic-reset-all 6652- statistic-remove-all 6653- statistic-sample-age-set 6654- statistic-sample-age-set-all 6655- statistic-sample-count-set 6656- statistic-sample-count-set-all 6657 6658as described in :ref:`command-stats`. 6659 6660.. _dhcp4-user-contexts: 6661 6662User Contexts in IPv4 6663===================== 6664 6665Kea allows the loading of hook libraries that can sometimes benefit from 6666additional parameters. If such a parameter is specific to the whole 6667library, it is typically defined as a parameter for the hook library. 6668However, sometimes there is a need to specify parameters that are 6669different for each pool. 6670 6671See :ref:`user-context` for additional background regarding the user 6672context idea. See :ref:`user-context-hooks` for a discussion from the 6673hooks perspective. 6674 6675User contexts can be specified at global scope; at the shared network, subnet, 6676pool, client class, option data, or definition level; and via host 6677reservation. One other useful feature is the ability to store comments or 6678descriptions. 6679 6680Let's consider an imaginary case of devices that have colored LED lights. 6681Depending on their location, they should glow red, blue, or green. It 6682would be easy to write a hook library that would send specific values, 6683maybe as a vendor option. However, the server has to have some way to 6684specify that value for each pool. This need is addressed by user 6685contexts. In essence, any user data can be specified in the user context 6686as long as it is a valid JSON map. For example, the aforementioned case 6687of LED devices could be configured in the following way: 6688 6689:: 6690 6691 "Dhcp4": { 6692 "subnet4": [{ 6693 "subnet": "192.0.2.0/24", 6694 "pools": [{ 6695 "pool": "192.0.2.10 - 192.0.2.20", 6696 # This is pool specific user context 6697 "user-context": { "color": "red" } 6698 } ], 6699 6700 # This is a subnet-specific user context. Any type 6701 # of information can be entered here as long as it is valid JSON. 6702 "user-context": { 6703 "comment": "network on the second floor", 6704 "last-modified": "2017-09-04 13:32", 6705 "description": "you can put anything you like here", 6706 "phones": [ "x1234", "x2345" ], 6707 "devices-registered": 42, 6708 "billing": false 6709 } 6710 } ] 6711 } 6712 6713Kea does not interpret or use the user-context information; it simply stores it and makes it 6714available to the hook libraries. It is up to each hook library to 6715extract that information and use it. The parser translates a "comment" 6716entry into a user context with the entry, which allows a comment to be 6717attached inside the configuration itself. 6718 6719.. _dhcp4-std: 6720 6721Supported DHCP Standards 6722======================== 6723 6724The following standards are currently supported: 6725 6726- *BOOTP Vendor Information Extensions*, `RFC 6727 1497 <https://tools.ietf.org/html/rfc1497>`__: This requires the open 6728 source BOOTP hook to be loaded. See :ref:`hooks-bootp` for details. 6729 6730- *Dynamic Host Configuration Protocol*, `RFC 6731 2131 <https://tools.ietf.org/html/rfc2131>`__: Supported messages are 6732 DHCPDISCOVER (1), DHCPOFFER (2), DHCPREQUEST (3), DHCPRELEASE (7), 6733 DHCPINFORM (8), DHCPACK (5), and DHCPNAK(6). 6734 6735- *DHCP Options and BOOTP Vendor Extensions*, `RFC 6736 2132 <https://tools.ietf.org/html/rfc2132>`__: Supported options are 6737 PAD (0), END(255), Message Type(53), DHCP Server Identifier (54), 6738 Domain Name (15), DNS Servers (6), IP Address Lease Time (51), Subnet 6739 Mask (1), and Routers (3). 6740 6741- *The IPv4 Subnet Selection Option for DHCP*, `RFC 6742 3011 <https://tools.ietf.org/html/rfc3011>`__: The subnet selection option 6743 is supported. If received in a packet, it is used in the subnet selection 6744 process. 6745 6746- *DHCP Relay Agent Information Option*, `RFC 6747 3046 <https://tools.ietf.org/html/rfc3046>`__: Relay Agent Information, 6748 Circuit ID, and Remote ID options are supported. 6749 6750- *Link Selection sub-option for the Relay Agent Option*, `RFC 3527 6751 <https://tools.ietf.org/html/rfc3527>`__: The link selection sub-option 6752 is supported. 6753 6754- *Vendor-Identifying Vendor Options for Dynamic Host Configuration 6755 Protocol version 4*, `RFC 6756 3925 <https://tools.ietf.org/html/rfc3925>`__: Vendor-Identifying 6757 Vendor Class and Vendor-Identifying Vendor-Specific Information 6758 options are supported. 6759 6760- *Subscriber-ID Suboption for the DHCP Relay Agent Option*, `RFC 6761 3993 <https://tools.ietf.org/html/rfc3993>`__: The Subscriber-ID 6762 option is supported. 6763 6764- *The Dynamic Host Configuration Protocol (DHCP) Client Fully 6765 Qualified Domain Name (FQDN) Option*, `RFC 4702 6766 <https://tools.ietf.org/html/rfc4702>`__: The Kea server is able to 6767 handle the Client FQDN option. Also, it is able to use the 6768 ``kea-dhcp-ddns`` component to initiate appropriate DNS Update 6769 operations. 6770 6771- *Resolution of Fully Qualified Domain Name (FQDN) Conflicts among Dynamic Host 6772 Configuration Protocol (DHCP) Clients*, `RFC 4703 6773 <https://tools.ietf.org/html/rfc4703>`__: The DHCPv6 server uses a DHCP-DDNS 6774 server to resolve conflicts. 6775 6776- *Client Identifier Option in DHCP Server Replies*, `RFC 6777 6842 <https://tools.ietf.org/html/rfc6842>`__: The server by default sends 6778 back the ``client-id`` option. That capability may be disabled. See :ref:`dhcp4-echo-client-id` for details. 6779 6780- *Generalized UDP Source Port for DHCP Relay*, `RFC 8357 6781 <https://tools.ietf.org/html/rfc8357>`__: The Kea server 6782 handles the Relay Agent Information Source Port sub-option in a received 6783 message, remembers the UDP port, and sends back reply to the same relay 6784 agent using this UDP port. 6785 6786- *IPv6-Only Preferred Option for DHCPv4*, `RFC 8925 6787 <https://tools.ietf.org/html/rfc8925>`__: The Kea 6788 server is able to designate its pools and subnets as IPv6-Only Preferred and send 6789 back the ``v6-only-preferred`` option to clients that requested it. 6790 6791Known RFC Violations 6792-------------------- 6793 6794In principle, Kea aspires to be a reference implementation and aims to implement 100% of the RFC standards. 6795However, in some cases there are practical aspects that prevent Kea from completely adhering to the text of the RFC documents. 6796 6797- `RFC 2131 <https://tools.ietf.org/html/rfc2131>`__, page 30, says that if the incoming DHCPREQUEST packet has no 6798 `requested IP address` option and ``ciaddr`` is not set, the server is supposed to respond with NAK. However, 6799 broken clients exist that will always send a DHCPREQUEST without those indicated. In that event, Kea accepts the DHCPREQUEST, 6800 assigns an address, and responds with an ACK. 6801 6802- `RFC 2131 <https://tools.ietf.org/html/rfc2131>`__, table 5, says that messages 6803 of type DHCPDECLINE or DHCPRELEASE must have the server identifier set and 6804 should be dropped if that option is missing. However, ISC DHCP does not enforce this, presumably as a compatibility 6805 effort for broken clients, and the Kea team decided to follow suit. 6806 6807.. _dhcp4-limit: 6808 6809DHCPv4 Server Limitations 6810========================= 6811 6812These are the current known limitations of the Kea DHCPv4 server software. Most of 6813them are reflections of the current stage of development and should be 6814treated as “not implemented yet,” rather than as actual limitations. 6815However, some of them are implications of the design choices made. Those 6816are clearly marked as such. 6817 6818- On the Linux and BSD system families, DHCP messages are sent and 6819 received over raw sockets (using LPF and BPF) and all packet 6820 headers (including data link layer, IP, and UDP headers) are created 6821 and parsed by Kea, rather than by the system kernel. Currently, Kea 6822 can only parse the data-link layer headers with a format adhering to 6823 the IEEE 802.3 standard, and assumes this data link layer header 6824 format for all interfaces. Thus, Kea does not work on interfaces 6825 which use different data-link layer header formats (e.g. Infiniband). 6826 6827- The DHCPv4 server does not verify that an assigned address is unused. 6828 According to `RFC 2131 <https://tools.ietf.org/html/rfc2131>`__, the 6829 allocating server should verify that an address is not used by 6830 sending an ICMP echo request. 6831 6832.. _dhcp4-srv-examples: 6833 6834Kea DHCPv4 Server Examples 6835========================== 6836 6837A collection of simple-to-use examples for the DHCPv4 component of Kea 6838is available with the source files, located in the `doc/examples/kea4` 6839directory. 6840 6841.. _dhcp4-cb: 6842 6843Configuration Backend in DHCPv4 6844=============================== 6845 6846In the :ref:`config-backend` section we have described the Configuration 6847Backend (CB) feature, its applicability, and its limitations. This section focuses 6848on the usage of the CB with the Kea DHCPv4 server. It lists the supported 6849parameters, describes limitations, and gives examples of DHCPv4 6850server configurations to take advantage of the CB. Please also refer to 6851the corresponding section :ref:`dhcp6-cb` for DHCPv6-specific usage of 6852the CB. 6853 6854.. _dhcp4-cb-parameters: 6855 6856Supported Parameters 6857-------------------- 6858 6859The ultimate goal for the CB is to serve as a central configuration 6860repository for one or multiple Kea servers connected to a database. 6861In currently supported Kea versions, only a subset of 6862the DHCPv4 server parameters can be configured in the database. All other 6863parameters must be specified in the JSON configuration file, if 6864required. 6865 6866The following table lists DHCPv4-specific parameters supported by the 6867Configuration Backend, with an indication of the level of the hierarchy 6868at which it is currently supported. "n/a" marks cases when a 6869given parameter is not applicable at the particular level of the 6870hierarchy or in cases when the server does not support the parameter 6871at this level of the hierarchy. "no" is used when a parameter is 6872supported at the given level of the hierarchy but is not 6873configurable via the Configuration Backend. 6874 6875All supported parameters can be configured via the ``cb_cmds`` hook library 6876described in the :ref:`cb-cmds-library` section. The general rule is that 6877scalar global parameters are set using 6878``remote-global-parameter4-set``; shared network-specific parameters 6879are set using ``remote-network4-set``; and subnet- and pool-level 6880parameters are set using ``remote-subnet4-set``. Whenever 6881there is an exception to this general rule, it is highlighted in the 6882table. Non-scalar global parameters have dedicated commands; for example, 6883the global DHCPv4 options (``option-data``) are modified using 6884``remote-option4-global-set``. Client classes, together with class-specific 6885option definitions and DHCPv4 options, are configured using the 6886``remote-class4-set`` command. 6887 6888The :ref:`cb-sharing` section explains the concept of shareable 6889and non-shareable configuration elements and the limitations for 6890sharing them between multiple servers. In the DHCP configuration (both DHCPv4 6891and DHCPv6), the shareable configuration elements are subnets and shared 6892networks. Thus, they can be explicitly associated with multiple server tags. 6893The global parameters, option definitions, and global options are non-shareable 6894and can be associated with only one server tag. This rule does not apply 6895to the configuration elements associated with `"all"` servers. Any configuration 6896element associated with `"all"` servers (using the `"all"` keyword as a server tag) is 6897used by all servers connecting to the configuration database. 6898 6899.. table:: List of DHCPv4 Parameters Supported by the Configuration Backend 6900 6901 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6902 | Parameter | Global | Client | Shared | Subnet | Pool | 6903 | | | Class | Network | | | 6904 +=============================+============================+==============+=============+=============+=============+ 6905 | 4o6-interface | n/a | n/a | n/a | yes | n/a | 6906 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6907 | 4o6-interface-id | n/a | n/a | n/a | yes | n/a | 6908 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6909 | 4o6-subnet | n/a | n/a | n/a | yes | n/a | 6910 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6911 | boot-file-name | yes | yes | yes | yes | n/a | 6912 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6913 | cache-max-age | yes | n/a | todo | todo | n/a | 6914 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6915 | cache-threshold | yes | n/a | todo | todo | n/a | 6916 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6917 | calculate-tee-times | yes | n/a | yes | yes | n/a | 6918 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6919 | client-class | n/a | n/a | yes | yes | yes | 6920 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6921 | ddns-send-update | yes | n/a | yes | yes | n/a | 6922 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6923 | ddns-override-no-update | yes | n/a | yes | yes | n/a | 6924 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6925 | ddns-override-client-update | yes | n/a | yes | yes | n/a | 6926 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6927 | ddns-replace-client-name | yes | n/a | yes | yes | n/a | 6928 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6929 | ddns-generated-prefix | yes | n/a | yes | yes | n/a | 6930 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6931 | ddns-qualifying-suffix | yes | n/a | yes | yes | n/a | 6932 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6933 | decline-probation-period | yes | n/a | n/a | n/a | n/a | 6934 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6935 | dhcp4o6-port | yes | n/a | n/a | n/a | n/a | 6936 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6937 | echo-client-id | yes | n/a | n/a | n/a | n/a | 6938 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6939 | hostname-char-set | no | n/a | no | no | n/a | 6940 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6941 | hostname-char-replacement | no | n/a | no | no | n/a | 6942 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6943 | interface | n/a | n/a | yes | yes | n/a | 6944 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6945 | match-client-id | yes | n/a | yes | yes | n/a | 6946 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6947 | min-valid-lifetime | yes | yes | yes | yes | n/a | 6948 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6949 | max-valid-lifetime | yes | yes | yes | yes | n/a | 6950 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6951 | next-server | yes | yes | yes | yes | n/a | 6952 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6953 | option-data | yes (via | yes | yes | yes | yes | 6954 | | remote-option4-global-set) | | | | | 6955 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6956 | option-def | yes (via | yes | n/a | n/a | n/a | 6957 | | remote-option-def4-set) | | | | | 6958 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6959 | rebind-timer | yes | n/a | yes | yes | n/a | 6960 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6961 | renew-timer | yes | n/a | yes | yes | n/a | 6962 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6963 | server-hostname | yes | yes | yes | yes | n/a | 6964 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6965 | valid-lifetime | yes | yes | yes | yes | n/a | 6966 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6967 | relay | n/a | n/a | yes | yes | n/a | 6968 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6969 | require-client-classes | no | n/a | yes | yes | yes | 6970 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6971 | reservation-mode | yes | n/a | yes | yes | n/a | 6972 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6973 | reservations-global | yes | n/a | yes | yes | n/a | 6974 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6975 | reservations-in-subnet | yes | n/a | yes | yes | n/a | 6976 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6977 | reservations-out-of-pool | yes | n/a | yes | yes | n/a | 6978 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6979 | t1-percent | yes | n/a | yes | yes | n/a | 6980 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6981 | t2-percent | yes | n/a | yes | yes | n/a | 6982 +-----------------------------+----------------------------+--------------+-------------+-------------+-------------+ 6983 6984.. _dhcp4-cb-json: 6985 6986Enabling the Configuration Backend 6987---------------------------------- 6988 6989Consider the following configuration snippet: 6990 6991:: 6992 6993 "Dhcp4": { 6994 "server-tag": "my DHCPv4 server", 6995 "config-control": { 6996 "config-databases": [{ 6997 "type": "mysql", 6998 "name": "kea", 6999 "user": "kea", 7000 "password": "kea", 7001 "host": "192.0.2.1", 7002 "port": 3302 7003 }], 7004 "config-fetch-wait-time": 20 7005 }, 7006 "hooks-libraries": [{ 7007 "library": "/usr/local/lib/kea/hooks/libdhcp_mysql_cb.so" 7008 }, { 7009 "library": "/usr/local/lib/kea/hooks/libdhcp_cb_cmds.so" 7010 }], 7011 } 7012 7013The ``config-control`` command contains two parameters. ``config-databases`` 7014is a list which contains one element comprising database type, location, 7015and the credentials to be used to connect to this database. (Note that 7016the parameters specified here correspond to the database specification 7017for the lease database backend and hosts database backend.) Currently 7018only one database connection can be specified on the 7019``config-databases`` list. The server connects to this database 7020during startup or reconfiguration, and fetches the configuration 7021available for this server from the database. This configuration is 7022merged into the configuration read from the configuration file. 7023 7024.. note:: 7025 7026 Whenever there is a conflict between the parameters specified in the 7027 configuration file and the database, the parameters from the database 7028 take precedence. We strongly recommend avoiding the duplication of 7029 parameters in the file and the database, but this recommendation is 7030 not enforced by the Kea servers. In particular, if the subnets' 7031 configuration is sourced from the database, we recommend that all 7032 subnets be specified in the database and that no subnets be specified in 7033 the configuration file. It is possible to specify the subnets in both 7034 places, but the subnets in the 7035 configuration file with overlapping IDs and/or prefixes with the 7036 subnets from the database will be superseded by those from the 7037 database. 7038 7039Once the Kea server is configured, it starts periodically polling 7040the database for configuration changes. The polling frequency is 7041controlled by the ``config-fetch-wait-time`` parameter, expressed 7042in seconds; it is the period between the time when the server 7043completed its last poll (and possibly the local configuration update) and 7044the time when it will begin polling again. In the example above, this period 7045is set to 20 seconds. This means that after adding a new configuration 7046into the database (e.g. adding a new subnet), it will take up to 20 seconds 7047(plus the time needed to fetch and apply the new configuration) before 7048the server starts using this subnet. The lower the 7049``config-fetch-wait-time`` value, the shorter the time for the server to 7050react to incremental configuration updates in the database. On the 7051other hand, polling the database too frequently may impact the DHCP 7052server's performance, because the server needs to make at least one query 7053to the database to discover any pending configuration updates. The 7054default value of ``config-fetch-wait-time`` is 30 seconds. 7055 7056The ``config-backend-pull`` command can be used to force the server to 7057immediately poll any configuration changes from the database and avoid 7058waiting for the next fetch cycle. (This command was added in Kea release 70591.7.1 for both DHCPv4 and DHCPv6 servers.) 7060 7061Finally, in the configuration example above, two hook libraries are 7062loaded. The first, ``libdhcp_mysql_cb.so``, is the implementation of 7063the Configuration Backend for MySQL. It must be always present when the 7064server uses MySQL as the configuration repository. Failing to load this 7065library will result in an error during the server configuration if the 7066`"mysql"` database is selected with the ``config-control`` parameter. 7067 7068The second hook library, ``libdhcp_cb_cmds.so``, is optional. It should 7069be loaded when the Kea server instance is to be used to manage the 7070configuration in the database. See the :ref:`cb-cmds-library` section for 7071details. This hook library is only available to ISC 7072customers with a paid support contract. 7073 7074.. _dhcp4-compatibility: 7075 7076Kea DHCPv4 Compatibility Configuration Parameters 7077================================================= 7078 7079ISC's intention is for Kea to follow the RFC documents to promote better standards 7080compliance. However, many buggy DHCP implementations already exist that cannot be 7081easily fixed or upgraded. Therefore, Kea provides an easy-to-use compatibility 7082mode for broken or non-compliant clients. For that purpose, flags must be 7083enabled to enable uncommon practices: 7084 7085.. code-block:: json 7086 7087 { 7088 "Dhcp4": { 7089 "compatibility": { 7090 } 7091 } 7092 } 7093 7094 7095Lenient Option Parsing 7096---------------------- 7097 7098By default, tuple fields defined in custom options are parsed as a set of 7099length-value pairs. 7100 7101With ``lenient-option-parsing: "true"``, if a length ever exceeds the rest of 7102the option's buffer, previous versions of Kea returned a log message ``unable to 7103parse the opaque data tuple, the buffer length is x, but the tuple length is y`` 7104with ``x < y``; this no longer occurs. Instead, the value is considered to be the rest of the buffer, 7105or in terms of the log message above, the tuple length ``y`` becomes ``x``. 7106 7107.. code-block:: json 7108 7109 { 7110 "Dhcp4": { 7111 "compatibility": { 7112 "lenient-option-parsing": true 7113 } 7114 } 7115 } 7116