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

Conflicts:
	ChangeLog
	doc/guide/bind10-guide.xml

ChangeLog

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

configure.ac

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

doc/Makefile.am

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

doc/guide/.gitignore

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

doc/guide/Makefile.am

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

doc/guide/config.xml

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

doc/guide/ddns.xml

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

doc/guide/install.xml

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

doc/guide/intro.xml

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

doc/guide/kea-guide.xml

@@ -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?
+
+-->

doc/guide/libdhcp.xml

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

doc/guide/logging.xml

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

doc/guide/quickstart.xml

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