libexec/bootpd/bootptab.5

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