2 # Copyright 1999-2005, The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
5 H1: Building and Installing OpenLDAP Software
7 This chapter details how to build and install the {{ORG:OpenLDAP}}
8 Software package including {{slapd}}(8), the stand-alone LDAP daemon
9 and {{slurpd}}(8), the stand-alone update replication daemon.
10 Building and installing OpenLDAP Software requires several steps:
11 installing prerequisite software, configuring OpenLDAP Software
12 itself, making, and finally installing. The following sections
13 describe this process in detail.
16 H2: Obtaining and Extracting the Software
18 You can obtain OpenLDAP Software from the project's download
19 page at {{URL: http://www.openldap.org/software/download/}} or
20 directly from the project's {{TERM:FTP}} service at
21 {{URL: ftp://ftp.openldap.org/pub/OpenLDAP/}}.
23 The project makes available two series of packages for {{general
24 use}}. The project makes {{releases}} as new features and bug fixes
25 come available. Though the project takes steps to improve stablity
26 of these releases, it is common for problems to arise only after
27 {{release}}. The {{stable}} release is the latest {{release}} which
28 has demonstrated stability through general use.
30 Users of OpenLDAP Software can choose, depending on their desire
31 for the {{latest features}} versus {{demonstrated stability}}, the
32 most appropriate series to install.
34 After downloading OpenLDAP Software, you need to extract the
35 distribution from the compressed archive file and change your working
36 directory to the top directory of the distribution:
38 .{{EX:gunzip -c openldap-VERSION.tgz | tar xf -}}
39 .{{EX:cd openldap-VERSION}}
41 You'll have to replace {{EX:VERSION}} with the version name of
44 You should now review the {{F:COPYRIGHT}}, {{F:LICENSE}}, {{F:README}}
45 and {{F:INSTALL}} documents provided with the distribution. The
46 {{F:COPYRIGHT}} and {{F:LICENSE}} provide information on acceptable
47 use, copying, and limitation of warranty of OpenLDAP Software. The
48 {{F:README}} and {{F:INSTALL}} documents provide detailed information
49 on prerequisite software and installation procedures.
52 H2: Prerequisite software
54 OpenLDAP Software relies upon a number of software packages distributed
55 by third parties. Depending on the features you intend to use, you
56 may have to download and install a number of additional software
57 packages. This section details commonly needed third party software
58 packages you might have to install. However, for an up-to-date
59 prerequisite information, the {{F:README}} document should be
60 consulted. Note that some of these third party packages may depend
61 on additional software packages. Install each package per the
62 installation instructions provided with it.
65 H3: {{TERM[expand]TLS}}
67 OpenLDAP clients and servers require installation of {{PRD:OpenSSL}}
68 {{TERM:TLS}} libraries to provide {{TERM[expand]TLS}} services. Though
69 some operating systems may provide these libraries as part of the
70 base system or as an optional software component, OpenSSL often
71 requires separate installation.
73 OpenSSL is available from {{URL: http://www.openssl.org/}}.
75 OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's
76 {{EX:configure}} detects a usable OpenSSL installation.
79 H3: Kerberos Authentication Services
81 OpenLDAP clients and servers support Kerberos-based authentication
83 In particular, OpenLDAP supports the {{TERM:SASL}}/{{TERM:GSSAPI}}
84 authentication mechanism using either {{PRD:Heimdal}} or
85 {{PRD:MIT Kerberos}} V packages.
86 If you desire to use Kerberos-based SASL/GSSAPI authentication,
87 you should install either Heimdal or MIT Kerberos V.
89 Heimdal Kerberos is available from {{URL:http://www.pdc.kth.se/heimdal/}}.
90 MIT Kerberos is available from {{URL:http://web.mit.edu/kerberos/www/}}.
92 Use of strong authentication services, such as those provided by
93 Kerberos, is highly recommended.
96 H3: {{TERM[expand]SASL}}
98 OpenLDAP clients and servers require installation of {{PRD:Cyrus}}'s
99 {{PRD:SASL}} libraries to provide {{TERM[expand]SASL}} services. Though
100 some operating systems may provide this library as part of the
101 base system or as an optional software component, Cyrus SASL
102 often requires separate installation.
104 Cyrus SASL is available from
105 {{URL:http://asg.web.cmu.edu/sasl/sasl-library.html}}.
106 Cyrus SASL will make use of OpenSSL and Kerberos/GSSAPI libraries
109 OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's
110 configure detects a usable Cyrus SASL installation.
113 H3: Database Software
115 OpenLDAP's {{slapd}}(8) {{TERM:BDB}} and {{TERM:HDB}} primary database backends
116 require {{ORG[expand]Sleepycat}} {{PRD:Berkeley DB}}.
117 If not available at configure time, you will not be able build
118 {{slapd}}(8) with these primary database backends.
120 Your operating system may provide a supported version of
121 {{PRD:Berkeley DB}} in the base system or as an optional
122 software component. If not, you'll have to obtain and
125 {{PRD:Berkeley DB}} is available from {{ORG[expand]Sleepycat}}'s
126 download page {{URL: http://www.sleepycat.com/download/}}. There
127 are several versions available. Generally, the most recent release
128 (with published patches) is recommended. This package is required
129 if you wish to use the {{TERM:BDB}} or {{TERM:HDB}} database backends.
131 OpenLDAP's {{slapd}}(8) LDBM backend supports a variety of data
132 base managers including {{PRD:Berkeley DB}} and {{PRD:GDBM}}.
133 {{PRD:GDBM}} is available from {{ORG:FSF}}'s download site {{URL:
134 ftp://ftp.gnu.org/pub/gnu/gdbm/}}.
139 OpenLDAP is designed to take advantage of threads. OpenLDAP
140 supports POSIX {{pthreads}}, Mach {{CThreads}}, and a number of
141 other varieties. {{EX:configure}} will complain if it cannot
142 find a suitable thread subsystem. If this occurs, please
143 consult the {{F:Software|Installation|Platform Hints}} section
144 of the OpenLDAP FAQ {{URL: http://www.openldap.org/faq/}}.
149 {{slapd}}(8) supports TCP Wrappers (IP level access control filters)
150 if preinstalled. Use of TCP Wrappers or other IP-level access
151 filters (such as those provided by an IP-level firewall) is recommended
152 for servers containing non-public information.
155 H2: Running configure
157 Now you should probably run the {{EX:configure}} script with the
158 {{EX:--help}} option.
159 This will give you a list of options that you can change when building
160 OpenLDAP. Many of the features of OpenLDAP can be enabled or disabled
163 Please see the appendix for a more detailed list of configure options,
168 The {{EX:configure}} script will also look at various environment variables
169 for certain settings. These environment variables include:
171 !block table; align=Center; coltags="EX,N"; title="Table 4.1: Environment Variables"
173 CC Specify alternative C Compiler
174 CFLAGS Specify additional compiler flags
175 CPPFLAGS Specify C Preprocessor flags
176 LDFLAGS Specify linker flags
177 LIBS Specify additional libraries
180 Now run the configure script with any desired configuration options or
181 environment variables.
183 > [[env] settings] ./configure [options]
185 As an example, let's assume that we want to install OpenLDAP with
186 BDB backend and TCP Wrappers support. By default, BDB
187 is enabled and TCP Wrappers is not. So, we just need to specify
188 {{EX:--with-wrappers}} to include TCP Wrappers support:
190 > ./configure --with-wrappers
192 However, this will fail to locate dependent software not
193 installed in system directories. For example, if TCP Wrappers
194 headers and libraries are installed in {{F:/usr/local/include}}
195 and {{F:/usr/local/lib}} respectively, the {{EX:configure}}
196 script should be called as follows:
198 > env CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib" \
199 > ./configure --with-wrappers
201 Note: Some shells, such as those derived from the Bourne {{sh}}(1),
202 do not require use of the {{env}}(1) command. In some cases, environmental
203 variables have to be specified using alternative syntaxes.
205 The {{EX:configure}} script will normally auto-detect appropriate
206 settings. If you have problems at this stage, consult any platform
207 specific hints and check your {{EX:configure}} options, if any.
210 H2: Building the Software
212 Once you have run the {{EX:configure}} script the last line of output
214 > Please "make depend" to build dependencies
216 If the last line of output does not match, {{EX:configure}} has failed,
217 and you will need to review its output to determine what went wrong.
218 You should not proceed until {{EX:configure}} completes successfully.
220 To build dependencies, run:
223 Now build the software, this step will actually compile OpenLDAP.
226 You should examine the output of this command carefully to make sure
227 everything is built correctly. Note that this command builds the LDAP
228 libraries and associated clients as well as {{slapd}}(8) and {{slurpd}}(8).
231 H2: Testing the Software
233 Once the software has been properly configured and successfully
234 made, you should run the test suite to verify the build.
238 Tests which apply to your configuration will run and they should pass.
239 Some tests, such as the replication test, may be skipped if not supported
240 by your configuration.
243 H2: Installing the Software
245 Once you have successfully tested the software, you are ready to
246 install it. You will need to have write permission to the installation
247 directories you specified when you ran configure. By default
248 OpenLDAP Software is installed in {{F:/usr/local}}. If you changed
249 this setting with the {{EX:--prefix}} configure option, it will be
250 installed in the location you provided.
252 Typically, the installation requires {{super-user}} privileges.
253 From the top level OpenLDAP source directory, type:
255 > su root -c 'make install'
257 and enter the appropriate password when requested.
259 You should examine the output of this command carefully to make sure
260 everything is installed correctly. You will find the configuration files
261 for {{slapd}}(8) in {{F:/usr/local/etc/openldap}} by default. See the
262 chapter {{SECT:Configuring slapd}} for additional information.