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