4 # The contents of this file are subject to the terms of the
5 # Common Development and Distribution License, Version 1.0 only
6 # (the "License"). You may not use this file except in compliance
9 # You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10 # or http://www.opensolaris.org/os/licensing.
11 # See the License for the specific language governing permissions
12 # and limitations under the License.
14 # When distributing Covered Code, include this CDDL HEADER in each
15 # file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16 # If applicable, add the following below this CDDL HEADER, with the
17 # fields enclosed by brackets "[]" replaced with your own identifying
18 # information: Portions Copyright [yyyy] [name of copyright owner]
22 Copyright (c) 2001 by Sun Microsystems, Inc.
25 Inittab Purpose, Goals, and Functionality
27 ident "%Z%%M% %I% %E% SMI"
32 Currently, each DHCP-related utility that needs to handle DHCP options
33 uses ad-hoc methods for learning and using them, ranging from using
34 hard-coded internal tables to providing published (but distinct)
35 configuration files describing these options.
37 Originally, when only the DHCP server needed to be concerned with DHCP
38 options, not having a standard API for managing and parsing DHCP
39 options was understandable. Now, with four consumers of DHCP options
40 in core Solaris (in.dhcpd, dhcpinfo, snoop, and dhcpmgr), the
41 situation has spiraled out of control. In addition to the obvious
42 maintenance headache caused by the redundant code, it has also become
43 a burden to our customers, who already have to cope with multiple
44 places where DHCP option information is stored (dhcptags(4),
47 The inittab API is designed to reduce the confusion, both for the
48 customer and the application developer. Its goal is to provide a
49 single configuration for applications to receive their DHCP option
50 knowledge from and general routines for encoding and decoding DHCP
56 The inittab file contains information regarding the syntax and (to
57 some degree) the semantics of DHCP options. It is primarily a
58 read-only file (like /etc/termcap) and should not need to be changed
59 by users. Experienced sysadmins may need to update this file to add
60 new DHCP options, but this should be rare.
62 The inittab file consists of inittab records, each being one line long
63 and describing a particular option. The format is based heavily on
64 the format for defining symbols in dhcptab(4). Each line has the
67 option_name category, code, type, granularity, maximum, consumers
71 `option_name' is user-interpretable name of the option (for use with
72 dhcpinfo(8) for instance). This field should at least be per-
73 category unique and ideally should be unique across all categories.
74 Of particular note is that options names in the STANDARD, SITE, and
75 VENDOR spaces should not overlap, or the behavior is undefined.
77 `category' is one of STANDARD, SITE, VENDOR, FIELD, or INTERNAL and
78 identifies the namespace in which the option falls.
80 `code' is the code of this option when it is sent over the
81 wire. (note: in most cases, `code' uniquely identifies the
82 option, without a category. however, in the case of internal
83 categories like FIELD or INTERNAL, `code' may be used for
84 other purposes and thus may not be globally unique). This field
85 should be per-category unique and the STANDARD and SITE fields
86 should not have overlapping code fields or the behavior is
89 `type' describes the payload associated with this option. Valid
90 types are IP, ASCII, OCTET, NUMBER, BOOL, UNUMBER8, UNUMBER16,
91 UNUMBER32, SNUMBER8, SNUMBER16, and SNUMBER32. For numbers,
92 a preceding `U' or `S' indicates whether the number is unsigned
93 or signed, and the trailing number indicates the number of bits
96 `granularity' describes how many units of `type' payload make
97 up a whole value for this option. In the case of `NUMBER',
98 granularity describes the number of bytes in the number. Note
99 that `NUMBER' is preserved for compatibility, but the more
100 descriptive [SU]NUMBER{8,16,32,64} types should preferred.
102 `maximum' describes how many whole values are allowed for this
103 option. 0 indicates an infinite number.
105 `consumers' describe which programs make use of this information.
106 (`i' for dhcpinfo, `s' for snoop, `d' for in.dhcpd, and
109 A sample entry would be
111 StaticRt STANDARD, 33, IP, 2, 0, isdm
113 which describes an option named `StaticRt', that is in the STANDARD
114 category (i.e., defined by the DHCP standard), and is option code
115 33, which is of type `IP Address', consisting of a potentially
116 infinite number of pairs of IP addresses. Lastly, the consumers of
117 option are dhcpinfo, snoop, in.dhcpd and dhcpmgr.
119 Comments in the inittab file begin with `#', and end with a newline.
120 Comments need not start at the beginning of a line. Lines cannot be
121 continued (with `\' for instance).
123 The inittab file becomes the authoritative source for all DHCP options
124 for all DHCP option consumers, with the following exceptions and notes:
126 o The DHCP agent and DHCP server both have their core protocol-
127 related functionality hardcoded into them, so changes to the
128 inittab file do not generally affect their inner workings.
130 o A program can specify which entries it wants from the inittab.
131 This means that some DHCP options will never be used by some
132 programs, even if they are listed as a `consumer' of the given
133 option. An example of this is that the DHCP server never
134 requests any fields with the VENDOR category. (VENDOR information
135 for the DHCP server comes from dhcptab(4) instead).
137 o In general, changing provided information in a released inittab
138 file is ill-advised. Adding new entries should be the extent
139 of the modifications that are performed.
141 o The inittab C API also provides functions which allow programs
142 to verify that a given entry in the inittab file is correct
143 (which it does by consulting a compiled-in database of current
144 options). In general, this functionality is only used where
145 absolutely necessary, since it nullifies some of the advantages
146 of having an inittab.
148 o Where a symbol is defined both in the inittab and in dhcptab(4),
149 inittab is authoritative. EXTEND symbol definitions in
150 dhcptab(4) will be deprecated in a future release of Solaris.
155 Each inittab entry describes a specific DHCP option and is defined as
156 a dhcp_symbol_t (as defined in usr/src/lib/libdhcputil/common/dhcp_symbol.h).
158 In general, it is expected that inittab entries are acquired via
159 inittab_load(), inittab_getbyname(), or inittab_getbycode() and passed
160 as needed to the remaining inittab_XXX functions. If consumers need
161 to convert the inittab entries into a different format, then the
162 fields inside the inittab entry may be read directly. Some inittab
163 functions return dynamically allocated parameters; all such parameters
164 can be freed with free(3c).
166 To get an inittab entry, one of the following API's must be used:
169 inittab_load(uchar_t categories, char consumer, size_t *n_entries);
172 inittab_getbyname(uchar_t categories, char consumer, const char *name);
175 inittab_getbycode(uchar_t categories, char consumer, unsigned int code);
177 where the `categories' parameter consists of the following values OR'd
180 #define ITAB_CAT_STANDARD 0x01
181 #define ITAB_CAT_FIELD 0x02
182 #define ITAB_CAT_INTERNAL 0x04
183 #define ITAB_CAT_VENDOR 0x08
184 #define ITAB_CAT_SITE 0x10
186 and the `consumer' field consists of one of the following:
188 #define ITAB_CONS_INFO 'i'
189 #define ITAB_CONS_SERVER 'd'
190 #define ITAB_CONS_SNOOP 's'
191 #define ITAB_CONS_MANAGER 'm'
193 inittab_load() creates and returns an array of dhcp_symbol_t's made
194 up of all the entries of the specified categories that are available
195 to the provided consumer. Note that there is no specified order to
196 the entries returned. The array is dynamically allocated, and the
197 number of items in the array is returned in the `n_entries' parameter.
199 inittab_getbyname()/inittab_getbycode() return an dhcp_symbol_t
200 matching the given name or code for the provided category and the
201 provided consumer. The dhcp_symbol_t is dynamically allocated.
203 Some inittab consumers may need to make sure that a given inittab
204 entry has not been corrupted in the inittab file. For those cases,
205 inittab_verify() can be used to validate an inittab_entry against an
206 internal table compiled into the inittab API:
209 inittab_verify(dhcp_symbol_t *inittab_ent,
210 dhcp_symbol_t *internal_ent);
212 where `inittab_ent' is an dhcp_symbol_t previously returned from
213 inittab_load() or inittab_getbyX(). inittab_verify() returns
214 ITAB_SUCCESS if `inittab_ent' is verified to be correct, ITAB_FAILURE
215 if `inittab_ent' is incorrect, and ITAB_UNKNOWN if inittab_verify()
216 doesn't know. If `internal_ent' is non-NULL, it is filled in with the
217 value of the option known internally to the inittab API. Entries are
218 verified using the `ds_category' and `ds_code' fields from the
219 dhcp_symbol_t. For ITAB_SUCCESS to be returned, the entry passed in
220 and the internal entry both must have the same ds_gran, ds_max, and
223 To perform encoding and decoding of DHCP options, the following
224 routines are provided:
227 inittab_encode(dhcp_symbol_t *inittab_ent, const char *data,
228 uint16_t *lengthp, boolean_t just_payload);
231 inittab_decode(dhcp_symbol_t *inittab_ent, uchar_t *data,
232 uint16_t length, boolean_t just_payload);
234 Both of these routines take an `inittab_ent' that was previously
235 returned from inittab_load() or inittab_getbyX().
237 For inittab_encode(), `data' is an ASCII string to encode, and a
238 pointer to a dynamically allocated byte-array representing the encoded
239 option is returned. The size of the resulting data returned is stored
240 in `lengthp'. Note that if the `just_payload' option is set, then
241 only the payload of the option is returned (i.e., the option code and
242 option length is left off the returned data). To encode multiple
243 items of a given type, separate the items by spaces, such as
244 "109.108.21.1 148.232.2.1". Octal data should be of the form "0xNN"
245 where NN is a hexadecimal digit representing the byte.
247 For inittab_decode(), `data' is a byte-array representing an encoded
248 option, which is `length' bytes long. A pointer to a dynamically
249 allocated string representing the option's value in ASCII is returned.
250 Note that if the `data' byte-array consists of just the payload of the
251 option, then the `just_payload' option should be set.
253 In addition, the following routines return extended error information
254 for reporting parsing errors:
257 inittab_encode_e(dhcp_symbol_t *inittab_ent, const char *data,
258 uint16_t *lengthp, boolean_t just_payload, int *eerrno);
261 inittab_decode_e(dhcp_symbol_t *inittab_ent, uchar_t *data,
262 uint16_t length, boolean_t just_payload, int *eerrno);
268 * DHCP Extended error codes
270 #define ITAB_SYNTAX_ERROR (-1)
271 #define ITAB_BAD_IPADDR (-2)
272 #define ITAB_BAD_STRING (-3)
273 #define ITAB_BAD_OCTET (-4)
274 #define ITAB_BAD_NUMBER (-5)
275 #define ITAB_BAD_BOOLEAN (-6)
276 #define ITAB_NOT_ENOUGH_IP (-7)
277 #define ITAB_BAD_GRAN (-8)
280 ENVIRONMENT VARIABLES
281 =====================
283 In order to aid in debugging inittab-related problems, two environment
284 variables, DHCP_INITTAB_DEBUG, and DHCP_INITTAB_PATH, can be set
285 before starting a program which uses the inittab API.
287 If DHCP_INITTAB_DEBUG is an exported environment variable, then the
288 inittab API will print useful diagnostic messages handy in tracking
289 down problems in the inittab file. If DHCP_INITTAB_PATH is an
290 exported environment variable, then its value is used as the location
291 of the inittab file, instead of /etc/dhcp/inittab.
294 Peter Memishian, Internet Engineering, Solaris Software (meem@east.sun.com)