From: Francis Dupont Date: Wed, 5 Dec 2018 13:17:33 +0000 (+0100) Subject: [198-user-s-guide-update-json-section-needs-a-refresh] Added ECMA 404 ref and cleaned... X-Git-Tag: 343-put-socket-control-buffer-in-the-stack_base~24 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=399b4bc6af66674659c51dc634c0f5e6e2b96a48;p=thirdparty%2Fkea.git [198-user-s-guide-update-json-section-needs-a-refresh] Added ECMA 404 ref and cleaned up JSON stuff --- diff --git a/doc/guide/config.xml b/doc/guide/config.xml index ac8965fa41..af035e06cc 100644 --- a/doc/guide/config.xml +++ b/doc/guide/config.xml @@ -28,11 +28,17 @@
JSON Syntax - Configuration files for DHCPv4, DHCPv6 and DDNS modules are defined - in an extended JSON format. Basic JSON is defined in RFC 7159. 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. + + Configuration files for DHCPv4, DHCPv6, DDNS, Control + Agent and Netconf modules are defined in an extended JSON + format. Basic JSON is defined + in RFC 7159 or + ECMA 404. + 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. Kea components use an extended JSON with additional features @@ -56,24 +62,33 @@ 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. + "file.json"?>. All Kea server or agent configuration + parsers support this feature. - 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. - - A very simple configuration for both DHCPv4 and - DHCPv6 could look like this: + 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. + + + 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, + + + + A very simple configuration for DHCPv4 could look like this: # 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 @@ 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, Logging and possibly - DhcpDdns) are present, but they are omitted for clarity. Usually, locations - where extra parameters may appear are denoted by an ellipsis. + 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.
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 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. + 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.