#
# 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
ident	"%Z%%M%	%I%	%E% SMI"

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(4),
dhcptab(4)).

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(4).  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(1M) 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(4) 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(4),
      inittab is authoritative.  EXTEND symbol definitions in
      dhcptab(4) 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)