The DHCP-DDNS Server

Configuring the DHCP-DDNS Server Before starting kea-dhcp-ddns module for the first time, a configuration file needs to be created. The following default configuration is a template that can be customised to your requirements. "DhcpDdns": { "ip_address": "127.0.0.1", "port": 53001, "dns_server_timeout": 100, "ncr_protocol": "UDP", "ncr_format": "JSON", "tsig_keys": [ ], "forward_ddns": { "ddns_domains": [ ] }, "reverse_ddns": { "ddns_domains": [ ] } } The configuration can be divided as follows, each of which is described in its own section: Global Server Parameters - values which control connectivity and global server behavior TSIG Key Info - defines the TSIG keys used for secure traffic with DNS servers Forward DDNS - defines the catalog of Forward DDNS Domains Reverse DDNS - defines the catalog of Forward DDNS Domains

Global Server Parameters ip_address - IP address on which D2 listens for requests. The default is the local loopback interface at address 127.0.0.1. You may specify either an IPv4 or IPv6 address. port - Port on which D2 listens for requests. The default value is 53001. dns_server_timeout - The maximum amount of time in milliseconds, that D2 will wait for a response from a DNS server to a single DNS update message. ncr_protocol - Packet format to use when sending requests to D2. Currently only JSON format is supported. Other formats may be available in future releases. ncr_format - Socket protocol to use when sending requests to D2. Currently only UDP is supported. TCP may be available in an upcoming release. D2 must listen for change requests on a known address and port. By default it listens at 127.0.0.1 on port 53001. The following example illustrates how to change D2's global parameters so it will listen at 192.168.1.10 port 900: "DhcpDdns": { "ip_address": "192.168.1.10", "port": 900, ... } } It is possible for a malicious attacker to send bogus NameChangeRequests to the DHCP-DDNS server. Addresses other than the IPv4 or IPv6 loopback addresses (127.0.0.1 or ::1) should only be used for testing purposes, but note that local users may still communicate with the DHCP-DDNS server. A future version of Kea will implement authentication to guard against such attacks. If the ip_address and port are changed, it will be necessary to change the corresponding values in the DHCP servers' "dhcp-ddns" configuration section.

TSIG Key List A DDNS protocol exchange can be conducted with or without TSIG (defined in RFC 2845). This configuration section allows the administrator to define the set of TSIG keys that may be used in such exchanges. To use TSIG when updating entries in a DNS Domain, a key must be defined in the TSIG Key List and referenced by name in that domain's configuration entry. When D2 matches a change request to a domain, it checks whether the domain has a TSIG key associated with it. If so, D2 will use that key to sign DNS update messages sent to and verify responses received from the domain's DNS server(s). For each TSIG key required by the DNS servers that D2 will be working with there must be a corresponding TSIG key in the TSIG Key list. As one might gather from the name, the tsig_key section of the D2 configuration lists the TSIG keys. Each entry describes a TSIG key used by one or more DNS servers to authenticate requests and sign responses. Every entry in the list has three parameters: name - a unique text label used to identify this key within the list. This value is used to specify which key (if any) should be used when updating a specific domain. So long as it is unique its content is arbitrary, although for clarity and ease of maintenance it is recommended that it match the name used on the DNS server(s). It cannot be blank. algorithm - specifies which hashing algorithm should be used with this key. This value must specify the same algorithm used for the key on the DNS server(s). The supported algorithms are listed below: HMAC-MD5 HMAC-SHA1 HMAC-SHA224 HMAC-SHA256 HMAC-SHA384 HMAC-SHA512 This value is not case sensitive. digest_bits - is used to specify the minimum truncated length in bits. The default value 0 means truncation is forbidden, not 0 values must be an integral number of octets, be greater than 80 and the half of the full length. Note in BIND9 this parameter is appended after a dash to the algorithm name. secret - is used to specify the shared secret key code for this key. This value is case sensitive and must exactly match the value specified on the DNS server(s). It is a base64-encoded text value. As an example, suppose that a domain D2 will be updating is maintained by a BIND9 DNS server which requires dynamic updates to be secured with TSIG. Suppose further that the entry for the TSIG key in BIND9's named.conf file looks like this: : key "key.four.example.com." { algorithm hmac-sha224; secret "bZEG7Ow8OgAUPfLWV3aAUQ=="; }; : By default, the TSIG Key list is empty: "DhcpDdns": { "tsig_keys": [ ], ... } We must extend the list with a new key: "DhcpDdns": { "tsig_keys": [ { "name": "key.four.example.com.", "algorithm": "HMAC-SHA224", "secret": "bZEG7Ow8OgAUPfLWV3aAUQ==" } ], ... } These steps would be repeated for each TSIG key needed. Note that the same TSIG key can be used with more than one domain.

Forward DDNS The Forward DDNS section is used to configure D2's forward update behavior. Currently it contains a single parameter, the catalog of forward DDNS Domains, which is a list of structures. "DhcpDdns": { "forward_ddns": { "ddns_domains": [ ] }, ... } By default, this list is empty, which will cause the server to ignore the forward update portions of requests.

Adding Forward DDNS Domains A forward DDNS Domain maps a forward DNS zone to a set of DNS servers which maintain the forward DNS data (i.e. name to address mapping) for that zone. You will need one forward DDNS Domain for each zone you wish to service. It may very well be that some or all of your zones are maintained by the same servers. You will still need one DDNS Domain per zone. Remember that matching a request to the appropriate server(s) is done by zone and a DDNS Domain only defines a single zone. This section describes how to add Forward DDNS Domains. Repeat these steps for each Forward DDNS Domain desired. Each Forward DDNS Domain has the following parameters: name - The fully qualified domain name (or zone) that this DDNS Domain can update. This is value used to compare against the request FQDN during forward matching. It must be unique within the catalog. key_name - If TSIG is used with this domain's servers, this value should be the name of the key from within the TSIG Key List to use. If the value is blank (the default), TSIG will not be used in DDNS conversations with this domain's servers. dns_servers - A list of one or more DNS servers which can conduct the server side of the DDNS protocol for this domain. The servers are used in a first to last preference. In other words, when D2 begins to process a request for this domain it will pick the first server in this list and attempt to communicate with it. If that attempt fails, it will move to next one in the list and so on until the it achieves success or the list is exhausted. To create a new forward DDNS Domain, one must add a new domain element and set its parameters: "DhcpDdns": { "forward_ddns": { "ddns_domains": [ { "name": "other.example.com.", "key_name": "", "dns_servers": [ ] } ] } } It is permissible to add a domain without any servers. If that domain should be matched to a request, however, the request will fail. In order to make the domain useful though, we must add at least one DNS server to it.

Adding Forward DNS Servers This section describes how to add DNS servers to a Forward DDNS Domain. Repeat them for as many servers as desired for a each domain. Forward DNS Server entries represent actual DNS servers which support the server side of the DDNS protocol. Each Forward DNS Server has the following parameters: hostname - The resolvable host name of the DNS server. This value is not yet implemented. ip_address - The IP address at which the server listens for DDNS requests. This may be either an IPv4 or an IPv6 address. port - The port on which the server listens for DDNS requests. It defaults to the standard DNS service port of 53. To create a new forward DNS Server, one must add a new server element to the domain and fill in its parameters. If for example the service is running at "172.88.99.10", then set it as follows: "DhcpDdns": { "forward_ddns": { "ddns_domains": [ { "name": "other.example.com.", "key_name": "", "dns_servers": [ { "hostname": "", "ip_address": "172.88.99.10", "port": 53 } ] } ] } } As stated earlier, "hostname" is not yet supported so, the parameter "ip_address" must be set to the address of the DNS server.

Reverse DDNS The Reverse DDNS section is used to configure D2's reverse update behavior, and the concepts are the same as for the forward DDNS section. Currently it contains a single parameter, the catalog of reverse DDNS Domains, which is a list of structures. "DhcpDdns": { "reverse_ddns": { "ddns_domains": [ ] } ... } By default, this list is empty, which will cause the server to ignore the reverse update portions of requests.

Adding Reverse DDNS Domains A reverse DDNS Domain maps a reverse DNS zone to a set of DNS servers which maintain the reverse DNS data (address to name mapping) for that zone. You will need one reverse DDNS Domain for each zone you wish to service. It may very well be that some or all of your zones are maintained by the same servers; even then, you will still need one DDNS Domain entry for each zone. Remember that matching a request to the appropriate server(s) is done by zone and a DDNS Domain only defines a single zone. This section describes how to add Reverse DDNS Domains. Repeat these steps for each Reverse DDNS Domain desired. Each Reverse DDNS Domain has the following parameters: name - The fully qualified reverse zone that this DDNS Domain can update. This is the value used during reverse matching which will compare it with a reversed version of the request's lease address. The zone name should follow the appropriate standards: for example, to to support the IPv4 subnet 172.16.1, the name should be. "1.16.172.in-addr.arpa.". Similarly, to support an IPv6 subent of 2001:db8:1, the name should be "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa." Whatever the name, it must be unique within the catalog. key_name - If TSIG should be used with this domain's servers, then this value should be the name of that key from the TSIG Key List. If the value is blank (the default), TSIG will not be used in DDNS conversations with this domain's servers. Currently this value is not used as TSIG has not been implemented. dns_servers - a list of one or more DNS servers which can conduct the server side of the DDNS protocol for this domain. Currently the servers are used in a first to last preference. In other words, when D2 begins to process a request for this domain it will pick the first server in this list and attempt to communicate with it. If that attempt fails, it will move to next one in the list and so on until the it achieves success or the list is exhausted. To create a new reverse DDNS Domain, one must add a new domain element and set its parameters. For example, to support subnet 2001:db8:1::, the following configuration could be used: "DhcpDdns": { "reverse_ddns": { "ddns_domains": [ { "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.", "key_name": "", "dns_servers": [ ] } ] } } It is permissible to add a domain without any servers. If that domain should be matched to a request, however, the request will fail. In order to make the domain useful though, we must add at least one DNS server to it.

Adding Reverse DNS Servers This section describes how to add DNS servers to a Reverse DDNS Domain. Repeat them for as many servers as desired for each domain. Reverse DNS Server entries represents a actual DNS servers which support the server side of the DDNS protocol. Each Reverse DNS Server has the following parameters: hostname - The resolvable host name of the DNS server. This value is currently ignored. ip_address - The IP address at which the server listens for DDNS requests. port - The port on which the server listens for DDNS requests. It defaults to the standard DNS service port of 53. To create a new reverse DNS Server, one must first add a new server element to the domain and fill in its parameters. If for example the service is running at "172.88.99.10", then set it as follows: "DhcpDdns": { "reverse_ddns": { "ddns_domains": [ { "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.", "key_name": "", "dns_servers": [ { "hostname": "", "ip_address": "172.88.99.10", "port": 53 } ] } ] } } As stated earlier, "hostname" is not yet supported so, the parameter "ip_address" must be set to the address of the DNS server.

Example DHCP-DDNS Server Configuration This section provides an example DHCP-DDNS server configuration based on a small example network. Let's suppose our example network has three domains, each with their own subnet. Our example network Domain Subnet Forward DNS Servers Reverse DNS Servers four.example.com 192.0.2.0/24 172.16.1.5, 172.16.2.5 172.16.1.5, 172.16.2.5 six.example.com 2001:db8:1::/64 3001:1::50 3001:1::51 example.com 192.0.0.0/16 172.16.2.5 172.16.2.5

We need to construct three forward DDNS Domains: Forward DDNS Domains Needed # DDNS Domain Name DNS Servers 1. four.example.com. 172.16.1.5, 172.16.2.5 2. six.example.com. 3001:1::50 3. example.com. 172.16.2.5

As discussed earlier, FQDN to domain matching is based on the longest match. The FQDN, "myhost.four.example.com.", will match the first domain ("four.example.com") while "admin.example.com." will match the third domain ("example.com"). The FQDN, "other.example.net." will fail to match any domain and would be rejected. The following example configuration specified the Forward DDNS Domains. "DhcpDdns": { "forward_ddns": { "ddns_domains": [ { "name": "four.example.com.", "key_name": "", "dns_servers": [ { "ip_address": "172.16.1.5" }, { "ip_address": "172.16.2.5" } ] }, { "name": "six.example.com.", "key_name": "", "dns_servers": [ { "ip_address": "2001:db8::1" } ] }, { "name": "example.com.", "key_name": "", "dns_servers": [ { "ip_address": "172.16.2.5" } ] }, ] } } Similarly, we need to construct the three reverse DDNS Domains: Reverse DDNS Domains Needed # DDNS Domain Name DNS Servers 1. 2.0.192.in-addr.arpa. 172.16.1.5, 172.16.2.5 2. 1.0.0.0.8.d.b.0.1.0.0.2.ip6.arpa. 3001:1::50 3. 0.182.in-addr.arpa. 172.16.2.5

An address of "192.0.2.150" will match the first domain, "2001:db8:1::10" will match the second domain, and "192.0.50.77" the third domain. These Reverse DDNS Domains are specified as follows: "DhcpDdns": { "reverse_ddns": { "ddns_domains": [ { "name": "2.0.192.in-addr.arpa.", "key_name": "", "dns_servers": [ { "ip_address": "172.16.1.5" }, { "ip_address": "172.16.2.5" } ] } { "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.", "key_name": "", "dns_servers": [ { "ip_address": "2001:db8::1" } ] } { "name": "0.192.in-addr.arpa.", "key_name": "", "dns_servers": [ { "ip_address": "172.16.2.5" } ] } ] } }