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 @@ ...@@ -6,15 +6,18 @@
<chapter id="kea-config"> <chapter id="kea-config">
<title>Kea Configuration</title> <title>Kea Configuration</title>
<para>Kea is designed to allow different methods by which it can be <para>Kea is using JSON structures to handle configuration. Previously
configured, each method being implemented by a component known as a we there was a concept of other configuration backends, but that never was
configuration backend. At present, only one such backend is implemented and the idea was abandoned.</para>
available, that allowing configuration by means of a JSON file.</para>
<section id="json">
<section id="json-backend"> <title>JSON Configuration</title>
<title>JSON Configuration Backend</title> <para>JSON is notation used throughout the Kea project. The most obvious
<para>JSON is the default configuration backend. usage is for configuration file, but it is also used for sending commands
It assumes that the servers are started from the command line 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>). (either directly or using a script, e.g. <filename>keactrl</filename>).
The JSON backend uses certain signals to influence Kea. The The JSON backend uses certain signals to influence Kea. The
configuration file is specified upon startup using the -c parameter.</para> configuration file is specified upon startup using the -c parameter.</para>
...@@ -23,9 +26,14 @@ ...@@ -23,9 +26,14 @@
<title>JSON Syntax</title> <title>JSON Syntax</title>
<para>Configuration files for DHCPv4, DHCPv6 and DDNS modules are defined <para>Configuration files for DHCPv4, DHCPv6 and DDNS modules are defined
in an extended JSON format. Basic JSON is defined in <ulink in an extended JSON format. Basic JSON is defined in <ulink
url="http://tools.ietf.org/html/rfc4627">RFC 4627</ulink>. Kea components url="http://tools.ietf.org/html/rfc7159">RFC 7159</ulink>. Note that Kea
use an extended JSON with additional features allowed: 1.2 introduces a new parser that is better at following the JSON spec. In
in that they allow shell-style 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> <itemizedlist>
<listitem> <listitem>
<simpara>shell comments: any text after the hash (#) <simpara>shell comments: any text after the hash (#)
...@@ -116,7 +124,7 @@ ...@@ -116,7 +124,7 @@
# The whole configuration structure ends here. # The whole configuration structure ends here.
} }
</screen> </screen>
</para> </para>
<para>More examples are available in the installed <para>More examples are available in the installed
<filename>share/doc/kea/examples</filename> directory.</para> <filename>share/doc/kea/examples</filename> directory.</para>
...@@ -140,7 +148,7 @@ ...@@ -140,7 +148,7 @@
valid-lifetime in the Dhcp6 component can be referred to as 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 Dhcp6/valid-lifetime and the pool in the first subnet defined in the DHCPv6
configuration as Dhcp6/subnet6[0]/pool.</para> configuration as Dhcp6/subnet6[0]/pool.</para>
<!-- @todo Add a reference here after #3422 is done --> <!-- @todo Add a reference here after #3422 is done -->
</section> </section>
......
...@@ -2978,7 +2978,7 @@ It is merely echoed by the server ...@@ -2978,7 +2978,7 @@ It is merely echoed by the server
<para> <para>
It is possible to store host reservations in MySQL or PostgreSQL database. See 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 reservations stored in MySQL or PostgreSQL. Kea does not provide any dedicated
tools for managing reservations in a database. The Kea wiki <ulink tools for managing reservations in a database. The Kea wiki <ulink
url="http://kea.isc.org/wiki/HostReservationsHowTo" /> provides detailed url="http://kea.isc.org/wiki/HostReservationsHowTo" /> provides detailed
......
...@@ -4,7 +4,7 @@ ...@@ -4,7 +4,7 @@
<!ENTITY mdash "&#x2014;" > <!ENTITY mdash "&#x2014;" >
]> ]>
<chapter id="dhcp6"> <chapter id="dhcp6">
<title>The DHCPv6 Server</title> <title>The DHCPv6 Server</title>
<section id="dhcp6-start-stop"> <section id="dhcp6-start-stop">
...@@ -3496,7 +3496,8 @@ If not specified, the default value is: ...@@ -3496,7 +3496,8 @@ If not specified, the default value is:
provided by the clients. provided by the clients.
</para> </para>
<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> <screen>
"Dhcp6": { "Dhcp6": {
<userinput>"mac-sources": [ "method1", "method2", "method3", ... ]</userinput>, <userinput>"mac-sources": [ "method1", "method2", "method3", ... ]</userinput>,
...@@ -3543,7 +3544,7 @@ If not specified, the default value is: ...@@ -3543,7 +3544,7 @@ If not specified, the default value is:
that those addresses are based on EUI-64, which contains MAC address. This 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 method is not completely reliable, as clients may use other link-local address
types. In particular, privacy extensions, defined in 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 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 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 is an interface identifier as per
...@@ -3600,7 +3601,11 @@ If not specified, the default value is: ...@@ -3600,7 +3601,11 @@ If not specified, the default value is:
</simpara> </simpara>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </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>
<section id="dhcp6-decline"> <section id="dhcp6-decline">
......
...@@ -245,8 +245,9 @@ tokens (e.g. TOPLEVEL_JSON and TOPLEVEL_DHCP6). For complete list of available ...@@ -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 starting contexts, see @ref isc::dhcp::Parser6Context::ParserType. The
Parse6Context::parse() method takes one parameter that specifies, whether 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 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 (DHCP6). This feature is currently mostly used by unit-tests (which often skip
to parse only subnets, host reservations, options or basically any other elements. 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: For example, to add the ability to parse only pools, the following could be added:
@code @code
...@@ -256,15 +257,15 @@ start: TOPLEVEL_GENERIC_JSON sub_json ...@@ -256,15 +257,15 @@ start: TOPLEVEL_GENERIC_JSON sub_json
; ;
@endcode @endcode
The code on trac5036 branch contains the code definition and the The parser code contains the code definition and the Kea-dhcp6 updated
Kea-dhcp6 updated to use that new parser. I'm sure that parser does to use that new parser. That parser is able to to load all examples
not cover 100% of all parameters, but so far it is able to load all from doc/example/kea6. It is also able to parser # comments (bash
examples from doc/example/kea6. It is also able to parser # comments style, starting at the beginning or middle of the line), // comments
(bash style, starting at the beginning or middle of the line), // (C++ style, can start anywhere) or / * * / comments (C style, can span
comments (C++ style, can start anywhere) or / * * / comments (C style, multiple lines).
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 There are several new unit-tests written, but the code mostly reuses existing
one to verify that existing functionality was not compromised. There are 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 ...@@ -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 match expected syntax (if subnet6 are really an array, not a map, if
timers are expressed as integers, not as strings etc.). timers are expressed as integers, not as strings etc.).
However, there are times when we need to parse a string as arbitrary JSON. However, there are times when we need to parse a string as arbitrary
For example, if we're in Dhcp6 and the config contains entries for DhcpDdns JSON. For example, if we're in Dhcp6 and the config contains entries
or Dhcp4. If we were to use naive approach, the lexer would go through for DhcpDdns or Dhcp4. If we were to use naive approach, the lexer
that content and most likely find some tokens that are also used in Dhcp6. would go through that content and most likely find some tokens that
for example 'renew-timer' would be detected and the parser would complain are also used in Dhcp6. for example 'renew-timer' would be detected
that it was not expected. To avoid this problem, parser context was and the parser would complain that it was not expected. To avoid this
introduced. When the syntactic parser expects certain type of content, problem, syntactic context was introduced. When the syntactic parser
it calls @ref isc::dhcp::Parser6Context::enter() method to indicate what expects certain type of content, it calls @ref
type of content is expected. For example, when Dhcp6 parser discovers 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 uninteresting content like Dhcp4, it enters NO_KEYWORD mode. In this
mode, everything is parsed as generic maps, lists, integers, booleans mode, everything is parsed as generic maps, lists, integers, booleans
or strings. This results in generic JSON structures without any syntax or strings. This results in generic JSON structures without any syntax
checking. Of course a corresponding/balanced @ref checking. A corresponding/balanced @ref
isc::dhcp::Parser6Context::leave() call is required before leaving isc::dhcp::Parser6Context::leave() call is required before leaving the
the context to come back to the previous context. 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 Details of the refactor of the classes derived from DhcpConfigParser are
documented in http://kea.isc.org/wiki/SimpleParser. documented in http://kea.isc.org/wiki/SimpleParser.
......
...@@ -286,13 +286,14 @@ public: ...@@ -286,13 +286,14 @@ public:
/// @brief Enter a new syntactic context /// @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 /// First, it allows the parser to avoid conflicts. Second, it
/// allows the lexer to return different tokens depending on /// allows the lexer to return different tokens depending on
/// context (e.g. if "renew-timer" string is detected, the lexer /// context (e.g. if "renew-timer" string is detected, the lexer
/// will return STRING token if in JSON mode or RENEW_TIMER if /// will return STRING token if in JSON mode or RENEW_TIMER if
/// in DHCP6 mode. Finally, the stntactic context allows the /// in DHCP6 mode. Finally, the syntactic context allows the
/// error message to be more descriptive. /// error message to be more descriptive if the input string
/// does not parse properly.
/// ///
/// @param ctx the syntactic context to enter into /// @param ctx the syntactic context to enter into
void enter(const ParserContext& ctx); 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