Skip to content

GitLab

Commit e7a7acb5 authored by Marcin Siodelski's avatar Marcin Siodelski
Browse files

[3395] Updated BIND10 Guide, removing DNS parts and updating examples.

parent 197f6749
Hide whitespace changes
Inline Side-by-side
Showing with 350 additions and 2037 deletions
doc/guide/bind10-guide.xml
View file @ e7a7acb5
......@@ -26,95 +26,64 @@
<?xml-stylesheet href="bind10-guide.css" type="text/css"?>
<bookinfo>
<title>BIND 10 Guide</title>
<subtitle>Administrator Reference for BIND 10</subtitle>
<title>Kea Guide</title>
<subtitle>Administrator Reference for Kea</subtitle>
<copyright>
<year>2010-2014</year><holder>Internet Systems Consortium, Inc.</holder>
</copyright>
<abstract>
<para>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 (codenamed Kea).
<para>
Kea is an implementation of the Dynamic Host Configuration
Protocol (DHCP) servers with development managed by Internet Systems
Consortium (ISC).
</para>
<!-- TODO: The VERSION needs to be updated -->
<para>
This is the reference guide for BIND 10 version &__VERSION__;.
This is the reference guide for Kea version &__VERSION__;.
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 <ulink url="http://bind10.isc.org/docs"/>.
Kea, can be found at <ulink url="http://kea.isc.org/docs"/>.
</para> </abstract>
<releaseinfo>This is the reference guide for BIND 10 version
<releaseinfo>This is the reference guide for Kea version
&__VERSION__;.</releaseinfo>
</bookinfo>
<!-- todo: Preface is now empty, but leave it around now -->
<preface>
<title>Preface</title>
<section id="acknowledgements">
<title>Acknowledgements</title>
<para>BIND 10 is a sponsored development project, and would not
be possible without the generous support of the sponsors.</para>
<para><ulink url="http://jprs.co.jp/">JPRS</ulink> and
<ulink url="http://cira.ca/">CIRA</ulink> are Patron Level
sponsors.</para>
<para><ulink url="https://www.afnic.fr/">AFNIC</ulink>,
<ulink url="https://www.cnnic.net.cn/">CNNIC</ulink>,
<ulink url="https://www.nic.cz/">CZ.NIC</ulink>,
<ulink url="http://www.denic.de/">DENIC eG</ulink>,
<ulink url="https://www.google.com/">Google</ulink>,
<ulink url="https://www.ripe.net/">RIPE NCC</ulink>,
<ulink url="https://registro.br/">Registro.br</ulink>,
<ulink url="https://nzrs.net.nz/">.nz Registry Services</ulink>, and
<ulink url="https://www.tcinet.ru/">Technical Center of Internet</ulink>
are current sponsors.</para>
<para><ulink url="https://www.afilias.info/">Afilias</ulink>,
<ulink url="https://www.iis.se/">IIS.SE</ulink>,
<ulink url="http://www.nominet.org.uk/">Nominet</ulink>, and
<ulink url="https://www.sidn.nl/">SIDN</ulink> were founding
sponsors of the project.</para>
<!-- DHCP sponsorship by Comcast -->
<para>Support for BIND 10 development of the DHCPv4 and DHCPv6
components is provided by
<ulink url="http://www.comcast.com/">Comcast</ulink>.</para>
</section>
</preface>
<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 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.
BIND 10 provides a EDNS0- and DNSSEC-capable authoritative
DNS server and a caching recursive name server which also
provides forwarding.
It also provides experimental DHCPv4 and DHCPv6 servers.
Kea is an implementation of the new generation DHCP servers from
ISC. It supports both DHCPv4 and DHCPv6 protocols along with their
extensions (e.g. prefix delegation). It also supports the dynamic
updates to DNS.
</para>
<para>
Kea has been initially developed as a part of the BIND 10 framework
(<ulink url="http://bind10.isc.org"/>). In early 2014, ISC has
made a decision to discontinue active development of BIND 10 and
continue development of Kea as standalone DHCP servers. As a result,
the DNS-related binaries and libraries are going to be removed from
the Kea source tree over time.
</para>
<para>
This guide covers BIND 10 version &__VERSION__;.
This guide covers Kea version &__VERSION__;.
</para>
<section>
<title>Supported Platforms</title>
<para>
BIND 10 builds have been tested on (in no particular order)
Kea builds have been tested on (in no particular order)
Debian GNU/Linux 6 and unstable, Ubuntu 9.10, NetBSD 5,
Solaris 10 and 11, FreeBSD 7 and 8, CentOS Linux 5.3,
MacOS 10.6 and 10.7, and OpenBSD 5.1.
......@@ -122,7 +91,7 @@
It has been tested on Sparc, i386, and amd64 hardware
platforms.
It is planned for BIND 10 to build, install and run on
It is planned for Kea to build, install and run on
Windows and standard Unix-type platforms.
</para>
</section>
......@@ -131,7 +100,7 @@
<title>Required Software at Run-time</title>
<para>
Running BIND 10 uses various extra software which may
Running Kea 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.
......@@ -140,52 +109,41 @@
</para>
<para>
BIND 10 requires at least Python 3.1
(<ulink url="http://www.python.org/"/>).
It also works with Python 3.2.
Kea was developed as a collection of applications within
BIND 10 framework and it still relies on the remaining parts
of this framework. In particular, the servers' configuration
and startup are still facilitated by the modules which origin
in BIND 10. These modules require at least Python 3.1 to run.
They also work with Python 3.2
(<ulink url="http://www.python.org/"/>)). The dependency
on Python will be removed once a replacing configuration
and startup mechanisms are developed for Kea. At this point
Kea will be written in pure C++.
</para>
<para>
BIND 10 uses the Botan crypto library for C++
Kea uses the Botan crypto library for C++
(<ulink url="http://botan.randombit.net/"/>).
It requires at least Botan version 1.8.
</para>
<para>
BIND 10 uses the log4cplus C++ logging library
Kea uses the log4cplus C++ logging library
(<ulink url="http://log4cplus.sourceforge.net/"/>).
It requires at least log4cplus version 1.0.3.
<!-- TODO: It is recommended to use at least version .... -->
</para>
<para>
The authoritative DNS server uses SQLite3
(<ulink url="http://www.sqlite.org/"/>).
<!-- TODO: is this still required? -->
It needs at least SQLite version 3.3.9.
</para>
<para>
The <command>b10-ddns</command>, <command>b10-xfrin</command>,
<command>b10-xfrout</command>, and <command>b10-zonemgr</command>
components require the libpython3 library and the Python
_sqlite3.so module (which is included with Python).
Python modules need to be built for the corresponding Python 3.
</para>
<!-- TODO: this will change ... -->
</section>
<section id="starting_stopping">
<title>Starting and Stopping the Server</title>
<para>
BIND 10 is modular. Part of this modularity is
Kea is modular. Part of this modularity is
accomplished using multiple cooperating processes which, together,
provide the server functionality. This is a change from
the previous generation of BIND software, which used a
single process.
provide the server functionality.
</para>
<!-- todo: Rename processes here, once they are renamed in the source -->
<para>
At first, running many different processes may seem confusing.
However, these processes are started by running a single
......@@ -200,14 +158,6 @@
<itemizedlist>
<listitem>
<simpara>
<command>b10-auth</command> &mdash;
Authoritative DNS server.
This process serves DNS requests.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-cfgmgr</command> &mdash;
......@@ -226,30 +176,36 @@
<listitem>
<simpara>
<command>b10-ddns</command> &mdash;
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.
<command>b10-dhcp4</command> &mdash;
DHCPv4 server process.
This process responds to DHCPv4 queries from clients.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-msgq</command> &mdash;
Message bus daemon.
This process coordinates communication between all of the other
BIND 10 processes.
<command>b10-dhcp6</command> &mdash;
DHCPv6 server process.
This process responds to DHCPv6 queries from clients.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-dhcp-ddns</command> &mdash;
DHCP-DDNS process.
This process acts as an intermediary between the DHCP servers
and DNS server. It receives name update requests from the DHCP
servers and sends DNS Update messages to the DNS servers.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-resolver</command> &mdash;
Recursive name server.
This process handles incoming DNS queries and provides
answers from its cache or by recursively doing remote lookups.
(This is an experimental proof of concept.)
<command>b10-msgq</command> &mdash;
Message bus daemon.
This process coordinates communication between all of the other
BIND 10 processes.
</simpara>
</listitem>
......@@ -278,33 +234,6 @@
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-xfrin</command> &mdash;
Incoming zone transfer service.
This process is used to transfer a new copy
of a zone into BIND 10, when acting as a secondary server.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-xfrout</command> &mdash;
Outgoing zone transfer service.
This process is used to handle transfer requests to
send a local zone to a remote secondary server.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-zonemgr</command> &mdash;
Secondary zone manager.
This process keeps track of timers and other
necessary information for BIND 10 to act as a slave server.
</simpara>
</listitem>
</itemizedlist>
</para>
......@@ -327,15 +256,7 @@
Interactive administration interface.
This is a low-level command-line tool which allows
a developer or an experienced administrator to control
BIND 10.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-loadzone</command> &mdash;
Zone file loader.
This tool will load standard masterfile-format zone files into
BIND 10.
Kea.
</simpara>
</listitem>
<listitem>
......@@ -343,7 +264,7 @@
<command>b10-cmdctl-usermgr</command> &mdash;
User access control.
This tool allows an administrator to authorize additional users
to manage BIND 10.
to manage Kea.
</simpara>
</listitem>
<!-- TODO usermgr -->
......@@ -381,10 +302,9 @@ var/
<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
for C++ and Python for the message bus and configuration backend,
and, of course, DHCP. These include detailed developer
documentation and code examples.
<!-- TODO: DHCP also but no Python yet. -->
<!-- TODO point to this -->
</para>
......@@ -395,13 +315,13 @@ var/
<para>
This quickly covers the standard steps for installing
and deploying BIND 10.
and deploying Kea.
For further details, full customizations, and troubleshooting,
see the respective chapters in the BIND 10 guide.
see the respective chapters in the Kea guide.
</para>
<section id="quick-start-auth-dns">
<title>Quick start guide for authoritative DNS service</title>
<section id="quick-start-dhcp6">
<title>Quick start guide for DHCPv6 service</title>
<orderedlist>
......@@ -411,22 +331,18 @@ var/
</simpara>
</listitem>
<!-- We may need to replace it with the link to a downloadable tarball
once we have it. -->
<listitem>
<simpara>
Download the BIND 10 source tar file from
<ulink url="ftp://ftp.isc.org/isc/bind10/"/>.
Checkout the latest Kea revision from the Git repository:
<screen>$ <userinput>git clone git://git.kea.isc.org/kea</userinput> </screen>
</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>
<screen>$ <userinput>cd kea</userinput>
$ <userinput>./configure</userinput></screen>
</para>
</listitem>
......@@ -465,16 +381,16 @@ $ <userinput>./configure</userinput></screen>
</listitem>
<listitem>
<para>DNS and DHCP components are not started in the default
configuration. In another console, enable the authoritative
DNS service (by using the <command>bindctl</command> utility
to configure the <command>b10-auth</command> component to
<para>DHCP components are not started in the default
configuration. In another console, enable the DHCPv6
service (by using the <command>bindctl</command> utility
to configure the <command>b10-dhcp6</command> component to
run): <screen>$ <userinput>bin/bindctl</userinput></screen>
(Login with the username and password you used above to create a user.)
<screen>
&gt; <userinput>config add Init/components b10-auth</userinput>
&gt; <userinput>config set Init/components/b10-auth/special auth</userinput>
&gt; <userinput>config set Init/components/b10-auth/kind needed</userinput>
&gt; <userinput>config add Init/components b10-dhcp6</userinput>
<!-- todo: Should the kind be needed or dispensable? -->
&gt; <userinput>config set Init/components/b10-dhcp6/kind dispensable</userinput>
&gt; <userinput>config commit</userinput>
&gt; <userinput>quit</userinput>
</screen>
......@@ -482,25 +398,13 @@ $ <userinput>./configure</userinput></screen>
</listitem>
<listitem>
<para>Test it; for example:
<screen>$ <userinput>dig @127.0.0.1 -c CH -t TXT version.bind</userinput></screen>
<para>Test it; for example, use the
<ulink url="http://www.isc.org/downloads/DHCP/">ISC DHCP client</ulink>
to send DHCPv6 queries to the server and verify that the client receives a
configuration from the server:
<screen>$ <userinput>dhclient -6</userinput></screen>
</para>
</listitem>
<listitem>
<para>Load desired zone file(s), for example:
<screen>$ <userinput>bin/b10-loadzone <replaceable>-c '{"database_file": "/usr/local/var/bind10/zone.sqlite3"}'</replaceable> <replaceable>your.zone.example.org</replaceable> <replaceable>your.zone.file</replaceable></userinput></screen>
</para>
(If you use the sqlite3 data source with the default DB
file, you can omit the -c option).
</listitem>
<listitem>
<simpara>
Test the new zone.
</simpara>
</listitem>
</orderedlist>
</section>
......@@ -516,7 +420,7 @@ $ <userinput>./configure</userinput></screen>
<para>
Some operating systems or software package vendors may
provide ready-to-use, pre-built software packages for
the BIND 10 suite.
the Kea.
Installing a pre-built package means you do not need to
install build-only prerequisites and do not need to
<emphasis>make</emphasis> the software.
......@@ -533,7 +437,7 @@ $ <userinput>./configure</userinput></screen>
<title>Install Hierarchy</title>
<para>
The following is the standard, common layout of the
complete BIND 10 installation:
complete Kea installation:
<itemizedlist>
<listitem>
<simpara>
......@@ -558,7 +462,7 @@ $ <userinput>./configure</userinput></screen>
<filename>libexec/bind10/</filename> &mdash;
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
These are the BIND 10 and Kea modules which are daemons started by
the <command>b10-init</command> master process.
</simpara>
</listitem>
......@@ -601,7 +505,7 @@ $ <userinput>./configure</userinput></screen>
<para>
In addition to the run-time requirements (listed in
<xref linkend="required-software"/>), building BIND 10
<xref linkend="required-software"/>), building Kea
from source code requires various development include headers and
program development tools.
</para>
......@@ -611,7 +515,7 @@ $ <userinput>./configure</userinput></screen>
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.
libraries, to build Kea from source code.
</simpara>
</note>
......@@ -625,7 +529,7 @@ $ <userinput>./configure</userinput></screen>
</para>
<para>
To build BIND 10, also install the Botan (at least version
To build Kea, also install the Botan (at least version
1.8) and the log4cplus (at least version 1.0.3)
development include headers.
</para>
......@@ -640,15 +544,15 @@ Debian and Ubuntu:
as a dependency earlier -->
<para>
Building BIND 10 also requires a C++ compiler and
Building Kea also requires a C++ compiler and
standard development headers, make, and pkg-config.
BIND 10 builds have been tested with GCC g++ 3.4.3, 4.1.2,
Kea builds have been tested with GCC g++ 3.4.3, 4.1.2,
4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10.
</para>
<para>
Visit the user-contributed wiki at <ulink
url="http://bind10.isc.org/wiki/SystemSpecificNotes" />
url="http://kea.isc.org/wiki/SystemSpecificNotes" />
for system-specific installation tips.
</para>
......@@ -657,26 +561,21 @@ as a dependency earlier -->
<section id="install">
<title>Installation from source</title>
<para>
BIND 10 is open source software written in C++ and Python.
Kea is open source software written in C++ and Python.
It is freely available in source code form from ISC as a
downloadable tar file or via BIND 10's Git code revision control
downloadable tar file or via Kea Git code revision control
service. (It may also be available in pre-compiled ready-to-use
packages from operating system vendors.)
</para>
<section>
<title>Download Tar File</title>
<para>
Downloading a release tar file is the recommended method to
obtain the source code.
</para>
<title>Download Tar File</title>
<para>
The BIND 10 releases are available as tar file downloads from
<ulink url="ftp://ftp.isc.org/isc/bind10/"/>.
Periodic development snapshots may also be available.
Kea 0.8 is available as a part of BIND10 1.2 release, which is
a final release of BIND10 from ISC. This release can be downloaded
from: <ulink url="ftp://ftp.isc.org/isc/bind10/"/>.
</para>
<!-- TODO -->
</section>
<section>
......@@ -698,18 +597,18 @@ as a dependency earlier -->
<para>
The latest development code (and temporary experiments
and un-reviewed code) is available via the BIND 10 code revision
control system. This is powered by Git and all the BIND 10
and un-reviewed code) is available via the Kea code revision
control system. This is powered by Git and all the Kea
development is public.
The leading development is done in the <quote>master</quote>
branch.
</para>
<para>
The code can be checked out from
<filename>git://git.bind10.isc.org/bind10</filename>;
<filename>git://git.kea.isc.org/kea</filename>;
for example:
<screen>$ <userinput>git clone git://git.bind10.isc.org/bind10</userinput></screen>
<screen>$ <userinput>git clone git://git.kea.isc.org/kea</userinput></screen>
</para>
<para>
......@@ -733,7 +632,7 @@ as a dependency earlier -->
<section id="configure">
<title>Configure before the build</title>
<para>
BIND 10 uses the GNU Build System to discover build environment
Kea uses the GNU Build System to discover build environment
details.
To generate the makefiles using the defaults, simply run:
<screen>$ <userinput>./configure</userinput></screen>
......@@ -794,7 +693,7 @@ as a dependency earlier -->
<note>
<para>
For additional instructions concerning the building and installation of
BIND 10 DHCP, see <xref linkend="dhcp-install-configure"/>.
Kea, see <xref linkend="dhcp-install-configure"/>.
</para>
</note>
</para>
......@@ -832,7 +731,7 @@ as a dependency earlier -->
<section>
<title>Install</title>
<para>
To install the BIND 10 executables, support files,
To install the Kea executables, support files,
and documentation, run:
<screen>$ <userinput>make install</userinput></screen>
</para>
......@@ -879,14 +778,14 @@ as a dependency earlier -->
</chapter>
<chapter id="bind10">
<title>Starting BIND 10 with <command>bind10</command></title>
<title>Starting Kea with <command>bind10</command></title>
<para>
BIND 10 is started with the <command>bind10</command> command.
Kea is started with the <command>bind10</command> command.
It runs the <command>b10-init</command> daemon which
starts up the required processes, and
will also restart some processes that exit unexpectedly.
<command>bind10</command> is the only command needed to start
the BIND 10 system.
the Kea.
</para>
<para>
......@@ -905,8 +804,8 @@ as a dependency earlier -->
module, if only to send information about themselves somewhere,
but more importantly to ask about their own settings, and
about other modules. The <command>b10-sockcreator</command> daemon
helps allocate Internet addresses and ports as needed for BIND 10
network services.
can allocate Internet addresses and ports needed by network services
but is currently unused by DHCP servers.
</para>
<para>
......@@ -915,13 +814,13 @@ as a dependency earlier -->
<command>b10-cmdctl</command> for administration tools to
communicate with the system, and
<command>b10-stats</command> for statistics collection.
The DNS and DHCP servers are not started by default.
The DHCP servers are not started by default.
The configuration of components to start is covered in
<xref linkend="bind10.components"/>.
<xref linkend="kea.components"/>.
</para>
<section id="start">
<title>Starting BIND 10</title>
<title>Starting Kea</title>
<para>
To start the BIND 10 service, simply run <command>bind10</command>
as root.
......@@ -954,7 +853,7 @@ as a dependency earlier -->
<para>
The BIND 10 components use the <command>b10-msgq</command>
message routing daemon to communicate with other BIND 10 components.
message routing daemon to communicate with Kea components.
The <command>b10-msgq</command> implements what is called the
<quote>Command Channel</quote>.
Processes intercommunicate by sending messages on the command
......@@ -980,14 +879,14 @@ as a dependency earlier -->
<para>
The configuration manager, <command>b10-cfgmgr</command>,
handles all BIND 10 system configuration. It provides
handles all system configuration. It provides
persistent storage for configuration, and notifies running
modules of configuration changes.
</para>