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