server/dhcpd.leases.5

   1 .\"     dhcpd.leases.5
   2 .\"
   3 .\" Copyright (c) 2004,2009 by Internet Systems Consortium, Inc. ("ISC")
   4 .\" Copyright (c) 1996-2003 by Internet Software Consortium
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
  16 .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .\"   Internet Systems Consortium, Inc.
  19 .\"   950 Charter Street
  20 .\"   Redwood City, CA 94063
  21 .\"   <info@isc.org>
  22 .\"   https://www.isc.org/
  23 .\"
  24 .\" This software has been written for Internet Systems Consortium
  25 .\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
  26 .\" To learn more about Internet Systems Consortium, see
  27 .\" ``https://www.isc.org/''.  To learn more about Vixie Enterprises,
  28 .\" see ``http://www.vix.com''.   To learn more about Nominum, Inc., see
  29 .\" ``http://www.nominum.com''.
  30 .\"
  31 .\" $Id: dhcpd.leases.5,v 1.16 2011/04/22 13:21:35 tomasz Exp $
  32 .\"
  33 .TH dhcpd.leases 5
  34 .SH NAME
  35 dhcpd.leases - DHCP client lease database
  36 .SH DESCRIPTION
  37 The Internet Systems Consortium DHCP Server keeps a persistent
  38 database of leases that it has assigned.  This database is a free-form
  39 ASCII file containing a series of lease declarations.  Every time a
  40 lease is acquired, renewed or released, its new value is recorded at
  41 the end of the lease file.  So if more than one declaration appears
  42 for a given lease, the last one in the file is the current one.
  43 .PP
  44 When dhcpd is first installed, there is no lease database.   However,
  45 dhcpd requires that a lease database be present before it will start.
  46 To make the initial lease database, just create an empty file called
  47 DBDIR/dhcpd.leases.   You can do this with:
  48 .PP
  49 .nf
  50         touch DBDIR/dhcpd.leases
  51 .fi
  52 .PP
  53 In order to prevent the lease database from growing without bound, the
  54 file is rewritten from time to time.   First, a temporary lease
  55 database is created and all known leases are dumped to it.   Then, the
  56 old lease database is renamed DBDIR/dhcpd.leases~.   Finally, the
  57 newly written lease database is moved into place.
  58 .SH FORMAT
  59 Lease descriptions are stored in a format that is parsed by the same
  60 recursive descent parser used to read the
  61 .B dhcpd.conf(5)
  62 and
  63 .B dhclient.conf(5)
  64 files.  Lease files can contain lease declarations, and also group and
  65 subgroup declarations, host declarations and failover state
  66 declarations.  Group, subgroup and host declarations are used to
  67 record objects created using the OMAPI protocol.
  68 .PP
  69 The lease file is a log-structured file - whenever a lease changes,
  70 the contents of that lease are written to the end of the file.   This
  71 means that it is entirely possible and quite reasonable for there to
  72 be two or more declarations of the same lease in the lease file at the
  73 same time.   In that case, the instance of that particular lease that
  74 appears last in the file is the one that is in effect.
  75 .PP
  76 Group, subgroup and host declarations in the lease file are handled in
  77 the same manner, except that if any of these objects are deleted, a
  78 \fIrubout\fR is written to the lease file.   This is just the same
  79 declaration, with \fB{ deleted; }\fR in the scope of the
  80 declaration.   When the lease file is rewritten, any such rubouts that
  81 can be eliminated are eliminated.   It is possible to delete a
  82 declaration in the \fBdhcpd.conf\fR file; in this case, the rubout
  83 can never be eliminated from the \fBdhcpd.leases\fR file.
  84 .SH THE LEASE DECLARATION
  85 .PP
  86 .B lease \fIip-address\fB { \fIstatements...\fB }
  87 .PP
  88 Each lease declaration includes the single IP address that has been
  89 leased to the client.   The statements within the braces define the
  90 duration of the lease and to whom it is assigned.
  91 .PP
  92 .nf
  93 .B starts \fIdate\fB;\fR
  94 .B ends \fIdate\fB;\fR
  95 .B tstp \fIdate\fB;\fR
  96 .B tsfp \fIdate\fB;\fR
  97 .B atsfp \fIdate\fB;\fR
  98 .B cltt \fIdate\fB;\fR
  99 .fi
 100 .PP
 101 The start and end time of a lease are recorded using the \fBstarts\fR
 102 and \fBends\fR statements.   The \fBtstp\fR statement is specified if
 103 the failover protocol is being used, and indicates what time the peer
 104 has been told the lease expires.   The \fBtsfp\fR statement is
 105 also specified if the failover protocol is being used, and indicates
 106 the lease expiry time that the peer has acknowledged.
 107 The \fBatsfp\fR statement is the actual time sent from the failover
 108 partner.
 109 The \fBcltt\fR statement is the client's last transaction time.
 110 .PP
 111 The \fIdate\fR is specified in two ways, depending on the configuration
 112 value for the \fBdb-time-format\fR parameter.  If it was set to \fIdefault\fR,
 113 then the \fIdate\fR fields appear as follows:
 114 .PP
 115 .I weekday year\fB/\fImonth\fB/\fIday hour\fB:\fIminute\fB:\fIsecond\fR
 116 .PP
 117 The weekday is present to make it easy for a human to tell when a
 118 lease expires - it's specified as a number from zero to six, with zero
 119 being Sunday.  The day of week is ignored on input.  The year is
 120 specified with the century, so it should generally be four digits
 121 except for really long leases.  The month is specified as a number
 122 starting with 1 for January.  The day of the month is likewise
 123 specified starting with 1.  The hour is a number between 0 and 23, the
 124 minute a number between 0 and 59, and the second also a number between
 125 0 and 59.
 126 .PP
 127 Lease times are specified in Universal Coordinated Time (UTC), not in
 128 the local time zone.  There is probably nowhere in the world where the
 129 times recorded on a lease are always the same as wall clock times.  On
 130 most unix machines, you can display the current time in UTC by typing
 131 \fBdate -u\fR.
 132 .PP
 133 If the \fBdb-time-format\fR was configured to \fIlocal\fR, then
 134 the \fIdate\fR fields appear as follows:
 135 .PP
 136  \fBepoch\fR \fI<seconds-since-epoch>\fR\fB; #\fR \fI<day-name> <month-name>
 137 <day-number> <hours>\fR\fB:\fR\fI<minutes>\fR\fB:\fR\fI<seconds> <year>\fR
 138 .PP
 139 The \fIseconds-since-epoch\fR is as according to the system's local clock (often
 140 referred to as "unix time").  The \fB#\fR symbol supplies a comment that
 141 describes what actual time this is as according to the system's configured
 142 timezone, at the time the value was written.  It is provided only for human
 143 inspection.
 144 .PP
 145 If a lease will never expire, \fIdate\fR is \fBnever\fR instead of an
 146 actual date.
 147 .PP
 148 .B hardware \fIhardware-type mac-address\fB;\fR
 149 .PP
 150 The hardware statement records the MAC address of the network
 151 interface on which the lease will be used.   It is specified as a
 152 series of hexadecimal octets, separated by colons.
 153 .PP
 154 .B uid \fIclient-identifier\fB;\fR
 155 .PP
 156 The \fBuid\fR statement records the client identifier used by the
 157 client to acquire the lease.   Clients are not required to send client
 158 identifiers, and this statement only appears if the client did in fact
 159 send one.   Client identifiers are normally an ARP type (1 for
 160 ethernet) followed by the MAC address, just like in the \fBhardware\fI
 161 statement, but this is not required.
 162 .PP
 163 The client identifier is recorded as a colon-separated hexadecimal
 164 list or as a quoted string.   If it is recorded as a quoted string and
 165 it contains one or more non-printable characters, those characters are
 166 represented as octal escapes - a backslash character followed by three
 167 octal digits.
 168 .PP
 169 .B client-hostname "\fIhostname\fB";\fR
 170 .PP
 171 Most DHCP clients will send their hostname in the \fIhost-name\fR
 172 option.  If a client sends its hostname in this way, the hostname is
 173 recorded on the lease with a \fBclient-hostname\fR statement.   This
 174 is not required by the protocol, however, so many specialized DHCP
 175 clients do not send a host-name option.
 176 .PP
 177 .B abandoned;
 178 .PP
 179 The \fBabandoned\fR statement indicates that the DHCP server has
 180 abandoned the lease.   In that case, the \fBabandoned\fR statement
 181 will be used to indicate that the lease should not be reassigned.
 182 Please see the \fBdhcpd.conf(5)\fR manual page for information about
 183 abandoned leases.
 184 .PP
 185 .B binding state \fIstate\fB;
 186 .B next binding state \fIstate\fB;
 187 .PP
 188 The \fBbinding state\fR statement declares the lease's binding state.
 189 When the DHCP server is not configured to use the failover protocol, a
 190 lease's binding state will be either \fBactive\fR or \fBfree\fR.   The
 191 failover protocol adds some additional transitional states, as well as
 192 the \fBbackup\fR state, which indicates that the lease is available
 193 for allocation by the failover secondary.
 194 .PP
 195 The \fBnext binding state\fR statement indicates what state the lease
 196 will move to when the current state expires.   The time when the
 197 current state expires is specified in the \fIends\fR statement.
 198 .PP
 199 .B option agent.circuit-id \fIstring\fR;
 200 .B option agent.remote-id \fIstring\fR;
 201 .PP
 202 The \fBoption agent.circuit-id\fR and \fBoption agent.remote-id\fR
 203 statements are used to record the circuit ID and remote ID options
 204 send by the relay agent, if the relay agent uses the \fIrelay agent
 205 information option\fR.   This allows these options to be used
 206 consistently in conditional evaluations even when the client is
 207 contacting the server directly rather than through its relay agent.
 208 .PP
 209 .B set \fIvariable\fB = \fIvalue\fB;
 210 .PP
 211 The \fBset\fR statement sets the value of a variable on the lease.
 212 For general information on variables, see the \fBdhcp-eval(5)\fR
 213 manual page.
 214 .PP
 215 .B The \fIddns-text\fB variable
 216 .PP
 217 The \fIddns-text\fR variable is used to record the value of the
 218 client's TXT identification record when the interim ddns update
 219 style has been used to update the DNS for a particular lease.
 220 .PP
 221 .B The \fIddns-fwd-name\fB variable
 222 .PP
 223 The \fIddns-fwd-name\fB variable records the value of the name used in
 224 updating the client's A record if a DDNS update has been successfully
 225 done by the server.   The server may also have used this name to
 226 update the client's PTR record.
 227 .PP
 228 .B The \fIddns-client-fqdn\fB variable
 229 .PP
 230 If the server is configured to use the interim ddns update style, and
 231 is also configured to allow clients to update their own fqdns, and the
 232 client did in fact update its own fqdn, then the
 233 \fIddns-client-fqdn\fR variable records the name that the client has
 234 indicated it is using.   This is the name that the server will have
 235 used to update the client's PTR record in this case.
 236 .PP
 237 .B The \fIddns-rev-name\fB variable
 238 .PP
 239 If the server successfully updates the client's PTR record, this
 240 variable will record the name that the DHCP server used for the PTR
 241 record.   The name to which the PTR record points will be either the
 242 \fIddns-fwd-name\fR or the \fIddns-client-fqdn\fR.
 243 .PP
 244 .B The \fIvendor-class-identifier\fB variable
 245 .PP
 246 The server retains the client-supplied Vendor Class Identifier option
 247 for informational purposes, and to render them in DHCPLEASEQUERY responses.
 248 .PP
 249 .B on \fIevents\fB { \fIstatements...\fB }
 250 The \fBon\fI statement records a list of statements to execute if a
 251 certain event occurs.   The possible events that can occur for an
 252 active lease are \fBrelease\fR and \fBexpiry\fR.   More than one event
 253 can be specified - if so, the events are separated by '|' characters.
 254 .PP
 255 .B bootp;
 256 .B reserved;
 257 These two statements are effectively flags.  If present, they indicate that
 258 the BOOTP and RESERVED failover flags, respectively, should be set.  BOOTP
 259 and RESERVED dynamic leases are treated differently than normal dynamic leases,
 260 as they may only be used by the client to which they are currently allocated.
 261 .RE
 262 .SH THE FAILOVER PEER STATE DECLARATION
 263 The state of any failover peering arrangements is also recorded in the
 264 lease file, using the \fBfailover peer\fR statement:
 265 .PP
 266 .nf
 267 .B failover peer "\fIname\fB" state {
 268 .B   my   state \fIstate\fB at \fIdate\fB;
 269 .B   peer state \fIstate\fB at \fIdate\fB;
 270 .B }
 271 .fi
 272 .PP
 273 The states of the peer named \fIname\fR is being recorded.   Both the
 274 state of the running server (\fBmy state\fR) and the other failover
 275 partner (\fIpeer state\fR) are recorded.   The following states are
 276 possible: \fBunknown-state\fR, \fBpartner-down\fR, \fBnormal\fR,
 277 \fBcommunications-interrupted\fR, \fBresolution-interrupted\fR,
 278 \fBpotential-conflict\fR, \fBrecover\fR, \fBrecover-done\fR,
 279 \fBshutdown\fR, \fBpaused\fR, and \fBstartup\fR.
 280 .B DBDIR/dhcpd.leases
 281 .SH SEE ALSO
 282 dhcpd(8), dhcp-options(5), dhcp-eval(5), dhcpd.conf(5), RFC2132, RFC2131.
 283 .SH AUTHOR
 284 .B dhcpd(8)
 285 was written by Ted Lemon
 286 under a contract with Vixie Labs.   Funding
 287 for this project was provided by Internet Systems Consortium.
 288 Information about Internet Systems Consortium can be found at:
 289 .B https://www.isc.org/