1# 2# CDDL HEADER START 3# 4# The contents of this file are subject to the terms of the 5# Common Development and Distribution License, Version 1.0 only 6# (the "License"). You may not use this file except in compliance 7# with the License. 8# 9# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 10# or http://www.opensolaris.org/os/licensing. 11# See the License for the specific language governing permissions 12# and limitations under the License. 13# 14# When distributing Covered Code, include this CDDL HEADER in each 15# file and include the License file at usr/src/OPENSOLARIS.LICENSE. 16# If applicable, add the following below this CDDL HEADER, with the 17# fields enclosed by brackets "[]" replaced with your own identifying 18# information: Portions Copyright [yyyy] [name of copyright owner] 19# 20# CDDL HEADER END 21# 22# 23# Copyright 2004 Sun Microsystems, Inc. All rights reserved. 24# Use is subject to license terms. 25# 26 27The DHCP server cache implementation 28Zhenghui.Xie@sun.com 29 30 31#ident "%Z%%M% %I% %E% SMI" 32 33INTRODUCTION 34============ 35 36The Solaris DHCP server implements a caching mechanism to: 37 38 * Ensure the ACK is consistent with the original OFFER, so that 39 subsequent requests get the same answer. 40 * Ensure the same IP address isn't offered to a different client. 41 * Improve performance by reducing the frequency of datastore lookups. 42 43IMPLEMENTATION OVERVIEW 44======================= 45 46The cache implementation consists of a number of hash tables and lists, 47enumerated below, along with a timeout and refresh mechanism: 48 49 * A global DHCP table hash (ntable): 50 51 Each active network table (dvsc_dnet_t) is hashed by subnet number 52 into a global hash called 'ntable'. The dsvc_dnet_t itself 53 contains a variety of information about each subnet, an access 54 handle to the underlying datastore, and a variety of caches which 55 we describe next. 56 57 An ntable hash entry will be removed after DHCP_NET_THRESHOLD 58 seconds of inactivity. 59 60 * A per-network client hash (ctable): 61 62 Each client structure (dsvc_clnt_t) is hashed by client identifier 63 into the per-network ctable. This table is used by the interface 64 worker thread to get client information. 65 66 A ctable hash entry will be removed if the client does not communicate 67 with the server for DHCP_CLIENT_THRESHOLD seconds. 68 69 * A per-network offer hash (itable): 70 71 The IP address associated with each pending OFFER is hashed into 72 the per-network itable. This table is used to reserve the offered 73 and in-use IP addresses on the given network. 74 75 An itable hash entry will be removed if more than DSVC_CV_OFFER_TTL 76 seconds elapse without update_offer() being called on it. 77 78 * A per-network free record list (freerec): 79 80 This is a cache of free records, populated with any unused records 81 retrieved from previous datastore lookups or from IP addresses that 82 have been explicitly released by DHCP clients. This is the first 83 list select_offer() consults. 84 85 An entry in the freerec list expires after DSVC_CV_CACHE_TTL seconds. 86 87 * A per-network least recently used record list (lrurec) 88 89 This is a cache of least recently used records, populated with any 90 unused records retrieved from a previous datastore lookup for 91 LRU records. This is the second list select_offer() consults, after 92 checking freerec. 93 94 An entry in the lrurec list expires after DSVC_CV_CACHE_TTL seconds. 95 96The concurrency between the datastore and cached records is handled by the 97underlying datastore implementation using perimeters and is transparent to 98in.dhcpd. $SRC/lib/libdhcpsvc/private/{private.c,public.c} implement the 99functions used by in.dhcpd and DHCP server admin tools to lookup and modify 100the underlying datastore records. 101 102TRANSACTIONS 103============ 104 105When in.dhcpd receives a packet from a client, the interface thread first 106calls open_dnet() to retrieve the dsvc_dnet_t which describes the network. 107The dsvc_dnet_t is either in the ntable hash, in which case it is returned, 108or a new dsvc_dnet_t is allocated and inserted to ntable. Then, using the 109dsvc_dnet_t, the interface thread calls open_clnt(), which searches the 110dsvc_dnet_t's ctable hash and returns the client structure (dsvc_clnt_t) if 111found. Otherwise, a new dsvc_clnt_t is allocated and inserted into the 112ctable. Finally, the packet is put to the client's packet list so that the 113client thread can process it. 114 115The client thread then processes the packet according to whether it's a 116DISCOVER, REQUEST, RELEASE, or DECLINE. 117 118For a DISCOVER: 119 120 1. If there is a pre-assigned IP for this client and the cached offer 121 is not timed out, then use the IP and the record in the 122 dsvc_clnt_t and make an OFFER. 123 124 2. If there is a pre-assigned IP but the cached offer is expired, 125 remove the cached OFFER from the itable, and try to find a new 126 record for the client (see below). 127 128 3. If there is no pre-assigned IP for this client, just try to find 129 a new record for the client (see following text). 130 131 To find a new record, the client thread first searches the datastore 132 for a record matching the client identifier provided in the packet. 133 If none is found, then the free record list (freerec) and least 134 recently used record list (lrurec) are searched, in that order. If 135 either freerec or lrurec is empty, or the head record on either list 136 is expired, in.dhcpd removes any existing records and attempts to 137 repopulate them by performing datastore lookups. Finally, any 138 unused records are cached for later use. 139 140 If a usable record is found, the server generates and sends an OFFER 141 to the client. Once sent, the client's dsvc_clnt_t is inserted to 142 the dsvc_dnet_t's itable if it is a new IP, or the itable is refreshed 143 if it is a pre-assigned IP. 144 145For a REQUEST: 146 147 1. If the REQUEST is a reply to a previous OFFER, it checks if the 148 OFFER has expired. If not, the itable timer is reset, the client 149 record is updated, and the ACK is sent. If it is expired and the 150 address cannot be confirmed to still be free, the REQUEST is 151 silently ignored (and the client should eventually drop back 152 to DISCOVER). 153 154 2. If the REQUEST is associated with a client INIT-REBOOT or a client 155 extending a lease, then the client thread does a datastore lookup 156 by client identifier. If a match is found, the record is updated 157 and an ACK is sent. 158 159If the packet is a RELEASE, the client thread modifies the record in the 160datastore so that it is marked free, and, if successful, puts the record onto 161the free record list (freerec). 162 163Finally, if the packet is a DECLINE, the client thread modifies the record in 164the datastore so that it is marked unusable. 165