[openldap] / doc / guide / admin / install.sdf

# $OpenLDAP$
# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Building and Installing OpenLDAP Software

This chapter details how to build and install the {{ORG: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.

In case you haven't already obtained OpenLDAP it is available at
the following location:
{{URL: ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz}}.

The {{ORG[expand]OLP}} also maintains an extensive site
({{URL:http://www.OpenLDAP.org/}}) on the World Wide Web.  The site
makes available a number of resources which you may utilize to
properly install OpenLDAP Software.  This includes:

!block table; align=Center; coltags="N,URL"; \
        title="Table 4.1: Other OpenLDAP resources"
Resource                        URL
Document Catalog                http://www.OpenLDAP.org/doc/
Frequently Asked Questions      http://www.OpenLDAP.org/faq/
Issue Tracking System           http://www.OpenLDAP.org/its/
Mailing Lists                   http://www.OpenLDAP.org/lists/
Software Pages                  http://www.OpenLDAP.org/software/
Support Page                    http://www.OpenLDAP.org/support/
!endblock
 
H2: 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.

H3: {{TERM[expand]TLS}}

OpenLDAP clients and servers require installation of {{PRD:OpenSSL}}
{{TERM:TLS}} libraries to provide {{TERM[expand]TLS}} 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 {{URL: http://www.openssl.org/}}.

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


H3: Kerberos Authentication Services

OpenLDAP clients and servers support Kerberos-based authentication
services.
In particular, OpenLDAP supports {{TERM:SASL}}/{{TERM:GSSAPI}}
authentication mechanism using either {{PRD:Heimdal}} or
{{PRD: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 {{URL:http://www.pdc.kth.se/heimdal/}}.
MIT Kerberos is available from {{URL:http://web.mit.edu/kerberos/www/}}.

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


H3: {{TERM[expand]SASL}}

OpenLDAP clients and servers require installation of {{PRD:Cyrus}}'s
{{PRD:SASL}} libraries to provide {{TERM[expand]SASL}} 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
{{URL: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.


H3: Database software

OpenLDAP's {{slapd}}(8) primary database backend, {{TERM:LDBM}},
requires that a compatible database package for entry storage.  LDBM
is compatible with {{ORG[expand]Sleepy}}'s {{PRD:BerkeleyDB}} (recommended)
or the {{ORG[expand]FSF}}'s {{PRD:GNU}} Database Manager ({{PRD: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
in base system or as an optional software component.  You may
need may need to obtain the software and install it yourself.

{{PRD:BerkeleyDB}} is available from {{ORG[expand]Sleepy}}'s
download page {{URL: 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. 

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


H3: Threads

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


H3: 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 a IP-level firewall) is recommended
for servers containing non-public information.


H2: Running configure

If you haven't already done so, extra the distribution for the
compressed archive file and change directory to the top of the
distribution:

.{{EX:gunzip -c openldap-VERSION.tgz | tar xf -}}
.{{EX:cd openldap-VERSION}}

Replacing {{EX:VERSION}} with the appropriate version string.

Note: If you intend to build OpenLDAP for multiple platforms from a
single source tree you should consult the {{F: INSTALL}} file in the
top level distribution directory before running {{EX:configure}}.

Now you should probably run the {{EX:configure}} script with the
{{EX:--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.  Please see the appendix for a more detailed list
of configure options, and their usage.
.{{EX:./configure --help}}

The {{EX:configure}} script will also look at certain environment variables
for certain settings.  These environment variables are:

!block table; align=Center; coltags="EX,N"; title="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
!endblock

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

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

As an example, let's assume that we want a copy of OpenLDAP configured
to use the LDBM backend, and the shell backend.  The LDBM backend
is turned on by default, so we don't need to do anything special
to enable it.

Additionally, we've installed the BerkeleyDB database package.  
{{EX:configure}} is smart enough to use BerkeleyDB automatically
if it can find it, but BerkeleyDB is installed by default in a
place {{EX:configure}} won't look at automatically.  BerkeleyDB
is usually installed in {{F:/usr/local/BerkeleyDB.3.1}} (assuming
that version 3.1 is being used.) 

The following example shows how to run {{EX:configure}} and specify where to 
find BerkeleyDB and turn on the DNS-SRV backend.  The example should be 
entered on a single line (it has been split onto separate lines for clarity.)

>       env CPPFLAGS="-I/usr/local/BerkeleyDB.3.1/include" \
>               LDFLAGS="-L/usr/local/BerkeleyDB.3.1/lib" \
>               ./configure --enable-dnssrv

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.

For more information on backends see the chapter on configuration.

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


H2: Building the Software

Once you have run the {{EX:configure}} script the last line of output
should be:
>       Please "make depend" to build dependencies

If the last line of output does not match, {{EX:configure}} has failed.
You should not proceed until {{EX: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).


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

The test will run a number of tests.


H2: 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 {{F:/usr/local}}.  If you changed this
setting with the {{F:--prefix}} configure option, it will be installed
in the location you provided.

Typically, the installation is done as {{root}}. From the top level OpenLDAP
source directory, type:

>       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 in {{F:/usr/local/etc/openldap}} by default.  See the
{{SECT:The slapd Configuration File}} chapter for additional information.