X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fguide%2Fadmin%2Finstall.sdf;h=1d4e7b5ab02f1aa183534c6b8787943fb30a51f0;hb=221e0f727be9967543ff6255c05d4221e70338f0;hp=5be34acf6bf3ef07637b81474b7697de753ce95f;hpb=b7b1f8e3ba0012094b89d007a51b0f881cc7e797;p=openldap diff --git a/doc/guide/admin/install.sdf b/doc/guide/admin/install.sdf index 5be34acf6b..1d4e7b5ab0 100644 --- a/doc/guide/admin/install.sdf +++ b/doc/guide/admin/install.sdf @@ -1,256 +1,259 @@ -# Copyright 1999, The OpenLDAP Foundation, All Rights Reserved. +# $OpenLDAP$ +# Copyright 1999-2007 The OpenLDAP Foundation, All Rights Reserved. # COPYING RESTRICTIONS APPLY, see COPYRIGHT. -H1: Building and Installing slapd & slurpd -Building and installing slapd requires three simple steps: configuring; -making; and installing. The following sections describe each step in -detail. If you are reading this guide, chances are you have already -obtained the software, but just in case, here's where you can get the -latest version of the OpenLDAP package, which includes all of the -software discussed in this guide: -{{URL: ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz}} +H1: Building and Installing OpenLDAP Software -There is also an OpenLDAP Project has an extensive site on the -World Wide Web. This sites contains the latest OpenLDAP news, -release announcements, and pointers to other resources. -You can access the site at: {{URL: http://www.OpenLDAP.org/}} +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: Pre-Build Configuration +H2: Obtaining and Extracting the Software -Before building slapd, be sure to take a look at the README file in the -top level directory in the distribution so that you are familiar with the -general configuration and make process. +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/}}. -Briefly, you should edit the include/ldapconfig.h.edit and -Make-common files to contain the site-specific configuration your site -requires before making. The next sections discuss these steps in -more detail. +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. -H3: Editing the {{EX: Make-common}} file +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: -All of the general Make-common configuration variables (e.g., -ETCDIR, BINDIR, etc.) apply to both slapd and slurpd. There are -additional Make-common configuration variables that also affect how -slapd and slurpd are built. They are: +.{{EX:gunzip -c openldap-VERSION.tgz | tar xf -}} +.{{EX:cd openldap-VERSION}} -H4: MAKE_SLAPD +You'll have to replace {{EX:VERSION}} with the version name of +the release. -This option controls whether slapd and slurpd get built at all. You -should set it to yes, like this: +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. -E: MAKE_SLAPD = yes -H4: SLAPD_BACKENDS +H2: Prerequisite software -This option controls which slapd backend databases get built. You -should set it to one or more of the following: +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. -*{{EX: DLDAP_LDBM}} This is the main backend. It is a high-performance -disk-based database suitable for handling up to a million entries or so. -See the LDBMBACKEND and LDBMLIB options below. -*{{EX: DLDAP_PASSWD}} This is a simple search-only backend that can be -pointed at an {{EX: /etc/passwd}} file. It is intended more as an example than -as a real backend. +H3: {{TERM[expand]TLS}} -*{{EX: DLDAP_SHELL}} This backend allows the execution of arbitrary -system administrator-defined commands in response to LDAP -queries. The commands to execute are defined in the configuration file. -See Appendix B for more information on writing shell backend -programs. +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 and GnuTLS often +require separate installation. -Example to enable the LDBM and SHELL backends only: +OpenSSL is available from {{URL: http://www.openssl.org/}}. +GnuTLS is available from {{URL: http://www.gnu.org/software/gnutls/}}. -E: SLAPD_BACKENDS= -DLDAP_LDBM -DLDAP_SHELL +OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's +{{EX:configure}} detects a usable TLS library. -The default is to build all three backends. Note that building a backend -only means that it can be enabled through the configuration file, not -that it will automatically be enabled. -H4: LDBMBACKEND +H3: {{TERM[expand]SASL}} -This option should only be defined if you have enabled the LDBM -backend as described above. The LDBM backend relies on a -low-level hash or B-tree package for its underlying database. This -option selects which package it will use. The currently supported -options in order of preference are: +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. -*{{EX: DLDBM_USE_DBBTREE}} +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. -.This option enables the Berkeley DB package btree database as the -LDBM backend. You can get this package from: -{{URL: ftp://ftp.cs.berkeley.edu/ucb/4bsd/db.tar.Z}} +OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's +configure detects a usable Cyrus SASL installation. -*{{EX: DLDBM_USE_DBHASH}} -.This option enables the Berkeley DB package hash database as the -LDBM backend. You can get this package from -{{URL ftp://ftp.cs.berkeley.edu/ucb/4bsd/db.tar.Z}} +H3: {{TERM[expand]Kerberos}} -*{{EX: DLDBM_USE_GDBM}} +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. -.This option enables GNU dbm as the LDBM backend. You can get this -package from -{{URL: ftp://prep.ai.mit.edu/pub/gnu/gdbm-1.7.3.tar.gz}} +Heimdal Kerberos is available from {{URL:http://www.pdc.kth.se/heimdal/}}. +MIT Kerberos is available from {{URL:http://web.mit.edu/kerberos/www/}}. -*{{EX: DLDBM_USE_NDBM}} +Use of strong authentication services, such as those provided by +Kerberos, is highly recommended. -.This option enables the standard UNIX ndbm(3) package as the -LDBM backend. This package should come standard on your UNIX -system. man ndbm for details. -Example to enable the Berkeley DB Btree backend: -E: LDBMBACKEND= -DLDBM_USE_DBBTREE +H3: Database Software -The default is -DLDBM_USE_NDBM, since it is the only one available -on all UNIX systems. NDBM has some serious limitations, though (not -thread-safe, severe size limits), and you are strongly encouraged to -use one of the other packages if you can. +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. -Note[label='Note to Solaris users: '] If you are running under Solaris 2.x -and linking in an external database package (e.g., db or gdbm) it is -very important that you compile the package with the {{EX: D_REENTRANT}} -flag. If you do not, bad things will happen. +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. -If you are using version 1.85 or earlier of the Berkeley db package, you -will need to apply the patch found in build/db.1.85.patch to the db -source before compiling it. You can do this with a command like this -from the db source area: +{{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. -E: patch -p < ldap-source-directory/build/db.1.85.patch -H4: LDBMLIB +H3: Threads -This option should only be defined if you have enabled the LDBM -backend as described above, and the necessary library for the -LDBMBACKEND option you chose above is not part of the standard C -library (i.e., anything other than NDBM). This option specifies the library -to link containing the package you selected, and optionally, its location. +OpenLDAP is designed to take advantage of threads. OpenLDAP +supports POSIX {{pthreads}}, Mach {{CThreads}}, and a number of +other varieties. {{EX:configure}} will complain if it cannot +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/}}. -Example to link with {{EX: libdb.a}}, contained in {{EX: /usr/local/lib}}: -E: LDBMLIB= -L/usr/local/lib -ldb +H3: TCP Wrappers -H4: THREADS +{{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. -This option is normally set automatically in the {{EX: Make-platform}} file, -based on the platform on which you are building. You do not normally -need to set it. If you want to use a non-default threads package, you -can specify the appropriate {{EX: -Ddefine}} to enable it here. -H4: THREADSLIB +H2: Running configure -This option is normally set automatically in the {{EX: Make-platform}} file, -based on the platform on which you are building. You do not normally -need to set it. If you have set {{EX: THREADS}} to a non-default threads -package as described above, you can specify the appropriate -{{EX: -Ldirectory}} flag and {{EX: -llibname}} flag needed to link -the package here. +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. +!if 0 +Please see the appendix for a more detailed list of configure options, +and their usage. +!endif +> ./configure --help -H4: PHONETIC +The {{EX:configure}} script will also look at various environment variables +for certain settings. These environment variables include: -This option controls the phonetic algorithm used by {{I: slapd}} when doing -approximate searches. The default is to use the metaphone algorithm. -You can have {{I: slapd}} use the soundex algorithm by setting this variable -to {{EX: -DSOUNDEX}}. +!block table; align=Center; coltags="EX,N"; title="Table 4.1: Environment Variables" +Variable Description +CC Specify alternative C Compiler +CFLAGS Specify additional compiler flags +CPPFLAGS Specify C Preprocessor flags +LDFLAGS Specify linker flags +LIBS Specify additional libraries +!endblock +Now run the configure script with any desired configuration options or +environment variables. -H3: Editing the {{EX: include/ldapconfig.h}} file +> [[env] settings] ./configure [options] -In addition to setting the {{EX: LDAPHOST}} and {{EX: DEFAULT_BASE}} defines -near the top of this file, there are some slapd-specific defines near the -bottom of the file you may want to change. The defaults should be just -fine, unless you have special needs. +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: -H4: SLAPD_DEFAULT_CONFIGFILE +> ./configure --with-wrappers -This define sets the location of the default slapd configuration file. -Normally, it is set to {{EX: $(ETCDIR)/slapd.conf}}, where -{{EX: ETCDIR}} comes from Make-common. +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: -H4: SLAPD_DEFAULT_SIZELIMIT +> env CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib" \ +> ./configure --with-wrappers -This define sets the default size limit on the number of entries returned -from a search. This option is configurable via the tailor file, but if you -want to change the default, do it here. +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. -H4: SLAPD_DEFAULT_TIMELIMIT +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. -This define sets the default time limit for a search. This option is -configurable via the tailor file, but if you want to change the default, do it -here. -H4: SLAPD_PIDFILE +H2: Building the Software -This define sets the location of the file to which slapd will write its -process ID when it starts up. +Once you have run the {{EX:configure}} script the last line of output +should be: +> Please "make depend" to build dependencies -H4: SLAPD_ARGSFILE +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. -This define sets the location of the file to which slapd will write its -argument vector when it starts up. +To build dependencies, run: +> make depend -H4: SLAPD_MONITOR_DN +Now build the software, this step will actually compile OpenLDAP. +> make -This define sets the distinguished name used to retrieve monitoring -information from {{I: slapd}}. See section 7 for more details. - -H4: SLAPD_LDBM_MIN_MAXIDS - -This define is only relevant to the LDBM backend. It sets the minimum -number of entry IDs that an index entry will contain before it becomes -an allIDs entry. See Section 9.1 for more details. - - - -H2: Making the Software +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). -Once you have edited the {{EX: include/ldapconfig.h.edit}} file and the -Make-common file (see the top level {{EX: README}} file in the distribution), -you are ready to make the software. From the top level LDAP source -directory, type -E: make +H2: Testing the Software -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 and slurpd. +Once the software has been properly configured and successfully +made, you should run the test suite to verify the build. -Note that the LDAP distribution can support making for multiple -platforms from a single source tree. If you want to do this, consult the -{{EX: INSTALL}} file in the top level distribution directory. +> make test +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 -Once the software has been properly configured and successfully -made, you are ready to install it. You will need to have write permission -to the installation directories you specified in the {{EX: Make-common}} file. -Typically, the installation is done as root. From the top level LDAP -source directory, type - -E: make install +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. -You should examine the output of this command carefully to make sure -everything is installed correctly. Slapd, slurpd, and their configuration -files, {{EX: slapd.conf}}, {{EX: slapd.at.conf}}, and {{EX: slapd.oc.conf}} - will be installed in the {{EX: ETCDIR}} directory you specified -in the {{EX: Make-common}} file. - -This command will install the entire LDAP distribution. If you only want -to install slapd and slurpd, you could do something like this: +Typically, the installation requires {{super-user}} privileges. +From the top level OpenLDAP source directory, type: -E: (cd servers/slapd; make install) +> su root -c 'make install' -E: (cd servers/slurpd; make install) +and enter the appropriate password when requested. -Note: The installation process installs configuration files as well as -binaries. Existing configuration files are first moved to a name with a -dash '-' appended, e.g., {{EX: slapd.conf}} is moved to {{EX: slapd.conf-}}. -If you install things twice, however, you can lose your existing configuration -files. +You should examine the output of this command carefully to make sure +everything is installed correctly. You will find the configuration files +for {{slapd}}(8) in {{F:/usr/local/etc/openldap}} by default. See the +chapter {{SECT:Configuring slapd}} for additional information.