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