may the whacking begin

1 files changed, 399 insertions, 0 deletions

diff --git a/usr.sbin/dhcpd/dhcpd.8 b/usr.sbin/dhcpd/dhcpd.8
new file mode 100644
index 00000000000..80c648c0391
--- /dev/null
+++ b/usr.sbin/dhcpd/dhcpd.8
@@ -0,0 +1,399 @@
+.\"	$OpenBSD: dhcpd.8,v 1.1 2004/04/13 23:41:48 henning Exp $
+.\"
+.\" 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/''.  To learn more about Vixie
+.\" Enterprises, see ``http://www.vix.com''.
+.\"
+.Dd January 1, 1995
+.Dt DHCPD 8
+.Os
+.Sh NAME
+.Nm dhcpd
+.Nd Dynamic Host Configuration Protocol Server
+.Sh SYNOPSIS
+.Nm dhcpd
+.Op Fl p Ar port
+.Op Fl f
+.Op Fl d
+.Op Fl q
+.Op Fl cf Ar config-file
+.Op Fl lf Ar lease-file
+.Bk -words
+.Op Ar if0 Op Ar ... ifN
+.Ek
+.Sh DESCRIPTION
+The Internet Software Consortium DHCP Server,
+.Nm 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 OPERATION
+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
+.Xr dhcpd.conf 5
+file.
+.Pp
+On startup,
+.Nm
+reads the
+.Pa 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,
+.Nm
+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,
+.Nm
+keeps a list of leases it has assigned in the
+.Xr dhcpd.leases 5
+file.
+Before
+.Nm
+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,
+.Nm
+will not forget about a lease that it has assigned.
+On startup, after reading the
+.Pa dhcpd.conf
+file,
+.Nm
+reads the
+.Pa dhcpd.leases
+file to refresh its memory about what leases have been assigned.
+.Pp
+New leases are appended to the end of the
+.Pa dhcpd.leases
+file.
+In order to prevent the file from becoming arbitrarily large,
+from time to time
+.Nm
+creates a new
+.Pa dhcpd.leases
+file from its in-core lease database.
+Once this file has been written to disk, the old file is renamed
+.Pa dhcpd.leases~ ,
+and the new file is renamed
+.Pa dhcpd.leases .
+If the system crashes in the middle of this process, whichever
+.Pa 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
+simply to provide a declaration in the
+.Pa dhcpd.conf
+file for each BOOTP client, permanently assigning an address to each client.
+.Pp
+Whenever changes are made to the
+.Pa dhcpd.conf
+file,
+.Nm
+must be restarted.
+To restart
+.Nm dhcpd ,
+send a SIGTERM (signal 15) to the process ID contained in
+.Pa /var/run/dhcpd.pid ,
+and then re-invoke
+.Nm dhcpd .
+Because the DHCP server database is not as lightweight as a BOOTP database,
+.Nm
+does not automatically restart itself when it sees a change to the
+.Pa dhcpd.conf
+file.
+.Pp
+DHCP traffic always bypasses IPsec.
+Otherwise there could be situations when a server has an IPsec SA for the
+client and sends replies over that,
+which a newly booted client would not be able to grasp.
+.Sh COMMAND LINE
+The names of the network interfaces on which
+.Nm
+should listen for broadcasts may be specified on the command line.
+This should be done on systems where
+.Nm
+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,
+.Nm
+will identify all network interfaces which are up, eliminating non-broadcast
+interfaces if possible, and listen for DHCP broadcasts on each interface.
+.Pp
+If
+.Nm
+should listen on a port other than the standard (port 67), the
+.Fl p
+flag may used.
+It should be followed by the UDP port number on which
+.Nm
+should listen.
+This is mostly useful for debugging purposes.
+If the
+.Fl 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
+.Fl 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
+.Fl 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
+.Nm
+as a foreground process, rather than allowing it to run as a daemon in the
+background, the
+.Fl f
+flag should be specified.
+This is useful when running
+.Nm
+under a debugger, or when running it out of inittab on System V systems.
+.Pp
+To have
+.Nm
+log to
+.Ar stderr ,
+the
+.Fl d
+flag should be specified.
+This can be useful for debugging, and also at sites where a complete log of
+all dhcp activity must be kept, but
+.Xr syslogd 8
+is not reliable or otherwise cannot be used.
+Normally,
+.Nm
+will log all output using the
+.Xr syslog 3
+function with the log facility set to LOG_DAEMON.
+.Pp
+.Nm
+can be made to use an alternate configuration file with the
+.Fl cf
+flag, or an alternate lease file with the
+.Fl lf
+flag.
+Because of the importance of using the same lease database at all times when
+running
+.Nm
+in production, these options should be used
+.Em only
+for testing lease files or database files in a non-production environment.
+.Pp
+To avoid printing out the entire copyright message on start-up, the
+.Fl q
+flag should be specified.
+.Sh CONFIGURATION
+The syntax of the
+.Xr dhcpd.conf 5
+file is discussed separately.
+This section should be used as an overview of the configuration process,
+and the
+.Xr dhcpd.conf 5
+documentation should be consulted for detailed reference information.
+.Bl -tag -width 3n
+.It Subnets
+.Nm
+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:
+.Bd -literal -offset indent
+subnet 239.252.197.0 netmask 255.255.255.0 {
+  range 239.252.197.10 239.252.197.250;
+}
+.Ed
+.Pp
+Multiple address ranges may be specified like this:
+.Bd -literal -offset indent
+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;
+}
+.Ed
+.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.
+.It 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:
+.Bd -literal -offset indent
+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;
+}
+.Ed
+.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 \- in 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.
+.It BOOTP Support
+Each BOOTP client must be explicitly declared in the
+.Xr dhcpd.conf 5
+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:
+.Bd -literal -offset indent
+host haagen {
+  hardware ethernet 08:00:2b:4c:59:23;
+  fixed-address 239.252.197.9;
+  filename "/tftpboot/haagen.boot";
+}
+.Ed
+.It 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.
+A reasonably complete DHCP configuration might look something like this:
+.Bd -literal -offset indent
+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";
+}
+.Ed
+.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:
+.Bd -literal -offset indent
+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";
+}
+.Ed
+.El
+.Pp
+A more complete description of the
+.Pa dhcpd.conf
+file syntax is provided in
+.Xr dhcpd.conf 5 .
+.Sh FILES
+.Bl -tag -width "/var/db/dhcpd.leases~  " -compact
+.It /etc/dhcpd.conf
+DHCPD configuration file.
+.It /var/db/dhcpd.leases
+Current DHCPD lease file.
+.It /var/db/dhcpd.leases~
+Backup DHCPD lease file.
+.It /var/run/dhcpd.pid
+DHCPD PID.
+.El
+.Sh SEE ALSO
+.Xr dhcpd.conf 5 ,
+.Xr dhcpd.leases 5 ,
+.Xr dhclient 8 ,
+.Xr dhcp 8 ,
+.Xr dhcrelay 8 ,
+.Xr pxeboot 8
+.Sh AUTHORS
+.Nm
+was written by
+.An Ted Lemon Aq 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
+.Pa http://www.isc.org/ .
+.Sh BUGS
+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.