346 lines
14 KiB
Groff
346 lines
14 KiB
Groff
.\" dhcpd.8
|
|
.\"
|
|
.\" Copyright (c) 1995, 1996 The Internet Software Consortium.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\"
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of The Internet Software Consortium nor the names
|
|
.\" of its contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE INTERNET SOFTWARE CONSORTIUM AND
|
|
.\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
|
|
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
.\" DISCLAIMED. IN NO EVENT SHALL THE INTERNET SOFTWARE CONSORTIUM OR
|
|
.\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
|
|
.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
|
.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
|
|
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" This software has been written for the Internet Software Consortium
|
|
.\" by Ted Lemon <mellon@fugue.com> in cooperation with Vixie
|
|
.\" Enterprises. To learn more about the Internet Software Consortium,
|
|
.\" see ``http://www.isc.org/isc''. To learn more about Vixie
|
|
.\" Enterprises, see ``http://www.vix.com''.
|
|
.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 -cf
|
|
.I config-file
|
|
]
|
|
[
|
|
.B -lf
|
|
.I lease-file
|
|
]
|
|
[
|
|
.I if0
|
|
[
|
|
.I ...ifN
|
|
]
|
|
]
|
|
.SH DESCRIPTION
|
|
The Internet Software 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 SYSTEM REQUIREMENTS
|
|
There \fPmust\fR be a /etc/dhcpd.conf file. There \fBmust\fR
|
|
be a /var/db/dhcpd.leases file. This file can initially be created by
|
|
typing \fItouch /var/db/dhcpd.leases\fR. You must have the Berkeley
|
|
Packet Filter (bpf) configured in your NetBSD kernel. You must have
|
|
at least one /dev/bpf* file for each broadcast network interface that
|
|
is attached to your system.
|
|
.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, elimininating 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.
|
|
If the
|
|
.B -p
|
|
flag is specified, the server will transmit responses to clients at a
|
|
port number that is one greater than the one specified - i.e., if you
|
|
specify
|
|
.B -p
|
|
67, then the server will listen on port 67 and transmit to port 68.
|
|
Datagrams that must go through relay agents are sent to the port
|
|
number specified with the
|
|
.B -p
|
|
flag - if you wish to use alternate port numbers, you must configure
|
|
any relay agents you are using to use the same alternate port numbers.
|
|
.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.
|
|
.SH CONFIGURATION
|
|
The syntax of the dhcpd.conf(5) file is discussed seperately. 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) provides 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. An 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 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), bpf(4)
|
|
.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 Corporation.
|
|
Information about the Internet Software Consortium can be found at
|
|
.B http://www.isc.org/isc.
|