manual/dhcp/original/man5/dhcpd.leases.5

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