[master] Merge branch 'trac4299' (devel guide update)

doc/devel/config-backend.dox

@@ -10,51 +10,35 @@
 
 @section configBackendIntro Introduction
 
-Kea is a flexible DHCP protocol engine. It offers a selection of lease database
-backends, extensibility via the hooks API and the definition of custom options.
-Depending on the environment, one lease database backend may be better than
-other. Similarly, because the best way of configuring the server can depend on
-the environment, Kea provides different ways of obtaining configuration
-information, through the Configuration Backend. Since the means by which
-configuration information is received cannot be part of the configuration itself, it
-has to be chosen at the compilation time (when configuring the sources).
-
-This page explains the background to the Configuration Backend and how
-it is implemented. It is aimed at people who want to develop and
-maintain their own backends.
-
-@section configBackendMotivation Motivation for Different Backends
-
-BIND10 (the project under which the first stages of Kea were developed)
-used to maintain an extensive framework that was responsible for the
-configuration of components.  After BIND10 was cancelled, two projects
-were created: <a href="http://kea.isc.org">Kea</a> (focused on DHCP)
-and <a href="http://www.bundy-dns.de">Bundy</a> (aimed at DNS). The
-Kea team decided to remove the BIND10 framework, while the Bundy team
-decided to keep it. However, even though the Kea team is focused on a
-backend that reads a JSON configuration file from disk, it decided to
-make it easy for others to use different backends.
-
-While ISC currently (May 2015) maintains only one configuration backend
-(a JSON file read from disk), it is quite possible that additional backends
-(e.g. using LDAP or XML) will be developed in the future by ISC or other
-organizations.
-
-@section configBackendAdding How to Add a New Configuration Backend
-
-The configuration backend concept was designed to make external (i.e. not
-maintained by ISC) configurations backends easy to maintain. In particular,
-the set of patches vs. separate files required strongly favors separate
-files. This is important if an external organization wants to develop its
-own configuration backend and then needs to apply it to every ISC release
-of Kea.
-
-The following steps are needed to add new configuration backend (it is assumed
-that the modified component is DHCPv4. Similar approach applies to the other
+Kea started as a sub-project in BIND10 that used a program (called
+bindctl) to deliver configuration information to its modules. This
+potentially allowed for modules to get their configuration information
+in a variaty of ways using what were known as configuration backends.
+After BIND10 was cancelled, the Kea project briefly tried to maintain
+backward compatibility with the BIND10 framework, but the effort
+was discontinued due to lack of interest.
+
+Currently the Kea team does not plan to develop any additional
+configuration backends. Instead, effort is being focused on enhancing
+the current control channel (see @ref ctrlSocket) to be as flexible
+as possible. If you are thinking about developing new ways to
+configure Kea, the recommendation is to write an external piece of
+software that will communicate with Kea using this channel.
+
+@section configBackendHistoric Historic Notes
+
+While this section currently has no practical value, it may become useful
+one day to develop a minimalistic, stripped down Kea version that does
+not have any command interface at all. This could prove useful for running
+Kea in embedded regime.
+
+The following steps are needed for the DHCPv4 server to be able to
+process a new method of configuration. (It is assumed that the
+modified component is DHCPv4. Similar approach applies to the other
 components: DHCPv6 or DHCP-DDNS):
 
 -# Write your own implementation of isc::dhcp::ControlledDhcpv4Srv::init(),
-   isc::dhcp::ControlledDhcpv4Srv::init() and isc::dhcp::ControlledDhcpv4Srv::cleanup()
+   isc::dhcp::ControlledDhcpv4Srv::init() and isc::dhcp::ControlledDhcpv4Srv::cleanup(),
    and put it in the src/bin/dhcp4 directory (e.g. as foo_controller.cc).
 -# Modify src/bin/dhcp4/Makefile.am to include your file (e.g. foo_controller.cc) in
    the build.
@@ -75,21 +59,6 @@ Optionally you can also:
 
 The following are some details of the JSON backend framework.
 
--# A switch called --with-kea-config has been implemented in the
-   configure script. It allows the selection at compilation time of how the
-   servers will be configured. Currently (June 2014),
-   there is one value: JSON (read configuration from a JSON file)
-   Although the Bundy/BIND10 framework has been removed from Kea, the
-   configuration choice is available for other projects (e.g. Bundy)
-   that want to include an implementation of Kea using that backend.
-   Such projects are advised to import the Kea modules and compile
-   them with the Bundy backend enabled.<br/><br/>
-   This switchable backend concept is quite simple. There are different
-   implementations of ControlledXSrv class, each backend keeping its code
-   in a separate file. It is a matter of compiling/linking
-   one file or another. Hence it is easy to remove the old backend (and for
-   external projects, like Bundy, to keep it if they desire). It is also easy
-   for other organizations to add and maintain their own backends (e.g. LDAP).<br/><br/>
 -# Each backend uses the common code for configuration and command
    processing callbacks. They all assume that JSON formatted parameters are sent
    and they are expected to return well formatted JSON responses. The exact
@@ -151,21 +120,4 @@ The following are some details of the JSON backend framework.
    that sending signals is possible (for configuration reload or shutdown). It is also
    able to print out a status.
 
-Future changes planned for this part of the code are:
-
--# Implement a common base class for the Kea4, Kea6, and D2 servers. Some
-   operations will be common for all three components: logger initialization,
-   handling and, at some future point, control socket. This calls for a small
-   base class that @ref isc::dhcp::Dhcpv4Srv "Dhcpv4Srv", @ref
-   isc::dhcp::Dhcpv6Srv "Dhcpv6Srv" and the @ref isc::d2::D2Controller
-   "D2Controller" classes can use.  It is expected that the base class (@ref
-   isc::dhcp::Daemon) will be a small one but will grow over time as the code is
-   unified. This has been implemented in @ref isc::dhcp::Daemon.<br/><br/>
--# After Kea 0.9 is released, a form of secure socket will be implemented
-   through which commands can be sent. Whatever the design, it will allow the
-   sending of configurations and commands in JSON format and the receiving of
-   responses.  Once that is done, Kea will have the same capability the BIND10
-   framework to send additional parameters. One obvious use case will be to send
-   a new configuration file name as the parameter for "reload".
-
 */

doc/devel/contribute.dox

@@ -9,7 +9,7 @@
  @page contributorGuide Kea Contributor's Guide
 
 So you found a bug in Kea or plan to develop an extension and want to
-send a patch? Great! This page will explain how to contribute your
+send us a patch? Great! This page will explain how to contribute your
 changes smoothly.
 
 @section contributorGuideWritePatch Writing a patch
@@ -25,14 +25,6 @@ design or the best proposed solution to a certain problem, but all
 the internal details should be discussed on kea-dev and not posted
 to kea-users.
 
-If you prefer to get
-faster feedback, most Kea developers hang out in the \c dhcp
-jabber room (xmpp:dhcp@conference.jabber.isc.org). Feel free to join this
-room and talk to us. It is possible that someone else is working on your
-specific issue or perhaps the solution you plan to implement is not
-the best one. Often having a 10 minute talk could save many hours of
-engineering work.
-
 The first step in writing the patch or new feature should be to get
 the source code from our Git repository. The procedure is very easy and
 is explained here: http://kea.isc.org/wiki/GitGuidelines.  While it is
@@ -44,18 +36,18 @@ OK, so you have written a patch? Great! Before you submit it, make sure
 that your code compiles. This may seem obvious, but there's more to
 it. You have surely checked that it compiles on your system, but Kea
 is portable software. Besides Linux, it is compiled and used on
-relatively uncommon systems like OpenBSD and Solaris 11. Will your code
+relatively uncommon systems like OpenBSD. Will your code
 compile and work there? What about endianess? It is likely that you used
 a regular x86 architecture machine to write your patch, but the software
 is expected to run on many other architectures. You may take a look at
-system specific build notes (http://kea.isc.org/wiki/SystemSpecificNotes).
+system specific build notes (http://kea.isc.org/wiki/Install).
 For a complete list of systems we build on, you may take a look at the
 following build farm report: https://jenkins.isc.org/view/Kea_BuildFarm/ .
 
 Does your patch conform to Kea coding guidelines
 (http://kea.isc.org/wiki/CodingGuidelines)? You can submit a
 patch that does not adhere to them, but that will reduce its chances of
-being accepted. If the deviations are minor, the Kea engineer who
+being accepted. If the deviations are minor, one of the Kea engineers who
 does the review will likely fix the issues. However, if there are lots
 of issues, the reviewer may simply reject the patch and ask you to fix
 it before re-submitting.
@@ -94,7 +86,24 @@ written and observing the test fail, you can detect the situation
 where a bug in the test code will cause it to pass regardless of
 the code being tested.
 
-See @ref unitTests for instructions on how to run unit-tests.
+Initially, some people unfamiliar with that approach react with "but
+my change is simple and I tested that it works". That approach
+is both insufficient and short-sighted. It is insufficient, because
+manual testing is by definition laborious and can't really be done
+on the multitude of systems we run Kea on. It is short-sighted, because
+even with your best intentions you will not be able to dedicate
+any significant amount of time for repeated testing of your improved
+code. The old ISC DHCP has two decades of history behind it and we
+hope to make Kea last similar time span. Over such long periods,
+code tends to be refactored several times. The change you
+made may be affected by some other change or by the code that
+hasn't been written yet.
+
+See @ref unitTests for instructions on how to run unit-tests. If you
+happen to touch any database related code, make sure you compile
+your code with @c --with-dhcp-mysql, @c --with-dhcp-pgsql and/or
+@c --with-cql as needed. For example, if you change something
+substantial, make sure the other compilation options still work.
 
 If you happen to add new files or have modified any \c Makefile.am
 files, it is also a good idea to check if you haven't broken the
@@ -120,47 +129,125 @@ A complete list of all switches can be obtained with the command:
  ./configure --help
 @endcode
 
+@section contributorGuideSendPatch Sending the patch
+
+There are several ways how you can send your changes. They are listed
+here from most to least preferred.
+
+- Send pull request (PR) on github. This is by far the most convenient way for
+everyone. See the excellent documentation on github:
+https://help.github.com/articles/creating-a-pull-request/ for details.  In
+essence, you need github account (spam/hassle free, takes one minute to set
+up). Then you can fork the Kea repository, commit changes to your repo and ask us to pull
+your changes into official Kea repository. This has a number of advantages. First, it is
+made against a specific code version, which can be easily checked with git log
+command. Second, this request pops up instantly on our list of open pull
+requests and will stay there. The third benefit is that the pull request mechanism is
+very flexible. Kea engineers (and other users, too) can comment on it, attach
+links, mention other users etc.  You as a submitter can augment the patch by
+commiting extra changes to your repository. Those extra commits will appear instantly
+in the pull request. This is really useful during the review. Finally, ISC engineers can
+better assess all open pull requests and add labels to them, such as "enhancement", "bug", or
+"unit-tests missing". This makes our life easier. Oh, and your commits will later
+be shown as yours in github history. If you care for that kind of things, once the
+patch is merged, you'll be automatically listed as contributor and Kea will be
+listed as project you have contributed to.
+
+- Create a ticket in the Kea trac and attach your patch to it. Sending a patch has a
+number of disadvantages. First, if you don't specify the base version against
+which it was created, one of ISC engineers will have to guess that or go through
+a series of trials and errors to find that out. If the code doesn't compile, the
+reviewer will not know if the patch is broken or maybe it was applied to
+incorrect base code. Another frequent problem is that it may be possible that
+the patch didn't include any new files you have added. If we happen to have any
+comments that you as submitter are expected to address (and in the overwhelming majority
+of cases, we have), you will be asked to send an updated patch. It is not
+uncommon to see several rounds of such reviews, so this can get very complicated
+very quickly. Please make sure your ticket is created in the default milestone
+"kea-proposed". ISC engineers review new tickets once a week and assign them to
+specific milestones. Please do not add tickets to working milestones directly.
+Having a ticket in trac ensures that the patch will never be forgotten and it
+will show up on our trac reports. It's not required, but much appreciated if
+you send a short note to the kea-dev mailing list explaining what you did with the code
+and announce the ticket number.
+
+- Send a patch to the kea-dev list. This is the third preferred method, if you
+can't or don't want to use github and trac for whatever reason.  If you
+send a patch to a mailing list in a wrong time, e.g. shortly before a release,
+ISC engineers may miss it or perhaps they will see it and then forget about
+it. Nevertheless, it is still doable and we successfully accepted patches that
+way. It just takes more time from everyone involved, so it's a slower process in
+general.
+
+- Send a tarball with your modified code. This is really the worst way one
+can contribute a patch. It has a number of disadvantages. In particular, someone
+will need to find out which version the code was based on and generate the
+patch. It's not a rocket science, but it may be a very mundane thing to do
+if the ISC engineer does not know the version in advance. The mailing list
+has a limit on the message size (for good reasons), so you'll likely need to
+upload it somewhere first. ISC engineers often don't pick up new tickets
+instantly, so it may have to wait weeks before the tarball is looked at.
+The tarball does not benefit from most of the advantages mentioned for github,
+like the ability to easily update the code, have a meaningful discussion
+or see what the exact scope of changes are. Nevertheless, if we given a choice
+of getting a tarball or not getting a patch at all, we prefer tarballs. Just
+keep in mind that processing a tarball is really cumbersome for ISC
+engineers, so it may take sigificantly longer than other ways.
+
 @section contributorGuideReview Going through a review
 
-Once everything is checked and working, feel free to create a ticket for
-your patch at http://kea.isc.org/ or attach your patch to an existing
-ticket if you have fixed it. It would be nice if you also join the
-\c dhcp chatroom saying that you have submitted a patch. Alternatively,
-you may send a note to the \c kea-dev mailing list.
-
-Here's the tricky part. One of Kea developers will review your patch,
-but it may not happen immediately. Unfortunately, developers are usually
-working under a tight schedule, so any extra unplanned review work may
-take a while sometimes. Having said that, we value external
-contributions very much and will do whatever we can to review patches in
-a timely manner. Don't get discouraged if your patch is not accepted
-after first review. To keep the code quality high, we use the same
+Once you let us submitted a patch using one of the ways above, the action
+is on one of the ISC engineers. First, we will need either a trac ticket
+or PR on github. We prefer the original submitter fill them as he or she
+has the best understanding of the purpose of the change and may have
+any extra information, e.g. "this patch fixes compilation issue on
+FreeBSD 10.1". If there there is no PR and no trac ticket, we will create
+one. Depending on the subjective importance and urgency as perceived by
+the ISC engineer, the ticket or PR will be assigned to one of the
+milestones.
+
+Sooner or later, one of ISC engineers will do the review. Here's the tricky
+part. One of Kea developers will review your patch, but it may not happen
+immediately. Unfortunately, developers are usually working under a tight
+schedule, so any extra unplanned review work may take a while sometimes. Having
+said that, we value external contributions very much and will do whatever we can
+to review patches in a timely manner. Don't get discouraged if your patch is not
+accepted after first review. To keep the code quality high, we use the same
 review processes for external patches as we do for internal code. It may take
-some cycles of review/updated patch submissions before the code is
-finally accepted. The nature of the review process is that it emphasizes
-areas that need improvement. If you are not used to the review process,
-you may get the impression that the feedback is negative. It is not: even
-the Kea developers seldom see reviews that say "All OK please merge".
-
-Once the process is almost complete, the developer will likely ask you
-how you would like to be credited. The typical answers are by first and
-last name, by nickname, by company name or anonymously. Typically we
-will add a note to the \c ChangeLog and also set you as the author of
-the commit applying the patch. If the contributed feature is big or
-critical for whatever reason, it may also be mentioned in release notes.
+some cycles of review/updated patch submissions before the code is finally
+accepted. The nature of the review process is that it emphasizes areas that need
+improvement. If you are not used to the review process, you may get the
+impression that the feedback is negative. It is not: even the Kea developers
+seldom see reviews that say "All OK please merge".
+
+Once the process is almost complete, the developer will likely ask you how you
+would like to be credited. The typical answers are by first and last name, by
+nickname, by company name or anonymously. Typically we will add a note to the \c
+ChangeLog and also set you as the author of the commit applying the patch and
+update the contributors section in the AUTHORS file. If the contributed feature
+is big or critical for whatever reason, it may also be mentioned in release
+notes.
+
+Sadly, we sometimes see patches that are submitted and then the submitter never
+responds to our comments or requests for an updated patch. Depending on the
+nature of the patch, we may either fix the outstanding issues on our own and get
+another ISC engineer to review them or the ticket may end up in our "Outstanding
+Tasks" milestone. When a new release is started, we go through the tickets in
+Outstanding Tasks, select a small number of them and move them to whatever the
+current milestone is. Keep that in mind if you plan to submit a patch and forget
+about it. We may accept it eventually, but it's much, much faster process if you
+participate in it.
 
 @section contributorGuideExtra Extra steps
 
-If you are interested in knowing the results of more in-depth testing,
-you are welcome to visit the ISC Jenkins page: https://jenkins.isc.org
-(Our old Kea build farm http://git.kea.isc.org/~tester/builder/KEA-builder-new.html
-is being migrated to Jenkins).  This is a
-live result page with all tests being run on various systems.  Besides
-basic unit-tests, we also have reports from valgrind (memory debugger),
-cppcheck and clang-analyzer (static code analyzers), Lettuce system
-tests and more. Although it is not possible for non ISC employees to run
-tests on that farm, it is possible that your contributed patch will end
-up there sooner or later. We also have ISC Forge tests running, but currently
-the test results are not publicly available.
+If you are interested in knowing the results of more in-depth testing, you are
+welcome to visit the ISC Jenkins page: https://jenkins.isc.org This is a live
+result page with all tests being run on various systems.  Besides basic
+unit-tests, we also have reports from valgrind (memory debugger), cppcheck and
+clang-analyzer (static code analyzers), Lettuce system tests and more. Although
+it is not possible for non ISC employees to run tests on that farm, it is
+possible that your contributed patch will end up there sooner or later. We also
+have ISC Forge tests running, but currently the test results are not publicly
+available.
 
 */

doc/devel/mainpage.dox

@@ -7,17 +7,17 @@
 /**
  * @mainpage Kea Developer's Guide
  *
- * Welcome to Kea Developer's Guide. This documentation is addressed at
+ * Welcome to the Kea Developer's Guide. This documentation is addressed at
  * either existing or prospective Kea developers and contributors, and
- * provides information needed to extend and maintain Kea.
+ * provides information needed to extend and maintain Kea source code.
 
- * If you wish to write "hook" code - code that is loaded by Kea at
+ * If you wish to write hook code - the code that is loaded by Kea at
  * run-time and modifies its behavior,  you should read the section
  * @ref hooksdgDevelopersGuide.
  *
- * Kea maintenance information is divided into a number of sections
- * depending on focus. Information on DHCP-specific topics can be found
- * in the @ref dhcpMaintenanceGuide.  General topics, are discussed in
+ * Kea maintenance information is divided into a number of sections.
+ * Information on DHCP-specific topics can be found
+ * in the @ref dhcpMaintenanceGuide.  General topics are discussed in
  * @ref miscellaneousTopics.
  *
  * If you are a user or system administrator, rather than software engineer,
@@ -32,7 +32,9 @@
  * <a href="http://kea.isc.org/">Kea webpage (http://kea.isc.org)</a>
  *
  * @section contrib Contributor's Guide
- * - @subpage contributorGuide
+ * - @subpage contributorGuide - This page describes the process of sending
+ * a patch to ISC and what happens next. Please read it if you are considering
+ * sending us any code.
  *
  * @section buildingKeaWithUnitTests Building Kea with Unit tests
  * - @subpage unitTests
@@ -108,9 +110,7 @@
  * - @subpage dhcpDatabaseBackends
  * - @subpage dhcpEval
  * - @subpage configBackend
- *   - @subpage configBackendMotivation
  *   - @subpage configBackendJSONDesign
- *   - @subpage configBackendAdding
  * - @subpage perfdhcpInternals
  *
  * @section miscellaneousTopics Miscellaneous Topics

doc/devel/unit-tests.dox

@@ -11,11 +11,11 @@
 @section unitTestsIntroduction Introduction
 
 Kea uses the Google C++ Testing Framework (also called googletest or gtest) as a
-base for our C++ unit-tests. See http://code.google.com/p/googletest/ for
+base for our C++ unit-tests. See https://github.com/google/googletest for
 details. We used to have Python unit-tests inherited from BIND10
 days but have been removed, so please do not write any new Kea unit
-tests in Python. (If you want to write DHCP tests in Python, we encourage you to
-take a look at ISC Forge: http://kea.isc.org/wiki/IscForge.)
+tests in Python. If you want to write DHCP tests in Python, we encourage you to
+take a look at ISC Forge: http://kea.isc.org/wiki/IscForge .
 
 You must have \c gtest installed or at least extracted in a directory
 before compiling Kea unit-tests.  To enable unit-tests in Kea, use:
@@ -261,4 +261,9 @@ local   all             postgres                                trust
   Reference Manual</a>).
 
 
+ @subsection cqlUnitTestsPrerequisites Cassandra database
+
+ @todo: Describe steps necessary to set up Cassandra database suitable for running
+ unittests.
+
  */

src/bin/dhcp4/dhcp4.dox

@@ -301,6 +301,6 @@ specified at server startup. The location of this file is held in the
 
 For hooks API support in DHCPv4, see @ref dhcpv4Hooks.
 
-@subpage dhcpv4o6Dhcp4
+For a description of how DHCPv4-over-DHCPv6 is implemented, see @subpage dhcpv4o6Dhcp4.
 
 */

src/bin/dhcp4/dhcp4_hooks.dox

@@ -39,9 +39,10 @@
 
 @section dhcpv4HooksHookPoints Hooks in the DHCPv4 Server
 
-The following list is ordered by appearance of specific hook points during
-packet processing. Hook points that are not specific to packet processing
-(e.g. lease expiration) will be added to the end of this list.
+The following list is roughly ordered by appearance of specific hook points during
+packet processing, but the exact order depends on the actual processing. Hook points
+that are not specific to packet processing (e.g. lease expiration) will be added
+to the end of this list.
 
  @subsection dhcpv4HooksBuffer4Receive buffer4_receive
 

src/bin/dhcp6/dhcp6.dox

@@ -174,13 +174,6 @@ different way. If the server overrides client's preference it will communicate i
 by sending the DHCPv6 Client FQDN Option in its responses to a client, with
 appropriate flags set.
 
-@todo Note, that current implementation doesn't allow configuration of the server's behavior
-with respect to DNS Updates. This is planned for the future. The default behavior is
-constituted by the set of constants defined in the (upper part of) dhcp6_srv.cc file.
-Once the configuration is implemented, these constants will be removed.
-
- @todo Add section about setting up options and their definitions with bindctl.
-
 @section dhcpv6OptionsParse Custom functions to parse message options
 
 The DHCPv6 server implementation provides a generic support to define option
@@ -308,6 +301,6 @@ specified at server startup. The location of this file is held in the
 
 For hooks API support in DHCPv6, see @ref dhcpv6Hooks.
 
-@subpage dhcpv4o6Dhcp6
+For a description of how DHCPv4-over-DHCPv6 is implemented, see @subpage dhcpv4o6Dhcp6
 
  */

src/bin/dhcp6/dhcp6_hooks.dox

@@ -39,9 +39,10 @@
 
 @section dhcpv6HooksHookPoints Hooks in the DHCPv6 Server
 
-The following list is ordered by appearance of specific hook points during
-packet processing. Hook points that are not specific to packet processing
-(e.g. lease expiration) will be added to the end of this list.
+The following list is roughly ordered by appearance of specific hook points during
+packet processing, but the exact order depends on the actual processing. Hook points
+that are not specific to packet processing (e.g. lease expiration) will be added
+to the end of this list.
 
  @subsection dhcpv6HooksBuffer6Receive buffer6_receive
 

src/hooks/dhcp/user_chk/libdhcp_user_chk.dox

@@ -7,9 +7,9 @@
 /**
 @page libdhcp_user_chk DHCP User Check Hooks Library
 
-@section libdhcp_user_chkIntro Libdhcp_user_chk: An Example Hooks Library
+@section libdhcp_user_chkIntro user_chk: An Example Hooks Library
 ## Introduction
-libdhcp_user_chk is an example hooks library which customizes the DHCP query
+user_chk is an example hooks library which customizes the DHCP query
 processing provided by Kea DHCP server modules (kea-dhcp4 and kea-dhcp6).
 Specifically it allows subnet selection and DHCP response option customization
 based upon a registry of DHCP clients.  Note that the words "client" and "user"
@@ -25,6 +25,8 @@ based upon user identity.
 3. To provide a real time record of the user registration activity which can be
 sampled by an external consumer.
 
+The source code is provided in the src/hooks/dhcp/use_chk directory.
+
 ## User Registry Classes
 At the heart of the library is a class hierarchy centered around the class,
 @c user_chk::UserRegistry.  This class represents a maintainable, searchable

src/lib/dhcpsrv/database_backends.dox

@@ -55,9 +55,13 @@
 
   - <b>type</b> - specifies the type of database backend.  The following values
   for the type keyword are supported:
-     - <B>memfile</b> - In-memory database.  Nothing is written to any
-       external storage, so this should not be used in production.
-     - <b>mysql</b> - Use MySQL as the database
+     - <B>memfile</b> - In-memory database.
+     - <b>mysql</b> - Use MySQL as the database. Must be enabled at compilation
+       time.
+     - <b>postgresql</b> - Use PostgreSQL as the database. Must be enabled
+       at compilation time.
+     - <b>cql</b> - Use Cassandra (CQL) as the database. Must be enabled at
+       compilation time.
 
   The following sections list the database-specific keywords:
 
@@ -72,6 +76,8 @@
   - <b>user</b> - database user ID under which the database is accessed.  If not
     specified, no user ID is used - the database is assumed to be open.
 
+  For details, see @ref isc::dhcp::MySqlConnection::openDatabase().
+
   @subsection dhcpdb-keywords-pgsql PostgreSQL connection string keywords
 
   - <b>host</b> - host on which the selected database is running.  If not
@@ -83,5 +89,20 @@
   - <b>user</b> - database user ID under which the database is accessed.  If not
     specified, no user ID is used - the database is assumed to be open.
 
+  For details, see @ref isc::dhcp::PgSqlConnection::openDatabase().
+
+  @subsection dhcpdb-keywords-cql Cassandra (CQL) connection string keywords
+
+  - <b>contact_points</b> - a list of comma separated IP addresses of the
+    cluster contact points>
+  - <b>port</b> - an integer specifying a connection port. If not specified, the
+    default port will be used.
+  - <b>user</b> - a database user name under which the database is accessed. If
+    not specified, no user name is used - the database is assumed to be open.
+  - <b>password</b> - an optional password if required for connection
+  - <b>keyspace</b> - an optional keyspace. If not specified, the default value
+    of 'keatest' will be used.
+
+  For details, see @ref isc::dhcp::CqlConnection::openDatabase().
 
   */

src/lib/eval/eval.dox

@@ -132,14 +132,14 @@ instantiated with the appropriate value and put onto the expression vector.
  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
+ - 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::TokenIpAddress -- represents a constant IP address, encoded as
    a 4 or 16 byte binary string, e.g., 10.0.0.1 is 0x10000001.
- - isc::dhcp::TokenOption - represents an option in a packet, e.g.
+ - isc::dhcp::TokenOption -- represents an option in a packet, e.g.
                     option[123].text;
- - isc::dhcp::TokenRelay4Option - represents a sub-option inserted by the
+ - isc::dhcp::TokenRelay4Option -- represents a sub-option inserted by the
                     DHCPv4 relay, e.g. relay[123].text or relay[123].hex
  - isc::dhcp::TokenRelay6Option -- represents a sub-option inserted by
    a DHCPv6 relay
@@ -149,14 +149,20 @@ instantiated with the appropriate value and put onto the expression vector.
  - isc::dhcp::TokenPkt6 -- represents a DHCPv6 packet field (message type
    or transaction id).
  - isc::dhcp::TokenRelay6Field -- represents a DHCPv6 relay information field.
- - isc::dhcp::TokenEqual - represents the equal (==) operator;
- - isc::dhcp::TokenSubstring - represents the substring(text, start, length) operator;
+ - isc::dhcp::TokenEqual -- represents the equal (==) operator;
+ - isc::dhcp::TokenSubstring -- represents the substring(text, start, length) operator;
  - isc::dhcp::TokenConcat -- represents the concat operator which
    concatenate two other tokens.
  - isc::dhcp::TokenNot -- the logical not operator.
  - isc::dhcp::TokenAnd -- the logical and (strict) operator.
  - isc::dhcp::TokenOr -- the logical or (strict) operator (strict means
    it always evaluates its operands).
+ - isc::dhcp::TokenVendor -- represents vendor information option's existence,
+   enterprise-id field and possible sub-options. (e.g. vendor[1234].exists,
+   vendor[*].enterprise-id, vendor[1234].option[1].exists, vendor[1234].option[1].hex)
+ - isc::dhcp::TokenVendorClass -- represents vendor information option's existence,
+   enterprise-id and included data chunks. (e.g. vendor-class[1234].exists,
+   vendor-class[*].enterprise-id, vendor-class[*].data[3])
 
 More operators are expected to be implemented in upcoming releases.
 

src/lib/util/io/socketsession.h

@@ -21,6 +21,10 @@ namespace io {
 
 /// \page SocketSessionUtility Socket session utility
 ///
+/// \note This class is currently unused. Once we get to the implementation
+///       of the remote parts of the management API, we will evaluate whether
+///       this code is useful or not and either start using it or remove it.
+///
 /// This utility defines a set of classes that support forwarding a
 /// "socket session" from one process to another.  A socket session is a
 /// conceptual tuple of the following elements: