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