4. Building and Installing OpenLDAP Software

This chapter details how to build and install the OpenLDAP Software package including slapd(8), the stand-alone LDAP daemon and slurpd(8), the stand-alone update replication daemon. Building and installing OpenLDAP requires several steps: installing prerequisite software, configuring OpenLDAP itself, making, and finally installing. The following sections describe this process in detail.

4.1. Obtaining and Extracting the Software

You can obtain OpenLDAP Software from the project's download page at http://www.openldap.org/software/download/ or directly from the project's FTP service at ftp://ftp.openldap.org/pub/OpenLDAP/.

The project makes available two series of packages for general use. The project makes releases as new features and bug fixes come available. Though the project takes steps to improve stablity of these releases, it is common for problems to arise only after release. The latest release which has demonstrated stability through general use.

Users of OpenLDAP Software can choose, depending on their desire for the latest features versus demonstrated stability, the most appropriate series to install.

After downloading OpenLDAP Software, you need to extract the distribution from the compressed archive file and change your working directory to the top directory of the distribution:

You'll have to replace VERSION with the version name of the release.

You should now review the COPYRIGHT, LICENSE, README and INSTALL documents provided with the distribution. The COPYRIGHT and LICENSE provide information on acceptable use, copying, and limitation of warranty of OpenLDAP software. The README and INSTALL documents provide detailed information on prerequisite software and installation procedures.

4.2. Prerequisite software

OpenLDAP Software relies upon a number of software packages distributed by third parties. Depending on the features you intend to use, you may have to download and install a number of additional software packages. This section details commonly needed third party software packages you might have to install. Note that some of these third party packages may depend on additional software packages. Install each package per installation instructions provided with it.

4.2.1. Transport Layer Security

OpenLDAP clients and servers require installation of OpenSSL TLS libraries to provide Transport Layer Security services. Though some operating systems may provide these libraries as part of the base system or as an optional software component, OpenSSL often requires separate installation.

OpenSSL is available from http://www.openssl.org/.

OpenLDAP will not be fully LDAPv3 compliant unless OpenLDAP's configure detects a usable OpenSSL installation.

4.2.2. Kerberos Authentication Services

OpenLDAP clients and servers support Kerberos-based authentication services. In particular, OpenLDAP supports SASL/GSSAPI authentication mechanism using either Heimdal or MIT Kerberos V packages. If you desire to use Kerberos-based SASL/GSSAPI authentication, you should install either Heimdal or MIT Kerberos V.

Heimdal Kerberos is available from http://www.pdc.kth.se/heimdal/. MIT Kerberos is available from http://web.mit.edu/kerberos/www/.

Use of strong authentication services, such as those provided by Kerberos, is highly recommended.

4.2.3. Simple Authentication and Security Layer

OpenLDAP clients and servers require installation of Cyrus's SASL libraries to provide Simple Authentication and Security Layer services. Though some operating systems may provide this library as part of the base system or as an optional software component, Cyrus SASL often requires separate installation.

Cyrus SASL is available from http://asg.web.cmu.edu/sasl/sasl-library.html. Cyrus SASL will make use of OpenSSL and Kerberos/GSSAPI libraries if preinstalled.

OpenLDAP will not be fully LDAPv3 compliant unless OpenLDAP's configure detects a usable Cyrus SASL installation.

4.2.4. Database Software

OpenLDAP's slapd(8) primary database backend, LDBM, requires a compatible database package for entry storage. LDBM is compatible with Sleepycat Software's BerkeleyDB (recommended) or the Free Software Foundation's GNU Database Manager (GDBM). If neither of these packages are available at configure time, you will not be able build slapd(8) with primary database backend.

Your operating system may provide one of these two packages in the base system or as an optional software component. You may need may need to obtain the software and install it yourself.

BerkeleyDB is available from Sleepycat Software's download page http://www.sleepycat.com/download.html. There are several versions available. At the time of this writing, the latest release, version 3.1, is recommended.

GDBM is available from FSF's download site ftp://ftp.gnu.org/pub/gnu/gdbm/. At the time of this writing, version 1.8 is the latest release.

4.2.5. Threads

OpenLDAP is designed to take advantage of threads. OpenLDAP supports POSIX pthreads, Mach CThreads, and a number of other varieties. configure will complain if it cannot find a suitable thread subsystem. If this occurs, please consult the Software|Installation|Platform Hints section of the OpenLDAP FAQ http://www.openldap.org/faq/.

4.2.6. TCP Wrappers

slapd(8) supports TCP wrappers (IP level access control filters) if preinstalled. Use of TCP wrappers or other IP-level access filters (such as those provided by an IP-level firewall) is recommended for servers containing non-public information.

4.3. Running configure

Now you should probably run the configure script with the --help option. This will give you a list of options that you can change when building OpenLDAP. Many of the features of OpenLDAP can be enabled or disabled using this method.

        ./configure --help

The configure script will also look at various environment variables for certain settings. These environment variables include:

Table 4.1: Environment Variables
Variable Description
CC Specify alternative C Compiler
CFLAGS Specify additional compiler flags
CPPFLAGS Specify C Preprocessor flags
LDFLAGS Specify linker flags
LIBS Specify additional libraries

Now run the configure script with any desired configuration options or environment variables.

        [[env] settings] ./configure [options]

As an example, let's assume that we want install OpenLDAP with LDBM backend and TCP wrapper support. By default, LDBM is enabled and TCP wrappers is not. So, we just need to specify --with-wrappers to include TCP wrapper support:

        ./configure --with-wrappers

However, this will fail to locate dependent software not installed in system directories. For example, if TCP Wrappers headers and libraries are installed in /usr/local/include and /usr/local/lib respectively, the configure script should be called as follows:

        env CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib" \
                ./configure --with-wrappers


Note: Some shells, such as those derived from the Bourne sh(1), do not require use of the env(1) command. In some cases, environmental variables have to be specified using alternative syntaxes.

The configure script will normally auto-detect appropriate settings. If you have problems at this stage, consult any platform specific hints and check your configure options, if any.

4.4. Building the Software

Once you have run the configure script the last line of output should be:

        Please "make depend" to build dependencies

If the last line of output does not match, configure has failed, and you will need to review its output to determine what went wrong. You should not proceed until configure completes successfully.

To build dependencies, run:

        make depend

Now build the software, this step will actually compile OpenLDAP.

        make

You should examine the output of this command carefully to make sure everything is built correctly. Note that this command builds the LDAP libraries and associated clients as well as slapd(8) and slurpd(8).

4.5. Testing the Software

Once the software has been properly configured and successfully made, you should run the test suite to verify the build.

        make test

Tests which apply to your configuration will run and they should pass. Some tests, such as the replication test, may be skipped if not supported by your configuration.

4.6. Installing the Software

One you have successfully tested the software, you are ready to install it. You will need to have write permission to the installation directories you specified when you ran configure. By default OpenLDAP is installed in /usr/local. If you changed this setting with the --prefix configure option, it will be installed in the location you provided.

Typically, the installation typically requires super-user priviledges. From the top level OpenLDAP source directory, type:

        su root -c 'make install'

You should examine the output of this command carefully to make sure everything is installed correctly. You will find the configuration files for slapd(8) in /usr/local/etc/openldap by default. See the The slapd Configuration File chapter for additional information.