From 439ef5986f51a9da98a9b878165f90adfb760b7b Mon Sep 17 00:00:00 2001 From: Tomek Mrugalski Date: Wed, 11 Jun 2014 14:21:54 +0200 Subject: [PATCH] [3418] Remaining chapters moved to separate files. --- doc/guide/Makefile.am | 3 +- doc/guide/ddns.xml | 811 +++++++ doc/guide/dhcp4-srv.xml | 1554 ++++++++++++++ doc/guide/dhcp6-srv.xml | 1545 ++++++++++++++ doc/guide/intro.xml | 288 +++ doc/guide/kea-guide.xml | 4335 +------------------------------------- doc/guide/libdhcp.xml | 56 + doc/guide/quickstart.xml | 105 + 8 files changed, 4371 insertions(+), 4326 deletions(-) create mode 100644 doc/guide/ddns.xml create mode 100644 doc/guide/dhcp4-srv.xml create mode 100644 doc/guide/dhcp6-srv.xml create mode 100644 doc/guide/intro.xml create mode 100644 doc/guide/libdhcp.xml create mode 100644 doc/guide/quickstart.xml diff --git a/doc/guide/Makefile.am b/doc/guide/Makefile.am index 840f88ab9b..a7e8d315ea 100644 --- a/doc/guide/Makefile.am +++ b/doc/guide/Makefile.am @@ -5,7 +5,8 @@ DOCS = kea-guide.txt dist_doc_DATA = $(DOCS) dist_html_DATA = $(HTMLDOCS) kea-guide.css -DOCBOOK = kea-guide.xml logging.xml config.xml install.xml +DOCBOOK = kea-guide.xml intro.xml quickstart.xml install.xml config.xml +DOCBOOK += dhcp4-srv.xml dhcp6-srv.xml logging.xml EXTRA_DIST = $(DOCBOOK) DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml diff --git a/doc/guide/ddns.xml b/doc/guide/ddns.xml new file mode 100644 index 0000000000..3abfc4be19 --- /dev/null +++ b/doc/guide/ddns.xml @@ -0,0 +1,811 @@ + + +]> + + + The DHCP-DDNS Server + + The DHCP-DDNS Server (b10-dhcp-ddns, known informally as D2) conducts the client side of + the DDNS protocol (defined in RFC 2136) on behalf of the DHCPv4 and DHCPv6 + servers (b10-dhcp4 and b10-dhcp6 respectively). The DHCP servers construct + DDNS update requests, known as NameChangeRequests (NCRs), based upon DHCP + lease change events and then post these to D2. D2 attempts to match + each such request to the appropriate DNS server(s) and carry out the + necessary conversation with those servers to update the DNS data. + + + In order to match a request to appropriate DNS servers, D2 must have a + catalog of servers from which to select. In fact, D2 has two such catalogs, + one for forward DNS and one for reverse DNS; these catalogs are referred + to as DDNS Domain Lists. Each list consists of one or more named DDNS + Domains. Further, each DDNS Domain has a list of of one or more DNS + servers that publish the DNS data for that domain. + + + When conducting forward domain matching, D2 will compare the FQDN in + the request against the name of each forward DDNS Domain. The domain + whose name matches the longest portion of the FQDN is considered the + best match. For example, if the FQDN is "myhost.sample.example.com.", + and there are two forward domains in the catalog: "sample.example.com." + and "example.com.", the former is regarded as the best match. In some + cases, it may not be possible to find a suitable match. Given the same two + forward domains there would be no match for the FQDN, "bogus.net", so the + request would be rejected. Finally, if there are no forward DDNS Domains + defined, D2 will simply disregard the forward update portion of requests. + + + When conducting reverse domain matching, D2 constructs a reverse + FQDN from the lease address in the request and compare that against + the name of each reverse DDNS Domain. Again, the domain whose name matches + the longest portion of the FQDN is considered the best match. For instance, + if the lease address is "172.16.1.40" and there are two reverse domains in + the catalog: "1.16.172.in-addr.arpa." and "16.172.in-addr.arpa", the + former is the best match. As with forward matching, it is possible to not + find a suitable match. Given the same two domains, there would be no + match for the lease address, "192.168.1.50", and the request would be + rejected. Finally, if there are no reverse DDNS Domains defined, D2 will + simply disregard the reverse update portion of requests. + +
+ Starting and Stopping the DHCP-DDNS Server + + b10-dhcp-ddns is the BIND 10 DHCP-DDNS server and, + like other parts of BIND 10, is configured through the + bindctl program. + + + After starting BIND 10 and entering bindctl, the first step in + configuring the server is to add it to the list of running BIND 10 + services. + +> config add Init/components b10-dhcp-ddns +> config set Init/components/b10-dhcp-ddns/kind dispensable +> config commit + + + + To remove b10-dhcp-ddns from the set of running services, + the b10-dhcp-ddns is removed from list of Init components: + +> config remove Init/components b10-dhcp-ddns +> config commit + + + + Note that the server was only removed from the list, so it will not be + automatically restarted, but the server itself is still running. Hence it + is usually desired to stop it: + + +> DhcpDdns shutdown + + + Upon start up the module will load its configuration and begin listening + for NCRs based on that configuration. + +
+
+ Configuring the DHCP-DDNS Server + + Once the server is started, it can be configured. To view the + current configuration, use the following command in bindctl: + +> config show DhcpDdns + When starting b10-dhcp-ddns module for the first time, the default + configuration will be available. It will look similar to this: + +> config show DhcpDdns +DhcpDdns/ip_address "127.0.0.1" string (default) +DhcpDdns/port 53001 integer (default) +DhcpDdns/dns_server_timeout 100 integer (default) +DhcpDdns/ncr_protocol "UDP" string (default) +DhcpDdns/ncr_format "JSON" string (default) +DhcpDdns/tsig_keys [] list (default) +DhcpDdns/forward_ddns/ddns_domains [] list (default) +DhcpDdns/reverse_ddns/ddns_domains [] list (default) + + + (While displayed, the parameter "interface" is not implemented, and + will be removed in the near future.) + + + + 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. + + + ncr_format - Socket protocol to use when sending requests to D2. + Currently only UDP is supported. TCP may be available in an upcoming + release. + + + 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. + + + 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. + + + + 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: + +> config set DhcpDdns/ip_address "192.168.1.10" +> config set DhcpDdns/port 900 +> config commit + + + + + When the DHCP-DDNS server is configured to listen at an address + other than the loopback address (127.0.0.1 or ::1), it is possible + for a malicious attacker to send bogus NameChangeRequests to it + and change entries in the DNS. For this reason, addresses other + than the IPv4 or IPv6 loopback addresses should only be used + for testing purposes. 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 repsonses 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. + + + + + 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: + +> config show DhcpDdns/tsig_keys +DhcpDdns/tsig_keys [] list (default) + + We must first create a new key in the list: + +> config add DhcpDdns/tsig_keys + + Displaying the new element, reveals: + +> config show DhcpDdns/tsig_keys[0] +DhcpDdns/tsig_keys[0]/name "" string (default) +DhcpDdns/tsig_keys[0]/algorithm "HMAC-MD5" string (modified) +DhcpDdns/tsig_keys[0]/secret "" string (default) + + Now set all three values to match BIND9's key: + +> config set DhcpDdns/tsig_keys[0]/name "key.four.example.com" +> config set DhcpDdns/tsig_keys[0]/algorithm "HMAC-SHA224" +> config set DhcpDdns/tsig_keys[0]/secret "bZEG7Ow8OgAUPfLWV3aAUQ==" +> config commit + + + 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: + +> config show DhcpDdns/forward_ddns/ +DhcpDdns/forward_ddns/ddns_domains [] list (default) + + 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 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. + + + The 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. Currently + TSIG has not been implemented, so this value is ignored. + + + + + 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 first add a new domain + element: + +> config add DhcpDdns/forward_ddns/ddns_domains + + Displaying the DDNS Domain reveals this: + +> config show DhcpDdns/forward_ddns/ddns_domains[0] +DhcpDdns/forward_ddns/ddns_domains[0]/name "" string (default) +DhcpDdns/forward_ddns/ddns_domains[0]/key_name "" string (default) +DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers [] list (default) + + To set the domain's name to "other.example.com": + +> config set DhcpDdns/forward_ddns/ddns_domains[1]/name "other.example.com" +> config commit + + 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 + + The 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 first add a new server + element to the domain: + +> config add DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers + + Displaying the DNS Server element should appear as follows: + +> config show DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0] +DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]/hostname "" string (default) +DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]/ip_address "" string (default) +DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]/port 53 integer(default) + + As stated earlier, "hostname" is not yet supported so, the parameter + "ip_address" must be set to the address of the DNS server. If for + example the service is running at "172.88.99.10", then set it as + follows: + +> config set DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]/ip_address "172.88.99.10" +> config commit + + +
+ +
+ +
+ +
+ 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: + +> config show DhcpDdns/reverse_ddns/ +DhcpDdns/reverse_ddns/ddns_domains [] list (default) + + 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 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. + + + The 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 first add a new domain + element: + +> config add DhcpDdns/reverse_ddns/ddns_domains + + Displaying the DDNS Domain reveals this: + +> config show DhcpDdns/reverse_ddns/ddns_domains[0] +DhcpDdns/reverse_ddns/ddns_domains[0]/name "" string (default) +DhcpDdns/reverse_ddns/ddns_domains[0]/key_name "" string (default) +DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers [] list (default) + + For domain supporting the subnet 2001:db8:1::, we would set the + domain's name as follows: + +> config set DhcpDdns/reverse_ddns/ddns_domains[1]/name "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa." +> config commit + + 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 + + The section describes how to add DNS servers to a Reverse DDNS Domain. + Repeat them for as many servers as desired for a 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: + +> config add DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers + + Displaying the DNS Server element should appear as follows: + +> config show DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0] +DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/hostname "" string (default) +DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/ip_address "" string (default) +DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/port 53 integer(default) + + As stated earlier, "hostname" is not yet supported so, the parameter + "ip_address" must be set to the address of the DNS server. If for + example the service is running at "172.88.99.10", then set it as + follows: + +> config set DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/ip_address "172.88.99.10" +> config commit + + +
+ +
+ +
+ +
+ 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 series of commands in bindctl will create the Forward + DDNS Domains. + + +> config add DhcpDdns/forward_ddns/ddns_domains +> config set DhcpDdns/forward_ddns/ddns_domains[0]/name "four.example.com." +> config add DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers +> config set DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]/ip_address "172.16.1.5" +> config add DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers +> config set DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[1]/ip_address "172.16.2.5" +> +> config add DhcpDdns/forward_ddns/ddns_domains +> config set DhcpDdns/forward_ddns/ddns_domains[1]/name "six.example.com." +> config add DhcpDdns/forward_ddns/ddns_domains[1]/dns_servers +> config set DhcpDdns/forward_ddns/ddns_domains[1]/dns_servers[0]/ip_address "3001:1::50:" +> +> config add DhcpDdns/forward_ddns/ddns_domains +> config set DhcpDdns/forward_ddns/ddns_domains[2]/name "example.com." +> config add DhcpDdns/forward_ddns/ddns_domains[2]/dns_servers +> config set DhcpDdns/forward_ddns/ddns_domains[2]/dns_servers[0]/ip_address "172.16.2.5" +> +> config commit + + + + + 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. + + + The following series of commands in bindctl will create our Reverse + DDNS Domains. + + +> config add DhcpDdns/reverse_ddns/ddns_domains +> config set DhcpDdns/reverse_ddns/ddns_domains[0]/name "2.0.192.in-addr.arpa." +> config add DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers +> config set DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/ip_address "172.16.1.5" +> config add DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers +> config set DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[1]/ip_address "172.16.2.5" +> +> config add DhcpDdns/reverse_ddns/ddns_domains +> config set DhcpDdns/reverse_ddns/ddns_domains[1]/name "1.0.0.0.8.d.b.0.1.0.0.2.ip6.arpa." +> config add DhcpDdns/reverse_ddns/ddns_domains[1]/dns_servers +> config set DhcpDdns/reverse_ddns/ddns_domains[1]/dns_servers[0]/ip_address "3001:1::50:" +> +> config add DhcpDdns/reverse_ddns/ddns_domains +> config set DhcpDdns/reverse_ddns/ddns_domains[2]/name "0.192.in-addr.arpa." +> config add DhcpDdns/reverse_ddns/ddns_domains[2]/dns_servers +> config set DhcpDdns/reverse_ddns/ddns_domains[2]/dns_servers[0]/ip_address "172.16.2.5" +> +> config commit + + + +
+
+
+ DHCP-DDNS Server Limitations + The following are the current limitations of the DHCP-DDNS Server. + + + + Requests received from the DHCP servers are placed in a + queue until they are processed. Currently all queued requests + are lost when the server shuts down. + + + + + TSIG Authentication (RFC 2845) + is not supported yet. + + + +
+ diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml new file mode 100644 index 0000000000..426f14b81b --- /dev/null +++ b/doc/guide/dhcp4-srv.xml @@ -0,0 +1,1554 @@ + + +]> + + + The DHCPv4 Server + +
+ Starting and Stopping the DHCPv4 Server + + + b10-dhcp4 is the Kea DHCPv4 server and is configured + through the bindctl program. + + + After starting bind10 and entering bindctl, the first step + in configuring the server is to add it to the list of running services. + +> config add Init/components b10-dhcp4 +> config set Init/components/b10-dhcp4/kind dispensable +> config commit + + + + To remove b10-dhcp4 from the set of running services, + the b10-dhcp4 is removed from list of Init components: + +> config remove Init/components b10-dhcp4 +> config commit + + + + Note that the server was only removed from the list, so BIND10 will not + restart it, but the server itself is still running. Hence it is usually + desired to stop it: + +> Dhcp4 shutdown + + + + + On start-up, the server will detect available network interfaces + and will attempt to open UDP sockets on all interfaces that + are up, running, are not loopback, and have IPv4 address + assigned. + + The server will then listen to incoming traffic. Currently + supported client messages are DISCOVER and REQUEST. The server + will respond to them with OFFER and ACK, respectively. + + Since the DHCPv4 server opens privileged ports, it requires root + access. Make sure you run this daemon as root. + + +
+ +
+ Configuring the DHCPv4 Server + + Once the server is started, it can be configured. To view the + current configuration, use the following command in bindctl: + +> config show Dhcp4 + When starting the DHCPv4 daemon for the first time, the default configuration + will be available. It will look similar to this: + +> config show Dhcp4 +Dhcp4/hooks-libraries [] list (default) +Dhcp4/interfaces/ list +Dhcp4/renew-timer 1800 integer +Dhcp4/rebind-timer 2000 integer (default) +Dhcp4/valid-lifetime 4000 integer (default) +Dhcp4/next-server "" string (default) +Dhcp4/echo-client-id true boolean (default) +Dhcp4/option-def [] list (default) +Dhcp4/option-data [] list (default) +Dhcp4/lease-database/type "" string (default) +Dhcp4/lease-database/name "" string (default) +Dhcp4/lease-database/user "" string (default) +Dhcp4/lease-database/host "" string (default) +Dhcp4/lease-database/password "" string (default) +Dhcp4/subnet4/ list +Dhcp4/dhcp-ddns/enable-updates true boolean +Dhcp4/dhcp-ddns/server-ip "127.0.0.1" string +Dhcp4/dhcp-ddns/server-port 53001 integer +Dhcp4/dhcp-ddns/sender-ip "" string +Dhcp4/dhcp-ddns/sender-port 0 integer +Dhcp4/dhcp-ddns/max-queue-size 1024 integer +Dhcp4/dhcp-ddns/ncr-protocol "UDP" string +Dhcp4/dhcp-ddns/ncr-format "JSON" string +Dhcp4/dhcp-ddns/override-no-update false boolean +Dhcp4/dhcp-ddns/override-client-update false boolean +Dhcp4/dhcp-ddns/replace-client-name false boolean +Dhcp4/dhcp-ddns/generated-prefix "myhost" string +Dhcp4/dhcp-ddns/qualifying-suffix "example.com" string + + + + + To change one of the parameters, simply follow + the usual bindctl procedure. For example, to make the + leases longer, change their valid-lifetime parameter: + +> config set Dhcp4/valid-lifetime 7200 +> config commit + Please note that most Dhcp4 parameters are of global scope + and apply to all defined subnets, unless they are overridden on a + per-subnet basis. + + + The renew-timer and rebind-timer are optional. If they are not specified, + the DHCPv4 options 58 and 59 are not sent in the server's response to the + client. + + +
+ Default storage for leases + + The server is able to store lease data in different repositories. Larger deployments + may elect to store leases in a database. + describes one way to do it. + By default, the server will use a CSV file rather than a database to store + lease information. One of the advantages of using a file is that it eliminates + dependency on third party database software. + + + The configuration of the file backend (Memfile) + is controlled through the Dhcp4/lease-database parameters. When default + parameters are used, the Memfile backend will write leases to a disk in the + [bind10-install-dir]/var/bind10/kea-leases4.csv. + + + It is possible to alter the default location of the lease file. The following + configuration: + +> config set Dhcp4/lease-database/type "memfile" +> config set Dhcp4/lease-database/persist true +> config set Dhcp4/lease-database/name "/tmp/kea-leases4.csv" +> config commit + + will change the default location of the lease file to /tmp/kea-leases4.csv. + + + The "persist" parameter controls whether the leases are written to disk. + It is strongly recommended that this parameter is set to "true" at all times + during the normal operation of the server + +
+ +
+ Database Configuration + + All leases issued by the server are stored in the lease database. Currently + there are 3 database backends available: MySQL, PostgreSQL and memfile. + + + The server comes with an in-memory database ("memfile") configured as the default + database. This is used for internal testing and is not supported. In addition, + it does not store lease information on disk: lease information will be lost if the + server is restarted. + + , and so the server must be configured to + access the correct database with the appropriate credentials. + + + + Database access information must be configured for the DHCPv4 server, even if + it has already been configured for the DHCPv6 server. The servers store their + information independently, so each server can use a separate + database or both servers can use the same database. + + + + Database configuration is controlled through the Dhcp4/lease-database parameters. + The type of the database must be set to "mysql", "postgresql" or "memfile": + +> config set Dhcp4/lease-database/type "mysql" + + Next, the name of the database is to hold the leases must be set: this is the + name used when the lease database was created (see + or ). + +> config set Dhcp4/lease-database/name "database-name" + + If the database is located on a different system to the DHCPv4 server, the + database host name must also be specified (although note that this configuration + may have a severe impact on server performance): + +> config set Dhcp4/lease-database/host "remote-host-name" + + The usual state of affairs will be to have the database on the same machine as the + DHCPv4 server. In this case, set the value to the empty string (this is the default): + +> config set Dhcp4/lease-database/host "" + + + + Finally, the credentials of the account under which the server will access the database + should be set: + +> config set Dhcp4/lease-database/user "user-name" +> config set Dhcp4/lease-database/password "password" + + If there is no password to the account, set the password to the empty string "". (This is also the default.) + + + The password is echoed when entered and is stored in clear text in the configuration + database. Improved password security will be added in a future version of Kea. + +
+ +
+ Interface selection + + When DHCPv4 server starts up, by default it will listen to the DHCP + traffic and respond to it on all interfaces detected during startup. + However, in many cases it is desired to configure the server to listen and + respond on selected interfaces only. The sample commands in this section + show how to make interface selection using bindctl. + + + The default configuration can be presented with the following command: + +> config show Dhcp4/interfaces +Dhcp4/interfaces[0] "*" string + An asterisk sign plays a role of the wildcard and means "listen on all interfaces". + + + In order to override the default configuration, the existing entry can be replaced + with the actual interface name: + +> config set Dhcp4/interfaces[0] eth1 +> config commit + Other interface names can be added on one-by-one basis: + +> config add Dhcp4/interfaces eth2 +> config commit + Configuration will now contain two interfaces which can be presented as follows: + +> config show Dhcp4/interfaces +Dhcp4/interfaces[0] "eth1" string +Dhcp4/interfaces[1] "eth2" string + When configuration gets committed, the server will start to listen on + eth1 and eth2 interfaces only. + + + It is possible to use wildcard interface name (asterisk) concurrently with explicit + interface names: + +> config add Dhcp4/interfaces * +> config commit + This will result in the following configuration: + +> config show Dhcp4/interfaces +Dhcp4/interfaces[0] "eth1" string +Dhcp4/interfaces[1] "eth2" string +Dhcp4/interfaces[2] "*" string + The presence of the wildcard name implies that server will listen on all interfaces. + In order to fall back to the previous configuration when server listens on eth1 and eth2: + +> config remove Dhcp4/interfaces[2] +> config commit + +
+ +
+ IPv4 Subnet Identifier + + Subnet identifier is a unique number associated with a particular subnet. + In principle, it is used to associate clients' leases with respective subnets. + When subnet identifier is not specified for a subnet being configured, it will + be automatically assigned by the configuration mechanism. The identifiers + are assigned from 1 and are monotonically increased for each subsequent + subnet: 1, 2, 3 .... + + + If there are multiple subnets configured with auto-generated identifiers and + one of them is removed, the subnet identifiers may be renumbered. For example: + if there are 4 subnets and 3rd is removed the last subnet will be assigned + identifier that the 3rd subnet had before removal. As a result, the leases + stored in the lease database for subnet 3 are now associated with the + subnet 4, which may have unexpected consequences. In the future it is planned + to implement the mechanism to preserve auto-generated subnet ids upon removal + of one of the subnets. Currently, the only remedy for this issue is to + manually specify the unique subnet identifier for each subnet. + + + The following configuration: + +> config add Dhcp4/subnet4 +> config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24" +> config set Dhcp4/subnet4[0]/id 1024 +> config commit + + will assign the arbitrary subnet identifier to the newly configured subnet. + This identifier will not change for this subnet until "id" parameter is + removed or set to 0. The value of 0 forces auto-generation of subnet + identifier. + +
+ +
+ Configuration of IPv4 Address Pools + + The essential role of DHCPv4 server is address assignment. The server + has to be configured with at least one subnet and one pool of dynamic + addresses to be managed. For example, assume that the server + is connected to a network segment that uses the 192.0.2.0/24 + prefix. The Administrator of that network has decided that addresses from range + 192.0.2.10 to 192.0.2.20 are going to be managed by the Dhcp4 + server. Such a configuration can be achieved in the following way: + +> config add Dhcp4/subnet4 +> config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24" +> config set Dhcp4/subnet4[0]/pool [ "192.0.2.10 - 192.0.2.20" ] +> config commit + Note that subnet is defined as a simple string, but the pool parameter + is actually a list of pools: for this reason, the pool definition is + enclosed in square brackets, even though only one range of addresses + is specified. + It is possible to define more than one pool in a + subnet: continuing the previous example, further assume that + 192.0.2.64/26 should be also be managed by the server. It could be written as + 192.0.2.64 to 192.0.2.127. Alternatively, it can be expressed more simply as + 192.0.2.64/26. Both formats are supported by Dhcp4 and can be mixed in the pool list. + For example, one could define the following pools: + +> config set Dhcp4/subnet4[0]/pool [ "192.0.2.10-192.0.2.20", "192.0.2.64/26" ] +> config commit + The number of pools is not limited, but for performance reasons it is recommended to + use as few as possible. Space and tabulations in pool definitions are ignored, so + spaces before and after hyphen are optional. They can be used to improve readability. + + + The server may be configured to serve more than one subnet. To add a second subnet, + use a command similar to the following: + +> config add Dhcp4/subnet4 +> config set Dhcp4/subnet4[1]/subnet "192.0.3.0/24" +> config set Dhcp4/subnet4[1]/pool [ "192.0.3.0/24" ] +> config commit + Arrays are counted from 0. subnet[0] refers to the subnet defined in the + previous example. The config add Dhcp4/subnet4 command adds + another (second) subnet. It can be referred to as + Dhcp4/subnet4[1]. In this example, we allow server to + dynamically assign all addresses available in the whole subnet. + + + When configuring a DHCPv4 server using prefix/length notation, please pay + attention to the boundary values. When specifying that the server should use + a given pool, it will be able to allocate also first (typically network + address) and the last (typically broadcast address) address from that pool. + In the aforementioned example of pool 192.0.3.0/24, both 192.0.3.0 and + 192.0.3.255 addresses may be assigned as well. This may be invalid in some + network configurations. If you want to avoid this, please use the "min-max" notation. + +
+ +
+ Standard DHCPv4 options + + One of the major features of DHCPv4 server is to provide configuration + options to clients. Although there are several options that require + special behavior, most options are sent by the server only if the client + explicitly requested them. The following example shows how to + configure DNS servers, which is one of the most frequently used + options. Options specified in this way are considered global and apply + to all configured subnets. + + +> config add Dhcp4/option-data +> config set Dhcp4/option-data[0]/name "domain-name-servers" +> config set Dhcp4/option-data[0]/code 6 +> config set Dhcp4/option-data[0]/space "dhcp4" +> config set Dhcp4/option-data[0]/csv-format true +> config set Dhcp4/option-data[0]/data "192.0.3.1, 192.0.3.2" +> config commit + + + + The first line creates new entry in option-data table. It + contains information on all global options that the server is + supposed to configure in all subnets. The second line specifies + option name. For a complete list of currently supported names, + see below. + The third line specifies option code, which must match one of the + values from that list. Line 4 specifies option space, which must always + be set to "dhcp4" as these are standard DHCPv4 options. For + other option spaces, including custom option spaces, see . The fifth line specifies the format in + which the data will be entered: use of CSV (comma + separated values) is recommended. The sixth line gives the actual value to + be sent to clients. Data is specified as a normal text, with + values separated by commas if more than one value is + allowed. + + + + Options can also be configured as hexadecimal values. If csv-format is + set to false, option data must be specified as a hex string. The + following commands configure the domain-name-servers option for all + subnets with the following addresses: 192.0.3.1 and 192.0.3.2. + Note that csv-format is set to false. + +> config add Dhcp4/option-data +> config set Dhcp4/option-data[0]/name "domain-name-servers" +> config set Dhcp4/option-data[0]/code 6 +> config set Dhcp4/option-data[0]/space "dhcp4" +> config set Dhcp4/option-data[0]/csv-format false +> config set Dhcp4/option-data[0]/data "C0 00 03 01 C0 00 03 02" +> config commit + + + + + It is possible to override options on a per-subnet basis. If + clients connected to most of your subnets are expected to get the + same values of a given option, you should use global options: you + can then override specific values for a small number of subnets. + On the other hand, if you use different values in each subnet, + it does not make sense to specify global option values + (Dhcp4/option-data), rather you should set only subnet-specific values + (Dhcp4/subnet[X]/option-data[Y]). + + + The following commands override the global + DNS servers option for a particular subnet, setting a single DNS + server with address 192.0.2.3. + +> config add Dhcp4/subnet4[0]/option-data +> config set Dhcp4/subnet4[0]/option-data[0]/name "domain-name-servers" +> config set Dhcp4/subnet4[0]/option-data[0]/code 6 +> config set Dhcp4/subnet4[0]/option-data[0]/space "dhcp4" +> config set Dhcp4/subnet4[0]/option-data[0]/csv-format true +> config set Dhcp4/subnet4[0]/option-data[0]/data "192.0.2.3" +> config commit + + + + In a future version of Kea, it will not be necessary to specify + the option code, space and csv-format fields as they will be set + automatically. + + + + The currently supported standard DHCPv4 options are + listed in + and . + The "Name" and "Code" + are the values that should be used as a name in the option-data + structures. "Type" designates the format of the data: the meanings of + the various types is given in . + + + Some options are designated as arrays, which means that more than one + value is allowed in such an option. For example the option time-servers + allows the specification of more than one IPv4 address, so allowing + clients to obtain the the addresses of multiple NTP servers. + + + + + The describes the configuration + syntax to create custom option definitions (formats). It is generally not + allowed to create custom definitions for standard options, even if the + definition being created matches the actual option format defined in the + RFCs. There is an exception from this rule for standard options for which + Kea does not provide a definition yet. In order to use such options, + a server administrator must create a definition as described in + in the 'dhcp4' option space. This + definition should match the option format described in the relevant + RFC but configuration mechanism would allow any option format as it has + no means to validate it at the moment. + + + + + List of standard DHCPv4 options + + + + + + + + Name + Code + Type + Array? + + + +subnet-mask1ipv4-addressfalse +time-offset2int32false +routers3ipv4-addresstrue +time-servers4ipv4-addresstrue +name-servers5ipv4-addressfalse +domain-name-servers6ipv4-addresstrue +log-servers7ipv4-addresstrue +cookie-servers8ipv4-addresstrue +lpr-servers9ipv4-addresstrue +impress-servers10ipv4-addresstrue +resource-location-servers11ipv4-addresstrue +host-name12stringfalse +boot-size13uint16false +merit-dump14stringfalse +domain-name15fqdnfalse +swap-server16ipv4-addressfalse +root-path17stringfalse +extensions-path18stringfalse +ip-forwarding19booleanfalse +non-local-source-routing20booleanfalse +policy-filter21ipv4-addresstrue +max-dgram-reassembly22uint16false +default-ip-ttl23uint8false +path-mtu-aging-timeout24uint32false +path-mtu-plateau-table25uint16true +interface-mtu26uint16false +all-subnets-local27booleanfalse +broadcast-address28ipv4-addressfalse +perform-mask-discovery29booleanfalse +mask-supplier30booleanfalse +router-discovery31booleanfalse +router-solicitation-address32ipv4-addressfalse +static-routes33ipv4-addresstrue +trailer-encapsulation34booleanfalse +arp-cache-timeout35uint32false +ieee802-3-encapsulation36booleanfalse +default-tcp-ttl37uint8false +tcp-keepalive-internal38uint32false +tcp-keepalive-garbage39booleanfalse + + + +
+ + + + + List of standard DHCPv4 options (continued) + + + + + + + + Name + Code + Type + Array? + + + + +nis-domain40stringfalse +nis-servers41ipv4-addresstrue +ntp-servers42ipv4-addresstrue +vendor-encapsulated-options43emptyfalse +netbios-name-servers44ipv4-addresstrue +netbios-dd-server45ipv4-addresstrue +netbios-node-type46uint8false +netbios-scope47stringfalse +font-servers48ipv4-addresstrue +x-display-manager49ipv4-addresstrue +dhcp-requested-address50ipv4-addressfalse + +dhcp-option-overload52uint8false + +dhcp-message56stringfalse +dhcp-max-message-size57uint16false + +vendor-class-identifier60binaryfalse + +nwip-domain-name62stringfalse +nwip-suboptions63binaryfalse +tftp-server-name66stringfalse +boot-file-name67stringfalse +user-class77binaryfalse +fqdn81recordfalse +dhcp-agent-options82emptyfalse +authenticate90binaryfalse +client-last-transaction-time91uint32false +associated-ip92ipv4-addresstrue +subnet-selection118ipv4-addressfalse +domain-search119binaryfalse +vivco-suboptions124binaryfalse +vivso-suboptions125binaryfalse + + +
+ + + + + List of standard DHCP option types + + + + + NameMeaning + + + binaryAn arbitrary string of bytes, specified as a set of hexadecimal digits. + booleanBoolean value with allowed values true or false + emptyNo value, data is carried in suboptions + fqdnFully qualified domain name (e.g. www.example.com) + ipv4-addressIPv4 address in the usual dotted-decimal notation (e.g. 192.0.2.1) + ipv6-addressIPv6 address in the usual colon notation (e.g. 2001:db8::1) + recordStructured data that may comprise any types (except "record" and "empty") + stringAny text + uint88 bit unsigned integer with allowed values 0 to 255 + uint1616 bit unsinged integer with allowed values 0 to 65535 + uint3232 bit unsigned integer with allowed values 0 to 4294967295 + + +
+ +
+ +
+ Custom DHCPv4 options + It is also possible to define options other than the standard ones. + Assume that we want to define a new DHCPv4 option called "foo" which will have + code 222 and will convey a single unsigned 32 bit integer value. We can define + such an option by using the following commands: + +> config add Dhcp4/option-def +> config set Dhcp4/option-def[0]/name "foo" +> config set Dhcp4/option-def[0]/code 222 +> config set Dhcp4/option-def[0]/type "uint32" +> config set Dhcp4/option-def[0]/array false +> config set Dhcp4/option-def[0]/record-types "" +> config set Dhcp4/option-def[0]/space "dhcp4" +> config set Dhcp4/option-def[0]/encapsulate "" +> config commit + The "false" value of the "array" parameter determines that the option + does NOT comprise an array of "uint32" values but rather a single value. + Two other parameters have been left blank: "record-types" and "encapsulate". + The former specifies the comma separated list of option data fields if the + option comprises a record of data fields. The "record-fields" value should + be non-empty if the "type" is set to "record". Otherwise it must be left + blank. The latter parameter specifies the name of the option space being + encapsulated by the particular option. If the particular option does not + encapsulate any option space it should be left blank. + Note that the above set of comments define the format of the new option and do not + set its values. + + + + In the current release the default values are not propagated to the + parser when the new configuration is being set. Therefore, all + parameters must be specified at all times, even if their values are + left blank. + + + + Once the new option format is defined, its value is set + in the same way as for a standard option. For example the following + commands set a global value that applies to all subnets. + +> config add Dhcp4/option-data +> config set Dhcp4/option-data[0]/name "foo" +> config set Dhcp4/option-data[0]/code 222 +> config set Dhcp4/option-data[0]/space "dhcp4" +> config set Dhcp4/option-data[0]/csv-format true +> config set Dhcp4/option-data[0]/data "12345" +> config commit + + + New options can take more complex forms than simple use of + primitives (uint8, string, ipv4-address etc): it is possible to + define an option comprising a number of existing primitives. + + Assume we want to define a new option that will consist of + an IPv4 address, followed by unsigned 16 bit integer, followed by + a boolean value, followed by a text string. Such an option could + be defined in the following way: + +> config add Dhcp4/option-def +> config set Dhcp4/option-def[0]/name "bar" +> config set Dhcp4/option-def[0]/code 223 +> config set Dhcp4/option-def[0]/space "dhcp4" +> config set Dhcp4/option-def[0]/type "record" +> config set Dhcp4/option-def[0]/array false +> config set Dhcp4/option-def[0]/record-types "ipv4-address, uint16, boolean, string" +> config set Dhcp4/option-def[0]/encapsulate "" + + The "type" is set to "record" to indicate that the option contains + multiple values of different types. These types are given as a comma-separated + list in the "record-types" field and should be those listed in . + + + The values of the option are set as follows: + +> config add Dhcp4/option-data +> config set Dhcp4/option-data[0]/name "bar" +> config set Dhcp4/option-data[0]/space "dhcp4" +> config set Dhcp4/option-data[0]/code 223 +> config set Dhcp4/option-data[0]/csv-format true +> config set Dhcp4/option-data[0]/data "192.0.2.100, 123, true, Hello World" +> config commit + "csv-format" is set "true" to indicate that the "data" field comprises a command-separated + list of values. The values in the "data" must correspond to the types set in + the "record-types" field of the option definition. + + + + It is recommended that boolean values are specified using "true" and "false" + strings. This helps to prevent errors when typing multiple comma separated + values, as it make it easier to identify the type of the value being typed, + and compare it with the order of data fields. Nevertheless, it is possible + to use integer values: "1" and "0", instead of "true" and "false" + accordingly. If other integer value is specified, the configuration is + rejected. + + +
+ +
+ DHCPv4 vendor specific options + + Currently there are three option spaces defined: dhcp4 (to + be used in DHCPv4 daemon) and dhcp6 (for the DHCPv6 daemon); there + is also vendor-encapsulated-options-space, which is empty by default, but options + can be defined in it. Those options are called vendor-specific + information options. The following examples show how to define + an option "foo" with code 1 that consists of an IPv4 address, an + unsigned 16 bit integer and a string. The "foo" option is conveyed + in a vendor specific information option. + + + The first step is to define the format of the option: + +> config add Dhcp4/option-def +> config set Dhcp4/option-def[0]/name "foo" +> config set Dhcp4/option-def[0]/code 1 +> config set Dhcp4/option-def[0]/space "vendor-encapsulated-options-space" +> config set Dhcp4/option-def[0]/type "record" +> config set Dhcp4/option-def[0]/array false +> config set Dhcp4/option-def[0]/record-types "ipv4-address, uint16, string" +> config set Dhcp4/option-def[0]/encapsulates "" +> config commit + + (Note that the option space is set to "vendor-encapsulated-options-space".) + Once the option format is defined, the next step is to define actual values + for that option: + +> config add Dhcp4/option-data +> config set Dhcp4/option-data[0]/name "foo" +> config set Dhcp4/option-data[0]/space "vendor-encapsulated-options-space" +> config set Dhcp4/option-data[0]/code 1 +> config set Dhcp4/option-data[0]/csv-format true +> config set Dhcp4/option-data[0]/data "192.0.2.3, 123, Hello World" +> config commit + We also set up a dummy value for vendor-opts, the option that conveys our sub-option "foo". + This is required else the option will not be included in messages sent to the client. + +> config add Dhcp4/option-data +> config set Dhcp4/option-data[1]/name "vendor-encapsulated-options" +> config set Dhcp4/option-data[1]/space "dhcp4" +> config set Dhcp4/option-data[1]/code 43 +> config set Dhcp4/option-data[1]/csv-format false +> config set Dhcp4/option-data[1]/data "" +> config commit + + + + + With this version of Kea, the "vendor-encapsulated-options" option + must be specified in the configuration although it has no configurable + parameters. If it is not specified, the server will assume that it is + not configured and will not send it to a client. In the future there + will be no need to include this option in the configuration. + + + +
+ +
+ + Nested DHCPv4 options (custom option spaces) + It is sometimes useful to define completely new option + space. This is the case when user creates new option in the + standard option space ("dhcp4 or "dhcp6") and wants this option + to convey sub-options. Thanks to being in the separate space, + sub-option codes will have a separate numbering scheme and may + overlap with codes of standard options. + + Note that creation of a new option space when defining + sub-options for a standard option is not required, because it is + created by default if the standard option is meant to convey any + sub-options (see ). + + + Assume that we want to have a DHCPv4 option called "container" with + code 222 that conveys two sub-options with codes 1 and 2. + First we need to define the new sub-options: + +> config add Dhcp4/option-def +> config set Dhcp4/option-def[0]/name "subopt1" +> config set Dhcp4/option-def[0]/code 1 +> config set Dhcp4/option-def[0]/space "isc" +> config set Dhcp4/option-def[0]/type "ipv4-address" +> config set Dhcp4/option-def[0]/record-types "" +> config set Dhcp4/option-def[0]/array false +> config set Dhcp4/option-def[0]/encapsulate "" +> config commit + +> config add Dhcp4/option-def +> config set Dhcp4/option-def[1]/name "subopt2" +> config set Dhcp4/option-def[1]/code 2 +> config set Dhcp4/option-def[1]/space "isc" +> config set Dhcp4/option-def[1]/type "string" +> config set Dhcp4/option-def[1]/record-types "" +> config set Dhcp4/option-def[1]/array false +> config set Dhcp4/option-def[1]/encapsulate "" +> config commit + + Note that we have defined the options to belong to a new option space + (in this case, "isc"). + + + The next step is to define a regular DHCPv4 option with our desired + code and specify that it should include options from the new option space: + +> add Dhcp4/option-def +> set Dhcp4/option-def[2]/name "container" +> set Dhcp4/option-def[2]/code 222 +> set Dhcp4/option-def[2]/space "dhcp4" +> set Dhcp4/option-def[2]/type "empty" +> set Dhcp4/option-def[2]/array false +> set Dhcp4/option-def[2]/record-types "" +> set Dhcp4/option-def[2]/encapsulate "isc" +> commit + + The name of the option space in which the sub-options are defined + is set in the "encapsulate" field. The "type" field is set to "empty" + to indicate that this option does not carry any data other than + sub-options. + + + Finally, we can set values for the new options: + +> config add Dhcp4/option-data +> config set Dhcp4/option-data[0]/name "subopt1" +> config set Dhcp4/option-data[0]/space "isc" +> config set Dhcp4/option-data[0]/code 1 +> config set Dhcp4/option-data[0]/csv-format true +> config set Dhcp4/option-data[0]/data "192.0.2.3" +> config commit + +> config add Dhcp4/option-data +> config set Dhcp4/option-data[1]/name "subopt2" +> config set Dhcp4/option-data[1]/space "isc" +> config set Dhcp4/option-data[1]/code 2 +> config set Dhcp4/option-data[1]/csv-format true +> config set Dhcp4/option-data[1]/data "Hello world" +> config commit + +> config add Dhcp4/option-data +> config set Dhcp4/option-data[2]/name "container" +> config set Dhcp4/option-data[2]/space "dhcp4" +> config set Dhcp4/option-data[2]/code 222 +> config set Dhcp4/option-data[2]/csv-format true +> config set Dhcp4/option-data[2]/data "" +> config commit + + Even though the "container" option does not carry any data except + sub-options, the "data" field must be explicitly set to an empty value. + This is required because in the current version of BIND 10 DHCP, the + default configuration values are not propagated to the configuration parsers: + if the "data" is not set the parser will assume that this + parameter is not specified and an error will be reported. + + Note that it is possible to create an option which carries some data + in addition to the sub-options defined in the encapsulated option space. For example, + if the "container" option from the previous example was required to carry an uint16 + value as well as the sub-options, the "type" value would have to be set to "uint16" in + the option definition. (Such an option would then have the following + data structure: DHCP header, uint16 value, sub-options.) The value specified + with the "data" parameter - which should be a valid integer enclosed in quotes, + e.g. "123" - would then be assigned to the uint16 field in the "container" option. + +
+ +
+ Client Classification in DHCPv4 + + + DHCPv4 server has been extended to support limited client classification. + Although the current capability is modest, it is expected to be expanded + in the future. It is envisaged that the majority of client classification + extensions will be using hooks extensions. + + + In certain cases it is useful to differentiate between different + types of clients and treat them differently. The process of doing + classification is conducted in two steps. The first step is to assess + incoming packet and assign it to zero or more classes. This classification + is currently simple, but is expected to grow in capability soon. Currently + the server checks whether incoming packet has vendor class identifier + option (60). If it has, content of that option is prepended with + "VENDOR_CLASS_" then is interpreted as a class. For example, + modern cable modems will send this option with value "docsis3.0" + and as a result the packet will belong to class "VENDOR_CLASS_docsis3.0". + + + It is envisaged that the client classification will be used for changing + behavior of almost any part of the DHCP message processing, including assigning + leases from different pools, assigning different option (or different values of + the same options) etc. For now, there are only two mechanisms that are taking + advantage of client classification: specific processing for cable modems and + subnet selection. + + + For clients that belong to the VENDOR_CLASS_docsis3.0 class, the siaddr + field is set to the value of next-server (if specified in a subnet). If + there is boot-file-name option specified, its value is also set in the + file field in the DHCPv4 packet. For eRouter1.0 class, the siaddr is + always set to 0.0.0.0. That capability is expected to be moved to + external hook library that will be dedicated to cable modems. + + + + Kea can be instructed to limit access to given subnets based on class information. + This is particularly useful for cases where two types of devices share the + same link and are expected to be served from two different subnets. The + primary use case for such a scenario is cable networks. There are two + classes of devices: cable modem itself, which should be handled a lease + from subnet A and all other devices behind modems that should get a lease + from subnet B. That segregation is essential to prevent overly curious + users from playing with their cable modems. For details on how to set up + class restrictions on subnets, see . + + +
+ +
+ Limiting access to IPv4 subnet to certain classes + + In certain cases it beneficial to restrict access to certain subnets + only to clients that belong to a given subnet. For details on client + classes, see . This is an + extension of a previous example from . + Let's assume that the server is connected to a network segment that uses + the 192.0.2.0/24 prefix. The Administrator of that network has decided + that addresses from range 192.0.2.10 to 192.0.2.20 are going to be + managed by the Dhcp4 server. Only clients belonging to client class + VENDOR_CLASS_docsis3.0 are allowed to use this subnet. Such a + configuration can be achieved in the following way: + +> config add Dhcp4/subnet4 +> config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24" +> config set Dhcp4/subnet4[0]/pool [ "192.0.2.10 - 192.0.2.20" ] +> config set Dhcp4/subnet4[0]/client-class "VENDOR_CLASS_docsis3.0" +> config commit + + + + Care should be taken with client classification as it is easy to prevent + clients that do not meet class criteria to be denied any service altogether. + +
+
+ Configuring DHCPv4 for DDNS + + As mentioned earlier, b10-dhcp4 can be configured to generate requests to the + DHCP-DDNS server to update DNS entries. These requests are known as + NameChangeRequests or NCRs. Each NCR contains the following information: + + + Whether it is a request to add (update) or remove DNS entries + + + Whether the change requests forward DNS updates (A records), reverse + DNS updates (PTR records), or both. + + + The FQDN, lease address, and DHCID + + + The parameters for controlling the generation of NCRs for submission to D2 + are contained in the "dhcp-ddns" section of the b10-dhcp4 server + configuration. The default values for this section appears as follows: + +> config show Dhcp4/dhcp-ddns +Dhcp4/dhcp-ddns/enable-updates true boolean +Dhcp4/dhcp-ddns/server-ip "127.0.0.1" string +Dhcp4/dhcp-ddns/server-port 53001 integer +Dhcp4/dhcp-ddns/sender-ip "" string +Dhcp4/dhcp-ddns/sender-port 0 integer +Dhcp4/dhcp-ddns/max-queue-size 1024 integer +Dhcp4/dhcp-ddns/ncr-protocol "UDP" string +Dhcp4/dhcp-ddns/ncr-format "JSON" string +Dhcp4/dhcp-ddns/override-no-update false boolean +Dhcp4/dhcp-ddns/override-client-update false boolean +Dhcp4/dhcp-ddns/replace-client-name false boolean +Dhcp4/dhcp-ddns/generated-prefix "myhost" string +Dhcp4/dhcp-ddns/qualifying-suffix "example.com" string + + + + The "enable-updates" parameter determines whether or not b10-dhcp4 will + generate NCRs. By default, this value is false hence DDNS updates are + disabled. To enable DDNS updates set this value to true: + + +> config set Dhcp4/dhcp-ddns/enable-updates true +> config commit + +
+ DHCP-DDNS Server Connectivity + + In order for NCRs to reach the D2 server, b10-dhcp4 must be able + to communicate with it. b10-dhcp4 uses the following configuration + parameters to control how it communications with D2: + + + server-ip - 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. + + + server-port - port on which D2 listens for requests. The default value + is 53001. + + + sender-ip - IP address which b10-dhcp4 should use to send requests to D2. + The default value is blank which instructs b10-dhcp4 to select a suitable + address. + + + sender-port - port which b10-dhcp4 should use to send requests to D2. The + default value of 0 instructs b10-dhcp4 to select suitable port. + + + ncr-format - Socket protocol use when sending requests to D2. Currently + only UDP is supported. TCP may be available in an upcoming release. + + + 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. + + + max-queue-size - maximum number of requests allowed to queue waiting to + be sent to D2. This value guards against requests accumulating + uncontrollably if they are being generated faster than they can be + delivered. If the number of requests queued for transmission reaches + this value, DDNS updating will be turned off until the queue backlog has + been sufficiently reduced. The intent is allow the b10-dhcp4 server to + continue lease operations. The default value is 1024. + + + By default, D2 is assumed to running on the same machine as b10-dhcp4, and + all of the default values mentioned above should be sufficient. + If, however, D2 has been configured to listen on a different address or + port, these values must altered accordingly. For example, if D2 has been + configured to listen on 198.162.1.10 port 900, the following commands + would be required: + +> config set Dhcp4/dhcp-ddns/server-ip "198.162.1.10" +> config set Dhcp4/dhcp-ddns/server-port 900 +> config commit + + +
+
+ When does the b10-dhcp4 server generate DDNS requests? + b10-dhcp4 follows the behavior prescribed for DHCP servers in RFC 4702. + It is important to keep in mind that b10-dhcp4 provides the initial decision + making of when and what to update and forwards that information to D2 in + the form of NCRs. Carrying out the actual DNS updates and dealing with + such things as conflict resolution are the purview of D2 (). + + This section describes when b10-dhcp4 will generate NCRs and the + configuration parameters that can be used to influence this decision. + It assumes that the "enable-updates" parameter is true. + + + In general, b10-dhcp4 will generate DDNS update requests when: + + + A new lease is granted in response to a DHCP REQUEST + + + An existing lease is renewed but the FQDN associated with it has + changed. + + + An existing lease is released in response to a DHCP RELEASE + + + In the second case, lease renewal, two DDNS requests will be issued: one + request to remove entries for the previous FQDN and a second request to + add entries for the new FQDN. In the last case, a lease release, a + single DDNS request to remove its entries will be made. The decision + making involved when granting a new lease (the first case) is more + involved and is discussed next. + + + When a new lease is granted, b10-dhcp4 will generate a DDNS + update request if the DHCP REQUEST contains either the FQDN option + (code 81) or the Host Name option (code 12). If both are present, + the server will use the FQDN option. By default b10-dhcp4 + will respect the FQDN N and S flags specified by the client as shown + in the following table: + + + Default FQDN Flag Behavior + + + + + + + + Client Flags:N-S + Client Intent + Server Response + Server Flags:N-S-O + + + + + 0-0 + + Client wants to do forward updates, server should do reverse updates + + Server generates reverse-only request + 1-0-0 + + + 0-1 + Server should do both forward and reverse updates + Server generates request to update both directions + 0-1-0 + + + 1-0 + Client wants no updates done + Server does not generate a request + 1-0-0 + + + +
+ + The first row in the table above represents "client delegation". Here + the DHCP client states that it intends to do the forward DNS updates and + the server should do the reverse updates. By default, b10-dhcp4 will honor + the client's wishes and generate a DDNS request to D2 to update only + reverse DNS data. The parameter, "override-client-update", can be used + to instruct the server to override client delegation requests. When + this parameter is true, b10-dhcp4 will disregard requests for client + delegation and generate a DDNS request to update both forward and + reverse DNS data. In this case, the N-S-O flags in the server's + response to the client will be 0-1-1 respectively. + + + (Note that the flag combination N=1, S=1 is prohibited according to + RFC 4702. If such a combination is received from the client, the packet + will be dropped by the b10-dhcp4.) + + + To override client delegation, issue the following commands: + + +> config set Dhcp4/dhcp-ddns/override-client-update true +> config commit + + + The third row in the table above describes the case in which the client + requests that no DNS updates be done. The parameter, "override-no-update", + can be used to instruct the server to disregard the client's wishes. When + this parameter is true, b10-dhcp4 will generate DDNS update request to D2 + even if the client requests no updates be done. The N-S-O flags in the + server's response to the client will be 0-1-1. + + + To override client delegation, issue the following commands: + + +> config set Dhcp4/dhcp-ddns/override-no-update true +> config commit + + + b10-dhcp4 will always generate DDNS update requests if the client request + only contains the Host Name option. In addition it will include an FQDN + option in the response to the client with the FQDN N-S-O flags set to + 0-1-0 respectively. The domain name portion of the FQDN option will be + the name submitted to D2 in the DDNS update request. + +
+
+ b10-dhcp4 name generation for DDNS update requests + Each NameChangeRequest must of course include the fully qualified domain + name whose DNS entries are to be affected. b10-dhcp4 can be configured to + supply a portion or all of that name based upon what it receives from + the client in the DHCP REQUEST. + + The rules for determining the FQDN option are as follows: + + + If configured to do, so ignore the REQUEST contents and generate a + FQDN using a configurable prefix and suffix. + + + If the REQUEST contains the client FQDN option, the candidate + name is taken from there, otherwise it is taken from the Host Name option. + The candiate name may then be modified: + + + If the candidate name is a fully qualified domain name, use it. + + + If the candidate name is a partial (i.e. unqualified) name then + add a configurable suffix to the name and use the result as the FQDN. + + + If the candidate name is a empty, generate a FQDN using a + configurable prefix and suffix. + + + + + To instruct b10-dhcp4 to always generate the FQDN for a client, set the + parameter "replace-client-name" to true as follows: + + +> config set Dhcp4/dhcp-ddns/replace-client-name true +> config commit + + + The prefix used in the generation of a FQDN is specified by the + "generated-prefix" parameter. The default value is "myhost". To alter + its value simply set it to the desired string: + + +> config set Dhcp4/dhcp-ddns/generated-prefix "another.host" +> config commit + + + The suffix used when generating a FQDN or when qualifying a partial + name is specified by the "qualifying-suffix" parameter. The default + value is "example.com". To alter its value simply set it to the desired + string: + + +> config set Dhcp4/dhcp-ddns/generated-prefix "our.net" +> config commit + +
+ + When generating a name, b10-dhcp4 will construct name of the format: + + + [generated-prefix]-[address-text].[qualifying-suffix]. + + + where address-text is simply the lease IP address converted to a + hyphenated string. For example, if lease address is 172.16.1.10 and + assuming default values for generated-prefix and qualifying-suffix, the + generated FQDN would be: + + + myhost-172-16-1-10.example.com. + +
+ +
+ +
+ Server Identifier in DHCPv4 + + The DHCPv4 protocol uses a "server identifier" for clients to be able + to discriminate between several servers present on the same link: this + value is an IPv4 address of the server. The server chooses the IPv4 address + of the interface on which the message from the client (or relay) has been + received. A single server instance will use multiple server identifiers + if it is receiving queries on multiple interfaces. + + + Currently there is no mechanism to override the default server identifiers + by an administrator. In the future, the configuration mechanism will be used + to specify the custom server identifier. + +
+ + +
+ Next server (siaddr) + In some cases, clients want to obtain configuration from the TFTP server. + Although there is a dedicated option for it, some devices may use siaddr field + in the DHCPv4 packet for that purpose. That specific field can be configured + using next-server directive. It is possible to define it in global scope or + for a given subnet only. If both are defined, subnet value takes precedence. + The value in subnet can be set to 0.0.0.0, which means that next-server should + not be sent. It may also be set to empty string, which means the same as if + it was not defined at all - use global value. + + + +> config add Dhcp4/next-server +> config set Dhcp4/next-server "192.0.2.123" +> config commit + +> config add Dhcp4/subnet[0]/next-server +> config set Dhcp4/subnet[0]/next-server "192.0.2.234" +> config commit + + +
+ +
+ Echoing client-id (RFC6842) + Original DHCPv4 spec (RFC2131) states that the DHCPv4 + server must not send back client-id options when responding to + clients. However, in some cases that confused clients that did + not have MAC address or client-id. See RFC6842 for details. That + behavior has changed with the publication of RFC6842 which + updated RFC2131. That update now states that the server must + send client-id if client sent it. That is the default behaviour + that Kea offers. However, in some cases older devices that do + not support RFC6842 may refuse to accept responses that include + client-id option. To enable backward compatibility, an optional + configuration parameter has been introduced. To configure it, + use the following commands: + + +> config add Dhcp4/echo-client-id +> config set Dhcp4/echo-client-id False +> config commit + + +
+ +
+ How DHCPv4 server selects subnet for a client + + The DHCPv4 server differentiates between the directly connected clients, + clients trying to renew leases and clients sending their messages through + relays. For the directly connected clients the server will check the + configuration of the interface on which the message has been received, and + if the server configuration doesn't match any configured subnet the + message is discarded. + Assuming that the server's interface is configured with the 192.0.2.3 + IPv4 address, the server will only process messages received through + this interface from the directly connected client, if there is a subnet + configured, to which this IPv4 address belongs, e.g. 192.0.2.0/24. + The server will use this subnet to assign IPv4 address for the client. + + + The rule above does not apply when the client unicasts its message, i.e. + is trying to renew its lease. Such message is accepted through any + interface. The renewing client sets ciaddr to the currently used IPv4 + address. The server uses this address to select the subnet for the client + (in particular, to extend the lease using this address). + + + If the message is relayed it is accepted through any interface. The giaddr + set by the relay agent is used to select the subnet for the client. + + + It is also possible to specify a relay IPv4 address for a given subnet. It + can be used to match incoming packets into a subnet in uncommon configurations, + e.g. shared subnets. See for details. + + + The subnet selection mechanism described in this section is based + on the assumption that client classification is not used. The classification + mechanism alters the way in which subnet is selected for the client, + depending on the classes that the client belongs to. + +
+ +
+ Using specific relay agent for a subnet + + The relay has to have an interface connected to the link on which + the clients are being configured. Typically the relay has an IPv4 + address configured on that interface that belongs to the subnet that + the server will assign addresses from. In such typical case, the + server is able to use IPv4 address inserted by the relay (in GIADDR + field of the DHCPv4 packet) to select appropriate subnet. + + + However, that is not always the case. In certain uncommon, but + valid deployments, the relay address may not match the subnet. This + usually means that there is more than one subnet allocated for a given + link. Two most common examples where this is the case are long lasting + network renumbering (where both old and new address space is still being + used) and a cable network. In a cable network both cable modems and the + devices behind them are physically connected to the same link, yet + they use distinct addressing. In such case, the DHCPv4 server needs + additional information (IPv4 address of the relay) to properly select + an appropriate subnet. + + + The following example assumes that there is a subnet 192.0.2.0/24 + that is accessible via relay that uses 10.0.0.1 as its IPv4 address. + The server will be able to select this subnet for any incoming packets + that came from a relay that has an address in 192.0.2.0/24 subnet. + It will also select that subnet for a relay with address 10.0.0.1. + +> config add Dhcp4/subnet4 +> config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24" +> config set Dhcp4/subnet4[0]/pool [ "192.0.2.10 - 192.0.2.20" ] +> config set Dhcp4/subnet4[0]/relay/ip-address "10.0.0.1" +> config commit + + +
+ +
+ Segregating IPv4 clients in a cable network + + In certain cases, it is useful to mix relay address information, + introduced in with client + classification, explained in . + One specific example is cable network, where typically modems + get addresses from a different subnet than all devices connected + behind them. + + + Let's assume that there is one CMTS (Cable Modem Termination System) + with one CM MAC (a physical link that modems are connected to). + We want the modems to get addresses from the 10.1.1.0/24 subnet, while + everything connected behind modems should get addresses from another + subnet (192.0.2.0/24). The CMTS that acts as a relay an uses address + 10.1.1.1. The following configuration can serve that configuration: + +> config add Dhcp4/subnet4 +> config set Dhcp4/subnet4[0]/subnet "10.1.1.0/24" +> config set Dhcp4/subnet4[0]/pool [ "10.1.1.2 - 10.1.1.20" ] +> config set Dhcp4/subnet4[0]/client-class "docsis3.0" +> config set Dhcp4/subnet4[0]/relay/ip-address "10.1.1.1" +> config add Dhcp4/subnet4 +> config set Dhcp4/subnet4[1]/subnet "192.0.2.0/24" +> config set Dhcp4/subnet4[1]/pool [ "192.0.2.10 - 192.0.2.20" ] +> config set Dhcp4/subnet4[1]/relay/ip-address "10.1.1.1" +> config commit + +
+ +
+ Supported Standards + The following standards and draft standards are currently + supported: + + + RFC 2131: Supported messages are DISCOVER, OFFER, + REQUEST, RELEASE, ACK, and NAK. + + + RFC 2132: + Supported options are: PAD (0), + END(255), Message Type(53), DHCP Server Identifier (54), + Domain Name (15), DNS Servers (6), IP Address Lease Time + (51), Subnet mask (1), and Routers (3). + + + RFC 3046: + Relay Agent Information option is supported. + + + RFC 3925: + Vendor-Identifying Vendor Class and Vendor-Identifying Vendor-Specific + Information option are supported. + + + RFC 6842: + Server by default sends back client-id option. That capability may be + disabled. See for details. + + + +
+ +
+ DHCPv4 Server Limitations + These are the current limitations of the DHCPv4 server + software. Most of them are reflections of the current stage of + development and should be treated as not implemented + yet, rather than actual limitations. + + + + Removal of a subnet during server reconfiguration may cause renumbering + of auto-generated subnet identifiers, as described in section + . + + + + + BOOTP (RFC 951) + is not supported. + + + + Raw sockets operation is working on Linux + only. See for details. + + + The DHCPv4 server does not verify that + assigned address is unused. According to RFC 2131, the + allocating server should verify that address is not used by + sending ICMP echo request. + + + Address duplication report (DECLINE) is not supported yet. + + + + The server doesn't act upon expired leases. In particular, + when a lease expires, the server doesn't request the removal + of the DNS records associated with it. + + + +
+ + + + diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml new file mode 100644 index 0000000000..6dae7b7134 --- /dev/null +++ b/doc/guide/dhcp6-srv.xml @@ -0,0 +1,1545 @@ + + +]> + + + The DHCPv6 Server + +
+ Starting and Stopping the DHCPv6 Server + + + b10-dhcp6 is the Kea DHCPv6 server and is configured + through the bindctl program. + + + After starting bind10 and starting bindctl, the first step + in configuring the server is to add b10-dhcp6 to the list of running services. + +> config add Init/components b10-dhcp6 +> config set Init/components/b10-dhcp6/kind dispensable +> config commit + + + + To remove b10-dhcp6 from the set of running services, + the b10-dhcp6 is removed from list of Init components: + +> config remove Init/components b10-dhcp6 +> config commit + + + + + Note that the server was only removed from the list, so BIND10 will not + restart it, but the server itself is still running. Hence it is usually + desired to stop it: + +> Dhcp6 shutdown + + + + + During start-up the server will detect available network interfaces + and will attempt to open UDP sockets on all interfaces that + are up, running, are not loopback, are multicast-capable, and + have IPv6 address assigned. It will then listen to incoming traffic. + + + +
+ +
+ DHCPv6 Server Configuration + + Once the server has been started, it can be configured. To view the + current configuration, use the following command in bindctl: + > config show Dhcp6 + When starting the Dhcp6 daemon for the first time, the default configuration + will be available. It will look similar to this: + +> config show Dhcp6 +Dhcp6/hooks-libraries [] list (default) +Dhcp6/interfaces/ list (default) +Dhcp6/renew-timer 1000 integer (default) +Dhcp6/rebind-timer 2000 integer (default) +Dhcp6/preferred-lifetime 3000 integer (default) +Dhcp6/valid-lifetime 4000 integer (default) +Dhcp6/option-def [] list (default) +Dhcp6/option-data [] list (default) +Dhcp6/lease-database/type "" string (default) +Dhcp6/lease-database/name "" string (default) +Dhcp6/lease-database/user "" string (default) +Dhcp6/lease-database/host "" string (default) +Dhcp6/lease-database/password "" string (default) +Dhcp6/subnet6/ list +Dhcp6/dhcp-ddns/enable-updates true boolean +Dhcp6/dhcp-ddns/server-ip "127.0.0.1" string +Dhcp6/dhcp-ddns/server-port 53001 integer +Dhcp6/dhcp-ddns/sender-ip "" string +Dhcp6/dhcp-ddns/sender-port 0 integer +Dhcp6/dhcp-ddns/max-queue-size 1024 integer +Dhcp6/dhcp-ddns/ncr-protocol "UDP" string +Dhcp6/dhcp-ddns/ncr-format "JSON" string +Dhcp6/dhcp-ddns/always-include-fqdn false boolean +Dhcp6/dhcp-ddns/override-no-update false boolean +Dhcp6/dhcp-ddns/override-client-update false boolean +Dhcp6/dhcp-ddns/replace-client-name false boolean +Dhcp6/dhcp-ddns/generated-prefix "myhost" string +Dhcp6/dhcp-ddns/qualifying-suffix "example.com" string + + + + To change one of the parameters, simply follow + the usual bindctl procedure. For example, to make the + leases longer, change their valid-lifetime parameter: + +> config set Dhcp6/valid-lifetime 7200 +> config commit + Most Dhcp6 parameters are of global scope + and apply to all defined subnets, unless they are overridden on a + per-subnet basis. + + + + With this version of Kea, there are a number of known limitations + and problems in the DHCPv6 server. See . + + + +
+ Default storage for leases + + The server is able to store lease data in different repositories. Larger deployments + may elect to store leases in a database. + describes one way to do it. + By default, the server will use a CSV file rather than a database to store + lease information. One of the advantages of using a file is that it eliminates + dependency on third party database software. + + + The configuration of the file backend (Memfile) + is controlled through the Dhcp6/lease-database parameters. When default + parameters are left, the Memfile backend will write leases to a disk in the + [bind10-install-dir]/var/bind10/kea-leases6.csv. + + + It is possible to alter the default location of the lease file. The following + configuration: + +> config set Dhcp4/lease-database/type "memfile" +> config set Dhcp4/lease-database/persist true +> config set Dhcp4/lease-database/leasefile "/tmp/kea-leases6.csv" +> config commit + + will change the default location of the lease file to /tmp/kea-leases6.csv. + + + The "persist" parameter controls whether the leases are written to disk. + It is strongly recommended that this parameter is set to "true" at all times + during the normal operation of the server. + +
+ +
+ Database Configuration + + All leases issued by the server are stored in the lease database. Currently + there are 3 database backends available: MySQL, PostgreSQL and memfile. + + + The server comes with an in-memory database ("memfile") configured as the default + database. This is used for internal testing and is not supported. In addition, + it does not store lease information on disk: lease information will be lost if the + server is restarted. + + , and so the server must be configured to + access the correct database with the appropriate credentials. + + + + Database access information must be configured for the DHCPv6 server, even if + it has already been configured for the DHCPv4 server. The servers store their + information independently, so each server can use a separate + database or both servers can use the same database. + + + + Database configuration is controlled through the Dhcp6/lease-database parameters. + The type of the database must be set to "mysql", "postgresql" or "memfile": + +> config set Dhcp6/lease-database/type "mysql" + + Next, the name of the database is to hold the leases must be set: this is the + name used when the lease database was created (see + or ). + +> config set Dhcp6/lease-database/name "database-name" + + If the database is located on a different system to the DHCPv6 server, the + database host name must also be specified (although note that this configuration + may have a severe impact on server performance): + +> config set Dhcp6/lease-database/host "remote-host-name" + + The usual state of affairs will be to have the database on the same machine as the + DHCPv6 server. In this case, set the value to the empty string (this is the default): + +> config set Dhcp6/lease-database/host "" + + + + Finally, the credentials of the account under which the server will access the database + should be set: + +> config set Dhcp6/lease-database/user "user-name" +> config set Dhcp6/lease-database/password "password" + + If there is no password to the account, set the password to the empty string "". (This is also the default.) + + + The password is echoed when entered and is stored in clear text in the configuration + database. Improved password security will be added in a future version of Kea. + +
+ +
+ Interface selection + + When DHCPv6 server starts up, by default it will listen to the DHCP + traffic and respond to it on all interfaces detected during startup. + However, in many cases it is desired to configure the server to listen and + respond on selected interfaces only. The sample commands in this section + show how to make interface selection using bindctl. + + + The default configuration can be presented with the following command: + +> config show Dhcp6/interfaces +Dhcp6/interfaces[0] "*" string + An asterisk sign plays a role of the wildcard and means "listen on all interfaces". + + + In order to override the default configuration, the existing entry can be replaced + with the actual interface name: + +> config set Dhcp6/interfaces[0] eth1 +> config commit + Other interface names can be added on one-by-one basis: + +> config add Dhcp6/interfaces eth2 +> config commit + Configuration will now contain two interfaces which can be presented as follows: + +> config show Dhcp6/interfaces +Dhcp6/interfaces[0] "eth1" string +Dhcp6/interfaces[1] "eth2" string + When configuration gets committed, the server will start to listen on + eth1 and eth2 interfaces only. + + + It is possible to use wildcard interface name (asterisk) concurrently with explicit + interface names: + +> config add Dhcp6/interfaces * +> config commit + This will result in the following configuration: + +> config show Dhcp6/interfaces +Dhcp6/interfaces[0] "eth1" string +Dhcp6/interfaces[1] "eth2" string +Dhcp6/interfaces[2] "*" string + The presence of the wildcard name implies that server will listen on all interfaces. + In order to fall back to the previous configuration when server listens on eth1 and eth2: + +> config remove Dhcp6/interfaces[2] +> config commit + +
+ +
+ IPv6 Subnet Identifier + + Subnet identifier is a unique number associated with a particular subnet. + In principle, it is used to associate clients' leases with respective subnets. + When subnet identifier is not specified for a subnet being configured, it will + be automatically assigned by the configuration mechanism. The identifiers + are assigned from 1 and are monotonically increased for each subsequent + subnet: 1, 2, 3 .... + + + If there are multiple subnets configured with auto-generated identifiers and + one of them is removed, the subnet identifiers may be renumbered. For example: + if there are 4 subnets and 3rd is removed the last subnet will be assigned + identifier that the 3rd subnet had before removal. As a result, the leases + stored in the lease database for subnet 3 are now associated with the + subnet 4, which may have unexpected consequences. In the future it is planned + to implement the mechanism to preserve auto-generated subnet ids upon removal + of one of the subnets. Currently, the only remedy for this issue is to + manually specify the unique subnet identifier for each subnet. + + + The following configuration: + +> config add Dhcp6/subnet6 +> config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64" +> config set Dhcp6/subnet6[0]/id 1024 +> config commit + + will assign the arbitrary subnet identifier to the newly configured subnet. + This identifier will not change for this subnet until "id" parameter is + removed or set to 0. The value of 0 forces auto-generation of subnet + identifier. + +
+ +
+ Unicast traffic support + + When DHCPv6 server starts up, by default it listens to the DHCP traffic + sent to multicast address ff02::1:2 on each interface that it is + configured to listen on (see ). + In some cases it is useful to configure a server to handle incoming + traffic sent to the global unicast addresses as well. The most common + reason for that is to have relays send their traffic to the server + directly. To configure server to listen on specific unicast address, a + notation to specify interfaces has been extended. Interface name can be + optionally followed by a slash, followed by global unicast address that + server should listen on. That will be done in addition to normal + link-local binding + listening on ff02::1:2 address. The sample commands + listed below show how to listen on 2001:db8::1 (a global address) + configured on the eth1 interface. + + + +> config set Dhcp6/interfaces[0] eth1/2001:db8::1 +> config commit + When configuration gets committed, the server will start to listen on + eth1 on link-local address, multicast group (ff02::1:2) and 2001:db8::1. + + + It is possible to mix interface names, wildcards and interface name/addresses + on the Dhcp6/interface list. It is not possible to specify more than one + unicast address on a given interface. + + + Care should be taken to specify proper unicast addresses. The server will + attempt to bind to those addresses specified, without any additional checks. + That approach is selected on purpose, so in the software can be used to + communicate over uncommon addresses if the administrator desires so. + +
+ +
+ Subnet and Address Pool + + The essential role of a DHCPv6 server is address assignment. For this, + the server has to be configured with at least one subnet and one pool of dynamic + addresses to be managed. For example, assume that the server + is connected to a network segment that uses the 2001:db8:1::/64 + prefix. The Administrator of that network has decided that addresses from range + 2001:db8:1::1 to 2001:db8:1::ffff are going to be managed by the Dhcp6 + server. Such a configuration can be achieved in the following way: + +> config add Dhcp6/subnet6 +> config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64" +> config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::0 - 2001:db8:1::ffff" ] +> config commit + Note that subnet is defined as a simple string, but the pool parameter + is actually a list of pools: for this reason, the pool definition is + enclosed in square brackets, even though only one range of addresses + is specified. + It is possible to define more than one pool in a + subnet: continuing the previous example, further assume that + 2001:db8:1:0:5::/80 should be also be managed by the server. It could be written as + 2001:db8:1:0:5:: to 2001:db8:1::5:ffff:ffff:ffff, but typing so many 'f's + is cumbersome. It can be expressed more simply as 2001:db8:1:0:5::/80. Both + formats are supported by Dhcp6 and can be mixed in the pool list. + For example, one could define the following pools: + +> config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::1 - 2001:db8:1::ffff", "2001:db8:1:0:5::/80" ] +> config commit + The number of pools is not limited, but for performance reasons it is recommended to + use as few as possible. + + + The server may be configured to serve more than one subnet. To add a second subnet, + use a command similar to the following: + +> config add Dhcp6/subnet6 +> config set Dhcp6/subnet6[1]/subnet "2001:db8:beef::/48" +> config set Dhcp6/subnet6[1]/pool [ "2001:db8:beef::/48" ] +> config commit + Arrays are counted from 0. subnet[0] refers to the subnet defined in the + previous example. The config add Dhcp6/subnet6 command adds + another (second) subnet. It can be referred to as + Dhcp6/subnet6[1]. In this example, we allow server to + dynamically assign all addresses available in the whole subnet. Although + very wasteful, it is certainly a valid configuration to dedicate the + whole /48 subnet for that purpose. + + + When configuring a DHCPv6 server using prefix/length notation, please pay + attention to the boundary values. When specifying that the server should use + a given pool, it will be able to allocate also first (typically network + address) address from that pool. For example for pool 2001:db8::/64 the + 2001:db8:: address may be assigned as well. If you want to avoid this, + please use the "min-max" notation. + +
+ +
+ + Subnet and Prefix Delegation Pools + + Subnets may also be configured to delegate address prefixes.... + A subnet may have one or more prefix delegation pools. Each pool has + a prefixed address, which is specified as a prefix and a prefix length, + as well as a delegated prefix length. A sample configuration is shown + below: + +> config add Dhcp6/subnet6 +> config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64" +> config show Dhcp6/subnet6[0] +> config add Dhcp6/subnet6[0]/pd-pools +> config set Dhcp6/subnet6[0]/pd-pools[0]/prefix "2001:db8:1::" +> config set Dhcp6/subnet6[0]/pd-pools[0]/prefix-len 64 +> config set Dhcp6/subnet6[0]/pd-pools[0]/delegated-len 96 +> config commit + +
+ +
+ Standard DHCPv6 options + + One of the major features of DHCPv6 server is to provide configuration + options to clients. Although there are several options that require + special behavior, most options are sent by the server only if the client + explicitly requested them. The following example shows how to + configure DNS servers, which is one of the most frequently used + options. Numbers in the first column are added for easier reference and + will not appear on screen. Options specified in this way are considered + global and apply to all configured subnets. + + +1. > config add Dhcp6/option-data +2. > config set Dhcp6/option-data[0]/name "dns-servers" +3. > config set Dhcp6/option-data[0]/code 23 +4. > config set Dhcp6/option-data[0]/space "dhcp6" +5. > config set Dhcp6/option-data[0]/csv-format true +6. > config set Dhcp6/option-data[0]/data "2001:db8::cafe, 2001:db8::babe" +7. > config commit + + + + The first line creates new entry in option-data table. It + contains information on all global options that the server is + supposed to configure in all subnets. The second line specifies + option name. For a complete list of currently supported names, + see . + The third line specifies option code, which must match one of the + values from that + list. Line 4 specifies option space, which must always + be set to "dhcp6" as these are standard DHCPv6 options. For + other name spaces, including custom option spaces, see . The fifth line specifies the format in + which the data will be entered: use of CSV (comma + separated values) is recommended. The sixth line gives the actual value to + be sent to clients. Data is specified as a normal text, with + values separated by commas if more than one value is + allowed. + + + + Options can also be configured as hexadecimal values. If csv-format is + set to false, the option data must be specified as a string of hexadecimal + numbers. The + following commands configure the DNS-SERVERS option for all + subnets with the following addresses: 2001:db8:1::cafe and + 2001:db8:1::babe. + +> config add Dhcp6/option-data +> config set Dhcp6/option-data[0]/name "dns-servers" +> config set Dhcp6/option-data[0]/code 23 +> config set Dhcp6/option-data[0]/space "dhcp6" +> config set Dhcp6/option-data[0]/csv-format false +> config set Dhcp6/option-data[0]/data "2001 0DB8 0001 0000 0000 0000 + 0000 CAFE 2001 0DB8 0001 0000 0000 0000 0000 BABE" +> config commit + + (The value for the setting of the "data" element is split across two + lines in this document for clarity: when entering the command, the + whole string should be entered on the same line.) + + + + It is possible to override options on a per-subnet basis. If + clients connected to most of your subnets are expected to get the + same values of a given option, you should use global options: you + can then override specific values for a small number of subnets. + On the other hand, if you use different values in each subnet, + it does not make sense to specify global option values + (Dhcp6/option-data), rather you should set only subnet-specific values + (Dhcp6/subnet[X]/option-data[Y]). + + + The following commands override the global + DNS servers option for a particular subnet, setting a single DNS + server with address 2001:db8:1::3. + +> config add Dhcp6/subnet6[0]/option-data +> config set Dhcp6/subnet6[0]/option-data[0]/name "dns-servers" +> config set Dhcp6/subnet6[0]/option-data[0]/code 23 +> config set Dhcp6/subnet6[0]/option-data[0]/space "dhcp6" +> config set Dhcp6/subnet6[0]/option-data[0]/csv-format true +> config set Dhcp6/subnet6[0]/option-data[0]/data "2001:db8:1::3" +> config commit + + + + + In future versions of BIND 10 DHCP, it will not be necessary to specify + option code, space and csv-format fields, as those fields will be set + automatically. + + + + + + The currently supported standard DHCPv6 options are + listed in . + The "Name" and "Code" + are the values that should be used as a name in the option-data + structures. "Type" designates the format of the data: the meanings of + the various types is given in . + + + Some options are designated as arrays, which means that more than one + value is allowed in such an option. For example the option dns-servers + allows the specification of more than one IPv6 address, so allowing + clients to obtain the the addresses of multiple DNS servers. + + + + + + The describes the configuration + syntax to create custom option definitions (formats). It is generally not + allowed to create custom definitions for standard options, even if the + definition being created matches the actual option format defined in the + RFCs. There is an exception from this rule for standard options for which + Kea does not provide a definition yet. In order to use such options, + a server administrator must create a definition as described in + in the 'dhcp6' option space. This + definition should match the option format described in the relevant + RFC but configuration mechanism would allow any option format as it has + no means to validate it at the moment. + + + + + + List of standard DHCPv6 options + + + + + + + NameCodeTypeArray? + + + +preference7uint8false + + +sip-server-dns21fqdntrue +sip-server-addr22ipv6-addresstrue +dns-servers23ipv6-addresstrue +domain-search24fqdntrue + + +nis-servers27ipv6-addresstrue +nisp-servers28ipv6-addresstrue +nis-domain-name29fqdntrue +nisp-domain-name30fqdntrue +sntp-servers31ipv6-addresstrue +information-refresh-time32uint32false +bcmcs-server-dns33fqdntrue +bcmcs-server-addr34ipv6-addresstrue +geoconf-civic36recordfalse +remote-id37recordfalse +subscriber-id38binaryfalse +client-fqdn39recordfalse +pana-agent40ipv6-addresstrue +new-posix-timezone41stringfalse +new-tzdb-timezone42stringfalse +ero43uint16true +lq-query44recordfalse +client-data45emptyfalse +clt-time46uint32false +lq-relay-data47recordfalse +lq-client-link48ipv6-addresstrue + + +
+ +
+ +
+ Custom DHCPv6 options + It is also possible to define options other than the standard ones. + Assume that we want to define a new DHCPv6 option called "foo" which will have + code 100 and will convey a single unsigned 32 bit integer value. We can define + such an option by using the following commands: + +> config add Dhcp6/option-def +> config set Dhcp6/option-def[0]/name "foo" +> config set Dhcp6/option-def[0]/code 100 +> config set Dhcp6/option-def[0]/type "uint32" +> config set Dhcp6/option-def[0]/array false +> config set Dhcp6/option-def[0]/record-types "" +> config set Dhcp6/option-def[0]/space "dhcp6" +> config set Dhcp6/option-def[0]/encapsulate "" +> config commit + The "false" value of the "array" parameter determines that the option + does NOT comprise an array of "uint32" values but rather a single value. + Two other parameters have been left blank: "record-types" and "encapsulate". + The former specifies the comma separated list of option data fields if the + option comprises a record of data fields. The "record-fields" value should + be non-empty if the "type" is set to "record". Otherwise it must be left + blank. The latter parameter specifies the name of the option space being + encapsulated by the particular option. If the particular option does not + encapsulate any option space it should be left blank. + Note that the above set of comments define the format of the new option and do not + set its values. + + Once the new option format is defined, its value is set + in the same way as for a standard option. For example the following + commands set a global value that applies to all subnets. + +> config add Dhcp6/option-data +> config set Dhcp6/option-data[0]/name "foo" +> config set Dhcp6/option-data[0]/code 100 +> config set Dhcp6/option-data[0]/space "dhcp6" +> config set Dhcp6/option-data[0]/csv-format true +> config set Dhcp6/option-data[0]/data "12345" +> config commit + + + New options can take more complex forms than simple use of + primitives (uint8, string, ipv6-address etc): it is possible to + define an option comprising a number of existing primitives. + + + Assume we want to define a new option that will consist of an IPv6 + address, followed by an unsigned 16 bit integer, followed by a + boolean value, followed by a text string. Such an option could + be defined in the following way: + +> config add Dhcp6/option-def +> config set Dhcp6/option-def[0]/name "bar" +> config set Dhcp6/option-def[0]/code 101 +> config set Dhcp6/option-def[0]/space "dhcp6" +> config set Dhcp6/option-def[0]/type "record" +> config set Dhcp6/option-def[0]/array false +> config set Dhcp6/option-def[0]/record-types "ipv6-address, uint16, boolean, string" +> config set Dhcp6/option-def[0]/encapsulate "" + + The "type" is set to "record" to indicate that the option contains + multiple values of different types. These types are given as a comma-separated + list in the "record-types" field and should be those listed in . + + + The values of the option are set as follows: + +> config add Dhcp6/option-data +> config set Dhcp6/option-data[0]/name "bar" +> config set Dhcp6/option-data[0]/space "dhcp6" +> config set Dhcp6/option-data[0]/code 101 +> config set Dhcp6/option-data[0]/csv-format true +> config set Dhcp6/option-data[0]/data "2001:db8:1::10, 123, false, Hello World" +> config commit + "csv-format" is set "true" to indicate that the "data" field comprises a command-separated + list of values. The values in the "data" must correspond to the types set in + the "record-types" field of the option definition. + + + + It is recommended that boolean values are specified using "true" and "false" + strings. This helps to prevent errors when typing multiple comma separated + values, as it make it easier to identify the type of the value being typed, + and compare it with the order of data fields. Nevertheless, it is possible + to use integer values: "1" and "0", instead of "true" and "false" + accordingly. If other integer value is specified, the configuration is + rejected. + + +
+ +
+ DHCPv6 vendor specific options + + Currently there are three option spaces defined: dhcp4 (to be used + in DHCPv4 daemon) and dhcp6 (for the DHCPv6 daemon); there is also + vendor-opts-space, which is empty by default, but options can be + defined in it. Those options are called vendor-specific information + options. The following examples show how to define an option "foo" + with code 1 that consists of an IPv6 address, an unsigned 16 bit integer + and a string. The "foo" option is conveyed in a vendor specific + information option. This option comprises a single uint32 value + that is set to "12345". The sub-option "foo" follows the data + field holding this value. + +> config add Dhcp6/option-def +> config set Dhcp6/option-def[0]/name "foo" +> config set Dhcp6/option-def[0]/code 1 +> config set Dhcp6/option-def[0]/space "vendor-opts-space" +> config set Dhcp6/option-def[0]/type "record" +> config set Dhcp6/option-def[0]/array false +> config set Dhcp6/option-def[0]/record-types "ipv6-address, uint16, string" +> config set Dhcp6/option-def[0]/encapsulates "" +> config commit + + (Note that the option space is set to "vendor-opts-space".) + Once the option format is defined, the next step is to define actual values + for that option: + +> config add Dhcp6/option-data +> config set Dhcp6/option-data[0]/name "foo" +> config set Dhcp6/option-data[0]/space "vendor-opts-space" +> config set Dhcp6/option-data[0]/code 1 +> config set Dhcp6/option-data[0]/csv-format true +> config set Dhcp6/option-data[0]/data "2001:db8:1::10, 123, Hello World" +> config commit + We should also define values for the vendor-opts, that will convey our option foo. + +> config add Dhcp6/option-data +> config set Dhcp6/option-data[1]/name "vendor-opts" +> config set Dhcp6/option-data[1]/space "dhcp6" +> config set Dhcp6/option-data[1]/code 17 +> config set Dhcp6/option-data[1]/csv-format true +> config set Dhcp6/option-data[1]/data "12345" +> config commit + +
+ +
+ Nested DHCPv6 options (custom option spaces) + It is sometimes useful to define completely new option + spaces. This is useful if the user wants his new option to + convey sub-options that use separate numbering scheme, for + example sub-options with codes 1 and 2. Those option codes + conflict with standard DHCPv6 options, so a separate option + space must be defined. + + Note that it is not required to create new option space when + defining sub-options for a standard option because it is by + default created if the standard option is meant to convey + any sub-options (see ). + + + Assume that we want to have a DHCPv6 option called "container" + with code 102 that conveys two sub-options with codes 1 and 2. + First we need to define the new sub-options: + +> config add Dhcp6/option-def +> config set Dhcp6/option-def[0]/name "subopt1" +> config set Dhcp6/option-def[0]/code 1 +> config set Dhcp6/option-def[0]/space "isc" +> config set Dhcp6/option-def[0]/type "ipv6-address" +> config set Dhcp6/option-def[0]/record-types "" +> config set Dhcp6/option-def[0]/array false +> config set Dhcp6/option-def[0]/encapsulate "" +> config commit +> +> config add Dhcp6/option-def +> config set Dhcp6/option-def[1]/name "subopt2" +> config set Dhcp6/option-def[1]/code 2 +> config set Dhcp6/option-def[1]/space "isc" +> config set Dhcp6/option-def[1]/type "string" +> config set Dhcp6/option-def[1]/record-types "" +> config set Dhcp6/option-def[1]/array false +> config set Dhcp6/option-def[1]/encapsulate "" +> config commit + + Note that we have defined the options to belong to a new option space + (in this case, "isc"). + + +The next step is to define a regular DHCPv6 option and specify that it +should include options from the isc option space: + +> config add Dhcp6/option-def +> config set Dhcp6/option-def[2]/name "container" +> config set Dhcp6/option-def[2]/code 102 +> config set Dhcp6/option-def[2]/space "dhcp6" +> config set Dhcp6/option-def[2]/type "empty" +> config set Dhcp6/option-def[2]/array false +> config set Dhcp6/option-def[2]/record-types "" +> config set Dhcp6/option-def[2]/encapsulate "isc" +> config commit + + The name of the option space in which the sub-options are defined + is set in the "encapsulate" field. The "type" field is set to "empty" + which imposes that this option does not carry any data other than + sub-options. + + + Finally, we can set values for the new options: + +> config add Dhcp6/option-data +> config set Dhcp6/option-data[0]/name "subopt1" +> config set Dhcp6/option-data[0]/space "isc" +> config set Dhcp6/option-data[0]/code 1 +> config set Dhcp6/option-data[0]/csv-format true +> config set Dhcp6/option-data[0]/data "2001:db8::abcd" +> config commit +> +> config add Dhcp6/option-data +> config set Dhcp6/option-data[1]/name "subopt2" +> config set Dhcp6/option-data[1]/space "isc" +> config set Dhcp6/option-data[1]/code 2 +> config set Dhcp6/option-data[1]/csv-format true +> config set Dhcp6/option-data[1]/data "Hello world" +> config commit +> +> config add Dhcp6/option-data +> config set Dhcp6/option-data[2]/name "container" +> config set Dhcp6/option-data[2]/space "dhcp6" +> config set Dhcp6/option-data[2]/code 102 +> config set Dhcp6/option-data[2]/csv-format true +> config set Dhcp6/option-data[2]/data "" +> config commit + + Even though the "container" option does not carry any data except + sub-options, the "data" field must be explicitly set to an empty value. + This is required because in the current version of BIND 10 DHCP, the + default configuration values are not propagated to the configuration parsers: + if the "data" is not set the parser will assume that this + parameter is not specified and an error will be reported. + + Note that it is possible to create an option which carries some data + in addition to the sub-options defined in the encapsulated option space. For example, + if the "container" option from the previous example was required to carry an uint16 + value as well as the sub-options, the "type" value would have to be set to "uint16" in + the option definition. (Such an option would then have the following + data structure: DHCP header, uint16 value, sub-options.) The value specified + with the "data" parameter - which should be a valid integer enclosed in quotes, + e.g. "123" - would then be assigned to the uint16 field in the "container" option. + +
+ +
+ IPv6 Subnet Selection + + The DHCPv6 server may receive requests from local (connected to the + same subnet as the server) and remote (connecting via relays) clients. + As server may have many subnet configurations defined, it must select + appropriate subnet for a given request. + + + The server can not assume which of configured subnets are local. It is + possible in IPv4, where there is reasonable expectation that the + server will have a (global) IPv4 address configured on the interface, + and can use that information to detect whether a subnet is local or + not. That assumption is not true in IPv6, as the DHCPv6 must be able + to operate with having link-local addresses only. Therefore an optional + "interface" parameter is available within a subnet definition + to designate that a given subnet is local, i.e. reachable directly over + specified interface. For example the server that is intended to serve + a local subnet over eth0 may be configured as follows: + +> config add Dhcp6/subnet6 +> config set Dhcp6/subnet6[1]/subnet "2001:db8:beef::/48" +> config set Dhcp6/subnet6[1]/pool [ "2001:db8:beef::/48" ] +> config set Dhcp6/subnet6[1]/interface "eth0" +> config commit + + +
+ +
+ DHCPv6 Relays + + A DHCPv6 server with multiple subnets defined must select the + appropriate subnet when it receives a request from client. For clients + connected via relays, two mechanisms are used: + + + The first uses the linkaddr field in the RELAY_FORW message. The name + of this field is somewhat misleading in that it does not contain a link-layer + address: instead, it holds an address (typically a global address) that is + used to identify a link. The DHCPv6 server checks if the address belongs + to a defined subnet and, if it does, that subnet is selected for the client's + request. + + + The second mechanism is based on interface-id options. While forwarding a client's + message, relays may insert an interface-id option into the message that + identifies the interface on the relay that received the message. (Some + relays allow configuration of that parameter, but it is sometimes + hardcoded and may range from the very simple (e.g. "vlan100") to the very cryptic: + one example seen on real hardware was "ISAM144|299|ipv6|nt:vp:1:110"). The + server can use this information to select the appropriate subnet. + The information is also returned to the relay which then knows the + interface to use to transmit the response to the client. In order for + this to work successfully, the relay interface IDs must be unique within + the network and the server configuration must match those values. + + + When configuring the DHCPv6 server, it should be noted that two + similarly-named parameters can be configured for a subnet: + + + "interface" defines which local network interface can be used + to access a given subnet. + + + "interface-id" specifies the content of the interface-id option + used by relays to identify the interface on the relay to which + the response packet is sent. + + + The two are mutually exclusive: a subnet cannot be both reachable locally + (direct traffic) and via relays (remote traffic). Specifying both is a + configuration error and the DHCPv6 server will refuse such a configuration. + + + + To specify interface-id with value "vlan123", the following commands can + be used: + +> config add Dhcp6/subnet6 +> config set Dhcp6/subnet6[0]/subnet "2001:db8:beef::/48" +> config set Dhcp6/subnet6[0]/pool [ "2001:db8:beef::/48" ] +> config set Dhcp6/subnet6[0]/interface-id "vland123" +> config commit + + +
+ +
+ Client Classification in DHCPv6 + + + DHCPv6 server has been extended to support limited client classification. + Although the current capability is modest, it is expected to be expanded + in the future. It is envisaged that the majority of client classification + extensions will be using hooks extensions. + + + In certain cases it is useful to differentiate between different types + of clients and treat them differently. The process of doing classification + is conducted in two steps. The first step is to assess incoming packet and + assign it to zero or more classes. This classification is currently simple, + but is expected to grow in capability soon. Currently the server checks whether + incoming packet has vendor class option (16). If it has, content + of that option is prepended with "VENDOR_CLASS_" interpreted as a + class. For example, modern cable modems will send this option with value + "docsis3.0" and as a result the packet will belong to class + "VENDOR_CLASS_docsis3.0". + + + It is envisaged that the client classification will be used for changing + behavior of almost any part of the DHCP engine processing, including assigning + leases from different pools, assigning different option (or different values of + the same options) etc. For now, there is only one mechanism that is taking + advantage of client classification: subnet selection. + + + Kea can be instructed to limit access to given subnets based on class information. + This is particularly useful for cases where two types of devices share the + same link and are expected to be served from two different subnets. The + primary use case for such a scenario are cable networks. There are two + classes of devices: cable modem itself, which should be handled a lease + from subnet A and all other devices behind modems that should get a lease + from subnet B. That segregation is essential to prevent overly curious + users from playing with their cable modems. For details on how to set up + class restrictions on subnets, see . + + +
+ +
+ Limiting access to IPv6 subnet to certain classes + + In certain cases it beneficial to restrict access to certains subnets + only to clients that belong to a given subnet. For details on client + classes, see . This is an + extension of a previous example from . + + Let's assume that the server is connected to a network segment that uses + the 2001:db8:1::/64 prefix. The Administrator of that network has + decided that addresses from range 2001:db8:1::1 to 2001:db8:1::ffff are + going to be managed by the Dhcp6 server. Only clients belonging to the + eRouter1.0 client class are allowed to use that pool. Such a + configuration can be achieved in the following way: + + +> config add Dhcp6/subnet6 +> config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64" +> config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::0 - 2001:db8:1::ffff" ] +> config set Dhcp6/subnet6[0]/client-class "eRouter1.0" +> config commit + + + + Care should be taken with client classification as it is easy to prevent + clients that do not meet class criteria to be denied any service altogether. + +
+ + +
+ Configuring DHCPv6 for DDNS + + As mentioned earlier, b10-dhcp6 can be configured to generate requests to + the DHCP-DDNS server (referred to here as the "D2" server) to update + DNS entries. These requests are known as NameChangeRequests or NCRs. + Each NCR contains the following information: + + + Whether it is a request to add (update) or remove DNS entries + + + Whether the change requests forward DNS updates (AAAA records), reverse + DNS updates (PTR records), or both. + + + The FQDN, lease address, and DHCID + + + The parameters controlling the generation of NCRs for submission to D2 + are contained in the "dhcp-ddns" section of b10-dhcp6 + configuration. The default values for this section appears as follows: + +> config show Dhcp6/dhcp-ddns +Dhcp6/dhcp-ddns/enable-updates true boolean +Dhcp6/dhcp-ddns/server-ip "127.0.0.1" string +Dhcp6/dhcp-ddns/server-port 53001 integer +Dhcp6/dhcp-ddns/sender-ip "" string +Dhcp6/dhcp-ddns/sender-port 0 integer +Dhcp6/dhcp-ddns/max-queue-size 1024 integer +Dhcp6/dhcp-ddns/ncr-protocol "UDP" string +Dhcp6/dhcp-ddns/ncr-format "JSON" string +Dhcp6/dhcp-ddns/override-no-update false boolean +Dhcp6/dhcp-ddns/override-client-update false boolean +Dhcp6/dhcp-ddns/replace-client-name false boolean +Dhcp6/dhcp-ddns/generated-prefix "myhost" string +Dhcp6/dhcp-ddns/qualifying-suffix "example.com" string + + + + The "enable-updates" parameter determines whether or not b10-dhcp6 will + generate NCRs. By default, this value is false hence DDNS updates are + disabled. To enable DDNS updates set this value to true as follows: + + +> config set Dhcp6/dhcp-ddns/enable-updates true +> config commit + +
+ DHCP-DDNS Server Connectivity + + In order for NCRs to reach the D2 server, b10-dhcp6 must be able + to communicate with it. b10-dhcp6 uses the following configuration + parameters to control how it communications with D2: + + + server-ip - 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. + + + server-port - port on which D2 listens for requests. The default value + is 53001. + + + sender-ip - IP address which b10-dhcp6 should use to send requests to D2. + The default value is blank which instructs b10-dhcp6 to select a suitable + address. + + + sender-port - port which b10-dhcp6 should use to send requests to D2. The + default value of 0 instructs b10-dhcp6 to select suitable port. + + + ncr-format - Socket protocol use when sending requests to D2. Currently + only UDP is supported. TCP may be available in an upcoming release. + + + 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. + + + max-queue-size - maximum number of requests allowed to queue waiting to + be sent to D2. This value guards against requests accumulating + uncontrollably if they are being generated faster than they can be + delivered. If the number of requests queued for transmission reaches + this value, DDNS updating will be turned off until the queue backlog has + been sufficiently reduced. The intent is allow b10-dhcp6 to + continue lease operations. The default value is 1024. + + + By default, D2 is assumed to running on the same machine as b10-dhcp6, and + all of the default values mentioned above should be sufficient. + If, however, D2 has been configured to listen on a different address or + port, these values must altered accordingly. For example, if D2 has been + configured to listen on 3001::5 port 900, the following commands + would be required: + +> config set Dhcp6/dhcp-ddns/server-ip "3001::5" +> config set Dhcp6/dhcp-ddns/server-port 900 +> config commit + + +
+
+ When does b10-dhcp6 generate DDNS request + b10-dhcp6 follows the behavior prescribed for DHCP servers in RFC 4704. + It is important to keep in mind that b10-dhcp6 provides the initial decision + making of when and what to update and forwards that information to D2 in + the form of NCRs. Carrying out the actual DNS updates and dealing with + such things as conflict resolution are the purview of D2 (). + + This section describes when b10-dhcp6 will generate NCRs and the + configuration parameters that can be used to influence this decision. + It assumes that the "enable-updates" parameter is true. + + + + Currently the interface between b10-dhcp6 and D2 only supports requests + which update DNS entries for a single IP address. If a lease grants + more than one address, b10-dhcp6 will create the DDNS update request for + only the first of these addresses. Support for multiple address + mappings may be provided in a future release. + + + + In general, b10-dhcp6 will generate DDNS update requests when: + + + A new lease is granted in response to a DHCP REQUEST + + + An existing lease is renewed but the FQDN associated with it has + changed. + + + An existing lease is released in response to a DHCP RELEASE + + + In the second case, lease renewal, two DDNS requests will be issued: one + request to remove entries for the previous FQDN and a second request to + add entries for the new FQDN. In the last case, a lease release, a + single DDNS request to remove its entries will be made. The decision + making involved when granting a new lease is more involved and is + discussed next. + + + b10-dhcp6 will generate a DDNS update request only if the DHCP REQUEST + contains the FQDN option (code 39). By default b10-dhcp6 will + respect the FQDN N and S flags specified by the client as shown in the + following table: + + + Default FQDN Flag Behavior + + + + + + + + Client Flags:N-S + Client Intent + Server Response + Server Flags:N-S-O + + + + + 0-0 + + Client wants to do forward updates, server should do reverse updates + + Server generates reverse-only request + 1-0-0 + + + 0-1 + Server should do both forward and reverse updates + Server generates request to update both directions + 0-1-0 + + + 1-0 + Client wants no updates done + Server does not generate a request + 1-0-0 + + + +
+ + The first row in the table above represents "client delegation". Here + the DHCP client states that it intends to do the forward DNS updates and + the server should do the reverse updates. By default, b10-dhcp6 will honor + the client's wishes and generate a DDNS request to D2 to update only + reverse DNS data. The parameter, "override-client-update", can be used + to instruct the server to override client delegation requests. When + this parameter is true, b10-dhcp6 will disregard requests for client + delegation and generate a DDNS request to update both forward and + reverse DNS data. In this case, the N-S-O flags in the server's + response to the client will be 0-1-1 respectively. + + + (Note that the flag combination N=1, S=1 is prohibited according to + RFC 4702. If such a combination is received from the client, the packet + will be dropped by b10-dhcp6.) + + + To override client delegation, issue the following commands: + + +> config set Dhcp6/dhcp-ddns/override-client-update true +> config commit + + + The third row in the table above describes the case in which the client + requests that no DNS updates be done. The parameter, "override-no-update", + can be used to instruct the server to disregard the client's wishes. When + this parameter is true, b10-dhcp6 will generate DDNS update request to D2 + even if the client requests no updates be done. The N-S-O flags in the + server's response to the client will be 0-1-1. + + + To override client delegation, issue the following commands: + + +> config set Dhcp6/dhcp-ddns/override-no-update true +> config commit + +
+
+ b10-dhcp6 name generation for DDNS update requests + Each NameChangeRequest must of course include the fully qualified domain + name whose DNS entries are to be affected. b10-dhcp6 can be configured to + supply a portion or all of that name based upon what it receives from + the client in the DHCP REQUEST. + + The rules for determining the FQDN option are as follows: + + + If configured to do so ignore the REQUEST contents and generate a + FQDN using a configurable prefix and suffix. + + + Otherwise, using is the domain name value from the client FQDN option as + the candidate name: + + + If the candidate name is a fully qualified domain name then use it. + + + If the candidate name is a partial (i.e. unqualified) name then + add a configurable suffix to the name and use the result as the FQDN. + + + If the candidate name is a empty then generate a FQDN using a + configurable prefix and suffix. + + + + + To instruct b10-dhcp6 to always generate a FQDN, set the parameter + "replace-client-name" to true: + + +> config set Dhcp6/dhcp-ddns/replace-client-name true +> config commit + + + The prefix used when generating a FQDN is specified by the + "generated-prefix" parameter. The default value is "myhost". To alter + its value, simply set it to the desired string: + + +> config set Dhcp6/dhcp-ddns/generated-prefix "another.host" +> config commit + + + The suffix used when generating a FQDN or when qualifying a partial + name is specified by the "qualifying-suffix" parameter. The default + value is "example.com". To alter its value simply set it to the desired + string: + + +> config set Dhcp6/dhcp-ddns/generated-prefix "our.net" +> config commit + +
+ + When qualifying a partial name, b10-dhcp6 will construct a name with the + format: + + + [candidate-name].[qualifying-suffix]. + + + where candidate-name is the partial name supplied in the REQUEST. + For example, if FQDN domain name value was "some-computer" and assuming + the default value for qualifying-suffix, the generated FQDN would be: + + + some-computer.example.com. + + + When generating a the entire name, b10-dhcp6 will construct name of the + format: + + + [generated-prefix]-[address-text].[qualifying-suffix]. + + + where address-text is simply the lease IP address converted to a + hyphenated string. For example, if lease address is 3001:1::70E and + assuming default values for generated-prefix and qualifying-suffix, the + generated FQDN would be: + + + myhost-3001-1--70E.example.com. + +
+ +
+ +
+ Server Identifier in DHCPv6 + The DHCPv6 protocol uses a "server identifier" (also known + as a DUID) for clients to be able to discriminate between several + servers present on the same link. There are several types of + DUIDs defined, but RFC 3315 instructs servers to use DUID-LLT if + possible. This format consists of a link-layer (MAC) address and a + timestamp. When started for the first time, the DHCPv6 server will + automatically generate such a DUID and store the chosen value to + a file. That file is read by the server + and the contained value used whenever the server is subsequently started. + + + It is unlikely that this parameter should ever need to be changed. + However, if such a need arises, stop the server, edit the file and restart + the server. (The file is named b10-dhcp6-serverid and by default is + stored in the "var" subdirectory of the directory in which BIND 10 is installed. + This can be changed when BIND 10 is built by using "--localstatedir" + on the "configure" command line.) The file is a text file that contains + double digit hexadecimal values + separated by colons. This format is similar to typical MAC address + format. Spaces are ignored. No extra characters are allowed in this + file. + + +
+ +
+ Using specific relay agent for a subnet + + The relay has to have an interface connected to the link on which + the clients are being configured. Typically the relay has a global IPv6 + address configured on that interface that belongs to the subnet that + the server will assign addresses from. In such typical case, the + server is able to use IPv6 address inserted by the relay (in link-addr + field in RELAY-FORW message) to select appropriate subnet. + + + However, that is not always the case. The relay + address may not match the subnet in certain deployments. This + usually means that there is more than one subnet allocated for a given + link. Two most common examples where this is the case are long lasting + network renumbering (where both old and new address space is still being + used) and a cable network. In a cable network both cable modems and the + devices behind them are physically connected to the same link, yet + they use distinct addressing. In such case, the DHCPv6 server needs + additional information (like the value of interface-id option or IPv6 + address inserted in the link-addr field in RELAY-FORW message) to + properly select an appropriate subnet. + + + The following example assumes that there is a subnet 2001:db8:1::/64 + that is accessible via relay that uses 3000::1 as its IPv6 address. + The server will be able to select this subnet for any incoming packets + that came from a relay that has an address in 2001:db8:1::/64 subnet. + It will also select that subnet for a relay with address 3000::1. + +> config add Dhcp6/subnet6 +> config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64" +> config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::2 - 2001:db8:1::ffff" ] +> config set Dhcp6/subnet6[0]/relay/ip-address "3000::1" +> config commit + + +
+ +
+ Segregating IPv6 clients in a cable network + + In certain cases, it is useful to mix relay address information, + introduced in with client + classification, explained in . + One specific example is cable network, where typically modems + get addresses from a different subnet than all devices connected + behind them. + + + Let's assume that there is one CMTS (Cable Modem Termination System) + with one CM MAC (a physical link that modems are connected to). + We want the modems to get addresses from the 3000::/64 subnet, + while everything connected behind modems should get addresses from + another subnet (2001:db8:1::/64). The CMTS that acts as a relay + an uses address 3000::1. The following configuration can serve + that configuration: + +> config add Dhcp6/subnet6 +> config set Dhcp6/subnet6[0]/subnet "3000::/64" +> config set Dhcp6/subnet6[0]/pool [ "3000::2 - 3000::ffff" ] +> config set Dhcp6/subnet6[0]/client-class "docsis3.0" +> config set Dhcp6/subnet6[0]/relay/ip-address "3000::1" +> config add Dhcp6/subnet6 +> config set Dhcp6/subnet6[1]/subnet "2001:db8:1::/64" +> config set Dhcp6/subnet6[1]/pool [ "2001:db8:1::1 - 2001:db8:1::ffff" ] +> config set Dhcp6/subnet6[1]/relay/ip-address "3000::1" +> config commit + +
+ + +
+ Supported Standards + The following standards and draft standards are currently + supported: + + + RFC 3315: Supported messages are SOLICIT, + ADVERTISE, REQUEST, RELEASE, RENEW, REBIND and REPLY. + + + RFC 3633: Supported options are IA_PD and + IA_PREFIX. Also supported is the status code NoPrefixAvail. + + + RFC 3646: Supported option is DNS_SERVERS. + + + RFC 4704: Supported option is CLIENT_FQDN. + + +
+ +
+ DHCPv6 Server Limitations + These are the current limitations and known problems + with the DHCPv6 server + software. Most of them are reflections of the early stage of + development and should be treated as not implemented + yet, rather than actual limitations. + + + + On-line configuration has some limitations. Adding new subnets or + modifying existing ones work, as is removing the last subnet from + the list. However, removing non-last (e.g. removing subnet 1,2 or 3 if + there are 4 subnets configured) will cause issues. The problem is + caused by simplistic subnet-id assignment. The subnets are always + numbered, starting from 1. That subnet-id is then used in leases + that are stored in the lease database. Removing non-last subnet will + cause the configuration information to mismatch data in the lease + database. It is possible to manually update subnet-id fields in + MySQL or PostgreSQL database, but it is awkward and error prone + process. A better reconfiguration support is planned. + + + + + + On startup, the DHCPv6 server does not get the full configuration from + BIND 10. To remedy this, after starting BIND 10, modify any parameter + and commit the changes, e.g. + +> config show Dhcp6/renew-timer +Dhcp6/renew-timer 1000 integer (default) +> config set Dhcp6/renew-timer 1001 +> config commit + + + + Temporary addresses are not supported. + + + + The server will allocate, renew or rebind a maximum of one lease + for a particular IA option (IA_NA or IA_PD) sent by a client. + RFC 3315 and + RFC 3633 allow + for multiple addresses or prefixes to be allocated for a single IA. + + + + Temporary addresses are not supported. + + + + Confirmation (CONFIRM), duplication report (DECLINE), + stateless configuration (INFORMATION-REQUEST) and client + reconfiguration (RECONFIGURE) are not yet supported. + + + + + The server doesn't act upon expired leases. In particular, + when a lease expires, the server doesn't request removal of + the DNS records associated with it. + + + +
+ + + + diff --git a/doc/guide/intro.xml b/doc/guide/intro.xml new file mode 100644 index 0000000000..8472bb7d27 --- /dev/null +++ b/doc/guide/intro.xml @@ -0,0 +1,288 @@ + + + +%version; +]> + + + Introduction + + Kea is the next generation of DHCP servers developed by ISC. + It supports both DHCPv4 and DHCPv6 protocols along with their + extensions, e.g. prefix delegation and dynamic updates to DNS. + + + + Kea has been initially developed as a part of the BIND 10 framework + (). In early 2014, ISC + made the decision to discontinue active development of BIND 10 and + continue development of Kea as standalone DHCP servers. As a result, + the components and libraries related to the BIND10 framework and DNS + are going to be removed from the Kea source tree over time. + In order to remove the dependency on Python 3, the BIND 10 framework + will be replaced by the server startup and configuration mechanisms + written in C++. + + + + Kea has been implemented in BIND 10 framework and to certain extent + it still depends on various BIND 10 libraries. It also requires the BIND 10 + framework to run, because BIND 10 configuration mechanisms are used to + configure Kea. As a result, this document still refers to BIND 10 in many + paragraphs. The term "BIND 10" in the context of this document means + "BIND 10 libraries and applications which are necessary for Kea to run + and configure". The term "Kea" means "the collection of binaries and libraries + which, as a whole, implement the DHCP protocols". + + + + + This guide covers Kea version &__VERSION__;. + + +
+ Supported Platforms + + Kea is officially supported on RedHat Enterprise Linux, + CentOS, Fedora and FreeBSD systems. It is also likely to work on many + other platforms: builds have been tested on (in no particular order) + Debian GNU/Linux 6 and unstable, Ubuntu 9.10, NetBSD 5, + Solaris 10 and 11, FreeBSD 7 and 8, CentOS Linux 5.3, + MacOS 10.6 and 10.7, and OpenBSD 5.1. Non supported systems + (especially non-Linux) are likely to have issues with directly + connected DHCPv4 clients. + + There are currently no plans to port Kea to Windows platforms. +
+ +
+ Required Software at Run-time + + + Running Kea uses various extra software which may + not be provided in some operating systems' default + installations nor standard packages collections. You may + need to install this required software separately. + (For the build requirements, also see + .) + + + + Kea was developed as a collection of applications within BIND + 10 framework and it still relies on the remaining parts of + this framework. In particular, the servers' configuration and + startup are still facilitated by the modules which originate + in BIND 10. These modules require at least Python 3.1 to run. + They also work with Python 3.2, 3.3 or 3.4 (). The dependency on Python will + be removed once a replacing configuration and startup + mechanisms are developed and released as Kea 0.9. At this + point Kea will be written in pure C++. + + + + Kea uses the Botan crypto library for C++ + (). + It requires at least Botan version 1.8. + + + + + Kea uses the log4cplus C++ logging library + (). + It requires at least log4cplus version 1.0.3. + + + + Kea can use MySQL headers and libraries to build MySQL database backend + that can be used to store leases. This is an optional dependency. When + it is missing, Kea will lack the ability to store leases in MySQL + database. + + + + Kea can use PostgreSQL headers and libraries to build PostgreSQL + database backend that can be used to store leases. This is an optional + dependency. When it is missing, Kea will lack the ability to store + leases in PostgreSQL database. + +
+ +
+ Starting and Stopping the Server + + + Kea is modular. Part of this modularity is + accomplished using multiple cooperating processes which, together, + provide the server functionality. + + + + + At first, running many different processes may seem confusing. + However, these processes are started by running a single + command, bind10. This command starts + a master process, b10-init, which will + start other required processes and other processes when + configured. The processes that may be started have names + starting with "b10-", including: + + + + + + + + + b10-cfgmgr — + Configuration manager. + This process maintains all of the configuration for BIND 10. + + + + + + b10-cmdctl — + Command and control service. + This process allows external control of the BIND 10 system. + + + + + + b10-dhcp4 — + DHCPv4 server process. + This process responds to DHCPv4 queries from clients. + + + + + + b10-dhcp6 — + DHCPv6 server process. + This process responds to DHCPv6 queries from clients. + + + + + + b10-dhcp-ddns — + DHCP-DDNS process. + This process acts as an intermediary between the DHCP servers + and DNS server. It receives name update requests from the DHCP + servers and sends DNS Update messages to the DNS servers. + + + + + + b10-msgq — + Message bus daemon. + This process coordinates communication between all of the other + BIND 10 processes. + + + + + + b10-sockcreator — + Socket creator daemon. + This process creates sockets used by + network-listening BIND 10 processes. + + + + + + b10-stats — + Statistics collection daemon. + This process collects and reports statistics data. + + + + + + b10-stats-httpd — + HTTP server for statistics reporting. + This process reports statistics data in XML format over HTTP. + + + + + + + + These do not need to be manually started independently. + + +
+ +
+ Managing BIND 10 + + + + Once BIND 10 is running, a few commands are used to interact + directly with the system: + + + + bindctl — + Interactive administration interface. + This is a low-level command-line tool which allows + a developer or an experienced administrator to control + Kea. + + + + + b10-cmdctl-usermgr — + User access control. + This tool allows an administrator to authorize additional users + to manage Kea. + + + + + +
+ + + The tools and modules are covered in full detail in this guide. + + In addition, manual pages are also provided in the default installation. + + + + + + BIND 10 also provides libraries and programmer interfaces + for C++ and Python for the message bus and configuration backend, + and, of course, DHCP. These include detailed developer + documentation and code examples. + + + + diff --git a/doc/guide/kea-guide.xml b/doc/guide/kea-guide.xml index cabb9d569f..cbd5d44656 100644 --- a/doc/guide/kea-guide.xml +++ b/doc/guide/kea-guide.xml @@ -51,4342 +51,31 @@ - - Introduction - - Kea is the next generation of DHCP servers developed by ISC. - It supports both DHCPv4 and DHCPv6 protocols along with their - extensions, e.g. prefix delegation and dynamic updates to DNS. - + - - Kea has been initially developed as a part of the BIND 10 framework - (). In early 2014, ISC - made the decision to discontinue active development of BIND 10 and - continue development of Kea as standalone DHCP servers. As a result, - the components and libraries related to the BIND10 framework and DNS - are going to be removed from the Kea source tree over time. - In order to remove the dependency on Python 3, the BIND 10 framework - will be replaced by the server startup and configuration mechanisms - written in C++. - - - - Kea has been implemented in BIND 10 framework and to certain extent - it still depends on various BIND 10 libraries. It also requires the BIND 10 - framework to run, because BIND 10 configuration mechanisms are used to - configure Kea. As a result, this document still refers to BIND 10 in many - paragraphs. The term "BIND 10" in the context of this document means - "BIND 10 libraries and applications which are necessary for Kea to run - and configure". The term "Kea" means "the collection of binaries and libraries - which, as a whole, implement the DHCP protocols". - - - - - This guide covers Kea version &__VERSION__;. - - -
- Supported Platforms - - Kea is officially supported on RedHat Enterprise Linux, - CentOS, Fedora and FreeBSD systems. It is also likely to work on many - other platforms: builds have been tested on (in no particular order) - Debian GNU/Linux 6 and unstable, Ubuntu 9.10, NetBSD 5, - Solaris 10 and 11, FreeBSD 7 and 8, CentOS Linux 5.3, - MacOS 10.6 and 10.7, and OpenBSD 5.1. Non supported systems - (especially non-Linux) are likely to have issues with directly - connected DHCPv4 clients. - - There are currently no plans to port Kea to Windows platforms. -
- -
- Required Software at Run-time - - - Running Kea uses various extra software which may - not be provided in some operating systems' default - installations nor standard packages collections. You may - need to install this required software separately. - (For the build requirements, also see - .) - - - - Kea was developed as a collection of applications within BIND - 10 framework and it still relies on the remaining parts of - this framework. In particular, the servers' configuration and - startup are still facilitated by the modules which originate - in BIND 10. These modules require at least Python 3.1 to run. - They also work with Python 3.2, 3.3 or 3.4 (). The dependency on Python will - be removed once a replacing configuration and startup - mechanisms are developed and released as Kea 0.9. At this - point Kea will be written in pure C++. - - - - Kea uses the Botan crypto library for C++ - (). - It requires at least Botan version 1.8. - - - - - Kea uses the log4cplus C++ logging library - (). - It requires at least log4cplus version 1.0.3. - - - - Kea can use MySQL headers and libraries to build MySQL database backend - that can be used to store leases. This is an optional dependency. When - it is missing, Kea will lack the ability to store leases in MySQL - database. - - - - Kea can use PostgreSQL headers and libraries to build PostgreSQL - database backend that can be used to store leases. This is an optional - dependency. When it is missing, Kea will lack the ability to store - leases in PostgreSQL database. - -
- -
- Starting and Stopping the Server - - - Kea is modular. Part of this modularity is - accomplished using multiple cooperating processes which, together, - provide the server functionality. - - - - - At first, running many different processes may seem confusing. - However, these processes are started by running a single - command, bind10. This command starts - a master process, b10-init, which will - start other required processes and other processes when - configured. The processes that may be started have names - starting with "b10-", including: - - - - - - - - - b10-cfgmgr — - Configuration manager. - This process maintains all of the configuration for BIND 10. - - - - - - b10-cmdctl — - Command and control service. - This process allows external control of the BIND 10 system. - - - - - - b10-dhcp4 — - DHCPv4 server process. - This process responds to DHCPv4 queries from clients. - - - - - - b10-dhcp6 — - DHCPv6 server process. - This process responds to DHCPv6 queries from clients. - - - - - - b10-dhcp-ddns — - DHCP-DDNS process. - This process acts as an intermediary between the DHCP servers - and DNS server. It receives name update requests from the DHCP - servers and sends DNS Update messages to the DNS servers. - - - - - - b10-msgq — - Message bus daemon. - This process coordinates communication between all of the other - BIND 10 processes. - - - - - - b10-sockcreator — - Socket creator daemon. - This process creates sockets used by - network-listening BIND 10 processes. - - - - - - b10-stats — - Statistics collection daemon. - This process collects and reports statistics data. - - - - - - b10-stats-httpd — - HTTP server for statistics reporting. - This process reports statistics data in XML format over HTTP. - - - - - - - - These do not need to be manually started independently. - - -
- -
- Managing BIND 10 - - - - Once BIND 10 is running, a few commands are used to interact - directly with the system: - - - - bindctl — - Interactive administration interface. - This is a low-level command-line tool which allows - a developer or an experienced administrator to control - Kea. - - - - - b10-cmdctl-usermgr — - User access control. - This tool allows an administrator to authorize additional users - to manage Kea. - - - - - -
- - - The tools and modules are covered in full detail in this guide. - - In addition, manual pages are also provided in the default installation. - - - - - - BIND 10 also provides libraries and programmer interfaces - for C++ and Python for the message bus and configuration backend, - and, of course, DHCP. These include detailed developer - documentation and code examples. - - - - - - - Quick start - - - This quickly covers the standard steps for installing and deploying Kea. - For further details, full customizations, and troubleshooting, see the - respective chapters in the Kea guide. - - -
- Quick start guide for DHCPv4 and DHCPv6 services - - - - - - Install required run-time and build dependencies. See for details. - - - - - - - Checkout the latest Kea revision from the Git repository: - $ git clone git://git.kea.isc.org/kea - - - - - Go into the source and run configure: - $ cd kea -$ autoreconf --install -$ ./configure [your extra parameters] - - - - - Build it: - $ make - - - - - Install it as root (by default to prefix - /usr/local/): - $ make install - - - - - Edit your configuration file for DHCPv4. See doc/examples/kea4 - for a set of examples. - - - - - Start Kea DHCPv4 server (as root): - # b10-dhcp4 -c /path/to/your/kea4/config/file.json - - - - - Test it; for example, use the - ISC DHCP client - to send DHCPv4 queries to the server and verify that the client receives a - configuration from the server: - $ dhclient -4 eth0 - - - - - Edit your configuration file for DHCPv6. See doc/examples/kea6 - for a set of examples. - - - - - Start Kea DHCPv6 server (as root): - # b10-dhcp6 -c /path/to/your/kea6/config/file.json - - - - - Test it; for example, use the - ISC DHCP client - to send DHCPv6 queries to the server and verify that the client receives a - configuration from the server: - $ dhclient -6 eth0 - - - - - - -
- - + - - The DHCPv4 Server + -
- Starting and Stopping the DHCPv4 Server + - - b10-dhcp4 is the Kea DHCPv4 server and is configured - through the bindctl program. - - - After starting bind10 and entering bindctl, the first step - in configuring the server is to add it to the list of running services. - -> config add Init/components b10-dhcp4 -> config set Init/components/b10-dhcp4/kind dispensable -> config commit - - - - To remove b10-dhcp4 from the set of running services, - the b10-dhcp4 is removed from list of Init components: - -> config remove Init/components b10-dhcp4 -> config commit - - - - Note that the server was only removed from the list, so BIND10 will not - restart it, but the server itself is still running. Hence it is usually - desired to stop it: - -> Dhcp4 shutdown - - + - - On start-up, the server will detect available network interfaces - and will attempt to open UDP sockets on all interfaces that - are up, running, are not loopback, and have IPv4 address - assigned. - - The server will then listen to incoming traffic. Currently - supported client messages are DISCOVER and REQUEST. The server - will respond to them with OFFER and ACK, respectively. - - Since the DHCPv4 server opens privileged ports, it requires root - access. Make sure you run this daemon as root. - - -
- -
- Configuring the DHCPv4 Server - - Once the server is started, it can be configured. To view the - current configuration, use the following command in bindctl: - -> config show Dhcp4 - When starting the DHCPv4 daemon for the first time, the default configuration - will be available. It will look similar to this: - -> config show Dhcp4 -Dhcp4/hooks-libraries [] list (default) -Dhcp4/interfaces/ list -Dhcp4/renew-timer 1800 integer -Dhcp4/rebind-timer 2000 integer (default) -Dhcp4/valid-lifetime 4000 integer (default) -Dhcp4/next-server "" string (default) -Dhcp4/echo-client-id true boolean (default) -Dhcp4/option-def [] list (default) -Dhcp4/option-data [] list (default) -Dhcp4/lease-database/type "" string (default) -Dhcp4/lease-database/name "" string (default) -Dhcp4/lease-database/user "" string (default) -Dhcp4/lease-database/host "" string (default) -Dhcp4/lease-database/password "" string (default) -Dhcp4/subnet4/ list -Dhcp4/dhcp-ddns/enable-updates true boolean -Dhcp4/dhcp-ddns/server-ip "127.0.0.1" string -Dhcp4/dhcp-ddns/server-port 53001 integer -Dhcp4/dhcp-ddns/sender-ip "" string -Dhcp4/dhcp-ddns/sender-port 0 integer -Dhcp4/dhcp-ddns/max-queue-size 1024 integer -Dhcp4/dhcp-ddns/ncr-protocol "UDP" string -Dhcp4/dhcp-ddns/ncr-format "JSON" string -Dhcp4/dhcp-ddns/override-no-update false boolean -Dhcp4/dhcp-ddns/override-client-update false boolean -Dhcp4/dhcp-ddns/replace-client-name false boolean -Dhcp4/dhcp-ddns/generated-prefix "myhost" string -Dhcp4/dhcp-ddns/qualifying-suffix "example.com" string - - - - - To change one of the parameters, simply follow - the usual bindctl procedure. For example, to make the - leases longer, change their valid-lifetime parameter: - -> config set Dhcp4/valid-lifetime 7200 -> config commit - Please note that most Dhcp4 parameters are of global scope - and apply to all defined subnets, unless they are overridden on a - per-subnet basis. - - - The renew-timer and rebind-timer are optional. If they are not specified, - the DHCPv4 options 58 and 59 are not sent in the server's response to the - client. - - -
- Default storage for leases - - The server is able to store lease data in different repositories. Larger deployments - may elect to store leases in a database. - describes one way to do it. - By default, the server will use a CSV file rather than a database to store - lease information. One of the advantages of using a file is that it eliminates - dependency on third party database software. - - - The configuration of the file backend (Memfile) - is controlled through the Dhcp4/lease-database parameters. When default - parameters are used, the Memfile backend will write leases to a disk in the - [bind10-install-dir]/var/bind10/kea-leases4.csv. - - - It is possible to alter the default location of the lease file. The following - configuration: - -> config set Dhcp4/lease-database/type "memfile" -> config set Dhcp4/lease-database/persist true -> config set Dhcp4/lease-database/name "/tmp/kea-leases4.csv" -> config commit - - will change the default location of the lease file to /tmp/kea-leases4.csv. - - - The "persist" parameter controls whether the leases are written to disk. - It is strongly recommended that this parameter is set to "true" at all times - during the normal operation of the server - -
- -
- Database Configuration - - All leases issued by the server are stored in the lease database. Currently - there are 3 database backends available: MySQL, PostgreSQL and memfile. - - - The server comes with an in-memory database ("memfile") configured as the default - database. This is used for internal testing and is not supported. In addition, - it does not store lease information on disk: lease information will be lost if the - server is restarted. - - , and so the server must be configured to - access the correct database with the appropriate credentials. - - - - Database access information must be configured for the DHCPv4 server, even if - it has already been configured for the DHCPv6 server. The servers store their - information independently, so each server can use a separate - database or both servers can use the same database. - - - - Database configuration is controlled through the Dhcp4/lease-database parameters. - The type of the database must be set to "mysql", "postgresql" or "memfile": - -> config set Dhcp4/lease-database/type "mysql" - - Next, the name of the database is to hold the leases must be set: this is the - name used when the lease database was created (see - or ). - -> config set Dhcp4/lease-database/name "database-name" - - If the database is located on a different system to the DHCPv4 server, the - database host name must also be specified (although note that this configuration - may have a severe impact on server performance): - -> config set Dhcp4/lease-database/host "remote-host-name" - - The usual state of affairs will be to have the database on the same machine as the - DHCPv4 server. In this case, set the value to the empty string (this is the default): - -> config set Dhcp4/lease-database/host "" - - - - Finally, the credentials of the account under which the server will access the database - should be set: - -> config set Dhcp4/lease-database/user "user-name" -> config set Dhcp4/lease-database/password "password" - - If there is no password to the account, set the password to the empty string "". (This is also the default.) - - - The password is echoed when entered and is stored in clear text in the configuration - database. Improved password security will be added in a future version of Kea. - -
- -
- Interface selection - - When DHCPv4 server starts up, by default it will listen to the DHCP - traffic and respond to it on all interfaces detected during startup. - However, in many cases it is desired to configure the server to listen and - respond on selected interfaces only. The sample commands in this section - show how to make interface selection using bindctl. - - - The default configuration can be presented with the following command: - -> config show Dhcp4/interfaces -Dhcp4/interfaces[0] "*" string - An asterisk sign plays a role of the wildcard and means "listen on all interfaces". - - - In order to override the default configuration, the existing entry can be replaced - with the actual interface name: - -> config set Dhcp4/interfaces[0] eth1 -> config commit - Other interface names can be added on one-by-one basis: - -> config add Dhcp4/interfaces eth2 -> config commit - Configuration will now contain two interfaces which can be presented as follows: - -> config show Dhcp4/interfaces -Dhcp4/interfaces[0] "eth1" string -Dhcp4/interfaces[1] "eth2" string - When configuration gets committed, the server will start to listen on - eth1 and eth2 interfaces only. - - - It is possible to use wildcard interface name (asterisk) concurrently with explicit - interface names: - -> config add Dhcp4/interfaces * -> config commit - This will result in the following configuration: - -> config show Dhcp4/interfaces -Dhcp4/interfaces[0] "eth1" string -Dhcp4/interfaces[1] "eth2" string -Dhcp4/interfaces[2] "*" string - The presence of the wildcard name implies that server will listen on all interfaces. - In order to fall back to the previous configuration when server listens on eth1 and eth2: - -> config remove Dhcp4/interfaces[2] -> config commit - -
- -
- IPv4 Subnet Identifier - - Subnet identifier is a unique number associated with a particular subnet. - In principle, it is used to associate clients' leases with respective subnets. - When subnet identifier is not specified for a subnet being configured, it will - be automatically assigned by the configuration mechanism. The identifiers - are assigned from 1 and are monotonically increased for each subsequent - subnet: 1, 2, 3 .... - - - If there are multiple subnets configured with auto-generated identifiers and - one of them is removed, the subnet identifiers may be renumbered. For example: - if there are 4 subnets and 3rd is removed the last subnet will be assigned - identifier that the 3rd subnet had before removal. As a result, the leases - stored in the lease database for subnet 3 are now associated with the - subnet 4, which may have unexpected consequences. In the future it is planned - to implement the mechanism to preserve auto-generated subnet ids upon removal - of one of the subnets. Currently, the only remedy for this issue is to - manually specify the unique subnet identifier for each subnet. - - - The following configuration: - -> config add Dhcp4/subnet4 -> config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24" -> config set Dhcp4/subnet4[0]/id 1024 -> config commit - - will assign the arbitrary subnet identifier to the newly configured subnet. - This identifier will not change for this subnet until "id" parameter is - removed or set to 0. The value of 0 forces auto-generation of subnet - identifier. - -
- -
- Configuration of IPv4 Address Pools - - The essential role of DHCPv4 server is address assignment. The server - has to be configured with at least one subnet and one pool of dynamic - addresses to be managed. For example, assume that the server - is connected to a network segment that uses the 192.0.2.0/24 - prefix. The Administrator of that network has decided that addresses from range - 192.0.2.10 to 192.0.2.20 are going to be managed by the Dhcp4 - server. Such a configuration can be achieved in the following way: - -> config add Dhcp4/subnet4 -> config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24" -> config set Dhcp4/subnet4[0]/pool [ "192.0.2.10 - 192.0.2.20" ] -> config commit - Note that subnet is defined as a simple string, but the pool parameter - is actually a list of pools: for this reason, the pool definition is - enclosed in square brackets, even though only one range of addresses - is specified. - It is possible to define more than one pool in a - subnet: continuing the previous example, further assume that - 192.0.2.64/26 should be also be managed by the server. It could be written as - 192.0.2.64 to 192.0.2.127. Alternatively, it can be expressed more simply as - 192.0.2.64/26. Both formats are supported by Dhcp4 and can be mixed in the pool list. - For example, one could define the following pools: - -> config set Dhcp4/subnet4[0]/pool [ "192.0.2.10-192.0.2.20", "192.0.2.64/26" ] -> config commit - The number of pools is not limited, but for performance reasons it is recommended to - use as few as possible. Space and tabulations in pool definitions are ignored, so - spaces before and after hyphen are optional. They can be used to improve readability. - - - The server may be configured to serve more than one subnet. To add a second subnet, - use a command similar to the following: - -> config add Dhcp4/subnet4 -> config set Dhcp4/subnet4[1]/subnet "192.0.3.0/24" -> config set Dhcp4/subnet4[1]/pool [ "192.0.3.0/24" ] -> config commit - Arrays are counted from 0. subnet[0] refers to the subnet defined in the - previous example. The config add Dhcp4/subnet4 command adds - another (second) subnet. It can be referred to as - Dhcp4/subnet4[1]. In this example, we allow server to - dynamically assign all addresses available in the whole subnet. - - - When configuring a DHCPv4 server using prefix/length notation, please pay - attention to the boundary values. When specifying that the server should use - a given pool, it will be able to allocate also first (typically network - address) and the last (typically broadcast address) address from that pool. - In the aforementioned example of pool 192.0.3.0/24, both 192.0.3.0 and - 192.0.3.255 addresses may be assigned as well. This may be invalid in some - network configurations. If you want to avoid this, please use the "min-max" notation. - -
- -
- Standard DHCPv4 options - - One of the major features of DHCPv4 server is to provide configuration - options to clients. Although there are several options that require - special behavior, most options are sent by the server only if the client - explicitly requested them. The following example shows how to - configure DNS servers, which is one of the most frequently used - options. Options specified in this way are considered global and apply - to all configured subnets. - - -> config add Dhcp4/option-data -> config set Dhcp4/option-data[0]/name "domain-name-servers" -> config set Dhcp4/option-data[0]/code 6 -> config set Dhcp4/option-data[0]/space "dhcp4" -> config set Dhcp4/option-data[0]/csv-format true -> config set Dhcp4/option-data[0]/data "192.0.3.1, 192.0.3.2" -> config commit - - - - The first line creates new entry in option-data table. It - contains information on all global options that the server is - supposed to configure in all subnets. The second line specifies - option name. For a complete list of currently supported names, - see below. - The third line specifies option code, which must match one of the - values from that list. Line 4 specifies option space, which must always - be set to "dhcp4" as these are standard DHCPv4 options. For - other option spaces, including custom option spaces, see . The fifth line specifies the format in - which the data will be entered: use of CSV (comma - separated values) is recommended. The sixth line gives the actual value to - be sent to clients. Data is specified as a normal text, with - values separated by commas if more than one value is - allowed. - - - - Options can also be configured as hexadecimal values. If csv-format is - set to false, option data must be specified as a hex string. The - following commands configure the domain-name-servers option for all - subnets with the following addresses: 192.0.3.1 and 192.0.3.2. - Note that csv-format is set to false. - -> config add Dhcp4/option-data -> config set Dhcp4/option-data[0]/name "domain-name-servers" -> config set Dhcp4/option-data[0]/code 6 -> config set Dhcp4/option-data[0]/space "dhcp4" -> config set Dhcp4/option-data[0]/csv-format false -> config set Dhcp4/option-data[0]/data "C0 00 03 01 C0 00 03 02" -> config commit - - - - - It is possible to override options on a per-subnet basis. If - clients connected to most of your subnets are expected to get the - same values of a given option, you should use global options: you - can then override specific values for a small number of subnets. - On the other hand, if you use different values in each subnet, - it does not make sense to specify global option values - (Dhcp4/option-data), rather you should set only subnet-specific values - (Dhcp4/subnet[X]/option-data[Y]). - - - The following commands override the global - DNS servers option for a particular subnet, setting a single DNS - server with address 192.0.2.3. - -> config add Dhcp4/subnet4[0]/option-data -> config set Dhcp4/subnet4[0]/option-data[0]/name "domain-name-servers" -> config set Dhcp4/subnet4[0]/option-data[0]/code 6 -> config set Dhcp4/subnet4[0]/option-data[0]/space "dhcp4" -> config set Dhcp4/subnet4[0]/option-data[0]/csv-format true -> config set Dhcp4/subnet4[0]/option-data[0]/data "192.0.2.3" -> config commit - - - - In a future version of Kea, it will not be necessary to specify - the option code, space and csv-format fields as they will be set - automatically. - - - - The currently supported standard DHCPv4 options are - listed in - and . - The "Name" and "Code" - are the values that should be used as a name in the option-data - structures. "Type" designates the format of the data: the meanings of - the various types is given in . - - - Some options are designated as arrays, which means that more than one - value is allowed in such an option. For example the option time-servers - allows the specification of more than one IPv4 address, so allowing - clients to obtain the the addresses of multiple NTP servers. - - - - - The describes the configuration - syntax to create custom option definitions (formats). It is generally not - allowed to create custom definitions for standard options, even if the - definition being created matches the actual option format defined in the - RFCs. There is an exception from this rule for standard options for which - Kea does not provide a definition yet. In order to use such options, - a server administrator must create a definition as described in - in the 'dhcp4' option space. This - definition should match the option format described in the relevant - RFC but configuration mechanism would allow any option format as it has - no means to validate it at the moment. - - - - - List of standard DHCPv4 options - - - - - - - - Name - Code - Type - Array? - - - -subnet-mask1ipv4-addressfalse -time-offset2int32false -routers3ipv4-addresstrue -time-servers4ipv4-addresstrue -name-servers5ipv4-addressfalse -domain-name-servers6ipv4-addresstrue -log-servers7ipv4-addresstrue -cookie-servers8ipv4-addresstrue -lpr-servers9ipv4-addresstrue -impress-servers10ipv4-addresstrue -resource-location-servers11ipv4-addresstrue -host-name12stringfalse -boot-size13uint16false -merit-dump14stringfalse -domain-name15fqdnfalse -swap-server16ipv4-addressfalse -root-path17stringfalse -extensions-path18stringfalse -ip-forwarding19booleanfalse -non-local-source-routing20booleanfalse -policy-filter21ipv4-addresstrue -max-dgram-reassembly22uint16false -default-ip-ttl23uint8false -path-mtu-aging-timeout24uint32false -path-mtu-plateau-table25uint16true -interface-mtu26uint16false -all-subnets-local27booleanfalse -broadcast-address28ipv4-addressfalse -perform-mask-discovery29booleanfalse -mask-supplier30booleanfalse -router-discovery31booleanfalse -router-solicitation-address32ipv4-addressfalse -static-routes33ipv4-addresstrue -trailer-encapsulation34booleanfalse -arp-cache-timeout35uint32false -ieee802-3-encapsulation36booleanfalse -default-tcp-ttl37uint8false -tcp-keepalive-internal38uint32false -tcp-keepalive-garbage39booleanfalse - - - -
- - - - - List of standard DHCPv4 options (continued) - - - - - - - - Name - Code - Type - Array? - - - - -nis-domain40stringfalse -nis-servers41ipv4-addresstrue -ntp-servers42ipv4-addresstrue -vendor-encapsulated-options43emptyfalse -netbios-name-servers44ipv4-addresstrue -netbios-dd-server45ipv4-addresstrue -netbios-node-type46uint8false -netbios-scope47stringfalse -font-servers48ipv4-addresstrue -x-display-manager49ipv4-addresstrue -dhcp-requested-address50ipv4-addressfalse - -dhcp-option-overload52uint8false - -dhcp-message56stringfalse -dhcp-max-message-size57uint16false - -vendor-class-identifier60binaryfalse - -nwip-domain-name62stringfalse -nwip-suboptions63binaryfalse -tftp-server-name66stringfalse -boot-file-name67stringfalse -user-class77binaryfalse -fqdn81recordfalse -dhcp-agent-options82emptyfalse -authenticate90binaryfalse -client-last-transaction-time91uint32false -associated-ip92ipv4-addresstrue -subnet-selection118ipv4-addressfalse -domain-search119binaryfalse -vivco-suboptions124binaryfalse -vivso-suboptions125binaryfalse - - -
- - - - - List of standard DHCP option types - - - - - NameMeaning - - - binaryAn arbitrary string of bytes, specified as a set of hexadecimal digits. - booleanBoolean value with allowed values true or false - emptyNo value, data is carried in suboptions - fqdnFully qualified domain name (e.g. www.example.com) - ipv4-addressIPv4 address in the usual dotted-decimal notation (e.g. 192.0.2.1) - ipv6-addressIPv6 address in the usual colon notation (e.g. 2001:db8::1) - recordStructured data that may comprise any types (except "record" and "empty") - stringAny text - uint88 bit unsigned integer with allowed values 0 to 255 - uint1616 bit unsinged integer with allowed values 0 to 65535 - uint3232 bit unsigned integer with allowed values 0 to 4294967295 - - -
- -
- -
- Custom DHCPv4 options - It is also possible to define options other than the standard ones. - Assume that we want to define a new DHCPv4 option called "foo" which will have - code 222 and will convey a single unsigned 32 bit integer value. We can define - such an option by using the following commands: - -> config add Dhcp4/option-def -> config set Dhcp4/option-def[0]/name "foo" -> config set Dhcp4/option-def[0]/code 222 -> config set Dhcp4/option-def[0]/type "uint32" -> config set Dhcp4/option-def[0]/array false -> config set Dhcp4/option-def[0]/record-types "" -> config set Dhcp4/option-def[0]/space "dhcp4" -> config set Dhcp4/option-def[0]/encapsulate "" -> config commit - The "false" value of the "array" parameter determines that the option - does NOT comprise an array of "uint32" values but rather a single value. - Two other parameters have been left blank: "record-types" and "encapsulate". - The former specifies the comma separated list of option data fields if the - option comprises a record of data fields. The "record-fields" value should - be non-empty if the "type" is set to "record". Otherwise it must be left - blank. The latter parameter specifies the name of the option space being - encapsulated by the particular option. If the particular option does not - encapsulate any option space it should be left blank. - Note that the above set of comments define the format of the new option and do not - set its values. - - - - In the current release the default values are not propagated to the - parser when the new configuration is being set. Therefore, all - parameters must be specified at all times, even if their values are - left blank. - - - - Once the new option format is defined, its value is set - in the same way as for a standard option. For example the following - commands set a global value that applies to all subnets. - -> config add Dhcp4/option-data -> config set Dhcp4/option-data[0]/name "foo" -> config set Dhcp4/option-data[0]/code 222 -> config set Dhcp4/option-data[0]/space "dhcp4" -> config set Dhcp4/option-data[0]/csv-format true -> config set Dhcp4/option-data[0]/data "12345" -> config commit - - - New options can take more complex forms than simple use of - primitives (uint8, string, ipv4-address etc): it is possible to - define an option comprising a number of existing primitives. - - Assume we want to define a new option that will consist of - an IPv4 address, followed by unsigned 16 bit integer, followed by - a boolean value, followed by a text string. Such an option could - be defined in the following way: - -> config add Dhcp4/option-def -> config set Dhcp4/option-def[0]/name "bar" -> config set Dhcp4/option-def[0]/code 223 -> config set Dhcp4/option-def[0]/space "dhcp4" -> config set Dhcp4/option-def[0]/type "record" -> config set Dhcp4/option-def[0]/array false -> config set Dhcp4/option-def[0]/record-types "ipv4-address, uint16, boolean, string" -> config set Dhcp4/option-def[0]/encapsulate "" - - The "type" is set to "record" to indicate that the option contains - multiple values of different types. These types are given as a comma-separated - list in the "record-types" field and should be those listed in . - - - The values of the option are set as follows: - -> config add Dhcp4/option-data -> config set Dhcp4/option-data[0]/name "bar" -> config set Dhcp4/option-data[0]/space "dhcp4" -> config set Dhcp4/option-data[0]/code 223 -> config set Dhcp4/option-data[0]/csv-format true -> config set Dhcp4/option-data[0]/data "192.0.2.100, 123, true, Hello World" -> config commit - "csv-format" is set "true" to indicate that the "data" field comprises a command-separated - list of values. The values in the "data" must correspond to the types set in - the "record-types" field of the option definition. - - - - It is recommended that boolean values are specified using "true" and "false" - strings. This helps to prevent errors when typing multiple comma separated - values, as it make it easier to identify the type of the value being typed, - and compare it with the order of data fields. Nevertheless, it is possible - to use integer values: "1" and "0", instead of "true" and "false" - accordingly. If other integer value is specified, the configuration is - rejected. - - -
- -
- DHCPv4 vendor specific options - - Currently there are three option spaces defined: dhcp4 (to - be used in DHCPv4 daemon) and dhcp6 (for the DHCPv6 daemon); there - is also vendor-encapsulated-options-space, which is empty by default, but options - can be defined in it. Those options are called vendor-specific - information options. The following examples show how to define - an option "foo" with code 1 that consists of an IPv4 address, an - unsigned 16 bit integer and a string. The "foo" option is conveyed - in a vendor specific information option. - - - The first step is to define the format of the option: - -> config add Dhcp4/option-def -> config set Dhcp4/option-def[0]/name "foo" -> config set Dhcp4/option-def[0]/code 1 -> config set Dhcp4/option-def[0]/space "vendor-encapsulated-options-space" -> config set Dhcp4/option-def[0]/type "record" -> config set Dhcp4/option-def[0]/array false -> config set Dhcp4/option-def[0]/record-types "ipv4-address, uint16, string" -> config set Dhcp4/option-def[0]/encapsulates "" -> config commit - - (Note that the option space is set to "vendor-encapsulated-options-space".) - Once the option format is defined, the next step is to define actual values - for that option: - -> config add Dhcp4/option-data -> config set Dhcp4/option-data[0]/name "foo" -> config set Dhcp4/option-data[0]/space "vendor-encapsulated-options-space" -> config set Dhcp4/option-data[0]/code 1 -> config set Dhcp4/option-data[0]/csv-format true -> config set Dhcp4/option-data[0]/data "192.0.2.3, 123, Hello World" -> config commit - We also set up a dummy value for vendor-opts, the option that conveys our sub-option "foo". - This is required else the option will not be included in messages sent to the client. - -> config add Dhcp4/option-data -> config set Dhcp4/option-data[1]/name "vendor-encapsulated-options" -> config set Dhcp4/option-data[1]/space "dhcp4" -> config set Dhcp4/option-data[1]/code 43 -> config set Dhcp4/option-data[1]/csv-format false -> config set Dhcp4/option-data[1]/data "" -> config commit - - - - - With this version of Kea, the "vendor-encapsulated-options" option - must be specified in the configuration although it has no configurable - parameters. If it is not specified, the server will assume that it is - not configured and will not send it to a client. In the future there - will be no need to include this option in the configuration. - - - -
- -
- - Nested DHCPv4 options (custom option spaces) - It is sometimes useful to define completely new option - space. This is the case when user creates new option in the - standard option space ("dhcp4 or "dhcp6") and wants this option - to convey sub-options. Thanks to being in the separate space, - sub-option codes will have a separate numbering scheme and may - overlap with codes of standard options. - - Note that creation of a new option space when defining - sub-options for a standard option is not required, because it is - created by default if the standard option is meant to convey any - sub-options (see ). - - - Assume that we want to have a DHCPv4 option called "container" with - code 222 that conveys two sub-options with codes 1 and 2. - First we need to define the new sub-options: - -> config add Dhcp4/option-def -> config set Dhcp4/option-def[0]/name "subopt1" -> config set Dhcp4/option-def[0]/code 1 -> config set Dhcp4/option-def[0]/space "isc" -> config set Dhcp4/option-def[0]/type "ipv4-address" -> config set Dhcp4/option-def[0]/record-types "" -> config set Dhcp4/option-def[0]/array false -> config set Dhcp4/option-def[0]/encapsulate "" -> config commit - -> config add Dhcp4/option-def -> config set Dhcp4/option-def[1]/name "subopt2" -> config set Dhcp4/option-def[1]/code 2 -> config set Dhcp4/option-def[1]/space "isc" -> config set Dhcp4/option-def[1]/type "string" -> config set Dhcp4/option-def[1]/record-types "" -> config set Dhcp4/option-def[1]/array false -> config set Dhcp4/option-def[1]/encapsulate "" -> config commit - - Note that we have defined the options to belong to a new option space - (in this case, "isc"). - - - The next step is to define a regular DHCPv4 option with our desired - code and specify that it should include options from the new option space: - -> add Dhcp4/option-def -> set Dhcp4/option-def[2]/name "container" -> set Dhcp4/option-def[2]/code 222 -> set Dhcp4/option-def[2]/space "dhcp4" -> set Dhcp4/option-def[2]/type "empty" -> set Dhcp4/option-def[2]/array false -> set Dhcp4/option-def[2]/record-types "" -> set Dhcp4/option-def[2]/encapsulate "isc" -> commit - - The name of the option space in which the sub-options are defined - is set in the "encapsulate" field. The "type" field is set to "empty" - to indicate that this option does not carry any data other than - sub-options. - - - Finally, we can set values for the new options: - -> config add Dhcp4/option-data -> config set Dhcp4/option-data[0]/name "subopt1" -> config set Dhcp4/option-data[0]/space "isc" -> config set Dhcp4/option-data[0]/code 1 -> config set Dhcp4/option-data[0]/csv-format true -> config set Dhcp4/option-data[0]/data "192.0.2.3" -> config commit - -> config add Dhcp4/option-data -> config set Dhcp4/option-data[1]/name "subopt2" -> config set Dhcp4/option-data[1]/space "isc" -> config set Dhcp4/option-data[1]/code 2 -> config set Dhcp4/option-data[1]/csv-format true -> config set Dhcp4/option-data[1]/data "Hello world" -> config commit - -> config add Dhcp4/option-data -> config set Dhcp4/option-data[2]/name "container" -> config set Dhcp4/option-data[2]/space "dhcp4" -> config set Dhcp4/option-data[2]/code 222 -> config set Dhcp4/option-data[2]/csv-format true -> config set Dhcp4/option-data[2]/data "" -> config commit - - Even though the "container" option does not carry any data except - sub-options, the "data" field must be explicitly set to an empty value. - This is required because in the current version of BIND 10 DHCP, the - default configuration values are not propagated to the configuration parsers: - if the "data" is not set the parser will assume that this - parameter is not specified and an error will be reported. - - Note that it is possible to create an option which carries some data - in addition to the sub-options defined in the encapsulated option space. For example, - if the "container" option from the previous example was required to carry an uint16 - value as well as the sub-options, the "type" value would have to be set to "uint16" in - the option definition. (Such an option would then have the following - data structure: DHCP header, uint16 value, sub-options.) The value specified - with the "data" parameter - which should be a valid integer enclosed in quotes, - e.g. "123" - would then be assigned to the uint16 field in the "container" option. - -
- -
- Client Classification in DHCPv4 - - - DHCPv4 server has been extended to support limited client classification. - Although the current capability is modest, it is expected to be expanded - in the future. It is envisaged that the majority of client classification - extensions will be using hooks extensions. - - - In certain cases it is useful to differentiate between different - types of clients and treat them differently. The process of doing - classification is conducted in two steps. The first step is to assess - incoming packet and assign it to zero or more classes. This classification - is currently simple, but is expected to grow in capability soon. Currently - the server checks whether incoming packet has vendor class identifier - option (60). If it has, content of that option is prepended with - "VENDOR_CLASS_" then is interpreted as a class. For example, - modern cable modems will send this option with value "docsis3.0" - and as a result the packet will belong to class "VENDOR_CLASS_docsis3.0". - - - It is envisaged that the client classification will be used for changing - behavior of almost any part of the DHCP message processing, including assigning - leases from different pools, assigning different option (or different values of - the same options) etc. For now, there are only two mechanisms that are taking - advantage of client classification: specific processing for cable modems and - subnet selection. - - - For clients that belong to the VENDOR_CLASS_docsis3.0 class, the siaddr - field is set to the value of next-server (if specified in a subnet). If - there is boot-file-name option specified, its value is also set in the - file field in the DHCPv4 packet. For eRouter1.0 class, the siaddr is - always set to 0.0.0.0. That capability is expected to be moved to - external hook library that will be dedicated to cable modems. - - - - Kea can be instructed to limit access to given subnets based on class information. - This is particularly useful for cases where two types of devices share the - same link and are expected to be served from two different subnets. The - primary use case for such a scenario is cable networks. There are two - classes of devices: cable modem itself, which should be handled a lease - from subnet A and all other devices behind modems that should get a lease - from subnet B. That segregation is essential to prevent overly curious - users from playing with their cable modems. For details on how to set up - class restrictions on subnets, see . - - -
- -
- Limiting access to IPv4 subnet to certain classes - - In certain cases it beneficial to restrict access to certain subnets - only to clients that belong to a given subnet. For details on client - classes, see . This is an - extension of a previous example from . - Let's assume that the server is connected to a network segment that uses - the 192.0.2.0/24 prefix. The Administrator of that network has decided - that addresses from range 192.0.2.10 to 192.0.2.20 are going to be - managed by the Dhcp4 server. Only clients belonging to client class - VENDOR_CLASS_docsis3.0 are allowed to use this subnet. Such a - configuration can be achieved in the following way: - -> config add Dhcp4/subnet4 -> config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24" -> config set Dhcp4/subnet4[0]/pool [ "192.0.2.10 - 192.0.2.20" ] -> config set Dhcp4/subnet4[0]/client-class "VENDOR_CLASS_docsis3.0" -> config commit - - - - Care should be taken with client classification as it is easy to prevent - clients that do not meet class criteria to be denied any service altogether. - -
-
- Configuring DHCPv4 for DDNS - - As mentioned earlier, b10-dhcp4 can be configured to generate requests to the - DHCP-DDNS server to update DNS entries. These requests are known as - NameChangeRequests or NCRs. Each NCR contains the following information: - - - Whether it is a request to add (update) or remove DNS entries - - - Whether the change requests forward DNS updates (A records), reverse - DNS updates (PTR records), or both. - - - The FQDN, lease address, and DHCID - - - The parameters for controlling the generation of NCRs for submission to D2 - are contained in the "dhcp-ddns" section of the b10-dhcp4 server - configuration. The default values for this section appears as follows: - -> config show Dhcp4/dhcp-ddns -Dhcp4/dhcp-ddns/enable-updates true boolean -Dhcp4/dhcp-ddns/server-ip "127.0.0.1" string -Dhcp4/dhcp-ddns/server-port 53001 integer -Dhcp4/dhcp-ddns/sender-ip "" string -Dhcp4/dhcp-ddns/sender-port 0 integer -Dhcp4/dhcp-ddns/max-queue-size 1024 integer -Dhcp4/dhcp-ddns/ncr-protocol "UDP" string -Dhcp4/dhcp-ddns/ncr-format "JSON" string -Dhcp4/dhcp-ddns/override-no-update false boolean -Dhcp4/dhcp-ddns/override-client-update false boolean -Dhcp4/dhcp-ddns/replace-client-name false boolean -Dhcp4/dhcp-ddns/generated-prefix "myhost" string -Dhcp4/dhcp-ddns/qualifying-suffix "example.com" string - - - - The "enable-updates" parameter determines whether or not b10-dhcp4 will - generate NCRs. By default, this value is false hence DDNS updates are - disabled. To enable DDNS updates set this value to true: - - -> config set Dhcp4/dhcp-ddns/enable-updates true -> config commit - -
- DHCP-DDNS Server Connectivity - - In order for NCRs to reach the D2 server, b10-dhcp4 must be able - to communicate with it. b10-dhcp4 uses the following configuration - parameters to control how it communications with D2: - - - server-ip - 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. - - - server-port - port on which D2 listens for requests. The default value - is 53001. - - - sender-ip - IP address which b10-dhcp4 should use to send requests to D2. - The default value is blank which instructs b10-dhcp4 to select a suitable - address. - - - sender-port - port which b10-dhcp4 should use to send requests to D2. The - default value of 0 instructs b10-dhcp4 to select suitable port. - - - ncr-format - Socket protocol use when sending requests to D2. Currently - only UDP is supported. TCP may be available in an upcoming release. - - - 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. - - - max-queue-size - maximum number of requests allowed to queue waiting to - be sent to D2. This value guards against requests accumulating - uncontrollably if they are being generated faster than they can be - delivered. If the number of requests queued for transmission reaches - this value, DDNS updating will be turned off until the queue backlog has - been sufficiently reduced. The intent is allow the b10-dhcp4 server to - continue lease operations. The default value is 1024. - - - By default, D2 is assumed to running on the same machine as b10-dhcp4, and - all of the default values mentioned above should be sufficient. - If, however, D2 has been configured to listen on a different address or - port, these values must altered accordingly. For example, if D2 has been - configured to listen on 198.162.1.10 port 900, the following commands - would be required: - -> config set Dhcp4/dhcp-ddns/server-ip "198.162.1.10" -> config set Dhcp4/dhcp-ddns/server-port 900 -> config commit - - -
-
- When does the b10-dhcp4 server generate DDNS requests? - b10-dhcp4 follows the behavior prescribed for DHCP servers in RFC 4702. - It is important to keep in mind that b10-dhcp4 provides the initial decision - making of when and what to update and forwards that information to D2 in - the form of NCRs. Carrying out the actual DNS updates and dealing with - such things as conflict resolution are the purview of D2 (). - - This section describes when b10-dhcp4 will generate NCRs and the - configuration parameters that can be used to influence this decision. - It assumes that the "enable-updates" parameter is true. - - - In general, b10-dhcp4 will generate DDNS update requests when: - - - A new lease is granted in response to a DHCP REQUEST - - - An existing lease is renewed but the FQDN associated with it has - changed. - - - An existing lease is released in response to a DHCP RELEASE - - - In the second case, lease renewal, two DDNS requests will be issued: one - request to remove entries for the previous FQDN and a second request to - add entries for the new FQDN. In the last case, a lease release, a - single DDNS request to remove its entries will be made. The decision - making involved when granting a new lease (the first case) is more - involved and is discussed next. - - - When a new lease is granted, b10-dhcp4 will generate a DDNS - update request if the DHCP REQUEST contains either the FQDN option - (code 81) or the Host Name option (code 12). If both are present, - the server will use the FQDN option. By default b10-dhcp4 - will respect the FQDN N and S flags specified by the client as shown - in the following table: - - - Default FQDN Flag Behavior - - - - - - - - Client Flags:N-S - Client Intent - Server Response - Server Flags:N-S-O - - - - - 0-0 - - Client wants to do forward updates, server should do reverse updates - - Server generates reverse-only request - 1-0-0 - - - 0-1 - Server should do both forward and reverse updates - Server generates request to update both directions - 0-1-0 - - - 1-0 - Client wants no updates done - Server does not generate a request - 1-0-0 - - - -
- - The first row in the table above represents "client delegation". Here - the DHCP client states that it intends to do the forward DNS updates and - the server should do the reverse updates. By default, b10-dhcp4 will honor - the client's wishes and generate a DDNS request to D2 to update only - reverse DNS data. The parameter, "override-client-update", can be used - to instruct the server to override client delegation requests. When - this parameter is true, b10-dhcp4 will disregard requests for client - delegation and generate a DDNS request to update both forward and - reverse DNS data. In this case, the N-S-O flags in the server's - response to the client will be 0-1-1 respectively. - - - (Note that the flag combination N=1, S=1 is prohibited according to - RFC 4702. If such a combination is received from the client, the packet - will be dropped by the b10-dhcp4.) - - - To override client delegation, issue the following commands: - - -> config set Dhcp4/dhcp-ddns/override-client-update true -> config commit - - - The third row in the table above describes the case in which the client - requests that no DNS updates be done. The parameter, "override-no-update", - can be used to instruct the server to disregard the client's wishes. When - this parameter is true, b10-dhcp4 will generate DDNS update request to D2 - even if the client requests no updates be done. The N-S-O flags in the - server's response to the client will be 0-1-1. - - - To override client delegation, issue the following commands: - - -> config set Dhcp4/dhcp-ddns/override-no-update true -> config commit - - - b10-dhcp4 will always generate DDNS update requests if the client request - only contains the Host Name option. In addition it will include an FQDN - option in the response to the client with the FQDN N-S-O flags set to - 0-1-0 respectively. The domain name portion of the FQDN option will be - the name submitted to D2 in the DDNS update request. - -
-
- b10-dhcp4 name generation for DDNS update requests - Each NameChangeRequest must of course include the fully qualified domain - name whose DNS entries are to be affected. b10-dhcp4 can be configured to - supply a portion or all of that name based upon what it receives from - the client in the DHCP REQUEST. - - The rules for determining the FQDN option are as follows: - - - If configured to do, so ignore the REQUEST contents and generate a - FQDN using a configurable prefix and suffix. - - - If the REQUEST contains the client FQDN option, the candidate - name is taken from there, otherwise it is taken from the Host Name option. - The candiate name may then be modified: - - - If the candidate name is a fully qualified domain name, use it. - - - If the candidate name is a partial (i.e. unqualified) name then - add a configurable suffix to the name and use the result as the FQDN. - - - If the candidate name is a empty, generate a FQDN using a - configurable prefix and suffix. - - - - - To instruct b10-dhcp4 to always generate the FQDN for a client, set the - parameter "replace-client-name" to true as follows: - - -> config set Dhcp4/dhcp-ddns/replace-client-name true -> config commit - - - The prefix used in the generation of a FQDN is specified by the - "generated-prefix" parameter. The default value is "myhost". To alter - its value simply set it to the desired string: - - -> config set Dhcp4/dhcp-ddns/generated-prefix "another.host" -> config commit - - - The suffix used when generating a FQDN or when qualifying a partial - name is specified by the "qualifying-suffix" parameter. The default - value is "example.com". To alter its value simply set it to the desired - string: - - -> config set Dhcp4/dhcp-ddns/generated-prefix "our.net" -> config commit - -
- - When generating a name, b10-dhcp4 will construct name of the format: - - - [generated-prefix]-[address-text].[qualifying-suffix]. - - - where address-text is simply the lease IP address converted to a - hyphenated string. For example, if lease address is 172.16.1.10 and - assuming default values for generated-prefix and qualifying-suffix, the - generated FQDN would be: - - - myhost-172-16-1-10.example.com. - -
- -
- -
- Server Identifier in DHCPv4 - - The DHCPv4 protocol uses a "server identifier" for clients to be able - to discriminate between several servers present on the same link: this - value is an IPv4 address of the server. The server chooses the IPv4 address - of the interface on which the message from the client (or relay) has been - received. A single server instance will use multiple server identifiers - if it is receiving queries on multiple interfaces. - - - Currently there is no mechanism to override the default server identifiers - by an administrator. In the future, the configuration mechanism will be used - to specify the custom server identifier. - -
- - -
- Next server (siaddr) - In some cases, clients want to obtain configuration from the TFTP server. - Although there is a dedicated option for it, some devices may use siaddr field - in the DHCPv4 packet for that purpose. That specific field can be configured - using next-server directive. It is possible to define it in global scope or - for a given subnet only. If both are defined, subnet value takes precedence. - The value in subnet can be set to 0.0.0.0, which means that next-server should - not be sent. It may also be set to empty string, which means the same as if - it was not defined at all - use global value. - - - -> config add Dhcp4/next-server -> config set Dhcp4/next-server "192.0.2.123" -> config commit - -> config add Dhcp4/subnet[0]/next-server -> config set Dhcp4/subnet[0]/next-server "192.0.2.234" -> config commit - - -
- -
- Echoing client-id (RFC6842) - Original DHCPv4 spec (RFC2131) states that the DHCPv4 - server must not send back client-id options when responding to - clients. However, in some cases that confused clients that did - not have MAC address or client-id. See RFC6842 for details. That - behavior has changed with the publication of RFC6842 which - updated RFC2131. That update now states that the server must - send client-id if client sent it. That is the default behaviour - that Kea offers. However, in some cases older devices that do - not support RFC6842 may refuse to accept responses that include - client-id option. To enable backward compatibility, an optional - configuration parameter has been introduced. To configure it, - use the following commands: - - -> config add Dhcp4/echo-client-id -> config set Dhcp4/echo-client-id False -> config commit - - -
- -
- How DHCPv4 server selects subnet for a client - - The DHCPv4 server differentiates between the directly connected clients, - clients trying to renew leases and clients sending their messages through - relays. For the directly connected clients the server will check the - configuration of the interface on which the message has been received, and - if the server configuration doesn't match any configured subnet the - message is discarded. - Assuming that the server's interface is configured with the 192.0.2.3 - IPv4 address, the server will only process messages received through - this interface from the directly connected client, if there is a subnet - configured, to which this IPv4 address belongs, e.g. 192.0.2.0/24. - The server will use this subnet to assign IPv4 address for the client. - - - The rule above does not apply when the client unicasts its message, i.e. - is trying to renew its lease. Such message is accepted through any - interface. The renewing client sets ciaddr to the currently used IPv4 - address. The server uses this address to select the subnet for the client - (in particular, to extend the lease using this address). - - - If the message is relayed it is accepted through any interface. The giaddr - set by the relay agent is used to select the subnet for the client. - - - It is also possible to specify a relay IPv4 address for a given subnet. It - can be used to match incoming packets into a subnet in uncommon configurations, - e.g. shared subnets. See for details. - - - The subnet selection mechanism described in this section is based - on the assumption that client classification is not used. The classification - mechanism alters the way in which subnet is selected for the client, - depending on the classes that the client belongs to. - -
- -
- Using specific relay agent for a subnet - - The relay has to have an interface connected to the link on which - the clients are being configured. Typically the relay has an IPv4 - address configured on that interface that belongs to the subnet that - the server will assign addresses from. In such typical case, the - server is able to use IPv4 address inserted by the relay (in GIADDR - field of the DHCPv4 packet) to select appropriate subnet. - - - However, that is not always the case. In certain uncommon, but - valid deployments, the relay address may not match the subnet. This - usually means that there is more than one subnet allocated for a given - link. Two most common examples where this is the case are long lasting - network renumbering (where both old and new address space is still being - used) and a cable network. In a cable network both cable modems and the - devices behind them are physically connected to the same link, yet - they use distinct addressing. In such case, the DHCPv4 server needs - additional information (IPv4 address of the relay) to properly select - an appropriate subnet. - - - The following example assumes that there is a subnet 192.0.2.0/24 - that is accessible via relay that uses 10.0.0.1 as its IPv4 address. - The server will be able to select this subnet for any incoming packets - that came from a relay that has an address in 192.0.2.0/24 subnet. - It will also select that subnet for a relay with address 10.0.0.1. - -> config add Dhcp4/subnet4 -> config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24" -> config set Dhcp4/subnet4[0]/pool [ "192.0.2.10 - 192.0.2.20" ] -> config set Dhcp4/subnet4[0]/relay/ip-address "10.0.0.1" -> config commit - - -
- -
- Segregating IPv4 clients in a cable network - - In certain cases, it is useful to mix relay address information, - introduced in with client - classification, explained in . - One specific example is cable network, where typically modems - get addresses from a different subnet than all devices connected - behind them. - - - Let's assume that there is one CMTS (Cable Modem Termination System) - with one CM MAC (a physical link that modems are connected to). - We want the modems to get addresses from the 10.1.1.0/24 subnet, while - everything connected behind modems should get addresses from another - subnet (192.0.2.0/24). The CMTS that acts as a relay an uses address - 10.1.1.1. The following configuration can serve that configuration: - -> config add Dhcp4/subnet4 -> config set Dhcp4/subnet4[0]/subnet "10.1.1.0/24" -> config set Dhcp4/subnet4[0]/pool [ "10.1.1.2 - 10.1.1.20" ] -> config set Dhcp4/subnet4[0]/client-class "docsis3.0" -> config set Dhcp4/subnet4[0]/relay/ip-address "10.1.1.1" -> config add Dhcp4/subnet4 -> config set Dhcp4/subnet4[1]/subnet "192.0.2.0/24" -> config set Dhcp4/subnet4[1]/pool [ "192.0.2.10 - 192.0.2.20" ] -> config set Dhcp4/subnet4[1]/relay/ip-address "10.1.1.1" -> config commit - -
- -
- Supported Standards - The following standards and draft standards are currently - supported: - - - RFC 2131: Supported messages are DISCOVER, OFFER, - REQUEST, RELEASE, ACK, and NAK. - - - RFC 2132: - Supported options are: PAD (0), - END(255), Message Type(53), DHCP Server Identifier (54), - Domain Name (15), DNS Servers (6), IP Address Lease Time - (51), Subnet mask (1), and Routers (3). - - - RFC 3046: - Relay Agent Information option is supported. - - - RFC 3925: - Vendor-Identifying Vendor Class and Vendor-Identifying Vendor-Specific - Information option are supported. - - - RFC 6842: - Server by default sends back client-id option. That capability may be - disabled. See for details. - - - -
- -
- DHCPv4 Server Limitations - These are the current limitations of the DHCPv4 server - software. Most of them are reflections of the current stage of - development and should be treated as not implemented - yet, rather than actual limitations. - - - - Removal of a subnet during server reconfiguration may cause renumbering - of auto-generated subnet identifiers, as described in section - . - - - - - BOOTP (RFC 951) - is not supported. - - - - Raw sockets operation is working on Linux - only. See for details. - - - The DHCPv4 server does not verify that - assigned address is unused. According to RFC 2131, the - allocating server should verify that address is not used by - sending ICMP echo request. - - - Address duplication report (DECLINE) is not supported yet. - - - - The server doesn't act upon expired leases. In particular, - when a lease expires, the server doesn't request the removal - of the DNS records associated with it. - - - -
- - - - - - - The DHCPv6 Server - -
- Starting and Stopping the DHCPv6 Server - - - b10-dhcp6 is the Kea DHCPv6 server and is configured - through the bindctl program. - - - After starting bind10 and starting bindctl, the first step - in configuring the server is to add b10-dhcp6 to the list of running services. - -> config add Init/components b10-dhcp6 -> config set Init/components/b10-dhcp6/kind dispensable -> config commit - - - - To remove b10-dhcp6 from the set of running services, - the b10-dhcp6 is removed from list of Init components: - -> config remove Init/components b10-dhcp6 -> config commit - - - - - Note that the server was only removed from the list, so BIND10 will not - restart it, but the server itself is still running. Hence it is usually - desired to stop it: - -> Dhcp6 shutdown - - - - - During start-up the server will detect available network interfaces - and will attempt to open UDP sockets on all interfaces that - are up, running, are not loopback, are multicast-capable, and - have IPv6 address assigned. It will then listen to incoming traffic. - - - -
- -
- DHCPv6 Server Configuration - - Once the server has been started, it can be configured. To view the - current configuration, use the following command in bindctl: - > config show Dhcp6 - When starting the Dhcp6 daemon for the first time, the default configuration - will be available. It will look similar to this: - -> config show Dhcp6 -Dhcp6/hooks-libraries [] list (default) -Dhcp6/interfaces/ list (default) -Dhcp6/renew-timer 1000 integer (default) -Dhcp6/rebind-timer 2000 integer (default) -Dhcp6/preferred-lifetime 3000 integer (default) -Dhcp6/valid-lifetime 4000 integer (default) -Dhcp6/option-def [] list (default) -Dhcp6/option-data [] list (default) -Dhcp6/lease-database/type "" string (default) -Dhcp6/lease-database/name "" string (default) -Dhcp6/lease-database/user "" string (default) -Dhcp6/lease-database/host "" string (default) -Dhcp6/lease-database/password "" string (default) -Dhcp6/subnet6/ list -Dhcp6/dhcp-ddns/enable-updates true boolean -Dhcp6/dhcp-ddns/server-ip "127.0.0.1" string -Dhcp6/dhcp-ddns/server-port 53001 integer -Dhcp6/dhcp-ddns/sender-ip "" string -Dhcp6/dhcp-ddns/sender-port 0 integer -Dhcp6/dhcp-ddns/max-queue-size 1024 integer -Dhcp6/dhcp-ddns/ncr-protocol "UDP" string -Dhcp6/dhcp-ddns/ncr-format "JSON" string -Dhcp6/dhcp-ddns/always-include-fqdn false boolean -Dhcp6/dhcp-ddns/override-no-update false boolean -Dhcp6/dhcp-ddns/override-client-update false boolean -Dhcp6/dhcp-ddns/replace-client-name false boolean -Dhcp6/dhcp-ddns/generated-prefix "myhost" string -Dhcp6/dhcp-ddns/qualifying-suffix "example.com" string - - - - To change one of the parameters, simply follow - the usual bindctl procedure. For example, to make the - leases longer, change their valid-lifetime parameter: - -> config set Dhcp6/valid-lifetime 7200 -> config commit - Most Dhcp6 parameters are of global scope - and apply to all defined subnets, unless they are overridden on a - per-subnet basis. - - - - With this version of Kea, there are a number of known limitations - and problems in the DHCPv6 server. See . - - - -
- Default storage for leases - - The server is able to store lease data in different repositories. Larger deployments - may elect to store leases in a database. - describes one way to do it. - By default, the server will use a CSV file rather than a database to store - lease information. One of the advantages of using a file is that it eliminates - dependency on third party database software. - - - The configuration of the file backend (Memfile) - is controlled through the Dhcp6/lease-database parameters. When default - parameters are left, the Memfile backend will write leases to a disk in the - [bind10-install-dir]/var/bind10/kea-leases6.csv. - - - It is possible to alter the default location of the lease file. The following - configuration: - -> config set Dhcp4/lease-database/type "memfile" -> config set Dhcp4/lease-database/persist true -> config set Dhcp4/lease-database/leasefile "/tmp/kea-leases6.csv" -> config commit - - will change the default location of the lease file to /tmp/kea-leases6.csv. - - - The "persist" parameter controls whether the leases are written to disk. - It is strongly recommended that this parameter is set to "true" at all times - during the normal operation of the server. - -
- -
- Database Configuration - - All leases issued by the server are stored in the lease database. Currently - there are 3 database backends available: MySQL, PostgreSQL and memfile. - - - The server comes with an in-memory database ("memfile") configured as the default - database. This is used for internal testing and is not supported. In addition, - it does not store lease information on disk: lease information will be lost if the - server is restarted. - - , and so the server must be configured to - access the correct database with the appropriate credentials. - - - - Database access information must be configured for the DHCPv6 server, even if - it has already been configured for the DHCPv4 server. The servers store their - information independently, so each server can use a separate - database or both servers can use the same database. - - - - Database configuration is controlled through the Dhcp6/lease-database parameters. - The type of the database must be set to "mysql", "postgresql" or "memfile": - -> config set Dhcp6/lease-database/type "mysql" - - Next, the name of the database is to hold the leases must be set: this is the - name used when the lease database was created (see - or ). - -> config set Dhcp6/lease-database/name "database-name" - - If the database is located on a different system to the DHCPv6 server, the - database host name must also be specified (although note that this configuration - may have a severe impact on server performance): - -> config set Dhcp6/lease-database/host "remote-host-name" - - The usual state of affairs will be to have the database on the same machine as the - DHCPv6 server. In this case, set the value to the empty string (this is the default): - -> config set Dhcp6/lease-database/host "" - - - - Finally, the credentials of the account under which the server will access the database - should be set: - -> config set Dhcp6/lease-database/user "user-name" -> config set Dhcp6/lease-database/password "password" - - If there is no password to the account, set the password to the empty string "". (This is also the default.) - - - The password is echoed when entered and is stored in clear text in the configuration - database. Improved password security will be added in a future version of Kea. - -
- -
- Interface selection - - When DHCPv6 server starts up, by default it will listen to the DHCP - traffic and respond to it on all interfaces detected during startup. - However, in many cases it is desired to configure the server to listen and - respond on selected interfaces only. The sample commands in this section - show how to make interface selection using bindctl. - - - The default configuration can be presented with the following command: - -> config show Dhcp6/interfaces -Dhcp6/interfaces[0] "*" string - An asterisk sign plays a role of the wildcard and means "listen on all interfaces". - - - In order to override the default configuration, the existing entry can be replaced - with the actual interface name: - -> config set Dhcp6/interfaces[0] eth1 -> config commit - Other interface names can be added on one-by-one basis: - -> config add Dhcp6/interfaces eth2 -> config commit - Configuration will now contain two interfaces which can be presented as follows: - -> config show Dhcp6/interfaces -Dhcp6/interfaces[0] "eth1" string -Dhcp6/interfaces[1] "eth2" string - When configuration gets committed, the server will start to listen on - eth1 and eth2 interfaces only. - - - It is possible to use wildcard interface name (asterisk) concurrently with explicit - interface names: - -> config add Dhcp6/interfaces * -> config commit - This will result in the following configuration: - -> config show Dhcp6/interfaces -Dhcp6/interfaces[0] "eth1" string -Dhcp6/interfaces[1] "eth2" string -Dhcp6/interfaces[2] "*" string - The presence of the wildcard name implies that server will listen on all interfaces. - In order to fall back to the previous configuration when server listens on eth1 and eth2: - -> config remove Dhcp6/interfaces[2] -> config commit - -
- -
- IPv6 Subnet Identifier - - Subnet identifier is a unique number associated with a particular subnet. - In principle, it is used to associate clients' leases with respective subnets. - When subnet identifier is not specified for a subnet being configured, it will - be automatically assigned by the configuration mechanism. The identifiers - are assigned from 1 and are monotonically increased for each subsequent - subnet: 1, 2, 3 .... - - - If there are multiple subnets configured with auto-generated identifiers and - one of them is removed, the subnet identifiers may be renumbered. For example: - if there are 4 subnets and 3rd is removed the last subnet will be assigned - identifier that the 3rd subnet had before removal. As a result, the leases - stored in the lease database for subnet 3 are now associated with the - subnet 4, which may have unexpected consequences. In the future it is planned - to implement the mechanism to preserve auto-generated subnet ids upon removal - of one of the subnets. Currently, the only remedy for this issue is to - manually specify the unique subnet identifier for each subnet. - - - The following configuration: - -> config add Dhcp6/subnet6 -> config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64" -> config set Dhcp6/subnet6[0]/id 1024 -> config commit - - will assign the arbitrary subnet identifier to the newly configured subnet. - This identifier will not change for this subnet until "id" parameter is - removed or set to 0. The value of 0 forces auto-generation of subnet - identifier. - -
- -
- Unicast traffic support - - When DHCPv6 server starts up, by default it listens to the DHCP traffic - sent to multicast address ff02::1:2 on each interface that it is - configured to listen on (see ). - In some cases it is useful to configure a server to handle incoming - traffic sent to the global unicast addresses as well. The most common - reason for that is to have relays send their traffic to the server - directly. To configure server to listen on specific unicast address, a - notation to specify interfaces has been extended. Interface name can be - optionally followed by a slash, followed by global unicast address that - server should listen on. That will be done in addition to normal - link-local binding + listening on ff02::1:2 address. The sample commands - listed below show how to listen on 2001:db8::1 (a global address) - configured on the eth1 interface. - - - -> config set Dhcp6/interfaces[0] eth1/2001:db8::1 -> config commit - When configuration gets committed, the server will start to listen on - eth1 on link-local address, multicast group (ff02::1:2) and 2001:db8::1. - - - It is possible to mix interface names, wildcards and interface name/addresses - on the Dhcp6/interface list. It is not possible to specify more than one - unicast address on a given interface. - - - Care should be taken to specify proper unicast addresses. The server will - attempt to bind to those addresses specified, without any additional checks. - That approach is selected on purpose, so in the software can be used to - communicate over uncommon addresses if the administrator desires so. - -
- -
- Subnet and Address Pool - - The essential role of a DHCPv6 server is address assignment. For this, - the server has to be configured with at least one subnet and one pool of dynamic - addresses to be managed. For example, assume that the server - is connected to a network segment that uses the 2001:db8:1::/64 - prefix. The Administrator of that network has decided that addresses from range - 2001:db8:1::1 to 2001:db8:1::ffff are going to be managed by the Dhcp6 - server. Such a configuration can be achieved in the following way: - -> config add Dhcp6/subnet6 -> config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64" -> config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::0 - 2001:db8:1::ffff" ] -> config commit - Note that subnet is defined as a simple string, but the pool parameter - is actually a list of pools: for this reason, the pool definition is - enclosed in square brackets, even though only one range of addresses - is specified. - It is possible to define more than one pool in a - subnet: continuing the previous example, further assume that - 2001:db8:1:0:5::/80 should be also be managed by the server. It could be written as - 2001:db8:1:0:5:: to 2001:db8:1::5:ffff:ffff:ffff, but typing so many 'f's - is cumbersome. It can be expressed more simply as 2001:db8:1:0:5::/80. Both - formats are supported by Dhcp6 and can be mixed in the pool list. - For example, one could define the following pools: - -> config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::1 - 2001:db8:1::ffff", "2001:db8:1:0:5::/80" ] -> config commit - The number of pools is not limited, but for performance reasons it is recommended to - use as few as possible. - - - The server may be configured to serve more than one subnet. To add a second subnet, - use a command similar to the following: - -> config add Dhcp6/subnet6 -> config set Dhcp6/subnet6[1]/subnet "2001:db8:beef::/48" -> config set Dhcp6/subnet6[1]/pool [ "2001:db8:beef::/48" ] -> config commit - Arrays are counted from 0. subnet[0] refers to the subnet defined in the - previous example. The config add Dhcp6/subnet6 command adds - another (second) subnet. It can be referred to as - Dhcp6/subnet6[1]. In this example, we allow server to - dynamically assign all addresses available in the whole subnet. Although - very wasteful, it is certainly a valid configuration to dedicate the - whole /48 subnet for that purpose. - - - When configuring a DHCPv6 server using prefix/length notation, please pay - attention to the boundary values. When specifying that the server should use - a given pool, it will be able to allocate also first (typically network - address) address from that pool. For example for pool 2001:db8::/64 the - 2001:db8:: address may be assigned as well. If you want to avoid this, - please use the "min-max" notation. - -
- -
- - Subnet and Prefix Delegation Pools - - Subnets may also be configured to delegate address prefixes.... - A subnet may have one or more prefix delegation pools. Each pool has - a prefixed address, which is specified as a prefix and a prefix length, - as well as a delegated prefix length. A sample configuration is shown - below: - -> config add Dhcp6/subnet6 -> config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64" -> config show Dhcp6/subnet6[0] -> config add Dhcp6/subnet6[0]/pd-pools -> config set Dhcp6/subnet6[0]/pd-pools[0]/prefix "2001:db8:1::" -> config set Dhcp6/subnet6[0]/pd-pools[0]/prefix-len 64 -> config set Dhcp6/subnet6[0]/pd-pools[0]/delegated-len 96 -> config commit - -
- -
- Standard DHCPv6 options - - One of the major features of DHCPv6 server is to provide configuration - options to clients. Although there are several options that require - special behavior, most options are sent by the server only if the client - explicitly requested them. The following example shows how to - configure DNS servers, which is one of the most frequently used - options. Numbers in the first column are added for easier reference and - will not appear on screen. Options specified in this way are considered - global and apply to all configured subnets. - - -1. > config add Dhcp6/option-data -2. > config set Dhcp6/option-data[0]/name "dns-servers" -3. > config set Dhcp6/option-data[0]/code 23 -4. > config set Dhcp6/option-data[0]/space "dhcp6" -5. > config set Dhcp6/option-data[0]/csv-format true -6. > config set Dhcp6/option-data[0]/data "2001:db8::cafe, 2001:db8::babe" -7. > config commit - - - - The first line creates new entry in option-data table. It - contains information on all global options that the server is - supposed to configure in all subnets. The second line specifies - option name. For a complete list of currently supported names, - see . - The third line specifies option code, which must match one of the - values from that - list. Line 4 specifies option space, which must always - be set to "dhcp6" as these are standard DHCPv6 options. For - other name spaces, including custom option spaces, see . The fifth line specifies the format in - which the data will be entered: use of CSV (comma - separated values) is recommended. The sixth line gives the actual value to - be sent to clients. Data is specified as a normal text, with - values separated by commas if more than one value is - allowed. - - - - Options can also be configured as hexadecimal values. If csv-format is - set to false, the option data must be specified as a string of hexadecimal - numbers. The - following commands configure the DNS-SERVERS option for all - subnets with the following addresses: 2001:db8:1::cafe and - 2001:db8:1::babe. - -> config add Dhcp6/option-data -> config set Dhcp6/option-data[0]/name "dns-servers" -> config set Dhcp6/option-data[0]/code 23 -> config set Dhcp6/option-data[0]/space "dhcp6" -> config set Dhcp6/option-data[0]/csv-format false -> config set Dhcp6/option-data[0]/data "2001 0DB8 0001 0000 0000 0000 - 0000 CAFE 2001 0DB8 0001 0000 0000 0000 0000 BABE" -> config commit - - (The value for the setting of the "data" element is split across two - lines in this document for clarity: when entering the command, the - whole string should be entered on the same line.) - - - - It is possible to override options on a per-subnet basis. If - clients connected to most of your subnets are expected to get the - same values of a given option, you should use global options: you - can then override specific values for a small number of subnets. - On the other hand, if you use different values in each subnet, - it does not make sense to specify global option values - (Dhcp6/option-data), rather you should set only subnet-specific values - (Dhcp6/subnet[X]/option-data[Y]). - - - The following commands override the global - DNS servers option for a particular subnet, setting a single DNS - server with address 2001:db8:1::3. - -> config add Dhcp6/subnet6[0]/option-data -> config set Dhcp6/subnet6[0]/option-data[0]/name "dns-servers" -> config set Dhcp6/subnet6[0]/option-data[0]/code 23 -> config set Dhcp6/subnet6[0]/option-data[0]/space "dhcp6" -> config set Dhcp6/subnet6[0]/option-data[0]/csv-format true -> config set Dhcp6/subnet6[0]/option-data[0]/data "2001:db8:1::3" -> config commit - - - - - In future versions of BIND 10 DHCP, it will not be necessary to specify - option code, space and csv-format fields, as those fields will be set - automatically. - - - - - - The currently supported standard DHCPv6 options are - listed in . - The "Name" and "Code" - are the values that should be used as a name in the option-data - structures. "Type" designates the format of the data: the meanings of - the various types is given in . - - - Some options are designated as arrays, which means that more than one - value is allowed in such an option. For example the option dns-servers - allows the specification of more than one IPv6 address, so allowing - clients to obtain the the addresses of multiple DNS servers. - - - - - - The describes the configuration - syntax to create custom option definitions (formats). It is generally not - allowed to create custom definitions for standard options, even if the - definition being created matches the actual option format defined in the - RFCs. There is an exception from this rule for standard options for which - Kea does not provide a definition yet. In order to use such options, - a server administrator must create a definition as described in - in the 'dhcp6' option space. This - definition should match the option format described in the relevant - RFC but configuration mechanism would allow any option format as it has - no means to validate it at the moment. - - - - - - List of standard DHCPv6 options - - - - - - - NameCodeTypeArray? - - - -preference7uint8false - - -sip-server-dns21fqdntrue -sip-server-addr22ipv6-addresstrue -dns-servers23ipv6-addresstrue -domain-search24fqdntrue - - -nis-servers27ipv6-addresstrue -nisp-servers28ipv6-addresstrue -nis-domain-name29fqdntrue -nisp-domain-name30fqdntrue -sntp-servers31ipv6-addresstrue -information-refresh-time32uint32false -bcmcs-server-dns33fqdntrue -bcmcs-server-addr34ipv6-addresstrue -geoconf-civic36recordfalse -remote-id37recordfalse -subscriber-id38binaryfalse -client-fqdn39recordfalse -pana-agent40ipv6-addresstrue -new-posix-timezone41stringfalse -new-tzdb-timezone42stringfalse -ero43uint16true -lq-query44recordfalse -client-data45emptyfalse -clt-time46uint32false -lq-relay-data47recordfalse -lq-client-link48ipv6-addresstrue - - -
- -
- -
- Custom DHCPv6 options - It is also possible to define options other than the standard ones. - Assume that we want to define a new DHCPv6 option called "foo" which will have - code 100 and will convey a single unsigned 32 bit integer value. We can define - such an option by using the following commands: - -> config add Dhcp6/option-def -> config set Dhcp6/option-def[0]/name "foo" -> config set Dhcp6/option-def[0]/code 100 -> config set Dhcp6/option-def[0]/type "uint32" -> config set Dhcp6/option-def[0]/array false -> config set Dhcp6/option-def[0]/record-types "" -> config set Dhcp6/option-def[0]/space "dhcp6" -> config set Dhcp6/option-def[0]/encapsulate "" -> config commit - The "false" value of the "array" parameter determines that the option - does NOT comprise an array of "uint32" values but rather a single value. - Two other parameters have been left blank: "record-types" and "encapsulate". - The former specifies the comma separated list of option data fields if the - option comprises a record of data fields. The "record-fields" value should - be non-empty if the "type" is set to "record". Otherwise it must be left - blank. The latter parameter specifies the name of the option space being - encapsulated by the particular option. If the particular option does not - encapsulate any option space it should be left blank. - Note that the above set of comments define the format of the new option and do not - set its values. - - Once the new option format is defined, its value is set - in the same way as for a standard option. For example the following - commands set a global value that applies to all subnets. - -> config add Dhcp6/option-data -> config set Dhcp6/option-data[0]/name "foo" -> config set Dhcp6/option-data[0]/code 100 -> config set Dhcp6/option-data[0]/space "dhcp6" -> config set Dhcp6/option-data[0]/csv-format true -> config set Dhcp6/option-data[0]/data "12345" -> config commit - - - New options can take more complex forms than simple use of - primitives (uint8, string, ipv6-address etc): it is possible to - define an option comprising a number of existing primitives. - - - Assume we want to define a new option that will consist of an IPv6 - address, followed by an unsigned 16 bit integer, followed by a - boolean value, followed by a text string. Such an option could - be defined in the following way: - -> config add Dhcp6/option-def -> config set Dhcp6/option-def[0]/name "bar" -> config set Dhcp6/option-def[0]/code 101 -> config set Dhcp6/option-def[0]/space "dhcp6" -> config set Dhcp6/option-def[0]/type "record" -> config set Dhcp6/option-def[0]/array false -> config set Dhcp6/option-def[0]/record-types "ipv6-address, uint16, boolean, string" -> config set Dhcp6/option-def[0]/encapsulate "" - - The "type" is set to "record" to indicate that the option contains - multiple values of different types. These types are given as a comma-separated - list in the "record-types" field and should be those listed in . - - - The values of the option are set as follows: - -> config add Dhcp6/option-data -> config set Dhcp6/option-data[0]/name "bar" -> config set Dhcp6/option-data[0]/space "dhcp6" -> config set Dhcp6/option-data[0]/code 101 -> config set Dhcp6/option-data[0]/csv-format true -> config set Dhcp6/option-data[0]/data "2001:db8:1::10, 123, false, Hello World" -> config commit - "csv-format" is set "true" to indicate that the "data" field comprises a command-separated - list of values. The values in the "data" must correspond to the types set in - the "record-types" field of the option definition. - - - - It is recommended that boolean values are specified using "true" and "false" - strings. This helps to prevent errors when typing multiple comma separated - values, as it make it easier to identify the type of the value being typed, - and compare it with the order of data fields. Nevertheless, it is possible - to use integer values: "1" and "0", instead of "true" and "false" - accordingly. If other integer value is specified, the configuration is - rejected. - - -
- -
- DHCPv6 vendor specific options - - Currently there are three option spaces defined: dhcp4 (to be used - in DHCPv4 daemon) and dhcp6 (for the DHCPv6 daemon); there is also - vendor-opts-space, which is empty by default, but options can be - defined in it. Those options are called vendor-specific information - options. The following examples show how to define an option "foo" - with code 1 that consists of an IPv6 address, an unsigned 16 bit integer - and a string. The "foo" option is conveyed in a vendor specific - information option. This option comprises a single uint32 value - that is set to "12345". The sub-option "foo" follows the data - field holding this value. - -> config add Dhcp6/option-def -> config set Dhcp6/option-def[0]/name "foo" -> config set Dhcp6/option-def[0]/code 1 -> config set Dhcp6/option-def[0]/space "vendor-opts-space" -> config set Dhcp6/option-def[0]/type "record" -> config set Dhcp6/option-def[0]/array false -> config set Dhcp6/option-def[0]/record-types "ipv6-address, uint16, string" -> config set Dhcp6/option-def[0]/encapsulates "" -> config commit - - (Note that the option space is set to "vendor-opts-space".) - Once the option format is defined, the next step is to define actual values - for that option: - -> config add Dhcp6/option-data -> config set Dhcp6/option-data[0]/name "foo" -> config set Dhcp6/option-data[0]/space "vendor-opts-space" -> config set Dhcp6/option-data[0]/code 1 -> config set Dhcp6/option-data[0]/csv-format true -> config set Dhcp6/option-data[0]/data "2001:db8:1::10, 123, Hello World" -> config commit - We should also define values for the vendor-opts, that will convey our option foo. - -> config add Dhcp6/option-data -> config set Dhcp6/option-data[1]/name "vendor-opts" -> config set Dhcp6/option-data[1]/space "dhcp6" -> config set Dhcp6/option-data[1]/code 17 -> config set Dhcp6/option-data[1]/csv-format true -> config set Dhcp6/option-data[1]/data "12345" -> config commit - -
- -
- Nested DHCPv6 options (custom option spaces) - It is sometimes useful to define completely new option - spaces. This is useful if the user wants his new option to - convey sub-options that use separate numbering scheme, for - example sub-options with codes 1 and 2. Those option codes - conflict with standard DHCPv6 options, so a separate option - space must be defined. - - Note that it is not required to create new option space when - defining sub-options for a standard option because it is by - default created if the standard option is meant to convey - any sub-options (see ). - - - Assume that we want to have a DHCPv6 option called "container" - with code 102 that conveys two sub-options with codes 1 and 2. - First we need to define the new sub-options: - -> config add Dhcp6/option-def -> config set Dhcp6/option-def[0]/name "subopt1" -> config set Dhcp6/option-def[0]/code 1 -> config set Dhcp6/option-def[0]/space "isc" -> config set Dhcp6/option-def[0]/type "ipv6-address" -> config set Dhcp6/option-def[0]/record-types "" -> config set Dhcp6/option-def[0]/array false -> config set Dhcp6/option-def[0]/encapsulate "" -> config commit -> -> config add Dhcp6/option-def -> config set Dhcp6/option-def[1]/name "subopt2" -> config set Dhcp6/option-def[1]/code 2 -> config set Dhcp6/option-def[1]/space "isc" -> config set Dhcp6/option-def[1]/type "string" -> config set Dhcp6/option-def[1]/record-types "" -> config set Dhcp6/option-def[1]/array false -> config set Dhcp6/option-def[1]/encapsulate "" -> config commit - - Note that we have defined the options to belong to a new option space - (in this case, "isc"). - - -The next step is to define a regular DHCPv6 option and specify that it -should include options from the isc option space: - -> config add Dhcp6/option-def -> config set Dhcp6/option-def[2]/name "container" -> config set Dhcp6/option-def[2]/code 102 -> config set Dhcp6/option-def[2]/space "dhcp6" -> config set Dhcp6/option-def[2]/type "empty" -> config set Dhcp6/option-def[2]/array false -> config set Dhcp6/option-def[2]/record-types "" -> config set Dhcp6/option-def[2]/encapsulate "isc" -> config commit - - The name of the option space in which the sub-options are defined - is set in the "encapsulate" field. The "type" field is set to "empty" - which imposes that this option does not carry any data other than - sub-options. - - - Finally, we can set values for the new options: - -> config add Dhcp6/option-data -> config set Dhcp6/option-data[0]/name "subopt1" -> config set Dhcp6/option-data[0]/space "isc" -> config set Dhcp6/option-data[0]/code 1 -> config set Dhcp6/option-data[0]/csv-format true -> config set Dhcp6/option-data[0]/data "2001:db8::abcd" -> config commit -> -> config add Dhcp6/option-data -> config set Dhcp6/option-data[1]/name "subopt2" -> config set Dhcp6/option-data[1]/space "isc" -> config set Dhcp6/option-data[1]/code 2 -> config set Dhcp6/option-data[1]/csv-format true -> config set Dhcp6/option-data[1]/data "Hello world" -> config commit -> -> config add Dhcp6/option-data -> config set Dhcp6/option-data[2]/name "container" -> config set Dhcp6/option-data[2]/space "dhcp6" -> config set Dhcp6/option-data[2]/code 102 -> config set Dhcp6/option-data[2]/csv-format true -> config set Dhcp6/option-data[2]/data "" -> config commit - - Even though the "container" option does not carry any data except - sub-options, the "data" field must be explicitly set to an empty value. - This is required because in the current version of BIND 10 DHCP, the - default configuration values are not propagated to the configuration parsers: - if the "data" is not set the parser will assume that this - parameter is not specified and an error will be reported. - - Note that it is possible to create an option which carries some data - in addition to the sub-options defined in the encapsulated option space. For example, - if the "container" option from the previous example was required to carry an uint16 - value as well as the sub-options, the "type" value would have to be set to "uint16" in - the option definition. (Such an option would then have the following - data structure: DHCP header, uint16 value, sub-options.) The value specified - with the "data" parameter - which should be a valid integer enclosed in quotes, - e.g. "123" - would then be assigned to the uint16 field in the "container" option. - -
- -
- IPv6 Subnet Selection - - The DHCPv6 server may receive requests from local (connected to the - same subnet as the server) and remote (connecting via relays) clients. - As server may have many subnet configurations defined, it must select - appropriate subnet for a given request. - - - The server can not assume which of configured subnets are local. It is - possible in IPv4, where there is reasonable expectation that the - server will have a (global) IPv4 address configured on the interface, - and can use that information to detect whether a subnet is local or - not. That assumption is not true in IPv6, as the DHCPv6 must be able - to operate with having link-local addresses only. Therefore an optional - "interface" parameter is available within a subnet definition - to designate that a given subnet is local, i.e. reachable directly over - specified interface. For example the server that is intended to serve - a local subnet over eth0 may be configured as follows: - -> config add Dhcp6/subnet6 -> config set Dhcp6/subnet6[1]/subnet "2001:db8:beef::/48" -> config set Dhcp6/subnet6[1]/pool [ "2001:db8:beef::/48" ] -> config set Dhcp6/subnet6[1]/interface "eth0" -> config commit - - -
- -
- DHCPv6 Relays - - A DHCPv6 server with multiple subnets defined must select the - appropriate subnet when it receives a request from client. For clients - connected via relays, two mechanisms are used: - - - The first uses the linkaddr field in the RELAY_FORW message. The name - of this field is somewhat misleading in that it does not contain a link-layer - address: instead, it holds an address (typically a global address) that is - used to identify a link. The DHCPv6 server checks if the address belongs - to a defined subnet and, if it does, that subnet is selected for the client's - request. - - - The second mechanism is based on interface-id options. While forwarding a client's - message, relays may insert an interface-id option into the message that - identifies the interface on the relay that received the message. (Some - relays allow configuration of that parameter, but it is sometimes - hardcoded and may range from the very simple (e.g. "vlan100") to the very cryptic: - one example seen on real hardware was "ISAM144|299|ipv6|nt:vp:1:110"). The - server can use this information to select the appropriate subnet. - The information is also returned to the relay which then knows the - interface to use to transmit the response to the client. In order for - this to work successfully, the relay interface IDs must be unique within - the network and the server configuration must match those values. - - - When configuring the DHCPv6 server, it should be noted that two - similarly-named parameters can be configured for a subnet: - - - "interface" defines which local network interface can be used - to access a given subnet. - - - "interface-id" specifies the content of the interface-id option - used by relays to identify the interface on the relay to which - the response packet is sent. - - - The two are mutually exclusive: a subnet cannot be both reachable locally - (direct traffic) and via relays (remote traffic). Specifying both is a - configuration error and the DHCPv6 server will refuse such a configuration. - - - - To specify interface-id with value "vlan123", the following commands can - be used: - -> config add Dhcp6/subnet6 -> config set Dhcp6/subnet6[0]/subnet "2001:db8:beef::/48" -> config set Dhcp6/subnet6[0]/pool [ "2001:db8:beef::/48" ] -> config set Dhcp6/subnet6[0]/interface-id "vland123" -> config commit - - -
- -
- Client Classification in DHCPv6 - - - DHCPv6 server has been extended to support limited client classification. - Although the current capability is modest, it is expected to be expanded - in the future. It is envisaged that the majority of client classification - extensions will be using hooks extensions. - - - In certain cases it is useful to differentiate between different types - of clients and treat them differently. The process of doing classification - is conducted in two steps. The first step is to assess incoming packet and - assign it to zero or more classes. This classification is currently simple, - but is expected to grow in capability soon. Currently the server checks whether - incoming packet has vendor class option (16). If it has, content - of that option is prepended with "VENDOR_CLASS_" interpreted as a - class. For example, modern cable modems will send this option with value - "docsis3.0" and as a result the packet will belong to class - "VENDOR_CLASS_docsis3.0". - - - It is envisaged that the client classification will be used for changing - behavior of almost any part of the DHCP engine processing, including assigning - leases from different pools, assigning different option (or different values of - the same options) etc. For now, there is only one mechanism that is taking - advantage of client classification: subnet selection. - - - Kea can be instructed to limit access to given subnets based on class information. - This is particularly useful for cases where two types of devices share the - same link and are expected to be served from two different subnets. The - primary use case for such a scenario are cable networks. There are two - classes of devices: cable modem itself, which should be handled a lease - from subnet A and all other devices behind modems that should get a lease - from subnet B. That segregation is essential to prevent overly curious - users from playing with their cable modems. For details on how to set up - class restrictions on subnets, see . - - -
- -
- Limiting access to IPv6 subnet to certain classes - - In certain cases it beneficial to restrict access to certains subnets - only to clients that belong to a given subnet. For details on client - classes, see . This is an - extension of a previous example from . - - Let's assume that the server is connected to a network segment that uses - the 2001:db8:1::/64 prefix. The Administrator of that network has - decided that addresses from range 2001:db8:1::1 to 2001:db8:1::ffff are - going to be managed by the Dhcp6 server. Only clients belonging to the - eRouter1.0 client class are allowed to use that pool. Such a - configuration can be achieved in the following way: - - -> config add Dhcp6/subnet6 -> config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64" -> config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::0 - 2001:db8:1::ffff" ] -> config set Dhcp6/subnet6[0]/client-class "eRouter1.0" -> config commit - - - - Care should be taken with client classification as it is easy to prevent - clients that do not meet class criteria to be denied any service altogether. - -
- - -
- Configuring DHCPv6 for DDNS - - As mentioned earlier, b10-dhcp6 can be configured to generate requests to - the DHCP-DDNS server (referred to here as the "D2" server) to update - DNS entries. These requests are known as NameChangeRequests or NCRs. - Each NCR contains the following information: - - - Whether it is a request to add (update) or remove DNS entries - - - Whether the change requests forward DNS updates (AAAA records), reverse - DNS updates (PTR records), or both. - - - The FQDN, lease address, and DHCID - - - The parameters controlling the generation of NCRs for submission to D2 - are contained in the "dhcp-ddns" section of b10-dhcp6 - configuration. The default values for this section appears as follows: - -> config show Dhcp6/dhcp-ddns -Dhcp6/dhcp-ddns/enable-updates true boolean -Dhcp6/dhcp-ddns/server-ip "127.0.0.1" string -Dhcp6/dhcp-ddns/server-port 53001 integer -Dhcp6/dhcp-ddns/sender-ip "" string -Dhcp6/dhcp-ddns/sender-port 0 integer -Dhcp6/dhcp-ddns/max-queue-size 1024 integer -Dhcp6/dhcp-ddns/ncr-protocol "UDP" string -Dhcp6/dhcp-ddns/ncr-format "JSON" string -Dhcp6/dhcp-ddns/override-no-update false boolean -Dhcp6/dhcp-ddns/override-client-update false boolean -Dhcp6/dhcp-ddns/replace-client-name false boolean -Dhcp6/dhcp-ddns/generated-prefix "myhost" string -Dhcp6/dhcp-ddns/qualifying-suffix "example.com" string - - - - The "enable-updates" parameter determines whether or not b10-dhcp6 will - generate NCRs. By default, this value is false hence DDNS updates are - disabled. To enable DDNS updates set this value to true as follows: - - -> config set Dhcp6/dhcp-ddns/enable-updates true -> config commit - -
- DHCP-DDNS Server Connectivity - - In order for NCRs to reach the D2 server, b10-dhcp6 must be able - to communicate with it. b10-dhcp6 uses the following configuration - parameters to control how it communications with D2: - - - server-ip - 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. - - - server-port - port on which D2 listens for requests. The default value - is 53001. - - - sender-ip - IP address which b10-dhcp6 should use to send requests to D2. - The default value is blank which instructs b10-dhcp6 to select a suitable - address. - - - sender-port - port which b10-dhcp6 should use to send requests to D2. The - default value of 0 instructs b10-dhcp6 to select suitable port. - - - ncr-format - Socket protocol use when sending requests to D2. Currently - only UDP is supported. TCP may be available in an upcoming release. - - - 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. - - - max-queue-size - maximum number of requests allowed to queue waiting to - be sent to D2. This value guards against requests accumulating - uncontrollably if they are being generated faster than they can be - delivered. If the number of requests queued for transmission reaches - this value, DDNS updating will be turned off until the queue backlog has - been sufficiently reduced. The intent is allow b10-dhcp6 to - continue lease operations. The default value is 1024. - - - By default, D2 is assumed to running on the same machine as b10-dhcp6, and - all of the default values mentioned above should be sufficient. - If, however, D2 has been configured to listen on a different address or - port, these values must altered accordingly. For example, if D2 has been - configured to listen on 3001::5 port 900, the following commands - would be required: - -> config set Dhcp6/dhcp-ddns/server-ip "3001::5" -> config set Dhcp6/dhcp-ddns/server-port 900 -> config commit - - -
-
- When does b10-dhcp6 generate DDNS request - b10-dhcp6 follows the behavior prescribed for DHCP servers in RFC 4704. - It is important to keep in mind that b10-dhcp6 provides the initial decision - making of when and what to update and forwards that information to D2 in - the form of NCRs. Carrying out the actual DNS updates and dealing with - such things as conflict resolution are the purview of D2 (). - - This section describes when b10-dhcp6 will generate NCRs and the - configuration parameters that can be used to influence this decision. - It assumes that the "enable-updates" parameter is true. - - - - Currently the interface between b10-dhcp6 and D2 only supports requests - which update DNS entries for a single IP address. If a lease grants - more than one address, b10-dhcp6 will create the DDNS update request for - only the first of these addresses. Support for multiple address - mappings may be provided in a future release. - - - - In general, b10-dhcp6 will generate DDNS update requests when: - - - A new lease is granted in response to a DHCP REQUEST - - - An existing lease is renewed but the FQDN associated with it has - changed. - - - An existing lease is released in response to a DHCP RELEASE - - - In the second case, lease renewal, two DDNS requests will be issued: one - request to remove entries for the previous FQDN and a second request to - add entries for the new FQDN. In the last case, a lease release, a - single DDNS request to remove its entries will be made. The decision - making involved when granting a new lease is more involved and is - discussed next. - - - b10-dhcp6 will generate a DDNS update request only if the DHCP REQUEST - contains the FQDN option (code 39). By default b10-dhcp6 will - respect the FQDN N and S flags specified by the client as shown in the - following table: - - - Default FQDN Flag Behavior - - - - - - - - Client Flags:N-S - Client Intent - Server Response - Server Flags:N-S-O - - - - - 0-0 - - Client wants to do forward updates, server should do reverse updates - - Server generates reverse-only request - 1-0-0 - - - 0-1 - Server should do both forward and reverse updates - Server generates request to update both directions - 0-1-0 - - - 1-0 - Client wants no updates done - Server does not generate a request - 1-0-0 - - - -
- - The first row in the table above represents "client delegation". Here - the DHCP client states that it intends to do the forward DNS updates and - the server should do the reverse updates. By default, b10-dhcp6 will honor - the client's wishes and generate a DDNS request to D2 to update only - reverse DNS data. The parameter, "override-client-update", can be used - to instruct the server to override client delegation requests. When - this parameter is true, b10-dhcp6 will disregard requests for client - delegation and generate a DDNS request to update both forward and - reverse DNS data. In this case, the N-S-O flags in the server's - response to the client will be 0-1-1 respectively. - - - (Note that the flag combination N=1, S=1 is prohibited according to - RFC 4702. If such a combination is received from the client, the packet - will be dropped by b10-dhcp6.) - - - To override client delegation, issue the following commands: - - -> config set Dhcp6/dhcp-ddns/override-client-update true -> config commit - - - The third row in the table above describes the case in which the client - requests that no DNS updates be done. The parameter, "override-no-update", - can be used to instruct the server to disregard the client's wishes. When - this parameter is true, b10-dhcp6 will generate DDNS update request to D2 - even if the client requests no updates be done. The N-S-O flags in the - server's response to the client will be 0-1-1. - - - To override client delegation, issue the following commands: - - -> config set Dhcp6/dhcp-ddns/override-no-update true -> config commit - -
-
- b10-dhcp6 name generation for DDNS update requests - Each NameChangeRequest must of course include the fully qualified domain - name whose DNS entries are to be affected. b10-dhcp6 can be configured to - supply a portion or all of that name based upon what it receives from - the client in the DHCP REQUEST. - - The rules for determining the FQDN option are as follows: - - - If configured to do so ignore the REQUEST contents and generate a - FQDN using a configurable prefix and suffix. - - - Otherwise, using is the domain name value from the client FQDN option as - the candidate name: - - - If the candidate name is a fully qualified domain name then use it. - - - If the candidate name is a partial (i.e. unqualified) name then - add a configurable suffix to the name and use the result as the FQDN. - - - If the candidate name is a empty then generate a FQDN using a - configurable prefix and suffix. - - - - - To instruct b10-dhcp6 to always generate a FQDN, set the parameter - "replace-client-name" to true: - - -> config set Dhcp6/dhcp-ddns/replace-client-name true -> config commit - - - The prefix used when generating a FQDN is specified by the - "generated-prefix" parameter. The default value is "myhost". To alter - its value, simply set it to the desired string: - - -> config set Dhcp6/dhcp-ddns/generated-prefix "another.host" -> config commit - - - The suffix used when generating a FQDN or when qualifying a partial - name is specified by the "qualifying-suffix" parameter. The default - value is "example.com". To alter its value simply set it to the desired - string: - - -> config set Dhcp6/dhcp-ddns/generated-prefix "our.net" -> config commit - -
- - When qualifying a partial name, b10-dhcp6 will construct a name with the - format: - - - [candidate-name].[qualifying-suffix]. - - - where candidate-name is the partial name supplied in the REQUEST. - For example, if FQDN domain name value was "some-computer" and assuming - the default value for qualifying-suffix, the generated FQDN would be: - - - some-computer.example.com. - - - When generating a the entire name, b10-dhcp6 will construct name of the - format: - - - [generated-prefix]-[address-text].[qualifying-suffix]. - - - where address-text is simply the lease IP address converted to a - hyphenated string. For example, if lease address is 3001:1::70E and - assuming default values for generated-prefix and qualifying-suffix, the - generated FQDN would be: - - - myhost-3001-1--70E.example.com. - -
- -
- -
- Server Identifier in DHCPv6 - The DHCPv6 protocol uses a "server identifier" (also known - as a DUID) for clients to be able to discriminate between several - servers present on the same link. There are several types of - DUIDs defined, but RFC 3315 instructs servers to use DUID-LLT if - possible. This format consists of a link-layer (MAC) address and a - timestamp. When started for the first time, the DHCPv6 server will - automatically generate such a DUID and store the chosen value to - a file. That file is read by the server - and the contained value used whenever the server is subsequently started. - - - It is unlikely that this parameter should ever need to be changed. - However, if such a need arises, stop the server, edit the file and restart - the server. (The file is named b10-dhcp6-serverid and by default is - stored in the "var" subdirectory of the directory in which BIND 10 is installed. - This can be changed when BIND 10 is built by using "--localstatedir" - on the "configure" command line.) The file is a text file that contains - double digit hexadecimal values - separated by colons. This format is similar to typical MAC address - format. Spaces are ignored. No extra characters are allowed in this - file. - - -
- -
- Using specific relay agent for a subnet - - The relay has to have an interface connected to the link on which - the clients are being configured. Typically the relay has a global IPv6 - address configured on that interface that belongs to the subnet that - the server will assign addresses from. In such typical case, the - server is able to use IPv6 address inserted by the relay (in link-addr - field in RELAY-FORW message) to select appropriate subnet. - - - However, that is not always the case. The relay - address may not match the subnet in certain deployments. This - usually means that there is more than one subnet allocated for a given - link. Two most common examples where this is the case are long lasting - network renumbering (where both old and new address space is still being - used) and a cable network. In a cable network both cable modems and the - devices behind them are physically connected to the same link, yet - they use distinct addressing. In such case, the DHCPv6 server needs - additional information (like the value of interface-id option or IPv6 - address inserted in the link-addr field in RELAY-FORW message) to - properly select an appropriate subnet. - - - The following example assumes that there is a subnet 2001:db8:1::/64 - that is accessible via relay that uses 3000::1 as its IPv6 address. - The server will be able to select this subnet for any incoming packets - that came from a relay that has an address in 2001:db8:1::/64 subnet. - It will also select that subnet for a relay with address 3000::1. - -> config add Dhcp6/subnet6 -> config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64" -> config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::2 - 2001:db8:1::ffff" ] -> config set Dhcp6/subnet6[0]/relay/ip-address "3000::1" -> config commit - - -
- -
- Segregating IPv6 clients in a cable network - - In certain cases, it is useful to mix relay address information, - introduced in with client - classification, explained in . - One specific example is cable network, where typically modems - get addresses from a different subnet than all devices connected - behind them. - - - Let's assume that there is one CMTS (Cable Modem Termination System) - with one CM MAC (a physical link that modems are connected to). - We want the modems to get addresses from the 3000::/64 subnet, - while everything connected behind modems should get addresses from - another subnet (2001:db8:1::/64). The CMTS that acts as a relay - an uses address 3000::1. The following configuration can serve - that configuration: - -> config add Dhcp6/subnet6 -> config set Dhcp6/subnet6[0]/subnet "3000::/64" -> config set Dhcp6/subnet6[0]/pool [ "3000::2 - 3000::ffff" ] -> config set Dhcp6/subnet6[0]/client-class "docsis3.0" -> config set Dhcp6/subnet6[0]/relay/ip-address "3000::1" -> config add Dhcp6/subnet6 -> config set Dhcp6/subnet6[1]/subnet "2001:db8:1::/64" -> config set Dhcp6/subnet6[1]/pool [ "2001:db8:1::1 - 2001:db8:1::ffff" ] -> config set Dhcp6/subnet6[1]/relay/ip-address "3000::1" -> config commit - -
- - -
- Supported Standards - The following standards and draft standards are currently - supported: - - - RFC 3315: Supported messages are SOLICIT, - ADVERTISE, REQUEST, RELEASE, RENEW, REBIND and REPLY. - - - RFC 3633: Supported options are IA_PD and - IA_PREFIX. Also supported is the status code NoPrefixAvail. - - - RFC 3646: Supported option is DNS_SERVERS. - - - RFC 4704: Supported option is CLIENT_FQDN. - - -
- -
- DHCPv6 Server Limitations - These are the current limitations and known problems - with the DHCPv6 server - software. Most of them are reflections of the early stage of - development and should be treated as not implemented - yet, rather than actual limitations. - - - - On-line configuration has some limitations. Adding new subnets or - modifying existing ones work, as is removing the last subnet from - the list. However, removing non-last (e.g. removing subnet 1,2 or 3 if - there are 4 subnets configured) will cause issues. The problem is - caused by simplistic subnet-id assignment. The subnets are always - numbered, starting from 1. That subnet-id is then used in leases - that are stored in the lease database. Removing non-last subnet will - cause the configuration information to mismatch data in the lease - database. It is possible to manually update subnet-id fields in - MySQL or PostgreSQL database, but it is awkward and error prone - process. A better reconfiguration support is planned. - - - - - - On startup, the DHCPv6 server does not get the full configuration from - BIND 10. To remedy this, after starting BIND 10, modify any parameter - and commit the changes, e.g. - -> config show Dhcp6/renew-timer -Dhcp6/renew-timer 1000 integer (default) -> config set Dhcp6/renew-timer 1001 -> config commit - - - - Temporary addresses are not supported. - - - - The server will allocate, renew or rebind a maximum of one lease - for a particular IA option (IA_NA or IA_PD) sent by a client. - RFC 3315 and - RFC 3633 allow - for multiple addresses or prefixes to be allocated for a single IA. - - - - Temporary addresses are not supported. - - - - Confirmation (CONFIRM), duplication report (DECLINE), - stateless configuration (INFORMATION-REQUEST) and client - reconfiguration (RECONFIGURE) are not yet supported. - - - - - The server doesn't act upon expired leases. In particular, - when a lease expires, the server doesn't request removal of - the DNS records associated with it. - - - -
- - - - - - - The DHCP-DDNS Server - - The DHCP-DDNS Server (b10-dhcp-ddns, known informally as D2) conducts the client side of - the DDNS protocol (defined in RFC 2136) on behalf of the DHCPv4 and DHCPv6 - servers (b10-dhcp4 and b10-dhcp6 respectively). The DHCP servers construct - DDNS update requests, known as NameChangeRequests (NCRs), based upon DHCP - lease change events and then post these to D2. D2 attempts to match - each such request to the appropriate DNS server(s) and carry out the - necessary conversation with those servers to update the DNS data. - - - In order to match a request to appropriate DNS servers, D2 must have a - catalog of servers from which to select. In fact, D2 has two such catalogs, - one for forward DNS and one for reverse DNS; these catalogs are referred - to as DDNS Domain Lists. Each list consists of one or more named DDNS - Domains. Further, each DDNS Domain has a list of of one or more DNS - servers that publish the DNS data for that domain. - - - When conducting forward domain matching, D2 will compare the FQDN in - the request against the name of each forward DDNS Domain. The domain - whose name matches the longest portion of the FQDN is considered the - best match. For example, if the FQDN is "myhost.sample.example.com.", - and there are two forward domains in the catalog: "sample.example.com." - and "example.com.", the former is regarded as the best match. In some - cases, it may not be possible to find a suitable match. Given the same two - forward domains there would be no match for the FQDN, "bogus.net", so the - request would be rejected. Finally, if there are no forward DDNS Domains - defined, D2 will simply disregard the forward update portion of requests. - - - When conducting reverse domain matching, D2 constructs a reverse - FQDN from the lease address in the request and compare that against - the name of each reverse DDNS Domain. Again, the domain whose name matches - the longest portion of the FQDN is considered the best match. For instance, - if the lease address is "172.16.1.40" and there are two reverse domains in - the catalog: "1.16.172.in-addr.arpa." and "16.172.in-addr.arpa", the - former is the best match. As with forward matching, it is possible to not - find a suitable match. Given the same two domains, there would be no - match for the lease address, "192.168.1.50", and the request would be - rejected. Finally, if there are no reverse DDNS Domains defined, D2 will - simply disregard the reverse update portion of requests. - -
- Starting and Stopping the DHCP-DDNS Server - - b10-dhcp-ddns is the BIND 10 DHCP-DDNS server and, - like other parts of BIND 10, is configured through the - bindctl program. - - - After starting BIND 10 and entering bindctl, the first step in - configuring the server is to add it to the list of running BIND 10 - services. - -> config add Init/components b10-dhcp-ddns -> config set Init/components/b10-dhcp-ddns/kind dispensable -> config commit - - - - To remove b10-dhcp-ddns from the set of running services, - the b10-dhcp-ddns is removed from list of Init components: - -> config remove Init/components b10-dhcp-ddns -> config commit - - - - Note that the server was only removed from the list, so it will not be - automatically restarted, but the server itself is still running. Hence it - is usually desired to stop it: - - -> DhcpDdns shutdown - - - Upon start up the module will load its configuration and begin listening - for NCRs based on that configuration. - -
-
- Configuring the DHCP-DDNS Server - - Once the server is started, it can be configured. To view the - current configuration, use the following command in bindctl: - -> config show DhcpDdns - When starting b10-dhcp-ddns module for the first time, the default - configuration will be available. It will look similar to this: - -> config show DhcpDdns -DhcpDdns/ip_address "127.0.0.1" string (default) -DhcpDdns/port 53001 integer (default) -DhcpDdns/dns_server_timeout 100 integer (default) -DhcpDdns/ncr_protocol "UDP" string (default) -DhcpDdns/ncr_format "JSON" string (default) -DhcpDdns/tsig_keys [] list (default) -DhcpDdns/forward_ddns/ddns_domains [] list (default) -DhcpDdns/reverse_ddns/ddns_domains [] list (default) - - - (While displayed, the parameter "interface" is not implemented, and - will be removed in the near future.) - - - - 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. - - - ncr_format - Socket protocol to use when sending requests to D2. - Currently only UDP is supported. TCP may be available in an upcoming - release. - - - 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. - - - 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. - - - - 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: - -> config set DhcpDdns/ip_address "192.168.1.10" -> config set DhcpDdns/port 900 -> config commit - - - - - When the DHCP-DDNS server is configured to listen at an address - other than the loopback address (127.0.0.1 or ::1), it is possible - for a malicious attacker to send bogus NameChangeRequests to it - and change entries in the DNS. For this reason, addresses other - than the IPv4 or IPv6 loopback addresses should only be used - for testing purposes. 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 repsonses 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. - - - - - 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: - -> config show DhcpDdns/tsig_keys -DhcpDdns/tsig_keys [] list (default) - - We must first create a new key in the list: - -> config add DhcpDdns/tsig_keys - - Displaying the new element, reveals: - -> config show DhcpDdns/tsig_keys[0] -DhcpDdns/tsig_keys[0]/name "" string (default) -DhcpDdns/tsig_keys[0]/algorithm "HMAC-MD5" string (modified) -DhcpDdns/tsig_keys[0]/secret "" string (default) - - Now set all three values to match BIND9's key: - -> config set DhcpDdns/tsig_keys[0]/name "key.four.example.com" -> config set DhcpDdns/tsig_keys[0]/algorithm "HMAC-SHA224" -> config set DhcpDdns/tsig_keys[0]/secret "bZEG7Ow8OgAUPfLWV3aAUQ==" -> config commit - - - 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: - -> config show DhcpDdns/forward_ddns/ -DhcpDdns/forward_ddns/ddns_domains [] list (default) - - 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 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. - - - The 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. Currently - TSIG has not been implemented, so this value is ignored. - - - - - 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 first add a new domain - element: - -> config add DhcpDdns/forward_ddns/ddns_domains - - Displaying the DDNS Domain reveals this: - -> config show DhcpDdns/forward_ddns/ddns_domains[0] -DhcpDdns/forward_ddns/ddns_domains[0]/name "" string (default) -DhcpDdns/forward_ddns/ddns_domains[0]/key_name "" string (default) -DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers [] list (default) - - To set the domain's name to "other.example.com": - -> config set DhcpDdns/forward_ddns/ddns_domains[1]/name "other.example.com" -> config commit - - 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 - - The 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 first add a new server - element to the domain: - -> config add DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers - - Displaying the DNS Server element should appear as follows: - -> config show DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0] -DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]/hostname "" string (default) -DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]/ip_address "" string (default) -DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]/port 53 integer(default) - - As stated earlier, "hostname" is not yet supported so, the parameter - "ip_address" must be set to the address of the DNS server. If for - example the service is running at "172.88.99.10", then set it as - follows: - -> config set DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]/ip_address "172.88.99.10" -> config commit - - -
- -
- -
- -
- 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: - -> config show DhcpDdns/reverse_ddns/ -DhcpDdns/reverse_ddns/ddns_domains [] list (default) - - 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 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. - - - The 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 first add a new domain - element: - -> config add DhcpDdns/reverse_ddns/ddns_domains - - Displaying the DDNS Domain reveals this: - -> config show DhcpDdns/reverse_ddns/ddns_domains[0] -DhcpDdns/reverse_ddns/ddns_domains[0]/name "" string (default) -DhcpDdns/reverse_ddns/ddns_domains[0]/key_name "" string (default) -DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers [] list (default) - - For domain supporting the subnet 2001:db8:1::, we would set the - domain's name as follows: - -> config set DhcpDdns/reverse_ddns/ddns_domains[1]/name "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa." -> config commit - - 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 - - The section describes how to add DNS servers to a Reverse DDNS Domain. - Repeat them for as many servers as desired for a 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: - -> config add DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers - - Displaying the DNS Server element should appear as follows: - -> config show DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0] -DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/hostname "" string (default) -DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/ip_address "" string (default) -DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/port 53 integer(default) - - As stated earlier, "hostname" is not yet supported so, the parameter - "ip_address" must be set to the address of the DNS server. If for - example the service is running at "172.88.99.10", then set it as - follows: - -> config set DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/ip_address "172.88.99.10" -> config commit - - -
- -
- -
- -
- 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 series of commands in bindctl will create the Forward - DDNS Domains. - - -> config add DhcpDdns/forward_ddns/ddns_domains -> config set DhcpDdns/forward_ddns/ddns_domains[0]/name "four.example.com." -> config add DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers -> config set DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]/ip_address "172.16.1.5" -> config add DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers -> config set DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[1]/ip_address "172.16.2.5" -> -> config add DhcpDdns/forward_ddns/ddns_domains -> config set DhcpDdns/forward_ddns/ddns_domains[1]/name "six.example.com." -> config add DhcpDdns/forward_ddns/ddns_domains[1]/dns_servers -> config set DhcpDdns/forward_ddns/ddns_domains[1]/dns_servers[0]/ip_address "3001:1::50:" -> -> config add DhcpDdns/forward_ddns/ddns_domains -> config set DhcpDdns/forward_ddns/ddns_domains[2]/name "example.com." -> config add DhcpDdns/forward_ddns/ddns_domains[2]/dns_servers -> config set DhcpDdns/forward_ddns/ddns_domains[2]/dns_servers[0]/ip_address "172.16.2.5" -> -> config commit - - - - - 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. - - - The following series of commands in bindctl will create our Reverse - DDNS Domains. - - -> config add DhcpDdns/reverse_ddns/ddns_domains -> config set DhcpDdns/reverse_ddns/ddns_domains[0]/name "2.0.192.in-addr.arpa." -> config add DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers -> config set DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/ip_address "172.16.1.5" -> config add DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers -> config set DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[1]/ip_address "172.16.2.5" -> -> config add DhcpDdns/reverse_ddns/ddns_domains -> config set DhcpDdns/reverse_ddns/ddns_domains[1]/name "1.0.0.0.8.d.b.0.1.0.0.2.ip6.arpa." -> config add DhcpDdns/reverse_ddns/ddns_domains[1]/dns_servers -> config set DhcpDdns/reverse_ddns/ddns_domains[1]/dns_servers[0]/ip_address "3001:1::50:" -> -> config add DhcpDdns/reverse_ddns/ddns_domains -> config set DhcpDdns/reverse_ddns/ddns_domains[2]/name "0.192.in-addr.arpa." -> config add DhcpDdns/reverse_ddns/ddns_domains[2]/dns_servers -> config set DhcpDdns/reverse_ddns/ddns_domains[2]/dns_servers[0]/ip_address "172.16.2.5" -> -> config commit - - - -
-
-
- DHCP-DDNS Server Limitations - The following are the current limitations of the DHCP-DDNS Server. - - - - Requests received from the DHCP servers are placed in a - queue until they are processed. Currently all queued requests - are lost when the server shuts down. - - - - - TSIG Authentication (RFC 2845) - is not supported yet. - - - -
- - - - libdhcp++ library - - libdhcp++ is a common library written in C++ that handles - many DHCP-related tasks, including: - - - DHCPv4 and DHCPv6 packets parsing, manipulation and assembly - - - Option parsing, manipulation and assembly - - - Network interface detection - - - Socket operations such as creation, data transmission and reception and socket closing. - - - - - - While this library is currently used by Kea, it is designed to - be a portable, universal library, useful for any kind of DHCP-related software. - - - - -
- Interface detection and Socket handling - Both the DHCPv4 and DHCPv6 components share network - interface detection routines. Interface detection is - currently supported on Linux, all BSD family (FreeBSD, NetBSD, - OpenBSD), Mac OS X and Solaris 11 systems. - - DHCPv4 requires special raw socket processing to send and receive - packets from hosts that do not have IPv4 address assigned yet. Support - for this operation is implemented on Linux only, so it is likely that - DHCPv4 component will not work in certain cases on systems other than - Linux. -
- - - - + Acknowledgements + Support for the development of the DHCPv4, DHCPv6 and + DHCP-DDNS components was provided by + Comcast. + Kea was initially implemented as a collection of applications within the BIND 10 framework. Hence, Kea development would not be possible without the generous support of BIND 10 project sponsors. @@ -4414,10 +103,6 @@ DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/port 53 integer(default) - Support for the development of the DHCPv4, DHCPv6 and - DHCP-DDNS components is provided by - Comcast. - diff --git a/doc/guide/libdhcp.xml b/doc/guide/libdhcp.xml new file mode 100644 index 0000000000..1d0dbfadec --- /dev/null +++ b/doc/guide/libdhcp.xml @@ -0,0 +1,56 @@ + + +]> + + + libdhcp++ library + + libdhcp++ is a common library written in C++ that handles + many DHCP-related tasks, including: + + + DHCPv4 and DHCPv6 packets parsing, manipulation and assembly + + + Option parsing, manipulation and assembly + + + Network interface detection + + + Socket operations such as creation, data transmission and reception and socket closing. + + + + + + While this library is currently used by Kea, it is designed to + be a portable, universal library, useful for any kind of DHCP-related software. + + + + +
+ Interface detection and Socket handling + Both the DHCPv4 and DHCPv6 components share network + interface detection routines. Interface detection is + currently supported on Linux, all BSD family (FreeBSD, NetBSD, + OpenBSD), Mac OS X and Solaris 11 systems. + + DHCPv4 requires special raw socket processing to send and receive + packets from hosts that do not have IPv4 address assigned yet. Support + for this operation is implemented on Linux only, so it is likely that + DHCPv4 component will not work in certain cases on systems other than + Linux. +
+ + + + diff --git a/doc/guide/quickstart.xml b/doc/guide/quickstart.xml new file mode 100644 index 0000000000..12efe32aec --- /dev/null +++ b/doc/guide/quickstart.xml @@ -0,0 +1,105 @@ + + +]> + + + Quick start + + + This quickly covers the standard steps for installing and deploying Kea. + For further details, full customizations, and troubleshooting, see the + respective chapters in the Kea guide. + + +
+ Quick start guide for DHCPv4 and DHCPv6 services + + + + + + Install required run-time and build dependencies. See for details. + + + + + + + Checkout the latest Kea revision from the Git repository: + $ git clone git://git.kea.isc.org/kea + + + + + Go into the source and run configure: + $ cd kea +$ autoreconf --install +$ ./configure [your extra parameters] + + + + + Build it: + $ make + + + + + Install it as root (by default to prefix + /usr/local/): + $ make install + + + + + Edit your configuration file for DHCPv4. See doc/examples/kea4 + for a set of examples. + + + + + Start Kea DHCPv4 server (as root): + # b10-dhcp4 -c /path/to/your/kea4/config/file.json + + + + + Test it; for example, use the + ISC DHCP client + to send DHCPv4 queries to the server and verify that the client receives a + configuration from the server: + $ dhclient -4 eth0 + + + + + Edit your configuration file for DHCPv6. See doc/examples/kea6 + for a set of examples. + + + + + Start Kea DHCPv6 server (as root): + # b10-dhcp6 -c /path/to/your/kea6/config/file.json + + + + + Test it; for example, use the + ISC DHCP client + to send DHCPv6 queries to the server and verify that the client receives a + configuration from the server: + $ dhclient -6 eth0 + + + + + + +
+ +