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 daemon</simpara>
      </listitem>
      <listitem>
      <simpara><command>b10-cmdctl</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>
      </sect2>
    </sect1>

    <sect1>
      <title>Dependencies</title>
      <para>
        BIND 10 requires Python 3.1, SQLite 3.3.9 or newer,
        and the Python _sqlite3.so module.
<!-- TODO: this will change ... -->
        Building BIND 10 also requires a C++ compiler and
        standard development headers.
      </para>
    </sect1>

    <sect1>
      <title>Supported Platforms</title>
      <para>
        BIND 10 builds have been tested on Debian GNU/Linux 5,
        NetBSD 5, Solaris 10, and FreeBSD 7. 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.
      </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 database
      </simpara>
      </listitem>
      </itemizedlist>
    </para>
    </sect1>

    <sect1>
    <title>Starting BIND 10</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>
   </sect1>

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