libexec/bootpd/bootptab.5

   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.2 2003/06/17 04:27:07 dillon 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 RFC1084 vendor field tag number.  Thus it is possible to immediately
 110 take advantage of future extensions to RFC1084 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 RFC1084-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 RFC1084-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 RFC1084
 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 .Pp
 370 .Bd -literal -offset indent
 371 # Sample bootptab file (domain=andrew.cmu.edu)
 372
 373 \&.default:\\
 374         :hd=/usr/boot:bf=null:\\
 375         :ds=netserver, lancaster:\\
 376         :ns=pcs2, pcs1:\\
 377         :ts=pcs2, pcs1:\\
 378         :sm=255.255.255.0:\\
 379         :gw=gw.cs.cmu.edu:\\
 380         :hn:to=-18000:
 381
 382 carnegie:ht=6:ha=7FF8100000AF:tc=.default:
 383 baldwin:ht=1:ha=0800200159C3:tc=.default:
 384 wylie:ht=1:ha=00DD00CADF00:tc=.default:
 385 arnold:ht=1:ha=0800200102AD:tc=.default:
 386 bairdford:ht=1:ha=08002B02A2F9:tc=.default:
 387 bakerstown:ht=1:ha=08002B0287C8:tc=.default:
 388
 389 # Special domain name server and option tags for next host
 390 butlerjct:ha=08002001560D:ds=128.2.13.42:\\
 391         :T37=0x12345927AD3BCF:\\
 392         :T99="Special ASCII string":\\
 393         :tc=.default:
 394
 395 gastonville:ht=6:ha=7FFF81000A47:tc=.default:
 396 hahntown:ht=6:ha=7FFF81000434:tc=.default:
 397 hickman:ht=6:ha=7FFF810001BA:tc=.default:
 398 lowber:ht=1:ha=00DD00CAF000:tc=.default:
 399 mtoliver:ht=1:ha=00DD00FE1600:tc=.default:
 400 .Ed
 401 .Sh FILES
 402 .Bl -tag -width /etc/bootptab -compact
 403 .It /etc/bootptab
 404 .El
 405 .Sh "SEE ALSO"
 406 .Xr bootpd 8 ,
 407 .Xr tftpd 8
 408 .Pp
 409 DARPA Internet Request For Comments RFC951, RFC1048, RFC1084, Assigned Numbers