Commit 742d5a19 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰
Browse files

[master] Merge branch 'trac3418' (Kea Guide update)

Conflicts:
	ChangeLog
	doc/guide/bind10-guide.xml
parents 701e23d6 73e6019d
796. [doc] tomek
User's Guide renamed to Kea Administrator Reference Manual,
removed sections specific to BIND10/Bundy framework, rewritten
general and DHCPv4 specific examples.
(Trac #3418, git 73e6019d83760f0500890240e2e187dcd5e1e14c)
795. [func] marcin
Added support to keactrl to start, stop, reconfigure and gather
status of the DHCP-DDNS server.
......
......@@ -2,7 +2,12 @@
# Process this file with autoconf to produce a configure script.
AC_PREREQ([2.59])
AC_INIT(bind10, 20140313, kea-dev@isc.org)
# For released versions, this is in x.y.z format.
# For GIT versions, this is x.y.z-git, where x.y.z denotes the software
# version that was used as a base + changes that were made later, but
# are not released yet.
AC_INIT(bind10, 0.8.0-git, kea-dev@isc.org)
AC_CONFIG_SRCDIR(README)
# serial-tests is not available in automake version before 1.13, so
......
......@@ -2,15 +2,22 @@ SUBDIRS = guide design
EXTRA_DIST = version.ent.in differences.txt Doxyfile Doxyfile-xml
nobase_dist_doc_DATA = examples/kea4/single-subnet.json
nobase_dist_doc_DATA += examples/kea4/several-subnets.json
nobase_dist_doc_DATA += examples/kea6/several-subnets.json
devel:
mkdir -p html
(cat Doxyfile; echo PROJECT_NUMBER=$(PACKAGE_VERSION)) | doxygen - > html/doxygen.log 2> html/doxygen-error.log
echo `grep -i ": warning:" html/doxygen-error.log | wc -l` warnings/errors detected.
guide:
$(MAKE) -C guide kea-guide.html
clean:
rm -rf html
# That's a bit of a hack, but we are making sure that devel target
# is always valid. The alternative is to make devel depend on all
# *.cc *.h files in the whole tree.
.PHONY: devel
.PHONY: devel guide
/bind10-guide.html
/bind10-guide.txt
/bind10-messages.html
/bind10-messages.xml
/kea-guide.html
/kea-guide.txt
/kea-messages.html
/kea-messages.xml
# generated documentation
HTMLDOCS = bind10-guide.html bind10-messages.html
DOCS = bind10-guide.txt
HTMLDOCS = kea-guide.html kea-messages.html
DOCS = kea-guide.txt
dist_doc_DATA = $(DOCS)
dist_html_DATA = $(HTMLDOCS) bind10-guide.css
dist_html_DATA = $(HTMLDOCS) kea-guide.css
EXTRA_DIST = bind10-guide.xml
DISTCLEANFILES = $(HTMLDOCS) $(DOCS) bind10-messages.xml
DOCBOOK = kea-guide.xml intro.xml quickstart.xml install.xml config.xml
DOCBOOK += dhcp4-srv.xml dhcp6-srv.xml logging.xml
EXTRA_DIST = $(DOCBOOK)
DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml
# This is not a "man" manual, but reuse this for now for docbook.
if GENERATE_DOCS
bind10-guide.html: bind10-guide.xml
kea-guide.html: $(DOCBOOK)
@XSLTPROC@ --novalid --xinclude --nonet \
--path $(top_builddir)/doc \
-o $@ \
--stringparam section.autolabel 1 \
--stringparam section.label.includes.component.label 1 \
--stringparam html.stylesheet bind10-guide.css \
--stringparam html.stylesheet kea-guide.css \
http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl \
$(srcdir)/bind10-guide.xml
$(srcdir)/kea-guide.xml
bind10-guide.txt: bind10-guide.html
@ELINKS@ -dump -no-numbering -no-references bind10-guide.html > $@
kea-guide.txt: kea-guide.html
@ELINKS@ -dump -no-numbering -no-references kea-guide.html > $@
bind10-messages.html: bind10-messages.xml
kea-messages.html: kea-messages.xml
@XSLTPROC@ --novalid --xinclude --nonet \
--path $(top_builddir)/doc \
-o $@ \
--stringparam html.stylesheet bind10-guide.css \
--stringparam html.stylesheet kea-guide.css \
http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl \
bind10-messages.xml
kea-messages.xml
bind10-messages.xml:
kea-messages.xml:
$(PYTHON) $(top_srcdir)/tools/system_messages.py -o $@ $(top_srcdir)
else
......
This diff is collapsed.
<?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;" >
]>
<chapter id="kea-config">
<title>Kea configuration</title>
<para>Depending on configuration backend chosen (see <xref
linkend="dhcp-config-backend"/>), configuration mechanisms are different. The
following sections describe details of the differeent configuration backends. Note
that only one configuration backend can be used and its selection is
made when the configure script is run.</para>
<section id="bundy-backend">
<title>BIND 10 configuration backend</title>
<para>This legacy configuration backend allows Kea to use the former BIND10
framework. That framework and this Kea configuration backend is no longer
supported by ISC. It is currently developed as part of the Bundy project (see
<ulink url="http://bundy-dns.de">Bundy homepage</ulink>). See the Bundy project
documentation regarding configuration.</para>
</section>
<section id="json-backend">
<title>JSON configuration backend</title>
<para>JSON is the default configuration backend and the only one supported
as of the 0.9 release. It assumes that the servers are started from the command line
(either directly or using a script, see TODO for details). The JSON backend uses
certain signals to influence Kea. The configuration file is
specified upon startup using -c parameter.</para>
<section id="json-format">
<title>JSON syntax</title>
<para>Configuration files for DHCPv4, DHCPv6 and DDNS modules are defined
in an extended JSON format. Basic JSON is defined in <ulink
url="http://tools.ietf.org/html/rfc4627">RFC 4627</ulink>. Kea components
use a slightly modified JSON, in that they allowing bash-style
comments in the file: lines with the hash (#) character in the first column
are comment lines and are ignored.</para>
<para>The configuration file consists of a single object (often colloquially
called a map) started with a curly bracket. It comprises the "Dhcp4", "Dhcp6",
"DhcpDdns" and/or "Logging" objects. It is possible to define additional
elements, but they will be ignored. (That principle was chosen to ease
configuration management.) For example, it is possible to define Dhcp4,
Dhcp6 and Logging elements in a single configuration file that can be used to
start both the DHCPv4 and DHCPv6 components. When starting, the DHCPv4 component
will use Dhcp4 object to configure itself and the Logging object to configure logging
parameters; it will ignore the Dhcp6 object.</para>
<para>For example, a very simple configuration for both DHCPv4 and DHCPv6
could look like this:
<screen>
# The whole configuration starts here.
{
# DHCPv4 specific configuration starts here.
"Dhcp4": {
"interfaces": [ "eth0" ],
"valid-lifetime": 4000,
"renew-timer": 1000,
"rebind-timer": 2000,
"subnet4": [{
"pool": "192.0.2.1-192.0.2.200",
"subnet": "192.0.2.0/24"
}],
...
},
# DHCPv4 specific configuration ends here.
# DHCPv6 specific configuration starts here.
"Dhcp6": {
"interfaces": [ "eth1" ],
"preferred-lifetime": 3000,
"valid-lifetime": 4000,
"renew-timer": 1000,
"rebind-timer": 2000,
"subnet6": [{
"pool": "2001:db8::/80",
"subnet": "2001:db8::/64"
}],
...
},
# DHCPv6 specific configuration ends here.
# Logger parameters (that could be shared among several components) start here.
# This section is used by both the DHCPv4 and DHCPv6 servers.
"Logging": {
"loggers": [{
"name": "*",
"severity": "DEBUG"
}],
...
}
# Logger parameters end here.
# The whole configuration structure ends here.
}
</screen>
</para>
<para>More examples are available in the Kea source code in the
<filename>doc/examples</filename> directory.</para>
<para>To avoid repetition of mostly similar structures, examples in the
rest of this guide will showcase only the subset of parameters appropriate for a given
context. For example, when discussing the IPv6 subnets configuration in
DHCPv6, only subnet6 parameters will be mentioned. It is implied that
remaining elements (the global map that holds Dhcp6, Logging and possibly
DhcpDdns) are present, but they are omitted for clarity. Usually, locations
where extra parameters may appear are denoted with an ellipsis.</para>
</section>
<section>
<title>Simplified Notation</title>
<para>It is sometimes convenient to refer to specific element in the
configuration hierarchy. Each hierarchy level is separated by a slash.
If there is an array, a specific instance within that array is referred by
a number in square brackets (with numbering starting at zero). For example, in the above configuration the
valid-lifetime in Dhcp6 component can be referred to as
Dhcp6/valid-lifetime, the first interface for the DHCPv4 server as
Dhcp4/interfaces[0] and the pool in the first subnet defined in the DHCPv6
configuration as Dhcp6/subnet6[0]/pool.</para>
<!-- @todo Add a reference here after #3422 is done -->
</section>
</section>
</chapter>
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
<?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;" >
<!ENTITY % version SYSTEM "version.ent">
%version;
]>
<chapter id="intro">
<title>Introduction</title>
<para>
Kea is the next generation of DHCP software developed by ISC.
It supports both DHCPv4 and DHCPv6 protocols along with their
extensions, e.g. prefix delegation and dynamic updates to DNS.
</para>
<para>
Kea was initially developed as a part of the BIND 10 framework
(<ulink url="http://bind10.isc.org"/>). In early 2014, ISC
made the decision to discontinue active development of BIND 10 and
continue development of Kea as standalone DHCP software. As a result,
the components and libraries related to the BIND10 framework and DNS
are going to be removed from the Kea source tree over time.
In order to remove the dependency on Python 3, the BIND 10 framework
will be replaced by the server startup and configuration mechanisms
written in C++.
</para>
<note>
<simpara>Kea was implemented in the BIND 10 framework and to certain extent
still depends on various BIND 10 libraries. It also requires the BIND 10
framework to run, because the BIND 10 configuration mechanisms are used to
configure Kea. As a result, this document still refers to BIND 10 in many
paragraphs. The term "BIND 10" in the context of this document means
"BIND 10 libraries and applications which are necessary for Kea to run
and configure". The term "Kea" means "the collection of binaries and libraries
which, as a whole, implement the DHCP protocols".
</simpara>
</note>
<para>
This guide covers Kea version &__VERSION__;.
</para>
<section>
<title>Supported Platforms</title>
<para>
Kea is officially supported on RedHat Enterprise Linux,
CentOS, Fedora and FreeBSD systems. It is also likely to work on many
other platforms: 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. Non supported systems
(especially non-Linux) are likely to have issues with directly
connected DHCPv4 clients.
</para>
<para>There are currently no plans to port Kea to Windows platforms.</para>
</section>
<section id="required-software">
<title>Required Software at Run-time</title>
<para>
Running Kea uses various extra software which may
not be provided in the default installation of some operating systems,
nor in the standard package collections. You may
need to install this required software separately.
(For the build requirements, also see
<xref linkend="build-requirements"/>.)
</para>
<itemizedlist>
<listitem>
<simpara>
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 originate
in BIND 10. These modules require at least Python 3.1 to run.
They also work with Python 3.2, 3.3 or 3.4 (<ulink
url="http://www.python.org/"/>). The dependency on Python will
be removed once replacement configuration and startup
mechanisms are developed and released as Kea 0.9. At this
point Kea will be written in pure C++.
</simpara>
</listitem>
<listitem>
<simpara>
Kea supports two crypto libraries: Botan and OpenSSL. Only one of them
is required during compilation. Kea uses the Botan crypto library for
C++ (<ulink url="http://botan.randombit.net/"/>), version 1.8 or
later. As an alternative to Botan, Kea can use the OpenSSL crypto
library (<ulink url="http://www.openssl.org/"/>). It requires a version
with SHA-2 support.
</simpara>
</listitem>
<listitem>
<simpara>
Kea uses the log4cplus C++ logging library
(<ulink url="http://log4cplus.sourceforge.net/"/>).
It requires at least log4cplus version 1.0.3.
</simpara>
</listitem>
<listitem>
<simpara>
In order to store lease information in a MySQL database, Kea requires MySQL
headers and libraries. This is an optional dependency in that Kea can be
built without MySQL support.
</simpara>
</listitem>
<listitem>
<simpara>
In order to store lease information in a PostgresSQL database, Kea requires PostgresSQL
headers and libraries. This is an optional dependency in that Kea can be
built without PostgresSQL support.
</simpara>
</listitem>
</itemizedlist>
</section>
<section id="starting_stopping">
<title>Starting and Stopping the Server</title>
<!-- @todo: Rewrite this section after #3422 is done -->
<para>
Kea is modular. Part of this modularity is
accomplished using multiple cooperating processes which, together,
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
command, <command>bind10</command>. This command starts
a master process, <command>b10-init</command>, which will
start other required processes and other processes when
configured. The processes that may be started have names
starting with "b10-", including:
</para>
<para>
<itemizedlist>
<listitem>
<simpara>
<command>b10-cfgmgr</command> &mdash;
Configuration manager.
This process maintains all of the configuration for BIND 10.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-cmdctl</command> &mdash;
Command and control service.
This process allows external control of the BIND 10 system.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-dhcp4</command> &mdash;
DHCPv4 server process.
This process responds to DHCPv4 queries from clients.
</simpara>
</listitem>
<listitem>
<simpara>
<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-msgq</command> &mdash;
Message bus daemon.
This process coordinates communication between all of the other
BIND 10 processes.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-sockcreator</command> &mdash;
Socket creator daemon.
This process creates sockets used by
network-listening BIND 10 processes.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-stats</command> &mdash;
Statistics collection daemon.
This process collects and reports statistics data.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-stats-httpd</command> &mdash;
HTTP server for statistics reporting.
This process reports statistics data in XML format over HTTP.
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
These do not need to be manually started independently.
</para>
</section>
<section id="managing_once_running">
<title>Managing BIND 10</title>
<!-- @todo: Rewrite this section after #3422 is done -->
<para>
Once BIND 10 is running, a few commands are used to interact
directly with the system:
<itemizedlist>
<listitem>
<simpara>
<command>bindctl</command> &mdash;
Interactive administration interface.
This is a low-level command-line tool which allows
a developer or an experienced administrator to control
Kea.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-cmdctl-usermgr</command> &mdash;
User access control.
This tool allows an administrator to authorize additional users
to manage Kea.
</simpara>
</listitem>
<!-- TODO usermgr -->
</itemizedlist>
</para>
</section>
<para>
The tools and modules are covered in full detail in this 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
init.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 and configuration backend,
and, of course, DHCP. These include detailed developer
documentation and code examples.
<!-- TODO point to this -->
</para>
</chapter>
<?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;" >
<!ENTITY % version SYSTEM "version.ent">
%version;
]>
<!--
- Copyright (C) 2010-2014 Internet Systems Consortium, Inc. ("ISC")
-
- Permission to use, copy, modify, and/or distribute this software for any
- purpose with or without fee is hereby granted, provided that the above
- copyright notice and this permission notice appear in all copies.
-
- THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
- REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
- AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
- LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<book>
<?xml-stylesheet href="bind10-guide.css" type="text/css"?>
<bookinfo>
<title>Kea Administrator Reference Manual</title>
<copyright>
<year>2010-2014</year><holder>Internet Systems Consortium, Inc.</holder>
</copyright>
<abstract>
<para>
Kea is an open source implementation of the Dynamic Host Configuration
Protocol (DHCP) servers, developed and maintained by Internet Systems
Consortium (ISC).
</para>
<para>
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
Kea, can be found at <ulink url="http://kea.isc.org/docs"/>.
</para> </abstract>
<releaseinfo>This is the reference guide for Kea version
&__VERSION__;.</releaseinfo>
</bookinfo>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="intro.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="quickstart.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="install.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="config.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp4-srv.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp6-srv.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ddns.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="libdhcp.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="logging.xml" />
<chapter id="acknowledgements">
<title>Acknowledgements</title>
<para>Support for the development of the DHCPv4, DHCPv6 and
DHCP-DDNS components was provided by
<ulink url="http://www.comcast.com/">Comcast</ulink>.</para>
<para>Kea was initially implemented as a collection of applications
within the BIND 10 framework. Hence, Kea development would not be
possible without the generous support of BIND 10 project sponsors.</para>
<para><ulink url="http://jprs.co.jp/">JPRS</ulink> and
<ulink url="http://cira.ca/">CIRA</ulink> are Patron Level
sponsors.</para>