git.sur5r.net Git - openldap/blob - doc/guide/admin/install.sdf

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