Document events that cause leases to be written.

Document lease time zones.
Further document abandoned leases.

1 files changed, 34 insertions, 16 deletions

diff --git a/server/dhcpd.leases.5 b/server/dhcpd.leases.5
index 291407c6..b579c29d 100644
--- a/server/dhcpd.leases.5
+++ b/server/dhcpd.leases.5
@@ -1,6 +1,6 @@
-.\"	dhcpd.conf.5
+.\"	dhcpd.leases.5
 .\"
-.\" Copyright (c) 1997 The Internet Software Consortium.
+.\" Copyright (c) 1997, 1998 The Internet Software Consortium.
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -41,10 +41,10 @@ dhcpd.leases - DHCP client lease database
 .SH DESCRIPTION
 The Internet Software Consortium DHCP Server keeps a persistent
 database of leases that it has assigned.  This database is a free-form
-ASCII file containing one valid declaration per lease.  If more than
-one declaration appears for a given lease, the last one in the file is
-used.  The file is written as a log, so this is not an unusual
-occurrance.
+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.
 .PP
 When dhcpd is first installed, there is no lease database.   However,
 dhcpd requires that a lease database be present before it will start.
@@ -97,13 +97,20 @@ hour\fB:\fIminute\fB:\fIsecond\fR
 .PP
 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.  When declaring a predefined lease, it can always be
-specified as zero.  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
-second also a number between 0 and 59.
+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 second also a number between
+0 and 59.
+.PP
+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 probably 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 \fBdate -u\fR.
 .PP
 The MAC address of the network interface that was used to acquire the
 lease is recorded with the \fBhardware\fR statement:
@@ -138,11 +145,22 @@ 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 \fBabandoned\fR statement will be used to
-indicate that the lease should never again be assigned.   Abandoned
-leases must currently be reclaimed by stopping the server, editing the
-abandoned lease out of the lease file, and restarting the server.
+indicate that the lease should not be reassigned.
 .PP
  \fBabandoned;\fR
+.PP
+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.
+.PP
+If a client \fBrequests\fR 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 immediately assigned to the client.
 .SH FILES
 .B DBDIR/dhcpd.leases
 .SH SEE ALSO