userguide.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY mdash  "&#x2014;" >
]>
<book>
  <bookinfo>
    <title>BIND 10 User Guide</title>
    <subtitle>Administrator Reference for BIND 10</subtitle>

    <copyright>
      <year>2010</year><holder>Internet Systems Consortium, Inc.</holder>
    </copyright>

<!--    <abstract><para>This is the definitive reference and user's guide for BIND 10</para></abstract> -->

  </bookinfo>

  <chapter id="intro">
    <title>Introduction</title>
    <para>
      BIND is the popular implementation of a DNS server, developer
      interfaces, and DNS tools.
      BIND 10 is a rewrite, using C++ and Python, to provide
      modular components for serving and maintaining DNS.
    </para>

    <note><para>BIND 10, at this time, does not provide an recursive
      DNS server. It does provide a EDNS0- and DNSSEC-capable
      authoritative DNS server.</para></note>

    <note><para>This guide covers the experimental prototype version
      of BIND 10.</para></note>

    <para>
      BIND 10 provides separate executables for different tasks.
      The standard components include:

      <itemizedlist>

      <listitem>
      <simpara><command>msgq</command> &mdash; message bus daemon</simpara>
      </listitem>
      <listitem>
      <simpara><command>b10-auth</command> &mdash; authoritative DNS server</simpara>
      </listitem>
      <listitem>
      <simpara><command>b10-cfgmgr</command> &mdash; configuration manager</simpara>
      </listitem>
      <listitem>
      <simpara><command>b10-cmdctl</command> REST-ful communication service</simpara>
      </listitem>

      <listitem>
      <simpara><command>b10-xfrin</command> Incoming zone transfer service</simpara>
      </listitem>

      <listitem>
      <simpara><command>bind10</command> &mdash; master process for BIND 10</simpara>
      </listitem>
      </itemizedlist>
    </para>

    <para>
      The user tools include:

      <itemizedlist>
      <listitem>
      <simpara><command>bindctl</command> &mdash; interactive administration interface</simpara>
      </listitem>
      <listitem>
      <simpara><command>b10-loadzone</command> &mdash; tool to load standard master zone files</simpara>
      </listitem>
<!-- TODO usermgr -->
      </itemizedlist>
    </para>

    <para>
      The tools and modules are covered in full detail in this users guide.
<!-- TODO point to these -->
      In addition, manual pages are also provided in the default installation.
    </para>
      
<!--
bin/
  bindctl*
  host*
lib/
  libauth
  libdns
  libexceptions
  python3.1/site-packages/isc/{cc,config}
sbin/
  bind10
share/
  share/bind10/                                       <
    auth.spec
    b10-cmdctl.pem
    bob.spec
    passwd.csv
  man/
var/
  bind10/b10-config.db
-->

    <para>
      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.
<!-- TODO point to this -->
    </para>

  </chapter>

  <chapter id="quickstart">
    <title>Quick start</title>
    <para>
      This quickly covers the standard steps for installing
      and deploying BIND 10 as an authoritative nameserver using
      its defaults. For troubleshooting, full customizations and further
      details, see the respective chapters in the BIND 10 user guide.
    </para>

    <itemizedlist>
    
      <listitem>
        <simpara>Install required dependencies: Python 3.1, SQLite3
          library, and Boost development headers.</simpara>
      </listitem>

      <listitem>
        <simpara>Download the BIND 10 source tarball. <!-- TODO: from -->
        </simpara>
      </listitem>

      <listitem>
        <para>Extract the tar file:
        <screen>$ <userinput>gzcat bind10-<replaceable>VERSION</replaceable>.tar.gz | tar -xvf -</userinput></screen>
        </para>
      </listitem>

      <listitem>
        <para>Go into the source and run configure:
          <screen>$ <userinput>cd bind10-<replaceable>VERSION</replaceable></userinput>
$ <userinput>./configure</userinput></screen>
        </para>
      </listitem>

      <listitem>
        <para>Build it:
          <screen>$ <userinput>make</userinput></screen>
        </para>
      </listitem>

      <listitem>
        <para>Install it (to default /usr/local):
          <screen>$ <userinput>make install</userinput></screen>
        </para>
      </listitem>

      <listitem>
        <para>Start the server:
          <screen>$ <userinput>/usr/local/sbin/bind10</userinput></screen>
        </para>
      </listitem>

      <listitem>

       <note><simpara>The Y1 prototype of the b10-auth server listens on
         0.0.0.0 (all interfaces) port 5300. (This is not the standard
         domain service port.)</simpara></note>

       <para>Test it; for example:
          <screen>$ <userinput>dig @127.0.0.1 -p 5300 -c CH -t TXT authors.bind</userinput></screen>
       </para>

      </listitem>

      <listitem>
        <para>Load desired zone file(s), for example:
          <screen>$ <userinput>b10-loadzone <replaceable>your.zone.example.org</replaceable></userinput></screen>
        </para>
      </listitem>

      <listitem>
        <simpara>Test the new zone.
        </simpara>
      </listitem>

    </itemizedlist>

  </chapter>

  <chapter id="install">
    <title>Installation from source</title>
    <para>
    BIND 10 is open source software written in C++ and Python.
    It is freely available in source code form from ISC via
    the Subversion code revision control system or as a downloadable
    tar file. It may also be available in pre-compiled ready-to-use
    packages from operating system vendors.
    </para>

    <sect1>
      <title>Download Tar File</title>
      <para>The BIND 10 development snapshots and releases
        are available as tarball downloads.
      </para>
<!-- TODO -->
    </sect1>

    <sect1>
      <title>Retrieve from Subversion</title>
      <para>
        The latest development code, including temporary experiments
        and un-reviewed code, is available via the BIND 10 code revision
        control system. This is powered by Subversion and all the BIND 10
        development is public.
        The leading development is done in the <quote>trunk</quote>
        and the first year prototype containing reviewed code is in
        <filename>branches/Y1</filename>.
      </para>
      <para>
        The code can be checked out from <filename>svn://bind10.isc.org/svn/bind10</filename>; for example to check out the trunk:

      <screen>$ <userinput>svn co svn://bind10.isc.org/svn/bind10/trunk</userinput></screen>
      </para>

      <para>
        You don't need to retrieve the source code from subversion
        unless you are testing latest code which is not provided in the
        source tarball. Most users will just use the source tar file.
      </para>

      <sect2>
        <title>Generate configuration files</title>
        <para>
        When checking out the code from
        the code version control system, it doesn't include the
        generated configure script, Makefile.in files, nor the
        related configure files.
        They can be created by running <command>autoreconf</command>
        with the <command>--install</command> switch.
        This will run <command>autoconf</command>, <command>aclocal</command>,
        <command>libtoolize</command>, <command>autoheader</command>,
        <command>automake</command>, and related commands &mdash;
        and provide needed build files.
      </para>
      <para>
        This requires <command>autoconf</command> version 2.59 or newer
	and <command>automake</command> version 1.11 or better (for
	working Python 3.1 tests).
      </para>
      <note><para>
        Some operating systems do not provide these in their
        default installation nor standard packages collections.
        You may need to install them separately.
      </para></note>
      </sect2>
    </sect1>

    <sect1>
      <title>Required Software</title>
      <para>
        BIND 10 requires Python 3.1.
      </para>

      <para>
        Building from the source tarball requires the Boost
        build-time headers. At least Boost version 1.34 is required.
<!-- TODO: we don't check for this version -->
<!-- NOTE: jreed has tested with 1.34, 1.38, and 1.41. -->
      </para>

      <para>
	If the Boost System Library is detected at configure time,
	BIND 10 will be built using an alternative method for
	networking I/O using Boost ASIO support.  This provides
	asynchrony support; with ASIO the Authoritative DNS server
	can handle other queries while the processing of a TCP
	transaction stalls.
        This dependency is not required unless you need
        <!-- TODO: want --> this feature as TCP transport support is
        provided using alternative code.
      </para>

      <note><para>
        For the Y1 prototype release, the only supported data source
        backend is SQLite3. The authoritative server requires
        SQLite 3.3.9 or newer,
        and the XFRin module requires the Python _sqlite3.so module.
      </para></note>
<!-- TODO: this will change ... -->

<!-- TODO: list where to get these from -->

      <note><para>
        Some operating systems do not provide these dependencies
	in their default installation nor standard packages
	collections.
        You may need to install them separately.
      </para></note>

      <para>
        Building BIND 10 also requires a C++ compiler and
        standard development headers.
        BIND 10 builds have been tested with GCC g++ 3.4.3, 4.1.2,
        4.2.1, 4.3.2, and 4.4.1.
      </para>

    </sect1>

    <sect1>
      <title>Supported Platforms</title>
      <para>
	BIND 10 builds have been tested on Debian GNU/Linux 5,
	Ubuntu 9.10, NetBSD 5, Solaris 10, FreeBSD 7, and CentOS
	Linux 5.3.

	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.
      </para>
    </sect1>

    <sect1>
      <title>Configure before the build</title>
      <para>
        BIND 10 uses the GNU Build System to discover build environment
        details.
        To generate the makefiles using the defaults, simply run:
        <screen>$ <userinput>./configure</userinput></screen>
      </para>
      <para>
        Run <command>./configure</command> with the <command>--help</command>
        switch to view the different options. The commonly-used options are:

        <variablelist>

        <varlistentry>
          <term>--with-boostlib</term>
          <listitem> 
            <simpara>Define the path to find the Boost system library.
            </simpara>
          </listitem> 
        </varlistentry>

        <varlistentry>
          <term>--without-boostlib</term> or
          <term>--with-boostlib=no</term>
          <listitem> 
            <simpara>Disable the Boost ASIO support.</simpara>
          </listitem> 
        </varlistentry>

        <varlistentry>
          <term>--with-pythonpath</term>
          <listitem> 
            <simpara>Define the path to Python 3.1 if it is not in the
              standard execution path.
            </simpara>
          </listitem> 
        </varlistentry>

        <varlistentry>
          <term>--with-boost-include</term>
          <listitem> 
            <simpara>Define the path to find the Boost headers.
            </simpara>
          </listitem> 
        </varlistentry>

        <varlistentry>
          <term>--prefix</term>
          <listitem> 
	    <simpara>Define the the installation location (the
	      default is <filename>/usr/local/</filename>).
            </simpara>
          </listitem> 
        </varlistentry>

        </variablelist>

      </para>
<!-- TODO: gtest, lcov -->

      <para>
        For example, the following configures it to build
	with BOOST ASIO support, find the Boost headers, find the
	Python interpreter, and sets the installation location:

        <screen>$ <userinput>./configure --with-boostlib=/usr/pkg/lib \
    --with-boost-include=/usr/pkg/include \
    --with-pythonpath=/usr/pkg/bin/python3.1 \
    --prefix=/opt/bind10</userinput></screen>
      </para>

      <para>
        If the configure fails, it may be due to missing or old
        dependencies.
      </para>

    </sect1>

    <sect1>
      <title>Build</title>
      <para>
	After the configure step is complete, to build the executables
	from the C++ code and prepare the Python scripts, run:

        <screen>$ <userinput>make</userinput></screen>
      </para>
    </sect1>

    <sect1>
      <title>Install</title>
      <para>
	To install the BIND 10 executables, support files,
	and documentation, run:
        <screen>$ <userinput>make install</userinput></screen>
      </para>
      <note><para>The install step may require superuser
      privileges.</para></note>

    </sect1>

<!-- TODO: tests -->

    <sect1>
      <title>Install Hierarchy</title>
      <para>
        The following is the layout of the complete BIND 10 installation:
      <itemizedlist>
      <listitem>
      <simpara><filename>bin/</filename> &mdash; general tools and
      diagnostic clients.</simpara>
      </listitem>
      <listitem>
      <simpara><filename>etc/bind10/</filename> &mdash; configuration files.
      </simpara>
<!-- TODO: create the etc/bind10/ directory? -->
      </listitem>
      <listitem>
      <simpara><filename>lib/</filename> &mdash; libraries and
      python modules.</simpara>
      </listitem>
      <listitem>
      <simpara><filename>libexec/bind10/</filename> &mdash; executables that
      a user wouldn't normally run directly. Nor would they be used
      independently. These are the BIND 10 modules which are daemons
      started by the <command>bind10</command> tool.
      </simpara>
      </listitem>
      <listitem>
      <simpara><filename>sbin/</filename> &mdash; commands used by
      the system administrator.
      </simpara>
      </listitem>
      <listitem>
      <simpara><filename>share/bind10/</filename> &mdash; configuration
        specifications.
      </simpara>
      </listitem>
      <listitem>
      <simpara><filename>share/man/</filename> &mdash; manual pages (online
        documentation).
      </simpara>
      </listitem>
      <listitem>
      <simpara><filename>var/bind10/</filename> &mdash; data source and
        configuration databases.
<!-- TODO: move the sqlite3 database there -->
      </simpara>
      </listitem>
      </itemizedlist>
    </para>
    </sect1>

<!--
    <sect1 id="install.troubleshooting">
      <title>Troubleshooting</title>
      <para>
      </para>
    </sect1>
-->
  
  </chapter>

  <chapter id="bind10">
    <title>Starting BIND10 with bind10</title>
    <para>
      BIND 10 provides the <command>bind10</command> command which 
      starts up the required daemons to provide the message
      communication bus, configurations, <!-- TODO: security, -->
      and the DNS server(s).
      Also known as BoB or the Boss of BIND, <command>bind10</command>
      will also restart processes that exit.
    </para>

    <para>
      After starting the <command>msgq</command> communications channel,
      <command>bind10</command> connects to it, 
      runs the configuration manager, and reads its own configuration.
      Then it starts the other modules.
    </para>

    <para>
      The <command>msgq</command> and <command>b10-cfgmgr</command>
      services make up the core. The <command>msgq</command> daemon
      provides the communication channel between every part of the system.
      The <command>b10-cfgmgr</command> daemon is always needed by every
      module, if only to send information about themselves somewhere,
      but more importantly to ask about their own settings, and
      about other modules.
      The <command>bind10</command> master process will also startup
      <command>b10-cmdctl</command> for admins to communicate with the
      system, <command>b10-auth</command> for Authoritative DNS service,
      and <command>b10-xfrin</command> for inbound DNS zone transfers.
      (These are covered in upcoming chapters.)
    </para>

    <sect1 id="start">
      <title>Starting BIND 10</title>
      <para>
        To start the BIND 10 service, simply run <command>bind10</command>.
        Run it with the <command>--verbose</command> switch to
        get additional debugging or diagnostic output.
      </para>
<!-- TODO: note it doesn't go into background -->
    </sect1>

  </chapter>

  <chapter id="msgq">
    <title>Command channel</title>

      <para>
        The BIND 10 components use the <command>msgq</command>
        message routing daemon to intercommunicate.
        This is called the <quote>Command Channel</quote>.
        The members of the channel subscribe to listen to certain
        messages and are programmed to handle received messages.
	Example messages include shutdown, get configurations, and set
	configurations.
      </para>

      <note><simpara>
        This Command Channel is not used for DNS message passing.
      </simpara></note>

      <para>
        Administrators do not communicate directly with the
        <command>msgq</command> daemon. The only configuration is
        to choose the port number it listens on.
        By default, BIND 10 uses port 9912 for the
        <command>msgq</command> service.
        It listens on 127.0.0.1.
      </para>

<!-- TODO: upcoming plans:
Unix domain sockets
-->

  </chapter>

  <chapter id="cfgmgr">
    <title>Configuration manager</title>

      <para>
	 The configuration manager, <command>b10-cfgmgr</command>,
	 handles all BIND 10 system configuration.  It provides
	 persistent storage for configuration, and notifies running
	 modules of configuration changes.</para>

      <para>The administrator
	 doesn't use it directly, but uses a tool like
	 <command>bindctl</command> (or other GUI or web interface)
         to communicate with the configuration manager.
      </para>

<!-- TODO: what about run time config to change this? -->
<!-- jelte: > config set cfgmgr/config_database <file> -->
<!-- TODO: what about command line switch to change this? -->
      <para>
        The stored configuration file is at
        <filename>/usr/local/var/bind10/b10-config.db</filename>.
        (The full path is what was defined at build configure time for
        --localstatedir. The default is <filename>/usr/local/var/</filename>.)
	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.
      </para>

      <para>
        The direct communication with the configuration manager is
        <command>b10-cmdctl</command> using its REST-ful interface.
        This is covered in <xref linkend="cmdctl"/>.
      </para>

<!-- TODO -->
      <note><para>
	The Y1 prototype release only provides the
	<command>bindctl</command> as a user interface to it.
        Upcoming releases will provide another interactive command-line
        interface and a web-based interface.
      </para></note>

      <para>
        The <command>b10-cfgmgr</command> daemon can send all
        specifications and all current settings to the
	<command>bindctl</command> client (via
	<command>b10-cmdctl</command>).
      </para>


<!--

Well the specfiles have a more fixed format (they must contain specific
stuff), but those are also directly parseable python structures (and
'coincidentally', our data::element string representation is the same)

loosely based on json, tweaked to be directly parseable in python, but a
subset of that.
wiki page is http://bind10.isc.org/wiki/DataElementDesign

nope, spec files are written by module developers, and db should be done
through bindctl and friends

-->

    <para>
      The configuration manager does not have any command line arguments.
      Normally it is not started manually, but is automatically
      started using the <command>bind10</command> master process
      (as covered in <xref linkend="bind10"/>).
    </para>

<!-- TODO: upcoming plans:
configuration for configuration manager itself. And perhaps we might
change the messaging protocol, but an admin should never see any of that
-->

     <para>
     </para>

<!-- TODO: show examples, test this -->
<!--
, so an admin can simply run bindctl,
do config show, and it shows all modules; config show >module> shows all
options for that module
-->

  </chapter>

  <chapter id="cmdctl">
    <title>Remote control daemon</title>

      <para>
        <command>b10-cmdctl</command> 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.
      </para>
<!-- TODO: copy examples from wiki, try with wget -->

      <para>
      When <command>b10-cmdctl</command> starts, it firsts
      asks <command>b10-cfgmgr</command> about what modules are
      running and what their configuration is (over the
      <command>msgq</command> channel). Then it will start listening
      on HTTPS for clients, such as <command>bindctl</command>.
    </para>

<!-- TODO: replace /usr/local -->
<!-- TODO: permissions -->
    <para>The HTTPS server requires a private key,
      such as a RSA PRIVATE KEY.
      The default location is at
      <filename>/usr/local/etc/bind10/cmdctl-keyfile.pem</filename>.
      (A sample key is at
      <filename>/usr/local/share/bind10/cmdctl-keyfile.pem</filename>.)
      It also uses a certificate located at
      <filename>/usr/local/etc/bind10/cmdctl-certfile.pem</filename>.
      (A sample certificate is at
      <filename>/usr/local/share/bind10/cmdctl-certfile.pem</filename>.)
      This may be a self-signed certificate or purchased from a
      certification authority.
    </para>

    <note><para>
      The HTTPS server doesn't support a certificate request from a
      client (at this time).
<!-- TODO: maybe allow request from server side -->
      The <command>b10-cmdctl</command> daemon does not provide a
      public service. If any client wants to control BIND 10, then
      a certificate needs to be first recieved from the BIND 10
      administrator.
      The BIND 10 installation provides a sample PEM bundle that matches
      the sample key and certificate.
    </para></note>
<!-- TODO: cross-ref -->

<!-- TODO
openssl req -new -x509 -keyout server.pem -out server.pem -days 365 -nodes
but that is a single file, maybethis should go back to that format?
-->

<!--
    <para>
(08:20:56) shane: It is in theory possible to run without cmdctl.
(08:21:02) shane: I think we discussed this.
    </para>
-->

<!-- TODO: Please check https://bind10.isc.org/wiki/cmd-ctrld -->


    <para>
      The <command>b10-cmdctl</command> daemon also requires
      the user account file located at
      <filename>/usr/local/etc/bind10/cmdctl-accounts.csv</filename>.
      This comma-delimited file lists the accounts with a user name,
      hashed password, and salt.
      (A sample file is at
      <filename>/usr/local/share/bind10/cmdctl-accounts.csv</filename>.
      It contains the user named <quote>root</quote> with the password
      <quote>bind10</quote>.)
    </para>

    <para>
      The administrator may create a user account with the
      <command>b10-cmdctl-usermgr</command> tool.
    </para>
<!-- TODO: show example -->

<!-- TODO: does cmdctl need to be restarted to change cert or key
or accounts database -->

    <para>
      By default the HTTPS server listens on the localhost port 8080.
      The port can be set by using the --port command line option.
      The address to listen on can be set using the --address command
      line argument.
      Each HTTPS connection is stateless and timesout in 1200 seconds
      by default.  This can be
      redefined by using the --idle-timeout command line argument.
    </para>

    <sect1 id="cmdctl.spec">
      <title>Configuration specification for b10-cmdctl</title>
      <para>
        The configuration items for <command>b10-cmdctl</command> are:
key_file
cert_file
accounts_file
      </para>
<!-- TODO -->

      <para>
        The control commands are:
print_settings
shutdown
print_message
      </para>
<!-- TODO -->
    </sect1>

<!--
TODO
(12:21:30) jinmei: I'd like to have sample session using a command line www client such as wget
(12:21:33) jinmei: btw
-->

  </chapter>

  <chapter id="authserver">
    <title>Authoritative Server</title>
    <para>
    </para>

    <sect1>
      <title>Server Configurations</title>
      <para>
      </para>
    </sect1>

    <sect1>
      <title>Data Source Backends</title>
      <para>
      </para>
    </sect1>

    <sect1>
      <title>Loading Master Zones Files</title>
      <para>
<!-- TODO
loadzone
What happens in the database? replaces existing? What if a.foo
existed but new zone file didn't have a.foo, would previous a.foo
in database be removed?

if you replace the zone foo.com, all records from the prior foo.com disappear and a whole new set appears
-->

<!--TODO: permissions for xfrin or loadzone to create the file -->

      </para>
    </sect1>

    <sect1>
      <title>Troubleshooting</title>
      <para>
      </para>
    </sect1>

  </chapter>

<!-- TODO: how to help: run unit tests, join lists, review trac tickets -->

  <!-- <index>    <title>Index</title> </index> -->

</book>

<!--

TODO:

Overview

Getting BIND 10 Installed
  Basics
  Dependencies
  Optional
  Advanced

How Does Everything Work Together?

Need Help?

-->