-# Copyright 1999, The OpenLDAP Foundation, All Rights Reserved.
+# $OpenLDAP$
+# Copyright 1999-2003, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
-H1: Building and Installing slapd & slurpd
-Building and installing slapd requires three simple steps: configuring;
-making; and installing. The following sections describe each step in
-detail. If you are reading this guide, chances are you have already
-obtained the software, but just in case, here's where you can get the
-latest version of the OpenLDAP package, which includes all of the
-software discussed in this guide:
+H1: Building and Installing OpenLDAP Software
-{{CMD[jump="ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz"]ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz}}
+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 Software requires several steps:
+installing prerequisite software, configuring OpenLDAP Software
+itself, making, and finally installing. The following sections
+describe this process in detail.
-There is also an OpenLDAP homepage accessible from the World
-Wide Web. This page contains the latest OpenLDAP news, release
-announcements, and pointers to other resources. You can access it
-at:
-{{CMD[jump="http://www.OpenLDAP.org/"]http://www.OpenLDAP.org/}}
+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/}}.
-H2: Pre-Build Configuration
+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.
-Before building slapd, be sure to take a look at the README file in the
-top level directory in the distribution so that you are familiar with the
-general configuration and make process.
+Users of OpenLDAP Software can choose, depending on their desire
+for the {{latest features}} versus {{demonstrated stability}}, the
+most appropriate series to install.
-Briefly, you should edit the include/ldapconfig.h.edit and
-Make-common files to contain the site-specific configuration your site
-requires before making. The next sections discuss these steps in
-more detail.
+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}}
+You'll have to replace {{EX:VERSION}} with the version name of
+the release.
-H3: Editing the {{EX: Make-common}} file
+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.
-All of the general Make-common configuration variables (e.g.,
-ETCDIR, BINDIR, etc.) apply to both slapd and slurpd. There are
-additional Make-common configuration variables that also affect how
-slapd and slurpd are built. They are:
-H4: MAKE_SLAPD
+H2: Prerequisite software
-This option controls whether slapd and slurpd get built at all. You
-should set it to yes, like this:
+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 the installation instructions
+provided with it.
-E: MAKE_SLAPD = yes
-H4: SLAPD_BACKENDS
+H3: {{TERM[expand]TLS}}
-This option controls which slapd backend databases get built. You
-should set it to one or more of the following:
+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.
-*{{EX: DLDAP_LDBM}} This is the main backend. It is a high-performance
-disk-based database suitable for handling up to a million entries or so.
-See the LDBMBACKEND and LDBMLIB options below.
+OpenSSL is available from {{URL: http://www.openssl.org/}}.
-*{{EX: DLDAP_PASSWD}} This is a simple search-only backend that can be
-pointed at an {{EX: /etc/passwd}} file. It is intended more as an example than
-as a real backend.
+OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's
+{{EX:configure}} detects a usable OpenSSL installation.
-*{{EX: DLDAP_SHELL}} This backend allows the execution of arbitrary
-system administrator-defined commands in response to LDAP
-queries. The commands to execute are defined in the configuration file.
-See Appendix B for more information on writing shell backend
-programs.
-Example to enable the LDBM and SHELL backends only:
+H3: Kerberos Authentication Services
-E: SLAPD_BACKENDS= -DLDAP_LDBM -DLDAP_SHELL
+OpenLDAP clients and servers support Kerberos-based authentication
+services.
+In particular, OpenLDAP supports the {{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.
-The default is to build all three backends. Note that building a backend
-only means that it can be enabled through the configuration file, not
-that it will automatically be enabled.
+Heimdal Kerberos is available from {{URL:http://www.pdc.kth.se/heimdal/}}.
+MIT Kerberos is available from {{URL:http://web.mit.edu/kerberos/www/}}.
-H4: LDBMBACKEND
+Use of strong authentication services, such as those provided by
+Kerberos, is highly recommended.
-This option should only be defined if you have enabled the LDBM
-backend as described above. The LDBM backend relies on a
-low-level hash or B-tree package for its underlying database. This
-option selects which package it will use. The currently supported
-options in order of preference are:
-*{{EX: DLDBM_USE_DBBTREE}}
-.
-.This option enables the Berkeley DB package btree database as the
-.LDBM backend. You can get this package from
-.
-.{{CMD[jump="ftp://ftp.cs.berkeley.edu/ucb/4bsd/db.tar.Z"]ftp://ftp.cs.berkeley.edu/ucb/4bsd/db.tar.Z}}
-.
+H3: {{TERM[expand]SASL}}
-*{{EX: DLDBM_USE_DBHASH}}
-.
-.This option enables the Berkeley DB package hash database as the
-.LDBM backend. You can get this package from
-.
-.{{CMD[jump="ftp://ftp.cs.berkeley.edu/ucb/4bsd/db.tar.Z"]ftp://ftp.cs.berkeley.edu/ucb/4bsd/db.tar.Z}}
-.
+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.
-*{{EX: DLDBM_USE_GDBM}}
-.
-.This option enables GNU dbm as the LDBM backend. You can get this
-.package from
-.
-.{{CMD[jump="ftp://prep.ai.mit.edu/pub/gnu/gdbm-1.7.3.tar.gz"]ftp://prep.ai.mit.edu/pub/gnu/gdbm-1.7.3.tar.gz}}
-.
+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.
-*{{EX: DLDBM_USE_NDBM}}
-.
-.This option enables the standard UNIX ndbm(3) package as the
-.LDBM backend. This package should come standard on your UNIX
-.system. man ndbm for details.
-.
+OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's
+configure detects a usable Cyrus SASL installation.
-Example to enable the Berkeley DB Btree backend:
-E: LDBMBACKEND= -DLDBM_USE_DBBTREE
+H3: Database Software
-The default is -DLDBM_USE_NDBM, since it is the only one available
-on all UNIX systems. NDBM has some serious limitations, though (not
-thread-safe, severe size limits), and you are strongly encouraged to
-use one of the other packages if you can.
+OpenLDAP's {{slapd}}(8) primary database backend, {{TERM:BDB}},
+requires {{ORG[expand]Sleepycat}} {{PRD:Berkeley DB}}, version 4.
+If not available at configure time, you will not be able build
+{{slapd}}(8) with this primary database backend.
-Note[label='Note to Solaris users: '] If you are running under Solaris 2.x
-and linking in an external database package (e.g., db or gdbm) it is
-very important that you compile the package with the {{EX: D_REENTRANT}}
-flag. If you do not, bad things will happen.
+Your operating system may provide {{PRD:Berkeley DB}}, version 4,
+in the base system or as an optional software component. If not,
+you'll have to obtain and install it yourself.
-If you are using version 1.85 or earlier of the Berkeley db package, you
-will need to apply the patch found in build/db.1.85.patch to the db
-source before compiling it. You can do this with a command like this
-from the db source area:
+{{PRD:Berkeley DB}} is available from {{ORG[expand]Sleepycat}}'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 4.1, is recommended. This package is
+required if you wish to use the {{TERM:BDB}} database backend.
-E: patch -p < ldap-source-directory/build/db.1.85.patch
+OpenLDAP's {{slapd}}(8) LDBM backend supports a variety of data
+base managers including {{PRD:Berkeley DB}} and {{PRD:GDBM}}.
+{{PRD:GDBM}} is available from {{ORG:FSF}}'s download site {{URL:
+ftp://ftp.gnu.org/pub/gnu/gdbm/}}.
-H4: LDBMLIB
-This option should only be defined if you have enabled the LDBM
-backend as described above, and the necessary library for the
-LDBMBACKEND option you chose above is not part of the standard C
-library (i.e., anything other than NDBM). This option specifies the library
-to link containing the package you selected, and optionally, its location.
+H3: Threads
-Example to link with {{EX: libdb.a}}, contained in {{EX: /usr/local/lib}}:
+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/}}.
-E: LDBMLIB= -L/usr/local/lib -ldb
-H4: THREADS
+H3: TCP Wrappers
-This option is normally set automatically in the {{EX: Make-platform}} file,
-based on the platform on which you are building. You do not normally
-need to set it. If you want to use a non-default threads package, you
-can specify the appropriate {{EX: -Ddefine}} to enable it here.
+{{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.
-H4: THREADSLIB
-This option is normally set automatically in the {{EX: Make-platform}} file,
-based on the platform on which you are building. You do not normally
-need to set it. If you have set {{EX: THREADS}} to a non-default threads
-package as described above, you can specify the appropriate
- {{EX: -Ldirectory}} flag and {{EX: -llibname}} flag needed to link the package here.
+H2: Running configure
-H4: PHONETIC
+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.
+!if 0
+Please see the appendix for a more detailed list of configure options,
+and their usage.
+!endif
+> ./configure --help
-This option controls the phonetic algorithm used by {{I: slapd}} when doing
-approximate searches. The default is to use the metaphone algorithm.
-You can have {{I: slapd}} use the soundex algorithm by setting this variable
-to {{EX: -DSOUNDEX}}.
+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
-H3: Editing the {{EX: include/ldapconfig.h}} file
+Now run the configure script with any desired configuration options or
+environment variables.
-In addition to setting the {{EX: LDAPHOST}} and {{EX: DEFAULT_BASE}} defines
-near the top of this file, there are some slapd-specific defines near the
-bottom of the file you may want to change. The defaults should be just
-fine, unless you have special needs.
+> [[env] settings] ./configure [options]
-H4: SLAPD_DEFAULT_CONFIGFILE
+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:
-This define sets the location of the default slapd configuration file.
-Normally, it is set to {{EX: $(ETCDIR)/slapd.conf}}, where
-{{EX: ETCDIR}} comes from Make-common.
+> ./configure --with-wrappers
-H4: SLAPD_DEFAULT_SIZELIMIT
+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:
-This define sets the default size limit on the number of entries returned
-from a search. This option is configurable via the tailor file, but if you
-want to change the default, do it here.
+> env CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib" \
+> ./configure --with-wrappers
-H4: SLAPD_DEFAULT_TIMELIMIT
+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.
-This define sets the default time limit for a search. This option is
-configurable via the tailor file, but if you want to change the default, do it
-here.
+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.
-H4: SLAPD_PIDFILE
-This define sets the location of the file to which slapd will write its
-process ID when it starts up.
+H2: Building the Software
-H4: SLAPD_ARGSFILE
+Once you have run the {{EX:configure}} script the last line of output
+should be:
+> Please "make depend" to build dependencies
-This define sets the location of the file to which slapd will write its
-argument vector when it starts up.
+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.
-H4: SLAPD_MONITOR_DN
+To build dependencies, run:
+> make depend
-This define sets the distinguished name used to retrieve monitoring
-information from {{I: slapd}}. See section 7 for more details.
-
-H4: SLAPD_LDBM_MIN_MAXIDS
-
-This define is only relevant to the LDBM backend. It sets the minimum
-number of entry IDs that an index entry will contain before it becomes
-an allIDs entry. See Section 9.1 for more details.
-
-
-
-H2: Making the Software
-
-Once you have edited the {{EX: include/ldapconfig.h.edit}} file and the
-Make-common file (see the top level {{EX: README}} file in the distribution),
-you are ready to make the software. From the top level LDAP source
-directory, type
-
-E: 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 LDAP distribution can support making 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 in the {{EX: Make-common}} file.
-Typically, the installation is done as root. From the top level LDAP
-source directory, type
+made, you should run the test suite to verify the build.
-E: make install
+> make test
-You should examine the output of this command carefully to make sure
-everything is installed correctly. Slapd, slurpd, and their configuration
-files, {{EX: slapd.conf}}, {{EX: slapd.at.conf}}, and {{EX: slapd.oc.conf}}
- will be installed in the {{EX: ETCDIR}} directory you specified
-in the {{EX: Make-common}} file.
+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.
-This command will install the entire LDAP distribution. If you only want
-to install slapd and slurpd, you could do something like this:
-E: (cd servers/slapd; make install)
+H2: Installing the Software
-E: (cd servers/slurpd; make install)
+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.
-Note: The installation process installs configuration files as well as
-binaries. Existing configuration files are first moved to a name with a
-dash '-' appended, e.g., {{EX: slapd.conf}} is moved to {{EX: slapd.conf-}}.
-If you install things twice, however, you can lose your existing configuration
-files.
+Typically, the installation requires {{super-user}} privileges.
+From the top level OpenLDAP source directory, type:
+> su root -c 'make install'
-PB:
+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}}(8) in {{F:/usr/local/etc/openldap}} by default. See the
+chapter {{SECT:The slapd Configuration File}} for additional information.
projects / openldap / blobdiff