Annotation of embedaddon/dhcp/server/dhcpd.leases.5, revision 1.1
1.1 ! misho 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.12.8.3.10.2 2011-09-19 00:23:44 sar 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: .RE
! 281: .SH FILES
! 282: .B DBDIR/dhcpd.leases DBDIR/dhcpd.leases~
! 283: .SH SEE ALSO
! 284: dhcpd(8), dhcp-options(5), dhcp-eval(5), dhcpd.conf(5), RFC2132, RFC2131.
! 285: .SH AUTHOR
! 286: .B dhcpd(8)
! 287: was written by Ted Lemon
! 288: under a contract with Vixie Labs. Funding
! 289: for this project was provided by Internet Systems Consortium.
! 290: Information about Internet Systems Consortium can be found at:
! 291: .B https://www.isc.org/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to dhcpd.leases.5 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / dhcp / server