bootptab(4) Kernel Interfaces Manual bootptab(4)
NAME
bootptab - BOOTP and DHCP server database
DESCRIPTION
The bootptab file is one of several text database files employed by
joind, the BOOTP and DHCP server. The file's format is similar to that
of the termcap(4) file.
Format
There are three types of lines in this file: data, comments, and white-
space (for readability). Data lines can be logically continued onto
the next physical line by preceding the newline character with a back-
slash (\), but the backslash-newline pair is ignored elsewhere.
A comment has the number sign (#) as the first non-whitespace character
on a line that is not a logical continuation of a data line; in no
other context is '#' treated specially. Comments and blank lines are
ignored when the file is parsed by joind but are preserved when editing
with the GUI, xjoin.
Data is organized into groups, the end of a group being identified by
an newline. A data group begins with a label, an optional printable
string and one or more colon-separated fields, each of which carries an
identifying tag used to represent configuration parameters and the
clients to which they apply.
label:tg=value. . . :tg:. . . :tg=value. . . .
The tags currently recognized are listed in dhcptags(4).
The tg is a two-character tag symbol. If tg refers to a data type that
is boolean, it may stand alone to indicate the the boolean is on or
true, though it may also take the (case insensitive) values true,
false, on, off. Other types require a value set off from the tag by an
equals sign. Leading or trailing whitespace surrounding a text value
is removed, but is retained if the string is enclosed in double quotes
(the quotes are stripped internally). The following special syntax is
also understood:
There is also a generic tag, Tn, where n is an integer in the range
1-254. The value may be represented as either a stream of hexadecimal
numbers or as a string of ASCII characters. If the numeric option is
not found in the dhcptags file, the former interpretation is tried
first; if an invalid hexadecimal digit is found, the second interpreta-
tion is used. The dhcptags file obviates the need to use this syntax,
but it is supported for backward-compatibility.
SEMANTICS
In this section, when a reference is made to a specific option, that
option is described by its standard two character identifier in dhcp-
tags. Note: These tags are identical to those in the widely used
Carnegie Mellon implementation of BOOTP, though DHCP defines wholly new
options as well.
The label is a printable string that groups together the tags that fol-
low the label and that can be referenced by the tc tag in other en-
tries. It may be interpreted as a client host name in the following
circumstances only: The data group refers to a specific BOOTP client
The hostname ho tag is not explicitly used The string is a valid host
name
Tags may appear in any order with one exception: the hardware type (ht)
must precede the hardware address (ha) (either explicitly or implic-
itly; see the tc description). The ht tag specifies the hardware type
code as either an unsigned decimal, octal, or hexadecimal integer or
one of the following symbolic names:
tab(@); lfHB lfHB lfHB l l l . _
Value@Symbol@Hardware Type
_
0@@Client Identifier 1@ethernet@10MB Ethernet @ether 2@ethernet3@3 MB
experimental Ethernet @ether3
[email protected] 4@pronet@Proteon ProNET Token
Ring 5@chaos 6@token-ring@IEEE 802 networks @ieee802 @tr 7@arcnet
_
The ha tag takes a value that (except when the type field is zero) is a
hardware address specified in hexadecimal; optional periods, dashes, or
colons may separate the octets for readability; a leading '0x' indicat-
ing hexadecimal data is also permissible. When the type field is zero,
it implies that the ha field will be used to match against a client
identifier, a DHCP concept. The client identifier is an opaque object
of arbitrary length, but may be printable string. Therefore, in the
case of ha, the value is first scanned as hexadecimal; if this scan
does not succeed the value is assumed to be a literal string and is
used as such.
Within each data group, certain tags and the label determine how the
database is to be constructed and searched to resolve a particular
client query. When the server starts up, each data group is internally
assigned to exactly one of 5 hash tables according to the presence of
one or more of the following tags: network IP address vendor class
hardware address/client identifier hardware type
The valid combinations are as follows:
The keys to the hash tables correspond to the values assumed by the tag
or tags. A particular configuration for a client (both DHCP and BOOTP)
is synthesized by searching these tables in the order given for a match
that corresponds to data explicit or implied in the client's BOOTPRE-
QUEST packet. Client parameters resolved earlier in the search take
precedence over those resolved later. Thus, a client configuration is
assembled by searching for parameters starting from most restrictive
match to least. Note: To support BOOTP clients in the manner to which
they are accustomed, you can omit any data groups with the other keys.
Any pre-existing bootptab file fulfills this requirement.
When the server tries to match a data group (partially) keyed by ht -
ha to a specific client, it normally uses the client's hardware type
and hardware address as sent in the htype and chaddr fields. DHCP
clients may choose to identify themselves by the so-called client iden-
tifier option, which they explicitly send to the server. In this in-
stance, the server tries to match to a key in the database by using the
client identifier in place of the harware address and using zero for
the type. DHCP clients that choose to use this mechanism must do so
consistently, and the data sent must constitute a unique identifier.
The client class (ct) is typically a string categorizing clients having
attributes in common, such as the CPU architecture/operating system
pair. Clients identify themselves as belonging to a particular class
by sending this data to the server. A data group in the dhcpcap file
is considered keyed with the class in either of the following ways: Ex-
plicitly by the presence of ct and its value. Implicitly by the data
group containing data items that are specific to a particular vendor.
It is illegal for a data group to contain data items for two or more
vendors (though it is permissible for standard tags to be combined with
vendor tags). It is also illegal for a data group keyed to a specific
class to refer to a data group of a different class with tc. Combina-
tions missing in the list are redundant: for instance, the client ID
always implies a particular vendor class, so there is no need for a
hash having that pair as its key. If the data group contains tags that
over determine the key, the extraneous tags are ignored.
In addition to the internal tables, another table whose purpose is dif-
ferent is formed by a hash on the label. It allows a convenient short-
hand by grouping subsets of parameters together and referencing them as
an ensemble with the reference tag, tc. There may be more than one tc
in a data group, and when encountered they are resolved. However, pa-
rameters that are explicitly named always take precedence over those
implied by tc, regardless of order within an entry. If two or more
continuation tags are found, values resolved from the first named en-
tity take precedence. The converse is true for other tags: if the same
parameter is tagged twice, the last value seen is chosen.
Sometimes it is necessary to delete a specific tag after it has been
implied by tc. This can be done using the construction tag @, which
removes the effect of tag. For example, to completely undo an IEN-116
name server specification, use :ns@: at an appropriate place in the
configuration entry. After removal with @, a tag can be set again
through the tc mechanism.
The remaining tags that imply special logic are described as follows:
The hd (home directory) and bf (bootfile) tags are ASCII strings. The
client's request and the values of the hd and bf symbols determine how
the server fills in the file field of the DHCP/BOOTP reply packet.
If the client specifies an absolute pathname and the file exists on the
server machine, that pathname is returned in the reply packet. If the
file cannot be found, no value is returned. If the client specifies a
relative pathname, a full pathname is formed by prepending the value of
the hd tag. If the hd tag is not supplied in the configuration file,
no value is returned.
If the client sends a null value in the file field, the exact reply de-
pends upon the hd and bf tags. If the bf tag gives an absolute path-
name, that pathname is returned. Otherwise, if the hd and bf tags to-
gether specify an accessible file, that filename is returned in the re-
ply. If a complete filename cannot be determined or the file does not
exist, the file field in the reply contains zeroes.
All filenames are first tried as filename.hostname and then as file-
name, providing for individual per-host bootfiles. The following table
summarizes these possibilities: tab(@); lfHB lfHB lfHB lfHB l l l l .
_
hd tag@bf tag@Received File@Returned File
_
any@any@/c@/c /a@any@/c@/a/c any@/b@null@/b /a@/b@null@/a/b
In all these cases, existence of the file means that, in addition to
actually being present, the file must have its public read access bit
set, since this is required by tftpd(8) to permit the file transfer.
(For other tftpd file access restrictions, see tftp(1).) Also, all
filenames are first tried as filename.hostname and then simply as file-
name, thus providing for individual per-host bootfiles.
Some versions of tftpd provide a security feature to change their root
directory using the chroot(2) system call. You can use the td tag to
inform the joind daemon of this special root directory used by the
tftpd daemon. The hd tag is specified relative to any such root direc-
tory. For example, if the real absolute path to the client's bootfile
is /tftpboot/bootfiles/bootimage, and tftpd uses /tftpboot as its se-
cure directory, specify the following line in the bootptab file:
:td=ftpboot:hd=/bootfiles:bf=bootimage:
If the bootfile is located in the /tftpboot directory, use following
line in the bootptab file:
:td=/tftpboot:hd=/:bf=bootimage:
You can use the sa or si tag to specify the IP address of the particu-
lar TFTP server the client to use. In the absence of either tag, joind
tells the client to perform TFTP to the same machine on which the joind
daemon is running.
Three options, bs, to, and vm, permit the special string auto to be
used as their value string.
The bootfile size (bs) is a decimal, octal, or hexadecimal integer
specifying the size of the bootfile in 512-octet blocks. If the keyword
auto is specified, the server should consult the file system to deter-
mine the size of the boot image. This assumes that the server is also
the TFTP host for the client's boot image. As with the time offset,
specifying the bs tag as a Boolean has the same effect as specifying
auto as its value.
The time offset (to) is a signed decimal integer specifying the
client's time zone offset in seconds from UTC. If the keyword auto is
specified, the client should use the server's time zone offset. Speci-
fying the to symbol as a Boolean has the same effect as specifying auto
as its value.
The vendor magic cookie selector (vm) tells the server the style of op-
tion-encoding that the client wishes to receive. The tag can take one
of the following keywords: Indicates that vendor information is deter-
mined by the client's request. Always forces an RFC 1048/RFC
1033-style reply. DHCP clients must always send the rfc1048 cookie or
they will be treated as BOOTP clients. Always forces a CMU-style re-
ply.
The encoding chosen is based primarily on the value of the magic cookie
in the options field of the BOOTPREQUEST from the client. If it is
present, the magic cookie must be either the rfc1048 cookie or the cmu
cookie. If this cookie is not present, the server will determine the
encoding from the value of vm.
The following table summarizes the possibilities. None means that al-
though the vendor field will be empty, the file and sname fields will
be returned with the client's IP address.
bootptab file
bootprequest none rfc1048 cmu auto
------------ -------------------------------
unrecognized none rfc1048 cmu none
rfc1048 rfc1048 rfc1048 rfc1048 rfc1048
cmu cmu cmu cmu cmu
The remaining tags describe actual client configuration data. The bw,
bx, cs, ds, gw, im, lg, lp, ns, nt, ra, rl, sr, ts, xd, and xs tags
take a whitespace-separated list of IP addresses or hostnames, while
the ba, ip, sa, si, sm, and sw tags each take a single IP address. The
legal formats that may be used for character string representations of
IP addresses are described in join.ipaddresses(4).
When a host name is specified instead of an IP address, the joind dae-
mon looks up the IP addresses for that host name using the gethostby-
name routine. If the ip tag is not specified, the joind daemon deter-
mines the IP address using the entry name as the host name. (Dummy en-
tries use an invalid host name to avoid automatic IP lookup.)
Since the gw tag is an extendable tagged subfield, you must also spec-
ify the vm=rfc1048 tag in order to pass the information to the client
in an appropriate RFC1048/RFC1033-style reply.
BOOTP Semantics
For BOOTP usage, the label in the general file format is hostname, the
name of a BOOTP client. Dummy entries have an invalid host name (one
with a period (.) as the first character) and are used to provide de-
fault values used by other entries through the tc=.dummy-entry mecha-
nism. The recognized BOOTP tags are as follows: Boot file Boot file
size (512 octet blocks) Cookie servers Dump file DNS domain name Domain
name servers Encapsulate flavor Gateways (IP rosters) Hardware address
Home directory Send host name Hardware type Impress servers Host or
network IP address Log servers LPR servers IEN-116 name servers Reply
address override Resource location protocol servers Root path TFTP
server address (used by clients) Subnet mask (host) Swap server address
Template host (points to similar host entry) TFTP root directory (used
by secure TFTP server) Time offset (seconds) Time servers Vendor magic
cookie selector
EXAMPLES
A sample bootptab for BOOTP support is as follows: # Sample bootptab
file for BOOTP support
.default1:\ :hd=/usr/boot:bf=null:\ :ds=128.2.35.50 128.2.13.21:\
:ns=128.2.11.77 128.2.15.25:\ :ts=128.2.11.77 128.2.15.25:\
:sm=255.255.0.0:gw=128.2.254.36:\ :hn:vm=auto:to=-18000:\
:T37=0x12345927AD3DCF:T99="Special ASCII string":
carnegie:ht=6:ha=7FF8100000AF:ip=128.2.11.1:tc=.default1: bald-
win:ht=1:ha=0800200159C3:ip=128.2.11.10:tc=.default1:
wylie:ht=1:ha=00DD00CADF00:ip=128.2.11.100:tc=.default1:
arnold:ht=1:ha=0800200102AD:ip=128.2.11.102:tc=.default1: baird-
ford:ht=1:ha=08002B02A2F9:ip=128.2.11.103:tc=.default1: baker-
stown:ht=1:ha=08002B0287C8:ip=128.2.11.104:tc=.default1:
# Special domain name server for next host
bojct:ht=1:ha=08002001560D:ip=128.2.11.108:ds=128.2.13.42:tc=.default1:
gastonville:ht=6:ha=7FFF81000A47:ip=128.2.11.115:tc=.default1: hahn-
town:ht=6:ha=7FFF81000434:ip=128.2.11.117:tc=.default1: hick-
man:ht=6:ha=7FFF810001BA:ip=128.2.11.118:tc=.default1: low-
ber:ht=1:ha=00DD00CAF000:ip=128.2.11.121:tc=.default1: mto-
liver:ht=1:ha=00DD00FE1600:ip=128.2.11.122:tc=.default1:
FILES
/etc/bootptab
RELATED INFORMATION
Daemons: joind(8), tftpd(8).
Files: dhcptags(4).
DARPA Internet Request For Comments: DHCP Options and BOOTP Vendor Ex-
tensions (RFC 1533), Dynamic Host Configuration Protocol (RFC 1541) de-
lim off
bootptab(4)