BIND 10 Guide

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

The BIND 10 releases are available as tar file downloads from ftp://ftp.isc.org/isc/bind10/. 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.

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

The code can be checked out from git://git.bind10.isc.org/bind10; for example:

$ git clone git://git.bind10.isc.org/bind10

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.

BIND 10 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:

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/bind10

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 BIND 10 executables, support files, and documentation, run:

$ make install

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

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

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):

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 b10-xfrin and b10-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, bindctl 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

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 BIND 10, we show some examples. They all assume they start with default configuration.

First, let's disable the static data source (“VERSION.BIND” 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 b10-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

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
          

bindctl. To reload a zone, you the same command as above.

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

Build and install BIND 10 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>

2. Create the database:

mysql> CREATE DATABASE database-name;

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

3. Create the database tables:

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

4. Create the user under which BIND 10 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';

5. Exit MySQL:

mysql> quit
Bye
$

All leases issued by the server are stored in the lease database. Currently, the only supported database is MySQL ^[1], and so the server must be configured to access the correct database with the appropriate credentials.

Database configuration is controlled through the Dhcp4/lease-database parameters. The type of the database must be set to MySQL (although the string entered is "mysql"):

> 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.3, “Create MySQL Database and BIND 10 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 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[0] 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[1]. 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.6, “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 2001:db8:1::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

Below is a list of currently supported standard DHCPv4 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.2, “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.

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.

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 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, 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.2, “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, Hello World"
> config commit

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

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.5, “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 explictly set to an empty value. This is required because in the current version of BIND 10 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.

All leases issued by the server are stored in the lease database. Currently, the only supported database is MySQL ^[2], and so the server must be configured to access the correct database with the appropriate credentials.

Database configuration is controlled through the Dhcp6/lease-database parameters. The type of the database must be set to MySQL (although the string entered is "mysql"):

> 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.3, “Create MySQL Database and BIND 10 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 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[0] 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[1]. 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.

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” 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 "dhcp6" as these are standard DHCPv6 options. For other name spaces, including custom option spaces, see Section 18.2.6, “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

Below is a list of currently supported 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.2, “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.

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 unsigned 16 bit integer, 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, 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.2, “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, Hello World"
> config commit

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.5, “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 explictly set to an empty value. This is required because in the current version of BIND 10 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 it may have many subnet configurations defined, it must select appropriate subnet for a given request. To do this, the server first checks if there is only one subnet defined and source of the packet is link-local. If this is the case, the server assumes that the only subnet defined is local and client is indeed connected to it. This check simplifies small deployments.

If there are two or more subnets defined, the server can not assume which of those (if any) subnets are local. 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

Within BIND 10, a message is logged through a component called a "logger". Different parts of BIND 10 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.

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

Start bindctl.

["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/bind10.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/bind10.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 “*”.