Update/fix documentation.V3_RC4

2 files changed, 239 insertions, 5 deletions

diff --git a/server/dhcpd.8 b/server/dhcpd.8
index 45b8213a..1ec659b0 100644
--- a/server/dhcpd.8
+++ b/server/dhcpd.8
@@ -361,6 +361,204 @@ use a different name server might be declared as follows:
 .PP
 A more complete description of the dhcpd.conf file syntax is provided
 in dhcpd.conf(5).
+.SH OMAPI
+The DHCP server provides the capability to modify some of its
+configuration while it is running, without stopping it, modifying its
+database files, and restarting it.  This capability is currently
+provided using OMAPI - an API for manipulating remote objects.  OMAPI
+clients connect to the server using TCP/IP, authenticate, and can then
+examine the server's current status and make changes to it.
+.PP
+Rather than implementing the underlying OMAPI protocol directly, user
+programs should use the dhcpctl API or OMAPI itself.   Dhcpctl is a
+wrapper that handles some of the housekeeping chores that OMAPI does
+not do automatically.   Dhcpctl and OMAPI are documented in \fBdhcpctl(3)\fR
+and \fBomapi(3)\fR.
+.PP
+OMAPI exports objects, which can then be examined and modified.   The
+DHCP server exports the following objects: lease, host,
+failover-state and group.   Each object has a number of methods that
+are provided: lookup, create, and destroy.   In addition, it is
+possible to look at attributes that are stored on objects, and in some
+cases to modify those attributes.
+.SH THE LEASE OBJECT
+Leases can't currently be created or destroyed, but they can be looked
+up to examine and modify their state.
+.PP
+Leases have the following attributes:
+.PP
+.B state \fIinteger\fR lookup, examine
+.RS 0.5i
+.nf
+1 = free
+2 = active
+3 = expired
+4 = released
+5 = abandoned
+6 = reset
+7 = backup
+8 = reserved
+9 = bootp
+.fi
+.RE
+.PP
+.B ip-address \fIdata\fR lookup, examine
+.RS 0.5i
+The IP address of the lease.
+.RE
+.PP
+.B dhcp-client-identifier \fIdata\fR lookup, examine, update
+.RS 0.5i
+The
+client identifier that the client used when it acquired the lease.
+Not all clients send client identifiers, so this may be empty.
+.RE
+.PP
+.B client-hostname \fIdata\fR examine, update
+.RS 0.5i
+The value the client sent in the host-name option.
+.RE
+.PP
+.B host \fIhandle\fR examine
+.RS 0.5i
+the host declaration associated with this lease, if any.
+.RE
+.PP
+.B subnet \fIhandle\fR examine
+.RS 0.5i
+the subnet object associated with this lease (the subnet object is not
+currently supported).
+.RE
+.PP
+.B pool \fIhandle\fR examine
+.RS 0.5i
+the pool object associted with this lease (the pool object is not
+currently supported).
+.RE
+.PP
+.B billing-class \fIhandle\fR examine
+.RS 0.5i
+the handle to the class to which this lease is currently billed, if
+any (the class object is not currently supported).
+.RE
+.PP
+.B hardware-address \fIdata\fR examine, update
+.RS 0.5i
+the hardware address (chaddr) field sent by the client when it
+acquired its lease.
+.RE
+.PP
+.B hardware-type \fIinteger\fR examine, update
+.RS 0.5i
+the type of the network interface that the client reported when it
+acquired its lease.
+.RE
+.PP
+.B ends \fItime\fR examine
+.RS 0.5i
+the time when the lease's current state ends, as understood by the
+client.
+.RE
+.PP
+.B tstp \fItime\fR examine
+.RS 0.5i
+the time when the lease's current state ends, as understood by the
+server.
+.RE
+.B tsfp \fItime\fR examine
+.RS 0.5i
+the time when the lease's current state ends, as understood by the
+failover peer (if there is no failover peer, this value is
+undefined).
+.RE
+.PP
+.B cltt \fItime\fR examine
+.RS 0.5i
+The time of the last transaction with the client on this lease.
+.RE
+.SH THE HOST OBJECT
+Hosts can be created, destroyed, looked up, examined and modified.
+If a host declaration is created or deleted using OMAPI, that
+information will be recorded in the dhcpd.leases file.   It is
+permissible to delete host declarations that are declared in the
+dhcpd.conf file.
+.PP
+Hosts have the following attributes:
+.PP
+.B name \fIdata\fR lookup, examine, modify
+.RS 0.5i
+the name of the host declaration.   This name must be unique among all
+host declarations.
+.RE
+.PP
+.B group \fIhandle\fR examine, modify
+.RS 0.5i
+the named group associated with the host declaration, if there is one.
+.RE
+.PP
+.B hardware-address \fIdata\fR lookup, examine, modify
+.RS 0.5i
+the link-layer address that will be used to match the client, if any.
+Only valid if hardware-type is also present.
+.RE
+.PP
+.B hardware-type \fIinteger\fR lookup, examine, modify
+.RS 0.5i
+the type of the network interface that will be used to match the
+client, if any.   Only valid if hardware-address is also present.
+.RE
+.PP
+.B dhcp-client-identifier \fIdata\fR lookup, examine, modify
+.RS 0.5i
+the dhcp-client-identifier option that will be used to match the
+client, if any.
+.RE
+.PP
+.B ip-address \fIdata\fR examine, modify
+.RS 0.5i
+a fixed IP address which is reserved for a DHCP client that matches
+this host declaration.   The IP address will only be assigned to the
+client if it is valid for the network segment to which the client is
+connected.
+.RE
+.PP
+.B statements \fIdata\fR modify
+.RS 0.5i
+a list of statements in the format of the dhcpd.conf file that will be
+executed whenever a message from the client is being processed.
+.RE
+.PP
+.B known \fIinteger\fR examine, modify
+.RS 0.5i
+if nonzero, indicates that a client matching this host declaration
+will be treated as \fIknown\fR in pool permit lists.   If zero, the
+client will not be treated as known.
+.RE
+.SH THE GROUP OBJECT
+Named groups can be created, destroyed, looked up, examined and
+modified.  If a group declaration is created or deleted using OMAPI,
+that information will be recorded in the dhcpd.leases file.  It is
+permissible to delete group declarations that are declared in the
+dhcpd.conf file.
+.PP
+Named groups currently can only be associated with
+hosts - this allows one set of statements to be efficiently attached
+to more than one host declaration.   
+.PP
+Groups have the following attributes:
+.PP
+.B name \fIdata\fR
+.RS 0.5i
+the name of the group.  All groups that are created using OMAPI must
+have names, and the names must be unique among all groups.
+.RE
+.PP
+.B statements \fIdata\fR
+.RS 0.5i
+a list of statements in the format of the dhcpd.conf file that will be
+executed whenever a message from a client whose host declaration
+references this group is processed.
+.RE
 .SH FILES
 .B ETCDIR/dhcpd.conf, DBDIR/dhcpd.leases, RUNDIR/dhcpd.pid,
 .B DBDIR/dhcpd.leases~.
@@ -368,8 +566,10 @@ in dhcpd.conf(5).
 dhclient(8), dhcrelay(8), dhcpd.conf(5), dhcpd.leases(5)
 .SH AUTHOR
 .B 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 Consortium.
-Information about the Internet Software Consortium can be found at
-.B http://www.isc.org/isc.
+was originally written by Ted Lemon under a contract with Vixie Labs.
+Funding for this project was provided by the Internet Software
+Consortium.   Version 3 of the DHCP server was funded by Nominum, Inc.
+Information about the Internet Software Consortium is available at
+.B http://www.isc.org/isc\fR.
+Information about Nominum and support contracts for DHCP and BIND can
+be found at \fBhttp://www.nominum.com\fR.
diff --git a/server/dhcpd.conf.5 b/server/dhcpd.conf.5
index 7ac7b8a4..1e842ba6 100644
--- a/server/dhcpd.conf.5
+++ b/server/dhcpd.conf.5
@@ -459,6 +459,37 @@ providing a way for each peer to behave in the opposite way from the
 other.   So one server must be configured as primary, and the other
 must be configured as secondary, and it doesn't matter too much which
 one is which.
+.SH FAILOVER STARTUP
+When a server starts that has not previously communicated with its
+failover peer, it must establish communications with its failover peer
+and synchronize with it before it can serve clients.   This can happen
+either because you have just configured your DHCP servers to perform
+failover for the first time, or because one of your failover servers
+has failed catastrophically and lost its database.
+.PP
+The initial recovery process is designed to ensure that when one
+failover peer loses its database and then resynchronizes, any leases
+that the failed server gave out before it failed will be honored.
+When the failed server starts up, it notices that it has no saved
+failover state, and attempts to contact its peer.
+.PP
+When it has established contact, it asks the peer for a complete copy
+its peer's lease database.  The peer then sends its complete database,
+and sends a message indicating that it is done.  The failed server
+then waits until MCLT has passed, and once MCLT has passed both
+servers make the transition back into normal operation.  This waiting
+period ensures that any leases the failed server may have given out
+while out of contact with its partner will have expired.
+.PP
+While the failed server is recovering, its partner remains in the
+partner-down state, which means that it is serving all clients.  The
+failed server provides no service at all to DHCP clients until it has
+made the transition into normal operation.
+.PP
+In the case where both servers detect that they have never before
+communicated with their partner, they both come up in this recovery
+state and follow the procedure we have just described.   In this case,
+no service will be provided to DHCP clients until MCLT has expired.
 .SH CONFIGURING FAILOVER
 In order to configure failover, you need to write a peer declaration
 that configures the failover protocol, and you need to write peer
@@ -2106,6 +2137,7 @@ works around a problem with relay agent information options, which is
 that they usually not appear in DHCPREQUEST messages sent by the
 client in the RENEWING state, because such messages are unicast
 directly to the server and not sent through a relay agent.
+.RE
 .PP
 The
 .I update-optimization
@@ -2126,6 +2158,7 @@ and has no effect on the ad-hoc DNS update scheme.   If this
 parameter is not specified, or is false, the DHCP server will only
 update when the client information changes, the client gets a
 different lease, or the client's lease expires.
+.RE
 .PP
 The
 .I update-static-leases
@@ -2144,6 +2177,7 @@ has been done, and therefore will not delete the record when it is not
 in use.   Also, the server must attempt the update each time the
 client renews its lease, which could have a significant performance
 impact in environments that place heavy demands on the DHCP server.
+.RE
 .PP
 The
 .I use-host-decl-names