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