[3406] Updated developer's guide with section about SIGHUP based reconfig.

diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox
index b775fe024f3c00e32c6121b42b81e147da34585f..2c1e1c1d18ec5e2799deb0cc59347a4a94f4e967 100644 (file)
--- a/doc/devel/mainpage.dox
+++ b/doc/devel/mainpage.dox
@@ -64,6 +64,7 @@
  *   - @subpage dhcpv6OptionsParse
  *   - @subpage dhcpv6Classifier
  *   - @subpage dhcpv6ConfigBackend
+ *   - @subpage dhcpv6SignalBasedReconfiguration
  *   - @subpage dhcpv6Other
  * - @subpage d2
  *   - @subpage d2CPL

diff --git a/src/bin/dhcp6/dhcp6.dox b/src/bin/dhcp6/dhcp6.dox
index 1571c93c911b91856cb9d05b8c47937907a45ca2..fdcd4091c76f57ed4c238f9873bbc6aabecaf743 100644 (file)
--- a/src/bin/dhcp6/dhcp6.dox
+++ b/src/bin/dhcp6/dhcp6.dox
@@ -1,4 +1,4 @@
-// Copyright (C) 2012-2013 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2012-2014 Internet Systems Consortium, Inc. ("ISC")
 //
 // Permission to use, copy, modify, and/or distribute this software for any
 // purpose with or without fee is hereby granted, provided that the above
@@ -262,6 +262,38 @@ for ISC-DHCP. Is at least possible that similar will happen for Kea. Finally, if
 extend the isc::dhcp::CfgMgr with configuration export, this approach could be used as
 a migration tool.
 
+@section dhcpv6SignalBasedReconfiguration Reconfiguring DHCPv6 server with SIGHUP signal
+
+Online reconfiguration (reconfiguration without a need to restart the server) is an
+important feature which is supported by all modern DHCP servers. When using the JSON
+configuration backend, a configuration file name is specified with a command line
+option of the DHCP server binary. The configuration file is used to configure the
+server at startup. If the initial configuration fails, the server will fail to start.
+If the server starts and configures successfully it will use the initial configuration
+until it is reconfigured.
+
+The reconfiguration request can be triggered externally (from other process) by editing
+a configuration file and sending a SIGHUP signal to DHCP server process. After receiving
+the SIGHUP signal, the server will re-read the configuration file specified at startup.
+If the reconfiguration fails, the server will continue to run and use the last good
+configuration.
+
+The SIGHUP signal handler is defined in the kea_controller.cc. The handler calls the
+same function to reconfigure the server which is called to configure it at startup.
+The signal handler catches exceptions emitted during reconfiguration so as the
+uncaught exceptions don't cause the process to exit.
+
+Signal handlers are static and therefore they must call static functions. The
+@c ControlledDhcpv6Srv::processCommand which performs the actual server
+reconfiguration is static, so it can be called from the signal handler. In order
+for the signal handler to know the location of the configuration file (specified
+at process startup), the location of this file needs to be stored in a static
+variable so as it may be directly accessed by the signal handler. This static
+variable is stored in the @c dhcp::Daemon class and all Kea processes can use
+it (all processes derive from this class). The configuration file location is
+initialized when the @c Daemon::init method is called. Therefore, derived
+classes should call it in their implementations of the @c init method.
+
  @section dhcpv6Other Other DHCPv6 topics
 
  For hooks API support in DHCPv6, see @ref dhcpv6Hooks.