kea/doc/userguide/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</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 release and development snapshots
        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>
      <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, SQLite 3.3.9 or newer,
        and the Python _sqlite3.so module.
<!-- TODO: list where to get these from -->
<!-- TODO: this will change ... -->
      </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>
      <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.
<!-- TODO: what about boost? ship with it or not? -->
      </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>Build and install</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 option
	is <command>--prefix</command> to define the installation
        location (the default is <filename>/usr/local/</filename>).
<!-- TODO: gtest, lcov -->
      </para>

      <para>
        Then to build the executables from the C++ code, run:
        <screen>$ <userinput>make</userinput></screen>
      </para>

      <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>

<!-- TODO: tests -->

    </sect1>
    <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>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; configuration and
        data source databases.
<!-- TODO: move the sqlite3 database there -->
      </simpara>
      </listitem>
      </itemizedlist>
    </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.
      And <command>b10-cfgmgr</command> 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.
    </para>


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

    <para>
      <command>b10-cmdctl</command> is the gateway between
      administrators and the whole system; when it 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 (i.e. <command>bindctl</command>).
    </para>
<!-- TODO: replace /usr/local -->
<!-- TODO: permissions -->
    <para><filename>/usr/local/share/bind10/cmdctl-keyfile.pem</filename>
      contains the Private key, such as a RSA PRIVATE KEY.
    </para>
    <para><filename>/usr/local/share/bind10/cmdctl-certfile.pem</filename>
      contains the Certificate.
    </para>
    <para>
      This could be a self-signed certificate or purchased from a
      certification authority.
    </para>
    </sect1>

<!--
    <para>
(08:20:56) shane: It is in theory possible to run without cmdctl.
(08:21:02) shane: I think we discussed this.
    </para>
-->
    <sect1 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.  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>
<!--
      <para>
        The stored configuration file is ...
TODO
      </para>
-->
    </sect1>

<!--
TODO
    <para>
bindctl talks to b10-cmdctl
    </para>
cfgmanager can send all specifications (and all current settings)
to bindctl (through cmdctl in fact), so an admin can simply run bindctl,
do config show, and it shows all modules; config show >module> shows all
options for that module

(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
-->

    <para>
      To start the BIND 10 service, 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 -->

  </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>
      </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?

-->