From: Marcin Siodelski Date: Wed, 5 Nov 2014 12:16:55 +0000 (+0100) Subject: [3467] Updated user guide with option-data parameters optionality. X-Git-Tag: kea-eng-20141219~12^2~4 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=57f4b32ee00bf951379277ef69224e5489b3c00e;p=thirdparty%2Fkea.git [3467] Updated user guide with option-data parameters optionality. --- diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index d24e5bbedc..1d75145c4a 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -552,6 +552,12 @@ temporarily override a list of interface names and listen on all interfaces. } + + Most of the parameters in the "option-data" structure are optional and + can be omitted in some circumstances as discussed in the + . + + It is possible to specify or override options on a per-subnet basis. If clients connected to most of your subnets are expected to get the @@ -589,15 +595,6 @@ temporarily override a list of interface names and listen on all interfaces. - - - In future versions of Kea, it will not be necessary to specify - the code, space - and csv-format fields, as they will - be set automatically. - - - The currently supported standard DHCPv4 options are listed in @@ -1099,6 +1096,76 @@ temporarily override a list of interface names and listen on all interfaces. +
+ Unspecified parameters for option configuration + In many cases it is not required to specify all parameters for + an option configuration and use the default values. However, it is + important to understand the implications of not specifing some of them + as it may result in configuration errors. The list below explains + the behavior of the server when a particular parameter is not explicitly + specified: + + + + name - the server requires an option name or + option code to identify an option. If this parameter is unspecified, the + option code must be specified. + + + + + code - the server requires an option name or + option code to identify an option. This parameter may be left unspecified if + the name parameter is specified. However, this also + requires that the particular option has its definition (it is either a + standard option or an administrator created a definition for the option + using an 'option-def' structure), as the option definition associates an + option with a particular name. It is possible to configure an option + for which there is no definition (unspecified option format). + Configuration of such options requires the use of option code. + + + + + space - if the option space is unspecified it + will default to 'dhcp4' which is an option space holding DHCPv4 standard + options. + + + + + data - if the option data is unspecified it + defaults to an empty value. The empty value is mostly used for the + options which have no payload (boolean options), but it is legal to specify + empty values for some options which carry variable length data and which + spec allows for the length of 0. For such options, the data parameter + may be omitted in the configuration. + + + + csv-format - if this value is not specified + and the definition for the particular option exists, the server will assume + that the option data is specified as a list of comma separated values to be + assigned to individual fields of the DHCP option. If the definition + does not exist for this option, the server will assume that the data + parameter contains the option payload in the binary format (represented + as a string of hexadecimal digits). Note that not specifying this + parameter doesn't imply that it defaults to a fixed value, but + the configuration data interpretation also depends on the presence + of the option definition. An administrator must be aware if the + definition for the particular option exists when this parameter + is not specified. It is generally recommended to not specify this + parameter only for the options for which the definition exists, e.g. + standard options. Setting csv-format to an explicit + value will cause the server to strictly check the format of the option + data specified. + + + + + +
+
Stateless Configuration of DHCPv4 clients The DHCPv4 server supports the stateless client configuration whereby the diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index 93ec7d71ab..4443005bc6 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -644,6 +644,13 @@ temporarily override a list of interface names and listen on all interfaces. to validate data correctness in hexadecimal is limited. + + Most of the parameters in the "option-data" structure are optional and + can be omitted in some circumstances as discussed in the + . + + + It is possible to override options on a per-subnet basis. If clients connected to most of your subnets are expected to get the @@ -681,16 +688,6 @@ temporarily override a list of interface names and listen on all interfaces. - - - In future versions of Kea, it will not be necessary to specify - the code, space - and csv-format fields, as they will - be set automatically. - - - - The currently supported standard DHCPv6 options are listed in . @@ -1090,6 +1087,76 @@ should include options from the isc option space:
+
+ Unspecified parameters for option configuration + In many cases it is not required to specify all parameters for + an option configuration and use the default values. However, it is + important to understand the implications of not specifing some of them + as it may result in configuration errors. The list below explains + the behavior of the server when a particular parameter is not explicitly + specified: + + + + name - the server requires an option name or + option code to identify an option. If this parameter is unspecified, the + option code must be specified. + + + + + code - the server requires an option name or + option code to identify an option. This parameter may be left unspecified if + the name parameter is specified. However, this also + requires that the particular option has its definition (it is either a + standard option or an administrator created a definition for the option + using an 'option-def' structure), as the option definition associates an + option with a particular name. It is possible to configure an option + for which there is no definition (unspecified option format). + Configuration of such options requires the use of option code. + + + + + space - if the option space is unspecified it + will default to 'dhcp6' which is an option space holding DHCPv6 standard + options. + + + + + data - if the option data is unspecified it + defaults to an empty value. The empty value is mostly used for the + options which have no payload (boolean options), but it is legal to specify + empty values for some options which carry variable length data and which + spec allows for the length of 0. For such options, the data parameter + may be omitted in the configuration. + + + + csv-format - if this value is not specified + and the definition for the particular option exists, the server will assume + that the option data is specified as a list of comma separated values to be + assigned to individual fields of the DHCP option. If the definition + does not exist for this option, the server will assume that the data + parameter contains the option payload in the binary format (represented + as a string of hexadecimal digits). Note that not specifying this + parameter doesn't imply that it defaults to a fixed value, but + the configuration data interpretation also depends on the presence + of the option definition. An administrator must be aware if the + definition for the particular option exists when this parameter + is not specified. It is generally recommended to not specify this + parameter only for the options for which the definition exists, e.g. + standard options. Setting csv-format to an explicit + value will cause the server to strictly check the format of the option + data specified. + + + + + +
+
IPv6 Subnet Selection