17c478bd9Sstevel@tonic-gate# 27c478bd9Sstevel@tonic-gate# CDDL HEADER START 37c478bd9Sstevel@tonic-gate# 47c478bd9Sstevel@tonic-gate# The contents of this file are subject to the terms of the 57c478bd9Sstevel@tonic-gate# Common Development and Distribution License, Version 1.0 only 67c478bd9Sstevel@tonic-gate# (the "License"). You may not use this file except in compliance 77c478bd9Sstevel@tonic-gate# with the License. 87c478bd9Sstevel@tonic-gate# 97c478bd9Sstevel@tonic-gate# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 107c478bd9Sstevel@tonic-gate# or http://www.opensolaris.org/os/licensing. 117c478bd9Sstevel@tonic-gate# See the License for the specific language governing permissions 127c478bd9Sstevel@tonic-gate# and limitations under the License. 137c478bd9Sstevel@tonic-gate# 147c478bd9Sstevel@tonic-gate# When distributing Covered Code, include this CDDL HEADER in each 157c478bd9Sstevel@tonic-gate# file and include the License file at usr/src/OPENSOLARIS.LICENSE. 167c478bd9Sstevel@tonic-gate# If applicable, add the following below this CDDL HEADER, with the 177c478bd9Sstevel@tonic-gate# fields enclosed by brackets "[]" replaced with your own identifying 187c478bd9Sstevel@tonic-gate# information: Portions Copyright [yyyy] [name of copyright owner] 197c478bd9Sstevel@tonic-gate# 207c478bd9Sstevel@tonic-gate# CDDL HEADER END 217c478bd9Sstevel@tonic-gate# 227c478bd9Sstevel@tonic-gateCopyright (c) 2001 by Sun Microsystems, Inc. 237c478bd9Sstevel@tonic-gateAll rights reserved. 247c478bd9Sstevel@tonic-gate 257c478bd9Sstevel@tonic-gateInittab Purpose, Goals, and Functionality 267c478bd9Sstevel@tonic-gatePeter Memishian 277c478bd9Sstevel@tonic-gate 287c478bd9Sstevel@tonic-gatePROBLEM STATEMENT 297c478bd9Sstevel@tonic-gate================= 307c478bd9Sstevel@tonic-gate 317c478bd9Sstevel@tonic-gateCurrently, each DHCP-related utility that needs to handle DHCP options 327c478bd9Sstevel@tonic-gateuses ad-hoc methods for learning and using them, ranging from using 337c478bd9Sstevel@tonic-gatehard-coded internal tables to providing published (but distinct) 347c478bd9Sstevel@tonic-gateconfiguration files describing these options. 357c478bd9Sstevel@tonic-gate 367c478bd9Sstevel@tonic-gateOriginally, when only the DHCP server needed to be concerned with DHCP 377c478bd9Sstevel@tonic-gateoptions, not having a standard API for managing and parsing DHCP 387c478bd9Sstevel@tonic-gateoptions was understandable. Now, with four consumers of DHCP options 397c478bd9Sstevel@tonic-gatein core Solaris (in.dhcpd, dhcpinfo, snoop, and dhcpmgr), the 407c478bd9Sstevel@tonic-gatesituation has spiraled out of control. In addition to the obvious 417c478bd9Sstevel@tonic-gatemaintenance headache caused by the redundant code, it has also become 427c478bd9Sstevel@tonic-gatea burden to our customers, who already have to cope with multiple 43*bbf21555SRichard Loweplaces where DHCP option information is stored (dhcptags(5), 44*bbf21555SRichard Lowedhcptab(5)). 457c478bd9Sstevel@tonic-gate 467c478bd9Sstevel@tonic-gateThe inittab API is designed to reduce the confusion, both for the 477c478bd9Sstevel@tonic-gatecustomer and the application developer. Its goal is to provide a 487c478bd9Sstevel@tonic-gatesingle configuration for applications to receive their DHCP option 497c478bd9Sstevel@tonic-gateknowledge from and general routines for encoding and decoding DHCP 507c478bd9Sstevel@tonic-gateoptions. 517c478bd9Sstevel@tonic-gate 527c478bd9Sstevel@tonic-gateINITTAB 537c478bd9Sstevel@tonic-gate======= 547c478bd9Sstevel@tonic-gate 557c478bd9Sstevel@tonic-gateThe inittab file contains information regarding the syntax and (to 567c478bd9Sstevel@tonic-gatesome degree) the semantics of DHCP options. It is primarily a 577c478bd9Sstevel@tonic-gateread-only file (like /etc/termcap) and should not need to be changed 587c478bd9Sstevel@tonic-gateby users. Experienced sysadmins may need to update this file to add 597c478bd9Sstevel@tonic-gatenew DHCP options, but this should be rare. 607c478bd9Sstevel@tonic-gate 617c478bd9Sstevel@tonic-gateThe inittab file consists of inittab records, each being one line long 627c478bd9Sstevel@tonic-gateand describing a particular option. The format is based heavily on 63*bbf21555SRichard Lowethe format for defining symbols in dhcptab(5). Each line has the 647c478bd9Sstevel@tonic-gatefollowing syntax: 657c478bd9Sstevel@tonic-gate 667c478bd9Sstevel@tonic-gate option_name category, code, type, granularity, maximum, consumers 677c478bd9Sstevel@tonic-gate 687c478bd9Sstevel@tonic-gatewhere: 697c478bd9Sstevel@tonic-gate 707c478bd9Sstevel@tonic-gate `option_name' is user-interpretable name of the option (for use with 71*bbf21555SRichard Lowe dhcpinfo(1) for instance). This field should at least be per- 727c478bd9Sstevel@tonic-gate category unique and ideally should be unique across all categories. 737c478bd9Sstevel@tonic-gate Of particular note is that options names in the STANDARD, SITE, and 747c478bd9Sstevel@tonic-gate VENDOR spaces should not overlap, or the behavior is undefined. 757c478bd9Sstevel@tonic-gate 767c478bd9Sstevel@tonic-gate `category' is one of STANDARD, SITE, VENDOR, FIELD, or INTERNAL and 777c478bd9Sstevel@tonic-gate identifies the namespace in which the option falls. 787c478bd9Sstevel@tonic-gate 797c478bd9Sstevel@tonic-gate `code' is the code of this option when it is sent over the 807c478bd9Sstevel@tonic-gate wire. (note: in most cases, `code' uniquely identifies the 817c478bd9Sstevel@tonic-gate option, without a category. however, in the case of internal 827c478bd9Sstevel@tonic-gate categories like FIELD or INTERNAL, `code' may be used for 837c478bd9Sstevel@tonic-gate other purposes and thus may not be globally unique). This field 847c478bd9Sstevel@tonic-gate should be per-category unique and the STANDARD and SITE fields 857c478bd9Sstevel@tonic-gate should not have overlapping code fields or the behavior is 867c478bd9Sstevel@tonic-gate undefined. 877c478bd9Sstevel@tonic-gate 887c478bd9Sstevel@tonic-gate `type' describes the payload associated with this option. Valid 897c478bd9Sstevel@tonic-gate types are IP, ASCII, OCTET, NUMBER, BOOL, UNUMBER8, UNUMBER16, 907c478bd9Sstevel@tonic-gate UNUMBER32, SNUMBER8, SNUMBER16, and SNUMBER32. For numbers, 917c478bd9Sstevel@tonic-gate a preceding `U' or `S' indicates whether the number is unsigned 927c478bd9Sstevel@tonic-gate or signed, and the trailing number indicates the number of bits 937c478bd9Sstevel@tonic-gate in the number. 947c478bd9Sstevel@tonic-gate 957c478bd9Sstevel@tonic-gate `granularity' describes how many units of `type' payload make 967c478bd9Sstevel@tonic-gate up a whole value for this option. In the case of `NUMBER', 977c478bd9Sstevel@tonic-gate granularity describes the number of bytes in the number. Note 987c478bd9Sstevel@tonic-gate that `NUMBER' is preserved for compatibility, but the more 997c478bd9Sstevel@tonic-gate descriptive [SU]NUMBER{8,16,32,64} types should preferred. 1007c478bd9Sstevel@tonic-gate 1017c478bd9Sstevel@tonic-gate `maximum' describes how many whole values are allowed for this 1027c478bd9Sstevel@tonic-gate option. 0 indicates an infinite number. 1037c478bd9Sstevel@tonic-gate 1047c478bd9Sstevel@tonic-gate `consumers' describe which programs make use of this information. 1057c478bd9Sstevel@tonic-gate (`i' for dhcpinfo, `s' for snoop, `d' for in.dhcpd, and 1067c478bd9Sstevel@tonic-gate `m' for dhcpmgr). 1077c478bd9Sstevel@tonic-gate 1087c478bd9Sstevel@tonic-gateA sample entry would be 1097c478bd9Sstevel@tonic-gate 1107c478bd9Sstevel@tonic-gate StaticRt STANDARD, 33, IP, 2, 0, isdm 1117c478bd9Sstevel@tonic-gate 1127c478bd9Sstevel@tonic-gatewhich describes an option named `StaticRt', that is in the STANDARD 1137c478bd9Sstevel@tonic-gatecategory (i.e., defined by the DHCP standard), and is option code 1147c478bd9Sstevel@tonic-gate33, which is of type `IP Address', consisting of a potentially 1157c478bd9Sstevel@tonic-gateinfinite number of pairs of IP addresses. Lastly, the consumers of 1167c478bd9Sstevel@tonic-gateoption are dhcpinfo, snoop, in.dhcpd and dhcpmgr. 1177c478bd9Sstevel@tonic-gate 1187c478bd9Sstevel@tonic-gateComments in the inittab file begin with `#', and end with a newline. 1197c478bd9Sstevel@tonic-gateComments need not start at the beginning of a line. Lines cannot be 1207c478bd9Sstevel@tonic-gatecontinued (with `\' for instance). 1217c478bd9Sstevel@tonic-gate 1227c478bd9Sstevel@tonic-gateThe inittab file becomes the authoritative source for all DHCP options 1237c478bd9Sstevel@tonic-gatefor all DHCP option consumers, with the following exceptions and notes: 1247c478bd9Sstevel@tonic-gate 1257c478bd9Sstevel@tonic-gate o The DHCP agent and DHCP server both have their core protocol- 1267c478bd9Sstevel@tonic-gate related functionality hardcoded into them, so changes to the 1277c478bd9Sstevel@tonic-gate inittab file do not generally affect their inner workings. 1287c478bd9Sstevel@tonic-gate 1297c478bd9Sstevel@tonic-gate o A program can specify which entries it wants from the inittab. 1307c478bd9Sstevel@tonic-gate This means that some DHCP options will never be used by some 1317c478bd9Sstevel@tonic-gate programs, even if they are listed as a `consumer' of the given 1327c478bd9Sstevel@tonic-gate option. An example of this is that the DHCP server never 1337c478bd9Sstevel@tonic-gate requests any fields with the VENDOR category. (VENDOR information 134*bbf21555SRichard Lowe for the DHCP server comes from dhcptab(5) instead). 1357c478bd9Sstevel@tonic-gate 1367c478bd9Sstevel@tonic-gate o In general, changing provided information in a released inittab 1377c478bd9Sstevel@tonic-gate file is ill-advised. Adding new entries should be the extent 1387c478bd9Sstevel@tonic-gate of the modifications that are performed. 1397c478bd9Sstevel@tonic-gate 1407c478bd9Sstevel@tonic-gate o The inittab C API also provides functions which allow programs 1417c478bd9Sstevel@tonic-gate to verify that a given entry in the inittab file is correct 1427c478bd9Sstevel@tonic-gate (which it does by consulting a compiled-in database of current 1437c478bd9Sstevel@tonic-gate options). In general, this functionality is only used where 1447c478bd9Sstevel@tonic-gate absolutely necessary, since it nullifies some of the advantages 1457c478bd9Sstevel@tonic-gate of having an inittab. 1467c478bd9Sstevel@tonic-gate 147*bbf21555SRichard Lowe o Where a symbol is defined both in the inittab and in dhcptab(5), 1487c478bd9Sstevel@tonic-gate inittab is authoritative. EXTEND symbol definitions in 149*bbf21555SRichard Lowe dhcptab(5) will be deprecated in a future release of Solaris. 1507c478bd9Sstevel@tonic-gate 1517c478bd9Sstevel@tonic-gateC-LEVEL API 1527c478bd9Sstevel@tonic-gate=========== 1537c478bd9Sstevel@tonic-gate 1547c478bd9Sstevel@tonic-gateEach inittab entry describes a specific DHCP option and is defined as 1557c478bd9Sstevel@tonic-gatea dhcp_symbol_t (as defined in usr/src/lib/libdhcputil/common/dhcp_symbol.h). 1567c478bd9Sstevel@tonic-gate 1577c478bd9Sstevel@tonic-gateIn general, it is expected that inittab entries are acquired via 1587c478bd9Sstevel@tonic-gateinittab_load(), inittab_getbyname(), or inittab_getbycode() and passed 1597c478bd9Sstevel@tonic-gateas needed to the remaining inittab_XXX functions. If consumers need 1607c478bd9Sstevel@tonic-gateto convert the inittab entries into a different format, then the 1617c478bd9Sstevel@tonic-gatefields inside the inittab entry may be read directly. Some inittab 1627c478bd9Sstevel@tonic-gatefunctions return dynamically allocated parameters; all such parameters 1637c478bd9Sstevel@tonic-gatecan be freed with free(3c). 1647c478bd9Sstevel@tonic-gate 1657c478bd9Sstevel@tonic-gateTo get an inittab entry, one of the following API's must be used: 1667c478bd9Sstevel@tonic-gate 1677c478bd9Sstevel@tonic-gate dhcp_symbol_t * 1687c478bd9Sstevel@tonic-gate inittab_load(uchar_t categories, char consumer, size_t *n_entries); 1697c478bd9Sstevel@tonic-gate 1707c478bd9Sstevel@tonic-gate dhcp_symbol_t * 1717c478bd9Sstevel@tonic-gate inittab_getbyname(uchar_t categories, char consumer, const char *name); 1727c478bd9Sstevel@tonic-gate 1737c478bd9Sstevel@tonic-gate dhcp_symbol_t * 1747c478bd9Sstevel@tonic-gate inittab_getbycode(uchar_t categories, char consumer, unsigned int code); 1757c478bd9Sstevel@tonic-gate 1767c478bd9Sstevel@tonic-gatewhere the `categories' parameter consists of the following values OR'd 1777c478bd9Sstevel@tonic-gatetogether: 1787c478bd9Sstevel@tonic-gate 1797c478bd9Sstevel@tonic-gate #define ITAB_CAT_STANDARD 0x01 1807c478bd9Sstevel@tonic-gate #define ITAB_CAT_FIELD 0x02 1817c478bd9Sstevel@tonic-gate #define ITAB_CAT_INTERNAL 0x04 1827c478bd9Sstevel@tonic-gate #define ITAB_CAT_VENDOR 0x08 1837c478bd9Sstevel@tonic-gate #define ITAB_CAT_SITE 0x10 1847c478bd9Sstevel@tonic-gate 1857c478bd9Sstevel@tonic-gateand the `consumer' field consists of one of the following: 1867c478bd9Sstevel@tonic-gate 1877c478bd9Sstevel@tonic-gate #define ITAB_CONS_INFO 'i' 1887c478bd9Sstevel@tonic-gate #define ITAB_CONS_SERVER 'd' 1897c478bd9Sstevel@tonic-gate #define ITAB_CONS_SNOOP 's' 1907c478bd9Sstevel@tonic-gate #define ITAB_CONS_MANAGER 'm' 1917c478bd9Sstevel@tonic-gate 1927c478bd9Sstevel@tonic-gateinittab_load() creates and returns an array of dhcp_symbol_t's made 1937c478bd9Sstevel@tonic-gateup of all the entries of the specified categories that are available 1947c478bd9Sstevel@tonic-gateto the provided consumer. Note that there is no specified order to 1957c478bd9Sstevel@tonic-gatethe entries returned. The array is dynamically allocated, and the 1967c478bd9Sstevel@tonic-gatenumber of items in the array is returned in the `n_entries' parameter. 1977c478bd9Sstevel@tonic-gate 1987c478bd9Sstevel@tonic-gateinittab_getbyname()/inittab_getbycode() return an dhcp_symbol_t 1997c478bd9Sstevel@tonic-gatematching the given name or code for the provided category and the 2007c478bd9Sstevel@tonic-gateprovided consumer. The dhcp_symbol_t is dynamically allocated. 2017c478bd9Sstevel@tonic-gate 2027c478bd9Sstevel@tonic-gateSome inittab consumers may need to make sure that a given inittab 2037c478bd9Sstevel@tonic-gateentry has not been corrupted in the inittab file. For those cases, 2047c478bd9Sstevel@tonic-gateinittab_verify() can be used to validate an inittab_entry against an 2057c478bd9Sstevel@tonic-gateinternal table compiled into the inittab API: 2067c478bd9Sstevel@tonic-gate 2077c478bd9Sstevel@tonic-gate int 2087c478bd9Sstevel@tonic-gate inittab_verify(dhcp_symbol_t *inittab_ent, 2097c478bd9Sstevel@tonic-gate dhcp_symbol_t *internal_ent); 2107c478bd9Sstevel@tonic-gate 2117c478bd9Sstevel@tonic-gatewhere `inittab_ent' is an dhcp_symbol_t previously returned from 2127c478bd9Sstevel@tonic-gateinittab_load() or inittab_getbyX(). inittab_verify() returns 2137c478bd9Sstevel@tonic-gateITAB_SUCCESS if `inittab_ent' is verified to be correct, ITAB_FAILURE 2147c478bd9Sstevel@tonic-gateif `inittab_ent' is incorrect, and ITAB_UNKNOWN if inittab_verify() 2157c478bd9Sstevel@tonic-gatedoesn't know. If `internal_ent' is non-NULL, it is filled in with the 2167c478bd9Sstevel@tonic-gatevalue of the option known internally to the inittab API. Entries are 2177c478bd9Sstevel@tonic-gateverified using the `ds_category' and `ds_code' fields from the 2187c478bd9Sstevel@tonic-gatedhcp_symbol_t. For ITAB_SUCCESS to be returned, the entry passed in 2197c478bd9Sstevel@tonic-gateand the internal entry both must have the same ds_gran, ds_max, and 2207c478bd9Sstevel@tonic-gateds_type values. 2217c478bd9Sstevel@tonic-gate 2227c478bd9Sstevel@tonic-gateTo perform encoding and decoding of DHCP options, the following 2237c478bd9Sstevel@tonic-gateroutines are provided: 2247c478bd9Sstevel@tonic-gate 2257c478bd9Sstevel@tonic-gate uchar_t * 2267c478bd9Sstevel@tonic-gate inittab_encode(dhcp_symbol_t *inittab_ent, const char *data, 2277c478bd9Sstevel@tonic-gate uint16_t *lengthp, boolean_t just_payload); 2287c478bd9Sstevel@tonic-gate 2297c478bd9Sstevel@tonic-gate const char * 2307c478bd9Sstevel@tonic-gate inittab_decode(dhcp_symbol_t *inittab_ent, uchar_t *data, 2317c478bd9Sstevel@tonic-gate uint16_t length, boolean_t just_payload); 2327c478bd9Sstevel@tonic-gate 2337c478bd9Sstevel@tonic-gateBoth of these routines take an `inittab_ent' that was previously 2347c478bd9Sstevel@tonic-gatereturned from inittab_load() or inittab_getbyX(). 2357c478bd9Sstevel@tonic-gate 2367c478bd9Sstevel@tonic-gateFor inittab_encode(), `data' is an ASCII string to encode, and a 2377c478bd9Sstevel@tonic-gatepointer to a dynamically allocated byte-array representing the encoded 2387c478bd9Sstevel@tonic-gateoption is returned. The size of the resulting data returned is stored 2397c478bd9Sstevel@tonic-gatein `lengthp'. Note that if the `just_payload' option is set, then 2407c478bd9Sstevel@tonic-gateonly the payload of the option is returned (i.e., the option code and 2417c478bd9Sstevel@tonic-gateoption length is left off the returned data). To encode multiple 2427c478bd9Sstevel@tonic-gateitems of a given type, separate the items by spaces, such as 2437c478bd9Sstevel@tonic-gate"109.108.21.1 148.232.2.1". Octal data should be of the form "0xNN" 2447c478bd9Sstevel@tonic-gatewhere NN is a hexadecimal digit representing the byte. 2457c478bd9Sstevel@tonic-gate 2467c478bd9Sstevel@tonic-gateFor inittab_decode(), `data' is a byte-array representing an encoded 2477c478bd9Sstevel@tonic-gateoption, which is `length' bytes long. A pointer to a dynamically 2487c478bd9Sstevel@tonic-gateallocated string representing the option's value in ASCII is returned. 2497c478bd9Sstevel@tonic-gateNote that if the `data' byte-array consists of just the payload of the 2507c478bd9Sstevel@tonic-gateoption, then the `just_payload' option should be set. 2517c478bd9Sstevel@tonic-gate 2527c478bd9Sstevel@tonic-gateIn addition, the following routines return extended error information 2537c478bd9Sstevel@tonic-gatefor reporting parsing errors: 2547c478bd9Sstevel@tonic-gate 2557c478bd9Sstevel@tonic-gate uchar_t * 2567c478bd9Sstevel@tonic-gate inittab_encode_e(dhcp_symbol_t *inittab_ent, const char *data, 2577c478bd9Sstevel@tonic-gate uint16_t *lengthp, boolean_t just_payload, int *eerrno); 2587c478bd9Sstevel@tonic-gate 2597c478bd9Sstevel@tonic-gate const char * 2607c478bd9Sstevel@tonic-gate inittab_decode_e(dhcp_symbol_t *inittab_ent, uchar_t *data, 2617c478bd9Sstevel@tonic-gate uint16_t length, boolean_t just_payload, int *eerrno); 2627c478bd9Sstevel@tonic-gate 2637c478bd9Sstevel@tonic-gate 2647c478bd9Sstevel@tonic-gateThe extended codes: 2657c478bd9Sstevel@tonic-gate 2667c478bd9Sstevel@tonic-gate/* 2677c478bd9Sstevel@tonic-gate * DHCP Extended error codes 2687c478bd9Sstevel@tonic-gate */ 2697c478bd9Sstevel@tonic-gate#define ITAB_SYNTAX_ERROR (-1) 2707c478bd9Sstevel@tonic-gate#define ITAB_BAD_IPADDR (-2) 2717c478bd9Sstevel@tonic-gate#define ITAB_BAD_STRING (-3) 2727c478bd9Sstevel@tonic-gate#define ITAB_BAD_OCTET (-4) 2737c478bd9Sstevel@tonic-gate#define ITAB_BAD_NUMBER (-5) 2747c478bd9Sstevel@tonic-gate#define ITAB_BAD_BOOLEAN (-6) 2757c478bd9Sstevel@tonic-gate#define ITAB_NOT_ENOUGH_IP (-7) 2767c478bd9Sstevel@tonic-gate#define ITAB_BAD_GRAN (-8) 2777c478bd9Sstevel@tonic-gate 2787c478bd9Sstevel@tonic-gate 2797c478bd9Sstevel@tonic-gateENVIRONMENT VARIABLES 2807c478bd9Sstevel@tonic-gate===================== 2817c478bd9Sstevel@tonic-gate 2827c478bd9Sstevel@tonic-gateIn order to aid in debugging inittab-related problems, two environment 2837c478bd9Sstevel@tonic-gatevariables, DHCP_INITTAB_DEBUG, and DHCP_INITTAB_PATH, can be set 2847c478bd9Sstevel@tonic-gatebefore starting a program which uses the inittab API. 2857c478bd9Sstevel@tonic-gate 2867c478bd9Sstevel@tonic-gateIf DHCP_INITTAB_DEBUG is an exported environment variable, then the 2877c478bd9Sstevel@tonic-gateinittab API will print useful diagnostic messages handy in tracking 2887c478bd9Sstevel@tonic-gatedown problems in the inittab file. If DHCP_INITTAB_PATH is an 2897c478bd9Sstevel@tonic-gateexported environment variable, then its value is used as the location 2907c478bd9Sstevel@tonic-gateof the inittab file, instead of /etc/dhcp/inittab. 2917c478bd9Sstevel@tonic-gate 2927c478bd9Sstevel@tonic-gate-- 2937c478bd9Sstevel@tonic-gatePeter Memishian, Internet Engineering, Solaris Software (meem@east.sun.com) 294