2 # Copyright 1999-2007 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 {{PRD:OpenLDAP}}
8 Software package including {{slapd}}(8), the Standalone {{TERM:LDAP}}
9 Daemon. Building and installing OpenLDAP Software requires several
10 steps: installing prerequisite software, configuring OpenLDAP
11 Software itself, making, and finally installing. The following
12 sections describe this process in detail.
15 H2: Obtaining and Extracting the Software
17 You can obtain OpenLDAP Software from the project's download
18 page at {{URL: http://www.openldap.org/software/download/}} or
19 directly from the project's {{TERM:FTP}} service at
20 {{URL: ftp://ftp.openldap.org/pub/OpenLDAP/}}.
22 The project makes available two series of packages for {{general
23 use}}. The project makes {{releases}} as new features and bug fixes
24 come available. Though the project takes steps to improve stablity
25 of these releases, it is common for problems to arise only after
26 {{release}}. The {{stable}} release is the latest {{release}} which
27 has demonstrated stability through general use.
29 Users of OpenLDAP Software can choose, depending on their desire
30 for the {{latest features}} versus {{demonstrated stability}}, the
31 most appropriate series to install.
33 After downloading OpenLDAP Software, you need to extract the
34 distribution from the compressed archive file and change your working
35 directory to the top directory of the distribution:
37 .{{EX:gunzip -c openldap-VERSION.tgz | tar xf -}}
38 .{{EX:cd openldap-VERSION}}
40 You'll have to replace {{EX:VERSION}} with the version name of
43 You should now review the {{F:COPYRIGHT}}, {{F:LICENSE}}, {{F:README}}
44 and {{F:INSTALL}} documents provided with the distribution. The
45 {{F:COPYRIGHT}} and {{F:LICENSE}} provide information on acceptable
46 use, copying, and limitation of warranty of OpenLDAP Software. The
47 {{F:README}} and {{F:INSTALL}} documents provide detailed information
48 on prerequisite software and installation procedures.
51 H2: Prerequisite software
53 OpenLDAP Software relies upon a number of software packages distributed
54 by third parties. Depending on the features you intend to use, you
55 may have to download and install a number of additional software
56 packages. This section details commonly needed third party software
57 packages you might have to install. However, for an up-to-date
58 prerequisite information, the {{F:README}} document should be
59 consulted. Note that some of these third party packages may depend
60 on additional software packages. Install each package per the
61 installation instructions provided with it.
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: {{TERM[expand]SASL}}
80 OpenLDAP clients and servers require installation of {{PRD:Cyrus SASL}}
81 libraries to provide {{TERM[expand]SASL}} services. Though
82 some operating systems may provide this library as part of the
83 base system or as an optional software component, Cyrus SASL
84 often requires separate installation.
86 Cyrus SASL is available from
87 {{URL:http://asg.web.cmu.edu/sasl/sasl-library.html}}.
88 Cyrus SASL will make use of OpenSSL and Kerberos/GSSAPI libraries
91 OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's
92 configure detects a usable Cyrus SASL installation.
95 H3: {{TERM[expand]Kerberos}}
97 OpenLDAP clients and servers support {{TERM:Kerberos}} authentication
98 services. In particular, OpenLDAP supports the Kerberos V
99 {{TERM:GSS-API}} {{TERM:SASL}} authentication mechanism known as
100 the {{TERM:GSSAPI}} mechanism. This feature requires, in addition to
101 Cyrus SASL libraries, either {{PRD:Heimdal}} or {{PRD:MIT Kerberos}}
104 Heimdal Kerberos is available from {{URL:http://www.pdc.kth.se/heimdal/}}.
105 MIT Kerberos is available from {{URL:http://web.mit.edu/kerberos/www/}}.
107 Use of strong authentication services, such as those provided by
108 Kerberos, is highly recommended.
112 H3: Database Software
114 OpenLDAP's {{slapd}}(8) {{TERM:BDB}} and {{TERM:HDB}} primary database backends
115 require {{ORG[expand]Oracle}} {{PRD:Berkeley DB}}.
116 If not available at configure time, you will not be able build
117 {{slapd}}(8) with these primary database backends.
119 Your operating system may provide a supported version of
120 {{PRD:Berkeley DB}} in the base system or as an optional
121 software component. If not, you'll have to obtain and
124 {{PRD:Berkeley DB}} is available from {{ORG[expand]Oracle}}'s Berkeley DB
126 {{URL: http://www.oracle.com/technology/software/products/berkeley-db/index.html}}. There are several versions available. Generally, the most recent
127 release (with published patches) is recommended. This package is required
128 if you wish to use the {{TERM:BDB}} or {{TERM:HDB}} database backends.
133 OpenLDAP is designed to take advantage of threads. OpenLDAP
134 supports POSIX {{pthreads}}, Mach {{CThreads}}, and a number of
135 other varieties. {{EX:configure}} will complain if it cannot
136 find a suitable thread subsystem. If this occurs, please
137 consult the {{F:Software|Installation|Platform Hints}} section
138 of the OpenLDAP FAQ {{URL: http://www.openldap.org/faq/}}.
143 {{slapd}}(8) supports TCP Wrappers (IP level access control filters)
144 if preinstalled. Use of TCP Wrappers or other IP-level access
145 filters (such as those provided by an IP-level firewall) is recommended
146 for servers containing non-public information.
149 H2: Running configure
151 Now you should probably run the {{EX:configure}} script with the
152 {{EX:--help}} option.
153 This will give you a list of options that you can change when building
154 OpenLDAP. Many of the features of OpenLDAP can be enabled or disabled
157 Please see the appendix for a more detailed list of configure options,
162 The {{EX:configure}} script will also look at various environment variables
163 for certain settings. These environment variables include:
165 !block table; align=Center; coltags="EX,N"; title="Table 4.1: Environment Variables"
167 CC Specify alternative C Compiler
168 CFLAGS Specify additional compiler flags
169 CPPFLAGS Specify C Preprocessor flags
170 LDFLAGS Specify linker flags
171 LIBS Specify additional libraries
174 Now run the configure script with any desired configuration options or
175 environment variables.
177 > [[env] settings] ./configure [options]
179 As an example, let's assume that we want to install OpenLDAP with
180 BDB backend and TCP Wrappers support. By default, BDB
181 is enabled and TCP Wrappers is not. So, we just need to specify
182 {{EX:--with-wrappers}} to include TCP Wrappers support:
184 > ./configure --with-wrappers
186 However, this will fail to locate dependent software not
187 installed in system directories. For example, if TCP Wrappers
188 headers and libraries are installed in {{F:/usr/local/include}}
189 and {{F:/usr/local/lib}} respectively, the {{EX:configure}}
190 script should be called as follows:
192 > env CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib" \
193 > ./configure --with-wrappers
195 Note: Some shells, such as those derived from the Bourne {{sh}}(1),
196 do not require use of the {{env}}(1) command. In some cases, environmental
197 variables have to be specified using alternative syntaxes.
199 The {{EX:configure}} script will normally auto-detect appropriate
200 settings. If you have problems at this stage, consult any platform
201 specific hints and check your {{EX:configure}} options, if any.
204 H2: Building the Software
206 Once you have run the {{EX:configure}} script the last line of output
208 > Please "make depend" to build dependencies
210 If the last line of output does not match, {{EX:configure}} has failed,
211 and you will need to review its output to determine what went wrong.
212 You should not proceed until {{EX:configure}} completes successfully.
214 To build dependencies, run:
217 Now build the software, this step will actually compile OpenLDAP.
220 You should examine the output of this command carefully to make sure
221 everything is built correctly. Note that this command builds the LDAP
222 libraries and associated clients as well as {{slapd}}(8).
225 H2: Testing the Software
227 Once the software has been properly configured and successfully
228 made, you should run the test suite to verify the build.
232 Tests which apply to your configuration will run and they should pass.
233 Some tests, such as the replication test, may be skipped if not supported
234 by your configuration.
237 H2: Installing the Software
239 Once you have successfully tested the software, you are ready to
240 install it. You will need to have write permission to the installation
241 directories you specified when you ran configure. By default
242 OpenLDAP Software is installed in {{F:/usr/local}}. If you changed
243 this setting with the {{EX:--prefix}} configure option, it will be
244 installed in the location you provided.
246 Typically, the installation requires {{super-user}} privileges.
247 From the top level OpenLDAP source directory, type:
249 > su root -c 'make install'
251 and enter the appropriate password when requested.
253 You should examine the output of this command carefully to make sure
254 everything is installed correctly. You will find the configuration files
255 for {{slapd}}(8) in {{F:/usr/local/etc/openldap}} by default. See the
256 chapter {{SECT:Configuring slapd}} for additional information.