BOOTPTAB(5)

NAME
bootptab - client database for dhcpd (BootP and DHCP server)

DESCRIPTION
The bootptab file is the configuration database file for dhcpd(8), a BootP and DHCP server.

This manual page describes the bootptab file read by Carnegie Mellon University's dhcpd(8) version 3.3.7 with the Princeton patches installed.

The default location of this file is /etc/bootptab, but that may be overridden via a commandline option to dhcpd(8) or a compile-time option when building dhcpd.

The format of the bootptab file is similar to that of 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:

hostname:tg=value. . . :tg=value. . . :tg=value. . . .

where hostname is the actual name of a client (or a "dummy entry"), and 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. :tg:).

Blank lines and lines beginning with "#" are ignored.

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; no entry may be longer than 1024 characters or 256 tokens. Tag values which are ASCII strings are limited to 80 characters.

Within an entry, 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, if a hardware address is specified.

Dummy entries are those with an invalid hostname (one with a "." as the first character) and are used to provide default values used by other entries via the tc=.dummy-entry mechanism.

TAGS

The currently recognized tags are:

    ba    IP Broadcast address
    be BootP exclude tag list
    bf    Bootfile
    bi BootP include tag list
    bs    Bootfile size in 512-octet blocks
    cf    Client FQDN
    cl    (DHCP) Client Identifier (unquoted hex string)
    cr Non-Local Source Routing Enable/Disable
    cs    Cookie server address list
    dd    Deny client dynamically-assigned IP addresses
    de    Deny client BOOTP and DHCP service
    df    Merit dump file
    dl    (DHCP) Lease time offered, in seconds
    dn    Domain name
    ds    Domain name server address list
    dy    This is an IP address that is assigned dynamically
    ef    Extension file
    en Ethernet encapsulation
    fi default finger server address list
    gw    IP Gateway address list
    ha    Client hardware address
    hd    Bootfile home directory
    hn    Send client's hostname to client
    ht    Host hardware type (see Assigned Numbers RFC)
    if IP Forwarding Enable/Disable
    im    Impress server address list
    ip    Host IP address
    ir default Internet Relay Chat (IRC) server address list
    kg TCP Keepalive Garbage
    lg    Log server address list
    lp    LPR server address list
    ma Simple Mail Transport Protocol (SMTP) server address list
    md Perform Mask Discovery
    ml    (DHCP) Maximum lease allowed, in seconds
    mu Mask Supplier
    nd NetBIOS over TCP/IP Datagram Distribution server address list
    nn Network News Transport Protocol (NNTP) server address list
    no    (DHCP) NetBIOS over TCP/IP Node Type
    nr (DHCP) Send even Non-Requested parameters
    ns    IEN-116 name server address list
    nt    NTP (time) Server (RFC 1129)
    pd Network Information Service+ (NIS+) Domain name
    po Post Office Protocol (POP3) server address list
    ps Network Information Service+ (NIS+) server address list
    ra    Reply address override
    rb    (DHCP) Seconds until client goes to REBINDING state
    rd    Perform router discovery
    rl    Resource location protocol server address list
    rn    (DHCP) Seconds until client goes to RENEWING state
    ro    (DHCP) Allow access to roaming-restricted dynamic addrs.
    rp    Root path to mount as root
    rs Router Solicitation Address
    sa    TFTP server IP address client should use
    sc    (DHCP) NetBIOS over TCP/IP Scope
    sl All Subnets are Local
    sm    Subnet mask
    sr    Static route
    sw    Swap server address
    tc    Table continuation (points to similar "template" host entry)
    td    TFTP root directory used by "secure" TFTP servers
    te trailer encapsulation
    tl TCP Default TTL
    to    Time offset in seconds from UTC
    ts    Time server address list
    tt Default IP Time-to-live (TTL)
    vm    Vendor magic cookie selector
    ws    (DHCP) NetBIOS over TCP/IP Name Server
    ww default World Wide Web (WWW) server address list
    xd X Windows System Display Manager address list
    xf X Windows System Font Server address list
    yd    YP (NIS) domain name
    ys    YP (NIS) server address

There is also a generic tag, Tn, where n is an RFC1084 vendor field tag number. Thus it may be possible to immediately take advantage of new BootP vendor extensions and DHCP options without being forced to modify dhcpd first. Generic data may be represented as either a stream of hexadecimal numbers (e.g. T200=12a7b5 or T200=0x12a7b5 or T200=12.a7.b5 or T200=0x12.a7.b5) or as a quoted string of ASCII characters (e.g. T201="foo"). Do not include a "length" value in the generic value; it will be computed automatically. It is a syntax error to specify a generic tag of zero length (e.g. :T202: or :T201=:). Do not use the generic tag syntax to specify a tag which has a well-defined bootptab tag name; if you do, results may be unpredictable. Tag numbers 0 and 255 may not be specified as generic tags.

The following tags take a whitespace-separated list of IP addresses: cs, ds, fi, gw, im, ir, lg, lp, ma, po, nd, ns, nt,
ra, rl, ts, ww, xd, and xf. The ip, rs, sa, sw, sm, and ys 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'). Any IP address may alternatively be specified as a hostname, causing dhcpd to lookup the IP address for that host name using gethostbyname(3). If the ip tag is not specified, dhcpd will determine the IP address using the entry name as the host name. (Dummy entries use an invalid host name to avoid automatic IP lookup.)

The sr tag takes a whitespace-separated list of IP addresses; the number of IP addresses must be a multiple of two. (Each pair of IP addresses is interpreted as a destination address, and a router address.)

The ht tag specifies the hardware type code as either an unsigned decimal, octal, or hexadecimal integer or one of the following symbolic names: ethernet or ether for 10Mb Ethernet, ethernet3 or ether3 for 3Mb experimental Ethernet, ieee802, tr, or token-ring for IEEE 802 networks, pronet for Proteon ProNET Token Ring, or chaos, arcnet, or ax.25 for Chaos, ARCNET, and AX.25 Amateur Radio networks, respectively. The ha tag takes a hardware address which may be specified as a host name or in numeric form. Note that the numeric form must be specified in hexadecimal; optional periods and/or a leading '0x' may be included for readability. The ha tag must be preceded by the ht tag (either explicitly or implicitly; see tc below). If the hardware address is not specified and the type is specified as either "ethernet" or "ieee802", then dhcpd will try to determine the hardware address using ether_hton(3).

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 hd and bf symbols determine how the server fills in the bootfile field of the bootp reply packet.

If a BootP client provides a bootfile name it is left as is. Otherwise, if the bf option is specified its value is copied into the BootP reply packet. If the hd option is specified as well, its value is prepended to the bootfile copied into the BootP reply packet. The existence of the boot file is checked only if the bs=auto option is used (to determine the boot file size). A reply may be sent whether or not the boot file exists.

Some newer versions of tftpd provide a security feature to change their root directory using the chroot(2) system call. The td tag may be used to inform dhcpd of this special root directory used by tftpd. (One may alternatively use the dhcpd "-c chdir" option.) The hd tag is actually relative to the root directory specified by the td tag. For example, if the real absolute path to your client bootfile is /tftpboot/bootfiles/bootimage, and tftpd uses /tftpboot as its "secure" directory, then specify the following in bootptab:

    :td=/tftpboot:hd=/bootfiles:bf=bootimage:

If your bootfiles are located directly in /tftpboot, use:

    :td=/tftpboot:hd=/:bf=bootimage:

The 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, dhcpd will tell a BootP client to perform TFTP to the same machine dhcpd is running on.

The time offset to may be either a signed decimal integer specifying the client's time zone offset in seconds from UTC, or the keyword auto which uses the server's time zone offset. Specifying the to symbol as a boolean has the same effect as specifying auto as its value.

The bootfile size bs may be either a decimal, octal, or hexadecimal integer specifying the size of the bootfile in 512-octet blocks, or the keyword auto which causes the server to automatically calculate the bootfile size at each request. As with the time offset, specifying the bs symbol as a boolean has the same effect as specifying auto as its value.

The vendor magic cookie selector (the vm tag) may take one of the following keywords: auto (indicating that vendor information is determined by the client's request), rfc1048 or rfc1084 (which always forces an RFC1084-style reply), or cmu (which always forces a CMU-style reply). If unspecified, it defaults to auto.

The rd tag takes a decimal, octal, or hexadecimal value. (Octal numbers begin with 0, hexadecimal numbers begin with '0x' or '0X.)

The hn tag is strictly a boolean tag; it does not take the usual equals-sign and value. Its presence indicates that the hostname should be sent to RFC1084 clients. Dhcpd 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).

The nr tag is strictly a boolean tag; it does not take the usual equals-sign and value. The tag makes sense only in bootptab entries that also have an ip tag. Its presence indicates that DHCPOFFER and DHCPACK packets should include all values specified in this bootptab entry, even those "not requested by the client." When this tag is not specified, these packets only include those values specifically requested by the client in a Parameter Request List option, plus those values that the server always attempts to return in these packets (the IP address, bootfile (if specified), TFTP server address (if specified) lease time, renewal time, rebinding time, and user class (if specified).

The de tag is strictly a boolean tag; it does not take the usual equals-sign and value. It may only be specified in entries which contain a hardware address or client identifier. Its presence indicates special handling for packets received from this client's hardware address or client identifier; the intent is to deny BOOTP and DHCP service from this server to the client, without interfering with any service the client may be able to receive from another BOOTP or DHCP server. BOOTPREQUEST and DHCPDISCOVER packets from the client are ignored. DHCPREQUEST packets from clients that are in SELECTING state are ignored (as usual) if the packet's Server Identifier Option does not correspond to this server. For DHCPREQUEST packets from clients that are in SELECTING state with a Server Identifier Option that specifies this server: if no offer or binding is present for this client identifier we send a DHCPNAK (as usual), but if an offer or binding is present for this client identifier we send a DHCPNAK and discard the binding/offer. For DHCPREQUEST packets from clients that are in INIT-REBOOT, if there is not presently a binding for this client identifier, the packet is ignored; if there is presently a binding for this client identifier, the binding is discarded and we send a DHCPNAK. DHCPREQUEST packets from clients that are in RENEWING or REBINDING (or confused) state, if there is not presently a binding for this client identifier, the packet is ignored; if there is presently a binding for this client identifier, the binding is discarded and we send a DHCPNAK.

The dd tag is strictly a boolean tag; it does not take the usual equals-sign and value. It may only be specified in entries which contain a hardware address or client identifier. Its presence indicates special handling for packets received from this client's hardware address or client identifier; the intent is to never award a dynamically-assigned IP address to this client, even if it would otherwise be eligible for one. It takes precedence over the access flags that might be specified in the network statement within the dhcpd.conf file, and also takes precedence over any ro tag that might be specified. It has no effect on awarding a static IP address to this client.

The cf tag is experimental, and associated with Dynamic DNS. Normally the server returns a Client FQDN option to any DHCP client that includes a Client FQDN option in the packet it sent to the server, or includes the Client FQDN option in any Parameters Request List option it sends to the server. Specify a cf value of 0x01 to force the server to also return a Client FQDN option to a client when the nr tag is also set for this client, and the client is speaking DHCP. Specify a cf value of 0x00 to prevent the server from ever returning a Client FQDN option to a client. This tag, and the entire behavior described here, may in the future be removed or changed in incompatible ways; they are experimental.

FILTERING BOOTPREPLY VENDOR OPTIONS

The be and bi tags can be used to filter the options that may be returned in the "vendor options" field of a BOOTPREPLY.

The "vendor options" field in a BOOTPREPLY packet is (strictly speaking) limited to 64 bytes, much less than the field in a DHCP response packet. If you have specified a significant amount of data in a bootptab entry, there may be too much to fit into the packet if the client speaks BootP. The be and bi tags can help, by letting you filter the options that we will try to insert into the BOOTPREPLY.

These tags only apply to replies sent to clients speaking BOOTP (not DHCP) that choose to use of the RFC1048 cookie. Either tag takes a value which is an ASCII string surrounded by double quotes ("). The value consists of whitespace-delimited tag names (including generic tag names); e.g. be="lp lg nt T144".

If the be tag is specified, then any elements specified in its list will be excluded from a BOOTPREPLY vendor options field. If the bi tag is specified, then any elements not specified in its list will be excluded from a BOOTPREPLY vendor options field. (That is, be and bi act as filters on our reply.)

You may not specify both be and bi in the same bootptab entry. (If the entry has inherited one of these tags from a template, cancel it (e.g. be@) before applying the other tag.)

Because be and bi tags apply to an IP address (rather than a hardware address or client identifier), they only make sense to specify in an entry that has an IP address, or an entry that is used as a template for other another entry that has an IP address.

If nr is specified in combination with be (or bi), the filtering specified by be (or bi) takes precedence.

The tag names specified within a be or bi list need not appear elsewhere in the bootptab entry.

Do not specify a tag in a be or bi list using the generic (Txxx) syntax if the tag has a well-defined bootptab tag name; if you do, the results may be unpredictable.

It is an error to specify in a be or bi list any tag names which do not correspond to an option that might actually appear in a BOOTPREPLY "vendor options" field. E.g. because any bootfile name would appear elsewhere in the BOOTPREPLY packet, it is an error to specify bf as an element with a be or bi list. The same is true for tag names that correspond to directives that modify the behavior of the server itself (e.g. de).

We do not permit you to filter a few options from a BOOTPREPLY's vendor options field. They include: subnet mask, router addresses, extension file, pad, end.

TEMPLATES

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 tc (table continuation) mechanism.

Often, the template entry is a dummy host which doesn't actually exist and never sends requests. This feature is similar to the tc feature of termcap(5) for similar terminals.

Dhcpd allows the tc tag symbol to appear anywhere in the host entry, unlike termcap which requires it to be the last tag.

Information explicitly specified for a host always overrides information implied by a tc tag symbol, regardless of its location within the entry. The value of the tc tag may be the hostname or IP address of any host entry previously listed in the configuration file.

Sometimes it is necessary to delete a specific tag after it has been inferred via tc. This can be done using the construction tag@ which removes the effect of tag as in 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 @, a tag is eligible to be set again through the tc mechanism. The tag@ construction may not be used for the tc tag itself (i.e. tc@ is not valid) nor for generic tags (e.g. T144@ is not valid).

DYNAMICALLY-ASSIGNED ADDRESSES

To define an IP address that dhcpd(8) should assign to clients dynamically, create a bootptab entry that contains the :ip: tag to define a specific IP address, contains the :dy: boolean tag to indicate this address should be assigned dynamically, and does not contain the :ht:, :ha:, or :cl: tags that would otherwise associate the address with a specific client.

All of the other usual tags may be used in the entry.

By inspecting the IP address, the server will determine into which pool of dynamic IP address this address belongs. It examines the network statements that appear in the dhcpd.conf(5) file, comparing the IP address defined in the bootptab entry to the netnumber and netmask values associated with each poolname in the dhcpd.conf.

To specify that a client may be assigned a dynamic IP address that falls into a pool defined with the roaming access-flag in the dhcpd.conf(5) file, specify the :ro: tag in the client's bootptab entry. (That is, the :ro: tag belongs in the bootptab entry that mentions the client's hardware address or Client Identifier.)

SPECIAL HOSTNAMES

To specify tags that should be supplied to all DHCP clients in response to requests that contain a particular User Class Information option (option 77), create a bootptab entry with an entry-name that consists of the two characters $C followed by the particular User Class Information option value (in hexadecimal). For example, to specify tags that should be provided in response to DHCP requests containing a User Class Information option value of 0x2A0EB5, create a bootptab entry with the entry name $C2A0EB5. Tags specified in this entry act as "overrides", taking precedence over tags specified in individual client or pool entries.

To specify tags that should be supplied to all DHCP clients in response to requests that do not contain any User Class Information option (option 77), but do contain a particular Vendor Specific Information option (option 43), create a bootptab entry with an entry-name that consists of the two characters $V followed by the particular Vendor Specific Information option value (in hexadecimal). For example, to specify tags that should be provided in response to DHCP requests containing no User Class Information option, but a Vendor Specific Information option value of 0x37020000 (which is used by Windows 95), create a bootptab entry with the entry name $V37020000. Tags specified in this entry act as "overrides", taking precedence over tags specified in individual client or pool entries.

To specify tags that should be supplied to all DHCP clients in response to requests that do not contain any User Class Information option (option 77), nor any Vendor Specific Information option (option 43), create a bootptab entry with an entry-name of $DHCP. Tags specified in this entry act as "overrides", taking precedence over tags specified in individual client or pool entries.

Note that the way the server searches for $C, $V, and $DHCP entries is not intuitive. If the DHCP request packet contains any User Class Information option, then the server only search the bootptab for a matching $C entry; it will not search for any $V entries or a $DHCP entry. Only if the DHCP request packet contains no User Class Information option will the server proceed to search the bootptab for a matching $V entry (if the request packet contains a Vendor Specific Information option). Only if the DHCP request packet contains no User Class Information option and no Vendor Specific Information option will the server proceed to search the bootptab for a $DHCP entry.

EXAMPLES

An example /etc/bootptab file follows:

	# Sample bootptab file (domain=andrew.cmu.edu)
	.default:\
		:hd=/usr/boot:bf=null:\
		:ds=netserver, lancaster:\
		:ns=pcs2, pcs1:\
		:ts=pcs2, pcs1:\
		:sm=255.255.255.0:\
		:gw=gw.cs.cmu.edu:\
		:hn:to=-18000:
	carnegie:ht=6:ha=7FF8100000AF:tc=.default:
	baldwin:ht=1:ha=0800200159C3:tc=.default:
	wylie:ht=1:ha=00DD00CADF00:tc=.default:
	arnold:ht=1:ha=0800200102AD:tc=.default:
	bairdford:ht=1:ha=08002B02A2F9:tc=.default:
	bakerstown:ht=1:ha=08002B0287C8:tc=.default:
	# Special domain name server and option tags for next host
	butlerjct:ha=08002001560D:ds=128.2.13.42:\
		:T37=0x12345927AD3BCF:\
		:T99="Special ASCII string":\
		:tc=.default:
	gastonville:ht=6:ha=7FFF81000A47:tc=.default:
	hahntown:ht=6:ha=7FFF81000434:tc=.default:
	hickman:ht=6:ha=7FFF810001BA:tc=.default:
	lowber:ht=1:ha=00DD00CAF000:tc=.default:
	mtoliver:ht=1:ha=00DD00FE1600:tc=.default:
	# a pool of dynamic ip addresses - note that they lack ht/ha/cl tags, but have dy tag
	.foobarnet:dy:gw=128.111.54.1:sm=255.255.255.0:ds=128.111.60.78 128.111.100.102:dn=banana.com:
	foo1:ip=128.111.54.70:tc=.foobarnet:
	foobaz:ip=128.111.54.71:tc=.foobarnet:
	yowza:ip=128.111.54.75:tc=.foobarnet:
	# a client that has no static ip address defined.  Presumably it is only being
    # being mentioned because it needs dynamic ip address assignment on a network on which
    # we've restricted dynamic address assignments to "registered" clients.
	mypc:ht=1:ha=080007010203:
	# Overrides for Win95 DHCP clients
	$V37020000:dl=86400:
	# Overrides for DHCP clients who do not specify any user class info option
	# nor vendor specific info option
	$DHCP:dl=86400:

FILES
/etc/bootptab

SEE ALSO
dhcpd(8), dhcpd.conf(5), dhcp-bindings-tool(8), tftpd(8)

Internet Requests for Comments:

RFC2132
    DHCP Options and BootP Vendor Extensions

RFC951
    Bootstrap Protocol

RFC1534
    Interoption Between DHCP and BootP

RFC1542
    Clarifications and Extensions for the Bootstrap Protocol

RFC1700
    Assigned Numbers

RFC2131
    Dynamic Host Configuration Protocol

RFC2132
    DHCP Options and BootP Vendor Extensions

RFC2241
    DHCP Options for Novell Directory Services

RFC2242
    NetWare/IP Domain Name and Information

RFC2485
    DHCP Option for The Open Group's User Authentication Protocol

RFC2610
    DHCP Options for Service Location Protocol

RFC2937
    The Name Service Search Option for DHCP

RFC2939
    Procedure and IANA Guidelines for Definition of New DHCP Options and Message Types

RFC3004
    The User Class Option for DHCP

RFC3011
    The IPv4 Subnet Selection Option for DHCP

RFC3046
    DHCP Relay Agent Information Option

<draft-ietf-dhc-fqdn-option-02.txt> The DHCP Client FQDN Option

RFC3942
    Reclassifying DHCPv4 Options

Internet Engineering Task Force draft documents are listed at the official IETF DHCP Working Group page: http://www.ietf.org/html.charters/dhc-charter.html

Additional DHCP resources are at: http://www.dhcp.org/