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 27ident "%Z%%M% %I% %E% SMI" 28 29PROBLEM STATEMENT 30================= 31 32Currently, each DHCP-related utility that needs to handle DHCP options 33uses ad-hoc methods for learning and using them, ranging from using 34hard-coded internal tables to providing published (but distinct) 35configuration files describing these options. 36 37Originally, when only the DHCP server needed to be concerned with DHCP 38options, not having a standard API for managing and parsing DHCP 39options was understandable. Now, with four consumers of DHCP options 40in core Solaris (in.dhcpd, dhcpinfo, snoop, and dhcpmgr), the 41situation has spiraled out of control. In addition to the obvious 42maintenance headache caused by the redundant code, it has also become 43a burden to our customers, who already have to cope with multiple 44places where DHCP option information is stored (dhcptags(4), 45dhcptab(4)). 46 47The inittab API is designed to reduce the confusion, both for the 48customer and the application developer. Its goal is to provide a 49single configuration for applications to receive their DHCP option 50knowledge from and general routines for encoding and decoding DHCP 51options. 52 53INITTAB 54======= 55 56The inittab file contains information regarding the syntax and (to 57some degree) the semantics of DHCP options. It is primarily a 58read-only file (like /etc/termcap) and should not need to be changed 59by users. Experienced sysadmins may need to update this file to add 60new DHCP options, but this should be rare. 61 62The inittab file consists of inittab records, each being one line long 63and describing a particular option. The format is based heavily on 64the format for defining symbols in dhcptab(4). Each line has the 65following syntax: 66 67 option_name category, code, type, granularity, maximum, consumers 68 69where: 70 71 `option_name' is user-interpretable name of the option (for use with 72 dhcpinfo(1M) 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. 76 77 `category' is one of STANDARD, SITE, VENDOR, FIELD, or INTERNAL and 78 identifies the namespace in which the option falls. 79 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 87 undefined. 88 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 94 in the number. 95 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. 101 102 `maximum' describes how many whole values are allowed for this 103 option. 0 indicates an infinite number. 104 105 `consumers' describe which programs make use of this information. 106 (`i' for dhcpinfo, `s' for snoop, `d' for in.dhcpd, and 107 `m' for dhcpmgr). 108 109A sample entry would be 110 111 StaticRt STANDARD, 33, IP, 2, 0, isdm 112 113which describes an option named `StaticRt', that is in the STANDARD 114category (i.e., defined by the DHCP standard), and is option code 11533, which is of type `IP Address', consisting of a potentially 116infinite number of pairs of IP addresses. Lastly, the consumers of 117option are dhcpinfo, snoop, in.dhcpd and dhcpmgr. 118 119Comments in the inittab file begin with `#', and end with a newline. 120Comments need not start at the beginning of a line. Lines cannot be 121continued (with `\' for instance). 122 123The inittab file becomes the authoritative source for all DHCP options 124for all DHCP option consumers, with the following exceptions and notes: 125 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. 129 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). 136 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. 140 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. 147 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. 151 152C-LEVEL API 153=========== 154 155Each inittab entry describes a specific DHCP option and is defined as 156a dhcp_symbol_t (as defined in usr/src/lib/libdhcputil/common/dhcp_symbol.h). 157 158In general, it is expected that inittab entries are acquired via 159inittab_load(), inittab_getbyname(), or inittab_getbycode() and passed 160as needed to the remaining inittab_XXX functions. If consumers need 161to convert the inittab entries into a different format, then the 162fields inside the inittab entry may be read directly. Some inittab 163functions return dynamically allocated parameters; all such parameters 164can be freed with free(3c). 165 166To get an inittab entry, one of the following API's must be used: 167 168 dhcp_symbol_t * 169 inittab_load(uchar_t categories, char consumer, size_t *n_entries); 170 171 dhcp_symbol_t * 172 inittab_getbyname(uchar_t categories, char consumer, const char *name); 173 174 dhcp_symbol_t * 175 inittab_getbycode(uchar_t categories, char consumer, unsigned int code); 176 177where the `categories' parameter consists of the following values OR'd 178together: 179 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 185 186and the `consumer' field consists of one of the following: 187 188 #define ITAB_CONS_INFO 'i' 189 #define ITAB_CONS_SERVER 'd' 190 #define ITAB_CONS_SNOOP 's' 191 #define ITAB_CONS_MANAGER 'm' 192 193inittab_load() creates and returns an array of dhcp_symbol_t's made 194up of all the entries of the specified categories that are available 195to the provided consumer. Note that there is no specified order to 196the entries returned. The array is dynamically allocated, and the 197number of items in the array is returned in the `n_entries' parameter. 198 199inittab_getbyname()/inittab_getbycode() return an dhcp_symbol_t 200matching the given name or code for the provided category and the 201provided consumer. The dhcp_symbol_t is dynamically allocated. 202 203Some inittab consumers may need to make sure that a given inittab 204entry has not been corrupted in the inittab file. For those cases, 205inittab_verify() can be used to validate an inittab_entry against an 206internal table compiled into the inittab API: 207 208 int 209 inittab_verify(dhcp_symbol_t *inittab_ent, 210 dhcp_symbol_t *internal_ent); 211 212where `inittab_ent' is an dhcp_symbol_t previously returned from 213inittab_load() or inittab_getbyX(). inittab_verify() returns 214ITAB_SUCCESS if `inittab_ent' is verified to be correct, ITAB_FAILURE 215if `inittab_ent' is incorrect, and ITAB_UNKNOWN if inittab_verify() 216doesn't know. If `internal_ent' is non-NULL, it is filled in with the 217value of the option known internally to the inittab API. Entries are 218verified using the `ds_category' and `ds_code' fields from the 219dhcp_symbol_t. For ITAB_SUCCESS to be returned, the entry passed in 220and the internal entry both must have the same ds_gran, ds_max, and 221ds_type values. 222 223To perform encoding and decoding of DHCP options, the following 224routines are provided: 225 226 uchar_t * 227 inittab_encode(dhcp_symbol_t *inittab_ent, const char *data, 228 uint16_t *lengthp, boolean_t just_payload); 229 230 const char * 231 inittab_decode(dhcp_symbol_t *inittab_ent, uchar_t *data, 232 uint16_t length, boolean_t just_payload); 233 234Both of these routines take an `inittab_ent' that was previously 235returned from inittab_load() or inittab_getbyX(). 236 237For inittab_encode(), `data' is an ASCII string to encode, and a 238pointer to a dynamically allocated byte-array representing the encoded 239option is returned. The size of the resulting data returned is stored 240in `lengthp'. Note that if the `just_payload' option is set, then 241only the payload of the option is returned (i.e., the option code and 242option length is left off the returned data). To encode multiple 243items 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" 245where NN is a hexadecimal digit representing the byte. 246 247For inittab_decode(), `data' is a byte-array representing an encoded 248option, which is `length' bytes long. A pointer to a dynamically 249allocated string representing the option's value in ASCII is returned. 250Note that if the `data' byte-array consists of just the payload of the 251option, then the `just_payload' option should be set. 252 253In addition, the following routines return extended error information 254for reporting parsing errors: 255 256 uchar_t * 257 inittab_encode_e(dhcp_symbol_t *inittab_ent, const char *data, 258 uint16_t *lengthp, boolean_t just_payload, int *eerrno); 259 260 const char * 261 inittab_decode_e(dhcp_symbol_t *inittab_ent, uchar_t *data, 262 uint16_t length, boolean_t just_payload, int *eerrno); 263 264 265The extended codes: 266 267/* 268 * DHCP Extended error codes 269 */ 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) 278 279 280ENVIRONMENT VARIABLES 281===================== 282 283In order to aid in debugging inittab-related problems, two environment 284variables, DHCP_INITTAB_DEBUG, and DHCP_INITTAB_PATH, can be set 285before starting a program which uses the inittab API. 286 287If DHCP_INITTAB_DEBUG is an exported environment variable, then the 288inittab API will print useful diagnostic messages handy in tracking 289down problems in the inittab file. If DHCP_INITTAB_PATH is an 290exported environment variable, then its value is used as the location 291of the inittab file, instead of /etc/dhcp/inittab. 292 293-- 294Peter Memishian, Internet Engineering, Solaris Software (meem@east.sun.com) 295