Annotation of embedaddon/dhcp/server/dhcpd.leases.5, revision 1.1.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: .\"
1.1.1.1 ! misho 31: .\" $Id: dhcpd.leases.5,v 1.12.8.3.10.2 2011/09/19 00:23:44 sar Exp $
1.1 misho 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