# $OpenLDAP$
-# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2006 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 OpenLDAP Software
-package including {{slapd}}(8), the stand-alone LDAP daemon and
-{{slurpd}}(8), the stand-alone update replication daemon.
+This chapter details how to build and install the {{PRD:OpenLDAP}}
+Software package including {{slapd}}(8), the stand-alone LDAP daemon
+and {{slurpd}}(8), the stand-alone update replication daemon.
+Building and installing OpenLDAP Software requires several steps:
+installing prerequisite software, configuring OpenLDAP Software
+itself, making, and finally installing. The following sections
+describe this process in detail.
+
+
+H2: Obtaining and Extracting the Software
+
+You can obtain OpenLDAP Software from the project's download
+page at {{URL: http://www.openldap.org/software/download/}} or
+directly from the project's {{TERM:FTP}} service at
+{{URL: 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 {{stable}} release is 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:
+
+.{{EX:gunzip -c openldap-VERSION.tgz | tar xf -}}
+.{{EX:cd openldap-VERSION}}
-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.
+You'll have to replace {{EX:VERSION}} with the version name of
+the release.
-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}}
+You should now review the {{F:COPYRIGHT}}, {{F:LICENSE}}, {{F:README}}
+and {{F:INSTALL}} documents provided with the distribution. The
+{{F:COPYRIGHT}} and {{F:LICENSE}} provide information on acceptable
+use, copying, and limitation of warranty of OpenLDAP Software. The
+{{F:README}} and {{F:INSTALL}} documents provide detailed information
+on prerequisite software and installation procedures.
-The OpenLDAP Project also maintains an extensive site on the World Wide Web.
-The site contains the latest OpenLDAP news, release announcements, and
-pointers to many other resources. You can access the site at:
-{{URL: http://www.OpenLDAP.org/}}
H2: Prerequisite software
-OpenLDAP relies 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.
+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. However, for an up-to-date
+prerequisite information, the {{F:README}} document should be
+consulted. Note that some of these third party packages may depend
+on additional software packages. Install each package per the
+installation instructions provided with it.
+
-H3: TLS Software
+H3: {{TERM[expand]TLS}}
-OpenLDAP clients and servers require installation of OpenSSL TLS
-libraries to provide {{TERM[expand]TLS}} services. Though
+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
-configure detects a usable OpenSSL installation.
-
-H3: Kerberos Software
+OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's
+{{EX:configure}} detects a usable OpenSSL installation.
-OpenLDAP clients and servers support Kerberos based authentication
-services. In particular, OpenLDAP supports SASL/GSSAPI based
-authentication using either Heimdal or MIT Kerberos V packages.
-If you desire to use Kerberos based authentication, you should
-install either Heimdal or MIT Kerberos V.
-Heimdal Kerberos is available from {{http://}}.
-MIT Kerberos is available from {{http://}}.
+H3: {{TERM[expand]SASL}}
-H3: SASL Software
-
-OpenLDAP clients and servers require installation of Cyrus SASL
+OpenLDAP clients and servers require installation of {{PRD:Cyrus SASL}}
libraries to provide {{TERM[expand]SASL}} services. Though
-some operating sytems may provide this library as part of the
+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:: }}. Cyrus SASL will
-make use of Kerberos libraries if preinstalled.
+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
+OpenLDAP Software 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 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.
+H3: {{TERM[expand]Kerberos}}
-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.
+OpenLDAP clients and servers support {{TERM:Kerberos}} authentication
+services. In particular, OpenLDAP supports the Kerberos V
+{{TERM:GSS-API}} {{TERM:SASL}} authentication mechanism known as
+the {{TERM:GSSAPI}} mechanism. This feature requires, in addition to
+Cyrus SASL libraries, either {{PRD:Heimdal}} or {{PRD:MIT Kerberos}}
+V libraries.
-BerkeleyDB is available from Sleepycat's web site
-{{URL: http://www.sleepycat.com/download.html}}. There are
-several versions available. At the time of this writing,
-version 3.1, the latest release, is recommended.
+Heimdal Kerberos is available from {{URL:http://www.pdc.kth.se/heimdal/}}.
+MIT Kerberos is available from {{URL:http://web.mit.edu/kerberos/www/}}.
-GDBM is available from GNU's ftp {{URL: ftp://ftp.gnu.org/pub/gnu/gdbm/}}
-At the time of this writing, version 1.8 is the latest release.
+Use of strong authentication services, such as those provided by
+Kerberos, is highly recommended.
-H2: Configuring OpenLDAP
-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}}
+H3: Database Software
+
+OpenLDAP's {{slapd}}(8) {{TERM:BDB}} and {{TERM:HDB}} primary database backends
+require {{ORG[expand]Oracle}} {{PRD:Berkeley DB}}.
+If not available at configure time, you will not be able build
+{{slapd}}(8) with these primary database backends.
+
+Your operating system may provide a supported version of
+{{PRD:Berkeley DB}} in the base system or as an optional
+software component. If not, you'll have to obtain and
+install it yourself.
+
+{{PRD:Berkeley DB}} is available from {{ORG[expand]Oracle}}'s Berkeley DB
+download page
+{{URL: http://www.oracle.com/technology/software/products/berkeley-db/index.html}}. There are several versions available. Generally, the most recent
+release (with published patches) is recommended. This package is required
+if you wish to use the {{TERM:BDB}} or {{TERM:HDB}} database backends.
-Replacing {{EX:VERSION}} with the appropriate version string.
+
+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 an IP-level firewall) is recommended
+for servers containing non-public information.
+
+
+H2: Running 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 configure script will also look at certain environment variables
-for certain settings. These environment variables are:
-!block table
-Variable Uses
-CC Sets which C Compiler to use (cc,gcc)
-CFLAGS What compiler flags to use
-CPPFLAGS What C Preprocessor flags to use
-LDFLAGS What flags to give the linker
-LIBS What libraries to include
+using this method.
+!if 0
+Please see the appendix for a more detailed list of configure options,
+and their usage.
+!endif
+> ./configure --help
+
+The {{EX:configure}} script will also look at various environment variables
+for certain settings. These environment variables include:
+
+!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
+Now run the configure script with any desired configuration options or
environment variables.
-.{{EX: [[env] settings] ./configure [options] }}
-As an example, lets 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.
+> [[env] settings] ./configure [options]
-Additionally, we've installed the BerkeleyDB database package.
-Configure is smart enough to use BerkeleyDB automaticly if it can find it, but
-BerkeleyDB is installed by default in a place configure won't look at
-automaticly. BerkeleyDB is usually installed in /usr/local/BerkeleyDB.3.1
-(assuming that version 3.1 is being used.)
+As an example, let's assume that we want to install OpenLDAP with
+BDB backend and TCP Wrappers support. By default, BDB
+is enabled and TCP Wrappers is not. So, we just need to specify
+{{EX:--with-wrappers}} to include TCP Wrappers support:
- The following example shows how to run configure and specify where to
-find BerkeleyDB and turn on the shell backend. The example should be
-entered on a single line (it has been split onto seperate lines for clarity.)
+> ./configure --with-wrappers
-If you are using csh (or any shell with similar syntax, ie tcsh.)
-.{{EX: env CPPFLAGS="-I/usr/local/BerkeleyDB.3.1/include" LDFLAGS="-L/usr/local/BerkeleyDB.3.1/lib" ./configure --enable-shell}}
+However, this will fail to locate dependent software not
+installed in system directories. For example, if TCP Wrappers
+headers and libraries are installed in {{F:/usr/local/include}}
+and {{F:/usr/local/lib}} respectively, the {{EX:configure}}
+script should be called as follows:
-If you are using sh (or any shell with similar syntax, ie bash,ksh,etc.)
-.{{EX: CPPFLAGS="-I/usr/local/BerkeleyDB.3.1/include" LDFLAGS="-L/usr/local/BerkeleyDB.3.1/lib" ./configure --enable-shell}}
+> env CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib" \
+> ./configure --with-wrappers
-For more information on backends see the chapter on configuration.
+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 {{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.
-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.
H2: Building the Software
-Once you have run the configure script the last line of output should be:
-.{{EX:Please "make depend" to build dependencies}}
+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, configure has probably failed.
-You should not proceed until configure completes sucessfuly.
+If the last line of output does not match, {{EX:configure}} has failed,
+and you will need to review its output to determine what went wrong.
+You should not proceed until {{EX:configure}} completes successfully.
-Now run make depend.
-.{{EX: make depend}}
+To build dependencies, run:
+> make depend
-Now run make, this step will actually compile OpenLDAP.
-.{{EX: make}}
+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 and slurpd.
+libraries and associated clients as well as {{slapd}}(8) and {{slurpd}}(8).
-Note that the OpenLDAP distribution can support building for multiple
-platforms from a single source tree. If you want to do this, consult the
-{{EX: INSTALL}} file in the top level distribution directory.
-H2: Installing the Software
+H2: Testing the Software
Once the software has been properly configured and successfully
-made, 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 --prefix configure option, it will be installed
-in the location you provided.
+made, you should run the test suite to verify the build.
-Typically, the installation is done as root. From the top level OpenLDAP
-source directory, type
+> make test
-.{{EX: make install}}
+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.
+
+
+H2: Installing the Software
+
+Once 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 Software is installed in {{F:/usr/local}}. If you changed
+this setting with the {{EX:--prefix}} configure option, it will be
+installed in the location you provided.
+
+Typically, the installation requires {{super-user}} privileges.
+From the top level OpenLDAP source directory, type:
+
+> su root -c 'make install'
+
+and enter the appropriate password when requested.
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 chapter 5 for more
-information on the configuration files.
-
+for {{slapd}}(8) in {{F:/usr/local/etc/openldap}} by default. See the
+chapter {{SECT:Configuring slapd}} for additional information.