xref: /freebsd/libexec/bootpd/bootpd.8 (revision 123af6ec70016f5556da5972d4d63c7d175c06d3)
1.\" Copyright (c) 1988, 1989, 1991 Carnegie Mellon University
2.\"
3.\" $FreeBSD$
4.\"
5.Dd February 10, 2004
6.Dt BOOTPD 8
7.Os
8.Sh NAME
9.Nm bootpd , bootpgw
10.Nd Internet Boot Protocol server/gateway
11.Sh SYNOPSIS
12.Nm
13.Op Fl i | s
14.Op Fl c Ar chdir-path
15.Op Fl d Ar level
16.Op Fl h Ar hostname
17.Op Fl t Ar timeout
18.Oo
19.Ar bootptab
20.Op Ar dumpfile
21.Oc
22.Nm bootpgw
23.Op Fl i | s
24.Op Fl d Ar level
25.Op Fl h Ar hostname
26.Op Fl t Ar timeout
27.Ar server
28.Sh DESCRIPTION
29The
30.Nm
31utility
32implements an Internet Bootstrap Protocol (BOOTP) server as defined in
33RFC951, RFC1532, and RFC1533.
34The
35.Nm bootpgw
36utility implements a simple BOOTP gateway which can be used to forward
37requests and responses between clients on one subnet and a
38BOOTP server (i.e.\&
39.Nm )
40on another subnet.
41While either
42.Nm
43or
44.Nm bootpgw
45will forward BOOTREPLY packets, only
46.Nm bootpgw
47will forward BOOTREQUEST packets.
48.Pp
49One host on each network segment is normally configured to run either
50.Nm
51or
52.Nm bootpgw
53from
54.Xr inetd 8
55by including one of the following lines in the file
56.Pa /etc/inetd.conf :
57.Pp
58.Dl bootps dgram udp wait root /usr/libexec/bootpd bootpd /etc/bootptab
59.Dl bootps dgram udp wait root /usr/libexec/bootpgw bootpgw server
60.Pp
61This mode of operation is referred to as "inetd mode" and causes
62.Nm
63(or
64.Nm bootpgw )
65to be started only when a boot request arrives.
66If it does not
67receive another packet within fifteen minutes of the last one
68it received, it will exit to conserve system resources.
69The
70.Fl t
71option controls this timeout (see OPTIONS).
72.Pp
73It is also possible to run
74.Nm
75(or
76.Nm bootpgw )
77in "standalone mode" (without
78.Xr inetd 8 )
79by simply invoking it from a shell like any other regular command.
80Standalone mode is particularly useful when
81.Nm
82is used with a large configuration database, where the start up
83delay might otherwise prevent timely response to client requests.
84(Automatic start up in standalone mode can be done by invoking
85.Nm
86from within
87.Pa /etc/rc.local ,
88for example.)
89Standalone mode is less useful for
90.Nm bootpgw
91which
92has very little start up delay because
93it does not read a configuration file.
94.Pp
95Either program automatically detects whether it was invoked from inetd
96or from a shell and automatically selects the appropriate mode.
97The
98.Fl s
99or
100.Fl i
101option may be used to force standalone or inetd mode respectively
102(see OPTIONS).
103.Sh OPTIONS
104The following options are available:
105.Bl -tag -width indent
106.It Fl t Ar timeout
107Specify the
108.Ar timeout
109value (in minutes) that a
110.Nm
111or
112.Nm bootpgw
113process will wait for a BOOTP packet before exiting.
114If no packets are received for
115.Ar timeout
116minutes, then the program will exit.
117A timeout value of zero means "run forever".
118In standalone mode, this option is forced to zero.
119.It Fl d Ar debug-level
120Set the
121.Ar debug-level
122variable that controls the amount of debugging messages generated.
123For example,
124.Fl d Ns 4
125or
126.Fl d
1274 will set the debugging level to 4.
128For compatibility with older versions of
129.Nm ,
130omitting the numeric parameter (i.e., just
131.Fl d )
132will simply increment the debug level by one.
133.It Fl c Ar chdir-path
134Set the current directory used by
135.Nm
136while checking the existence and size of client boot files.
137This is
138useful when client boot files are specified as relative pathnames, and
139.Nm
140needs to use the same current directory as the TFTP server
141(typically
142.Pa /tftpboot ) .
143This option is not recognized by
144.Nm bootpgw .
145.It Fl h Ar hostname
146Specify the hostname corresponding to the IP address to listen on.
147By default,
148.Nm
149listens on the IP address corresponding to the machine's hostname, as
150returned by
151.Xr gethostname 3 .
152.It Fl i
153Force inetd mode.
154This option is obsolete, but remains for
155compatibility with older versions of
156.Nm .
157.It Fl s
158Force standalone mode.
159This option is obsolete, but remains for
160compatibility with older versions of
161.Nm .
162.It Ar bootptab
163Specify the name of the configuration file from which
164.Nm
165loads its database of known clients and client options
166.No ( Nm
167only).
168.It Ar dumpfile
169Specify the name of the file that
170.Nm
171will dump its internal database into when it receives a
172SIGUSR1 signal
173.No ( Nm
174only).
175This option is only recognized if
176.Nm
177was compiled with the -DDEBUG flag.
178.It Ar server
179Specify the name of a BOOTP server to which
180.Nm bootpgw
181will forward all BOOTREQUEST packets it receives
182.Pf ( Nm bootpgw
183only).
184.El
185.Sh OPERATION
186Both
187.Nm
188and
189.Nm bootpgw
190operate similarly in that both listen for any packets sent to the
191.Em bootps
192port, and both simply forward any BOOTREPLY packets.
193They differ in their handling of BOOTREQUEST packets.
194.Pp
195When
196.Nm bootpgw
197is started, it determines the address of a BOOTP server
198whose name is provided as a command line parameter.
199When
200.Nm bootpgw
201receives a BOOTREQUEST packet, it sets the "gateway address"
202and "hop count" fields in the packet and forwards the packet
203to the BOOTP server at the address determined earlier.
204Requests are forwarded only if they indicate that
205the client has been waiting for at least three seconds.
206.Pp
207When
208.Nm
209is started it reads a configuration file, (normally
210.Pa /etc/bootptab )
211that initializes the internal database of known clients and client
212options.
213This internal database is reloaded
214from the configuration file when
215.Nm
216receives a hangup signal (SIGHUP) or when it discovers that the
217configuration file has changed.
218.Pp
219When
220.Nm
221receives a BOOTREQUEST packet, it
222.\" checks the modification time of the
223.\" configuration file and reloads the database if necessary.  Then it
224looks for a database entry matching the client request.
225If the client is known,
226.Nm
227composes a BOOTREPLY packet using the database entry found above,
228and sends the reply to the client (possibly using a gateway).
229If the client is unknown, the request is discarded
230(with a notice if debug > 0).
231.Pp
232If
233.Nm
234is compiled with the -DDEBUG option, receipt of a SIGUSR1 signal causes
235it to dump its internal database to the file
236.Pa /tmp/bootpd.dump
237or the dumpfile specified as a command line parameter.
238.Pp
239During initialization, both programs
240determine the UDP port numbers to be used by calling
241.Xr getservbyname 3
242(which normally uses
243.Pa /etc/services ) .
244Two service names (and port numbers) are used:
245.Pp
246.Dl bootps BOOTP Server listening port
247.Dl bootpc BOOTP Client destination port
248.Pp
249If the port numbers cannot be determined using
250.Xr getservbyname 3
251then the values default to bootps=67 and bootpc=68.
252.Sh FILES
253.Bl -tag -width /tmp/bootpd.dump -compact
254.It Pa /etc/bootptab
255Database file read by
256.Nm .
257.It Pa /tmp/bootpd.dump
258Debugging dump file created by
259.Nm .
260.It Pa /etc/services
261Internet service numbers.
262.It Pa /tftpboot
263Current directory typically used by the TFTP server and
264.Nm .
265.El
266.Sh "SEE ALSO"
267.Xr bootptab 5 ,
268.Xr inetd 8 ,
269.Xr tftpd 8
270.Pp
271DARPA Internet Request For Comments:
272.Bl -tag -width RFC1533 -compact
273.It RFC951
274Bootstrap Protocol
275.It RFC1532
276Clarifications and Extensions for the Bootstrap Protocol
277.It RFC1533
278DHCP Options and BOOTP Vendor Extensions
279.El
280.Sh AUTHORS
281This distribution is currently maintained by
282.An Walter L. Wimer Aq Mt walt+@cmu.edu .
283.Pp
284The original BOOTP server was created by
285.An Bill Croft
286at Stanford University in January 1986.
287.Pp
288The current version of
289.Nm
290is primarily the work of
291.An David Kovar ,
292.An Drew D. Perkins ,
293and
294.An Walter L. Wimer ,
295at Carnegie Mellon University.
296.Pp
297Enhancements and bug-fixes have been contributed by:
298.Pp
299(in alphabetical order)
300.Pp
301.An -split
302.An Danny Backx Aq Mt db@sunbim.be
303.An John Brezak Aq Mt brezak@ch.hp.com
304.An Frank da Cruz Aq Mt fdc@cc.columbia.edu
305.An David R. Linn Aq Mt drl@vuse.vanderbilt.edu
306.An Jim McKim Aq Mt mckim@lerc.nasa.gov
307.An Gordon W. Ross Aq Mt gwr@mc.com
308.An Jason Zions Aq Mt jazz@hal.com .
309.Sh BUGS
310Individual host entries must not exceed 1024 characters.
311