install.xml 25.7 KB
Newer Older
1 2 3 4 5 6 7
<!--
 - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
 -
 - 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
 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
-->
8

9 10
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="installation">
11 12
    <title>Installation</title>

13
    <section xml:id="packages">
14 15 16 17
      <title>Packages</title>

      <para>
        Some operating systems or software package vendors may provide
18
        ready-to-use, pre-built software packages for Kea. Installing a
19 20 21
        pre-built package means you do not need to install the software
        required only to build Kea and do not need to <emphasis>make</emphasis>
        the software.
22 23 24 25
      </para>

    </section>

26
    <section xml:id="install-hierarchy">
27
      <title>Installation Hierarchy</title>
28
      <para>
29 30
        The following is the directory layout of the complete Kea installation.
        (All directory paths are relative to the installation directory):
31
        <itemizedlist>
32 33
          <listitem>
          <simpara>
34
            <filename>bin/</filename>
35 36 37
            utility programs.
          </simpara>
          </listitem>
38 39
          <listitem>
          <simpara>
40
            <filename>etc/kea/</filename>
41 42 43 44 45
            configuration files.
          </simpara>
          </listitem>
          <listitem>
            <simpara>
46
              <filename>include/</filename>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
47
              C++ development header files.
48 49 50 51
            </simpara>
          </listitem>
          <listitem>
            <simpara>
52
              <filename>lib/</filename>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
53
              libraries.
54 55
            </simpara>
          </listitem>
56 57 58 59 60 61
          <listitem>
            <simpara>
              <filename>lib/hooks</filename>
              additional hooks libraries.
            </simpara>
          </listitem>
62 63
          <listitem>
            <simpara>
64
              <filename>sbin/</filename>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
65
              server software and commands used by the system administrator.
66 67 68 69
            </simpara>
          </listitem>
          <listitem>
            <simpara>
70
              <filename>share/kea/</filename>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
71
              configuration specifications and examples.
72 73 74 75
            </simpara>
          </listitem>
          <listitem>
            <simpara>
76
              <filename>share/doc/kea/</filename>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
77
              this guide, other supplementary documentation, and examples.
78 79 80 81
            </simpara>
          </listitem>
          <listitem>
            <simpara>
82
              <filename>share/man/</filename>
83 84 85 86 87
              manual pages (online documentation).
            </simpara>
          </listitem>
          <listitem>
            <simpara>
88
              <filename>var/kea/</filename>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
89
              server identification, lease databases, and log files.
90 91 92 93 94 95
            </simpara>
          </listitem>
        </itemizedlist>
      </para>
    </section>

96
    <section xml:id="build-requirements">
97 98 99
      <title>Building Requirements</title>

        <para>
100
          In addition to the run-time requirements (listed in <xref linkend="required-software"/>), building Kea from source code requires
101 102 103 104 105 106 107 108
          various development include headers and program development tools.
        </para>

        <note>
          <simpara>
            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
109
            libraries, to build Kea from the source code.
110 111 112 113
          </simpara>
        </note>

        <para>
114 115 116 117
          Building from source code requires the following software installed
          on the system:</para>
          <itemizedlist>
            <listitem>
118
                <para>Boost C++ Libraries
119
          (<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/">http://www.boost.org/</uri>).
120 121 122
          The oldest Boost version used for testing is 1.57 (it may work with
          older versions). Boost system library is required.  Building boost
          header only is no longer recommended.
123
        </para>
124
        </listitem>
125

126
          <listitem>
127
        <para>
Francis Dupont's avatar
Francis Dupont committed
128 129 130
          Botan (at least version 1.9) or OpenSSL (at least version 1.0.1).
          Note that Botan version 2 or later and OpenSSL version 1.0.2 or
          1.1.0 or later are strongly recommended.
131
        </para>
132 133 134 135 136
          </listitem>

          <listitem>
          <para>
            log4cplus (at least version 1.0.3)
137 138
          development include headers.
        </para>
139
        </listitem>
140 141 142 143 144 145 146

<!--
TODO
Debian and Ubuntu:
 libgmp3-dev and libbz2-dev required for botan too
-->

147
        <listitem>
148
        <para>
149 150 151 152
          A C++ compiler (with C++11 support) and standard development
          headers. Kea builds have been tested with GCC g++ 4.7.2 4.7.3
          4.8.2 4.8.4 4.8.5 4.9.3 4.9.4 5.3.1 5.4.0 6.3.0 6.3.1
          clang-800.0.38 clang-802.0.42 clang-900.0.37
153
        </para>
154 155 156 157
        </listitem>

        <listitem>
        <para>
158
          The development tools automake, libtool, pkg-config.
159 160 161
        </para>
        </listitem>

162 163
        <listitem>
        <para>
164
          The MySQL client and the client development libraries, when using
165
          the --with-mysql configuration flag to build the Kea MySQL
166
          database backend. In this case an instance of the MySQL server
167 168
          running locally or on a machine reachable over a network
          is required. Note that
169
          running the unit tests requires a local MySQL server.
170 171 172 173 174
        </para>
        </listitem>

        <listitem>
        <para>
175
          The PostgreSQL client and the client development libraries, when
176
          using the --with-pgsql configuration flag to build the Kea
177 178 179 180 181
          PostgreSQL database backend. In this case an instance of the
          PostgreSQL server running locally or on some other machine,
          reachable over the network from the machine running Kea, is
          required. Note that running the unit tests requires a local
          PostgreSQL server.
182 183 184
        </para>
        </listitem>

185 186 187 188 189 190 191 192 193 194 195
        <listitem>
        <para>
          Cpp-driver from DataStax is needed when using the --with-cql
	  configuration flag to build Kea with Cassandra database backend.
          In this case an instance of the Cassandra server running locally
          or on some other machine, reachable over the network from the
          machine running Kea, is required. Note that running the unit
          tests requires a local Cassandra server.
	</para>
        </listitem>

196 197
        <listitem>
        <para>
198
          googletest (version 1.8 or later), when using the --with-gtest configuration
199
          option to build the unit tests.
200 201 202 203 204
        </para>
        </listitem>

        <listitem>
          <para>
205 206 207
            The documentation generation tools elinks, docbook-xsl, libxslt and Doxygen,
            if using the --enable-generate-docs configuration option
            to create the documentation.
208 209 210
          </para>
        </listitem>

211
        </itemizedlist>
212 213

        <para>
214
          Visit the user-contributed wiki at
215
          <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://oldkea.isc.org/wiki/Install">http://oldkea.isc.org/wiki/Install</uri>
216 217 218 219
          for system-specific installation tips.
        </para>
    </section>

220
    <section xml:id="install">
221
      <title>Installation from Source</title>
222
      <para>
223 224
        Kea is open source software written in C++.  It is freely available in
        source code form from ISC as a downloadable tar file.  A copy of the Kea
225
        source code repository is accessible from Github (<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/isc-projects/kea">https://github.com/isc-projects/kea</uri>). Kea may also be available
226
        in pre-compiled ready-to-use packages from operating system vendors.
227 228 229 230 231 232
      </para>

      <section>

        <title>Download Tar File</title>
        <para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
233
          The Kea release tarballs may be downloaded from:
234
          <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://ftp.isc.org/isc/kea/">http://ftp.isc.org/isc/kea/</uri> (using FTP or HTTP).
235 236 237 238 239 240 241 242 243 244 245 246 247
        </para>
      </section>

      <section>
        <title>Retrieve from Git</title>
        <para>
          Downloading this "bleeding edge" code is recommended only for
          developers or advanced users.  Using development code in a production
          environment is not recommended.
        </para>

        <note>
          <para>
248 249
            When building from source code retrieved via Git, additional
            software will be required:  automake (v1.11 or later),
250
            libtoolize, and autoconf (v2.69 or later).
251 252 253 254 255
            These may need to be installed.
          </para>
        </note>

        <para>
256
          The latest development code is available on Github (see
257
          <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/isc-projects/kea">https://github.com/isc-projects/kea</uri>). The Kea source
258
          is public and development is done in the <quote>master</quote>
259 260 261 262
          branch.
        </para>
        <para>
          The code can be checked out from
263
          <filename>https://github.com/isc-projects/kea.git</filename>:
264

265
        <screen>$ <userinput>git clone https://github.com/isc-projects/kea.git</userinput></screen>
266 267 268
        </para>

        <para>
269
          The code checked out from the git repository does not include the
270 271 272 273 274 275 276 277 278 279 280 281
          generated configure script, Makefile.in files, nor their
          related build files.
          They can be created by running <command>autoreconf</command>
          with the <option>--install</option> switch.
          This will run <command>autoconf</command>,
          <command>aclocal</command>,
          <command>libtoolize</command>,
          <command>autoheader</command>,
          <command>automake</command>,
          and related commands.
        </para>

282
        <para>
283
          Write access to the Kea repository is only granted to ISC staff. If you
284 285
          are a developer planning to contribute to Kea, please fork our Github
          repository and use the "pull request" mechanism to request integration of
286
          your code. Please consult
287
          <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://help.github.com/articles/fork-a-repo/">https://help.github.com/articles/fork-a-repo/</uri> for help on
288
          how to fork a Github repository.
289
          The <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://oldkea.isc.org/docs/devel/">Kea
290
          Developer's Guide</link> contains more information about the process, as
291
          well as describing the requirements for contributed code to be accepted by ISC.
292 293
        </para>

294 295 296
      </section>


297
      <section xml:id="configure">
298
        <title>Configure Before the Build</title>
299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314
        <para>
          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>
        </para>
        <para>
          Run <command>./configure</command> with the <option>--help</option>
          switch to view the different options. Some commonly-used options are:

          <variablelist>

          <varlistentry>
            <term>--prefix</term>
            <listitem>
              <simpara>Define the installation location (the
315
                default is <filename>/usr/local</filename>).
316 317 318 319 320 321 322 323 324 325 326 327
              </simpara>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--with-boost-include</term>
            <listitem>
              <simpara>Define the path to find the Boost headers.
              </simpara>
            </listitem>
          </varlistentry>

328
          <varlistentry>
329
            <term>--with-botan-config</term>
330
            <listitem>
331 332
              <simpara>Specify the path to the botan-config
                script to build with Botan for cryptographic functions.
333 334 335 336
              </simpara>
            </listitem>
          </varlistentry>

337
          <varlistentry>
338
            <term>--with-mysql</term>
339
            <listitem>
340
              <simpara>
341 342
                Build Kea with code to allow it to store leases and
                host reservations in a MySQL database.
343 344 345 346
              </simpara>
            </listitem>
          </varlistentry>

347
          <varlistentry>
348
            <term>--with-pgsql</term>
349
            <listitem>
350
              <simpara>
351 352
                Build Kea with code to allow it to store leases and
                host reservations in a PostgreSQL database.
353 354 355 356 357
              </simpara>
            </listitem>
          </varlistentry>

          <varlistentry>
358 359 360 361 362 363 364 365 366 367 368
            <term>--with-cql</term>
            <listitem>
              <simpara>
                Build Kea with code to allow it to store leases and
                host reservations in a Cassandra (CQL) database.
              </simpara>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--with-gtest, --with-gtest-source</term>
369
            <listitem>
370
              <simpara>Enable the building of the C++ Unit Tests using the
371 372 373
                Google Test framework. This option specifies the path to the
                gtest source. (If the framework
                is not installed on your system, it can be downloaded
374
                from <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/google/googletest">https://github.com/google/googletest</uri>.)
375 376 377 378 379 380 381 382 383 384 385 386 387
                from <ulink url="https://github.com/google/googletest"/>.)
              </simpara>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--with-benchmark, --with-benchmark-source</term>
            <listitem>
              <simpara>Enable the building of the database backend
              benchmarks using the Google Benchmark framework. This
              option specifies the path to the gtest source. (If the
              framework is not installed on your system, it can be downloaded
              from <ulink url="https://github.com/google/benchmark"/>.)
388 389 390 391
              </simpara>
            </listitem>
          </varlistentry>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
392 393 394 395 396 397 398 399 400
          <varlistentry>
            <term>--with-log4cplus</term>
            <listitem>
              <simpara>Define the path to find the Log4cplus headers
                and libraries.
              </simpara>
            </listitem>
          </varlistentry>

401 402 403
          <varlistentry>
            <term>--with-openssl</term>
            <listitem>
404 405 406 407
              <simpara>Replace Botan by the OpenSSL the cryptographic library.
                By default <command>configure</command> searches for a valid
                Botan installation:
                if one is not found, it searches for OpenSSL.
408 409 410 411 412 413 414
              </simpara>
            </listitem>
          </varlistentry>

          </variablelist>
          <note>
            <para>
415 416 417
              For instructions concerning the installation and configuration
              of database backends for Kea, see <xref linkend="dhcp-install-configure"/>.
              For information concerning the configuration backends, see
418
              <xref linkend="dhcp-config-backend"/>.
419 420 421 422 423 424
            </para>
          </note>
        </para>
  <!-- TODO: lcov -->

        <para>
425 426 427 428
          For example, the following command configures Kea to find the
          Boost headers in /usr/pkg/include, specifies that PostgreSQL
          support should be enabled, and sets the installation location
          to /opt/kea:
429 430 431

          <screen>$ <userinput>./configure \
      --with-boost-include=/usr/pkg/include \
432
      --with-pgsql=/usr/local/bin/pg_config \
433 434 435
      --prefix=/opt/kea</userinput></screen>
        </para>

436
        <para>
437
          If you have some problems with building Kea using the header-only
438 439
          Boost code or you'd like to use the Boost system library
          (assumed for the sake of this example to be located in /usr/pkg/lib):
440 441 442 443 444 445

          <screen>$ <userinput>./configure \
      --with-boost-libs=-lboost_system \
      --with-boost-lib-dir=/usr/pkg/lib</userinput></screen>
        </para>

446
        <para>
447
          If <command>configure</command> fails, it may be due to missing or old
448 449 450
          dependencies.
        </para>

451
        <para>
452 453 454 455
          If <command>configure</command> succeeds, it displays a report
          with the parameters used to build the code. This report is saved into
          the file <filename>config.report</filename> and is also embedded into
          the executable binaries, e.g., <userinput>kea-dhcp4</userinput>.
456
        </para>
457 458 459 460 461 462

      </section>

      <section>
        <title>Build</title>
        <para>
463 464
          After the configure step is complete, build the executables
          from the C++ code and prepare the Python scripts by running the command:
465 466 467 468 469 470 471 472
          <screen>$ <userinput>make</userinput></screen>
        </para>
      </section>

      <section>
        <title>Install</title>
        <para>
          To install the Kea executables, support files,
473
          and documentation, issue the command:
474 475 476
          <screen>$ <userinput>make install</userinput></screen>
        </para>
        <para>
477
          Do not use any form of parallel or job server options
478
          (such as GNU make's <command>-j</command> option) when
479
          performing this step: doing so may cause errors.
480 481 482 483 484
        </para>
        <note>
          <para>The install step may require superuser privileges.</para>
        </note>
        <para>
485 486 487 488 489 490
          If required, run <command>ldconfig</command> as root with
          <filename>/usr/local/lib</filename> (or with <replaceable>prefix</replaceable>/lib if
          configured with --prefix) in
          <filename>/etc/ld.so.conf</filename> (or the relevant linker
          cache configuration file for your OS):
          <screen>$ <userinput>ldconfig</userinput></screen>
491 492 493
        </para>
        <note>
          <para>
494 495
            If you do not run <command>ldconfig</command> where it is
            required, you may see errors like the following:
496
            <screen>
497 498 499 500
              program: error while loading shared libraries: libkea-something.so.1:
              cannot open shared object file: No such file or directory
            </screen>
          </para>
501 502 503 504 505 506 507
        </note>
      </section>

  <!-- @todo: tests -->

    </section>

508
    <section xml:id="dhcp-config-backend">
509
      <title>Selecting the Configuration Backend</title>
510
      <para>Kea 0.9 introduced configuration backends that are
511 512
      switchable during the compilation phase. Only one backend, JSON,
      is currently supported.
513
      </para>
514 515 516 517 518 519

      <variablelist>

        <varlistentry>
          <term>JSON</term>
          <listitem>
520 521 522 523
            <simpara>JSON is the default configuration backend
            that allows Kea to read JSON configuration files from
            disk. It does not require any framework and thus is
            considered more lightweight. It allows dynamic on-line
524
            reconfiguration using Kea API.</simpara>
525 526 527 528 529 530
          </listitem>
        </varlistentry>
      </variablelist>

    </section>

531
    <section xml:id="dhcp-install-configure">
532 533
      <title>DHCP Database Installation and Configuration</title>
      <para>
534 535 536 537 538 539 540 541 542
        Kea stores its leases in a lease database.  The software has been
        written in a way that makes it possible to choose which database product
        should be used to store the lease information.  At present, Kea supports
        four database backends: MySQL, PostgreSQL, Cassandra and Memfile. To
        limit external dependencies, MySQL, PostgreSQL and Cassandra support are
        disabled by default and only Memfile is available. Support for the
        optional external database backend must be explicitly included when Kea
        is built.  This section covers the building of Kea with one of the
        optional backends and the creation of the lease database.
543
      </para>
544 545 546

      <note>
        <simpara>
547
          When unit tests are built with Kea (the --with-gtest configuration option is specified),
548 549
          the databases must be manually pre-configured for the unit tests to run.
          The details of this configuration can be found in the
550 551
          <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://git.kea.isc.org/~tester/kea/doxygen">Kea Developer's
          Guide</link>.
552 553 554
        </simpara>
      </note>

555
      <section>
556
        <title>Building with MySQL Support</title>
557 558 559 560 561 562
        <para>
          Install MySQL according to the instructions for your system.  The client development
          libraries must be installed.
        </para>
        <para>
          Build and install Kea as described in <xref linkend="installation"/>, with
Jeremy C. Reed's avatar
Jeremy C. Reed committed
563
          the following modification. To enable the MySQL database code, at the
564
          "configure" step (see <xref linkend="configure"/>), the --with-mysql switch
565
          should be specified:
566
          <screen><userinput>./configure [other-options] --with-mysql</userinput></screen>
567
              If MySQL was not installed in the default location, the location of the MySQL
568
          configuration program "mysql_config" should be included with the switch, i.e.
569
          <screen><userinput>./configure [other-options] --with-mysql=<replaceable>path-to-mysql_config</replaceable></userinput></screen>
570 571
        </para>
        <para>
572 573
          See <xref linkend="mysql-database-create"/> for details regarding
          MySQL database configuration.
574
        </para>
575
      </section>
576 577 578 579 580

      <section>
        <title>Building with PostgreSQL support</title>
        <para>
          Install PostgreSQL according to the instructions for your system.  The client development
581
          libraries must be installed. Client development libraries are often packaged as "libpq".
582 583 584
        </para>
        <para>
          Build and install Kea as described in <xref linkend="installation"/>, with
Jeremy C. Reed's avatar
Jeremy C. Reed committed
585
          the following modification. To enable the PostgreSQL database code, at the
586
          "configure" step (see <xref linkend="configure"/>), the --with-pgsql switch
587
          should be specified:
588
          <screen><userinput>./configure [other-options] --with-pgsql</userinput></screen>
589
              If PostgreSQL was not installed in the default location, the location of the PostgreSQL
590
          configuration program "pg_config" should be included with the switch, i.e.
591
          <screen><userinput>./configure [other-options] --with-pgsql=<replaceable>path-to-pg_config</replaceable></userinput></screen>
592 593
        </para>
        <para>
594
          See <xref linkend="pgsql-database-create"/> for details regarding
595
          PostgreSQL database configuration.
596 597
        </para>
      </section>
598 599 600 601 602

      <section>
        <title>Building with CQL (Cassandra) support</title>
        <para>
          Install Cassandra according to the instructions for your system. The
603
          Cassandra project website contains useful pointers: <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://cassandra.apache.org">http://cassandra.apache.org</uri>.
604
        </para>
Francis Dupont's avatar
Francis Dupont committed
605 606
        <para>
          If you have a cpp-driver package available as binary or as source
607
          simply install or build and install the package. Then build
Francis Dupont's avatar
Francis Dupont committed
608 609 610 611 612
          and install Kea as described in <xref linkend="installation"/>:
          To enable the Cassandra (CQL) database code, at the "configure"
          step (see <xref linkend="configure"/>), do:
          <screen><userinput>./configure [other-options] --with-cql=<replaceable>path-to-pkg-config</replaceable></userinput></screen>
          Note if <command>pkg-config</command> is at its standard location
613 614 615
          (and thus in the shell path) you do not need to supply its path.
          If it does not work (e.g. no pkg-config, package not available in
          pkg-config with the cassandra name), you can still use
Francis Dupont's avatar
Francis Dupont committed
616 617
          the <command>cql_config</command> script in tools/ as describe below.
        </para>
618 619 620
        <para>
          Download and compile cpp-driver from DataStax. For details regarding
          dependencies for building cpp-driver, see the project homepage
621
          <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/datastax/cpp-driver">https://github.com/datastax/cpp-driver</uri>. In June
622 623 624 625 626
          2016, the following commands were used:
          <screen>
$ <userinput>git clone https://github.com/datastax/cpp-driver</userinput>
$ <userinput>cd cpp-driver</userinput>
$ <userinput>mkdir build</userinput>
627
$ <userinput>cd build</userinput>
628 629 630 631 632 633
$ <userinput>cmake ..</userinput>
$ <userinput>make</userinput>
</screen>
        </para>
        <para>
          As of June 2016, cpp-driver does not include cql_config script
634 635 636 637 638 639 640 641
          yet. Work is in progress to contribute such a script to the cpp-driver
          project but, until that is complete, intermediate steps that need to
          be conducted. A cql_config script is present in the tools/ directory
          of the Kea sources. Before using it, please create a
          cql_config_defines.sh in the same directory (there is an example in
          cql_config_define.sh.sample available, you may copy it over to
          cql_config_defines.sh and edit path specified in it) and change the
          environment variable CPP_DRIVER_PATH to point to the directory, where
Tomek Mrugalski's avatar
Tomek Mrugalski committed
642
          cpp-driver sources are located.
643 644 645 646 647 648 649 650
        </para>
        <para>
          Build and install Kea as described in <xref linkend="installation"/>, with
          the following modification. To enable the Cassandra (CQL) database code, at the
          "configure" step (see <xref linkend="configure"/>), do:
          <screen><userinput>./configure [other-options] --with-cql=<replaceable>path-to-cql_config</replaceable></userinput></screen>
        </para>
      </section>
651 652 653
   </section>

  </chapter>