Commit c8de97c7 authored by Stephen Morris's avatar Stephen Morris
Browse files

[3418] Changes to installation instructions made as part of review.

parent 2a7a7dd9
......@@ -26,8 +26,8 @@
<section id="install-hierarchy">
<title>Install Hierarchy</title>
<para>
The following is the standard, common layout of the
complete Kea installation:
The following is the directory layout of the complete Kea installation
(all directories paths are relative to the installation directory):
<itemizedlist>
<listitem>
<simpara>
......@@ -109,25 +109,36 @@
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 source code.
libraries, to build Kea from the source code.
</simpara>
</note>
<para>
Building from source code requires the Boost
build-time headers
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>
To build Kea, also install the Botan (at least version
1.8) and the log4cplus (at least version 1.0.3)
Botan (at least version
1.8).</para>
</listitem>
<listitem>
<para>
log4cplus (at least version 1.0.3)
development include headers.
<!-- @todo: Add OpenSSL note here once #2406 is merged -->
</para>
</listitem>
<!--
TODO
......@@ -138,13 +149,24 @@ Debian and Ubuntu:
<!-- NOTE: _sqlite3 is only needed at test time; it is already listed
as a dependency earlier -->
<listitem>
<para>
Building Kea also requires a C++ compiler and
standard development headers, make, and pkg-config.
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 -->
</para>
</listitem>
</itemizedlist>
<para>
Visit the user-contributed wiki at <ulink
......@@ -155,7 +177,7 @@ as a dependency earlier -->
</section>
<section id="install">
<title>Installation from source</title>
<title>Installation from Source</title>
<para>
Kea is open source software written in C++ (some components of the
BIND 10 framework are written in Python).
......@@ -171,7 +193,7 @@ as a dependency earlier -->
<para>
Kea 0.8 is available as a part of BIND10 1.2 release, which is a final
release of BIND10 from ISC. This release can be downloaded from:
<ulink url="ftp://ftp.isc.org/isc/bind10/"/>. Upcoming Kea 0.9 and all
<ulink url="ftp://ftp.isc.org/isc/bind10/"/>. The upcoming Kea 0.9 and all
following releases will be shipped as a stand-alone tarball.
</para>
</section>
......@@ -186,15 +208,15 @@ as a dependency earlier -->
<note>
<para>
When using source code retrieved via Git, additional
software will be required: automake (v1.11 or newer),
libtoolize, and autoconf (2.59 or newer).
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 (and temporary experiments
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.
......@@ -203,15 +225,13 @@ as a dependency earlier -->
</para>
<para>
The code can be checked out from
<filename>git://git.kea.isc.org/kea</filename>;
for example:
<filename>git://git.kea.isc.org/kea</filename>:
<screen>$ <userinput>git clone git://git.kea.isc.org/kea</userinput></screen>
</para>
<para>
When checking out the code from
the code version control system, it doesn't include the
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>
......@@ -245,7 +265,7 @@ as a dependency earlier -->
<term>--prefix</term>
<listitem>
<simpara>Define the installation location (the
default is <filename>/usr/local/</filename>).
default is <filename>/usr/local</filename>).
</simpara>
</listitem>
</varlistentry>
......@@ -263,7 +283,7 @@ as a dependency earlier -->
<listitem>
<simpara>Define the path to Python 3.x if it is not in the
standard execution path. Python 3.x is mandatory for Kea 0.8,
but is no longer required for upcoming Kea 0.9.
but will not be required for the upcoming Kea 0.9.
</simpara>
</listitem>
</varlistentry>
......@@ -271,9 +291,11 @@ as a dependency earlier -->
<varlistentry>
<term>--with-gtest</term>
<listitem>
<simpara>Enable building the C++ Unit Tests using the
Google Tests framework. Optionally this can define the
path to the gtest header files and library.
<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>
......@@ -283,7 +305,7 @@ as a dependency earlier -->
<listitem>
<simpara>Disable the default use of the
<option>-Werror</option> compiler flag so that
compiler warnings aren't build failures.
compiler warnings do not result in build failures.
</simpara>
</listitem>
</varlistentry>
......@@ -301,9 +323,10 @@ as a dependency earlier -->
<!-- TODO: lcov -->
<para>
For example, the following configures it to find the Boost headers,
specifies that PostgreSQL support should be enabled, and sets the
installation location:
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 \
......@@ -322,8 +345,8 @@ as a dependency earlier -->
<section>
<title>Build</title>
<para>
After the configure step is complete, to build the executables
from the C++ code and prepare the Python scripts, run:
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>
......@@ -333,13 +356,13 @@ as a dependency earlier -->
<title>Install</title>
<para>
To install the Kea executables, support files,
and documentation, run:
and documentation, issue the command:
<screen>$ <userinput>make install</userinput></screen>
</para>
<para>
Please don't use any form of parallel or job server options
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.
performing this step: doing so may cause errors.
</para>
<note>
<para>The install step may require superuser privileges.</para>
......@@ -369,11 +392,12 @@ as a dependency earlier -->
</section>
<section id="dhcp-config-backend">
<title>Selecting configuration backend</title>
<para>Kea 0.9 introduces configuration backends that are switchable during
compilation phase. There is a new parameter for configure script:
--with-kea-config. It currently supports two values: BIND10 and
JSON. This is currently only supported by DHCPv6 component.</para>
<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: BIND10 and JSON. This is currently
only supported by DHCPv6 component.</para>
<variablelist>
......@@ -412,7 +436,7 @@ as a dependency earlier -->
<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 3 database backends: MySQL,
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 (which is implemented in pure C++)
is available. Support for a given database backend must be explicitly included when
......@@ -420,7 +444,7 @@ as a dependency earlier -->
and the creation of the lease database.
</para>
<section>
<title>Building with MySQL support</title>
<title>Building with MySQL Support</title>
<para>
Install MySQL according to the instructions for your system. The client development
libraries must be installed.
......@@ -438,7 +462,7 @@ as a dependency earlier -->
</para>
</section>
<section id="dhcp-mysql-database-create">
<title>Create MySQL Database and Kea User</title>
<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:
......@@ -456,12 +480,12 @@ mysql></screen>
... <replaceable>database-name</replaceable> is the name you have chosen for the database.
</para>
<para>
3. Create the database tables:
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-bind10</replaceable>/share/bind10/dhcpdb_create.mysql</userinput></screen>
</para>
<para>
4. Create the user under which BIND 10 will access the database (and give it a password), then grant it access to the database tables:
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>
......@@ -531,7 +555,7 @@ Bye<userinput/>
$</screen>
</para>
<para>
5. Create the database tables using the new user's credentials.
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:
......@@ -556,13 +580,13 @@ $
</screen>
</para>
<para>
If instead you encounter an error such as shown below:
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>
This indicates that the PostgreSQL configuration needs to be modified.
... 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
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment