'\" te
.\"  Copyright (c) 2002,  Sun Microsystems, Inc.  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH DHCPTAB 4 "Mar 15, 2002"
.SH NAME
dhcptab \- DHCP configuration parameter table
.SH DESCRIPTION
.sp
.LP
The \fBdhcptab\fR configuration table allows network administrators to organize
groups of configuration parameters as macro definitions, which can then be
referenced in the definition of other useful macros. These macros are then used
by the \fBDHCP\fR server to return their values to \fBDHCP\fR and \fBBOOTP\fR
clients.
.sp
.LP
The preferred method of managing the \fBdhcptab\fR is through the  use of the
\fBdhcpmgr\fR(1M) or \fBdhtadm\fR(1M) utility. The description of \fBdhcptab\fR
entries included in this manual page is intended for informational purposes
only, and should not be used to manually edit entries.
.sp
.LP
You can view the contents of the \fBdhcptab\fR using the DHCP manager's tabs
for Macros and Options, or using the \fBdhtadm -P\fR command.
.SS "Syntax of dhcptab Entries"
.sp
.LP
The format of a \fBdhcptab\fR table depends on the data store used to maintain
it. However, any \fBdhcptab\fR must contain the following fields in each
record:
.sp
.ne 2
.na
\fB\fBName\fR\fR
.ad
.RS 9n
This field identifies the macro or symbol record and is used as a search key
into the \fBdhcptab\fR table. The name of a macro or symbol must consist of
\fBASCII\fR characters, with the length limited to 128 characters. Names can
include spaces, except at the end of the name. The name is not case-sensitive.
.RE

.sp
.ne 2
.na
\fB\fBType\fR\fR
.ad
.RS 9n
This field specifies the type of record and is used as a search key into the
\fBdhcptab\fR. Currently, there are only two legal values for \fBType\fR:
.sp
.ne 2
.na
\fB\fBm\fR\fR
.ad
.RS 5n
This record is a \fBDHCP\fR macro definition.
.RE

.sp
.ne 2
.na
\fB\fBs\fR\fR
.ad
.RS 5n
This record is a \fBDHCP\fR symbol definition. It is used to define vendor and
site-specific options.
.RE

.RE

.sp
.ne 2
.na
\fB\fBValue\fR\fR
.ad
.RS 9n
This field contains the value for the specified type of record. For the \fBm\fR
type, the value will consist of a series of symbol=value pairs, separated by
the colon (\fB:\fR) character. For the \fBs\fR type, the value will consist of
a series of fields, separated by a comma (\fB,\fR), which define a symbol's
characteristics. Once defined, a symbol can be used in macro definitions.
.RE

.SS "Symbol Characteristics"
.sp
.LP
The Value field of a symbols definition contain the following fields describing
the characteristics of a symbol:
.sp
.ne 2
.na
\fB\fBContext\fR\fR
.ad
.RS 15n
This field defines the context in which the symbol definition is to be used. It
can have one of the following values:
.sp
.ne 2
.na
\fB\fBSite\fR\fR
.ad
.RS 27n
This symbol defines a site-specific option, codes 128-254.
.RE

.sp
.ne 2
.na
\fB\fBVendor=Client Class ...\fR\fR
.ad
.RS 27n
This symbol defines a vendor-specific option, codes 1-254. The Vendor context
takes \fBASCII\fR string arguments which identify the client class that this
vendor option is associated with. Multiple client class names can be specified,
separated by white space. Only those clients whose client class matches one of
these values will see this option. For Sun machines, the Vendor client class
matches the value returned by the command \fBuname -i\fR on the client, with
periods replacing commas.
.RE

.RE

.sp
.ne 2
.na
\fB\fBCode\fR\fR
.ad
.RS 15n
This field specifies the option code number associated with this symbol. Valid
values are 128-254 for site-specific options, and 1-254 for vendor-specific
options.
.RE

.sp
.ne 2
.na
\fB\fBType\fR\fR
.ad
.RS 15n
This field defines the type of data expected as a value for this symbol, and is
not case-sensitive. Legal values are:
.sp
.ne 2
.na
\fB\fBASCII\fR\fR
.ad
.RS 11n
\fBNVT ASCII\fR text. Value is enclosed in double-quotes (\fB"\fR). Granularity
setting has no effect on symbols of this type, since \fBASCII\fR strings have a
natural granularity of one (1).
.RE

.sp
.ne 2
.na
\fB\fBBOOLEAN\fR\fR
.ad
.RS 11n
No value is associated with this data type. Presence of symbols of this type
denote boolean \fBTRUE,\fR whereas absence denotes \fBFALSE.\fR Granularity and
Miximum values have no meaning for symbols of this type.
.RE

.sp
.ne 2
.na
\fB\fBIP\fR\fR
.ad
.RS 11n
Dotted decimal form of an Internet address. Multi-IP address granularity is
supported.
.RE

.sp
.ne 2
.na
\fB\fBNUMBER\fR\fR
.ad
.RS 11n
An unsigned number with a supported granularity of \fB1\fR, \fB2\fR, \fB4\fR,
and \fB8\fR octets.
.sp
Valid \fBNUMBER\fR types are: \fBUNUMBER8\fR, \fBSNUMBER8\fR, \fBUNUMBER16\fR,
\fBSNUMBER16\fR, \fBUNUMBER32\fR, \fBSNUMBER32\fR, \fBUNUMBER64\fR, and
\fBSNUMBER64\fR. See \fBdhcp_inittab\fR(4) for details.
.RE

.sp
.ne 2
.na
\fB\fBOCTET\fR\fR
.ad
.RS 11n
Uninterpreted \fBASCII\fR representation of binary data. The client identifier
is one example of an \fBOCTET\fR string. Valid characters are \fB0\fR-\fB9\fR,
\fBa\fR-\fBf\fR, \fBA\fR-\fBF\fR. One \fBASCII\fR character represents one
nibble (4 bits), thus two \fBASCII\fR characters are needed to represent an 8
bit quantity. The granularity setting has no effect on symbols of this type,
since \fBOCTET\fR strings have a natural granularity of one (\fB1\fR).
.sp
For example, to encode a sequence of bytes with decimal values \fB77\fR,
\fB82\fR, \fB5\fR, \fB240\fR, \fB14\fR, the option value would be encoded as
\fB4d5205f00e\fR. A macro which supplies a value for option code \fB78\fR,
\fBSLP_DA\fR, with a \fB0\fR Mandatory byte and Directory Agents at
\fB192.168.1.5\fR and \fB192.168.0.133\fR  would appear in the \fBdhcptab\fR
as:
.sp
.in +2
.nf
slpparams
Macro
:SLP_DA=00c0a80105c0a80085:
.fi
.in -2

.RE

.RE

.sp
.ne 2
.na
\fB\fBGranularity\fR\fR
.ad
.RS 15n
This value specifies how many objects of \fBType\fR define a single
\fBinstance\fR of the symbol value. For example, the static route option is
defined to be a variable list of routes. Each route consists of two \fBIP\fR
addresses, so the \fBType\fR is defined to be \fBIP\fR, and the data's
granularity is defined to be \fB2\fR \fBIP\fR addresses. The granularity field
affects the \fBIP\fR and \fBNUMBER\fR data types.
.RE

.sp
.ne 2
.na
\fB\fBMaximum\fR\fR
.ad
.RS 15n
This value specifies the maximum items of \fBGranularity\fR which are
permissible in a definition using this symbol. For example, there can only be
one \fBIP\fR address specified for a subnet mask, so the  \fBMaximum\fR number
of items in this case is one (\fB1\fR). A  \fBMaximum\fR value of zero
(\fB0\fR) means that a variable number of items is permitted.
.RE

.sp
.LP
The following example defines a site-specific option (symbol) called
\fBMystatRt\fR, of code \fB130\fR, type \fBIP,\fR and granularity \fB2\fR, and
a \fBMaximum\fR of \fB0\fR. This definition corresponds to the internal
definition of the static route option (\fBStaticRt\fR).
.sp
.in +2
.nf
MystatRt s Site,130,IP,2,0
.fi
.in -2

.sp
.LP
The following example demonstrates how a SLP Service Scope symbol
(\fBSLP_SS\fR) with a scope value of \fBhappy\fR and mandatory byte set to
\fB0\fR is encoded. The first octet of the option is the Mandatory octet, which
is set either to \fB0\fR or \fB1\fR. In this example, it is set to \fB0
(00)\fR. The balance of the value is the hexidecimal ASCII code numbers
representing the name \fBhappy\fR, that is, \fB6861707079\fR.
.sp
.in +2
.nf
SLP_SS=006861707079
.fi
.in -2

.SS "Macro Definitions"
.sp
.LP
The following example illustrates a macro defined using the \fBMystatRt\fR site
option symbol just defined:
.sp
.in +2
.nf
10netnis m :MystatRt=3.0.0.0 10.0.0.30:
.fi
.in -2

.sp
.LP
Macros can be specified in the \fBMacro\fR field in \fBDHCP\fR network tables
(see \fBdhcp_network\fR(4)), which will bind particular macro definitions to
specific \fBIP addresses.\fR
.sp
.LP
Up to four macro definitions are consulted by the \fBDHCP\fR server to
determine the options that are returned to the requesting client.
.sp
.LP
These macros are processed in the following order:
.sp
.ne 2
.na
\fB\fBClient Class\fR\fR
.ad
.RS 21n
A macro named using the \fBASCII\fR representation of the client class (e.g.
\fBSUNW.Ultra-30\fR) is searched for in the \fBdhcptab\fR. If found, its
symbol/value pairs will be selected for delivery to the client. This mechanism
permits the network administrator to select configuration parameters to be
returned to all clients of the same class.
.RE

.sp
.ne 2
.na
\fB\fBNetwork\fR\fR
.ad
.RS 21n
A macro named by the dotted Internet form of the network address of the
client's network (for example, \fB10.0.0.0\fR) is searched for in the
\fBdhcptab\fR. If found, its symbol/value pairs will be combined with those of
the \fBClient Class\fR macro. If a symbol exists in both macros, then the
\fBNetwork\fR macro value overrides the value defined in the \fBClient Class\fR
macro. This mechanism permits the network administrator to select configuration
parameters to be returned to all clients on the same network.
.RE

.sp
.ne 2
.na
\fB\fBIP Address\fR\fR
.ad
.RS 21n
This macro may be named anything, but must be specified in the \fBDHCP\fR
network table for the IP address record assigned to the requesting client. If
this macro is found in the \fBdhcptab\fR, then its symbol/value pairs will be
combined with those of the \fBClient Class\fR macro and the \fBNetwork\fR
macro. This mechanism permits the network administrator to select configuration
parameters to be returned to clients using a particular \fBIP\fR address. It
can also be used to deliver a macro defined to include "server-specific"
information by including this macro definition in all \fBDHCP\fR network table
entries owned by a specific server.
.RE

.sp
.ne 2
.na
\fB\fBClient Identifier\fR\fR
.ad
.RS 21n
A macro named by the \fBASCII\fR representation of the client's unique
identifier as shown in the \fBDHCP\fR network table (see
\fBdhcp_network\fR(4)). If found, its symbol/value pairs are combined to the
sum of the \fBClient Class\fR, \fBNetwork\fR, and \fBIP Address\fR macros. Any
symbol collisions are replaced with those specified in the client identifier
macro. The client mechanism permits the network administrator to select
configuration parameters to be returned to a particular client, regardless of
what network that client is connected to.
.RE

.sp
.LP
Refer to \fISystem Administration Guide: IP Services\fR for more information
about macro processing.
.sp
.LP
Refer to the \fBdhcp_inittab\fR(4) man page for more information about symbols
used in Solaris DHCP.
.SH SEE ALSO
.sp
.LP
\fBdhcpmgr\fR(1M), \fBdhtadm\fR(1M), \fBin.dhcpd\fR(1M), \fBdhcp_inittab\fR(4),
\fBdhcp_network\fR(4), \fBdhcp\fR(5)
.sp
.LP
\fISystem Administration Guide: IP Services\fR
.sp
.LP
Alexander, S., and R. Droms, \fIDHCP Options and BOOTP Vendor Extensions\fR,
RFC 2132, Silicon Graphics, Inc., Bucknell University, March 1997.
.sp
.LP
Droms, R., \fIInteroperation Between DHCP and BOOTP\fR, RFC 1534, Bucknell
University, October 1993.
.sp
.LP
Droms, R., \fIDynamic Host Configuration Protocol\fR, RFC 2131, Bucknell
University, March 1997.
.sp
.LP
Wimer, W., \fIClarifications and Extensions for the Bootstrap Protocol\fR, RFC
1542, Carnegie Mellon University, October 1993.