BIND 10 Guide

BIND 10 Guide

Administrator Reference for BIND 10

BIND 10 Guide

Copyright 2010-2013 Internet Systems Consortium, Inc.

ii

BIND 10 Guide

iii

Contents

Introduction

1.1

Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1.2

Required Software at Run-time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1.3

Starting and Stopping the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1.4

Managing BIND 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Quick start

2.1

Quick start guide for authoritative DNS service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Installation

3.1

Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.2

Install Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.3

Building Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.4

Installation from source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.4.1

Download Tar File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.4.2

Retrieve from Git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.4.3

Configure before the build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.4.4

Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.4.5

Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Starting BIND 10 with bind10

4.1

Starting BIND 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Command channel

Configuration manager

10

Remote control daemon

11

7.1

Configuration specification for b10-cmdctl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

BIND 10 Guide

Control and configure user interface

12

8.1

bindctl command-line options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

8.2

General syntax of bindctl commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

8.3

Bindctl help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

8.4

Command arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

8.5

Module commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

8.6

Configuration commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

8.7

iv

8.6.1

List of configuration commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

8.6.2

Configuration data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

The execute command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

8.7.1

Execute directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

8.7.2

Notes on execute scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Common configuration elements

9.1

9.2

18

TSIG keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
9.1.1

Key anatomy and syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

9.1.2

Key ring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
9.2.1

Matching properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

9.2.2

More complicated matches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

9.2.3

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

9.2.4

Interaction with bindctl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

10 bind10 Control and Configuration

22

10.1 Stopping bind10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

10.2 Configuration to start processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
11 Authoritative Server

24

11.1 Server Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

11.2 Data Source Backends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
11.2.1 Data source types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
11.2.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
11.3 Loading Master Zones Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
12 Incoming Zone Transfers

28

12.1 Configuration for Incoming Zone Transfers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

12.2 TSIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
12.3 Control the use of IXFR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
12.4 Secondary Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
12.5 Trigger an Incoming Zone Transfer Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
12.6 Incoming Transfers with In-memory Datasource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

BIND 10 Guide

13 Outbound Zone Transfers

31

14 Dynamic DNS Update

32

14.1 Enabling Dynamic Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

14.2 Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
14.3 Miscellaneous Operational Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
15 Recursive Name Server

35

15.1 Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

15.2 Forwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
16 DHCP

37

16.1 DHCP Database Installation and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

16.1.1 Install MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
16.1.2 Build and Install BIND 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
16.1.3 Create MySQL Database and BIND 10 User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
17 The DHCPv4 Server

39

17.1 Starting and Stopping the DHCPv4 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

17.2 Configuring the DHCPv4 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
17.2.1 Database Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
17.2.2 Configuration of Address Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
17.2.3 Standard DHCPv4 options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
17.2.4 Custom DHCPv4 options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
17.2.5 DHCPv4 vendor specific options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
17.2.6 Nested DHCPv4 options (custom option spaces) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
17.3 Server Identifier in DHCPv4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
17.4 Supported Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
17.5 DHCPv4 Server Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
18 The DHCPv6 Server

50

18.1 Starting and Stopping the DHCPv6 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

18.2 DHCPv6 Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
18.2.1 Database Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
18.2.2 Subnet and Address Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
18.2.3 Standard DHCPv6 options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
18.2.4 Custom DHCPv6 options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
18.2.5 DHCPv6 vendor specific options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
18.2.6 Nested DHCPv6 options (custom option spaces) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
18.2.7 Subnet Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
18.2.8 DHCPv6 Relays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
18.3 Server Identifier in DHCPv6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
18.4 Supported Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
18.5 DHCPv6 Server Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

BIND 10 Guide

vi

19 libdhcp++ library

60

19.1 Interface detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

20 Statistics

61

21 Logging

62

21.1 Logging configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

21.1.1 Loggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
21.1.1.1 name (string) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
21.1.1.2 severity (string) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
21.1.1.3 output_options (list) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
21.1.1.4 debuglevel (integer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
21.1.1.5 additive (true or false) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
21.1.2 Output Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
21.1.2.1 destination (string) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
21.1.2.2 output (string) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
21.1.2.2.1

flush (true of false) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

21.1.2.2.2

maxsize (integer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

21.1.2.2.3

maxver (integer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

21.1.3 Example session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

21.2 Logging Message Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

BIND 10 Guide

vii

List of Tables

10.1 Special startup components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

17.1 List of standard DHCPv4 options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
17.2 List of standard DHCPv4 options (continued) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
17.3 List of standard DHCP option types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
18.1 List of standard DHCPv6 options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Abstract

BIND 10 is a framework that features Domain Name System (DNS) suite and Dynamic Host Configuration Protocol (DHCP)
servers with development managed by Internet Systems Consortium (ISC). It includes DNS libraries, modular components for
controlling authoritative and recursive DNS servers, and experimental DHCPv4 and DHCPv6 servers.
This is the reference guide for BIND 10 version 20130529. The most up-to-date version of this document (in PDF, HTML, and
plain text formats), along with other documents for BIND 10, can be found at http://bind10.isc.org/docs.

BIND 10 Guide

ix

Preface
Acknowledgements
BIND 10 is a sponsored development project, and would not be possible without the generous support of the sponsors.
JPRS and CIRA are Patron Level sponsors.
AFNIC, CNNIC, CZ.NIC, DENIC eG, Google, RIPE NCC, Registro.br, .nz Registry Services, and Technical Center of Internet
are current sponsors.
Afilias, IIS.SE, Nominet, and SIDN were founding sponsors of the project.
Support for BIND 10 development of the DHCPv4 and DHCPv6 components is provided by Comcast.

BIND 10 Guide

1 / 66

Chapter 1

Introduction
BIND is the popular implementation of a DNS server, developer interfaces, and DNS tools. BIND 10 is a rewrite of BIND 9 and
ISC DHCP. BIND 10 is written in C++ and Python and provides a modular environment for serving, maintaining, and developing
DNS and DHCP. BIND 10 provides a EDNS0- and DNSSEC-capable authoritative DNS server and a caching recursive name
server which also provides forwarding. It also provides experimental DHCPv4 and DHCPv6 servers.
This guide covers BIND 10 version 20130529.

1.1

Supported Platforms

BIND 10 builds have been tested on (in no particular order) Debian GNU/Linux 6 and unstable, Ubuntu 9.10, NetBSD 5, Solaris
10 and 11, FreeBSD 7 and 8, CentOS Linux 5.3, MacOS 10.6 and 10.7, and OpenBSD 5.1. It has been tested on Sparc, i386, and
amd64 hardware platforms. It is planned for BIND 10 to build, install and run on Windows and standard Unix-type platforms.

1.2

Required Software at Run-time

Running BIND 10 uses various extra software which may not be provided in some operating systems default installations nor
standard packages collections. You may need to install this required software separately. (For the build requirements, also see
Section 3.3.)
BIND 10 requires at least Python 3.1 (http://www.python.org/). It also works with Python 3.2.
BIND 10 uses the Botan crypto library for C++ (http://botan.randombit.net/). It requires at least Botan version 1.8.
BIND 10 uses the log4cplus C++ logging library (http://log4cplus.sourceforge.net/). It requires at least log4cplus
version 1.0.3.
The authoritative DNS server uses SQLite3 (http://www.sqlite.org/). It needs at least SQLite version 3.3.9.
The b10-ddns, b10-xfrin, b10-xfrout, and b10-zonemgr components require the libpython3 library and the Python _sqlite3.so
module (which is included with Python). Python modules need to be built for the corresponding Python 3.

1.3

Starting and Stopping the Server

BIND 10 is modular. Part of this modularity is accomplished using multiple cooperating processes which, together, provide the
server functionality. This is a change from the previous generation of BIND software, which used a single process.
At first, running many different processes may seem confusing. However, these processes are started by running a single command, bind10. This command starts a master process, b10-init, which will start other required processes and other processes
when configured. The processes that may be started have names starting with "b10-", including:

BIND 10 Guide

2 / 66

b10-auth Authoritative DNS server. This process serves DNS requests.

b10-cfgmgr Configuration manager. This process maintains all of the configuration for BIND 10.
b10-cmdctl Command and control service. This process allows external control of the BIND 10 system.
b10-ddns Dynamic DNS update service. This process is used to handle incoming DNS update requests to allow granted
clients to update zones for which BIND 10 is serving as a primary server.
b10-msgq Message bus daemon. This process coordinates communication between all of the other BIND 10 processes.
b10-resolver Recursive name server. This process handles incoming DNS queries and provides answers from its cache or
by recursively doing remote lookups. (This is an experimental proof of concept.)
b10-sockcreator Socket creator daemon. This process creates sockets used by network-listening BIND 10 processes.
b10-stats Statistics collection daemon. This process collects and reports statistics data.
b10-stats-httpd HTTP server for statistics reporting. This process reports statistics data in XML format over HTTP.
b10-xfrin Incoming zone transfer service. This process is used to transfer a new copy of a zone into BIND 10, when acting
as a secondary server.
b10-xfrout Outgoing zone transfer service. This process is used to handle transfer requests to send a local zone to a remote
secondary server.
b10-zonemgr Secondary zone manager. This process keeps track of timers and other necessary information for BIND 10
to act as a slave server.
These do not need to be manually started independently.

1.4

Managing BIND 10

Once BIND 10 is running, a few commands are used to interact directly with the system:
bindctl Interactive administration interface. This is a low-level command-line tool which allows a developer or an experienced administrator to control BIND 10.
b10-loadzone Zone file loader. This tool will load standard masterfile-format zone files into BIND 10.
b10-cmdctl-usermgr User access control. This tool allows an administrator to authorize additional users to manage BIND
10.
The tools and modules are covered in full detail in this guide. In addition, manual pages are also provided in the default
installation.
BIND 10 also provides libraries and programmer interfaces for C++ and Python for the message bus, configuration backend, and,
of course, DNS. These include detailed developer documentation and code examples.

BIND 10 Guide

3 / 66

Chapter 2

Quick start
This quickly covers the standard steps for installing and deploying BIND 10. For further details, full customizations, and
troubleshooting, see the respective chapters in the BIND 10 guide.

2.1

Quick start guide for authoritative DNS service

1. Install required run-time and build dependencies.

2. Download the BIND 10 source tar file from ftp://ftp.isc.org/isc/bind10/.
3. Extract the tar file:
$ gzcat bind10-VERSION.tar.gz | tar -xvf -

4. Go into the source and run configure:

$ cd bind10-VERSION
$ ./configure

5. Build it:
$ make

6. Install it as root (to default /usr/local):

$ make install

7. Create a user for yourself:

$ cd /usr/local/etc/bind10/
$ /usr/local/sbin/b10-cmdctl-usermgr

8. Start the server (as root):

$ /usr/local/sbin/bind10

9. DNS and DHCP components are not started in the default configuration. In another console, enable the authoritative DNS
service (by using the bindctl utility to configure the b10-auth component to run):
$ bindctl

BIND 10 Guide

4 / 66

(Login with the username and password you used above to create a user.)
>
>
>
>
>

config
config
config
config
quit

add Init/components b10-auth

set Init/components/b10-auth/special auth
set Init/components/b10-auth/kind needed
commit

10. Test it; for example:

$ dig @127.0.0.1 -c CH -t TXT version.bind

11. Load desired zone file(s), for example:

$ b10-loadzone -c {"database_file": "/usr/local/var/bind10/zone.sqlite3"} your.zone. example.org your.zone.file

(If you use the sqlite3 data source with the default DB file, you can omit the -c option).
12. Test the new zone.

BIND 10 Guide

5 / 66

Chapter 3

Installation
3.1

Packages

Some operating systems or software package vendors may provide ready-to-use, pre-built software packages for the BIND 10
suite. Installing a pre-built package means you do not need to install build-only prerequisites and do not need to make the
software.
FreeBSD ports, NetBSD pkgsrc, and Debian testing package collections provide all the prerequisite packages.

3.2

Install Hierarchy

The following is the standard, common layout of the complete BIND 10 installation:
bin/ general tools and diagnostic clients.
etc/bind10/ configuration files.
lib/ libraries and python modules.
libexec/bind10/ executables that a user wouldnt normally run directly and are not run independently. These are the
BIND 10 modules which are daemons started by the b10-init master process.
sbin/ commands used by the system administrator.
share/bind10/ configuration specifications.
share/doc/bind10/ this guide and other supplementary documentation.
share/man/ manual pages (online documentation).
var/bind10/ data source and configuration databases.

3.3

Building Requirements

In addition to the run-time requirements (listed in Section 1.2), building BIND 10 from source code requires various development
include headers and program development tools.
Note
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 BIND 10 from source code.

BIND 10 Guide

6 / 66

Building from source code requires the Boost build-time headers (http://www.boost.org/). At least Boost version 1.35
is required.
To build BIND 10, also install the Botan (at least version 1.8) and the log4cplus (at least version 1.0.3) development include
headers.
Building BIND 10 also requires a C++ compiler and standard development headers, make, and pkg-config. BIND 10 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.
Visit the user-contributed wiki at http://bind10.isc.org/wiki/SystemSpecificNotes for system-specific installation tips.

3.4

Installation from source

BIND 10 is open source software written in C++ and Python. It is freely available in source code form from ISC as a downloadable tar file or via BIND 10s Git code revision control service. (It may also be available in pre-compiled ready-to-use packages
from operating system vendors.)

3.4.1

Download Tar File

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.

3.4.2

Retrieve from Git

Downloading this "bleeding edge" code is recommended only for developers or advanced users. Using development code in a
production environment is not recommended.
Note
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 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 doesnt 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.

3.4.3

Configure before the build

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:

BIND 10 Guide

7 / 66

--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 arent build failures.
Note
For additional instructions concerning the building and installation of BIND 10 DHCP, see Section 16.1.

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.

3.4.4

Build

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

3.4.5

Install

To install the BIND 10 executables, support files, and documentation, run:

$ make install

Note
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

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

program: error while loading shared libraries: libb10-something.so.1:

cannot open shared object file: No such file or directory

BIND 10 Guide

8 / 66

Chapter 4

Starting BIND 10 with bind10

BIND 10 is started with the bind10 command. It runs the b10-init daemon which starts up the required processes, and will also
restart some processes that exit unexpectedly. bind10 is the only command needed to start the BIND 10 system.
After starting the b10-msgq communications channel, b10-init connects to it, runs the configuration manager, and reads its own
configuration. Then it starts the other modules.
The b10-sockcreator, b10-msgq and b10-cfgmgr services make up the core. The b10-msgq daemon provides the communication channel between every part of the system. The b10-cfgmgr daemon is always needed by every module, if only to send
information about themselves somewhere, but more importantly to ask about their own settings, and about other modules. The
b10-sockcreator daemon helps allocate Internet addresses and ports as needed for BIND 10 network services.
In its default configuration, the b10-init master process will also start up b10-cmdctl for administration tools to communicate
with the system, and b10-stats for statistics collection. The DNS and DHCP servers are not started by default. The configuration
of components to start is covered in Section 10.2.

4.1

Starting BIND 10

To start the BIND 10 service, simply run bind10 as root. It will run in the foreground and your shell prompt will not be available.
It will output various log messages as it starts up and is used. Run it with the --verbose switch to get additional debugging or
diagnostic output.
Note
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.

BIND 10 Guide

9 / 66

Chapter 5

Command channel
The BIND 10 components use the b10-msgq message routing daemon to communicate with other BIND 10 components. The
b10-msgq implements what is called the Command Channel. Processes intercommunicate by sending messages on the command channel. Example messages include shutdown, get configurations, and set configurations. This Command Channel is not
used for DNS message passing. It is used only to control and monitor the BIND 10 system.
Administrators do not communicate directly with the b10-msgq daemon. By default, BIND 10 uses a UNIX domain socket file
named /usr/local/var/bind10/msg_socket for this interprocess communication.

BIND 10 Guide

10 / 66

Chapter 6

Configuration manager
The configuration manager, b10-cfgmgr, handles all BIND 10 system configuration. It provides persistent storage for configuration, and notifies running modules of configuration changes.
The b10-auth and b10-xfrin daemons and other components receive their configurations from the configuration manager over
the b10-msgq command channel.
The administrator doesnt connect to it directly, but uses a user interface to communicate with the configuration manager via
b10-cmdctls REST-ful interface. b10-cmdctl is covered in Chapter 7.
Note
The current release only provides bindctl as a user interface to b10-cmdctl. Upcoming releases will provide another interactive
command-line interface and a web-based interface.

The b10-cfgmgr daemon can send all specifications and all current settings to the bindctl client (via b10-cmdctl). b10-cfgmgr
relays configurations received from b10-cmdctl to the appropriate modules.
The stored configuration file is at /usr/local/var/bind10/b10-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 b10-init master process (as covered in Chapter 4).

BIND 10 Guide

11 / 66

Chapter 7

Remote control daemon

b10-cmdctl is the gateway between administrators and the BIND 10 system. It is a HTTPS server that uses standard HTTP
Digest Authentication for username and password validation. It provides a REST-ful interface for accessing and controlling
BIND 10.
When b10-cmdctl starts, it firsts asks b10-cfgmgr about what modules are running and what their configuration is (over the
b10-msgq channel). Then it will start listening on HTTPS for clients the user interface such as bindctl.
b10-cmdctl directly sends commands (received from the user interface) to the specified component. Configuration changes are
actually commands to b10-cfgmgr so are sent there.
The HTTPS server requires a private key, such as a RSA PRIVATE KEY. The default location is at /usr/local/etc/
bind10/cmdctl-keyfile.pem. (A sample key is at /usr/local/share/bind10/cmdctl-keyfile.pem.) It
also uses a certificate located at /usr/local/etc/bind10/cmdctl-certfile.pem. (A sample certificate is at /usr/
local/share/bind10/cmdctl-certfile.pem.) This may be a self-signed certificate or purchased from a certification
authority.
Note
The HTTPS server doesnt support a certificate request from a client (at this time). The b10-cmdctl daemon does not provide a
public service. If any client wants to control BIND 10, then a certificate needs to be first received from the BIND 10 administrator.
The BIND 10 installation provides a sample PEM bundle that matches the sample key and certificate.

The b10-cmdctl daemon also requires the user account file located at /usr/local/etc/bind10/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 b10-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.

7.1

Configuration specification for b10-cmdctl

The configuration items for b10-cmdctl are: accounts_file which defines the path to the user accounts database (the default
is /usr/local/etc/bind10/cmdctl-accounts.csv); cert_file which defines the path to the PEM certificate file
(the default is /usr/local/etc/bind10/cmdctl-certfile.pem); and key_file which defines the path to the PEM
private key file (the default is /usr/local/etc/bind10/cmdctl-keyfile.pem).

BIND 10 Guide

12 / 66

Chapter 8

Control and configure user interface

Note
For the current release, bindctl is the only user interface. It is expected that upcoming releases will provide another interactive
command-line interface and a web-based interface for controlling and configuring BIND 10.

Note
bindctl has an internal command history, as well as tab-completion for most of the commands and arguments. However, these
are only enabled if the python readline module is available on the system. If not, neither of these features will be supported.

The bindctl tool provides an interactive prompt for configuring, controlling, and querying the BIND 10 components. It communicates directly with a REST-ful interface over HTTPS provided by b10-cmdctl. It doesnt communicate to any other components
directly.

8.1

bindctl command-line options

-a <address>, --address=<address> IP address that BIND 10s b10-cmdctl module is listening on. By default, this is
127.0.0.1.
-c <certificate file>, --certificate-chain=<certificate file> PEM-formatted server certificate file. When this option is given, bindctl will verify the server certificate using the given file as the root of the certificate chain. If not
specified, bindctl does not validate the certificate.
--csv-file-dir=<csv file> bindctl stores the username and password for logging in in a file called default_user.csv;
this option specifies the directory where this file is stored and read from. When not specified, ~/.bind10/ is used.
Note Currently, this file contains an unencrypted password.

-h, --help Shows a short overview of the command-line options of bindctl, and exits.
--version Shows the version of bindctl, and exits.
-p <port number>, --port=<port number> Port number that BIND 10s b10-cmdctl module is listening on. By default, this
is port 8080.

BIND 10 Guide

8.2

13 / 66

General syntax of bindctl commands

The bindctl tool is an interactive command-line tool, with dynamic commands depending on the BIND 10 modules that are
running. There are a number of fixed commands that have no module and that are always available. The general syntax of a
command is
<module> <command> [argument(s)]

For example, the Init module has a shutdown command to shut down BIND 10, with an optional argument help:
> Init shutdown help
Command shutdown
(Shut down BIND 10)
help (Get help for command)
This command has no parameters

There are no mandatory arguments, only the optional help.

8.3

Bindctl help

help is both a command and an option that is available to all other commands. When run as a command directly, it shows the
available modules.
> help
usage: <module name> <command name> [param1 = value1 [, param2 = value2]]
Type Tab character to get the hint of module/command/parameters.
Type "help(? h)" for help on bindctl.
Type "<module_name> help" for help on the specific module.
Type "<module_name> <command_name> help" for help on the specific command.
Available module names:
(list of modules)

When help is used as a command to a module, it shows the supported commands for the module; for example:
> Init help
Module Init Master process
Available commands:
help
Get help for module.
shutdown
Shut down BIND 10
ping
Ping the Init process
show_processes
List the running BIND 10 processes

And when added to a module command, it shows the description and parameters of that specific command; for example:
> Auth loadzone help
Command loadzone
((Re)load a specified zone)
help (Get help for command)
Parameters:
class (string, optional)
origin (string, mandatory)

8.4

Command arguments

Commands can have arguments, which can be either optional or mandatory. They can be specified by name (e.g. <command> <ar
gument name>=<argument value>), or positionally, (e.g. <command> <argument value 1> <argument value 2>).

BIND 10 Guide

14 / 66

<command> help shows the arguments a command supports and which of those are mandatory, and in which order the arguments
are expected if positional arguments are used.

For example, the loadzone command of the Auth module, as shown in the last example of the previous section, has two arguments, one of which is optional. The positional arguments in this case are class first and origin second; for example:
> Auth loadzone IN example.com.

But since the class is optional (defaulting to IN), leaving it out works as well:
> Auth loadzone example.com.

The arguments can also be provided with their names, in which case the order does not matter:
> Auth loadzone origin="example.com." class="IN"

8.5

Module commands

Each module has its own set of commands (if any), which will only be available if the module is running. For instance, the Auth
module has a loadzone command. The commands a module provides are documented in this guide in the section of that module
or in the modules corresponding manual page.

8.6

Configuration commands

Configuration commands are used to view and change the configuration of BIND 10 and its modules. Module configuration
is only shown if that module is running, but similar to commands, there are a number of top-level configuration items that are
always available (for instance tsig_keys and data_sources). Configuration changes (set, unset, add and remove) are done
locally first, and have no immediate effect. The changes can be viewed with config diff, and either reverted (config revert), or
committed (config commit). In the latter case, all local changes are submitted to the configuration manager, which verifies them,
and if they are accepted, applied and saved in persistent storage. When identifying items in configuration commands, the format
is
Module/example/item

Sub-elements of names, lists and sets (see Section 8.6.2) are separated with the / character, and list indices are identified with
[<index>]; for example:
Module/example/list[2]/foo

8.6.1

List of configuration commands

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

BIND 10 Guide

15 / 66

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 bindctl, and we recommend not using
it for general cases.

8.6.2

Configuration data types

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.
real A basic floating point number; can be set directly with config set, to any floating point value.
boolean A basic boolean value; can be set directly with config set, to either true or false.
string A basic string value; can be set directly with config set, so 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. [0]), 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[1]/port

BIND 10 Guide

16 / 66

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.

8.7

The execute command

The execute command executes a set of commands, either from a file or from a pre-defined set. Currently, the only predefined set
is init_authoritative_server, which adds b10-auth, b10-xfrin, and b10-xfrout to the set of components to be started by BIND
10. This pre-defined set does not commit the changes, so these modules do not show up for commands or configuration until the
user enters config commit after execute init_authoritative_server. For example:
> execute init_authoritative_server
> execute file /tmp/example_commands

The optional argument show displays the exact set of commands that would be executed; for example:
> execute init_authoritative_server show
!echo adding Authoritative server component
config add /Init/components b10-auth
config set /Init/components/b10-auth/kind needed
config set /Init/components/b10-auth/special auth
!echo adding Xfrin component
config add /Init/components b10-xfrin
config set /Init/components/b10-xfrin/address Xfrin
config set /Init/components/b10-xfrin/kind dispensable
!echo adding Xfrout component
config add /Init/components b10-xfrout
config set /Init/components/b10-xfrout/address Xfrout
config set /Init/components/b10-xfrout/kind dispensable
!echo adding Zone Manager component
config add /Init/components b10-zonemgr
config set /Init/components/b10-zonemgr/address Zonemgr
config set /Init/components/b10-zonemgr/kind dispensable
!echo Components added. Please enter "config commit" to
!echo finalize initial setup and run the components.

The optional show argument may also be used when executing a script from a file; for example:
> execute file /tmp/example_commands show

BIND 10 Guide

8.7.1

17 / 66

Execute directives

Within sets of commands to be run with the execute command, a number of directives are supported:
!echo <string> Prints the given string to bindctls 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.

8.7.2

Notes on execute scripts

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.

BIND 10 Guide

18 / 66

Chapter 9

Common configuration elements

Some things are configured in the same or similar manner across many modules. So we show them here in one place.

9.1

TSIG keys

TSIG is a way to sign requests and responses in DNS. It is defined in RFC 2845 and uses symmetric cryptography to sign the
DNS messages. If you want to make any use of TSIG (to authenticate transfers or DDNS, for example), you need to set up shared
secrets between the endpoints.
BIND 10 uses a global key ring for the secrets. It doesnt currently mean they would be stored differently, they are just in one
place of the configuration.

9.1.1

Key anatomy and syntax

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", youd 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.

BIND 10 Guide

9.1.2

19 / 66

Key ring

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.

9.2

ACLs

An ACL, or Access Control List, is a way to describe if a request is allowed or disallowed. The principle is, theres a list of rules.
Each rule is a name-value mapping (a dictionary, in the JSON terminology). Each rule must contain exactly one mapping called
"action", which describes what should happen if the rule applies. There may be more mappings, called matches, which describe
the conditions under which the rule applies.
When theres a query, the first rule is examined. If it matches, the action in it is taken. If not, next rule is examined. If there are
no more rules to examine, a default action is taken.
There are three possible "action" values. The "ACCEPT" value means the query is handled. If it is "REJECT", the query is not
answered, but a polite error message is sent back (if that makes sense in the context). The "DROP" action acts like a black hole.
The query is not answered and no error message is sent.
If there are multiple matching conditions inside the rule, all of them must be satisfied for the rule to apply. This can be used, for
example, to require the query to be signed by a TSIG key and originate from given address.
This is encoded in form of JSON. Semi-formal description could look something like this. It is described in more details below.
ACL := [ RULE, RULE, ... ]
RULE := { "action": "ACCEPT"|"REJECT"|"DROP", MATCH, MATCH, ... }
RULE_RAW := { MATCH, MATCH, ... }
MATCH := FROM_MATCH|KEY_MATCH|NOT_MATCH|OR_MATCH|AND_MATCH|...
FROM_MATCH := "from": [RANGE, RANGE, RANGE, ...] | RANGE
RANGE := "<ip range>"
KEY_MATCH := "key": [KEY, KEY, KEY, ...] | KEY
KEY := "<key name>"
NOT_MATCH := "NOT": RULE_RAW
OR_MATCH := "ANY": [ RULE_RAW, RULE_RAW, ... ]
AND_MATCH := "ALL": [ RULE_RAW, RULE_RAW, ... ]

9.2.1

Matching properties

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). This property is applicable only to the DNS context.
More properties to match are planned the destination address, ports, matches against the packet content.

BIND 10 Guide

9.2.2

20 / 66

More complicated matches

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.

9.2.3

Examples

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 youd 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"},

BIND 10 Guide

21 / 66

{"from": "192.168.0.0/16"},
{"from": "fc00::/7"}
]
},
"action": "REJECT"
},
{
"action": "ACCEPT"
}
]

9.2.4

Interaction with bindctl

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.
Youd 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

BIND 10 Guide

22 / 66

Chapter 10

bind10 Control and Configuration

This chapter explains how to control and configure the b10-init parent. The startup of this resident process that runs the BIND
10 daemons is covered in Chapter 4.

10.1

Stopping bind10

The BIND 10 suite may be shut down by stopping the parent b10-init process. This may be done by running the Init
shutdown command at the bindctl prompt.

10.2

Configuration to start processes

The processes to be used can be configured for b10-init to start, with the exception of the required b10-sockcreator, b10msgq and b10-cfgmgr components. The configuration is in the Init/components section. Each element represents one
component, which is an abstraction of a process.
To add a process to the set, lets say the resolver (which is not started by default), you would do this:
>
>
>
>
>

config
config
config
config
config

add Init/components b10-resolver

set Init/components/b10-resolver/special resolver
set Init/components/b10-resolver/kind needed
set Init/components/b10-resolver/priority 10
commit

Now, what it means. We add an entry called b10-resolver. It is both a name used to reference this component in the configuration and the name of the process to start. Then we set some parameters on how to start it.
The special setting is for components that need some kind of special care during startup or shutdown. Unless specified, the
component is started in a usual way. This is the list of components that need to be started in a special way, with the value of
special used for them:
Component
b10-auth
b10-resolver

Special
auth
resolver

b10-cmdctl

cmdctl

Description
Authoritative DNS server
DNS resolver
Command control (remote control
interface)

Table 10.1: Special startup components

The kind specifies how a failure of the component should be handled. If it is set to dispensable (the default unless you set
something else), it will get started again if it fails. If it is set to needed and it fails at startup, the whole b10-init shuts down

BIND 10 Guide

23 / 66

and exits with an error exit code. But if it fails some time later, it is just started again. If you set it to core, you indicate that
the system is not usable without the component and if such component fails, the system shuts down no matter when the failure
happened. This is the behavior of the core components (the ones you cant turn off), but you can declare any other components
as core as well if you wish (but you can turn these off, they just cant fail).
The priority defines order in which the components should start. The ones with higher numbers are started sooner than the
ones with lower ones. If you dont set it, 0 (zero) is used as the priority. Usually, leaving it at the default is enough.
There are other parameters we didnt use in our example. One of them is address. It is the address used by the component
on the b10-msgq message bus. The special components already know their address, but the usual ones dont. The address is by
convention the thing after b10-, with the first letter capitalized (eg. b10-stats would have Stats as its address).
The last one is process. It is the name of the process to be started. It defaults to the name of the component if not set, but you
can use this to override it. (The special components also already know their executable name.)
Note
The configuration is quite powerful, but that includes a lot of space for mistakes. You could turn off the b10-cmdctl, but then
you couldnt 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: b10-stats-httpd needs b10-stats, b10-xfrout needs b10-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 b10-auth and b10-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
config
config
config

add Init/components b10-resolver-2

set Init/components/b10-resolver-2/special resolver
set Init/components/b10-resolver-2/kind needed
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 dont 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 b10-init may be listed by running Init show_processes using bindctl.

BIND 10 Guide

24 / 66

Chapter 11

Authoritative Server
The b10-auth is the authoritative DNS server. It supports EDNS0, DNSSEC, IPv6, and SQLite3 and in-memory zone data
backends. Normally it is started by the b10-init master process.

11.1

Server Configurations

b10-auth is configured via the b10-cfgmgr configuration manager. The module name is Auth. The configuration data items
are:
database_file This is an optional string to define the path to find the SQLite3 database file. Note: This may be a temporary
setting because the DNS server can use various data source backends.
datasources datasources configures data sources. The list items include: type to define the required data source type
(such as memory); class to optionally select the class (it defaults to IN); and zones to define the file path name,
the filetype (sqlite3 to load from a SQLite3 database file or text to load from a master text file), and the origin
(default domain). By default, this is empty.
Note
Currently this is only used for the memory data source. Only the IN class is supported at this time. By default, the memory
data source is disabled. Also, currently the zone file must be canonical such as generated by named-compilezone -D,
or must be an SQLite3 database.

listen_on listen_on is a list of addresses and ports for b10-auth to listen on. The list items are the address string and
port number. By default, b10-auth listens on port 53 on the IPv6 (::) and IPv4 (0.0.0.0) wildcard addresses.
Note
The default configuration is currently not appropriate for a multi-homed host. In case you have multiple public IP addresses, it is possible the query UDP packet comes through one interface and the answer goes out through another. The
answer will probably be dropped by the client, as it has a different source address than the one it sent the query to. The
client would fallback on TCP after several attempts, which works well in this situation, but is clearly not ideal.
There are plans to solve the problem such that the server handles it by itself. But until it is actually implemented, it
is recommended to alter the configuration remove the wildcard addresses and list all addresses explicitly. Then the
server will answer on the same interface the request came on, preserving the correct address.

tcp_recv_timeout tcp_recv_timeout is the timeout used on incoming TCP connections, in milliseconds. If the query is
not sent within this time, the connection is closed. Setting this to 0 will disable TCP timeouts completely.
The configuration commands are:

BIND 10 Guide

25 / 66

loadzone loadzone tells b10-auth to load or reload a zone file. The arguments include: class which optionally defines the
class (it defaults to IN); origin is the domain name of the zone; and datasrc optionally defines the type of datasource
(it defaults to memory).
Note
Currently this only supports the IN class and the memory data source.

getstats getstats requests b10-auth to send its statistics data to b10-stats(8) as a response of the command.
shutdown Stop the authoritative DNS server. This has an optional pid argument to select the process ID to stop. (Note that the
BIND 10 init process may restart this service if configured.)

11.2

Data Source Backends

Bind 10 has the concept of data sources. A data source is a place where authoritative zone data reside and where they can be
served from. This can be a master file, a database or something completely different.
Once a query arrives, b10-auth goes through a configured list of data sources and finds the one containing a best matching zone.
From the equally good ones, the first one is taken. This data source is then used to answer the query.
Note
In the current release, b10-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.BIND.. The IN class contains single SQLite3 data source with database file located at /usr/local/var/
bind10/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 BIND 10 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, b10-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, cachezones, is a list of zone origins to load into in-memory.

11.2.1

Data source types

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 (cachezones) should be omitted. The params is a dictionary mapping from zone origins to the files they reside in.

BIND 10 Guide

11.2.2

26 / 66

Examples

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, lets disable the built-in 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, lets 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
config
config
config

set data_sources/classes/IN[0]/cache-enable true

add data_sources/classes/IN[0]/cache-zones example.org.
add data_sources/classes/IN[0]/cache-zones example.net.
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 dont 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.

Note
Theres also Auth/database_file configuration variable, pointing to a SQLite3 database file. This is no longer used by
b10-auth, but it is left in place for now, since other modules use it. Once b10-zonemgr, b10-xfrout and b10-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, youre
good.

11.3

Loading Master Zones Files

RFC 1035 style DNS master zone files may imported into a BIND 10 SQLite3 data source by using the b10-loadzone utility.
b10-loadzone supports the following special directives (control entries):

BIND 10 Guide

27 / 66

$INCLUDE Loads an additional zone file. This may be recursive.

$ORIGIN Defines the relative domain name.
$TTL Defines the time-to-live value used for following records that dont include a TTL.
Note
In the current release, only the SQLite3 back end is used by b10-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.

BIND 10 Guide

28 / 66

Chapter 12

Incoming Zone Transfers

Incoming zones are transferred using the b10-xfrin process which is started by b10-init. When received, the zone is stored in
the corresponding BIND 10 data source, and its records can be served by b10-auth. In combination with b10-zonemgr (for
automated SOA checks), this allows the BIND 10 server to provide secondary service.
The b10-xfrin process supports both AXFR and IXFR.

12.1

Configuration for Incoming Zone Transfers

In order to enable incoming zone transfers for a secondary zone, you will first need to make the zone "exist" in some data source.
One easy way to do this is to create an empty zone using the b10-loadzone utility. For example, this makes an empty zone (or
empties any existing content of the zone) "example.com" in the default data source for b10-loadzone (which is SQLite3-based
data source):
$ b10-loadzone -e example.com

Next, you need to specify a list of secondary zones to enable incoming zone transfers for these zones in most practical cases (you
can still trigger a zone transfer manually, without a prior configuration (see below)).
For example, to enable zone transfers for a zone named "example.com" (whose master address is assumed to be 2001:db8::53
here), run the following at the bindctl prompt:
>
>
>
>

config
config
config
config

add Xfrin/zones
set Xfrin/zones[0]/name "example.com"
set Xfrin/zones[0]/master_addr "2001:db8::53"
commit

(We assume there has been no zone configuration before).

Note
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 BIND 10 modules. When its
done, part or all of the initial configuration setup described in this section may be deprecated.

12.2

TSIG

If you want to use TSIG for incoming transfers, a system wide TSIG key ring must be configured (see Section 9.1.2). To specify a
key to use, set tsig_key value to the name of the key to use from the key ring. > config set Xfrin/zones[0]/tsig_key
"example.key"

BIND 10 Guide

12.3

29 / 66

Control the use of IXFR

By default, b10-xfrin uses IXFR for transferring zones specified in the Xfrin/zones list of the configuration, unless it doesnt
know the current SOA serial of the zone (including the case where the zone has never transferred or locally loaded), in which case
it automatically uses AXFR. If the attempt of IXFR fails, b10-xfrin automatically retries the transfer using AXFR. In general,
this works for any master server implementations including those that dont support IXFR and in any local state of the zone. So
there should normally be no need to configure on whether to use IXFR.
In some cases, however, it may be desirable to specify how and whether to use IXFR and AXFR. The request_ixfr configuration item under Xfrin/zones can be used to control such policies. It can take the following values.
yes This is the default behavior as described above.
no Only use AXFR. Note that this value normally shouldnt be needed thanks to the automatic fallback from IXFR to IXFR.
A possible case where this value needs to be used is that the master server has a bug and crashes if it receives an IXFR
request.
only Only use IXFR except when the current SOA serial is not known. This value has a severe drawback, that is, if the master
server does not support IXFR zone transfers never succeed (except for the very first one, which will use AXFR), and the
zone will eventually expire. Therefore it should not be used in general. Still, in some special cases the use of this value
may make sense. For example, if the operator is sure that the master server supports IXFR and the zone is very large, they
may want to avoid falling back to AXFR as it can be more expensive.
Note
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.

12.4

Secondary Manager

The b10-zonemgr process is started by b10-init. It keeps track of SOA refresh, retry, and expire timers and other details for
BIND 10 to perform as a slave. When the b10-auth authoritative DNS server receives a NOTIFY message, b10-zonemgr may
tell b10-xfrin to do a refresh to start an inbound zone transfer. The secondary manager resets its counters when a new zone is
transferred in.
Note
Access control (such as allowing notifies) is not yet provided. The primary/secondary service is not yet complete.

The following example shows using bindctl 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), b10-zonemgr will automatically tell b10-xfrin
to transfer the zone in.

12.5

Trigger an Incoming Zone Transfer Manually

To manually trigger a zone transfer to retrieve a remote zone, you may use the bindctl utility. For example, at the bindctl prompt
run:
> Xfrin retransfer zone_name="foo.example.org" master=192.0.2.99

BIND 10 Guide

30 / 66

The retransfer command always uses AXFR. To use IXFR for a zone that has already been transferred once, use the refresh
command. It honors the Xfrin/zones/request_ixfr configuration item (see Section 12.3.), and if its configured to use
IXFR, it will be used.
Both the retransfer and refresh commands can be used for an initial transfer before setting up secondary configurations. In this
case AXFR will be used for the obvious reason.

12.6

Incoming Transfers with In-memory Datasource

In the case of an incoming zone transfer, the received zone is first stored in the corresponding BIND 10 datasource. In case the
secondary zone is served by an in-memory datasource with an SQLite3 backend, b10-auth is automatically sent a loadzone
command to reload the corresponding zone into memory from the backend.
The administrator doesnt have to do anything for b10-auth to serve the new version of the zone, except for the configuration
such as the one described in Section 11.2.

BIND 10 Guide

31 / 66

Chapter 13

Outbound Zone Transfers

The b10-xfrout process is started by b10-init. When the b10-auth authoritative DNS server receives an AXFR or IXFR request,
b10-auth internally forwards the request to b10-xfrout, which handles the rest of this request processing. This is used to provide
primary DNS service to share zones to secondary name servers. The b10-xfrout is also used to send NOTIFY messages to
secondary servers.
A global or per zone transfer_acl configuration can be used to control accessibility of the outbound zone transfer service.
By default, b10-xfrout allows any clients to perform zone transfers for any zones.
> config show Xfrout/transfer_acl
Xfrout/transfer_acl[0] {"action": "ACCEPT"}

any (default)

If you want to require TSIG in access control, a system wide TSIG key ring must be configured (see Section 9.1.2). In this
example, we allow client matching both the IP address and key.
> config set tsig_keys/keys ["key.example:<base64-key>"]
> config set Xfrout/zone_config[0]/transfer_acl [{"action": "ACCEPT", "from": "192.0.2.1",
"key": "key.example"}]
> config commit

Both b10-xfrout and b10-auth will use the system wide key ring to check TSIGs in the incoming messages and to sign responses.
For further details on ACL configuration, see Section 9.2.
Note
The way to specify zone specific configuration (ACLs, etc) is likely to be changed.

BIND 10 Guide

32 / 66

Chapter 14

Dynamic DNS Update

BIND 10 supports the server side of the Dynamic DNS Update (DDNS) protocol as defined in RFC 2136. This service is
provided by the b10-ddns component, which is started by the b10-init process if configured so.
When the b10-auth authoritative DNS server receives an UPDATE request, it internally forwards the request to b10-ddns, which
handles the rest of this request processing. When the processing is completed, b10-ddns will send a response to the client as
specified in RFC 2136 (NOERROR for successful update, REFUSED if rejected due to ACL check, etc). If the zone has been
changed as a result, it will internally notify b10-xfrout so that other secondary servers will be notified via the DNS NOTIFY
protocol. In addition, if b10-auth serves the updated zone (as described in Section 11.2), b10-ddns will also notify b10-auth so
that b10-auth will re-cache the updated zone content if necessary.
The b10-ddns component supports requests over both UDP and TCP, and both IPv6 and IPv4; for TCP requests, however, it
terminates the TCP connection immediately after each single request has been processed. Clients cannot reuse the same TCP
connection for multiple requests. (This is a current implementation limitation of b10-ddns. While RFC 2136 doesnt specify
anything about such reuse of TCP connection, there is no reason for disallowing it as RFC 1035 generally allows multiple requests
sent over a single TCP connection. BIND 9 supports such reuse.)
As of this writing b10-ddns does not support update forwarding for secondary zones. If it receives an update request for a
secondary zone, it will immediately return a not implemented response.
Note
For feature completeness, update forwarding should be eventually supported. But currently its considered a lower priority task
and there is no specific plan of implementing this feature.

14.1

Enabling Dynamic Update

First off, it must be made sure that a few components on which b10-ddns depends are configured to run, which are b10-auth
and b10-zonemgr. In addition, b10-xfrout should also be configured to run; otherwise the notification after an update (see
above) will fail with a timeout, suspending the DDNS service while b10-ddns waits for the response (see the description of the
DDNS_UPDATE_NOTIFY_FAIL log message for further details). If BIND 10 is already configured to provide authoritative
DNS service they should normally be configured to run already.
Second, for the obvious reason dynamic update requires that the underlying data source storing the zone data be writable. In
the current implementation this means the zone must be stored in an SQLite3-based data source. Also, in this current version,
the b10-ddns component configures itself with the data source referring to the database_file configuration parameter of
b10-auth. So this information must be configured correctly before starting b10-ddns.
Note
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.

BIND 10 Guide

33 / 66

In general, if something goes wrong regarding the dependency described above, b10-ddns will log the related event at the
warning or error level. Its advisable to check the log message when you first enable DDNS or if it doesnt work as you expect to
see if theres any warning or error log message.
Next, to enable the DDNS service, b10-ddns needs to be explicitly configured to run. It can be done by using the bindctl utility.
For example:
>
>
>
>

config
config
config
config

add Init/components b10-ddns

set Init/components/b10-ddns/address DDNS
set Init/components/b10-ddns/kind dispensable
commit

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

14.2

Access Control

By default, b10-ddns rejects any update requests from any clients by returning a REFUSED response. To allow updates to take
effect, an access control rule (called update ACL) with a policy allowing updates must explicitly be configured. Update ACL
must be configured per zone basis in the zones configuration parameter of b10-ddns. This is a list of per-zone configurations
regarding DDNS. Each list element consists of the following parameters:
origin The zones origin name
class The RR class of the zone (normally IN, and in that case can be omitted in configuration)
update_acl List of access control rules (ACL) for the zone
The syntax of the ACL is the same as ACLs for other components. Specific examples are given below.
In general, an update ACL rule that allows an update request should be configured with a TSIG key. This is an example update
ACL that allows updates to the zone named example.org (of default RR class IN) from clients that send requests signed with
a TSIG whose key name is "key.example.org" (and refuses all others):
>
>
>
>

config
config
config
config

add DDNS/zones
set DDNS/zones[0]/origin example.org
add DDNS/zones[0]/update_acl {"action": "ACCEPT", "key": "key.example.org"}
commit

The TSIG key must be configured system wide (see Section 9.1).
The full description of ACLs can be found in Section 9.2.
Note
The b10-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; its not possible to specify access control with higher granularity
such as for particular domain names or specific types of RRs.

BIND 10 Guide

34 / 66

Note
Contrary to what RFC 2136 (literally) specifies, b10-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.

14.3

Miscellaneous Operational Issues

Unlike BIND 9, BIND 10 currently does not support automatic re-signing of DNSSEC-signed zone when its updated via DDNS.
It could be possible to re-sign the updated zone afterwards or make sure the update request also updates related DNSSEC records,
but that will be pretty error-prone operation. In general, its not advisable to allow DDNS for a signed zone at this moment.
Also unlike BIND 9, its currently not possible to freeze a zone temporarily in order to suspend DDNS while you manually
update the zone. If you need to make manual updates to a dynamic zone, youll need to temporarily reject any updates to the
zone via the update ACLs.
Dynamic updates are only applicable to primary zones. In order to avoid updating secondary zones via DDNS requests, b10ddns refers to the secondary_zones configuration of b10-zonemgr. Zones listed in secondary_zones will never be updated
via DDNS regardless of the update ACL configuration; b10-ddns will return a NOTAUTH (server not authoritative for the zone)
response. If you have a "conceptual" secondary zone whose content is a copy of some external source but is not updated via the
standard zone transfers and therefore not listed in secondary_zones, be careful not to allow DDNS for the zone; it would be
quite likely to lead to inconsistent state between different servers. Normally this should not be a problem because the default
update ACL rejects any update requests, but you may want to take an extra care about the configuration if you have such type of
secondary zones.
The difference of two versions of a zone, before and after a DDNS transaction, is automatically recorded in the underlying data
source, and can be retrieved in the form of outbound IXFR. This is done automatically; it does not require specific configuration
to make this possible.

BIND 10 Guide

35 / 66

Chapter 15

Recursive Name Server

Note
The b10-resolver is an experimental proof of concept.

The b10-resolver daemon provides an iterative caching and forwarding DNS server. The process is started by b10-init.
The main b10-init process can be configured to select to run either the authoritative or resolver or both. By default, it doesnt
start either one. You may change this using bindctl, for example:
>
>
>
>
>

config
config
config
config
config

add Init/components b10-resolver

set Init/components/b10-resolver/special resolver
set Init/components/b10-resolver/kind needed
set Init/components/b10-resolver/priority 10
commit

The master b10-init process will stop and start the desired services.
By default, the resolver listens on port 53 for 127.0.0.1 and ::1. The following example shows how it can be configured to listen
on an additional address (and port):
>
>
>
>

config
config
config
config

add Resolver/listen_on
set Resolver/listen_on[2]/address "192.168.1.1"
set Resolver/listen_on[2]/port 53
commit

(Replace the 2 as needed; run config show Resolver/listen_on if needed.)

15.1

Access Control

By default, the b10-resolver daemon only accepts DNS queries from the localhost (127.0.0.1 and ::1). The Resolver/quer
y_acl configuration may be used to reject, drop, or allow specific IPs or networks. See Section 9.2.
The following session is an example of extending the ACL to also allow queries from 192.0.2.0/24:
> config show Resolver/query_acl
Resolver/query_acl[0]
{"action":
Resolver/query_acl[1]
{"action":
> config add Resolver/query_acl
> config set Resolver/query_acl[2]
> config add Resolver/query_acl
> config show Resolver/query_acl
Resolver/query_acl[0]
{"action":

"ACCEPT", "from": "127.0.0.1"}

any (default)
"ACCEPT", "from": "::1"} any (default)
{"action": "ACCEPT", "from": "192.0.2.0/24"}

"ACCEPT", "from": "127.0.0.1"}

any (modified)

BIND 10 Guide

Resolver/query_acl[1]
Resolver/query_acl[2]
Resolver/query_acl[3]
> config commit

36 / 66

{"action": "ACCEPT", "from": "::1"} any (modified)

{"action": "ACCEPT", "from": "192.0.2.0/24"} any (modified)
{"action": "REJECT"}
any (modified)

Note that we didnt set the value of the last final rule (query_acl[3]) -- in the case of resolver, rejecting all queries is the default
value of a new rule. In fact, this rule can even be omitted completely, as the default, when a query falls off the list, is rejection.

15.2

Forwarding

To enable forwarding, the upstream address and port must be configured to forward queries to, such as:
> config set Resolver/forward_addresses [{ "address": "192.168.1.1", "port": 53 }]
> config commit

(Replace 192.168.1.1 to point to your full resolver.)

Normal iterative name service can be re-enabled by clearing the forwarding address(es); for example:
> config set Resolver/forward_addresses []
> config commit

BIND 10 Guide

37 / 66

Chapter 16

DHCP
The Dynamic Host Configuration Protocol for IPv4 (DHCP or DHCPv4) and Dynamic Host Configuration Protocol for IPv6
(DHCPv6) are protocols that allow one node (server) to provision configuration parameters to many hosts and devices (clients).
To ease deployment in larger networks, additional nodes (relays) may be deployed that facilitate communication between servers
and clients. Even though principles of both DHCPv4 and DHCPv6 are somewhat similar, these are two radically different
protocols. BIND 10 offers two server implementations, one for DHCPv4 and one for DHCPv6.
This chapter covers those parts of BIND 10 that are common to both servers. DHCPv4-specific details are covered in Chapter 17,
while those details specific to DHCPv6 are described in Chapter 18
Note
In this release of BIND 10, the DHCPv4 and DHCPv6 servers must be considered experimental.

16.1

DHCP Database Installation and Configuration

BIND 10 DHCP stores its leases in a lease database. The software has been written in a way that makes it possible to choose
which database product should be used to store the lease information. At present, only support for MySQL is provided, and that
support must be explicitly included when BIND 10 is built. This section covers the building of BIND 10 with MySQL and the
creation of the lease database.

16.1.1

Install MySQL

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

16.1.2

Build and Install BIND 10

Build and install BIND 10 as described in Chapter 3, with the following modification: to enable the MySQL database code,
at the "configure" step (see Section 3.4.3), 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.

BIND 10 Guide

16.1.3

38 / 66

Create MySQL Database and BIND 10 User

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
$

BIND 10 Guide

39 / 66

Chapter 17

The DHCPv4 Server

17.1

Starting and Stopping the DHCPv4 Server

b10-dhcp4 is the BIND 10 DHCPv4 server and, like other parts of BIND 10, is configured through the bindctl program.
After starting BIND 10 and entering bindctl, the first step in configuring the server is to add it to the list of running BIND 10
services.
> config add Init/components b10-dhcp4
> config set Init/components/b10-dhcp4/kind dispensable
> config commit

To remove b10-dhcp4 from the set of running services, the b10-dhcp4 is removed from list of Init components:
> config remove Init/components b10-dhcp4
> config commit

On start-up, the server will detect available network interfaces and will attempt to open UDP sockets on all interfaces that are up,
running, are not loopback, and have IPv4 address assigned. The server will then listen to incoming traffic. Currently supported
client messages are DISCOVER and REQUEST. The server will respond to them with OFFER and ACK, respectively. Since the
DHCPv4 server opens privileged ports, it requires root access. Make sure you run this daemon as root.

17.2

Configuring the DHCPv4 Server

Once the server is started, it can be configured. To view the current configuration, use the following command in bindctl:
> config show Dhcp4

When starting the DHCPv4 daemon for the first time, the default configuration will be available. It will look similar to this:
> config show Dhcp4
Dhcp4/interface/ list (default)
Dhcp4/renew-timer 1000 integer (default)
Dhcp4/rebind-timer 2000 integer (default)
Dhcp4/valid-lifetime 4000 integer (default)
Dhcp4/option-data [] list (default)
Dhcp4/lease-database/type "memfile" string (default)
Dhcp4/lease-database/name "" string (default)
Dhcp4/lease-database/user "" string (default)
Dhcp4/lease-database/host "" string (default)
Dhcp4/lease-database/password "" string (default)
Dhcp4/subnet4 [] list (default)

BIND 10 Guide

40 / 66

To change one of the parameters, simply follow the usual bindctl procedure. For example, to make the leases longer, change
their valid-lifetime parameter:
> config set Dhcp4/valid-lifetime 7200
> config commit

Please note that most Dhcp4 parameters are of global scope and apply to all defined subnets, unless they are overridden on a
per-subnet basis.

17.2.1

Database Configuration

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.
Note
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 (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).
> 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.)
Note
The password is echoed when entered and is stored in clear text in the BIND 10 configuration database. Improved password
security will be added in a future version of BIND 10 DHCP
1 The server comes with an in-memory database ("memfile") configured as the default database. This is used for internal testing and is not supported. In
addition, it does not store lease information on disk: lease information will be lost if the server is restarted.

BIND 10 Guide

17.2.2

41 / 66

Configuration of Address Pools

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
config
config
config

add Dhcp4/subnet4
set Dhcp4/subnet4[0]/subnet "192.0.2.0/24"
set Dhcp4/subnet4[0]/pool [ "192.0.2.10 - 192.0.2.20" ]
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
config
config
config

add Dhcp4/subnet4
set Dhcp4/subnet4[1]/subnet "192.0.3.0/24"
set Dhcp4/subnet4[1]/pool [ "192.0.3.0/24" ]
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.

17.2.3

Standard DHCPv4 options

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
config
config
config
config
config
config

add Dhcp4/option-data
set Dhcp4/option-data[0]/name "domain-name-servers"
set Dhcp4/option-data[0]/code 6
set Dhcp4/option-data[0]/space "dhcp4"
set Dhcp4/option-data[0]/csv-format true
set Dhcp4/option-data[0]/data "192.0.3.1, 192.0.3.2"
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

BIND 10 Guide

42 / 66

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. 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
config
config
config
config
config
config

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

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

Note
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 and Table 17.2. 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.
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.

17.2.4

Custom DHCPv4 options

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
config
config
config
config
config

add
set
set
set
set
set

Dhcp4/option-def
Dhcp4/option-def[0]/name "foo"
Dhcp4/option-def[0]/code 222
Dhcp4/option-def[0]/type "uint32"
Dhcp4/option-def[0]/array false
Dhcp4/option-def[0]/record-types ""

BIND 10 Guide

Name
subnet-mask
time-offset
routers
time-servers
name-servers
domain-name-servers
log-servers
cookie-servers
lpr-servers
impress-servers
resource-location-servers
host-name
boot-size
merit-dump
domain-name
swap-server
root-path
extensions-path
ip-forwarding
non-local-source-routing
policy-filter
max-dgram-reassembly
default-ip-ttl
path-mtu-aging-timeout
path-mtu-plateau-table
interface-mtu
all-subnets-local
broadcast-address
perform-mask-discovery
mask-supplier
router-discovery
router-solicitation-address
static-routes
trailer-encapsulation
arp-cache-timeout
ieee802-3-encapsulation
default-tcp-ttl
tcp-keepalive-internal
tcp-keepalive-garbage

43 / 66

Code
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

Type
ipv4-address
uint32
ipv4-address
ipv4-address
ipv4-address
ipv4-address
ipv4-address
ipv4-address
ipv4-address
ipv4-address
ipv4-address
string
uint16
string
fqdn
ipv4-address
string
string
boolean
boolean
ipv4-address
uint16
uint8
uint32
uint16
uint16
boolean
ipv4-address
boolean
boolean
boolean
ipv4-address
ipv4-address
boolean
uint32
boolean
uint8
uint32
boolean
Table 17.1: List of standard DHCPv4 options

Array?
false
false
true
true
false
true
true
true
true
true
true
false
false
false
false
false
false
false
false
false
true
false
false
false
true
false
false
false
false
false
false
false
true
false
false
false
false
false
false

BIND 10 Guide

Name
nis-domain
nis-servers
ntp-servers
vendor-encapsulatedoptions
netbios-name-servers
netbios-dd-server
netbios-node-type
netbios-scope
font-servers
x-display-manager
dhcp-requested-address
dhcp-option-overload
dhcp-message
dhcp-max-message-size
vendor-class-identifier
nwip-domain-name
nwip-suboptions
user-class
fqdn
dhcp-agent-options
authenticate
client-last-transaction-time
associated-ip
subnet-selection
domain-search
vivco-suboptions
vivso-suboptions

44 / 66

Code
40
41
42

Type
string
ipv4-address
ipv4-address

Array?
false
true
true

43

empty

false

44
45
46
47
48
49
50
52
56
57
60
62
63
77
81
82
90
91
92
118
119
124
125

ipv4-address
ipv4-address
uint8
string
ipv4-address
ipv4-address
ipv4-address
uint8
string
uint16
binary
string
binary
binary
record
empty
binary
uint32
ipv4-address
ipv4-address
binary
binary
binary

true
true
false
false
true
true
false
false
false
false
false
false
false
false
false
false
false
false
true
false
false
false
false

Table 17.2: List of standard DHCPv4 options (continued)

Name
binary
boolean
empty
fqdn
ipv4-address
ipv6-address
record
string
uint8
uint16
uint32

Meaning
An arbitrary string of bytes, specified as a set of
hexadecimal digits.
Boolean value with allowed values true or false
No value, data is carried in suboptions
Fully qualified domain name (e.g. www.example.com)
IPv4 address in the usual dotted-decimal notation (e.g.
192.0.2.1)
IPv6 address in the usual colon notation (e.g. 2001:db8::1)
Structured data that may comprise any types (except
"record" and "empty")
Any text
8 bit unsigned integer with allowed values 0 to 255
16 bit unsinged integer with allowed values 0 to 65535
32 bit unsigned integer with allowed values 0 to
4294967295
Table 17.3: List of standard DHCP option types

BIND 10 Guide

45 / 66

> 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.
Note
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
config
config
config
config
config
config

add Dhcp4/option-data
set Dhcp4/option-data[0]/name "foo"
set Dhcp4/option-data[0]/code 222
set Dhcp4/option-data[0]/space "dhcp4"
set Dhcp4/option-data[0]/csv-format true
set Dhcp4/option-data[0]/data "12345"
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
config
config
config
config
config
config
config

add
set
set
set
set
set
set
set

Dhcp4/option-def
Dhcp4/option-def[0]/name "bar"
Dhcp4/option-def[0]/code 223
Dhcp4/option-def[0]/space "dhcp4"
Dhcp4/option-def[0]/type "record"
Dhcp4/option-def[0]/array false
Dhcp4/option-def[0]/record-types "ipv4-address, uint16, string"
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.
The values of the option are set as follows:
>
>
>
>
>
>
>

config
config
config
config
config
config
config

add Dhcp4/option-data
set Dhcp4/option-data[0]/name "bar"
set Dhcp4/option-data[0]/space "dhcp4"
set Dhcp4/option-data[0]/code 223
set Dhcp4/option-data[0]/csv-format true
set Dhcp4/option-data[0]/data "192.0.2.100, 123, Hello World"
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.

BIND 10 Guide

17.2.5

46 / 66

DHCPv4 vendor specific options

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
config
config
config
config
config
config
config
config

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

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

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

Note
With this version of BIND 10, 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.

17.2.6

Nested DHCPv4 options (custom option spaces)

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

BIND 10 Guide

47 / 66

>
>
>
>
>
>
>
>
>

config
config
config
config
config
config
config
config
config

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

>
>
>
>
>
>
>
>
>

config
config
config
config
config
config
config
config
config

add Dhcp4/option-def
set Dhcp4/option-def[1]/name "subopt2"
set Dhcp4/option-def[1]/code 2
set Dhcp4/option-def[1]/space "isc"
set Dhcp4/option-def[1]/type "string"
set Dhcp4/option-def[1]/record-types ""
set Dhcp4/option-def[1]/array false
set Dhcp4/option-def[1]/encapsulate ""
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
config
config
config
config
config
config

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

>
>
>
>
>
>
>

config
config
config
config
config
config
config

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

>
>
>
>
>
>

config
config
config
config
config
config

add
set
set
set
set
set

Dhcp4/option-data
Dhcp4/option-data[2]/name "container"
Dhcp4/option-data[2]/space "dhcp4"
Dhcp4/option-data[2]/code 222
Dhcp4/option-data[2]/csv-format true
Dhcp4/option-data[2]/data ""

BIND 10 Guide

48 / 66

> 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 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.

17.3

Server Identifier in DHCPv4

The DHCPv4 protocol uses a "server identifier" for clients to be able to discriminate between several servers present on the same
link: this value is an IPv4 address of the server. When started for the first time, the DHCPv4 server will choose one of its IPv4
addresses as its server-id, and store the chosen value to a file. That file will be read by the server and the contained value used
whenever the server is subsequently started.
It is unlikely that this parameter should ever need to be changed. However, if such a need arises, stop the server, edit the file
and restart the server. (The file is named b10-dhcp4-serverid and by default is stored in the "var" subdirectory of the directory in
which BIND 10 is installed. This can be changed when BIND 10 is built by using "--localstatedir" on the "configure" command
line.) The file is a text file that should contain an IPv4 address. Spaces are ignored, and no extra characters are allowed in this
file.

17.4

Supported Standards

The following standards and draft standards are currently supported:

RFC 2131: Supported messages are DISCOVER, OFFER, REQUEST, RELEASE, ACK, and NAK.
RFC 2132: Supported options are: PAD (0), END(255), Message Type(53), DHCP Server Identifier (54), Domain Name (15),
DNS Servers (6), IP Address Lease Time (51), Subnet mask (1), and Routers (3).

17.5

DHCPv4 Server Limitations

These are the current limitations of the DHCPv4 server software. Most of them are reflections of the current stage of development
and should be treated as not implemented yet, rather than actual limitations.
On startup, the DHCPv4 server does not get the full configuration from BIND 10. To remedy this, after starting BIND 10,
modify any parameter and commit the changes, e.g.
> config show Dhcp4/renew-timer
Dhcp4/renew-timer 1000 integer (default)
> config set Dhcp4/renew-timer 1001
> config commit

During the initial IPv4 node configuration, the server is expected to send packets to a node that does not have IPv4 address
assigned yet. The server requires certain tricks (or hacks) to transmit such packets. This is not implemented yet, therefore
DHCPv4 server supports relayed traffic only (that is, normal point to point communication).
Upon start, the server will open sockets on all interfaces that are not loopback, are up and running and have IPv4 address.

BIND 10 Guide

49 / 66

The DHCPv4 server does not support BOOTP. That is a design choice and the limitation is permanent. If you have legacy
nodes that cant use DHCP and require BOOTP support, please use the latest version of ISC DHCP, available from http:
//www.isc.org/software/dhcp.
Interface detection is currently working on Linux only. See Section 19.1 for details.
The DHCPv4 server does not verify that assigned address is unused. According to RFC 2131, the allocating server should
verify that address is not used by sending ICMP echo request.
Address rebinding (REBIND) and duplication report (DECLINE) are not supported yet.
DNS Update is not yet supported.

BIND 10 Guide

50 / 66

Chapter 18

The DHCPv6 Server

18.1

Starting and Stopping the DHCPv6 Server

b10-dhcp6 is the BIND 10 DHCPv6 server and, like other parts of BIND 10, is configured through the bindctl program.
After starting BIND 10 and starting bindctl, the first step in configuring the server is to add b10-dhcp6 to the list of running
BIND 10 services.
> config add Init/components b10-dhcp6
> config set Init/components/b10-dhcp6/kind dispensable
> config commit

To remove b10-dhcp6 from the set of running services, the b10-dhcp4 is removed from list of Init components:
> config remove Init/components b10-dhcp6
> config commit

During start-up the server will detect available network interfaces and will attempt to open UDP sockets on all interfaces that are
up, running, are not loopback, are multicast-capable, and have IPv6 address assigned. It will then listen to incoming traffic.

18.2

DHCPv6 Server Configuration

Once the server has been started, it can be configured. To view the current configuration, use the following command in bindctl:
> config show Dhcp6

When starting the Dhcp6 daemon for the first time, the default configuration will be available. It will look similar to this:
> config show Dhcp6
Dhcp6/interface/ list (default)
Dhcp6/renew-timer 1000 integer (default)
Dhcp6/rebind-timer 2000 integer (default)
Dhcp6/preferred-lifetime 3000 integer (default)
Dhcp6/valid-lifetime 4000 integer (default)
Dhcp6/option-data [] list (default)
Dhcp6/lease-database/type "memfile" string (default)
Dhcp6/lease-database/name "" string (default)
Dhcp6/lease-database/user "" string (default)
Dhcp6/lease-database/host "" string (default)
Dhcp6/lease-database/password "" string (default)
Dhcp6/subnet6/ list

BIND 10 Guide

51 / 66

To change one of the parameters, simply follow the usual bindctl procedure. For example, to make the leases longer, change
their valid-lifetime parameter:
> config set Dhcp6/valid-lifetime 7200
> config commit

Most Dhcp6 parameters are of global scope and apply to all defined subnets, unless they are overridden on a per-subnet basis.
Note
With this version of BIND 10, there are a number of known limitations and problems in the DHCPv6 server. See Section 18.5.

18.2.1

Database Configuration

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.
Note
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 (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).
> 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.)
Note
The password is echoed when entered and is stored in clear text in the BIND 10 configuration database. Improved password
security will be added in a future version of BIND 10 DHCP
1 The server comes with an in-memory database ("memfile") configured as the default database. This is used for internal testing and is not supported. In
addition, it does not store lease information on disk: lease information will be lost if the server is restarted.

BIND 10 Guide

18.2.2

52 / 66

Subnet and Address Pool

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
config
config
config

add Dhcp6/subnet6
set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64"
set Dhcp6/subnet6[0]/pool [ "2001:db8:1::0 - 2001:db8:1::ffff" ]
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
fs 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
config
config
config

add Dhcp6/subnet6
set Dhcp6/subnet6[1]/subnet "2001:db8:beef::/48"
set Dhcp6/subnet6[1]/pool [ "2001:db8:beef::/48" ]
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.

18.2.3

Standard DHCPv6 options

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.
2.
3.
4.
5.
6.
7.

>
>
>
>
>
>
>

config
config
config
config
config
config
config

add Dhcp6/option-data
set Dhcp6/option-data[0]/name "dns-servers"
set Dhcp6/option-data[0]/code 23
set Dhcp6/option-data[0]/space "dhcp6"
set Dhcp6/option-data[0]/csv-format true
set Dhcp6/option-data[0]/data "2001:db8::cafe, 2001:db8::babe"
commit

BIND 10 Guide

53 / 66

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.
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. 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
config
config
config
config
config
config

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

Note
In future versions of BIND 10 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. 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.
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.

18.2.4

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

BIND 10 Guide

Name
preference
sip-server-dns
sip-server-addr
dns-servers
domain-search
nis-servers
nisp-servers
nis-domain-name
nisp-domain-name
sntp-servers
information-refresh-time
bcmcs-server-dns
bcmcs-server-addr
geoconf-civic
remote-id
subscriber-id
client-fqdn
pana-agent
new-posix-timezone
new-tzdb-timezone
ero
lq-query
client-data
clt-time
lq-relay-data
lq-client-link

54 / 66

Code
7
21
22
23
24
27
28
29
30
31
32
33
34
36
37
38
39
40
41
42
43
44
45
46
47
48

Type
uint8
fqdn
ipv6-address
ipv6-address
fqdn
ipv6-address
ipv6-address
fqdn
fqdn
ipv6-address
uint32
fqdn
ipv6-address
record
record
binary
record
ipv6-address
string
string
uint16
record
empty
uint32
record
ipv6-address
Table 18.1: List of standard DHCPv6 options

Array?
false
true
true
true
true
true
true
true
true
true
false
true
true
false
false
false
false
true
false
false
true
false
false
false
false
true

BIND 10 Guide

>
>
>
>
>
>
>
>
>

config
config
config
config
config
config
config
config
config

55 / 66

add Dhcp6/option-def
set Dhcp6/option-def[0]/name "foo"
set Dhcp6/option-def[0]/code 100
set Dhcp6/option-def[0]/type "uint32"
set Dhcp6/option-def[0]/array false
set Dhcp6/option-def[0]/record-types ""
set Dhcp6/option-def[0]/space "dhcp6"
set Dhcp6/option-def[0]/encapsulate ""
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
config
config
config
config
config
config

add Dhcp6/option-data
set Dhcp6/option-data[0]/name "foo"
set Dhcp6/option-data[0]/code 100
set Dhcp6/option-data[0]/space "dhcp6"
set Dhcp6/option-data[0]/csv-format true
set Dhcp6/option-data[0]/data "12345"
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
config
config
config
config
config
config
config

add
set
set
set
set
set
set
set

Dhcp6/option-def
Dhcp6/option-def[0]/name "bar"
Dhcp6/option-def[0]/code 101
Dhcp6/option-def[0]/space "dhcp6"
Dhcp6/option-def[0]/type "record"
Dhcp6/option-def[0]/array false
Dhcp6/option-def[0]/record-types "ipv6-address, uint16, string"
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.
The values of the option are set as follows:
>
>
>
>
>
>
>

config
config
config
config
config
config
config

add Dhcp6/option-data
set Dhcp6/option-data[0]/name "bar"
set Dhcp6/option-data[0]/space "dhcp6"
set Dhcp6/option-data[0]/code 101
set Dhcp6/option-data[0]/csv-format true
set Dhcp6/option-data[0]/data "2001:db8:1::10, 123, Hello World"
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.

BIND 10 Guide

18.2.5

56 / 66

DHCPv6 vendor specific options

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 vendorspecific 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
config
config
config
config
config
config
config
config

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

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

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

config
config
config
config
config
config
config

18.2.6

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

Nested DHCPv6 options (custom option spaces)

It is sometimes useful to define completely new option spaces. This is useful if the user wants his new option to convey suboptions 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).
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
config
config
config
config
config
config
config
config

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

BIND 10 Guide

>
>
>
>
>
>
>
>
>
>

config
config
config
config
config
config
config
config
config

57 / 66

add Dhcp6/option-def
set Dhcp6/option-def[1]/name "subopt2"
set Dhcp6/option-def[1]/code 2
set Dhcp6/option-def[1]/space "isc"
set Dhcp6/option-def[1]/type "string"
set Dhcp6/option-def[1]/record-types ""
set Dhcp6/option-def[1]/array false
set Dhcp6/option-def[1]/encapsulate ""
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
config
config
config
config
config
config
config
config

add Dhcp6/option-def
set Dhcp6/option-def[2]/name "container"
set Dhcp6/option-def[2]/code 102
set Dhcp6/option-def[2]/space "dhcp6"
set Dhcp6/option-def[2]/type "empty"
set Dhcp6/option-def[2]/array false
set Dhcp6/option-def[2]/record-types ""
set Dhcp6/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" which imposes that this option does not carry any data other than sub-options.
Finally, we can set values for the new options:
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

config
config
config
config
config
config
config

add Dhcp6/option-data
set Dhcp6/option-data[0]/name "subopt1"
set Dhcp6/option-data[0]/space "isc"
set Dhcp6/option-data[0]/code 1
set Dhcp6/option-data[0]/csv-format true
set Dhcp6/option-data[0]/data "2001:db8::abcd"
commit

config
config
config
config
config
config
config

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

config
config
config
config
config
config
config

add Dhcp6/option-data
set Dhcp6/option-data[2]/name "container"
set Dhcp6/option-data[2]/space "dhcp6"
set Dhcp6/option-data[2]/code 102
set Dhcp6/option-data[2]/csv-format true
set Dhcp6/option-data[2]/data ""
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 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

BIND 10 Guide

58 / 66

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.

18.2.7

Subnet Selection

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. 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
config
config
config
config

18.2.8

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

DHCPv6 Relays

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 clients request.
The second mechanism is based on interface-id options. While forwarding a clients 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
config
config
config
config

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

BIND 10 Guide

18.3

59 / 66

Server Identifier in DHCPv6

The DHCPv6 protocol uses a "server identifier" (also known as a DUID) for clients to be able to discriminate between several
servers present on the same link. There are several types of DUIDs defined, but RFC 3315 instructs servers to use DUID-LLT if
possible. This format consists of a link-layer (MAC) address and a timestamp. When started for the first time, the DHCPv6 server
will automatically generate such a DUID and store the chosen value to a file. That file is read by the server and the contained
value used whenever the server is subsequently started.
It is unlikely that this parameter should ever need to be changed. However, if such a need arises, stop the server, edit the file
and restart the server. (The file is named b10-dhcp6-serverid and by default is stored in the "var" subdirectory of the directory in
which BIND 10 is installed. This can be changed when BIND 10 is built by using "--localstatedir" on the "configure" command
line.) The file is a text file that contains double digit hexadecimal values separated by colons. This format is similar to typical
MAC address format. Spaces are ignored. No extra characters are allowed in this file.

18.4

Supported Standards

The following standards and draft standards are currently supported:

RFC 3315: Supported messages are SOLICIT, ADVERTISE, REQUEST, RELEASE, RENEW, and REPLY.
RFC 3646: Supported option is DNS_SERVERS.

18.5

DHCPv6 Server Limitations

These are the current limitations and known problems with the DHCPv6 server software. Most of them are reflections of the
early stage of development and should be treated as not implemented yet, rather than actual limitations.
On startup, the DHCPv6 server does not get the full configuration from BIND 10. To remedy this, after starting BIND 10,
modify any parameter and commit the changes, e.g.
> config show Dhcp6/renew-timer
Dhcp6/renew-timer 1000 integer (default)
> config set Dhcp6/renew-timer 1001
> config commit

Temporary addresses are not supported.

Prefix delegation is not supported.
Rebinding (REBIND), confirmation (CONFIRM), and duplication report (DECLINE) are not yet supported.
DNS Update is not supported.
Interface detection is currently working on Linux only. See Section 19.1 for details.

BIND 10 Guide

60 / 66

Chapter 19

libdhcp++ library
libdhcp++ is a common library written in C++ that handles many DHCP-related tasks, including:
DHCPv4 and DHCPv6 packets parsing, manipulation and assembly
Option parsing, manipulation and assembly
Network interface detection
Socket operations such as creation, data transmission and reception and socket closing.
While this library is currently used by BIND 10 DHCP, it is designed to be a portable, universal library, useful for any kind of
DHCP-related software.

19.1

Interface detection

Both the DHCPv4 and DHCPv6 components share network interface detection routines. Interface detection is currently only
supported on Linux systems.
For non-Linux systems, there is currently a stub implementation provided. The interface manager detects loopback interfaces
only as their name (lo or lo0) can be easily predicted. Please contact the BIND 10 development team if you are interested in
running DHCP components on systems other than Linux.

BIND 10 Guide

61 / 66

Chapter 20

Statistics
The b10-stats process is started by b10-init. It periodically collects statistics data from various modules and aggregates it.
This stats daemon provides commands to identify if it is running, show specified or all statistics data, and show specified or all
statistics data schema. For example, using bindctl:
> Stats show
{
"Auth": {
"opcode.iquery": 0,
"opcode.notify": 10,
"opcode.query": 869617,
...
"queries.tcp": 1749,
"queries.udp": 867868
},
"Init": {
"boot_time": "2011-01-20T16:59:03Z"
},
"Stats": {
"boot_time": "2011-01-20T16:59:05Z",
"last_update_time": "2011-01-20T17:04:05Z",
"lname": "4d3869d9_a@jreed.example.net",
"report_time": "2011-01-20T17:04:06Z",
"timestamp": 1295543046.823504
}
}

BIND 10 Guide

62 / 66

Chapter 21

Logging
21.1

Logging configuration

The logging system in BIND 10 is configured through the Logging module. All BIND 10 modules will look at the configuration
in Logging to see what should be logged and to where.

21.1.1

Loggers

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).
21.1.1.1

name (string)

Each logger in the system has a name, the name being that of the component using it to log messages. For instance, if you want
to configure logging for the resolver module, you add an entry for a logger named Resolver. This configuration will then be
used by the loggers in the Resolver module, and all the libraries used by it.
If you want to specify logging for one specific library within the module, you set the name to module.library . For example,
the logger used by the nameserver address store component has the full name of Resolver.nsas. If there is no entry in Logging
for a particular library, it will use the configuration given for the module.
To illustrate this, suppose you want the cache library to log messages of severity DEBUG, and the rest of the resolver code to log
messages of severity INFO. To achieve this you specify two loggers, one with the name Resolver and severity INFO, and one
with the name Resolver.cache with severity DEBUG. As there are no entries for other libraries (e.g. the nsas), they will use the
configuration for the module (Resolver), so giving the desired behavior.
One special case is that of a module name of * (asterisks), which is interpreted as any module. You can set global logging
options by using this, including setting the logging configuration for a library that is used by multiple modules (e.g. *.config
specifies the configuration library code in whatever module is using it).
If there are multiple logger specifications in the configuration that might match a particular logger, the specification with the more
specific logger name takes precedence. For example, if there are entries for both * and Resolver, the resolver module and
all libraries it uses will log messages according to the configuration in the second entry (Resolver). All other modules will
use the configuration of the first entry (*). If there was also a configuration entry for Resolver.cache, the cache library within
the resolver would use that in preference to the entry for Resolver.

BIND 10 Guide

63 / 66

One final note about the naming. When specifying the module name within a logger, use the name of the module as specified in
bindctl, e.g. Resolver for the resolver module, Xfrout for the xfrout module, etc. When the message is logged, the message
will include the name of the logger generating the message, but with the module name replaced by the name of the process
implementing the module (so for example, a message generated by the Auth.cache logger will appear in the output with a
logger name of b10-auth.cache).
21.1.1.2

severity (string)

This specifies the category of messages logged. Each message is logged with an associated severity which may be one of the
following (in descending order of severity):
FATAL
ERROR
WARN
INFO
DEBUG
When the severity of a logger is set to one of these values, it will only log messages of that severity, and the severities above it.
The severity may also be set to NONE, in which case all messages from that logger are inhibited.
21.1.1.3

output_options (list)

Each logger can have zero or more output_options. These specify where log messages are sent to. These are explained in
detail below.
The other options for a logger are:
21.1.1.4

debuglevel (integer)

When a loggers severity is set to DEBUG, this value specifies what debug messages should be printed. It ranges from 0 (least
verbose) to 99 (most verbose).
If severity for the logger is not DEBUG, this value is ignored.
21.1.1.5

additive (true or false)

If this is true, the output_options from the parent will be used. For example, if there are two loggers configured; Resolver
and Resolver.cache, and additive is true in the second, it will write the log messages not only to the destinations specified
for Resolver.cache, but also to the destinations as specified in the output_options in the logger named Resolver.

21.1.2

Output Options

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.
21.1.2.1

destination (string)

The destination is the type of output. It can be one of:

console
file
syslog

BIND 10 Guide

21.1.2.2

64 / 66

output (string)

Depending on what is set as the output destination, this value is interpreted as follows:
destination is console The value of output must be one of stdout (messages printed to standard output) or stderr
(messages printed to standard error).
Note: if output is set to stderr and a lot of messages are produced in a short time (e.g. if the logging level is set to
DEBUG), you may occasionally see some messages jumbled up together. This is due to a combination of the way that
messages are written to the screen and the unbuffered nature of the standard error stream. If this occurs, it is recommended
that output be set to stdout.
destination is file The value of output is interpreted as a file name; log messages will be appended to this file.
destination is syslog The value of output is interpreted as the syslog facility (e.g. local0) that should be used for log
messages.
The other options for output_options are:
21.1.2.2.1

flush (true of false)

Flush buffers after each log message. Doing this will reduce performance but will ensure that if the program terminates abnormally, all messages up to the point of termination are output.
21.1.2.2.2

maxsize (integer)

Only relevant when destination is file, this is maximum file size of output files in bytes. When the maximum size is reached, the
file is renamed and a new file opened. (For example, a ".1" is appended to the name if a ".1" file exists, it is renamed ".2", etc.)
If this is 0, no maximum file size is used.
Note
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 BIND 10 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 BIND 10, it shouldnt happen. Even for older versions it is normally expected to happen rarely unless the log messages
are produced very frequently by multiple different processes.

21.1.2.2.3

maxver (integer)

Maximum number of old log files to keep around when rolling the output file. Only relevant when destination is file.

21.1.3

Example session

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.
Lets first add a default logger:

BIND 10 Guide

65 / 66

> 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. Lets 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 arent the values we are looking for.

>
>
>
>

config
config
config
config

set
set
set
set

Logging/loggers[0]/output_options[0]/destination file
Logging/loggers[0]/output_options[0]/output /var/log/bind10.log
Logging/loggers[0]/output_options[0]/maxsize 204800
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 lets commit it before we add the configuration for the authoritative servers logger.
>

config commit

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

BIND 10 Guide

>
>
>
>
>
>
>
>

config
config
config
config
config
config
config
config

66 / 66

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

And thats 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 *.

21.2

Logging Message Format

Each message written by BIND 10 to the configured logging destinations comprises a number of components that identify the
origin of the message and, if the message indicates a problem, information about the problem that may be useful in fixing it.
Consider the message below logged to a file:
2011-06-15 13:48:22.034 ERROR [b10-resolver.asiolink]
ASIODNS_OPENSOCK error 111 opening TCP socket to 127.0.0.1(53)

Note: the layout of messages written to the system logging file (syslog) may be slightly different. This message has been split
across two lines here for display reasons; in the logging file, it will appear on one line.)
The log message comprises a number of components:
2011-06-15 13:48:22.034 The date and time at which the message was generated.
ERROR The severity of the message.
[b10-resolver.asiolink] The source of the message. This comprises two components: the BIND 10 process generating the
message (in this case, b10-resolver) and the module within the program from which the message originated (which in the
example is the asynchronous I/O link module, asiolink).
ASIODNS_OPENSOCK The message identification. Every message in BIND 10 has a unique identification, which can be used
as an index into the BIND 10 Messages Manual (http://bind10.isc.org/docs/bind10-messages.html)
from which more information can be obtained.
error 111 opening TCP socket to 127.0.0.1(53) A brief description of the cause of the problem. Within this text, information
relating to the condition that caused the message to be logged will be included. In this example, error number 111 (an
operating system-specific error number) was encountered when trying to open a TCP connection to port 53 on the local
system (address 127.0.0.1). The next step would be to find out the reason for the failure by consulting your systems
documentation to identify what error number 111 means.