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

   1 # $OpenLDAP$
   2 # Copyright 1999-2018 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:MDB}} primary database backend uses the {{TERM:LMDB}}
 118 software included with the OpenLDAP source.  There is no need to download any
 119 additional software to have {{MDB}} support.
 120
 121 OpenLDAP's {{slapd}}(8) {{TERM:BDB}} and {{TERM:HDB}} deprecated database backends
 122 require {{ORG[expand]Oracle}}'s Berkeley DB.
 123 If not available at configure time, you will not be able to build
 124 {{slapd}}(8) with these deprecated database backends.
 125
 126 Your operating system may provide a supported version of
 127 Berkeley DB in the base system or as an optional
 128 software component.  If not, you'll have to obtain and
 129 install it yourself.  Berkeley DB is available from
 130 {{ORG[expand]Oracle}}'s Berkeley DB download page if required.
 131
 132 There are several versions available from {{ORG[expand]Oracle}}.
 133 Berkeley DB version 6.0.20 and later uses a software license that is
 134 incompatible with LDAP technology and should not be used with OpenLDAP.
 135
 136 Note: Please see {{SECT:Recommended OpenLDAP Software Dependency Versions}} for
 137 more information.
 138
 139
 140 H3: Threads
 141
 142 OpenLDAP is designed to take advantage of threads.  OpenLDAP
 143 supports POSIX {{pthreads}}, Mach {{CThreads}}, and a number of
 144 other varieties.  {{EX:configure}} will complain if it cannot
 145 find a suitable thread subsystem.   If this occurs, please
 146 consult the {{F:Software|Installation|Platform Hints}} section
 147 of the OpenLDAP FAQ {{URL: http://www.openldap.org/faq/}}.
 148
 149
 150 H3: TCP Wrappers
 151
 152 {{slapd}}(8) supports TCP Wrappers (IP level access control filters)
 153 if preinstalled.  Use of TCP Wrappers or other IP-level access
 154 filters (such as those provided by an IP-level firewall) is recommended
 155 for servers containing non-public information.
 156
 157
 158 H2: Running configure
 159
 160 Now you should probably run the {{EX:configure}} script with the
 161 {{EX:--help}} option.
 162 This will give you a list of options that you can change when building
 163 OpenLDAP.  Many of the features of OpenLDAP can be enabled or disabled
 164 using this method.
 165 !if 0
 166 Please see the appendix for a more detailed list of configure options,
 167 and their usage.
 168 !endif
 169 >       ./configure --help
 170
 171 The {{EX:configure}} script also looks for certain variables
 172 on the command line and in the environment.  These include:
 173
 174 !block table; align=Center; coltags="EX,N"; title="Table 4.1: Variables"
 175 Variable        Description
 176 CC              Specify alternative C Compiler
 177 CFLAGS          Specify additional compiler flags
 178 CPPFLAGS        Specify C Preprocessor flags
 179 LDFLAGS         Specify linker flags
 180 LIBS            Specify additional libraries
 181 !endblock
 182
 183 Now run the configure script with any desired configuration options or
 184 variables.
 185
 186 >       ./configure [options] [variable=value ...]
 187
 188 As an example, let's assume that we want to install OpenLDAP with
 189 MDB backend and TCP Wrappers support.  By default, MDB
 190 is enabled and TCP Wrappers is not.  So, we just need to specify
 191 {{EX:--enable-wrappers}} to include TCP Wrappers support:
 192
 193 >       ./configure --enable-wrappers
 194
 195 However, this will fail to locate dependent software not
 196 installed in system directories.  For example, if TCP Wrappers
 197 headers and libraries are installed in {{F:/usr/local/include}}
 198 and {{F:/usr/local/lib}} respectively, the {{EX:configure}}
 199 script should typically be called as follows:
 200
 201 >       ./configure --enable-wrappers \
 202 >               CPPFLAGS="-I/usr/local/include" \
 203 >               LDFLAGS="-L/usr/local/lib -Wl,-rpath,/usr/local/lib"
 204
 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.
 208
 209
 210 H2: Building the Software
 211
 212 Once you have run the {{EX:configure}} script the last line of output
 213 should be:
 214 >       Please "make depend" to build dependencies
 215
 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.
 219
 220 To build dependencies, run:
 221 >       make depend
 222
 223 Now build the software, this step will actually compile OpenLDAP.
 224 >       make
 225
 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).
 229
 230
 231 H2: Testing the Software
 232
 233 Once the software has been properly configured and successfully
 234 made, you should run the test suite to verify the build.
 235
 236 >       make test
 237
 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.
 241
 242
 243 H2: Installing the Software
 244
 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.
 251
 252 Typically, the installation requires {{super-user}} privileges.
 253 From the top level OpenLDAP source directory, type:
 254
 255 >       su root -c 'make install'
 256
 257 and enter the appropriate password when requested.
 258
 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.
 263