X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fguide%2Fadmin%2Finstall.sdf;h=1d4e7b5ab02f1aa183534c6b8787943fb30a51f0;hb=221e0f727be9967543ff6255c05d4221e70338f0;hp=8876bb0f27912e24fab8194f0f070b6b0f5198d5;hpb=e70eadc2c5ae0f8855ab3f27cd8fc57474bbc19f;p=openldap diff --git a/doc/guide/admin/install.sdf b/doc/guide/admin/install.sdf index 8876bb0f27..1d4e7b5ab0 100644 --- a/doc/guide/admin/install.sdf +++ b/doc/guide/admin/install.sdf @@ -1,109 +1,134 @@ # $OpenLDAP$ -# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved. +# Copyright 1999-2007 The OpenLDAP Foundation, All Rights Reserved. # COPYING RESTRICTIONS APPLY, see COPYRIGHT. + H1: Building and Installing OpenLDAP Software -This chapter details how to build and install the {{ORG:OpenLDAP}} -Software package including {{slapd}}(8), the stand-alone LDAP -daemon and {{slurpd}}(8), the stand-alone update replication daemon. - -Building and installing OpenLDAP requires several steps: installing -prerequisite software, configuring OpenLDAP itself, making, and finally -installing. The following sections describe this process in detail. - -In case you haven't already obtained OpenLDAP it is available at the following -location: {{URL: ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz}} - -The {{ORG[expand]OLP}} also maintains an extensive site -({{URL:http://www.OpenLDAP.org/}}) on the World Wide Web. The site -makes available a number of resources which you may utilize to -properly install OpenLDAP Software. This includes: - -!block table; align=Center; coltags="N,URL" -Resource URL -Documentation Catalog http://www.OpenLDAP.org/doc/ -Frequently Asked Questions http://www.OpenLDAP.org/faq/ -Issue Tracking System http://www.OpenLDAP.org/its/ -Mailing Lists http://www.OpenLDAP.org/lists/ -Software Pages http://www.OpenLDAP.org/software/ -Support Page http://www.OpenLDAP.org/support/ -!endblock - +This chapter details how to build and install the {{PRD:OpenLDAP}} +Software package including {{slapd}}(8), the Standalone {{TERM:LDAP}} +Daemon. Building and installing OpenLDAP Software requires several +steps: installing prerequisite software, configuring OpenLDAP +Software itself, making, and finally installing. The following +sections describe this process in detail. + + +H2: Obtaining and Extracting the Software + +You can obtain OpenLDAP Software from the project's download +page at {{URL: http://www.openldap.org/software/download/}} or +directly from the project's {{TERM:FTP}} service at +{{URL: ftp://ftp.openldap.org/pub/OpenLDAP/}}. + +The project makes available two series of packages for {{general +use}}. The project makes {{releases}} as new features and bug fixes +come available. Though the project takes steps to improve stability +of these releases, it is common for problems to arise only after +{{release}}. The {{stable}} release is the latest {{release}} which +has demonstrated stability through general use. + +Users of OpenLDAP Software can choose, depending on their desire +for the {{latest features}} versus {{demonstrated stability}}, the +most appropriate series to install. + +After downloading OpenLDAP Software, you need to extract the +distribution from the compressed archive file and change your working +directory to the top directory of the distribution: + +.{{EX:gunzip -c openldap-VERSION.tgz | tar xf -}} +.{{EX:cd openldap-VERSION}} + +You'll have to replace {{EX:VERSION}} with the version name of +the release. + +You should now review the {{F:COPYRIGHT}}, {{F:LICENSE}}, {{F:README}} +and {{F:INSTALL}} documents provided with the distribution. The +{{F:COPYRIGHT}} and {{F:LICENSE}} provide information on acceptable +use, copying, and limitation of warranty of OpenLDAP Software. The +{{F:README}} and {{F:INSTALL}} documents provide detailed information +on prerequisite software and installation procedures. + + H2: Prerequisite software -OpenLDAP relies a number of software packages distributed by third -parties. Depending on the features you intend to use, you may have -to download and install a number of additional software packages. -This section details commonly needed third party software packages -you might have to install. Note that some of these third party -packages may depend on additional software packages. Install each -package per installation instructions provided with it. +OpenLDAP Software relies upon a number of software packages distributed +by third parties. Depending on the features you intend to use, you +may have to download and install a number of additional software +packages. This section details commonly needed third party software +packages you might have to install. However, for an up-to-date +prerequisite information, the {{F:README}} document should be +consulted. Note that some of these third party packages may depend +on additional software packages. Install each package per the +installation instructions provided with it. + H3: {{TERM[expand]TLS}} -OpenLDAP clients and servers require installation of {{PRD:OpenSSL}} +OpenLDAP clients and servers require installation of either {{PRD:OpenSSL}} +or {{PRD:GnuTLS}} {{TERM:TLS}} libraries to provide {{TERM[expand]TLS}} services. Though some operating systems may provide these libraries as part of the -base system or as an optional software component, OpenSSL often -requires separate installation. +base system or as an optional software component, OpenSSL and GnuTLS often +require separate installation. OpenSSL is available from {{URL: http://www.openssl.org/}}. +GnuTLS is available from {{URL: http://www.gnu.org/software/gnutls/}}. -OpenLDAP will not be fully LDAPv3 compliant unless OpenLDAP's -{{EX:configure}} detects a usable OpenSSL installation. - -H3: Kerberos Authentication Services +OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's +{{EX:configure}} detects a usable TLS library. -OpenLDAP clients and servers support Kerberos based authentication -services. -In particular, OpenLDAP supports {{TERM:SASL}}/{{TERM:GSSAPI}} based -authentication using either {{PRD:Heimdal}} or {{PRD:MIT Kerberos}} -V packages. -If you desire to use Kerberos based authentication, you should -install either Heimdal or MIT Kerberos V. - -Heimdal Kerberos is available from {{URL:http://www.pdc.kth.se/heimdal/}}. -MIT Kerberos is available from {{URL:http://web.mit.edu/kerberos/www/}}. - -Use of strong authentication services, such as those provided by -Kerberos, is highly recommended. H3: {{TERM[expand]SASL}} -OpenLDAP clients and servers require installation of {{PRD:Cyrus}} -SASL libraries to provide {{TERM[expand]SASL}} services. Though +OpenLDAP clients and servers require installation of {{PRD:Cyrus SASL}} +libraries to provide {{TERM[expand]SASL}} services. Though some operating systems may provide this library as part of the base system or as an optional software component, Cyrus SASL often requires separate installation. -Cyrus SASL is available from {{URL:http://asg.cmu.edu/cyrus/sasl/}}. +Cyrus SASL is available from +{{URL:http://asg.web.cmu.edu/sasl/sasl-library.html}}. Cyrus SASL will make use of OpenSSL and Kerberos/GSSAPI libraries if preinstalled. -OpenLDAP will not be fully LDAPv3 compliant unless OpenLDAP's +OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's configure detects a usable Cyrus SASL installation. -H3: Database software -OpenLDAP's {{slapd}}(8) primary database backend, {{TERM:LDBM}}, -requires that a compatible database package for entry storage. LDBM -is compatible with {{ORG[expand]Sleepy}}'s {{PRD:BerkeleyDB}} (recommended) -or the {{ORG[expand]FSF}}'s {{PRD:GNU}} Database Manager ({{PRD:GDBM}}). -If neither of these packages are available at configure time, -you will not be able build slapd(8) with primary database backend. +H3: {{TERM[expand]Kerberos}} + +OpenLDAP clients and servers support {{TERM:Kerberos}} authentication +services. In particular, OpenLDAP supports the Kerberos V +{{TERM:GSS-API}} {{TERM:SASL}} authentication mechanism known as +the {{TERM:GSSAPI}} mechanism. This feature requires, in addition to +Cyrus SASL libraries, either {{PRD:Heimdal}} or {{PRD:MIT Kerberos}} +V libraries. + +Heimdal Kerberos is available from {{URL:http://www.pdc.kth.se/heimdal/}}. +MIT Kerberos is available from {{URL:http://web.mit.edu/kerberos/www/}}. + +Use of strong authentication services, such as those provided by +Kerberos, is highly recommended. + + + +H3: Database Software -Your operating system may provide one of these two packages in -in base system or as an optional software component. You may -need may need to obtain the software and install it yourself. +OpenLDAP's {{slapd}}(8) {{TERM:BDB}} and {{TERM:HDB}} primary database backends +require {{ORG[expand]Oracle}} {{PRD:Berkeley DB}}. +If not available at configure time, you will not be able build +{{slapd}}(8) with these primary database backends. -{{PRD:BerkeleyDB}} is available from {{ORG[expand]Sleepy}}'s -download page {{URL: http://www.sleepycat.com/download.html}}. -There are several versions available. At the time of this writing, -the latest release, version 3.1, is recommended. +Your operating system may provide a supported version of +{{PRD:Berkeley DB}} in the base system or as an optional +software component. If not, you'll have to obtain and +install it yourself. + +{{PRD:Berkeley DB}} is available from {{ORG[expand]Oracle}}'s Berkeley DB +download page +{{URL: http://www.oracle.com/technology/software/products/berkeley-db/index.html}}. There are several versions available. Generally, the most recent +release (with published patches) is recommended. This package is required +if you wish to use the {{TERM:BDB}} or {{TERM:HDB}} database backends. -{{PRD:GDBM}} is available from {{ORG:FSF}}'s download site -{{URL: ftp://ftp.gnu.org/pub/gnu/gdbm/}}. -At the time of this writing, version 1.8 is the latest release. H3: Threads @@ -114,39 +139,30 @@ find a suitable thread subsystem. If this occurs, please consult the {{F:Software|Installation|Platform Hints}} section of the OpenLDAP FAQ {{URL: http://www.openldap.org/faq/}}. + H3: TCP Wrappers -{{slapd}}(8) supports TCP wrappers (IP level access control filters) -if preinstalled. Use of TCP wrappers or other IP level access -filters (such as those provided by IP firewall) is recommended +{{slapd}}(8) supports TCP Wrappers (IP level access control filters) +if preinstalled. Use of TCP Wrappers or other IP-level access +filters (such as those provided by an IP-level firewall) is recommended for servers containing non-public information. -H2: Configuring OpenLDAP - -If you haven't already done so, extra the distribution for the -compressed archive file and change directory to the top of the -distribution: - -.{{EX:gunzip -c openldap-VERSION.tgz | tar xf -}} -.{{EX:cd openldap-VERSION}} - -Replacing {{EX:VERSION}} with the appropriate version string. - -Note: If you intend to build OpenLDAP for multiple platforms from a -single source tree you should consult the {{F: INSTALL}} file in the -top level distribution directory before running {{EX:configure}}. +H2: Running configure Now you should probably run the {{EX:configure}} script with the {{EX:--help}} option. This will give you a list of options that you can change when building OpenLDAP. Many of the features of OpenLDAP can be enabled or disabled -using this method. Please see the appendix for a more detailed list -of configure options, and their usage. -.{{EX:./configure --help}} +using this method. +!if 0 +Please see the appendix for a more detailed list of configure options, +and their usage. +!endif +> ./configure --help -The {{EX:configure}} script will also look at certain environment variables -for certain settings. These environment variables are: +The {{EX:configure}} script will also look at various environment variables +for certain settings. These environment variables include: !block table; align=Center; coltags="EX,N"; title="Table 4.1: Environment Variables" Variable Description @@ -157,38 +173,35 @@ LDFLAGS Specify linker flags LIBS Specify additional libraries !endblock -Now run the configure script with any desired configure options or +Now run the configure script with any desired configuration options or environment variables. > [[env] settings] ./configure [options] -As an example, lets assume that we want a copy of OpenLDAP configured to use the -LDBM backend, and the shell backend. The LDBM backend is turned on by default, so we don't need to do anything special to enable it. +As an example, let's assume that we want to install OpenLDAP with +BDB backend and TCP Wrappers support. By default, BDB +is enabled and TCP Wrappers is not. So, we just need to specify +{{EX:--with-wrappers}} to include TCP Wrappers support: -Additionally, we've installed the BerkeleyDB database package. -{{EX:configure}} is smart enough to use BerkeleyDB automatically -if it can find it, but BerkeleyDB is installed by default in a -place {{EX:configure}} won't look at automatically. BerkeleyDB -is usually installed in {{F:/usr/local/BerkeleyDB.3.1}} (assuming -that version 3.1 is being used.) +> ./configure --with-wrappers -The following example shows how to run {{EX:configure}} and specify where to -find BerkeleyDB and turn on the DNS-SRV backend. The example should be -entered on a single line (it has been split onto separate lines for clarity.) +However, this will fail to locate dependent software not +installed in system directories. For example, if TCP Wrappers +headers and libraries are installed in {{F:/usr/local/include}} +and {{F:/usr/local/lib}} respectively, the {{EX:configure}} +script should be called as follows: -> env CPPFLAGS="-I/usr/local/BerkeleyDB.3.1/include" \ -> LDFLAGS="-L/usr/local/BerkeleyDB.3.1/lib" \ -> ./configure --enable-dnssrv +> env CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib" \ +> ./configure --with-wrappers Note: Some shells, such as those derived from the Bourne {{sh}}(1), do not require use of the {{env}}(1) command. In some cases, environmental variables have to be specified using alternative syntaxes. -For more information on backends see the chapter on configuration. +The {{EX:configure}} script will normally auto-detect appropriate +settings. If you have problems at this stage, consult any platform +specific hints and check your {{EX:configure}} options, if any. -The {{EX:configure}} script will normally auto-detect appropriate settings. -If you have problems at this stage, consult any platform specific -hints and check your {{EX:configure}} options if any. H2: Building the Software @@ -196,7 +209,8 @@ Once you have run the {{EX:configure}} script the last line of output should be: > Please "make depend" to build dependencies -If the last line of output does not match, {{EX:configure}} has failed. +If the last line of output does not match, {{EX:configure}} has failed, +and you will need to review its output to determine what went wrong. You should not proceed until {{EX:configure}} completes successfully. To build dependencies, run: @@ -206,8 +220,9 @@ Now build the software, this step will actually compile OpenLDAP. > make You should examine the output of this command carefully to make sure -everything is built correctly. Note that this command builds the LDAP -libraries and associated clients as well as {{slapd}}(8) and {{slurpd}}(8). +everything is built correctly. Note that this command builds the LDAP +libraries and associated clients as well as {{slapd}}(8). + H2: Testing the Software @@ -216,24 +231,29 @@ made, you should run the test suite to verify the build. > make test -The test will run a number of tests. +Tests which apply to your configuration will run and they should pass. +Some tests, such as the replication test, may be skipped if not supported +by your configuration. + H2: Installing the Software -One you have successfully tested the software, you are ready to install it. -You will need to have write permission -to the installation directories you specified when you ran configure. -By default OpenLDAP is installed in {{F:/usr/local}}. If you changed this -setting with the {{F:--prefix}} configure option, it will be installed -in the location you provided. +Once you have successfully tested the software, you are ready to +install it. You will need to have write permission to the installation +directories you specified when you ran configure. By default +OpenLDAP Software is installed in {{F:/usr/local}}. If you changed +this setting with the {{EX:--prefix}} configure option, it will be +installed in the location you provided. + +Typically, the installation requires {{super-user}} privileges. +From the top level OpenLDAP source directory, type: -Typically, the installation is done as {{root}}. From the top level OpenLDAP -source directory, type: +> su root -c 'make install' -> make install +and enter the appropriate password when requested. You should examine the output of this command carefully to make sure everything is installed correctly. You will find the configuration files -for slapd in {{F:/usr/local/etc/openldap}} by default. See chapter 5 for more -information on the configuration files. +for {{slapd}}(8) in {{F:/usr/local/etc/openldap}} by default. See the +chapter {{SECT:Configuring slapd}} for additional information.