libexec/bootpd/bootptab.5

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