<html><head><metahttp-equiv="Content-Type"content="text/html; charset=ISO-8859-1"><title>BIND 10 Guide</title><linkrel="stylesheet"href="./bind10-guide.css"type="text/css"><metaname="generator"content="DocBook XSL Stylesheets V1.75.2"><metaname="description"content="BIND 10 is a Domain Name System (DNS) suite managed by Internet Systems Consortium (ISC). It includes DNS libraries and modular components for controlling authoritative and recursive DNS servers. This is the reference guide for BIND 10 version 20110809. 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 ."></head><bodybgcolor="white"text="black"link="#0000FF"vlink="#840084"alink="#0000FF"><divclass="book"title="BIND 10 Guide"><divclass="titlepage"><div><div><h1class="title"><aname="id1168229451102"></a>BIND 10 Guide</h1></div><div><h2class="subtitle">Administrator Reference for BIND 10</h2></div><div><pclass="releaseinfo">This is the reference guide for BIND 10 version
20110809.</p></div><div><pclass="copyright">Copyright <20> 2010-2011 Internet Systems Consortium, Inc.</p></div><div><divclass="abstract"title="Abstract"><pclass="title"><b>Abstract</b></p><p>BIND 10 is a Domain Name System (DNS) suite managed by
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 <aclass="ulink"href="http://bind10.isc.org/docs"target="_top">http://bind10.isc.org/docs</a>.
</p></div></div></div><hr></div><divclass="toc"><p><b>Table of Contents</b></p><dl><dt><spanclass="chapter"><ahref="#intro">1. Introduction</a></span></dt><dd><dl><dt><spanclass="section"><ahref="#id1168229451238">Supported Platforms</a></span></dt><dt><spanclass="section"><ahref="#id1168229451265">Required Software</a></span></dt><dt><spanclass="section"><ahref="#starting_stopping">Starting and Stopping the Server</a></span></dt><dt><spanclass="section"><ahref="#managing_once_running">Managing BIND 10</a></span></dt></dl></dd><dt><spanclass="chapter"><ahref="#installation">2. Installation</a></span></dt><dd><dl><dt><spanclass="section"><ahref="#id1168229436567">Building Requirements</a></span></dt><dt><spanclass="section"><ahref="#quickstart">Quick start</a></span></dt><dt><spanclass="section"><ahref="#install">Installation from source</a></span></dt><dd><dl><dt><spanclass="section"><ahref="#id1168229436859">Download Tar File</a></span></dt><dt><spanclass="section"><ahref="#id1168229436878">Retrieve from Git</a></span></dt><dt><spanclass="section"><ahref="#id1168229436939">Configure before the build</a></span></dt><dt><spanclass="section"><ahref="#id1168229437037">Build</a></span></dt><dt><spanclass="section"><ahref="#id1168229437052">Install</a></span></dt><dt><spanclass="section"><ahref="#id1168229437076">Install Hierarchy</a></span></dt></dl></dd></dl></dd><dt><spanclass="chapter"><ahref="#bind10">3. Starting BIND10 with <spanclass="command"><strong>bind10</strong></span></a></span></dt><dd><dl><dt><spanclass="section"><ahref="#start">Starting BIND 10</a></span></dt></dl></dd><dt><spanclass="chapter"><ahref="#msgq">4. Command channel</a></span></dt><dt><spanclass="chapter"><ahref="#cfgmgr">5. Configuration manager</a></span></dt><dt><spanclass="chapter"><ahref="#cmdctl">6. Remote control daemon</a></span></dt><dd><dl><dt><spanclass="section"><ahref="#cmdctl.spec">Configuration specification for b10-cmdctl</a></span></dt></dl></dd><dt><spanclass="chapter"><ahref="#bindctl">7. Control and configure user interface</a></span></dt><dt><spanclass="chapter"><ahref="#authserver">8. Authoritative Server</a></span></dt><dd><dl><dt><spanclass="section"><ahref="#id1168229437660">Server Configurations</a></span></dt><dt><spanclass="section"><ahref="#id1168229437725">Data Source Backends</a></span></dt><dt><spanclass="section"><ahref="#id1168229437755">Loading Master Zones Files</a></span></dt></dl></dd><dt><spanclass="chapter"><ahref="#xfrin">9. Incoming Zone Transfers</a></span></dt><dd><dl><dt><spanclass="section"><ahref="#id1168229437989">Configuration for Incoming Zone Transfers</a></span></dt><dt><spanclass="section"><ahref="#id1168229438027">Enabling IXFR</a></span></dt><dt><spanclass="section"><ahref="#id1168229438069">Trigger an Incoming Zone Transfer Manually</a></span></dt></dl></dd><dt><spanclass="chapter"><ahref="#xfrout">10. Outbound Zone Transfers</a></span></dt><dt><spanclass="chapter"><ahref="#zonemgr">11. Secondary Manager</a></span></dt><dt><spanclass="chapter"><ahref="#resolverserver">12. Recursive Name Server</a></span></dt><dd><dl><dt><spanclass="section"><ahref="#id1168229438327">Access Control</a></span></dt><dt><spanclass="section"><ahref="#id1168229438512">Forwarding</a></span></dt></dl></dd><dt><spanclass="chapter"><ahref="#statistics">13. Statistics</a></span></dt><dt><spanclass="chapter"><ahref="#logging">14. Logging</a></span></dt><dd><dl><dt><spanclass="section"><ahref="#id1168229438628">Logging configuration</a></span></dt><dd><dl><dt><spanclass="section"><ahref="#id1168229438638">Loggers</a></span></dt><dt><spanclass="section"><ahref="#id1168229439154">Output Options</a></span></dt><dt><spanclass="section"><ahref="#id1168229439328">Example session</a></span></dt></dl></dd><dt><spanclass="section"><ahref="#id1168229439609">Logging Message Format</a></span></dt></dl></dd></dl></div><divclass="chapter"title="Chapter<65>1.<2E>Introduction"><divclass="titlepage"><div><div><h2class="title"><aname="intro"></a>Chapter<EFBFBD>1.
Some operating systems do not provide these dependencies
in their default installation nor standard packages
collections.
You may need to install them separately.
</p></div></div><divclass="section"title="Starting and Stopping the Server"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aname="starting_stopping"></a>Starting and Stopping the Server</h2></div></div></div><p>
BIND 10 is modular. Part of this modularity is
accomplished using multiple cooperating processes which, together,
</p></div><divclass="chapter"title="Chapter<65>2.<2E>Installation"><divclass="titlepage"><div><div><h2class="title"><aname="installation"></a>Chapter<EFBFBD>2.<2E>Installation</h2></div></div></div><divclass="toc"><p><b>Table of Contents</b></p><dl><dt><spanclass="section"><ahref="#id1168229436567">Building Requirements</a></span></dt><dt><spanclass="section"><ahref="#quickstart">Quick start</a></span></dt><dt><spanclass="section"><ahref="#install">Installation from source</a></span></dt><dd><dl><dt><spanclass="section"><ahref="#id1168229436859">Download Tar File</a></span></dt><dt><spanclass="section"><ahref="#id1168229436878">Retrieve from Git</a></span></dt><dt><spanclass="section"><ahref="#id1168229436939">Configure before the build</a></span></dt><dt><spanclass="section"><ahref="#id1168229437037">Build</a></span></dt><dt><spanclass="section"><ahref="#id1168229437052">Install</a></span></dt><dt><spanclass="section"><ahref="#id1168229437076">Install Hierarchy</a></span></dt></dl></dd></dl></div><divclass="section"title="Building Requirements"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aname="id1168229436567"></a>Building Requirements</h2></div></div></div><p>
</li></ol></div></div><divclass="section"title="Installation from source"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aname="install"></a>Installation from source</h2></div></div></div><p>
BIND 10 is open source software written in C++ and Python.
It is freely available in source code form from ISC via
</p><divclass="section"title="Download Tar File"><divclass="titlepage"><div><div><h3class="title"><aname="id1168229436859"></a>Download Tar File</h3></div></div></div><p>
</p></div><divclass="section"title="Retrieve from Git"><divclass="titlepage"><div><div><h3class="title"><aname="id1168229436878"></a>Retrieve from Git</h3></div></div></div><p>
</p></div><divclass="section"title="Configure before the build"><divclass="titlepage"><div><div><h3class="title"><aname="id1168229436939"></a>Configure before the build</h3></div></div></div><p>
</p></div></div></div><divclass="chapter"title="Chapter<65>3.<2E>Starting BIND10 with bind10"><divclass="titlepage"><div><div><h2class="title"><aname="bind10"></a>Chapter<EFBFBD>3.<2E>Starting BIND10 with <spanclass="command"><strong>bind10</strong></span></h2></div></div></div><divclass="toc"><p><b>Table of Contents</b></p><dl><dt><spanclass="section"><ahref="#start">Starting BIND 10</a></span></dt></dl></div><p>
</p><p>The administrator doesn't connect to it directly, but
uses a user interface to communicate with the configuration
manager via <spanclass="command"><strong>b10-cmdctl</strong></span>'s REST-ful interface.
<spanclass="command"><strong>b10-cmdctl</strong></span> is covered in <aclass="xref"href="#cmdctl"title="Chapter<65>6.<2E>Remote control daemon">Chapter<EFBFBD>6, <i>Remote control daemon</i></a>.
The configuration manager does not have any command line arguments.
Normally it is not started manually, but is automatically
started using the <spanclass="command"><strong>bind10</strong></span> master process
(as covered in <aclass="xref"href="#bind10"title="Chapter<65>3.<2E>Starting BIND10 with bind10">Chapter<EFBFBD>3, <i>Starting BIND10 with <spanclass="command"><strong>bind10</strong></span></i></a>).
</p></div><divclass="chapter"title="Chapter<65>6.<2E>Remote control daemon"><divclass="titlepage"><div><div><h2class="title"><aname="cmdctl"></a>Chapter<EFBFBD>6.<2E>Remote control daemon</h2></div></div></div><divclass="toc"><p><b>Table of Contents</b></p><dl><dt><spanclass="section"><ahref="#cmdctl.spec">Configuration specification for b10-cmdctl</a></span></dt></dl></div><p>
<spanclass="command"><strong>b10-cmdctl</strong></span> 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.
</p><p>
When <spanclass="command"><strong>b10-cmdctl</strong></span> starts, it firsts
asks <spanclass="command"><strong>b10-cfgmgr</strong></span> about what modules are
By default the HTTPS server listens on the localhost port 8080.
The port can be set by using the <codeclass="option">--port</code> command line option.
The address to listen on can be set using the <codeclass="option">--address</code> command
line argument.
Each HTTPS connection is stateless and timesout in 1200 seconds
by default. This can be
redefined by using the <codeclass="option">--idle-timeout</code> command line argument.
</p><divclass="section"title="Configuration specification for b10-cmdctl"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aname="cmdctl.spec"></a>Configuration specification for b10-cmdctl</h2></div></div></div><p>
The configuration items for <spanclass="command"><strong>b10-cmdctl</strong></span> are:
</p></div></div><divclass="chapter"title="Chapter<65>7.<2E>Control and configure user interface"><divclass="titlepage"><div><div><h2class="title"><aname="bindctl"></a>Chapter<EFBFBD>7.<2E>Control and configure user interface</h2></div></div></div><divclass="note"title="Note"style="margin-left: 0.5in; margin-right: 0.5in;"><h3class="title">Note</h3><p>
</p></div><divclass="section"title="Loading Master Zones Files"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aname="id1168229437755"></a>Loading Master Zones Files</h2></div></div></div><p>
</p></div></div><divclass="chapter"title="Chapter<65>9.<2E>Incoming Zone Transfers"><divclass="titlepage"><div><div><h2class="title"><aname="xfrin"></a>Chapter<EFBFBD>9.<2E>Incoming Zone Transfers</h2></div></div></div><divclass="toc"><p><b>Table of Contents</b></p><dl><dt><spanclass="section"><ahref="#id1168229437989">Configuration for Incoming Zone Transfers</a></span></dt><dt><spanclass="section"><ahref="#id1168229438027">Enabling IXFR</a></span></dt><dt><spanclass="section"><ahref="#id1168229438069">Trigger an Incoming Zone Transfer Manually</a></span></dt></dl></div><p>
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.
</p></div><divclass="section"title="Configuration for Incoming Zone Transfers"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aname="id1168229437989"></a>Configuration for Incoming Zone Transfers</h2></div></div></div><p>
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
(see below)).
</p><p>
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 <spanclass="command"><strong>bindctl</strong></span> prompt:
One reason why IXFR is disabled by default in the current
release is because it does not support automatic fallback from IXFR to
AXFR when it encounters a primary server that doesn't support
outbound IXFR (and, not many existing implementations support
it). Another, related reason is that it does not use AXFR even
if it has no knowledge about the zone (like at the very first
time the secondary server is set up). IXFR requires the
"current version" of the zone, so obviously it doesn't work
in this situation and AXFR is the only workable choice.
The current release of <spanclass="command"><strong>b10-xfrin</strong></span> does not
make this selection automatically.
These features will be implemented in a near future
version, at which point we will enable IXFR by default.
</p></div></div><divclass="section"title="Trigger an Incoming Zone Transfer Manually"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aname="id1168229438069"></a>Trigger an Incoming Zone Transfer Manually</h2></div></div></div><p>
To manually trigger a zone transfer to retrieve a remote zone,
you may use the <spanclass="command"><strong>bindctl</strong></span> utility.
For example, at the <spanclass="command"><strong>bindctl</strong></span> prompt run:
</p></div></div><divclass="chapter"title="Chapter<65>10.<2E>Outbound Zone Transfers"><divclass="titlepage"><div><div><h2class="title"><aname="xfrout"></a>Chapter<EFBFBD>10.<2E>Outbound Zone Transfers</h2></div></div></div><p>
</p></div></div><divclass="chapter"title="Chapter<65>12.<2E>Recursive Name Server"><divclass="titlepage"><div><div><h2class="title"><aname="resolverserver"></a>Chapter<EFBFBD>12.<2E>Recursive Name Server</h2></div></div></div><divclass="toc"><p><b>Table of Contents</b></p><dl><dt><spanclass="section"><ahref="#id1168229438327">Access Control</a></span></dt><dt><spanclass="section"><ahref="#id1168229438512">Forwarding</a></span></dt></dl></div><p>
><strongclass="userinput"><code>config set Resolver/query_acl[<emclass="replaceable"><code>2</code></em>]/action "ACCEPT"</code></strong>
><strongclass="userinput"><code>config set Resolver/query_acl[<emclass="replaceable"><code>2</code></em>]/from "<emclass="replaceable"><code>192.168.1.0/24</code></em>"</code></strong>
</pre><p>(Replace the <spanclass="quote">“<spanclass="quote"><emclass="replaceable"><code>2</code></em></span>”</span>
as needed; run <spanclass="quote">“<spanclass="quote"><strongclass="userinput"><code>config show
Resolver/query_acl</code></strong></span>”</span> if needed.)</p><divclass="note"title="Note"style="margin-left: 0.5in; margin-right: 0.5in;"><h3class="title">Note</h3><p>This prototype access control configuration
syntax may be changed.</p></div></div><divclass="section"title="Forwarding"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aname="id1168229438512"></a>Forwarding</h2></div></div></div><p>
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 <spanclass="quote">“<spanclass="quote">Resolver</span>”</span>. This
configuration will then be used by the loggers in the
Resolver module, and all the libraries used by it.
</p><p>
If you want to specify logging for one specific library
within the module, you set the name to
<emclass="replaceable"><code>module.library</code></em>. For example, the
logger used by the nameserver address store component
has the full name of <spanclass="quote">“<spanclass="quote">Resolver.nsas</span>”</span>. If
there is no entry in Logging for a particular library,
it will use the configuration given for the module.
</p><p>
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
<spanclass="quote">“<spanclass="quote">Resolver</span>”</span> and severity INFO, and one with
the name <spanclass="quote">“<spanclass="quote">Resolver.cache</span>”</span> with severity
DEBUG. As there are no entries for other libraries (e.g.
the nsas), they will use the configuration for the module
(<spanclass="quote">“<spanclass="quote">Resolver</span>”</span>), so giving the desired behavior.
</p><p>
One special case is that of a module name of <spanclass="quote">“<spanclass="quote">*</span>”</span>
(asterisks), which is interpreted as <spanclass="emphasis"><em>any</em></span>
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. <spanclass="quote">“<spanclass="quote">*.config</span>”</span>
specifies the configuration library code in whatever
module is using it).
</p><p>
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 <spanclass="quote">“<spanclass="quote">*</span>”</span> and <spanclass="quote">“<spanclass="quote">Resolver</span>”</span>, the
resolver module — and all libraries it uses —
will log messages according to the configuration in the
second entry (<spanclass="quote">“<spanclass="quote">Resolver</span>”</span>). All other modules
will use the configuration of the first entry
(<spanclass="quote">“<spanclass="quote">*</span>”</span>). If there was also a configuration
entry for <spanclass="quote">“<spanclass="quote">Resolver.cache</span>”</span>, the cache library
within the resolver would use that in preference to the
entry for <spanclass="quote">“<spanclass="quote">Resolver</span>”</span>.
</p><p>
One final note about the naming. When specifying the
module name within a logger, use the name of the module
as specified in <spanclass="command"><strong>bindctl</strong></span>, e.g.
<spanclass="quote">“<spanclass="quote">Resolver</span>”</span> for the resolver module,
<spanclass="quote">“<spanclass="quote">Xfrout</span>”</span> 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
<spanclass="quote">“<spanclass="quote">Auth.cache</span>”</span> logger will appear in the output
with a logger name of <spanclass="quote">“<spanclass="quote">b10-auth.cache</span>”</span>).
</p></div><divclass="section"title="additive (true or false)"><divclass="titlepage"><div><div><h4class="title"><aname="id1168229439117"></a>additive (true or false)</h4></div></div></div><p>
Depending on what is set as the output destination, this
value is interpreted as follows:
</p><divclass="variablelist"><dl><dt><spanclass="term"><codeclass="option">destination</code> is <spanclass="quote">“<spanclass="quote">console</span>”</span></span></dt><dd>
The value of output must be one of <spanclass="quote">“<spanclass="quote">stdout</span>”</span>
(messages printed to standard output) or
<spanclass="quote">“<spanclass="quote">stderr</span>”</span> (messages printed to standard
error).
</dd><dt><spanclass="term"><codeclass="option">destination</code> is <spanclass="quote">“<spanclass="quote">file</span>”</span></span></dt><dd>
The value of output is interpreted as a file name;
log messages will be appended to this file.
</dd><dt><spanclass="term"><codeclass="option">destination</code> is <spanclass="quote">“<spanclass="quote">syslog</span>”</span></span></dt><dd>
</p><divclass="section"title="flush (true of false)"><divclass="titlepage"><div><div><h5class="title"><aname="id1168229439286"></a>flush (true of false)</h5></div></div></div><p>
The message identification. Every message in BIND 10
has a unique identification, which can be used as an
index into the <aclass="ulink"href="bind10-messages.html"target="_top"><emclass="citetitle">BIND 10 Messages
Manual</em></a> (<aclass="ulink"href="http://bind10.isc.org/docs/bind10-messages.html"target="_top">http://bind10.isc.org/docs/bind10-messages.html</a>) from which more information can be obtained.
