dhcpd.8

DHCP服务器源码

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 THE CONTROL OBJECT
The control object allows you to shut the server down.   If the server
is doing failover with another peer, it will make a clean transition
into the shutdown state and notify its peer, so that the peer can go
into partner down, and then record the "recover" state in the lease
file so that when the server is restarted, it will automatically
resynchronize with its peer.
.PP
On shutdown the server will also attempt to cleanly shut down all
OMAPI connections.  If these connections do not go down cleanly after
five seconds, they are shut down pre-emptively.  It can take as much
as 25 seconds from the beginning of the shutdown process to the time
that the server actually exits.
.PP
To shut the server down, open its control object and set the state
attribute to 2.
.SH THE FAILOVER-STATE OBJECT
The failover-state object is the object that tracks the state of the
failover protocol as it is being managed for a given failover peer.
The failover object has the following attributes (please see
.B dhcpd.conf (5)
for explanations about what these attributes mean):
.PP
.B name \fIdata\fR examine
.RS 0.5i
Indicates the name of the failover peer relationship, as described in
the server's \fBdhcpd.conf\fR file.
.RE
.PP
.B partner-address \fIdata\fR examine
.RS 0.5i
Indicates the failover partner's IP address.
.RE
.PP
.B local-address \fIdata\fR examine
.RS 0.5i
Indicates the IP address that is being used by the DHCP server for
this failover pair.
.RE
.PP
.B partner-port \fIdata\fR examine
.RS 0.5i
Indicates the TCP port on which the failover partner is listening for
failover protocol connections.
.RE
.PP
.B local-port \fIdata\fR examine
.RS 0.5i
Indicates the TCP port on which the DHCP server is listening for
failover protocol connections for this failover pair.
.RE
.PP
.B max-outstanding-updates \fIinteger\fR examine
.RS 0.5i
Indicates the number of updates that can be outstanding and
unacknowledged at any given time, in this failover relationship.
.RE
.PP
.B mclt \fIinteger\fR examine
.RS 0.5i
Indicates the maximum client lead time in this failover relationship.
.RE
.PP
.B load-balance-max-secs \fIinteger\fR examine
.RS 0.5i
Indicates the maximum value for the secs field in a client request
before load balancing is bypassed.
.RE
.PP
.B load-balance-hba \fIdata\fR examine
.RS 0.5i
Indicates the load balancing hash bucket array for this failover
relationship.
.RE
.PP
.B local-state \fIinteger\fR examine, modify
.RS 0.5i
Indicates the present state of the DHCP server in this failover
relationship.   Possible values for state are:
.RE
.RS 1i
.PP
.nf
1  - partner down
2  - normal
3  - communications interrupted
4  - resolution interrupted
5  - potential conflict
6  - recover
7  - recover done
8  - shutdown
9  - paused
10 - startup
11 - recover wait
.fi
.RE
.PP
.RS 0.5i
In general it is not a good idea to make changes to this state.
However, in the case that the failover partner is known to be down, it
can be useful to set the DHCP server's failover state to partner
down.   At this point the DHCP server will take over service of the
failover partner's leases as soon as possible, and will give out
normal leases, not leases that are restricted by MCLT.   If you do put
the DHCP server into the partner-down when the other DHCP server is
not in the partner-down state, but is not reachable, IP address
assignment conflicts are possible, even likely.   Once a server has
been put into partner-down mode, its failover partner must not be
brought back online until communication is possible between the two
servers.
.RE
.PP
.B partner-state \fIinteger\fR examine
.RS 0.5i
Indicates the present state of the failover partner.
.RE
.PP
.B local-stos \fIinteger\fR examine
.RS 0.5i
Indicates the time at which the DHCP server entered its present state
in this failover relationship.
.RE
.PP
.B partner-stos \fIinteger\fR examine
.RS 0.5i
Indicates the time at which the failover partner entered its present state.
.RE
.PP
.B hierarchy \fIinteger\fR examine
.RS 0.5i
Indicates whether the DHCP server is primary (0) or secondary (1) in
this failover relationship.
.RE
.PP
.B last-packet-sent \fIinteger\fR examine
.RS 0.5i
Indicates the time at which the most recent failover packet was sent
by this DHCP server to its failover partner.
.RE
.PP
.B last-timestamp-received \fIinteger\fR examine
.RS 0.5i
Indicates the timestamp that was on the failover message most recently
received from the failover partner.
.RE
.PP
.B skew \fIinteger\fR examine
.RS 0.5i
Indicates the skew between the failover partner's clock and this DHCP
server's clock
.RE
.PP
.B max-response-delay \fIinteger\fR examine
.RS 0.5i
Indicates the time in seconds after which, if no message is received
from the failover partner, the partner is assumed to be out of
communication.
.RE
.PP
.B cur-unacked-updates \fIinteger\fR examine
.RS 0.5i
Indicates the number of update messages that have been received from
the failover partner but not yet processed.
.RE
.SH FILES
.B ETCDIR/dhcpd.conf, DBDIR/dhcpd.leases, RUNDIR/dhcpd.pid,
.B DBDIR/dhcpd.leases~.
.SH SEE ALSO
dhclient(8), dhcrelay(8), dhcpd.conf(5), dhcpd.leases(5)
.SH AUTHOR
.B dhcpd(8)
was originally written by Ted Lemon under a contract with Vixie Labs.
Funding for this project was provided by Internet Systems
Consortium.   Version 3 of the DHCP server was funded by Nominum, Inc.
Information about Internet Systems Consortium is available at
.B http://www.isc.org/\fR.
Information about Nominum can be found at \fBhttp://www.nominum.com/\fR.