1dhcpd.leases(5)               File Formats Manual              dhcpd.leases(5)
2
3
4

NAME

6       dhcpd.leases - DHCP client lease database
7

DESCRIPTION

9       The Internet Systems Consortium DHCP Server keeps a persistent database
10       of leases that it has assigned.  This database  is  a  free-form  ASCII
11       file  containing a series of lease declarations.  Every time a lease is
12       acquired, renewed or released, its new value is recorded at the end  of
13       the  lease  file.   So if more than one declaration appears for a given
14       lease, the last one in the file is the current one.
15
16       When dhcpd is first installed, there is no lease  database.    However,
17       dhcpd  requires  that a lease database be present before it will start.
18       To make the initial lease database, just create an  empty  file  called
19       /var/lib/dhcpd/dhcpd.leases.   You can do this with:
20
21            touch /var/lib/dhcpd/dhcpd.leases
22
23       In  order to prevent the lease database from growing without bound, the
24       file is rewritten from time to time.   First, a temporary  lease  data‐
25       base  is created and all known leases are dumped to it.   Then, the old
26       lease database is renamed /var/lib/dhcpd/dhcpd.leases~.   Finally,  the
27       newly written lease database is moved into place.
28
29       In  order  to  process both DHCPv4 and DHCPv6 messages you will need to
30       run two separate  instances  of  the  dhcpd  process.   Each  of  these
31       instances will need it's own lease file.  You can use the -lf option on
32       the server's command line to specify a different lease  file  name  for
33       one or both servers.
34

FORMAT

36       Lease  descriptions  are  stored in a format that is parsed by the same
37       recursive  descent  parser  used  to   read   the   dhcpd.conf(5)   and
38       dhclient.conf(5)  files.   Lease  files can contain lease declarations,
39       and  also  group  and  subgroup  declarations,  host  declarations  and
40       failover state declarations.  Group, subgroup and host declarations are
41       used to record objects created using the OMAPI protocol.
42
43       The lease file is a log-structured file - whenever a lease changes, the
44       contents of that lease are written to the end of the file.   This means
45       that it is entirely possible and quite reasonable for there to  be  two
46       or  more  declarations  of the same lease in the lease file at the same
47       time.   In that case,  the  instance  of  that  particular  lease  that
48       appears last in the file is the one that is in effect.
49
50       Group,  subgroup and host declarations in the lease file are handled in
51       the same manner, except that if any of these  objects  are  deleted,  a
52       rubout  is  written to the lease file.   This is just the same declara‐
53       tion, with { deleted; } in the scope of  the  declaration.    When  the
54       lease  file  is  rewritten, any such rubouts that can be eliminated are
55       eliminated.   It is possible to delete a declaration in the  dhcpd.conf
56       file;  in  this  case,  the  rubout  can  never  be eliminated from the
57       dhcpd.leases file.
58

COMMON STATEMENTS FOR LEASE DECLARATIONS

60       While the lease file formats for DHCPv4 and DHCPv6 are  different  they
61       share  many  common  statements and structures.  This section describes
62       the common statements while the succeeding sections describe the proto‐
63       col specific statements.
64
65       Dates
66
67       A  date  is specified in two ways, depending on the configuration value
68       for the db-time-format parameter.  If it was set to default,  then  the
69       date fields appear as follows:
70
71       weekday year/month/day hour:minute:second
72
73       The weekday is present to make it easy for a human to tell when a lease
74       expires - it's specified as a number from zero to six, with zero  being
75       Sunday.   The  day  of week is ignored on input.  The year is specified
76       with the century, so it should generally  be  four  digits  except  for
77       really long leases.  The month is specified as a number starting with 1
78       for January.  The day of the month is likewise specified starting  with
79       1.   The hour is a number between 0 and 23, the minute a number between
80       0 and 59, and the second also a number between 0 and 59.
81
82       Lease times are specified in Universal Coordinated Time (UTC),  not  in
83       the  local time zone.  There is probably nowhere in the world where the
84       times recorded on a lease are always the same as wall clock times.   On
85       most  unix  machines, you can display the current time in UTC by typing
86       date -u.
87
88       If the db-time-format was configured to local,  then  the  date  fields
89       appear as follows:
90
91        epoch  <seconds-since-epoch>;  #  <day-name> <month-name> <day-number>
92       <hours>:<minutes>:<seconds> <year>
93
94       The seconds-since-epoch is as according to  the  system's  local  clock
95       (often  referred  to  as "unix time").  The # symbol supplies a comment
96       that describes what actual time this is as according  to  the  system's
97       configured timezone, at the time the value was written.  It is provided
98       only for human inspection.
99
100       If a lease will never expire, date is never instead of an actual date.
101
102       General Variables
103
104       As part of the processing of a lease information may be attached to the
105       lease  structure,  for example the DDNS information or if you specify a
106       variable in your configuration file.  Some  of  these,  like  the  DDNS
107       information, have specific descriptions below.  For others, such as any
108       you might define, a generic line of the following will be included.
109
110       set variable = value;
111
112       The set statement sets the value of a variable on the lease.  For  gen‐
113       eral information on variables, see the dhcp-eval(5) manual page.
114
115       DDNS Variables
116
117       The ddns-text and ddns-dhcid variables
118
119       These variables are used to record the value of the client's identification
120       record when the server has updated DNS for a particular lease.  The text
121       record is used with the interim DDNS update style while the dhcid record
122       is used for the standard DDNS update style.
123
124       The ddns-fwd-name variable
125
126       This variable records the value of the name used in
127       updating the client's A record if a DDNS update has been successfully
128       done by the server.   The server may also have used this name to
129       update the client's PTR record.
130
131       The ddns-client-fqdn variable
132
133       If the server is configured both to use the interim or standard DDNS update
134       style, and to allow clients to update their own FQDNs, then if the
135       client did in fact update its own FQDN, the
136       ddns-client-fqdn variable records the name that the client has
137       indicated it is using.   This is the name that the server will have
138       used to update the client's PTR record in this case.
139
140       The ddns-rev-name variable
141
142       If the server successfully updates the client's PTR record, this
143       variable will record the name that the DHCP server used for the PTR
144       record.   The name to which the PTR record points will be either the
145       ddns-fwd-name or the ddns-client-fqdn.
146
147       Executable Statements
148
149       on events { statements... }
150       The on statement records a list of statements to execute if a
151       certain event occurs.   The possible events that can occur for an
152       active lease are release and expiry.   More than one event
153       can be specified - if so, the events are separated by '|' characters.
154
155       The authoring-byte-order statement
156
157         authoring-byte-order [ big-endian | little-endian ] ;
158
159         This statement is automatically added to the top of new lease files by
160         the server. It indicates the internal byte order of the server.  This
161         permits lease files generated on a server with one form of byte order
162         to be read by a server with a different form.  Lease files which do not
163         contain this entry are simply treated as having the same byte order as
164         the server reading them.  If you are migrating lease files generated
165         by a server that predates this statement and is of a different byte
166         order than the your destination server, you can manually add this
167         statement.  It must proceed any lease entries.  Valid values for this
168         parameter are little-endian and big-endian.
169

THE DHCPv4 LEASE DECLARATION

171       lease ip-address { statements... }
172
173       Each  lease  declaration  includes  the single IP address that has been
174       leased to the client.   The statements within  the  braces  define  the
175       duration of the lease and to whom it is assigned.
176
177       starts date;
178       ends date;
179       tstp date;
180       tsfp date;
181       atsfp date;
182       cltt date;
183
184       The  start  and  end  time of a lease are recorded using the starts and
185       ends statements.   The tstp statement is present if the failover proto‐
186       col  is  being used, and indicates what time the peer has been told the
187       lease expires.   The tsfp statement is also  present  if  the  failover
188       protocol  is  being  used, and indicates the lease expiry time that the
189       peer has acknowledged.  The atsfp statement is  the  actual  time  sent
190       from  the  failover  partner.   The cltt statement is the client's last
191       transaction time.
192
193       See the description of dates in the section on common structures.
194
195       hardware hardware-type mac-address;
196
197       The hardware statement records the MAC address of the network interface
198       on which the lease will be used.   It is specified as a series of hexa‐
199       decimal octets, separated by colons.
200
201       uid client-identifier;
202
203       The uid statement records the client identifier used by the  client  to
204       acquire  the  lease.    Clients are not required to send client identi‐
205       fiers, and this statement only appears if the client did in  fact  send
206       one.    Client  identifiers  are  normally an ARP type (1 for ethernet)
207       followed by the MAC address, just like in the hardware  statement,  but
208       this is not required.
209
210       The client identifier is recorded as a colon-separated hexadecimal list
211       or as a quoted string.   If it is recorded as a quoted  string  and  it
212       contains  one  or  more  non-printable characters, those characters are
213       represented as octal escapes - a backslash character followed by  three
214       octal  digits.   The  format  used is determined by the lease-id-format
215       parameter, which defaults to octal.
216
217       client-hostname hostname ;
218
219       Most DHCP clients will send their hostname in the host-name option.  If
220       a  client  sends  its hostname in this way, the hostname is recorded on
221       the lease with a client-hostname statement.   This is not  required  by
222       the  protocol,  however, so many specialized DHCP clients do not send a
223       host-name option.
224
225       binding state state;
226       next binding state state;
227
228       The binding state statement declares the lease's binding  state.   When
229       the  DHCP  server  is  not  configured  to use the failover protocol, a
230       lease's binding state may be active, free or abandoned.   The  failover
231       protocol  adds  some  additional  transitional  states,  as well as the
232       backup state, which indicates that the lease is available  for  alloca‐
233       tion  by  the  failover  secondary. Please see the dhcpd.conf(5) manual
234       page for more information about abandoned leases.
235
236       The next binding state statement indicates what state  the  lease  will
237       move  to  when  the  current state expires.   The time when the current
238       state expires is specified in the ends statement.
239
240       rewind binding state state;
241
242       This statement is part of an optimization for use with failover.   This
243       helps a server rewind a lease to the state most recently transmitted to
244       its peer.
245
246       option agent.circuit-id string;
247       option agent.remote-id string;
248
249       These statements are used to  record  the  circuit  ID  and  remote  ID
250       options  sent  by  the  relay  agent, if the relay agent uses the relay
251       agent information option.   This allows these options to be  used  con‐
252       sistently in conditional evaluations even when the client is contacting
253       the server directly rather than through its relay agent.
254
255       The vendor-class-identifier variable
256
257       The server retains the client-supplied Vendor Class  Identifier  option
258       for  informational  purposes,  and  to  render  them  in DHCPLEASEQUERY
259       responses.
260
261       bootp;
262       reserved;
263
264       If present, they indicate that the BOOTP and  RESERVED  failover  flags
265       (respectively)  should  be  set.  BOOTP and RESERVED dynamic leases are
266       treated differently than normal dynamic leases, as  they  may  only  be
267       used by the client to which they are currently allocated.
268
269       Other  Additional options or executable statements may be included, see
270       the description of them in the section on common structures.
271

THE DHCPv6 LEASE (IA) DECLARATION

273       ia_ta  IAID_DUID { statements... }
274       ia_na  IAID_DUID { statements... }
275       ia_pd  IAID_DUID { statements... }
276
277       Each lease declaration starts with a tag indicating  the  type  of  the
278       lease.   ia_ta  is  for temporary addresses, ia_na is for non-temporary
279       addresses and ia_pd is for prefix delegation.  Following  this  tag  is
280       the combined IAID and DUID from the client for this lease.
281
282       The  IAID_DUID  value is recorded as a colon-separated hexadecimal list
283       or as a quoted string.   If it is recorded as a quoted  string  and  it
284       contains  one  or  more  non-printable characters, those characters are
285       represented as octal escapes - a backslash character followed by  three
286       octal  digits.   The  format  used  is  governed by the lease-id-format
287       parameter, which defaults to octal.
288
289       cltt date;
290
291       The cltt statement is the client's last transaction time.
292
293       See the description of dates in the section on common structures.
294
295       iaaddr ipv6-address { statements... }
296       iaprefix ipv6-address/prefix-length { statements... }
297
298       Within a given lease there can be multiple iaaddr and iaprefix statements.
299       Each will have either an IPv6 address or an IPv6 prefix (an address and
300       a prefix length indicating a CIDR style block of addresses).  The following
301       statements may occur Within each iaaddr or iaprefix.
302
303       binding state state;
304
305       The binding state statement declares the lease's binding state.
306       In DHCPv6 you will normally see this as active or expired.
307
308       preferred-life lifetime;
309
310       The IPv6 preferred lifetime associated with this address, in seconds.
311
312       max-life lifetime;
313
314       The valid lifetime associated with this address, in seconds.
315
316       ends date;
317
318       The end time of the lease.  See the description of dates in the section on
319       common structures.
320
321       Additional options or executable statements may be included.  See the description
322       of them in the section on common structures.
323

THE FAILOVER PEER STATE DECLARATION

325       The state of any failover peering arrangements is also recorded in  the
326       lease file, using the failover peer statement:
327
328       failover peer name state {
329       my state state at date;
330       peer state state at date;
331       }
332
333       The  states  of the peer named name is being recorded.   Both the state
334       of the running server (my state) and the other failover  partner  (peer
335       state)  are  recorded.    The  following  states are possible: unknown-
336       state, partner-down,  normal,  communications-interrupted,  resolution-
337       interrupted,   potential-conflict,   recover,  recover-done,  shutdown,
338       paused, and startup.
339

FILES

341       /var/lib/dhcpd/dhcpd.leases /var/lib/dhcpd/dhcpd.leases~
342

SEE ALSO

344       dhcpd(8),  dhcp-options(5),   dhcp-eval(5),   dhcpd.conf(5),   RFC2132,
345       RFC2131.
346

AUTHOR

348       dhcpd(8) is maintained by ISC.  Information about Internet Systems Con‐
349       sortium can be found at: https://www.isc.org/
350
351
352
353                                                               dhcpd.leases(5)
Impressum