1.. _dhcp-ddns-server: 2 3******************** 4The DHCP-DDNS Server 5******************** 6 7.. _dhcp-ddns-overview: 8 9Overview 10======== 11 12The DHCP-DDNS Server (kea-dhcp-ddns, known informally as D2) conducts 13the client side of the Dynamic DNS protocol (DDNS, defined in `RFC 142136 <https://tools.ietf.org/html/rfc2136>`__) on behalf of the DHCPv4 15and DHCPv6 servers (kea-dhcp4 and kea-dhcp6 respectively). The DHCP 16servers construct DDNS update requests, known as Name Change Requests 17(NCRs), based on DHCP lease change events and then post them to D2. D2 18attempts to match each request to the appropriate DNS server(s) and 19carries out the necessary conversation with those servers to update the 20DNS data. 21 22.. _dhcp-ddns-dns-server-selection: 23 24DNS Server Selection 25-------------------- 26 27In order to match a request to the appropriate DNS servers, D2 must have 28a catalog of servers from which to select. In fact, D2 has two such 29catalogs, one for forward DNS and one for reverse DNS; these catalogs 30are referred to as DDNS Domain Lists. Each list consists of one or more 31named DDNS Domains. Further, each DDNS Domain has a list of one or more 32DNS servers that publish the DNS data for that domain. 33 34When conducting forward domain matching, D2 compares the fully qualified 35domain name (FQDN) in the request against the name of each Forward DDNS 36Domain in its catalog. The domain whose name matches the longest portion 37of the FQDN is considered the best match. For example, if the FQDN is 38"myhost.sample.example.com.", and there are two forward domains in the 39catalog, "sample.example.com." and "example.com.", the former is 40regarded as the best match. In some cases, it may not be possible to 41find a suitable match. Given the same two forward domains there would be 42no match for the FQDN, "bogus.net", so the request would be rejected. 43Finally, if there are no Forward DDNS Domains defined, D2 simply 44disregards the forward update portion of requests. 45 46When conducting reverse domain matching, D2 constructs a reverse FQDN 47from the lease address in the request and compares that against the name 48of each Reverse DDNS Domain. Again, the domain whose name matches the 49longest portion of the FQDN is considered the best match. For instance, 50if the lease address is "172.16.1.40" and there are two reverse domains 51in the catalog, "1.16.172.in-addr.arpa." and "16.172.in-addr.arpa", the 52former is the best match. As with forward matching, it may not find a 53suitable match. Given the same two domains, there would be no match for 54the lease address, "192.168.1.50", and the request would be rejected. 55Finally, if there are no Reverse DDNS Domains defined, D2 simply 56disregards the reverse update portion of requests. 57 58.. _dhcp-ddns-conflict-resolution: 59 60Conflict Resolution 61------------------- 62 63D2 implements the conflict resolution strategy prescribed by `RFC 644703 <https://tools.ietf.org/html/rfc4703>`__. Conflict resolution is 65intended to prevent different clients from mapping to the same FQDN at 66the same time. To make this possible, the RFC requires that forward DNS 67entries for a given FQDN must be accompanied by a DHCID resource record 68(RR). This record contains a client identifier that uniquely identifies 69the client to whom the name belongs. Furthermore, any DNS updater that 70wishes to update or remove existing forward entries for an FQDN may only 71do so if their client matches that of the DHCID RR. 72 73In other words, the DHCID RR maps an FQDN to the client to whom it 74belongs, and thereafter changes to that mapping should only be done by 75or at the behest of that client. 76 77Currently, conflict detection is always performed. 78 79.. _dhcp-ddns-dual-stack: 80 81Dual-Stack Environments 82----------------------- 83 84`RFC 4703, section 855.2, <https://tools.ietf.org/html/rfc4703#section-5.2>`__ describes 86issues that may arise with dual-stack clients. These are clients that 87wish to have both IPv4 and IPv6 mappings for the same FQDN. For 88this to work properly, the clients are required to embed their IPv6 DUID 89within their IPv4 client identifier option, as described in `RFC 904703 <https://tools.ietf.org/html/rfc4361>`__. In this way, DNS updates 91for both IPv4 and IPv6 can be managed under the same DHCID RR. Kea does not 92currently support this feature. 93 94.. _dhcp-ddns-server-start-stop: 95 96Starting and Stopping the DHCP-DDNS Server 97========================================== 98 99``kea-dhcp-ddns`` is the Kea DHCP-DDNS server and, due to the nature of 100DDNS, it runs alongside either the DHCPv4 or DHCPv6 component (or both). 101Like other parts of Kea, it is a separate binary that can be run on its 102own or through ``keactrl`` (see :ref:`keactrl`). In normal 103operation, controlling ``kea-dhcp-ddns`` with ``keactrl`` is 104recommended; however, it is also possible to run the DHCP-DDNS server 105directly. It accepts the following command-line switches: 106 107- ``-c file`` - specifies the configuration file. This is the only 108 mandatory switch. 109 110- ``-d`` - specifies whether the server logging should be switched to 111 debug/verbose mode. In verbose mode, the logging severity and 112 debuglevel specified in the configuration file are ignored and 113 "debug" severity and the maximum debuglevel (99) are assumed. The 114 flag is convenient for temporarily switching the server into maximum 115 verbosity, e.g. when debugging. 116 117- ``-v`` - displays the Kea version and exits. 118 119- ``-W`` - displays the Kea configuration report and exits. The report 120 is a copy of the ``config.report`` file produced by ``./configure``; 121 it is embedded in the executable binary. 122 123- ``-t file`` - specifies the configuration file to be tested. 124 Kea-dhcp-ddns will attempt to load it and will conduct sanity checks. 125 Note that certain checks are possible only while running the actual 126 server. The actual status is reported with an exit code (0 = 127 configuration looks ok, 1 = error encountered). Kea prints out log 128 messages to standard output and errors to standard error when testing 129 the configuration. 130 131The ``config.report`` may also be accessed more directly, via the 132following command. The binary ``path`` may be found in the install 133directory or in the ``.libs`` subdirectory in the source tree. For 134example: ``kea/src/bin/d2/.libs/kea-dhcp-ddns``. 135 136:: 137 138 strings path/kea-dhcp-ddns | sed -n 's/;;;; //p' 139 140Upon startup, the module will load its configuration and begin listening 141for NCRs based on that configuration. 142 143During startup, the server will attempt to create a PID file of the form: 144[**runstatedir**]/[**conf name**].kea-dhcp-ddns.pid where: 145 146- ``runstatedir`` - is the value as passed into the build configure 147 script; it defaults to "/usr/local/var/run". Note that this value may be 148 overridden at runtime by setting the environment variable 149 KEA_PIDFILE_DIR. This is intended primarily for testing purposes. 150 151- ``conf name`` - is the configuration file name used to start the server, 152 minus all preceding paths and the file extension. For example, given 153 a pathname of "/usr/local/etc/kea/myconf.txt", the portion used would 154 be "myconf". 155 156If the file already exists and contains the PID of a live process, the 157server will issue a DHCP_DDNS_ALREADY_RUNNING log message and exit. It 158is possible, though unlikely, that the file is a remnant of a system 159crash and the process to which the PID belongs is unrelated to Kea. In 160such a case it is necessary to manually delete the PID file. 161 162.. _d2-configuration: 163 164Configuring the DHCP-DDNS Server 165================================ 166 167Before starting the ``kea-dhcp-ddns`` module for the first time, a 168configuration file must be created. The following default configuration 169is a template that can be customized to individual requirements. 170 171:: 172 173 "DhcpDdns": { 174 "ip-address": "127.0.0.1", 175 "port": 53001, 176 "dns-server-timeout": 100, 177 "ncr-protocol": "UDP", 178 "ncr-format": "JSON", 179 "tsig-keys": [ ], 180 "forward-ddns": { 181 "ddns-domains": [ ] 182 }, 183 "reverse-ddns": { 184 "ddns-domains": [ ] 185 } 186 } 187 188The configuration can be divided into the following sections, each of 189which is described below: 190 191- *Global Server Parameters* - define values which control connectivity and 192 global server behavior. 193 194- *Control Socket* - defines the Control Socket type and name. 195 196- *TSIG Key Info* - defines the TSIG keys used for secure traffic with 197 DNS servers. 198 199- *Forward DDNS* - defines the catalog of Forward DDNS Domains. 200 201- *Reverse DDNS* - defines the catalog of Forward DDNS Domains. 202 203.. _d2-server-parameter-config: 204 205Global Server Parameters 206------------------------ 207 208- ``ip-address`` - the IP address on which D2 listens for requests. The 209 default is the local loopback interface at address 127.0.0.1. 210 Either an IPv4 or IPv6 address may be specified. 211 212- ``port`` - the port on which D2 listens for requests. The default value 213 is 53001. 214 215- ``dns-server-timeout`` - the maximum amount of time, in milliseconds, 216 that D2 will wait for a response from a DNS server to a single DNS 217 update message. 218 219- ``ncr-protocol`` - the socket protocol to use when sending requests to 220 D2. Currently only UDP is supported. 221 222- ``ncr-format`` - the packet format to use when sending requests to D2. 223 Currently only JSON format is supported. 224 225D2 must listen for change requests on a known address and port. By 226default it listens at 127.0.0.1 on port 53001. The following example 227illustrates how to change D2's global parameters so it will listen at 228192.168.1.10 port 900: 229 230:: 231 232 "DhcpDdns": { 233 "ip-address": "192.168.1.10", 234 "port": 900, 235 ... 236 } 237 } 238 239.. 240 241.. warning:: 242 243 It is possible for a malicious attacker to send bogus 244 NameChangeRequests to the DHCP-DDNS server. Addresses other than the 245 IPv4 or IPv6 loopback addresses (127.0.0.1 or ::1) should only be 246 used for testing purposes; note that local users may still 247 communicate with the DHCP-DDNS server. 248 249.. note:: 250 251 If the ip-address and port are changed, the corresponding values in 252 the DHCP servers' "dhcp-ddns" configuration section must be changed. 253 254.. _d2-ctrl-channel: 255 256Management API for the D2 Server 257-------------------------------- 258 259The management API allows the issuing of specific management commands, 260such as configuration retrieval or shutdown. For more details, see 261:ref:`ctrl-channel`. Currently, the only supported communication 262channel type is UNIX stream socket. By default there are no sockets 263open; to instruct Kea to open a socket, the following entry in the 264configuration file can be used: 265 266:: 267 268 "DhcpDdns": { 269 "control-socket": { 270 "socket-type": "unix", 271 "socket-name": "/path/to/the/unix/socket" 272 }, 273 ... 274 } 275 276The length of the path specified by the ``socket-name`` parameter is 277restricted by the maximum length for the UNIX socket name on the 278operating system, i.e. the size of the ``sun_path`` field in the 279``sockaddr_un`` structure, decreased by 1. This value varies on 280different operating systems between 91 and 107 characters. Typical 281values are 107 on Linux and 103 on FreeBSD. 282 283Communication over the control channel is conducted using JSON structures. 284See the `Control Channel section in the Kea Developer's 285Guide <https://reports.kea.isc.org/dev_guide/d2/d96/ctrlSocket.html>`__ 286for more details. 287 288The D2 server supports the following operational commands: 289 290- build-report 291- config-get 292- config-reload 293- config-set 294- config-test 295- config-write 296- list-commands 297- shutdown 298- status-get 299- version-get 300 301Starting with Kea version 2.0.0 the D2 server supports too the following 302operational commands for statistics: 303 304- statistic-get 305- statistic-get-all 306- statistic-reset 307- statistic-reset-all 308 309The ``shutdown`` command supports the extra ``type`` argument which controls the 310way the D2 server cleans up on exit. 311The supported shutdown types are: 312 313- ``normal`` - Stops the queue manager and finishes all current transactions 314 before exiting. This is the default. 315 316- ``drain_first`` - Stops the queue manager but continues processing requests 317 from the queue until it is empty. 318 319- ``now`` - Exits immediately. 320 321An example command may look like this: 322 323:: 324 325 { 326 "command": "shutdown" 327 "arguments": { 328 "exit-value": 3, 329 "type": "drain_first" 330 } 331 } 332 333.. _d2-tsig-key-list-config: 334 335TSIG Key List 336------------- 337 338A DDNS protocol exchange can be conducted with or without TSIG (defined 339in `RFC 2845 <https://tools.ietf.org/html/rfc2845>`__). This 340configuration section allows the administrator to define the set of TSIG 341keys that may be used in such exchanges. 342 343To use TSIG when updating entries in a DNS domain, a key must be defined 344in the TSIG Key list and referenced by name in that domain's 345configuration entry. When D2 matches a change request to a domain, it 346checks whether the domain has a TSIG key associated with it. If so, D2 347uses that key to sign DNS update messages sent to and verify 348responses received from the domain's DNS server(s). For each TSIG key 349required by the DNS servers that D2 will be working with, there must be 350a corresponding TSIG key in the TSIG Key list. 351 352As one might gather from the name, the tsig-key section of the D2 353configuration lists the TSIG keys. Each entry describes a TSIG key used 354by one or more DNS servers to authenticate requests and sign responses. 355Every entry in the list has three parameters: 356 357- ``name`` - is a unique text label used to identify this key within the 358 list. This value is used to specify which key (if any) should be used 359 when updating a specific domain. As long as the name is unique its 360 content is arbitrary, although for clarity and ease of maintenance it 361 is recommended that it match the name used on the DNS server(s). This 362 field cannot be blank. 363 364- ``algorithm`` - specifies which hashing algorithm should be used with 365 this key. This value must specify the same algorithm used for the key 366 on the DNS server(s). The supported algorithms are listed below: 367 368 - HMAC-MD5 369 - HMAC-SHA1 370 - HMAC-SHA224 371 - HMAC-SHA256 372 - HMAC-SHA384 373 - HMAC-SHA512 374 375 This value is not case-sensitive. 376 377- ``digest-bits`` - is used to specify the minimum truncated length in 378 bits. The default value 0 means truncation is forbidden; non-zero 379 values must be an integral number of octets, and be greater than both 380 80 and half of the full length. (Note that in BIND 9 this parameter 381 is appended after a dash to the algorithm name.) 382 383- ``secret`` - is used to specify the shared secret key code for this 384 key. This value is case-sensitive and must exactly match the value 385 specified on the DNS server(s). It is a base64-encoded text value. 386 387As an example, suppose that a domain D2 will be updating is maintained 388by a BIND 9 DNS server, which requires dynamic updates to be secured 389with TSIG. Suppose further that the entry for the TSIG key in BIND 9's 390named.conf file looks like this: 391 392:: 393 394 : 395 key "key.four.example.com." { 396 algorithm hmac-sha224; 397 secret "bZEG7Ow8OgAUPfLWV3aAUQ=="; 398 }; 399 : 400 401By default, the TSIG Key list is empty: 402 403:: 404 405 "DhcpDdns": { 406 "tsig-keys": [ ], 407 ... 408 } 409 410We must extend the list with a new key: 411 412:: 413 414 "DhcpDdns": { 415 "tsig-keys": [ 416 { 417 "name": "key.four.example.com.", 418 "algorithm": "HMAC-SHA224", 419 "secret": "bZEG7Ow8OgAUPfLWV3aAUQ==" 420 } 421 ], 422 ... 423 } 424 425These steps would be repeated for each TSIG key needed. Note that the 426same TSIG key can be used with more than one domain. 427 428.. _d2-forward-ddns-config: 429 430Forward DDNS 431------------ 432 433The Forward DDNS section is used to configure D2's forward update 434behavior. Currently it contains a single parameter, the catalog of 435Forward DDNS Domains, which is a list of structures. 436 437:: 438 439 "DhcpDdns": { 440 "forward-ddns": { 441 "ddns-domains": [ ] 442 }, 443 ... 444 } 445 446By default, this list is empty, which will cause the server to ignore 447the forward update portions of requests. 448 449.. _add-forward-ddns-domain: 450 451Adding Forward DDNS Domains 452~~~~~~~~~~~~~~~~~~~~~~~~~~~ 453 454A Forward DDNS Domain maps a forward DNS zone to a set of DNS servers 455which maintain the forward DNS data (i.e. name-to-address mapping) for 456that zone. Each zone served needs one Forward DDNS Domain. It may very 457well be that some or all of the zones are maintained by the same 458servers, but one DDNS Domain is still needed for each zone. Remember that 459matching a request to the appropriate server(s) is done by zone and a 460DDNS Domain only defines a single zone. 461 462This section describes how to add Forward DDNS Domains; repeat these 463steps for each Forward DDNS Domain desired. Each Forward DDNS Domain has 464the following parameters: 465 466- ``name`` - the fully qualified domain name (or zone) that this DDNS 467 Domain can update. This value is compared against the request FQDN 468 during forward matching. It must be unique within the catalog. 469 470- ``key-name`` - if TSIG is used with this domain's servers, this value 471 should be the name of the key from the TSIG Key list. If the 472 value is blank (the default), TSIG will not be used in DDNS 473 conversations with this domain's servers. 474 475- ``dns-servers`` - a list of one or more DNS servers which can conduct 476 the server side of the DDNS protocol for this domain. The servers are 477 used in a first-to-last preference; in other words, when D2 begins to 478 process a request for this domain, it will pick the first server in 479 this list and attempt to communicate with it. If that attempt fails, 480 D2 will move to the next one in the list and so on until either it 481 is successful or the list is exhausted. 482 483To create a new Forward DDNS Domain, add a new domain element and set 484its parameters: 485 486:: 487 488 "DhcpDdns": { 489 "forward-ddns": { 490 "ddns-domains": [ 491 { 492 "name": "other.example.com.", 493 "key-name": "", 494 "dns-servers": [ 495 ] 496 } 497 ] 498 } 499 } 500 501It is possible to add a domain without any servers; however, if that 502domain matches a request, the request will fail. To make the domain 503useful, at least one DNS server must be added to it. 504 505.. _add-forward-dns-servers: 506 507Adding Forward DNS Servers 508^^^^^^^^^^^^^^^^^^^^^^^^^^ 509 510This section describes how to add DNS servers to a Forward DDNS Domain. 511Repeat these instructions as needed for all the servers in each domain. 512 513Forward DNS Server entries represent actual DNS servers which support 514the server side of the DDNS protocol. Each Forward DNS Server has the 515following parameters: 516 517- ``hostname`` - the resolvable host name of the DNS server; this 518 parameter is not yet implemented. 519 520- ``ip-address`` - the IP address at which the server listens for DDNS 521 requests. This may be either an IPv4 or an IPv6 address. 522 523- ``port`` - the port on which the server listens for DDNS requests. It 524 defaults to the standard DNS service port of 53. 525 526To create a new Forward DNS Server, a new server element must be added to 527the domain and its parameters filled in. If, for example, the service is 528running at "172.88.99.10", set the Forward DNS Server as follows: 529 530:: 531 532 "DhcpDdns": { 533 "forward-ddns": { 534 "ddns-domains": [ 535 { 536 "name": "other.example.com.", 537 "key-name": "", 538 "dns-servers": [ 539 { 540 "ip-address": "172.88.99.10", 541 "port": 53 542 } 543 ] 544 } 545 ] 546 } 547 } 548 549.. 550 551.. note:: 552 553 Since "hostname" is not yet supported, the parameter "ip-address" 554 must be set to the address of the DNS server. 555 556.. _d2-reverse-ddns-config: 557 558Reverse DDNS 559------------ 560 561The Reverse DDNS section is used to configure D2's reverse update 562behavior, and the concepts are the same as for the forward DDNS section. 563Currently it contains a single parameter, the catalog of Reverse DDNS 564Domains, which is a list of structures. 565 566:: 567 568 "DhcpDdns": { 569 "reverse-ddns": { 570 "ddns-domains": [ ] 571 } 572 ... 573 } 574 575By default, this list is empty, which will cause the server to ignore 576the reverse update portions of requests. 577 578.. _add-reverse-ddns-domain: 579 580Adding Reverse DDNS Domains 581~~~~~~~~~~~~~~~~~~~~~~~~~~~ 582 583A Reverse DDNS Domain maps a reverse DNS zone to a set of DNS servers 584which maintain the reverse DNS data (address-to-name mapping) for that 585zone. Each zone served needs one Reverse DDNS Domain. It may very well 586be that some or all of the zones are maintained by the same servers, but 587one DDNS Domain entry is still needed for each zone. Remember that 588matching a request to the appropriate server(s) is done by zone and a 589DDNS Domain only defines a single zone. 590 591This section describes how to add Reverse DDNS Domains; repeat these 592steps for each Reverse DDNS Domain desired. Each Reverse DDNS Domain has 593the following parameters: 594 595- ``name`` - the fully qualified reverse zone that this DDNS domain can 596 update. This is the value used during reverse matching, which will 597 compare it with a reversed version of the request's lease address. 598 The zone name should follow the appropriate standards; for example, 599 to support the IPv4 subnet 172.16.1, the name should be 600 "1.16.172.in-addr.arpa.". Similarly, to support an IPv6 subnet of 601 2001:db8:1, the name should be "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa." 602 Whatever the name, it must be unique within the catalog. 603 604- ``key-name`` - if TSIG is used with this domain's servers, 605 this value should be the name of the key from the TSIG Key List. If 606 the value is blank (the default), TSIG will not be used in DDNS 607 conversations with this domain's servers. 608 609- ``dns-servers`` - a list of one or more DNS servers which can conduct 610 the server side of the DDNS protocol for this domain. Currently, the 611 servers are used in a first-to-last preference; in other words, when 612 D2 begins to process a request for this domain, it will pick the 613 first server in this list and attempt to communicate with it. If that 614 attempt fails, D2 will move to the next one in the list and so on 615 until either it is successful or the list is exhausted. 616 617To create a new Reverse DDNS Domain, a new domain element must be added 618and its parameters set. For example, to support subnet 2001:db8:1::, the 619following configuration could be used: 620 621:: 622 623 "DhcpDdns": { 624 "reverse-ddns": { 625 "ddns-domains": [ 626 { 627 "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.", 628 "key-name": "", 629 "dns-servers": [ 630 ] 631 } 632 ] 633 } 634 } 635 636It is possible to add a domain without any servers; however, if that 637domain matches a request, the request will fail. To make the domain 638useful, at least one DNS server must be added to it. 639 640.. _add-reverse-dns-servers: 641 642Adding Reverse DNS Servers 643^^^^^^^^^^^^^^^^^^^^^^^^^^ 644 645This section describes how to add DNS servers to a Reverse DDNS Domain. 646Repeat these instructions as needed for all the servers in each domain. 647 648Reverse DNS Server entries represent actual DNS servers which support 649the server side of the DDNS protocol. Each Reverse DNS Server has the 650following parameters: 651 652- ``hostname`` - the resolvable host name of the DNS server; this value 653 is currently ignored. 654 655- ``ip-address`` - the IP address at which the server listens for DDNS 656 requests. 657 658- ``port`` - the port on which the server listens for DDNS requests. It 659 defaults to the standard DNS service port of 53. 660 661To create a new reverse DNS Server, a new server 662element must be added to the domain and its parameters filled in. If, for example, the 663service is running at "172.88.99.10", then set it as follows: 664 665:: 666 667 "DhcpDdns": { 668 "reverse-ddns": { 669 "ddns-domains": [ 670 { 671 "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.", 672 "key-name": "", 673 "dns-servers": [ 674 { 675 "ip-address": "172.88.99.10", 676 "port": 53 677 } 678 ] 679 } 680 ] 681 } 682 } 683 684.. 685 686.. note:: 687 688 Since "hostname" is not yet supported, the parameter "ip-address" 689 must be set to the address of the DNS server. 690 691.. _per-server-keys: 692 693Per DNS server TSIG keys 694~~~~~~~~~~~~~~~~~~~~~~~~ 695 696Since Kea version 2.0.0 a TSIG key can be specified in a DNS server 697configuration. The priority rule is: 698 699- if a not empty key name is specified in a DNS server entry this TSIG 700 key will protect DNS updates sent to this server. 701 702- if empty or no key name is specified in a DNS server entry but a not 703 empty key name is specified in the parent domain entry, the domain 704 TSIG key will protect DNS updates sent to this server. 705 706- if empty or no key name is specified in a DNS server entry and its parent 707 domain entry, no TSIG will protect DNS updates sent to this server. 708 709For instance in this configuration: 710 711:: 712 713 "DhcpDdns": { 714 "forward-ddns": { 715 "ddns-domains": [ 716 { 717 "name": "other.example.com.", 718 "key-name": "foo", 719 "dns-servers": [ 720 { 721 "ip-address": "172.88.99.10", 722 "port": 53 723 }, 724 { 725 "ip-address": "172.88.99.11", 726 "port": 53, 727 "key-name": "bar" 728 } 729 ] 730 } 731 ] 732 }, 733 "reverse-ddns": { 734 "ddns-domains": [ 735 { 736 "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.", 737 "dns-servers": [ 738 { 739 "ip-address": "172.88.99.12", 740 "port": 53 741 }, 742 { 743 "ip-address": "172.88.99.13", 744 "port": 53, 745 "key-name": "bar" 746 } 747 ] 748 } 749 ] 750 }, 751 "tsig-keys": [ 752 { 753 "name": "foo", 754 "algorithm": "HMAC-MD5", 755 "secret": "LSWXnfkKZjdPJI5QxlpnfQ==" 756 }, 757 { 758 "name": "bar", 759 "algorithm": "HMAC-SHA224", 760 "secret": "bZEG7Ow8OgAUPfLWV3aAUQ==" 761 } 762 ] 763 } 764 765 766The 172.88.99.10 server will use the foo TSIG key, 172.88.99.11 and 767172.88.99.13 servers the bar one and 172.88.99.12 will not use TSIG. 768 769.. _d2-user-contexts: 770 771User Contexts in DDNS 772--------------------- 773 774See :ref:`user-context` for additional background regarding the user 775context idea. 776 777User contexts can be specified on global scope, DDNS domain, DNS server, 778TSIG key, and loggers. One other useful usage is the ability to store 779comments or descriptions; the parser translates a "comment" entry into a 780user context with the entry, which allows a comment to be attached 781inside the configuration itself. 782 783.. _d2-example-config: 784 785Example DHCP-DDNS Server Configuration 786-------------------------------------- 787 788This section provides a sample DHCP-DDNS server configuration, based on 789a small example network. Let's suppose our example network has three 790domains, each with their own subnet. 791 792.. table:: Our Example Network 793 794 +------------------+-----------------+-----------------+-----------------+ 795 | Domain | Subnet | Forward DNS | Reverse DNS | 796 | | | Servers | Servers | 797 +==================+=================+=================+=================+ 798 | four.example.com | 192.0.2.0/24 | 172.16.1.5, | 172.16.1.5, | 799 | | | 172.16.2.5 | 172.16.2.5 | 800 +------------------+-----------------+-----------------+-----------------+ 801 | six.example.com | 2001:db8:1::/64 | 3001:1::50 | 3001:1::51 | 802 +------------------+-----------------+-----------------+-----------------+ 803 | example.com | 192.0.0.0/16 | 172.16.2.5 | 172.16.2.5 | 804 +------------------+-----------------+-----------------+-----------------+ 805 806We need to construct three Forward DDNS Domains: 807 808.. table:: Forward DDNS Domains Needed 809 810 +----+-------------------+------------------------+ 811 | # | DDNS Domain Name | DNS Servers | 812 +====+===================+========================+ 813 | 1. | four.example.com. | 172.16.1.5, 172.16.2.5 | 814 +----+-------------------+------------------------+ 815 | 2. | six.example.com. | 3001:1::50 | 816 +----+-------------------+------------------------+ 817 | 3. | example.com. | 172.16.2.5 | 818 +----+-------------------+------------------------+ 819 820As discussed earlier, FQDN-to-domain matching is based on the longest 821match. The FQDN, "myhost.four.example.com.", will match the first domain 822("four.example.com") while "admin.example.com." will match the third 823domain ("example.com"). The FQDN, "other.example.net.", will fail to 824match any domain and is rejected. 825 826The following example configuration specifies the Forward DDNS Domains. 827 828:: 829 830 "DhcpDdns": { 831 "comment": "example configuration: forward part", 832 "forward-ddns": { 833 "ddns-domains": [ 834 { 835 "name": "four.example.com.", 836 "key-name": "", 837 "dns-servers": [ 838 { "ip-address": "172.16.1.5" }, 839 { "ip-address": "172.16.2.5" } 840 ] 841 }, 842 { 843 "name": "six.example.com.", 844 "key-name": "", 845 "dns-servers": [ 846 { "ip-address": "2001:db8::1" } 847 ] 848 }, 849 { 850 "name": "example.com.", 851 "key-name": "", 852 "dns-servers": [ 853 { "ip-address": "172.16.2.5" } 854 ], 855 "user-context": { "backup": false } 856 }, 857 858 ] 859 } 860 } 861 862Similarly, we need to construct the three Reverse DDNS Domains: 863 864.. table:: Reverse DDNS Domains Needed 865 866 +----+-----------------------------------+------------------------+ 867 | # | DDNS Domain Name | DNS Servers | 868 +====+===================================+========================+ 869 | 1. | 2.0.192.in-addr.arpa. | 172.16.1.5, 172.16.2.5 | 870 +----+-----------------------------------+------------------------+ 871 | 2. | 1.0.0.0.8.d.b.0.1.0.0.2.ip6.arpa. | 3001:1::50 | 872 +----+-----------------------------------+------------------------+ 873 | 3. | 0.182.in-addr.arpa. | 172.16.2.5 | 874 +----+-----------------------------------+------------------------+ 875 876An address of "192.0.2.150" will match the first domain, 877"2001:db8:1::10" will match the second domain, and "192.0.50.77" the 878third domain. 879 880These Reverse DDNS Domains are specified as follows: 881 882:: 883 884 "DhcpDdns": { 885 "comment": "example configuration: reverse part", 886 "reverse-ddns": { 887 "ddns-domains": [ 888 { 889 "name": "2.0.192.in-addr.arpa.", 890 "key-name": "", 891 "dns-servers": [ 892 { "ip-address": "172.16.1.5" }, 893 { "ip-address": "172.16.2.5" } 894 ] 895 } 896 { 897 "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.", 898 "key-name": "", 899 "dns-servers": [ 900 { "ip-address": "2001:db8::1" } 901 ] 902 } 903 { 904 "name": "0.192.in-addr.arpa.", 905 "key-name": "", 906 "dns-servers": [ 907 { "ip-address": "172.16.2.5" } 908 ] 909 } 910 ] 911 } 912 } 913 914DHCP-DDNS Server Statistics 915=========================== 916 917Kea version 2.0.0 introduced statistics support for the DHCP-DDNS. 918 919Statistics are divided in three groups: Name Change Request, DNS update 920and per TSIG key DNS updates. If the statistics of the first two groups 921are cumulative, i.e. not affected by configuration change or reload, 922per key statistics are reset to 0 when the underlying object is 923(re)created. 924 925Currently the statistics management is limited: 926 927- only integer samples (i.e. a counter and a timestamp) are used 928- the maximum sample count is 1 929- there is no API to remove one or all statistics 930- there is no API to set the maximum sample count or age 931 932.. note:: 933 934 Hook libraries like the GSS-TSIG add new statistics. 935 936A reference about Kea statistics can be found at :ref:`stats`. 937 938NCR Statistics 939-------------- 940 941The Name Change Request statistics are: 942 943- ``ncr-received`` - received valid NCRs 944- ``ncr-invalid`` - received invalid NCRs 945- ``ncr-error`` - errors in NCR receptions other than I/O cancel on shutdown 946 947DNS Update Statistics 948--------------------- 949 950The global DNS update statistics are: 951 952- ``update-sent`` - sent DNS updates 953- ``update-signed`` - sent DNS updates protected by TSIG 954- ``update-unsigned`` - sent DNS updates not protected by TSIG 955- ``update-success`` - DNS updates which completed with a success 956- ``update-timeout`` - DNS updates which completed on timeout 957- ``update-error`` - DNS updates which completed with an error other than 958 timeout 959 960Per TSIG key DNS Update Statistics 961---------------------------------- 962 963The per TSIG key DNS update statistics are: 964 965- ``update-sent`` - sent DNS updates 966- ``update-success`` - DNS updates which completed with a success 967- ``update-timeout`` - DNS updates which completed on timeout 968- ``update-error`` - DNS updates which completed with an error other than 969 timeout 970 971The name of a per key statistics is ``key[<key-DNS-name>].<stat-name>``, 972for instance the name of the ``update-sent`` statistics for the 973``key.example.com.`` TSIG key is ``key[key.example.com.].update-sent``. 974 975DHCP-DDNS Server Limitations 976============================ 977 978The following are the current limitations of the DHCP-DDNS Server. 979 980- Requests received from the DHCP servers are placed in a queue until 981 they are processed. Currently, all queued requests are lost if the 982 server shuts down. 983 984Supported Standards 985=================== 986 987The following RFCs are supported by the DHCP-DDNS server: 988 989- *Secret Key Transaction Authentication for DNS (TSIG)*, `RFC 2845 990 <https://tools.ietf.org/html/rfc2845>`__: All DNS Update packets sent and 991 received by DHCP-DDNS server can be protected by TSIG signatures. 992 993- *Dynamic Updates in the Domain Name System (DNS UPDATE)*, `RFC 2136 994 <https://tools.ietf.org/html/rfc2136>`__: The whole DNS Update mechanism is 995 supported. 996 997- *Resolution of Fully Qualified Domain Name (FQDN) Conflicts among Dynamic Host 998 Configuration Protocol (DHCP) Clients*, `RFC 4703 999 <https://tools.ietf.org/html/rfc4703>`__: The DHCP-DDNS takes care of the 1000 conflict resolution. This capability is used by DHCPv4 and DHCPv6 servers. 1001 1002- *A DNS Resource Record (RR) for Encoding Dynamic Host Configuration Protocol 1003 (DHCP) Information (DHCID RR)*, `RFC 4701 1004 <https://tools.ietf.org/html/rfc4701>`__: The DHCP-DDNS server uses the DHCID 1005 records. 1006