Some operating systems have split their distribution packages into a run-time and a development package. You will need to install the development package versions, which include header files and libraries, to build Bundy from source code.

Building from source code requires the Boost build-time headers (http://www.boost.org/). At least Boost version 1.35 is required.

To build Bundy, also install the Botan (at least version 1.8) and the log4cplus (at least version 1.0.3) development include headers.

Building Bundy also requires a C++ compiler and standard development headers, make, and pkg-config. Bundy builds have been tested with GCC g++ 3.4.3, 4.1.2, 4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10.

Downloading a release tar file is the recommended method to obtain the source code.

The Bundy releases are available as tar file downloads from http://bundy-dns.de/. Periodic development snapshots may also be available.

Downloading this "bleeding edge" code is recommended only for developers or advanced users. Using development code in a production environment is not recommended.

When using source code retrieved via Git, additional software will be required: automake (v1.11 or newer), libtoolize, and autoconf (2.59 or newer). These may need to be installed.

The latest development code (and temporary experiments and un-reviewed code) is available via the Bundy code revision control system. This is powered by Git and all the Bundy development is public. The leading development is done in the “master” branch.

The code can be checked out from git://github/newname; for example:

$ git clone git://github/newname

When checking out the code from the code version control system, it doesn't include the generated configure script, Makefile.in files, nor their related build files. They can be created by running autoreconf with the --install switch. This will run autoconf, aclocal, libtoolize, autoheader, automake, and related commands.

Bundy uses the GNU Build System to discover build environment details. To generate the makefiles using the defaults, simply run:

$ ./configure

Run ./configure with the --help switch to view the different options. Some commonly-used options are:

–prefix

Define the installation location (the default is /usr/local/).

–with-boost-include

Define the path to find the Boost headers.

–with-pythonpath

Define the path to Python 3.1 if it is not in the standard execution path.

–with-gtest

Enable building the C++ Unit Tests using the Google Tests framework. Optionally this can define the path to the gtest header files and library.

–without-werror

Disable the default use of the -Werror compiler flag so that compiler warnings aren't build failures.

For additional instructions concerning the building and installation of Bundy DHCP, see Section 16.1, “DHCP Database Installation and Configuration”.

For example, the following configures it to find the Boost headers, find the Python interpreter, and sets the installation location:

$ ./configure \
      --with-boost-include=/usr/pkg/include \
      --with-pythonpath=/usr/pkg/bin/python3.1 \
      --prefix=/opt/bundy

If the configure fails, it may be due to missing or old dependencies.

After the configure step is complete, to build the executables from the C++ code and prepare the Python scripts, run:

$ make

To install the Bundy executables, support files, and documentation, run:

$ make install

Please don't use any form of parallel or job server options (such as GNU make's -j option) when performing this step. Doing so may cause errors.

The install step may require superuser privileges.

If required, run ldconfig as root with /usr/local/lib (or with ${prefix}/lib if configured with –prefix) in /etc/ld.so.conf (or the relevant linker cache configuration file for your OS):

$ ldconfig

If you do not run ldconfig where it is required, you may see errors like the following:

program: error while loading shared libraries: libbundy-something.so.1:
cannot open shared object file: No such file or directory

If the setproctitle Python module is detected at start up, the process names for the Python-based daemons will be renamed to better identify them instead of just “python”. This is not needed on some operating systems.

The current release only provides bundyctl as a user interface to bundy-cmdctl. Upcoming releases will provide another interactive command-line interface and a web-based interface.

The bundy-cfgmgr daemon can send all specifications and all current settings to the bundyctl client (via bundy-cmdctl). bundy-cfgmgr relays configurations received from bundy-cmdctl to the appropriate modules.

The stored configuration file is at /usr/local/var/bundy/bundy-config.db. (The directory is what was defined at build configure time for --localstatedir. The default is /usr/local/var/.) The format is loosely based on JSON and is directly parseable python, but this may change in a future version. This configuration data file is not manually edited by the administrator.

The configuration manager does not have any command line arguments. Normally it is not started manually, but is automatically started using the bundy-init master process (as covered in Chapter 4, Starting Bundy with bundy).

The HTTPS server doesn't support a certificate request from a client (at this time). The bundy-cmdctl daemon does not provide a public service. If any client wants to control Bundy, then a certificate needs to be first received from the Bundy administrator. The Bundy installation provides a sample PEM bundle that matches the sample key and certificate.

The bundy-cmdctl daemon also requires the user account file located at /usr/local/etc/bundy/cmdctl-accounts.csv. This comma-delimited file lists the accounts with a user name, hashed password, and salt.

The administrator may create a user account with the bundy-cmdctl-usermgr tool.

By default the HTTPS server listens on the localhost port 8080. The port can be set by using the --port command line option. The address to listen on can be set using the --address command line argument. Each HTTPS connection is stateless and times out in 1200 seconds by default. This can be redefined by using the --idle-timeout command line argument.

The following configuration commands are available:

show [all] [item name]

Shows the current configuration of the given item. If 'all' is given, it will recurse through the entire set, and show every nested value.

show\_json [item name]

Shows the full configuration of the given item in JSON format.

add <item name> [value]

Add an entry to configuration list or a named set (see Section 8.6.2, “Configuration data types”). When adding to a list, the command has one optional argument, a value to add to the list. The value must be in correct JSON and complete. When adding to a named set, it has one mandatory parameter (the name to add), and an optional parameter value, similar to when adding to a list. In either case, when no value is given, an entry will be constructed with default values.

remove

Remove an item from a configuration list or a named set. When removing an item for a list, either the index needs to be specified, or the complete value of the element to remove must be specified (in JSON format).

set <item name> <value>

Directly set the value of the given item to the given value.

unset <item name>

Remove any user-specified value for the given item.

diff

Show all current local changes that have not been committed yet.

revert

Revert all local changes without committing them.

commit

Send all local changes to the configuration manager, which will validate them, and apply them if validation succeeds.

go

Go to a specific configuration part, similar to the 'cd' command in a shell.

* Note

There are a number of problems with the current implementation of go within bundyctl, and we recommend not using it for general cases.

Configuration data can be of different types, which can be modified in ways that depend on the types. There are a few syntax restrictions on these types, but only basic ones. Modules may impose additional restrictions on the values of elements.

integer

A basic integer; can be set directly with config set, to any integer value. The value must not be quoted, or else, it will be parsed as a string.

real

A basic floating point number; can be set directly with config set, to any floating point value. The value must not be quoted, or else, it will be parsed as a string.

boolean

A basic boolean value; can be set directly with config set, to either true or false. The value must not be quoted, or else, it will be parsed as a string. Integer values are not allowed.

string

A basic string value; can be set directly with config set to any string. Double quotation marks are optional.

null

This is a special type representing 'no value at all'; usable in compound structures that have optional elements that are not set.

maps

Maps are (pre-defined) compound collections of other elements of any other type. They are not usually modified directly, but their elements are. Every top-level element for a module is a map containing the configuration values for that map, which can themselves be maps again. For instance, the Auth module configuration is a map containing the elements 'listen_on' (list) and 'tcp_recv_timeout' (integer). When changing one of its values, they can be modified directly with config set Auth/tcp\_recv\timeout 3000.

Some map entries are optional. If they are, and currently have a value, the value can be unset by using either config unset <item name> or config set <item name> null.

Maps can be modified as a whole, but using the full JSON representation of the entire map to set. Since this involves a lot of text, this is usually not recommended.

Another example is the Logging virtual module, which is, like any module, a map, but it only contains one element: a list of loggers. Normally, an administrator would only modify that list (or its elements) directly, but it is possible to set the entire map in one command; for example: config set Logging { "loggers": [] }

list

A list is a compound list of other elements of the same type. Elements can be added with config add <list name> [value], and removed with config remove <list name> [value] or config remove <list name>=//=<index>. The index is of the form square bracket, number, square bracket (e.g. ¹), and it immediately follows the list name (there is no separator or space between them). List indices start with 0 for the first element.

For addition, if the value is omitted, an entry with default values will be added. For removal, either the index or the full value (in JSON format) needs to be specified.

Lists can also be used with config set, but like maps, only by specifying the entire list value in JSON format.

For example, this command shows the port number used for the second element of the list listen_on in the Auth module: config show Auth/listen\_on²/port

named set

Named sets are similar to lists, in that they are sets of elements of the same type, but they are not indexed by numbers, but by strings.

Values can be added with config add <item name> <string> [value] where 'string' is the name of the element. If 'value' is ommitted, default values will be used. Elements can be removed with config remove <item name> <string>

Elements in a named set can be addressed similarly to maps.

For example, the Init/components elements is a named set; adding, showing, and then removing an element can be done with the following three commands (note the '/'-character versus the space before 'example\_module'):

config add Init/components example\_module

config show Init/components/example\_module

config remove Init/components example\_module

any

The 'any' type is a special type that can have any form. Apart from that, it must consist of elements as described in this chapter, there is no restriction on which element types are used. This type is used in places where different data formats could be used. Element modification commands depend on the actual type of the value. For instance, if the value of an 'any' element is a list, config add and config remove work as for other lists.

Within sets of commands to be run with the execute command, a number of directives are supported:

!echo <string>

Prints the given string to bundyctl's output.

!verbose on

Enables verbose mode; all following commands that are to be executed are also printed.

!verbose off

Disables verbose mode; following commands that are to be executed are no longer printed.

Within scripts, you can add or remove modules with the normal configuration commands for Init/components. However, as module configuration and commands do not show up until the module is running, it is currently not possible to add a module and set its configuration in one script. This will be addressed in the future, but for now the only option is to add and configure modules in separate commands and execute scripts.

Each key has three attributes. One is a name by which it is referred both in DNS packets and the rest of the configuration. Another is the algorithm used to compute the signature. And the last part is a base64 encoded secret, which might be any blob of data.

The parts are written into a string, concatenated together by colons. So if you wanted to have a key called "example.key", used as a HMAC-MD5 key with secret "secret", you'd write it as:

"example.key.:c2VjcmV0:hmac-md5"

The HMAC-MD5 algorithm is the default, so you can omit it. You could write the same key as:

"example.key.:c2VjcmV0"

You can also use these algorithms (which may not be omitted from the key definition if used):

• hmac-sha1
• hmac-sha224
• hmac-sha256
• hmac-sha384
• hmac-sha512

The name of the key must be a valid DNS name.

The key ring lives in the configuration in "tsig\_keys/keys". Most of the system uses the keys from there — ACLs, authoritative server to sign responses to signed queries, and bundy-xfrin and bundy-xfrout to sign transfers.

The key ring is just a list of strings, each describing one key. So, to add a new key, you can do this:

> config add tsig_keys/keys "example.key.:c2VjcmV0"
> config show tsig_keys/keys
tsig_keys/keys[0]   "example.key.:c2VjcmV0" string  (modified)
> config commit

You can keep as many keys as you want in the key ring, but each must have a different name.

The first thing you can check against is the source address of request. The name is from and the value is a string containing either a single IPv4 or IPv6 address, or a range in the usual slash notation (eg. "192.0.2.0/24").

The other is TSIG key by which the message was signed. The ACL contains only the name (under the name "key"), the key itself must be stored in the global key ring (see Section 9.1.2, “Key ring”). This property is applicable only to the DNS context.

More properties to match are planned — the destination address, ports, matches against the packet content.

From time to time, you need to express something more complex than just a single address or key.

You can specify a list of values instead of single value. Then the property needs to match at least one of the values listed — so you can say “"from": ["192.0.2.0/24", "2001:db8::/32"]” to match any address in the ranges set aside for documentation. The keys or any future properties will work in a similar way.

If that is not enough, you can compose the matching conditions to logical expressions. They are called "ANY", "ALL" and "NOT". The "ANY" and "ALL" ones contain lists of subexpressions — each subexpression is a similar dictionary, just not containing the "action" element. The "NOT" contains single subexpression. Their function should be obvious — "NOT" matches if and only if the subexpression does not match. The "ALL" matches exactly when each of the subexpressions matches and "ANY" when at least one matches.

All the examples here is just the JSON representing the ACL, nicely formatted and split across lines. They are out of any surrounding context. This is similar to what you'd get from config show\_json called on the entry containing the ACL.

In the first example, the ACL accepts queries from two known hosts. Each host has an IP addresses (both IPv4 and IPv6) and a TSIG key. Other queries are politely rejected. The last entry in the list has no conditions — making it match any query.

[
  {
    "from": ["192.0.2.1", "2001:db8::1"],
    "key": "first.key",
    "action": "ACCEPT"
  },
  {
    "from": ["192.0.2.2", "2001:db8::2"],
    "key": "second.key",
    "action": "ACCEPT"
  },
  {
    "action": "REJECT"
  }
]

Now we show two ways to accept only the queries from private ranges. This is the same as rejecting anything that is outside.

[
  {
    "from": [
      "10.0.0.0/8",
      "172.16.0.0/12",
      "192.168.0.0/16",
      "fc00::/7"
    ],
    "action": "ACCEPT"
  },
  {
    "action": "REJECT"
  }
]

[
  {
    "NOT": {
       "ANY": [
	 {"from": "10.0.0.0/8"},
	 {"from": "172.16.0.0/12"},
	 {"from": "192.168.0.0/16"},
	 {"from": "fc00::/7"}
       ]
    },
    "action": "REJECT"
  },
  {
    "action": "ACCEPT"
  }
]

Currently, bundyctl has hard time coping with the variable nature of the ACL syntax. This technical limitation makes it impossible to edit parts of the entries. You need to set the whole entry at once, providing the whole JSON value.

This limitation is planned to be solved soon at least partially.

You'd do something like this to create the second example. Note that the whole JSON must be on a single line.

> config add somewhere/acl
> config set somewhere/acl[0] { "from": [ "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "fc00::/7" ], "action": "ACCEPT" }
> config add somewhere/acl
> config set somewhere/acl[1] { "action": "REJECT" }
> config commit

The configuration is quite powerful, but that includes a lot of space for mistakes. You could turn off the bundy-cmdctl, but then you couldn't change it back the usual way, as it would require it to be running (you would have to find and edit the configuration directly). Also, some modules might have dependencies: bundy-stats-httpd needs bundy-stats, bundy-xfrout needs bundy-auth to be running, etc.

In short, you should think twice before disabling something here.

It is possible to start some components multiple times (currently bundy-auth and bundy-resolver). You might want to do that to gain more performance (each one uses only single core). Just put multiple entries under different names, like this, with the same config:

> config add Init/components bundy-resolver-2
> config set Init/components/bundy-resolver-2/special resolver
> config set Init/components/bundy-resolver-2/kind needed
> config commit

However, this is work in progress and the support is not yet complete. For example, each resolver will have its own cache, each authoritative server will keep its own copy of in-memory data and there could be problems with locking the sqlite database, if used. The configuration might be changed to something more convenient in future. Other components don't expect such a situation, so it would probably not do what you want. Such support is yet to be implemented.

The running processes started by bundy-init may be listed by running Init show_processes using bundyctl.

In the current release, bundy-auth can serve data from a SQLite3 data source backend and from master files. Upcoming versions will be able to use multiple different data sources, such as MySQL and Berkeley DB.

The configuration is located in data\_sources/classes. Each item there represents one RR class and a list used to answer queries for that class. The default contains two classes. The CH class contains a built-in data source — one that serves things like “AUTHORS.Bundy.”. The IN class contains single SQLite3 data source with database file located at /usr/local/var/bundy/zone.sqlite3.

Each data source has several options. The first one is type, which specifies the type of data source to use. Valid types include the ones listed below, but Bundy uses dynamically loaded modules for them, so there may be more in your case. This option is mandatory.

Another option is params. This option is type specific; it holds different data depending on the type above. Also, depending on the type, it could be possible to omit it.

There are two options related to the so-called cache. If you enable cache, zone data from the data source are loaded into memory. Then, when answering a query, bundy-auth looks into the memory only instead of the data source, which speeds answering up. The first option is cache-enable, a boolean value turning the cache on and off (off is the default). The second one, cache-zones, is a list of zone origins to load into in-memory.

As mentioned, the type used by default is “sqlite3”. It has single configuration option inside params — database_file, which contains the path to the SQLite3 file containing the data.

Another type is called “MasterFiles”. This one is slightly special. The data are stored in RFC1034 master files. Because answering directly from them would be impractical, this type mandates the cache to be enabled. Also, the list of zones (cache-zones) should be omitted. The params is a dictionary mapping from zone origins to the files they reside in.

As this is one of the more complex configurations of Bundy, we show some examples. They all assume they start with default configuration.

First, let's disable the built-in data source (“VERSION.Bundy” and friends). As it is the only data source in the CH class, we can remove the whole class.

> config remove data_sources/classes CH
> config commit

Another one, let's say our default data source contains zones “example.org.” and “example.net.”. We want them to be served from memory to make the answering faster.

> config set data_sources/classes/IN[0]/cache-enable true
> config add data_sources/classes/IN[0]/cache-zones example.org.
> config add data_sources/classes/IN[0]/cache-zones example.net.
> config commit

Now every time the zone in the data source is changed by the operator, the authoritative server needs to be told to reload it, by

> Auth loadzone example.org

You don't need to do this when the zone is modified by bundy-xfrin; it does so automatically.

Now, the last example is when there are master files we want to serve in addition to whatever is inside the SQLite3 database.

> config add data_sources/classes/IN
> config set data_sources/classes/IN[1]/type MasterFiles
> config set data_sources/classes/IN[1]/cache-enable true
> config set data_sources/classes/IN[1]/params { "example.org": "/path/to/example.org", "example.com": "/path/to/example.com" }
> config commit

Unfortunately, due to current technical limitations, the params must be set as one JSON blob. To reload a zone, use the same Auth loadzone command as above.

Initially, a map value has to be set, but this value may be an empty map. After that, key/value pairs can be added with config add and keys can be removed with config remove. The initial value may be an empty map, but it has to be set before zones are added or removed.

> config set data_sources/classes/IN[1]/params {}
> config add data_sources/classes/IN[1]/params another.example.org /path/to/another.example.org
> config add data_sources/classes/IN[1]/params another.example.com /path/to/another.example.com
> config remove data_sources/classes/IN[1]/params another.example.org
> config commit

There's also Auth/database_file configuration variable, pointing to a SQLite3 database file. This is no longer used by bundy-auth, but it is left in place for now, since other modules use it. Once bundy-zonemgr, bundy-xfrout and bundy-ddns are ported to the new configuration, this will disappear. But for now, make sure that if you use any of these modules, the new and old configuration correspond. The defaults are consistent, so unless you tweaked either the new or the old configuration, you're good.

Bundy includes a zone file named static.zone in the CH (Chaos) class for providing information about the server via the AUTHORS.Bundy and VERSION.Bundy TXT records. By default, this Bundy zone is configured and its records are served.

If you have removed this zone from the configuration (e.g., by using the commands in the previous section to disable the "built-in data source"), here is how you can add it back to serve the zones in the static.zone file.

First, add the CH class if it doesn't exist:

> config add data_sources/classes CH
> config commit

Then, add a data source of type MasterFiles in the CH class to serve the zones in static.zone:

> config add data_sources/classes/CH
> config set data_sources/classes/CH[0]/type MasterFiles
> config set data_sources/classes/CH[0]/cache-enable true
> config set data_sources/classes/CH[0]/params {"Bundy": "/usr/local/bundy/share/bundy/static.zone"}
> config commit

Then, lookup the static data from static.zone to test it (assuming your authoritative server is running on localhost):

> dig @localhost -c CH -t TXT version.bind
> dig @localhost -c CH -t TXT authors.bind

In the current release, only the SQLite3 back end is used by bundy-loadzone. Multiple zones are stored in a single SQLite3 zone database.

If you reload a zone already existing in the database, all records from that prior zone disappear and a whole new set appears.

There is a plan to revise overall zone management configuration (which are primary and secondary zones, which data source they are stored, etc) so it can be configured more consistently and in a unified way among various Bundy modules. When it's done, part or all of the initial configuration setup described in this section may be deprecated.

There used to be a boolean configuration item named use_ixfr. It was deprecated for the finer control described above. The request_ixfr item should be used instead.

Access control (such as allowing notifies) is not yet provided. The primary/secondary service is not yet complete.

The following example shows using bundyctl to configure the server to be a secondary for the example zone:

> config add Zonemgr/secondary_zones
> config set Zonemgr/secondary_zones[0]/name "example.com"
> config commit

If the zone does not exist in the data source already (i.e. no SOA record for it), bundy-zonemgr will automatically tell bundy-xfrin to transfer the zone in.

The way to configure data sources is now being revised. Configuration on the data source for DDNS will be very likely to be changed in a backward incompatible manner in a near future version.

In general, if something goes wrong regarding the dependency described above, bundy-ddns will log the related event at the warning or error level. It's advisable to check the log message when you first enable DDNS or if it doesn't work as you expect to see if there's any warning or error log message.

Next, to enable the DDNS service, bundy-ddns needs to be explicitly configured to run. It can be done by using the bundyctl utility. For example:

> config add Init/components bundy-ddns
> config set Init/components/bundy-ddns/address DDNS
> config set Init/components/bundy-ddns/kind dispensable
> config commit

In theory kind could be omitted because "dispensable" is its default. But there's some peculiar behavior (which should be a bug and should be fixed eventually; see Trac ticket #2064) with bundyctl and you'll still need to specify that explicitly. Likewise, address may look unnecessary because bundy-ddns would start and work without specifying it. But for it to shutdown gracefully this parameter should also be specified.

The bundy-ddns component accepts an ACL rule that just allows updates from a specific IP address (i.e., without requiring TSIG), but this is highly discouraged (remember that requests can be made over UDP and spoofing the source address of a UDP packet is often pretty easy). Unless you know what you are doing and that you can accept its consequence, any update ACL rule that allows updates should have a TSIG key in its constraints.

Currently update ACL can only control updates per zone basis; it's not possible to specify access control with higher granularity such as for particular domain names or specific types of RRs.

Contrary to what RFC 2136 (literally) specifies, bundy-ddns checks the update ACL before checking the prerequisites of the update request. This is a deliberate implementation decision. This counter intuitive specification has been repeatedly discussed among implementers and in the IETF, and it is now widely agreed that it does not make sense to strictly follow that part of RFC. One known specific bad result of following the RFC is that it could leak information about which name or record exists or does not exist in the zone as a result of prerequisite checks even if a zone is somehow configured to reject normal queries from arbitrary clients. There have been other troubles that could have been avoided if the ACL could be checked before the prerequisite check.

Install MySQL according to the instructions for your system. The client development libraries must be installed.

Build and install Bundy as described in Chapter 3, Installation, with the following modification: to enable the MySQL database code, at the "configure" step (see Section 3.4.3, “Configure before the build”), specify the location of the MySQL configuration program "mysql\_config" with the "–with-dhcp-mysql" switch, i.e.

./configure [other-options] --with-dhcp-mysql

…if MySQL was installed in the default location, or:

./configure [other-options] --with-dhcp-mysql=path-to-mysql_config

…if not.

The next task is to create both the lease database and the user under which the servers will access it. A number of steps are required:

1. Log into MySQL as "root":

$ mysql -u root -p
Enter password:
   :
mysql>

1. Create the database:

mysql> CREATE DATABASE database-name;

… database-name is the name you have chosen for the database.

1. Create the database tables:

mysql> CONNECT database-name;
mysql> SOURCE path-to-bundy/share/bundy/dhcpdb_create.mysql

1. Create the user under which Bundy will access the database (and

give it a password), then grant it access to the database tables:

mysql> CREATE USER 'user-name'@'localhost' IDENTIFIED BY 'password';
mysql> GRANT ALL ON database-name.* TO 'user-name'@'localhost';

1. Exit MySQL:

mysql> quit
Bye
$

Install PostgreSQL according to the instructions for your system. The client development libraries must be installed. Client development libraries are often packaged as "libpq".

Build and install Bundy as described in Chapter 3, Installation, with the following modification: to enable the PostgreSQL database code, at the "configure" step (see Section 3.4.3, “Configure before the build”), specify the location of the PostgreSQL configuration program "pg\_config" with the "–with-dhcp-pgsql" switch, i.e.

./configure [other-options] --with-dhcp-pgsql

…if Postgresql was installed in the default location, or:

./configure [other-options] --with-dhcp-pgsql=path-to-pg_config

…if not.

The next task is to create both the lease database and the user under which the servers will access it. A number of steps are required:

1. Log into PostgreSQL as "root":

$ sudo -u postgres psql postgres
Enter password:
   :
postgres=#

1. Create the database:

postgres=# CREATE DATABASE database-name;
CREATE DATABASE
postgres=#

… database-name is the name you have chosen for the database.

1. Create the user under which Kea will access the database (and give it

a password), then grant it access to the database:

postgres=# CREATE USER user-name WITH PASSWORD 'password';
CREATE ROLE
postgres=#
postgres=# GRANT ALL PRIVILEGES ON DATABASE database-name TO user-name;
GRANT
postgres=#

1. Exit PostgreSQL:

postgres=# \q
Bye
$

1. Create the database tables using the new user's credentials. After

entering the following command, you will be prompted for the new user's password. When the command completes you will be returned to the shell prompt. You should see output similiar to following:

$ psql -d database-name -U user-name -f path-to-bundy/share/bundy/dhcpdb_create.pgsql
Password for user user-name:
CREATE TABLE
CREATE INDEX
CREATE INDEX
CREATE TABLE
CREATE INDEX
CREATE TABLE
START TRANSACTION
INSERT 0 1
INSERT 0 1
INSERT 0 1
COMMIT
CREATE TABLE
START TRANSACTION
INSERT 0 1
COMMIT
$

If instead you encounter an error such as shown below:

psql: FATAL:  no pg_hba.conf entry for host "[local]", user "user-name", database "database-name", SSL off

This indicates that the Postgresql configuration needs to be modified. Kea uses password authentication when connecting to the database and must have the appropriate entries added to Posgresql's pg\_hba.conf file. This file is normally located in the primary data directory for your Postgresql server. The precise path may vary but the default location for Postgres 9.3 on Centos 6.5 is: /var/lib/pgsql/9.3/data/pg_hba.conf. Assuming Kea is running on the same host as Postgresql, adding lines similiar to following should be sufficient to provide password-authenticated access to Kea's database:

local   database-name    user-name                                 password
host    database-name    user-name          127.0.0.1/32           password
host    database-name    user-name          ::1/128                password

Please consult your PostgreSQL user manual before making these changes as they may expose your other databases that you run on the same system.

The server is able to store lease data in different repositories. Larger deployments may elect to store leases in a database. Section 17.2.2, “Database Configuration” describes one way to do it. By default, the server will use a CSV file rather than a database to store lease information. One of the advantages of using a file is that it eliminates dependency on third party database software.

The configuration of the file backend (Memfile) is controlled through the Dhcp4/lease-database parameters. When default parameters are used, the Memfile backend will write leases to a disk in the [bundy-install-dir]/var/bundy/kea-leases4.csv.

It is possible to alter the default location of the lease file. The following configuration:

> config set Dhcp4/lease-database/type "memfile"
> config set Dhcp4/lease-database/persist true
> config set Dhcp4/lease-database/name "/tmp/kea-leases4.csv"
> config commit

will change the default location of the lease file to /tmp/kea-leases4.csv.

The "persist" parameter controls whether the leases are written to disk. It is strongly recommended that this parameter is set to "true" at all times during the normal operation of the server

All leases issued by the server are stored in the lease database. Currently there are 3 database backends available: MySQL, PostgreSQL and memfile. ^{[1]}, and so the server must be configured to access the correct database with the appropriate credentials.

Database access information must be configured for the DHCPv4 server, even if it has already been configured for the DHCPv6 server. The servers store their information independently, so each server can use a separate database or both servers can use the same database.

Database configuration is controlled through the Dhcp4/lease-database parameters. The type of the database must be set to "mysql", "postgresql" or "memfile":

> config set Dhcp4/lease-database/type "mysql"

Next, the name of the database is to hold the leases must be set: this is the name used when the lease database was created (see Section 16.1.2, “Create MySQL Database and Kea User” or Section 16.1.4, “Create PostgreSQL Database and Kea User”).

> config set Dhcp4/lease-database/name "database-name"

If the database is located on a different system to the DHCPv4 server, the database host name must also be specified (although note that this configuration may have a severe impact on server performance):

> config set Dhcp4/lease-database/host "remote-host-name"

The usual state of affairs will be to have the database on the same machine as the DHCPv4 server. In this case, set the value to the empty string (this is the default):

> config set Dhcp4/lease-database/host ""

Finally, the credentials of the account under which the server will access the database should be set:

> config set Dhcp4/lease-database/user "user-name"
> config set Dhcp4/lease-database/password "password"

If there is no password to the account, set the password to the empty string "". (This is also the default.)

The password is echoed when entered and is stored in clear text in the Bundy configuration database. Improved password security will be added in a future version of Bundy DHCP

When DHCPv4 server starts up, by default it will listen to the DHCP traffic and respond to it on all interfaces detected during startup. However, in many cases it is desired to configure the server to listen and respond on selected interfaces only. The sample commands in this section show how to make interface selection using bundyctl.

The default configuration can be presented with the following command:

> config show Dhcp4/interfaces
Dhcp4/interfaces[0] "*" string

An asterisk sign plays a role of the wildcard and means "listen on all interfaces".

In order to override the default configuration, the existing entry can be replaced with the actual interface name:

> config set Dhcp4/interfaces[0] eth1
> config commit

Other interface names can be added on one-by-one basis:

> config add Dhcp4/interfaces eth2
> config commit

Configuration will now contain two interfaces which can be presented as follows:

> config show Dhcp4/interfaces
Dhcp4/interfaces[0] "eth1"  string
Dhcp4/interfaces[1] "eth2"  string

When configuration gets committed, the server will start to listen on eth1 and eth2 interfaces only.

It is possible to use wildcard interface name (asterisk) concurrently with explicit interface names:

> config add Dhcp4/interfaces *
> config commit

This will result in the following configuration:

> config show Dhcp4/interfaces
Dhcp4/interfaces[0] "eth1"  string
Dhcp4/interfaces[1] "eth2"  string
Dhcp4/interfaces[2] "*" string

The presence of the wildcard name implies that server will listen on all interfaces. In order to fall back to the previous configuration when server listens on eth1 and eth2:

> config remove Dhcp4/interfaces[2]
> config commit

Subnet identifier is a unique number associated with a particular subnet. In principle, it is used to associate clients' leases with respective subnets. When subnet identifier is not specified for a subnet being configured, it will be automatically assigned by the configuration mechanism. The identifiers are assigned from 1 and are monotonically increased for each subsequent subnet: 1, 2, 3 ….

If there are multiple subnets configured with auto-generated identifiers and one of them is removed, the subnet identifiers may be renumbered. For example: if there are 4 subnets and 3rd is removed the last subnet will be assigned identifier that the 3rd subnet had before removal. As a result, the leases stored in the lease database for subnet 3 are now associated with the subnet 4, which may have unexpected consequences. In the future it is planned to implement the mechanism to preserve auto-generated subnet ids upon removal of one of the subnets. Currently, the only remedy for this issue is to manually specify the unique subnet identifier for each subnet.

The following configuration:

> config add Dhcp4/subnet4
> config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24"
> config set Dhcp4/subnet4[0]/id 1024
> config commit

will assign the arbitrary subnet identifier to the newly configured subnet. This identifier will not change for this subnet until "id" parameter is removed or set to 0. The value of 0 forces auto-generation of subnet identifier.

The essential role of DHCPv4 server is address assignment. The server has to be configured with at least one subnet and one pool of dynamic addresses to be managed. For example, assume that the server is connected to a network segment that uses the 192.0.2.0/24 prefix. The Administrator of that network has decided that addresses from range 192.0.2.10 to 192.0.2.20 are going to be managed by the Dhcp4 server. Such a configuration can be achieved in the following way:

> config add Dhcp4/subnet4
> config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24"
> config set Dhcp4/subnet4[0]/pool [ "192.0.2.10 - 192.0.2.20" ]
> config commit

Note that subnet is defined as a simple string, but the pool parameter is actually a list of pools: for this reason, the pool definition is enclosed in square brackets, even though only one range of addresses is specified.

It is possible to define more than one pool in a subnet: continuing the previous example, further assume that 192.0.2.64/26 should be also be managed by the server. It could be written as 192.0.2.64 to 192.0.2.127. Alternatively, it can be expressed more simply as 192.0.2.64/26. Both formats are supported by Dhcp4 and can be mixed in the pool list. For example, one could define the following pools:

> config set Dhcp4/subnet4[0]/pool [ "192.0.2.10-192.0.2.20", "192.0.2.64/26" ]
> config commit

The number of pools is not limited, but for performance reasons it is recommended to use as few as possible. Space and tabulations in pool definitions are ignored, so spaces before and after hyphen are optional. They can be used to improve readability.

The server may be configured to serve more than one subnet. To add a second subnet, use a command similar to the following:

> config add Dhcp4/subnet4
> config set Dhcp4/subnet4[1]/subnet "192.0.3.0/24"
> config set Dhcp4/subnet4[1]/pool [ "192.0.3.0/24" ]
> config commit

Arrays are counted from 0. subnet¹ refers to the subnet defined in the previous example. The config add Dhcp4/subnet4 command adds another (second) subnet. It can be referred to as Dhcp4/subnet4². In this example, we allow server to dynamically assign all addresses available in the whole subnet.

When configuring a DHCPv4 server using prefix/length notation, please pay attention to the boundary values. When specifying that the server should use a given pool, it will be able to allocate also first (typically network address) and the last (typically broadcast address) address from that pool. In the aforementioned example of pool 192.0.3.0/24, both 192.0.3.0 and 192.0.3.255 addresses may be assigned as well. This may be invalid in some network configurations. If you want to avoid this, please use the "min-max" notation.

One of the major features of DHCPv4 server is to provide configuration options to clients. Although there are several options that require special behavior, most options are sent by the server only if the client explicitly requested them. The following example shows how to configure DNS servers, which is one of the most frequently used options. Options specified in this way are considered global and apply to all configured subnets.

> config add Dhcp4/option-data
> config set Dhcp4/option-data[0]/name "domain-name-servers"
> config set Dhcp4/option-data[0]/code 6
> config set Dhcp4/option-data[0]/space "dhcp4"
> config set Dhcp4/option-data[0]/csv-format true
> config set Dhcp4/option-data[0]/data "192.0.3.1, 192.0.3.2"
> config commit

The first line creates new entry in option-data table. It contains information on all global options that the server is supposed to configure in all subnets. The second line specifies option name. For a complete list of currently supported names, see Table 17.1, “List of standard DHCPv4 options” below. The third line specifies option code, which must match one of the values from that list. Line 4 specifies option space, which must always be set to "dhcp4" as these are standard DHCPv4 options. For other option spaces, including custom option spaces, see Section 17.2.9, “Nested DHCPv4 options (custom option spaces)”. The fifth 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 a normal text, with values separated by commas if more than one value is allowed.

Options can also be configured as hexadecimal values. If csv-format is set to false, option data must be specified as a hex string. The following commands configure the domain-name-servers option for all subnets with the following addresses: 192.0.3.1 and 192.0.3.2. Note that csv-format is set to false.

> config add Dhcp4/option-data
> config set Dhcp4/option-data[0]/name "domain-name-servers"
> config set Dhcp4/option-data[0]/code 6
> config set Dhcp4/option-data[0]/space "dhcp4"
> config set Dhcp4/option-data[0]/csv-format false
> config set Dhcp4/option-data[0]/data "C0 00 03 01 C0 00 03 02"
> config commit

It is possible to override options on a per-subnet basis. If clients connected to most of your subnets are expected to get the same values of a given option, you should use global options: you can then override specific values for a small number of subnets. On the other hand, if you use different values in each subnet, it does not make sense to specify global option values (Dhcp4/option-data), rather you should set only subnet-specific values (Dhcp4/subnet[X]/option-data[Y]).

The following commands override the global DNS servers option for a particular subnet, setting a single DNS server with address 192.0.2.3.

> config add Dhcp4/subnet4[0]/option-data
> config set Dhcp4/subnet4[0]/option-data[0]/name "domain-name-servers"
> config set Dhcp4/subnet4[0]/option-data[0]/code 6
> config set Dhcp4/subnet4[0]/option-data[0]/space "dhcp4"
> config set Dhcp4/subnet4[0]/option-data[0]/csv-format true
> config set Dhcp4/subnet4[0]/option-data[0]/data "192.0.2.3"
> config commit

In a future version of Kea, it will not be necessary to specify the option code, space and csv-format fields as they will be set automatically.

The currently supported standard DHCPv4 options are listed in Table 17.1, “List of standard DHCPv4 options” and Table 17.2, “List of standard DHCPv4 options (continued)”. 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 the various types is given in Table 17.3, “List of standard DHCP option types”.

Some options are designated as arrays, which means that more than one value is allowed in such an option. For example the option time-servers allows the specification of more than one IPv4 address, so allowing clients to obtain the the addresses of multiple NTP servers.

The Section 17.2.7, “Custom DHCPv4 options” describes the configuration syntax to create custom option definitions (formats). It is generally not allowed to create custom definitions for standard options, even if the definition being created matches the actual option format defined in the RFCs. There is an exception from this rule for standard options for which Kea does not provide a definition yet. In order to use such options, a server administrator must create a definition as described in Section 17.2.7, “Custom DHCPv4 options” in the 'dhcp4' option space. This definition should match the option format described in the relevant RFC but configuration mechanism would allow any option format as it has no means to validate it at the moment.

Table 17.1. List of standard DHCPv4 options

Table 17.2. List of standard DHCPv4 options (continued)

Table 17.3. List of standard DHCP option types

It is also possible to define options other than the standard ones. Assume that we want to define a new DHCPv4 option called "foo" which will have code 222 and will convey a single unsigned 32 bit integer value. We can define such an option by using the following commands:

> config add Dhcp4/option-def
> config set Dhcp4/option-def[0]/name "foo"
> config set Dhcp4/option-def[0]/code 222
> config set Dhcp4/option-def[0]/type "uint32"
> config set Dhcp4/option-def[0]/array false
> config set Dhcp4/option-def[0]/record-types ""
> config set Dhcp4/option-def[0]/space "dhcp4"
> config set Dhcp4/option-def[0]/encapsulate ""
> config commit

The "false" value of the "array" parameter determines that the option does NOT comprise an array of "uint32" values but rather a single value. Two other parameters have been left blank: "record-types" and "encapsulate". The former specifies the comma separated list of option data fields if the option comprises a record of data fields. The "record-fields" value should be non-empty if the "type" is set to "record". Otherwise it must be left blank. The latter parameter specifies the name of the option space being encapsulated by the particular option. If the particular option does not encapsulate any option space it should be left blank. Note that the above set of comments define the format of the new option and do not set its values.

In the current release the default values are not propagated to the parser when the new configuration is being set. Therefore, all parameters must be specified at all times, even if their values are left blank.

Once the new option format is defined, its value is set in the same way as for a standard option. For example the following commands set a global value that applies to all subnets.

> config add Dhcp4/option-data
> config set Dhcp4/option-data[0]/name "foo"
> config set Dhcp4/option-data[0]/code 222
> config set Dhcp4/option-data[0]/space "dhcp4"
> config set Dhcp4/option-data[0]/csv-format true
> config set Dhcp4/option-data[0]/data "12345"
> config commit

New options can take more complex forms than simple use of primitives (uint8, string, ipv4-address etc): it is possible to define an option comprising a number of existing primitives.

Assume we want to define a new option that will consist of an IPv4 address, followed by unsigned 16 bit integer, followed by a boolean value, followed by a text string. Such an option could be defined in the following way:

> config add Dhcp4/option-def
> config set Dhcp4/option-def[0]/name "bar"
> config set Dhcp4/option-def[0]/code 223
> config set Dhcp4/option-def[0]/space "dhcp4"
> config set Dhcp4/option-def[0]/type "record"
> config set Dhcp4/option-def[0]/array false
> config set Dhcp4/option-def[0]/record-types "ipv4-address, uint16, boolean, string"
> config set Dhcp4/option-def[0]/encapsulate ""

The "type" is set to "record" to indicate that the option contains multiple values of different types. These types are given as a comma-separated list in the "record-types" field and should be those listed in Table 17.3, “List of standard DHCP option types”.

The values of the option are set as follows:

> config add Dhcp4/option-data
> config set Dhcp4/option-data[0]/name "bar"
> config set Dhcp4/option-data[0]/space "dhcp4"
> config set Dhcp4/option-data[0]/code 223
> config set Dhcp4/option-data[0]/csv-format true
> config set Dhcp4/option-data[0]/data "192.0.2.100, 123, true, Hello World"
> config commit

"csv-format" is set "true" to indicate that the "data" field comprises a command-separated list of values. The values in the "data" must correspond to the types set in the "record-types" field of the option definition.

It is recommended that boolean values are specified using "true" and "false" strings. This helps to prevent errors when typing multiple comma separated values, as it make it easier to identify the type of the value being typed, and compare it with the order of data fields. Nevetheless, it is possible to use integer values: "1" and "0", instead of "true" and "false" accordingly. If other integer value is specified, the configuration is rejected.

Currently there are three option spaces defined: dhcp4 (to be used in DHCPv4 daemon) and dhcp6 (for the DHCPv6 daemon); there is also vendor-encapsulated-options-space, which is empty by default, but options can be defined in it. Those options are called vendor-specific information options. The following examples show how to define an option "foo" with code 1 that consists of an IPv4 address, an unsigned 16 bit integer and a string. The "foo" option is conveyed in a vendor specific information option.

The first step is to define the format of the option:

> config add Dhcp4/option-def
> config set Dhcp4/option-def[0]/name "foo"
> config set Dhcp4/option-def[0]/code 1
> config set Dhcp4/option-def[0]/space "vendor-encapsulated-options-space"
> config set Dhcp4/option-def[0]/type "record"
> config set Dhcp4/option-def[0]/array false
> config set Dhcp4/option-def[0]/record-types "ipv4-address, uint16, string"
> config set Dhcp4/option-def[0]/encapsulates ""
> config commit

(Note that the option space is set to "vendor-encapsulated-options-space".) Once the option format is defined, the next step is to define actual values for that option:

> config add Dhcp4/option-data
> config set Dhcp4/option-data[0]/name "foo"
> config set Dhcp4/option-data[0]/space "vendor-encapsulated-options-space"
> config set Dhcp4/option-data[0]/code 1
> config set Dhcp4/option-data[0]/csv-format true
> config set Dhcp4/option-data[0]/data "192.0.2.3, 123, Hello World"
> config commit

We also set up a dummy value for vendor-opts, the option that conveys our sub-option "foo". This is required else the option will not be included in messages sent to the client.

> config add Dhcp4/option-data
> config set Dhcp4/option-data[1]/name "vendor-encapsulated-options"
> config set Dhcp4/option-data[1]/space "dhcp4"
> config set Dhcp4/option-data[1]/code 43
> config set Dhcp4/option-data[1]/csv-format false
> config set Dhcp4/option-data[1]/data ""
> config commit

With this version of Bundy, the "vendor-encapsulated-options" option must be specified in the configuration although it has no configurable parameters. If it is not specified, the server will assume that it is not configured and will not send it to a client. In the future there will be no need to include this option in the configuration.

It is sometimes useful to define completely new option space. This is the case when user creates new option in the standard option space ("dhcp4 or "dhcp6") and wants this option to convey sub-options. Thanks to being in the separate space, sub-option codes will have a separate numbering scheme and may overlap with codes of standard options.

Note that creation of a new option space when defining sub-options for a standard option is not required, because it is created by default if the standard option is meant to convey any sub-options (see Section 17.2.8, “DHCPv4 vendor specific options”).

Assume that we want to have a DHCPv4 option called "container" with code 222 that conveys two sub-options with codes 1 and 2. First we need to define the new sub-options:

> config add Dhcp4/option-def
> config set Dhcp4/option-def[0]/name "subopt1"
> config set Dhcp4/option-def[0]/code 1
> config set Dhcp4/option-def[0]/space "isc"
> config set Dhcp4/option-def[0]/type "ipv4-address"
> config set Dhcp4/option-def[0]/record-types ""
> config set Dhcp4/option-def[0]/array false
> config set Dhcp4/option-def[0]/encapsulate ""
> config commit

> config add Dhcp4/option-def
> config set Dhcp4/option-def[1]/name "subopt2"
> config set Dhcp4/option-def[1]/code 2
> config set Dhcp4/option-def[1]/space "isc"
> config set Dhcp4/option-def[1]/type "string"
> config set Dhcp4/option-def[1]/record-types ""
> config set Dhcp4/option-def[1]/array false
> config set Dhcp4/option-def[1]/encapsulate ""
> config commit

Note that we have defined the options to belong to a new option space (in this case, "isc").

The next step is to define a regular DHCPv4 option with our desired code and specify that it should include options from the new option space:

> add Dhcp4/option-def
> set Dhcp4/option-def[2]/name "container"
> set Dhcp4/option-def[2]/code 222
> set Dhcp4/option-def[2]/space "dhcp4"
> set Dhcp4/option-def[2]/type "empty"
> set Dhcp4/option-def[2]/array false
> set Dhcp4/option-def[2]/record-types ""
> set Dhcp4/option-def[2]/encapsulate "isc"
> commit

The name of the option space in which the sub-options are defined is set in the "encapsulate" field. The "type" field is set to "empty" to indicate that this option does not carry any data other than sub-options.

Finally, we can set values for the new options:

> config add Dhcp4/option-data
> config set Dhcp4/option-data[0]/name "subopt1"
> config set Dhcp4/option-data[0]/space "isc"
> config set Dhcp4/option-data[0]/code 1
> config set Dhcp4/option-data[0]/csv-format true
> config set Dhcp4/option-data[0]/data "192.0.2.3"
> config commit

> config add Dhcp4/option-data
> config set Dhcp4/option-data[1]/name "subopt2"
> config set Dhcp4/option-data[1]/space "isc"
> config set Dhcp4/option-data[1]/code 2
> config set Dhcp4/option-data[1]/csv-format true
> config set Dhcp4/option-data[1]/data "Hello world"
> config commit

> config add Dhcp4/option-data
> config set Dhcp4/option-data[2]/name "container"
> config set Dhcp4/option-data[2]/space "dhcp4"
> config set Dhcp4/option-data[2]/code 222
> config set Dhcp4/option-data[2]/csv-format true
> config set Dhcp4/option-data[2]/data ""
> config commit

Even though the "container" option does not carry any data except sub-options, the "data" field must be explicitly set to an empty value. This is required because in the current version of Bundy DHCP, the default configuration values are not propagated to the configuration parsers: if the "data" is not set the parser will assume that this parameter is not specified and an error will be reported.

Note that it is possible to create an option which carries some data in addition to the sub-options defined in the encapsulated option space. For example, if the "container" option from the previous example was required to carry an uint16 value as well as the sub-options, the "type" value would have to be set to "uint16" in the option definition. (Such an option would then have the following data structure: DHCP header, uint16 value, sub-options.) The value specified with the "data" parameter - which should be a valid integer enclosed in quotes, e.g. "123" - would then be assigned to the uint16 field in the "container" option.

DHCPv4 server has been extended to support limited client classification. Although the current capability is modest, it is expected to be expanded in the future. It is envisaged that the majority of client classification extensions will be using hooks extensions.

In certain cases it is useful to differentiate between different types of clients and treat them differently. The process of doing classification is conducted in two steps. The first step is to assess incoming packet and assign it to zero or more classes. This classification is currently simple, but is expected to grow in capability soon. Currently the server checks whether incoming packet has vendor class identifier option (60). If it has, content of that option is prepended with "VENDOR\_CLASS\_" then is interpreted as a class. For example, modern cable modems will send this option with value "docsis3.0" and as a result the packet will belong to class "VENDOR\_{CLASS\docsis3}.0".

It is envisaged that the client classification will be used for changing behavior of almost any part of the DHCP message processing, including assigning leases from different pools, assigning different option (or different values of the same options) etc. For now, there are only two mechanisms that are taking advantage of client classification: specific processing for cable modems and subnet selection.

For clients that belong to the VENDOR\_{CLASS\docsis3}.0 class, the siaddr field is set to the value of next-server (if specified in a subnet). If there is boot-file-name option specified, its value is also set in the file field in the DHCPv4 packet. For eRouter1.0 class, the siaddr is always set to 0.0.0.0. That capability is expected to be moved to external hook library that will be dedicated to cable modems.

Kea can be instructed to limit access to given subnets based on class information. This is particularly useful for cases where two types of devices share the same link and are expected to be served from two different subnets. The primary use case for such a scenario is cable networks. There are two classes of devices: cable modem itself, which should be handled a lease from subnet A and all other devices behind modems that should get a lease from subnet B. That segregation is essential to prevent overly curious users from playing with their cable modems. For details on how to set up class restrictions on subnets, see Section 17.2.11, “Limiting access to IPv4 subnet to certain classes”.

In certain cases it beneficial to restrict access to certain subnets only to clients that belong to a given subnet. For details on client classes, see Section 17.2.10, “Client Classification in DHCPv4”. This is an extension of a previous example from Section 17.2.5, “Configuration of IPv4 Address Pools”. Let's assume that the server is connected to a network segment that uses the 192.0.2.0/24 prefix. The Administrator of that network has decided that addresses from range 192.0.2.10 to 192.0.2.20 are going to be managed by the Dhcp4 server. Only clients belonging to client class VENDOR\_{CLASS\docsis3}.0 are allowed to use this subnet. Such a configuration can be achieved in the following way:

> config add Dhcp4/subnet4
> config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24"
> config set Dhcp4/subnet4[0]/pool [ "192.0.2.10 - 192.0.2.20" ]
> config set Dhcp4/subnet4[0]/client-class "VENDOR_CLASS_docsis3.0"
> config commit

Care should be taken with client classification as it is easy to prevent clients that do not meet class criteria to be denied any service altogether.

As mentioned earlier, DHCPv4 can be configured to generate requests to the DHCP-DDNS server to update DNS entries. These requests are known as NameChangeRequests or NCRs. Each NCR contains the following information:

1. Whether it is a request to add (update) or remove DNS entries
2. Whether the change requests forward DNS updates (A records), reverse DNS updates (PTR records), or both.
3. The FQDN, lease address, and DHCID

The paramaters for controlling the generation of NCRs for submission to D2 are contained in the "dhcp-ddns" section of the DHCPv4 server configuration. The default values for this section appears as follows:

> config show Dhcp4/dhcp-ddns
Dhcp4/dhcp-ddns/enable-updates  true    boolean
Dhcp4/dhcp-ddns/server-ip   "127.0.0.1" string
Dhcp4/dhcp-ddns/server-port 53001   integer
Dhcp4/dhcp-ddns/ncr-protocol    "UDP"   string
Dhcp4/dhcp-ddns/ncr-format  "JSON"  string
Dhcp4/dhcp-ddns/override-no-update  false   boolean
Dhcp4/dhcp-ddns/override-client-update  false   boolean
Dhcp4/dhcp-ddns/replace-client-name false   boolean
Dhcp4/dhcp-ddns/generated-prefix    "myhost"    string
Dhcp4/dhcp-ddns/qualifying-suffix   "example.com"   string

The "enable-updates" parameter determines whether or not DHCPv4 will generate NCRs. By default, this value is false hence DDNS updates are disabled. To enable DDNS updates set this value to true:

> config set Dhcp4/dhcp-ddns/enable-updates true
> config commit

The subnet selection mechanism described in this section is based on the assumption that client classification is not used. The classification mechanism alters the way in which subnet is selected for the client, depending on the clasess that the client belongs to.

With this version of Bundy, there are a number of known limitations and problems in the DHCPv6 server. See Section 18.7, “DHCPv6 Server Limitations”.

The server is able to store lease data in different repositories. Larger deployments may elect to store leases in a database. Section 18.2.2, “Database Configuration” describes one way to do it. By default, the server will use a CSV file rather than a database to store lease information. One of the advantages of using a file is that it eliminates dependency on third party database software.

The configuration of the file backend (Memfile) is controlled through the Dhcp6/lease-database parameters. When default parameters are left, the Memfile backend will write leases to a disk in the [bundy-install-dir]/var/bundy/kea-leases6.csv.

It is possible to alter the default location of the lease file. The following configuration:

> config set Dhcp4/lease-database/type "memfile"
> config set Dhcp4/lease-database/persist true
> config set Dhcp4/lease-database/leasefile "/tmp/kea-leases6.csv"
> config commit

will change the default location of the lease file to /tmp/kea-leases6.csv.

The "persist" parameter controls whether the leases are written to disk. It is strongly recommended that this parameter is set to "true" at all times during the normal operation of the server.

All leases issued by the server are stored in the lease database. Currently there are 3 database backends available: MySQL, PostgreSQL and memfile. ^{[2]}, and so the server must be configured to access the correct database with the appropriate credentials.

Database access information must be configured for the DHCPv6 server, even if it has already been configured for the DHCPv4 server. The servers store their information independently, so each server can use a separate database or both servers can use the same database.

Database configuration is controlled through the Dhcp6/lease-database parameters. The type of the database must be set to "mysql", "postgresql" or "memfile":

> config set Dhcp6/lease-database/type "mysql"

Next, the name of the database is to hold the leases must be set: this is the name used when the lease database was created (see Section 16.1.2, “Create MySQL Database and Kea User” or Section 16.1.4, “Create PostgreSQL Database and Kea User”).

> config set Dhcp6/lease-database/name "database-name"

If the database is located on a different system to the DHCPv6 server, the database host name must also be specified (although note that this configuration may have a severe impact on server performance):

> config set Dhcp6/lease-database/host "remote-host-name"

The usual state of affairs will be to have the database on the same machine as the DHCPv6 server. In this case, set the value to the empty string (this is the default):

> config set Dhcp6/lease-database/host ""

Finally, the credentials of the account under which the server will access the database should be set:

> config set Dhcp6/lease-database/user "user-name"
> config set Dhcp6/lease-database/password "password"

If there is no password to the account, set the password to the empty string "". (This is also the default.)

The password is echoed when entered and is stored in clear text in the Bundy configuration database. Improved password security will be added in a future version of Bundy DHCP

When DHCPv6 server starts up, by default it will listen to the DHCP traffic and respond to it on all interfaces detected during startup. However, in many cases it is desired to configure the server to listen and respond on selected interfaces only. The sample commands in this section show how to make interface selection using bundyctl.

The default configuration can be presented with the following command:

> config show Dhcp6/interfaces
Dhcp6/interfaces[0] "*" string

An asterisk sign plays a role of the wildcard and means "listen on all interfaces".

In order to override the default configuration, the existing entry can be replaced with the actual interface name:

> config set Dhcp6/interfaces[0] eth1
> config commit

Other interface names can be added on one-by-one basis:

> config add Dhcp6/interfaces eth2
> config commit

Configuration will now contain two interfaces which can be presented as follows:

> config show Dhcp6/interfaces
Dhcp6/interfaces[0] "eth1"  string
Dhcp6/interfaces[1] "eth2"  string

When configuration gets committed, the server will start to listen on eth1 and eth2 interfaces only.

It is possible to use wildcard interface name (asterisk) concurrently with explicit interface names:

> config add Dhcp6/interfaces *
> config commit

This will result in the following configuration:

> config show Dhcp6/interfaces
Dhcp6/interfaces[0] "eth1"  string
Dhcp6/interfaces[1] "eth2"  string
Dhcp6/interfaces[2] "*" string

The presence of the wildcard name implies that server will listen on all interfaces. In order to fall back to the previous configuration when server listens on eth1 and eth2:

> config remove Dhcp6/interfaces[2]
> config commit

Subnet identifier is a unique number associated with a particular subnet. In principle, it is used to associate clients' leases with respective subnets. When subnet identifier is not specified for a subnet being configured, it will be automatically assigned by the configuration mechanism. The identifiers are assigned from 1 and are monotonically increased for each subsequent subnet: 1, 2, 3 ….

If there are multiple subnets configured with auto-generated identifiers and one of them is removed, the subnet identifiers may be renumbered. For example: if there are 4 subnets and 3rd is removed the last subnet will be assigned identifier that the 3rd subnet had before removal. As a result, the leases stored in the lease database for subnet 3 are now associated with the subnet 4, which may have unexpected consequences. In the future it is planned to implement the mechanism to preserve auto-generated subnet ids upon removal of one of the subnets. Currently, the only remedy for this issue is to manually specify the unique subnet identifier for each subnet.

The following configuration:

> config add Dhcp6/subnet6
> config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64"
> config set Dhcp6/subnet6[0]/id 1024
> config commit

will assign the arbitrary subnet identifier to the newly configured subnet. This identifier will not change for this subnet until "id" parameter is removed or set to 0. The value of 0 forces auto-generation of subnet identifier.

When DHCPv6 server starts up, by default it listens to the DHCP traffic sent to multicast address ff02::1:2 on each interface that it is configured to listen on (see Section 18.2.3, “Interface selection”). In some cases it is useful to configure a server to handle incoming traffic sent to the global unicast addresses as well. The most common reason for that is to have relays send their traffic to the server directly. To configure server to listen on specific unicast address, a notation to specify interfaces has been extended. Interface name can be optionally followed by a slash, followed by global unicast address that server should listen on. That will be done in addition to normal link-local binding + listening on ff02::1:2 address. The sample commands listed below show how to listen on 2001:db8::1 (a global address) configured on the eth1 interface.

> config set Dhcp6/interfaces[0] eth1/2001:db8::1
> config commit

When configuration gets committed, the server will start to listen on eth1 on link-local address, mutlicast group (ff02::1:2) and 2001:db8::1.

It is possible to mix interface names, wildcards and interface name/addresses on the Dhcp6/interface list. It is not possible to specify more than one unicast address on a given interface.

Care should be taken to specify proper unicast addresses. The server will attempt to bind to those addresses specified, without any additional checks. That approach is selected on purpose, so in the software can be used to communicate over uncommon addresses if the administrator desires so.

The essential role of a DHCPv6 server is address assignment. For this, the server has to be configured with at least one subnet and one pool of dynamic addresses to be managed. For example, assume that the server is connected to a network segment that uses the 2001:db8:1::/64 prefix. The Administrator of that network has decided that addresses from range 2001:db8:1::1 to 2001:db8:1::ffff are going to be managed by the Dhcp6 server. Such a configuration can be achieved in the following way:

> config add Dhcp6/subnet6
> config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64"
> config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::0 - 2001:db8:1::ffff" ]
> config commit

Note that subnet is defined as a simple string, but the pool parameter is actually a list of pools: for this reason, the pool definition is enclosed in square brackets, even though only one range of addresses is specified.

It is possible to define more than one pool in a subnet: continuing the previous example, further assume that 2001:db8:1:0:5::/80 should be also be managed by the server. It could be written as 2001:db8:1:0:5:: to 2001:db8:1::5:ffff:ffff:ffff, but typing so many 'f's is cumbersome. It can be expressed more simply as 2001:db8:1:0:5::/80. Both formats are supported by Dhcp6 and can be mixed in the pool list. For example, one could define the following pools:

> config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::1 - 2001:db8:1::ffff", "2001:db8:1:0:5::/80" ]
> config commit

The number of pools is not limited, but for performance reasons it is recommended to use as few as possible.

The server may be configured to serve more than one subnet. To add a second subnet, use a command similar to the following:

> config add Dhcp6/subnet6
> config set Dhcp6/subnet6[1]/subnet "2001:db8:beef::/48"
> config set Dhcp6/subnet6[1]/pool [ "2001:db8:beef::/48" ]
> config commit

Arrays are counted from 0. subnet¹ refers to the subnet defined in the previous example. The config add Dhcp6/subnet6 command adds another (second) subnet. It can be referred to as Dhcp6/subnet6². In this example, we allow server to dynamically assign all addresses available in the whole subnet. Although very wasteful, it is certainly a valid configuration to dedicate the whole /48 subnet for that purpose.

When configuring a DHCPv6 server using prefix/length notation, please pay attention to the boundary values. When specifying that the server should use a given pool, it will be able to allocate also first (typically network address) address from that pool. For example for pool 2001:db8::/64 the 2001:db8:: address may be assigned as well. If you want to avoid this, please use the "min-max" notation.

Subnets may also be configured to delegate address prefixes…. A subnet may have one or more prefix delegation pools. Each pool has a prefixed address, which is specified as a prefix and a prefix length, as well as a delegated prefix length. A sample configuration is shown below:

> config add Dhcp6/subnet6
> config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64"
> config show Dhcp6/subnet6[0]
> config add Dhcp6/subnet6[0]/pd-pools
> config set Dhcp6/subnet6[0]/pd-pools[0]/prefix "2001:db8:1::"
> config set Dhcp6/subnet6[0]/pd-pools[0]/prefix-len 64
> config set Dhcp6/subnet6[0]/pd-pools[0]/delegated-len 96
> config commit

One of the major features of DHCPv6 server is to provide configuration options to clients. Although there are several options that require special behavior, most options are sent by the server only if the client explicitly requested them. The following example shows how to configure DNS servers, which is one of the most frequently used options. Numbers in the first column are added for easier reference and will not appear on screen. Options specified in this way are considered global and apply to all configured subnets.

1. > config add Dhcp6/option-data
2. > config set Dhcp6/option-data[0]/name "dns-servers"
3. > config set Dhcp6/option-data[0]/code 23
4. > config set Dhcp6/option-data[0]/space "dhcp6"
5. > config set Dhcp6/option-data[0]/csv-format true
6. > config set Dhcp6/option-data[0]/data "2001:db8::cafe, 2001:db8::babe"
7. > config commit

The first line creates new entry in option-data table. It contains information on all global options that the server is supposed to configure in all subnets. The second line specifies option name. For a complete list of currently supported names, see Table 18.1, “List of standard DHCPv6 options”. The third line specifies option code, which must match one of the values from that list. Line 4 specifies option space, which must always be set to "dhcp6" as these are standard DHCPv6 options. For other name spaces, including custom option spaces, see Section 18.2.11, “Nested DHCPv6 options (custom option spaces)”. The fifth 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 a normal text, with values separated by commas if more than one value is allowed.

Options can also be configured as hexadecimal values. If csv-format is set to false, the option data must be specified as a string of hexadecimal numbers. The following commands configure the DNS-SERVERS option for all subnets with the following addresses: 2001:db8:1::cafe and 2001:db8:1::babe.

> config add Dhcp6/option-data
> config set Dhcp6/option-data[0]/name "dns-servers"
> config set Dhcp6/option-data[0]/code 23
> config set Dhcp6/option-data[0]/space "dhcp6"
> config set Dhcp6/option-data[0]/csv-format false
> config set Dhcp6/option-data[0]/data "2001 0DB8 0001 0000 0000 0000
	0000 CAFE 2001 0DB8 0001 0000 0000 0000 0000 BABE"
> config commit

(The value for the setting of the "data" element is split across two lines in this document for clarity: when entering the command, the whole string should be entered on the same line.)

It is possible to override options on a per-subnet basis. If clients connected to most of your subnets are expected to get the same values of a given option, you should use global options: you can then override specific values for a small number of subnets. On the other hand, if you use different values in each subnet, it does not make sense to specify global option values (Dhcp6/option-data), rather you should set only subnet-specific values (Dhcp6/subnet[X]/option-data[Y]).

The following commands override the global DNS servers option for a particular subnet, setting a single DNS server with address 2001:db8:1::3.

> config add Dhcp6/subnet6[0]/option-data
> config set Dhcp6/subnet6[0]/option-data[0]/name "dns-servers"
> config set Dhcp6/subnet6[0]/option-data[0]/code 23
> config set Dhcp6/subnet6[0]/option-data[0]/space "dhcp6"
> config set Dhcp6/subnet6[0]/option-data[0]/csv-format true
> config set Dhcp6/subnet6[0]/option-data[0]/data "2001:db8:1::3"
> config commit

In future versions of Bundy DHCP, it will not be necessary to specify option code, space and csv-format fields, as those fields will be set automatically.

The currently supported standard DHCPv6 options are listed in Table 18.1, “List of standard DHCPv6 options”. 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 the various types is given in Table 17.3, “List of standard DHCP option types”.

Some options are designated as arrays, which means that more than one value is allowed in such an option. For example the option dns-servers allows the specification of more than one IPv6 address, so allowing clients to obtain the the addresses of multiple DNS servers.

The Section 18.2.9, “Custom DHCPv6 options” describes the configuration syntax to create custom option definitions (formats). It is generally not allowed to create custom definitions for standard options, even if the definition being created matches the actual option format defined in the RFCs. There is an exception from this rule for standard options for which Kea does not provide a definition yet. In order to use such options, a server administrator must create a definition as described in Section 18.2.9, “Custom DHCPv6 options” in the 'dhcp6' option space. This definition should match the option format described in the relevant RFC but configuration mechanism would allow any option format as it has no means to validate it at the moment.

Table 18.1. List of standard DHCPv6 options

It is also possible to define options other than the standard ones. Assume that we want to define a new DHCPv6 option called "foo" which will have code 100 and will convey a single unsigned 32 bit integer value. We can define such an option by using the following commands:

> config add Dhcp6/option-def
> config set Dhcp6/option-def[0]/name "foo"
> config set Dhcp6/option-def[0]/code 100
> config set Dhcp6/option-def[0]/type "uint32"
> config set Dhcp6/option-def[0]/array false
> config set Dhcp6/option-def[0]/record-types ""
> config set Dhcp6/option-def[0]/space "dhcp6"
> config set Dhcp6/option-def[0]/encapsulate ""
> config commit

The "false" value of the "array" parameter determines that the option does NOT comprise an array of "uint32" values but rather a single value. Two other parameters have been left blank: "record-types" and "encapsulate". The former specifies the comma separated list of option data fields if the option comprises a record of data fields. The "record-fields" value should be non-empty if the "type" is set to "record". Otherwise it must be left blank. The latter parameter specifies the name of the option space being encapsulated by the particular option. If the particular option does not encapsulate any option space it should be left blank. Note that the above set of comments define the format of the new option and do not set its values.

Once the new option format is defined, its value is set in the same way as for a standard option. For example the following commands set a global value that applies to all subnets.

> config add Dhcp6/option-data
> config set Dhcp6/option-data[0]/name "foo"
> config set Dhcp6/option-data[0]/code 100
> config set Dhcp6/option-data[0]/space "dhcp6"
> config set Dhcp6/option-data[0]/csv-format true
> config set Dhcp6/option-data[0]/data "12345"
> config commit

New options can take more complex forms than simple use of primitives (uint8, string, ipv6-address etc): it is possible to define an option comprising a number of existing primitives.

Assume we want to define a new option that will consist of an IPv6 address, followed by an unsigned 16 bit integer, followed by a boolean value, followed by a text string. Such an option could be defined in the following way:

> config add Dhcp6/option-def
> config set Dhcp6/option-def[0]/name "bar"
> config set Dhcp6/option-def[0]/code 101
> config set Dhcp6/option-def[0]/space "dhcp6"
> config set Dhcp6/option-def[0]/type "record"
> config set Dhcp6/option-def[0]/array false
> config set Dhcp6/option-def[0]/record-types "ipv6-address, uint16, boolean, string"
> config set Dhcp6/option-def[0]/encapsulate ""

The "type" is set to "record" to indicate that the option contains multiple values of different types. These types are given as a comma-separated list in the "record-types" field and should be those listed in Table 17.3, “List of standard DHCP option types”.

The values of the option are set as follows:

> config add Dhcp6/option-data
> config set Dhcp6/option-data[0]/name "bar"
> config set Dhcp6/option-data[0]/space "dhcp6"
> config set Dhcp6/option-data[0]/code 101
> config set Dhcp6/option-data[0]/csv-format true
> config set Dhcp6/option-data[0]/data "2001:db8:1::10, 123, false, Hello World"
> config commit

"csv-format" is set "true" to indicate that the "data" field comprises a command-separated list of values. The values in the "data" must correspond to the types set in the "record-types" field of the option definition.

It is recommended that boolean values are specified using "true" and "false" strings. This helps to prevent errors when typing multiple comma separated values, as it make it easier to identify the type of the value being typed, and compare it with the order of data fields. Nevetheless, it is possible to use integer values: "1" and "0", instead of "true" and "false" accordingly. If other integer value is specified, the configuration is rejected.

Currently there are three option spaces defined: dhcp4 (to be used in DHCPv4 daemon) and dhcp6 (for the DHCPv6 daemon); there is also vendor-opts-space, which is empty by default, but options can be defined in it. Those options are called vendor-specific information options. The following examples show how to define an option "foo" with code 1 that consists of an IPv6 address, an unsigned 16 bit integer and a string. The "foo" option is conveyed in a vendor specific information option. This option comprises a single uint32 value that is set to "12345". The sub-option "foo" follows the data field holding this value.

> config add Dhcp6/option-def
> config set Dhcp6/option-def[0]/name "foo"
> config set Dhcp6/option-def[0]/code 1
> config set Dhcp6/option-def[0]/space "vendor-opts-space"
> config set Dhcp6/option-def[0]/type "record"
> config set Dhcp6/option-def[0]/array false
> config set Dhcp6/option-def[0]/record-types "ipv6-address, uint16, string"
> config set Dhcp6/option-def[0]/encapsulates ""
> config commit

(Note that the option space is set to "vendor-opts-space".) Once the option format is defined, the next step is to define actual values for that option:

> config add Dhcp6/option-data
> config set Dhcp6/option-data[0]/name "foo"
> config set Dhcp6/option-data[0]/space "vendor-opts-space"
> config set Dhcp6/option-data[0]/code 1
> config set Dhcp6/option-data[0]/csv-format true
> config set Dhcp6/option-data[0]/data "2001:db8:1::10, 123, Hello World"
> config commit

We should also define values for the vendor-opts, that will convey our option foo.

> config add Dhcp6/option-data
> config set Dhcp6/option-data[1]/name "vendor-opts"
> config set Dhcp6/option-data[1]/space "dhcp6"
> config set Dhcp6/option-data[1]/code 17
> config set Dhcp6/option-data[1]/csv-format true
> config set Dhcp6/option-data[1]/data "12345"
> config commit

It is sometimes useful to define completely new option spaces. This is useful if the user wants his new option to convey sub-options that use separate numbering scheme, for example sub-options with codes 1 and 2. Those option codes conflict with standard DHCPv6 options, so a separate option space must be defined.

Note that it is not required to create new option space when defining sub-options for a standard option because it is by default created if the standard option is meant to convey any sub-options (see Section 18.2.10, “DHCPv6 vendor specific options”).

Assume that we want to have a DHCPv6 option called "container" with code 102 that conveys two sub-options with codes 1 and 2. First we need to define the new sub-options:

> config add Dhcp6/option-def
> config set Dhcp6/option-def[0]/name "subopt1"
> config set Dhcp6/option-def[0]/code 1
> config set Dhcp6/option-def[0]/space "isc"
> config set Dhcp6/option-def[0]/type "ipv6-address"
> config set Dhcp6/option-def[0]/record-types ""
> config set Dhcp6/option-def[0]/array false
> config set Dhcp6/option-def[0]/encapsulate ""
> config commit
> 
> config add Dhcp6/option-def
> config set Dhcp6/option-def[1]/name "subopt2"
> config set Dhcp6/option-def[1]/code 2
> config set Dhcp6/option-def[1]/space "isc"
> config set Dhcp6/option-def[1]/type "string"
> config set Dhcp6/option-def[1]/record-types ""
> config set Dhcp6/option-def[1]/array false
> config set Dhcp6/option-def[1]/encapsulate ""
> config commit

Note that we have defined the options to belong to a new option space (in this case, "isc").

The next step is to define a regular DHCPv6 option and specify that it should include options from the isc option space:

> config add Dhcp6/option-def
> config set Dhcp6/option-def[2]/name "container"
> config set Dhcp6/option-def[2]/code 102
> config set Dhcp6/option-def[2]/space "dhcp6"
> config set Dhcp6/option-def[2]/type "empty"
> config set Dhcp6/option-def[2]/array false
> config set Dhcp6/option-def[2]/record-types ""
> config set Dhcp6/option-def[2]/encapsulate "isc"
> config commit

The name of the option space in which the sub-options are defined is set in the "encapsulate" field. The "type" field is set to "empty" which imposes that this option does not carry any data other than sub-options.

Finally, we can set values for the new options:

> config add Dhcp6/option-data
> config set Dhcp6/option-data[0]/name "subopt1"
> config set Dhcp6/option-data[0]/space "isc"
> config set Dhcp6/option-data[0]/code 1
> config set Dhcp6/option-data[0]/csv-format true
> config set Dhcp6/option-data[0]/data "2001:db8::abcd"
> config commit
> 
> config add Dhcp6/option-data
> config set Dhcp6/option-data[1]/name "subopt2"
> config set Dhcp6/option-data[1]/space "isc"
> config set Dhcp6/option-data[1]/code 2
> config set Dhcp6/option-data[1]/csv-format true
> config set Dhcp6/option-data[1]/data "Hello world"
> config commit
> 
> config add Dhcp6/option-data
> config set Dhcp6/option-data[2]/name "container"
> config set Dhcp6/option-data[2]/space "dhcp6"
> config set Dhcp6/option-data[2]/code 102
> config set Dhcp6/option-data[2]/csv-format true
> config set Dhcp6/option-data[2]/data ""
> config commit

Even though the "container" option does not carry any data except sub-options, the "data" field must be explicitly set to an empty value. This is required because in the current version of Bundy DHCP, the default configuration values are not propagated to the configuration parsers: if the "data" is not set the parser will assume that this parameter is not specified and an error will be reported.

Note that it is possible to create an option which carries some data in addition to the sub-options defined in the encapsulated option space. For example, if the "container" option from the previous example was required to carry an uint16 value as well as the sub-options, the "type" value would have to be set to "uint16" in the option definition. (Such an option would then have the following data structure: DHCP header, uint16 value, sub-options.) The value specified with the "data" parameter - which should be a valid integer enclosed in quotes, e.g. "123" - would then be assigned to the uint16 field in the "container" option.

The DHCPv6 server may receive requests from local (connected to the same subnet as the server) and remote (connecting via relays) clients. As server may have many subnet configurations defined, it must select appropriate subnet for a given request.

The server can not assume which of configured subnets are local. It is possible in IPv4, where there is reasonable expectation that the server will have a (global) IPv4 address configured on the interface, and can use that information to detect whether a subnet is local or not. That assumption is not true in IPv6, as the DHCPv6 must be able to operate with having link-local addresses only. Therefore an optional "interface" parameter is available within a subnet definition to designate that a given subnet is local, i.e. reachable directly over specified interface. For example the server that is intended to serve a local subnet over eth0 may be configured as follows:

> config add Dhcp6/subnet6
> config set Dhcp6/subnet6[1]/subnet "2001:db8:beef::/48"
> config set Dhcp6/subnet6[1]/pool [ "2001:db8:beef::/48" ]
> config set Dhcp6/subnet6[1]/interface "eth0"
> config commit

A DHCPv6 server with multiple subnets defined must select the appropriate subnet when it receives a request from client. For clients connected via relays, two mechanisms are used:

The first uses the linkaddr field in the RELAY\_FORW message. The name of this field is somewhat misleading in that it does not contain a link-layer address: instead, it holds an address (typically a global address) that is used to identify a link. The DHCPv6 server checks if the address belongs to a defined subnet and, if it does, that subnet is selected for the client's request.

The second mechanism is based on interface-id options. While forwarding a client's message, relays may insert an interface-id option into the message that identifies the interface on the relay that received the message. (Some relays allow configuration of that parameter, but it is sometimes hardcoded and may range from the very simple (e.g. "vlan100") to the very cryptic: one example seen on real hardware was "ISAM144|299|ipv6|nt:vp:1:110"). The server can use this information to select the appropriate subnet. The information is also returned to the relay which then knows the interface to use to transmit the response to the client. In order for this to work successfully, the relay interface IDs must be unique within the network and the server configuration must match those values.

When configuring the DHCPv6 server, it should be noted that two similarly-named parameters can be configured for a subnet:

• "interface" defines which local network interface can be used to access a given subnet.
• "interface-id" specifies the content of the interface-id option used by relays to identify the interface on the relay to which the response packet is sent.

The two are mutually exclusive: a subnet cannot be both reachable locally (direct traffic) and via relays (remote traffic). Specifying both is a configuration error and the DHCPv6 server will refuse such a configuration.

To specify interface-id with value "vlan123", the following commands can be used:

> config add Dhcp6/subnet6
> config set Dhcp6/subnet6[0]/subnet "2001:db8:beef::/48"
> config set Dhcp6/subnet6[0]/pool [ "2001:db8:beef::/48" ]
> config set Dhcp6/subnet6[0]/interface-id "vland123"
> config commit

DHCPv6 server has been extended to support limited client classification. Although the current capability is modest, it is expected to be expanded in the future. It is envisaged that the majority of client classification extensions will be using hooks extensions.

In certain cases it is useful to differentiate between different types of clients and treat them differently. The process of doing classification is conducted in two steps. The first step is to assess incoming packet and assign it to zero or more classes. This classification is currently simple, but is expected to grow in capability soon. Currently the server checks whether incoming packet has vendor class option (16). If it has, content of that option is prepended with "VENDOR\_CLASS\_" interpreted as a class. For example, modern cable modems will send this option with value "docsis3.0" and as a result the packet will belong to class "VENDOR\_{CLASS\docsis3}.0".

It is envisaged that the client classification will be used for changing behavior of almost any part of the DHCP engine processing, including assigning leases from different pools, assigning different option (or different values of the same options) etc. For now, there is only one mechanism that is taking advantage of client classification: subnet selection.

Kea can be instructed to limit access to given subnets based on class information. This is particularly useful for cases where two types of devices share the same link and are expected to be served from two different subnets. The primary use case for such a scenario are cable networks. There are two classes of devices: cable modem itself, which should be handled a lease from subnet A and all other devices behind modems that should get a lease from subnet B. That segregation is essential to prevent overly curious users from playing with their cable modems. For details on how to set up class restrictions on subnets, see Section 18.2.15, “Limiting access to IPv6 subnet to certain classes”.

In certain cases it beneficial to restrict access to certains subnets only to clients that belong to a given subnet. For details on client classes, see Section 18.2.14, “Client Classification in DHCPv6”. This is an extension of a previous example from Section 18.2.6, “Subnet and Address Pool”. Let's assume that the server is connected to a network segment that uses the 2001:db8:1::/64 prefix. The Administrator of that network has decided that addresses from range 2001:db8:1::1 to 2001:db8:1::ffff are going to be managed by the Dhcp6 server. Only clients belonging to the eRouter1.0 client class are allowed to use that pool. Such a configuration can be achieved in the following way:

> config add Dhcp6/subnet6
> config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64"
> config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::0 - 2001:db8:1::ffff" ]
> config set Dhcp6/subnet6[0]/client-class "eRouter1.0"
> config commit

Care should be taken with client classification as it is easy to prevent clients that do not meet class criteria to be denied any service altogether.

As mentioned earlier, DHCPv6 can be configured to generate requests to the DHCP-DDNS server (referred to here as the "D2" server) to update DNS entries. These requests are known as NameChangeRequests or NCRs. Each NCR contains the following information:

1. Whether it is a request to add (update) or remove DNS entries
2. Whether the change requests forward DNS updates (AAAA records), reverse DNS updates (PTR records), or both.
3. The FQDN, lease address, and DHCID

The parameters controlling the generation of NCRs for submission to D2 are contained in the "dhcp-ddns" section of the DHCPv6 server configuration. The default values for this section appears as follows:

> config show Dhcp6/dhcp-ddns
Dhcp6/dhcp-ddns/enable-updates  true    boolean
Dhcp6/dhcp-ddns/server-ip   "127.0.0.1" string
Dhcp6/dhcp-ddns/server-port 53001   integer
Dhcp6/dhcp-ddns/ncr-protocol    "UDP"   string
Dhcp6/dhcp-ddns/ncr-format  "JSON"  string
Dhcp6/dhcp-ddns/override-no-update  false   boolean
Dhcp6/dhcp-ddns/override-client-update  false   boolean
Dhcp6/dhcp-ddns/replace-client-name false   boolean
Dhcp6/dhcp-ddns/generated-prefix    "myhost"    string
Dhcp6/dhcp-ddns/qualifying-suffix   "example.com"   string

The "enable-updates" parameter determines whether or not DHCPv6 will generate NCRs. By default, this value is false hence DDNS updates are disabled. To enable DDNS updates set this value to true as follows:

> config set Dhcp6/dhcp-ddns/enable-updates true
> config commit

Currently the interface between DHCPv6 and D2 only supports requests which update DNS entries for a single IP address. If a lease grants more than one address, DHCPv6 will create the DDNS update request for only the first of these addresses. Support for multiple address mappings may be provided in a future release.

In general, DHCPv6 will generate DDNS udpate requests when:

1. A new lease is granted in response to a DHCP REQUEST
2. An existing lease is renewed but the FQDN associated with it has changed.
3. An existing lease is released in response to a DHCP RELEASE

In the second case, lease renewal, two DDNS requests will be issued: one request to remove entries for the previous FQDN and a second request to add entries for the new FQDN. In the last case, a lease release, a single DDNS request to remove its entries will be made. The decision making involved when granting a new lease is more involved and is discussed next.

DHCPv6 will generate a DDNS update request only if the DHCP REQUEST contains the FQDN option (code 39). By default the DHCPv6 server will respect the FQDN N and S flags specified by the client as shown in the following table:

Table 18.2. Default FQDN Flag Behavior

The first row in the table above represents "client delegation". Here the DHCP client states that it intends to do the forward DNS updates and the server should do the reverese updates. By default, DHCPv6 will honor the client's wishes and generate a DDNS request to D2 to update only reverse DNS data. The parameter, "override-client-update", can be used to instruct the server to override client delegation requests. When this parameter is true, DHCPv6 will disregard requests for client delegation and generate a DDNS request to update both forward and reverse DNS data. In this case, the N-S-O flags in the server's response to the client will be 0-1-1 respectively.

(Note that the flag combination N=1, S=1 is prohibited according to RFC

1. If such a combination is received from the client, the packet will

be dropped by the DHCPv6 server.)

To override client delegation, issue the following commands:

> config set Dhcp6/dhcp-ddns/override-client-update true
> config commit

The third row in the table above describes the case in which the client requests that no DNS updates be done. The parameter, "override-no-update", can be used to instruct the server to disregard the client's wishes. When this parameter is true, DHCPv6 will generate DDNS udpate request to D2 even if the client requests no updates be done. The N-S-O flags in the server's response to the client will be 0-1-1.

To override client delegation, issue the following commands:

> config set Dhcp6/dhcp-ddns/override-no-update true
> config commit

The DHCP-DDNS server must listen for requests on a known address and port. By default, it will listen at 127.0.0.1 on port 53001. This is governed by the parameters, "ip-address" and "port". Either value may be changed using config set/commit. For example to change the server to listen at 192.168.1.10 port 900:

> config set DhcpDdns/ip_address "192.168.1.10"
> config set DhcpDdns/port 900
> config commit

The server may be configured to listen over IPv4 or IPv6, therefore ip-address may an IPv4 or IPv6 address.

When the DHCP-DDNS server is configured to listen at an address other than the loopback address (127.0.0.1 or ::1), it is possible for a malicious attacker to send bogus NameChangeRequests to it and change entries in the DNS. For this reason, addresses other than the IPv4 or IPv6 loopback addresses should only be used for testing purposes. A future version of Kea will implement authentication to guard against such attacks.

If the ip\_address and port are changed, it will be necessary to change the corresponding values in the DHCP servers' "dhcp-ddns" configuration section.

While this section may be displayed and edited using bundyctl, the use of TSIG in actual communications between D2 and DNS servers is not yet implemented.

DDNS protocol can be conducted with or without TSIG as defined in RFC

1. This configuration section allows the administrator to define the

dictionary of TSIG keys to may be used. To use TSIG when working with a specific DDNS Domain that key must be defined in the TSIG Key List and referenced by name in that domain's entry in the DDNS catalog.

As one might gather from its name, this section is a list of TSIG keys. Each key has three parameters:

• name — is a unique text label used to idenfity the this key within the list. It is this value that is used to specify which key (if any) should be used with a specific DNS server. So long as it is unique, its content is arbitrary. It cannot be blank.
• algorithm — specifies which hashing algorithm should be used with this key. This value is not currently used.
• secret — is used to specify the shared secret key code for this key. This value is not currently used.

By default, the TSIG Key list is empty:

> config show DhcpDdns/tsig_keys
DhcpDdns/tsig_keys  []  list  (default)

To create a new key in the list, one must first add a new key element:

> config add DhcpDdns/tsig_keys

Displaying the new element, reveals this:

> config show DhcpDdns/tsig_keys[0]
DhcpDdns/tsig_keys[0]/name  ""  string  (default)
DhcpDdns/tsig_keys[0]/algorithm "hmac_md5"  string  (modified)
DhcpDdns/tsig_keys[0]/secret  ""  string  (default)

Populating the key name and secret, while accepting the default value for alogorithm:

> config set DhcpDdns/tsig_keys[0]/name "key1.example.com"
> config set DhcpDdns/tsig_keys[0]/secret "123456789"
> config commit

The Forward DDNS section is used to configure D2's forward update behavior. Currently it contains a single parameter, the catalog of forward DDNS Domains:

> config show DhcpDdns/forward_ddns/
DhcpDdns/forward_ddns/ddns_domains  [] list  (default)

By default, this list is empty, which will cause the server to ignore the forward update portions of requests.

The Reverse DDNS section is used to configure D2's reverse update behavior, and the concepts are the same as for the forward DDNS section. Currently it contains a single parameter, the catalog of reverse DDNS Domains:

> config show DhcpDdns/reverse_ddns/
DhcpDdns/reverse_ddns/ddns_domains  [] list  (default)

By default, this list is empty, which will cause the server to ignore the reverse update portions of requests.

This section provides an example DHCP-DDNS server configuration based on a small example network. Let's suppose our example network has three domains, each with their own subnet.

Table 19.1. Our example network

We need to construct three forward DDNS Domains:

Table 19.2. Forward DDNS Domains Needed

As discussed earlier, FQDN to domain matching is based on the longest match. The FQDN, "myhost.four.example.com.", will match the first domain ("four.example.com") while "admin.example.com." will match the third domain ("example.com"). The FQDN, "other.example.net." will fail to match any domain and would be rejected.

The following series of commands in bundyctl will create the Forward DDNS Domains.

> config add DhcpDdns/forward_ddns/ddns_domains
> config set DhcpDdns/forward_ddns/ddns_domains[0]/name "four.example.com."
> config add DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers
> config set DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]/ip_address "172.16.1.5"
> config add DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers
> config set DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[1]/ip_address "172.16.2.5"
>
> config add DhcpDdns/forward_ddns/ddns_domains
> config set DhcpDdns/forward_ddns/ddns_domains[1]/name "six.example.com."
> config add DhcpDdns/forward_ddns/ddns_domains[1]/dns_servers
> config set DhcpDdns/forward_ddns/ddns_domains[1]/dns_servers[0]/ip_address "3001:1::50:"
>
> config add DhcpDdns/forward_ddns/ddns_domains
> config set DhcpDdns/forward_ddns/ddns_domains[2]/name "example.com."
> config add DhcpDdns/forward_ddns/ddns_domains[2]/dns_servers
> config set DhcpDdns/forward_ddns/ddns_domains[2]/dns_servers[0]/ip_address "172.16.2.5"
>
> config commit

Similarly, we need to construct the three reverse DDNS Domains:

Table 19.3. Reverse DDNS Domains Needed

An address of "192.0.2.150" will match the first domain, "2001:db8:1::10" will match the second domain, and "192.0.50.77" the third domain.

The following series of commands in bundyctl will create our Reverse DDNS Domains.

> config add DhcpDdns/reverse_ddns/ddns_domains
> config set DhcpDdns/reverse_ddns/ddns_domains[0]/name "2.0.192.in-addr.arpa."
> config add DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers
> config set DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/ip_address "172.16.1.5"
> config add DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers
> config set DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[1]/ip_address "172.16.2.5"
>
> config add DhcpDdns/reverse_ddns/ddns_domains
> config set DhcpDdns/reverse_ddns/ddns_domains[1]/name "1.0.0.0.8.d.b.0.1.0.0.2.ip6.arpa."
> config add DhcpDdns/reverse_ddns/ddns_domains[1]/dns_servers
> config set DhcpDdns/reverse_ddns/ddns_domains[1]/dns_servers[0]/ip_address "3001:1::50:"
>
> config add DhcpDdns/reverse_ddns/ddns_domains
> config set DhcpDdns/reverse_ddns/ddns_domains[2]/name "0.192.in-addr.arpa."
> config add DhcpDdns/reverse_ddns/ddns_domains[2]/dns_servers
> config set DhcpDdns/reverse_ddns/ddns_domains[2]/dns_servers[0]/ip_address "172.16.2.5"
>
> config commit

Within Bundy, a message is logged through a component called a "logger". Different parts of Bundy log messages through different loggers, and each logger can be configured independently of one another.

In the Logging module, you can specify the configuration for zero or more loggers; any that are not specified will take appropriate default values.

The three most important elements of a logger configuration are the name (the component that is generating the messages), the severity (what to log), and the output_options (where to log).

The main settings for an output option are the destination and a value called output, the meaning of which depends on the destination that is set.

Due to a limitation of the underlying logging library (log4cplus), rolling over the log files (from ".1" to ".2", etc) may show odd results: There can be multiple small files at the timing of roll over. This can happen when multiple Bundy processes try to roll over the files simultaneously. Version 1.1.0 of log4cplus solved this problem, so if this or higher version of log4cplus is used to build Bundy, it shouldn't happen. Even for older versions it is normally expected to happen rarely unless the log messages are produced very frequently by multiple different processes.

In this example we want to set the global logging to write to the file /var/log/my_bundy.log, at severity WARN. We want the authoritative server to log at DEBUG with debuglevel 40, to a different file (/tmp/debug_messages).

Start bundyctl.

["login success "]
> config show Logging
Logging/loggers []  list

By default, no specific loggers are configured, in which case the severity defaults to INFO and the output is written to stderr.

Let's first add a default logger:

> config add Logging/loggers
> config show Logging
Logging/loggers/    list    (modified)

The loggers value line changed to indicate that it is no longer an empty list:

> config show Logging/loggers
Logging/loggers[0]/name ""  string  (default)
Logging/loggers[0]/severity "INFO"  string  (default)
Logging/loggers[0]/debuglevel   0   integer (default)
Logging/loggers[0]/additive false   boolean (default)
Logging/loggers[0]/output_options   []  list    (default)

The name is mandatory, so we must set it. We will also change the severity as well. Let's start with the global logger.

> config set Logging/loggers[0]/name *
> config set Logging/loggers[0]/severity WARN
> config show Logging/loggers
Logging/loggers[0]/name "*" string  (modified)
Logging/loggers[0]/severity "WARN"  string  (modified)
Logging/loggers[0]/debuglevel   0   integer (default)
Logging/loggers[0]/additive false   boolean (default)
Logging/loggers[0]/output_options   []  list    (default)

Of course, we need to specify where we want the log messages to go, so we add an entry for an output option.

>  config add Logging/loggers[0]/output_options
>  config show Logging/loggers[0]/output_options
Logging/loggers[0]/output_options[0]/destination    "console"   string  (default)
Logging/loggers[0]/output_options[0]/output "stdout"    string  (default)
Logging/loggers[0]/output_options[0]/flush  false   boolean (default)
Logging/loggers[0]/output_options[0]/maxsize    0   integer (default)
Logging/loggers[0]/output_options[0]/maxver 0   integer (default)

These aren't the values we are looking for.

>  config set Logging/loggers[0]/output_options[0]/destination file
>  config set Logging/loggers[0]/output_options[0]/output /var/log/bundy.log
>  config set Logging/loggers[0]/output_options[0]/maxsize 204800
>  config set Logging/loggers[0]/output_options[0]/maxver 8

Which would make the entire configuration for this logger look like:

>  config show all Logging/loggers
Logging/loggers[0]/name "*" string  (modified)
Logging/loggers[0]/severity "WARN"  string  (modified)
Logging/loggers[0]/debuglevel   0   integer (default)
Logging/loggers[0]/additive false   boolean (default)
Logging/loggers[0]/output_options[0]/destination    "file"  string  (modified)
Logging/loggers[0]/output_options[0]/output "/var/log/bundy.log"   string  (modified)
Logging/loggers[0]/output_options[0]/flush  false   boolean (default)
Logging/loggers[0]/output_options[0]/maxsize    204800  integer (modified)
Logging/loggers[0]/output_options[0]/maxver 8   integer (modified)

That looks OK, so let's commit it before we add the configuration for the authoritative server's logger.

>  config commit

Now that we have set it, and checked each value along the way, adding a second entry is quite similar.

>  config add Logging/loggers
>  config set Logging/loggers[1]/name Auth
>  config set Logging/loggers[1]/severity DEBUG
>  config set Logging/loggers[1]/debuglevel 40
>  config add Logging/loggers[1]/output_options
>  config set Logging/loggers[1]/output_options[0]/destination file
>  config set Logging/loggers[1]/output_options[0]/output /tmp/auth_debug.log
>  config commit

And that's it. Once we have found whatever it was we needed the debug messages for, we can simply remove the second logger to let the authoritative server use the same settings as the rest.

>  config remove Logging/loggers[1]
>  config commit

And every module will now be using the values from the logger named “*”.