Hsqldb Back-end

This is the default back-end for DHCP Cluster. It is based on “Hypersonic DB” which is a simple and very fast database in pure Java, suitable for small to medium size deployments.

This back-end allows for fast deployment of end-to-end DHCP solutions without installing or managing a separate database (MySQL, Oracle…).

This back-end offers high brute performance, but is not suitable for high-availability cluster solutions or highly scalable services.

• Pure Java module running in the same process as the DHCP server - simple to install and to manage - equivalent to many other free solutions
• Very fast database engine capable of managing requests in-memory; it can be typically 20x faster than classical databases

• database is not multi-threaded (yet multi-thread safe); this can become a bottleneck issue for very high performance servers
• there is no support for active high-availability modes allowing automatic failover from one server to another in case of hardware failure

The Hsqldb back-end is kept as small and simple as possible.

It is currently only used to keep track of client leases. All other configuration parameters are stored in a single XML file.

There is basically only one persistant table: T_LEASE, which stores usage of IP addresses.

Other non-persistent table are created in-memory for lease calculation and OFFER tracking:

• minimal topology description: T_POOL lists all dynamic address pools available for address distribution, all pools in the same network are linked through the T_POOL_SET table
• to accelerate calculation of free addresses in pools, a T_BUBBLE keeps track of blocks (bubbles) of free addresses in each pool. These bubbles listed through a linked list.
• offers are temporarily kept in the table T_OFFER which is memory-only (not persistent), since offers have only a 60 seconds life-time. A timed-out offer becomes a free bubble again.

During debug and development, it is interesting to run the db in “Server” mode, which opens a server socket. The front-end connects via this socket despite the fact that the db runs in the same VM as the front-end. This allows for external client connection for manual data inspection. For maximum performance, you can swith to in-process mode where communication goes directly without going through network layers; this however prevents external client connection.

TODO : howto and performance gain

The table T_LEASE is kept entirely in-memory by default for simpliest and maximum performance. Data commited is however immediately written to disk into a SQL script. This SQL script is completely reloaded at next startup.

If the lease volume increases widely, it can be interesting to switch this table to cached mode, where the data is kept on disk and only partially cached in memory. Performance will be slightly reduced but server restart will be faster.

TODO

The first sequence in IP address allocation is the client sending a DHCPDiscover request and the server sending back a DHCPOffer with a (hopefully) proposed IP address.

The internal sequence when receiving a DHCPDiscover is as follows:

1. Applying Front-End rules to filter out requests (cf. Front End TODO)
2. Find out in which subnet the client is, hence which address pools are eligible for address allocation
3. Check if there rules allocating a static address to this client, if so directly send back the response
4. If there are dynamic addresses pools, call the DB stored procedure “DHCP_DISCOVER” to ask for an IP address

This stored procedure is responsible for finding a suitable IP address for the client.

• The temporary tables T_POOL_SET, T_POOL and T_BUBBLE are populated and consistent
• There is no overlap between T_POOL ranges
• There is no overlap between T_BUBBLE ranges
• There is no OFFERED or USED address in any T_BUBBLE range
• There is no empty T_BUBBLE range (start address > end address)

• poolId id of the POOL_SET, hence the address ranges
• macHex hex representation of the client's MAC address (must not be null)
• iccQuota maximum number of addresses allowed of this icc, or 0 to ignore icc
• icc icc identifier of the client, must not be null if iccQuota is > 0
• offerTime number of seconds to reserve OFFER before reallocating address

1. Check if the client already has an active lease in the specified address pool
   Select T_LEASE table with client's Mac address and Status is not FREE or ABANDONED,
   then filtering the result set with the specified address pool.
2. If no active lease is found, then look for the first free available address
   1. First check if we have not reached the ICC quota
      Select T_LEASE table with the client's ICC, then count active leases
      If the limit is reached, return an error (-4)
   2. Find a the first free address in the address pool
      Select T_BUBBLE to find the first free bubble, retrieve the first address then update the bubble: increase its start address or delete it if it becomes empty
      If there is no more available address return an empty code (0)
3. If a lease for this client (same MAC address) is already in DB
   1. If RECYCLE_DATE is over, change lease into FREE status
   2. If status is OFFERED, extend lease time
   3. If status is USED, extend lease time if it needs to be
   4. If status is ABANDONED, return error (-5) (pre-condition violation)
   5. If status is FREE, set up lease
   6. If unknown status, return error (-6)
4. If a lease existed for another client (and has expired, or pre-condition violation)
   Reserve lease for this client (reset all fields including CREATE_DATE)
5. If lease does not exist in db
   Create new lease for this client

• same as pre-conditions
• if not successfull (returned value ⇐ 0), the database is unchanged (rollback)
• if successful, for the IP address returned, a T_LEASE row is created with
  • IP = offered address
  • UPDATE_DATE = now
  • CREATION_DATE ⇐ UPDATE_DATE
  • EXPIRATION_DATE >= now+offerTime
  • RECYCLE_DATE >= EXPIRATION_DATE
  • MAC = client's mac address
  • ICC = client's ICC identifier (if present)
  • STATUS = OFFERED or USED

This stored procedure is responsible for allocating the final IP address for the client.

• to be completed

• poolId id of the POOL_SET, hence the address ranges
• requestedIp IP address requested by client
• leaseTime number of seconds to reserve the lease in DB
• margin percentage of margin for the lease time before reallocated, this is necessary for potential clock drifts between client and server (e.g. 30 means allocated 30% more time)
• macHex hex representation of the client's MAC address (must not be null)
• optimisticAllocation whether we allow a client to request a free address even if there was no previous OFFER
  this can be necessary to rebuild the database and allowing client renewals

The first step is to analyze both the client request and the database state. This lets us determine what actions should be done on the db, and which kind of response to send back to the client.

1. Retrieve the lease in db for the requested ip
2. if the lease already exists in db:
   1. if lease status is ABANDONED, return error (-5)
   2. if the lease's status is FREE, the address needs to be taken of free bubbles updateBubble=true
   3. is the lease's RECYCLE_DATE is past, the lease is temporarily considered as FREE before being reallocated (but bubbles are not updated)
   4. if the lease's status is OFFERED or USED, and the mac address is different, the then lease is owned by another client, return an error (-2)
   5. else mark lease to be updated updateLease=true
3. if the lease does not exist:
   1. mark lease to be created updateLease=false and mark bubble to be updated updateBubble=true

1. If existing lease object in db needs update:
   1. if previous lease owner is the same client, set renewal=true
   2. if this is not a renewal and we are not in optimistic mode, return an error (-1)
   3. update the lease in db
2. Else if we need to create a new lease object in db
   1. if not in optimistic mode, return an error (-1)
   2. insert new lease object in db
3. If updateBubble is true (we need to remove IP address from a free bubble):
   1. if IP address is not in a bubble, this is a pre-conditions violation, return an error (-6)
   2. if IP address is stricly inside a bubble (not the lower or upper limit), split the bubble into 2 bubbles excluding the allocated IP address
   3. if IP address is the lower or upper limit of the bubble, reduce the bubble's limit. If the bubble becomes empty, remove the bubble

Return code if successful >= 0 (bit array)

1. 1: (bit 0) lease is a renewal (was already in OFFERED or USED mode)
2. 2: (bit 1) bubble has been updated (possible only in optimistic mode)
3. 4: (bit 2) lease has been updated in database (a lease already existed potentially outdated)

• to be completed

When leases RECYCLE_DATE is past, they are eligible for garbage collection. The garbage collector is called every 5 minutes to reclaim free leases.

Design issue: there can be a significant delay between the time a lease has expired and the time when the address is free to be allocated to another client. The trade-off is in favor of runtime performance causing potentially some address starving in extreme conditions. However, a specific “urgent” clean-up may be introduced in case of an free address starvation.