-# Copyright 1999, The OpenLDAP Foundation, All Rights Reserved.
+# $OpenLDAP$
+# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
-H1: Building and Installing slapd & slurpd
+H1: Building and Installing OpenLDAP Software
-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:
+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}}.
-{{CMD[jump="ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz"]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:
-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:
+!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
-{{CMD[jump="http://www.OpenLDAP.org/"]http://www.OpenLDAP.org/}}
+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}}
-H2: Pre-Build Configuration
+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.
-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.
+OpenSSL is available from {{URL: http://www.openssl.org/}}.
-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.
+OpenLDAP will not be fully LDAPv3 compliant unless OpenLDAP's
+{{EX:configure}} detects a usable OpenSSL installation.
+H3: Kerberos Authentication Services
-H3: Editing the {{EX: Make-common}} file
+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.
-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:
+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: MAKE_SLAPD
+Use of strong authentication services, such as those provided by
+Kerberos, is highly recommended.
-This option controls whether slapd and slurpd get built at all. You
-should set it to yes, like this:
-E: MAKE_SLAPD = yes
+H3: {{TERM[expand]SASL}}
-H4: SLAPD_BACKENDS
+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.
-This option controls which slapd backend databases get built. You
-should set it to one or more of the following:
+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: 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.
+OpenLDAP will not be fully LDAPv3 compliant unless OpenLDAP's
+configure detects a usable Cyrus SASL installation.
-*{{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.
-*{{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.
+H3: Database software
-Example to enable the LDBM and SHELL backends only:
+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.
-E: SLAPD_BACKENDS= -DLDAP_LDBM -DLDAP_SHELL
+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.
-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.
+{{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.
-H4: LDBMBACKEND
+{{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.
-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: Threads
-*{{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 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/}}.
-*{{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}}
-.
-*{{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.
-.
+H3: TCP Wrappers
-Example to enable the Berkeley DB Btree backend:
+{{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.
-E: LDBMBACKEND= -DLDBM_USE_DBBTREE
-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.
+H2: Running configure
-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.
+If you haven't already done so, extra the distribution for the
+compressed archive file and change directory to the top of the
+distribution:
-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:
+.{{EX:gunzip -c openldap-VERSION.tgz | tar xf -}}
+.{{EX:cd openldap-VERSION}}
-E: patch -p < ldap-source-directory/build/db.1.85.patch
+Replacing {{EX:VERSION}} with the appropriate version string.
-H4: LDBMLIB
+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}}.
-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.
+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}}
-Example to link with {{EX: libdb.a}}, contained in {{EX: /usr/local/lib}}:
+The {{EX:configure}} script will also look at certain environment variables
+for certain settings. These environment variables are:
-E: LDBMLIB= -L/usr/local/lib -ldb
+!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
-H4: THREADS
+Now run the configure script with any desired configure options or
+environment variables.
-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.
+> [[env] settings] ./configure [options]
-H4: THREADSLIB
+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.
-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.
+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.)
-H4: PHONETIC
+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.)
-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}}.
+> 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.
-H3: Editing the {{EX: include/ldapconfig.h}} file
+For more information on backends see the chapter on configuration.
-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.
+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_DEFAULT_CONFIGFILE
-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.
+H2: Building the Software
-H4: SLAPD_DEFAULT_SIZELIMIT
+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 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.
+If the last line of output does not match, {{EX:configure}} has failed.
+You should not proceed until {{EX:configure}} completes successfully.
-H4: SLAPD_DEFAULT_TIMELIMIT
+To build dependencies, run:
+> make depend
-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.
-
-H4: SLAPD_PIDFILE
-
-This define sets the location of the file to which slapd will write its
-process ID when it starts up.
-
-H4: SLAPD_ARGSFILE
-
-This define sets the location of the file to which slapd will write its
-argument vector when it starts up.
-
-H4: SLAPD_MONITOR_DN
-
-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.
-
-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.
-
+libraries and associated clients as well as {{slapd}}(8) and {{slurpd}}(8).
-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
-
-E: make install
+made, you should run the test suite to verify the build.
-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.
+> make test
-This command will install the entire LDAP distribution. If you only want
-to install slapd and slurpd, you could do something like this:
+The test will run a number of tests.
-E: (cd servers/slapd; make install)
-E: (cd servers/slurpd; make install)
+H2: Installing the Software
-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.
+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:
-PB:
+> 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.
projects / openldap / blobdiff