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
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY mdash "—" >
+]>
+
+ <chapter id="dhcp-ddns-server">
+ <title>The DHCP-DDNS Server</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <section id="dhcp-ddns-server-start-stop">
+ <title>Starting and Stopping the DHCP-DDNS Server</title>
+ <para>
+ <command>b10-dhcp-ddns</command> is the BIND 10 DHCP-DDNS server and,
+ like other parts of BIND 10, is configured through the
+ <command>bindctl</command> program.
+ </para>
+ <para>
+ 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.
+<screen>
+> <userinput>config add Init/components b10-dhcp-ddns</userinput>
+> <userinput>config set Init/components/b10-dhcp-ddns/kind dispensable</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ </para>
+ <para>
+ To remove <command>b10-dhcp-ddns</command> from the set of running services,
+ the <command>b10-dhcp-ddns</command> is removed from list of Init components:
+<screen>
+> <userinput>config remove Init/components b10-dhcp-ddns</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ </para>
+ <para>
+ 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:
+ </para>
+<screen>
+> <userinput>DhcpDdns shutdown</userinput>
+</screen>
+ <para>
+ Upon start up the module will load its configuration and begin listening
+ for NCRs based on that configuration.
+ </para>
+ </section> <!-- end start-stop -->
+ <section id="d2-configuration">
+ <title>Configuring the DHCP-DDNS Server</title>
+ <para>
+ Once the server is started, it can be configured. To view the
+ current configuration, use the following command in <command>bindctl</command>:
+ <screen>
+> <userinput>config show DhcpDdns</userinput></screen>
+ When starting b10-dhcp-ddns module for the first time, the default
+ configuration will be available. It will look similar to this:
+<screen>
+> <userinput>config show DhcpDdns</userinput>
+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)
+</screen>
+ <para>
+ (While displayed, the parameter "interface" is not implemented, and
+ will be removed in the near future.)
+ </para>
+ </para>
+ <para>
+ The configuration can be divided as follows, each of which is described
+ in its own section:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <command>Global Server Parameters</command> —
+ values which control connectivity and global server behavior
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>TSIG Key Info</command> —
+ defines the TSIG keys used for secure traffic with DNS servers
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>Forward DDNS</command> —
+ defines the catalog of Forward DDNS Domains
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>Reverse DDNS</command> —
+ defines the catalog of Forward DDNS Domains
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ <section id="d2-server-parameter-config">
+ <title>Global Server Parameters</title>
+ <orderedlist>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ port - Port on which D2 listens for requests. The default value
+ is 53001.
+ </para></listitem>
+ <listitem><para>
+ ncr_format - Socket protocol to use when sending requests to D2.
+ Currently only UDP is supported. TCP may be available in an upcoming
+ release.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ </orderedlist>
+ <para>
+ 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:
+<screen>
+> <userinput>config set DhcpDdns/ip_address "192.168.1.10"</userinput>
+> <userinput>config set DhcpDdns/port 900</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ </para>
+ <warning>
+ <simpara>
+ 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.
+ </simpara>
+ </warning>
+<note>
+<simpara>
+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.
+</simpara>
+</note>
+ </section> <!-- "d2-server-parameter-config" -->
+
+ <section id="d2-tsig-key-list-config">
+ <title>TSIG Key List</title>
+ <para>
+ A DDNS protocol exchange can be conducted with or without TSIG
+ (defined in <ulink url="http://tools.ietf/org/html/rfc2845">RFC
+ 2845</ulink>). This configuration section allows the administrator
+ to define the set of TSIG keys that may be used in such
+ exchanges.</para>
+
+ <para>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.</para>
+
+ <para>
+ 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:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <command>name</command> —
+ 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.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>algorithm</command> —
+ 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:
+ <itemizedlist>
+ <listitem>
+ <command>HMAC-MD5</command>
+ </listitem>
+ <listitem>
+ <command>HMAC-SHA1</command>
+ </listitem>
+ <listitem>
+ <command>HMAC-SHA224</command>
+ </listitem>
+ <listitem>
+ <command>HMAC-SHA256</command>
+ </listitem>
+ <listitem>
+ <command>HMAC-SHA384</command>
+ </listitem>
+ <listitem>
+ <command>HMAC-SHA512</command>
+ </listitem>
+ </itemizedlist>
+ This value is not case sensitive.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>secret</command> —
+ 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.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ 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:
+<screen>
+ :
+ key "key.four.example.com." {
+ algorithm hmac-sha224;
+ secret "bZEG7Ow8OgAUPfLWV3aAUQ==";
+ };
+ :
+</screen>
+ By default, the TSIG Key list is empty:
+<screen>
+<userinput>> config show DhcpDdns/tsig_keys</userinput>
+DhcpDdns/tsig_keys [] list (default)
+</screen>
+ We must first create a new key in the list:
+<screen>
+<userinput>> config add DhcpDdns/tsig_keys</userinput>
+</screen>
+ Displaying the new element, reveals:
+<screen>
+<userinput>> config show DhcpDdns/tsig_keys[0]</userinput>
+DhcpDdns/tsig_keys[0]/name "" string (default)
+DhcpDdns/tsig_keys[0]/algorithm "HMAC-MD5" string (modified)
+DhcpDdns/tsig_keys[0]/secret "" string (default)
+</screen>
+ Now set all three values to match BIND9's key:
+<screen>
+<userinput>> config set DhcpDdns/tsig_keys[0]/name "key.four.example.com"</userinput>
+<userinput>> config set DhcpDdns/tsig_keys[0]/algorithm "HMAC-SHA224"</userinput>
+<userinput>> config set DhcpDdns/tsig_keys[0]/secret "bZEG7Ow8OgAUPfLWV3aAUQ=="</userinput>
+<userinput>> config commit</userinput>
+</screen>
+ </para>
+ These steps would be repeated for each TSIG key needed. Note that the same TSIG key
+ can be used with more than one domain.
+ </section> <!-- "d2-tsig-key-list-config" -->
+
+ <section id="d2-forward-ddns-config">
+ <title>Forward DDNS</title>
+ <para>
+ 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:
+<screen>
+<userinput>> config show DhcpDdns/forward_ddns/</userinput>
+DhcpDdns/forward_ddns/ddns_domains [] list (default)
+</screen>
+ By default, this list is empty, which will cause the server to ignore
+ the forward update portions of requests.
+ </para>
+ <section id="add-forward-ddns-domain">
+ <title>Adding Forward DDNS Domains</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <command>name</command> —
+ 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.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>key_name</command> —
+ 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.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>dns_servers</command> —
+ 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.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ To create a new forward DDNS Domain, one must first add a new domain
+ element:
+<screen>
+<userinput>> config add DhcpDdns/forward_ddns/ddns_domains</userinput>
+</screen>
+ Displaying the DDNS Domain reveals this:
+<screen>
+<userinput>> config show DhcpDdns/forward_ddns/ddns_domains[0]</userinput>
+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)
+</screen>
+ To set the domain's name to "other.example.com":
+<screen>
+<userinput>> config set DhcpDdns/forward_ddns/ddns_domains[1]/name "other.example.com"</userinput>
+<userinput>> config commit</userinput>
+</screen>
+ 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.
+ </para>
+
+ <section id="add-forward-dns-servers">
+ <title>Adding Forward DNS Servers</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <command>hostname</command> —
+ The resolvable host name of the DNS server. This value is not
+ yet implemented.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>ip_address</command> —
+ The IP address at which the server listens for DDNS requests.
+ This may be either an IPv4 or an IPv6 address.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>port</command> —
+ The port on which the server listens for DDNS requests. It
+ defaults to the standard DNS service port of 53.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ To create a new forward DNS Server, one must first add a new server
+ element to the domain:
+<screen>
+<userinput>> config add DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers</userinput>
+</screen>
+ Displaying the DNS Server element should appear as follows:
+<screen>
+<userinput>> config show DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]</userinput>
+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)
+</screen>
+ 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:
+<screen>
+<userinput>> config set DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]/ip_address "172.88.99.10"</userinput>
+<userinput>> config commit</userinput>
+</screen>
+ </para>
+ </section> <!-- "add-forward-dns-servers" -->
+
+ </section> <!-- "add-forward-ddns-domains" -->
+
+ </section> <!-- "d2-forward-ddns-config" -->
+
+ <section id="d2-reverse-ddns-config">
+ <title>Reverse DDNS</title>
+ <para>
+ 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:
+<screen>
+<userinput>> config show DhcpDdns/reverse_ddns/</userinput>
+DhcpDdns/reverse_ddns/ddns_domains [] list (default)
+</screen>
+ By default, this list is empty, which will cause the server to ignore
+ the reverse update portions of requests.
+ </para>
+ <section id="add-reverse-ddns-domain">
+ <title>Adding Reverse DDNS Domains</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <command>name</command> —
+ 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.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>key_name</command> —
+ 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.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>dns_servers</command> —
+ 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.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ To create a new reverse DDNS Domain, one must first add a new domain
+ element:
+<screen>
+<userinput>> config add DhcpDdns/reverse_ddns/ddns_domains</userinput>
+</screen>
+ Displaying the DDNS Domain reveals this:
+<screen>
+<userinput>> config show DhcpDdns/reverse_ddns/ddns_domains[0]</userinput>
+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)
+</screen>
+ For domain supporting the subnet 2001:db8:1::, we would set the
+ domain's name as follows:
+<screen>
+<userinput>> config set DhcpDdns/reverse_ddns/ddns_domains[1]/name "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa."</userinput>
+<userinput>> config commit</userinput>
+</screen>
+ 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.
+ </para>
+
+ <section id="add-reverse-dns-servers">
+ <title>Adding Reverse DNS Servers</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <command>hostname</command> —
+ The resolvable host name of the DNS server. This value is
+ currently ignored.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>ip_address</command> —
+ The IP address at which the server listens for DDNS requests.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>port</command> —
+ The port on which the server listens for DDNS requests. It
+ defaults to the standard DNS service port of 53.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ To create a new reverse DNS Server, one must first add a new server
+ element to the domain:
+<screen>
+<userinput>> config add DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers</userinput>
+</screen>
+ Displaying the DNS Server element should appear as follows:
+<screen>
+<userinput>> config show DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]</userinput>
+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)
+</screen>
+ 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:
+<screen>
+<userinput>> config set DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/ip_address "172.88.99.10"</userinput>
+<userinput>> config commit</userinput>
+</screen>
+ </para>
+ </section> <!-- "add-reverse-dns-servers" -->
+
+ </section> <!-- "add-reverse-ddns-domains" -->
+
+ </section> <!-- "d2-reverse-ddns-config" -->
+
+ <section id="d2-exmaple-config">
+ <title>Example DHCP-DDNS Server Configuration</title>
+ <para>
+ 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.
+
+ <table>
+ <title>Our example network</title>
+ <tgroup cols='4' align='left'>
+ <colspec colname='domain'/>
+ <colspec colname='subnet'/>
+ <colspec colname='fservers'/>
+ <colspec colname='rservers'/>
+ <thead>
+ <row>
+ <entry>Domain</entry>
+ <entry>Subnet</entry>
+ <entry>Forward DNS Servers</entry>
+ <entry>Reverse DNS Servers</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>four.example.com</entry>
+ <entry>192.0.2.0/24</entry>
+ <entry>172.16.1.5, 172.16.2.5</entry>
+ <entry>172.16.1.5, 172.16.2.5</entry>
+ </row>
+ <row>
+ <entry>six.example.com</entry>
+ <entry>2001:db8:1::/64</entry>
+ <entry>3001:1::50</entry>
+ <entry>3001:1::51</entry>
+ </row>
+ <row>
+ <entry>example.com</entry>
+ <entry>192.0.0.0/16</entry>
+ <entry>172.16.2.5</entry>
+ <entry>172.16.2.5</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ <para>
+ We need to construct three forward DDNS Domains:
+ <table>
+ <title>Forward DDNS Domains Needed</title>
+ <tgroup cols='3' align='left'>
+ <colspec colname='num'/>
+ <colspec colname='name'/>
+ <colspec colname='servers'/>
+ <thead>
+ <row>
+ <entry>#</entry>
+ <entry>DDNS Domain Name</entry>
+ <entry>DNS Servers</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>1.</entry>
+ <entry>four.example.com.</entry>
+ <entry>172.16.1.5, 172.16.2.5</entry>
+ </row>
+ <row>
+ <entry>2.</entry>
+ <entry>six.example.com.</entry>
+ <entry>3001:1::50</entry>
+ </row>
+ <row>
+ <entry>3.</entry>
+ <entry>example.com.</entry>
+ <entry>172.16.2.5</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ 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.
+ </para>
+ <para>
+ The following series of commands in bindctl will create the Forward
+ DDNS Domains.
+<screen>
+<userinput>
+> 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
+</userinput>
+</screen>
+ </para>
+ <para>
+ Similarly, we need to construct the three reverse DDNS Domains:
+ <table>
+ <title>Reverse DDNS Domains Needed</title>
+ <tgroup cols='3' align='left'>
+ <colspec colname='num'/>
+ <colspec colname='DDNS Domain name'/>
+ <colspec colname='DDNS Domain DNS Servers'/>
+ <thead>
+ <row>
+ <entry>#</entry>
+ <entry>DDNS Domain Name</entry>
+ <entry>DNS Servers</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>1.</entry>
+ <entry>2.0.192.in-addr.arpa.</entry>
+ <entry>172.16.1.5, 172.16.2.5</entry>
+ </row>
+ <row>
+ <entry>2.</entry>
+ <entry>1.0.0.0.8.d.b.0.1.0.0.2.ip6.arpa.</entry>
+ <entry>3001:1::50</entry>
+ </row>
+ <row>
+ <entry>3.</entry>
+ <entry>0.182.in-addr.arpa.</entry>
+ <entry>172.16.2.5</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ 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.
+ </para>
+ <para>
+ The following series of commands in bindctl will create our Reverse
+ DDNS Domains.
+<screen>
+<userinput>
+> 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
+</userinput>
+</screen>
+ </para>
+ </section> <!-- end of "d2-example" -->
+ </section> <!-- end of section "d2-configuration" -->
+ <section>
+ <title>DHCP-DDNS Server Limitations</title>
+ <para>The following are the current limitations of the DHCP-DDNS Server.</para>
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ 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.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ TSIG Authentication (<ulink
+ url="http://tools.ietf.org/html/rfc2845">RFC 2845</ulink>)
+ is not supported yet.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </chapter> <!-- DHCP-DDNS Server -->
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY mdash "—" >
+]>
+
+ <chapter id="dhcp4">
+ <title>The DHCPv4 Server</title>
+
+ <section id="dhcp4-start-stop">
+ <title>Starting and Stopping the DHCPv4 Server</title>
+
+ <para>
+ <command>b10-dhcp4</command> is the Kea DHCPv4 server and is configured
+ through the <command>bindctl</command> program.
+ </para>
+ <para>
+ After starting <command>bind10</command> and entering bindctl, the first step
+ in configuring the server is to add it to the list of running services.
+<screen>
+> <userinput>config add Init/components b10-dhcp4</userinput>
+> <userinput>config set Init/components/b10-dhcp4/kind dispensable</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ </para>
+ <para>
+ To remove <command>b10-dhcp4</command> from the set of running services,
+ the <command>b10-dhcp4</command> is removed from list of Init components:
+<screen>
+> <userinput>config remove Init/components b10-dhcp4</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ </para>
+ <para>
+ 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:
+<screen>
+> <userinput>Dhcp4 shutdown</userinput>
+</screen>
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ </section>
+
+ <section id="dhcp4-configuration">
+ <title>Configuring the DHCPv4 Server</title>
+ <para>
+ Once the server is started, it can be configured. To view the
+ current configuration, use the following command in <command>bindctl</command>:
+ <screen>
+> <userinput>config show Dhcp4</userinput></screen>
+ When starting the DHCPv4 daemon for the first time, the default configuration
+ will be available. It will look similar to this:
+<screen>
+> <userinput>config show Dhcp4</userinput>
+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
+</screen>
+ </para>
+
+ <para>
+ To change one of the parameters, simply follow
+ the usual <command>bindctl</command> procedure. For example, to make the
+ leases longer, change their valid-lifetime parameter:
+ <screen>
+> <userinput>config set Dhcp4/valid-lifetime 7200</userinput>
+> <userinput>config commit</userinput></screen>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+
+ <section>
+ <title>Default storage for leases</title>
+ <para>
+ The server is able to store lease data in different repositories. Larger deployments
+ may elect to store leases in a database.
+ <xref linkend="database-configuration4"/> 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ It is possible to alter the default location of the lease file. The following
+ configuration:
+<screen>
+> <userinput>config set Dhcp4/lease-database/type "memfile"</userinput>
+> <userinput>config set Dhcp4/lease-database/persist true</userinput>
+> <userinput>config set Dhcp4/lease-database/name "/tmp/kea-leases4.csv"</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ will change the default location of the lease file to /tmp/kea-leases4.csv.
+ </para>
+ <para>
+ 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
+ </para>
+ </section>
+
+ <section id="database-configuration4">
+ <title>Database Configuration</title>
+ <para>
+ All leases issued by the server are stored in the lease database. Currently
+ there are 3 database backends available: MySQL, PostgreSQL and memfile.
+ <footnote>
+ <para>
+ 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.
+ </para>
+ </footnote>, and so the server must be configured to
+ access the correct database with the appropriate credentials.
+ </para>
+ <note>
+ <para>
+ 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.
+ </para>
+ </note>
+ <para>
+ Database configuration is controlled through the Dhcp4/lease-database parameters.
+ The type of the database must be set to "mysql", "postgresql" or "memfile":
+<screen>
+> <userinput>config set Dhcp4/lease-database/type "mysql"</userinput>
+</screen>
+ 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 <xref linkend="dhcp-mysql-database-create"/>
+ or <xref linkend="dhcp-pgsql-database-create"/>).
+<screen>
+> <userinput>config set Dhcp4/lease-database/name "<replaceable>database-name</replaceable>"</userinput>
+</screen>
+ 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):
+<screen>
+> <userinput>config set Dhcp4/lease-database/host "<replaceable>remote-host-name</replaceable>"</userinput>
+</screen>
+ 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):
+<screen>
+> <userinput>config set Dhcp4/lease-database/host ""</userinput>
+</screen>
+ </para>
+ <para>
+ Finally, the credentials of the account under which the server will access the database
+ should be set:
+<screen>
+> <userinput>config set Dhcp4/lease-database/user "<replaceable>user-name</replaceable>"</userinput>
+> <userinput>config set Dhcp4/lease-database/password "<replaceable>password</replaceable>"</userinput>
+</screen>
+ If there is no password to the account, set the password to the empty string "". (This is also the default.)
+ </para>
+ <note>
+ <para>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.</para>
+ </note>
+ </section>
+
+ <section id="dhcp4-interface-selection">
+ <title>Interface selection</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ The default configuration can be presented with the following command:
+ <screen>
+> <userinput>config show Dhcp4/interfaces</userinput>
+<userinput>Dhcp4/interfaces[0] "*" string</userinput></screen>
+ An asterisk sign plays a role of the wildcard and means "listen on all interfaces".
+ </para>
+ <para>
+ In order to override the default configuration, the existing entry can be replaced
+ with the actual interface name:
+ <screen>
+> <userinput>config set Dhcp4/interfaces[0] eth1</userinput>
+> <userinput>config commit</userinput></screen>
+ Other interface names can be added on one-by-one basis:
+ <screen>
+> <userinput>config add Dhcp4/interfaces eth2</userinput>
+> <userinput>config commit</userinput></screen>
+ Configuration will now contain two interfaces which can be presented as follows:
+ <screen>
+> <userinput>config show Dhcp4/interfaces</userinput>
+<userinput>Dhcp4/interfaces[0] "eth1" string</userinput>
+<userinput>Dhcp4/interfaces[1] "eth2" string</userinput></screen>
+ When configuration gets committed, the server will start to listen on
+ eth1 and eth2 interfaces only.
+ </para>
+ <para>
+ It is possible to use wildcard interface name (asterisk) concurrently with explicit
+ interface names:
+ <screen>
+> <userinput>config add Dhcp4/interfaces *</userinput>
+> <userinput>config commit</userinput></screen>
+ This will result in the following configuration:
+ <screen>
+> <userinput>config show Dhcp4/interfaces</userinput>
+<userinput>Dhcp4/interfaces[0] "eth1" string</userinput>
+<userinput>Dhcp4/interfaces[1] "eth2" string</userinput>
+<userinput>Dhcp4/interfaces[2] "*" string</userinput></screen>
+ 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:
+ <screen>
+> <userinput>config remove Dhcp4/interfaces[2]</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+ </section>
+
+ <section id="ipv4-subnet-id">
+ <title>IPv4 Subnet Identifier</title>
+ <para>
+ 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 ....
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ The following configuration:
+ <screen>
+> <userinput>config add Dhcp4/subnet4</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24"</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/id 1024</userinput>
+> <userinput>config commit</userinput>
+ </screen>
+ 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.
+ </para>
+ </section>
+
+ <section id="dhcp4-address-config">
+ <title>Configuration of IPv4 Address Pools</title>
+ <para>
+ 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:
+ <screen>
+> <userinput>config add Dhcp4/subnet4</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24"</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/pool [ "192.0.2.10 - 192.0.2.20" ]</userinput>
+> <userinput>config commit</userinput></screen>
+ 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.</para>
+ <para>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:
+ <screen>
+> <userinput>config set Dhcp4/subnet4[0]/pool [ "192.0.2.10-192.0.2.20", "192.0.2.64/26" ]</userinput>
+> <userinput>config commit</userinput></screen>
+ 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.
+ </para>
+ <para>
+ The server may be configured to serve more than one subnet. To add a second subnet,
+ use a command similar to the following:
+ <screen>
+> <userinput>config add Dhcp4/subnet4</userinput>
+> <userinput>config set Dhcp4/subnet4[1]/subnet "192.0.3.0/24"</userinput>
+> <userinput>config set Dhcp4/subnet4[1]/pool [ "192.0.3.0/24" ]</userinput>
+> <userinput>config commit</userinput></screen>
+ Arrays are counted from 0. subnet[0] refers to the subnet defined in the
+ previous example. The <command>config add Dhcp4/subnet4</command> command adds
+ another (second) subnet. It can be referred to as
+ <command>Dhcp4/subnet4[1]</command>. In this example, we allow server to
+ dynamically assign all addresses available in the whole subnet.
+ </para>
+ <para>
+ 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.
+ </para>
+ </section>
+
+ <section id="dhcp4-std-options">
+ <title>Standard DHCPv4 options</title>
+ <para>
+ 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.
+
+ <screen>
+> <userinput>config add Dhcp4/option-data</userinput>
+> <userinput>config set Dhcp4/option-data[0]/name "domain-name-servers"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/code 6</userinput>
+> <userinput>config set Dhcp4/option-data[0]/space "dhcp4"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
+> <userinput>config set Dhcp4/option-data[0]/data "192.0.3.1, 192.0.3.2"</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ </para>
+ <para>
+ 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 <xref linkend="dhcp4-std-options-list"/> 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 <xref
+ linkend="dhcp4-option-spaces"/>. 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.
+ </para>
+
+ <para>
+ 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.
+ <screen>
+> <userinput>config add Dhcp4/option-data</userinput>
+> <userinput>config set Dhcp4/option-data[0]/name "domain-name-servers"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/code 6</userinput>
+> <userinput>config set Dhcp4/option-data[0]/space "dhcp4"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/csv-format false</userinput>
+> <userinput>config set Dhcp4/option-data[0]/data "C0 00 03 01 C0 00 03 02"</userinput>
+> <userinput>config commit</userinput>
+ </screen>
+ </para>
+
+ <para>
+ 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]).
+ </para>
+ <para>
+ The following commands override the global
+ DNS servers option for a particular subnet, setting a single DNS
+ server with address 192.0.2.3.
+ <screen>
+> <userinput>config add Dhcp4/subnet4[0]/option-data</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/option-data[0]/name "domain-name-servers"</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/option-data[0]/code 6</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/option-data[0]/space "dhcp4"</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/option-data[0]/csv-format true</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/option-data[0]/data "192.0.2.3"</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+
+ <note>
+ <para>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.</para>
+ </note>
+
+ <para>
+ The currently supported standard DHCPv4 options are
+ listed in <xref linkend="dhcp4-std-options-list"/>
+ and <xref linkend="dhcp4-std-options-list-part2"/>.
+ 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 <xref linkend="dhcp-types"/>.
+ </para>
+ <para>
+ 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.
+ </para>
+ <!-- @todo: describe record types -->
+
+ <para>
+ The <xref linkend="dhcp4-custom-options"/> 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
+ <xref linkend="dhcp4-custom-options"/> 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.
+ </para>
+
+ <para>
+ <table frame="all" id="dhcp4-std-options-list">
+ <title>List of standard DHCPv4 options</title>
+ <tgroup cols='4'>
+ <colspec colname='name'/>
+ <colspec colname='code'/>
+ <colspec colname='type'/>
+ <colspec colname='array'/>
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Code</entry>
+ <entry>Type</entry>
+ <entry>Array?</entry>
+ </row>
+ </thead>
+ <tbody>
+<row><entry>subnet-mask</entry><entry>1</entry><entry>ipv4-address</entry><entry>false</entry></row>
+<row><entry>time-offset</entry><entry>2</entry><entry>int32</entry><entry>false</entry></row>
+<row><entry>routers</entry><entry>3</entry><entry>ipv4-address</entry><entry>true</entry></row>
+<row><entry>time-servers</entry><entry>4</entry><entry>ipv4-address</entry><entry>true</entry></row>
+<row><entry>name-servers</entry><entry>5</entry><entry>ipv4-address</entry><entry>false</entry></row>
+<row><entry>domain-name-servers</entry><entry>6</entry><entry>ipv4-address</entry><entry>true</entry></row>
+<row><entry>log-servers</entry><entry>7</entry><entry>ipv4-address</entry><entry>true</entry></row>
+<row><entry>cookie-servers</entry><entry>8</entry><entry>ipv4-address</entry><entry>true</entry></row>
+<row><entry>lpr-servers</entry><entry>9</entry><entry>ipv4-address</entry><entry>true</entry></row>
+<row><entry>impress-servers</entry><entry>10</entry><entry>ipv4-address</entry><entry>true</entry></row>
+<row><entry>resource-location-servers</entry><entry>11</entry><entry>ipv4-address</entry><entry>true</entry></row>
+<row><entry>host-name</entry><entry>12</entry><entry>string</entry><entry>false</entry></row>
+<row><entry>boot-size</entry><entry>13</entry><entry>uint16</entry><entry>false</entry></row>
+<row><entry>merit-dump</entry><entry>14</entry><entry>string</entry><entry>false</entry></row>
+<row><entry>domain-name</entry><entry>15</entry><entry>fqdn</entry><entry>false</entry></row>
+<row><entry>swap-server</entry><entry>16</entry><entry>ipv4-address</entry><entry>false</entry></row>
+<row><entry>root-path</entry><entry>17</entry><entry>string</entry><entry>false</entry></row>
+<row><entry>extensions-path</entry><entry>18</entry><entry>string</entry><entry>false</entry></row>
+<row><entry>ip-forwarding</entry><entry>19</entry><entry>boolean</entry><entry>false</entry></row>
+<row><entry>non-local-source-routing</entry><entry>20</entry><entry>boolean</entry><entry>false</entry></row>
+<row><entry>policy-filter</entry><entry>21</entry><entry>ipv4-address</entry><entry>true</entry></row>
+<row><entry>max-dgram-reassembly</entry><entry>22</entry><entry>uint16</entry><entry>false</entry></row>
+<row><entry>default-ip-ttl</entry><entry>23</entry><entry>uint8</entry><entry>false</entry></row>
+<row><entry>path-mtu-aging-timeout</entry><entry>24</entry><entry>uint32</entry><entry>false</entry></row>
+<row><entry>path-mtu-plateau-table</entry><entry>25</entry><entry>uint16</entry><entry>true</entry></row>
+<row><entry>interface-mtu</entry><entry>26</entry><entry>uint16</entry><entry>false</entry></row>
+<row><entry>all-subnets-local</entry><entry>27</entry><entry>boolean</entry><entry>false</entry></row>
+<row><entry>broadcast-address</entry><entry>28</entry><entry>ipv4-address</entry><entry>false</entry></row>
+<row><entry>perform-mask-discovery</entry><entry>29</entry><entry>boolean</entry><entry>false</entry></row>
+<row><entry>mask-supplier</entry><entry>30</entry><entry>boolean</entry><entry>false</entry></row>
+<row><entry>router-discovery</entry><entry>31</entry><entry>boolean</entry><entry>false</entry></row>
+<row><entry>router-solicitation-address</entry><entry>32</entry><entry>ipv4-address</entry><entry>false</entry></row>
+<row><entry>static-routes</entry><entry>33</entry><entry>ipv4-address</entry><entry>true</entry></row>
+<row><entry>trailer-encapsulation</entry><entry>34</entry><entry>boolean</entry><entry>false</entry></row>
+<row><entry>arp-cache-timeout</entry><entry>35</entry><entry>uint32</entry><entry>false</entry></row>
+<row><entry>ieee802-3-encapsulation</entry><entry>36</entry><entry>boolean</entry><entry>false</entry></row>
+<row><entry>default-tcp-ttl</entry><entry>37</entry><entry>uint8</entry><entry>false</entry></row>
+<row><entry>tcp-keepalive-internal</entry><entry>38</entry><entry>uint32</entry><entry>false</entry></row>
+<row><entry>tcp-keepalive-garbage</entry><entry>39</entry><entry>boolean</entry><entry>false</entry></row>
+
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+ <para>
+ <table frame="all" id="dhcp4-std-options-list-part2">
+ <title>List of standard DHCPv4 options (continued)</title>
+ <tgroup cols='4'>
+ <colspec colname='name'/>
+ <colspec colname='code'/>
+ <colspec colname='type'/>
+ <colspec colname='array'/>
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Code</entry>
+ <entry>Type</entry>
+ <entry>Array?</entry>
+ </row>
+ </thead>
+ <tbody>
+
+<row><entry>nis-domain</entry><entry>40</entry><entry>string</entry><entry>false</entry></row>
+<row><entry>nis-servers</entry><entry>41</entry><entry>ipv4-address</entry><entry>true</entry></row>
+<row><entry>ntp-servers</entry><entry>42</entry><entry>ipv4-address</entry><entry>true</entry></row>
+<row><entry>vendor-encapsulated-options</entry><entry>43</entry><entry>empty</entry><entry>false</entry></row>
+<row><entry>netbios-name-servers</entry><entry>44</entry><entry>ipv4-address</entry><entry>true</entry></row>
+<row><entry>netbios-dd-server</entry><entry>45</entry><entry>ipv4-address</entry><entry>true</entry></row>
+<row><entry>netbios-node-type</entry><entry>46</entry><entry>uint8</entry><entry>false</entry></row>
+<row><entry>netbios-scope</entry><entry>47</entry><entry>string</entry><entry>false</entry></row>
+<row><entry>font-servers</entry><entry>48</entry><entry>ipv4-address</entry><entry>true</entry></row>
+<row><entry>x-display-manager</entry><entry>49</entry><entry>ipv4-address</entry><entry>true</entry></row>
+<row><entry>dhcp-requested-address</entry><entry>50</entry><entry>ipv4-address</entry><entry>false</entry></row>
+<!-- Lease time should not be configured by a user.
+<row><entry>dhcp-lease-time</entry><entry>51</entry><entry>uint32</entry><entry>false</entry></row>
+-->
+<row><entry>dhcp-option-overload</entry><entry>52</entry><entry>uint8</entry><entry>false</entry></row>
+<!-- Message Type, Server Identifier and Parameter Request List should not be configured by a user.
+<row><entry>dhcp-message-type</entry><entry>53</entry><entry>uint8</entry><entry>false</entry></row>
+<row><entry>dhcp-server-identifier</entry><entry>54</entry><entry>ipv4-address</entry><entry>false</entry></row>
+<row><entry>dhcp-parameter-request-list</entry><entry>55</entry><entry>uint8</entry><entry>true</entry></row>
+-->
+<row><entry>dhcp-message</entry><entry>56</entry><entry>string</entry><entry>false</entry></row>
+<row><entry>dhcp-max-message-size</entry><entry>57</entry><entry>uint16</entry><entry>false</entry></row>
+<!-- Renewal and rebinding time should not be configured by a user.
+<row><entry>dhcp-renewal-time</entry><entry>58</entry><entry>uint32</entry><entry>false</entry></row>
+<row><entry>dhcp-rebinding-time</entry><entry>59</entry><entry>uint32</entry><entry>false</entry></row>
+-->
+<row><entry>vendor-class-identifier</entry><entry>60</entry><entry>binary</entry><entry>false</entry></row>
+<!-- Client identifier should not be configured by a user.
+<row><entry>dhcp-client-identifier</entry><entry>61</entry><entry>binary</entry><entry>false</entry></row>
+-->
+<row><entry>nwip-domain-name</entry><entry>62</entry><entry>string</entry><entry>false</entry></row>
+<row><entry>nwip-suboptions</entry><entry>63</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>tftp-server-name</entry><entry>66</entry><entry>string</entry><entry>false</entry></row>
+<row><entry>boot-file-name</entry><entry>67</entry><entry>string</entry><entry>false</entry></row>
+<row><entry>user-class</entry><entry>77</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>fqdn</entry><entry>81</entry><entry>record</entry><entry>false</entry></row>
+<row><entry>dhcp-agent-options</entry><entry>82</entry><entry>empty</entry><entry>false</entry></row>
+<row><entry>authenticate</entry><entry>90</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>client-last-transaction-time</entry><entry>91</entry><entry>uint32</entry><entry>false</entry></row>
+<row><entry>associated-ip</entry><entry>92</entry><entry>ipv4-address</entry><entry>true</entry></row>
+<row><entry>subnet-selection</entry><entry>118</entry><entry>ipv4-address</entry><entry>false</entry></row>
+<row><entry>domain-search</entry><entry>119</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>vivco-suboptions</entry><entry>124</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>vivso-suboptions</entry><entry>125</entry><entry>binary</entry><entry>false</entry></row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </para>
+ <para>
+ <table frame="all" id="dhcp-types">
+ <title>List of standard DHCP option types</title>
+ <tgroup cols='2'>
+ <colspec colname='name'/>
+ <colspec colname='meaning'/>
+ <thead>
+ <row><entry>Name</entry><entry>Meaning</entry></row>
+ </thead>
+ <tbody>
+ <row><entry>binary</entry><entry>An arbitrary string of bytes, specified as a set of hexadecimal digits.</entry></row>
+ <row><entry>boolean</entry><entry>Boolean value with allowed values true or false</entry></row>
+ <row><entry>empty</entry><entry>No value, data is carried in suboptions</entry></row>
+ <row><entry>fqdn</entry><entry>Fully qualified domain name (e.g. www.example.com)</entry></row>
+ <row><entry>ipv4-address</entry><entry>IPv4 address in the usual dotted-decimal notation (e.g. 192.0.2.1)</entry></row>
+ <row><entry>ipv6-address</entry><entry>IPv6 address in the usual colon notation (e.g. 2001:db8::1)</entry></row>
+ <row><entry>record</entry><entry>Structured data that may comprise any types (except "record" and "empty")</entry></row>
+ <row><entry>string</entry><entry>Any text</entry></row>
+ <row><entry>uint8</entry><entry>8 bit unsigned integer with allowed values 0 to 255</entry></row>
+ <row><entry>uint16</entry><entry>16 bit unsinged integer with allowed values 0 to 65535</entry></row>
+ <row><entry>uint32</entry><entry>32 bit unsigned integer with allowed values 0 to 4294967295</entry></row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </section>
+
+ <section id="dhcp4-custom-options">
+ <title>Custom DHCPv4 options</title>
+ <para>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:
+ <screen>
+> <userinput>config add Dhcp4/option-def</userinput>
+> <userinput>config set Dhcp4/option-def[0]/name "foo"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/code 222</userinput>
+> <userinput>config set Dhcp4/option-def[0]/type "uint32"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/array false</userinput>
+> <userinput>config set Dhcp4/option-def[0]/record-types ""</userinput>
+> <userinput>config set Dhcp4/option-def[0]/space "dhcp4"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/encapsulate ""</userinput>
+> <userinput>config commit</userinput></screen>
+ 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.
+ </para>
+ <note>
+ <para>
+ 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.
+ </para>
+ </note>
+
+ <para>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.
+ <screen>
+> <userinput>config add Dhcp4/option-data</userinput>
+> <userinput>config set Dhcp4/option-data[0]/name "foo"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/code 222</userinput>
+> <userinput>config set Dhcp4/option-data[0]/space "dhcp4"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
+> <userinput>config set Dhcp4/option-data[0]/data "12345"</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+
+ <para>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.
+ </para>
+ <para>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:
+<screen>
+> <userinput>config add Dhcp4/option-def</userinput>
+> <userinput>config set Dhcp4/option-def[0]/name "bar"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/code 223</userinput>
+> <userinput>config set Dhcp4/option-def[0]/space "dhcp4"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/type "record"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/array false</userinput>
+> <userinput>config set Dhcp4/option-def[0]/record-types "ipv4-address, uint16, boolean, string"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/encapsulate ""</userinput>
+</screen>
+ 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 <xref linkend="dhcp-types"/>.
+ </para>
+ <para>
+ The values of the option are set as follows:
+<screen>
+> <userinput>config add Dhcp4/option-data</userinput>
+> <userinput>config set Dhcp4/option-data[0]/name "bar"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/space "dhcp4"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/code 223</userinput>
+> <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
+> <userinput>config set Dhcp4/option-data[0]/data "192.0.2.100, 123, true, Hello World"</userinput>
+> <userinput>config commit</userinput></screen>
+ "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.
+ </para>
+ <note>
+ <para>
+ 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.
+ </para>
+ </note>
+ </section>
+
+ <section id="dhcp4-vendor-opts">
+ <title>DHCPv4 vendor specific options</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ The first step is to define the format of the option:
+<screen>
+> <userinput>config add Dhcp4/option-def</userinput>
+> <userinput>config set Dhcp4/option-def[0]/name "foo"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/code 1</userinput>
+> <userinput>config set Dhcp4/option-def[0]/space "vendor-encapsulated-options-space"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/type "record"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/array false</userinput>
+> <userinput>config set Dhcp4/option-def[0]/record-types "ipv4-address, uint16, string"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/encapsulates ""</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ (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:
+ <screen>
+> <userinput>config add Dhcp4/option-data</userinput>
+> <userinput>config set Dhcp4/option-data[0]/name "foo"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/space "vendor-encapsulated-options-space"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/code 1</userinput>
+> <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
+> <userinput>config set Dhcp4/option-data[0]/data "192.0.2.3, 123, Hello World"</userinput>
+> <userinput>config commit</userinput></screen>
+ 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.
+ <screen>
+> <userinput>config add Dhcp4/option-data</userinput>
+> <userinput>config set Dhcp4/option-data[1]/name "vendor-encapsulated-options"</userinput>
+> <userinput>config set Dhcp4/option-data[1]/space "dhcp4"</userinput>
+> <userinput>config set Dhcp4/option-data[1]/code 43</userinput>
+> <userinput>config set Dhcp4/option-data[1]/csv-format false</userinput>
+> <userinput>config set Dhcp4/option-data[1]/data ""</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+
+ <note>
+ <para>
+ 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.
+ </para>
+ </note>
+
+ </section>
+
+ <section id="dhcp4-option-spaces">
+
+ <title>Nested DHCPv4 options (custom option spaces)</title>
+ <para>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.
+ </para>
+ <para>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 <xref linkend="dhcp4-vendor-opts"/>).
+ </para>
+ <para>
+ 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:
+<screen>
+> <userinput>config add Dhcp4/option-def</userinput>
+> <userinput>config set Dhcp4/option-def[0]/name "subopt1"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/code 1</userinput>
+> <userinput>config set Dhcp4/option-def[0]/space "isc"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/type "ipv4-address"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/record-types ""</userinput>
+> <userinput>config set Dhcp4/option-def[0]/array false</userinput>
+> <userinput>config set Dhcp4/option-def[0]/encapsulate ""</userinput>
+> <userinput>config commit</userinput>
+
+> <userinput>config add Dhcp4/option-def</userinput>
+> <userinput>config set Dhcp4/option-def[1]/name "subopt2"</userinput>
+> <userinput>config set Dhcp4/option-def[1]/code 2</userinput>
+> <userinput>config set Dhcp4/option-def[1]/space "isc"</userinput>
+> <userinput>config set Dhcp4/option-def[1]/type "string"</userinput>
+> <userinput>config set Dhcp4/option-def[1]/record-types ""</userinput>
+> <userinput>config set Dhcp4/option-def[1]/array false</userinput>
+> <userinput>config set Dhcp4/option-def[1]/encapsulate ""</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ Note that we have defined the options to belong to a new option space
+ (in this case, "isc").
+ </para>
+ <para>
+ 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:
+<screen>
+> <userinput>add Dhcp4/option-def</userinput>
+> <userinput>set Dhcp4/option-def[2]/name "container"</userinput>
+> <userinput>set Dhcp4/option-def[2]/code 222</userinput>
+> <userinput>set Dhcp4/option-def[2]/space "dhcp4"</userinput>
+> <userinput>set Dhcp4/option-def[2]/type "empty"</userinput>
+> <userinput>set Dhcp4/option-def[2]/array false</userinput>
+> <userinput>set Dhcp4/option-def[2]/record-types ""</userinput>
+> <userinput>set Dhcp4/option-def[2]/encapsulate "isc"</userinput>
+> <userinput>commit</userinput>
+</screen>
+ 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.
+ </para>
+ <para>
+ Finally, we can set values for the new options:
+<screen>
+> <userinput>config add Dhcp4/option-data</userinput>
+> <userinput>config set Dhcp4/option-data[0]/name "subopt1"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/space "isc"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/code 1</userinput>
+> <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
+> <userinput>config set Dhcp4/option-data[0]/data "192.0.2.3"</userinput>
+> <userinput>config commit</userinput>
+<userinput></userinput>
+> <userinput>config add Dhcp4/option-data</userinput>
+> <userinput>config set Dhcp4/option-data[1]/name "subopt2"</userinput>
+> <userinput>config set Dhcp4/option-data[1]/space "isc"</userinput>
+> <userinput>config set Dhcp4/option-data[1]/code 2</userinput>
+> <userinput>config set Dhcp4/option-data[1]/csv-format true</userinput>
+> <userinput>config set Dhcp4/option-data[1]/data "Hello world"</userinput>
+> <userinput>config commit</userinput>
+<userinput></userinput>
+> <userinput>config add Dhcp4/option-data</userinput>
+> <userinput>config set Dhcp4/option-data[2]/name "container"</userinput>
+> <userinput>config set Dhcp4/option-data[2]/space "dhcp4"</userinput>
+> <userinput>config set Dhcp4/option-data[2]/code 222</userinput>
+> <userinput>config set Dhcp4/option-data[2]/csv-format true</userinput>
+> <userinput>config set Dhcp4/option-data[2]/data ""</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ 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.
+ </para>
+ <para>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.
+ </para>
+ </section>
+
+ <section id="dhcp4-client-classifier">
+ <title>Client Classification in DHCPv4</title>
+ <note>
+ <para>
+ 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.
+ </para>
+ </note>
+ <para>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".
+ </para>
+
+ <para>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.</para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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 <xref linkend="dhcp4-subnet-class"/>.
+ </para>
+
+ </section>
+
+ <section id="dhcp4-subnet-class">
+ <title>Limiting access to IPv4 subnet to certain classes</title>
+ <para>
+ 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 <xref linkend="dhcp4-client-classifier"/>. This is an
+ extension of a previous example from <xref linkend="dhcp4-address-config"/>.
+ 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:
+ <screen>
+> <userinput>config add Dhcp4/subnet4</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24"</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/pool [ "192.0.2.10 - 192.0.2.20" ]</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/client-class "VENDOR_CLASS_docsis3.0"</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+
+ <para>
+ 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.
+ </para>
+ </section>
+ <section id="dhcp4-ddns-config">
+ <title>Configuring DHCPv4 for DDNS</title>
+ <para>
+ 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:
+ <orderedlist>
+ <listitem><para>
+ Whether it is a request to add (update) or remove DNS entries
+ </para></listitem>
+ <listitem><para>
+ Whether the change requests forward DNS updates (A records), reverse
+ DNS updates (PTR records), or both.
+ </para></listitem>
+ <listitem><para>
+ The FQDN, lease address, and DHCID
+ </para></listitem>
+ </orderedlist>
+ 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:
+<screen>
+> <userinput>config show Dhcp4/dhcp-ddns</userinput>
+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
+</screen>
+ </para>
+ <para>
+ 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:
+ </para>
+<screen>
+> <userinput>config set Dhcp4/dhcp-ddns/enable-updates true</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ <section id="dhcpv4-d2-io-config">
+ <title>DHCP-DDNS Server Connectivity</title>
+ <para>
+ 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:
+ <orderedlist>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ server-port - port on which D2 listens for requests. The default value
+ is 53001.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ ncr-format - Socket protocol use when sending requests to D2. Currently
+ only UDP is supported. TCP may be available in an upcoming release.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ </orderedlist>
+ 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:
+<screen>
+> <userinput>config set Dhcp4/dhcp-ddns/server-ip "198.162.1.10"</userinput>
+> <userinput>config set Dhcp4/dhcp-ddns/server-port 900</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ </para>
+ </section>
+ <section id="dhcpv4-d2-rules-config">
+ <title>When does the b10-dhcp4 server generate DDNS requests?</title>
+ 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 (<xref linkend="dhcp-ddns-server"/>).
+ <para>
+ 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.
+ </para>
+ <para>
+ In general, b10-dhcp4 will generate DDNS update requests when:
+ <orderedlist>
+ <listitem><para>
+ A new lease is granted in response to a DHCP REQUEST
+ </para></listitem>
+ <listitem><para>
+ An existing lease is renewed but the FQDN associated with it has
+ changed.
+ </para></listitem>
+ <listitem><para>
+ An existing lease is released in response to a DHCP RELEASE
+ </para></listitem>
+ </orderedlist>
+ 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.
+ </para>
+ <para>
+ 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:
+ </para>
+ <table id="fqdn-flag-table">
+ <title>Default FQDN Flag Behavior</title>
+ <tgroup cols='4' align='left'>
+ <colspec colname='cflags'/>
+ <colspec colname='meaning'/>
+ <colspec colname='response'/>
+ <colspec colname='sflags'/>
+ <thead>
+ <row>
+ <entry>Client Flags:N-S</entry>
+ <entry>Client Intent</entry>
+ <entry>Server Response</entry>
+ <entry>Server Flags:N-S-O</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0-0</entry>
+ <entry>
+ Client wants to do forward updates, server should do reverse updates
+ </entry>
+ <entry>Server generates reverse-only request</entry>
+ <entry>1-0-0</entry>
+ </row>
+ <row>
+ <entry>0-1</entry>
+ <entry>Server should do both forward and reverse updates</entry>
+ <entry>Server generates request to update both directions</entry>
+ <entry>0-1-0</entry>
+ </row>
+ <row>
+ <entry>1-0</entry>
+ <entry>Client wants no updates done</entry>
+ <entry>Server does not generate a request</entry>
+ <entry>1-0-0</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ 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.
+ </para>
+ <para>
+ (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.)
+ </para>
+ <para>
+ To override client delegation, issue the following commands:
+ </para>
+<screen>
+> <userinput>config set Dhcp4/dhcp-ddns/override-client-update true</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ <para>
+ 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.
+ </para>
+ <para>
+ To override client delegation, issue the following commands:
+ </para>
+<screen>
+> <userinput>config set Dhcp4/dhcp-ddns/override-no-update true</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ <para>
+ 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.
+ </para>
+ </section>
+ <section id="dhcpv4-fqdn-name-generation">
+ <title>b10-dhcp4 name generation for DDNS update requests</title>
+ 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.
+ <para>
+ The rules for determining the FQDN option are as follows:
+ <orderedlist>
+ <listitem><para>
+ If configured to do, so ignore the REQUEST contents and generate a
+ FQDN using a configurable prefix and suffix.
+ </para></listitem>
+ <listitem><para>
+ 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:
+ <orderedlist>
+ <listitem><para>
+ If the candidate name is a fully qualified domain name, use it.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ If the candidate name is a empty, generate a FQDN using a
+ configurable prefix and suffix.
+ </para></listitem>
+ </orderedlist>
+ </para></listitem>
+ </orderedlist>
+ To instruct b10-dhcp4 to always generate the FQDN for a client, set the
+ parameter "replace-client-name" to true as follows:
+ </para>
+<screen>
+> <userinput>config set Dhcp4/dhcp-ddns/replace-client-name true</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ <para>
+ 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:
+ </para>
+<screen>
+> <userinput>config set Dhcp4/dhcp-ddns/generated-prefix "another.host"</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ <para>
+ 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:
+ </para>
+<screen>
+> <userinput>config set Dhcp4/dhcp-ddns/generated-prefix "our.net"</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ </section>
+ <para>
+ When generating a name, b10-dhcp4 will construct name of the format:
+ </para>
+ <para>
+ [generated-prefix]-[address-text].[qualifying-suffix].
+ </para>
+ <para>
+ 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:
+ </para>
+ <para>
+ myhost-172-16-1-10.example.com.
+ </para>
+ </section>
+
+ </section> <!-- end of configuring b10-dhcp4 server section with many subsections -->
+
+ <section id="dhcp4-serverid">
+ <title>Server Identifier in DHCPv4</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ </section>
+
+
+ <section id="dhcp4-next-server">
+ <title>Next server (siaddr)</title>
+ <para>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.
+ </para>
+
+<screen>
+> <userinput>config add Dhcp4/next-server</userinput>
+> <userinput>config set Dhcp4/next-server "192.0.2.123"</userinput>
+> <userinput>config commit</userinput>
+<userinput></userinput>
+> <userinput>config add Dhcp4/subnet[0]/next-server</userinput>
+> <userinput>config set Dhcp4/subnet[0]/next-server "192.0.2.234"</userinput>
+> <userinput>config commit</userinput>
+</screen>
+
+ </section>
+
+ <section id="dhcp4-echo-client-id">
+ <title>Echoing client-id (RFC6842)</title>
+ <para>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:</para>
+
+<screen>
+> <userinput>config add Dhcp4/echo-client-id</userinput>
+> <userinput>config set Dhcp4/echo-client-id False</userinput>
+> <userinput>config commit</userinput>
+</screen>
+
+ </section>
+
+ <section id="dhcp4-subnet-selection">
+ <title>How DHCPv4 server selects subnet for a client</title>
+ <para>
+ 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.</para>
+ <para>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.
+ </para>
+ <para>
+ 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).
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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 <xref linkend="dhcp4-relay-override"/> for details.
+ </para>
+ <note>
+ <para>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.</para>
+ </note>
+ </section>
+
+ <section id="dhcp4-relay-override">
+ <title>Using specific relay agent for a subnet</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ <screen>
+> <userinput>config add Dhcp4/subnet4</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24"</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/pool [ "192.0.2.10 - 192.0.2.20" ]</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/relay/ip-address "10.0.0.1"</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+
+ </section>
+
+ <section id="dhcp4-srv-example-client-class-relay">
+ <title>Segregating IPv4 clients in a cable network</title>
+ <para>
+ In certain cases, it is useful to mix relay address information,
+ introduced in <xref linkend="dhcp4-relay-override"/> with client
+ classification, explained in <xref linkend="dhcp4-subnet-class"/>.
+ One specific example is cable network, where typically modems
+ get addresses from a different subnet than all devices connected
+ behind them.
+ </para>
+ <para>
+ 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:
+ <screen>
+> <userinput>config add Dhcp4/subnet4</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/subnet "10.1.1.0/24"</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/pool [ "10.1.1.2 - 10.1.1.20" ]</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/client-class "docsis3.0"</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/relay/ip-address "10.1.1.1"</userinput>
+> <userinput>config add Dhcp4/subnet4</userinput>
+> <userinput>config set Dhcp4/subnet4[1]/subnet "192.0.2.0/24"</userinput>
+> <userinput>config set Dhcp4/subnet4[1]/pool [ "192.0.2.10 - 192.0.2.20" ]</userinput>
+> <userinput>config set Dhcp4/subnet4[1]/relay/ip-address "10.1.1.1"</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+ </section>
+
+ <section id="dhcp4-std">
+ <title>Supported Standards</title>
+ <para>The following standards and draft standards are currently
+ supported:</para>
+ <itemizedlist>
+ <listitem>
+ <simpara><ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>: Supported messages are DISCOVER, OFFER,
+ REQUEST, RELEASE, ACK, and NAK.</simpara>
+ </listitem>
+ <listitem>
+ <simpara><ulink url="http://tools.ietf.org/html/rfc2132">RFC 2132</ulink>:
+ 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).</simpara>
+ </listitem>
+ <listitem>
+ <simpara><ulink url="http://tools.ietf.org/html/rfc3046">RFC 3046</ulink>:
+ Relay Agent Information option is supported.</simpara>
+ </listitem>
+ <listitem>
+ <simpara><ulink url="http://tools.ietf.org/html/rfc3925">RFC 3925</ulink>:
+ Vendor-Identifying Vendor Class and Vendor-Identifying Vendor-Specific
+ Information option are supported.</simpara>
+ </listitem>
+ <listitem>
+ <simpara><ulink url="http://tools.ietf.org/html/rfc6842">RFC 6842</ulink>:
+ Server by default sends back client-id option. That capability may be
+ disabled. See <xref linkend="dhcp4-echo-client-id"/> for details.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="dhcp4-limit">
+ <title>DHCPv4 Server Limitations</title>
+ <para>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 <quote>not implemented
+ yet</quote>, rather than actual limitations.</para>
+ <itemizedlist>
+ <listitem> <!-- see tickets #3234, #3281 -->
+ <simpara>
+ Removal of a subnet during server reconfiguration may cause renumbering
+ of auto-generated subnet identifiers, as described in section
+ <xref linkend="ipv4-subnet-id"/>.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ BOOTP (<ulink url="http://tools.ietf.org/html/rfc951">RFC 951</ulink>)
+ is not supported.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>Raw sockets operation is working on Linux
+ only. See <xref linkend="iface-detect"/> for details.</simpara>
+ </listitem>
+ <listitem>
+ <simpara>The DHCPv4 server does not verify that
+ assigned address is unused. According to <ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>, the
+ allocating server should verify that address is not used by
+ sending ICMP echo request.</simpara>
+ </listitem>
+ <listitem>
+ <simpara>Address duplication report (DECLINE) is not supported yet.</simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ 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.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <!--
+ <section id="dhcp4-srv-examples">
+ <title>Kea DHCPv4 server examples</title>
+
+ <para>
+ This section provides easy to use example. Each example can be read
+ separately. It is not intended to be read sequentially as there will
+ be many repetitions between examples. They are expected to serve as
+ easy to use copy-paste solutions to many common deployments.
+ </para>
+
+ @todo: add simple configuration for direct clients
+ @todo: add configuration for relayed clients
+ @todo: add client classification example
+
+ </section> -->
+
+ </chapter>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY mdash "—" >
+]>
+
+ <chapter id="dhcp6">
+ <title>The DHCPv6 Server</title>
+
+ <section id="dhcp6-start-stop">
+ <title>Starting and Stopping the DHCPv6 Server</title>
+
+ <para>
+ <command>b10-dhcp6</command> is the Kea DHCPv6 server and is configured
+ through the <command>bindctl</command> program.
+ </para>
+ <para>
+ After starting <command>bind10</command> and starting <command>bindctl</command>, the first step
+ in configuring the server is to add <command>b10-dhcp6</command> to the list of running services.
+<screen>
+> <userinput>config add Init/components b10-dhcp6</userinput>
+> <userinput>config set Init/components/b10-dhcp6/kind dispensable</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ </para>
+ <para>
+ To remove <command>b10-dhcp6</command> from the set of running services,
+ the <command>b10-dhcp6</command> is removed from list of Init components:
+<screen>
+> <userinput>config remove Init/components b10-dhcp6</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ </para>
+
+ <para>
+ 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:
+<screen>
+> <userinput>Dhcp6 shutdown</userinput>
+</screen>
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+
+ </section>
+
+ <section id="dhcp6-configuration">
+ <title>DHCPv6 Server Configuration</title>
+ <para>
+ Once the server has been started, it can be configured. To view the
+ current configuration, use the following command in <command>bindctl</command>:
+ <screen>> <userinput>config show Dhcp6</userinput></screen>
+ When starting the Dhcp6 daemon for the first time, the default configuration
+ will be available. It will look similar to this:
+<screen>
+> <userinput>config show Dhcp6</userinput>
+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
+</screen>
+ </para>
+ <para>
+ To change one of the parameters, simply follow
+ the usual <command>bindctl</command> procedure. For example, to make the
+ leases longer, change their valid-lifetime parameter:
+ <screen>
+> <userinput>config set Dhcp6/valid-lifetime 7200</userinput>
+> <userinput>config commit</userinput></screen>
+ Most Dhcp6 parameters are of global scope
+ and apply to all defined subnets, unless they are overridden on a
+ per-subnet basis.
+ </para>
+ <note>
+ <para>
+ With this version of Kea, there are a number of known limitations
+ and problems in the DHCPv6 server. See <xref linkend="dhcp6-limit"/>.
+ </para>
+ </note>
+
+ <section>
+ <title>Default storage for leases</title>
+ <para>
+ The server is able to store lease data in different repositories. Larger deployments
+ may elect to store leases in a database.
+ <xref linkend="database-configuration6"/> 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ It is possible to alter the default location of the lease file. The following
+ configuration:
+<screen>
+> <userinput>config set Dhcp4/lease-database/type "memfile"</userinput>
+> <userinput>config set Dhcp4/lease-database/persist true</userinput>
+> <userinput>config set Dhcp4/lease-database/leasefile "/tmp/kea-leases6.csv"</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ will change the default location of the lease file to /tmp/kea-leases6.csv.
+ </para>
+ <para>
+ 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.
+ </para>
+ </section>
+
+ <section id="database-configuration6">
+ <title>Database Configuration</title>
+ <para>
+ All leases issued by the server are stored in the lease database. Currently
+ there are 3 database backends available: MySQL, PostgreSQL and memfile.
+ <footnote>
+ <para>
+ 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.
+ </para>
+ </footnote>, and so the server must be configured to
+ access the correct database with the appropriate credentials.
+ </para>
+ <note>
+ <para>
+ 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.
+ </para>
+ </note>
+ <para>
+ Database configuration is controlled through the Dhcp6/lease-database parameters.
+ The type of the database must be set to "mysql", "postgresql" or "memfile":
+<screen>
+> <userinput>config set Dhcp6/lease-database/type "mysql"</userinput>
+</screen>
+ 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 <xref linkend="dhcp-mysql-database-create"/>
+ or <xref linkend="dhcp-pgsql-database-create"/>).
+<screen>
+> <userinput>config set Dhcp6/lease-database/name "<replaceable>database-name</replaceable>"</userinput>
+</screen>
+ 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):
+<screen>
+> <userinput>config set Dhcp6/lease-database/host "<replaceable>remote-host-name</replaceable>"</userinput>
+</screen>
+ 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):
+<screen>
+> <userinput>config set Dhcp6/lease-database/host ""</userinput>
+</screen>
+ </para>
+ <para>
+ Finally, the credentials of the account under which the server will access the database
+ should be set:
+<screen>
+> <userinput>config set Dhcp6/lease-database/user "<replaceable>user-name</replaceable>"</userinput>
+> <userinput>config set Dhcp6/lease-database/password "<replaceable>password</replaceable>"</userinput>
+</screen>
+ If there is no password to the account, set the password to the empty string "". (This is also the default.)
+ </para>
+ <note>
+ <para>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.</para>
+ </note>
+ </section>
+
+ <section id="dhcp6-interface-selection">
+ <title>Interface selection</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ The default configuration can be presented with the following command:
+ <screen>
+> <userinput>config show Dhcp6/interfaces</userinput>
+<userinput>Dhcp6/interfaces[0] "*" string</userinput></screen>
+ An asterisk sign plays a role of the wildcard and means "listen on all interfaces".
+ </para>
+ <para>
+ In order to override the default configuration, the existing entry can be replaced
+ with the actual interface name:
+ <screen>
+> <userinput>config set Dhcp6/interfaces[0] eth1</userinput>
+> <userinput>config commit</userinput></screen>
+ Other interface names can be added on one-by-one basis:
+ <screen>
+> <userinput>config add Dhcp6/interfaces eth2</userinput>
+> <userinput>config commit</userinput></screen>
+ Configuration will now contain two interfaces which can be presented as follows:
+ <screen>
+> <userinput>config show Dhcp6/interfaces</userinput>
+<userinput>Dhcp6/interfaces[0] "eth1" string</userinput>
+<userinput>Dhcp6/interfaces[1] "eth2" string</userinput></screen>
+ When configuration gets committed, the server will start to listen on
+ eth1 and eth2 interfaces only.
+ </para>
+ <para>
+ It is possible to use wildcard interface name (asterisk) concurrently with explicit
+ interface names:
+ <screen>
+> <userinput>config add Dhcp6/interfaces *</userinput>
+> <userinput>config commit</userinput></screen>
+ This will result in the following configuration:
+ <screen>
+> <userinput>config show Dhcp6/interfaces</userinput>
+<userinput>Dhcp6/interfaces[0] "eth1" string</userinput>
+<userinput>Dhcp6/interfaces[1] "eth2" string</userinput>
+<userinput>Dhcp6/interfaces[2] "*" string</userinput></screen>
+ 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:
+ <screen>
+> <userinput>config remove Dhcp6/interfaces[2]</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+ </section>
+
+ <section id="ipv6-subnet-id">
+ <title>IPv6 Subnet Identifier</title>
+ <para>
+ 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 ....
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ The following configuration:
+ <screen>
+> <userinput>config add Dhcp6/subnet6</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64"</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/id 1024</userinput>
+> <userinput>config commit</userinput>
+ </screen>
+ 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.
+ </para>
+ </section>
+
+ <section id="dhcp6-unicast">
+ <title>Unicast traffic support</title>
+ <para>
+ 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 <xref linkend="dhcp6-interface-selection"/>).
+ 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.
+ </para>
+ <para>
+ <screen>
+> <userinput>config set Dhcp6/interfaces[0] eth1/2001:db8::1</userinput>
+> <userinput>config commit</userinput></screen>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ </section>
+
+ <section id="dhcp6-address-config">
+ <title>Subnet and Address Pool</title>
+ <para>
+ 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:
+ <screen>
+> <userinput>config add Dhcp6/subnet6</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64"</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::0 - 2001:db8:1::ffff" ]</userinput>
+> <userinput>config commit</userinput></screen>
+ 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.</para>
+ <para>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:
+ <screen>
+> <userinput>config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::1 - 2001:db8:1::ffff", "2001:db8:1:0:5::/80" ]</userinput>
+> <userinput>config commit</userinput></screen>
+ The number of pools is not limited, but for performance reasons it is recommended to
+ use as few as possible.
+ </para>
+ <para>
+ The server may be configured to serve more than one subnet. To add a second subnet,
+ use a command similar to the following:
+ <screen>
+> <userinput>config add Dhcp6/subnet6</userinput>
+> <userinput>config set Dhcp6/subnet6[1]/subnet "2001:db8:beef::/48"</userinput>
+> <userinput>config set Dhcp6/subnet6[1]/pool [ "2001:db8:beef::/48" ]</userinput>
+> <userinput>config commit</userinput></screen>
+ Arrays are counted from 0. subnet[0] refers to the subnet defined in the
+ previous example. The <command>config add Dhcp6/subnet6</command> command adds
+ another (second) subnet. It can be referred to as
+ <command>Dhcp6/subnet6[1]</command>. 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ </section>
+
+ <section>
+<!-- @todo: add real meat to the prefix delegation config this is just place holder stuff -->
+ <title>Subnet and Prefix Delegation Pools</title>
+ <para>
+ 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:
+ <screen>
+> <userinput>config add Dhcp6/subnet6</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64"</userinput>
+> <userinput>config show Dhcp6/subnet6[0]</userinput>
+> <userinput>config add Dhcp6/subnet6[0]/pd-pools</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/pd-pools[0]/prefix "2001:db8:1::"</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/pd-pools[0]/prefix-len 64</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/pd-pools[0]/delegated-len 96</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+ </section>
+
+ <section id="dhcp6-std-options">
+ <title>Standard DHCPv6 options</title>
+ <para>
+ 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.
+
+ <screen>
+1. > <userinput>config add Dhcp6/option-data</userinput>
+2. > <userinput>config set Dhcp6/option-data[0]/name "dns-servers"</userinput>
+3. > <userinput>config set Dhcp6/option-data[0]/code 23</userinput>
+4. > <userinput>config set Dhcp6/option-data[0]/space "dhcp6"</userinput>
+5. > <userinput>config set Dhcp6/option-data[0]/csv-format true</userinput>
+6. > <userinput>config set Dhcp6/option-data[0]/data "2001:db8::cafe, 2001:db8::babe"</userinput>
+7. > <userinput>config commit</userinput>
+</screen>
+ </para>
+ <para>
+ 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 <xref linkend="dhcp6-std-options-list"/>.
+ 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 <xref
+ linkend="dhcp6-option-spaces"/>. 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.
+ </para>
+
+ <para>
+ 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.
+ <screen>
+> <userinput>config add Dhcp6/option-data</userinput>
+> <userinput>config set Dhcp6/option-data[0]/name "dns-servers"</userinput>
+> <userinput>config set Dhcp6/option-data[0]/code 23</userinput>
+> <userinput>config set Dhcp6/option-data[0]/space "dhcp6"</userinput>
+> <userinput>config set Dhcp6/option-data[0]/csv-format false</userinput>
+> <userinput>config set Dhcp6/option-data[0]/data "2001 0DB8 0001 0000 0000 0000</userinput>
+ <userinput>0000 CAFE 2001 0DB8 0001 0000 0000 0000 0000 BABE"</userinput>
+> <userinput>config commit</userinput>
+ </screen>
+ (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.)
+ </para>
+
+ <para>
+ 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]).
+ </para>
+ <para>
+ The following commands override the global
+ DNS servers option for a particular subnet, setting a single DNS
+ server with address 2001:db8:1::3.
+ <screen>
+> <userinput>config add Dhcp6/subnet6[0]/option-data</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/option-data[0]/name "dns-servers"</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/option-data[0]/code 23</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/option-data[0]/space "dhcp6"</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/option-data[0]/csv-format true</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/option-data[0]/data "2001:db8:1::3"</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+
+ <note>
+ <para>
+ 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.
+ </para>
+ </note>
+
+
+ <para>
+ The currently supported standard DHCPv6 options are
+ listed in <xref linkend="dhcp6-std-options-list"/>.
+ 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 <xref linkend="dhcp-types"/>.
+ </para>
+ <para>
+ 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.
+ </para>
+
+<!-- @todo: describe record types -->
+
+ <para>
+ The <xref linkend="dhcp6-custom-options"/> 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
+ <xref linkend="dhcp6-custom-options"/> 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.
+ </para>
+
+
+ <para>
+ <table frame="all" id="dhcp6-std-options-list">
+ <title>List of standard DHCPv6 options</title>
+ <tgroup cols='4'>
+ <colspec colname='name'/>
+ <colspec colname='code'/>
+ <colspec colname='type'/>
+ <colspec colname='array'/>
+ <thead>
+ <row><entry>Name</entry><entry>Code</entry><entry>Type</entry><entry>Array?</entry></row>
+ </thead>
+ <tbody>
+<!-- Our engine uses those options on its own, admin must not configure them on his own
+<row><entry>clientid</entry><entry>1</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>serverid</entry><entry>2</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>ia-na</entry><entry>3</entry><entry>record</entry><entry>false</entry></row>
+<row><entry>ia-ta</entry><entry>4</entry><entry>uint32</entry><entry>false</entry></row>
+<row><entry>iaaddr</entry><entry>5</entry><entry>record</entry><entry>false</entry></row>
+<row><entry>oro</entry><entry>6</entry><entry>uint16</entry><entry>true</entry></row> -->
+<row><entry>preference</entry><entry>7</entry><entry>uint8</entry><entry>false</entry></row>
+
+<!-- Our engine uses those options on its own, admin must not configure them on his own
+<row><entry>elapsed-time</entry><entry>8</entry><entry>uint16</entry><entry>false</entry></row>
+<row><entry>relay-msg</entry><entry>9</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>auth</entry><entry>11</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>unicast</entry><entry>12</entry><entry>ipv6-address</entry><entry>false</entry></row>
+<row><entry>status-code</entry><entry>13</entry><entry>record</entry><entry>false</entry></row>
+<row><entry>rapid-commit</entry><entry>14</entry><entry>empty</entry><entry>false</entry></row>
+<row><entry>user-class</entry><entry>15</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>vendor-class</entry><entry>16</entry><entry>record</entry><entry>false</entry></row>
+<row><entry>vendor-opts</entry><entry>17</entry><entry>uint32</entry><entry>false</entry></row>
+<row><entry>interface-id</entry><entry>18</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>reconf-msg</entry><entry>19</entry><entry>uint8</entry><entry>false</entry></row>
+<row><entry>reconf-accept</entry><entry>20</entry><entry>empty</entry><entry>false</entry></row> -->
+<row><entry>sip-server-dns</entry><entry>21</entry><entry>fqdn</entry><entry>true</entry></row>
+<row><entry>sip-server-addr</entry><entry>22</entry><entry>ipv6-address</entry><entry>true</entry></row>
+<row><entry>dns-servers</entry><entry>23</entry><entry>ipv6-address</entry><entry>true</entry></row>
+<row><entry>domain-search</entry><entry>24</entry><entry>fqdn</entry><entry>true</entry></row>
+<!-- <row><entry>ia-pd</entry><entry>25</entry><entry>record</entry><entry>false</entry></row> -->
+<!-- <row><entry>iaprefix</entry><entry>26</entry><entry>record</entry><entry>false</entry></row> -->
+<row><entry>nis-servers</entry><entry>27</entry><entry>ipv6-address</entry><entry>true</entry></row>
+<row><entry>nisp-servers</entry><entry>28</entry><entry>ipv6-address</entry><entry>true</entry></row>
+<row><entry>nis-domain-name</entry><entry>29</entry><entry>fqdn</entry><entry>true</entry></row>
+<row><entry>nisp-domain-name</entry><entry>30</entry><entry>fqdn</entry><entry>true</entry></row>
+<row><entry>sntp-servers</entry><entry>31</entry><entry>ipv6-address</entry><entry>true</entry></row>
+<row><entry>information-refresh-time</entry><entry>32</entry><entry>uint32</entry><entry>false</entry></row>
+<row><entry>bcmcs-server-dns</entry><entry>33</entry><entry>fqdn</entry><entry>true</entry></row>
+<row><entry>bcmcs-server-addr</entry><entry>34</entry><entry>ipv6-address</entry><entry>true</entry></row>
+<row><entry>geoconf-civic</entry><entry>36</entry><entry>record</entry><entry>false</entry></row>
+<row><entry>remote-id</entry><entry>37</entry><entry>record</entry><entry>false</entry></row>
+<row><entry>subscriber-id</entry><entry>38</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>client-fqdn</entry><entry>39</entry><entry>record</entry><entry>false</entry></row>
+<row><entry>pana-agent</entry><entry>40</entry><entry>ipv6-address</entry><entry>true</entry></row>
+<row><entry>new-posix-timezone</entry><entry>41</entry><entry>string</entry><entry>false</entry></row>
+<row><entry>new-tzdb-timezone</entry><entry>42</entry><entry>string</entry><entry>false</entry></row>
+<row><entry>ero</entry><entry>43</entry><entry>uint16</entry><entry>true</entry></row>
+<row><entry>lq-query</entry><entry>44</entry><entry>record</entry><entry>false</entry></row>
+<row><entry>client-data</entry><entry>45</entry><entry>empty</entry><entry>false</entry></row>
+<row><entry>clt-time</entry><entry>46</entry><entry>uint32</entry><entry>false</entry></row>
+<row><entry>lq-relay-data</entry><entry>47</entry><entry>record</entry><entry>false</entry></row>
+<row><entry>lq-client-link</entry><entry>48</entry><entry>ipv6-address</entry><entry>true</entry></row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </section>
+
+ <section id="dhcp6-custom-options">
+ <title>Custom DHCPv6 options</title>
+ <para>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:
+ <screen>
+> <userinput>config add Dhcp6/option-def</userinput>
+> <userinput>config set Dhcp6/option-def[0]/name "foo"</userinput>
+> <userinput>config set Dhcp6/option-def[0]/code 100</userinput>
+> <userinput>config set Dhcp6/option-def[0]/type "uint32"</userinput>
+> <userinput>config set Dhcp6/option-def[0]/array false</userinput>
+> <userinput>config set Dhcp6/option-def[0]/record-types ""</userinput>
+> <userinput>config set Dhcp6/option-def[0]/space "dhcp6"</userinput>
+> <userinput>config set Dhcp6/option-def[0]/encapsulate ""</userinput>
+> <userinput>config commit</userinput></screen>
+ 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.
+ </para>
+ <para>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.
+ <screen>
+> <userinput>config add Dhcp6/option-data</userinput>
+> <userinput>config set Dhcp6/option-data[0]/name "foo"</userinput>
+> <userinput>config set Dhcp6/option-data[0]/code 100</userinput>
+> <userinput>config set Dhcp6/option-data[0]/space "dhcp6"</userinput>
+> <userinput>config set Dhcp6/option-data[0]/csv-format true</userinput>
+> <userinput>config set Dhcp6/option-data[0]/data "12345"</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+
+ <para>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.
+ </para>
+ <para>
+ 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:
+<screen>
+> <userinput>config add Dhcp6/option-def</userinput>
+> <userinput>config set Dhcp6/option-def[0]/name "bar"</userinput>
+> <userinput>config set Dhcp6/option-def[0]/code 101</userinput>
+> <userinput>config set Dhcp6/option-def[0]/space "dhcp6"</userinput>
+> <userinput>config set Dhcp6/option-def[0]/type "record"</userinput>
+> <userinput>config set Dhcp6/option-def[0]/array false</userinput>
+> <userinput>config set Dhcp6/option-def[0]/record-types "ipv6-address, uint16, boolean, string"</userinput>
+> <userinput>config set Dhcp6/option-def[0]/encapsulate ""</userinput>
+</screen>
+ 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 <xref linkend="dhcp-types"/>.
+ </para>
+ <para>
+ The values of the option are set as follows:
+<screen>
+> <userinput>config add Dhcp6/option-data</userinput>
+> <userinput>config set Dhcp6/option-data[0]/name "bar"</userinput>
+> <userinput>config set Dhcp6/option-data[0]/space "dhcp6"</userinput>
+> <userinput>config set Dhcp6/option-data[0]/code 101</userinput>
+> <userinput>config set Dhcp6/option-data[0]/csv-format true</userinput>
+> <userinput>config set Dhcp6/option-data[0]/data "2001:db8:1::10, 123, false, Hello World"</userinput>
+> <userinput>config commit</userinput></screen>
+ "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.
+ </para>
+ <note>
+ <para>
+ 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.
+ </para>
+ </note>
+ </section>
+
+ <section id="dhcp6-vendor-opts">
+ <title>DHCPv6 vendor specific options</title>
+ <para>
+ 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.
+ <screen>
+> <userinput>config add Dhcp6/option-def</userinput>
+> <userinput>config set Dhcp6/option-def[0]/name "foo"</userinput>
+> <userinput>config set Dhcp6/option-def[0]/code 1</userinput>
+> <userinput>config set Dhcp6/option-def[0]/space "vendor-opts-space"</userinput>
+> <userinput>config set Dhcp6/option-def[0]/type "record"</userinput>
+> <userinput>config set Dhcp6/option-def[0]/array false</userinput>
+> <userinput>config set Dhcp6/option-def[0]/record-types "ipv6-address, uint16, string"</userinput>
+> <userinput>config set Dhcp6/option-def[0]/encapsulates ""</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ (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:
+ <screen>
+> <userinput>config add Dhcp6/option-data</userinput>
+> <userinput>config set Dhcp6/option-data[0]/name "foo"</userinput>
+> <userinput>config set Dhcp6/option-data[0]/space "vendor-opts-space"</userinput>
+> <userinput>config set Dhcp6/option-data[0]/code 1</userinput>
+> <userinput>config set Dhcp6/option-data[0]/csv-format true</userinput>
+> <userinput>config set Dhcp6/option-data[0]/data "2001:db8:1::10, 123, Hello World"</userinput>
+> <userinput>config commit</userinput></screen>
+ We should also define values for the vendor-opts, that will convey our option foo.
+ <screen>
+> <userinput>config add Dhcp6/option-data</userinput>
+> <userinput>config set Dhcp6/option-data[1]/name "vendor-opts"</userinput>
+> <userinput>config set Dhcp6/option-data[1]/space "dhcp6"</userinput>
+> <userinput>config set Dhcp6/option-data[1]/code 17</userinput>
+> <userinput>config set Dhcp6/option-data[1]/csv-format true</userinput>
+> <userinput>config set Dhcp6/option-data[1]/data "12345"</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+ </section>
+
+ <section id="dhcp6-option-spaces">
+ <title>Nested DHCPv6 options (custom option spaces)</title>
+ <para>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.
+ </para>
+ <para>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 <xref linkend="dhcp6-vendor-opts"/>).
+ </para>
+ <para>
+ 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:
+<screen>
+> <userinput>config add Dhcp6/option-def</userinput>
+> <userinput>config set Dhcp6/option-def[0]/name "subopt1"</userinput>
+> <userinput>config set Dhcp6/option-def[0]/code 1</userinput>
+> <userinput>config set Dhcp6/option-def[0]/space "isc"</userinput>
+> <userinput>config set Dhcp6/option-def[0]/type "ipv6-address"</userinput>
+> <userinput>config set Dhcp6/option-def[0]/record-types ""</userinput>
+> <userinput>config set Dhcp6/option-def[0]/array false</userinput>
+> <userinput>config set Dhcp6/option-def[0]/encapsulate ""</userinput>
+> <userinput>config commit</userinput>
+> <userinput></userinput>
+> <userinput>config add Dhcp6/option-def</userinput>
+> <userinput>config set Dhcp6/option-def[1]/name "subopt2"</userinput>
+> <userinput>config set Dhcp6/option-def[1]/code 2</userinput>
+> <userinput>config set Dhcp6/option-def[1]/space "isc"</userinput>
+> <userinput>config set Dhcp6/option-def[1]/type "string"</userinput>
+> <userinput>config set Dhcp6/option-def[1]/record-types ""</userinput>
+> <userinput>config set Dhcp6/option-def[1]/array false</userinput>
+> <userinput>config set Dhcp6/option-def[1]/encapsulate ""</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ Note that we have defined the options to belong to a new option space
+ (in this case, "isc").
+ </para>
+ <para>
+The next step is to define a regular DHCPv6 option and specify that it
+should include options from the isc option space:
+<screen>
+> <userinput>config add Dhcp6/option-def</userinput>
+> <userinput>config set Dhcp6/option-def[2]/name "container"</userinput>
+> <userinput>config set Dhcp6/option-def[2]/code 102</userinput>
+> <userinput>config set Dhcp6/option-def[2]/space "dhcp6"</userinput>
+> <userinput>config set Dhcp6/option-def[2]/type "empty"</userinput>
+> <userinput>config set Dhcp6/option-def[2]/array false</userinput>
+> <userinput>config set Dhcp6/option-def[2]/record-types ""</userinput>
+> <userinput>config set Dhcp6/option-def[2]/encapsulate "isc"</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ 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.
+ </para>
+ <para>
+ Finally, we can set values for the new options:
+<screen>
+> <userinput>config add Dhcp6/option-data</userinput>
+> <userinput>config set Dhcp6/option-data[0]/name "subopt1"</userinput>
+> <userinput>config set Dhcp6/option-data[0]/space "isc"</userinput>
+> <userinput>config set Dhcp6/option-data[0]/code 1</userinput>
+> <userinput>config set Dhcp6/option-data[0]/csv-format true</userinput>
+> <userinput>config set Dhcp6/option-data[0]/data "2001:db8::abcd"</userinput>
+> <userinput>config commit</userinput>
+> <userinput></userinput>
+> <userinput>config add Dhcp6/option-data</userinput>
+> <userinput>config set Dhcp6/option-data[1]/name "subopt2"</userinput>
+> <userinput>config set Dhcp6/option-data[1]/space "isc"</userinput>
+> <userinput>config set Dhcp6/option-data[1]/code 2</userinput>
+> <userinput>config set Dhcp6/option-data[1]/csv-format true</userinput>
+> <userinput>config set Dhcp6/option-data[1]/data "Hello world"</userinput>
+> <userinput>config commit</userinput>
+> <userinput></userinput>
+> <userinput>config add Dhcp6/option-data</userinput>
+> <userinput>config set Dhcp6/option-data[2]/name "container"</userinput>
+> <userinput>config set Dhcp6/option-data[2]/space "dhcp6"</userinput>
+> <userinput>config set Dhcp6/option-data[2]/code 102</userinput>
+> <userinput>config set Dhcp6/option-data[2]/csv-format true</userinput>
+> <userinput>config set Dhcp6/option-data[2]/data ""</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ 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.
+ </para>
+ <para>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.
+ </para>
+ </section>
+
+ <section id="dhcp6-config-subnets">
+ <title>IPv6 Subnet Selection</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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:
+<screen>
+> <userinput>config add Dhcp6/subnet6</userinput>
+> <userinput>config set Dhcp6/subnet6[1]/subnet "2001:db8:beef::/48"</userinput>
+> <userinput>config set Dhcp6/subnet6[1]/pool [ "2001:db8:beef::/48" ]</userinput>
+> <userinput>config set Dhcp6/subnet6[1]/interface "eth0"</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ </para>
+ </section>
+
+ <section id="dhcp6-relays">
+ <title>DHCPv6 Relays</title>
+ <para>
+ 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:
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ When configuring the DHCPv6 server, it should be noted that two
+ similarly-named parameters can be configured for a subnet:
+ <itemizedlist>
+ <listitem><simpara>
+ "interface" defines which local network interface can be used
+ to access a given subnet.
+ </simpara></listitem>
+ <listitem><simpara>
+ "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.
+ </simpara></listitem>
+ </itemizedlist>
+ 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.
+ </para>
+
+ <para>
+ To specify interface-id with value "vlan123", the following commands can
+ be used:
+ <screen>
+> <userinput>config add Dhcp6/subnet6</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/subnet "2001:db8:beef::/48"</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/pool [ "2001:db8:beef::/48" ]</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/interface-id "vland123"</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ </para>
+ </section>
+
+ <section id="dhcp6-client-classifier">
+ <title>Client Classification in DHCPv6</title>
+ <note>
+ <para>
+ 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.
+ </para>
+ </note>
+ <para>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".
+ </para>
+
+ <para>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.</para>
+
+ <para>
+ 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 <xref linkend="dhcp6-subnet-class"/>.
+ </para>
+
+ </section>
+
+ <section id="dhcp6-subnet-class">
+ <title>Limiting access to IPv6 subnet to certain classes</title>
+ <para>
+ 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 <xref linkend="dhcp6-client-classifier"/>. This is an
+ extension of a previous example from <xref linkend="dhcp6-address-config"/>.
+
+ 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:
+
+ <screen>
+> <userinput>config add Dhcp6/subnet6</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64"</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::0 - 2001:db8:1::ffff" ]</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/client-class "eRouter1.0"</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+
+ <para>
+ 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.
+ </para>
+ </section>
+
+
+ <section id="dhcp6-ddns-config">
+ <title>Configuring DHCPv6 for DDNS</title>
+ <para>
+ 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:
+ <orderedlist>
+ <listitem><para>
+ Whether it is a request to add (update) or remove DNS entries
+ </para></listitem>
+ <listitem><para>
+ Whether the change requests forward DNS updates (AAAA records), reverse
+ DNS updates (PTR records), or both.
+ </para></listitem>
+ <listitem><para>
+ The FQDN, lease address, and DHCID
+ </para></listitem>
+ </orderedlist>
+ 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:
+<screen>
+> <userinput>config show Dhcp6/dhcp-ddns</userinput>
+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
+</screen>
+ </para>
+ <para>
+ 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:
+ </para>
+<screen>
+> <userinput>config set Dhcp6/dhcp-ddns/enable-updates true</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ <section id="dhcpv6-d2-io-config">
+ <title>DHCP-DDNS Server Connectivity</title>
+ <para>
+ 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:
+ <orderedlist>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ server-port - port on which D2 listens for requests. The default value
+ is 53001.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ ncr-format - Socket protocol use when sending requests to D2. Currently
+ only UDP is supported. TCP may be available in an upcoming release.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ </orderedlist>
+ 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:
+<screen>
+> <userinput>config set Dhcp6/dhcp-ddns/server-ip "3001::5"</userinput>
+> <userinput>config set Dhcp6/dhcp-ddns/server-port 900</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ </para>
+ </section>
+ <section id="dhcpv6-d2-rules-config">
+ <title>When does b10-dhcp6 generate DDNS request</title>
+ 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 (<xref linkend="dhcp-ddns-server"/>).
+ <para>
+ 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.
+ </para>
+ <note>
+ <para>
+ 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.
+ </para>
+ </note>
+ <para>
+ In general, b10-dhcp6 will generate DDNS update requests when:
+ <orderedlist>
+ <listitem><para>
+ A new lease is granted in response to a DHCP REQUEST
+ </para></listitem>
+ <listitem><para>
+ An existing lease is renewed but the FQDN associated with it has
+ changed.
+ </para></listitem>
+ <listitem><para>
+ An existing lease is released in response to a DHCP RELEASE
+ </para></listitem>
+ </orderedlist>
+ 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.
+ </para>
+ <para>
+ 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:
+ </para>
+ <table id="dhcp6-fqdn-flag-table">
+ <title>Default FQDN Flag Behavior</title>
+ <tgroup cols='4' align='left'>
+ <colspec colname='cflags'/>
+ <colspec colname='meaning'/>
+ <colspec colname='response'/>
+ <colspec colname='sflags'/>
+ <thead>
+ <row>
+ <entry>Client Flags:N-S</entry>
+ <entry>Client Intent</entry>
+ <entry>Server Response</entry>
+ <entry>Server Flags:N-S-O</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0-0</entry>
+ <entry>
+ Client wants to do forward updates, server should do reverse updates
+ </entry>
+ <entry>Server generates reverse-only request</entry>
+ <entry>1-0-0</entry>
+ </row>
+ <row>
+ <entry>0-1</entry>
+ <entry>Server should do both forward and reverse updates</entry>
+ <entry>Server generates request to update both directions</entry>
+ <entry>0-1-0</entry>
+ </row>
+ <row>
+ <entry>1-0</entry>
+ <entry>Client wants no updates done</entry>
+ <entry>Server does not generate a request</entry>
+ <entry>1-0-0</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ 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.
+ </para>
+ <para>
+ (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.)
+ </para>
+ <para>
+ To override client delegation, issue the following commands:
+ </para>
+<screen>
+> <userinput>config set Dhcp6/dhcp-ddns/override-client-update true</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ <para>
+ 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.
+ </para>
+ <para>
+ To override client delegation, issue the following commands:
+ </para>
+<screen>
+> <userinput>config set Dhcp6/dhcp-ddns/override-no-update true</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ </section>
+ <section id="dhcpv6-fqdn-name-generation">
+ <title>b10-dhcp6 name generation for DDNS update requests</title>
+ 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.
+ <para>
+ The rules for determining the FQDN option are as follows:
+ <orderedlist>
+ <listitem><para>
+ If configured to do so ignore the REQUEST contents and generate a
+ FQDN using a configurable prefix and suffix.
+ </para></listitem>
+ <listitem><para>
+ Otherwise, using is the domain name value from the client FQDN option as
+ the candidate name:
+ <orderedlist>
+ <listitem><para>
+ If the candidate name is a fully qualified domain name then use it.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ If the candidate name is a empty then generate a FQDN using a
+ configurable prefix and suffix.
+ </para></listitem>
+ </orderedlist>
+ </para></listitem>
+ </orderedlist>
+ To instruct b10-dhcp6 to always generate a FQDN, set the parameter
+ "replace-client-name" to true:
+ </para>
+<screen>
+> <userinput>config set Dhcp6/dhcp-ddns/replace-client-name true</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ <para>
+ 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:
+ </para>
+<screen>
+> <userinput>config set Dhcp6/dhcp-ddns/generated-prefix "another.host"</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ <para>
+ 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:
+ </para>
+<screen>
+> <userinput>config set Dhcp6/dhcp-ddns/generated-prefix "our.net"</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ </section>
+ <para>
+ When qualifying a partial name, b10-dhcp6 will construct a name with the
+ format:
+ </para>
+ <para>
+ [candidate-name].[qualifying-suffix].
+ </para>
+ <para>
+ 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:
+ </para>
+ <para>
+ some-computer.example.com.
+ </para>
+ <para>
+ When generating a the entire name, b10-dhcp6 will construct name of the
+ format:
+ </para>
+ <para>
+ [generated-prefix]-[address-text].[qualifying-suffix].
+ </para>
+ <para>
+ 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:
+ </para>
+ <para>
+ myhost-3001-1--70E.example.com.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="dhcp6-serverid">
+ <title>Server Identifier in DHCPv6</title>
+ <para>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 <ulink url="http://tools.ietf.org/html/rfc3315">RFC 3315</ulink> 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.
+ </para>
+ <para>
+ 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.
+ </para>
+
+ </section>
+
+ <section id="dhcp6-relay-override">
+ <title>Using specific relay agent for a subnet</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ <screen>
+> <userinput>config add Dhcp6/subnet6</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64"</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::2 - 2001:db8:1::ffff" ]</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/relay/ip-address "3000::1"</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+
+ </section>
+
+ <section id="dhcp6-client-class-relay">
+ <title>Segregating IPv6 clients in a cable network</title>
+ <para>
+ In certain cases, it is useful to mix relay address information,
+ introduced in <xref linkend="dhcp6-relay-override"/> with client
+ classification, explained in <xref linkend="dhcp6-subnet-class"/>.
+ One specific example is cable network, where typically modems
+ get addresses from a different subnet than all devices connected
+ behind them.
+ </para>
+ <para>
+ 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:
+ <screen>
+> <userinput>config add Dhcp6/subnet6</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/subnet "3000::/64"</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/pool [ "3000::2 - 3000::ffff" ]</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/client-class "docsis3.0"</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/relay/ip-address "3000::1"</userinput>
+> <userinput>config add Dhcp6/subnet6</userinput>
+> <userinput>config set Dhcp6/subnet6[1]/subnet "2001:db8:1::/64"</userinput>
+> <userinput>config set Dhcp6/subnet6[1]/pool [ "2001:db8:1::1 - 2001:db8:1::ffff" ]</userinput>
+> <userinput>config set Dhcp6/subnet6[1]/relay/ip-address "3000::1"</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+ </section>
+
+
+ <section id="dhcp6-std">
+ <title>Supported Standards</title>
+ <para>The following standards and draft standards are currently
+ supported:</para>
+ <itemizedlist>
+ <listitem>
+ <simpara><ulink url="http://tools.ietf.org/html/rfc3315">RFC 3315</ulink>: Supported messages are SOLICIT,
+ ADVERTISE, REQUEST, RELEASE, RENEW, REBIND and REPLY.</simpara>
+ </listitem>
+ <listitem>
+ <simpara><ulink url="http://tools.ietf.org/html/rfc3633">RFC 3633</ulink>: Supported options are IA_PD and
+ IA_PREFIX. Also supported is the status code NoPrefixAvail.</simpara>
+ </listitem>
+ <listitem>
+ <simpara><ulink url="http://tools.ietf.org/html/rfc3646">RFC 3646</ulink>: Supported option is DNS_SERVERS.</simpara>
+ </listitem>
+ <listitem>
+ <simpara><ulink url="http://tools.ietf.org/html/rfc4704">RFC 4704</ulink>: Supported option is CLIENT_FQDN.</simpara>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="dhcp6-limit">
+ <title>DHCPv6 Server Limitations</title>
+ <para> 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 <quote>not implemented
+ yet</quote>, rather than actual limitations.</para>
+ <itemizedlist>
+ <listitem> <!-- see tickets #3234, #3281 -->
+ <para>
+ 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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.
+ <screen>
+> <userinput>config show Dhcp6/renew-timer</userinput>
+Dhcp6/renew-timer 1000 integer (default)
+> <userinput>config set Dhcp6/renew-timer 1001</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+ </listitem>
+ <listitem>
+ <simpara>Temporary addresses are not supported.</simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ 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.
+ <ulink url="http://tools.ietf.org/html/rfc3315">RFC 3315</ulink> and
+ <ulink url="http://tools.ietf.org/html/rfc3633">RFC 3633</ulink> allow
+ for multiple addresses or prefixes to be allocated for a single IA.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>Temporary addresses are not supported.</simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Confirmation (CONFIRM), duplication report (DECLINE),
+ stateless configuration (INFORMATION-REQUEST) and client
+ reconfiguration (RECONFIGURE) are not yet supported.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ 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.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <!--
+ <section id="dhcp6-srv-examples">
+ <title>Kea DHCPv6 server examples</title>
+
+ <para>
+ This section provides easy to use example. Each example can be read
+ separately. It is not intended to be read sequentially as there will
+ be many repetitions between examples. They are expected to serve as
+ easy to use copy-paste solutions to many common deployments.
+ </para>
+
+ @todo: add simple configuration for direct clients
+ @todo: add configuration for relayed clients
+ @todo: add client classification example
+
+ </section> -->
+
+ </chapter>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY mdash "—" >
+<!ENTITY % version SYSTEM "version.ent">
+%version;
+]>
+
+ <chapter id="intro">
+ <title>Introduction</title>
+ <para>
+ 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.
+ </para>
+
+ <para>
+ Kea has been initially developed as a part of the BIND 10 framework
+ (<ulink url="http://bind10.isc.org"/>). 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++.
+ </para>
+
+ <note>
+ <simpara>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".
+ </simpara>
+ </note>
+
+ <para>
+ This guide covers Kea version &__VERSION__;.
+ </para>
+
+ <section>
+ <title>Supported Platforms</title>
+ <para>
+ 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.
+ </para>
+ <para>There are currently no plans to port Kea to Windows platforms.</para>
+ </section>
+
+ <section id="required-software">
+ <title>Required Software at Run-time</title>
+
+ <para>
+ 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
+ <xref linkend="build-requirements"/>.)
+ </para>
+
+ <para>
+ 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 (<ulink
+ url="http://www.python.org/"/>). 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++.
+ </para>
+
+ <para>
+ Kea uses the Botan crypto library for C++
+ (<ulink url="http://botan.randombit.net/"/>).
+ It requires at least Botan version 1.8.
+<!-- @todo 0.9/#2406: Add info about OpenSSL here -->
+ </para>
+
+ <para>
+ Kea uses the log4cplus C++ logging library
+ (<ulink url="http://log4cplus.sourceforge.net/"/>).
+ It requires at least log4cplus version 1.0.3.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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.
+ </para>
+ </section>
+
+ <section id="starting_stopping">
+ <title>Starting and Stopping the Server</title>
+ <!-- @todo: Rewrite this section as part of #3422-->
+ <para>
+ Kea is modular. Part of this modularity is
+ accomplished using multiple cooperating processes which, together,
+ provide the server functionality.
+ </para>
+
+ <!-- @todo: Rename processes here, once they are renamed in the source -->
+ <para>
+ At first, running many different processes may seem confusing.
+ However, these processes are started by running a single
+ command, <command>bind10</command>. This command starts
+ a master process, <command>b10-init</command>, which will
+ start other required processes and other processes when
+ configured. The processes that may be started have names
+ starting with "b10-", including:
+ </para>
+
+ <para>
+
+ <itemizedlist>
+
+ <listitem>
+ <simpara>
+ <command>b10-cfgmgr</command> —
+ Configuration manager.
+ This process maintains all of the configuration for BIND 10.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>b10-cmdctl</command> —
+ Command and control service.
+ This process allows external control of the BIND 10 system.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>b10-dhcp4</command> —
+ DHCPv4 server process.
+ This process responds to DHCPv4 queries from clients.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>b10-dhcp6</command> —
+ DHCPv6 server process.
+ This process responds to DHCPv6 queries from clients.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>b10-dhcp-ddns</command> —
+ 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.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>b10-msgq</command> —
+ Message bus daemon.
+ This process coordinates communication between all of the other
+ BIND 10 processes.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>b10-sockcreator</command> —
+ Socket creator daemon.
+ This process creates sockets used by
+ network-listening BIND 10 processes.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>b10-stats</command> —
+ Statistics collection daemon.
+ This process collects and reports statistics data.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>b10-stats-httpd</command> —
+ HTTP server for statistics reporting.
+ This process reports statistics data in XML format over HTTP.
+ </simpara>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+
+ <para>
+ These do not need to be manually started independently.
+ </para>
+
+ </section>
+
+ <section id="managing_once_running">
+ <title>Managing BIND 10</title>
+ <!-- @todo: Rewrite this section as part of #3422 -->
+
+ <para>
+ Once BIND 10 is running, a few commands are used to interact
+ directly with the system:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <command>bindctl</command> —
+ Interactive administration interface.
+ This is a low-level command-line tool which allows
+ a developer or an experienced administrator to control
+ Kea.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>b10-cmdctl-usermgr</command> —
+ User access control.
+ This tool allows an administrator to authorize additional users
+ to manage Kea.
+ </simpara>
+ </listitem>
+ <!-- TODO usermgr -->
+ </itemizedlist>
+ </para>
+ </section>
+
+ <para>
+ The tools and modules are covered in full detail in this guide.
+<!-- TODO point to these -->
+ In addition, manual pages are also provided in the default installation.
+ </para>
+
+<!--
+bin/
+ bindctl*
+ host*
+lib/
+ libauth
+ libdns
+ libexceptions
+ python3.1/site-packages/isc/{cc,config}
+sbin/
+ bind10
+share/
+ share/bind10/
+ auth.spec
+ b10-cmdctl.pem
+ init.spec
+ passwd.csv
+ man/
+var/
+ bind10/b10-config.db
+-->
+
+ <para>
+ 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.
+<!-- TODO point to this -->
+ </para>
+
+ </chapter>
</bookinfo>
- <chapter id="intro">
- <title>Introduction</title>
- <para>
- 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.
- </para>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="intro.xml" />
- <para>
- Kea has been initially developed as a part of the BIND 10 framework
- (<ulink url="http://bind10.isc.org"/>). 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++.
- </para>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="quickstart.xml" />
- <note>
- <simpara>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".
- </simpara>
- </note>
-
- <para>
- This guide covers Kea version &__VERSION__;.
- </para>
-
- <section>
- <title>Supported Platforms</title>
- <para>
- 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.
- </para>
- <para>There are currently no plans to port Kea to Windows platforms.</para>
- </section>
-
- <section id="required-software">
- <title>Required Software at Run-time</title>
-
- <para>
- 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
- <xref linkend="build-requirements"/>.)
- </para>
-
- <para>
- 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 (<ulink
- url="http://www.python.org/"/>). 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++.
- </para>
-
- <para>
- Kea uses the Botan crypto library for C++
- (<ulink url="http://botan.randombit.net/"/>).
- It requires at least Botan version 1.8.
-<!-- @todo 0.9/#2406: Add info about OpenSSL here -->
- </para>
-
- <para>
- Kea uses the log4cplus C++ logging library
- (<ulink url="http://log4cplus.sourceforge.net/"/>).
- It requires at least log4cplus version 1.0.3.
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- 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.
- </para>
- </section>
-
- <section id="starting_stopping">
- <title>Starting and Stopping the Server</title>
- <!-- @todo: Rewrite this section as part of #3422-->
- <para>
- Kea is modular. Part of this modularity is
- accomplished using multiple cooperating processes which, together,
- provide the server functionality.
- </para>
-
- <!-- @todo: Rename processes here, once they are renamed in the source -->
- <para>
- At first, running many different processes may seem confusing.
- However, these processes are started by running a single
- command, <command>bind10</command>. This command starts
- a master process, <command>b10-init</command>, which will
- start other required processes and other processes when
- configured. The processes that may be started have names
- starting with "b10-", including:
- </para>
-
- <para>
-
- <itemizedlist>
-
- <listitem>
- <simpara>
- <command>b10-cfgmgr</command> —
- Configuration manager.
- This process maintains all of the configuration for BIND 10.
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- <command>b10-cmdctl</command> —
- Command and control service.
- This process allows external control of the BIND 10 system.
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- <command>b10-dhcp4</command> —
- DHCPv4 server process.
- This process responds to DHCPv4 queries from clients.
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- <command>b10-dhcp6</command> —
- DHCPv6 server process.
- This process responds to DHCPv6 queries from clients.
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- <command>b10-dhcp-ddns</command> —
- 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.
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- <command>b10-msgq</command> —
- Message bus daemon.
- This process coordinates communication between all of the other
- BIND 10 processes.
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- <command>b10-sockcreator</command> —
- Socket creator daemon.
- This process creates sockets used by
- network-listening BIND 10 processes.
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- <command>b10-stats</command> —
- Statistics collection daemon.
- This process collects and reports statistics data.
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- <command>b10-stats-httpd</command> —
- HTTP server for statistics reporting.
- This process reports statistics data in XML format over HTTP.
- </simpara>
- </listitem>
-
- </itemizedlist>
- </para>
-
- <para>
- These do not need to be manually started independently.
- </para>
-
- </section>
-
- <section id="managing_once_running">
- <title>Managing BIND 10</title>
- <!-- @todo: Rewrite this section as part of #3422 -->
-
- <para>
- Once BIND 10 is running, a few commands are used to interact
- directly with the system:
- <itemizedlist>
- <listitem>
- <simpara>
- <command>bindctl</command> —
- Interactive administration interface.
- This is a low-level command-line tool which allows
- a developer or an experienced administrator to control
- Kea.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>b10-cmdctl-usermgr</command> —
- User access control.
- This tool allows an administrator to authorize additional users
- to manage Kea.
- </simpara>
- </listitem>
- <!-- TODO usermgr -->
- </itemizedlist>
- </para>
- </section>
-
- <para>
- The tools and modules are covered in full detail in this guide.
-<!-- TODO point to these -->
- In addition, manual pages are also provided in the default installation.
- </para>
-
-<!--
-bin/
- bindctl*
- host*
-lib/
- libauth
- libdns
- libexceptions
- python3.1/site-packages/isc/{cc,config}
-sbin/
- bind10
-share/
- share/bind10/
- auth.spec
- b10-cmdctl.pem
- init.spec
- passwd.csv
- man/
-var/
- bind10/b10-config.db
--->
-
- <para>
- 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.
-<!-- TODO point to this -->
- </para>
-
- </chapter>
-
- <chapter id="quickstart">
- <title>Quick start</title>
-
- <para>
- 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.
- </para>
-
- <section id="quick-start">
- <title>Quick start guide for DHCPv4 and DHCPv6 services</title>
-
- <orderedlist>
-
- <listitem>
- <simpara>
- Install required run-time and build dependencies. See <xref
- linkend="build-requirements"/> for details.
- </simpara>
- </listitem>
-
- <!-- We may need to replace it with the link to a downloadable tarball
- once we have it. -->
- <listitem>
- <simpara>
- Checkout the latest Kea revision from the Git repository:
- <screen>$ <userinput>git clone git://git.kea.isc.org/kea</userinput> </screen>
- </simpara>
- </listitem>
-
- <listitem>
- <para>Go into the source and run configure:
- <screen>$ <userinput>cd kea</userinput>
-$ <userinput>autoreconf --install</userinput>
-$ <userinput>./configure [your extra parameters]</userinput></screen>
- </para>
- </listitem>
-
- <listitem>
- <para>Build it:
- <screen>$ <userinput>make</userinput></screen>
- </para>
- </listitem>
-
- <listitem>
- <para>Install it as root (by default to prefix
- <filename>/usr/local/</filename>):
- <screen>$ <userinput>make install</userinput></screen>
- </para>
- </listitem>
-
- <listitem>
- <para>Edit your configuration file for DHCPv4. See doc/examples/kea4
- for a set of examples.
- </para>
- </listitem>
-
- <listitem>
- <para>Start Kea DHCPv4 server (as root):
- <screen># <userinput>b10-dhcp4 -c /path/to/your/kea4/config/file.json</userinput></screen>
- </para>
- </listitem>
-
- <listitem>
- <para>Test it; for example, use the
- <ulink url="http://www.isc.org/downloads/DHCP/">ISC DHCP client</ulink>
- to send DHCPv4 queries to the server and verify that the client receives a
- configuration from the server:
- <screen>$ <userinput>dhclient -4 eth0</userinput></screen>
- </para>
- </listitem>
-
- <listitem>
- <para>Edit your configuration file for DHCPv6. See doc/examples/kea6
- for a set of examples.
- </para>
- </listitem>
-
- <listitem>
- <para>Start Kea DHCPv6 server (as root):
- <screen># <userinput>b10-dhcp6 -c /path/to/your/kea6/config/file.json</userinput></screen>
- </para>
- </listitem>
-
- <listitem>
- <para>Test it; for example, use the
- <ulink url="http://www.isc.org/downloads/DHCP/">ISC DHCP client</ulink>
- to send DHCPv6 queries to the server and verify that the client receives a
- configuration from the server:
- <screen>$ <userinput>dhclient -6 eth0</userinput></screen>
- </para>
- </listitem>
-
-
- </orderedlist>
-
- </section>
-
- </chapter>
-
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="install.xml" />
-
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="config.xml" />
-
- <chapter id="dhcp4">
- <title>The DHCPv4 Server</title>
-
- <section id="dhcp4-start-stop">
- <title>Starting and Stopping the DHCPv4 Server</title>
-
- <para>
- <command>b10-dhcp4</command> is the Kea DHCPv4 server and is configured
- through the <command>bindctl</command> program.
- </para>
- <para>
- After starting <command>bind10</command> and entering bindctl, the first step
- in configuring the server is to add it to the list of running services.
-<screen>
-> <userinput>config add Init/components b10-dhcp4</userinput>
-> <userinput>config set Init/components/b10-dhcp4/kind dispensable</userinput>
-> <userinput>config commit</userinput>
-</screen>
- </para>
- <para>
- To remove <command>b10-dhcp4</command> from the set of running services,
- the <command>b10-dhcp4</command> is removed from list of Init components:
-<screen>
-> <userinput>config remove Init/components b10-dhcp4</userinput>
-> <userinput>config commit</userinput>
-</screen>
- </para>
- <para>
- 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:
-<screen>
-> <userinput>Dhcp4 shutdown</userinput>
-</screen>
- </para>
-
- <para>
- 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.
- </para>
-
- </section>
-
- <section id="dhcp4-configuration">
- <title>Configuring the DHCPv4 Server</title>
- <para>
- Once the server is started, it can be configured. To view the
- current configuration, use the following command in <command>bindctl</command>:
- <screen>
-> <userinput>config show Dhcp4</userinput></screen>
- When starting the DHCPv4 daemon for the first time, the default configuration
- will be available. It will look similar to this:
-<screen>
-> <userinput>config show Dhcp4</userinput>
-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
-</screen>
- </para>
-
- <para>
- To change one of the parameters, simply follow
- the usual <command>bindctl</command> procedure. For example, to make the
- leases longer, change their valid-lifetime parameter:
- <screen>
-> <userinput>config set Dhcp4/valid-lifetime 7200</userinput>
-> <userinput>config commit</userinput></screen>
- 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.
- </para>
- <para>
- 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.
- </para>
-
- <section>
- <title>Default storage for leases</title>
- <para>
- The server is able to store lease data in different repositories. Larger deployments
- may elect to store leases in a database.
- <xref linkend="database-configuration4"/> 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.
- </para>
- <para>
- 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.
- </para>
- <para>
- It is possible to alter the default location of the lease file. The following
- configuration:
-<screen>
-> <userinput>config set Dhcp4/lease-database/type "memfile"</userinput>
-> <userinput>config set Dhcp4/lease-database/persist true</userinput>
-> <userinput>config set Dhcp4/lease-database/name "/tmp/kea-leases4.csv"</userinput>
-> <userinput>config commit</userinput>
-</screen>
- will change the default location of the lease file to /tmp/kea-leases4.csv.
- </para>
- <para>
- 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
- </para>
- </section>
-
- <section id="database-configuration4">
- <title>Database Configuration</title>
- <para>
- All leases issued by the server are stored in the lease database. Currently
- there are 3 database backends available: MySQL, PostgreSQL and memfile.
- <footnote>
- <para>
- 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.
- </para>
- </footnote>, and so the server must be configured to
- access the correct database with the appropriate credentials.
- </para>
- <note>
- <para>
- 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.
- </para>
- </note>
- <para>
- Database configuration is controlled through the Dhcp4/lease-database parameters.
- The type of the database must be set to "mysql", "postgresql" or "memfile":
-<screen>
-> <userinput>config set Dhcp4/lease-database/type "mysql"</userinput>
-</screen>
- 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 <xref linkend="dhcp-mysql-database-create"/>
- or <xref linkend="dhcp-pgsql-database-create"/>).
-<screen>
-> <userinput>config set Dhcp4/lease-database/name "<replaceable>database-name</replaceable>"</userinput>
-</screen>
- 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):
-<screen>
-> <userinput>config set Dhcp4/lease-database/host "<replaceable>remote-host-name</replaceable>"</userinput>
-</screen>
- 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):
-<screen>
-> <userinput>config set Dhcp4/lease-database/host ""</userinput>
-</screen>
- </para>
- <para>
- Finally, the credentials of the account under which the server will access the database
- should be set:
-<screen>
-> <userinput>config set Dhcp4/lease-database/user "<replaceable>user-name</replaceable>"</userinput>
-> <userinput>config set Dhcp4/lease-database/password "<replaceable>password</replaceable>"</userinput>
-</screen>
- If there is no password to the account, set the password to the empty string "". (This is also the default.)
- </para>
- <note>
- <para>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.</para>
- </note>
- </section>
-
- <section id="dhcp4-interface-selection">
- <title>Interface selection</title>
- <para>
- 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.
- </para>
- <para>
- The default configuration can be presented with the following command:
- <screen>
-> <userinput>config show Dhcp4/interfaces</userinput>
-<userinput>Dhcp4/interfaces[0] "*" string</userinput></screen>
- An asterisk sign plays a role of the wildcard and means "listen on all interfaces".
- </para>
- <para>
- In order to override the default configuration, the existing entry can be replaced
- with the actual interface name:
- <screen>
-> <userinput>config set Dhcp4/interfaces[0] eth1</userinput>
-> <userinput>config commit</userinput></screen>
- Other interface names can be added on one-by-one basis:
- <screen>
-> <userinput>config add Dhcp4/interfaces eth2</userinput>
-> <userinput>config commit</userinput></screen>
- Configuration will now contain two interfaces which can be presented as follows:
- <screen>
-> <userinput>config show Dhcp4/interfaces</userinput>
-<userinput>Dhcp4/interfaces[0] "eth1" string</userinput>
-<userinput>Dhcp4/interfaces[1] "eth2" string</userinput></screen>
- When configuration gets committed, the server will start to listen on
- eth1 and eth2 interfaces only.
- </para>
- <para>
- It is possible to use wildcard interface name (asterisk) concurrently with explicit
- interface names:
- <screen>
-> <userinput>config add Dhcp4/interfaces *</userinput>
-> <userinput>config commit</userinput></screen>
- This will result in the following configuration:
- <screen>
-> <userinput>config show Dhcp4/interfaces</userinput>
-<userinput>Dhcp4/interfaces[0] "eth1" string</userinput>
-<userinput>Dhcp4/interfaces[1] "eth2" string</userinput>
-<userinput>Dhcp4/interfaces[2] "*" string</userinput></screen>
- 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:
- <screen>
-> <userinput>config remove Dhcp4/interfaces[2]</userinput>
-> <userinput>config commit</userinput></screen>
- </para>
- </section>
-
- <section id="ipv4-subnet-id">
- <title>IPv4 Subnet Identifier</title>
- <para>
- 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 ....
- </para>
- <para>
- 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.
- </para>
- <para>
- The following configuration:
- <screen>
-> <userinput>config add Dhcp4/subnet4</userinput>
-> <userinput>config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24"</userinput>
-> <userinput>config set Dhcp4/subnet4[0]/id 1024</userinput>
-> <userinput>config commit</userinput>
- </screen>
- 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.
- </para>
- </section>
-
- <section id="dhcp4-address-config">
- <title>Configuration of IPv4 Address Pools</title>
- <para>
- 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:
- <screen>
-> <userinput>config add Dhcp4/subnet4</userinput>
-> <userinput>config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24"</userinput>
-> <userinput>config set Dhcp4/subnet4[0]/pool [ "192.0.2.10 - 192.0.2.20" ]</userinput>
-> <userinput>config commit</userinput></screen>
- 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.</para>
- <para>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:
- <screen>
-> <userinput>config set Dhcp4/subnet4[0]/pool [ "192.0.2.10-192.0.2.20", "192.0.2.64/26" ]</userinput>
-> <userinput>config commit</userinput></screen>
- 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.
- </para>
- <para>
- The server may be configured to serve more than one subnet. To add a second subnet,
- use a command similar to the following:
- <screen>
-> <userinput>config add Dhcp4/subnet4</userinput>
-> <userinput>config set Dhcp4/subnet4[1]/subnet "192.0.3.0/24"</userinput>
-> <userinput>config set Dhcp4/subnet4[1]/pool [ "192.0.3.0/24" ]</userinput>
-> <userinput>config commit</userinput></screen>
- Arrays are counted from 0. subnet[0] refers to the subnet defined in the
- previous example. The <command>config add Dhcp4/subnet4</command> command adds
- another (second) subnet. It can be referred to as
- <command>Dhcp4/subnet4[1]</command>. In this example, we allow server to
- dynamically assign all addresses available in the whole subnet.
- </para>
- <para>
- 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.
- </para>
- </section>
-
- <section id="dhcp4-std-options">
- <title>Standard DHCPv4 options</title>
- <para>
- 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.
-
- <screen>
-> <userinput>config add Dhcp4/option-data</userinput>
-> <userinput>config set Dhcp4/option-data[0]/name "domain-name-servers"</userinput>
-> <userinput>config set Dhcp4/option-data[0]/code 6</userinput>
-> <userinput>config set Dhcp4/option-data[0]/space "dhcp4"</userinput>
-> <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
-> <userinput>config set Dhcp4/option-data[0]/data "192.0.3.1, 192.0.3.2"</userinput>
-> <userinput>config commit</userinput>
-</screen>
- </para>
- <para>
- 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 <xref linkend="dhcp4-std-options-list"/> 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 <xref
- linkend="dhcp4-option-spaces"/>. 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.
- </para>
-
- <para>
- 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.
- <screen>
-> <userinput>config add Dhcp4/option-data</userinput>
-> <userinput>config set Dhcp4/option-data[0]/name "domain-name-servers"</userinput>
-> <userinput>config set Dhcp4/option-data[0]/code 6</userinput>
-> <userinput>config set Dhcp4/option-data[0]/space "dhcp4"</userinput>
-> <userinput>config set Dhcp4/option-data[0]/csv-format false</userinput>
-> <userinput>config set Dhcp4/option-data[0]/data "C0 00 03 01 C0 00 03 02"</userinput>
-> <userinput>config commit</userinput>
- </screen>
- </para>
-
- <para>
- 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]).
- </para>
- <para>
- The following commands override the global
- DNS servers option for a particular subnet, setting a single DNS
- server with address 192.0.2.3.
- <screen>
-> <userinput>config add Dhcp4/subnet4[0]/option-data</userinput>
-> <userinput>config set Dhcp4/subnet4[0]/option-data[0]/name "domain-name-servers"</userinput>
-> <userinput>config set Dhcp4/subnet4[0]/option-data[0]/code 6</userinput>
-> <userinput>config set Dhcp4/subnet4[0]/option-data[0]/space "dhcp4"</userinput>
-> <userinput>config set Dhcp4/subnet4[0]/option-data[0]/csv-format true</userinput>
-> <userinput>config set Dhcp4/subnet4[0]/option-data[0]/data "192.0.2.3"</userinput>
-> <userinput>config commit</userinput></screen>
- </para>
-
- <note>
- <para>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.</para>
- </note>
-
- <para>
- The currently supported standard DHCPv4 options are
- listed in <xref linkend="dhcp4-std-options-list"/>
- and <xref linkend="dhcp4-std-options-list-part2"/>.
- 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 <xref linkend="dhcp-types"/>.
- </para>
- <para>
- 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.
- </para>
- <!-- @todo: describe record types -->
-
- <para>
- The <xref linkend="dhcp4-custom-options"/> 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
- <xref linkend="dhcp4-custom-options"/> 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.
- </para>
-
- <para>
- <table frame="all" id="dhcp4-std-options-list">
- <title>List of standard DHCPv4 options</title>
- <tgroup cols='4'>
- <colspec colname='name'/>
- <colspec colname='code'/>
- <colspec colname='type'/>
- <colspec colname='array'/>
- <thead>
- <row>
- <entry>Name</entry>
- <entry>Code</entry>
- <entry>Type</entry>
- <entry>Array?</entry>
- </row>
- </thead>
- <tbody>
-<row><entry>subnet-mask</entry><entry>1</entry><entry>ipv4-address</entry><entry>false</entry></row>
-<row><entry>time-offset</entry><entry>2</entry><entry>int32</entry><entry>false</entry></row>
-<row><entry>routers</entry><entry>3</entry><entry>ipv4-address</entry><entry>true</entry></row>
-<row><entry>time-servers</entry><entry>4</entry><entry>ipv4-address</entry><entry>true</entry></row>
-<row><entry>name-servers</entry><entry>5</entry><entry>ipv4-address</entry><entry>false</entry></row>
-<row><entry>domain-name-servers</entry><entry>6</entry><entry>ipv4-address</entry><entry>true</entry></row>
-<row><entry>log-servers</entry><entry>7</entry><entry>ipv4-address</entry><entry>true</entry></row>
-<row><entry>cookie-servers</entry><entry>8</entry><entry>ipv4-address</entry><entry>true</entry></row>
-<row><entry>lpr-servers</entry><entry>9</entry><entry>ipv4-address</entry><entry>true</entry></row>
-<row><entry>impress-servers</entry><entry>10</entry><entry>ipv4-address</entry><entry>true</entry></row>
-<row><entry>resource-location-servers</entry><entry>11</entry><entry>ipv4-address</entry><entry>true</entry></row>
-<row><entry>host-name</entry><entry>12</entry><entry>string</entry><entry>false</entry></row>
-<row><entry>boot-size</entry><entry>13</entry><entry>uint16</entry><entry>false</entry></row>
-<row><entry>merit-dump</entry><entry>14</entry><entry>string</entry><entry>false</entry></row>
-<row><entry>domain-name</entry><entry>15</entry><entry>fqdn</entry><entry>false</entry></row>
-<row><entry>swap-server</entry><entry>16</entry><entry>ipv4-address</entry><entry>false</entry></row>
-<row><entry>root-path</entry><entry>17</entry><entry>string</entry><entry>false</entry></row>
-<row><entry>extensions-path</entry><entry>18</entry><entry>string</entry><entry>false</entry></row>
-<row><entry>ip-forwarding</entry><entry>19</entry><entry>boolean</entry><entry>false</entry></row>
-<row><entry>non-local-source-routing</entry><entry>20</entry><entry>boolean</entry><entry>false</entry></row>
-<row><entry>policy-filter</entry><entry>21</entry><entry>ipv4-address</entry><entry>true</entry></row>
-<row><entry>max-dgram-reassembly</entry><entry>22</entry><entry>uint16</entry><entry>false</entry></row>
-<row><entry>default-ip-ttl</entry><entry>23</entry><entry>uint8</entry><entry>false</entry></row>
-<row><entry>path-mtu-aging-timeout</entry><entry>24</entry><entry>uint32</entry><entry>false</entry></row>
-<row><entry>path-mtu-plateau-table</entry><entry>25</entry><entry>uint16</entry><entry>true</entry></row>
-<row><entry>interface-mtu</entry><entry>26</entry><entry>uint16</entry><entry>false</entry></row>
-<row><entry>all-subnets-local</entry><entry>27</entry><entry>boolean</entry><entry>false</entry></row>
-<row><entry>broadcast-address</entry><entry>28</entry><entry>ipv4-address</entry><entry>false</entry></row>
-<row><entry>perform-mask-discovery</entry><entry>29</entry><entry>boolean</entry><entry>false</entry></row>
-<row><entry>mask-supplier</entry><entry>30</entry><entry>boolean</entry><entry>false</entry></row>
-<row><entry>router-discovery</entry><entry>31</entry><entry>boolean</entry><entry>false</entry></row>
-<row><entry>router-solicitation-address</entry><entry>32</entry><entry>ipv4-address</entry><entry>false</entry></row>
-<row><entry>static-routes</entry><entry>33</entry><entry>ipv4-address</entry><entry>true</entry></row>
-<row><entry>trailer-encapsulation</entry><entry>34</entry><entry>boolean</entry><entry>false</entry></row>
-<row><entry>arp-cache-timeout</entry><entry>35</entry><entry>uint32</entry><entry>false</entry></row>
-<row><entry>ieee802-3-encapsulation</entry><entry>36</entry><entry>boolean</entry><entry>false</entry></row>
-<row><entry>default-tcp-ttl</entry><entry>37</entry><entry>uint8</entry><entry>false</entry></row>
-<row><entry>tcp-keepalive-internal</entry><entry>38</entry><entry>uint32</entry><entry>false</entry></row>
-<row><entry>tcp-keepalive-garbage</entry><entry>39</entry><entry>boolean</entry><entry>false</entry></row>
-
- </tbody>
- </tgroup>
- </table>
- </para>
-
- <para>
- <table frame="all" id="dhcp4-std-options-list-part2">
- <title>List of standard DHCPv4 options (continued)</title>
- <tgroup cols='4'>
- <colspec colname='name'/>
- <colspec colname='code'/>
- <colspec colname='type'/>
- <colspec colname='array'/>
- <thead>
- <row>
- <entry>Name</entry>
- <entry>Code</entry>
- <entry>Type</entry>
- <entry>Array?</entry>
- </row>
- </thead>
- <tbody>
-
-<row><entry>nis-domain</entry><entry>40</entry><entry>string</entry><entry>false</entry></row>
-<row><entry>nis-servers</entry><entry>41</entry><entry>ipv4-address</entry><entry>true</entry></row>
-<row><entry>ntp-servers</entry><entry>42</entry><entry>ipv4-address</entry><entry>true</entry></row>
-<row><entry>vendor-encapsulated-options</entry><entry>43</entry><entry>empty</entry><entry>false</entry></row>
-<row><entry>netbios-name-servers</entry><entry>44</entry><entry>ipv4-address</entry><entry>true</entry></row>
-<row><entry>netbios-dd-server</entry><entry>45</entry><entry>ipv4-address</entry><entry>true</entry></row>
-<row><entry>netbios-node-type</entry><entry>46</entry><entry>uint8</entry><entry>false</entry></row>
-<row><entry>netbios-scope</entry><entry>47</entry><entry>string</entry><entry>false</entry></row>
-<row><entry>font-servers</entry><entry>48</entry><entry>ipv4-address</entry><entry>true</entry></row>
-<row><entry>x-display-manager</entry><entry>49</entry><entry>ipv4-address</entry><entry>true</entry></row>
-<row><entry>dhcp-requested-address</entry><entry>50</entry><entry>ipv4-address</entry><entry>false</entry></row>
-<!-- Lease time should not be configured by a user.
-<row><entry>dhcp-lease-time</entry><entry>51</entry><entry>uint32</entry><entry>false</entry></row>
--->
-<row><entry>dhcp-option-overload</entry><entry>52</entry><entry>uint8</entry><entry>false</entry></row>
-<!-- Message Type, Server Identifier and Parameter Request List should not be configured by a user.
-<row><entry>dhcp-message-type</entry><entry>53</entry><entry>uint8</entry><entry>false</entry></row>
-<row><entry>dhcp-server-identifier</entry><entry>54</entry><entry>ipv4-address</entry><entry>false</entry></row>
-<row><entry>dhcp-parameter-request-list</entry><entry>55</entry><entry>uint8</entry><entry>true</entry></row>
--->
-<row><entry>dhcp-message</entry><entry>56</entry><entry>string</entry><entry>false</entry></row>
-<row><entry>dhcp-max-message-size</entry><entry>57</entry><entry>uint16</entry><entry>false</entry></row>
-<!-- Renewal and rebinding time should not be configured by a user.
-<row><entry>dhcp-renewal-time</entry><entry>58</entry><entry>uint32</entry><entry>false</entry></row>
-<row><entry>dhcp-rebinding-time</entry><entry>59</entry><entry>uint32</entry><entry>false</entry></row>
--->
-<row><entry>vendor-class-identifier</entry><entry>60</entry><entry>binary</entry><entry>false</entry></row>
-<!-- Client identifier should not be configured by a user.
-<row><entry>dhcp-client-identifier</entry><entry>61</entry><entry>binary</entry><entry>false</entry></row>
--->
-<row><entry>nwip-domain-name</entry><entry>62</entry><entry>string</entry><entry>false</entry></row>
-<row><entry>nwip-suboptions</entry><entry>63</entry><entry>binary</entry><entry>false</entry></row>
-<row><entry>tftp-server-name</entry><entry>66</entry><entry>string</entry><entry>false</entry></row>
-<row><entry>boot-file-name</entry><entry>67</entry><entry>string</entry><entry>false</entry></row>
-<row><entry>user-class</entry><entry>77</entry><entry>binary</entry><entry>false</entry></row>
-<row><entry>fqdn</entry><entry>81</entry><entry>record</entry><entry>false</entry></row>
-<row><entry>dhcp-agent-options</entry><entry>82</entry><entry>empty</entry><entry>false</entry></row>
-<row><entry>authenticate</entry><entry>90</entry><entry>binary</entry><entry>false</entry></row>
-<row><entry>client-last-transaction-time</entry><entry>91</entry><entry>uint32</entry><entry>false</entry></row>
-<row><entry>associated-ip</entry><entry>92</entry><entry>ipv4-address</entry><entry>true</entry></row>
-<row><entry>subnet-selection</entry><entry>118</entry><entry>ipv4-address</entry><entry>false</entry></row>
-<row><entry>domain-search</entry><entry>119</entry><entry>binary</entry><entry>false</entry></row>
-<row><entry>vivco-suboptions</entry><entry>124</entry><entry>binary</entry><entry>false</entry></row>
-<row><entry>vivso-suboptions</entry><entry>125</entry><entry>binary</entry><entry>false</entry></row>
- </tbody>
- </tgroup>
- </table>
-
- </para>
- <para>
- <table frame="all" id="dhcp-types">
- <title>List of standard DHCP option types</title>
- <tgroup cols='2'>
- <colspec colname='name'/>
- <colspec colname='meaning'/>
- <thead>
- <row><entry>Name</entry><entry>Meaning</entry></row>
- </thead>
- <tbody>
- <row><entry>binary</entry><entry>An arbitrary string of bytes, specified as a set of hexadecimal digits.</entry></row>
- <row><entry>boolean</entry><entry>Boolean value with allowed values true or false</entry></row>
- <row><entry>empty</entry><entry>No value, data is carried in suboptions</entry></row>
- <row><entry>fqdn</entry><entry>Fully qualified domain name (e.g. www.example.com)</entry></row>
- <row><entry>ipv4-address</entry><entry>IPv4 address in the usual dotted-decimal notation (e.g. 192.0.2.1)</entry></row>
- <row><entry>ipv6-address</entry><entry>IPv6 address in the usual colon notation (e.g. 2001:db8::1)</entry></row>
- <row><entry>record</entry><entry>Structured data that may comprise any types (except "record" and "empty")</entry></row>
- <row><entry>string</entry><entry>Any text</entry></row>
- <row><entry>uint8</entry><entry>8 bit unsigned integer with allowed values 0 to 255</entry></row>
- <row><entry>uint16</entry><entry>16 bit unsinged integer with allowed values 0 to 65535</entry></row>
- <row><entry>uint32</entry><entry>32 bit unsigned integer with allowed values 0 to 4294967295</entry></row>
- </tbody>
- </tgroup>
- </table>
- </para>
- </section>
-
- <section id="dhcp4-custom-options">
- <title>Custom DHCPv4 options</title>
- <para>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:
- <screen>
-> <userinput>config add Dhcp4/option-def</userinput>
-> <userinput>config set Dhcp4/option-def[0]/name "foo"</userinput>
-> <userinput>config set Dhcp4/option-def[0]/code 222</userinput>
-> <userinput>config set Dhcp4/option-def[0]/type "uint32"</userinput>
-> <userinput>config set Dhcp4/option-def[0]/array false</userinput>
-> <userinput>config set Dhcp4/option-def[0]/record-types ""</userinput>
-> <userinput>config set Dhcp4/option-def[0]/space "dhcp4"</userinput>
-> <userinput>config set Dhcp4/option-def[0]/encapsulate ""</userinput>
-> <userinput>config commit</userinput></screen>
- 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.
- </para>
- <note>
- <para>
- 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.
- </para>
- </note>
-
- <para>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.
- <screen>
-> <userinput>config add Dhcp4/option-data</userinput>
-> <userinput>config set Dhcp4/option-data[0]/name "foo"</userinput>
-> <userinput>config set Dhcp4/option-data[0]/code 222</userinput>
-> <userinput>config set Dhcp4/option-data[0]/space "dhcp4"</userinput>
-> <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
-> <userinput>config set Dhcp4/option-data[0]/data "12345"</userinput>
-> <userinput>config commit</userinput></screen>
- </para>
-
- <para>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.
- </para>
- <para>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:
-<screen>
-> <userinput>config add Dhcp4/option-def</userinput>
-> <userinput>config set Dhcp4/option-def[0]/name "bar"</userinput>
-> <userinput>config set Dhcp4/option-def[0]/code 223</userinput>
-> <userinput>config set Dhcp4/option-def[0]/space "dhcp4"</userinput>
-> <userinput>config set Dhcp4/option-def[0]/type "record"</userinput>
-> <userinput>config set Dhcp4/option-def[0]/array false</userinput>
-> <userinput>config set Dhcp4/option-def[0]/record-types "ipv4-address, uint16, boolean, string"</userinput>
-> <userinput>config set Dhcp4/option-def[0]/encapsulate ""</userinput>
-</screen>
- 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 <xref linkend="dhcp-types"/>.
- </para>
- <para>
- The values of the option are set as follows:
-<screen>
-> <userinput>config add Dhcp4/option-data</userinput>
-> <userinput>config set Dhcp4/option-data[0]/name "bar"</userinput>
-> <userinput>config set Dhcp4/option-data[0]/space "dhcp4"</userinput>
-> <userinput>config set Dhcp4/option-data[0]/code 223</userinput>
-> <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
-> <userinput>config set Dhcp4/option-data[0]/data "192.0.2.100, 123, true, Hello World"</userinput>
-> <userinput>config commit</userinput></screen>
- "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.
- </para>
- <note>
- <para>
- 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.
- </para>
- </note>
- </section>
-
- <section id="dhcp4-vendor-opts">
- <title>DHCPv4 vendor specific options</title>
- <para>
- 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.
- </para>
- <para>
- The first step is to define the format of the option:
-<screen>
-> <userinput>config add Dhcp4/option-def</userinput>
-> <userinput>config set Dhcp4/option-def[0]/name "foo"</userinput>
-> <userinput>config set Dhcp4/option-def[0]/code 1</userinput>
-> <userinput>config set Dhcp4/option-def[0]/space "vendor-encapsulated-options-space"</userinput>
-> <userinput>config set Dhcp4/option-def[0]/type "record"</userinput>
-> <userinput>config set Dhcp4/option-def[0]/array false</userinput>
-> <userinput>config set Dhcp4/option-def[0]/record-types "ipv4-address, uint16, string"</userinput>
-> <userinput>config set Dhcp4/option-def[0]/encapsulates ""</userinput>
-> <userinput>config commit</userinput>
-</screen>
- (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:
- <screen>
-> <userinput>config add Dhcp4/option-data</userinput>
-> <userinput>config set Dhcp4/option-data[0]/name "foo"</userinput>
-> <userinput>config set Dhcp4/option-data[0]/space "vendor-encapsulated-options-space"</userinput>
-> <userinput>config set Dhcp4/option-data[0]/code 1</userinput>
-> <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
-> <userinput>config set Dhcp4/option-data[0]/data "192.0.2.3, 123, Hello World"</userinput>
-> <userinput>config commit</userinput></screen>
- 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.
- <screen>
-> <userinput>config add Dhcp4/option-data</userinput>
-> <userinput>config set Dhcp4/option-data[1]/name "vendor-encapsulated-options"</userinput>
-> <userinput>config set Dhcp4/option-data[1]/space "dhcp4"</userinput>
-> <userinput>config set Dhcp4/option-data[1]/code 43</userinput>
-> <userinput>config set Dhcp4/option-data[1]/csv-format false</userinput>
-> <userinput>config set Dhcp4/option-data[1]/data ""</userinput>
-> <userinput>config commit</userinput></screen>
- </para>
-
- <note>
- <para>
- 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.
- </para>
- </note>
-
- </section>
-
- <section id="dhcp4-option-spaces">
-
- <title>Nested DHCPv4 options (custom option spaces)</title>
- <para>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.
- </para>
- <para>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 <xref linkend="dhcp4-vendor-opts"/>).
- </para>
- <para>
- 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:
-<screen>
-> <userinput>config add Dhcp4/option-def</userinput>
-> <userinput>config set Dhcp4/option-def[0]/name "subopt1"</userinput>
-> <userinput>config set Dhcp4/option-def[0]/code 1</userinput>
-> <userinput>config set Dhcp4/option-def[0]/space "isc"</userinput>
-> <userinput>config set Dhcp4/option-def[0]/type "ipv4-address"</userinput>
-> <userinput>config set Dhcp4/option-def[0]/record-types ""</userinput>
-> <userinput>config set Dhcp4/option-def[0]/array false</userinput>
-> <userinput>config set Dhcp4/option-def[0]/encapsulate ""</userinput>
-> <userinput>config commit</userinput>
-
-> <userinput>config add Dhcp4/option-def</userinput>
-> <userinput>config set Dhcp4/option-def[1]/name "subopt2"</userinput>
-> <userinput>config set Dhcp4/option-def[1]/code 2</userinput>
-> <userinput>config set Dhcp4/option-def[1]/space "isc"</userinput>
-> <userinput>config set Dhcp4/option-def[1]/type "string"</userinput>
-> <userinput>config set Dhcp4/option-def[1]/record-types ""</userinput>
-> <userinput>config set Dhcp4/option-def[1]/array false</userinput>
-> <userinput>config set Dhcp4/option-def[1]/encapsulate ""</userinput>
-> <userinput>config commit</userinput>
-</screen>
- Note that we have defined the options to belong to a new option space
- (in this case, "isc").
- </para>
- <para>
- 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:
-<screen>
-> <userinput>add Dhcp4/option-def</userinput>
-> <userinput>set Dhcp4/option-def[2]/name "container"</userinput>
-> <userinput>set Dhcp4/option-def[2]/code 222</userinput>
-> <userinput>set Dhcp4/option-def[2]/space "dhcp4"</userinput>
-> <userinput>set Dhcp4/option-def[2]/type "empty"</userinput>
-> <userinput>set Dhcp4/option-def[2]/array false</userinput>
-> <userinput>set Dhcp4/option-def[2]/record-types ""</userinput>
-> <userinput>set Dhcp4/option-def[2]/encapsulate "isc"</userinput>
-> <userinput>commit</userinput>
-</screen>
- 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.
- </para>
- <para>
- Finally, we can set values for the new options:
-<screen>
-> <userinput>config add Dhcp4/option-data</userinput>
-> <userinput>config set Dhcp4/option-data[0]/name "subopt1"</userinput>
-> <userinput>config set Dhcp4/option-data[0]/space "isc"</userinput>
-> <userinput>config set Dhcp4/option-data[0]/code 1</userinput>
-> <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
-> <userinput>config set Dhcp4/option-data[0]/data "192.0.2.3"</userinput>
-> <userinput>config commit</userinput>
-<userinput></userinput>
-> <userinput>config add Dhcp4/option-data</userinput>
-> <userinput>config set Dhcp4/option-data[1]/name "subopt2"</userinput>
-> <userinput>config set Dhcp4/option-data[1]/space "isc"</userinput>
-> <userinput>config set Dhcp4/option-data[1]/code 2</userinput>
-> <userinput>config set Dhcp4/option-data[1]/csv-format true</userinput>
-> <userinput>config set Dhcp4/option-data[1]/data "Hello world"</userinput>
-> <userinput>config commit</userinput>
-<userinput></userinput>
-> <userinput>config add Dhcp4/option-data</userinput>
-> <userinput>config set Dhcp4/option-data[2]/name "container"</userinput>
-> <userinput>config set Dhcp4/option-data[2]/space "dhcp4"</userinput>
-> <userinput>config set Dhcp4/option-data[2]/code 222</userinput>
-> <userinput>config set Dhcp4/option-data[2]/csv-format true</userinput>
-> <userinput>config set Dhcp4/option-data[2]/data ""</userinput>
-> <userinput>config commit</userinput>
-</screen>
- 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.
- </para>
- <para>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.
- </para>
- </section>
-
- <section id="dhcp4-client-classifier">
- <title>Client Classification in DHCPv4</title>
- <note>
- <para>
- 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.
- </para>
- </note>
- <para>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".
- </para>
-
- <para>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.</para>
-
- <para>
- 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.
- </para>
-
- <para>
- 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 <xref linkend="dhcp4-subnet-class"/>.
- </para>
-
- </section>
-
- <section id="dhcp4-subnet-class">
- <title>Limiting access to IPv4 subnet to certain classes</title>
- <para>
- 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 <xref linkend="dhcp4-client-classifier"/>. This is an
- extension of a previous example from <xref linkend="dhcp4-address-config"/>.
- 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:
- <screen>
-> <userinput>config add Dhcp4/subnet4</userinput>
-> <userinput>config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24"</userinput>
-> <userinput>config set Dhcp4/subnet4[0]/pool [ "192.0.2.10 - 192.0.2.20" ]</userinput>
-> <userinput>config set Dhcp4/subnet4[0]/client-class "VENDOR_CLASS_docsis3.0"</userinput>
-> <userinput>config commit</userinput></screen>
- </para>
-
- <para>
- 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.
- </para>
- </section>
- <section id="dhcp4-ddns-config">
- <title>Configuring DHCPv4 for DDNS</title>
- <para>
- 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:
- <orderedlist>
- <listitem><para>
- Whether it is a request to add (update) or remove DNS entries
- </para></listitem>
- <listitem><para>
- Whether the change requests forward DNS updates (A records), reverse
- DNS updates (PTR records), or both.
- </para></listitem>
- <listitem><para>
- The FQDN, lease address, and DHCID
- </para></listitem>
- </orderedlist>
- 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:
-<screen>
-> <userinput>config show Dhcp4/dhcp-ddns</userinput>
-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
-</screen>
- </para>
- <para>
- 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:
- </para>
-<screen>
-> <userinput>config set Dhcp4/dhcp-ddns/enable-updates true</userinput>
-> <userinput>config commit</userinput>
-</screen>
- <section id="dhcpv4-d2-io-config">
- <title>DHCP-DDNS Server Connectivity</title>
- <para>
- 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:
- <orderedlist>
- <listitem><para>
- 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.
- </para></listitem>
- <listitem><para>
- server-port - port on which D2 listens for requests. The default value
- is 53001.
- </para></listitem>
- <listitem><para>
- 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.
- </para></listitem>
- <listitem><para>
- 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.
- </para></listitem>
- <listitem><para>
- ncr-format - Socket protocol use when sending requests to D2. Currently
- only UDP is supported. TCP may be available in an upcoming release.
- </para></listitem>
- <listitem><para>
- 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.
- </para></listitem>
- <listitem><para>
- 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.
- </para></listitem>
- </orderedlist>
- 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:
-<screen>
-> <userinput>config set Dhcp4/dhcp-ddns/server-ip "198.162.1.10"</userinput>
-> <userinput>config set Dhcp4/dhcp-ddns/server-port 900</userinput>
-> <userinput>config commit</userinput>
-</screen>
- </para>
- </section>
- <section id="dhcpv4-d2-rules-config">
- <title>When does the b10-dhcp4 server generate DDNS requests?</title>
- 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 (<xref linkend="dhcp-ddns-server"/>).
- <para>
- 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.
- </para>
- <para>
- In general, b10-dhcp4 will generate DDNS update requests when:
- <orderedlist>
- <listitem><para>
- A new lease is granted in response to a DHCP REQUEST
- </para></listitem>
- <listitem><para>
- An existing lease is renewed but the FQDN associated with it has
- changed.
- </para></listitem>
- <listitem><para>
- An existing lease is released in response to a DHCP RELEASE
- </para></listitem>
- </orderedlist>
- 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.
- </para>
- <para>
- 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:
- </para>
- <table id="fqdn-flag-table">
- <title>Default FQDN Flag Behavior</title>
- <tgroup cols='4' align='left'>
- <colspec colname='cflags'/>
- <colspec colname='meaning'/>
- <colspec colname='response'/>
- <colspec colname='sflags'/>
- <thead>
- <row>
- <entry>Client Flags:N-S</entry>
- <entry>Client Intent</entry>
- <entry>Server Response</entry>
- <entry>Server Flags:N-S-O</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>0-0</entry>
- <entry>
- Client wants to do forward updates, server should do reverse updates
- </entry>
- <entry>Server generates reverse-only request</entry>
- <entry>1-0-0</entry>
- </row>
- <row>
- <entry>0-1</entry>
- <entry>Server should do both forward and reverse updates</entry>
- <entry>Server generates request to update both directions</entry>
- <entry>0-1-0</entry>
- </row>
- <row>
- <entry>1-0</entry>
- <entry>Client wants no updates done</entry>
- <entry>Server does not generate a request</entry>
- <entry>1-0-0</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>
- 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.
- </para>
- <para>
- (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.)
- </para>
- <para>
- To override client delegation, issue the following commands:
- </para>
-<screen>
-> <userinput>config set Dhcp4/dhcp-ddns/override-client-update true</userinput>
-> <userinput>config commit</userinput>
-</screen>
- <para>
- 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.
- </para>
- <para>
- To override client delegation, issue the following commands:
- </para>
-<screen>
-> <userinput>config set Dhcp4/dhcp-ddns/override-no-update true</userinput>
-> <userinput>config commit</userinput>
-</screen>
- <para>
- 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.
- </para>
- </section>
- <section id="dhcpv4-fqdn-name-generation">
- <title>b10-dhcp4 name generation for DDNS update requests</title>
- 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.
- <para>
- The rules for determining the FQDN option are as follows:
- <orderedlist>
- <listitem><para>
- If configured to do, so ignore the REQUEST contents and generate a
- FQDN using a configurable prefix and suffix.
- </para></listitem>
- <listitem><para>
- 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:
- <orderedlist>
- <listitem><para>
- If the candidate name is a fully qualified domain name, use it.
- </para></listitem>
- <listitem><para>
- 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.
- </para></listitem>
- <listitem><para>
- If the candidate name is a empty, generate a FQDN using a
- configurable prefix and suffix.
- </para></listitem>
- </orderedlist>
- </para></listitem>
- </orderedlist>
- To instruct b10-dhcp4 to always generate the FQDN for a client, set the
- parameter "replace-client-name" to true as follows:
- </para>
-<screen>
-> <userinput>config set Dhcp4/dhcp-ddns/replace-client-name true</userinput>
-> <userinput>config commit</userinput>
-</screen>
- <para>
- 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:
- </para>
-<screen>
-> <userinput>config set Dhcp4/dhcp-ddns/generated-prefix "another.host"</userinput>
-> <userinput>config commit</userinput>
-</screen>
- <para>
- 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:
- </para>
-<screen>
-> <userinput>config set Dhcp4/dhcp-ddns/generated-prefix "our.net"</userinput>
-> <userinput>config commit</userinput>
-</screen>
- </section>
- <para>
- When generating a name, b10-dhcp4 will construct name of the format:
- </para>
- <para>
- [generated-prefix]-[address-text].[qualifying-suffix].
- </para>
- <para>
- 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:
- </para>
- <para>
- myhost-172-16-1-10.example.com.
- </para>
- </section>
-
- </section> <!-- end of configuring b10-dhcp4 server section with many subsections -->
-
- <section id="dhcp4-serverid">
- <title>Server Identifier in DHCPv4</title>
- <para>
- 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.
- </para>
- <para>
- 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.
- </para>
- </section>
-
-
- <section id="dhcp4-next-server">
- <title>Next server (siaddr)</title>
- <para>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.
- </para>
-
-<screen>
-> <userinput>config add Dhcp4/next-server</userinput>
-> <userinput>config set Dhcp4/next-server "192.0.2.123"</userinput>
-> <userinput>config commit</userinput>
-<userinput></userinput>
-> <userinput>config add Dhcp4/subnet[0]/next-server</userinput>
-> <userinput>config set Dhcp4/subnet[0]/next-server "192.0.2.234"</userinput>
-> <userinput>config commit</userinput>
-</screen>
-
- </section>
-
- <section id="dhcp4-echo-client-id">
- <title>Echoing client-id (RFC6842)</title>
- <para>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:</para>
-
-<screen>
-> <userinput>config add Dhcp4/echo-client-id</userinput>
-> <userinput>config set Dhcp4/echo-client-id False</userinput>
-> <userinput>config commit</userinput>
-</screen>
-
- </section>
-
- <section id="dhcp4-subnet-selection">
- <title>How DHCPv4 server selects subnet for a client</title>
- <para>
- 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.</para>
- <para>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.
- </para>
- <para>
- 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).
- </para>
- <para>
- 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.
- </para>
- <para>
- 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 <xref linkend="dhcp4-relay-override"/> for details.
- </para>
- <note>
- <para>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.</para>
- </note>
- </section>
-
- <section id="dhcp4-relay-override">
- <title>Using specific relay agent for a subnet</title>
- <para>
- 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.
- </para>
- <para>
- 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.
- </para>
- <para>
- 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.
- <screen>
-> <userinput>config add Dhcp4/subnet4</userinput>
-> <userinput>config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24"</userinput>
-> <userinput>config set Dhcp4/subnet4[0]/pool [ "192.0.2.10 - 192.0.2.20" ]</userinput>
-> <userinput>config set Dhcp4/subnet4[0]/relay/ip-address "10.0.0.1"</userinput>
-> <userinput>config commit</userinput></screen>
- </para>
-
- </section>
-
- <section id="dhcp4-srv-example-client-class-relay">
- <title>Segregating IPv4 clients in a cable network</title>
- <para>
- In certain cases, it is useful to mix relay address information,
- introduced in <xref linkend="dhcp4-relay-override"/> with client
- classification, explained in <xref linkend="dhcp4-subnet-class"/>.
- One specific example is cable network, where typically modems
- get addresses from a different subnet than all devices connected
- behind them.
- </para>
- <para>
- 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:
- <screen>
-> <userinput>config add Dhcp4/subnet4</userinput>
-> <userinput>config set Dhcp4/subnet4[0]/subnet "10.1.1.0/24"</userinput>
-> <userinput>config set Dhcp4/subnet4[0]/pool [ "10.1.1.2 - 10.1.1.20" ]</userinput>
-> <userinput>config set Dhcp4/subnet4[0]/client-class "docsis3.0"</userinput>
-> <userinput>config set Dhcp4/subnet4[0]/relay/ip-address "10.1.1.1"</userinput>
-> <userinput>config add Dhcp4/subnet4</userinput>
-> <userinput>config set Dhcp4/subnet4[1]/subnet "192.0.2.0/24"</userinput>
-> <userinput>config set Dhcp4/subnet4[1]/pool [ "192.0.2.10 - 192.0.2.20" ]</userinput>
-> <userinput>config set Dhcp4/subnet4[1]/relay/ip-address "10.1.1.1"</userinput>
-> <userinput>config commit</userinput></screen>
- </para>
- </section>
-
- <section id="dhcp4-std">
- <title>Supported Standards</title>
- <para>The following standards and draft standards are currently
- supported:</para>
- <itemizedlist>
- <listitem>
- <simpara><ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>: Supported messages are DISCOVER, OFFER,
- REQUEST, RELEASE, ACK, and NAK.</simpara>
- </listitem>
- <listitem>
- <simpara><ulink url="http://tools.ietf.org/html/rfc2132">RFC 2132</ulink>:
- 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).</simpara>
- </listitem>
- <listitem>
- <simpara><ulink url="http://tools.ietf.org/html/rfc3046">RFC 3046</ulink>:
- Relay Agent Information option is supported.</simpara>
- </listitem>
- <listitem>
- <simpara><ulink url="http://tools.ietf.org/html/rfc3925">RFC 3925</ulink>:
- Vendor-Identifying Vendor Class and Vendor-Identifying Vendor-Specific
- Information option are supported.</simpara>
- </listitem>
- <listitem>
- <simpara><ulink url="http://tools.ietf.org/html/rfc6842">RFC 6842</ulink>:
- Server by default sends back client-id option. That capability may be
- disabled. See <xref linkend="dhcp4-echo-client-id"/> for details.
- </simpara>
- </listitem>
- </itemizedlist>
- </section>
-
- <section id="dhcp4-limit">
- <title>DHCPv4 Server Limitations</title>
- <para>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 <quote>not implemented
- yet</quote>, rather than actual limitations.</para>
- <itemizedlist>
- <listitem> <!-- see tickets #3234, #3281 -->
- <simpara>
- Removal of a subnet during server reconfiguration may cause renumbering
- of auto-generated subnet identifiers, as described in section
- <xref linkend="ipv4-subnet-id"/>.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- BOOTP (<ulink url="http://tools.ietf.org/html/rfc951">RFC 951</ulink>)
- is not supported.
- </simpara>
- </listitem>
- <listitem>
- <simpara>Raw sockets operation is working on Linux
- only. See <xref linkend="iface-detect"/> for details.</simpara>
- </listitem>
- <listitem>
- <simpara>The DHCPv4 server does not verify that
- assigned address is unused. According to <ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>, the
- allocating server should verify that address is not used by
- sending ICMP echo request.</simpara>
- </listitem>
- <listitem>
- <simpara>Address duplication report (DECLINE) is not supported yet.</simpara>
- </listitem>
- <listitem>
- <simpara>
- 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.
- </simpara>
- </listitem>
- </itemizedlist>
- </section>
-
- <!--
- <section id="dhcp4-srv-examples">
- <title>Kea DHCPv4 server examples</title>
-
- <para>
- This section provides easy to use example. Each example can be read
- separately. It is not intended to be read sequentially as there will
- be many repetitions between examples. They are expected to serve as
- easy to use copy-paste solutions to many common deployments.
- </para>
-
- @todo: add simple configuration for direct clients
- @todo: add configuration for relayed clients
- @todo: add client classification example
-
- </section> -->
-
- </chapter>
-
- <chapter id="dhcp6">
- <title>The DHCPv6 Server</title>
-
- <section id="dhcp6-start-stop">
- <title>Starting and Stopping the DHCPv6 Server</title>
-
- <para>
- <command>b10-dhcp6</command> is the Kea DHCPv6 server and is configured
- through the <command>bindctl</command> program.
- </para>
- <para>
- After starting <command>bind10</command> and starting <command>bindctl</command>, the first step
- in configuring the server is to add <command>b10-dhcp6</command> to the list of running services.
-<screen>
-> <userinput>config add Init/components b10-dhcp6</userinput>
-> <userinput>config set Init/components/b10-dhcp6/kind dispensable</userinput>
-> <userinput>config commit</userinput>
-</screen>
- </para>
- <para>
- To remove <command>b10-dhcp6</command> from the set of running services,
- the <command>b10-dhcp6</command> is removed from list of Init components:
-<screen>
-> <userinput>config remove Init/components b10-dhcp6</userinput>
-> <userinput>config commit</userinput>
-</screen>
- </para>
-
- <para>
- 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:
-<screen>
-> <userinput>Dhcp6 shutdown</userinput>
-</screen>
- </para>
-
- <para>
- 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.
- </para>
-
-
- </section>
-
- <section id="dhcp6-configuration">
- <title>DHCPv6 Server Configuration</title>
- <para>
- Once the server has been started, it can be configured. To view the
- current configuration, use the following command in <command>bindctl</command>:
- <screen>> <userinput>config show Dhcp6</userinput></screen>
- When starting the Dhcp6 daemon for the first time, the default configuration
- will be available. It will look similar to this:
-<screen>
-> <userinput>config show Dhcp6</userinput>
-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
-</screen>
- </para>
- <para>
- To change one of the parameters, simply follow
- the usual <command>bindctl</command> procedure. For example, to make the
- leases longer, change their valid-lifetime parameter:
- <screen>
-> <userinput>config set Dhcp6/valid-lifetime 7200</userinput>
-> <userinput>config commit</userinput></screen>
- Most Dhcp6 parameters are of global scope
- and apply to all defined subnets, unless they are overridden on a
- per-subnet basis.
- </para>
- <note>
- <para>
- With this version of Kea, there are a number of known limitations
- and problems in the DHCPv6 server. See <xref linkend="dhcp6-limit"/>.
- </para>
- </note>
-
- <section>
- <title>Default storage for leases</title>
- <para>
- The server is able to store lease data in different repositories. Larger deployments
- may elect to store leases in a database.
- <xref linkend="database-configuration6"/> 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.
- </para>
- <para>
- 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.
- </para>
- <para>
- It is possible to alter the default location of the lease file. The following
- configuration:
-<screen>
-> <userinput>config set Dhcp4/lease-database/type "memfile"</userinput>
-> <userinput>config set Dhcp4/lease-database/persist true</userinput>
-> <userinput>config set Dhcp4/lease-database/leasefile "/tmp/kea-leases6.csv"</userinput>
-> <userinput>config commit</userinput>
-</screen>
- will change the default location of the lease file to /tmp/kea-leases6.csv.
- </para>
- <para>
- 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.
- </para>
- </section>
-
- <section id="database-configuration6">
- <title>Database Configuration</title>
- <para>
- All leases issued by the server are stored in the lease database. Currently
- there are 3 database backends available: MySQL, PostgreSQL and memfile.
- <footnote>
- <para>
- 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.
- </para>
- </footnote>, and so the server must be configured to
- access the correct database with the appropriate credentials.
- </para>
- <note>
- <para>
- 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.
- </para>
- </note>
- <para>
- Database configuration is controlled through the Dhcp6/lease-database parameters.
- The type of the database must be set to "mysql", "postgresql" or "memfile":
-<screen>
-> <userinput>config set Dhcp6/lease-database/type "mysql"</userinput>
-</screen>
- 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 <xref linkend="dhcp-mysql-database-create"/>
- or <xref linkend="dhcp-pgsql-database-create"/>).
-<screen>
-> <userinput>config set Dhcp6/lease-database/name "<replaceable>database-name</replaceable>"</userinput>
-</screen>
- 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):
-<screen>
-> <userinput>config set Dhcp6/lease-database/host "<replaceable>remote-host-name</replaceable>"</userinput>
-</screen>
- 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):
-<screen>
-> <userinput>config set Dhcp6/lease-database/host ""</userinput>
-</screen>
- </para>
- <para>
- Finally, the credentials of the account under which the server will access the database
- should be set:
-<screen>
-> <userinput>config set Dhcp6/lease-database/user "<replaceable>user-name</replaceable>"</userinput>
-> <userinput>config set Dhcp6/lease-database/password "<replaceable>password</replaceable>"</userinput>
-</screen>
- If there is no password to the account, set the password to the empty string "". (This is also the default.)
- </para>
- <note>
- <para>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.</para>
- </note>
- </section>
-
- <section id="dhcp6-interface-selection">
- <title>Interface selection</title>
- <para>
- 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.
- </para>
- <para>
- The default configuration can be presented with the following command:
- <screen>
-> <userinput>config show Dhcp6/interfaces</userinput>
-<userinput>Dhcp6/interfaces[0] "*" string</userinput></screen>
- An asterisk sign plays a role of the wildcard and means "listen on all interfaces".
- </para>
- <para>
- In order to override the default configuration, the existing entry can be replaced
- with the actual interface name:
- <screen>
-> <userinput>config set Dhcp6/interfaces[0] eth1</userinput>
-> <userinput>config commit</userinput></screen>
- Other interface names can be added on one-by-one basis:
- <screen>
-> <userinput>config add Dhcp6/interfaces eth2</userinput>
-> <userinput>config commit</userinput></screen>
- Configuration will now contain two interfaces which can be presented as follows:
- <screen>
-> <userinput>config show Dhcp6/interfaces</userinput>
-<userinput>Dhcp6/interfaces[0] "eth1" string</userinput>
-<userinput>Dhcp6/interfaces[1] "eth2" string</userinput></screen>
- When configuration gets committed, the server will start to listen on
- eth1 and eth2 interfaces only.
- </para>
- <para>
- It is possible to use wildcard interface name (asterisk) concurrently with explicit
- interface names:
- <screen>
-> <userinput>config add Dhcp6/interfaces *</userinput>
-> <userinput>config commit</userinput></screen>
- This will result in the following configuration:
- <screen>
-> <userinput>config show Dhcp6/interfaces</userinput>
-<userinput>Dhcp6/interfaces[0] "eth1" string</userinput>
-<userinput>Dhcp6/interfaces[1] "eth2" string</userinput>
-<userinput>Dhcp6/interfaces[2] "*" string</userinput></screen>
- 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:
- <screen>
-> <userinput>config remove Dhcp6/interfaces[2]</userinput>
-> <userinput>config commit</userinput></screen>
- </para>
- </section>
-
- <section id="ipv6-subnet-id">
- <title>IPv6 Subnet Identifier</title>
- <para>
- 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 ....
- </para>
- <para>
- 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.
- </para>
- <para>
- The following configuration:
- <screen>
-> <userinput>config add Dhcp6/subnet6</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64"</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/id 1024</userinput>
-> <userinput>config commit</userinput>
- </screen>
- 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.
- </para>
- </section>
-
- <section id="dhcp6-unicast">
- <title>Unicast traffic support</title>
- <para>
- 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 <xref linkend="dhcp6-interface-selection"/>).
- 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.
- </para>
- <para>
- <screen>
-> <userinput>config set Dhcp6/interfaces[0] eth1/2001:db8::1</userinput>
-> <userinput>config commit</userinput></screen>
- 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.
- </para>
- <para>
- 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.
- </para>
- <para>
- 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.
- </para>
- </section>
-
- <section id="dhcp6-address-config">
- <title>Subnet and Address Pool</title>
- <para>
- 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:
- <screen>
-> <userinput>config add Dhcp6/subnet6</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64"</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::0 - 2001:db8:1::ffff" ]</userinput>
-> <userinput>config commit</userinput></screen>
- 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.</para>
- <para>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:
- <screen>
-> <userinput>config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::1 - 2001:db8:1::ffff", "2001:db8:1:0:5::/80" ]</userinput>
-> <userinput>config commit</userinput></screen>
- The number of pools is not limited, but for performance reasons it is recommended to
- use as few as possible.
- </para>
- <para>
- The server may be configured to serve more than one subnet. To add a second subnet,
- use a command similar to the following:
- <screen>
-> <userinput>config add Dhcp6/subnet6</userinput>
-> <userinput>config set Dhcp6/subnet6[1]/subnet "2001:db8:beef::/48"</userinput>
-> <userinput>config set Dhcp6/subnet6[1]/pool [ "2001:db8:beef::/48" ]</userinput>
-> <userinput>config commit</userinput></screen>
- Arrays are counted from 0. subnet[0] refers to the subnet defined in the
- previous example. The <command>config add Dhcp6/subnet6</command> command adds
- another (second) subnet. It can be referred to as
- <command>Dhcp6/subnet6[1]</command>. 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.
- </para>
- <para>
- 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.
- </para>
- </section>
-
- <section>
-<!-- @todo: add real meat to the prefix delegation config this is just place holder stuff -->
- <title>Subnet and Prefix Delegation Pools</title>
- <para>
- 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:
- <screen>
-> <userinput>config add Dhcp6/subnet6</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64"</userinput>
-> <userinput>config show Dhcp6/subnet6[0]</userinput>
-> <userinput>config add Dhcp6/subnet6[0]/pd-pools</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/pd-pools[0]/prefix "2001:db8:1::"</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/pd-pools[0]/prefix-len 64</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/pd-pools[0]/delegated-len 96</userinput>
-> <userinput>config commit</userinput></screen>
- </para>
- </section>
-
- <section id="dhcp6-std-options">
- <title>Standard DHCPv6 options</title>
- <para>
- 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.
-
- <screen>
-1. > <userinput>config add Dhcp6/option-data</userinput>
-2. > <userinput>config set Dhcp6/option-data[0]/name "dns-servers"</userinput>
-3. > <userinput>config set Dhcp6/option-data[0]/code 23</userinput>
-4. > <userinput>config set Dhcp6/option-data[0]/space "dhcp6"</userinput>
-5. > <userinput>config set Dhcp6/option-data[0]/csv-format true</userinput>
-6. > <userinput>config set Dhcp6/option-data[0]/data "2001:db8::cafe, 2001:db8::babe"</userinput>
-7. > <userinput>config commit</userinput>
-</screen>
- </para>
- <para>
- 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 <xref linkend="dhcp6-std-options-list"/>.
- 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 <xref
- linkend="dhcp6-option-spaces"/>. 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.
- </para>
-
- <para>
- 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.
- <screen>
-> <userinput>config add Dhcp6/option-data</userinput>
-> <userinput>config set Dhcp6/option-data[0]/name "dns-servers"</userinput>
-> <userinput>config set Dhcp6/option-data[0]/code 23</userinput>
-> <userinput>config set Dhcp6/option-data[0]/space "dhcp6"</userinput>
-> <userinput>config set Dhcp6/option-data[0]/csv-format false</userinput>
-> <userinput>config set Dhcp6/option-data[0]/data "2001 0DB8 0001 0000 0000 0000</userinput>
- <userinput>0000 CAFE 2001 0DB8 0001 0000 0000 0000 0000 BABE"</userinput>
-> <userinput>config commit</userinput>
- </screen>
- (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.)
- </para>
-
- <para>
- 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]).
- </para>
- <para>
- The following commands override the global
- DNS servers option for a particular subnet, setting a single DNS
- server with address 2001:db8:1::3.
- <screen>
-> <userinput>config add Dhcp6/subnet6[0]/option-data</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/option-data[0]/name "dns-servers"</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/option-data[0]/code 23</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/option-data[0]/space "dhcp6"</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/option-data[0]/csv-format true</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/option-data[0]/data "2001:db8:1::3"</userinput>
-> <userinput>config commit</userinput></screen>
- </para>
-
- <note>
- <para>
- 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.
- </para>
- </note>
-
-
- <para>
- The currently supported standard DHCPv6 options are
- listed in <xref linkend="dhcp6-std-options-list"/>.
- 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 <xref linkend="dhcp-types"/>.
- </para>
- <para>
- 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.
- </para>
-
-<!-- @todo: describe record types -->
-
- <para>
- The <xref linkend="dhcp6-custom-options"/> 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
- <xref linkend="dhcp6-custom-options"/> 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.
- </para>
-
-
- <para>
- <table frame="all" id="dhcp6-std-options-list">
- <title>List of standard DHCPv6 options</title>
- <tgroup cols='4'>
- <colspec colname='name'/>
- <colspec colname='code'/>
- <colspec colname='type'/>
- <colspec colname='array'/>
- <thead>
- <row><entry>Name</entry><entry>Code</entry><entry>Type</entry><entry>Array?</entry></row>
- </thead>
- <tbody>
-<!-- Our engine uses those options on its own, admin must not configure them on his own
-<row><entry>clientid</entry><entry>1</entry><entry>binary</entry><entry>false</entry></row>
-<row><entry>serverid</entry><entry>2</entry><entry>binary</entry><entry>false</entry></row>
-<row><entry>ia-na</entry><entry>3</entry><entry>record</entry><entry>false</entry></row>
-<row><entry>ia-ta</entry><entry>4</entry><entry>uint32</entry><entry>false</entry></row>
-<row><entry>iaaddr</entry><entry>5</entry><entry>record</entry><entry>false</entry></row>
-<row><entry>oro</entry><entry>6</entry><entry>uint16</entry><entry>true</entry></row> -->
-<row><entry>preference</entry><entry>7</entry><entry>uint8</entry><entry>false</entry></row>
-
-<!-- Our engine uses those options on its own, admin must not configure them on his own
-<row><entry>elapsed-time</entry><entry>8</entry><entry>uint16</entry><entry>false</entry></row>
-<row><entry>relay-msg</entry><entry>9</entry><entry>binary</entry><entry>false</entry></row>
-<row><entry>auth</entry><entry>11</entry><entry>binary</entry><entry>false</entry></row>
-<row><entry>unicast</entry><entry>12</entry><entry>ipv6-address</entry><entry>false</entry></row>
-<row><entry>status-code</entry><entry>13</entry><entry>record</entry><entry>false</entry></row>
-<row><entry>rapid-commit</entry><entry>14</entry><entry>empty</entry><entry>false</entry></row>
-<row><entry>user-class</entry><entry>15</entry><entry>binary</entry><entry>false</entry></row>
-<row><entry>vendor-class</entry><entry>16</entry><entry>record</entry><entry>false</entry></row>
-<row><entry>vendor-opts</entry><entry>17</entry><entry>uint32</entry><entry>false</entry></row>
-<row><entry>interface-id</entry><entry>18</entry><entry>binary</entry><entry>false</entry></row>
-<row><entry>reconf-msg</entry><entry>19</entry><entry>uint8</entry><entry>false</entry></row>
-<row><entry>reconf-accept</entry><entry>20</entry><entry>empty</entry><entry>false</entry></row> -->
-<row><entry>sip-server-dns</entry><entry>21</entry><entry>fqdn</entry><entry>true</entry></row>
-<row><entry>sip-server-addr</entry><entry>22</entry><entry>ipv6-address</entry><entry>true</entry></row>
-<row><entry>dns-servers</entry><entry>23</entry><entry>ipv6-address</entry><entry>true</entry></row>
-<row><entry>domain-search</entry><entry>24</entry><entry>fqdn</entry><entry>true</entry></row>
-<!-- <row><entry>ia-pd</entry><entry>25</entry><entry>record</entry><entry>false</entry></row> -->
-<!-- <row><entry>iaprefix</entry><entry>26</entry><entry>record</entry><entry>false</entry></row> -->
-<row><entry>nis-servers</entry><entry>27</entry><entry>ipv6-address</entry><entry>true</entry></row>
-<row><entry>nisp-servers</entry><entry>28</entry><entry>ipv6-address</entry><entry>true</entry></row>
-<row><entry>nis-domain-name</entry><entry>29</entry><entry>fqdn</entry><entry>true</entry></row>
-<row><entry>nisp-domain-name</entry><entry>30</entry><entry>fqdn</entry><entry>true</entry></row>
-<row><entry>sntp-servers</entry><entry>31</entry><entry>ipv6-address</entry><entry>true</entry></row>
-<row><entry>information-refresh-time</entry><entry>32</entry><entry>uint32</entry><entry>false</entry></row>
-<row><entry>bcmcs-server-dns</entry><entry>33</entry><entry>fqdn</entry><entry>true</entry></row>
-<row><entry>bcmcs-server-addr</entry><entry>34</entry><entry>ipv6-address</entry><entry>true</entry></row>
-<row><entry>geoconf-civic</entry><entry>36</entry><entry>record</entry><entry>false</entry></row>
-<row><entry>remote-id</entry><entry>37</entry><entry>record</entry><entry>false</entry></row>
-<row><entry>subscriber-id</entry><entry>38</entry><entry>binary</entry><entry>false</entry></row>
-<row><entry>client-fqdn</entry><entry>39</entry><entry>record</entry><entry>false</entry></row>
-<row><entry>pana-agent</entry><entry>40</entry><entry>ipv6-address</entry><entry>true</entry></row>
-<row><entry>new-posix-timezone</entry><entry>41</entry><entry>string</entry><entry>false</entry></row>
-<row><entry>new-tzdb-timezone</entry><entry>42</entry><entry>string</entry><entry>false</entry></row>
-<row><entry>ero</entry><entry>43</entry><entry>uint16</entry><entry>true</entry></row>
-<row><entry>lq-query</entry><entry>44</entry><entry>record</entry><entry>false</entry></row>
-<row><entry>client-data</entry><entry>45</entry><entry>empty</entry><entry>false</entry></row>
-<row><entry>clt-time</entry><entry>46</entry><entry>uint32</entry><entry>false</entry></row>
-<row><entry>lq-relay-data</entry><entry>47</entry><entry>record</entry><entry>false</entry></row>
-<row><entry>lq-client-link</entry><entry>48</entry><entry>ipv6-address</entry><entry>true</entry></row>
- </tbody>
- </tgroup>
- </table>
- </para>
- </section>
-
- <section id="dhcp6-custom-options">
- <title>Custom DHCPv6 options</title>
- <para>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:
- <screen>
-> <userinput>config add Dhcp6/option-def</userinput>
-> <userinput>config set Dhcp6/option-def[0]/name "foo"</userinput>
-> <userinput>config set Dhcp6/option-def[0]/code 100</userinput>
-> <userinput>config set Dhcp6/option-def[0]/type "uint32"</userinput>
-> <userinput>config set Dhcp6/option-def[0]/array false</userinput>
-> <userinput>config set Dhcp6/option-def[0]/record-types ""</userinput>
-> <userinput>config set Dhcp6/option-def[0]/space "dhcp6"</userinput>
-> <userinput>config set Dhcp6/option-def[0]/encapsulate ""</userinput>
-> <userinput>config commit</userinput></screen>
- 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.
- </para>
- <para>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.
- <screen>
-> <userinput>config add Dhcp6/option-data</userinput>
-> <userinput>config set Dhcp6/option-data[0]/name "foo"</userinput>
-> <userinput>config set Dhcp6/option-data[0]/code 100</userinput>
-> <userinput>config set Dhcp6/option-data[0]/space "dhcp6"</userinput>
-> <userinput>config set Dhcp6/option-data[0]/csv-format true</userinput>
-> <userinput>config set Dhcp6/option-data[0]/data "12345"</userinput>
-> <userinput>config commit</userinput></screen>
- </para>
-
- <para>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.
- </para>
- <para>
- 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:
-<screen>
-> <userinput>config add Dhcp6/option-def</userinput>
-> <userinput>config set Dhcp6/option-def[0]/name "bar"</userinput>
-> <userinput>config set Dhcp6/option-def[0]/code 101</userinput>
-> <userinput>config set Dhcp6/option-def[0]/space "dhcp6"</userinput>
-> <userinput>config set Dhcp6/option-def[0]/type "record"</userinput>
-> <userinput>config set Dhcp6/option-def[0]/array false</userinput>
-> <userinput>config set Dhcp6/option-def[0]/record-types "ipv6-address, uint16, boolean, string"</userinput>
-> <userinput>config set Dhcp6/option-def[0]/encapsulate ""</userinput>
-</screen>
- 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 <xref linkend="dhcp-types"/>.
- </para>
- <para>
- The values of the option are set as follows:
-<screen>
-> <userinput>config add Dhcp6/option-data</userinput>
-> <userinput>config set Dhcp6/option-data[0]/name "bar"</userinput>
-> <userinput>config set Dhcp6/option-data[0]/space "dhcp6"</userinput>
-> <userinput>config set Dhcp6/option-data[0]/code 101</userinput>
-> <userinput>config set Dhcp6/option-data[0]/csv-format true</userinput>
-> <userinput>config set Dhcp6/option-data[0]/data "2001:db8:1::10, 123, false, Hello World"</userinput>
-> <userinput>config commit</userinput></screen>
- "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.
- </para>
- <note>
- <para>
- 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.
- </para>
- </note>
- </section>
-
- <section id="dhcp6-vendor-opts">
- <title>DHCPv6 vendor specific options</title>
- <para>
- 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.
- <screen>
-> <userinput>config add Dhcp6/option-def</userinput>
-> <userinput>config set Dhcp6/option-def[0]/name "foo"</userinput>
-> <userinput>config set Dhcp6/option-def[0]/code 1</userinput>
-> <userinput>config set Dhcp6/option-def[0]/space "vendor-opts-space"</userinput>
-> <userinput>config set Dhcp6/option-def[0]/type "record"</userinput>
-> <userinput>config set Dhcp6/option-def[0]/array false</userinput>
-> <userinput>config set Dhcp6/option-def[0]/record-types "ipv6-address, uint16, string"</userinput>
-> <userinput>config set Dhcp6/option-def[0]/encapsulates ""</userinput>
-> <userinput>config commit</userinput>
-</screen>
- (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:
- <screen>
-> <userinput>config add Dhcp6/option-data</userinput>
-> <userinput>config set Dhcp6/option-data[0]/name "foo"</userinput>
-> <userinput>config set Dhcp6/option-data[0]/space "vendor-opts-space"</userinput>
-> <userinput>config set Dhcp6/option-data[0]/code 1</userinput>
-> <userinput>config set Dhcp6/option-data[0]/csv-format true</userinput>
-> <userinput>config set Dhcp6/option-data[0]/data "2001:db8:1::10, 123, Hello World"</userinput>
-> <userinput>config commit</userinput></screen>
- We should also define values for the vendor-opts, that will convey our option foo.
- <screen>
-> <userinput>config add Dhcp6/option-data</userinput>
-> <userinput>config set Dhcp6/option-data[1]/name "vendor-opts"</userinput>
-> <userinput>config set Dhcp6/option-data[1]/space "dhcp6"</userinput>
-> <userinput>config set Dhcp6/option-data[1]/code 17</userinput>
-> <userinput>config set Dhcp6/option-data[1]/csv-format true</userinput>
-> <userinput>config set Dhcp6/option-data[1]/data "12345"</userinput>
-> <userinput>config commit</userinput></screen>
- </para>
- </section>
-
- <section id="dhcp6-option-spaces">
- <title>Nested DHCPv6 options (custom option spaces)</title>
- <para>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.
- </para>
- <para>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 <xref linkend="dhcp6-vendor-opts"/>).
- </para>
- <para>
- 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:
-<screen>
-> <userinput>config add Dhcp6/option-def</userinput>
-> <userinput>config set Dhcp6/option-def[0]/name "subopt1"</userinput>
-> <userinput>config set Dhcp6/option-def[0]/code 1</userinput>
-> <userinput>config set Dhcp6/option-def[0]/space "isc"</userinput>
-> <userinput>config set Dhcp6/option-def[0]/type "ipv6-address"</userinput>
-> <userinput>config set Dhcp6/option-def[0]/record-types ""</userinput>
-> <userinput>config set Dhcp6/option-def[0]/array false</userinput>
-> <userinput>config set Dhcp6/option-def[0]/encapsulate ""</userinput>
-> <userinput>config commit</userinput>
-> <userinput></userinput>
-> <userinput>config add Dhcp6/option-def</userinput>
-> <userinput>config set Dhcp6/option-def[1]/name "subopt2"</userinput>
-> <userinput>config set Dhcp6/option-def[1]/code 2</userinput>
-> <userinput>config set Dhcp6/option-def[1]/space "isc"</userinput>
-> <userinput>config set Dhcp6/option-def[1]/type "string"</userinput>
-> <userinput>config set Dhcp6/option-def[1]/record-types ""</userinput>
-> <userinput>config set Dhcp6/option-def[1]/array false</userinput>
-> <userinput>config set Dhcp6/option-def[1]/encapsulate ""</userinput>
-> <userinput>config commit</userinput>
-</screen>
- Note that we have defined the options to belong to a new option space
- (in this case, "isc").
- </para>
- <para>
-The next step is to define a regular DHCPv6 option and specify that it
-should include options from the isc option space:
-<screen>
-> <userinput>config add Dhcp6/option-def</userinput>
-> <userinput>config set Dhcp6/option-def[2]/name "container"</userinput>
-> <userinput>config set Dhcp6/option-def[2]/code 102</userinput>
-> <userinput>config set Dhcp6/option-def[2]/space "dhcp6"</userinput>
-> <userinput>config set Dhcp6/option-def[2]/type "empty"</userinput>
-> <userinput>config set Dhcp6/option-def[2]/array false</userinput>
-> <userinput>config set Dhcp6/option-def[2]/record-types ""</userinput>
-> <userinput>config set Dhcp6/option-def[2]/encapsulate "isc"</userinput>
-> <userinput>config commit</userinput>
-</screen>
- 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.
- </para>
- <para>
- Finally, we can set values for the new options:
-<screen>
-> <userinput>config add Dhcp6/option-data</userinput>
-> <userinput>config set Dhcp6/option-data[0]/name "subopt1"</userinput>
-> <userinput>config set Dhcp6/option-data[0]/space "isc"</userinput>
-> <userinput>config set Dhcp6/option-data[0]/code 1</userinput>
-> <userinput>config set Dhcp6/option-data[0]/csv-format true</userinput>
-> <userinput>config set Dhcp6/option-data[0]/data "2001:db8::abcd"</userinput>
-> <userinput>config commit</userinput>
-> <userinput></userinput>
-> <userinput>config add Dhcp6/option-data</userinput>
-> <userinput>config set Dhcp6/option-data[1]/name "subopt2"</userinput>
-> <userinput>config set Dhcp6/option-data[1]/space "isc"</userinput>
-> <userinput>config set Dhcp6/option-data[1]/code 2</userinput>
-> <userinput>config set Dhcp6/option-data[1]/csv-format true</userinput>
-> <userinput>config set Dhcp6/option-data[1]/data "Hello world"</userinput>
-> <userinput>config commit</userinput>
-> <userinput></userinput>
-> <userinput>config add Dhcp6/option-data</userinput>
-> <userinput>config set Dhcp6/option-data[2]/name "container"</userinput>
-> <userinput>config set Dhcp6/option-data[2]/space "dhcp6"</userinput>
-> <userinput>config set Dhcp6/option-data[2]/code 102</userinput>
-> <userinput>config set Dhcp6/option-data[2]/csv-format true</userinput>
-> <userinput>config set Dhcp6/option-data[2]/data ""</userinput>
-> <userinput>config commit</userinput>
-</screen>
- 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.
- </para>
- <para>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.
- </para>
- </section>
-
- <section id="dhcp6-config-subnets">
- <title>IPv6 Subnet Selection</title>
- <para>
- 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.
- </para>
- <para>
- 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:
-<screen>
-> <userinput>config add Dhcp6/subnet6</userinput>
-> <userinput>config set Dhcp6/subnet6[1]/subnet "2001:db8:beef::/48"</userinput>
-> <userinput>config set Dhcp6/subnet6[1]/pool [ "2001:db8:beef::/48" ]</userinput>
-> <userinput>config set Dhcp6/subnet6[1]/interface "eth0"</userinput>
-> <userinput>config commit</userinput>
-</screen>
- </para>
- </section>
-
- <section id="dhcp6-relays">
- <title>DHCPv6 Relays</title>
- <para>
- 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:
- </para>
- <para>
- 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.
- </para>
- <para>
- 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.
- </para>
- <para>
- When configuring the DHCPv6 server, it should be noted that two
- similarly-named parameters can be configured for a subnet:
- <itemizedlist>
- <listitem><simpara>
- "interface" defines which local network interface can be used
- to access a given subnet.
- </simpara></listitem>
- <listitem><simpara>
- "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.
- </simpara></listitem>
- </itemizedlist>
- 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.
- </para>
-
- <para>
- To specify interface-id with value "vlan123", the following commands can
- be used:
- <screen>
-> <userinput>config add Dhcp6/subnet6</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/subnet "2001:db8:beef::/48"</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/pool [ "2001:db8:beef::/48" ]</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/interface-id "vland123"</userinput>
-> <userinput>config commit</userinput>
-</screen>
- </para>
- </section>
-
- <section id="dhcp6-client-classifier">
- <title>Client Classification in DHCPv6</title>
- <note>
- <para>
- 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.
- </para>
- </note>
- <para>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".
- </para>
-
- <para>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.</para>
-
- <para>
- 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 <xref linkend="dhcp6-subnet-class"/>.
- </para>
-
- </section>
-
- <section id="dhcp6-subnet-class">
- <title>Limiting access to IPv6 subnet to certain classes</title>
- <para>
- 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 <xref linkend="dhcp6-client-classifier"/>. This is an
- extension of a previous example from <xref linkend="dhcp6-address-config"/>.
-
- 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:
-
- <screen>
-> <userinput>config add Dhcp6/subnet6</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64"</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::0 - 2001:db8:1::ffff" ]</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/client-class "eRouter1.0"</userinput>
-> <userinput>config commit</userinput></screen>
- </para>
-
- <para>
- 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.
- </para>
- </section>
-
-
- <section id="dhcp6-ddns-config">
- <title>Configuring DHCPv6 for DDNS</title>
- <para>
- 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:
- <orderedlist>
- <listitem><para>
- Whether it is a request to add (update) or remove DNS entries
- </para></listitem>
- <listitem><para>
- Whether the change requests forward DNS updates (AAAA records), reverse
- DNS updates (PTR records), or both.
- </para></listitem>
- <listitem><para>
- The FQDN, lease address, and DHCID
- </para></listitem>
- </orderedlist>
- 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:
-<screen>
-> <userinput>config show Dhcp6/dhcp-ddns</userinput>
-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
-</screen>
- </para>
- <para>
- 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:
- </para>
-<screen>
-> <userinput>config set Dhcp6/dhcp-ddns/enable-updates true</userinput>
-> <userinput>config commit</userinput>
-</screen>
- <section id="dhcpv6-d2-io-config">
- <title>DHCP-DDNS Server Connectivity</title>
- <para>
- 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:
- <orderedlist>
- <listitem><para>
- 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.
- </para></listitem>
- <listitem><para>
- server-port - port on which D2 listens for requests. The default value
- is 53001.
- </para></listitem>
- <listitem><para>
- 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.
- </para></listitem>
- <listitem><para>
- 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.
- </para></listitem>
- <listitem><para>
- ncr-format - Socket protocol use when sending requests to D2. Currently
- only UDP is supported. TCP may be available in an upcoming release.
- </para></listitem>
- <listitem><para>
- 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.
- </para></listitem>
- <listitem><para>
- 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.
- </para></listitem>
- </orderedlist>
- 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:
-<screen>
-> <userinput>config set Dhcp6/dhcp-ddns/server-ip "3001::5"</userinput>
-> <userinput>config set Dhcp6/dhcp-ddns/server-port 900</userinput>
-> <userinput>config commit</userinput>
-</screen>
- </para>
- </section>
- <section id="dhcpv6-d2-rules-config">
- <title>When does b10-dhcp6 generate DDNS request</title>
- 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 (<xref linkend="dhcp-ddns-server"/>).
- <para>
- 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.
- </para>
- <note>
- <para>
- 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.
- </para>
- </note>
- <para>
- In general, b10-dhcp6 will generate DDNS update requests when:
- <orderedlist>
- <listitem><para>
- A new lease is granted in response to a DHCP REQUEST
- </para></listitem>
- <listitem><para>
- An existing lease is renewed but the FQDN associated with it has
- changed.
- </para></listitem>
- <listitem><para>
- An existing lease is released in response to a DHCP RELEASE
- </para></listitem>
- </orderedlist>
- 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.
- </para>
- <para>
- 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:
- </para>
- <table id="dhcp6-fqdn-flag-table">
- <title>Default FQDN Flag Behavior</title>
- <tgroup cols='4' align='left'>
- <colspec colname='cflags'/>
- <colspec colname='meaning'/>
- <colspec colname='response'/>
- <colspec colname='sflags'/>
- <thead>
- <row>
- <entry>Client Flags:N-S</entry>
- <entry>Client Intent</entry>
- <entry>Server Response</entry>
- <entry>Server Flags:N-S-O</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>0-0</entry>
- <entry>
- Client wants to do forward updates, server should do reverse updates
- </entry>
- <entry>Server generates reverse-only request</entry>
- <entry>1-0-0</entry>
- </row>
- <row>
- <entry>0-1</entry>
- <entry>Server should do both forward and reverse updates</entry>
- <entry>Server generates request to update both directions</entry>
- <entry>0-1-0</entry>
- </row>
- <row>
- <entry>1-0</entry>
- <entry>Client wants no updates done</entry>
- <entry>Server does not generate a request</entry>
- <entry>1-0-0</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>
- 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.
- </para>
- <para>
- (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.)
- </para>
- <para>
- To override client delegation, issue the following commands:
- </para>
-<screen>
-> <userinput>config set Dhcp6/dhcp-ddns/override-client-update true</userinput>
-> <userinput>config commit</userinput>
-</screen>
- <para>
- 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.
- </para>
- <para>
- To override client delegation, issue the following commands:
- </para>
-<screen>
-> <userinput>config set Dhcp6/dhcp-ddns/override-no-update true</userinput>
-> <userinput>config commit</userinput>
-</screen>
- </section>
- <section id="dhcpv6-fqdn-name-generation">
- <title>b10-dhcp6 name generation for DDNS update requests</title>
- 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.
- <para>
- The rules for determining the FQDN option are as follows:
- <orderedlist>
- <listitem><para>
- If configured to do so ignore the REQUEST contents and generate a
- FQDN using a configurable prefix and suffix.
- </para></listitem>
- <listitem><para>
- Otherwise, using is the domain name value from the client FQDN option as
- the candidate name:
- <orderedlist>
- <listitem><para>
- If the candidate name is a fully qualified domain name then use it.
- </para></listitem>
- <listitem><para>
- 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.
- </para></listitem>
- <listitem><para>
- If the candidate name is a empty then generate a FQDN using a
- configurable prefix and suffix.
- </para></listitem>
- </orderedlist>
- </para></listitem>
- </orderedlist>
- To instruct b10-dhcp6 to always generate a FQDN, set the parameter
- "replace-client-name" to true:
- </para>
-<screen>
-> <userinput>config set Dhcp6/dhcp-ddns/replace-client-name true</userinput>
-> <userinput>config commit</userinput>
-</screen>
- <para>
- 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:
- </para>
-<screen>
-> <userinput>config set Dhcp6/dhcp-ddns/generated-prefix "another.host"</userinput>
-> <userinput>config commit</userinput>
-</screen>
- <para>
- 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:
- </para>
-<screen>
-> <userinput>config set Dhcp6/dhcp-ddns/generated-prefix "our.net"</userinput>
-> <userinput>config commit</userinput>
-</screen>
- </section>
- <para>
- When qualifying a partial name, b10-dhcp6 will construct a name with the
- format:
- </para>
- <para>
- [candidate-name].[qualifying-suffix].
- </para>
- <para>
- 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:
- </para>
- <para>
- some-computer.example.com.
- </para>
- <para>
- When generating a the entire name, b10-dhcp6 will construct name of the
- format:
- </para>
- <para>
- [generated-prefix]-[address-text].[qualifying-suffix].
- </para>
- <para>
- 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:
- </para>
- <para>
- myhost-3001-1--70E.example.com.
- </para>
- </section>
-
- </section>
-
- <section id="dhcp6-serverid">
- <title>Server Identifier in DHCPv6</title>
- <para>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 <ulink url="http://tools.ietf.org/html/rfc3315">RFC 3315</ulink> 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.
- </para>
- <para>
- 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.
- </para>
-
- </section>
-
- <section id="dhcp6-relay-override">
- <title>Using specific relay agent for a subnet</title>
- <para>
- 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.
- </para>
- <para>
- 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.
- </para>
- <para>
- 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.
- <screen>
-> <userinput>config add Dhcp6/subnet6</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64"</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::2 - 2001:db8:1::ffff" ]</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/relay/ip-address "3000::1"</userinput>
-> <userinput>config commit</userinput></screen>
- </para>
-
- </section>
-
- <section id="dhcp6-client-class-relay">
- <title>Segregating IPv6 clients in a cable network</title>
- <para>
- In certain cases, it is useful to mix relay address information,
- introduced in <xref linkend="dhcp6-relay-override"/> with client
- classification, explained in <xref linkend="dhcp6-subnet-class"/>.
- One specific example is cable network, where typically modems
- get addresses from a different subnet than all devices connected
- behind them.
- </para>
- <para>
- 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:
- <screen>
-> <userinput>config add Dhcp6/subnet6</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/subnet "3000::/64"</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/pool [ "3000::2 - 3000::ffff" ]</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/client-class "docsis3.0"</userinput>
-> <userinput>config set Dhcp6/subnet6[0]/relay/ip-address "3000::1"</userinput>
-> <userinput>config add Dhcp6/subnet6</userinput>
-> <userinput>config set Dhcp6/subnet6[1]/subnet "2001:db8:1::/64"</userinput>
-> <userinput>config set Dhcp6/subnet6[1]/pool [ "2001:db8:1::1 - 2001:db8:1::ffff" ]</userinput>
-> <userinput>config set Dhcp6/subnet6[1]/relay/ip-address "3000::1"</userinput>
-> <userinput>config commit</userinput></screen>
- </para>
- </section>
-
-
- <section id="dhcp6-std">
- <title>Supported Standards</title>
- <para>The following standards and draft standards are currently
- supported:</para>
- <itemizedlist>
- <listitem>
- <simpara><ulink url="http://tools.ietf.org/html/rfc3315">RFC 3315</ulink>: Supported messages are SOLICIT,
- ADVERTISE, REQUEST, RELEASE, RENEW, REBIND and REPLY.</simpara>
- </listitem>
- <listitem>
- <simpara><ulink url="http://tools.ietf.org/html/rfc3633">RFC 3633</ulink>: Supported options are IA_PD and
- IA_PREFIX. Also supported is the status code NoPrefixAvail.</simpara>
- </listitem>
- <listitem>
- <simpara><ulink url="http://tools.ietf.org/html/rfc3646">RFC 3646</ulink>: Supported option is DNS_SERVERS.</simpara>
- </listitem>
- <listitem>
- <simpara><ulink url="http://tools.ietf.org/html/rfc4704">RFC 4704</ulink>: Supported option is CLIENT_FQDN.</simpara>
- </listitem>
- </itemizedlist>
- </section>
-
- <section id="dhcp6-limit">
- <title>DHCPv6 Server Limitations</title>
- <para> 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 <quote>not implemented
- yet</quote>, rather than actual limitations.</para>
- <itemizedlist>
- <listitem> <!-- see tickets #3234, #3281 -->
- <para>
- 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.
- </para>
- </listitem>
-
- <listitem>
- <para>
- 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.
- <screen>
-> <userinput>config show Dhcp6/renew-timer</userinput>
-Dhcp6/renew-timer 1000 integer (default)
-> <userinput>config set Dhcp6/renew-timer 1001</userinput>
-> <userinput>config commit</userinput></screen>
- </para>
- </listitem>
- <listitem>
- <simpara>Temporary addresses are not supported.</simpara>
- </listitem>
- <listitem>
- <simpara>
- 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.
- <ulink url="http://tools.ietf.org/html/rfc3315">RFC 3315</ulink> and
- <ulink url="http://tools.ietf.org/html/rfc3633">RFC 3633</ulink> allow
- for multiple addresses or prefixes to be allocated for a single IA.
- </simpara>
- </listitem>
- <listitem>
- <simpara>Temporary addresses are not supported.</simpara>
- </listitem>
- <listitem>
- <simpara>
- Confirmation (CONFIRM), duplication report (DECLINE),
- stateless configuration (INFORMATION-REQUEST) and client
- reconfiguration (RECONFIGURE) are not yet supported.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- 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.
- </simpara>
- </listitem>
- </itemizedlist>
- </section>
-
- <!--
- <section id="dhcp6-srv-examples">
- <title>Kea DHCPv6 server examples</title>
-
- <para>
- This section provides easy to use example. Each example can be read
- separately. It is not intended to be read sequentially as there will
- be many repetitions between examples. They are expected to serve as
- easy to use copy-paste solutions to many common deployments.
- </para>
-
- @todo: add simple configuration for direct clients
- @todo: add configuration for relayed clients
- @todo: add client classification example
-
- </section> -->
-
- </chapter>
-
- <chapter id="dhcp-ddns-server">
- <title>The DHCP-DDNS Server</title>
- <para>
- 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.
- </para>
- <para>
- 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.
- </para>
- <para>
- 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.
- </para>
- <para>
- 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.
- </para>
- <section id="dhcp-ddns-server-start-stop">
- <title>Starting and Stopping the DHCP-DDNS Server</title>
- <para>
- <command>b10-dhcp-ddns</command> is the BIND 10 DHCP-DDNS server and,
- like other parts of BIND 10, is configured through the
- <command>bindctl</command> program.
- </para>
- <para>
- 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.
-<screen>
-> <userinput>config add Init/components b10-dhcp-ddns</userinput>
-> <userinput>config set Init/components/b10-dhcp-ddns/kind dispensable</userinput>
-> <userinput>config commit</userinput>
-</screen>
- </para>
- <para>
- To remove <command>b10-dhcp-ddns</command> from the set of running services,
- the <command>b10-dhcp-ddns</command> is removed from list of Init components:
-<screen>
-> <userinput>config remove Init/components b10-dhcp-ddns</userinput>
-> <userinput>config commit</userinput>
-</screen>
- </para>
- <para>
- 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:
- </para>
-<screen>
-> <userinput>DhcpDdns shutdown</userinput>
-</screen>
- <para>
- Upon start up the module will load its configuration and begin listening
- for NCRs based on that configuration.
- </para>
- </section> <!-- end start-stop -->
- <section id="d2-configuration">
- <title>Configuring the DHCP-DDNS Server</title>
- <para>
- Once the server is started, it can be configured. To view the
- current configuration, use the following command in <command>bindctl</command>:
- <screen>
-> <userinput>config show DhcpDdns</userinput></screen>
- When starting b10-dhcp-ddns module for the first time, the default
- configuration will be available. It will look similar to this:
-<screen>
-> <userinput>config show DhcpDdns</userinput>
-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)
-</screen>
- <para>
- (While displayed, the parameter "interface" is not implemented, and
- will be removed in the near future.)
- </para>
- </para>
- <para>
- The configuration can be divided as follows, each of which is described
- in its own section:
- </para>
- <itemizedlist>
- <listitem>
- <simpara>
- <command>Global Server Parameters</command> —
- values which control connectivity and global server behavior
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>TSIG Key Info</command> —
- defines the TSIG keys used for secure traffic with DNS servers
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>Forward DDNS</command> —
- defines the catalog of Forward DDNS Domains
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>Reverse DDNS</command> —
- defines the catalog of Forward DDNS Domains
- </simpara>
- </listitem>
- </itemizedlist>
- <section id="d2-server-parameter-config">
- <title>Global Server Parameters</title>
- <orderedlist>
- <listitem><para>
- 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.
- </para></listitem>
- <listitem><para>
- port - Port on which D2 listens for requests. The default value
- is 53001.
- </para></listitem>
- <listitem><para>
- ncr_format - Socket protocol to use when sending requests to D2.
- Currently only UDP is supported. TCP may be available in an upcoming
- release.
- </para></listitem>
- <listitem><para>
- 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.
- </para></listitem>
- <listitem><para>
- 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.
- </para></listitem>
- </orderedlist>
- <para>
- 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:
-<screen>
-> <userinput>config set DhcpDdns/ip_address "192.168.1.10"</userinput>
-> <userinput>config set DhcpDdns/port 900</userinput>
-> <userinput>config commit</userinput>
-</screen>
- </para>
- <warning>
- <simpara>
- 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.
- </simpara>
- </warning>
-<note>
-<simpara>
-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.
-</simpara>
-</note>
- </section> <!-- "d2-server-parameter-config" -->
-
- <section id="d2-tsig-key-list-config">
- <title>TSIG Key List</title>
- <para>
- A DDNS protocol exchange can be conducted with or without TSIG
- (defined in <ulink url="http://tools.ietf/org/html/rfc2845">RFC
- 2845</ulink>). This configuration section allows the administrator
- to define the set of TSIG keys that may be used in such
- exchanges.</para>
-
- <para>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.</para>
-
- <para>
- 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:
- <itemizedlist>
- <listitem>
- <simpara>
- <command>name</command> —
- 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.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>algorithm</command> —
- 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:
- <itemizedlist>
- <listitem>
- <command>HMAC-MD5</command>
- </listitem>
- <listitem>
- <command>HMAC-SHA1</command>
- </listitem>
- <listitem>
- <command>HMAC-SHA224</command>
- </listitem>
- <listitem>
- <command>HMAC-SHA256</command>
- </listitem>
- <listitem>
- <command>HMAC-SHA384</command>
- </listitem>
- <listitem>
- <command>HMAC-SHA512</command>
- </listitem>
- </itemizedlist>
- This value is not case sensitive.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>secret</command> —
- 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.
- </simpara>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- 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:
-<screen>
- :
- key "key.four.example.com." {
- algorithm hmac-sha224;
- secret "bZEG7Ow8OgAUPfLWV3aAUQ==";
- };
- :
-</screen>
- By default, the TSIG Key list is empty:
-<screen>
-<userinput>> config show DhcpDdns/tsig_keys</userinput>
-DhcpDdns/tsig_keys [] list (default)
-</screen>
- We must first create a new key in the list:
-<screen>
-<userinput>> config add DhcpDdns/tsig_keys</userinput>
-</screen>
- Displaying the new element, reveals:
-<screen>
-<userinput>> config show DhcpDdns/tsig_keys[0]</userinput>
-DhcpDdns/tsig_keys[0]/name "" string (default)
-DhcpDdns/tsig_keys[0]/algorithm "HMAC-MD5" string (modified)
-DhcpDdns/tsig_keys[0]/secret "" string (default)
-</screen>
- Now set all three values to match BIND9's key:
-<screen>
-<userinput>> config set DhcpDdns/tsig_keys[0]/name "key.four.example.com"</userinput>
-<userinput>> config set DhcpDdns/tsig_keys[0]/algorithm "HMAC-SHA224"</userinput>
-<userinput>> config set DhcpDdns/tsig_keys[0]/secret "bZEG7Ow8OgAUPfLWV3aAUQ=="</userinput>
-<userinput>> config commit</userinput>
-</screen>
- </para>
- These steps would be repeated for each TSIG key needed. Note that the same TSIG key
- can be used with more than one domain.
- </section> <!-- "d2-tsig-key-list-config" -->
-
- <section id="d2-forward-ddns-config">
- <title>Forward DDNS</title>
- <para>
- 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:
-<screen>
-<userinput>> config show DhcpDdns/forward_ddns/</userinput>
-DhcpDdns/forward_ddns/ddns_domains [] list (default)
-</screen>
- By default, this list is empty, which will cause the server to ignore
- the forward update portions of requests.
- </para>
- <section id="add-forward-ddns-domain">
- <title>Adding Forward DDNS Domains</title>
- <para>
- 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.
- </para>
- <para>
- 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:
- <itemizedlist>
- <listitem>
- <simpara>
- <command>name</command> —
- 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.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>key_name</command> —
- 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.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>dns_servers</command> —
- 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.
- </simpara>
- </listitem>
- </itemizedlist>
- To create a new forward DDNS Domain, one must first add a new domain
- element:
-<screen>
-<userinput>> config add DhcpDdns/forward_ddns/ddns_domains</userinput>
-</screen>
- Displaying the DDNS Domain reveals this:
-<screen>
-<userinput>> config show DhcpDdns/forward_ddns/ddns_domains[0]</userinput>
-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)
-</screen>
- To set the domain's name to "other.example.com":
-<screen>
-<userinput>> config set DhcpDdns/forward_ddns/ddns_domains[1]/name "other.example.com"</userinput>
-<userinput>> config commit</userinput>
-</screen>
- 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.
- </para>
-
- <section id="add-forward-dns-servers">
- <title>Adding Forward DNS Servers</title>
- <para>
- 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.
- </para>
- <para>
- 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:
- <itemizedlist>
- <listitem>
- <simpara>
- <command>hostname</command> —
- The resolvable host name of the DNS server. This value is not
- yet implemented.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>ip_address</command> —
- The IP address at which the server listens for DDNS requests.
- This may be either an IPv4 or an IPv6 address.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>port</command> —
- The port on which the server listens for DDNS requests. It
- defaults to the standard DNS service port of 53.
- </simpara>
- </listitem>
- </itemizedlist>
- To create a new forward DNS Server, one must first add a new server
- element to the domain:
-<screen>
-<userinput>> config add DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers</userinput>
-</screen>
- Displaying the DNS Server element should appear as follows:
-<screen>
-<userinput>> config show DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]</userinput>
-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)
-</screen>
- 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:
-<screen>
-<userinput>> config set DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]/ip_address "172.88.99.10"</userinput>
-<userinput>> config commit</userinput>
-</screen>
- </para>
- </section> <!-- "add-forward-dns-servers" -->
-
- </section> <!-- "add-forward-ddns-domains" -->
-
- </section> <!-- "d2-forward-ddns-config" -->
-
- <section id="d2-reverse-ddns-config">
- <title>Reverse DDNS</title>
- <para>
- 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:
-<screen>
-<userinput>> config show DhcpDdns/reverse_ddns/</userinput>
-DhcpDdns/reverse_ddns/ddns_domains [] list (default)
-</screen>
- By default, this list is empty, which will cause the server to ignore
- the reverse update portions of requests.
- </para>
- <section id="add-reverse-ddns-domain">
- <title>Adding Reverse DDNS Domains</title>
- <para>
- 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.
- </para>
- <para>
- 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:
- <itemizedlist>
- <listitem>
- <simpara>
- <command>name</command> —
- 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.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>key_name</command> —
- 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.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>dns_servers</command> —
- 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.
- </simpara>
- </listitem>
- </itemizedlist>
- To create a new reverse DDNS Domain, one must first add a new domain
- element:
-<screen>
-<userinput>> config add DhcpDdns/reverse_ddns/ddns_domains</userinput>
-</screen>
- Displaying the DDNS Domain reveals this:
-<screen>
-<userinput>> config show DhcpDdns/reverse_ddns/ddns_domains[0]</userinput>
-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)
-</screen>
- For domain supporting the subnet 2001:db8:1::, we would set the
- domain's name as follows:
-<screen>
-<userinput>> config set DhcpDdns/reverse_ddns/ddns_domains[1]/name "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa."</userinput>
-<userinput>> config commit</userinput>
-</screen>
- 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.
- </para>
-
- <section id="add-reverse-dns-servers">
- <title>Adding Reverse DNS Servers</title>
- <para>
- 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.
- </para>
- <para>
- 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:
- <itemizedlist>
- <listitem>
- <simpara>
- <command>hostname</command> —
- The resolvable host name of the DNS server. This value is
- currently ignored.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>ip_address</command> —
- The IP address at which the server listens for DDNS requests.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>port</command> —
- The port on which the server listens for DDNS requests. It
- defaults to the standard DNS service port of 53.
- </simpara>
- </listitem>
- </itemizedlist>
- To create a new reverse DNS Server, one must first add a new server
- element to the domain:
-<screen>
-<userinput>> config add DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers</userinput>
-</screen>
- Displaying the DNS Server element should appear as follows:
-<screen>
-<userinput>> config show DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]</userinput>
-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)
-</screen>
- 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:
-<screen>
-<userinput>> config set DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/ip_address "172.88.99.10"</userinput>
-<userinput>> config commit</userinput>
-</screen>
- </para>
- </section> <!-- "add-reverse-dns-servers" -->
-
- </section> <!-- "add-reverse-ddns-domains" -->
-
- </section> <!-- "d2-reverse-ddns-config" -->
-
- <section id="d2-exmaple-config">
- <title>Example DHCP-DDNS Server Configuration</title>
- <para>
- 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.
-
- <table>
- <title>Our example network</title>
- <tgroup cols='4' align='left'>
- <colspec colname='domain'/>
- <colspec colname='subnet'/>
- <colspec colname='fservers'/>
- <colspec colname='rservers'/>
- <thead>
- <row>
- <entry>Domain</entry>
- <entry>Subnet</entry>
- <entry>Forward DNS Servers</entry>
- <entry>Reverse DNS Servers</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>four.example.com</entry>
- <entry>192.0.2.0/24</entry>
- <entry>172.16.1.5, 172.16.2.5</entry>
- <entry>172.16.1.5, 172.16.2.5</entry>
- </row>
- <row>
- <entry>six.example.com</entry>
- <entry>2001:db8:1::/64</entry>
- <entry>3001:1::50</entry>
- <entry>3001:1::51</entry>
- </row>
- <row>
- <entry>example.com</entry>
- <entry>192.0.0.0/16</entry>
- <entry>172.16.2.5</entry>
- <entry>172.16.2.5</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
- <para>
- We need to construct three forward DDNS Domains:
- <table>
- <title>Forward DDNS Domains Needed</title>
- <tgroup cols='3' align='left'>
- <colspec colname='num'/>
- <colspec colname='name'/>
- <colspec colname='servers'/>
- <thead>
- <row>
- <entry>#</entry>
- <entry>DDNS Domain Name</entry>
- <entry>DNS Servers</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>1.</entry>
- <entry>four.example.com.</entry>
- <entry>172.16.1.5, 172.16.2.5</entry>
- </row>
- <row>
- <entry>2.</entry>
- <entry>six.example.com.</entry>
- <entry>3001:1::50</entry>
- </row>
- <row>
- <entry>3.</entry>
- <entry>example.com.</entry>
- <entry>172.16.2.5</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- 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.
- </para>
- <para>
- The following series of commands in bindctl will create the Forward
- DDNS Domains.
-<screen>
-<userinput>
-> 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
-</userinput>
-</screen>
- </para>
- <para>
- Similarly, we need to construct the three reverse DDNS Domains:
- <table>
- <title>Reverse DDNS Domains Needed</title>
- <tgroup cols='3' align='left'>
- <colspec colname='num'/>
- <colspec colname='DDNS Domain name'/>
- <colspec colname='DDNS Domain DNS Servers'/>
- <thead>
- <row>
- <entry>#</entry>
- <entry>DDNS Domain Name</entry>
- <entry>DNS Servers</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>1.</entry>
- <entry>2.0.192.in-addr.arpa.</entry>
- <entry>172.16.1.5, 172.16.2.5</entry>
- </row>
- <row>
- <entry>2.</entry>
- <entry>1.0.0.0.8.d.b.0.1.0.0.2.ip6.arpa.</entry>
- <entry>3001:1::50</entry>
- </row>
- <row>
- <entry>3.</entry>
- <entry>0.182.in-addr.arpa.</entry>
- <entry>172.16.2.5</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- 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.
- </para>
- <para>
- The following series of commands in bindctl will create our Reverse
- DDNS Domains.
-<screen>
-<userinput>
-> 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
-</userinput>
-</screen>
- </para>
- </section> <!-- end of "d2-example" -->
- </section> <!-- end of section "d2-configuration" -->
- <section>
- <title>DHCP-DDNS Server Limitations</title>
- <para>The following are the current limitations of the DHCP-DDNS Server.</para>
- <itemizedlist>
- <listitem>
- <simpara>
- 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.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- TSIG Authentication (<ulink
- url="http://tools.ietf.org/html/rfc2845">RFC 2845</ulink>)
- is not supported yet.
- </simpara>
- </listitem>
- </itemizedlist>
- </section>
- </chapter> <!-- DHCP-DDNS Server -->
-
- <chapter id="libdhcp">
- <title>libdhcp++ library</title>
- <para>
- libdhcp++ is a common library written in C++ that handles
- many DHCP-related tasks, including:
- <itemizedlist>
- <listitem>
- <simpara>DHCPv4 and DHCPv6 packets parsing, manipulation and assembly</simpara>
- </listitem>
- <listitem>
- <simpara>Option parsing, manipulation and assembly</simpara>
- </listitem>
- <listitem>
- <simpara>Network interface detection</simpara>
- </listitem>
- <listitem>
- <simpara>Socket operations such as creation, data transmission and reception and socket closing.</simpara>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- 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.
- </para>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="install.xml" />
-<!-- TODO: point to doxygen docs -->
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="config.xml" />
- <section id="iface-detect">
- <title>Interface detection and Socket handling</title>
- <para>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.</para>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp4-srv.xml" />
- <para>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.</para>
- </section>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp6-srv.xml" />
-<!--
- <section id="packet-handling">
- <title>DHCPv4/DHCPv6 packet handling</title>
- <para>TODO: Describe packet handling here, with pointers to wiki</para>
- </section>
--->
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ddns.xml" />
- </chapter>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="libdhcp.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="logging.xml" />
<chapter id="acknowledgements">
<title>Acknowledgements</title>
+ <para>Support for the development of the DHCPv4, DHCPv6 and
+ DHCP-DDNS components was provided by
+ <ulink url="http://www.comcast.com/">Comcast</ulink>.</para>
+
<para>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.</para>
<!-- DHCP sponsorship by Comcast -->
- <para>Support for the development of the DHCPv4, DHCPv6 and
- DHCP-DDNS components is provided by
- <ulink url="http://www.comcast.com/">Comcast</ulink>.</para>
-
</chapter>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY mdash "—" >
+]>
+
+ <chapter id="libdhcp">
+ <title>libdhcp++ library</title>
+ <para>
+ libdhcp++ is a common library written in C++ that handles
+ many DHCP-related tasks, including:
+ <itemizedlist>
+ <listitem>
+ <simpara>DHCPv4 and DHCPv6 packets parsing, manipulation and assembly</simpara>
+ </listitem>
+ <listitem>
+ <simpara>Option parsing, manipulation and assembly</simpara>
+ </listitem>
+ <listitem>
+ <simpara>Network interface detection</simpara>
+ </listitem>
+ <listitem>
+ <simpara>Socket operations such as creation, data transmission and reception and socket closing.</simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+<!-- TODO: point to doxygen docs -->
+
+ <section id="iface-detect">
+ <title>Interface detection and Socket handling</title>
+ <para>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.</para>
+
+ <para>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.</para>
+ </section>
+
+<!--
+ <section id="packet-handling">
+ <title>DHCPv4/DHCPv6 packet handling</title>
+ <para>TODO: Describe packet handling here, with pointers to wiki</para>
+ </section>
+-->
+
+ </chapter>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY mdash "—" >
+]>
+
+ <chapter id="quickstart">
+ <title>Quick start</title>
+
+ <para>
+ 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.
+ </para>
+
+ <section id="quick-start">
+ <title>Quick start guide for DHCPv4 and DHCPv6 services</title>
+
+ <orderedlist>
+
+ <listitem>
+ <simpara>
+ Install required run-time and build dependencies. See <xref
+ linkend="build-requirements"/> for details.
+ </simpara>
+ </listitem>
+
+ <!-- We may need to replace it with the link to a downloadable tarball
+ once we have it. -->
+ <listitem>
+ <simpara>
+ Checkout the latest Kea revision from the Git repository:
+ <screen>$ <userinput>git clone git://git.kea.isc.org/kea</userinput> </screen>
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <para>Go into the source and run configure:
+ <screen>$ <userinput>cd kea</userinput>
+$ <userinput>autoreconf --install</userinput>
+$ <userinput>./configure [your extra parameters]</userinput></screen>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Build it:
+ <screen>$ <userinput>make</userinput></screen>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Install it as root (by default to prefix
+ <filename>/usr/local/</filename>):
+ <screen>$ <userinput>make install</userinput></screen>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Edit your configuration file for DHCPv4. See doc/examples/kea4
+ for a set of examples.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Start Kea DHCPv4 server (as root):
+ <screen># <userinput>b10-dhcp4 -c /path/to/your/kea4/config/file.json</userinput></screen>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Test it; for example, use the
+ <ulink url="http://www.isc.org/downloads/DHCP/">ISC DHCP client</ulink>
+ to send DHCPv4 queries to the server and verify that the client receives a
+ configuration from the server:
+ <screen>$ <userinput>dhclient -4 eth0</userinput></screen>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Edit your configuration file for DHCPv6. See doc/examples/kea6
+ for a set of examples.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Start Kea DHCPv6 server (as root):
+ <screen># <userinput>b10-dhcp6 -c /path/to/your/kea6/config/file.json</userinput></screen>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Test it; for example, use the
+ <ulink url="http://www.isc.org/downloads/DHCP/">ISC DHCP client</ulink>
+ to send DHCPv6 queries to the server and verify that the client receives a
+ configuration from the server:
+ <screen>$ <userinput>dhclient -6 eth0</userinput></screen>
+ </para>
+ </listitem>
+
+
+ </orderedlist>
+
+ </section>
+
+ </chapter>
projects / thirdparty / kea.git / commitdiff
