freebsd-dev/libexec/bootpd/bootpd.8

295 lines
7.3 KiB
Groff
Raw Normal View History

1994-09-30 05:45:07 +00:00
.\" Copyright (c) 1988, 1989, 1991 Carnegie Mellon University
.\"
1999-08-28 00:22:10 +00:00
.\" $FreeBSD$
1994-09-30 05:45:07 +00:00
.\"
.Dd November 6, 1993
1998-02-03 07:30:22 +00:00
.Dt BOOTPD 8
.Os
1998-02-03 07:30:22 +00:00
.Sh NAME
.Nm bootpd , bootpgw
.Nd Internet Boot Protocol server/gateway
.Sh SYNOPSIS
.Nm
1998-02-03 07:30:22 +00:00
.Op Fl i
.Op Fl s
.Op Fl t Ar timeout
.Op Fl d Ar level
.Op Fl c Ar chdir-path
.Oo
.Ar bootptab
.Op Ar dumpfile
.Oc
.Nm bootpgw
.Op Fl i
2001-07-15 07:53:42 +00:00
.Op Fl s
1998-02-03 07:30:22 +00:00
.Op Fl t Ar timeout
.Op Fl d Ar level
.Ar server
.Sh DESCRIPTION
2002-07-06 19:19:48 +00:00
The
.Nm
utility
1994-09-30 05:45:07 +00:00
implements an Internet Bootstrap Protocol (BOOTP) server as defined in
RFC951, RFC1532, and RFC1533.
2002-07-06 19:19:48 +00:00
The
.Nm bootpgw
utility implements a simple BOOTP gateway which can be used to forward
1994-09-30 05:45:07 +00:00
requests and responses between clients on one subnet and a
BOOTP server (i.e.\&
.Nm )
1994-09-30 05:45:07 +00:00
on another subnet. While either
1998-02-03 07:30:22 +00:00
.Nm
1994-09-30 05:45:07 +00:00
or
1998-02-03 07:30:22 +00:00
.Nm bootpgw
1994-09-30 05:45:07 +00:00
will forward BOOTREPLY packets, only
1998-02-03 07:30:22 +00:00
.Nm bootpgw
1994-09-30 05:45:07 +00:00
will forward BOOTREQUEST packets.
1998-02-03 07:30:22 +00:00
.Pp
1994-09-30 05:45:07 +00:00
One host on each network segment is normally configured to run either
1998-02-03 07:30:22 +00:00
.Nm
1994-09-30 05:45:07 +00:00
or
1998-02-03 07:30:22 +00:00
.Nm bootpgw
1994-09-30 05:45:07 +00:00
from
1998-02-03 07:30:22 +00:00
.Xr inetd 8
1994-09-30 05:45:07 +00:00
by including one of the following lines in the file
1998-02-03 07:30:22 +00:00
.Pa /etc/inetd.conf :
.Pp
.Dl bootps dgram udp wait root /usr/libexec/bootpd bootpd /etc/bootptab
.Dl bootps dgram udp wait root /usr/libexec/bootpgw bootpgw server
.Pp
1994-09-30 05:45:07 +00:00
This mode of operation is referred to as "inetd mode" and causes
1998-02-03 07:30:22 +00:00
.Nm
1994-09-30 05:45:07 +00:00
(or
1998-02-03 07:30:22 +00:00
.Nm bootpgw )
1994-09-30 05:45:07 +00:00
to be started only when a boot request arrives. If it does not
receive another packet within fifteen minutes of the last one
it received, it will exit to conserve system resources. The
1998-02-03 07:30:22 +00:00
.Fl t
1994-09-30 05:45:07 +00:00
option controls this timeout (see OPTIONS).
1998-02-03 07:30:22 +00:00
.Pp
1994-09-30 05:45:07 +00:00
It is also possible to run
1998-02-03 07:30:22 +00:00
.Nm
1994-09-30 05:45:07 +00:00
(or
1998-02-03 07:30:22 +00:00
.Nm bootpgw )
1994-09-30 05:45:07 +00:00
in "standalone mode" (without
1998-02-03 07:30:22 +00:00
.Xr inetd 8 )
1994-09-30 05:45:07 +00:00
by simply invoking it from a shell like any other regular command.
Standalone mode is particularly useful when
1998-02-03 07:30:22 +00:00
.Nm
1994-09-30 05:45:07 +00:00
is used with a large configuration database, where the start up
delay might otherwise prevent timely response to client requests.
(Automatic start up in standalone mode can be done by invoking
1998-02-03 07:30:22 +00:00
.Nm
1994-09-30 05:45:07 +00:00
from within
1998-02-03 07:30:22 +00:00
.Pa /etc/rc.local ,
1994-09-30 05:45:07 +00:00
for example.)
Standalone mode is less useful for
1998-02-03 07:30:22 +00:00
.Nm bootpgw
1994-09-30 05:45:07 +00:00
which
has very little start up delay because
it does not read a configuration file.
1998-02-03 07:30:22 +00:00
.Pp
1994-09-30 05:45:07 +00:00
Either program automatically detects whether it was invoked from inetd
or from a shell and automatically selects the appropriate mode.
2001-07-15 07:53:42 +00:00
The
1998-02-03 07:30:22 +00:00
.Fl s
1994-09-30 05:45:07 +00:00
or
1998-02-03 07:30:22 +00:00
.Fl i
1994-09-30 05:45:07 +00:00
option may be used to force standalone or inetd mode respectively
(see OPTIONS).
1998-02-03 07:30:22 +00:00
.Sh OPTIONS
The following options are available:
.Bl -tag -width indent
.It Fl t Ar timeout
Specify the
.Ar timeout
1994-09-30 05:45:07 +00:00
value (in minutes) that a
1998-02-03 07:30:22 +00:00
.Nm
1994-09-30 05:45:07 +00:00
or
1998-02-03 07:30:22 +00:00
.Nm bootpgw
1994-09-30 05:45:07 +00:00
process will wait for a BOOTP packet before exiting.
If no packets are received for
1998-02-03 07:30:22 +00:00
.Ar timeout
minutes, then the program will exit.
1994-09-30 05:45:07 +00:00
A timeout value of zero means "run forever".
In standalone mode, this option is forced to zero.
1998-02-03 07:30:22 +00:00
.It Fl d Ar debug-level
Set the
.Ar debug-level
1994-09-30 05:45:07 +00:00
variable that controls the amount of debugging messages generated.
1998-02-03 07:30:22 +00:00
For example,
.Fl d Ns 4
or
.Fl d
4 will set the debugging level to 4.
1994-09-30 05:45:07 +00:00
For compatibility with older versions of
.Nm ,
1998-02-03 07:30:22 +00:00
omitting the numeric parameter (i.e. just
.Fl d Ns )
will simply increment the debug level by one.
.It Fl c Ar chdir-path
Set the current directory used by
.Nm
1994-09-30 05:45:07 +00:00
while checking the existence and size of client boot files. This is
useful when client boot files are specified as relative pathnames, and
1998-02-03 07:30:22 +00:00
.Nm
1994-09-30 05:45:07 +00:00
needs to use the same current directory as the TFTP server
1998-02-03 07:30:22 +00:00
(typically
.Pa /tftpboot ) .
1998-02-03 07:30:22 +00:00
This option is not recognized by
.Nm bootpgw .
.It Fl i
1994-09-30 05:45:07 +00:00
Force inetd mode. This option is obsolete, but remains for
compatibility with older versions of
.Nm .
1998-02-03 07:30:22 +00:00
.It Fl s
1994-09-30 05:45:07 +00:00
Force standalone mode. This option is obsolete, but remains for
compatibility with older versions of
.Nm .
1998-02-03 07:30:22 +00:00
.It Ar bootptab
Specify the name of the configuration file from which
.Nm
1994-09-30 05:45:07 +00:00
loads its database of known clients and client options
.No ( Nm
1994-09-30 05:45:07 +00:00
only).
1998-02-03 07:30:22 +00:00
.It Ar dumpfile
Specify the name of the file that
.Nm
1994-09-30 05:45:07 +00:00
will dump its internal database into when it receives a
SIGUSR1 signal
.No ( Nm
1998-02-03 07:30:22 +00:00
only). This option is only recognized if
.Nm
1994-09-30 05:45:07 +00:00
was compiled with the -DDEBUG flag.
1998-02-03 07:30:22 +00:00
.It Ar server
Specify the name of a BOOTP server to which
.Nm bootpgw
1994-09-30 05:45:07 +00:00
will forward all BOOTREQUEST packets it receives
1998-02-03 07:30:22 +00:00
.Pf ( Nm bootpgw
1994-09-30 05:45:07 +00:00
only).
1998-02-03 07:30:22 +00:00
.El
.Sh OPERATION
1994-09-30 05:45:07 +00:00
Both
1998-02-03 07:30:22 +00:00
.Nm
1994-09-30 05:45:07 +00:00
and
1998-02-03 07:30:22 +00:00
.Nm bootpgw
1994-09-30 05:45:07 +00:00
operate similarly in that both listen for any packets sent to the
1998-02-03 07:30:22 +00:00
.Em bootps
1994-09-30 05:45:07 +00:00
port, and both simply forward any BOOTREPLY packets.
They differ in their handling of BOOTREQUEST packets.
1998-02-03 07:30:22 +00:00
.Pp
1994-09-30 05:45:07 +00:00
When
1998-02-03 07:30:22 +00:00
.Nm bootpgw
1994-09-30 05:45:07 +00:00
is started, it determines the address of a BOOTP server
whose name is provided as a command line parameter. When
1998-02-03 07:30:22 +00:00
.Nm bootpgw
1994-09-30 05:45:07 +00:00
receives a BOOTREQUEST packet, it sets the "gateway address"
and "hop count" fields in the packet and forwards the packet
to the BOOTP server at the address determined earlier.
Requests are forwarded only if they indicate that
the client has been waiting for at least three seconds.
1998-02-03 07:30:22 +00:00
.Pp
1994-09-30 05:45:07 +00:00
When
1998-02-03 07:30:22 +00:00
.Nm
1994-09-30 05:45:07 +00:00
is started it reads a configuration file, (normally
.Pa /etc/bootptab )
1994-09-30 05:45:07 +00:00
that initializes the internal database of known clients and client
options. This internal database is reloaded
from the configuration file when
1998-02-03 07:30:22 +00:00
.Nm
1994-09-30 05:45:07 +00:00
receives a hangup signal (SIGHUP) or when it discovers that the
configuration file has changed.
1998-02-03 07:30:22 +00:00
.Pp
1994-09-30 05:45:07 +00:00
When
1998-02-03 07:30:22 +00:00
.Nm
1994-09-30 05:45:07 +00:00
receives a BOOTREQUEST packet, it
.\" checks the modification time of the
.\" configuration file and reloads the database if necessary. Then it
looks for a database entry matching the client request.
If the client is known,
1998-02-03 07:30:22 +00:00
.Nm
1994-09-30 05:45:07 +00:00
composes a BOOTREPLY packet using the database entry found above,
and sends the reply to the client (possibly using a gateway).
If the client is unknown, the request is discarded
(with a notice if debug > 0).
1998-02-03 07:30:22 +00:00
.Pp
1994-09-30 05:45:07 +00:00
If
1998-02-03 07:30:22 +00:00
.Nm
1994-09-30 05:45:07 +00:00
is compiled with the -DDEBUG option, receipt of a SIGUSR1 signal causes
it to dump its internal database to the file
1998-02-03 07:30:22 +00:00
.Pa /tmp/bootpd.dump
1994-09-30 05:45:07 +00:00
or the dumpfile specified as a command line parameter.
1998-02-03 07:30:22 +00:00
.Pp
1994-09-30 05:45:07 +00:00
During initialization, both programs
determine the UDP port numbers to be used by calling
1998-02-03 07:30:22 +00:00
.Xr getservbyname 3
(which normally uses
.Pa /etc/services ) .
1994-09-30 05:45:07 +00:00
Two service names (and port numbers) are used:
1998-02-03 07:30:22 +00:00
.Pp
.Dl bootps BOOTP Server listening port
.Dl bootpc BOOTP Client destination port
.Pp
If the port numbers cannot be determined using
.Xr getservbyname 3
then the values default to bootps=67 and bootpc=68.
1998-02-03 07:30:22 +00:00
.Sh FILES
.Bl -tag -width /tmp/bootpd.dump -compact
.It Pa /etc/bootptab
1994-09-30 05:45:07 +00:00
Database file read by
.Nm .
1998-02-03 07:30:22 +00:00
.It Pa /tmp/bootpd.dump
1994-09-30 05:45:07 +00:00
Debugging dump file created by
.Nm .
1998-02-03 07:30:22 +00:00
.It Pa /etc/services
1994-09-30 05:45:07 +00:00
Internet service numbers.
1998-02-03 07:30:22 +00:00
.It Pa /tftpboot
1994-09-30 05:45:07 +00:00
Current directory typically used by the TFTP server and
.Nm .
1998-02-03 07:30:22 +00:00
.El
.Sh BUGS
1994-09-30 05:45:07 +00:00
Individual host entries must not exceed 1024 characters.
1998-02-03 07:30:22 +00:00
.Sh CREDITS
1994-09-30 05:45:07 +00:00
This distribution is currently maintained by
1998-02-03 07:30:22 +00:00
.An Walter L. Wimer Aq walt+@cmu.edu .
.Pp
1994-09-30 05:45:07 +00:00
The original BOOTP server was created by
1998-02-03 07:30:22 +00:00
.An Bill Croft
at Stanford University in January 1986.
.Pp
1994-09-30 05:45:07 +00:00
The current version of
1998-02-03 07:30:22 +00:00
.Nm
is primarily the work of
.An David Kovar ,
.An Drew D. Perkins ,
and
.An Walter L. Wimer ,
1994-09-30 05:45:07 +00:00
at Carnegie Mellon University.
1998-02-03 07:30:22 +00:00
.Pp
Enhancements and bug-fixes have been contributed by:
.Pp
1994-09-30 05:45:07 +00:00
(in alphabetical order)
1998-02-03 07:30:22 +00:00
.Pp
.An -split
1998-02-03 07:30:22 +00:00
.An Danny Backx Aq db@sunbim.be
.An John Brezak Aq brezak@ch.hp.com
.An Frank da Cruz Aq fdc@cc.columbia.edu
.An David R. Linn Aq drl@vuse.vanderbilt.edu
.An Jim McKim Aq mckim@lerc.nasa.gov
.An Gordon W. Ross Aq gwr@mc.com
.An Jason Zions Aq jazz@hal.com .
.Sh "SEE ALSO"
.Xr bootptab 5 ,
.Xr inetd 8 ,
.Xr tftpd 8
.Pp
1994-09-30 05:45:07 +00:00
DARPA Internet Request For Comments:
1998-02-03 07:30:22 +00:00
.Bl -tag -width RFC1533 -compact
.It RFC951
1994-09-30 05:45:07 +00:00
Bootstrap Protocol
1998-02-03 07:30:22 +00:00
.It RFC1532
1994-09-30 05:45:07 +00:00
Clarifications and Extensions for the Bootstrap Protocol
1998-02-03 07:30:22 +00:00
.It RFC1533
1994-09-30 05:45:07 +00:00
DHCP Options and BOOTP Vendor Extensions
1998-02-03 07:30:22 +00:00
.El