1 files changed, 330 insertions, 0 deletions
diff --git a/doc/sphinx/arm/config.rst b/doc/sphinx/arm/config.rst
new file mode 100644
index 0000000..cb29dcc
--- /dev/null
+++ b/doc/sphinx/arm/config.rst
@@ -0,0 +1,330 @@
+.. _kea-config:
+
+*****************
+Kea Configuration
+*****************
+
+Kea uses JSON structures to represent server configurations. The
+following sections describe how the configuration structures are
+organized.
+
+.. _json:
+
+JSON Configuration
+==================
+
+JSON is the notation used throughout the Kea project. The most obvious
+usage is for the configuration file, but JSON is also used for sending
+commands over the Management API (see :ref:`ctrl-channel`) and for
+communicating between DHCP servers and the DDNS update daemon.
+
+Typical usage assumes that the servers are started from the command
+line, either directly or using a script, e.g. ``keactrl``. The
+configuration file is specified upon startup using the ``-c`` parameter.
+
+.. _json-format:
+
+JSON Syntax
+-----------
+
+Configuration files for the DHCPv4, DHCPv6, DDNS, Control Agent, and
+NETCONF modules are defined in an extended JSON format. Basic JSON is
+defined in `RFC 7159 <https://tools.ietf.org/html/rfc7159>`__ and `ECMA
+404 <https://www.ecma-international.org/publications/standards/Ecma-404.htm>`__.
+In particular, the only boolean values allowed are true or false (all
+lowercase). The capitalized versions (True or False) are not accepted.
+
+Even though the JSON standard (ECMA 404) does not require JSON objects
+(i.e. name/value maps) to have unique entries, Kea implements them
+using a C++ STL map with unique entries. Therefore, if there are multiple
+values for the same name in an object/map, the last value overwrites previous values.
+Since Kea 1.9.0, configuration file parsers raise a syntax error in such cases.
+
+Kea components use extended JSON with additional features allowed:
+
+-  Shell comments: any text after the hash (#) character is ignored.
+
+-  C comments: any text after the double slashes (//) character is
+   ignored.
+
+-  Multiline comments: any text between /\* and \*/ is ignored. This
+   comment can span multiple lines.
+
+-  File inclusion: JSON files can include other JSON files by using a
+   statement of the form \<?include "file.json"?\>.
+
+-  Extra commas: to remove the inconvenience of errors caused by leftover commas
+   after making changes to configuration. While parsing, a warning is printed
+   with the location of the comma to give the user the ability to correct a
+   potential mistake.
+
+.. warning::
+
+   These features are meant to be used in a JSON configuration file.
+   Their usage in any other way may result in errors.
+
+The configuration file consists of a single object (often colloquially
+called a map) started with a curly bracket. It comprises only one of
+the "Dhcp4", "Dhcp6", "DhcpDdns", "Control-agent", or "Netconf" objects.
+It is possible to define additional elements but they will be ignored.
+
+A very simple configuration for DHCPv4 could look like this:
+
+::
+
+   # The whole configuration starts here.
+   {
+       # DHCPv4 specific configuration starts here.
+       "Dhcp4": {
+           "interfaces-config": {
+               "interfaces": [ "eth0" ],
+               "dhcp-socket-type": "raw"
+           },
+           "valid-lifetime": 4000,
+           "renew-timer": 1000,
+           "rebind-timer": 2000,
+           "subnet4": [{
+              "pools": [ { "pool": "192.0.2.1-192.0.2.200" } ],
+              "subnet": "192.0.2.0/24"
+           }],
+
+          # Now loggers are inside the DHCPv4 object.
+          "loggers": [{
+               "name": "*",
+               "severity": "DEBUG"
+           }]
+       }
+
+   # The whole configuration structure ends here.
+   }
+
+More examples are available in the installed ``share/doc/kea/examples``
+directory.
+
+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 the remaining elements (the global map that holds Dhcp6)
+are present, but they are omitted for clarity. Usually,
+locations where extra parameters may appear are denoted by an ellipsis
+(...).
+
+.. _user-context:
+
+Comments and User Context
+-------------------------
+
+Shell, C, or C++ style comments are all permitted in the JSON configuration file if
+the file is used locally. This is convenient and works in simple cases where
+the configuration is kept statically using a local file. However, since comments
+are not part of JSON syntax, most JSON tools detect them as
+errors. Another problem with them is that once Kea loads its configuration, the
+shell, C, and C++ style comments are ignored. If commands such as
+``config-get`` or ``config-write`` are used, those comments are lost. An example of such
+comments was presented in the previous section.
+
+Historically, to address the problem, Kea code allowed the use of `comment` strings
+as valid JSON entities. This had the benefit of being retained through various
+operations (such as ``config-get``), or allowing processing by JSON tools. An
+example JSON comment looks like this:
+
+::
+
+   "Dhcp4": {
+       "subnet4": [{
+           "subnet": "192.0.2.0/24",
+           "pools": [{ "pool": "192.0.2.10 - 192.0.2.20" }],
+           "comment": "second floor"
+       }]
+   }
+
+However, the facts that the comment could only be a single line, and that it was not
+possible to add any other information in a more structured form, were frustrating. One specific
+example was a request to add floor levels and building numbers to subnets. This
+was one of the reasons why the concept of user context was introduced. It
+allows adding an arbitrary JSON structure to most Kea configuration structures.
+
+This has a number of benefits compared to earlier approaches. First, it is fully
+compatible with JSON tools and Kea commands. Second, it allows storing simple
+comment strings, but it can also store much more complex data, such as
+multiple lines (as a string array), extra typed data (such as floor numbers being
+actual numbers), and more. Third, the data is exposed to hooks, so it is possible
+to develop third-party hooks that take advantage of that extra information. An
+example user context looks like this:
+
+::
+
+   "Dhcp4": {
+       "subnet4": [{
+           "subnet": "192.0.2.0/24",
+           "pools": [{ "pool": "192.0.2.10 - 192.0.2.20" }],
+           "user-context": {
+               "comment": "second floor",
+               "floor": 2
+           }
+       }]
+   }
+
+User contexts can store an arbitrary data file as long as it has valid JSON
+syntax and its top-level element is a map (i.e. the data must be enclosed in
+curly brackets). However, some hook libraries may expect specific formatting;
+please consult the specific hook library documentation for details.
+
+In a sense the user-context mechanism has superseded the JSON comment
+capabilities; ISC encourages administrators to use user-context instead of
+the older mechanisms. To promote this way of storing comments, Kea compared
+converts JSON comments to user-context on the fly.
+
+However, if the configuration uses the old JSON
+comment, the ``config-get`` command returns a slightly modified
+configuration. It is not uncommon for a call for ``config-set`` followed by a
+``config-get`` to receive a slightly different structure.
+The best way to avoid this problem is simply to abandon JSON comments and
+use user-context.
+
+Kea supports user contexts at the following levels: global scope,
+interfaces configuration, shared networks,
+subnets, client classes, option data and definitions, host
+reservations, control socket, DHCP-DDNS, loggers, leases, and server ID. These
+are supported in both DHCPv4 and DHCPv6, with the exception of server ID,
+which is DHCPv6 only.
+
+User context can be added and edited in structures supported by commands.
+
+We encourage Kea users to utilize these functions to store information
+used by other systems and custom hooks.
+
+For example, the `subnet4-update` command can be used to add user context data
+to an existing subnet.
+
+::
+
+   "subnet4": [ {
+      "id": 1,
+      "subnet": "10.20.30.0/24",
+      "user-context": {
+         "building": "Main"
+         "floor": 1
+         }
+    } ]
+
+The same can be done with many other commands like lease6-add etc.
+
+Kea also uses user context to store non-standard data.
+Currently, only :ref:`dhcp4-store-extended-info` uses this feature.
+
+When enabled, it adds the ISC key in `user-context` to differentiate automatically
+added content.
+
+Example of relay information stored in a lease:
+
+::
+
+   {
+   "arguments": {
+      "client-id": "42:42:42:42:42:42:42:42",
+      "cltt": 12345678,
+      "fqdn-fwd": false,
+      "fqdn-rev": true,
+      "hostname": "myhost.example.com.",
+      "hw-address": "08:08:08:08:08:08",
+      "ip-address": "192.0.2.1",
+      "state": 0,
+      "subnet-id": 44,
+      "valid-lft": 3600
+      "user-context": {
+         "ISC": {
+         "relays": [
+         {
+               "hop": 2,
+               "link": "2001:db8::1",
+               "peer": "2001:db8::2"
+         },
+         {
+               "hop": 1,
+               "link": "2001:db8::3",
+               "options": "0x00C800080102030405060708",
+               "peer": "2001:db8::4"
+         }]
+         }
+      }
+   }
+
+
+User context can store configuration for multiple hooks and comments at once.
+
+For a discussion about user context used in hooks, see :ref:`user-context-hooks`.
+
+
+Simplified Notation
+-------------------
+
+It is sometimes convenient to refer to a 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
+referenced by a number in square brackets (with numbering starting at
+zero). For example, in the above configuration the valid-lifetime in the
+Dhcp4 component can be referred to as Dhcp4/valid-lifetime, and the pool
+in the first subnet defined in the DHCPv4 configuration as
+Dhcp4/subnet4[0]/pool.
+
+
+.. include:: config-backend.rst
+
+
+Configuration Files Inclusion
+-----------------------------
+
+The parser provides the ability to include files. The syntax was chosen
+to look similar to how Apache includes PHP scripts in HTML code. This particular
+syntax was chosen to emphasize that the include directive is an additional
+feature and not a part of JSON syntax.
+
+The inclusion is implemented as a stack of files. You can use the include directive
+in nested includes. Up to ten nesting levels are supported. This arbitrarily chosen
+limit is protection against recursive inclusions.
+
+The include directive has the form:
+
+::
+
+   <?include "[PATH]"?>
+
+The *[PATH]* pattern should be replaced with an absolute path or a path relative to
+the current working directory at the time the Kea process was launched.
+
+To include one file from another, use the following syntax:
+
+.. code-block:: javascript
+
+   {
+      "Dhcp6": {
+         "interfaces-config": {
+            "interfaces": [ "*" ]},
+         "preferred-lifetime": 3000,
+         "rebind-timer": 2000,
+         "renew-timer": 1000,
+         <?include "subnets.json"?>
+         "valid-lifetime": 4000
+      }
+   }
+
+where the content of "subnets.json" may be:
+
+::
+
+   "subnet4": [
+      {
+         "id": 123,
+         "subnet": "192.0.2.0/24"
+      },
+      {
+         "id": 234,
+         "subnet": "192.0.3.0/24"
+      },
+      {
+         "id": 345,
+         "subnet": "10.0.0.0/8"
+      }
+   ],