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