mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-30 21:45:37 +00:00
Code Issues Releases Wiki Activity

[3418] Remaining chapters moved to separate files.

Browse Source
This commit is contained in:
Tomek Mrugalski
2014-06-11 14:21:54 +02:00
parent 433bf38a0f
commit 439ef5986f
8 changed files with 4371 additions and 4326 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
doc/guide/Makefile.am
View File

@@ -5,7 +5,8 @@ DOCS = kea-guide.txt
dist_doc_DATA = $(DOCS) dist_doc_DATA = $(DOCS)
dist_html_DATA = $(HTMLDOCS) kea-guide.css 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) EXTRA_DIST = $(DOCBOOK)
DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml

811
doc/guide/ddns.xml Normal file
View File

@@ -0,0 +1,811 @@
<?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 "&#x2014;" >
]>
<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>
&gt; <userinput>config add Init/components b10-dhcp-ddns</userinput>
&gt; <userinput>config set Init/components/b10-dhcp-ddns/kind dispensable</userinput>
&gt; <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>
&gt; <userinput>config remove Init/components b10-dhcp-ddns</userinput>
&gt; <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>
&gt; <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>
&gt; <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>
&gt; <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> &mdash;
values which control connectivity and global server behavior
</simpara>
</listitem>
<listitem>
<simpara>
<command>TSIG Key Info</command> &mdash;
defines the TSIG keys used for secure traffic with DNS servers
</simpara>
</listitem>
<listitem>
<simpara>
<command>Forward DDNS</command> &mdash;
defines the catalog of Forward DDNS Domains
</simpara>
</listitem>
<listitem>
<simpara>
<command>Reverse DDNS</command> &mdash;
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>
&gt; <userinput>config set DhcpDdns/ip_address "192.168.1.10"</userinput>
&gt; <userinput>config set DhcpDdns/port 900</userinput>
&gt; <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> &mdash;
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> &mdash;
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> &mdash;
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> &mdash;
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> &mdash;
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> &mdash;
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> &mdash;
The resolvable host name of the DNS server. This value is not
yet implemented.
</simpara>
</listitem>
<listitem>
<simpara>
<command>ip_address</command> &mdash;
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> &mdash;
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> &mdash;
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> &mdash;
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> &mdash;
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> &mdash;
The resolvable host name of the DNS server. This value is
currently ignored.
</simpara>
</listitem>
<listitem>
<simpara>
<command>ip_address</command> &mdash;
The IP address at which the server listens for DDNS requests.
</simpara>
</listitem>
<listitem>
<simpara>
<command>port</command> &mdash;
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 -->

1554
doc/guide/dhcp4-srv.xml Normal file
View File

File diff suppressed because it is too large Load Diff

1545
doc/guide/dhcp6-srv.xml Normal file
View File

File diff suppressed because it is too large Load Diff

288
doc/guide/intro.xml Normal file
View File

@@ -0,0 +1,288 @@
<?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 "&#x2014;" >
<!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> &mdash;
Configuration manager.
This process maintains all of the configuration for BIND 10.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-cmdctl</command> &mdash;
Command and control service.
This process allows external control of the BIND 10 system.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-dhcp4</command> &mdash;
DHCPv4 server process.
This process responds to DHCPv4 queries from clients.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-dhcp6</command> &mdash;
DHCPv6 server process.
This process responds to DHCPv6 queries from clients.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-dhcp-ddns</command> &mdash;
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> &mdash;
Message bus daemon.
This process coordinates communication between all of the other
BIND 10 processes.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-sockcreator</command> &mdash;
Socket creator daemon.
This process creates sockets used by
network-listening BIND 10 processes.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-stats</command> &mdash;
Statistics collection daemon.
This process collects and reports statistics data.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-stats-httpd</command> &mdash;
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> &mdash;
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> &mdash;
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>

4335
doc/guide/kea-guide.xml
View File

File diff suppressed because it is too large Load Diff

56
doc/guide/libdhcp.xml Normal file
View File

@@ -0,0 +1,56 @@
<?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 "&#x2014;" >
]>
<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>

105
doc/guide/quickstart.xml Normal file
View File

@@ -0,0 +1,105 @@
<?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 "&#x2014;" >
]>
<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>