<section xml: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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc7159">RFC 7159</link>. Note that Kea
- 1.2 introduces a new parser that is better at following the JSON spec. In
- particular, the only values allowed for boolean are true or false (all
- lowercase). The capitalized versions (True or False) are not accepted.
+
+ <para>Configuration files for DHCPv4, DHCPv6, DDNS, Control
+ Agent and Netconf modules are defined in an extended JSON
+ format. Basic JSON is defined
+ in <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="http://tools.ietf.org/html/rfc7159">RFC 7159</link> or
+ <link xmlns:xlink="http://www.ecma-international.org/publications/standards/Ecma-404.htm">ECMA 404</link>.
+ Note that Kea 1.2 introduces a new parser that is better at
+ following the JSON spec. In particular, the only values allowed
+ for boolean are true or false (all lowercase). The capitalized
+ versions (True or False) are not accepted.
</para>
<para>Kea components use an extended JSON with additional features
<listitem>
<simpara>File inclusion: JSON files can include other JSON
files. This can be done by using <?include
- "file.json"?>. Both Dhcp4 and Dhcp6 supports this
- feature.</simpara>
+ "file.json"?>. All Kea server or agent configuration
+ parsers support this feature.</simpara>
</listitem>
</itemizedlist>
</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. 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>A very simple configuration for both DHCPv4 and
- DHCPv6 could look like this:
+ <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", "Control-agent",
+ "Netconf" and/or "Logging" objects. It is possible to define
+ additional elements, but they will be ignored and in a future
+ version rejected. 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.
+ This feature is both misleading and does not work when a
+ configuration is retreaved so its support will be removed in
+ a future release.</para>
+
+ <note>
+ <para>The "Logging" object is planned to be merged in the 1.6
+ release, i.e. the "loggers" will have to be moved inside the
+ for instance "Dhcpv4" object/map. Backward compatibility, i.e.
+ "Logging" object/map, will be supported for at least one version,
+ </para>
+ </note>
+
+ <para>A very simple configuration for DHCPv4 could look like this:
<screen>
# The whole configuration starts here.
{
},
# DHCPv4 specific configuration ends here.
-# DHCPv6 specific configuration starts here.
-"Dhcp6": {
- "interfaces-config": {
- "interfaces": [ "eth1" ]
- },
- "preferred-lifetime": 3000,
- "valid-lifetime": 4000,
- "renew-timer": 1000,
- "rebind-timer": 2000,
- "subnet6": [{
- "pools": [ { "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.
+# Logger parameters start here.
"Logging": {
"loggers": [{
"name": "*",
"severity": "DEBUG"
}]
}
-# Logger parameters end here.
# The whole configuration structure ends here.
}
<para>More examples are available in the installed
<filename>share/doc/kea/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
- the 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 by an ellipsis.</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 the remaining elements (the global map that holds
+ Dhcp6, Logging) are present, but they are omitted for
+ clarity. Usually, locations where extra parameters may appear
+ are denoted by an ellipsis.</para>
</section>
<section>
<title>Simplified Notation</title>
- <para>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 Dhcp6 component can be referred to as
- Dhcp6/valid-lifetime and the pool in the first subnet defined in the DHCPv6
- configuration as Dhcp6/subnet6[0]/pool.</para>
+ <para>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 Dhcp6
+ component can be referred to as Dhcp6/valid-lifetime 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>
projects / thirdparty / kea.git / commitdiff
