Commit 5b7aaae7 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰

[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
parent af79ebab
......@@ -6,15 +6,18 @@
<chapter id="kea-config">
<title>Kea Configuration</title>
<para>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.</para>
<section id="json-backend">
<title>JSON Configuration Backend</title>
<para>JSON is the default configuration backend.
It assumes that the servers are started from the command line
<para>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.</para>
<section id="json">
<title>JSON Configuration</title>
<para>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 <xref linkend="ctrl-channel"/>) and for
communicating between DHCP servers and DDNS update daemon.</para>
<para>Typical usage assumes that the servers are started from the command line
(either directly or using a script, e.g. <filename>keactrl</filename>).
The JSON backend uses certain signals to influence Kea. The
configuration file is specified upon startup using the -c parameter.</para>
......@@ -23,9 +26,14 @@
<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 <ulink
url="http://tools.ietf.org/html/rfc4627">RFC 4627</ulink>. 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</ulink>. 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
allowed:
<itemizedlist>
<listitem>
<simpara>shell comments: any text after the hash (#)
......
......@@ -2978,7 +2978,7 @@ It is merely echoed by the server
<para>
It is possible to store host reservations in MySQL or PostgreSQL database. See
<xref linkend="hosts-storage4"/> for information on how to configure Kea to use
<xref linkend="hosts4-storage"/> 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 <ulink
url="http://kea.isc.org/wiki/HostReservationsHowTo" /> provides detailed
......
......@@ -3496,7 +3496,8 @@ If not specified, the default value is:
provided by the clients.
</para>
<para>
The configuration is controlled by the <command>mac-sources</command>parameter as follows:
The configuration is controlled by the <command>mac-sources</command>
parameter as follows:
<screen>
"Dhcp6": {
<userinput>"mac-sources": [ "method1", "method2", "method3", ... ]</userinput>,
......@@ -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
<ulink utl="http://tools.ietf.org/html/rfc4941">RFC 4941</ulink>, do not use
<ulink url="http://tools.ietf.org/html/rfc4941">RFC 4941</ulink>, 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
......@@ -3601,6 +3602,10 @@ If not specified, the default value is:
</listitem>
</itemizedlist>
</para>
<para>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.</para>
</section>
<section id="dhcp6-decline">
......
......@@ -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.
......
......@@ -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);
......
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