Skip to content
GitLab
Projects
Groups
Snippets
/
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Menu
Open sidebar
Adam Osuchowski
Kea
Commits
e7a7acb5
Commit
e7a7acb5
authored
Apr 11, 2014
by
Marcin Siodelski
Browse files
[3395] Updated BIND10 Guide, removing DNS parts and updating examples.
parent
197f6749
Changes
1
Hide whitespace changes
Inline
Side-by-side
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>
—
Authoritative DNS server.
This process serves DNS requests.
</simpara>
</listitem>
<listitem>
<simpara>
<command>
b10-cfgmgr
</command>
—
...
...
@@ -226,30 +176,36 @@
<listitem>
<simpara>
<command>
b10-ddns
</command>
—
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>
—
DHCPv4 server process.
This process responds to DHCPv4 queries from clients.
</simpara>
</listitem>
<listitem>
<simpara>
<command>
b10-msgq
</command>
—
Message bus daemon.
This process coordinates communication between all of the other
BIND 10 processes.
<command>
b10-dhcp6
</command>
—
DHCPv6 server process.
This process responds to DHCPv6 queries from clients.
</simpara>
</listitem>
<listitem>
<simpara>
<command>
b10-dhcp-ddns
</command>
—
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>
—
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>
—
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>
—
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>
—
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>
—
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>
—
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>
—
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, D
NS
. These include detailed developer
for C++ and Python for the message bus
and
configuration backend,
and, of course, D
HCP
. 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>
>
<userinput>
config add Init/components b10-
auth
</userinput>
>
<userinput>
config set Init/components/b10-auth/special auth
</userinput
>
>
<userinput>
config set Init/components/b10-
auth
/kind
needed
</userinput>
>
<userinput>
config add Init/components b10-
dhcp6
</userinput>
<!-- todo: Should the kind be needed or dispensable? --
>
>
<userinput>
config set Init/components/b10-
dhcp6
/kind
dispensable
</userinput>
>
<userinput>
config commit
</userinput>
>
<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>
—
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
serv
ic
es.
can
allocate Internet addresses and ports needed
by network services
but is currently unused by DHCP
serve
r
s.
</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.