Commit 399b4bc6 authored by Francis Dupont's avatar Francis Dupont Committed by Marcin Siodelski

[198-user-s-guide-update-json-section-needs-a-refresh] Added ECMA 404 ref and cleaned up JSON stuff

parent c91d4e12
......@@ -28,11 +28,17 @@
<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
......@@ -56,24 +62,33 @@
<listitem>
<simpara>File inclusion: JSON files can include other JSON
files. This can be done by using &lt;?include
"file.json"?&gt;. Both Dhcp4 and Dhcp6 supports this
feature.</simpara>
"file.json"?&gt;. 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.
{
......@@ -94,31 +109,13 @@
},
# 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.
}
......@@ -128,25 +125,29 @@
<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>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment