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>

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

      <itemizedlist>

      <listitem>
      <simpara><command>msgq</command> &mdash; message bus</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> <!-- TODO --></simpara>
      </listitem>

      <listitem>
      <simpara><command>b10-xfrin</command> <!-- TODO --></simpara>
      </listitem>

      </itemizedlist>
    </para>

    <para>
      The user tools include:

      <itemizedlist>
      <listitem>
      <simpara><command>bindctl</command> &mdash; interactive administration interface</simpara>
      </listitem>
      <listitem>
      <simpara><command>bind10</command> &mdash; master process for BIND 10</simpara>
      </listitem>
      </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>Quickstart</title>
    <para>
      This chapter just covers the standard steps for installing
      and deploying BIND 10 as an authoritative nameserver using
      its defaults. For full customizations and details, see
      the respective chapters.
    </para>
  </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

-->

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