From 5b7aaae74dfc1a27de645cc2d82d5f1cfc848509 Mon Sep 17 00:00:00 2001 From: Tomek Mrugalski Date: Mon, 12 Dec 2016 14:59:57 +0100 Subject: [PATCH] [5036] Changes after review: - clarified JSON usage in admin guide (True/False not allowed) - fixed incorrect reference to hosts4-storage - clarified that empty mac-sources entry is not allowed - added extra text about syntactic contexts - corrected several typos --- doc/guide/config.xml | 36 ++++++++++++++--------- doc/guide/dhcp4-srv.xml | 2 +- doc/guide/dhcp6-srv.xml | 13 ++++++--- src/bin/dhcp6/dhcp6.dox | 53 ++++++++++++++++++++-------------- src/bin/dhcp6/parser_context.h | 7 +++-- 5 files changed, 67 insertions(+), 44 deletions(-) diff --git a/doc/guide/config.xml b/doc/guide/config.xml index 8c98c9508a..d2f81f48d9 100644 --- a/doc/guide/config.xml +++ b/doc/guide/config.xml @@ -6,15 +6,18 @@ Kea Configuration - Kea is designed to allow different methods by which it can be - configured, each method being implemented by a component known as a - configuration backend. At present, only one such backend is - available, that allowing configuration by means of a JSON file. - -
- JSON Configuration Backend - JSON is the default configuration backend. - It assumes that the servers are started from the command line + Kea is using JSON structures to handle configuration. Previously + we there was a concept of other configuration backends, but that never was + implemented and the idea was abandoned. + +
+ JSON Configuration + JSON is notation used throughout the Kea project. The most obvious + usage is for configuration file, but it is also used for sending commands + over Management API (see ) and for + communicating between DHCP servers and DDNS update daemon. + + Typical usage assumes that the servers are started from the command line (either directly or using a script, e.g. keactrl). The JSON backend uses certain signals to influence Kea. The configuration file is specified upon startup using the -c parameter. @@ -23,9 +26,14 @@ JSON Syntax Configuration files for DHCPv4, DHCPv6 and DDNS modules are defined in an extended JSON format. Basic JSON is defined in RFC 4627. Kea components - use an extended JSON with additional features allowed: - in that they allow shell-style + url="http://tools.ietf.org/html/rfc7159">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. + + + Kea components use an extended JSON with additional features + allowed: shell comments: any text after the hash (#) @@ -116,7 +124,7 @@ # The whole configuration structure ends here. } - + More examples are available in the installed share/doc/kea/examples directory. @@ -140,7 +148,7 @@ 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. - +
diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index 4c7c3efa4c..c2798e7a02 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -2978,7 +2978,7 @@ It is merely echoed by the server It is possible to store host reservations in MySQL or PostgreSQL database. See - for information on how to configure Kea to use + for information on how to configure Kea to use reservations stored in MySQL or PostgreSQL. Kea does not provide any dedicated tools for managing reservations in a database. The Kea wiki provides detailed diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index 8fb04a40d1..9c7ca469ce 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -4,7 +4,7 @@ ]> - + The DHCPv6 Server
@@ -3496,7 +3496,8 @@ If not specified, the default value is: provided by the clients. - The configuration is controlled by the mac-sourcesparameter as follows: + The configuration is controlled by the mac-sources + parameter as follows: "Dhcp6": { "mac-sources": [ "method1", "method2", "method3", ... ], @@ -3543,7 +3544,7 @@ If not specified, the default value is: that those addresses are based on EUI-64, which contains MAC address. This method is not completely reliable, as clients may use other link-local address types. In particular, privacy extensions, defined in - RFC 4941, do not use + RFC 4941, do not use MAC addresses. Also note that successful extraction requires that the address's u-bit must be set to 1 and its g-bit set to 0, indicating that it is an interface identifier as per @@ -3600,7 +3601,11 @@ If not specified, the default value is: - + + + Empty mac-sources is not allowed. If you do not want to specify it, + either simply omit mac-sources definition or specify it with the "any" value + which is the default.
diff --git a/src/bin/dhcp6/dhcp6.dox b/src/bin/dhcp6/dhcp6.dox index 19c18ae06b..fc13d5befb 100644 --- a/src/bin/dhcp6/dhcp6.dox +++ b/src/bin/dhcp6/dhcp6.dox @@ -245,8 +245,9 @@ tokens (e.g. TOPLEVEL_JSON and TOPLEVEL_DHCP6). For complete list of available starting contexts, see @ref isc::dhcp::Parser6Context::ParserType. The Parse6Context::parse() method takes one parameter that specifies, whether the data to be parsed is expected to have a generic JSON or the whole configuration -(DHCP6). This is only a proof-of-concept, but similar approach can be implemented -to parse only subnets, host reservations, options or basically any other elements. +(DHCP6). This feature is currently mostly used by unit-tests (which often skip +the '{ "Dhcp6": {' preamble), but it is expected to be soon used for parsing +subnets only, host reservations only, options or basically any other elements. For example, to add the ability to parse only pools, the following could be added: @code @@ -256,15 +257,15 @@ start: TOPLEVEL_GENERIC_JSON sub_json ; @endcode -The code on trac5036 branch contains the code definition and the -Kea-dhcp6 updated to use that new parser. I'm sure that parser does -not cover 100% of all parameters, but so far it is able to load all -examples from doc/example/kea6. It is also able to parser # comments -(bash style, starting at the beginning or middle of the line), // -comments (C++ style, can start anywhere) or / * * / comments (C style, -can span multiple lines). +The parser code contains the code definition and the Kea-dhcp6 updated +to use that new parser. That parser is able to to load all examples +from doc/example/kea6. It is also able to parser # comments (bash +style, starting at the beginning or middle of the line), // comments +(C++ style, can start anywhere) or / * * / comments (C style, can span +multiple lines). -This parser is currently used. See configure() method in kea_controller.cc. +This parser is currently used in production code. See configure() +method in kea_controller.cc. There are several new unit-tests written, but the code mostly reuses existing one to verify that existing functionality was not compromised. There are @@ -310,21 +311,29 @@ check if it's a valid JSON syntax, but also check that the resulting structures match expected syntax (if subnet6 are really an array, not a map, if timers are expressed as integers, not as strings etc.). -However, there are times when we need to parse a string as arbitrary JSON. -For example, if we're in Dhcp6 and the config contains entries for DhcpDdns -or Dhcp4. If we were to use naive approach, the lexer would go through -that content and most likely find some tokens that are also used in Dhcp6. -for example 'renew-timer' would be detected and the parser would complain -that it was not expected. To avoid this problem, parser context was -introduced. When the syntactic parser expects certain type of content, -it calls @ref isc::dhcp::Parser6Context::enter() method to indicate what -type of content is expected. For example, when Dhcp6 parser discovers +However, there are times when we need to parse a string as arbitrary +JSON. For example, if we're in Dhcp6 and the config contains entries +for DhcpDdns or Dhcp4. If we were to use naive approach, the lexer +would go through that content and most likely find some tokens that +are also used in Dhcp6. for example 'renew-timer' would be detected +and the parser would complain that it was not expected. To avoid this +problem, syntactic context was introduced. When the syntactic parser +expects certain type of content, it calls @ref +isc::dhcp::Parser6Context::enter() method to indicate what type of +content is expected. For example, when Dhcp6 parser discovers uninteresting content like Dhcp4, it enters NO_KEYWORD mode. In this mode, everything is parsed as generic maps, lists, integers, booleans or strings. This results in generic JSON structures without any syntax -checking. Of course a corresponding/balanced @ref -isc::dhcp::Parser6Context::leave() call is required before leaving -the context to come back to the previous context. +checking. A corresponding/balanced @ref +isc::dhcp::Parser6Context::leave() call is required before leaving the +context to come back to the previous context. + +Entering a new syntactic context is useful in several ways. First, it allows +the parser to avoid conflicts. Second, it allows the lexer to return different +tokens depending on context (e.g. if "renew-timer" string is detected, the lexer +will return STRING token if in JSON mode or RENEW_TIMER if in DHCP6 +mode). Finally, the syntactic context allows the error message to be more +descriptive if the input string does not parse properly. Details of the refactor of the classes derived from DhcpConfigParser are documented in http://kea.isc.org/wiki/SimpleParser. diff --git a/src/bin/dhcp6/parser_context.h b/src/bin/dhcp6/parser_context.h index ae6610fdbe..24ee963d70 100644 --- a/src/bin/dhcp6/parser_context.h +++ b/src/bin/dhcp6/parser_context.h @@ -286,13 +286,14 @@ public: /// @brief Enter a new syntactic context /// - /// Entering a nex syntactic context is useful in several ways. + /// Entering a new syntactic context is useful in several ways. /// First, it allows the parser to avoid conflicts. Second, it /// allows the lexer to return different tokens depending on /// context (e.g. if "renew-timer" string is detected, the lexer /// will return STRING token if in JSON mode or RENEW_TIMER if - /// in DHCP6 mode. Finally, the stntactic context allows the - /// error message to be more descriptive. + /// in DHCP6 mode. Finally, the syntactic context allows the + /// error message to be more descriptive if the input string + /// does not parse properly. /// /// @param ctx the syntactic context to enter into void enter(const ParserContext& ctx); -- 2.47.3