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 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  DBDIR/dhcpd.leases~.   Finally, the newly written
       lease database is moved into place.

       There is a window of vulnerability where if the dhcpd pro­
       cess  is  killed or the system crashes after the old lease
       database has been renamed but before the new one has  been
       moved  into  place,  there  will be no DBDIR/dhcpd.leases.
       In this case, dhcpd will refuse to start, and will require
       manual  intervention.    DO  NOT simply create a new lease
       file when this happens - if you do, you will lose all your
       old  bindings,  and  chaos  will  ensue.   Instead, rename
       DBDIR/dhcpd.leases~ to DBDIR/dhcpd.leases,  restoring  the
       old,  valid lease file, and then start dhcpd.   This guar­
       antees that a valid lease file will be restored.

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.   Currently, the
       only  declaration that is used in the dhcpd.leases file is
       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.

       The  start  and end time of a lease are recorded using the
       ``starts'' and ``ends'' statements:

         starts date;
         ends date;

       Dates are specified as follows:

        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 Greenwich Mean Time (GMT),
       not in the local time zone.   Since Greenwich is  actually
       on Daylight Savings Time part of the year, there is proba­
       bly nowhere in the world where the  times  recorded  on  a
       lease  are always the same as wall clock times.  On a unix
       machine, one can often figure out the current time in  GMT
       by typing date -u.

       The  MAC address of the network interface that was used to
       acquire the lease is recorded with the hardware statement:

        hardware hardware-type mac-address;

       The  MAC  address  is specified as a series of hexadecimal
       octets, seperated by colons.

       If the client used a  client  identifier  to  acquire  its
       address,  the  client identifier is recorded using the uid
       statement:

        uid client-identifier;

       The client identifier is recorded as a series of hexadeci­
       mal  octets, regardless of whether the client specifies an
       ASCII string or uses the newer hardware  type/MAC  address
       format.

       If  the  client sends a hostname using the Client Hostname
       option, as specified in  some  versions  of  the  DHCP-DNS
       Interaction  draft,  that  hostname  is recorded using the
       client-hostname statement.

        client-hostname "hostname";

       If the  client  sends  its  hostname  using  the  Hostname
       option,  as  Windows  95  does,  it  is recorded using the
       hostname statement.

        hostname "hostname";

       The DHCP server may determine that a lease has  been  mis­
       used  in  some  way, either because a client that has been
       assigned a lease NAKs it,  or  because  the  server's  own
       attempt to see if an address is in use prior to reusing it
       reveals that the address is in fact already in  use.    In
       that  case,  the abandoned statement will be used to indi­
       cate that the lease should not be reassigned.

        abandoned;

       Abandoned leases are  reclaimed  automatically.    When  a
       client  asks  for a new address, and the server finds that
       there are no new addresses, it checks to see if there  are
       any  abandoned  leases,  and  allocates the least recently
       abandoned lease.   The standard  mechanisms  for  checking
       for  lease address conflicts are still followed, so if the
       abandoned lease's IP address is still in use, it  will  be
       reabandoned.

       If  a  client  requests  an  abandoned address, the server
       assumes that the reason the address was abandoned was that
       the  lease  file was corrupted, and that the client is the
       machine that responded when the lease was probed,  causing
       it to be abandoned.   In that case, the address is immedi­
       ately assigned to the client.

FILES

       DBDIR/dhcpd.leases

SEE ALSO

       dhcpd(8),   dhcp-options(5),    dhcpd.conf(5),    RFC2132,
       RFC2131.

AUTHOR

       dhcpd(8) was written by Ted Lemon <mellon@vix.com> under a
       contract with Vixie Labs.   Funding for this  project  was
       provided  by  the Internet Software Corporation.  Informa­
       tion about the Internet Software Consortium can  be  found
       at http://www.isc.org/isc.