[master] Merge branch 'trac4102' (Dev guide updated with client classification)

configure.ac

@@ -1579,9 +1579,6 @@ Log4cplus:
   LOG4CPLUS_INCLUDES: ${LOG4CPLUS_INCLUDES}
   LOG4CPLUS_LIBS:  ${LOG4CPLUS_LIBS}
 
-Kea config backend:
-  CONFIG_BACKEND:  ${CONFIG_BACKEND}
-
 Flex/bison:
   FLEX:  ${LEX}
   BISON: ${YACC}
@@ -1635,9 +1632,6 @@ fi
 
 cat >> config.report << END
 
-Features:
-  $enable_features
-
 Developer:
   Enable Debugging: $debug_enabled
   Google Tests: $enable_gtest

doc/guide/classify.xml

@@ -19,7 +19,7 @@
       </para></listitem>
       <listitem><para>
       The clients have different behavior, e.g.a smart phone behaves
-      differently to a lapttop.
+      differently to a laptop.
       </para></listitem>
       <listitem><para>
       The clients require different values for some options, e.g. a docsis3.0

src/bin/dhcp4/dhcp4.dox

@@ -207,10 +207,16 @@ these constants will be removed.
 
 @section dhcpv4Classifier DHCPv4 Client Classification
 
-The Kea DHCPv4 server currently supports simplified client classification. It is called
+The Kea DHCPv4 currently supports two classification modes: simplified client
+classification (that was an early implementation that used values of vendor class option)
+and full client classification.
+
+@subsection dhcpv4ClassifierSimple Simple Client Classification in DHCPv4
+
+The Kea DHCPv4 server supports simplified client classification. It is called
 "simplified", because the incoming packets are classified based on the content
-of the vendor class (60) option. More flexible classification is planned, but there
-are no specific development dates agreed.
+of the vendor class (60) option. More flexible classification was added in 1.0
+and is described in @ref dhcpv4ClassifierFull .
 
 For each incoming packet, @ref isc::dhcp::Dhcpv4Srv::classifyPacket() method is called.
 It attempts to extract content of the vendor class option and interpret as a name
@@ -225,48 +231,59 @@ Nevertheless, there is such a possibility and it will be used in a near future.
 check whether a packet belongs to given class, isc::dhcp::Pkt4::inClass method should
 be used.
 
+The code sometimes refers to this classification as "simple" or 'built-in", because
+it does not require any configuration and thus is built into the server logic.
+
+@subsection dhcpv4ClassifierFull Full Client Classification in DHCPv4
+
+Kea 1.0 introduced full client classification. Each client class consists of a name
+and an expression that can be evaluated on an incoming packet. If it evaluates to
+true, this packet is considered a member of said class. Class definitions are stored
+in isc::dhcp::ClientClassDef objects that are kept in isc::dhcp::ClientClassDictionary.
+This is convenient as there are often multiple classes associated with a given scope.
+As of Kea 1.0, the only supported scope is global, but there are plans to support
+class definitions that are subnet specific.
+
+Client classification is done in isc::dhcp::Dhcpv4Srv::classifyPacket. First, the old
+"built-in" (see @ref dhcpv4ClassifierSimple) classification is called. Then the code
+iterates over all class definitions and for each class definition it calls
+isc::dhcp::evaluate, which is implemented in libeval (see @ref dhcpEval). If the
+evaluation is successful, the class name is added to the packet (by calling
+isc::dhcp::pkt::addClass).
+
+If packet belongs to at least one class, this fact is logged. If there are any
+exceptions raised during class evaluation, an error is logged and the code attempts
+to evaluate the next class.
+
+@subsection dhcpv4ClassifierUsage How client classification information is used in DHCPv4
+
 Currently there is a short code section that alternates packet processing depending on
-which class it belongs to. It is planned to move that capability to an external hook
-library. See ticket #3275. The class specific behavior is:
+which class it belongs to. (It is planned to move that capability to an external hook
+library, see ticket #3275.) The class specific behavior is:
 
 - docsis3.0 packets have siaddr (next server) field set
 - docsis3.0 packets have file field set to the content of the boot-file-name option
 - eRouter1.0 packets have siaddr (next server) field cleared
 
-Aforementioned modifications are conducted in @ref isc::dhcp::Dhcpv4Srv::classSpecificProcessing.
+Aforementioned modifications are conducted in
+@ref isc::dhcp::Dhcpv4Srv::vendorClassSpecificProcessing.
 
 It is possible to define class restrictions in subnet, so a given subnet is only
-accessible to clients that belong to a given class. That is implemented as isc::dhcp::Pkt4::classes_
-being passed in isc::dhcp::Dhcpv4Srv::selectSubnet() to isc::dhcp::CfgMgr::getSubnet4().
-Currently this capability is usable, but the number of scenarios it supports is
-limited.
-
- @section dhcpv4ConfigBackend Configuration backend for DHCPv4
-
-There are many theoretical ways in which server configuration can be stored.
-The legacy ISC-DHCP implementation uses flat files. Configuration stored in JSON files is
-becoming more and more popular among various projects. There are unofficial patches for
-ISC-DHCP that keep parts of the configuration in LDAP. It was also suggested that in some
-cases it would be convenient to keep configuration in XML files.
-
-Kea 0.9 has introduced configuration backends that are switchable during compilation phase. Currently the only choice is JSON.
-
-JSON is a new configuration backend that causes Kea to read JSON configuration file from
-disk. It does not require any framework and thus is considered more lightweight. It will
-allow dynamic on-line reconfiguration, but will lack remote capabilities (i.e. no RESTful
-API). This configuration backend is expected to be the default for upcoming Kea 0.9. It
-requires <tt> -c config-file </tt> command-line option.
-
-Internally, configuration backends are implemented as different implementations of the
-isc::dhcp::ControlledDhcpv4Srv class, stored in kea_controller.cc files.
-
-While it is unlikely that ISC will support more than one backend at any given time, there
-are several aspects that make that approach appealing in the long term. First, having
-two backends is essential during transition time, where both old and new backend is used.
-Second, there are external organizations that develop and presumably maintain LDAP backend
-for ISC-DHCP. Is at least possible that similar will happen for Kea. Finally, if we ever
-extend the isc::dhcp::CfgMgr with configuration export, this approach could be used as
-a migration tool.
+accessible to clients that belong to a given class. That is implemented as
+isc::dhcp::Pkt4::classes_ being passed in isc::dhcp::Dhcpv4Srv::selectSubnet()
+to isc::dhcp::CfgMgr::getSubnet4().  Currently this capability is usable, but
+the number of scenarios it supports is limited.
+
+Finally, it is possible to define client class-specific options, so clients belonging
+to a class foo, will get options associated with class foo. This is implemented in
+isc::dhcp::Dhcpv4Srv::buildCfgOptionList.
+
+@section dhcpv4ConfigBackend Configuration backend for DHCPv4
+
+Earlier Kea vesions had a concept of backends, which were implementations of
+different ways how configuration could be delivered to Kea. It seems that the
+concept of backends didn't get much enthusiasm from users and having multiple
+backends was cumbersome to maintain, so it was removed in 1.0.
 
 @section dhcpv4SignalBasedReconfiguration Reconfiguring DHCPv4 server with SIGHUP signal
 
@@ -286,7 +303,7 @@ configuration.
 
 The signal handler for SIGHUP (also for SIGTERM and SIGINT) are installed in the
 kea_controller.cc using the @c isc::util::SignalSet class. The
-@c isc::dhcp::Dhcp6Srv calls @c isc::dhcp::Daemon::handleSignal on each pass
+@c isc::dhcp::Dhcp4Srv calls @c isc::dhcp::Daemon::handleSignal on each pass
 through the main loop. This method fetches the last received signal and calls
 a handler function defined in the kea_controller.cc. The handler function
 calls a static function @c configure defined in the kea_controller.cc.

src/bin/dhcp6/dhcp6.dox

@@ -214,10 +214,16 @@ definitions).
 
 @section dhcpv6Classifier DHCPv6 Client Classification
 
-The Kea DHCPv6 server currently supports simplified client classification. It is called
+The Kea DHCPv6 currently supports two classification modes: simplified client
+classification (that was an early implementation that used values of vendor class option)
+and full client classification.
+
+@subsection dhcpv6ClassifierSimple Simple Client Classification in DHCPv6
+
+The Kea DHCPv6 server supports simplified client classification. It is called
 "simplified", because the incoming packets are classified based on the content
-of the vendor class (16) option. More flexible classification is planned, but there
-are no specific development dates agreed.
+of the vendor class (16) option. More flexible classification was added in 1.0
+and is described in @ref dhcpv6ClassifierFull.
 
 For each incoming packet, @ref isc::dhcp::Dhcpv6Srv::classifyPacket() method is
 called.  It attempts to extract content of the vendor class option and interprets
@@ -235,8 +241,35 @@ Nevertheless, there is such a possibility and it will be used in a near future.
 check whether a packet belongs to given class, isc::dhcp::Pkt6::inClass method should
 be used.
 
+The code sometimes refers to this classification as "simple" or 'built-in", because
+it does not require any configuration and thus is built into the server logic.
+
+@subsection dhcpv6ClassifierFull Full Client Classification in DHCPv6
+
+Kea 1.0 introduced full client classification. Each client class consists of a name
+and an expression that can be evaluated on an incoming packet. If it evaluates to
+true, this packet is considered a member of said class. Class definitions are stored
+in isc::dhcp::ClientClassDef objects that are kept in isc::dhcp::ClientClassDictionary
+and can be retrieved from CfgMgr using isc::dhcp::SrvConfig::getClientClassDictionary().
+This is convenient as there are often multiple classes associated with a given scope.
+As of Kea 1.0, the only supported scope is global, but there are plans to support
+class definitions that are subnet specific.
+
+Client classification is done in isc::dhcp::Dhcpv6Srv::classifyPacket. First, the old
+"built-in" (see @ref dhcpv6ClassifierSimple) classification is called (see @ref
+isc::dhcp::Dhcpv6Srv::classifyByVendor). Then the code iterates over all class definitions
+and for each class definition it calls isc::dhcp::evaluate, which is implemented in libeval
+(see @ref dhcpEval). If the evaluation is successful, the class name is added to the packet
+(by calling isc::dhcp::pkt::addClass).
+
+If packet belongs to at least one class, this fact is logged. If there are any
+exceptions raised during class evaluation, an error is logged and the code attempts
+to evaluate the next class.
+
+@subsection dhcpv6ClassifierUsage How client classification information is used in DHCPv6
+
 Currently there is no class behavior coded in DHCPv6, hence no v6 equivalent of
-@ref isc::dhcp::Dhcpv4Srv::classSpecificProcessing. Should any need for such a code arise,
+@ref isc::dhcp::Dhcpv6Srv::vendorClassSpecificProcessing. Should any need for such a code arise,
 it will be conducted in an external hooks library.
 
 It is possible to define class restrictions in subnet, so a given subnet is only
@@ -245,33 +278,16 @@ being passed in isc::dhcp::Dhcpv6Srv::selectSubnet() to isc::dhcp::CfgMgr::getSu
 Currently this capability is usable, but the number of scenarios it supports is
 limited.
 
- @section dhcpv6ConfigBackend Configuration backend for DHCPv6
-
-There are many theoretical ways in which the server configuration can be stored.
-The legacy ISC-DHCP implementation uses flat files. Configuration stored in JSON files is
-becoming more and more popular among various projects. There are unofficial patches for
-ISC-DHCP that keep parts of the configuration in LDAP. It was also suggested that in some
-cases it would be convenient to keep configuration in XML files.
-
-Kea 0.9 has introduced configuration backends that are switchable during the
-compilation phase. Currently the only choice is JSON.
-
-JSON is a new configuration backend that causes Kea to read JSON configuration file from
-disk. It does not require any framework and thus is considered more lightweight. It will
-allow dynamic on-line reconfiguration, but will lack remote capabilities (i.e. no RESTful
-API). This configuration backend is expected to be the default for upcoming Kea 0.9. It
-requires <tt> -c config-file </tt> command-line option.
-
-Internally, the configuration backend is implemented as am implementations of the
-isc::dhcp::ControlledDhcpv6Srv class, stored in kea_controller.cc files.
-
-While it is unlikely that ISC will support more than one backend at any given time, there
-are several aspects that make that approach appealing in the long term. First, having
-two backends is essential during transition time, where both old and new backend is used.
-Second, there are external organizations that develop and presumably maintain LDAP backend
-for ISC-DHCP. Is at least possible that similar will happen for Kea. Finally, if we ever
-extend the isc::dhcp::CfgMgr with configuration export, this approach could be used as
-a migration tool.
+Finally, it is possible to define client class-specific options, so clients belonging
+to a class foo, will get options associated with class foo. This is implemented in
+isc::dhcp::Dhcpv6Srv::buildCfgOptionList.
+
+@section dhcpv6ConfigBackend Configuration backend for DHCPv6
+
+Earlier Kea vesions had a concept of backends, which were implementations of
+different ways how configuration could be delivered to Kea. It seems that the
+concept of backends didn't get much enthusiasm from users and having multiple
+backends was cumbersome to maintain, so it was removed in 1.0.
 
 @section dhcpv6SignalBasedReconfiguration Reconfiguring DHCPv6 server with SIGHUP signal
 

src/lib/eval/eval.dox

@@ -127,11 +127,27 @@ instantiated with the appropriate value and put onto the expression vector.
 @section dhcpEvalConfigure Configure options
 
  Since the flex/bison tools are not necessary for a regular compilation,
- checks conducted during configure, but the lack of flex or
- bison tools does not stop the configure process. There is a flag
+ checks are conducted during the configure script, but the lack of flex or
+ bison tools does not stop the process. There is a flag
  (--enable-generate-parser) that tells configure script that the
  parser will be generated. With this flag, the checks for flex/bison
  are mandatory. If either tool is missing or at too early a version, the
  configure process will terminate with an error.
 
+@section dhcpEcalToken Supported tokens
+
+ There is a number of tokens implemented. Each token is derived from
+ isc::eval::Token class and represents a certain expression primitive.
+ Currently supported tokens are:
+
+ - isc::dhcp::TokenString - represents a constant string, e.g. "MSFT";
+ - isc::dhcp::TokenHexString - represents a constant string, encoded as
+   hex string, e.g. 0x666f6f which is actually "foo";
+ - isc::dhcp::TokenOption - represents an option in a packet, e.g.
+                    option[123].text;
+ - isc::dhcp::TokenEqual - represents equal (==) operator;
+ - isc::dhcp::TokenSubstring - represents substring(text, start, length) operator;
+
+More operators are expected to be implemented in upcoming releases.
+
 */