add .Mt to man pages in libexec/
[dragonfly.git] / libexec / bootpd / bootpd.8
CommitLineData
984263bc
MD
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
d0de9052
SW
9.Nm bootpd ,
10.Nm bootpgw
984263bc
MD
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
31implements an Internet Bootstrap Protocol (BOOTP) server as defined in
cabeba47 32RFC 951, RFC 1532, and RFC 1533.
984263bc
MD
33.Nm Bootpgw
34implements a simple BOOTP gateway which can be used to forward
35requests and responses between clients on one subnet and a
36BOOTP server (i.e.\&
37.Nm )
38on another subnet. While either
39.Nm
40or
41.Nm bootpgw
42will forward BOOTREPLY packets, only
43.Nm bootpgw
44will forward BOOTREQUEST packets.
45.Pp
46One host on each network segment is normally configured to run either
47.Nm
48or
49.Nm bootpgw
50from
51.Xr inetd 8
52by 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
58This mode of operation is referred to as "inetd mode" and causes
59.Nm
60(or
61.Nm bootpgw )
62to be started only when a boot request arrives. If it does not
63receive another packet within fifteen minutes of the last one
64it received, it will exit to conserve system resources. The
65.Fl t
66option controls this timeout (see OPTIONS).
67.Pp
68It is also possible to run
69.Nm
70(or
71.Nm bootpgw )
72in "standalone mode" (without
73.Xr inetd 8 )
74by simply invoking it from a shell like any other regular command.
75Standalone mode is particularly useful when
76.Nm
77is used with a large configuration database, where the start up
78delay might otherwise prevent timely response to client requests.
79(Automatic start up in standalone mode can be done by invoking
80.Nm
81from within
82.Pa /etc/rc.local ,
83for example.)
84Standalone mode is less useful for
85.Nm bootpgw
86which
87has very little start up delay because
88it does not read a configuration file.
89.Pp
90Either program automatically detects whether it was invoked from inetd
91or from a shell and automatically selects the appropriate mode.
92The
93.Fl s
94or
95.Fl i
96option may be used to force standalone or inetd mode respectively
97(see OPTIONS).
98.Sh OPTIONS
99The following options are available:
100.Bl -tag -width indent
101.It Fl t Ar timeout
102Specify the
103.Ar timeout
104value (in minutes) that a
105.Nm
106or
107.Nm bootpgw
108process will wait for a BOOTP packet before exiting.
109If no packets are received for
110.Ar timeout
111minutes, then the program will exit.
112A timeout value of zero means "run forever".
113In standalone mode, this option is forced to zero.
114.It Fl d Ar debug-level
115Set the
116.Ar debug-level
117variable that controls the amount of debugging messages generated.
118For example,
119.Fl d Ns 4
120or
121.Fl d
1224 will set the debugging level to 4.
123For compatibility with older versions of
124.Nm ,
125omitting the numeric parameter (i.e. just
126.Fl d Ns )
127will simply increment the debug level by one.
128.It Fl c Ar chdir-path
129Set the current directory used by
130.Nm
131while checking the existence and size of client boot files. This is
132useful when client boot files are specified as relative pathnames, and
133.Nm
134needs to use the same current directory as the TFTP server
135(typically
136.Pa /tftpboot ) .
137This option is not recognized by
138.Nm bootpgw .
139.It Fl i
140Force inetd mode. This option is obsolete, but remains for
141compatibility with older versions of
142.Nm .
143.It Fl s
144Force standalone mode. This option is obsolete, but remains for
145compatibility with older versions of
146.Nm .
147.It Ar bootptab
148Specify the name of the configuration file from which
149.Nm
150loads its database of known clients and client options
151.No ( Nm
152only).
153.It Ar dumpfile
154Specify the name of the file that
155.Nm
156will dump its internal database into when it receives a
62f7f702
SW
157.Dv SIGUSR1
158signal
984263bc
MD
159.No ( Nm
160only). This option is only recognized if
161.Nm
162was compiled with the -DDEBUG flag.
163.It Ar server
164Specify the name of a BOOTP server to which
165.Nm bootpgw
166will forward all BOOTREQUEST packets it receives
167.Pf ( Nm bootpgw
168only).
169.El
170.Sh OPERATION
171Both
172.Nm
173and
174.Nm bootpgw
175operate similarly in that both listen for any packets sent to the
176.Em bootps
177port, and both simply forward any BOOTREPLY packets.
178They differ in their handling of BOOTREQUEST packets.
179.Pp
180When
181.Nm bootpgw
182is started, it determines the address of a BOOTP server
183whose name is provided as a command line parameter. When
184.Nm bootpgw
185receives a BOOTREQUEST packet, it sets the "gateway address"
186and "hop count" fields in the packet and forwards the packet
187to the BOOTP server at the address determined earlier.
188Requests are forwarded only if they indicate that
189the client has been waiting for at least three seconds.
190.Pp
191When
192.Nm
193is started it reads a configuration file, (normally
194.Pa /etc/bootptab )
195that initializes the internal database of known clients and client
196options. This internal database is reloaded
197from the configuration file when
198.Nm
62f7f702
SW
199receives a hangup signal
200.Dv ( SIGHUP )
201or when it discovers that the configuration file has changed.
984263bc
MD
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
62f7f702
SW
218is compiled with the -DDEBUG option, receipt of a
219.Dv SIGUSR1
220signal causes it to dump its internal database to the file
984263bc
MD
221.Pa /tmp/bootpd.dump
222or the dumpfile specified as a command line parameter.
223.Pp
224During initialization, both programs
225determine the UDP port numbers to be used by calling
226.Xr getservbyname 3
227(which normally uses
228.Pa /etc/services ) .
229Two service names (and port numbers) are used:
230.Pp
231.Dl bootps BOOTP Server listening port
232.Dl bootpc BOOTP Client destination port
233.Pp
234If the port numbers cannot be determined using
235.Xr getservbyname 3
236then 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
240Database file read by
241.Nm .
242.It Pa /tmp/bootpd.dump
243Debugging dump file created by
244.Nm .
245.It Pa /etc/services
246Internet service numbers.
247.It Pa /tftpboot
248Current directory typically used by the TFTP server and
249.Nm .
250.El
d600454b
SW
251.Sh "SEE ALSO"
252.Xr bootptab 5 ,
253.Xr inetd 8 ,
254.Xr tftpd 8
255.Pp
256DARPA Internet Request For Comments:
cabeba47
SW
257.Bl -tag -width "RFC 1533" -compact
258.It RFC 951
d600454b 259Bootstrap Protocol
cabeba47 260.It RFC 1532
d600454b 261Clarifications and Extensions for the Bootstrap Protocol
cabeba47 262.It RFC 1533
d600454b
SW
263DHCP Options and BOOTP Vendor Extensions
264.El
984263bc
MD
265.Sh BUGS
266Individual host entries must not exceed 1024 characters.
267.Sh CREDITS
268This distribution is currently maintained by
3f1f8d16 269.An Walter L. Wimer Aq Mt walt+@cmu.edu .
984263bc
MD
270.Pp
271The original BOOTP server was created by
272.An Bill Croft
273at Stanford University in January 1986.
274.Pp
275The current version of
276.Nm
277is primarily the work of
278.An David Kovar ,
279.An Drew D. Perkins ,
280and
281.An Walter L. Wimer ,
282at Carnegie Mellon University.
283.Pp
284Enhancements and bug-fixes have been contributed by:
285.Pp
286(in alphabetical order)
287.Pp
288.An -split
3f1f8d16
FF
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