usr/src/lib/libdhcputil/README.inittab

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