mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-31 14:05:33 +00:00
Code Issues Releases Wiki Activity

[master] Merge branch 'trac3418' (Kea Guide update)

Browse Source 
Conflicts:
	ChangeLog
	doc/guide/bind10-guide.xml
This commit is contained in:
Tomek Mrugalski
2014-07-01 11:31:29 +02:00
parent 701e23d637 73e6019d83
commit 742d5a1911
17 changed files with 6275 additions and 6892 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
ChangeLog
View File

@@ -1,3 +1,9 @@
796. [doc] tomek
User's Guide renamed to Kea Administrator Reference Manual,
removed sections specific to BIND10/Bundy framework, rewritten
general and DHCPv4 specific examples.
(Trac #3418, git 73e6019d83760f0500890240e2e187dcd5e1e14c)
795. [func] marcin
Added support to keactrl to start, stop, reconfigure and gather
status of the DHCP-DDNS server.

7
configure.ac
View File

@@ -2,7 +2,12 @@
# Process this file with autoconf to produce a configure script.
AC_PREREQ([2.59])
AC_INIT(bind10, 20140313, kea-dev@isc.org)
# For released versions, this is in x.y.z format.
# For GIT versions, this is x.y.z-git, where x.y.z denotes the software
# version that was used as a base + changes that were made later, but
# are not released yet.
AC_INIT(bind10, 0.8.0-git, kea-dev@isc.org)
AC_CONFIG_SRCDIR(README)
# serial-tests is not available in automake version before 1.13, so

9
doc/Makefile.am
View File

@@ -2,15 +2,22 @@ SUBDIRS = guide design
EXTRA_DIST = version.ent.in differences.txt Doxyfile Doxyfile-xml
nobase_dist_doc_DATA = examples/kea4/single-subnet.json
nobase_dist_doc_DATA += examples/kea4/several-subnets.json
nobase_dist_doc_DATA += examples/kea6/several-subnets.json
devel:
mkdir -p html
(cat Doxyfile; echo PROJECT_NUMBER=$(PACKAGE_VERSION)) | doxygen - > html/doxygen.log 2> html/doxygen-error.log
echo `grep -i ": warning:" html/doxygen-error.log | wc -l` warnings/errors detected.
guide:
$(MAKE) -C guide kea-guide.html
clean:
rm -rf html
# That's a bit of a hack, but we are making sure that devel target
# is always valid. The alternative is to make devel depend on all
# *.cc *.h files in the whole tree.
.PHONY: devel
.PHONY: devel guide

8
doc/guide/.gitignore vendored
View File

@@ -1,4 +1,4 @@
/bind10-guide.html
/bind10-guide.txt
/bind10-messages.html
/bind10-messages.xml
/kea-guide.html
/kea-guide.txt
/kea-messages.html
/kea-messages.xml

31
doc/guide/Makefile.am
View File

@@ -1,38 +1,41 @@
# generated documentation
HTMLDOCS = bind10-guide.html bind10-messages.html
DOCS = bind10-guide.txt
HTMLDOCS = kea-guide.html kea-messages.html
DOCS = kea-guide.txt
dist_doc_DATA = $(DOCS)
dist_html_DATA = $(HTMLDOCS) bind10-guide.css
dist_html_DATA = $(HTMLDOCS) kea-guide.css
EXTRA_DIST = bind10-guide.xml
DISTCLEANFILES = $(HTMLDOCS) $(DOCS) bind10-messages.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
# This is not a "man" manual, but reuse this for now for docbook.
if GENERATE_DOCS
bind10-guide.html: bind10-guide.xml
kea-guide.html: $(DOCBOOK)
@XSLTPROC@ --novalid --xinclude --nonet \
--path $(top_builddir)/doc \
-o $@ \
--stringparam section.autolabel 1 \
--stringparam section.label.includes.component.label 1 \
--stringparam html.stylesheet bind10-guide.css \
--stringparam html.stylesheet kea-guide.css \
http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl \
$(srcdir)/bind10-guide.xml
$(srcdir)/kea-guide.xml
bind10-guide.txt: bind10-guide.html
@ELINKS@ -dump -no-numbering -no-references bind10-guide.html > $@
kea-guide.txt: kea-guide.html
@ELINKS@ -dump -no-numbering -no-references kea-guide.html > $@
bind10-messages.html: bind10-messages.xml
kea-messages.html: kea-messages.xml
@XSLTPROC@ --novalid --xinclude --nonet \
--path $(top_builddir)/doc \
-o $@ \
--stringparam html.stylesheet bind10-guide.css \
--stringparam html.stylesheet kea-guide.css \
http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl \
bind10-messages.xml
kea-messages.xml
bind10-messages.xml:
kea-messages.xml:
$(PYTHON) $(top_srcdir)/tools/system_messages.py -o $@ $(top_srcdir)
else

6872
doc/guide/bind10-guide.xml
View File

File diff suppressed because it is too large Load Diff

131
doc/guide/config.xml Normal file
View File

@@ -0,0 +1,131 @@
<?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="kea-config">
<title>Kea configuration</title>
<para>Depending on configuration backend chosen (see <xref
linkend="dhcp-config-backend"/>), configuration mechanisms are different. The
following sections describe details of the differeent configuration backends. Note
that only one configuration backend can be used and its selection is
made when the configure script is run.</para>
<section id="bundy-backend">
<title>BIND 10 configuration backend</title>
<para>This legacy configuration backend allows Kea to use the former BIND10
framework. That framework and this Kea configuration backend is no longer
supported by ISC. It is currently developed as part of the Bundy project (see
<ulink url="http://bundy-dns.de">Bundy homepage</ulink>). See the Bundy project
documentation regarding configuration.</para>
</section>
<section id="json-backend">
<title>JSON configuration backend</title>
<para>JSON is the default configuration backend and the only one supported
as of the 0.9 release. It assumes that the servers are started from the command line
(either directly or using a script, see TODO for details). The JSON backend uses
certain signals to influence Kea. The configuration file is
specified upon startup using -c parameter.</para>
<section id="json-format">
<title>JSON syntax</title>
<para>Configuration files for DHCPv4, DHCPv6 and DDNS modules are defined
in an extended JSON format. Basic JSON is defined in <ulink
url="http://tools.ietf.org/html/rfc4627">RFC 4627</ulink>. Kea components
use a slightly modified JSON, in that they allowing bash-style
comments in the file: lines with the hash (#) character in the first column
are comment lines and are ignored.</para>
<para>The configuration file consists of a single object (often colloquially
called a map) started with a curly bracket. It comprises the "Dhcp4", "Dhcp6",
"DhcpDdns" and/or "Logging" objects. It is possible to define additional
elements, but they will be ignored. (That principle was chosen to ease
configuration management.) For example, it is possible to define Dhcp4,
Dhcp6 and Logging elements in a single configuration file that can be used to
start both the DHCPv4 and DHCPv6 components. When starting, the DHCPv4 component
will use Dhcp4 object to configure itself and the Logging object to configure logging
parameters; it will ignore the Dhcp6 object.</para>
<para>For example, a very simple configuration for both DHCPv4 and DHCPv6
could look like this:
<screen>
# The whole configuration starts here.
{
# DHCPv4 specific configuration starts here.
"Dhcp4": {
"interfaces": [ "eth0" ],
"valid-lifetime": 4000,
"renew-timer": 1000,
"rebind-timer": 2000,
"subnet4": [{
"pool": "192.0.2.1-192.0.2.200",
"subnet": "192.0.2.0/24"
}],
...
},
# DHCPv4 specific configuration ends here.
# DHCPv6 specific configuration starts here.
"Dhcp6": {
"interfaces": [ "eth1" ],
"preferred-lifetime": 3000,
"valid-lifetime": 4000,
"renew-timer": 1000,
"rebind-timer": 2000,
"subnet6": [{
"pool": "2001:db8::/80",
"subnet": "2001:db8::/64"
}],
...
},
# DHCPv6 specific configuration ends here.
# Logger parameters (that could be shared among several components) start here.
# This section is used by both the DHCPv4 and DHCPv6 servers.
"Logging": {
"loggers": [{
"name": "*",
"severity": "DEBUG"
}],
...
}
# Logger parameters end here.
# The whole configuration structure ends here.
}
</screen>
</para>
<para>More examples are available in the Kea source code in the
<filename>doc/examples</filename> directory.</para>
<para>To avoid repetition of mostly similar structures, examples in the
rest of this guide will showcase only the subset of parameters appropriate for a given
context. For example, when discussing the IPv6 subnets configuration in
DHCPv6, only subnet6 parameters will be mentioned. It is implied that
remaining elements (the global map that holds Dhcp6, Logging and possibly
DhcpDdns) are present, but they are omitted for clarity. Usually, locations
where extra parameters may appear are denoted with an ellipsis.</para>
</section>
<section>
<title>Simplified Notation</title>
<para>It is sometimes convenient to refer to specific element in the
configuration hierarchy. Each hierarchy level is separated by a slash.
If there is an array, a specific instance within that array is referred by
a number in square brackets (with numbering starting at zero). For example, in the above configuration the
valid-lifetime in Dhcp6 component can be referred to as
Dhcp6/valid-lifetime, the first interface for the DHCPv4 server as
Dhcp4/interfaces[0] and the pool in the first subnet defined in the DHCPv6
configuration as Dhcp6/subnet6[0]/pool.</para>
<!-- @todo Add a reference here after #3422 is done -->
</section>
</section>
</chapter>

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 -->

1799
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

624
doc/guide/install.xml Normal file
View File

@@ -0,0 +1,624 @@
<?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="installation">
<title>Installation</title>
<section id="packages">
<title>Packages</title>
<para>
Some operating systems or software package vendors may provide
ready-to-use, pre-built software packages for Kea. Installing a
pre-built package means you do not need to install build-only
prerequisites and do not need to <emphasis>make</emphasis> the software.
</para>
<para>
FreeBSD ports, NetBSD pkgsrc, and Debian <emphasis>testing</emphasis>
package collections provide all the prerequisite packages.
</para>
</section>
<section id="install-hierarchy">
<title>Install Hierarchy</title>
<para>
The following is the directory layout of the complete Kea installation
(all directories paths are relative to the installation directory):
<itemizedlist>
<listitem>
<simpara>
<filename>bin/</filename> &mdash;
general tools and diagnostic clients.
</simpara>
</listitem>
<listitem>
<simpara>
<!-- @todo: 0.9: update this -->
<filename>etc/bind10/</filename> &mdash;
configuration files.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>lib/</filename> &mdash;
libraries and python modules.
</simpara>
</listitem>
<listitem>
<simpara>
<!-- @todo 0.9: update this -->
<filename>libexec/bind10/</filename> &mdash;
executables that a user wouldn't normally run directly and
are not run independently.
These are the BIND 10 and Kea modules which are daemons started by
the <command>b10-init</command> master process.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>sbin/</filename> &mdash;
commands used by the system administrator.
</simpara>
</listitem>
<listitem>
<simpara>
<!-- @todo 0.9: update this -->
<filename>share/bind10/</filename> &mdash;
configuration specifications.
</simpara>
</listitem>
<listitem>
<simpara>
<!-- @todo 0.9: update this -->
<filename>share/doc/bind10/</filename> &mdash;
this guide and other supplementary documentation.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>share/man/</filename> &mdash;
manual pages (online documentation).
</simpara>
</listitem>
<listitem>
<simpara>
<!-- @todo 0.9: update this -->
<filename>var/bind10/</filename> &mdash;
data source and configuration databases.
</simpara>
</listitem>
</itemizedlist>
</para>
</section>
<section id="build-requirements">
<title>Building Requirements</title>
<para>
In addition to the run-time requirements (listed in <xref
linkend="required-software"/>), building Kea from source code requires
various development include headers and program development tools.
</para>
<note>
<simpara>
Some operating systems have split their distribution packages into
a run-time and a development package. You will need to install
the development package versions, which include header files and
libraries, to build Kea from the source code.
</simpara>
</note>
<para>
Building from source code requires the following software installed
on the system:</para>
<itemizedlist>
<listitem>
<para>Boost build-time headers
(<ulink url="http://www.boost.org/"/>).
At least Boost version 1.35 is required.
<!-- TODO: we don't check for this version -->
<!-- NOTE: jreed has tested with 1.34, 1.38, and 1.41. -->
</para>
</listitem>
<listitem>
<para>
Botan (at least version
1.8).</para>
</listitem>
<listitem>
<para>
log4cplus (at least version 1.0.3)
development include headers.
<!-- @todo: Add OpenSSL note here once #2406 is merged -->
</para>
</listitem>
<!--
TODO
Debian and Ubuntu:
libgmp3-dev and libbz2-dev required for botan too
-->
<!-- NOTE: _sqlite3 is only needed at test time; it is already listed
as a dependency earlier -->
<listitem>
<para>
A C++ compiler and
standard development headers.
Kea builds have been tested with GCC g++ 3.4.3, 4.1.2,
4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10.
<!-- @todo update this list -->
</para>
</listitem>
<listitem>
<para>
The development tools "make" and "pkg-config".
<!-- @todo update this list -->
</para>
</listitem>
</itemizedlist>
<para>
Visit the user-contributed wiki at <ulink
url="http://kea.isc.org/wiki/SystemSpecificNotes" />
for system-specific installation tips.
</para>
</section>
<section id="install">
<title>Installation from Source</title>
<para>
Kea is open source software written in C++ (some components of the
BIND 10 framework are written in Python).
It is freely available in source code form from ISC as a
downloadable tar file or via Kea Git code revision control
service. (It may also be available in pre-compiled ready-to-use
packages from operating system vendors.)
</para>
<section>
<title>Download Tar File</title>
<para>
Kea 0.8 is available as a part of BIND10 1.2 release, which is a final
release of BIND10 from ISC. This release can be downloaded from:
<ulink url="ftp://ftp.isc.org/isc/bind10/"/>. The upcoming Kea 0.9 and all
following releases will be shipped as a stand-alone tarball.
</para>
</section>
<section>
<title>Retrieve from Git</title>
<para>
Downloading this "bleeding edge" code is recommended only for
developers or advanced users. Using development code in a production
environment is not recommended.
</para>
<note>
<para>
When building from source code retrieved via Git, additional
software will be required: automake (v1.11 or later),
libtoolize, and autoconf (2.59 or later).
These may need to be installed.
</para>
</note>
<para>
The latest development code (together with temporary experiments
and un-reviewed code) is available via the Kea code revision
control system. This is powered by Git and all the Kea
development is public.
The leading development is done in the <quote>master</quote>
branch.
</para>
<para>
The code can be checked out from
<filename>git://git.kea.isc.org/kea</filename>:
<screen>$ <userinput>git clone git://git.kea.isc.org/kea</userinput></screen>
</para>
<para>
The code checked out from the git repository doesn't include the
generated configure script, Makefile.in files, nor their
related build files.
They can be created by running <command>autoreconf</command>
with the <option>--install</option> switch.
This will run <command>autoconf</command>,
<command>aclocal</command>,
<command>libtoolize</command>,
<command>autoheader</command>,
<command>automake</command>,
and related commands.
</para>
</section>
<section id="configure">
<title>Configure before the build</title>
<para>
Kea uses the GNU Build System to discover build environment
details.
To generate the makefiles using the defaults, simply run:
<screen>$ <userinput>./configure</userinput></screen>
</para>
<para>
Run <command>./configure</command> with the <option>--help</option>
switch to view the different options. Some commonly-used options are:
<variablelist>
<varlistentry>
<term>--prefix</term>
<listitem>
<simpara>Define the installation location (the
default is <filename>/usr/local</filename>).
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-boost-include</term>
<listitem>
<simpara>Define the path to find the Boost headers.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-pythonpath</term>
<listitem>
<simpara>Define the path to Python 3.x if it is not in the
standard execution path. Python 3.x is mandatory for Kea 0.8,
but will not be required for the upcoming Kea 0.9.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-gtest</term>
<listitem>
<simpara>Enable the building of the C++ Unit Tests using the
Google Test framework. Optionally this can define the
path to the gtest header files and library. (If the framework
is not already installed on your system, it can be downloaded
from <ulink url="https://code.google.com/p/googletest"/>.)
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-openssl</term>
<listitem>
<simpara>Replace Botan by OpenSSL for the crypto library.
The default is to try to find a working Botan then
OpenSSL only if Botan is not found.
</simpara>
</listitem>
</varlistentry>
<!-- missing -with-botan-config -->
<varlistentry>
<term>--without-werror</term>
<listitem>
<simpara>Disable the default use of the
<option>-Werror</option> compiler flag so that
compiler warnings do not result in build failures.
</simpara>
</listitem>
</varlistentry>
</variablelist>
<note>
<para>
For additional instructions concerning the building and installation of
Kea for various databases, see <xref linkend="dhcp-install-configure"/>.
For additional instructions concerning configuration backends, see
<xref linkend="dhcp-config-backend" />.
</para>
</note>
</para>
<!-- TODO: lcov -->
<para>
For example, the following command configures Kea to find the
Boost headers in /usr/pkg/include, specifies that PostgreSQL
support should be enabled, and sets the installation location
to /opt/kea:
<screen>$ <userinput>./configure \
--with-boost-include=/usr/pkg/include \
--with-dhcp-pgsql=/usr/local/bin/pg_config \
--prefix=/opt/kea</userinput></screen>
</para>
<para>
If the configure fails, it may be due to missing or old
dependencies.
</para>
</section>
<section>
<title>Build</title>
<para>
After the configure step is complete, build the executables
from the C++ code and prepare the Python scripts by running the command:
<screen>$ <userinput>make</userinput></screen>
</para>
</section>
<section>
<title>Install</title>
<para>
To install the Kea executables, support files,
and documentation, issue the command:
<screen>$ <userinput>make install</userinput></screen>
</para>
<para>
Do not use any form of parallel or job server options
(such as GNU make's <command>-j</command> option) when
performing this step: doing so may cause errors.
</para>
<note>
<para>The install step may require superuser privileges.</para>
</note>
<para>
If required, run <command>ldconfig</command> as root with
<filename>/usr/local/lib</filename> (or with ${prefix}/lib if
configured with --prefix) in
<filename>/etc/ld.so.conf</filename> (or the relevant linker
cache configuration file for your OS):
<screen>$ <userinput>ldconfig</userinput></screen>
</para>
<note>
<para>
If you do not run <command>ldconfig</command> where it is
required, you may see errors like the following:
<screen>
program: error while loading shared libraries: libkea-something.so.1:
cannot open shared object file: No such file or directory
</screen>
</para>
</note>
</section>
<!-- @todo: tests -->
</section>
<section id="dhcp-config-backend">
<title>Selecting the Configuration Backend</title>
<para>Kea 0.9 introduces configuration backends that are
switchable during compilation phase. The backend is chosen using
the --with-kea-config switch when running the configure script. It
currently supports two values: BIND10 and JSON. This is currently
only supported by DHCPv6 component.</para>
<variablelist>
<varlistentry>
<term>BIND10</term>
<listitem>
<simpara>BIND10 (which is the default value as of April 2014) means
that Kea6 is linked with the BIND10 configuration backend that
connects to the BIND10 framework and in general works exactly the
same as Kea 0.8 and earlier versions. The benefits of that backend
are uniform integration with BIND10 framework, easy on-line
reconfiguration using bindctl, available RESTful API. On the other
hand, it requires the whole heavy BIND10 framework that requires
Python3 to be present. That backend is likely to go away with the
release of Kea 0.9.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>JSON</term>
<listitem>
<simpara>JSON is a new configuration backend that causes Kea to read
JSON configuration file from disk. It does not require any framework
and thus is considered more lightweight. It will allow dynamic
on-line reconfiguration, but will lack remote capabilities (i.e. no
RESTful API). This configuration backend is expected to be the
default for upcoming Kea 0.9.</simpara>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id="dhcp-install-configure">
<title>DHCP Database Installation and Configuration</title>
<para>
Kea stores its leases in a lease database. The software has been written in
a way that makes it possible to choose which database product should be used to
store the lease information. At present, Kea supports three database backends: MySQL,
PostgreSQL and Memfile. To limit external dependencies, both MySQL and PostgreSQL
support are disabled by default and only Memfile (which is implemented in pure C++)
is available. Support for a given database backend must be explicitly included when
Kea is built. This section covers the building of Kea with MySQL and/or PostgreSQL
and the creation of the lease database.
</para>
<section>
<title>Building with MySQL Support</title>
<para>
Install MySQL according to the instructions for your system. The client development
libraries must be installed.
</para>
<para>
Build and install Kea as described in <xref linkend="installation"/>, with
the following modification: to enable the MySQL database code, at the
"configure" step (see <xref linkend="configure"/>), specify the location of the
MySQL configuration program "mysql_config" with the "--with-dhcp-mysql" switch,
i.e.
<screen><userinput>./configure [other-options] --with-dhcp-mysql</userinput></screen>
...if MySQL was installed in the default location, or:
<screen><userinput>./configure [other-options] --with-dhcp-mysql=<replaceable>path-to-mysql_config</replaceable></userinput></screen>
...if not.
</para>
</section>
<section id="dhcp-mysql-database-create">
<title>Create the MySQL Database and the Kea User</title>
<para>
The next task is to create both the lease database and the user under which the servers will
access it. A number of steps are required:
</para>
<para>
1. Log into MySQL as "root":
<screen>$ <userinput>mysql -u root -p</userinput>
Enter password:<userinput/>
:<userinput/>
mysql></screen>
</para>
<para>
2. Create the database:
<screen>mysql> <userinput>CREATE DATABASE <replaceable>database-name</replaceable>;</userinput></screen>
... <replaceable>database-name</replaceable> is the name you have chosen for the database.
</para>
<para>
3. Create the database tables by running the dhcpdb_create.mysql script supplied as part of Kea:
<screen>mysql> <userinput>CONNECT <replaceable>database-name</replaceable>;</userinput>
mysql> <userinput>SOURCE <replaceable>path-to-bind10</replaceable>/share/bind10/dhcpdb_create.mysql</userinput></screen>
</para>
<para>
4. Create the user under which Kea will access the database (and give it a password), then grant it access to the database tables:
<screen>mysql> <userinput>CREATE USER '<replaceable>user-name</replaceable>'@'localhost' IDENTIFIED BY '<replaceable>password</replaceable>';</userinput>
mysql> <userinput>GRANT ALL ON <replaceable>database-name</replaceable>.* TO '<replaceable>user-name</replaceable>'@'localhost';</userinput></screen>
</para>
<para>
5. Exit MySQL:
<screen>mysql> <userinput>quit</userinput>
Bye<userinput/>
$</screen>
</para>
</section>
<section>
<title>Building with PostgreSQL support</title>
<para>
Install PostgreSQL according to the instructions for your system. The client development
libraries must be installed. Client development libraries are often packaged as &quot;libpq&quot;.
</para>
<para>
Build and install Kea as described in <xref linkend="installation"/>, with
the following modification: to enable the PostgreSQL database code, at the
"configure" step (see <xref linkend="configure"/>), specify the location of the
PostgreSQL configuration program "pg_config" with the "--with-dhcp-pgsql" switch,
i.e.
<screen><userinput>./configure [other-options] --with-dhcp-pgsql</userinput></screen>
...if PostgreSQL was installed in the default location, or:
<screen><userinput>./configure [other-options] --with-dhcp-pgsql=<replaceable>path-to-pg_config</replaceable></userinput></screen>
...if not.
</para>
</section>
<section id="dhcp-pgsql-database-create">
<title>Create PostgreSQL Database and Kea User</title>
<para>
The next task is to create both the lease database and the user under which the servers will
access it. A number of steps are required:
</para>
<para>
1. Log into PostgreSQL as "root":
<screen>$ <userinput>sudo -u postgres psql postgres</userinput>
Enter password:<userinput/>
:<userinput/>
postgres=#</screen>
</para>
<para>
2. Create the database:
<screen>
postgres=#<userinput> CREATE DATABASE <replaceable>database-name</replaceable>;</userinput>
CREATE DATABASE
postgres=#
</screen>
... <replaceable>database-name</replaceable> is the name you have chosen for the database.
</para>
<para>
3. Create the user under which Kea will access the database (and give it a password), then grant it access to the database:
<screen>postgres=#<userinput> CREATE USER <replaceable>user-name</replaceable> WITH PASSWORD '<replaceable>password</replaceable>';</userinput>
CREATE ROLE
postgres=#
postgres=#<userinput> GRANT ALL PRIVILEGES ON DATABASE <replaceable>database-name</replaceable> TO <replaceable>user-name</replaceable>;</userinput>
GRANT
postgres=#
</screen>
</para>
<para>
4. Exit PostgreSQL:
<screen>postgres=# <userinput>\q</userinput>
Bye<userinput/>
$</screen>
</para>
<para>
5. Create the database tables using the new user's credentials and the dhcpdb_create.pgsql script supplied with Kea.
After entering the following command, you will be prompted for the new
user's password. When the command completes you will be returned to
the shell prompt. You should see output similar to following:
<screen>$ <userinput>psql -d <replaceable>database-name</replaceable> -U <replaceable>user-name</replaceable> -f <replaceable>path-to-bind10</replaceable>/share/bind10/dhcpdb_create.pgsql</userinput>
Password for user <replaceable>user-name</replaceable>:
CREATE TABLE
CREATE INDEX
CREATE INDEX
CREATE TABLE
CREATE INDEX
CREATE TABLE
START TRANSACTION
INSERT 0 1
INSERT 0 1
INSERT 0 1
COMMIT
CREATE TABLE
START TRANSACTION
INSERT 0 1
COMMIT
$
</screen>
</para>
<para>
If instead you encounter an error like:
</para>
<screen>
psql: FATAL: no pg_hba.conf entry for host "[local]", user "<replaceable>user-name</replaceable>", database "<replaceable>database-name</replaceable>", SSL off
</screen>
<para>
... you will need to alter the PostgreSQL configuration.
Kea uses password authentication when connecting to the database and must
have the appropriate entries added to PostgreSQL's pg_hba.conf file. This
file is normally located in the primary data directory for your PostgreSQL
server. The precise path may vary but the default location for PostgreSQL 9.3
on Centos 6.5 is:
<filename>/var/lib/pgsql/9.3/data/pg_hba.conf</filename>.
Assuming Kea is running on the same host as PostgreSQL, adding lines similar
to following should be sufficient to provide password-authenticated access to
Kea's database:
</para>
<screen>
local <replaceable>database-name</replaceable> <replaceable>user-name</replaceable> password
host <replaceable>database-name</replaceable> <replaceable>user-name</replaceable> 127.0.0.1/32 password
host <replaceable>database-name</replaceable> <replaceable>user-name</replaceable> ::1/128 password
</screen>
<para>
Please consult your PostgreSQL user manual before making these changes as they
may expose your other databases that you run on the same system.
</para>
</section>
</section>
</chapter>

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

@@ -0,0 +1,300 @@
<?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 software 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 was 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 software. 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 was implemented in the BIND 10 framework and to certain extent
still depends on various BIND 10 libraries. It also requires the BIND 10
framework to run, because the 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 the default installation of some operating systems,
nor in the standard package collections. You may
need to install this required software separately.
(For the build requirements, also see
<xref linkend="build-requirements"/>.)
</para>
<itemizedlist>
<listitem>
<simpara>
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 replacement configuration and startup
mechanisms are developed and released as Kea 0.9. At this
point Kea will be written in pure C++.
</simpara>
</listitem>
<listitem>
<simpara>
Kea supports two crypto libraries: Botan and OpenSSL. Only one of them
is required during compilation. Kea uses the Botan crypto library for
C++ (<ulink url="http://botan.randombit.net/"/>), version 1.8 or
later. As an alternative to Botan, Kea can use the OpenSSL crypto
library (<ulink url="http://www.openssl.org/"/>). It requires a version
with SHA-2 support.
</simpara>
</listitem>
<listitem>
<simpara>
Kea uses the log4cplus C++ logging library
(<ulink url="http://log4cplus.sourceforge.net/"/>).
It requires at least log4cplus version 1.0.3.
</simpara>
</listitem>
<listitem>
<simpara>
In order to store lease information in a MySQL database, Kea requires MySQL
headers and libraries. This is an optional dependency in that Kea can be
built without MySQL support.
</simpara>
</listitem>
<listitem>
<simpara>
In order to store lease information in a PostgresSQL database, Kea requires PostgresSQL
headers and libraries. This is an optional dependency in that Kea can be
built without PostgresSQL support.
</simpara>
</listitem>
</itemizedlist>
</section>
<section id="starting_stopping">
<title>Starting and Stopping the Server</title>
<!-- @todo: Rewrite this section after #3422 is done -->
<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 after #3422 is done -->
<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>

0
doc/guide/bind10-guide.css → doc/guide/kea-guide.css
View File

134
doc/guide/kea-guide.xml Normal file
View File

@@ -0,0 +1,134 @@
<?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;
]>
<!--
- Copyright (C) 2010-2014 Internet Systems Consortium, Inc. ("ISC")
-
- Permission to use, copy, modify, and/or distribute this software for any
- purpose with or without fee is hereby granted, provided that the above
- copyright notice and this permission notice appear in all copies.
-
- THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
- REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
- AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
- LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<book>
<?xml-stylesheet href="bind10-guide.css" type="text/css"?>
<bookinfo>
<title>Kea Administrator Reference Manual</title>
<copyright>
<year>2010-2014</year><holder>Internet Systems Consortium, Inc.</holder>
</copyright>
<abstract>
<para>
Kea is an open source implementation of the Dynamic Host Configuration
Protocol (DHCP) servers, developed and maintained by Internet Systems
Consortium (ISC).
</para>
<para>
This is the reference guide for Kea version &__VERSION__;.
The most up-to-date version of this document (in PDF, HTML,
and plain text formats), along with other documents for
Kea, can be found at <ulink url="http://kea.isc.org/docs"/>.
</para> </abstract>
<releaseinfo>This is the reference guide for Kea version
&__VERSION__;.</releaseinfo>
</bookinfo>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="intro.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="quickstart.xml" />
<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" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp4-srv.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp6-srv.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ddns.xml" />
<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>
<para><ulink url="http://jprs.co.jp/">JPRS</ulink> and
<ulink url="http://cira.ca/">CIRA</ulink> are Patron Level
sponsors.</para>
<para><ulink url="https://www.afnic.fr/">AFNIC</ulink>,
<ulink url="https://www.cnnic.net.cn/">CNNIC</ulink>,
<ulink url="https://www.nic.cz/">CZ.NIC</ulink>,
<ulink url="http://www.denic.de/">DENIC eG</ulink>,
<ulink url="https://www.google.com/">Google</ulink>,
<ulink url="https://www.ripe.net/">RIPE NCC</ulink>,
<ulink url="https://registro.br/">Registro.br</ulink>,
<ulink url="https://nzrs.net.nz/">.nz Registry Services</ulink>, and
<ulink url="https://www.tcinet.ru/">Technical Center of Internet</ulink>
are current sponsors.</para>
<para><ulink url="https://www.afilias.info/">Afilias</ulink>,
<ulink url="https://www.iis.se/">IIS.SE</ulink>,
<ulink url="http://www.nominet.org.uk/">Nominet</ulink>, and
<ulink url="https://www.sidn.nl/">SIDN</ulink> were founding
sponsors of the project.</para>
<!-- DHCP sponsorship by Comcast -->
</chapter>
<!-- TODO: Add bibliography section (mostly RFCs, probably) -->
<!-- TODO: how to help: run unit tests, join lists, review trac tickets -->
<!-- <index> <title>Index</title> </index> -->
</book>
<!--
TODO:
Overview
Getting BIND 10 Installed
Basics
Dependencies
Optional
Advanced
How Does Everything Work Together?
Need Help?
-->

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>

719
doc/guide/logging.xml Normal file
View File

@@ -0,0 +1,719 @@
<?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="logging">
<title>Logging</title>
<section>
<title>Logging configuration</title>
<para>
The logging system in Kea is configured through the
Logging module. All modules will look at the
configuration in Logging to see what should be logged and
to where.
<!-- TODO: what is context of Logging module for readers of this guide? -->
</para>
<section>
<title>Loggers</title>
<para>
Within Kea, a message is logged through a component
called a "logger". Different parts of log messages
through different loggers, and each logger can be configured
independently of one another.
</para>
<para>
In the Logging module, you can specify the configuration
for zero or more loggers; any that are not specified will
take appropriate default values.
</para>
<para>
The three most important elements of a logger configuration
are the <option>name</option> (the component that is
generating the messages), the <option>severity</option>
(what to log), and the <option>output_options</option>
(where to log).
</para>
<section>
<title>name (string)</title>
<para>
Each logger in the system has a name, the name being that
of the component using it to log messages. For instance,
if you want to configure logging for the Dhcp4 module,
you add an entry for a logger named <quote>Dhcp4</quote>. This
configuration will then be used by the loggers in the
Dhcp4 module, and all the libraries used by it.
</para>
<!-- TODO: later we will have a way to know names of all modules
Right now you can only see what their names are if they are running
(a simple 'help' without anything else in bindctl for instance).
-->
<para>
If you want to specify logging for one specific library
within the module, you set the name to
<replaceable>module.library</replaceable>. For example, the
logger used by the nameserver address store component
has the full name of <quote>Dhcp4.dhcpsrv</quote>. If
there is no entry in Logging for a particular library,
it will use the configuration given for the module.
</para>
<para>
To illustrate this, suppose you want the dhcpsrv library
to log messages of severity DEBUG, and the rest of the
Dhcp4 code to log messages of severity INFO. To achieve
this you specify two loggers, one with the name
<quote>Dhcp4</quote> and severity INFO, and one with
the name <quote>Dhcp4.dhcpsrv</quote> with severity
DEBUG. As there are no entries for other libraries,
they will use the configuration for the module
(<quote>Dhcp4</quote>), so giving the desired behavior.
</para>
<para>
One special case is that of a module name of <quote>*</quote>
(asterisks), which is interpreted as <emphasis>any</emphasis>
module. You can set global logging options by using this,
including setting the logging configuration for a library
that is used by multiple modules (e.g. <quote>*.config</quote>
specifies the configuration library code in whatever
module is using it).
</para>
<para>
If there are multiple logger specifications in the
configuration that might match a particular logger, the
specification with the more specific logger name takes
precedence. For example, if there are entries for
both <quote>*</quote> and <quote>Dhcp4</quote>, the
Dhcp4 module &mdash; and all libraries it uses &mdash;
will log messages according to the configuration in the
second entry (<quote>Dhcp4</quote>). All other modules
will use the configuration of the first entry
(<quote>*</quote>).
</para>
<para>
One final note about the naming. When specifying the
module name within a logger, use the name of the module
as specified in <command>bindctl</command>, e.g.
<quote>Dhcp4</quote> for the Dhcp4 module,
<quote>Dhcp6</quote> for the Dhcp6 module, etc. When
the message is logged, the message will include the name
of the logger generating the message, but with the module
name replaced by the name of the process implementing
the module (so for example, a message generated by the
<quote>Dhcp4</quote> logger will appear in the output
with a logger name of <quote>b10-dhcp4</quote>).
</para>
</section>
<section>
<title>severity (string)</title>
<para>
This specifies the category of messages logged.
Each message is logged with an associated severity which
may be one of the following (in descending order of
severity):
</para>
<itemizedlist>
<listitem>
<simpara> FATAL </simpara>
</listitem>
<listitem>
<simpara> ERROR </simpara>
</listitem>
<listitem>
<simpara> WARN </simpara>
</listitem>
<listitem>
<simpara> INFO </simpara>
</listitem>
<listitem>
<simpara> DEBUG </simpara>
</listitem>
</itemizedlist>
<para>
When the severity of a logger is set to one of these
values, it will only log messages of that severity, and
the severities above it. The severity may also be set to
NONE, in which case all messages from that logger are
inhibited.
<!-- TODO: worded wrong? If I set to INFO, why would it show DEBUG which is literally below in that list? -->
</para>
</section>
<section>
<title>output_options (list)</title>
<para>
Each logger can have zero or more
<option>output_options</option>. These specify where log
messages are sent to. These are explained in detail below.
</para>
<para>
The other options for a logger are:
</para>
</section>
<section>
<title>debuglevel (integer)</title>
<para>
When a logger's severity is set to DEBUG, this value
specifies what debug messages should be printed. It ranges
from 0 (least verbose) to 99 (most verbose).
</para>
<!-- TODO: complete this sentence:
The general classification of debug message types is
TODO; there's a ticket to determine these levels, see #1074
-->
<para>
If severity for the logger is not DEBUG, this value is ignored.
</para>
</section>
<section>
<title>additive (true or false)</title>
<para>
If this is true, the <option>output_options</option> from
the parent will be used. For example, if there are two
loggers configured; <quote>Dhcp4</quote> and
<quote>Dhcp4.dhcpsrv</quote>, and <option>additive</option>
is true in the second, it will write the log messages
not only to the destinations specified for
<quote>Dhcp4.dhcpsrv</quote>, but also to the destinations
as specified in the <option>output_options</option> in
the logger named <quote>Dhcp4</quote>.
</para>
</section>
</section>
<section>
<title>Output Options</title>
<para>
The main settings for an output option are the
<option>destination</option> and a value called
<option>output</option>, the meaning of which depends on
the destination that is set.
</para>
<section>
<title>destination (string)</title>
<para>
The destination is the type of output. It can be one of:
</para>
<itemizedlist>
<listitem>
<simpara> console </simpara>
</listitem>
<listitem>
<simpara> file </simpara>
</listitem>
<listitem>
<simpara> syslog </simpara>
</listitem>
</itemizedlist>
</section>
<section>
<title>output (string)</title>
<para>
Depending on what is set as the output destination, this
value is interpreted as follows:
</para>
<variablelist>
<varlistentry>
<term><option>destination</option> is <quote>console</quote></term>
<listitem>
<para>
The value of output must be one of <quote>stdout</quote>
(messages printed to standard output) or
<quote>stderr</quote> (messages printed to standard
error).
</para>
<para>
Note: if output is set to <quote>stderr</quote> and a lot of
messages are produced in a short time (e.g. if the logging
level is set to DEBUG), you may occasionally see some messages
jumbled up together. This is due to a combination of the way
that messages are written to the screen and the unbuffered
nature of the standard error stream. If this occurs, it is
recommended that output be set to <quote>stdout</quote>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>destination</option> is <quote>file</quote></term>
<listitem>
<para>
The value of output is interpreted as a file name;
log messages will be appended to this file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>destination</option> is <quote>syslog</quote></term>
<listitem>
<para>
The value of output is interpreted as the
<command>syslog</command> facility (e.g.
<emphasis>local0</emphasis>) that should be used
for log messages.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The other options for <option>output_options</option> are:
</para>
<section>
<title>flush (true of false)</title>
<para>
Flush buffers after each log message. Doing this will
reduce performance but will ensure that if the program
terminates abnormally, all messages up to the point of
termination are output.
</para>
</section>
<section>
<title>maxsize (integer)</title>
<para>
Only relevant when destination is file, this is maximum
file size of output files in bytes. When the maximum
size is reached, the file is renamed and a new file opened.
(For example, a ".1" is appended to the name &mdash;
if a ".1" file exists, it is renamed ".2",
etc.)
</para>
<para>
If this is 0, no maximum file size is used.
</para>
<note>
<simpara>
Due to a limitation of the underlying logging library
(log4cplus), rolling over the log files (from ".1" to
".2", etc) may show odd results: There can be
multiple small files at the timing of roll over. This
can happen when multiple processes try to roll
over the files simultaneously.
Version 1.1.0 of log4cplus solved this problem, so if
this or higher version of log4cplus is used to build
Kea, it shouldn't happen. Even for older versions
it is normally expected to happen rarely unless the log
messages are produced very frequently by multiple
different processes.
</simpara>
</note>
</section>
<section>
<title>maxver (integer)</title>
<para>
Maximum number of old log files to keep around when
rolling the output file. Only relevant when
<option>destination</option> is <quote>file</quote>.
</para>
</section>
</section>
</section>
<section>
<title>Example session</title>
<para>
In this example we want to set the global logging to
write to the file <filename>/var/log/my_bind10.log</filename>,
at severity WARN. We want the authoritative server to
log at DEBUG with debuglevel 40, to a different file
(<filename>/tmp/debug_messages</filename>).
</para>
<para>
Start <command>bindctl</command>.
</para>
<para>
<screen>["login success "]
&gt; <userinput>config show Logging</userinput>
Logging/loggers [] list
</screen>
</para>
<para>
By default, no specific loggers are configured, in which
case the severity defaults to INFO and the output is
written to stderr.
</para>
<para>
Let's first add a default logger:
</para>
<!-- TODO: adding the empty loggers makes no sense -->
<para>
<screen>&gt; <userinput>config add Logging/loggers</userinput>
&gt; <userinput>config show Logging</userinput>
Logging/loggers/ list (modified)
</screen>
</para>
<para>
The loggers value line changed to indicate that it is no
longer an empty list:
</para>
<para>
<screen>&gt; <userinput>config show Logging/loggers</userinput>
Logging/loggers[0]/name "" string (default)
Logging/loggers[0]/severity "INFO" string (default)
Logging/loggers[0]/debuglevel 0 integer (default)
Logging/loggers[0]/additive false boolean (default)
Logging/loggers[0]/output_options [] list (default)
</screen>
</para>
<para>
The name is mandatory, so we must set it. We will also
change the severity as well. Let's start with the global
logger.
</para>
<para>
<screen>&gt; <userinput>config set Logging/loggers[0]/name *</userinput>
&gt; <userinput>config set Logging/loggers[0]/severity WARN</userinput>
&gt; <userinput>config show Logging/loggers</userinput>
Logging/loggers[0]/name "*" string (modified)
Logging/loggers[0]/severity "WARN" string (modified)
Logging/loggers[0]/debuglevel 0 integer (default)
Logging/loggers[0]/additive false boolean (default)
Logging/loggers[0]/output_options [] list (default)
</screen>
</para>
<para>
Of course, we need to specify where we want the log
messages to go, so we add an entry for an output option.
</para>
<para>
<screen>&gt; <userinput> config add Logging/loggers[0]/output_options</userinput>
&gt; <userinput> config show Logging/loggers[0]/output_options</userinput>
Logging/loggers[0]/output_options[0]/destination "console" string (default)
Logging/loggers[0]/output_options[0]/output "stdout" string (default)
Logging/loggers[0]/output_options[0]/flush false boolean (default)
Logging/loggers[0]/output_options[0]/maxsize 0 integer (default)
Logging/loggers[0]/output_options[0]/maxver 0 integer (default)
</screen>
</para>
<para>
These aren't the values we are looking for.
</para>
<para>
<screen>&gt; <userinput> config set Logging/loggers[0]/output_options[0]/destination file</userinput>
&gt; <userinput> config set Logging/loggers[0]/output_options[0]/output /var/log/kea.log</userinput>
&gt; <userinput> config set Logging/loggers[0]/output_options[0]/maxsize 204800</userinput>
&gt; <userinput> config set Logging/loggers[0]/output_options[0]/maxver 8</userinput>
</screen>
</para>
<para>
Which would make the entire configuration for this logger
look like:
</para>
<para>
<screen>&gt; <userinput> config show all Logging/loggers</userinput>
Logging/loggers[0]/name "*" string (modified)
Logging/loggers[0]/severity "WARN" string (modified)
Logging/loggers[0]/debuglevel 0 integer (default)
Logging/loggers[0]/additive false boolean (default)
Logging/loggers[0]/output_options[0]/destination "file" string (modified)
Logging/loggers[0]/output_options[0]/output "/var/log/kea.log" string (modified)
Logging/loggers[0]/output_options[0]/flush false boolean (default)
Logging/loggers[0]/output_options[0]/maxsize 204800 integer (modified)
Logging/loggers[0]/output_options[0]/maxver 8 integer (modified)
</screen>
</para>
<para>
That looks OK, so let's commit it before we add the
configuration for the authoritative server's logger.
</para>
<para>
<screen>&gt; <userinput> config commit</userinput></screen>
</para>
<para>
Now that we have set it, and checked each value along
the way, adding a second entry is quite similar.
</para>
<para>
<screen>&gt; <userinput> config add Logging/loggers</userinput>
&gt; <userinput> config set Logging/loggers[1]/name Dhcp4</userinput>
&gt; <userinput> config set Logging/loggers[1]/severity DEBUG</userinput>
&gt; <userinput> config set Logging/loggers[1]/debuglevel 40</userinput>
&gt; <userinput> config add Logging/loggers[1]/output_options</userinput>
&gt; <userinput> config set Logging/loggers[1]/output_options[0]/destination file</userinput>
&gt; <userinput> config set Logging/loggers[1]/output_options[0]/output /tmp/dhcp4_debug.log</userinput>
&gt; <userinput> config commit</userinput>
</screen>
</para>
<para>
And that's it. Once we have found whatever it was we
needed the debug messages for, we can simply remove the
second logger to let the DHCP server use the
same settings as the rest.
</para>
<para>
<screen>&gt; <userinput> config remove Logging/loggers[1]</userinput>
&gt; <userinput> config commit</userinput>
</screen>
</para>
<para>
And every module will now be using the values from the
logger named <quote>*</quote>.
</para>
</section>
</section>
<section>
<title>Logging Message Format</title>
<para>
Each message written to the configured logging
destinations comprises a number of components that identify
the origin of the message and, if the message indicates
a problem, information about the problem that may be
useful in fixing it.
</para>
<para>
Consider the message below logged to a file:
<screen>2014-04-11 12:58:01.005 INFO [b10-dhcp4.dhcpsrv/27456]
DHCPSRV_MEMFILE_DB opening memory file lease database: type=memfile universe=4</screen>
</para>
<para>
Note: the layout of messages written to the system logging
file (syslog) may be slightly different. This message has
been split across two lines here for display reasons; in the
logging file, it will appear on one line.)
</para>
<para>
The log message comprises a number of components:
<variablelist>
<varlistentry>
<term>2014-04-11 12:58:01.005</term>
<!-- TODO: timestamp repeated even if using syslog? -->
<listitem><para>
The date and time at which the message was generated.
</para></listitem>
</varlistentry>
<varlistentry>
<term>INFO</term>
<listitem><para>
The severity of the message.
</para></listitem>
</varlistentry>
<varlistentry>
<term>[b10-dhcp4.dhcpsrv/27456]</term>
<listitem><para>
The source of the message. This comprises two components:
the BIND 10 process generating the message (in this
case, <command>b10-dhcp4</command>) and the module
within the program from which the message originated
(which is the name of the common library used by DHCP server
implementations).
</para></listitem>
</varlistentry>
<varlistentry>
<term>DHCPSRV_MEMFILE_DB</term>
<listitem><para>
The message identification. Every message in Kea
has a unique identification, which can be used as an
index into the <ulink
url="kea-messages.html"><citetitle>Kea Messages
Manual</citetitle></ulink> (<ulink
url="http://kea.isc.org/docs/kea-messages.html"
/>) from which more information can be obtained.
</para></listitem>
</varlistentry>
<varlistentry>
<term>opening memory file lease database: type=memfile universe=4</term>
<listitem><para>
A brief description.
Within this text, information relating to the condition
that caused the message to be logged will be included.
In this example, the information is logged that the in-memory
lease database backend will be used to store DHCP leases.
</para></listitem>
</varlistentry>
</variablelist>
</para>
</section>
</chapter>

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

@@ -0,0 +1,115 @@
<?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 directory and run the configure script:
<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 (by default the installation prefix is <filename>/usr/local/</filename>,
so you need root privileges for that step):
<screen>$ <userinput>make install</userinput></screen>
</para>
</listitem>
<listitem>
<para>If you wish to run a DHCP server for IPv4, you need to set up and start
the b10-dhcp4 server:</para>
<orderedlist>
<listitem>
<para>Edit your configuration file for DHCPv4. <xref linkend="dhcp4-configuration"/>
describes the configuration choices available; example DHCPv4 configuration can be found in
doc/examples/kea4.</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>
</orderedlist>
</listitem>
<listitem>
<para>If you wish to run a DHCP server for IPv6, you need to set up and start
the b10-dhcp6 server:</para>
<orderedlist>
<listitem>
<para>Edit your configuration file for DHCPv6. <xref linkend="dhcp6-configuration"/>
describes the configuration ch, and some example DHCPv6 configuration can be found in
doc/examples/kea6.</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>
</listitem>
</orderedlist>
</section>
</chapter>