From: Tomek Mrugalski Date: Sun, 26 Jan 2020 20:38:32 +0000 (+0100) Subject: [#1079] Comments vs user-context documented X-Git-Tag: Kea-1.7.4~50 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ccfb9d4f0e783cf8f00ea45acce8fc5e1ba405f4;p=thirdparty%2Fkea.git [#1079] Comments vs user-context documented --- diff --git a/doc/sphinx/arm/config.rst b/doc/sphinx/arm/config.rst index c02c98987f..965109ca9d 100644 --- a/doc/sphinx/arm/config.rst +++ b/doc/sphinx/arm/config.rst @@ -112,6 +112,83 @@ and Logging) 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 +------------------------- + +You can specify shell, C or C++ style comments in the JSON configuration file if +you use the file locally. This is convenient and works in simple cases where +your configuration is kept statically using local file. However, since comments +are not part of JSON syntax, most JSON tools will detect them as +errors. Another problem with them is once Kea loads its configuration, the +shell, C and C++ style comments are ignored. If you use commands such as +`config-get` or `config-write`, those comments will be lost. An example of such +comments has been presented in the previous section. + +Historically, to address the problem Kea code allowed to put `comment` strings +as valid JSON entities. This had the benefit of being retained through various +operations (such as `config-get`) or allowed 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, users complained that the comment is only a single line and it's not +possible to add any other information in more structured form. 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 has been introduced. It +allows adding arbitrary JSON structure to most Kea configuration structures. It +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 if you want to, but it can store much more complex data, such as +multiple lines (as string array), extra typed data (such as floor numbers being +actual numbers) and more. Third, the data is exposed to hooks, so it's possible +to develop third party hooks that take advantage of that extra information. An +example user context would look 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 superseeded the JSON comment +capabilities. ISC would like to encourage people to use user-context in favor of +the older mechanisms and we hope to deprecate JSON comments one day in the +future. To promote this way of storing comments, Kea code is able to undestand +JSON comments, but converts them to user context on the fly. + +The is one side effect, however. If your configuration uses the old JSON +comment, the `config-get` command will return a slightly modified +configuration. Don't be surpised if you call `config-set` followed by a +`config-get` and receive a slightly different value. If this bothers you, the +best way to avoid this problem is simply abandon JSON comments and start using +user-context. + +For a discussion about user context used in hooks, see :ref:`user-context-hooks`. + + Simplified Notation ------------------- diff --git a/doc/sphinx/arm/ddns.rst b/doc/sphinx/arm/ddns.rst index 1858090d55..e63badf53d 100644 --- a/doc/sphinx/arm/ddns.rst +++ b/doc/sphinx/arm/ddns.rst @@ -669,9 +669,8 @@ User Contexts in DDNS User contexts were designed for hook libraries, which are not yet supported for DHCP-DDNS server configuration. -User contexts can store arbitrary data as long as the file has valid JSON -syntax and the top-level element is a map (i.e. the data must be -enclosed in curly brackets). +See :ref:`user-context` for additional background regarding the user +context idea. User contexts can be specified on global scope, DDNS domain, DNS server, TSIG key, and loggers. One other useful usage is the ability to store diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst index d3e5146d0e..e32495a39e 100644 --- a/doc/sphinx/arm/dhcp4-srv.rst +++ b/doc/sphinx/arm/dhcp4-srv.rst @@ -5600,11 +5600,9 @@ library, it is typically defined as a parameter for the hook library. However, sometimes there is a need to specify parameters that are different for each pool. -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. +See :ref:`user-context` for additional background regarding the user +context idea. See :ref:`user-context-hooks` for a discussion from the +hooks perspective. User contexts can be specified at global scope, shared network, subnet, pool, client class, option data, or definition level, and via host @@ -5650,8 +5648,6 @@ extract that information and use it. The parser translates a "comment" entry into a user context with the entry, which allows a comment to be attached inside the configuration itself. -For more background information, see :ref:`user-context`. - .. _dhcp4-std: Supported DHCP Standards diff --git a/doc/sphinx/arm/dhcp6-srv.rst b/doc/sphinx/arm/dhcp6-srv.rst index fc86f09fe1..b9c0ef1a2f 100644 --- a/doc/sphinx/arm/dhcp6-srv.rst +++ b/doc/sphinx/arm/dhcp6-srv.rst @@ -5578,11 +5578,9 @@ library, it is typically defined as a parameter for the hook library. However, sometimes there is a need to specify parameters that are different for each pool. -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. +See :ref:`user-context` for additional background regarding the user +context idea. See :ref:`user-context-hooks` for a discussion from the +hooks perspective. User contexts can be specified at global scope, shared network, subnet, pool, client class, option data, or definition level, and via host @@ -5644,8 +5642,6 @@ hook library to extract that information and use it. The parser translates a "comment" entry into a user context with the entry, which allows a comment to be attached inside the configuration itself. -For more background information, see :ref:`user-context`. - .. _dhcp6-std: Supported DHCPv6 Standards diff --git a/doc/sphinx/arm/hooks-radius.rst b/doc/sphinx/arm/hooks-radius.rst index db5cdc1fe6..2d72600d36 100644 --- a/doc/sphinx/arm/hooks-radius.rst +++ b/doc/sphinx/arm/hooks-radius.rst @@ -536,8 +536,8 @@ received during the initial Discover/Offer exchanges and use it again later when sending accounting messages. This mechanism is implemented based on user context in host -reservations. (See :ref:`user-context` for details.) -The host cache mechanism allows the information retrieved by +reservations. (See :ref:`user-context` and :ref:`user-context-hooks` for +details.) The host cache mechanism allows the information retrieved by RADIUS to be stored and later used for sending accounting and access queries to the RADIUS server. In other words, the host-cache mechanism is mandatory, unless administrators do not want RADIUS communication for messages diff --git a/doc/sphinx/arm/hooks.rst b/doc/sphinx/arm/hooks.rst index 084d08cc98..dac8792a47 100644 --- a/doc/sphinx/arm/hooks.rst +++ b/doc/sphinx/arm/hooks.rst @@ -2813,10 +2813,10 @@ both the command and the response. .. include:: hooks-host-cache.rst -.. _user-context: +.. _user-context-hooks: -User Contexts -============= +User Contexts in Hooks +====================== Hooks libraries can have their own configuration parameters, which is convenient if the parameter applies to the whole library. However,