kea/doc/guide/install.xml

<?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="installation">
    <title>Installation</title>

    <section id="packages">
      <title>Packages</title>

      <para>
        Some operating systems or software package vendors may provide
        ready-to-use, pre-built software packages for Kea.  Installing a
        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.
      </para>

      <para>
        FreeBSD ports, NetBSD pkgsrc, and Debian
        <emphasis>testing</emphasis> package collections provide all the
        prerequisite packages.
      </para>
    </section>

    <section id="install-hierarchy">
      <title>Installation Hierarchy</title>
      <para>
        The following is the directory layout of the complete Kea installation.
        (All directory paths are relative to the installation directory):
        <itemizedlist>
          <listitem>
          <simpara>
            <filename>bin/</filename> &mdash;
            utility programs.
          </simpara>
          </listitem>
          <listitem>
          <simpara>
            <filename>etc/kea/</filename> &mdash;
            configuration files.
          </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>include/</filename> &mdash;
              C++ development header files.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>lib/</filename> &mdash;
              libraries.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>sbin/</filename> &mdash;
              server software and commands used by the system administrator.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>share/kea/</filename> &mdash;
              configuration specifications and examples.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>share/doc/kea/</filename> &mdash;
              this guide, other supplementary documentation, and examples.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>share/man/</filename> &mdash;
              manual pages (online documentation).
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>var/kea/</filename> &mdash;
              server identification, lease databases, and log files.
            </simpara>
          </listitem>
        </itemizedlist>
      </para>
    </section>

    <section id="build-requirements">
      <title>Building Requirements</title>

        <para>
          In addition to the run-time requirements (listed in <xref
          linkend="required-software"/>), building Kea from source code requires
          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
            libraries, to build Kea from the source code.
          </simpara>
        </note>

        <para>
          Building from source code requires the following software installed
          on the system:</para>
          <itemizedlist>
            <listitem>
                <para>Boost build-time headers
          (<ulink url="http://www.boost.org/"/>).
          At least Boost version 1.41 is required.
          When header-only Boost error code is not available or wanted, the
          Boost system library is required too.
        </para>
        </listitem>

          <listitem>
        <para>
          Botan (at least version 1.8) or OpenSSL (at least version 1.0.1).
        </para>
          </listitem>

          <listitem>
          <para>
            log4cplus (at least version 1.0.3)
          development include headers.
        </para>
        </listitem>

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

        <listitem>
        <para>
          A C++ compiler and standard development headers.
          Kea 1.1.0 builds have been tested with GCC g++ 4.2.1,
          4.4.7, 4.6.3, 4.8.3, 4.8.4, 4.8.5, 5.4.0; Clang++ 3.4.1;
          and Apple Clang++ 703.0.31.
	  <!-- @todo update this list -->
        </para>
        </listitem>

        <listitem>
        <para>
          The development tools automake, libtool, pkg-config.
        </para>
        </listitem>

        <listitem>
        <para>
          The MySQL client and the client development libraries, when using
          the --with-dhcp-mysql configuration flag to build the Kea MySQL
          database backend. In this case an instance of the MySQL server
          running locally or on a machine reachable over a network
          is required. Note that
          running the unit tests requires a local MySQL server.
        </para>
        </listitem>

        <listitem>
        <para>
          The PostgreSQL client and the client development libraries, when
          using the --with-dhcp-pgsql configuration flag to build the Kea
          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.
        </para>
        </listitem>

        <listitem>
        <para>
          googletest (version 1.6 or later), when using the --with-gtest configuration
          option to build the unit tests.
        </para>
        </listitem>

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

        </itemizedlist>

        <para>
          Visit the user-contributed wiki at
          <ulink url="http://kea.isc.org/wiki/SystemSpecificNotes" />
          for system-specific installation tips.
        </para>

    </section>

    <section id="install">
      <title>Installation from Source</title>
      <para>
        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
        source code repository is accessible from Github (<ulink
        url="https://github.com/isc-projects/kea"/>). Kea may also be available
        in pre-compiled ready-to-use packages from operating system vendors.
      </para>

      <section>

        <title>Download Tar File</title>
        <para>
          The Kea release tarballs may be downloaded from:
          <ulink url="http://ftp.isc.org/isc/kea/"/> (using FTP or HTTP).
        </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>
            When building from source code retrieved via Git, additional
            software will be required:  automake (v1.11 or later),
            libtoolize, and autoconf (v2.59 or later).
            These may need to be installed.
          </para>
        </note>

        <para>
          The latest development code is available on Github (see
          <ulink url="https://github.com/isc-projects/kea"/>). The Kea source
          is public and development is done in the <quote>master</quote>
          branch.
        </para>
        <para>
          The code can be checked out from
          <filename>https://github.com/isc-projects/kea.git</filename>:

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

        <para>
          The code checked out from the git repository does not include the
          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>

        <para>
          Write access to the Kea repository is only granted to ISC staff. If you
          are a developer planning to contribute to Kea, please fork our Github
          repository and use the "pull request" mechanism to request integration of
          your code. Please consult
          <ulink url="https://help.github.com/articles/fork-a-repo/"/> for help on
          how to fork a Github repository.
          The <ulink url="http://git.kea.isc.org/~tester/kea/doxygen/">Kea 
          Developer's Guide</ulink> contains more information about the process, as
          well as describing the requirements for contributed code to be accepted by ISC.
        </para>

      </section>


      <section id="configure">
        <title>Configure Before the Build</title>
        <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
                default is <filename>/usr/local</filename>).
              </simpara>
            </listitem>
          </varlistentry>

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

          <varlistentry>
            <term>--with-botan-config</term>
            <listitem>
              <simpara>Specify the path to the botan-config
                script to build with Botan for cryptographic functions.
              </simpara>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--with-dhcp-mysql</term>
            <listitem>
              <simpara>
                Build Kea with code to allow it to store leases (and access
                host reservations) in a MySQL database.
              </simpara>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--with-dhcp-pgsql</term>
            <listitem>
              <simpara>
                Build Kea with code to allow it to store leases (and access
                host reservations) in a PostgreSQL database.
              </simpara>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--with-gtest-source</term>
            <listitem>
              <simpara>Enable the building of the C++ Unit Tests using the
                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
                from <ulink url="https://code.google.com/p/googletest"/>.)
              </simpara>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--with-log4cplus</term>
            <listitem>
              <simpara>Define the path to find the Log4cplus headers
                and libraries.
              </simpara>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--with-openssl</term>
            <listitem>
              <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.
              </simpara>
            </listitem>
          </varlistentry>

          </variablelist>
          <note>
            <para>
              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
              <xref linkend="dhcp-config-backend" />.
            </para>
          </note>
        </para>
  <!-- TODO: lcov -->

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

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

        <para>
          If you have some problems with building Kea using the header-only
          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):

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

        <para>
          If <command>configure</command> fails, it may be due to missing or old
          dependencies.
        </para>

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

      </section>

      <section>
        <title>Build</title>
        <para>
          After the configure step is complete, build the executables
          from the C++ code and prepare the Python scripts by running the command:
          <screen>$ <userinput>make</userinput></screen>
        </para>
      </section>

      <section>
        <title>Install</title>
        <para>
          To install the Kea executables, support files,
          and documentation, issue the command:
          <screen>$ <userinput>make install</userinput></screen>
        </para>
        <para>
          Do not use any form of parallel or job server options
          (such as GNU make's <command>-j</command> option) when
          performing this step: doing so may cause errors.
        </para>
        <note>
          <para>The install step may require superuser privileges.</para>
        </note>
        <para>
	  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>
        </para>
        <note>
          <para>
	    If you do not run <command>ldconfig</command> where it is
	    required, you may see errors like the following:
            <screen>
	      program: error while loading shared libraries: libkea-something.so.1:
	      cannot open shared object file: No such file or directory
	    </screen>
	  </para>
        </note>
      </section>

  <!-- @todo: tests -->

    </section>

    <section id="dhcp-config-backend">
      <title>Selecting the Configuration Backend</title>
      <para>Kea 0.9 introduced configuration backends that are
      switchable during the compilation phase. Only one backend, JSON,
      is currently supported.
      </para>

      <variablelist>

        <varlistentry>
          <term>JSON</term>
          <listitem>
	    <simpara>JSON is the new 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 will allow dynamic
	    on-line reconfiguration, but lacks remote capabilities
	    (i.e. no RESTful API).</simpara>
          </listitem>
        </varlistentry>
      </variablelist>

    </section>

    <section id="dhcp-install-configure">
      <title>DHCP Database Installation and Configuration</title>
      <para>
        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.
      </para>

      <note>
        <simpara>
          When unit tests are built with Kea (the --with-gtest configuration option is specified),
          the databases must be manually pre-configured for the unit tests to run.
          The details of this configuration can be found in the
          <ulink url="http://git.kea.isc.org/~tester/kea/doxygen">Kea Developer's
          Guide</ulink>.
        </simpara>
      </note>

      <section>
        <title>Building with MySQL Support</title>
        <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
          the following modification. To enable the MySQL database code, at the
          "configure" step (see <xref linkend="configure"/>), the --with-dhcp-mysql switch
          should be specified:
          <screen><userinput>./configure [other-options] --with-dhcp-mysql</userinput></screen>
	      If MySQL was not installed in the default location, the location of the MySQL
          configuration program "mysql_config" should be included with the switch, i.e.
          <screen><userinput>./configure [other-options] --with-dhcp-mysql=<replaceable>path-to-mysql_config</replaceable></userinput></screen>
        </para>
        <para>
          See <xref linkend="mysql-database-create"/> for details regarding
          MySQL database configuration.
        </para>
      </section>

      <section>
        <title>Building with PostgreSQL support</title>
        <para>
          Install PostgreSQL according to the instructions for your system.  The client development
          libraries must be installed. Client development libraries are often packaged as &quot;libpq&quot;.
        </para>
        <para>
          Build and install Kea as described in <xref linkend="installation"/>, with
          the following modification. To enable the PostgreSQL database code, at the
          "configure" step (see <xref linkend="configure"/>), the --with-dhcp-pgsql switch
          should be specified:
          <screen><userinput>./configure [other-options] --with-dhcp-pgsql</userinput></screen>
	      If PostgreSQL was not installed in the default location, the location of the PostgreSQL
          configuration program "pg_config" should be included with the switch, i.e.
          <screen><userinput>./configure [other-options] --with-dhcp-pgsql=<replaceable>path-to-pg_config</replaceable></userinput></screen>
        </para>
        <para>
          See <xref linkend="pgsql-database-create"/> for details regarding
          PostgreSQL database configuration.
        </para>
      </section>

      <section>
        <title>Building with CQL (Cassandra) support</title>
        <para>
          Install Cassandra according to the instructions for your system. The
          Cassandra project website contains useful pointers: <ulink
          url="http://cassandra.apache.org" />.
        </para>
        <para>
          Download and compile cpp-driver from DataStax. For details regarding
          dependencies for building cpp-driver, see the project homepage
          <ulink url="https://github.com/datastax/cpp-driver" />. In June
          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>
$ <userinput>cmake ..</userinput>
$ <userinput>make</userinput>
</screen>
        </para>
        <para>
          As of June 2016, cpp-driver does not include cql_config script
          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
          edit cql_config_defines.sh in the same directory and change the
          environment variable CPP_DRIVER_PATH to point to the directory,
          where cpp-driver sources are located. (If the cpp-driver sources already
          provide cql_config script please use that rather than the version
          from Kea sources.)
        </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>
   </section>

  </chapter>