From: Marcin Siodelski Date: Mon, 26 Oct 2015 15:15:55 +0000 (+0100) Subject: [3979] Updated user guide for lease expiration. X-Git-Tag: trac4106_base~6^2~4 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=94847b1629cd50d48cf25135be458f7f76154385;p=thirdparty%2Fkea.git [3979] Updated user guide for lease expiration. --- diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox index 9204a327cf..df2cf4d028 100644 --- a/doc/devel/mainpage.dox +++ b/doc/devel/mainpage.dox @@ -100,6 +100,8 @@ * - @subpage hostmgr * - @subpage optionsConfig * - @subpage allocengine + * - @subpage timerManager + * - @subpage leaseReclamationRoutine * - @subpage libdhcp_ddns * - @subpage dhcpDatabaseBackends * - @subpage configBackend diff --git a/src/lib/dhcpsrv/libdhcpsrv.dox b/src/lib/dhcpsrv/libdhcpsrv.dox index 7c800e49ef..befff37559 100644 --- a/src/lib/dhcpsrv/libdhcpsrv.dox +++ b/src/lib/dhcpsrv/libdhcpsrv.dox @@ -258,4 +258,120 @@ was made. The client will be offered/allocated a reserved address the next time it retries sending a DHCPDISCOVER/DHCPREQUEST message to the server. +@section timerManager Timer Manager + +The fundamental role of the DHCP server is to receive and process DHCP +messages received over the sockets opened on network interfaces. The +servers' include the main loops in which the servers passively wait +for the messages. This is done by calling the +@c isc::dhcp::IfaceMgr::receive4 and/or @c isc::dhcp::IfaceMgr::receive6 +methods for DHCPv4 and DHCPv6 server respectively. Internally, these +methods call @c select() on open sockets, which blocks for a +specified amount of time. + +The implication of using the @c select() is that the server has no +means to process any "events" while it is waiting for the @c select() +to return. An example of such an event is the expiration of the timer +which controls when the server should detect and process expired +leases. + +The @c isc::dhcp::TimerMgr has been created to address the issue of +processing expired leases according to the the dedicated timer. +Nevertheless, this concept is univeral and should be used for +all timers which need to be triggered asynchronously, i.e. independently +from processing the DHCP messages. + +The @c TimerMgr allows for registering timers and associating them with +user callback functions, which are executed without waiting for the +call to the @c select() function to return as a result of the timeout. +When the particular timer elapses, the blocking call to select is +interrupted by sending data over the dedicated (for a timer) +@c isc::util::WatchSocket. Each timer has an instance of the +@c isc::util::WatchSocket associated with it, and each such socket +is registered in the @c IfaceMgr using the @c IfaceMgr::addExternalSocket. +When the transmission of the data over the watch socket interrupts the +@c select() call, the user callback is executed by the +@c isc::dhcp::IfaceMgr and the watch socket is cleared to accept +subsequent events for the particular timer. + +The timers are implemented using the @c isc::asiolink::IntervalTimer class. +They are run in a dedicated thread which is owned (created and destroyed) +in the @c isc::dhcp::TimerMgr. This worker thread runs an instance +of the @c isc::asiolink::IOService object, associated with all +registered timers. The thread uses a common callback function which +is executed when the timer elapses. This callback function receives +a name of the elapsed timer as an argument and, based on that, selects the +appropriate @c isc::util::WatchSocket to be marked as ready. In order to +overcome the race conditions with a main thread, the worker thread blocks +right after it marks the watch socket as ready, and waits for this +socket to be cleared by the main thread. This is the indication +that the timer specific callback function has been invoked and the +worker thread may continue monitoring registered timers and signal +their readiness when they elapse. + +@section leaseReclamationRoutine Leases Reclamation Routine + +The lease reclamation is the process in which the expired lease becomes +available for re-assignment to the same or another client. When the +server reclaims the lease it executes the callouts registered for the +"lease4_expire" and "lease6_expire" hook points, performs the DNS update +to remove any DNS records associated with the expired lease, and finally +marks a lease as reclaimed in the lease database. The lease may be +marked as reclaimed by setting its state to @c Lease::STATE_EXPIRED_RECLAIMED +or by being removed from the database. + +The leases reclamation is performed periodically for a bulk of expired +leases in the lease reclamation routine. The lease reclamation routines +for both DHCP servers are implemented in the @c isc::dhcp::AllocEngine: +- @c isc::dhcp::AllocEngine::reclaimExpiredLeases4 (DHCPv4) +- @c isc::dhcp::AllocEngine::reclaimExpiredLeases6 (DHCPv6) + +Note that besides the reclamation of the leases, these methods also +update the relevant statistics, i.e. decrease the number of assigned +leases and increase the number of reclaimed leases. + +The leases reclamation routines are executed periodically according to +the server configuration (see the documentation for the +"expired-leases-processing" configuration map). Internally, they are +registered as callback functions in the @c isc::dhcp::TimerMgr +(see @ref timerManager for the details), during the servers' startup +or reconfiguration. + +Execution of the leases reclamation routine may take relatively +long period of time. It depends on the complexity of the callouts, +whether the DNS update is required for leases, and the type of the +lease database used. While the leases reclamation routine is +executed, the server is not processing any DHCP messages to avoid +race conditions being a result of concurrent access to the lease +database to allocate and reclaim leases. To make sure that the +server remains responsive, it is possible to limit the number of +leases being processed by the leases reclamation routine and/or +limit the time for the lease reclamation routine to process +leases. Both limits are specified in the respective arguments +passed to the lease reclamation routines. + +As mentioned above, reclaimed leases may be marked as such, by +updating their state to @c Lease::STATE_EXPIRED_RECLAIMED or by +being removed. This behavior is controlled by the boolean parameter +passed to the reclamation routine. The first approach is desired +when the server should provide "lease affinity", i.e. ability to +re-assign the same lease to the returning client. By only +updating the lease state, the server preserves association of the +lease with the particular client. When the client returns the +server may assign the same lease to the client, assuming that this +lease is still available. The lease is removed during the +reclamation when the lease affinity is not required and it is +preferred to not keep redundant information (about expired +leases) in the lease database. + +If the reclaimed leases are not removed, they are held in the +database for a specified amount of time after their expiration. +Each reclaimed lease is removed when this time elapses for it. +The @c isc::dhcp::LeaseMgr::deleteExpiredReclaimedLeases4 and +@c isc::dhcp::LeaseMgr::deleteExpiredReclaimedLeases6 are used +to remove those leases for which the specified amount of time +since expiration elapsed. These methods are executed periodically +by the DHCP servers using the dedicated timers registered in the +@c isc::dhcp::TimerMgr. + */