2 # Copyright 1999-2003, 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,
56 you may have to download and install a number of additional
57 software packages. This section details commonly needed third party
58 software packages you might have to install. Note that some of
59 these third party packages may depend on additional software
60 packages. Install each package per the installation instructions
64 H3: {{TERM[expand]TLS}}
66 OpenLDAP clients and servers require installation of {{PRD:OpenSSL}}
67 {{TERM:TLS}} libraries to provide {{TERM[expand]TLS}} services. Though
68 some operating systems may provide these libraries as part of the
69 base system or as an optional software component, OpenSSL often
70 requires separate installation.
72 OpenSSL is available from {{URL: http://www.openssl.org/}}.
74 OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's
75 {{EX:configure}} detects a usable OpenSSL installation.
78 H3: Kerberos Authentication Services
80 OpenLDAP clients and servers support Kerberos-based authentication
82 In particular, OpenLDAP supports the {{TERM:SASL}}/{{TERM:GSSAPI}}
83 authentication mechanism using either {{PRD:Heimdal}} or
84 {{PRD:MIT Kerberos}} V packages.
85 If you desire to use Kerberos-based SASL/GSSAPI authentication,
86 you should install either Heimdal or MIT Kerberos V.
88 Heimdal Kerberos is available from {{URL:http://www.pdc.kth.se/heimdal/}}.
89 MIT Kerberos is available from {{URL:http://web.mit.edu/kerberos/www/}}.
91 Use of strong authentication services, such as those provided by
92 Kerberos, is highly recommended.
95 H3: {{TERM[expand]SASL}}
97 OpenLDAP clients and servers require installation of {{PRD:Cyrus}}'s
98 {{PRD:SASL}} libraries to provide {{TERM[expand]SASL}} services. Though
99 some operating systems may provide this library as part of the
100 base system or as an optional software component, Cyrus SASL
101 often requires separate installation.
103 Cyrus SASL is available from
104 {{URL:http://asg.web.cmu.edu/sasl/sasl-library.html}}.
105 Cyrus SASL will make use of OpenSSL and Kerberos/GSSAPI libraries
108 OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's
109 configure detects a usable Cyrus SASL installation.
112 H3: Database Software
114 OpenLDAP's {{slapd}}(8) primary database backend, {{TERM:BDB}},
115 requires {{ORG[expand]Sleepycat}} {{PRD:Berkeley DB}}, version 4.
116 If not available at configure time, you will not be able build
117 {{slapd}}(8) with this primary database backend.
119 Your operating system may provide {{PRD:Berkeley DB}}, version 4,
120 in the base system or as an optional software component. If not,
121 you'll have to obtain and install it yourself.
123 {{PRD:Berkeley DB}} is available from {{ORG[expand]Sleepycat}}'s
124 download page {{URL: http://www.sleepycat.com/download.html}}.
125 There are several versions available. At the time of this writing,
126 the latest release, version 4.1, is recommended. This package is
127 required if you wish to use the {{TERM:BDB}} database backend.
129 OpenLDAP's {{slapd}}(8) LDBM backend supports a variety of data
130 base managers including {{PRD:Berkeley DB}} and {{PRD:GDBM}}.
131 {{PRD:GDBM}} is available from {{ORG:FSF}}'s download site {{URL:
132 ftp://ftp.gnu.org/pub/gnu/gdbm/}}.
137 OpenLDAP is designed to take advantage of threads. OpenLDAP
138 supports POSIX {{pthreads}}, Mach {{CThreads}}, and a number of
139 other varieties. {{EX:configure}} will complain if it cannot
140 find a suitable thread subsystem. If this occurs, please
141 consult the {{F:Software|Installation|Platform Hints}} section
142 of the OpenLDAP FAQ {{URL: http://www.openldap.org/faq/}}.
147 {{slapd}}(8) supports TCP Wrappers (IP level access control filters)
148 if preinstalled. Use of TCP Wrappers or other IP-level access
149 filters (such as those provided by an IP-level firewall) is recommended
150 for servers containing non-public information.
153 H2: Running configure
155 Now you should probably run the {{EX:configure}} script with the
156 {{EX:--help}} option.
157 This will give you a list of options that you can change when building
158 OpenLDAP. Many of the features of OpenLDAP can be enabled or disabled
161 Please see the appendix for a more detailed list of configure options,
166 The {{EX:configure}} script will also look at various environment variables
167 for certain settings. These environment variables include:
169 !block table; align=Center; coltags="EX,N"; title="Table 4.1: Environment Variables"
171 CC Specify alternative C Compiler
172 CFLAGS Specify additional compiler flags
173 CPPFLAGS Specify C Preprocessor flags
174 LDFLAGS Specify linker flags
175 LIBS Specify additional libraries
178 Now run the configure script with any desired configuration options or
179 environment variables.
181 > [[env] settings] ./configure [options]
183 As an example, let's assume that we want to install OpenLDAP with
184 BDB backend and TCP Wrappers support. By default, BDB
185 is enabled and TCP Wrappers is not. So, we just need to specify
186 {{EX:--with-wrappers}} to include TCP Wrappers support:
188 > ./configure --with-wrappers
190 However, this will fail to locate dependent software not
191 installed in system directories. For example, if TCP Wrappers
192 headers and libraries are installed in {{F:/usr/local/include}}
193 and {{F:/usr/local/lib}} respectively, the {{EX:configure}}
194 script should be called as follows:
196 > env CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib" \
197 > ./configure --with-wrappers
199 Note: Some shells, such as those derived from the Bourne {{sh}}(1),
200 do not require use of the {{env}}(1) command. In some cases, environmental
201 variables have to be specified using alternative syntaxes.
203 The {{EX:configure}} script will normally auto-detect appropriate
204 settings. If you have problems at this stage, consult any platform
205 specific hints and check your {{EX:configure}} options, if any.
208 H2: Building the Software
210 Once you have run the {{EX:configure}} script the last line of output
212 > Please "make depend" to build dependencies
214 If the last line of output does not match, {{EX:configure}} has failed,
215 and you will need to review its output to determine what went wrong.
216 You should not proceed until {{EX:configure}} completes successfully.
218 To build dependencies, run:
221 Now build the software, this step will actually compile OpenLDAP.
224 You should examine the output of this command carefully to make sure
225 everything is built correctly. Note that this command builds the LDAP
226 libraries and associated clients as well as {{slapd}}(8) and {{slurpd}}(8).
229 H2: Testing the Software
231 Once the software has been properly configured and successfully
232 made, you should run the test suite to verify the build.
236 Tests which apply to your configuration will run and they should pass.
237 Some tests, such as the replication test, may be skipped if not supported
238 by your configuration.
241 H2: Installing the Software
243 Once you have successfully tested the software, you are ready to
244 install it. You will need to have write permission to the installation
245 directories you specified when you ran configure. By default
246 OpenLDAP Software is installed in {{F:/usr/local}}. If you changed
247 this setting with the {{EX:--prefix}} configure option, it will be
248 installed in the location you provided.
250 Typically, the installation requires {{super-user}} privileges.
251 From the top level OpenLDAP source directory, type:
253 > su root -c 'make install'
255 and enter the appropriate password when requested.
257 You should examine the output of this command carefully to make sure
258 everything is installed correctly. You will find the configuration files
259 for {{slapd}}(8) in {{F:/usr/local/etc/openldap}} by default. See the
260 chapter {{SECT:The slapd Configuration File}} for additional information.