| blob | ac975a1f59844a272ec925733b56a7202a206baf |
1 .\" Copyright (c) 1988, 1989, 1991 Carnegie Mellon University
2 .\"
3 .\" $FreeBSD: src/libexec/bootpd/bootptab.5,v 1.4.2.4 2001/08/16 10:44:13 ru Exp $
4 .\" $DragonFly: src/libexec/bootpd/bootptab.5,v 1.4 2008/05/02 02:05:04 swildner Exp $
5 .\"
6 .Dd October 31, 1991
7 .Dt BOOTPTAB 5
8 .Os
9 .Sh NAME
10 .Nm bootptab
11 .Nd Internet Bootstrap Protocol server database
12 .Sh DESCRIPTION
13 The
14 .Nm
15 file is the configuration database file for
16 .Xr bootpd 8 ,
17 the Internet Bootstrap Protocol server.
18 Its format is similar to that of
19 .Xr termcap 5
20 in which two-character case-sensitive tag symbols are used to
21 represent host parameters. These parameter declarations are separated by
22 colons (:), with a general format of:
23 .Pp
24 .Dl "hostname:tg=value. . . :tg=value. . . :tg=value. . . ."
25 .Pp
26 where
27 .Em hostname
28 is the actual name of a bootp client (or a "dummy entry"), and
29 .Em tg
30 is a two-character tag symbol. Dummy entries have an invalid hostname
31 (one with a "." as the first character) and are used to provide
32 default values used by other entries via the
33 .Em tc=.dummy-entry
34 mechanism. Most tags must be followed by an equals-sign
35 and a value as above. Some may also appear in a boolean form with no
36 value (i.e.\&
37 .Em :tg: ) .
38 The currently recognized tags are:
39 .Pp
40 .Bl -tag -width xxx -compact
41 .It bf
42 Bootfile
43 .It bs
44 Bootfile size in 512-octet blocks
45 .It cs
46 Cookie server address list
47 .It df
48 Merit dump file
49 .It dn
50 Domain name
51 .It ds
52 Domain name server address list
53 .It ef
54 Extension file
55 .It gw
56 Gateway address list
57 .It ha
58 Host hardware address
59 .It hd
60 Bootfile home directory
61 .It hn
62 Send client's hostname to client
63 .It ht
64 Host hardware type (see Assigned Numbers RFC)
65 .It im
66 Impress server address list
67 .It ip
68 Host IP address
69 .It lg
70 Log server address list
71 .It lp
72 LPR server address list
73 .It ns
74 IEN-116 name server address list
75 .It nt
76 NTP (time) Server (RFC 1129)
77 .It ra
78 Reply address override
79 .It rl
80 Resource location protocol server address list
81 .It rp
82 Root path to mount as root
83 .It sa
84 TFTP server address client should use
85 .It sm
86 Host subnet mask
87 .It sw
88 Swap server address
89 .It tc
90 Table continuation (points to similar "template" host entry)
91 .It td
92 TFTP root directory used by "secure" TFTP servers
93 .It to
94 Time offset in seconds from UTC
95 .It ts
96 Time server address list
97 .It vm
98 Vendor magic cookie selector
99 .It yd
100 YP (NIS) domain name
101 .It ys
102 YP (NIS) server address
103 .El
104 .Pp
105 There is also a generic tag,
106 .Pf T Em n ,
107 where
108 .Em n
109 is an RFC 1084 vendor field tag number. Thus it is possible to immediately
110 take advantage of future extensions to RFC 1084 without being forced to modify
111 .Nm bootpd
112 first. Generic data may be represented as either a stream of hexadecimal
113 numbers or as a quoted string of
114 .Tn ASCII
115 characters. The length of the generic
116 data is automatically determined and inserted into the proper field(s) of the
117 RFC 1084 style bootp reply.
118 .Pp
119 The following tags take a whitespace-separated list of IP addresses:
120 .Em cs ,
121 .Em ds ,
122 .Em gw ,
123 .Em im ,
124 .Em lg ,
125 .Em lp ,
126 .Em ns ,
127 .Em nt ,
128 .Em ra ,
129 .Em rl ,
130 and
131 .Em ts .
132 The
133 .Em ip ,
134 .Em sa ,
135 .Em sw ,
136 .Em sm ,
137 and
138 .Em ys
139 tags each take a single IP address.
140 All IP addresses are specified in standard Internet "dot" notation
141 and may use decimal, octal, or hexadecimal numbers
142 (octal numbers begin with 0, hexadecimal numbers begin with '0x' or '0X').
143 Any IP addresses may alternatively be specified as a hostname, causing
144 .Nm bootpd
145 to lookup the IP address for that host name using
146 .Xr gethostbyname 3 .
147 If the
148 .Em ip
149 tag is not specified,
150 .Nm bootpd
151 will determine the IP address using the entry name as the host name.
152 (Dummy entries use an invalid host name to avoid automatic IP lookup.)
153 .Pp
154 The
155 .Em ht
156 tag specifies the hardware type code as either an unsigned decimal, octal, or
157 hexadecimal integer or one of the following symbolic names:
158 .Em ethernet
159 or
160 .Em ether
161 for 10Mb Ethernet,
162 .Em ethernet3
163 or
164 .Em ether3
165 for 3Mb experimental Ethernet,
166 .Em ieee802 ,
167 .Em tr ,
168 or
169 .Em token-ring
170 for IEEE 802 networks,
171 .Em pronet
172 for Proteon ProNET Token Ring, or
173 .Em chaos ,
174 .Em arcnet ,
175 or
176 .Em ax.25
177 for Chaos, ARCNET, and AX.25 Amateur Radio networks, respectively.
178 The
179 .Em ha
180 tag takes a hardware address which may be specified as a host name
181 or in numeric form. Note that the numeric form
182 .Em must
183 be specified in hexadecimal; optional periods and/or a leading '0x' may be
184 included for readability. The
185 .Em ha
186 tag must be preceded by the
187 .Em ht
188 tag (either explicitly or implicitly; see
189 .Em tc
190 below).
191 If the hardware address is not specified and the type is specified
192 as either "ethernet" or "ieee802", then
193 .Nm bootpd
194 will try to determine the hardware address using
195 .Xr ether_hostton 3 .
196 .Pp
197 The hostname, home directory, and bootfile are
198 .Tn ASCII
199 strings which may be
200 optionally surrounded by double quotes ("). The client's request and the
201 values of the
202 .Em hd
203 and
204 .Em bf
205 symbols determine how the server fills in the bootfile field of the bootp
206 reply packet.
207 .Pp
208 If the client provides a file name it is left as is.
209 Otherwise, if the
210 .Em bf
211 option is specified its value is copied into the reply packet.
212 If the
213 .Em hd
214 option is specified as well, its value is prepended to the
215 boot file copied into the reply packet.
216 The existence of the boot file is checked only if the
217 .Em bs Ns =auto
218 option is used (to determine the boot file size).
219 A reply may be sent whether or not the boot file exists.
220 .Pp
221 Some newer versions of
222 .Xr tftpd 8
223 provide a security feature to change their root directory using
224 the
225 .Xr chroot 2
226 system call.
227 The
228 .Em td
229 tag may be used to inform
230 .Nm bootpd
231 of this special root directory used by
232 .Nm tftpd .
233 (One may alternatively use the
234 .Nm bootpd
235 .Fl c Ar chdir
236 option.)
237 The
238 .Em hd
239 tag is actually relative to the root directory specified by the
240 .Em td
241 tag.
242 For example, if the real absolute path to your BOOTP client bootfile is
243 .Pa /tftpboot/bootfiles/bootimage ,
244 and
245 .Nm tftpd
246 uses
247 .Pa /tftpboot
248 as its "secure" directory, then specify the following in
249 .Pa bootptab :
250 .Pp
251 .Dl :td=/tftpboot:hd=/bootfiles:bf=bootimage:
252 .Pp
253 If your bootfiles are located directly in
254 .Pa /tftpboot ,
255 use:
256 .Pp
257 .Dl :td=/tftpboot:hd=/:bf=bootimage:
258 .Pp
259 The
260 .Em sa
261 tag may be used to specify the IP address of the particular TFTP server
262 you wish the client to use. In the absence of this tag,
263 .Nm bootpd
264 will tell the client to perform TFTP to the same machine
265 .Nm bootpd
266 is running on.
267 .Pp
268 The time offset
269 .Em to
270 may be either a signed decimal integer specifying the client's
271 time zone offset in seconds from UTC, or the keyword
272 .Em auto
273 which uses the server's time zone offset. Specifying the
274 .Em to
275 symbol as a boolean has the same effect as specifying
276 .Em auto
277 as its value.
278 .Pp
279 The bootfile size
280 .Em bs
281 may be either a decimal, octal, or hexadecimal integer specifying the size of
282 the bootfile in 512-octet blocks, or the keyword
283 .Em auto
284 which causes the server to automatically calculate the bootfile size at each
285 request. As with the time offset, specifying the
286 .Em bs
287 symbol as a boolean has the same effect as specifying
288 .Em auto
289 as its value.
290 .Pp
291 The vendor magic cookie selector (the
292 .Em vm
293 tag) may take one of the following keywords:
294 .Em auto
295 (indicating that vendor information is determined by the client's request),
296 .Em rfc1048
297 or
298 .Em rfc1084
299 (which always forces an RFC 1084 style reply), or
300 .Em cmu
301 (which always forces a CMU style reply).
302 .Pp
303 The
304 .Em hn
305 tag is strictly a boolean tag; it does not take the usual equals-sign and
306 value. Its presence indicates that the hostname should be sent to RFC 1084
307 clients.
308 .Nm Bootpd
309 attempts to send the entire hostname as it is specified in the configuration
310 file; if this will not fit into the reply packet, the name is shortened to
311 just the host field (up to the first period, if present) and then tried.
312 In no case is an arbitrarily-truncated hostname sent (if nothing reasonable
313 will fit, nothing is sent).
314 .Pp
315 Often, many host entries share common values for certain tags (such as name
316 servers, etc.). Rather than repeatedly specifying these tags, a full
317 specification can be listed for one host entry and shared by others via the
318 .Em tc
319 (table continuation) mechanism.
320 Often, the template entry is a dummy host which doesn't actually exist and
321 never sends bootp requests. This feature is similar to the
322 .Em tc
323 feature of
324 .Xr termcap 5
325 for similar terminals. Note that
326 .Nm bootpd
327 allows the
328 .Em tc
329 tag symbol to appear anywhere in the host entry, unlike
330 .Pa termcap
331 which requires it to be the last tag. Information explicitly specified for a
332 host always overrides information implied by a
333 .Em tc
334 tag symbol, regardless of its location within the entry. The
335 value of the
336 .Em tc
337 tag may be the hostname or IP address of any host entry
338 previously listed in the configuration file.
339 .Pp
340 Sometimes it is necessary to delete a specific tag after it has been inferred
341 via
342 .Em tc .
343 This can be done using the construction
344 .Em tag Ns @
345 which removes the effect of
346 .Em tag
347 as in
348 .Xr termcap 5 .
349 For example, to completely undo an IEN-116 name server specification, use
350 .Em :ns@:
351 at an appropriate place in the configuration entry. After removal
352 with
353 .Em @ ,
354 a tag is eligible to be set again through the
355 .Em tc
356 mechanism.
357 .Pp
358 Blank lines and lines beginning with "#" are ignored in the configuration
359 file. Host entries are separated from one another by newlines; a single host
360 entry may be extended over multiple lines if the lines end with a backslash
361 (\\). It is also acceptable for lines to be longer than 80 characters. Tags
362 may appear in any order, with the following exceptions: the hostname must be
363 the very first field in an entry, and the hardware type must precede the
364 hardware address.
365 .Pp
366 An example
367 .Pa /etc/bootptab
368 file follows:
369 .Bd -literal -offset indent
370 # Sample bootptab file (domain=andrew.cmu.edu)
372 \&.default:\\
373 :hd=/usr/boot:bf=null:\\
374 :ds=netserver, lancaster:\\
375 :ns=pcs2, pcs1:\\
376 :ts=pcs2, pcs1:\\
377 :sm=255.255.255.0:\\
378 :gw=gw.cs.cmu.edu:\\
379 :hn:to=-18000:
381 carnegie:ht=6:ha=7FF8100000AF:tc=.default:
382 baldwin:ht=1:ha=0800200159C3:tc=.default:
383 wylie:ht=1:ha=00DD00CADF00:tc=.default:
384 arnold:ht=1:ha=0800200102AD:tc=.default:
385 bairdford:ht=1:ha=08002B02A2F9:tc=.default:
386 bakerstown:ht=1:ha=08002B0287C8:tc=.default:
388 # Special domain name server and option tags for next host
389 butlerjct:ha=08002001560D:ds=128.2.13.42:\\
390 :T37=0x12345927AD3BCF:\\
391 :T99="Special ASCII string":\\
392 :tc=.default:
394 gastonville:ht=6:ha=7FFF81000A47:tc=.default:
395 hahntown:ht=6:ha=7FFF81000434:tc=.default:
396 hickman:ht=6:ha=7FFF810001BA:tc=.default:
397 lowber:ht=1:ha=00DD00CAF000:tc=.default:
398 mtoliver:ht=1:ha=00DD00FE1600:tc=.default:
399 .Ed
400 .Sh FILES
401 .Bl -tag -width /etc/bootptab -compact
402 .It /etc/bootptab
403 .El
404 .Sh "SEE ALSO"
405 .Xr bootpd 8 ,
406 .Xr tftpd 8
407 .Pp
408 DARPA Internet Request For Comments RFC 951, RFC 1048, RFC 1084,
409 Assigned Numbers