<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>
<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 (#)
# The whole configuration structure ends here.
}
</screen>
- </para>
+ </para>
<para>More examples are available in the installed
<filename>share/doc/kea/examples</filename> directory.</para>
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.</para>
-
+
<!-- @todo Add a reference here after #3422 is done -->
</section>
<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
<!ENTITY mdash "—" >
]>
- <chapter id="dhcp6">
+ <chapter id="dhcp6">
<title>The DHCPv6 Server</title>
<section id="dhcp6-start-stop">
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>,
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
</simpara>
</listitem>
</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 id="dhcp6-decline">
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
;
@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
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.
/// @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);
projects / thirdparty / kea.git / commitdiff
