bind10-guide.html 154 KB
Newer Older
1
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>BIND 10 Guide</title><link rel="stylesheet" href="./bind10-guide.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><meta name="description" content="BIND 10 is a framework that features Domain Name System (DNS) suite and Dynamic Host Configuration Protocol (DHCP) servers with development managed by Internet Systems Consortium (ISC). It includes DNS libraries, modular components for controlling authoritative and recursive DNS servers, and experimental DHCPv4 and DHCPv6 servers. This is the reference guide for BIND 10 version 20120712. 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><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" title="BIND 10 Guide"><div class="titlepage"><div><div><h1 class="title"><a name="idp25872"></a>BIND 10 Guide</h1></div><div><h2 class="subtitle">Administrator Reference for BIND 10</h2></div><div><p class="releaseinfo">This is the reference guide for BIND 10 version
2
        20120712.</p></div><div><p class="copyright">Copyright © 2010-2012 Internet Systems Consortium, Inc.</p></div><div><div class="abstract" title="Abstract"><p class="title"><b>Abstract</b></p><p>BIND 10 is a framework that features Domain Name System
3
      (DNS) suite and Dynamic Host Configuration Protocol (DHCP)
4 5
      servers with development managed by Internet Systems Consortium (ISC).
      It includes DNS libraries, modular components for controlling
6 7
      authoritative and recursive DNS servers, and experimental DHCPv4
      and DHCPv6 servers.
8
      </p><p>
9
        This is the reference guide for BIND 10 version 20120712.
10 11 12
        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 <a class="ulink" href="http://bind10.isc.org/docs" target="_top">http://bind10.isc.org/docs</a>.
13
        </p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="#idp32704">Preface</a></span></dt><dd><dl><dt><span class="section"><a href="#acknowledgements">1. Acknowledgements</a></span></dt></dl></dd><dt><span class="chapter"><a href="#intro">1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#idp38720">1.1. Supported Platforms</a></span></dt><dt><span class="section"><a href="#required-software">1.2. Required Software at Run-time</a></span></dt><dt><span class="section"><a href="#starting_stopping">1.3. Starting and Stopping the Server</a></span></dt><dt><span class="section"><a href="#managing_once_running">1.4. Managing BIND 10</a></span></dt></dl></dd><dt><span class="chapter"><a href="#installation">2. Installation</a></span></dt><dd><dl><dt><span class="section"><a href="#packages">2.1. Packages</a></span></dt><dt><span class="section"><a href="#install-hierarchy">2.2. Install Hierarchy</a></span></dt><dt><span class="section"><a href="#build-requirements">2.3. Building Requirements</a></span></dt><dt><span class="section"><a href="#quickstart">2.4. Quick start</a></span></dt><dt><span class="section"><a href="#install">2.5. Installation from source</a></span></dt><dd><dl><dt><span class="section"><a href="#idp146688">2.5.1. Download Tar File</a></span></dt><dt><span class="section"><a href="#idp149472">2.5.2. Retrieve from Git</a></span></dt><dt><span class="section"><a href="#idp158496">2.5.3. Configure before the build</a></span></dt><dt><span class="section"><a href="#idp171840">2.5.4. Build</a></span></dt><dt><span class="section"><a href="#idp173824">2.5.5. Install</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#bind10">3. Starting BIND10 with <span class="command"><strong>bind10</strong></span></a></span></dt><dd><dl><dt><span class="section"><a href="#start">3.1. Starting BIND 10</a></span></dt><dt><span class="section"><a href="#bind10.config">3.2. Configuration to start processes</a></span></dt></dl></dd><dt><span class="chapter"><a href="#msgq">4. Command channel</a></span></dt><dt><span class="chapter"><a href="#cfgmgr">5. Configuration manager</a></span></dt><dt><span class="chapter"><a href="#cmdctl">6. Remote control daemon</a></span></dt><dd><dl><dt><span class="section"><a href="#cmdctl.spec">6.1. Configuration specification for b10-cmdctl</a></span></dt></dl></dd><dt><span class="chapter"><a href="#bindctl">7. Control and configure user interface</a></span></dt><dt><span class="chapter"><a href="#authserver">8. Authoritative Server</a></span></dt><dd><dl><dt><span class="section"><a href="#idp288016">8.1. Server Configurations</a></span></dt><dt><span class="section"><a href="#datasrc">8.2. Data Source Backends</a></span></dt><dd><dl><dt><span class="section"><a href="#datasource-types">8.2.1. Data source types</a></span></dt><dt><span class="section"><a href="#datasrc-examples">8.2.2. Examples</a></span></dt></dl></dd><dt><span class="section"><a href="#idp357664">8.3. Loading Master Zones Files</a></span></dt></dl></dd><dt><span class="chapter"><a href="#xfrin">9. Incoming Zone Transfers</a></span></dt><dd><dl><dt><span class="section"><a href="#idp375872">9.1. Configuration for Incoming Zone Transfers</a></span></dt><dt><span class="section"><a href="#idp381216">9.2. Enabling IXFR</a></span></dt><dt><span class="section"><a href="#zonemgr">9.3. Secondary Manager</a></span></dt><dt><span class="section"><a href="#idp396992">9.4. Trigger an Incoming Zone Transfer Manually</a></span></dt><dt><span class="section"><a href="#idp400688">9.5. Incoming Transfers with In-memory Datasource</a></span></dt></dl></dd><dt><span class="chapter"><a href="#xfrout">10. Outbound Zone Transfers</a></span></dt><dt><span class="chapter"><a href="#ddns">11. Dynamic DNS Update</a></span></dt><dd><dl><dt><span class="section"><a href="#idp434672">11.1. Enabling Dynamic Update</a></span></dt><dt><span class="section"><a href="#idp450256">11.2. Access Control</a></span></dt><dt><span class="section"><a href="#idp475168">11.3. Miscellaneous Operational Issues</a></span></dt></dl></dd><dt><span class="chapter"><a href="#resolverserver">12. Recursive Name Server</a></span></dt><dd><dl><dt><span class="section"><a href="#idp496224">12.1. Access Control</a></span></dt><dt><span class="section"><a href="#idp512960">12.2. Forwarding</a></span></dt></dl></dd><dt><span class="chapter"><a href="#dhcp4">13. DHCPv4 Server</a></span></dt><dd><dl><dt><span class="section"><a href="#dhcp4-usage">13.1. DHCPv4 Server Usage</a></span></dt><dt><span class="section"><a href="#dhcp4-config">13.2. DHCPv4 Server Configuration</a></span></dt><dt><span class="section"><a href="#dhcp4-std">13.3. Supported standards</a></span></dt><dt><span class="section"><a href="#dhcp4-limit">13.4. DHCPv4 Server Limitations</a></span></dt></dl></dd><dt><span class="chapter"><a href="#dhcp6">14. DHCPv6 Server</a></span></dt><dd><dl><dt><span class="section"><a href="#dhcp6-usage">14.1. DHCPv6 Server Usage</a></span></dt><dt><span class="section"><a href="#dhcp6-config">14.2. DHCPv6 Server Configuration</a></span></dt><dt><span class="section"><a href="#dhcp6-std">14.3. Supported DHCPv6 Standards</a></span></dt><dt><span class="section"><a href="#dhcp6-limit">14.4. DHCPv6 Server Limitations</a></span></dt></dl></dd><dt><span class="chapter"><a href="#libdhcp">15. libdhcp++ library</a></span></dt><dd><dl><dt><span class="section"><a href="#iface-detect">15.1. Interface detection</a></span></dt><dt><span class="section"><a href="#packet-handling">15.2. DHCPv4/DHCPv6 packet handling</a></span></dt></dl></dd><dt><span class="chapter"><a href="#statistics">16. Statistics</a></span></dt><dt><span class="chapter"><a href="#logging">17. Logging</a></span></dt><dd><dl><dt><span class="section"><a href="#idp611696">17.1. Logging configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#idp613392">17.1.1. Loggers</a></span></dt><dt><span class="section"><a href="#idp649760">17.1.2. Output Options</a></span></dt><dt><span class="section"><a href="#idp674816">17.1.3. Example session</a></span></dt></dl></dd><dt><span class="section"><a href="#idp705584">17.2. Logging Message Format</a></span></dt></dl></dd></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>3.1. <a href="#idp200656">Special startup components</a></dt></dl></div><div class="preface" title="Preface"><div class="titlepage"><div><div><h2 class="title"><a name="idp32704"></a>Preface</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#acknowledgements">1. Acknowledgements</a></span></dt></dl></div><div class="section" title="1. Acknowledgements"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="acknowledgements"></a>1. Acknowledgements</h2></div></div></div><p>ISC would like to acknowledge generous support for
14
      BIND 10 development of DHCPv4 and DHCPv6 components provided
15
      by <a class="ulink" href="http://www.comcast.com/" target="_top">Comcast</a>.</p></div></div><div class="chapter" title="Chapter 1. Introduction"><div class="titlepage"><div><div><h2 class="title"><a name="intro"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp38720">1.1. Supported Platforms</a></span></dt><dt><span class="section"><a href="#required-software">1.2. Required Software at Run-time</a></span></dt><dt><span class="section"><a href="#starting_stopping">1.3. Starting and Stopping the Server</a></span></dt><dt><span class="section"><a href="#managing_once_running">1.4. Managing BIND 10</a></span></dt></dl></div><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
16 17
      BIND is the popular implementation of a DNS server, developer
      interfaces, and DNS tools.
18 19 20
      BIND 10 is a rewrite of BIND 9 and ISC DHCP.
      BIND 10 is written in C++ and Python and provides a modular
      environment for serving, maintaining, and developing DNS and DHCP.
21 22 23
      BIND 10 provides a EDNS0- and DNSSEC-capable authoritative
      DNS server and a caching recursive name server which also
      provides forwarding.
24
      It also provides experimental DHCPv4 and DHCPv6 servers.
25 26
    </p><p>
      This guide covers the experimental prototype of
27
      BIND 10 version 20120712.
28
    </p><div class="section" title="1.1. Supported Platforms"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp38720"></a>1.1. Supported Platforms</h2></div></div></div><p>
29
  BIND 10 builds have been tested on (in no particular order)
30
  Debian GNU/Linux 6 and unstable, Ubuntu 9.10, NetBSD 5,
31 32
  Solaris 10 and 11, FreeBSD 7 and 8, CentOS Linux 5.3,
  MacOS 10.6 and 10.7, and OpenBSD 5.1.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
33 34 35 36 37 38

  It has been tested on Sparc, i386, and amd64 hardware
  platforms.

        It is planned for BIND 10 to build, install and run on
        Windows and standard Unix-type platforms.
39 40 41 42 43 44 45 46
      </p></div><div class="section" title="1.2. Required Software at Run-time"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="required-software"></a>1.2. Required Software at Run-time</h2></div></div></div><p>
        Running BIND 10 uses various extra software which may
        not be provided in some operating systems' default
        installations nor standard packages collections. You may
        need to install this required software separately.
        (For the build requirements, also see
        <a class="xref" href="#build-requirements" title="2.3. Building Requirements">Section 2.3, &#8220;Building Requirements&#8221;</a>.)
      </p><p>
47 48
        BIND 10 requires at least Python 3.1
        (<a class="ulink" href="http://www.python.org/" target="_top">http://www.python.org/</a>).
49
        It also works with Python 3.2.
50 51 52 53
      </p><p>
        BIND 10 uses the Botan crypto library for C++
        (<a class="ulink" href="http://botan.randombit.net/" target="_top">http://botan.randombit.net/</a>).
        It requires at least Botan version 1.8.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
54
      </p><p>
55 56 57
        BIND 10 uses the log4cplus C++ logging library
        (<a class="ulink" href="http://log4cplus.sourceforge.net/" target="_top">http://log4cplus.sourceforge.net/</a>).
        It requires at least log4cplus version 1.0.3.
58

59
      </p><p>
60 61 62 63
        The authoritative DNS server uses SQLite3
        (<a class="ulink" href="http://www.sqlite.org/" target="_top">http://www.sqlite.org/</a>).

        It needs at least SQLite version 3.3.9.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
64
      </p><p>
65 66 67 68
        The <span class="command"><strong>b10-ddns</strong></span>, <span class="command"><strong>b10-xfrin</strong></span>,
        <span class="command"><strong>b10-xfrout</strong></span>, and <span class="command"><strong>b10-zonemgr</strong></span>
        components require the libpython3 library and the Python
        _sqlite3.so module (which is included with Python).
69 70
        Python modules need to be built for the corresponding Python 3.
      </p></div><div class="section" title="1.3. Starting and Stopping the Server"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="starting_stopping"></a>1.3. Starting and Stopping the Server</h2></div></div></div><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
71 72
        BIND 10 is modular.  Part of this modularity is
        accomplished using multiple cooperating processes which, together,
73 74 75
        provide the server functionality.  This is a change from
        the previous generation of BIND software, which used a
        single process.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
76
      </p><p>
77 78 79 80 81 82 83
        At first, running many different processes may seem confusing.
        However, these processes are started, stopped, and maintained
        by a single command, <span class="command"><strong>bind10</strong></span>.
        This command starts a master process which will start other
        processes as needed.
        The processes started by the <span class="command"><strong>bind10</strong></span>
        command have names starting with "b10-", including:
Jeremy C. Reed's avatar
Jeremy C. Reed committed
84 85 86 87
      </p><p>

        </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
              <span class="command"><strong>b10-auth</strong></span> &#8212;
88
              Authoritative DNS server.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
89 90 91
              This process serves DNS requests.
            </li><li class="listitem">
              <span class="command"><strong>b10-cfgmgr</strong></span> &#8212;
92
              Configuration manager.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
93 94 95
              This process maintains all of the configuration for BIND 10.
            </li><li class="listitem">
              <span class="command"><strong>b10-cmdctl</strong></span> &#8212;
96
              Command and control service.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
97
              This process allows external control of the BIND 10 system.
98 99 100 101 102 103
            </li><li class="listitem">
              <span class="command"><strong>b10-ddns</strong></span> &#8212;
              Dynamic DNS update service.
              This process is used to handle incoming DNS update
              requests to allow granted clients to update zones
	      for which BIND 10 is serving as a primary server.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
104 105 106 107 108
            </li><li class="listitem">
              <span class="command"><strong>b10-msgq</strong></span> &#8212;
              Message bus daemon.
              This process coordinates communication between all of the other
              BIND 10 processes.
109 110 111
            </li><li class="listitem">
              <span class="command"><strong>b10-resolver</strong></span> &#8212;
              Recursive name server.
112 113
              This process handles incoming DNS queries and provides
              answers from its cache or by recursively doing remote lookups.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
114 115 116 117 118
            </li><li class="listitem">
              <span class="command"><strong>b10-sockcreator</strong></span> &#8212;
              Socket creator daemon.
              This process creates sockets used by
              network-listening BIND 10 processes.
119 120 121 122
            </li><li class="listitem">
              <span class="command"><strong>b10-stats</strong></span> &#8212;
              Statistics collection daemon.
              This process collects and reports statistics data.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
123 124 125 126
            </li><li class="listitem">
              <span class="command"><strong>b10-stats-httpd</strong></span> &#8212;
              HTTP server for statistics reporting.
              This process reports statistics data in XML format over HTTP.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
127 128 129
            </li><li class="listitem">
              <span class="command"><strong>b10-xfrin</strong></span> &#8212;
              Incoming zone transfer service.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
130
              This process is used to transfer a new copy
Jeremy C. Reed's avatar
Jeremy C. Reed committed
131
              of a zone into BIND 10, when acting as a secondary server.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
132 133 134
            </li><li class="listitem">
              <span class="command"><strong>b10-xfrout</strong></span> &#8212;
              Outgoing zone transfer service.
135
              This process is used to handle transfer requests to
136
              send a local zone to a remote secondary server.
137 138
            </li><li class="listitem">
              <span class="command"><strong>b10-zonemgr</strong></span> &#8212;
139
              Secondary zone manager.
140
              This process keeps track of timers and other
141
              necessary information for BIND 10 to act as a slave server.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
142
            </li></ul></div><p>
143
      </p><p>
144 145
        These are ran by <span class="command"><strong>bind10</strong></span>
        and do not need to be manually started independently.
146
      </p></div><div class="section" title="1.4. Managing BIND 10"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="managing_once_running"></a>1.4. Managing BIND 10</h2></div></div></div><p>
147 148
        Once BIND 10 is running, a few commands are used to interact
        directly with the system:
Jeremy C. Reed's avatar
Jeremy C. Reed committed
149 150
        </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
              <span class="command"><strong>bindctl</strong></span> &#8212;
151
              Interactive administration interface.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
152 153 154
              This is a low-level command-line tool which allows
              a developer or an experienced administrator to control
              BIND 10.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
155 156
            </li><li class="listitem">
              <span class="command"><strong>b10-loadzone</strong></span> &#8212;
157
              Zone file loader.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
158 159 160 161
              This tool will load standard masterfile-format zone files into
              BIND 10.
            </li><li class="listitem">
              <span class="command"><strong>b10-cmdctl-usermgr</strong></span> &#8212;
162
              User access control.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
163 164 165 166 167 168 169 170 171 172 173 174 175
              This tool allows an administrator to authorize additional users
              to manage BIND 10.
            </li></ul></div><p>
      </p></div><p>
      The tools and modules are covered in full detail in this guide.

      In addition, manual pages are also provided in the default installation.
    </p><p>
      BIND 10 also provides libraries and programmer interfaces
      for C++ and Python for the message bus, configuration backend,
      and, of course, DNS. These include detailed developer
      documentation and code examples.

176

177
    </p></div><div class="chapter" title="Chapter 2. Installation"><div class="titlepage"><div><div><h2 class="title"><a name="installation"></a>Chapter 2. Installation</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#packages">2.1. Packages</a></span></dt><dt><span class="section"><a href="#install-hierarchy">2.2. Install Hierarchy</a></span></dt><dt><span class="section"><a href="#build-requirements">2.3. Building Requirements</a></span></dt><dt><span class="section"><a href="#quickstart">2.4. Quick start</a></span></dt><dt><span class="section"><a href="#install">2.5. Installation from source</a></span></dt><dd><dl><dt><span class="section"><a href="#idp146688">2.5.1. Download Tar File</a></span></dt><dt><span class="section"><a href="#idp149472">2.5.2. Retrieve from Git</a></span></dt><dt><span class="section"><a href="#idp158496">2.5.3. Configure before the build</a></span></dt><dt><span class="section"><a href="#idp171840">2.5.4. Build</a></span></dt><dt><span class="section"><a href="#idp173824">2.5.5. Install</a></span></dt></dl></dd></dl></div><div class="section" title="2.1. Packages"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="packages"></a>2.1. Packages</h2></div></div></div><p>
178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226
        Some operating systems or softare package vendors may
        provide ready-to-use, pre-built software packages for
        the BIND 10 suite.
        Installing a pre-built package means you do not need to
        install build-only prerequisites and do not need to
        <span class="emphasis"><em>make</em></span> the software.
      </p><p>
        FreeBSD ports, NetBSD pkgsrc, and Debian
        <span class="emphasis"><em>testing</em></span> package collections provide
        all the prerequisite packages.
      </p></div><div class="section" title="2.2. Install Hierarchy"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-hierarchy"></a>2.2. Install Hierarchy</h2></div></div></div><p>
        The following is the standard, common layout of the
        complete BIND 10 installation:
        </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
              <code class="filename">bin/</code> &#8212;
              general tools and diagnostic clients.
            </li><li class="listitem">
            <code class="filename">etc/bind10-devel/</code> &#8212;
            configuration files.
          </li><li class="listitem">
              <code class="filename">lib/</code> &#8212;
              libraries and python modules.
            </li><li class="listitem">
              <code class="filename">libexec/bind10-devel/</code> &#8212;
              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 <span class="command"><strong>bind10</strong></span> tool.
            </li><li class="listitem">
              <code class="filename">sbin/</code> &#8212;
              commands used by the system administrator.
            </li><li class="listitem">
              <code class="filename">share/bind10-devel/</code> &#8212;
              configuration specifications.
            </li><li class="listitem">
              <code class="filename">share/doc/bind10-devel/</code> &#8212;
              this guide and other supplementary documentation.
            </li><li class="listitem">
              <code class="filename">share/man/</code> &#8212;
              manual pages (online documentation).
            </li><li class="listitem">
              <code class="filename">var/bind10-devel/</code> &#8212;
              data source and configuration databases.
            </li></ul></div><p>
      </p></div><div class="section" title="2.3. Building Requirements"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="build-requirements"></a>2.3. Building Requirements</h2></div></div></div><p>
          In addition to the run-time requirements (listed in
          <a class="xref" href="#required-software" title="1.2. Required Software at Run-time">Section 1.2, &#8220;Required Software at Run-time&#8221;</a>), building BIND 10
          from source code requires various development include headers and
          program development tools.
227
        </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
228 229 230 231 232 233
            Some operating systems have split their distribution packages into
            a run-time and a development package.  You will need to install
            the development package versions, which include header files and
            libraries, to build BIND 10 from source code.
          </p></div><p>
          Building from source code requires the Boost
234 235 236
          build-time headers
          (<a class="ulink" href="http://www.boost.org/" target="_top">http://www.boost.org/</a>).
          At least Boost version 1.35 is required.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
237 238 239
  
  
        </p><p>
240 241
          To build BIND 10, also install the Botan (at least version
          1.8) and the log4cplus (at least version 1.0.3)
242 243
          development include headers.
        </p><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
244
          Building BIND 10 also requires a C++ compiler and
Jeremy C. Reed's avatar
Jeremy C. Reed committed
245
          standard development headers, make, and pkg-config.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
246
          BIND 10 builds have been tested with GCC g++ 3.4.3, 4.1.2,
247
          4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10.
248
        </p><p>
249
          Visit the user-contributed wiki at <a class="ulink" href="http://bind10.isc.org/wiki/SystemSpecificNotes" target="_top">http://bind10.isc.org/wiki/SystemSpecificNotes</a>
250
          for system-specific installation tips.
251
        </p></div><div class="section" title="2.4. Quick start"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="quickstart"></a>2.4. Quick start</h2></div></div></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
252 253 254 255 256 257 258
          This quickly covers the standard steps for installing
          and deploying BIND 10 as an authoritative name server using
          its defaults. For troubleshooting, full customizations and further
          details, see the respective chapters in the BIND 10 guide.
        </p></div><p>
        To quickly get started with BIND 10, follow these steps.
      </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
259
            Install required run-time and build dependencies.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
260 261 262 263 264 265 266 267 268 269 270 271 272 273 274
          </li><li class="listitem">
            Download the BIND 10 source tar file from
            <a class="ulink" href="ftp://ftp.isc.org/isc/bind10/" target="_top">ftp://ftp.isc.org/isc/bind10/</a>.
          </li><li class="listitem"><p>Extract the tar file:
          </p><pre class="screen">$ <strong class="userinput"><code>gzcat bind10-<em class="replaceable"><code>VERSION</code></em>.tar.gz | tar -xvf -</code></strong></pre><p>
          </p></li><li class="listitem"><p>Go into the source and run configure:
            </p><pre class="screen">$ <strong class="userinput"><code>cd bind10-<em class="replaceable"><code>VERSION</code></em></code></strong>
  $ <strong class="userinput"><code>./configure</code></strong></pre><p>
          </p></li><li class="listitem"><p>Build it:
            </p><pre class="screen">$ <strong class="userinput"><code>make</code></strong></pre><p>
          </p></li><li class="listitem"><p>Install it (to default /usr/local):
            </p><pre class="screen">$ <strong class="userinput"><code>make install</code></strong></pre><p>
          </p></li><li class="listitem"><p>Start the server:
            </p><pre class="screen">$ <strong class="userinput"><code>/usr/local/sbin/bind10</code></strong></pre><p>
          </p></li><li class="listitem"><p>Test it; for example:
275
            </p><pre class="screen">$ <strong class="userinput"><code>dig @127.0.0.1 -c CH -t TXT authors.bind</code></strong></pre><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
276 277 278 279
         </p></li><li class="listitem"><p>Load desired zone file(s), for example:
            </p><pre class="screen">$ <strong class="userinput"><code>b10-loadzone <em class="replaceable"><code>your.zone.example.org</code></em></code></strong></pre><p>
          </p></li><li class="listitem">
            Test the new zone.
280
          </li></ol></div></div><div class="section" title="2.5. Installation from source"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install"></a>2.5. Installation from source</h2></div></div></div><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
281
        BIND 10 is open source software written in C++ and Python.
282 283 284 285
        It is freely available in source code form from ISC as a
        downloadable tar file or via BIND 10's Git code revision control
        service. (It may also be available in pre-compiled ready-to-use
        packages from operating system vendors.)
286
      </p><div class="section" title="2.5.1. Download Tar File"><div class="titlepage"><div><div><h3 class="title"><a name="idp146688"></a>2.5.1. Download Tar File</h3></div></div></div><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
287 288 289 290 291 292
          Downloading a release tar file is the recommended method to
          obtain the source code.
        </p><p>
          The BIND 10 releases are available as tar file downloads from
          <a class="ulink" href="ftp://ftp.isc.org/isc/bind10/" target="_top">ftp://ftp.isc.org/isc/bind10/</a>.
          Periodic development snapshots may also be available.
293
        </p></div><div class="section" title="2.5.2. Retrieve from Git"><div class="titlepage"><div><div><h3 class="title"><a name="idp149472"></a>2.5.2. Retrieve from Git</h3></div></div></div><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
294 295 296 297
          Downloading this "bleeding edge" code is recommended only for
          developers or advanced users.  Using development code in a production
          environment is not recommended.
        </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
298
            When using source code retrieved via Git, additional
Jeremy C. Reed's avatar
Jeremy C. Reed committed
299 300 301 302
            software will be required:  automake (v1.11 or newer),
            libtoolize, and autoconf (2.59 or newer).
            These may need to be installed.
          </p></div><p>
303 304
          The latest development code (and temporary experiments
          and un-reviewed code) is available via the BIND 10 code revision
305
          control system. This is powered by Git and all the BIND 10
Jeremy C. Reed's avatar
Jeremy C. Reed committed
306
          development is public.
307 308
          The leading development is done in the <span class="quote">&#8220;<span class="quote">master</span>&#8221;</span>
          branch.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
309
        </p><p>
310
          The code can be checked out from
311
          <code class="filename">git://git.bind10.isc.org/bind10</code>;
312
          for example:
Jeremy C. Reed's avatar
Jeremy C. Reed committed
313

314
        </p><pre class="screen">$ <strong class="userinput"><code>git clone git://git.bind10.isc.org/bind10</code></strong></pre><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
315 316 317
        </p><p>
          When checking out the code from
          the code version control system, it doesn't include the
318 319
          generated configure script, Makefile.in files, nor their
          related build files.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
320 321 322 323 324 325 326 327
          They can be created by running <span class="command"><strong>autoreconf</strong></span>
          with the <code class="option">--install</code> switch.
          This will run <span class="command"><strong>autoconf</strong></span>,
          <span class="command"><strong>aclocal</strong></span>,
          <span class="command"><strong>libtoolize</strong></span>,
          <span class="command"><strong>autoheader</strong></span>,
          <span class="command"><strong>automake</strong></span>,
          and related commands.
328
        </p></div><div class="section" title="2.5.3. Configure before the build"><div class="titlepage"><div><div><h3 class="title"><a name="idp158496"></a>2.5.3. Configure before the build</h3></div></div></div><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
329 330 331 332 333 334
          BIND 10 uses the GNU Build System to discover build environment
          details.
          To generate the makefiles using the defaults, simply run:
          </p><pre class="screen">$ <strong class="userinput"><code>./configure</code></strong></pre><p>
        </p><p>
          Run <span class="command"><strong>./configure</strong></span> with the <code class="option">--help</code>
335
          switch to view the different options. Some commonly-used options are:
Jeremy C. Reed's avatar
Jeremy C. Reed committed
336

337
          </p><div class="variablelist"><dl><dt><span class="term">--prefix</span></dt><dd>Define the installation location (the
Jeremy C. Reed's avatar
Jeremy C. Reed committed
338
                default is <code class="filename">/usr/local/</code>).
Jeremy C. Reed's avatar
Jeremy C. Reed committed
339
              </dd><dt><span class="term">--with-boost-include</span></dt><dd>Define the path to find the Boost headers.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
340 341 342 343 344
              </dd><dt><span class="term">--with-pythonpath</span></dt><dd>Define the path to Python 3.1 if it is not in the
                standard execution path.
              </dd><dt><span class="term">--with-gtest</span></dt><dd>Enable building the C++ Unit Tests using the
                Google Tests framework. Optionally this can define the
                path to the gtest header files and library.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
345 346 347
              </dd></dl></div><p>

        </p><p>
348
          For example, the following configures it to
349
    find the Boost headers, find the
Jeremy C. Reed's avatar
Jeremy C. Reed committed
350 351
    Python interpreter, and sets the installation location:

352
          </p><pre class="screen">$ <strong class="userinput"><code>./configure \
Jeremy C. Reed's avatar
Jeremy C. Reed committed
353 354 355 356 357 358
      --with-boost-include=/usr/pkg/include \
      --with-pythonpath=/usr/pkg/bin/python3.1 \
      --prefix=/opt/bind10</code></strong></pre><p>
        </p><p>
          If the configure fails, it may be due to missing or old
          dependencies.
359
        </p></div><div class="section" title="2.5.4. Build"><div class="titlepage"><div><div><h3 class="title"><a name="idp171840"></a>2.5.4. Build</h3></div></div></div><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
360 361 362 363
    After the configure step is complete, to build the executables
    from the C++ code and prepare the Python scripts, run:

          </p><pre class="screen">$ <strong class="userinput"><code>make</code></strong></pre><p>
364
        </p></div><div class="section" title="2.5.5. Install"><div class="titlepage"><div><div><h3 class="title"><a name="idp173824"></a>2.5.5. Install</h3></div></div></div><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
365 366 367
          To install the BIND 10 executables, support files,
          and documentation, run:
          </p><pre class="screen">$ <strong class="userinput"><code>make install</code></strong></pre><p>
368
        </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The install step may require superuser privileges.</p></div></div></div></div><div class="chapter" title="Chapter 3. Starting BIND10 with bind10"><div class="titlepage"><div><div><h2 class="title"><a name="bind10"></a>Chapter 3. Starting BIND10 with <span class="command"><strong>bind10</strong></span></h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#start">3.1. Starting BIND 10</a></span></dt><dt><span class="section"><a href="#bind10.config">3.2. Configuration to start processes</a></span></dt></dl></div><p>
369
      BIND 10 provides the <span class="command"><strong>bind10</strong></span> command which
Jeremy C. Reed's avatar
Jeremy C. Reed committed
370 371
      starts up the required processes.
      <span class="command"><strong>bind10</strong></span>
372
      will also restart some processes that exit unexpectedly.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
373 374
      This is the only command needed to start the BIND 10 system.
    </p><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
375
      After starting the <span class="command"><strong>b10-msgq</strong></span> communications channel,
376
      <span class="command"><strong>bind10</strong></span> connects to it,
Jeremy C. Reed's avatar
Jeremy C. Reed committed
377 378 379
      runs the configuration manager, and reads its own configuration.
      Then it starts the other modules.
    </p><p>
380 381
      The <span class="command"><strong>b10-sockcreator</strong></span>, <span class="command"><strong>b10-msgq</strong></span> and
      <span class="command"><strong>b10-cfgmgr</strong></span>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
382
      services make up the core. The <span class="command"><strong>b10-msgq</strong></span> daemon
Jeremy C. Reed's avatar
Jeremy C. Reed committed
383 384 385 386
      provides the communication channel between every part of the system.
      The <span class="command"><strong>b10-cfgmgr</strong></span> daemon is always needed by every
      module, if only to send information about themselves somewhere,
      but more importantly to ask about their own settings, and
387 388 389
      about other modules. The <span class="command"><strong>b10-sockcreator</strong></span> daemon
      helps allocate Internet addresses and ports as needed for BIND 10
      network services.
390 391 392
    </p><p>
      In its default configuration, the <span class="command"><strong>bind10</strong></span>
      master process will also start up
Jeremy C. Reed's avatar
Jeremy C. Reed committed
393
      <span class="command"><strong>b10-cmdctl</strong></span> for administration tools to
394 395
      communicate with the system, and
      <span class="command"><strong>b10-stats</strong></span> for statistics collection.
396
    </p><div class="section" title="3.1. Starting BIND 10"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="start"></a>3.1. Starting BIND 10</h2></div></div></div><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
397 398 399
        To start the BIND 10 service, simply run <span class="command"><strong>bind10</strong></span>.
        Run it with the <code class="option">--verbose</code> switch to
        get additional debugging or diagnostic output.
400 401 402 403 404
      </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
          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 <span class="quote">&#8220;<span class="quote">python</span>&#8221;</span>.
          This is not needed on some operating systems.
405 406 407 408 409 410 411 412 413
        </p></div></div><div class="section" title="3.2. Configuration to start processes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="bind10.config"></a>3.2. Configuration to start processes</h2></div></div></div><p>
	The processes to be used can be configured for
	<span class="command"><strong>bind10</strong></span> to start, with the exception
	of the required <span class="command"><strong>b10-sockcreator</strong></span>,
	<span class="command"><strong>b10-msgq</strong></span> and <span class="command"><strong>b10-cfgmgr</strong></span>
	components.
	The configuration is in the <code class="varname">Boss/components</code>
	section. Each element represents one component, which is
	an abstraction of a process.
414
      </p><p>
415 416
	To add a process to the set, let's say the resolver (which
	is not started by default), you would do this:
417 418 419 420 421
        </p><pre class="screen">&gt; <strong class="userinput"><code>config add Boss/components b10-resolver</code></strong>
&gt; <strong class="userinput"><code>config set Boss/components/b10-resolver/special resolver</code></strong>
&gt; <strong class="userinput"><code>config set Boss/components/b10-resolver/kind needed</code></strong>
&gt; <strong class="userinput"><code>config set Boss/components/b10-resolver/priority 10</code></strong>
&gt; <strong class="userinput"><code>config commit</code></strong></pre><p>
422 423 424 425 426
	Now, what it means. We add an entry called
	<span class="quote">&#8220;<span class="quote">b10-resolver</span>&#8221;</span>. 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.
427
      </p><p>
428 429 430 431 432 433 434
	The <code class="varname">special</code> setting is for components
	that need some kind of special care during startup or
	shutdown. Unless specified, the component is started in a
	usual way. This is the list of components that need to be
	started in a special way, with the value of special used
	for them:

435
        </p><div class="table"><a name="idp200656"></a><p class="title"><b>Table 3.1. Special startup components</b></p><div class="table-contents"><table summary="Special startup components" border="1"><colgroup><col align="left"><col align="left"><col align="left"></colgroup><thead><tr><th align="left">Component</th><th align="left">Special</th><th align="left">Description</th></tr></thead><tbody><tr><td align="left">b10-auth</td><td align="left">auth</td><td align="left">Authoritative DNS server</td></tr><tr><td align="left">b10-resolver</td><td align="left">resolver</td><td align="left">DNS resolver</td></tr><tr><td align="left">b10-cmdctl</td><td align="left">cmdctl</td><td align="left">Command control (remote control interface)</td></tr></tbody></table></div></div><p><br class="table-break">
436
      </p><p>
437 438 439 440 441 442 443 444 445 446 447 448 449 450 451
	The <code class="varname">kind</code> specifies how a failure of the
	component should be handled.  If it is set to
	<span class="quote">&#8220;<span class="quote">dispensable</span>&#8221;</span> (the default unless you set
	something else), it will get started again if it fails. If
	it is set to <span class="quote">&#8220;<span class="quote">needed</span>&#8221;</span> and it fails at startup,
	the whole <span class="command"><strong>bind10</strong></span> shuts down and exits
	with an error exit code. But if it fails some time later, it
	is just started again. If you set it to <span class="quote">&#8220;<span class="quote">core</span>&#8221;</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).
452
      </p><p>
453 454 455 456 457
	The <code class="varname">priority</code> defines order in which the
	components should start.  The ones with higher numbers are
	started sooner than the ones with lower ones. If you don't
	set it, 0 (zero) is used as the priority.  Usually, leaving
	it at the default is enough.
458 459
      </p><p>
        There are other parameters we didn't use in our example.
460
        One of them is <code class="varname">address</code>. It is the address
461 462 463 464
        used by the component on the <span class="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 <span class="emphasis"><em>b10-</em></span>, with
465
        the first letter capitalized (eg. <span class="command"><strong>b10-stats</strong></span>
466
        would have <span class="quote">&#8220;<span class="quote">Stats</span>&#8221;</span> as its address).
467 468

      </p><p>
469 470 471 472 473
	The last one is <code class="varname">process</code>. It is the name
	of the process to be started.  It defaults to the name of
	the component if not set, but you can use this to override
	it. (The special components also already know their
        executable name.)
474
      </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
475 476 477 478 479
          The configuration is quite powerful, but that includes
          a lot of space for mistakes. You could turn off the
          <span class="command"><strong>b10-cmdctl</strong></span>, 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
480 481
          directly).  Also, some modules might have dependencies:
          <span class="command"><strong>b10-stats-httpd</strong></span> needs
482
          <span class="command"><strong>b10-stats</strong></span>, <span class="command"><strong>b10-xfrout</strong></span>
483
          needs <span class="command"><strong>b10-auth</strong></span> to be running, etc.
484 485 486 487 488



        </p><p>
          In short, you should think twice before disabling something here.
Michal 'vorner' Vaner's avatar
Michal 'vorner' Vaner committed
489 490
        </p></div><p>
        It is possible to start some components multiple times (currently
491
        <span class="command"><strong>b10-auth</strong></span> and <span class="command"><strong>b10-resolver</strong></span>).
Michal 'vorner' Vaner's avatar
Michal 'vorner' Vaner committed
492 493 494 495 496 497 498 499 500 501 502 503 504
        You might want to do that to gain more performance (each one uses only
        single core). Just put multiple entries under different names, like
        this, with the same config:
        </p><pre class="screen">&gt; <strong class="userinput"><code>config add Boss/components b10-resolver-2</code></strong>
&gt; <strong class="userinput"><code>config set Boss/components/b10-resolver-2/special resolver</code></strong>
&gt; <strong class="userinput"><code>config set Boss/components/b10-resolver-2/kind needed</code></strong>
&gt; <strong class="userinput"><code>config commit</code></strong></pre><p>
      </p><p>
        However, this is work in progress and the support is not yet complete.
        For example, each resolver will have its own cache, each authoritative
        server will keep its own copy of in-memory data and there could be
        problems with locking the sqlite database, if used. The configuration
        might be changed to something more convenient in future.
505 506 507
	Other components don't expect such a situation, so it would
	probably not do what you want. Such support is yet to be
	implemented.
Michal 'vorner' Vaner's avatar
Michal 'vorner' Vaner committed
508
      </p></div></div><div class="chapter" title="Chapter 4. Command channel"><div class="titlepage"><div><div><h2 class="title"><a name="msgq"></a>Chapter 4. Command channel</h2></div></div></div><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
509
        The BIND 10 components use the <span class="command"><strong>b10-msgq</strong></span>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
510
        message routing daemon to communicate with other BIND 10 components.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
511
        The <span class="command"><strong>b10-msgq</strong></span> implements what is called the
Jeremy C. Reed's avatar
Jeremy C. Reed committed
512 513 514 515 516 517 518 519 520
        <span class="quote">&#8220;<span class="quote">Command Channel</span>&#8221;</span>.
        Processes intercommunicate by sending messages on the command
        channel.
        Example messages include shutdown, get configurations, and set
        configurations.
        This Command Channel is not used for DNS message passing.
        It is used only to control and monitor the BIND 10 system.
      </p><p>
        Administrators do not communicate directly with the
Jeremy C. Reed's avatar
Jeremy C. Reed committed
521
        <span class="command"><strong>b10-msgq</strong></span> daemon.
522 523 524
        By default, BIND 10 uses a UNIX domain socket file named
        <code class="filename">/usr/local/var/bind10-devel/msg_socket</code>
        for this interprocess communication.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
525
      </p></div><div class="chapter" title="Chapter 5. Configuration manager"><div class="titlepage"><div><div><h2 class="title"><a name="cfgmgr"></a>Chapter 5. Configuration manager</h2></div></div></div><p>
Michael Graff's avatar
Michael Graff committed
526 527 528 529 530 531 532
         The configuration manager, <span class="command"><strong>b10-cfgmgr</strong></span>,
         handles all BIND 10 system configuration.  It provides
         persistent storage for configuration, and notifies running
         modules of configuration changes.
      </p><p>
        The <span class="command"><strong>b10-auth</strong></span> and <span class="command"><strong>b10-xfrin</strong></span>
        daemons and other components receive their configurations
Jeremy C. Reed's avatar
Jeremy C. Reed committed
533
        from the configuration manager over the <span class="command"><strong>b10-msgq</strong></span>
Michael Graff's avatar
Michael Graff committed
534
        command channel.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
535 536 537 538 539
      </p><p>The administrator doesn't connect to it directly, but
        uses a user interface to communicate with the configuration
        manager via <span class="command"><strong>b10-cmdctl</strong></span>'s REST-ful interface.
        <span class="command"><strong>b10-cmdctl</strong></span> is covered in <a class="xref" href="#cmdctl" title="Chapter 6. Remote control daemon">Chapter 6, <i>Remote control daemon</i></a>.
      </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
540
          The development prototype release only provides
Michael Graff's avatar
Michael Graff committed
541 542 543 544 545
          <span class="command"><strong>bindctl</strong></span> as a user interface to
          <span class="command"><strong>b10-cmdctl</strong></span>.
          Upcoming releases will provide another interactive command-line
          interface and a web-based interface.
        </p></div><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
546 547
        The <span class="command"><strong>b10-cfgmgr</strong></span> daemon can send all
        specifications and all current settings to the
Michael Graff's avatar
Michael Graff committed
548 549
        <span class="command"><strong>bindctl</strong></span> client (via
        <span class="command"><strong>b10-cmdctl</strong></span>).
Jeremy C. Reed's avatar
Jeremy C. Reed committed
550 551 552 553 554
        <span class="command"><strong>b10-cfgmgr</strong></span> relays configurations received
        from <span class="command"><strong>b10-cmdctl</strong></span> to the appropriate modules.
      </p><p>
        The stored configuration file is at
        <code class="filename">/usr/local/var/bind10-devel/b10-config.db</code>.
555
        (The directory is what was defined at build configure time for
Jeremy C. Reed's avatar
Jeremy C. Reed committed
556 557
        <code class="option">--localstatedir</code>.
        The default is <code class="filename">/usr/local/var/</code>.)
Michael Graff's avatar
Michael Graff committed
558 559 560 561
        The format is loosely based on JSON and is directly parseable
        python, but this may change in a future version.
        This configuration data file is not manually edited by the
        administrator.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
562 563 564 565 566
      </p><p>
      The configuration manager does not have any command line arguments.
      Normally it is not started manually, but is automatically
      started using the <span class="command"><strong>bind10</strong></span> master process
      (as covered in <a class="xref" href="#bind10" title="Chapter 3. Starting BIND10 with bind10">Chapter 3, <i>Starting BIND10 with <span class="command"><strong>bind10</strong></span></i></a>).
567
    </p></div><div class="chapter" title="Chapter 6. Remote control daemon"><div class="titlepage"><div><div><h2 class="title"><a name="cmdctl"></a>Chapter 6. Remote control daemon</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#cmdctl.spec">6.1. Configuration specification for b10-cmdctl</a></span></dt></dl></div><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
568 569 570 571 572 573 574 575 576 577
      <span class="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 <span class="command"><strong>b10-cmdctl</strong></span> starts, it firsts
      asks <span class="command"><strong>b10-cfgmgr</strong></span> about what modules are
      running and what their configuration is (over the
Jeremy C. Reed's avatar
Jeremy C. Reed committed
578
      <span class="command"><strong>b10-msgq</strong></span> channel). Then it will start listening
Jeremy C. Reed's avatar
Jeremy C. Reed committed
579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603
      on HTTPS for clients &#8212; the user interface &#8212; such
      as <span class="command"><strong>bindctl</strong></span>.
    </p><p>
      <span class="command"><strong>b10-cmdctl</strong></span> directly sends commands
      (received from the user interface) to the specified component.
      Configuration changes are actually commands to
      <span class="command"><strong>b10-cfgmgr</strong></span> so are sent there.
    </p><p>The HTTPS server requires a private key,
      such as a RSA PRIVATE KEY.
      The default location is at
      <code class="filename">/usr/local/etc/bind10-devel/cmdctl-keyfile.pem</code>.
      (A sample key is at
      <code class="filename">/usr/local/share/bind10-devel/cmdctl-keyfile.pem</code>.)
      It also uses a certificate located at
      <code class="filename">/usr/local/etc/bind10-devel/cmdctl-certfile.pem</code>.
      (A sample certificate is at
      <code class="filename">/usr/local/share/bind10-devel/cmdctl-certfile.pem</code>.)
      This may be a self-signed certificate or purchased from a
      certification authority.
    </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
      The HTTPS server doesn't support a certificate request from a
      client (at this time).

      The <span class="command"><strong>b10-cmdctl</strong></span> daemon does not provide a
      public service. If any client wants to control BIND 10, then
Jeremy C. Reed's avatar
Jeremy C. Reed committed
604
      a certificate needs to be first received from the BIND 10
Jeremy C. Reed's avatar
Jeremy C. Reed committed
605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625
      administrator.
      The BIND 10 installation provides a sample PEM bundle that matches
      the sample key and certificate.
    </p></div><p>
      The <span class="command"><strong>b10-cmdctl</strong></span> daemon also requires
      the user account file located at
      <code class="filename">/usr/local/etc/bind10-devel/cmdctl-accounts.csv</code>.
      This comma-delimited file lists the accounts with a user name,
      hashed password, and salt.
      (A sample file is at
      <code class="filename">/usr/local/share/bind10-devel/cmdctl-accounts.csv</code>.
      It contains the user named <span class="quote">&#8220;<span class="quote">root</span>&#8221;</span> with the password
      <span class="quote">&#8220;<span class="quote">bind10</span>&#8221;</span>.)
    </p><p>
      The administrator may create a user account with the
      <span class="command"><strong>b10-cmdctl-usermgr</strong></span> tool.
    </p><p>
      By default the HTTPS server listens on the localhost port 8080.
      The port can be set by using the <code class="option">--port</code> command line option.
      The address to listen on can be set using the <code class="option">--address</code> command
      line argument.
626
      Each HTTPS connection is stateless and times out in 1200 seconds
Jeremy C. Reed's avatar
Jeremy C. Reed committed
627 628
      by default.  This can be
      redefined by using the <code class="option">--idle-timeout</code> command line argument.
629
    </p><div class="section" title="6.1. Configuration specification for b10-cmdctl"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmdctl.spec"></a>6.1. Configuration specification for b10-cmdctl</h2></div></div></div><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
630
        The configuration items for <span class="command"><strong>b10-cmdctl</strong></span> are:
631 632 633 634 635 636 637 638 639 640
        <code class="varname">accounts_file</code> which defines the path to the
        user accounts database (the default is
        <code class="filename">/usr/local/etc/bind10-devel/cmdctl-accounts.csv</code>);
        <code class="varname">cert_file</code> which defines the path to the
        PEM certificate file (the default is
        <code class="filename">/usr/local/etc/bind10-devel/cmdctl-certfile.pem</code>);
        and
	<code class="varname">key_file</code> which defines the path to the
	PEM private key file (the default is
        <code class="filename">/usr/local/etc/bind10-devel/cmdctl-keyfile.pem</code>).
Jeremy C. Reed's avatar
Jeremy C. Reed committed
641
      </p></div></div><div class="chapter" title="Chapter 7. Control and configure user interface"><div class="titlepage"><div><div><h2 class="title"><a name="bindctl"></a>Chapter 7. Control and configure user interface</h2></div></div></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
642
      For this development prototype release, <span class="command"><strong>bindctl</strong></span>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658
      is the only user interface. It is expected that upcoming
      releases will provide another interactive command-line
      interface and a web-based interface for controlling and
      configuring BIND 10.
    </p></div><p>
      The <span class="command"><strong>bindctl</strong></span> tool provides an interactive
      prompt for configuring, controlling, and querying the BIND 10
      components.
      It communicates directly with a REST-ful interface over HTTPS
      provided by <span class="command"><strong>b10-cmdctl</strong></span>. It doesn't
      communicate to any other components directly.
    </p><p>
      Configuration changes are actually commands to
      <span class="command"><strong>b10-cfgmgr</strong></span>. So when <span class="command"><strong>bindctl</strong></span>
      sends a configuration, it is sent to <span class="command"><strong>b10-cmdctl</strong></span>
      (over a HTTPS connection); then <span class="command"><strong>b10-cmdctl</strong></span>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
659
      sends the command (over a <span class="command"><strong>b10-msgq</strong></span> command
Jeremy C. Reed's avatar
Jeremy C. Reed committed
660
      channel) to <span class="command"><strong>b10-cfgmgr</strong></span> which then stores
Jeremy C. Reed's avatar
Jeremy C. Reed committed
661
      the details and relays (over a <span class="command"><strong>b10-msgq</strong></span> command
Jeremy C. Reed's avatar
Jeremy C. Reed committed
662 663
      channel) the configuration on to the specified module.
    </p><p>
664
    </p></div><div class="chapter" title="Chapter 8. Authoritative Server"><div class="titlepage"><div><div><h2 class="title"><a name="authserver"></a>Chapter 8. Authoritative Server</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp288016">8.1. Server Configurations</a></span></dt><dt><span class="section"><a href="#datasrc">8.2. Data Source Backends</a></span></dt><dd><dl><dt><span class="section"><a href="#datasource-types">8.2.1. Data source types</a></span></dt><dt><span class="section"><a href="#datasrc-examples">8.2.2. Examples</a></span></dt></dl></dd><dt><span class="section"><a href="#idp357664">8.3. Loading Master Zones Files</a></span></dt></dl></div><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
665
      The <span class="command"><strong>b10-auth</strong></span> is the authoritative DNS server.
666 667
      It supports EDNS0, DNSSEC, IPv6, and SQLite3 and in-memory zone
      data backends.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
668 669
      Normally it is started by the <span class="command"><strong>bind10</strong></span> master
      process.
670
    </p><div class="section" title="8.1. Server Configurations"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp288016"></a>8.1. Server Configurations</h2></div></div></div><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
671 672 673
        <span class="command"><strong>b10-auth</strong></span> is configured via the
        <span class="command"><strong>b10-cfgmgr</strong></span> configuration manager.
        The module name is <span class="quote">&#8220;<span class="quote">Auth</span>&#8221;</span>.
674
        The configuration data items are:
Jeremy C. Reed's avatar
Jeremy C. Reed committed
675 676 677 678

        </p><div class="variablelist"><dl><dt><span class="term">database_file</span></dt><dd>This is an optional string to define the path to find
                 the SQLite3 database file.

679 680
Note: This may be a temporary setting because the DNS server
can use various data source backends.
681 682 683 684 685 686 687 688
              </dd><dt><span class="term">datasources</span></dt><dd>
      <code class="varname">datasources</code> configures data sources.
      The list items include:
      <code class="varname">type</code> to define the required data source type
      (such as <span class="quote">&#8220;<span class="quote">memory</span>&#8221;</span>);
      <code class="varname">class</code> to optionally select the class
      (it defaults to <span class="quote">&#8220;<span class="quote">IN</span>&#8221;</span>);
      and
689 690
      <code class="varname">zones</code> to define
      the <code class="varname">file</code> path name,
691 692 693
      the <code class="varname">filetype</code> (<span class="quote">&#8220;<span class="quote">sqlite3</span>&#8221;</span> to load
      from a SQLite3 database file or <span class="quote">&#8220;<span class="quote">text</span>&#8221;</span> to
      load from a master text file),
694
      and the <code class="varname">origin</code> (default domain).
695 696 697 698 699 700 701 702 703

      By default, this is empty.

      <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
        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
704 705
        generated by <span class="command"><strong>named-compilezone -D</strong></span>, or
        must be an SQLite3 database.
706 707 708 709 710 711 712 713 714
      </p></div>

              </dd><dt><span class="term">listen_on</span></dt><dd>
      <code class="varname">listen_on</code> is a list of addresses and ports for
      <span class="command"><strong>b10-auth</strong></span> to listen on.
      The list items are the <code class="varname">address</code> string
      and <code class="varname">port</code> number.
      By default, <span class="command"><strong>b10-auth</strong></span> listens on port 53
      on the IPv6 (::) and IPv4 (0.0.0.0) wildcard addresses.
715 716 717 718 719 720 721 722 723 724 725 726 727 728 729
      <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
          The default configuration is currently not appropriate for a multi-homed host.
          In case you have multiple public IP addresses, it is possible the
          query UDP packet comes through one interface and the answer goes out
          through another. The answer will probably be dropped by the client, as it
          has a different source address than the one it sent the query to. The
          client would fallback on TCP after several attempts, which works
          well in this situation, but is clearly not ideal.
        </p><p>
          There are plans to solve the problem such that the server handles
          it by itself. But until it is actually implemented, it is recommended to
          alter the configuration &#8212; remove the wildcard addresses and list all
          addresses explicitly. Then the server will answer on the same
          interface the request came on, preserving the correct address.
        </p></div>
730 731 732 733 734 735 736
              </dd><dt><span class="term">statistics-interval</span></dt><dd>
      <code class="varname">statistics-interval</code> is the timer interval
      in seconds for <span class="command"><strong>b10-auth</strong></span> to share its
      statistics information to
      <span class="citerefentry"><span class="refentrytitle">b10-stats</span>(8)</span>.
      Statistics updates can be disabled by setting this to 0.
      The default is 60.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
737 738 739 740
              </dd></dl></div><p>

      </p><p>

741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766
        The configuration commands are:

        </p><div class="variablelist"><dl><dt><span class="term">loadzone</span></dt><dd>
      <span class="command"><strong>loadzone</strong></span> tells <span class="command"><strong>b10-auth</strong></span>
      to load or reload a zone file. The arguments include:
      <code class="varname">class</code> which optionally defines the class
      (it defaults to <span class="quote">&#8220;<span class="quote">IN</span>&#8221;</span>);
      <code class="varname">origin</code> is the domain name of the zone;
      and
      <code class="varname">datasrc</code> optionally defines the type of datasource
      (it defaults to <span class="quote">&#8220;<span class="quote">memory</span>&#8221;</span>).

      <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
        In this development version, currently this only supports the
        IN class and the memory data source.
      </p></div>
              </dd><dt><span class="term">sendstats</span></dt><dd>
      <span class="command"><strong>sendstats</strong></span> tells <span class="command"><strong>b10-auth</strong></span>
      to send its statistics data to
      <span class="citerefentry"><span class="refentrytitle">b10-stats</span>(8)</span>
      immediately.
              </dd><dt><span class="term">shutdown</span></dt><dd>Stop the authoritative DNS server.
      This has an optional <code class="varname">pid</code> argument to
      select the process ID to stop.
      (Note that the BIND 10 boss process may restart this service
      if configured.)
Jeremy C. Reed's avatar
Jeremy C. Reed committed
767 768
              </dd></dl></div><p>

769 770 771 772 773 774 775 776 777 778 779 780 781 782
      </p></div><div class="section" title="8.2. Data Source Backends"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="datasrc"></a>8.2. Data Source Backends</h2></div></div></div><p>
        Bind 10 has the concept of data sources. A data source is a place
        where authoritative zone data reside and where they can be served
        from. This can be a master file, a database or something completely
        different.
      </p><p>
        Once a query arrives, <span class="command"><strong>b10-auth</strong></span> goes through a
        configured list of data sources and finds the one containing a best
        matching zone. From the equally good ones, the first one is taken.
        This data source is then used to answer the query.
      </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
        In the development prototype release, <span class="command"><strong>b10-auth</strong></span>
        can serve data from a SQLite3 data source backend and from master
        files.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
783
        Upcoming versions will be able to use multiple different
784
        data sources, such as MySQL and Berkeley DB.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
785
      </p></div><p>
786 787 788 789 790 791
        The configuration is located in data_sources/classes. Each item there
        represents one RR class and a list used to answer queries for that
        class. The default contains two classes. The CH class contains a static
        data source &#8212; one that serves things like
        <span class="quote">&#8220;<span class="quote">AUTHORS.BIND.</span>&#8221;</span>. The IN class contains single SQLite3
        data source with database file located at
Jeremy C. Reed's avatar
Jeremy C. Reed committed
792
        <code class="filename">/usr/local/var/bind10-devel/zone.sqlite3</code>.
793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833
      </p><p>
        Each data source has several options. The first one is
        <code class="varname">type</code>, which specifies the type of data source to
        use. Valid types include the ones listed below, but bind10 uses
        dynamically loaded modules for them, so there may be more in your
        case. This option is mandatory.
      </p><p>
        Another option is <code class="varname">params</code>. This option is type
        specific; it holds different data depending on the type
        above. Also, depending on the type, it could be possible to omit it.
      </p><p>
        There are two options related to the so-called cache. If you enable
        cache, zone data from the data source are loaded into memory.
        Then, when answering a query, <span class="command"><strong>b10-auth</strong></span> looks
        into the memory only instead of the data source, which speeds
        answering up. The first option is <code class="varname">cache-enable</code>,
        a boolean value turning the cache on and off (off is the default).
        The second one, <code class="varname">cache-zones</code>, is a list of zone
        origins to load into in-memory. Remember that zones in the data source
        not listed here will not be loaded and will not be available at all.
      </p><div class="section" title="8.2.1. Data source types"><div class="titlepage"><div><div><h3 class="title"><a name="datasource-types"></a>8.2.1. Data source types</h3></div></div></div><p>
          As mentioned, the type used by default is <span class="quote">&#8220;<span class="quote">sqlite3</span>&#8221;</span>.
          It has single configuration option inside <code class="varname">params</code>
          &#8212; <code class="varname">database_file</code>, which contains the path
          to the sqlite3 file containing the data.
        </p><p>
          Another type is called <span class="quote">&#8220;<span class="quote">MasterFiles</span>&#8221;</span>. This one is
          slightly special. The data are stored in RFC1034 master files.
          Because answering directly from them would be impractical,
          this type mandates the cache to be enabled. Also, the list of
          zones (<code class="varname">cache-zones</code>) should be omitted. The
          <code class="varname">params</code> is a dictionary mapping from zone
          origins to the files they reside in.
        </p></div><div class="section" title="8.2.2. Examples"><div class="titlepage"><div><div><h3 class="title"><a name="datasrc-examples"></a>8.2.2. Examples</h3></div></div></div><p>
          As this is one of the more complex configurations of Bind10,
          we show some examples. They all assume they start with default
          configuration.
        </p><p>
          First, let's disable the static data source
          (<span class="quote">&#8220;<span class="quote">VERSION.BIND</span>&#8221;</span> and friends). As it is the only
          data source in the CH class, we can remove the whole class.
834

835
          </p><pre class="screen">&gt; <strong class="userinput"><code>config remove data_sources/classes CH</code></strong>
836
&gt; <strong class="userinput"><code>config commit</code></strong></pre><p>
837 838 839 840 841 842 843 844 845
        </p><p>
          Another one, let's say our default data source contains zones
          <span class="quote">&#8220;<span class="quote">example.org.</span>&#8221;</span> and <span class="quote">&#8220;<span class="quote">example.net.</span>&#8221;</span>.
          We want them to be served from memory to make the answering
          faster.

          </p><pre class="screen">&gt; <strong class="userinput"><code>config set data_sources/classes/IN[0]/cache-enable true</code></strong>
&gt; <strong class="userinput"><code>config add data_sources/classes/IN[0]/cache-zones example.org.</code></strong>
&gt; <strong class="userinput"><code>config add data_sources/classes/IN[0]/cache-zones example.net.</code></strong>
846 847
&gt; <strong class="userinput"><code>config commit</code></strong></pre><p>

848 849 850 851 852 853 854 855
          Now every time the zone in the data source is changed by the
          operator, Bind10 needs to be told to reload it, by
          </p><pre class="screen">&gt; <strong class="userinput"><code>Auth loadzone example.org</code></strong></pre><p>
          You don't need to do this when the zone is modified by
          XfrIn, it does so automatically.
        </p><p>
          Now, the last example is when there are master files we want to
          serve in addition to whatever is inside the sqlite3 database.
856

857 858 859 860
          </p><pre class="screen">&gt; <strong class="userinput"><code>config add data_sources/classes/IN</code></strong>
&gt; <strong class="userinput"><code>config set data_sources/classes/IN[1]/type MasterFiles</code></strong>
&gt; <strong class="userinput"><code>config set data_sources/classes/IN[1]/cache-enable true</code></strong>
&gt; <strong class="userinput"><code>config set data_sources/classes/IN[1]/params { "example.org": "/path/to/example.org", "example.com": "/path/to/example.com" }</code></strong>
861 862
&gt; <strong class="userinput"><code>config commit</code></strong></pre><p>

863 864 865 866 867 868 869 870 871 872 873 874 875
          Initially, a map value has to be set, but this value may be an
          empty map. After that, key/value pairs can be added with 'config
          add' and keys can be removed with 'config remove'. The initial
          value may be an empty map, but it has to be set before zones are
          added or removed.

          </p><pre class="screen">
&gt; <strong class="userinput"><code>config set data_sources/classes/IN[1]/params {}</code></strong>
&gt; <strong class="userinput"><code>config add data_sources/classes/IN[1]/params another.example.org /path/to/another.example.org</code></strong>
&gt; <strong class="userinput"><code>config add data_sources/classes/IN[1]/params another.example.com /path/to/another.example.com</code></strong>
&gt; <strong class="userinput"><code>config remove data_sources/classes/IN[1]/params another.example.org</code></strong>
          </pre><p>

876 877 878 879 880 881 882 883 884 885 886 887 888
          <span class="command"><strong>bindctl</strong></span>. To reload a zone, you the same command
          as above.
        </p></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
        There's also <code class="varname">Auth/database_file</code> configuration
        variable, pointing to a sqlite3 database file. This is no longer
        used by <span class="command"><strong>b10-auth</strong></span>, but it is left in place for
        now, since other modules use it. Once <span class="command"><strong>b10-xfrin</strong></span>,
        <span class="command"><strong>b10-xfrout</strong></span> and <span class="command"><strong>b10-ddns</strong></span>
        are ported to the new configuration, this will disappear. But for
        now, make sure that if you use any of these modules, the new
        and old configuration correspond. The defaults are consistent, so
        unless you tweaked either the new or the old configuration, you're
        good.
889
      </p></div></div><div class="section" title="8.3. Loading Master Zones Files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp357664"></a>8.3. Loading Master Zones Files</h2></div></div></div><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
890
        RFC 1035 style DNS master zone files may imported
891
        into a BIND 10 SQLite3 data source by using the
Jeremy C. Reed's avatar
Jeremy C. Reed committed
892 893 894 895 896 897 898 899 900 901 902 903 904 905 906
        <span class="command"><strong>b10-loadzone</strong></span> utility.
      </p><p>
        <span class="command"><strong>b10-loadzone</strong></span> supports the following
        special directives (control entries):

        </p><div class="variablelist"><dl><dt><span class="term">$INCLUDE</span></dt><dd>Loads an additional zone file. This may be recursive.
              </dd><dt><span class="term">$ORIGIN</span></dt><dd>Defines the relative domain name.
              </dd><dt><span class="term">$TTL</span></dt><dd>Defines the time-to-live value used for following
                records that don't include a TTL.
              </dd></dl></div><p>

      </p><p>
        The <code class="option">-o</code> argument may be used to define the
        default origin for loaded zone file records.
      </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
907
        In the development prototype release, only the SQLite3 back
908
        end is used by <span class="command"><strong>b10-loadzone</strong></span>.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
909 910 911 912 913 914 915
        By default, it stores the zone data in
        <code class="filename">/usr/local/var/bind10-devel/zone.sqlite3</code>
        unless the <code class="option">-d</code> switch is used to set the
        database filename.
        Multiple zones are stored in a single SQLite3 zone database.
      </p></div><p>
        If you reload a zone already existing in the database,
Jeremy C. Reed's avatar
Jeremy C. Reed committed
916
        all records from that prior zone disappear and a whole new set
Jeremy C. Reed's avatar
Jeremy C. Reed committed
917
        appears.
918
      </p></div></div><div class="chapter" title="Chapter 9. Incoming Zone Transfers"><div class="titlepage"><div><div><h2 class="title"><a name="xfrin"></a>Chapter 9. Incoming Zone Transfers</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp375872">9.1. Configuration for Incoming Zone Transfers</a></span></dt><dt><span class="section"><a href="#idp381216">9.2. Enabling IXFR</a></span></dt><dt><span class="section"><a href="#zonemgr">9.3. Secondary Manager</a></span></dt><dt><span class="section"><a href="#idp396992">9.4. Trigger an Incoming Zone Transfer Manually</a></span></dt><dt><span class="section"><a href="#idp400688">9.5. Incoming Transfers with In-memory Datasource</a></span></dt></dl></div><p>
919 920
      Incoming zones are transferred using the <span class="command"><strong>b10-xfrin</strong></span>
      process which is started by <span class="command"><strong>bind10</strong></span>.
921 922
      When received, the zone is stored in the corresponding BIND 10
      data source, and its records can be served by
Jeremy C. Reed's avatar
Jeremy C. Reed committed
923
      <span class="command"><strong>b10-auth</strong></span>.
924 925
      In combination with <span class="command"><strong>b10-zonemgr</strong></span> (for
      automated SOA checks), this allows the BIND 10 server to
926
      provide <span class="emphasis"><em>secondary</em></span> service.
927 928 929 930 931
    </p><p>
      The <span class="command"><strong>b10-xfrin</strong></span> process supports both AXFR and
      IXFR.  Due to some implementation limitations of the current
      development release, however, it only tries AXFR by default,
      and care should be taken to enable IXFR.
932
    </p><div class="section" title="9.1. Configuration for Incoming Zone Transfers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp375872"></a>9.1. Configuration for Incoming Zone Transfers</h2></div></div></div><p>
933 934 935 936
        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)).
937
      </p><p>
938 939 940
        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 <span class="command"><strong>bindctl</strong></span> prompt:
941 942 943 944 945 946 947

      </p><pre class="screen">&gt; <strong class="userinput"><code>config add Xfrin/zones</code></strong>
&gt; <strong class="userinput"><code>config set Xfrin/zones[0]/name "<code class="option">example.com</code>"</code></strong>
&gt; <strong class="userinput"><code>config set Xfrin/zones[0]/master_addr "<code class="option">2001:db8::53</code>"</code></strong>
&gt; <strong class="userinput"><code>config commit</code></strong></pre><p>

      (We assume there has been no zone configuration before).
948
      </p></div><div class="section" title="9.2. Enabling IXFR"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp381216"></a>9.2. Enabling IXFR</h2></div></div></div><p>
949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969
        As noted above, <span class="command"><strong>b10-xfrin</strong></span> uses AXFR for
        zone transfers by default.  To enable IXFR for zone transfers
        for a particular zone, set the <strong class="userinput"><code>use_ixfr</code></strong>
        configuration parameter to <strong class="userinput"><code>true</code></strong>.
        In the above example of configuration sequence, you'll need
        to add the following before performing <strong class="userinput"><code>commit</code></strong>:
      </p><pre class="screen">&gt; <strong class="userinput"><code>config set Xfrin/zones[0]/use_ixfr true</code></strong></pre><p>
      </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
      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 <span class="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.
970
      </p></div></div><div class="section" title="9.3. Secondary Manager"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="zonemgr"></a>9.3. Secondary Manager</h2></div></div></div><p>
971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996
        The <span class="command"><strong>b10-zonemgr</strong></span> process is started by
        <span class="command"><strong>bind10</strong></span>.
        It keeps track of SOA refresh, retry, and expire timers
        and other details for BIND 10 to perform as a slave.
        When the <span class="command"><strong>b10-auth</strong></span> authoritative DNS server
        receives a NOTIFY message, <span class="command"><strong>b10-zonemgr</strong></span>
        may tell <span class="command"><strong>b10-xfrin</strong></span> to do a refresh
        to start an inbound zone transfer.
        The secondary manager resets its counters when a new zone is
        transferred in.
      </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
        Access control (such as allowing notifies) is not yet provided.
        The primary/secondary service is not yet complete.
      </p></div><p>
        The following example shows using <span class="command"><strong>bindctl</strong></span>
        to configure the server to be a secondary for the example zone:

      </p><pre class="screen">&gt; <strong class="userinput"><code>config add Zonemgr/secondary_zones</code></strong>
&gt; <strong class="userinput"><code>config set Zonemgr/secondary_zones[0]/name "<code class="option">example.com</code>"</code></strong>
&gt; <strong class="userinput"><code>config commit</code></strong></pre><p>

      </p><p>
        If the zone does not exist in the data source already
        (i.e. no SOA record for it), <span class="command"><strong>b10-zonemgr</strong></span>
        will automatically tell <span class="command"><strong>b10-xfrin</strong></span>
        to transfer the zone in.
997
      </p></div><div class="section" title="9.4. Trigger an Incoming Zone Transfer Manually"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp396992"></a>9.4. Trigger an Incoming Zone Transfer Manually</h2></div></div></div><p>
998 999 1000 1001 1002
        To manually trigger a zone transfer to retrieve a remote zone,
        you may use the <span class="command"><strong>bindctl</strong></span> utility.
        For example, at the <span class="command"><strong>bindctl</strong></span> prompt run:

        </p><pre class="screen">&gt; <strong class="userinput"><code>Xfrin retransfer zone_name="<code class="option">foo.example.org</code>" master=<code class="option">192.0.2.99</code></code></strong></pre><p>
1003
      </p></div><div class="section" title="9.5. Incoming Transfers with In-memory Datasource"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp400688"></a>9.5. Incoming Transfers with In-memory Datasource</h2></div></div></div><p>
1004 1005 1006 1007 1008 1009 1010 1011 1012 1013
        In the case of an incoming zone transfer, the received zone is
        first stored in the corresponding BIND 10 datasource. In
        case the secondary zone is served by an in-memory datasource
        with an SQLite3 backend, <span class="command"><strong>b10-auth</strong></span> is
        automatically sent a <code class="varname">loadzone</code> command to
        reload the corresponding zone into memory from the backend.
      </p><p>
	The administrator doesn't have to do anything for
	<span class="command"><strong>b10-auth</strong></span> to serve the new version of the
	zone, except for the configuration such as the one described in
1014
	<a class="xref" href="#datasrc" title="8.2. Data Source Backends">Section 8.2, &#8220;Data Source Backends&#8221;</a>.
1015
      </p></div></div><div class="chapter" title="Chapter 10. Outbound Zone Transfers"><div class="titlepage"><div><div><h2 class="title"><a name="xfrout"></a>Chapter 10. Outbound Zone Transfers</h2></div></div></div><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1016 1017 1018
      The <span class="command"><strong>b10-xfrout</strong></span> process is started by
      <span class="command"><strong>bind10</strong></span>.
      When the <span class="command"><strong>b10-auth</strong></span> authoritative DNS server
1019 1020
      receives an AXFR or IXFR request, <span class="command"><strong>b10-auth</strong></span>
      internally forwards the request to <span class="command"><strong>b10-xfrout</strong></span>,
1021
      which handles the rest of this request processing.
1022
      This is used to provide primary DNS service to share zones
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1023
      to secondary name servers.
1024
      The <span class="command"><strong>b10-xfrout</strong></span> is also used to send
1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042
      NOTIFY messages to secondary servers.
    </p><p>
      A global or per zone <code class="option">transfer_acl</code> configuration
      can be used to control accessibility of the outbound zone
      transfer service.
      By default, <span class="command"><strong>b10-xfrout</strong></span> allows any clients to
      perform zone transfers for any zones:
    </p><pre class="screen">&gt; <strong class="userinput"><code>config show Xfrout/transfer_acl</code></strong>
Xfrout/transfer_acl[0]	{"action": "ACCEPT"}	any	(default)</pre><p>
      You can change this to, for example, rejecting all transfer
      requests by default while allowing requests for the transfer
      of zone "example.com" from 192.0.2.1 and 2001:db8::1 as follows:
    </p><pre class="screen">&gt; <strong class="userinput"><code>config set Xfrout/transfer_acl[0] {"action": "REJECT"}</code></strong>
&gt; <strong class="userinput"><code>config add Xfrout/zone_config</code></strong>
&gt; <strong class="userinput"><code>config set Xfrout/zone_config[0]/origin "example.com"</code></strong>
&gt; <strong class="userinput"><code>config set Xfrout/zone_config[0]/transfer_acl [{"action": "ACCEPT", "from": "192.0.2.1"},</code></strong>
<strong class="userinput"><code>                                                 {"action": "ACCEPT", "from": "2001:db8::1"}]</code></strong>
&gt; <strong class="userinput"><code>config commit</code></strong></pre><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
1043 1044 1045
        In the above example the lines
        for <code class="option">transfer_acl</code> were divided for
        readability.  In the actual input it must be in a single line.
1046
    </p></div><p>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1047 1048
      If you want to require TSIG in access control, a system wide TSIG
      "key ring" must be configured.
1049 1050 1051 1052 1053
      For example, to change the previous example to allowing requests
      from 192.0.2.1 signed by a TSIG with a key name of
      "key.example", you'll need to do this:
    </p><pre class="screen">&gt; <strong class="userinput"><code>config set tsig_keys/keys ["key.example:&lt;base64-key&gt;"]</code></strong>
&gt; <strong class="userinput"><code>config set Xfrout/zone_config[0]/transfer_acl [{"action": "ACCEPT", "from": "192.0.2.1", "key": "key.example"}]</code></strong>
1054 1055 1056
&gt; <strong class="userinput"><code>config commit</code></strong></pre><p>Both <span class="command"><strong>b10-xfrout</strong></span> and <span class="command"><strong>b10-auth</strong></span>
      will use the system wide keyring to check
      TSIGs in the incoming messages and to sign responses.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
1057
        The way to specify zone specific configuration (ACLs, etc) is
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1058
        likely to be changed.
1059
    </p></div></div><div class="chapter" title="Chapter 11. Dynamic DNS Update"><div class="titlepage"><div><div><h2 class="title"><a name="ddns"></a>Chapter 11. Dynamic DNS Update</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp434672">11.1. Enabling Dynamic Update</a></span></dt><dt><span class="section"><a href="#idp450256">11.2. Access Control</a></span></dt><dt><span class="section"><a href="#idp475168">11.3. Miscellaneous Operational Issues</a></span></dt></dl></div><p>
1060 1061 1062 1063 1064 1065 1066 1067 1068
      BIND 10 supports the server side of the Dynamic DNS Update
      (DDNS) protocol as defined in RFC 2136.
      This service is provided by the <span class="command"><strong>b10-ddns</strong></span>
      component, which is started by the <span class="command"><strong>bind10</strong></span>
      process if configured so.
    </p><p>
      When the <span class="command"><strong>b10-auth</strong></span> authoritative DNS server
      receives an UPDATE request, it internally forwards the request
      to <span class="command"><strong>b10-ddns</strong></span>, which handles the rest of
1069 1070 1071 1072 1073
      this request processing.
      When the processing is completed, <span class="command"><strong>b10-ddns</strong></span>
      will send a response to the client as specified in RFC 2136
      (NOERROR for successful update, REFUSED if rejected due to
      ACL check, etc).
1074 1075
      If the zone has been changed as a result, it will internally
      notify <span class="command"><strong>b10-xfrout</strong></span> so that other secondary
1076
      servers will be notified via the DNS NOTIFY protocol.
1077
      In addition, if <span class="command"><strong>b10-auth</strong></span> serves the updated
1078 1079
      zone (as described in
      <a class="xref" href="#datasrc" title="8.2. Data Source Backends">Section 8.2, &#8220;Data Source Backends&#8221;</a>),
1080 1081
      <span class="command"><strong>b10-ddns</strong></span> will also
      notify <span class="command"><strong>b10-auth</strong></span> so that <span class="command"><strong>b10-auth</strong></span>
1082
      will re-cache the updated zone content if necessary.
1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097
    </p><p>
      The <span class="command"><strong>b10-ddns</strong></span> component supports requests over
      both UDP and TCP, and both IPv6 and IPv4; for TCP requests,
      however, it terminates the TCP connection immediately after
      each single request has been processed.  Clients cannot reuse the
      same TCP connection for multiple requests. (This is a current
      implementation limitation of <span class="command"><strong>b10-ddns</strong></span>.
      While RFC 2136 doesn't specify anything about such reuse of TCP
      connection, there is no reason for disallowing it as RFC 1035
      generally allows multiple requests sent over a single TCP
      connection.  BIND 9 supports such reuse.)
    </p><p>
      As of this writing <span class="command"><strong>b10-ddns</strong></span> does not support
      update forwarding for secondary zones.
      If it receives an update request for a secondary zone, it will
1098
      immediately return a <span class="quote">&#8220;<span class="quote">not implemented</span>&#8221;</span> response.
1099
      </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
1100 1101
	  For feature completeness, update forwarding should be
	  eventually supported.  But currently it's considered a lower
1102 1103 1104 1105
	  priority task and there is no specific plan of implementing
	  this feature.

      </p></div><p>
1106
    </p><div class="section" title="11.1. Enabling Dynamic Update"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp434672"></a>11.1. Enabling Dynamic Update</h2></div></div></div><p>
1107 1108 1109 1110 1111 1112 1113 1114 1115