[3405] Updated developer's guide with respect to the dynamic reconfigure.

doc/devel/mainpage.dox

@@ -56,6 +56,7 @@
  *   - @subpage dhcpv4DDNSIntegration
  *   - @subpage dhcpv4Classifier
  *   - @subpage dhcpv4ConfigBackend
+ *   - @subpage dhcpv4SignalBasedReconfiguration
  *   - @subpage dhcpv4Other
  * - @subpage dhcp6
  *   - @subpage dhcpv6Session

src/bin/dhcp4/dhcp4.dox

@@ -231,6 +231,37 @@ 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 dhcpv4SignalBasedReconfiguration Reconfiguring DHCPv4 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 signal handler for SIGHUP (also for SIGTERM and SIGINT) are installed in the
+kea_controller.cc using the @c isc::util::io::SignalSet class. The
+@c isc::dhcp::Dhcp6Srv 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.
+
+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 dhcpv4Other Other DHCPv4 topics
 
  For hooks API support in DHCPv4, see @ref dhcpv4Hooks.

src/bin/dhcp6/dhcp6.dox

@@ -279,21 +279,20 @@ the SIGHUP signal, the server will re-read the configuration file specified at s
 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
+The signal handler for SIGHUP (also for SIGTERM and SIGINT) are installed in the
-same function to reconfigure the server which is called to configure it at startup.
+kea_controller.cc using the @c isc::util::io::SignalSet class. The
-The signal handler catches exceptions emitted during reconfiguration so as the
+@c isc::dhcp::Dhcp6Srv calls @c isc::dhcp::Daemon::handleSignal on each pass
-uncaught exceptions don't cause the process to exit.
+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.
 
-Signal handlers are static and therefore they must call static functions. The
+In order for the signal handler to know the location of the configuration file
-@c ControlledDhcpv6Srv::processCommand which performs the actual server
+(specified at process startup), the location of this file needs to be stored
-reconfiguration is static, so it can be called from the signal handler. In order
+in a static variable so as it may be directly accessed by the signal handler.
-for the signal handler to know the location of the configuration file (specified
+This static variable is stored in the @c dhcp::Daemon class and all Kea processes
-at process startup), the location of this file needs to be stored in a static
+can use it (all processes derive from this class). The configuration file
-variable so as it may be directly accessed by the signal handler. This static
+location is initialized when the @c Daemon::init method is called. Therefore,
-variable is stored in the @c dhcp::Daemon class and all Kea processes can use
+derived classes should call it in their implementations of the @c init method.
-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