]> git.sur5r.net Git - openldap/blob - doc/guide/admin/install.sdf
Merge remote-tracking branch 'origin/mdb.master'
[openldap] / doc / guide / admin / install.sdf
1 # $OpenLDAP$
2 # Copyright 1999-2012 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4
5 H1: Building and Installing OpenLDAP Software
6
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.
13
14
15 H2: Obtaining and Extracting the Software
16
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/}}.
21
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 stability
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.
28
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.
32
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:
36
37 .{{EX:gunzip -c openldap-VERSION.tgz | tar xf -}}
38 .{{EX:cd openldap-VERSION}}
39
40 You'll have to replace {{EX:VERSION}} with the version name of
41 the release.
42
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.
49
50
51 H2: Prerequisite software
52
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.
62
63
64 H3: {{TERM[expand]TLS}}
65
66 OpenLDAP clients and servers require installation of {{PRD:OpenSSL}},
67  {{PRD:GnuTLS}}, or {{PRD:MozNSS}}
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, GnuTLS, and
71 Mozilla NSS often require separate installation.
72
73 OpenSSL is available from {{URL: http://www.openssl.org/}}.
74 GnuTLS is available from {{URL: http://www.gnu.org/software/gnutls/}}.
75 Mozilla NSS is available from {{URL: http://developer.mozilla.org/en/NSS}}.
76
77 OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's
78 {{EX:configure}} detects a usable TLS library.
79
80
81 H3: {{TERM[expand]SASL}}
82
83 OpenLDAP clients and servers require installation of {{PRD:Cyrus SASL}} 
84 libraries to provide {{TERM[expand]SASL}} services.  Though
85 some operating systems may provide this library as part of the
86 base system or as an optional software component, Cyrus SASL
87 often requires separate installation.
88
89 Cyrus SASL is available from
90 {{URL:http://asg.web.cmu.edu/sasl/sasl-library.html}}.
91 Cyrus SASL will make use of OpenSSL and Kerberos/GSSAPI libraries
92 if preinstalled.
93
94 OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's
95 configure detects a usable Cyrus SASL installation.
96
97
98 H3: {{TERM[expand]Kerberos}}
99
100 OpenLDAP clients and servers support {{TERM:Kerberos}} authentication
101 services.  In particular, OpenLDAP supports the Kerberos V
102 {{TERM:GSS-API}} {{TERM:SASL}} authentication mechanism known as
103 the {{TERM:GSSAPI}} mechanism.  This feature requires, in addition to
104 Cyrus SASL libraries, either {{PRD:Heimdal}} or {{PRD:MIT Kerberos}}
105 V libraries.
106
107 Heimdal Kerberos is available from {{URL:http://www.pdc.kth.se/heimdal/}}.
108 MIT Kerberos is available from {{URL:http://web.mit.edu/kerberos/www/}}.
109
110 Use of strong authentication services, such as those provided by
111 Kerberos, is highly recommended.
112
113
114
115 H3: Database Software
116
117 OpenLDAP's {{slapd}}(8) {{TERM:BDB}} and {{TERM:HDB}} primary database backends
118 require {{ORG[expand]Oracle}} {{PRD:Berkeley DB}}.
119 If not available at configure time, you will not be able to build
120 {{slapd}}(8) with these primary database backends.
121
122 Your operating system may provide a supported version of
123 {{PRD:Berkeley DB}} in the base system or as an optional
124 software component.  If not, you'll have to obtain and
125 install it yourself.
126
127 {{PRD:Berkeley DB}} is available from {{ORG[expand]Oracle}}'s Berkeley DB
128 download page
129 {{URL: http://www.oracle.com/technology/software/products/berkeley-db/index.html}}.  
130
131 There are several versions available. Generally, the most recent
132 release (with published patches) is recommended. This package is required
133 if you wish to use the {{TERM:BDB}} or {{TERM:HDB}} database backends.
134
135 Note: Please see {{SECT:Recommended OpenLDAP Software Dependency Versions}} for
136 more information.
137
138
139 H3: Threads
140
141 OpenLDAP is designed to take advantage of threads.  OpenLDAP
142 supports POSIX {{pthreads}}, Mach {{CThreads}}, and a number of
143 other varieties.  {{EX:configure}} will complain if it cannot
144 find a suitable thread subsystem.   If this occurs, please
145 consult the {{F:Software|Installation|Platform Hints}} section
146 of the OpenLDAP FAQ {{URL: http://www.openldap.org/faq/}}.
147
148
149 H3: TCP Wrappers
150
151 {{slapd}}(8) supports TCP Wrappers (IP level access control filters)
152 if preinstalled.  Use of TCP Wrappers or other IP-level access
153 filters (such as those provided by an IP-level firewall) is recommended
154 for servers containing non-public information.
155
156
157 H2: Running configure
158
159 Now you should probably run the {{EX:configure}} script with the
160 {{EX:--help}} option.
161 This will give you a list of options that you can change when building
162 OpenLDAP.  Many of the features of OpenLDAP can be enabled or disabled
163 using this method.
164 !if 0
165 Please see the appendix for a more detailed list of configure options,
166 and their usage.
167 !endif
168 >       ./configure --help
169
170 The {{EX:configure}} script also looks for certain variables
171 on the command line and in the environment.  These include:
172
173 !block table; align=Center; coltags="EX,N"; title="Table 4.1: Variables"
174 Variable        Description
175 CC              Specify alternative C Compiler
176 CFLAGS          Specify additional compiler flags
177 CPPFLAGS        Specify C Preprocessor flags
178 LDFLAGS         Specify linker flags
179 LIBS            Specify additional libraries
180 !endblock
181
182 Now run the configure script with any desired configuration options or
183 variables.
184
185 >       ./configure [options] [variable=value ...]
186
187 As an example, let's assume that we want to install OpenLDAP with
188 BDB backend and TCP Wrappers support.  By default, BDB
189 is enabled and TCP Wrappers is not.  So, we just need to specify
190 {{EX:--enable-wrappers}} to include TCP Wrappers support:
191
192 >       ./configure --enable-wrappers
193
194 However, this will fail to locate dependent software not
195 installed in system directories.  For example, if TCP Wrappers
196 headers and libraries are installed in {{F:/usr/local/include}}
197 and {{F:/usr/local/lib}} respectively, the {{EX:configure}}
198 script should typically be called as follows:
199
200 >       ./configure --enable-wrappers \
201 >               CPPFLAGS="-I/usr/local/include" \
202 >               LDFLAGS="-L/usr/local/lib -Wl,-rpath,/usr/local/lib"
203
204 The {{EX:configure}} script will normally auto-detect appropriate
205 settings.  If you have problems at this stage, consult any platform
206 specific hints and check your {{EX:configure}} options, if any.
207
208
209 H2: Building the Software
210
211 Once you have run the {{EX:configure}} script the last line of output
212 should be:
213 >       Please "make depend" to build dependencies
214
215 If the last line of output does not match, {{EX:configure}} has failed,
216 and you will need to review its output to determine what went wrong.
217 You should not proceed until {{EX:configure}} completes successfully.
218
219 To build dependencies, run:
220 >       make depend
221
222 Now build the software, this step will actually compile OpenLDAP.
223 >       make
224
225 You should examine the output of this command carefully to make sure
226 everything is built correctly.  Note that this command builds the LDAP
227 libraries and associated clients as well as {{slapd}}(8).
228
229
230 H2: Testing the Software
231
232 Once the software has been properly configured and successfully
233 made, you should run the test suite to verify the build.
234
235 >       make test
236
237 Tests which apply to your configuration will run and they should pass.
238 Some tests, such as the replication test, may be skipped if not supported
239 by your configuration.
240
241
242 H2: Installing the Software
243
244 Once you have successfully tested the software, you are ready to
245 install it.  You will need to have write permission to the installation
246 directories you specified when you ran configure.  By default
247 OpenLDAP Software is installed in {{F:/usr/local}}.  If you changed
248 this setting with the {{EX:--prefix}} configure option, it will be
249 installed in the location you provided.
250
251 Typically, the installation requires {{super-user}} privileges.
252 From the top level OpenLDAP source directory, type:
253
254 >       su root -c 'make install'
255
256 and enter the appropriate password when requested.
257
258 You should examine the output of this command carefully to make sure
259 everything is installed correctly. You will find the configuration files
260 for {{slapd}}(8) in {{F:/usr/local/etc/openldap}} by default.  See the
261 chapter {{SECT:Configuring slapd}} for additional information.
262