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