1.. _kea-config: 2 3***************** 4Kea Configuration 5***************** 6 7Kea uses JSON structures to represent server configurations. The 8following sections describe how the configuration structures are 9organized. 10 11.. _json: 12 13JSON Configuration 14================== 15 16JSON is the notation used throughout the Kea project. The most obvious 17usage is for the configuration file, but JSON is also used for sending 18commands over the Management API (see :ref:`ctrl-channel`) and for 19communicating between DHCP servers and the DDNS update daemon. 20 21Typical usage assumes that the servers are started from the command 22line, either directly or using a script, e.g. ``keactrl``. The 23configuration file is specified upon startup using the ``-c`` parameter. 24 25.. _json-format: 26 27JSON Syntax 28----------- 29 30Configuration files for the DHCPv4, DHCPv6, DDNS, Control Agent, and 31NETCONF modules are defined in an extended JSON format. Basic JSON is 32defined in `RFC 7159 <https://tools.ietf.org/html/rfc7159>`__ and `ECMA 33404 <https://www.ecma-international.org/publications/standards/Ecma-404.htm>`__. 34In particular, the only boolean values allowed are true or false (all 35lowercase). The capitalized versions (True or False) are not accepted. 36 37Even though the JSON standard (ECMA 404) does not require JSON objects 38(i.e. name/value maps) to have unique entries, Kea implements them 39using a C++ STL map with unique entries. Therefore, if there are multiple 40values for the same name in an object/map, the last value overwrites previous values. 41Since Kea 1.9.0, configuration file parsers raise a syntax error in such cases. 42 43Kea components use extended JSON with additional features allowed: 44 45- Shell comments: any text after the hash (#) character is ignored. 46 47- C comments: any text after the double slashes (//) character is 48 ignored. 49 50- Multiline comments: any text between /\* and \*/ is ignored. This 51 comment can span multiple lines. 52 53- File inclusion: JSON files can include other JSON files by using a 54 statement of the form \<?include "file.json"?\>. 55 56The configuration file consists of a single object (often colloquially 57called a map) started with a curly bracket. It comprises only one of 58the "Dhcp4", "Dhcp6", "DhcpDdns", "Control-agent", or "Netconf" objects. 59It is possible to define additional elements but they will be ignored. 60 61A very simple configuration for DHCPv4 could look like this: 62 63:: 64 65 # The whole configuration starts here. 66 { 67 # DHCPv4 specific configuration starts here. 68 "Dhcp4": { 69 "interfaces-config": { 70 "interfaces": [ "eth0" ], 71 "dhcp-socket-type": "raw" 72 }, 73 "valid-lifetime": 4000, 74 "renew-timer": 1000, 75 "rebind-timer": 2000, 76 "subnet4": [{ 77 "pools": [ { "pool": "192.0.2.1-192.0.2.200" } ], 78 "subnet": "192.0.2.0/24" 79 }], 80 81 # Now loggers are inside the DHCPv4 object. 82 "loggers": [{ 83 "name": "*", 84 "severity": "DEBUG" 85 }] 86 } 87 88 # The whole configuration structure ends here. 89 } 90 91More examples are available in the installed ``share/doc/kea/examples`` 92directory. 93 94 .. note:: 95 96 As of Kea 1.6.0, the "Logging" element was removed and its contents (the 97 "loggers" object) moved inside the configuration objects (maps) for the 98 respective Kea modules. For example, the "Dhcp4" map contains the 99 "loggers" object, specifying logging configuration for the DHCPv4 100 server. Support for the top-level "Logging" object was 101 removed in Kea 1.7.10. 102 103 The specification for supporting several elements (e.g. "Dhcp4", "Dhcp6") 104 in one file was removed in Kea 1.7.10, so each component 105 now requires a separate configuration file. 106 107To avoid repetition of mostly similar structures, examples in the rest 108of this guide will showcase only the subset of parameters appropriate 109for a given context. For example, when discussing the IPv6 subnets 110configuration in DHCPv6, only subnet6 parameters will be mentioned. It 111is implied that the remaining elements (the global map that holds Dhcp6) 112are present, but they are omitted for clarity. Usually, 113locations where extra parameters may appear are denoted by an ellipsis 114(...). 115 116.. _user-context: 117 118Comments and User Context 119------------------------- 120 121Shell, C, or C++ style comments are all permitted in the JSON configuration file if 122the file is used locally. This is convenient and works in simple cases where 123the configuration is kept statically using a local file. However, since comments 124are not part of JSON syntax, most JSON tools detect them as 125errors. Another problem with them is that once Kea loads its configuration, the 126shell, C, and C++ style comments are ignored. If commands such as 127``config-get`` or ``config-write`` are used, those comments are lost. An example of such 128comments was presented in the previous section. 129 130Historically, to address the problem, Kea code allowed the use of `comment` strings 131as valid JSON entities. This had the benefit of being retained through various 132operations (such as ``config-get``), or allowing processing by JSON tools. An 133example JSON comment looks like this: 134 135:: 136 137 "Dhcp4": { 138 "subnet4": [{ 139 "subnet": "192.0.2.0/24", 140 "pools": [{ "pool": "192.0.2.10 - 192.0.2.20" }], 141 "comment": "second floor" 142 }] 143 } 144 145However, the facts that the comment could only be a single line, and that it was not 146possible to add any other information in a more structured form, were frustrating. One specific 147example was a request to add floor levels and building numbers to subnets. This 148was one of the reasons why the concept of user context was introduced. It 149allows adding an arbitrary JSON structure to most Kea configuration structures. 150 151This has a number of benefits compared to earlier approaches. First, it is fully 152compatible with JSON tools and Kea commands. Second, it allows storing simple 153comment strings, but it can also store much more complex data, such as 154multiple lines (as a string array), extra typed data (such as floor numbers being 155actual numbers), and more. Third, the data is exposed to hooks, so it is possible 156to develop third-party hooks that take advantage of that extra information. An 157example user context looks like this: 158 159:: 160 161 "Dhcp4": { 162 "subnet4": [{ 163 "subnet": "192.0.2.0/24", 164 "pools": [{ "pool": "192.0.2.10 - 192.0.2.20" }], 165 "user-context": { 166 "comment": "second floor", 167 "floor": 2 168 } 169 }] 170 } 171 172User contexts can store an arbitrary data file as long as it has valid JSON 173syntax and its top-level element is a map (i.e. the data must be enclosed in 174curly brackets). However, some hook libraries may expect specific formatting; 175please consult the specific hook library documentation for details. 176 177In a sense the user-context mechanism has superseded the JSON comment 178capabilities; ISC encourages administrators to use user-context instead of 179the older mechanisms. To promote this way of storing comments, Kea compared 180converts JSON comments to user-context on the fly. 181 182However, if the configuration uses the old JSON 183comment, the ``config-get`` command returns a slightly modified 184configuration. It is not uncommon for a call for ``config-set`` followed by a 185``config-get`` to receive a slightly different structure. 186The best way to avoid this problem is simply to abandon JSON comments and 187use user-context. 188 189For a discussion about user-context used in hooks, see :ref:`user-context-hooks`. 190 191 192Simplified Notation 193------------------- 194 195It is sometimes convenient to refer to a specific element in the 196configuration hierarchy. Each hierarchy level is separated by a slash. 197If there is an array, a specific instance within that array is 198referenced by a number in square brackets (with numbering starting at 199zero). For example, in the above configuration the valid-lifetime in the 200Dhcp4 component can be referred to as Dhcp4/valid-lifetime, and the pool 201in the first subnet defined in the DHCPv4 configuration as 202Dhcp4/subnet4[0]/pool. 203 204 205.. include:: config-backend.rst 206 207 208Configuration Files Inclusion 209----------------------------- 210 211The parser provides the ability to include files. The syntax was chosen 212to look similar to how Apache includes PHP scripts in HTML code. This particular 213syntax was chosen to emphasize that the include directive is an additional 214feature and not a part of JSON syntax. 215 216The inclusion is implemented as a stack of files. You can use the include directive 217in nested includes. Up to ten nesting levels are supported. This arbitrarily chosen 218limit is protection against recursive inclusions. 219 220The include directive has the form: 221 222:: 223 224 <?include "[PATH]"?> 225 226The *[PATH]* pattern should be replaced with an absolute path or a path relative to 227the current working directory at the time the Kea process was launched. 228 229To include one file from another, use the following syntax: 230 231.. code-block:: javascript 232 233 { 234 "Dhcp6": { 235 "interfaces-config": { 236 "interfaces": [ "*" ]}, 237 "preferred-lifetime": 3000, 238 "rebind-timer": 2000, 239 "renew-timer": 1000, 240 <?include "subnets.json"?> 241 "valid-lifetime": 4000 242 } 243 } 244 245where the content of "subnets.json" may be: 246 247:: 248 249 "subnet4": [ 250 { 251 "id": 123, 252 "subnet": "192.0.2.0/24" 253 }, 254 { 255 "id": 234, 256 "subnet": "192.0.3.0/24" 257 }, 258 { 259 "id": 345, 260 "subnet": "10.0.0.0/8" 261 } 262 ], 263