intro.xml 8.67 KB
Newer Older
1
<!--
2
 - Copyright (C) 2014-2019 Internet Systems Consortium, Inc. ("ISC")
3
4
5
 -
 - This Source Code Form is subject to the terms of the Mozilla Public
 - License, v. 2.0. If a copy of the MPL was not distributed with this
Suzanne Goldlust's avatar
Suzanne Goldlust committed
6
 - file, you can obtain one at http://mozilla.org/MPL/2.0/.
7
8
9
10
11
12
-->

<!-- need this include to make the &keaversion; macro work -->
<!DOCTYPE book [
<!ENTITY % keaversion SYSTEM "version.ent">
%keaversion;
13
14
]>

15
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="intro">
16
17
    <title>Introduction</title>
    <para>
18
      Kea is the next generation of DHCP software developed by ISC.
19
20
21
22
23
      It supports both DHCPv4 and DHCPv6 protocols along with their
      extensions, e.g. prefix delegation and dynamic updates to DNS.
    </para>

    <para>
24
      This guide covers Kea version &keaversion;.
25
26
27
28
29
    </para>

    <section>
      <title>Supported Platforms</title>
      <para>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
30
        Kea is officially supported on CentOS, Fedora, Ubuntu, Debian, and FreeBSD systems.
31
        It is also likely to work on many other platforms. Kea-&keaversion; builds have been tested on:
32
        <itemizedlist>
Michal Nowikowski's avatar
Michal Nowikowski committed
33
          <listitem>CentOS Linux — 7.1804 (aka 7.5)</listitem>
34
          <listitem>Fedora — 28, 29</listitem>
Michal Nowikowski's avatar
Michal Nowikowski committed
35
          <listitem>Ubuntu — 16.04, 18.04</listitem>
Michal Nowikowski's avatar
Michal Nowikowski committed
36
          <listitem>Debian GNU/Linux — 8, 9</listitem>
37
          <listitem>FreeBSD — 11.0</listitem>
38
          <listitem>macOS — 10.13, 10.14</listitem>
39
        </itemizedlist>
40
41
42
43
      </para>
      <para>There are currently no plans to port Kea to Windows platforms.</para>
    </section>

44
    <section xml:id="required-software">
45
46
47
      <title>Required Software at Run-time</title>

      <para>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
48
        Running Kea uses various extra software packages which may
49
50
        not be provided in the default installation of some operating systems,
        nor in the standard package collections. You may
51
52
53
54
55
        need to install this required software separately.
        (For the build requirements, also see
        <xref linkend="build-requirements"/>.)
      </para>

56
      <itemizedlist>
57

58
59
        <listitem>
            <simpara>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
60
        Kea supports two cryptographic libraries: Botan and OpenSSL. Only one of them
61
        is required to be installed during compilation. Kea uses the Botan
Suzanne Goldlust's avatar
Suzanne Goldlust committed
62
63
64
        library for C++ (<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://botan.randombit.net/">http://botan.randombit.net/</uri>),
        version 1.9 or later. Note that support for Botan versions earlier than 2.0 will be removed in Kea 1.6.0 and later. As an alternative to Botan, Kea can use the
        OpenSSL cryptographic library (<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.openssl.org/">http://www.openssl.org/</uri>),
65
        version 1.0.2 or later.
66
67
            </simpara>
        </listitem>
68

69
70
        <listitem>
            <simpara>
71
        Kea uses the log4cplus C++ logging library
72
        (<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://log4cplus.sourceforge.net/">http://log4cplus.sourceforge.net/</uri>).
73
        It requires log4cplus version 1.0.3 or later.
74
75
            </simpara>
        </listitem>
76

77
78
        <listitem>
          <simpara>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
79
            Kea requires the Boost system library (<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/">http://www.boost.org/</uri>). Building with the header-only version of Boost is no longer recommended.
80
81
82
          </simpara>
        </listitem>

83
84
85
        <listitem>
            <simpara>
	In order to store lease information in a MySQL database, Kea requires MySQL
Suzanne Goldlust's avatar
Suzanne Goldlust committed
86
    headers and libraries. This is an optional dependency in that Kea can be
87
88
89
    built without MySQL support.
            </simpara>
        </listitem>
90

91
92
        <listitem>
            <simpara>
93
	In order to store lease information in a PostgreSQL database, Kea requires PostgreSQL
Suzanne Goldlust's avatar
Suzanne Goldlust committed
94
    headers and libraries. This is an optional dependency in that Kea can be
95
    built without PostgreSQL support.
96
97
98
99
100
            </simpara>
        </listitem>

        <listitem>
            <simpara>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
101
	In order to store lease information in a Cassandra database (CQL), Kea
102
103
    requires Cassandra headers and libraries. This is an optional dependency
    in that Kea can be built without Cassandra support.
104
105
            </simpara>
        </listitem>
106
107
108

        <listitem>
          <simpara>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
109
110
111
    Integration with RADIUS is provided in Kea via the hooks
    library available to our paid support customers. Use of this library requires
    the FreeRadius-client library to be present on the system where Kea is running.
112
113
114
115
116
117
    This is an optional dependency in that Kea can be built without RADIUS support.
          </simpara>
        </listitem>

        <listitem>
          <simpara>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
118
    As of the 1.5.0 release, Kea provides a NETCONF interface with the kea-netconf agent.
119
    This Kea module is built optionally and requires Sysrepo software when used.
Suzanne Goldlust's avatar
Suzanne Goldlust committed
120
    Building Kea with NETCONF support requires many dependencies to be installed,
Suzanne Goldlust's avatar
Suzanne Goldlust committed
121
    which are described in more detail in <xref linkend="netconf-install"/>.
122
123
          </simpara>
        </listitem>
124
      </itemizedlist>
125
126
    </section>

127
    <section xml:id="kea_software">
128
      <title>Kea Software</title>
129
      <para>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
130
        Kea is modular. Part of this modularity is
131
132
        accomplished using multiple cooperating processes which, together,
        provide the server functionality.
133
        The following software is included with Kea:
134
135
136
137
138
139
140
141
      </para>

      <para>

        <itemizedlist>

          <listitem>
            <simpara>
142
              <command>keactrl</command>
143
144
              Tool to start, stop, reconfigure, and report status
              for the Kea servers.
145
146
147
148
149
            </simpara>
          </listitem>

          <listitem>
            <simpara>
150
              <command>kea-dhcp4</command>
151
              The DHCPv4 server process.
152
153
154
155
156
157
              This process responds to DHCPv4 queries from clients.
            </simpara>
          </listitem>

          <listitem>
            <simpara>
158
              <command>kea-dhcp6</command>
159
              The DHCPv6 server process.
160
161
162
163
164
165
              This process responds to DHCPv6 queries from clients.
            </simpara>
          </listitem>

          <listitem>
            <simpara>
166
              <command>kea-dhcp-ddns</command>
167
              The DHCP Dynamic DNS process.
168
              This process acts as an intermediary between the DHCP servers
169
              and DNS servers. It receives name update requests from the DHCP
Suzanne Goldlust's avatar
Suzanne Goldlust committed
170
              servers and sends DNS update messages to the DNS servers.
171
172
173
            </simpara>
          </listitem>

174
175
          <listitem>
            <simpara>
176
              <command>kea-admin</command>
177
              A useful tool for database backend maintenance (creating a new
Suzanne Goldlust's avatar
Suzanne Goldlust committed
178
              database, checking versions, upgrading, etc.)
179
180
181
            </simpara>
          </listitem>

182
183
          <listitem>
            <simpara>
184
              <command>kea-lfc</command>
185
              This process removes redundant information from the files used
Suzanne Goldlust's avatar
Suzanne Goldlust committed
186
              to provide persistent storage for the memfile database backend.
187
              While it can be run standalone, it is normally run as and when
188
              required by the Kea DHCP servers.
189
190
191
            </simpara>
          </listitem>

192
193
          <listitem>
            <simpara>
194
              <command>kea-ctrl-agent</command>
195
              Kea Control Agent (CA) is a daemon that exposes a RESTful control
196
197
              interface for managing Kea servers.
            </simpara>
198
199
200
201
          </listitem>

          <listitem>
            <simpara>
202
              <command>kea-netconf</command> -
203
204
205
              Kea netconf is an agent that provides a YANG/NETCONF interface
              for the Kea environment.
            </simpara>
206
207
          </listitem>

208
209
210
          <listitem>
            <simpara>
              <command>kea-shell</command>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
211
              This simple text client uses the REST interface to connect to the Kea
212
213
214
215
              Control Agent.
            </simpara>
          </listitem>

216
217
          <listitem>
            <simpara>
218
              <command>perfdhcp</command>
219
220
              A DHCP benchmarking tool which simulates multiple clients to
              test both DHCPv4 and DHCPv6 server performance.
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
            </simpara>
          </listitem>

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

    <para>
236
      Kea also provides C++ libraries and programmer interfaces for
Suzanne Goldlust's avatar
Suzanne Goldlust committed
237
      DHCP. These include detailed developer documentation and
238
      code examples.
239
240
241
242
<!-- TODO point to this -->
    </para>

  </chapter>