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