NetBSD/libexec/bootpd/bootptab.5

.\" Copyright (c) 1988, 1989, 1991 Carnegie Mellon University
.\"
.\"	$Header: /cvsroot/src/libexec/bootpd/Attic/bootptab.5,v 1.1 1994/04/18 05:15:58 glass Exp $
.\"
.TH BOOTPTAB 5 "October 31, 1991" "Carnegie Mellon University"
.UC 6

.SH NAME
bootptab \- Internet Bootstrap Protocol server database
.SH DESCRIPTION
The
.I bootptab
file is the configuration database file for
.IR bootpd ,
the Internet Bootstrap Protocol server.
It's format is similar to that of
.IR termcap (5)
in which two-character case-sensitive tag symbols are used to
represent host parameters.  These parameter declarations are separated by
colons (:), with a general format of:
.PP
.I "	hostname:tg=value. . . :tg=value. . . :tg=value. . . ."
.PP
where
.I hostname
is the actual name of a bootp client and
.I tg
is a two-character tag symbol.  Most tags must be followed by an equals-sign
and a value as above.  Some may also appear in a boolean form with no
value (i.e.
.RI : tg :).
The currently recognized tags are:
.PP
.br
	bf	Bootfile
.br
	bs	Bootfile size in 512-octet blocks
.br
	cs	Cookie server address list
.br
	df	Merit dump file
.br
	dn	Domain name
.br
	ds	Domain name server address list
.br
	gw	Gateway address list
.br
	ha	Host hardware address
.br
	hd	Bootfile home directory
.br
	hn	Send client's hostname to client
.br
	ht	Host hardware type (see Assigned Numbers RFC)
.br
	im	Impress server address list
.br
	ip	Host IP address
.br
	lg	Log server address list
.br
	lp	LPR server address list
.br
	ns	IEN-116 name server address list
.br
	rl	Resource location protocol server address list
.br
	rp	Root path to mount as root
.br
	sa	TFTP server address client should use
.br
	sm	Host subnet mask
.br
	sw	Swap server address
.br
	tc	Table continuation (points to similar "template" host entry)
.br
	td	TFTP root directory used by "secure" TFTP servers
.br
	to	Time offset in seconds from UTC
.br
	ts	Time server address list
.br
	vm	Vendor magic cookie selector

.PP
There is also a generic tag,
.RI T n ,
where
.I n
is an RFC1084 vendor field tag number.  Thus it is possible to immediately
take advantage of future extensions to RFC1084 without being forced to modify
.I bootpd
first.  Generic data may be represented as either a stream of hexadecimal
numbers or as a quoted string of ASCII characters.  The length of the generic
data is automatically determined and inserted into the proper field(s) of the
RFC1084-style bootp reply.
.PP
The following tags take a whitespace-separated list of IP addresses:
.BR cs ,
.BR ds ,
.BR gw ,
.BR im ,
.BR lg ,
.BR lp ,
.BR ns ,
.BR rl ,
and
.BR ts .
The
.BR ip ,
.BR sa ,
.BR sw ,
and
.B sm
tags each take a single IP address.
All IP addresses are specified in standard Internet "dot" notation and may use
decimal, octal, or hexadecimal numbers (octal numbers begin with 0,
hexadecimal numbers begin with '0x' or '0X').
.PP
The
.B ht
tag specifies the hardware type code as either an unsigned decimal, octal, or
hexadecimal integer or one of the following symbolic names:
.B ethernet
or
.B ether
for 10Mb Ethernet,
.B ethernet3
or
.B ether3
for 3Mb experimental Ethernet,
.BR ieee802 ,
.BR tr ,
or
.B token-ring
for IEEE 802 networks,
.B pronet
for Proteon ProNET Token Ring, or
.BR chaos ,
.BR arcnet ,
or
.B ax.25
for Chaos, ARCNET, and AX.25 Amateur Radio networks, respectively.
The
.B ha
tag takes a hardware address which
.I must
be specified in hexadecimal; optional periods and/or a leading '0x' may be
included for readability.  The
.B ha
tag must be preceded by the
.B ht
tag (either explicitly or implicitly; see
.B tc
below).
.PP
The hostname, home directory, and bootfile are ASCII strings which may be
optionally surrounded by double quotes (").  The client's request and the
values of the
.B hd
and
.B bf
symbols determine how the server fills in the bootfile field of the bootp
reply packet.
.PP
If the client specifies an absolute pathname and that file exists on the
server machine, that pathname is returned in the reply packet.  If the file
cannot be found, the request is discarded; no reply is sent.  If the client
specifies a relative pathname, a full pathname is formed by prepending the
value of the
.B hd
tag and testing for existence of the file.  If the
.B hd
tag is not supplied in the configuration file or if the resulting boot file
cannot be found, then the request is discarded.
.PP
Clients which specify null boot files will always elicit a reply from the
server.  The exact reply will again depend upon the
.B hd
and
.B bf
tags.  If the
.B bf
tag gives an absolute pathname and the file exists, that pathname is returned
in the reply packet.  Otherwise, if the
.B hd
and
.B bf
tags together specify an accessible file, that filename is returned in the
reply.  If a complete filename cannot be determined or the file does not
exist, the reply will contain a zeroed-out bootfile field.
.PP
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
.IR tftpd (8)
to permit the file transfer.  Also, all filenames are first tried as
.I filename.hostname
and then simply as
.IR filename ,
thus providing for individual per-host bootfiles.
.PP
Some newer versions of
.I tftpd
provide a security feature to change their root directory using
the
.IR chroot (2)
system call.
The
.B td
tag may be used to inform
.I bootpd
of this special root directory used by
.IR tftpd .
The
.B hd
tag is actually relative to the root directory specified by the
.B td
tag.
For example, if the real absolute path to your BOOTP client bootfile is
/tftpboot/bootfiles/bootimage, and
.IR tftpd
uses /tftpboot as its "secure" directory, then specify the following in
.IR bootptab :
.PP
.br
	:td=/tftpboot:hd=/bootfiles:bf=bootimage:
.PP
If your bootfiles are located directly in /tftpboot, use:
.PP
.br
	:td=/tftpboot:hd=/:bf=bootimage:
.PP
The
.B sa
tag may be used to specify the IP address of the particular TFTP server
you wish the client to use.  In the absence of this tag,
.I bootpd
will tell the client to perform TFTP to the same machine
.I bootpd
is running on.
.PP
The time offset
.B to
may be either a signed decimal integer specifying the client's
time zone offset in seconds from UTC, or the keyword
.B auto
which uses the server's time zone offset.  Specifying the
.B to
symbol as a boolean has the same effect as specifying
.B auto
as its value.
.PP
The bootfile size
.B bs
may be either a decimal, octal, or hexadecimal integer specifying the size of
the bootfile in 512-octet blocks, or the keyword
.B auto
which causes the server to automatically calculate the bootfile size at each
request.  As with the time offset, specifying the
.B bs
symbol as a boolean has the same effect as specifying
.B auto
as its value.
.PP
The vendor magic cookie selector (the
.B vm
tag) may take one of the following keywords:
.B auto
(indicating that vendor information is determined by the client's request),
.B rfc1048
or
.B rfc1084
(which always forces an RFC1084-style reply), or
.B cmu
(which always forces a CMU-style reply).
.PP
The
.B hn
tag is strictly a boolean tag; it does not take the usual equals-sign and
value.  It's presence indicates that the hostname should be sent to RFC1084
clients.
.I Bootpd
attempts to send the entire hostname as it is specified in the configuration
file; if this will not fit into the reply packet, the name is shortened to
just the host field (up to the first period, if present) and then tried.
In no case is an arbitrarily-truncated hostname sent (if nothing reasonable
will fit, nothing is sent).
.PP
Often, many host entries share common values for certain tags (such as name
servers, etc.).  Rather than repeatedly specifying these tags, a full
specification can be listed for one host entry and shared by others via the
.B tc
(table continuation) mechanism.
Often, the template entry is a dummy host which doesn't actually exist and
never sends bootp requests.  This feature is similar to the
.B tc
feature of
.IR termcap (5)
for similar terminals.  Note that
.I bootpd
allows the
.B tc
tag symbol to appear anywhere in the host entry, unlike
.I termcap
which requires it to be the last tag.  Information explicitly specified for a
host always overrides information implied by a
.B tc
tag symbol, regardless of its location within the entry.  The
value of the
.B tc
tag may be the hostname or IP address of any host entry
previously listed in the configuration file.
.PP
Sometimes it is necessary to delete a specific tag after it has been inferred
via
.BR tc .
This can be done using the construction
.IB tag @
which removes the effect of
.I tag
as in
.IR termcap (5).
For example, to completely undo an IEN-116 name server specification, use
":ns@:" at an appropriate place in the configuration entry.  After removal
with
.BR @ ,
a tag is eligible to be set again through the
.B tc
mechanism.
.PP
Blank lines and lines beginning with "#" are ignored in the configuration
file.  Host entries are separated from one another by newlines; a single host
entry may be extended over multiple lines if the lines end with a backslash
(\\).  It is also acceptable for lines to be longer than 80 characters.  Tags
may appear in any order, with the following exceptions:  the hostname must be
the very first field in an entry, and the hardware type must precede the
hardware address.
.PP
An example
.I /etc/bootptab
file follows:
.PP

.br
	# Sample bootptab file

.br
	default1:\\
.br
		:hd=/usr/boot:bf=null:\\
.br
		:ds=128.2.35.50 128.2.13.21:\\
.br
		:ns=0x80020b4d 0x80020ffd:\\
.br
		:ts=0x80020b4d 0x80020ffd:\\
.br
		:sm=255.255.0.0:gw=0x8002fe24:\\
.br
		:hn:vm=auto:to=-18000:\\
.br
		:T37=0x12345927AD3BCF:T99="Special ASCII string":

.br
	carnegie:ht=6:ha=7FF8100000AF:ip=128.2.11.1:tc=default1:
.br
	baldwin:ht=1:ha=0800200159C3:ip=128.2.11.10:tc=default1:
.br
	wylie:ht=1:ha=00DD00CADF00:ip=128.2.11.100:tc=default1:
.br
	arnold:ht=1:ha=0800200102AD:ip=128.2.11.102:tc=default1:
.br
	bairdford:ht=1:ha=08002B02A2F9:ip=128.2.11.103:tc=default1:
.br
	bakerstown:ht=1:ha=08002B0287C8:ip=128.2.11.104:tc=default1:

.br
	# Special domain name server for next host
.br
	butlerjct:ht=1:ha=08002001560D:ip=128.2.11.108:ds=128.2.13.42:tc=default1:

.br
	gastonville:ht=6:ha=7FFF81000A47:ip=128.2.11.115:tc=default1:
.br
	hahntown:ht=6:ha=7FFF81000434:ip=128.2.11.117:tc=default1:
.br
	hickman:ht=6:ha=7FFF810001BA:ip=128.2.11.118:tc=default1:
.br
	lowber:ht=1:ha=00DD00CAF000:ip=128.2.11.121:tc=default1:
.br
	mtoliver:ht=1:ha=00DD00FE1600:ip=128.2.11.122:tc=default1:


.SH FILES
/etc/bootptab

.SH "SEE ALSO"
.br
bootpd(8), tftpd(8),
.br
DARPA Internet Request For Comments RFC951, RFC1048, RFC1084, Assigned Numbers