Commit a3ca4ab1 authored by Francis Dupont's avatar Francis Dupont

[5036] Improved dhcp6.dox

parent 58e7eba1
...@@ -72,7 +72,7 @@ general, the following issues of the existing code were noted: ...@@ -72,7 +72,7 @@ general, the following issues of the existing code were noted:
no-op operation. no-op operation.
-# There is no way to generate a list of all directives. We do have .spec files, -# There is no way to generate a list of all directives. We do have .spec files,
but they're not actually used by the code. The code has the directives but they're not actually used by the code. The code has the directives
spread out in multiple places in multiple files in mutliple directories. spread out in multiple places in multiple files in multiple directories.
Answering a simple question ("can I do X in the scope Y?") requires Answering a simple question ("can I do X in the scope Y?") requires
a short session of reverse engineering. What's worse, we have the .spec a short session of reverse engineering. What's worse, we have the .spec
files that are kinda kept up to date. This is actually more damaging that files that are kinda kept up to date. This is actually more damaging that
...@@ -127,13 +127,13 @@ PHASE 2: simplify existing parsers by getting rid of the build/commit split. ...@@ -127,13 +127,13 @@ PHASE 2: simplify existing parsers by getting rid of the build/commit split.
from the existing parsers and implemented in the bison parser. from the existing parsers and implemented in the bison parser.
It should return extra JSON elements. The details are TBD, but there is It should return extra JSON elements. The details are TBD, but there is
one example for setting up an renew-timer value on the subnet level that one example for setting up an renew-timer value on the subnet level that
is ihnerited from the global ("Dhcp6") level. This phase is covered by is inherited from the global ("Dhcp6") level. This phase is covered by
ticket 5039. ticket 5039.
The code change for 5036 introduces bison based parser. It is The code change for 5036 introduces flex/bison based parser. It is
essentially defined in two files: dhcp6_lexer.ll, which defines essentially defined in two files: dhcp6_lexer.ll, which defines
regular expressions that are used on the input (be it a file or a regular expressions that are used on the input (be it a file or a
string in memory). In essence, this code is being called repetively string in memory). In essence, this code is being called repeatedly
and each time it returns a token. This repeats until either the and each time it returns a token. This repeats until either the
parsing is complete or syntax error is encountered. For example, for parsing is complete or syntax error is encountered. For example, for
the following text: the following text:
...@@ -147,8 +147,8 @@ the following text: ...@@ -147,8 +147,8 @@ the following text:
} }
@endcode @endcode
this code would return the following sentence of tokens: LCURLY_BRACKET, this code would return the following sentence of tokens: LCURLY_BRACKET,
DHCP6, LCURLY_BRACKET, COLON, LCURLY_BRACKET, RENEW_TIMER, COLON, DHCP6, COLON, LCURLY_BRACKET, RENEW_TIMER, COLON, INTEGER
INTEGER(a token with a value of 100), RCURLY_BRACKET, RCURLY_BRACKET, END (a token with a value of 100), RCURLY_BRACKET, RCURLY_BRACKET, END
This stream of tokens is being consumed by the parser that is defined This stream of tokens is being consumed by the parser that is defined
in dhcp6_parser.yy. This file defines a grammar. Here's very simplified in dhcp6_parser.yy. This file defines a grammar. Here's very simplified
...@@ -158,29 +158,29 @@ version of the Dhcp6 grammar: ...@@ -158,29 +158,29 @@ version of the Dhcp6 grammar:
dhcp6_object: DHCP6 COLON LCURLY_BRACKET global_params RCURLY_BRACKET; dhcp6_object: DHCP6 COLON LCURLY_BRACKET global_params RCURLY_BRACKET;
global_params: global_param global_params: global_param
| global_params COMMA global_param; | global_params COMMA global_param
;
// These are the parameters that are allowed in the top-level for // These are the parameters that are allowed in the top-level for
// Dhcp6. // Dhcp6.
global_param global_param: preferred_lifetime
: preferred_lifetime | valid_lifetime
| valid_lifetime | renew_timer
| renew_timer | rebind_timer
| rebind_timer | subnet6_list
| subnet6_list | interfaces_config
| interfaces_config | lease_database
| lease_database | hosts_database
| hosts_database | mac_sources
| mac_sources | relay_supplied_options
| relay_supplied_options | host_reservation_identifiers
| host_reservation_identifiers | client_classes
| client_classes | option_data_list
| option_data_list | hooks_libraries
| hooks_libraries | expired_leases_processing
| expired_leases_processing | server_id
| server_id | dhcp4o6_port
| dhcp4o6_port ;
;
renew_timer: RENEW_TIMER COLON INTEGER; renew_timer: RENEW_TIMER COLON INTEGER;
@endcode @endcode
...@@ -190,16 +190,16 @@ to the notation, it's very powerful and easy to extend. The first line defines ...@@ -190,16 +190,16 @@ to the notation, it's very powerful and easy to extend. The first line defines
that dhcp6_object consists of certain tokens (DHCP6, COLON and LCURLY_BRACKET) that dhcp6_object consists of certain tokens (DHCP6, COLON and LCURLY_BRACKET)
followed by 'global_params' expression, followed by RCURLY_BRACKET. followed by 'global_params' expression, followed by RCURLY_BRACKET.
The 'global_params' is defined recursively. It can either be a single 'global_param' The 'global_params' is defined recursively. It can either be a single
expression, or (a shorter) global_params followed by a comma and global_param. 'global_param' expression, or (a shorter) global_params followed by a
Bison will apply this and will be able to parse comma separated lists of comma and global_param. Bison will apply this and will be able to
arbitrary lengths. parse comma separated lists of arbitrary lengths.
A single parameter is defined by 'global_param' expression. This represents A single parameter is defined by 'global_param' expression. This
any paramter that may appear in the global scope of Dhcp6 object. The represents any parameter that may appear in the global scope of Dhcp6
complete definition for all of them is complex, but the example above includes object. The complete definition for all of them is complex, but the
renew_timer definition. It is defined as a series of RENEW_TIMER, COLON, INTEGER example above includes renew_timer definition. It is defined as a
tokens. series of RENEW_TIMER, COLON, INTEGER tokens.
The above is a simplified version of the actual grammar. If used in the version The above is a simplified version of the actual grammar. If used in the version
above, it would parse the whole file, but would do nothing with that information. above, it would parse the whole file, but would do nothing with that information.
...@@ -237,10 +237,10 @@ is removed from the stack. At the end of parsing, there should be a single ...@@ -237,10 +237,10 @@ is removed from the stack. At the end of parsing, there should be a single
element on the stack as the top-level parsing (syntax_map) only inserts the element on the stack as the top-level parsing (syntax_map) only inserts the
MapElement object, but does not remove it. MapElement object, but does not remove it.
@section dhcpv6ConfigSubParser Parsing Partial Configuation in DHCPv6 @section dhcpv6ConfigSubParser Parsing Partial Configuration in DHCPv6
One another important capability required is the ability to parse not only the One another important capability required is the ability to parse not only the
whole configuration, but a subset of it. This is done by introducing articifical whole configuration, but a subset of it. This is done by introducing artificial
tokens (e.g. TOPLEVEL_JSON and TOPLEVEL_DHCP6). For complete list of available 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
...@@ -251,15 +251,17 @@ For example, to add the ability to parse only pools, the following could be adde ...@@ -251,15 +251,17 @@ For example, to add the ability to parse only pools, the following could be adde
@code @code
start: TOPLEVEL_GENERIC_JSON sub_json start: TOPLEVEL_GENERIC_JSON sub_json
| TOPLEVEL_DHCP6 sub_dhcp6 | TOPLEVEL_DHCP6 sub_dhcp6
| TOPLEVEL_POOL6 sub_pool6; | TOPLEVEL_POOL6 sub_pool6
;
@endcode @endcode
The code on trac5036 branch contains the code defintion and the Kea-dhcp6 updated The code on trac5036 branch contains the code definition and the
to use that new parser. I'm sure that parser does not cover 100% of all parameters, Kea-dhcp6 updated to use that new parser. I'm sure that parser does
but so far it is able to load all examples from doc/example/kea6. It is also not cover 100% of all parameters, but so far it is able to load all
able to parser # comments (bash style, starting at the beginning or middle of examples from doc/example/kea6. It is also able to parser # comments
the line), // comments (C++ style, can start anywhere) or / * * / comments (C style, (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). can span multiple lines).
This parser is currently used. See configure() method in kea_controller.cc. This parser is currently used. See configure() method in kea_controller.cc.
...@@ -293,11 +295,12 @@ To include one file from another, user the following syntax: ...@@ -293,11 +295,12 @@ To include one file from another, user the following syntax:
} }
@endcode @endcode
The inclusion is implemented as a stack of files. Typically, when a single The inclusion is implemented as a stack of files. Typically, when a
file is parsed, the files_ (a vector of strings) and sfiles_ (a vector of FILE*) single file is parsed, the files_ (a vector of strings) and sfiles_ (a
both contain a single entry. However, when lexer detects <?include "filename.json?>, vector of FILE*) both contain a single entry. However, when lexer
it calls @ref isc::dhcp::Parser6Context::includeFile method. Up to ten detects <?include "filename.json?>, it calls
nesting levels are supported. This arbitrarily chosen limit is a protection @ref isc::dhcp::Parser6Context::includeFile method. Up to ten nesting
levels are supported. This arbitrarily chosen limit is a protection
against recursive inclusions. against recursive inclusions.
@section dhcp6ParserConflicts Avoiding syntactical conflicts in parsers @section dhcp6ParserConflicts Avoiding syntactical conflicts in parsers
...@@ -307,7 +310,6 @@ check if it's a valid JSON syntax, but also check that the resulting structures ...@@ -307,7 +310,6 @@ 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 JSON.
For example, if we're in Dhcp6 and the config contains entries for DhcpDdns 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 or Dhcp4. If we were to use naive approach, the lexer would go through
...@@ -320,7 +322,9 @@ type of content is expected. For example, when Dhcp6 parser discovers ...@@ -320,7 +322,9 @@ 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. 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.
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.
......
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