<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 20111021. 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
20111021.</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
</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><dt><spanclass="section"><ahref="#bind10.config">Configuration of started processes</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="#id1168229438007">Server Configurations</a></span></dt><dt><spanclass="section"><ahref="#id1168229438072">Data Source Backends</a></span></dt><dt><spanclass="section"><ahref="#id1168229438171">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="#id1168229438302">Configuration for Incoming Zone Transfers</a></span></dt><dt><spanclass="section"><ahref="#id1168229438340">Enabling IXFR</a></span></dt><dt><spanclass="section"><ahref="#id1168229438382">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="#id1168229438673">Access Control</a></span></dt><dt><spanclass="section"><ahref="#id1168229438891">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="#id1168229439042">Logging configuration</a></span></dt><dd><dl><dt><spanclass="section"><ahref="#id1168229439052">Loggers</a></span></dt><dt><spanclass="section"><ahref="#id1168229439294">Output Options</a></span></dt><dt><spanclass="section"><ahref="#id1168229439468">Example session</a></span></dt></dl></dd><dt><spanclass="section"><ahref="#id1168229440023">Logging Message Format</a></span></dt></dl></dd></dl></div><divclass="list-of-tables"><p><b
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><dt><spanclass="section"><ahref="#bind10.config">Configuration of started processes</a></span></dt></dl></div><p>
</p></div></div><divclass="section"title="Configuration of started processes"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aname="bind10.config"></a>Configuration of started processes</h2></div></div></div><p>
The processes to be started can be configured, with the exception
of the <spanclass="command"><strong>b10-sockcreator</strong></span>, <spanclass="command"><strong>b10-msgq</strong></span>
and <spanclass="command"><strong>b10-cfgmgr</strong></span>.
</p><p>
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
Now, what it means. We add an entry called b10-resolver. It is both a
name used to reference this component in the configuration and the
name of the process to start. Then we set some parameters on how to
start it.
</p><p>
The special one is for components that need some kind of special care
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:
</p><divclass="table"><aname="id1168229437338"></a><pclass="title"><b>Table<EFBFBD>3.1.<2E></b></p><divclass="table-contents"><tableborder="1"><colgroup><colalign="left"><colalign="left"><colalign="left"></colgroup><thead><tr><thalign="left">Component</th><thalign="left">Special</th><thalign="left">Description</th></tr></thead><tbody><tr><tdalign="left">b10-auth</td><tdalign="left">auth</td><tdalign="left">Authoritative server</td></tr><tr><tdalign="left">b10-resolver</td><tdalign="left">resolver</td><tdalign="left">The resolver</td></tr><tr><tdalign="left">b10-cmdctl</td><tdalign="left">cmdctl</td><tdalign="left">The command control (remote control interface)</td></tr><tr><tdalign="left">setuid</td><tdalign="left">setuid</td><tdalign="left">Virtual component, see below</td></tr></tbody></table></div></div><p><brclass="table-break">
</p><p>
The kind specifies how a failure of the component should
be handled. If it is set to <spanclass="quote">“<spanclass="quote">dispensable</span>”</span>
(the default unless you set something else), it will get
started again if it fails. If it is set to <spanclass="quote">“<spanclass="quote">needed</span>”</span>
and it fails at startup, the whole <spanclass="command"><strong>bind10</strong></span>
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 <spanclass="quote">“<spanclass="quote">core</span>”</span>, 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 core as well if you wish (but you can
turn these off, they just can't fail).
</p><p>
The priority defines order in which the components should start.
The ones with higher number are started sooner than the ones with
lower ones. If you don't set it, 0 (zero) is used as the priority.
</p><p>
There are other parameters we didn't use in our example.
One of them is <spanclass="quote">“<spanclass="quote">address</span>”</span>. It is the address
used by the component on the <spanclass="command"><strong>b10-msgq</strong></span>
message bus. The special components already know their
address, but the usual ones don't. The address is by
convention the thing after <spanclass="emphasis"><em>b10-</em></span>, with
the first letter capital (eg. <spanclass="command"><strong>b10-stats</strong></span>
would have <spanclass="quote">“<spanclass="quote">Stats</span>”</span> as its address).
</p><p>
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
</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="id1168229438171"></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="#id1168229438302">Configuration for Incoming Zone Transfers</a></span></dt><dt><spanclass="section"><ahref="#id1168229438340">Enabling IXFR</a></span></dt><dt><spanclass="section"><ahref="#id1168229438382">Trigger an Incoming Zone Transfer Manually</a></span></dt></dl></div><p>
</p></div><divclass="section"title="Configuration for Incoming Zone Transfers"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aname="id1168229438302"></a>Configuration for Incoming Zone Transfers</h2></div></div></div><p>
</p></div></div><divclass="section"title="Trigger an Incoming Zone Transfer Manually"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aname="id1168229438382"></a>Trigger an Incoming Zone Transfer Manually</h2></div></div></div><p>
</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="#id1168229438673">Access Control</a></span></dt><dt><spanclass="section"><ahref="#id1168229438891">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="id1168229438891"></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="id1168229439258"></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="id1168229439427"></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.
