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 build-only
        prerequisites 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>Install Hierarchy</title>
      <para>
        The following is the directory layout of the complete Kea installation
        (all directories paths are relative to the installation directory):
        <itemizedlist>
          <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.35 is required.
  <!-- TODO: we don't check for this version -->
  <!-- NOTE: jreed has tested with 1.34, 1.38, and 1.41. -->
        </para>
        </listitem>

            <listitem>
        <para>
          Botan (at least version 1.8) or OpenSSL.</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 builds have been tested with GCC g++ 3.4.3, 4.1.2,
          4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10.
	  <!-- @todo update this list -->
        </para>
        </listitem>

        <listitem>
        <para>
          The development tools "make" and "pkg-config".
	  <!-- @todo update this list, pkg-config shouldn't be required -->
        </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 or via Kea Git code revision control
        service. (It 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 (2.59 or later).
            These may need to be installed.
          </para>
        </note>

        <para>
          The latest development code (together with temporary experiments
          and un-reviewed code) is available via the Kea code revision
          control system. This is powered by Git and all the Kea
          development is public.
          The leading development is done in the <quote>master</quote>
          branch.
        </para>
        <para>
          The code can be checked out from
          <filename>git://git.kea.isc.org/kea</filename>:

        <screen>$ <userinput>git clone git://git.kea.isc.org/kea</userinput></screen>
        </para>

        <para>
          The code checked out from the git repository doesn't 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>

      </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>To specific the path to the botan-config
                script to build with Botan for the crypto code.
              </simpara>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--with-gtest</term>
            <listitem>
              <simpara>Enable the building of the C++ Unit Tests using the
                Google Test framework. Optionally this can define the
                path to the gtest header files and library. (If the framework
                is not already 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 OpenSSL for the crypto library.
                The default is to try to find a working Botan then
                OpenSSL only if Botan is not found.
              </simpara>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--without-werror</term>
            <listitem>
              <simpara>Disable the default use of the
		<option>-Werror</option> compiler flag so that
		compiler warnings do not result in build failures.
              </simpara>
            </listitem>
          </varlistentry>

          </variablelist>
          <note>
            <para>
              For additional instructions concerning the building and installation of
              Kea for various databases, see <xref linkend="dhcp-install-configure"/>.
              For additional instructions concerning 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 the configure fails, it may be due to missing or old
          dependencies.
        </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 ${prefix}/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 introduces configuration backends that are
      switchable during compilation phase. The backend is chosen using
      the --with-kea-config switch when running the configure script. It
      currently supports two values: BUNDY and JSON. JSON is the default.
      </para>

      <variablelist>

        <varlistentry>
          <term>BUNDY</term>
          <listitem>
            <simpara>BUNDY means
            that Kea is linked with the Bundy configuration backend that
            connects to the Bundy framework and in general works exactly the
	    same as Kea 0.8 and earlier BIND10 versions. The benefits
	    of that backend are uniform integration with the Bundy
	    framework, easy on-line reconfiguration using bindctl,
	    available RESTful API. On the other hand, it requires
	    the whole heavy Bundy framework that requires Python3
	    to be present. That backend is likely to go away with
	    the release of Kea 1.0.</simpara>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>JSON</term>
          <listitem>
	    <simpara>JSON is a new default configuration backend
	    that causes Kea to read JSON configuration file from
	    disk. It does not require any framework and thus is
	    considered more lightweight. It will allow dynamic
	    on-line reconfiguration, but will lack 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 three database backends: MySQL,
        PostgreSQL and Memfile. To limit external dependencies, both MySQL and PostgreSQL
        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 MySQL and/or PostgreSQL
        and the creation of the lease database.
      </para>
      <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"/>), do:
          <screen><userinput>./configure [other-options] --with-dhcp-mysql</userinput></screen>
	  Or specify the location of the MySQL configuration program
	  "mysql_config" if MySQL was not installed in the default location:
          <screen><userinput>./configure [other-options] --with-dhcp-mysql=<replaceable>path-to-mysql_config</replaceable></userinput></screen>
        </para>
      </section>
      <section id="dhcp-mysql-database-create">
        <title>Create the MySQL Database and the Kea User</title>
        <para>
          The next task is to create both the lease database and the user under which the servers will
          access it. A number of steps are required:
        </para>
        <para>
          1. Log into MySQL as "root":
          <screen>$ <userinput>mysql -u root -p</userinput>
Enter password:<userinput/>
   :<userinput/>
mysql></screen>
        </para>
        <para>
          2. Create the database:
          <screen>mysql> <userinput>CREATE DATABASE <replaceable>database-name</replaceable>;</userinput></screen>
	  (<replaceable>database-name</replaceable> is the name you
	  have chosen for the database.)
        </para>
         <para>
          3. Create the database tables by running the dhcpdb_create.mysql script supplied as part of Kea:
          <screen>mysql> <userinput>CONNECT <replaceable>database-name</replaceable>;</userinput>
mysql> <userinput>SOURCE <replaceable>path-to-kea</replaceable>/share/kea/dhcpdb_create.mysql</userinput></screen>
        </para>
         <para>
          4. Create the user under which Kea will access the database (and give it a password), then grant it access to the database tables:
          <screen>mysql> <userinput>CREATE USER '<replaceable>user-name</replaceable>'@'localhost' IDENTIFIED BY '<replaceable>password</replaceable>';</userinput>
mysql> <userinput>GRANT ALL ON <replaceable>database-name</replaceable>.* TO '<replaceable>user-name</replaceable>'@'localhost';</userinput></screen>
        </para>
        <para>
          5. Exit MySQL:
          <screen>mysql> <userinput>quit</userinput>
Bye<userinput/>
$</screen>
       </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"/>), do:
          <screen><userinput>./configure [other-options] --with-dhcp-pgsql</userinput></screen>
	  Or specify the location of the PostgreSQL configuration
	  program "pg_config" if PostgreSQL was not installed in
	  the default location:
          <screen><userinput>./configure [other-options] --with-dhcp-pgsql=<replaceable>path-to-pg_config</replaceable></userinput></screen>
        </para>
      </section>
      <section id="dhcp-pgsql-database-create">
        <title>Create PostgreSQL Database and Kea User</title>
        <para>
          The next task is to create both the lease database and the user under which the servers will
          access it. A number of steps are required:
        </para>
        <para>
          1. Log into PostgreSQL as "root":
          <screen>$ <userinput>sudo -u postgres psql postgres</userinput>
Enter password:<userinput/>
   :<userinput/>
postgres=#</screen>
        </para>
        <para>
          2. Create the database:
<screen>
postgres=#<userinput> CREATE DATABASE <replaceable>database-name</replaceable>;</userinput>
CREATE DATABASE
postgres=#
</screen>
	  (<replaceable>database-name</replaceable> is the name you
	  have chosen for the database.)
        </para>
         <para>
          3. Create the user under which Kea will access the database (and give it a password), then grant it access to the database:
<screen>postgres=#<userinput> CREATE USER <replaceable>user-name</replaceable> WITH PASSWORD '<replaceable>password</replaceable>';</userinput>
CREATE ROLE
postgres=#
postgres=#<userinput> GRANT ALL PRIVILEGES ON DATABASE <replaceable>database-name</replaceable> TO <replaceable>user-name</replaceable>;</userinput>
GRANT
postgres=#
</screen>
        </para>
         <para>
          4. Exit PostgreSQL:
          <screen>postgres=# <userinput>\q</userinput>
Bye<userinput/>
$</screen>
       </para>
       <para>
        5. Create the database tables using the new user's credentials and the dhcpdb_create.pgsql script supplied with Kea.
        After entering the following command, you will be prompted for the new
        user's password. When the command completes you will be returned to
        the shell prompt. You should see output similar to following:
<screen>$ <userinput>psql -d <replaceable>database-name</replaceable> -U <replaceable>user-name</replaceable> -f <replaceable>path-to-kea</replaceable>/share/kea/dhcpdb_create.pgsql</userinput>
Password for user <replaceable>user-name</replaceable>:
CREATE TABLE
CREATE INDEX
CREATE INDEX
CREATE TABLE
CREATE INDEX
CREATE TABLE
START TRANSACTION
INSERT 0 1
INSERT 0 1
INSERT 0 1
COMMIT
CREATE TABLE
START TRANSACTION
INSERT 0 1
COMMIT
$
</screen>
  </para>
  <para>
  If instead you encounter an error like:
  </para>
<screen>
psql: FATAL:  no pg_hba.conf entry for host "[local]", user "<replaceable>user-name</replaceable>", database "<replaceable>database-name</replaceable>", SSL off
</screen>
  <para>
  ... you will need to alter the PostgreSQL configuration.
  Kea uses password authentication when connecting to the database and must
  have the appropriate entries added to PostgreSQL's pg_hba.conf file.  This
  file is normally located in the primary data directory for your PostgreSQL
  server. The precise path may vary but the default location for PostgreSQL 9.3
  on Centos 6.5 is:
  <filename>/var/lib/pgsql/9.3/data/pg_hba.conf</filename>.
  Assuming Kea is running on the same host as PostgreSQL, adding lines similar
  to following should be sufficient to provide password-authenticated access to
  Kea's database:
  </para>
<screen>
local   <replaceable>database-name</replaceable>    <replaceable>user-name</replaceable>                                 password
host    <replaceable>database-name</replaceable>    <replaceable>user-name</replaceable>          127.0.0.1/32           password
host    <replaceable>database-name</replaceable>    <replaceable>user-name</replaceable>          ::1/128                password
</screen>
  <para>
  Please consult your PostgreSQL user manual before making these changes as they
  may expose your other databases that you run on the same system.
  </para>
      </section>
   </section>

  </chapter>