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