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