1# $OpenLDAP$ 2# Copyright 1999-2021 The OpenLDAP Foundation, All Rights Reserved. 3# COPYING RESTRICTIONS APPLY, see COPYRIGHT. 4 5H1: Building and Installing OpenLDAP Software 6 7This chapter details how to build and install the {{PRD:OpenLDAP}} 8Software package including {{slapd}}(8), the Standalone {{TERM:LDAP}} 9Daemon. Building and installing OpenLDAP Software requires several 10steps: installing prerequisite software, configuring OpenLDAP 11Software itself, making, and finally installing. The following 12sections describe this process in detail. 13 14 15H2: Obtaining and Extracting the Software 16 17You can obtain OpenLDAP Software from the project's download 18page at {{URL: http://www.openldap.org/software/download/}} or 19directly from the project's {{TERM:FTP}} service at 20{{URL: ftp://ftp.openldap.org/pub/OpenLDAP/}}. 21 22The project makes available two series of packages for {{general 23use}}. The project makes {{releases}} as new features and bug fixes 24come available. Though the project takes steps to improve stability 25of these releases, it is common for problems to arise only after 26{{release}}. The {{stable}} release is the latest {{release}} which 27has demonstrated stability through general use. 28 29Users of OpenLDAP Software can choose, depending on their desire 30for the {{latest features}} versus {{demonstrated stability}}, the 31most appropriate series to install. 32 33After downloading OpenLDAP Software, you need to extract the 34distribution from the compressed archive file and change your working 35directory to the top directory of the distribution: 36 37.{{EX:gunzip -c openldap-VERSION.tgz | tar xf -}} 38.{{EX:cd openldap-VERSION}} 39 40You'll have to replace {{EX:VERSION}} with the version name of 41the release. 42 43You should now review the {{F:COPYRIGHT}}, {{F:LICENSE}}, {{F:README}} 44and {{F:INSTALL}} documents provided with the distribution. The 45{{F:COPYRIGHT}} and {{F:LICENSE}} provide information on acceptable 46use, copying, and limitation of warranty of OpenLDAP Software. The 47{{F:README}} and {{F:INSTALL}} documents provide detailed information 48on prerequisite software and installation procedures. 49 50 51H2: Prerequisite software 52 53OpenLDAP Software relies upon a number of software packages distributed 54by third parties. Depending on the features you intend to use, you 55may have to download and install a number of additional software 56packages. This section details commonly needed third party software 57packages you might have to install. However, for an up-to-date 58prerequisite information, the {{F:README}} document should be 59consulted. Note that some of these third party packages may depend 60on additional software packages. Install each package per the 61installation instructions provided with it. 62 63 64H3: {{TERM[expand]TLS}} 65 66OpenLDAP clients and servers require installation of {{PRD:OpenSSL}} 67 or {{PRD:GnuTLS}} 68{{TERM:TLS}} libraries to provide {{TERM[expand]TLS}} services. Though 69some operating systems may provide these libraries as part of the 70base system or as an optional software component, OpenSSL and GnuTLS 71often require separate installation. 72 73OpenSSL is available from {{URL: http://www.openssl.org/}}. 74GnuTLS is available from {{URL: http://www.gnu.org/software/gnutls/}}. 75 76OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's 77{{EX:configure}} detects a usable TLS library. 78 79 80H3: {{TERM[expand]SASL}} 81 82OpenLDAP clients and servers require installation of {{PRD:Cyrus SASL}} 83libraries to provide {{TERM[expand]SASL}} services. Though 84some operating systems may provide this library as part of the 85base system or as an optional software component, Cyrus SASL 86often requires separate installation. 87 88Cyrus SASL is available from 89{{URL:http://asg.web.cmu.edu/sasl/sasl-library.html}}. 90Cyrus SASL will make use of OpenSSL and Kerberos/GSSAPI libraries 91if preinstalled. 92 93OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's 94configure detects a usable Cyrus SASL installation. 95 96 97H3: {{TERM[expand]Kerberos}} 98 99OpenLDAP clients and servers support {{TERM:Kerberos}} authentication 100services. In particular, OpenLDAP supports the Kerberos V 101{{TERM:GSS-API}} {{TERM:SASL}} authentication mechanism known as 102the {{TERM:GSSAPI}} mechanism. This feature requires, in addition to 103Cyrus SASL libraries, either {{PRD:Heimdal}} or {{PRD:MIT Kerberos}} 104V libraries. 105 106Heimdal Kerberos is available from {{URL:http://www.pdc.kth.se/heimdal/}}. 107MIT Kerberos is available from {{URL:http://web.mit.edu/kerberos/www/}}. 108 109Use of strong authentication services, such as those provided by 110Kerberos, is highly recommended. 111 112 113 114H3: Database Software 115 116OpenLDAP's {{slapd}}(8) {{TERM:MDB}} primary database backend uses the {{TERM:LMDB}} 117software included with the OpenLDAP source. There is no need to download any 118additional software to have {{MDB}} support. 119 120 121 122H3: Threads 123 124OpenLDAP is designed to take advantage of threads. OpenLDAP 125supports POSIX {{pthreads}}, NT threads and a number of 126other varieties. {{EX:configure}} will complain if it cannot 127find a suitable thread subsystem. If this occurs, please 128consult the {{F:Software|Installation|Platform Hints}} section 129of the OpenLDAP FAQ {{URL: http://www.openldap.org/faq/}}. 130 131 132H3: TCP Wrappers 133 134{{slapd}}(8) supports TCP Wrappers (IP level access control filters) 135if preinstalled. Use of TCP Wrappers or other IP-level access 136filters (such as those provided by an IP-level firewall) is recommended 137for servers containing non-public information. 138 139 140H2: Running configure 141 142Now you should probably run the {{EX:configure}} script with the 143{{EX:--help}} option. 144This will give you a list of options that you can change when building 145OpenLDAP. Many of the features of OpenLDAP can be enabled or disabled 146using this method. 147!if 0 148Please see the appendix for a more detailed list of configure options, 149and their usage. 150!endif 151> ./configure --help 152 153The {{EX:configure}} script also looks for certain variables 154on the command line and in the environment. These include: 155 156!block table; align=Center; coltags="EX,N"; title="Table 4.1: Variables" 157Variable Description 158CC Specify alternative C Compiler 159CFLAGS Specify additional compiler flags 160CPPFLAGS Specify C Preprocessor flags 161LDFLAGS Specify linker flags 162LIBS Specify additional libraries 163!endblock 164 165Now run the configure script with any desired configuration options or 166variables. 167 168> ./configure [options] [variable=value ...] 169 170As an example, let's assume that we want to install OpenLDAP with 171MDB backend and TCP Wrappers support. By default, MDB 172is enabled and TCP Wrappers is not. So, we just need to specify 173{{EX:--enable-wrappers}} to include TCP Wrappers support: 174 175> ./configure --enable-wrappers 176 177However, this will fail to locate dependent software not 178installed in system directories. For example, if TCP Wrappers 179headers and libraries are installed in {{F:/usr/local/include}} 180and {{F:/usr/local/lib}} respectively, the {{EX:configure}} 181script should typically be called as follows: 182 183> ./configure --enable-wrappers \ 184> CPPFLAGS="-I/usr/local/include" \ 185> LDFLAGS="-L/usr/local/lib -Wl,-rpath,/usr/local/lib" 186 187The {{EX:configure}} script will normally auto-detect appropriate 188settings. If you have problems at this stage, consult any platform 189specific hints and check your {{EX:configure}} options, if any. 190 191 192H2: Building the Software 193 194Once you have run the {{EX:configure}} script the last line of output 195should be: 196> Please "make depend" to build dependencies 197 198If the last line of output does not match, {{EX:configure}} has failed, 199and you will need to review its output to determine what went wrong. 200You should not proceed until {{EX:configure}} completes successfully. 201 202To build dependencies, run: 203> make depend 204 205Now build the software, this step will actually compile OpenLDAP. 206> make 207 208You should examine the output of this command carefully to make sure 209everything is built correctly. Note that this command builds the LDAP 210libraries and associated clients as well as {{slapd}}(8). 211 212 213H2: Testing the Software 214 215Once the software has been properly configured and successfully 216made, you should run the test suite to verify the build. 217 218> make test 219 220Tests which apply to your configuration will run and they should pass. 221Some tests, such as the replication test, may be skipped if not supported 222by your configuration. 223 224 225H2: Installing the Software 226 227Once you have successfully tested the software, you are ready to 228install it. You will need to have write permission to the installation 229directories you specified when you ran configure. By default 230OpenLDAP Software is installed in {{F:/usr/local}}. If you changed 231this setting with the {{EX:--prefix}} configure option, it will be 232installed in the location you provided. 233 234Typically, the installation requires {{super-user}} privileges. 235From the top level OpenLDAP source directory, type: 236 237> su root -c 'make install' 238 239and enter the appropriate password when requested. 240 241You should examine the output of this command carefully to make sure 242everything is installed correctly. You will find the configuration files 243for {{slapd}}(8) in {{F:/usr/local/etc/openldap}} by default. See the 244chapter {{SECT:Configuring slapd}} for additional information. 245 246