intro.xml 10.2 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11
<?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>
12
      Kea is the next generation of DHCP software developed by ISC.
13 14 15 16 17
      It supports both DHCPv4 and DHCPv6 protocols along with their
      extensions, e.g. prefix delegation and dynamic updates to DNS.
    </para>

    <para>
18
      Kea was initially developed as a part of the BIND 10 framework
19 20
      (<ulink url="http://bind10.isc.org"/>). In early 2014, ISC
      made the decision to discontinue active development of BIND 10 and
21
      continue development of Kea as standalone DHCP software. As a result,
22 23 24 25 26 27 28 29
      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>
30 31 32
      <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
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64
      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
65 66
        not be provided in the default installation of some operating systems,
        nor in the standard package collections. You may
67 68 69 70 71
        need to install this required software separately.
        (For the build requirements, also see
        <xref linkend="build-requirements"/>.)
      </para>

72 73 74
      <itemizedlist>
        <listitem>
            <simpara>
75 76 77 78 79 80 81
        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
82
        be removed once replacement configuration and startup
83 84
        mechanisms are developed and released as Kea 0.9. At this
        point Kea will be written in pure C++.
85 86
            </simpara>
        </listitem>
87

88 89
        <listitem>
            <simpara>
90 91 92 93 94 95
        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.
96 97
            </simpara>
        </listitem>
98

99 100
        <listitem>
            <simpara>
101 102 103
        Kea uses the log4cplus C++ logging library
        (<ulink url="http://log4cplus.sourceforge.net/"/>).
        It requires at least log4cplus version 1.0.3.
104 105
            </simpara>
        </listitem>
106

107 108 109 110 111 112 113
        <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>
114

115 116
        <listitem>
            <simpara>
117
	In order to store lease information in a PostgreSQL database, Kea requires PostgreSQL
118
    headers and libraries.  This is an optional dependency in that Kea can be
119
    built without PostgreSQL support.
120 121 122
            </simpara>
        </listitem>
      </itemizedlist>
123 124 125 126
    </section>

    <section id="starting_stopping">
      <title>Starting and Stopping the Server</title>
127
      <!-- @todo: Rewrite this section after #3422 is done -->
128 129 130 131 132 133 134 135 136 137 138 139 140 141
      <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
142
	starting with "kea-", including:
143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166
      </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>
167
              <command>kea-dhcp4</command> &mdash;
168 169 170 171 172 173 174
              DHCPv4 server process.
              This process responds to DHCPv4 queries from clients.
            </simpara>
          </listitem>

          <listitem>
            <simpara>
175
              <command>kea-dhcp6</command> &mdash;
176 177 178 179 180 181 182
              DHCPv6 server process.
              This process responds to DHCPv6 queries from clients.
            </simpara>
          </listitem>

          <listitem>
            <simpara>
183
              <command>kea-dhcp-ddns</command> &mdash;
184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201
              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>
202
              <command>kea-sockcreator</command> &mdash;
203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235
              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>
236
      <!-- @todo: Rewrite this section after #3422 is done -->
237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300

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