Skip to content

GitLab

Commit 4cbf341f authored by Francis Dupont's avatar Francis Dupont
Browse files

[master] Finished merge of (hex in integer options)

parents fc28ed03 9957f9c1
Hide whitespace changes
Inline Side-by-side
ChangeLog
View file @ 4cbf341f
1242. [func] fdupont
Integer fields in options can now be specified in either
decimal or hexadecimal format.
(Trac $4540, git xxx)
1241. [func] fdupont
Support for tuple-based options added. DHCPv6 option
bootfile-param (code 60) can now be set in a more convenient
......
doc/examples/kea4/multiple-options.json
View file @ 4cbf341f
# This is an example configuration file for the DHCPv4 server in Kea.
# It demonstrates simple configuration of the options for a subnet.
// This is an example configuration file for the DHCPv4 server in Kea.
// It demonstrates simple configuration of the options for a subnet.
{ "Dhcp4":
{
# Kea is told to listen on ethX interface only.
// Kea is told to listen on ethX interface only.
"interfaces-config": {
"interfaces": [ "ethX" ]
},
# We need to specify the the database used to store leases. As of
# September 2016, four database backends are supported: MySQL,
# PostgreSQL, Cassandra, and the in-memory database, Memfile.
# We'll use memfile because it doesn't require any prior set up.
// We need to specify the the database used to store leases. As of
// September 2016, four database backends are supported: MySQL,
// PostgreSQL, Cassandra, and the in-memory database, Memfile.
// We'll use memfile because it doesn't require any prior set up.
"lease-database": {
"type": "memfile"
},
# Addresses will be assigned with a lifetime of 4000 seconds.
// Addresses will be assigned with a lifetime of 4000 seconds.
"valid-lifetime": 4000,
# Renew and rebind timers are commented out. This implies that options
# 58 and 59 will not be sent to the client. In this case it is up to
# the client to pick the timer values according to RFC2131. Uncomment the
# timers to send these options to the client.
# "renew-timer": 1000,
# "rebind-timer": 2000,
// Renew and rebind timers are commented out. This implies that options
// 58 and 59 will not be sent to the client. In this case it is up to
// the client to pick the timer values according to RFC2131. Uncomment the
// timers to send these options to the client.
// "renew-timer": 1000,
// "rebind-timer": 2000,
// Defining a subnet. There are 3 DHCP options returned to the
// Defining a subnet. There are some DHCP options returned to the
// clients connected to this subnet. The first and third options are
// clients connected to this subnet. The first two options are
// identified by the name. The third option is identified by the
// option code.
"subnet4": [
......@@ -37,39 +38,85 @@
"subnet": "192.0.2.0/24",
"interface": "ethX",
"option-data": [
// When specifying options, you typically need to specify
// one of (name or code) and data. The full option specification
// covers name, code, space, csv-format and data.
// space defaults to "dhcp4" which is usually correct, unless you
// use encapsulate options. csv-format defaults to "true", so
// this is also correct, unless you want to specify the whole
// option value as long hex string. For example, to specify
// domain-name-servers you could do this:
// {
// "name": "domain-name-servers",
// "code": 6,
// "csv-format": "true",
// "space": "dhcp4",
// "data": "192.0.2.1, 192.0.2.2"
// }
// but it's a lot of writing, so it's easier to do this instead:
{
"name": "domain-name-servers",
"data": "192.0.2.1, 192.0.2.2"
},
// Note the Kea provides some of the options on its own. In
// particular:
// - IP address lease time (option 51) is governed by valid-lifetime
// parameter, so you don't need to specify it as option.
// - Subnet mask (option 1) is calculated automatically from the
// subnet parameter specified for each "subnet4" entry.
// - renewal-timer (option 58) is calculated from renew-timer
// parameter
// - rebind timer (option 59) is calculated from rebind-timer
// parameter
// For each IPv4 subnet you most likely need to specify at least
// one router.
{
"name": "routers",
"data": "192.0.2.1"
},
// Typically people prefer to refer to options by their names, so they
// don't need to remember the code names. However, some people like
// to use numerical values. For example, option "domain-name" uses
// option code 15, so you can reference to it either by
// "name": "domain-name" or "code": 15.
{
"code": 15,
"data": "example.org"
},
// String options that have a comma in their values need to have
// it escaped (i.e. each comma is predeced by two backslashes).
// That's because commas are reserved for separating fields in
// compound options. At the same time, we need to be conformant
// with JSON spec, that does not allow "\,". Therefore the
// slightly uncommon double backslashes notation is needed.
// Legal JSON escapes are \ followed by "\/bfnrt character
// or \u followed by 4 hexa-decimal numbers (currently Kea
// supports only \u0000 to \u00ff code points).
// CSV processing translates '\\' into '\' and '\,' into ','
// only so for instance '\x' is translated into '\x'. But
// as it works on a JSON string value each of these '\'
// characters must be doubled on JSON input.
{
// String options that have a comma in their values need to have
// it escaped (i.e. each comma is predeced by two backslashes).
// That's because commas are reserved for separating fields in
// compound options. At the same time, we need to be conformant
// with JSON spec, that does not allow "\,". Therefore the
// slightly uncommon double backslashes notation is needed.
"name": "boot-file-name",
"data": "EST5EDT4\\,M3.2.0/02:00\\,M11.1.0/02:00"
"name": "boot-file-name",
"data": "EST5EDT4\\,M3.2.0/02:00\\,M11.1.0/02:00"
// Legal JSON escapes are \ followed by "\/bfnrt character
// or \u followed by 4 hexa-decimal numbers (currently Kea
// supports only \u0000 to \u00ff code points).
// CSV processing translates '\\' into '\' and '\,' into ','
// only so for instance '\x' is translated into '\x'. But
// as it works on a JSON string value each of these '\'
// characters must be doubled on JSON input.
},
// Options that take integer values can either be specified in
// dec or hex format. Hex format could be either plain (e.g. abcd)
// or prefixed with 0x (e.g. 0xabcd).
{
"name": "default-ip-ttl",
"data": "0xf0"
}
]
}
]
},
# The following configures logging. It assumes that messages with at least
# informational level (info, warn, error and fatal) should be logged to stdout.
// The following configures logging. It assumes that messages with at least
// informational level (info, warn, error and fatal) should be logged to stdout.
"Logging": {
"loggers": [
{
......
doc/examples/kea6/multiple-options.json
View file @ 4cbf341f
# This is an example configuration file for DHCPv6 server in Kea.
# It demonstrates simple configuration of the options for a subnet.
// This is an example configuration file for DHCPv6 server in Kea.
// It demonstrates simple configuration of the options for a subnet.
{ "Dhcp6":
{
# Kea is told to listen on ethX interface only.
// Kea is told to listen on ethX interface only.
"interfaces-config": {
"interfaces": [ "ethX" ]
},
# We need to specify the the database used to store leases. As of
# September 2016, four database backends are supported: MySQL,
# PostgreSQL, Cassandra, and the in-memory database, Memfile.
# We'll use memfile because it doesn't require any prior set up.
// We need to specify the the database used to store leases. As of
// September 2016, four database backends are supported: MySQL,
// PostgreSQL, Cassandra, and the in-memory database, Memfile.
// We'll use memfile because it doesn't require any prior set up.
"lease-database": {
"type": "memfile"
},
# Addresses will be assigned with preferred and valid lifetimes
# being 3000 and 4000, respectively. Client is told to start
# renewing after 1000 seconds. If the server does not respond
# after 2000 seconds since the lease was granted, client is supposed
# to start REBIND procedure (emergency renewal that allows switching
# to a different server).
// Addresses will be assigned with preferred and valid lifetimes
// being 3000 and 4000, respectively. Client is told to start
// renewing after 1000 seconds. If the server does not respond
// after 2000 seconds since the lease was granted, client is supposed
// to start REBIND procedure (emergency renewal that allows switching
// to a different server).
"preferred-lifetime": 3000,
"valid-lifetime": 4000,
"renew-timer": 1000,
"rebind-timer": 2000,
# Defining a subnet. There are 3 DHCP options returned to the
# clients connected to this subnet. The first option is identified
# by the name. The second option is identified by the code.
# There are two address pools defined within this subnet. Pool
# specific value for option 12 is defined for the pool:
# 2001:db8:1::1 - 2001:db8:1::100. Clients obtaining an address
# from this pool will be assigned option 12 with a value of
# 3001:cafe::21. Clients belonging to this subnet but obtaining
# addresses from the other pool, or the clients obtaining
# stateless configuration will be assigned subnet specific value
# of option 12, i.e. 2001:db8:1:0:ff00::1.
# For DHCPv6 subnets can have prefix delegation pools too so
# a pd-pools with an option-data is defined too.
// Defining a subnet. There are some DHCP options returned to the
// clients connected to this subnet. The first option is identified
// by the name. The second option is identified by the code.
// There are two address pools defined within this subnet. Pool
// specific value for option 12 is defined for the pool:
// 2001:db8:1::1 - 2001:db8:1::100. Clients obtaining an address
// from this pool will be assigned option 12 with a value of
// 3001:cafe::21. Clients belonging to this subnet but obtaining
// addresses from the other pool, or the clients obtaining
// stateless configuration will be assigned subnet specific value
// of option 12, i.e. 2001:db8:1:0:ff00::1.
// For DHCPv6 subnets can have prefix delegation pools too so
// a pd-pools with an option-data is defined too.
"subnet6": [
{
"option-data": [
{
"name": "dns-servers",
"data": "2001:db8:2::45, 2001:db8:2::100"
},
{
"code": 12,
"data": "2001:db8:1:0:ff00::1"
},
{
// This is how option values are defined for this particular subnet.
"option-data": [
// When specifying options, you typically need to specify
// one of (name or code) and data. The full option specification
// covers name, code, space, csv-format and data.
// space defaults to "dhcp6" which is usually correct, unless you
// use encapsulate options. csv-format defaults to "true", so
// this is also correct, unless you want to specify the whole
// option value as long hex string. For example, to specify
// domain-name-servers you could do this:
// {
// "name": "dns-servers",
// "code": 23,
// "csv-format": "true",
// "space": "dhcp6",
// "data": "2001:db8:2::45, 2001:db8:2::100"
// }
// but it's a lot of writing, so it's easier to do this instead:
{
"name": "dns-servers",
"data": "2001:db8:2::45, 2001:db8:2::100"
},
// Typically people prefer to refer to options by their names, so they
// don't need to remember the code names. However, some people like
// to use numerical values. For example, DHCPv6 can optionally use
// server unicast communication, if extra option is present. Option
// "unicast" uses option code 12, so you can reference to it either
// by "name": "unicast" or "code": 12.
{
"code": 12,
"data": "2001:db8:1:0:ff00::1"
},
// String options that have a comma in their values need to have
// it escaped (i.e. each comma is predeced by two backslashes).
// That's because commas are reserved for separating fields in
// compound options. At the same time, we need to be conformant
// with JSON spec, that does not allow "\,". Therefore the
// slightly uncommon double backslashes notation is needed.
"name": "new-posix-timezone",
"data": "EST5EDT4\\,M3.2.0/02:00\\,M11.1.0/02:00"
// Legal JSON escapes are \ followed by "\/bfnrt character
// or \u followed by 4 hexa-decimal numbers (currently Kea
......@@ -69,14 +91,26 @@
// only so for instance '\x' is translated into '\x'. But
// as it works on a JSON string value each of these '\'
// characters must be doubled on JSON input.
},
{
{
"name": "new-posix-timezone",
"data": "EST5EDT4\\,M3.2.0/02:00\\,M11.1.0/02:00"
},
// Options that take integer values can either be specified in
// dec or hex format. Hex format could be either plain (e.g. abcd)
// or prefixed with 0x (e.g. 0xabcd).
{
"name": "preference",
"data": "0xf0"
},
// A few options are encoded in (length, string) tuples
// which can be defined using only strings as the CSV
// processing computes lengths.
"name": "bootfile-param",
"data": "root=/dev/sda2, quiet, splash"
}
{
"name": "bootfile-param",
"data": "root=/dev/sda2, quiet, splash"
}
],
"pools": [
{
......@@ -111,8 +145,8 @@
]
},
# The following configures logging. It assumes that messages with at least
# informational level (info, warn, error and fatal) should be logged to stdout.
// The following configures logging. It assumes that messages with at least
// informational level (info, warn, error and fatal) should be logged to stdout.
"Logging": {
"loggers": [
{
......
doc/guide/dhcp4-srv.xml
View file @ 4cbf341f
......@@ -957,22 +957,38 @@ temporarily override a list of interface names and listen on all interfaces.
...
]
}
</screen>
</screen>
Note that only one of name or code is required, you don't need to
specify both. Space has a default value of "dhcp4", so you can skip this
as well if you define a regular (not encapsulated) DHCPv4 option.
Finally, csv-format defaults to true, so it too can be skipped, unless
you want to specify the option value as hexstring. Therefore the
above example can be simplified to:
<screen>
"Dhcp4": {
"option-data": [
{
<userinput>"name": "domain-name-servers",
"data": "192.0.2.1, 192.0.2.2"</userinput>
},
...
]
} </screen>
</para>
<para>
The <command>name</command> parameter specifies the
option name. For a list of currently supported names, see
<xref linkend="dhcp4-std-options-list"/> below.
The <command>code</command> parameter specifies the option code, which must match one of the
values from that list. The next line specifies the option space, which must always
be set to "dhcp4" as these are standard DHCPv4 options. For
other option spaces, including custom option spaces, see <xref
The <command>name</command> parameter specifies the option name. For a
list of currently supported names, see <xref
linkend="dhcp4-std-options-list"/> below. The <command>code</command>
parameter specifies the option code, which must match one of the values
from that list. The next line specifies the option space, which must
always be set to "dhcp4" as these are standard DHCPv4 options. For other
option spaces, including custom option spaces, see <xref
linkend="dhcp4-option-spaces"/>. The next line specifies the format in
which the data will be entered: use of CSV (comma
separated values) is recommended. The sixth line gives the actual value to
be sent to clients. Data is specified as normal text, with
values separated by commas if more than one value is
allowed.
which the data will be entered: use of CSV (comma separated values) is
recommended. The sixth line gives the actual value to be sent to
clients. Data is specified as normal text, with values separated by commas
if more than one value is allowed.
</para>
<para>
......@@ -1043,8 +1059,7 @@ temporarily override a list of interface names and listen on all interfaces.
<para>
The currently supported standard DHCPv4 options are
listed in <xref linkend="dhcp4-std-options-list"/>
and <xref linkend="dhcp4-std-options-list-part2"/>.
listed in <xref linkend="dhcp4-std-options-list"/>.
The "Name" and "Code"
are the values that should be used as a name in the option-data
structures. "Type" designates the format of the data: the meanings of
......@@ -1165,32 +1180,6 @@ This rather belong to the DDNS configuration
<row><entry>default-tcp-ttl</entry><entry>37</entry><entry>uint8</entry><entry>false</entry><entry>false</entry></row>
<row><entry>tcp-keepalive-interval</entry><entry>38</entry><entry>uint32</entry><entry>false</entry><entry>false</entry></row>
<row><entry>tcp-keepalive-garbage</entry><entry>39</entry><entry>boolean</entry><entry>false</entry><entry>false</entry></row>
</tbody>
</tgroup>
</table>
</para>
<para>
<table frame="all" id="dhcp4-std-options-list-part2">
<title>List of standard DHCPv4 options (continued)</title>
<tgroup cols='5'>
<colspec colname='name'/>
<colspec colname='code' align='center'/>
<colspec colname='type' align='center'/>
<colspec colname='array' align='center'/>
<colspec colname='always-returned' align='center'/>
<thead>
<row>
<entry>Name</entry>
<entry>Code</entry>
<entry>Type</entry>
<entry>Array?</entry>
<entry>Returned if not requested?</entry>
</row>
</thead>
<tbody>
<row><entry>nis-domain</entry><entry>40</entry><entry>string</entry><entry>false</entry><entry>false</entry></row>
<row><entry>nis-servers</entry><entry>41</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
<row><entry>ntp-servers</entry><entry>42</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
......@@ -1414,6 +1403,12 @@ It is merely echoed by the server
<command>"1"</command>. Future versions of Kea will accept all those values
for all boolean parameters.</para>
</note>
<note>
<para>Numbers can be specified in decimal or hexadecimal format.
The hexadecimal format can be either plain (e.g. abcd) or
prefixed with 0x (e.g. 0xabcd).
</para>
</note>
</section>
<section id="dhcp4-vendor-opts">
......
doc/guide/dhcp6-srv.xml
View file @ 4cbf341f
......@@ -982,9 +982,26 @@ temporarily override a list of interface names and listen on all interfaces.
</para>
<para>
Most of the parameters in the "option-data" structure are optional and
can be omitted in some circumstances as discussed in the
<xref linkend="dhcp6-option-data-defaults"/>.
Most of the parameters in the "option-data" structure are
optional and can be omitted in some circumstances as discussed
in the <xref linkend="dhcp6-option-data-defaults"/>. Only one
of name or code is required, so you don't need to specify
both. Space has a default value of "dhcp6", so you can skip
this as well if you define a regular (not encapsulated) DHCPv6
option. Finally, csv-format defaults to true, so it too can
be skipped, unless you want to specify the option value as
hexstring. Therefore the above example can be simplified to:
<screen>
"Dhcp4": {
"option-data": [
{
<userinput>"name": "dns-servers",
"data": "2001:db8::cafe, 2001:db8::babe"</userinput>
},
...
]
} </screen>
</para>
......
src/lib/dhcp/option_definition.cc
View file @ 4cbf341f
......@@ -29,6 +29,7 @@
#include <boost/algorithm/string/classification.hpp>
#include <boost/algorithm/string/predicate.hpp>
#include <boost/dynamic_bitset.hpp>
#include <sstream>
using namespace std;
using namespace isc::util;
......@@ -496,8 +497,15 @@ OptionDefinition::lexicalCastWithRangeCheck(const std::string& value_str)
result = boost::lexical_cast<int64_t>(value_str);
} catch (const boost::bad_lexical_cast&) {
isc_throw(BadDataTypeCast, "unable to convert the value '"
<< value_str << "' to integer data type");
// boost::lexical_cast does not handle hexadecimal
// but stringstream does so do it the hard way.
std::stringstream ss;
ss << std::hex << value_str;
ss >> result;
if (ss.fail() || !ss.eof()) {
isc_throw(BadDataTypeCast, "unable to convert the value '"
<< value_str << "' to integer data type");
}
}
// Perform range checks.
if (OptionDataTypeTraits<T>::integer_type) {
......
src/lib/dhcp/option_definition.h
View file @ 4cbf341f
......@@ -641,7 +641,7 @@ private:
/// This function performs lexical cast of a string value to integer
/// value and checks if the resulting value is within a range of a
/// target type. The target type should be one of the supported
/// integer types.
/// integer types. Hexadecimal input is supported.
///
/// @param value_str input value given as string.
/// @tparam T target integer type for lexical cast.
......
src/lib/dhcp/tests/option_definition_unittest.cc
View file @ 4cbf341f
......@@ -1191,7 +1191,8 @@ TEST_F(OptionDefinitionTest, uint32ArrayTokenized) {
OptionPtr option_v6;
std::vector<std::string> str_values;
str_values.push_back("123456");
str_values.push_back("7");
// Try with hexadecimal
str_values.push_back("0x7");
str_values.push_back("256");
str_values.push_back("1111");
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment