dhcpd.leases(5)
- NetBSD Manual Pages
dhcpd.leases(5) dhcpd.leases(5)
NAME
dhcpd.leases - DHCP client lease database
DESCRIPTION
The Internet Software Consortium DHCP Server keeps a per-
sistent database of leases that it has assigned. This
database is a free-form ASCII file containing a series of
lease declarations. Every time a lease is acquired,
renewed or released, its new value is recorded at the end
of the lease file. So if more than one declaration
appears for a given lease, the last one in the file is the
current one.
When dhcpd is first installed, there is no lease database.
However, dhcpd requires that a lease database be present
before it will start. To make the initial lease database,
just create an empty file called /var/db/dhcpd.leases.
You can do this with:
touch DBDIR/dhcpd.leases
In order to prevent the lease database from growing with-
out bound, the file is rewritten from time to time.
First, a temporary lease database is created and all known
leases are dumped to it. Then, the old lease database is
renamed /var/db/dhcpd.leases~. Finally, the newly writ-
ten lease database is moved into place.
FORMAT
Lease descriptions are stored in a format that is parsed
by the same recursive descent parser used to read the
dhcpd.conf(5) and dhclient.conf(5) files. Lease files can
contain lease declarations, and also group and subgroup
declarations, host declarations and failover state decla-
rations. Group, subgroup and host declarations are used
to record objects created using the OMAPI protocol.
The lease file is a log-structured file - whenever a lease
changes, the contents of that lease are written to the end
of the file. This means that it is entirely possible and
quite reasonable for there to be two or more declarations
of the same lease in the lease file at the same time. In
that case, the instance of that particular lease that
appears last in the file is the one that is in effect.
Group, subgroup and host declarations in the lease file
are handled in the same manner, except that if any of
these objects are deleted, a rubout is written to the
lease file. This is just the same declaration, with {
deleted; } in the scope of the declaration. When the
lease file is rewritten, any such rubouts that can be
eliminated are eliminated. It is possible to delete a
declaration in the dhcpd.conf file; in this case, the
rubout can never be eliminated from the dhcpd.leases file.
1
dhcpd.leases(5) dhcpd.leases(5)
THE LEASE DECLARATION
lease ip-address { statements... }
Each lease declaration include the single IP address that
has been leased to the client. The statements within the
braces define the duration of the lease and to whom it is
assigned.
starts date;
ends date;
tstp date;
tsfp date;
The start and end time of a lease are recorded using the
starts and ends statements. The tstp statement is speci-
fied if the failover protocol is being used, and indicates
what time the peer has been told the lease expires. The
tsfp statement is also specified if the failover protocol
is being used, and indicates the lease expiry time that
the peer has acknowledged. The date is specified as fol-
lows:
weekday year/month/day hour:minute:second
The weekday is present to make it easy for a human to tell
when a lease expires - it's specified as a number from
zero to six, with zero being Sunday. The day of week is
ignored on input. The year is specified with the century,
so it should generally be four digits except for really
long leases. The month is specified as a number starting
with 1 for January. The day of the month is likewise
specified starting with 1. The hour is a number between 0
and 23, the minute a number between 0 and 59, and the sec-
ond also a number between 0 and 59.
Lease times are specified in Coordinated Universal Time
(UTC), not in the local time zone. There is probably
nowhere in the world where the times recorded on a lease
are always the same as wall clock times. On most unix
machines, you can display the current time in UTC by typ-
ing date -u.
If a lease will never expire, date is never instead of an
actual date.
hardware hardware-type mac-address;
The hardware statement records the MAC address of the net-
work interface on which the lease will be used. It is
specified as a series of hexadecimal octets, separated by
colons.
uid client-identifier;
2
dhcpd.leases(5) dhcpd.leases(5)
The uid statement records the client identifier used by
the client to acquire the lease. Clients are not
required to send client identifiers, and this statement
only appears if the client did in fact send one. Client
identifiers are normally an ARP type (1 for ethernet) fol-
lowed by the MAC address, just like in the hardware state-
ment, but this is not required.
The client identifier is recorded as a colon-separated
hexadecimal list or as a quoted string. If it is
recorded as a quoted string and it contains one or more
non-printable characters, those characters are represented
as octal escapes - a backslash character followed by three
octal digits.
client-hostname hostname ;
Most DHCP clients will send their hostname in the host-
name option. If a client sends its hostname in this way,
the hostname is recorded on the lease with a client-host-
name statement. This is not required by the protocol,
however, so many specialized DHCP clients do not send a
host-name option.
abandoned;
The abandoned statement indicates that the DHCP server has
abandoned the lease. In that case, the abandoned state-
ment will be used to indicate that the lease should not be
reassigned. Please see the dhcpd.conf(5) manual page for
information about abandoned leases.
binding state state; next binding state state;
The binding state statement declares the lease's binding
state. When the DHCP server is not configured to use the
failover protocol, a lease's binding state will be either
active or free. The failover protocol adds some addi-
tional transitional states, as well as the backup state,
which indicates that the lease is available for allocation
by the failover secondary.
The next binding state statement indicates what state the
lease will move to when the current state expires. The
time when the current state expires is specified in the
ends statement.
option agent.circuit-id string; option agent.remote-id
string;
The option agent.circuit-id and option agent.remote-id
statements are used to record the circuit ID and remote ID
options send by the relay agent, if the relay agent uses
the relay agent information option. This allows these
3
dhcpd.leases(5) dhcpd.leases(5)
options to be used consistently in conditional evaluations
even when the client is contacting the server directly
rather than through its relay agent.
set variable = value;
The set statement sets the value of a variable on the
lease. For general information on variables, see the
dhcp-eval(5) manual page.
The ddns-text variable
The ddns-text variable is used to record the value of the
client's TXT identification record when the interim ddns
update style has been used to update the DNS for a partic-
ular lease.
The ddns-fwd-name variable
The ddns-fwd-name variable records the value of the name
used in updating the client's A record if a DDNS update
has been successfully done by the server. The server may
also have used this name to update the client's PTR
record.
The ddns-client-fqdn variable
If the server is configured to use the interim ddns update
style, and is also configured to allow clients to update
their own fqdns, and the client did in fact update its own
fqdn, then the ddns-client-fqdn variable records the name
that the client has indicated it is using. This is the
name that the server will have used to update the client's
PTR record in this case.
The ddns-rev-name variable
If the server successfully updates the client's PTR
record, this variable will record the name that the DHCP
server used for the PTR record. The name to which the
PTR record points will be either the ddns-fwd-name or the
ddns-client-fqdn.
on events { statements... } The on statement records a
list of statements to execute if a certain event occurs.
The possible events that can occur for an active lease are
release and expiry. More than one event can be specified
- if so, the events are separated by '|' characters.
THE FAILOVER PEER STATE DECLARATION
The state of any failover peering arrangements is also
recorded in the lease file, using the failover peer state-
ment:
4
dhcpd.leases(5) dhcpd.leases(5)
failover peer name state {
my state state at date;
peer state state at date;
}
The states of the peer named name is being recorded.
Both the state of the running server (my state) and the
other failover partner (peer state) are recorded. The
following states are possible: unknown-state, partner-
down, normal, communications-interrupted, resolution-
interrupted, potential-conflict, recover, recover-done,
shutdown, paused, and startup. DBDIR/dhcpd.leases
SEE ALSO
dhcpd(8), dhcp-options(5), dhcp-eval(5), dhcpd.conf(5),
RFC2132, RFC2131.
AUTHOR
dhcpd(8) was written by Ted Lemon under a contract with
Vixie Labs. Funding for this project was provided by the
Internet Software Consortium. Information about the
Internet Software Consortium can be found at:
http://www.isc.org/
5
Powered by man-cgi (2024-03-20).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.