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

FORMAT

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

THE LEASE DECLARATION

54       lease ip-address { statements... }
55
56       Each lease declaration includes the single IP  address  that  has  been
57       leased  to  the  client.    The statements within the braces define the
58       duration of the lease and to whom it is assigned.
59
60       starts date;
61       ends date;
62       tstp date;
63       tsfp date;
64       atsfp date;
65       cltt date;
66
67       The start and end time of a lease are recorded  using  the  starts  and
68       ends statements.   The tstp statement is specified if the failover pro‐
69       tocol is being used, and indicates what time the peer has been told the
70       lease  expires.    The tsfp statement is also specified if the failover
71       protocol is being used, and indicates the lease expiry  time  that  the
72       peer  has  acknowledged.   The  atsfp statement is the actual time sent
73       from the failover partner.  The cltt statement  is  the  client's  last
74       transaction time.
75
76       The date is specified in two ways, depending on the configuration value
77       for the db-time-format parameter.  If it was set to default,  then  the
78       date fields appear as follows:
79
80       weekday year/month/day hour:minute:second
81
82       The weekday is present to make it easy for a human to tell when a lease
83       expires - it's specified as a number from zero to six, with zero  being
84       Sunday.   The  day  of week is ignored on input.  The year is specified
85       with the century, so it should generally  be  four  digits  except  for
86       really long leases.  The month is specified as a number starting with 1
87       for January.  The day of the month is likewise specified starting  with
88       1.   The hour is a number between 0 and 23, the minute a number between
89       0 and 59, and the second also a number between 0 and 59.
90
91       Lease times are specified in Universal Coordinated Time (UTC),  not  in
92       the  local time zone.  There is probably nowhere in the world where the
93       times recorded on a lease are always the same as wall clock times.   On
94       most  unix  machines, you can display the current time in UTC by typing
95       date -u.
96
97       If the db-time-format was configured to local,  then  the  date  fields
98       appear as follows:
99
100        epoch  <seconds-since-epoch>;  #  <day-name> <month-name> <day-number>
101       <hours>:<minutes>:<seconds> <year>
102
103       The seconds-since-epoch is as according to  the  system's  local  clock
104       (often  referred  to  as "unix time").  The # symbol supplies a comment
105       that describes what actual time this is as according  to  the  system's
106       configured timezone, at the time the value was written.  It is provided
107       only for human inspection.
108
109       If a lease will never expire, date is never instead of an actual date.
110
111       hardware hardware-type mac-address;
112
113       The hardware statement records the MAC address of the network interface
114       on which the lease will be used.   It is specified as a series of hexa‐
115       decimal octets, separated by colons.
116
117       uid client-identifier;
118
119       The uid statement records the client identifier used by the  client  to
120       acquire  the  lease.    Clients are not required to send client identi‐
121       fiers, and this statement only appears if the client did in  fact  send
122       one.    Client  identifiers  are  normally an ARP type (1 for ethernet)
123       followed by the MAC address, just like in the hardware  statement,  but
124       this is not required.
125
126       The client identifier is recorded as a colon-separated hexadecimal list
127       or as a quoted string.   If it is recorded as a quoted  string  and  it
128       contains  one  or  more  non-printable characters, those characters are
129       represented as octal escapes - a backslash character followed by  three
130       octal digits.
131
132       client-hostname hostname ;
133
134       Most DHCP clients will send their hostname in the host-name option.  If
135       a client sends its hostname in this way, the hostname  is  recorded  on
136       the  lease  with a client-hostname statement.   This is not required by
137       the protocol, however, so many specialized DHCP clients do not  send  a
138       host-name option.
139
140       abandoned;
141
142       The  abandoned  statement  indicates that the DHCP server has abandoned
143       the lease.   In that case, the abandoned  statement  will  be  used  to
144       indicate  that  the  lease  should  not  be reassigned.  Please see the
145       dhcpd.conf(5) manual page for information about abandoned leases.
146
147       binding state state; next binding state state;
148
149       The binding state statement declares the lease's binding  state.   When
150       the  DHCP  server  is  not  configured  to use the failover protocol, a
151       lease's binding state will be either active  or  free.    The  failover
152       protocol  adds  some  additional  transitional  states,  as well as the
153       backup state, which indicates that the lease is available  for  alloca‐
154       tion by the failover secondary.
155
156       The  next  binding  state statement indicates what state the lease will
157       move to when the current state expires.   The  time  when  the  current
158       state expires is specified in the ends statement.
159
160       option agent.circuit-id string; option agent.remote-id string;
161
162       The  option  agent.circuit-id and option agent.remote-id statements are
163       used to record the circuit ID and remote ID options send by  the  relay
164       agent,  if  the  relay  agent  uses the relay agent information option.
165       This allows these options to be used consistently in conditional evalu‐
166       ations  even  when  the client is contacting the server directly rather
167       than through its relay agent.
168
169       set variable = value;
170
171       The set statement sets the value of a variable on the lease.  For  gen‐
172       eral information on variables, see the dhcp-eval(5) manual page.
173
174       The ddns-text variable
175
176       The  ddns-text variable is used to record the value of the client's TXT
177       identification record when the interim ddns update style has been  used
178       to update the DNS for a particular lease.
179
180       The ddns-fwd-name variable
181
182       The ddns-fwd-name variable records the value of the name used in updat‐
183       ing the client's A record if a DDNS update has been  successfully  done
184       by  the server.   The server may also have used this name to update the
185       client's PTR record.
186
187       The ddns-client-fqdn variable
188
189       If the server is configured to use the interim ddns update  style,  and
190       is  also configured to allow clients to update their own fqdns, and the
191       client did in fact update its own fqdn, then the ddns-client-fqdn vari‐
192       able records the name that the client has indicated it is using.   This
193       is the name that the server will have used to update the  client's  PTR
194       record in this case.
195
196       The ddns-rev-name variable
197
198       If  the server successfully updates the client's PTR record, this vari‐
199       able will record the name that the DHCP server used for the PTR record.
200       The  name  to  which the PTR record points will be either the ddns-fwd-
201       name or the ddns-client-fqdn.
202
203       The vendor-class-identifier variable
204
205       The server retains the client-supplied Vendor Class  Identifier  option
206       for  informational  purposes,  and  to  render  them  in DHCPLEASEQUERY
207       responses.
208
209       on events { statements... } The on statement records a list  of  state‐
210       ments  to execute if a certain event occurs.   The possible events that
211       can occur for an active lease are release and expiry.   More  than  one
212       event can be specified - if so, the events are separated by '|' charac‐
213       ters.
214
215       bootp; reserved;  These  two  statements  are  effectively  flags.   If
216       present,  they  indicate  that  the  BOOTP and RESERVED failover flags,
217       respectively, should be set.  BOOTP and  RESERVED  dynamic  leases  are
218       treated  differently  than  normal  dynamic leases, as they may only be
219       used by the client to which they are currently allocated.
220

THE FAILOVER PEER STATE DECLARATION

222       The state of any failover peering arrangements is also recorded in  the
223       lease file, using the failover peer statement:
224
225       failover peer name state {
226       my state state at date;
227       peer state state at date;
228       }
229
230       The  states  of the peer named name is being recorded.   Both the state
231       of the running server (my state) and the other failover  partner  (peer
232       state)  are  recorded.    The  following  states are possible: unknown-
233       state, partner-down,  normal,  communications-interrupted,  resolution-
234       interrupted,   potential-conflict,   recover,  recover-done,  shutdown,
235       paused, and startup.
236

FILES

238       /var/lib/dhcpd/dhcpd.leases /var/lib/dhcpd/dhcpd.leases~
239

SEE ALSO

241       dhcpd(8),  dhcp-options(5),   dhcp-eval(5),   dhcpd.conf(5),   RFC2132,
242       RFC2131.
243

AUTHOR

245       dhcpd(8)  was  written  by  Ted Lemon under a contract with Vixie Labs.
246       Funding for this project was provided by Internet  Systems  Consortium.
247       Information   about  Internet  Systems  Consortium  can  be  found  at:
248       https://www.isc.org/
249
250
251
252                                                               dhcpd.leases(5)
Impressum