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

   1 # $OpenLDAP$
   2 # Copyright 1999-2005, 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 {{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.
  14
  15
  16 H2: Obtaining and Extracting the Software
  17
  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/}}.
  22
  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.
  29
  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.
  33
  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:
  37
  38 .{{EX:gunzip -c openldap-VERSION.tgz | tar xf -}}
  39 .{{EX:cd openldap-VERSION}}
  40
  41 You'll have to replace {{EX:VERSION}} with the version name of
  42 the release.
  43
  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.
  50
  51
  52 H2: Prerequisite software
  53
  54 OpenLDAP Software relies upon a number of software packages distributed
  55 by third parties.  Depending on the features you intend to use, you
  56 may have to download and install a number of additional software
  57 packages.  This section details commonly needed third party software
  58 packages you might have to install.  However, for an up-to-date
  59 prerequisite information, the {{F:README}} document should be
  60 consulted.  Note that some of these third party packages may depend
  61 on additional software packages.  Install each package per the
  62 installation instructions provided with it.
  63
  64
  65 H3: {{TERM[expand]TLS}}
  66
  67 OpenLDAP clients and servers require installation of {{PRD:OpenSSL}}
  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 often
  71 requires separate installation.
  72
  73 OpenSSL is available from {{URL: http://www.openssl.org/}}.
  74
  75 OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's
  76 {{EX:configure}} detects a usable OpenSSL installation.
  77
  78
  79 H3: Kerberos Authentication Services
  80
  81 OpenLDAP clients and servers support Kerberos-based authentication
  82 services.
  83 In particular, OpenLDAP supports the {{TERM:SASL}}/{{TERM:GSSAPI}}
  84 authentication mechanism using either {{PRD:Heimdal}} or
  85 {{PRD:MIT Kerberos}} V packages.
  86 If you desire to use Kerberos-based SASL/GSSAPI authentication,
  87 you should install either Heimdal or MIT Kerberos V.
  88
  89 Heimdal Kerberos is available from {{URL:http://www.pdc.kth.se/heimdal/}}.
  90 MIT Kerberos is available from {{URL:http://web.mit.edu/kerberos/www/}}.
  91
  92 Use of strong authentication services, such as those provided by
  93 Kerberos, is highly recommended.
  94
  95
  96 H3: {{TERM[expand]SASL}}
  97
  98 OpenLDAP clients and servers require installation of {{PRD:Cyrus}}'s
  99 {{PRD:SASL}} libraries to provide {{TERM[expand]SASL}} services.  Though
 100 some operating systems may provide this library as part of the
 101 base system or as an optional software component, Cyrus SASL
 102 often requires separate installation.
 103
 104 Cyrus SASL is available from
 105 {{URL:http://asg.web.cmu.edu/sasl/sasl-library.html}}.
 106 Cyrus SASL will make use of OpenSSL and Kerberos/GSSAPI libraries
 107 if preinstalled.
 108
 109 OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's
 110 configure detects a usable Cyrus SASL installation.
 111
 112
 113 H3: Database Software
 114
 115 OpenLDAP's {{slapd}}(8) primary database backend, {{TERM:BDB}},
 116 requires {{ORG[expand]Sleepycat}} {{PRD:Berkeley DB}}.
 117 If not available at configure time, you will not be able build
 118 {{slapd}}(8) with this primary database backend.
 119
 120 Your operating system may provide a supported version of
 121 {{PRD:Berkeley DB}} in the base system or as an optional
 122 software component.  If not, you'll have to obtain and
 123 install it yourself.
 124
 125 {{PRD:Berkeley DB}} is available from {{ORG[expand]Sleepycat}}'s
 126 download page {{URL: http://www.sleepycat.com/download/}}.  There
 127 are several versions available.  Generally, the most recent release
 128 (with published patches) is recommended.  This package is required
 129 if you wish to use the {{TERM:BDB}} database backend.
 130
 131 OpenLDAP's {{slapd}}(8) LDBM backend supports a variety of data
 132 base managers including {{PRD:Berkeley DB}} and {{PRD:GDBM}}.
 133 {{PRD:GDBM}} is available from {{ORG:FSF}}'s download site {{URL:
 134 ftp://ftp.gnu.org/pub/gnu/gdbm/}}.
 135
 136
 137 H3: Threads
 138
 139 OpenLDAP is designed to take advantage of threads.  OpenLDAP
 140 supports POSIX {{pthreads}}, Mach {{CThreads}}, and a number of
 141 other varieties.  {{EX:configure}} will complain if it cannot
 142 find a suitable thread subsystem.   If this occurs, please
 143 consult the {{F:Software|Installation|Platform Hints}} section
 144 of the OpenLDAP FAQ {{URL: http://www.openldap.org/faq/}}.
 145
 146
 147 H3: TCP Wrappers
 148
 149 {{slapd}}(8) supports TCP Wrappers (IP level access control filters)
 150 if preinstalled.  Use of TCP Wrappers or other IP-level access
 151 filters (such as those provided by an IP-level firewall) is recommended
 152 for servers containing non-public information.
 153
 154
 155 H2: Running configure
 156
 157 Now you should probably run the {{EX:configure}} script with the
 158 {{EX:--help}} option.
 159 This will give you a list of options that you can change when building
 160 OpenLDAP.  Many of the features of OpenLDAP can be enabled or disabled
 161 using this method.
 162 !if 0
 163 Please see the appendix for a more detailed list of configure options,
 164 and their usage.
 165 !endif
 166 >       ./configure --help
 167
 168 The {{EX:configure}} script will also look at various environment variables
 169 for certain settings.  These environment variables include:
 170
 171 !block table; align=Center; coltags="EX,N"; title="Table 4.1: Environment Variables"
 172 Variable        Description
 173 CC              Specify alternative C Compiler
 174 CFLAGS          Specify additional compiler flags
 175 CPPFLAGS        Specify C Preprocessor flags
 176 LDFLAGS         Specify linker flags
 177 LIBS            Specify additional libraries
 178 !endblock
 179
 180 Now run the configure script with any desired configuration options or
 181 environment variables.
 182
 183 >       [[env] settings] ./configure [options]
 184
 185 As an example, let's assume that we want to install OpenLDAP with
 186 BDB backend and TCP Wrappers support.  By default, BDB
 187 is enabled and TCP Wrappers is not.  So, we just need to specify
 188 {{EX:--with-wrappers}} to include TCP Wrappers support:
 189
 190 >       ./configure --with-wrappers
 191
 192 However, this will fail to locate dependent software not
 193 installed in system directories.  For example, if TCP Wrappers
 194 headers and libraries are installed in {{F:/usr/local/include}}
 195 and {{F:/usr/local/lib}} respectively, the {{EX:configure}}
 196 script should be called as follows:
 197
 198 >       env CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib" \
 199 >               ./configure --with-wrappers
 200
 201 Note: Some shells, such as those derived from the Bourne {{sh}}(1),
 202 do not require use of the {{env}}(1) command.  In some cases, environmental
 203 variables have to be specified using alternative syntaxes.
 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) and {{slurpd}}(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:The slapd Configuration File}} for additional information.
 263