# # CDDL HEADER START # # The contents of this file are subject to the terms of the # Common Development and Distribution License, Version 1.0 only # (the "License"). You may not use this file except in compliance # with the License. # # You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE # or http://www.opensolaris.org/os/licensing. # See the License for the specific language governing permissions # and limitations under the License. # # When distributing Covered Code, include this CDDL HEADER in each # file and include the License file at usr/src/OPENSOLARIS.LICENSE. # If applicable, add the following below this CDDL HEADER, with the # fields enclosed by brackets "[]" replaced with your own identifying # information: Portions Copyright [yyyy] [name of copyright owner] # # CDDL HEADER END # Copyright (c) 2001 by Sun Microsystems, Inc. All rights reserved. Inittab Purpose, Goals, and Functionality Peter Memishian PROBLEM STATEMENT ================= Currently, each DHCP-related utility that needs to handle DHCP options uses ad-hoc methods for learning and using them, ranging from using hard-coded internal tables to providing published (but distinct) configuration files describing these options. Originally, when only the DHCP server needed to be concerned with DHCP options, not having a standard API for managing and parsing DHCP options was understandable. Now, with four consumers of DHCP options in core Solaris (in.dhcpd, dhcpinfo, snoop, and dhcpmgr), the situation has spiraled out of control. In addition to the obvious maintenance headache caused by the redundant code, it has also become a burden to our customers, who already have to cope with multiple places where DHCP option information is stored (dhcptags(5), dhcptab(5)). The inittab API is designed to reduce the confusion, both for the customer and the application developer. Its goal is to provide a single configuration for applications to receive their DHCP option knowledge from and general routines for encoding and decoding DHCP options. INITTAB ======= The inittab file contains information regarding the syntax and (to some degree) the semantics of DHCP options. It is primarily a read-only file (like /etc/termcap) and should not need to be changed by users. Experienced sysadmins may need to update this file to add new DHCP options, but this should be rare. The inittab file consists of inittab records, each being one line long and describing a particular option. The format is based heavily on the format for defining symbols in dhcptab(5). Each line has the following syntax: option_name category, code, type, granularity, maximum, consumers where: `option_name' is user-interpretable name of the option (for use with dhcpinfo(1) for instance). This field should at least be per- category unique and ideally should be unique across all categories. Of particular note is that options names in the STANDARD, SITE, and VENDOR spaces should not overlap, or the behavior is undefined. `category' is one of STANDARD, SITE, VENDOR, FIELD, or INTERNAL and identifies the namespace in which the option falls. `code' is the code of this option when it is sent over the wire. (note: in most cases, `code' uniquely identifies the option, without a category. however, in the case of internal categories like FIELD or INTERNAL, `code' may be used for other purposes and thus may not be globally unique). This field should be per-category unique and the STANDARD and SITE fields should not have overlapping code fields or the behavior is undefined. `type' describes the payload associated with this option. Valid types are IP, ASCII, OCTET, NUMBER, BOOL, UNUMBER8, UNUMBER16, UNUMBER32, SNUMBER8, SNUMBER16, and SNUMBER32. For numbers, a preceding `U' or `S' indicates whether the number is unsigned or signed, and the trailing number indicates the number of bits in the number. `granularity' describes how many units of `type' payload make up a whole value for this option. In the case of `NUMBER', granularity describes the number of bytes in the number. Note that `NUMBER' is preserved for compatibility, but the more descriptive [SU]NUMBER{8,16,32,64} types should preferred. `maximum' describes how many whole values are allowed for this option. 0 indicates an infinite number. `consumers' describe which programs make use of this information. (`i' for dhcpinfo, `s' for snoop, `d' for in.dhcpd, and `m' for dhcpmgr). A sample entry would be StaticRt STANDARD, 33, IP, 2, 0, isdm which describes an option named `StaticRt', that is in the STANDARD category (i.e., defined by the DHCP standard), and is option code 33, which is of type `IP Address', consisting of a potentially infinite number of pairs of IP addresses. Lastly, the consumers of option are dhcpinfo, snoop, in.dhcpd and dhcpmgr. Comments in the inittab file begin with `#', and end with a newline. Comments need not start at the beginning of a line. Lines cannot be continued (with `\' for instance). The inittab file becomes the authoritative source for all DHCP options for all DHCP option consumers, with the following exceptions and notes: o The DHCP agent and DHCP server both have their core protocol- related functionality hardcoded into them, so changes to the inittab file do not generally affect their inner workings. o A program can specify which entries it wants from the inittab. This means that some DHCP options will never be used by some programs, even if they are listed as a `consumer' of the given option. An example of this is that the DHCP server never requests any fields with the VENDOR category. (VENDOR information for the DHCP server comes from dhcptab(5) instead). o In general, changing provided information in a released inittab file is ill-advised. Adding new entries should be the extent of the modifications that are performed. o The inittab C API also provides functions which allow programs to verify that a given entry in the inittab file is correct (which it does by consulting a compiled-in database of current options). In general, this functionality is only used where absolutely necessary, since it nullifies some of the advantages of having an inittab. o Where a symbol is defined both in the inittab and in dhcptab(5), inittab is authoritative. EXTEND symbol definitions in dhcptab(5) will be deprecated in a future release of Solaris. C-LEVEL API =========== Each inittab entry describes a specific DHCP option and is defined as a dhcp_symbol_t (as defined in usr/src/lib/libdhcputil/common/dhcp_symbol.h). In general, it is expected that inittab entries are acquired via inittab_load(), inittab_getbyname(), or inittab_getbycode() and passed as needed to the remaining inittab_XXX functions. If consumers need to convert the inittab entries into a different format, then the fields inside the inittab entry may be read directly. Some inittab functions return dynamically allocated parameters; all such parameters can be freed with free(3c). To get an inittab entry, one of the following API's must be used: dhcp_symbol_t * inittab_load(uchar_t categories, char consumer, size_t *n_entries); dhcp_symbol_t * inittab_getbyname(uchar_t categories, char consumer, const char *name); dhcp_symbol_t * inittab_getbycode(uchar_t categories, char consumer, unsigned int code); where the `categories' parameter consists of the following values OR'd together: #define ITAB_CAT_STANDARD 0x01 #define ITAB_CAT_FIELD 0x02 #define ITAB_CAT_INTERNAL 0x04 #define ITAB_CAT_VENDOR 0x08 #define ITAB_CAT_SITE 0x10 and the `consumer' field consists of one of the following: #define ITAB_CONS_INFO 'i' #define ITAB_CONS_SERVER 'd' #define ITAB_CONS_SNOOP 's' #define ITAB_CONS_MANAGER 'm' inittab_load() creates and returns an array of dhcp_symbol_t's made up of all the entries of the specified categories that are available to the provided consumer. Note that there is no specified order to the entries returned. The array is dynamically allocated, and the number of items in the array is returned in the `n_entries' parameter. inittab_getbyname()/inittab_getbycode() return an dhcp_symbol_t matching the given name or code for the provided category and the provided consumer. The dhcp_symbol_t is dynamically allocated. Some inittab consumers may need to make sure that a given inittab entry has not been corrupted in the inittab file. For those cases, inittab_verify() can be used to validate an inittab_entry against an internal table compiled into the inittab API: int inittab_verify(dhcp_symbol_t *inittab_ent, dhcp_symbol_t *internal_ent); where `inittab_ent' is an dhcp_symbol_t previously returned from inittab_load() or inittab_getbyX(). inittab_verify() returns ITAB_SUCCESS if `inittab_ent' is verified to be correct, ITAB_FAILURE if `inittab_ent' is incorrect, and ITAB_UNKNOWN if inittab_verify() doesn't know. If `internal_ent' is non-NULL, it is filled in with the value of the option known internally to the inittab API. Entries are verified using the `ds_category' and `ds_code' fields from the dhcp_symbol_t. For ITAB_SUCCESS to be returned, the entry passed in and the internal entry both must have the same ds_gran, ds_max, and ds_type values. To perform encoding and decoding of DHCP options, the following routines are provided: uchar_t * inittab_encode(dhcp_symbol_t *inittab_ent, const char *data, uint16_t *lengthp, boolean_t just_payload); const char * inittab_decode(dhcp_symbol_t *inittab_ent, uchar_t *data, uint16_t length, boolean_t just_payload); Both of these routines take an `inittab_ent' that was previously returned from inittab_load() or inittab_getbyX(). For inittab_encode(), `data' is an ASCII string to encode, and a pointer to a dynamically allocated byte-array representing the encoded option is returned. The size of the resulting data returned is stored in `lengthp'. Note that if the `just_payload' option is set, then only the payload of the option is returned (i.e., the option code and option length is left off the returned data). To encode multiple items of a given type, separate the items by spaces, such as "109.108.21.1 148.232.2.1". Octal data should be of the form "0xNN" where NN is a hexadecimal digit representing the byte. For inittab_decode(), `data' is a byte-array representing an encoded option, which is `length' bytes long. A pointer to a dynamically allocated string representing the option's value in ASCII is returned. Note that if the `data' byte-array consists of just the payload of the option, then the `just_payload' option should be set. In addition, the following routines return extended error information for reporting parsing errors: uchar_t * inittab_encode_e(dhcp_symbol_t *inittab_ent, const char *data, uint16_t *lengthp, boolean_t just_payload, int *eerrno); const char * inittab_decode_e(dhcp_symbol_t *inittab_ent, uchar_t *data, uint16_t length, boolean_t just_payload, int *eerrno); The extended codes: /* * DHCP Extended error codes */ #define ITAB_SYNTAX_ERROR (-1) #define ITAB_BAD_IPADDR (-2) #define ITAB_BAD_STRING (-3) #define ITAB_BAD_OCTET (-4) #define ITAB_BAD_NUMBER (-5) #define ITAB_BAD_BOOLEAN (-6) #define ITAB_NOT_ENOUGH_IP (-7) #define ITAB_BAD_GRAN (-8) ENVIRONMENT VARIABLES ===================== In order to aid in debugging inittab-related problems, two environment variables, DHCP_INITTAB_DEBUG, and DHCP_INITTAB_PATH, can be set before starting a program which uses the inittab API. If DHCP_INITTAB_DEBUG is an exported environment variable, then the inittab API will print useful diagnostic messages handy in tracking down problems in the inittab file. If DHCP_INITTAB_PATH is an exported environment variable, then its value is used as the location of the inittab file, instead of /etc/dhcp/inittab. -- Peter Memishian, Internet Engineering, Solaris Software (meem@east.sun.com)