This is the reference guide for BIND 10 version - 20120127.
Copyright © 2010-2012 Internet Systems Consortium, Inc.
Abstract
BIND 10 is a framework that features Domain Name System +
This is the reference guide for BIND 10 version + 20120405.
Copyright © 2010-2012 Internet Systems Consortium, Inc.
Abstract
BIND 10 is a framework that features Domain Name System (DNS) suite and Dynamic Host Configuration Protocol (DHCP) servers 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 20120127. + This is the reference guide for BIND 10 version 20120405. 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. -
Table of Contents
Table of Contents
Table of Contents
Table of Contents
ISC would like to acknowledge generous support for BIND 10 development of DHCPv4 and DHCPv6 components provided - by Comcast.
Table of Contents
+ by Comcast.
Table of Contents
BIND is the popular implementation of a DNS server, developer interfaces, and DNS tools. BIND 10 is a rewrite of BIND 9. BIND 10 is written in C++ and Python @@ -22,8 +22,8 @@ provides forwarding.
This guide covers the experimental prototype of - BIND 10 version 20120127. -
+ BIND 10 version 20120405. +
BIND 10 builds have been tested on Debian GNU/Linux 5 and unstable, Ubuntu 9.10, NetBSD 5, Solaris 10, FreeBSD 7 and 8, CentOS Linux 5.3, and MacOS 10.6. @@ -162,7 +162,7 @@ and, of course, DNS. These include detailed developer documentation and code examples. -
Table of Contents
Table of Contents
In addition to the run-time requirements, building BIND 10 from source code requires various development include headers.
@@ -224,14 +224,14 @@ the Git code revision control system or as a downloadable tar file. It may also be available in pre-compiled ready-to-use packages from operating system vendors. -
+
Downloading a release tar file is the recommended method to obtain the source code.
The BIND 10 releases are available as tar file downloads from ftp://ftp.isc.org/isc/bind10/. Periodic development snapshots may also be available. -
Downloading this "bleeding edge" code is recommended only for developers or advanced users. Using development code in a production environment is not recommended. @@ -265,7 +265,7 @@ autoheader, automake, and related commands. -
BIND 10 uses the GNU Build System to discover build environment details. To generate the makefiles using the defaults, simply run: @@ -296,16 +296,16 @@
If the configure fails, it may be due to missing or old dependencies. -
After the configure step is complete, to build the executables from the C++ code and prepare the Python scripts, run:
$ make-
To install the BIND 10 executables, support files, and documentation, run:
$ make install-
The install step may require superuser privileges.
The following is the layout of the complete BIND 10 installation:
bin/ —
@@ -361,12 +361,8 @@
master process will also start up
b10-cmdctl for administration tools to
communicate with the system,
- b10-auth for authoritative DNS service,
- b10-stats for statistics collection,
- b10-stats-httpd for statistics reporting,
- b10-xfrin for inbound DNS zone transfers,
- b10-xfrout for outbound DNS zone transfers,
- and b10-zonemgr for secondary service.
+ b10-stats for statistics collection, and
+ b10-stats-httpd for statistics reporting.
To start the BIND 10 service, simply run bind10.
Run it with the --verbose switch to
@@ -384,12 +380,7 @@
The configuration is in the Boss/components section. Each element
represents one component, which is an abstraction of a process
(currently there's also one component which doesn't represent
- a process). If you didn't want to transfer out at all (your server
- is a slave only), you would just remove the corresponding component
- from the set, like this and the process would be stopped immediately
- (and not started on the next startup):
-
>config remove Boss/components b10-xfrout->config commit
+ a process).
To add a process to the set, let's say the resolver (which not started by default), you would do this: @@ -407,7 +398,7 @@ during startup or shutdown. Unless specified, the component is started in 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: -
Table 3.1.
| Component | Special | Description |
|---|---|---|
| b10-auth | auth | Authoritative server |
| b10-resolver | resolver | The resolver |
| b10-cmdctl | cmdctl | The command control (remote control interface) |
+
Table 3.1.
| Component | Special | Description |
|---|---|---|
| b10-auth | auth | Authoritative server |
| b10-resolver | resolver | The resolver |
| b10-cmdctl | cmdctl | The command control (remote control interface) |
The kind specifies how a failure of the component should be handled. If it is set to “dispensable” @@ -446,7 +437,7 @@ This system allows you to start the same component multiple times (by including it in the configuration with different names, but the same process setting). However, the rest of the system doesn't expect - such situation, so it would probably not do what you want. Such + such a situation, so it would probably not do what you want. Such support is yet to be implemented.
The configuration is quite powerful, but that includes @@ -454,10 +445,10 @@ b10-cmdctl, but then you couldn't change it back the usual way, as it would require it to be running (you would have to find and edit the configuration - directly). Also, some modules might have dependencies - -- b10-stats-httpd need + directly). Also, some modules might have dependencies: + b10-stats-httpd needs b10-stats, b10-xfrout - needs the b10-auth to be running, etc. + needs b10-auth to be running, etc. @@ -511,7 +502,7 @@ manager via b10-cmdctl's REST-ful interface. b10-cmdctl is covered in Chapter 6, Remote control daemon.
- The development prototype release only provides the
+ The development prototype release only provides
bindctl as a user interface to
b10-cmdctl.
Upcoming releases will provide another interactive command-line
@@ -598,7 +589,7 @@
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 timesout in 1200 seconds
+ 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.
@@ -635,32 +626,92 @@ shutdown the details and relays (over a b10-msgq command channel) the configuration on to the specified module.
-
+
Table of Contents
The b10-auth is the authoritative DNS server. It supports EDNS0 and DNSSEC. It supports IPv6. Normally it is started by the bind10 master process. -
+
b10-auth is configured via the b10-cfgmgr configuration manager. The module name is “Auth”. - The configuration data item is: + The configuration data items are:
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 and the
+ origin (default domain).
+
+ By default, this is empty.
+
+ + In this development version, 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. +
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.
+ statistics-interval is the timer interval
+ in seconds for b10-auth to share its
+ statistics information to
+ b10-stats(8).
+ Statistics updates can be disabled by setting this to 0.
+ The default is 60.
- The configuration command is: + The configuration commands are: -
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”).
+
+ + In this development version, currently this only supports the + IN class and the memory data source. +
pid argument to
+ select the process ID to stop.
+ (Note that the BIND 10 boss process may restart this service
+ if configured.)
-
+
For the development prototype release, b10-auth
supports a SQLite3 data source backend and in-memory data source
backend.
@@ -672,11 +723,57 @@ This may be a temporary setting until then.
(The full path is what was defined at build configure time for
--localstatedir.
The default is /usr/local/var/.)
- This data file location may be changed by defining the
- “database_file” configuration.
-
+ This data file location may be changed by defining the + “database_file” configuration. +
+ + The following commands to bindctl + provide an example of configuring an in-memory data + source containing the “example.com” zone + with the zone file named “example.com.zone”: + + + +
>config add Auth/datasources+>config set Auth/datasources[0]/type "+>memory"config add Auth/datasources[0]/zones+>config set Auth/datasources[0]/zones[0]/origin "+>example.com"config set Auth/datasources[0]/zones[0]/file "+>example.com.zone"config commit
+ + The authoritative server will begin serving it immediately + after it is loaded. +
+ Use the Auth loadzone command in + bindctl to reload a changed master + file into memory; for example: + +
> Auth loadzone origin="example.com"
++ +
+ By default, the memory data source is disabled; it must be
+ configured explicitly. To disable all the in-memory zones,
+ specify a null list for Auth/datasources:
+
+
+
+
>config set Auth/datasources/ []+>config commit
+
+ The following example stops serving a specific zone: + +
>config remove Auth/datasources[+>0]/zones[0]config commit
+
+ (Replace the list number(s) in
+ datasources[
+ and/or 0]zones[
+ for the relevant zone as needed.)
+
+ 0]
RFC 1035 style DNS master zone files may imported - into a BIND 10 data source by using the + into a BIND 10 SQLite3 data source by using the b10-loadzone utility.
b10-loadzone supports the following @@ -693,7 +790,7 @@ This may be a temporary setting until then. default origin for loaded zone file records.
In the development prototype release, only the SQLite3 back
- end is used.
+ end is used by b10-loadzone.
By default, it stores the zone data in
/usr/local/var/bind10-devel/zone.sqlite3
unless the -d switch is used to set the
@@ -703,7 +800,7 @@ This may be a temporary setting until then.
If you reload a zone already existing in the database,
all records from that prior zone disappear and a whole new set
appears.
-
Table of Contents
+
Table of Contents
Incoming zones are transferred using the b10-xfrin process which is started by bind10. When received, the zone is stored in the corresponding BIND 10 @@ -721,7 +818,7 @@ This may be a temporary setting until then. In the current development release of BIND 10, incoming zone transfers are only available for SQLite3-based data sources, that is, they don't work for an in-memory data source. -
In practice, you need to specify a list of secondary zones to
enable incoming zone transfers for these zones (you can still
trigger a zone transfer manually, without a prior configuration
@@ -737,7 +834,7 @@ This may be a temporary setting until then.
> config commit
(We assume there has been no zone configuration before). -
As noted above, b10-xfrin uses AXFR for
zone transfers by default. To enable IXFR for zone transfers
for a particular zone, set the use_ixfr
@@ -789,7 +886,7 @@ This may be a temporary setting until then.
(i.e. no SOA record for it), b10-zonemgr
will automatically tell b10-xfrin
to transfer the zone in.
-
To manually trigger a zone transfer to retrieve a remote zone, you may use the bindctl utility. For example, at the bindctl prompt run: @@ -835,25 +932,20 @@ Xfrout/transfer_acl[0] {"action": "ACCEPT"} any (default)
>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 Xfrout and Auth will use the system wide keyring to check - TSIGs in the incomming messages and to sign responses.
+ TSIGs in the incoming messages and to sign responses.
The way to specify zone specific configuration (ACLs, etc) is likely to be changed. -
Table of Contents
The b10-resolver process is started by bind10.
The main bind10 process can be configured to select to run either the authoritative or resolver or both. - By default, it starts the authoritative service. - - - You may change this using bindctl, for example: + By default, it doesn't start either one. You may change this using + bindctl, for example:
->config remove Boss/components b10-xfrout->config remove Boss/components b10-xfrin->config remove Boss/components b10-auth>config add Boss/components b10-resolver>config set Boss/components/b10-resolver/special resolver>config set Boss/components/b10-resolver/kind needed@@ -877,7 +969,7 @@ Xfrout/transfer_acl[0] {"action": "ACCEPT"} any (default)
(Replace the “2”
as needed; run “config show
- Resolver/listen_on” if needed.)
+ Resolver/listen_on” if needed.)
By default, the b10-resolver daemon only accepts
DNS queries from the localhost (127.0.0.1 and ::1).
The Resolver/query_acl configuration may
@@ -910,7 +1002,7 @@ Xfrout/transfer_acl[0] {"action": "ACCEPT"} any (default)
(Replace the “2”
as needed; run “config show
Resolver/query_acl” if needed.)
This prototype access control configuration - syntax may be changed.
To enable forwarding, the upstream address and port must be configured to forward queries to, such as: @@ -1222,7 +1314,7 @@ eth0 fe80::21e:8cff:fe9b:7349 } }
-
Table of Contents
Table of Contents
The logging system in BIND 10 is configured through the Logging module. All BIND 10 modules will look at the @@ -1231,7 +1323,7 @@ eth0 fe80::21e:8cff:fe9b:7349 -
+
Within BIND 10, a message is logged through a component called a "logger". Different parts of BIND 10 log messages @@ -1242,7 +1334,7 @@ eth0 fe80::21e:8cff:fe9b:7349 In the Logging module, you can specify the configuration for zero or more loggers; any that are not specified will - take appropriate default values.. + take appropriate default values.
@@ -1252,7 +1344,7 @@ eth0 fe80::21e:8cff:fe9b:7349
(what to log), and the output_options
(where to log).
-
+
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, @@ -1325,7 +1417,7 @@ eth0 fe80::21e:8cff:fe9b:7349 “Auth.cache” logger will appear in the output with a logger name of “b10-auth.cache”). -
This specifies the category of messages logged. Each message is logged with an associated severity which @@ -1341,7 +1433,7 @@ eth0 fe80::21e:8cff:fe9b:7349 -
Each logger can have zero or more
output_options. These specify where log
@@ -1351,7 +1443,7 @@ eth0 fe80::21e:8cff:fe9b:7349
The other options for a logger are:
-
When a logger's severity is set to DEBUG, this value specifies what debug messages should be printed. It ranges @@ -1360,7 +1452,7 @@ eth0 fe80::21e:8cff:fe9b:7349 If severity for the logger is not DEBUG, this value is ignored. -
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.
-
+
The destination is the type of output. It can be one of: -
Depending on what is set as the output destination, this value is interpreted as follows: -
destination is “console”destination is “console”The value of output must be one of “stdout” (messages printed to standard output) or “stderr” (messages printed to standard error). -
destination is “file”+ 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”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:
-
+
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. -
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. @@ -1421,11 +1521,11 @@ eth0 fe80::21e:8cff:fe9b:7349 etc.)
If this is 0, no maximum file size is used. -
In this example we want to set the global logging to
write to the file /var/log/my_bind10.log,
@@ -1519,7 +1619,7 @@ Logging/loggers[0]/output_options[0]/maxver 0 integer (default)
>config set Logging/loggers[0]/output_options[0]/destination file>config set Logging/loggers[0]/output_options[0]/output /var/log/bind10.log->config set Logging/loggers[0]/output_options[0]/maxsize 30000+>config set Logging/loggers[0]/output_options[0]/maxsize 204800>config set Logging/loggers[0]/output_options[0]/maxver 8
@@ -1538,7 +1638,7 @@ 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 30000 integer (modified) +Logging/loggers[0]/output_options[0]/maxsize 204800 integer (modified) Logging/loggers[0]/output_options[0]/maxver 8 integer (modified)
@@ -1586,7 +1686,7 @@ Logging/loggers[0]/output_options[0]/maxver 8 integer (modified) And every module will now be using the values from the logger named “*”. -
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
diff --git a/doc/guide/bind10-guide.txt b/doc/guide/bind10-guide.txt
index aad5c04206..cf81af6b3f 100644
--- a/doc/guide/bind10-guide.txt
+++ b/doc/guide/bind10-guide.txt
@@ -2,9 +2,9 @@
Administrator Reference for BIND 10
- This is the reference guide for BIND 10 version 20120127.
+ This is the reference guide for BIND 10 version 20120405.
- Copyright (c) 2010-2012 Internet Systems Consortium, Inc.
+ Copyright © 2010-2012 Internet Systems Consortium, Inc.
Abstract
@@ -14,7 +14,7 @@ Administrator Reference for BIND 10
for controlling authoritative and recursive DNS servers, and experimental
DHCPv4 and DHCPv6 servers.
- This is the reference guide for BIND 10 version 20120127. The most
+ This is the reference guide for BIND 10 version 20120405. 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.
@@ -79,6 +79,8 @@ Administrator Reference for BIND 10
8.2. Data Source Backends
+ 8.2.1. In-memory Data Source
+
8.3. Loading Master Zones Files
9. Incoming Zone Transfers
@@ -149,12 +151,12 @@ Preface
1. Acknowledgements
-1. Acknowledgements
+1. Acknowledgements
ISC would like to acknowledge generous support for BIND 10 development of
DHCPv4 and DHCPv6 components provided by Comcast.
-Chapter 1. Introduction
+Chapter 1. Introduction
Table of Contents
@@ -172,9 +174,9 @@ Chapter 1. Introduction
DNS. BIND 10 provides a EDNS0- and DNSSEC-capable authoritative DNS server
and a caching recursive name server which also provides forwarding.
- This guide covers the experimental prototype of BIND 10 version 20120127.
+ This guide covers the experimental prototype of BIND 10 version 20120405.
-1.1. Supported Platforms
+1.1. Supported Platforms
BIND 10 builds have been tested on Debian GNU/Linux 5 and unstable, Ubuntu
9.10, NetBSD 5, Solaris 10, FreeBSD 7 and 8, CentOS Linux 5.3, and MacOS
@@ -182,7 +184,7 @@ Chapter 1. Introduction
is planned for BIND 10 to build, install and run on Windows and standard
Unix-type platforms.
-1.2. Required Software
+1.2. Required Software
BIND 10 requires at least Python 3.1 (http://www.python.org/). It has also
been tested with Python 3.2.
@@ -208,7 +210,7 @@ Chapter 1. Introduction
installation nor standard packages collections. You may need to install
them separately.
-1.3. Starting and Stopping the Server
+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.
@@ -221,44 +223,43 @@ Chapter 1. Introduction
processes as needed. The processes started by the bind10 command have
names starting with "b10-", including:
- o b10-auth -- Authoritative DNS server. This process serves DNS
- requests.
- o b10-cfgmgr -- Configuration manager. This process maintains all of the
+ o b10-auth — Authoritative DNS server. This process serves DNS requests.
+ o b10-cfgmgr — Configuration manager. This process maintains all of the
configuration for BIND 10.
- o b10-cmdctl -- Command and control service. This process allows
- external control of the BIND 10 system.
- o b10-msgq -- Message bus daemon. This process coordinates communication
+ o b10-cmdctl — Command and control service. This process allows external
+ control of the BIND 10 system.
+ o b10-msgq — Message bus daemon. This process coordinates communication
between all of the other BIND 10 processes.
- o b10-resolver -- Recursive name server. This process handles incoming
+ o b10-resolver — Recursive name server. This process handles incoming
queries.
- o b10-sockcreator -- Socket creator daemon. This process creates sockets
+ o b10-sockcreator — Socket creator daemon. This process creates sockets
used by network-listening BIND 10 processes.
- o b10-stats -- Statistics collection daemon. This process collects and
+ o b10-stats — Statistics collection daemon. This process collects and
reports statistics data.
- o b10-stats-httpd -- HTTP server for statistics reporting. This process
+ o b10-stats-httpd — HTTP server for statistics reporting. This process
reports statistics data in XML format over HTTP.
- o b10-xfrin -- Incoming zone transfer service. This process is used to
+ o 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.
- o b10-xfrout -- Outgoing zone transfer service. This process is used to
+ o b10-xfrout — Outgoing zone transfer service. This process is used to
handle transfer requests to send a local zone to a remote secondary
server, when acting as a master server.
- o b10-zonemgr -- Secondary manager. This process keeps track of timers
+ o b10-zonemgr — Secondary manager. This process keeps track of timers
and other necessary information for BIND 10 to act as a slave server.
These are ran automatically by bind10 and do not need to be run manually.
-1.4. Managing BIND 10
+1.4. Managing BIND 10
Once BIND 10 is running, a few commands are used to interact directly with
the system:
- o bindctl -- interactive administration interface. This is a low-level
+ o bindctl — interactive administration interface. This is a low-level
command-line tool which allows a developer or an experienced
administrator to control BIND 10.
- o b10-loadzone -- zone file loader. This tool will load standard
+ o b10-loadzone — zone file loader. This tool will load standard
masterfile-format zone files into BIND 10.
- o b10-cmdctl-usermgr -- user access control. This tool allows an
+ o 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
@@ -268,7 +269,7 @@ Chapter 1. Introduction
Python for the message bus, configuration backend, and, of course, DNS.
These include detailed developer documentation and code examples.
-Chapter 2. Installation
+Chapter 2. Installation
Table of Contents
@@ -290,7 +291,7 @@ Chapter 2. Installation
2.3.6. Install Hierarchy
-2.1. Building Requirements
+2.1. Building Requirements
In addition to the run-time requirements, building BIND 10 from source
code requires various development include headers.
@@ -316,7 +317,7 @@ Chapter 2. Installation
Visit the wiki at http://bind10.isc.org/wiki/SystemSpecificNotes for
system-specific installation tips.
-2.2. Quick start
+2.2. Quick start
Note
@@ -327,48 +328,48 @@ Chapter 2. Installation
To quickly get started with BIND 10, follow these steps.
- 1. Install required run-time and build dependencies.
- 2. Download the BIND 10 source tar file from
+  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:
+  3. Extract the tar file:
$ gzcat bind10-VERSION.tar.gz | tar -xvf -
- 4. Go into the source and run configure:
+  4. Go into the source and run configure:
$ cd bind10-VERSION
$ ./configure
- 5. Build it:
+  5. Build it:
$ make
- 6. Install it (to default /usr/local):
+  6. Install it (to default /usr/local):
$ make install
- 7. Start the server:
+  7. Start the server:
$ /usr/local/sbin/bind10
- 8. Test it; for example:
+  8. Test it; for example:
$ dig @127.0.0.1 -c CH -t TXT authors.bind
- 9. Load desired zone file(s), for example:
+  9. Load desired zone file(s), for example:
$ b10-loadzone your.zone.example.org
- 10. Test the new zone.
+ 10. Test the new zone.
-2.3. Installation from source
+2.3. Installation from source
BIND 10 is open source software written in C++ and Python. It is freely
available in source code form from ISC via the Git code revision control
system or as a downloadable tar file. It may also be available in
pre-compiled ready-to-use packages from operating system vendors.
- 2.3.1. Download Tar File
+ 2.3.1. Download Tar File
Downloading a release tar file is the recommended method to obtain the
source code.
@@ -377,7 +378,7 @@ Chapter 2. Installation
ftp://ftp.isc.org/isc/bind10/. Periodic development snapshots may also be
available.
- 2.3.2. Retrieve from Git
+ 2.3.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
@@ -392,7 +393,7 @@ Chapter 2. Installation
The latest development code, including 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".
+ The leading development is done in the “master”.
The code can be checked out from git://git.bind10.isc.org/bind10; for
example:
@@ -405,7 +406,7 @@ Chapter 2. Installation
the --install switch. This will run autoconf, aclocal, libtoolize,
autoheader, automake, and related commands.
- 2.3.3. Configure before the build
+ 2.3.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:
@@ -440,14 +441,14 @@ Chapter 2. Installation
If the configure fails, it may be due to missing or old dependencies.
- 2.3.4. Build
+ 2.3.4. Build
After the configure step is complete, to build the executables from the
C++ code and prepare the Python scripts, run:
$ make
- 2.3.5. Install
+ 2.3.5. Install
To install the BIND 10 executables, support files, and documentation, run:
@@ -457,22 +458,22 @@ Chapter 2. Installation
The install step may require superuser privileges.
- 2.3.6. Install Hierarchy
+ 2.3.6. Install Hierarchy
The following is the layout of the complete BIND 10 installation:
- o bin/ -- general tools and diagnostic clients.
- o etc/bind10-devel/ -- configuration files.
- o lib/ -- libraries and python modules.
- o libexec/bind10-devel/ -- executables that a user wouldn't normally run
+ o bin/ — general tools and diagnostic clients.
+ o etc/bind10-devel/ — configuration files.
+ o lib/ — libraries and python modules.
+ o libexec/bind10-devel/ — executables that a user wouldn't normally run
directly and are not run independently. These are the BIND 10 modules
which are daemons started by the bind10 tool.
- o sbin/ -- commands used by the system administrator.
- o share/bind10-devel/ -- configuration specifications.
- o share/man/ -- manual pages (online documentation).
- o var/bind10-devel/ -- data source and configuration databases.
+ o sbin/ — commands used by the system administrator.
+ o share/bind10-devel/ — configuration specifications.
+ o share/man/ — manual pages (online documentation).
+ o var/bind10-devel/ — data source and configuration databases.
-Chapter 3. Starting BIND10 with bind10
+Chapter 3. Starting BIND10 with bind10
Table of Contents
@@ -497,12 +498,10 @@ Chapter 3. Starting BIND10 with bind10
In its default configuration, the bind10 master process will also start up
b10-cmdctl for administration tools to communicate with the system,
- b10-auth for authoritative DNS service, b10-stats for statistics
- collection, b10-stats-httpd for statistics reporting, b10-xfrin for
- inbound DNS zone transfers, b10-xfrout for outbound DNS zone transfers,
- and b10-zonemgr for secondary service.
+ b10-stats for statistics collection, and b10-stats-httpd for statistics
+ reporting.
-3.1. Starting BIND 10
+3.1. Starting BIND 10
To start the BIND 10 service, simply run bind10. Run it with the --verbose
switch to get additional debugging or diagnostic output.
@@ -511,23 +510,16 @@ Chapter 3. Starting BIND10 with bind10
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.
+ instead of just “python”. This is not needed on some operating systems.
-3.2. Configuration of started processes
+3.2. Configuration of started processes
The processes to be started can be configured, with the exception of the
b10-sockcreator, b10-msgq and b10-cfgmgr.
The configuration is in the Boss/components section. Each element
represents one component, which is an abstraction of a process (currently
- there's also one component which doesn't represent a process). If you
- didn't want to transfer out at all (your server is a slave only), you
- would just remove the corresponding component from the set, like this and
- the process would be stopped immediately (and not started on the next
- startup):
-
- > config remove Boss/components b10-xfrout
- > config commit
+ there's also one component which doesn't represent a process).
To add a process to the set, let's say the resolver (which not started by
default), you would do this:
@@ -547,7 +539,7 @@ Chapter 3. Starting BIND10 with bind10
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:
- Table 3.1.
+ Table 3.1.Â
+------------------------------------------------------------------------+
| Component | Special | Description |
@@ -561,11 +553,11 @@ Chapter 3. Starting BIND10 with bind10
+------------------------------------------------------------------------+
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
+ 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 bind10 shuts down and exits with 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
+ 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 behaviour of the core components
(the ones you can't turn off), but you can declare any other components as
@@ -578,10 +570,10 @@ Chapter 3. Starting BIND10 with bind10
the default is enough.
There are other parameters we didn't use in our example. One of them is
- "address". It is the address used by the component on the b10-msgq message
+ “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
don't. The address is by convention the thing after b10-, with the first
- letter capital (eg. b10-stats would have "Stats" as its address).
+ letter capital (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
@@ -591,7 +583,7 @@ Chapter 3. Starting BIND10 with bind10
This system allows you to start the same component multiple times (by
including it in the configuration with different names, but the same
- process setting). However, the rest of the system doesn't expect such
+ process setting). However, the rest of the system doesn't expect such a
situation, so it would probably not do what you want. Such support is yet
to be implemented.
@@ -601,8 +593,8 @@ Chapter 3. Starting BIND10 with bind10
mistakes. You could turn off the b10-cmdctl, but then you couldn't change
it back the usual way, as it would require it to be running (you would
have to find and edit the configuration directly). Also, some modules
- might have dependencies -- b10-stats-httpd need b10-stats, b10-xfrout
- needs the b10-auth to be running, etc.
+ 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.
@@ -622,11 +614,11 @@ Chapter 3. Starting BIND10 with bind10
locking the sqlite database, if used. The configuration might be changed
to something more convenient in future.
-Chapter 4. Command channel
+Chapter 4. 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
+ 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
@@ -636,7 +628,7 @@ Chapter 4. Command channel
default, BIND 10 uses port 9912 for the b10-msgq service. It listens on
127.0.0.1.
-Chapter 5. Configuration manager
+Chapter 5. Configuration manager
The configuration manager, b10-cfgmgr, handles all BIND 10 system
configuration. It provides persistent storage for configuration, and
@@ -648,12 +640,12 @@ Chapter 5. Configuration manager
The administrator doesn't connect to it directly, but uses a user
interface to communicate with the configuration manager via b10-cmdctl's
- REST-ful interface. b10-cmdctl is covered in Chapter 6, Remote control
+ REST-ful interface. b10-cmdctl is covered in Chapter 6, Remote control
daemon.
Note
- The development prototype release only provides the bindctl as a user
+ The development prototype 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.
@@ -672,10 +664,10 @@ Chapter 5. Configuration manager
The configuration manager does not have any command line arguments.
Normally it is not started manually, but is automatically started using
- the bind10 master process (as covered in Chapter 3, Starting BIND10 with
+ the bind10 master process (as covered in Chapter 3, Starting BIND10 with
bind10).
-Chapter 6. Remote control daemon
+Chapter 6. Remote control daemon
Table of Contents
@@ -688,7 +680,7 @@ Chapter 6. Remote control daemon
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
+ 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
@@ -715,7 +707,7 @@ Chapter 6. Remote control daemon
/usr/local/etc/bind10-devel/cmdctl-accounts.csv. This comma-delimited file
lists the accounts with a user name, hashed password, and salt. (A sample
file is at /usr/local/share/bind10-devel/cmdctl-accounts.csv. It contains
- the user named "root" with the password "bind10".)
+ the user named “root” with the password “bind10”.)
The administrator may create a user account with the b10-cmdctl-usermgr
tool.
@@ -723,17 +715,17 @@ Chapter 6. Remote control daemon
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 timesout in 1200 seconds by default. This can
+ connection is stateless and times out in 1200 seconds by default. This can
be redefined by using the --idle-timeout command line argument.
-6.1. Configuration specification for b10-cmdctl
+6.1. Configuration specification for b10-cmdctl
The configuration items for b10-cmdctl are: key_file cert_file
accounts_file
The control commands are: print_settings shutdown
-Chapter 7. Control and configure user interface
+Chapter 7. Control and configure user interface
Note
@@ -753,7 +745,7 @@ Chapter 7. Control and configure user interface
b10-cfgmgr which then stores the details and relays (over a b10-msgq
command channel) the configuration on to the specified module.
-Chapter 8. Authoritative Server
+Chapter 8. Authoritative Server
Table of Contents
@@ -761,28 +753,74 @@ Chapter 8. Authoritative Server
8.2. Data Source Backends
+ 8.2.1. In-memory Data Source
+
8.3. Loading Master Zones Files
The b10-auth is the authoritative DNS server. It supports EDNS0 and
DNSSEC. It supports IPv6. Normally it is started by the bind10 master
process.
-8.1. Server Configurations
+8.1. Server Configurations
b10-auth is configured via the b10-cfgmgr configuration manager. The
- module name is "Auth". The configuration data item is:
+ 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: Later the DNS server will use various data
source backends. This may be a temporary setting until then.
- The configuration command is:
+ 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 and the origin (default domain). By
+ default, this is empty.
+
+ Note
+
+ In this development version, 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.
+
+ 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.
+
+ statistics-interval
+ statistics-interval is the timer interval in seconds for b10-auth
+ to share its statistics information to b10-stats(8). Statistics
+ updates can be disabled by setting this to 0. The default is 60.
+
+ The configuration commands are:
+
+ 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
+
+ In this development version, currently this only supports the IN
+ class and the memory data source.
+
+ sendstats
+ sendstats tells b10-auth to send its statistics data to
+ b10-stats(8) immediately.
shutdown
- Stop the authoritative DNS server.
+ Stop the authoritative DNS server. This has an optional pid
+ argument to select the process ID to stop. (Note that the BIND 10
+ boss process may restart this service if configured.)
-8.2. Data Source Backends
+8.2. Data Source Backends
Note
@@ -795,12 +833,48 @@ Chapter 8. Authoritative Server
/usr/local/var/bind10-devel/zone.sqlite3. (The full path is what was
defined at build configure time for --localstatedir. The default is
/usr/local/var/.) This data file location may be changed by defining the
- "database_file" configuration.
+ “database_file” configuration.
-8.3. Loading Master Zones Files
+ 8.2.1. In-memory Data Source
- RFC 1035 style DNS master zone files may imported into a BIND 10 data
- source by using the b10-loadzone utility.
+ The following commands to bindctl provide an example of configuring an
+ in-memory data source containing the “example.com” zone with the zone file
+ named “example.com.zone”:
+
+ > config add Auth/datasources
+ > config set Auth/datasources[0]/type "memory"
+ > config add Auth/datasources[0]/zones
+ > config set Auth/datasources[0]/zones[0]/origin "example.com"
+ > config set Auth/datasources[0]/zones[0]/file "example.com.zone"
+ > config commit
+
+ The authoritative server will begin serving it immediately after it is
+ loaded.
+
+ Use the Auth loadzone command in bindctl to reload a changed master file
+ into memory; for example:
+
+ > Auth loadzone origin="example.com"
+
+ By default, the memory data source is disabled; it must be configured
+ explicitly. To disable all the in-memory zones, specify a null list for
+ Auth/datasources:
+
+ > config set Auth/datasources/ []
+ > config commit
+
+ The following example stops serving a specific zone:
+
+ > config remove Auth/datasources[0]/zones[0]
+ > config commit
+
+ (Replace the list number(s) in datasources[0] and/or zones[0] for the
+ relevant zone as needed.)
+
+8.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):
@@ -819,8 +893,8 @@ Chapter 8. Authoritative Server
Note
- In the development prototype release, only the SQLite3 back end is used.
- By default, it stores the zone data in
+ In the development prototype release, only the SQLite3 back end is used by
+ b10-loadzone. By default, it stores the zone data in
/usr/local/var/bind10-devel/zone.sqlite3 unless the -d switch is used to
set the database filename. Multiple zones are stored in a single SQLite3
zone database.
@@ -828,7 +902,7 @@ Chapter 8. Authoritative Server
If you reload a zone already existing in the database, all records from
that prior zone disappear and a whole new set appears.
-Chapter 9. Incoming Zone Transfers
+Chapter 9. Incoming Zone Transfers
Table of Contents
@@ -844,7 +918,7 @@ Chapter 9. Incoming Zone Transfers
started by bind10. 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.
+ BIND 10 server to provide “secondary” service.
The b10-xfrin process supports both AXFR and IXFR. Due to some
implementation limitations of the current development release, however, it
@@ -856,7 +930,7 @@ Chapter 9. Incoming Zone Transfers
only available for SQLite3-based data sources, that is, they don't work
for an in-memory data source.
-9.1. Configuration for Incoming Zone Transfers
+9.1. Configuration for Incoming Zone Transfers
In practice, you need to specify a list of secondary zones to enable
incoming zone transfers for these zones (you can still trigger a zone
@@ -873,7 +947,7 @@ Chapter 9. Incoming Zone Transfers
(We assume there has been no zone configuration before).
-9.2. Enabling IXFR
+9.2. Enabling IXFR
As noted above, b10-xfrin uses AXFR for zone transfers by default. To
enable IXFR for zone transfers for a particular zone, set the use_ixfr
@@ -896,7 +970,7 @@ Chapter 9. Incoming Zone Transfers
be implemented in a near future version, at which point we will enable
IXFR by default.
-9.3. Secondary Manager
+9.3. Secondary Manager
The b10-zonemgr process is started by bind10. It keeps track of SOA
refresh, retry, and expire timers and other details for BIND 10 to perform
@@ -922,14 +996,14 @@ Chapter 9. Incoming Zone Transfers
for it), b10-zonemgr will automatically tell b10-xfrin to transfer the
zone in.
-9.4. Trigger an Incoming Zone Transfer Manually
+9.4. 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
-Chapter 10. Outbound Zone Transfers
+Chapter 10. Outbound Zone Transfers
The b10-xfrout process is started by bind10. When the b10-auth
authoritative DNS server receives an AXFR or IXFR request, b10-auth
@@ -971,14 +1045,14 @@ Chapter 10. Outbound Zone Transfers
> config commit
Both Xfrout and Auth will use the system wide keyring to check TSIGs in
- the incomming messages and to sign responses.
+ the incoming messages and to sign responses.
Note
The way to specify zone specific configuration (ACLs, etc) is likely to be
changed.
-Chapter 11. Recursive Name Server
+Chapter 11. Recursive Name Server
Table of Contents
@@ -989,12 +1063,9 @@ Chapter 11. Recursive Name Server
The b10-resolver process is started by bind10.
The main bind10 process can be configured to select to run either the
- authoritative or resolver or both. By default, it starts the authoritative
- service. You may change this using bindctl, for example:
+ authoritative or resolver or both. By default, it doesn't start either
+ one. You may change this using bindctl, for example:
- > config remove Boss/components b10-xfrout
- > config remove Boss/components b10-xfrin
- > config remove Boss/components b10-auth
> config add Boss/components b10-resolver
> config set Boss/components/b10-resolver/special resolver
> config set Boss/components/b10-resolver/kind needed
@@ -1012,26 +1083,26 @@ Chapter 11. Recursive Name Server
> config set Resolver/listen_on[2]/port 53
> config commit
- (Replace the "2" as needed; run "config show Resolver/listen_on" if
+ (Replace the “2” as needed; run “config show Resolver/listen_on” if
needed.)
-11.1. Access Control
+11.1. Access Control
By default, the b10-resolver daemon only accepts DNS queries from the
localhost (127.0.0.1 and ::1). The Resolver/query_acl configuration may be
used to reject, drop, or allow specific IPs or networks. This
configuration list is first match.
- The configuration's action item may be set to "ACCEPT" to allow the
- incoming query, "REJECT" to respond with a DNS REFUSED return code, or
- "DROP" to ignore the query without any response (such as a blackhole). For
+ The configuration's action item may be set to “ACCEPT” to allow the
+ incoming query, “REJECT” to respond with a DNS REFUSED return code, or
+ “DROP” to ignore the query without any response (such as a blackhole). For
more information, see the respective debugging messages:
RESOLVER_QUERY_ACCEPTED, RESOLVER_QUERY_REJECTED, and
RESOLVER_QUERY_DROPPED.
The required configuration's from item is set to an IPv4 or IPv6 address,
addresses with an network mask, or to the special lowercase keywords
- "any6" (for any IPv6 address) or "any4" (for any IPv4 address).
+ “any6” (for any IPv6 address) or “any4” (for any IPv4 address).
For example to allow the 192.168.1.0/24 network to use your recursive name
server, at the bindctl prompt run:
@@ -1041,14 +1112,14 @@ Chapter 11. Recursive Name Server
> config set Resolver/query_acl[2]/from "192.168.1.0/24"
> config commit
- (Replace the "2" as needed; run "config show Resolver/query_acl" if
+ (Replace the “2” as needed; run “config show Resolver/query_acl” if
needed.)
Note
This prototype access control configuration syntax may be changed.
-11.2. Forwarding
+11.2. Forwarding
To enable forwarding, the upstream address and port must be configured to
forward queries to, such as:
@@ -1064,7 +1135,7 @@ Chapter 11. Recursive Name Server
> config set Resolver/forward_addresses []
> config commit
-Chapter 12. DHCPv4 Server
+Chapter 12. DHCPv4 Server
Table of Contents
@@ -1084,7 +1155,7 @@ Chapter 12. DHCPv4 Server
clients. Even though principles of both DHCPv4 and DHCPv6 are somewhat
similar, these are two radically different protocols. BIND10 offers server
implementations for both DHCPv4 and DHCPv6. This chapter is about DHCP for
- IPv4. For a description of the DHCPv6 server, see Chapter 13, DHCPv6
+ IPv4. For a description of the DHCPv6 server, see Chapter 13, DHCPv6
Server.
The DHCPv4 server component is currently under intense development. You
@@ -1092,7 +1163,7 @@ Chapter 12. DHCPv4 Server
developers mailing list.
The DHCPv4 and DHCPv6 components in BIND10 architecture are internally
- code named "Kea".
+ code named “Kea”.
Note
@@ -1100,17 +1171,17 @@ Chapter 12. DHCPv4 Server
servers. That means that while they are capable of performing DHCP
configuration, they are not fully functional yet. In particular, neither
has functional lease databases. This means that they will assign the same,
- fixed, hardcoded addresses to any client that will ask. See Section 12.4,
- "DHCPv4 Server Limitations" and Section 13.4, "DHCPv6 Server Limitations"
+ fixed, hardcoded addresses to any client that will ask. See Section 12.4,
+ “DHCPv4 Server Limitations” and Section 13.4, “DHCPv6 Server Limitations”
for detailed description.
-12.1. DHCPv4 Server Usage
+12.1. DHCPv4 Server Usage
BIND10 provides the DHCPv4 server component since December 2011. It is a
skeleton server and can be described as an early prototype that is not
fully functional yet. It is mature enough to conduct first tests in lab
- environment, but it has significant limitations. See Section 12.4, "DHCPv4
- Server Limitations" for details.
+ environment, but it has significant limitations. See Section 12.4, “DHCPv4
+ Server Limitations” for details.
The DHCPv4 server is implemented as b10-dhcp4 daemon. As it is not
configurable yet, it is fully autonomous, that is it does not interact
@@ -1136,7 +1207,7 @@ Chapter 12. DHCPv4 Server
started directly, but rather via bind10. Please be aware of this planned
change.
-12.2. DHCPv4 Server Configuration
+12.2. DHCPv4 Server Configuration
The DHCPv4 server does not have a lease database implemented yet nor any
support for configuration, so every time the same set of configuration
@@ -1157,60 +1228,60 @@ Chapter 12. DHCPv4 Server
Lease database and configuration support is planned for 2012.
-12.3. Supported standards
+12.3. Supported standards
The following standards and draft standards are currently supported:
- o RFC2131: Supported messages are DISCOVER, OFFER, REQUEST, and ACK.
- o RFC2132: Supported options are: PAD (0), END(255), Message Type(53),
+ o RFC2131: Supported messages are DISCOVER, OFFER, REQUEST, and ACK.
+ o RFC2132: 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).
-12.4. DHCPv4 Server Limitations
+12.4. DHCPv4 Server Limitations
These are the current limitations of the DHCPv4 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.
+ treated as “not implemented yet”, rather than actual limitations.
- o During initial IPv4 node configuration, the server is expected to send
+ o During 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).
- o b10-dhcp4 provides a single, fixed, hardcoded lease to any client that
+ o b10-dhcp4 provides a single, fixed, hardcoded lease to any client that
asks. There is no lease manager implemented. If two clients request
addresses, they will both get the same fixed address.
- o b10-dhcp4 does not support any configuration mechanisms yet. The whole
+ o b10-dhcp4 does not support any configuration mechanisms yet. The whole
configuration is currently hardcoded. The only way to tweak
- configuration is to directly modify source code. See see Section 12.2,
- "DHCPv4 Server Configuration" for details.
- o Upon start, the server will open sockets on all interfaces that are
+ configuration is to directly modify source code. See see Section 12.2,
+ “DHCPv4 Server Configuration” for details.
+ o Upon start, the server will open sockets on all interfaces that are
not loopback, are up and running and have IPv4 address. Support for
multiple interfaces is not coded in reception routines yet, so if you
are running this code on a machine that has many interfaces and
b10-dhcp4 happens to listen on wrong interface, the easiest way to
work around this problem is to turn down other interfaces. This
limitation will be fixed shortly.
- o PRL (Parameter Request List, a list of options requested by a client)
+ o PRL (Parameter Request List, a list of options requested by a client)
is currently ignored and server assigns DNS SERVER and DOMAIN NAME
options.
- o b10-dhcp4 does not support BOOTP. That is a design choice. This
+ o b10-dhcp4 does not support BOOTP. That is a design choice. This
limitation is permanent. If you have legacy nodes that can't use DHCP
and require BOOTP support, please use latest version of ISC DHCP
http://www.isc.org/software/dhcp.
- o Interface detection is currently working on Linux only. See
- Section 14.1, "Interface detection" for details.
- o b10-dhcp4 does not verify that assigned address is unused. According
+ o Interface detection is currently working on Linux only. See
+ Section 14.1, “Interface detection” for details.
+ o b10-dhcp4 does not verify that assigned address is unused. According
to RFC2131, the allocating server should verify that address is no
used by sending ICMP echo request.
- o Address renewal (RENEW), rebinding (REBIND), confirmation (CONFIRM),
+ o Address renewal (RENEW), rebinding (REBIND), confirmation (CONFIRM),
duplication report (DECLINE) and release (RELEASE) are not supported
yet.
- o DNS Update is not supported yet.
- o -v (verbose) command line option is currently the default, and cannot
+ o DNS Update is not supported yet.
+ o -v (verbose) command line option is currently the default, and cannot
be disabled.
-Chapter 13. DHCPv6 Server
+Chapter 13. DHCPv6 Server
Table of Contents
@@ -1225,14 +1296,14 @@ Chapter 13. DHCPv6 Server
Dynamic Host Configuration Protocol for IPv6 (DHCPv6) is specified in
RFC3315. BIND10 provides DHCPv6 server implementation that is described in
this chapter. For a description of the DHCPv4 server implementation, see
- Chapter 12, DHCPv4 Server.
+ Chapter 12, DHCPv4 Server.
The DHCPv6 server component is currently under intense development. You
may want to check out BIND10 DHCP (Kea) wiki and recent posts on BIND10
developers mailing list.
The DHCPv4 and DHCPv6 components in BIND10 architecture are internally
- code named "Kea".
+ code named “Kea”.
Note
@@ -1240,17 +1311,17 @@ Chapter 13. DHCPv6 Server
servers. That means that while they are capable of performing DHCP
configuration, they are not fully functional yet. In particular, neither
has functional lease databases. This means that they will assign the same,
- fixed, hardcoded addresses to any client that will ask. See Section 12.4,
- "DHCPv4 Server Limitations" and Section 13.4, "DHCPv6 Server Limitations"
+ fixed, hardcoded addresses to any client that will ask. See Section 12.4,
+ “DHCPv4 Server Limitations” and Section 13.4, “DHCPv6 Server Limitations”
for detailed description.
-13.1. DHCPv6 Server Usage
+13.1. DHCPv6 Server Usage
BIND10 provides the DHCPv6 server component since September 2011. It is a
skeleton server and can be described as an early prototype that is not
fully functional yet. It is mature enough to conduct first tests in lab
- environment, but it has significant limitations. See Section 13.4, "DHCPv6
- Server Limitations" for details.
+ environment, but it has significant limitations. See Section 13.4, “DHCPv6
+ Server Limitations” for details.
The DHCPv6 server is implemented as b10-dhcp6 daemon. As it is not
configurable yet, it is fully autonomous, that is it does not interact
@@ -1276,7 +1347,7 @@ Chapter 13. DHCPv6 Server
started directly, but rather via bind10. Please be aware of this planned
change.
-13.2. DHCPv6 Server Configuration
+13.2. DHCPv6 Server Configuration
The DHCPv6 server does not have lease database implemented yet or any
support for configuration, so every time the same set of configuration
@@ -1296,50 +1367,50 @@ Chapter 13. DHCPv6 Server
Lease database and configuration support is planned for 2012.
-13.3. Supported DHCPv6 Standards
+13.3. Supported DHCPv6 Standards
The following standards and draft standards are currently supported:
- o RFC3315: Supported messages are SOLICIT, ADVERTISE, REQUEST, and
+ o RFC3315: Supported messages are SOLICIT, ADVERTISE, REQUEST, and
REPLY. Supported options are SERVER_ID, CLIENT_ID, IA_NA, and
IAADDRESS.
- o RFC3646: Supported option is DNS_SERVERS.
+ o RFC3646: Supported option is DNS_SERVERS.
-13.4. DHCPv6 Server Limitations
+13.4. DHCPv6 Server Limitations
These are the current limitations of 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.
+ treated as “not implemented yet”, rather than actual limitations.
- o Relayed traffic is not supported.
- o b10-dhcp6 provides a single, fixed, hardcoded lease to any client that
+ o Relayed traffic is not supported.
+ o b10-dhcp6 provides a single, fixed, hardcoded lease to any client that
asks. There is no lease manager implemented. If two clients request
addresses, they will both get the same fixed address.
- o b10-dhcp6 does not support any configuration mechanisms yet. The whole
+ o b10-dhcp6 does not support any configuration mechanisms yet. The whole
configuration is currently hardcoded. The only way to tweak
- configuration is to directly modify source code. See see Section 13.2,
- "DHCPv6 Server Configuration" for details.
- o Upon start, the server will open sockets on all interfaces that are
+ configuration is to directly modify source code. See see Section 13.2,
+ “DHCPv6 Server Configuration” for details.
+ o Upon start, the server will open sockets on all interfaces that are
not loopback, are up, running and are multicast capable and have IPv6
address. Support for multiple interfaces is not coded in reception
routines yet, so if you are running this code on a machine that has
many interfaces and b10-dhcp6 happens to listen on wrong interface,
the easiest way to work around this problem is to turn down other
interfaces. This limitation will be fixed shortly.
- o ORO (Option Request Option, a list of options requested by a client)
+ o ORO (Option Request Option, a list of options requested by a client)
is currently ignored and server assigns DNS SERVER option.
- o Temporary addresses are not supported yet.
- o Prefix delegation is not supported yet.
- o Address renewal (RENEW), rebinding (REBIND), confirmation (CONFIRM),
+ o Temporary addresses are not supported yet.
+ o Prefix delegation is not supported yet.
+ o Address renewal (RENEW), rebinding (REBIND), confirmation (CONFIRM),
duplication report (DECLINE) and release (RELEASE) are not supported
yet.
- o DNS Update is not supported yet.
- o Interface detection is currently working on Linux only. See
- Section 14.1, "Interface detection" for details.
- o -v (verbose) command line option is currently the default, and cannot
+ o DNS Update is not supported yet.
+ o Interface detection is currently working on Linux only. See
+ Section 14.1, “Interface detection” for details.
+ o -v (verbose) command line option is currently the default, and cannot
be disabled.
-Chapter 14. libdhcp++ library
+Chapter 14. libdhcp++ library
Table of Contents
@@ -1357,7 +1428,7 @@ Chapter 14. libdhcp++ library
is designed to be portable, universal library useful for any kind of
DHCP-related software.
-14.1. Interface detection
+14.1. Interface detection
Both DHCPv4 and DHCPv6 components share network interface detection
routines. Interface detection is currently only supported on Linux
@@ -1379,11 +1450,11 @@ Chapter 14. libdhcp++ library
# For DHCPv4, please use following format:
#eth0 192.0.2.5
-14.2. DHCPv4/DHCPv6 packet handling
+14.2. DHCPv4/DHCPv6 packet handling
TODO: Describe packet handling here, with pointers to wiki
-Chapter 15. Statistics
+Chapter 15. Statistics
The b10-stats process is started by bind10. It periodically collects
statistics data from various modules and aggregates it.
@@ -1415,7 +1486,7 @@ Chapter 15. Statistics
}
-Chapter 16. Logging
+Chapter 16. Logging
Table of Contents
@@ -1429,97 +1500,97 @@ Chapter 16. Logging
16.2. Logging Message Format
-16.1. Logging configuration
+16.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.
- 16.1.1. Loggers
+ 16.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..
+ 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).
- 16.1.1.1. name (string)
+ 16.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".
+ 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".
+ 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
+ “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
+ 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
+ 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
+ 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 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",
+ 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".
+ entry for “Resolver”.
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.
+ “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").
+ generated by the “Auth.cache” logger will appear in the output with a
+ logger name of “b10-auth.cache”).
- 16.1.1.2. severity (string)
+ 16.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):
- o FATAL
- o ERROR
- o WARN
- o INFO
- o DEBUG
+ o FATAL
+ o ERROR
+ o WARN
+ o INFO
+ o 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.
- 16.1.1.3. output_options (list)
+ 16.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:
- 16.1.1.4. debuglevel (integer)
+ 16.1.1.4. debuglevel (integer)
When a logger's severity is set to DEBUG, this value specifies what debug
messages should be printed. It ranges from 0 (least verbose) to 99 (most
@@ -1527,69 +1598,80 @@ Chapter 16. Logging
If severity for the logger is not DEBUG, this value is ignored.
- 16.1.1.5. additive (true or false)
+ 16.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",
+ 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".
+ logger named “Resolver”.
- 16.1.2. Output Options
+ 16.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.
- 16.1.2.1. destination (string)
+ 16.1.2.1. destination (string)
The destination is the type of output. It can be one of:
- o console
- o file
- o syslog
+ o console
+ o file
+ o syslog
- 16.1.2.2. output (string)
+ 16.1.2.2. 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).
+ 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”
- destination is "file"
The value of output is interpreted as a file name; log messages
will be appended to this file.
- destination is "syslog"
+ 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:
- 16.1.2.2.1. flush (true of false)
+ 16.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.
- 16.1.2.2.2. maxsize (integer)
+ 16.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.)
+ name — if a ".1" file exists, it is renamed ".2", etc.)
If this is 0, no maximum file size is used.
- 16.1.2.2.3. maxver (integer)
+ 16.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".
+ file. Only relevant when destination is “file”.
- 16.1.3. Example session
+ 16.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
@@ -1648,7 +1730,7 @@ Chapter 16. Logging
> config set Logging/loggers[0]/output_options[0]/destination file
> config set Logging/loggers[0]/output_options[0]/output /var/log/bind10.log
- > config set Logging/loggers[0]/output_options[0]/maxsize 30000
+ > config set Logging/loggers[0]/output_options[0]/maxsize 204800
> config set Logging/loggers[0]/output_options[0]/maxver 8
Which would make the entire configuration for this logger look like:
@@ -1661,7 +1743,7 @@ Chapter 16. Logging
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 30000 integer (modified)
+ Logging/loggers[0]/output_options[0]/maxsize 204800 integer (modified)
Logging/loggers[0]/output_options[0]/maxver 8 integer (modified)
That looks OK, so let's commit it before we add the configuration for the
@@ -1688,9 +1770,9 @@ Chapter 16. Logging
> config remove Logging/loggers[1]
> config commit
- And every module will now be using the values from the logger named "*".
+ And every module will now be using the values from the logger named “*”.
-16.2. Logging Message Format
+16.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
diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml
index 1eaad90061..a1c63996c5 100644
--- a/doc/guide/bind10-guide.xml
+++ b/doc/guide/bind10-guide.xml
@@ -2809,34 +2809,43 @@ TODO; there's a ticket to determine these levels, see #1074
console
stdout
(messages printed to standard output) or
stderr
(messages printed to standard
error).
- 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
.
+ file
syslog