735 lines
25 KiB
Groff
735 lines
25 KiB
Groff
.\" dhcpd.8
|
|
.\"
|
|
.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
|
|
.\" Copyright (c) 1996-2003 by Internet Software Consortium
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
|
|
.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.\" Internet Systems Consortium, Inc.
|
|
.\" 950 Charter Street
|
|
.\" Redwood City, CA 94063
|
|
.\" <info@isc.org>
|
|
.\" http://www.isc.org/
|
|
.\"
|
|
.\" This software has been written for Internet Systems Consortium
|
|
.\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
|
|
.\" To learn more about Internet Systems Consortium, see
|
|
.\" ``http://www.isc.org/''. To learn more about Vixie Enterprises,
|
|
.\" see ``http://www.vix.com''. To learn more about Nominum, Inc., see
|
|
.\" ``http://www.nominum.com''.
|
|
.\"
|
|
.\" $Id: dhcpd.8,v 1.7 2005/08/11 17:13:30 drochner Exp $
|
|
.\"
|
|
.TH dhcpd 8
|
|
.SH NAME
|
|
dhcpd - Dynamic Host Configuration Protocol Server
|
|
.SH SYNOPSIS
|
|
.B dhcpd
|
|
[
|
|
.B -p
|
|
.I port
|
|
]
|
|
[
|
|
.B -f
|
|
]
|
|
[
|
|
.B -d
|
|
]
|
|
[
|
|
.B -q
|
|
]
|
|
[
|
|
.B -t
|
|
|
|
|
.B -T
|
|
]
|
|
[
|
|
.B -cf
|
|
.I config-file
|
|
]
|
|
[
|
|
.B -lf
|
|
.I lease-file
|
|
]
|
|
[
|
|
.B -tf
|
|
.I trace-output-file
|
|
]
|
|
[
|
|
.B -play
|
|
.I trace-playback-file
|
|
]
|
|
[
|
|
.I if0
|
|
[
|
|
.I ...ifN
|
|
]
|
|
]
|
|
.SH DESCRIPTION
|
|
The Internet Systems Consortium DHCP Server, dhcpd, implements the
|
|
Dynamic Host Configuration Protocol (DHCP) and the Internet Bootstrap
|
|
Protocol (BOOTP). DHCP allows hosts on a TCP/IP network to request
|
|
and be assigned IP addresses, and also to discover information about
|
|
the network to which they are attached. BOOTP provides similar
|
|
functionality, with certain restrictions.
|
|
.SH CONTRIBUTIONS
|
|
.PP
|
|
This software is free software. At various times its development has
|
|
been underwritten by various organizations, including the ISC and
|
|
Vixie Enterprises. The development of 3.0 has been funded almost
|
|
entirely by Nominum, Inc.
|
|
.PP
|
|
At this point development is being shepherded by Ted Lemon, and hosted
|
|
by the ISC, but the future of this project depends on you. If you
|
|
have features you want, please consider implementing them.
|
|
.SH OPERATION
|
|
.PP
|
|
The DHCP protocol allows a host which is unknown to the network
|
|
administrator to be automatically assigned a new IP address out of a
|
|
pool of IP addresses for its network. In order for this to work, the
|
|
network administrator allocates address pools in each subnet and
|
|
enters them into the dhcpd.conf(5) file.
|
|
.PP
|
|
On startup, dhcpd reads the
|
|
.IR dhcpd.conf
|
|
file and stores a list of available addresses on each subnet in
|
|
memory. When a client requests an address using the DHCP protocol,
|
|
dhcpd allocates an address for it. Each client is assigned a lease,
|
|
which expires after an amount of time chosen by the administrator (by
|
|
default, one day). Before leases expire, the clients to which leases
|
|
are assigned are expected to renew them in order to continue to use
|
|
the addresses. Once a lease has expired, the client to which that
|
|
lease was assigned is no longer permitted to use the leased IP
|
|
address.
|
|
.PP
|
|
In order to keep track of leases across system reboots and server
|
|
restarts, dhcpd keeps a list of leases it has assigned in the
|
|
dhcpd.leases(5) file. Before dhcpd grants a lease to a host, it
|
|
records the lease in this file and makes sure that the contents of the
|
|
file are flushed to disk. This ensures that even in the event of a
|
|
system crash, dhcpd will not forget about a lease that it has
|
|
assigned. On startup, after reading the dhcpd.conf file, dhcpd
|
|
reads the dhcpd.leases file to refresh its memory about what leases
|
|
have been assigned.
|
|
.PP
|
|
New leases are appended to the end of the dhcpd.leases
|
|
file. In order to prevent the file from becoming arbitrarily large,
|
|
from time to time dhcpd creates a new dhcpd.leases file from its
|
|
in-core lease database. Once this file has been written to disk, the
|
|
old file is renamed
|
|
.IR dhcpd.leases~ ,
|
|
and the new file is renamed dhcpd.leases. If the system crashes in
|
|
the middle of this process, whichever dhcpd.leases file remains will
|
|
contain all the lease information, so there is no need for a special
|
|
crash recovery process.
|
|
.PP
|
|
BOOTP support is also provided by this server. Unlike DHCP, the BOOTP
|
|
protocol does not provide a protocol for recovering
|
|
dynamically-assigned addresses once they are no longer needed. It is
|
|
still possible to dynamically assign addresses to BOOTP clients, but
|
|
some administrative process for reclaiming addresses is required. By
|
|
default, leases are granted to BOOTP clients in perpetuity, although
|
|
the network administrator may set an earlier cutoff date or a shorter
|
|
lease length for BOOTP leases if that makes sense.
|
|
.PP
|
|
BOOTP clients may also be served in the old standard way, which is to
|
|
simply provide a declaration in the dhcpd.conf file for each
|
|
BOOTP client, permanently assigning an address to each client.
|
|
.PP
|
|
Whenever changes are made to the dhcpd.conf file, dhcpd must be
|
|
restarted. To restart dhcpd, send a SIGTERM (signal 15) to the
|
|
process ID contained in
|
|
.IR /var/run/dhcpd.pid ,
|
|
and then re-invoke dhcpd. Because the DHCP server database is not as
|
|
lightweight as a BOOTP database, dhcpd does not automatically restart
|
|
itself when it sees a change to the dhcpd.conf file.
|
|
.PP
|
|
Note: We get a lot of complaints about this. We realize that it would
|
|
be nice if one could send a SIGHUP to the server and have it reload
|
|
the database. This is not technically impossible, but it would
|
|
require a great deal of work, our resources are extremely limited, and
|
|
they can be better spent elsewhere. So please don't complain about
|
|
this on the mailing list unless you're prepared to fund a project to
|
|
implement this feature, or prepared to do it yourself.
|
|
.SH COMMAND LINE
|
|
.PP
|
|
The names of the network interfaces on which dhcpd should listen for
|
|
broadcasts may be specified on the command line. This should be done
|
|
on systems where dhcpd is unable to identify non-broadcast interfaces,
|
|
but should not be required on other systems. If no interface names
|
|
are specified on the command line dhcpd will identify all network
|
|
interfaces which are up, eliminating non-broadcast interfaces if
|
|
possible, and listen for DHCP broadcasts on each interface.
|
|
.PP
|
|
If dhcpd should listen on a port other than the standard (port 67),
|
|
the
|
|
.B -p
|
|
flag may used. It should be followed by the udp port number on which
|
|
dhcpd should listen. This is mostly useful for debugging purposes.
|
|
.PP
|
|
To run dhcpd as a foreground process, rather than allowing it to run
|
|
as a daemon in the background, the
|
|
.B -f
|
|
flag should be specified. This is useful when running dhcpd under a
|
|
debugger, or when running it out of inittab on System V systems.
|
|
.PP
|
|
To have dhcpd log to the standard error descriptor, specify the
|
|
.B -d
|
|
flag. This can be useful for debugging, and also at sites where a
|
|
complete log of all dhcp activity must be kept but syslogd is not
|
|
reliable or otherwise cannot be used. Normally, dhcpd will log all
|
|
output using the syslog(3) function with the log facility set to
|
|
LOG_DAEMON.
|
|
.PP
|
|
Dhcpd can be made to use an alternate configuration file with the
|
|
.B -cf
|
|
flag, or an alternate lease file with the
|
|
.B -lf
|
|
flag. Because of the importance of using the same lease database at
|
|
all times when running dhcpd in production, these options should be
|
|
used \fBonly\fR for testing lease files or database files in a
|
|
non-production environment.
|
|
.PP
|
|
When starting dhcpd up from a system startup script (e.g., /etc/rc),
|
|
it may not be desirable to print out the entire copyright message on
|
|
startup. To avoid printing this message, the
|
|
.B -q
|
|
flag may be specified.
|
|
.PP
|
|
The DHCP server reads two files on startup: a configuration file, and
|
|
a lease database. If the
|
|
.B -t
|
|
flag is specified, the server will simply test the configuration file
|
|
for correct syntax, but will not attempt to perform any network
|
|
operations. This can be used to test the a new configuration file
|
|
automatically before installing it.
|
|
.PP
|
|
The
|
|
.B -T
|
|
flag can be used to test the lease database file in a similar way.
|
|
.PP
|
|
The \fB-tf\fR and \fB-play\fR options allow you to specify a file into
|
|
which the entire startup state of the server and all the transactions
|
|
it processes are either logged or played back from. This can be
|
|
useful in submitting bug reports - if you are getting a core dump
|
|
every so often, you can start the server with the \fB-tf\fR option and
|
|
then, when the server dumps core, the trace file will contain all the
|
|
transactions that led up to it dumping core, so that the problem can
|
|
be easily debugged with \fB-play\fR.
|
|
.PP
|
|
The \fB-play\fR option must be specified with an alternate lease file,
|
|
using the \fB-lf\fR switch, so that the DHCP server doesn't wipe out
|
|
your existing lease file with its test data. The DHCP server will
|
|
refuse to operate in playback mode unless you specify an alternate
|
|
lease file.
|
|
.SH CONFIGURATION
|
|
The syntax of the dhcpd.conf(5) file is discussed separately. This
|
|
section should be used as an overview of the configuration process,
|
|
and the dhcpd.conf(5) documentation should be consulted for detailed
|
|
reference information.
|
|
.PP
|
|
.SH Subnets
|
|
dhcpd needs to know the subnet numbers and netmasks of all subnets for
|
|
which it will be providing service. In addition, in order to
|
|
dynamically allocate addresses, it must be assigned one or more ranges
|
|
of addresses on each subnet which it can in turn assign to client
|
|
hosts as they boot. Thus, a very simple configuration providing DHCP
|
|
support might look like this:
|
|
.nf
|
|
.sp 1
|
|
subnet 239.252.197.0 netmask 255.255.255.0 {
|
|
range 239.252.197.10 239.252.197.250;
|
|
}
|
|
.fi
|
|
.PP
|
|
Multiple address ranges may be specified like this:
|
|
.nf
|
|
.sp 1
|
|
subnet 239.252.197.0 netmask 255.255.255.0 {
|
|
range 239.252.197.10 239.252.197.107;
|
|
range 239.252.197.113 239.252.197.250;
|
|
}
|
|
.fi
|
|
.PP
|
|
If a subnet will only be provided with BOOTP service and no dynamic
|
|
address assignment, the range clause can be left out entirely, but the
|
|
subnet statement must appear.
|
|
.PP
|
|
.SH Lease Lengths
|
|
DHCP leases can be assigned almost any length from zero seconds to
|
|
infinity. What lease length makes sense for any given subnet, or for
|
|
any given installation, will vary depending on the kinds of hosts
|
|
being served.
|
|
.PP
|
|
For example, in an office environment where systems are added from
|
|
time to time and removed from time to time, but move relatively
|
|
infrequently, it might make sense to allow lease times of a month of
|
|
more. In a final test environment on a manufacturing floor, it may
|
|
make more sense to assign a maximum lease length of 30 minutes -
|
|
enough time to go through a simple test procedure on a network
|
|
appliance before packaging it up for delivery.
|
|
.PP
|
|
It is possible to specify two lease lengths: the default length that
|
|
will be assigned if a client doesn't ask for any particular lease
|
|
length, and a maximum lease length. These are specified as clauses
|
|
to the subnet command:
|
|
.nf
|
|
.sp 1
|
|
subnet 239.252.197.0 netmask 255.255.255.0 {
|
|
range 239.252.197.10 239.252.197.107;
|
|
default-lease-time 600;
|
|
max-lease-time 7200;
|
|
}
|
|
.fi
|
|
.PP
|
|
This particular subnet declaration specifies a default lease time of
|
|
600 seconds (ten minutes), and a maximum lease time of 7200 seconds
|
|
(two hours). Other common values would be 86400 (one day), 604800
|
|
(one week) and 2592000 (30 days).
|
|
.PP
|
|
Each subnet need not have the same lease\(emin the case of an office
|
|
environment and a manufacturing environment served by the same DHCP
|
|
server, it might make sense to have widely disparate values for
|
|
default and maximum lease times on each subnet.
|
|
.SH BOOTP Support
|
|
Each BOOTP client must be explicitly declared in the dhcpd.conf
|
|
file. A very basic client declaration will specify the client
|
|
network interface's hardware address and the IP address to assign to
|
|
that client. If the client needs to be able to load a boot file from
|
|
the server, that file's name must be specified. A simple bootp
|
|
client declaration might look like this:
|
|
.nf
|
|
.sp 1
|
|
host haagen {
|
|
hardware ethernet 08:00:2b:4c:59:23;
|
|
fixed-address 239.252.197.9;
|
|
filename "/tftpboot/haagen.boot";
|
|
}
|
|
.fi
|
|
.SH Options
|
|
DHCP (and also BOOTP with Vendor Extensions) provide a mechanism
|
|
whereby the server can provide the client with information about how
|
|
to configure its network interface (e.g., subnet mask), and also how
|
|
the client can access various network services (e.g., DNS, IP routers,
|
|
and so on).
|
|
.PP
|
|
These options can be specified on a per-subnet basis, and, for BOOTP
|
|
clients, also on a per-client basis. In the event that a BOOTP
|
|
client declaration specifies options that are also specified in its
|
|
subnet declaration, the options specified in the client declaration
|
|
take precedence. A reasonably complete DHCP configuration might
|
|
look something like this:
|
|
.nf
|
|
.sp 1
|
|
subnet 239.252.197.0 netmask 255.255.255.0 {
|
|
range 239.252.197.10 239.252.197.250;
|
|
default-lease-time 600 max-lease-time 7200;
|
|
option subnet-mask 255.255.255.0;
|
|
option broadcast-address 239.252.197.255;
|
|
option routers 239.252.197.1;
|
|
option domain-name-servers 239.252.197.2, 239.252.197.3;
|
|
option domain-name "isc.org";
|
|
}
|
|
.fi
|
|
.PP
|
|
A bootp host on that subnet that needs to be in a different domain and
|
|
use a different name server might be declared as follows:
|
|
.nf
|
|
.sp 1
|
|
host haagen {
|
|
hardware ethernet 08:00:2b:4c:59:23;
|
|
fixed-address 239.252.197.9;
|
|
filename "/tftpboot/haagen.boot";
|
|
option domain-name-servers 192.5.5.1;
|
|
option domain-name "vix.com";
|
|
}
|
|
.fi
|
|
.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 associated 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 /etc/dhcpd.conf, /var/db/dhcpd.leases, /var/run/dhcpd.pid,
|
|
.B /var/db/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.
|