X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fguide%2Fadmin%2Finstall.sdf;h=92d0a902c9fb1dcccd33ca50c06b83510e85a48e;hb=65acab0edd99e1b3c888c5ca6c899a450d4d526a;hp=0728e36fc8f909b957f5d0b26bae07ed85be6aba;hpb=9bf1190a20bae790de3ca9b8d43221b69e534d86;p=openldap diff --git a/doc/guide/admin/install.sdf b/doc/guide/admin/install.sdf index 0728e36fc8..92d0a902c9 100644 --- a/doc/guide/admin/install.sdf +++ b/doc/guide/admin/install.sdf @@ -1,257 +1,253 @@ # $OpenLDAP$ # Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved. # COPYING RESTRICTIONS APPLY, see COPYRIGHT. -H1: Building and Installing slapd & slurpd +H1: Building and Installing OpenLDAP Software -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}} +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}}. -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/}} +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"; \ + title="Table 4.1: Other OpenLDAP resources" +Resource URL +Document 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 + +H2: Prerequisite software -H2: Pre-Build Configuration +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. Note that some of +these third party packages may depend on additional software +packages. Install each package per installation instructions +provided with it. -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. +H3: {{TERM[expand]TLS}} -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. +OpenLDAP clients and servers require installation of {{PRD:OpenSSL}} +{{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. +OpenSSL is available from {{URL: http://www.openssl.org/}}. -H3: Editing the {{EX: Make-common}} file +OpenLDAP will not be fully LDAPv3 compliant unless OpenLDAP's +{{EX:configure}} detects a usable OpenSSL installation. -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: -H4: MAKE_SLAPD +H3: Kerberos Authentication Services -This option controls whether slapd and slurpd get built at all. You -should set it to yes, like this: +OpenLDAP clients and servers support Kerberos-based authentication +services. +In particular, OpenLDAP supports {{TERM:SASL}}/{{TERM:GSSAPI}} +authentication mechanism using either {{PRD:Heimdal}} or +{{PRD:MIT Kerberos}} V packages. +If you desire to use Kerberos-based SASL/GSSAPI authentication, +you should install either Heimdal or MIT Kerberos V. -E: MAKE_SLAPD = yes +Heimdal Kerberos is available from {{URL:http://www.pdc.kth.se/heimdal/}}. +MIT Kerberos is available from {{URL:http://web.mit.edu/kerberos/www/}}. -H4: SLAPD_BACKENDS +Use of strong authentication services, such as those provided by +Kerberos, is highly recommended. -This option controls which slapd backend databases get built. You -should set it to one or more of the following: -*{{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. +H3: {{TERM[expand]SASL}} -*{{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. +OpenLDAP clients and servers require installation of {{PRD:Cyrus}}'s +{{PRD: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: 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. +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. -Example to enable the LDBM and SHELL backends only: +OpenLDAP will not be fully LDAPv3 compliant unless OpenLDAP's +configure detects a usable Cyrus SASL installation. -E: SLAPD_BACKENDS= -DLDAP_LDBM -DLDAP_SHELL -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. +H3: Database software -H4: LDBMBACKEND +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. -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: +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. -*{{EX: DLDBM_USE_DBBTREE}} +{{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. -.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}} +{{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. -*{{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: Threads -*{{EX: DLDBM_USE_GDBM}} +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/}}. -.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}} -*{{EX: DLDBM_USE_NDBM}} +H3: TCP Wrappers -.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. +{{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 a IP-level firewall) is recommended +for servers containing non-public information. -Example to enable the Berkeley DB Btree backend: -E: LDBMBACKEND= -DLDBM_USE_DBBTREE +H2: Running configure -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. +If you haven't already done so, extra the distribution for the +compressed archive file and change directory to the top of the +distribution: -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. +.{{EX:gunzip -c openldap-VERSION.tgz | tar xf -}} +.{{EX:cd openldap-VERSION}} -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: +Replacing {{EX:VERSION}} with the appropriate version string. -E: patch -p < ldap-source-directory/build/db.1.85.patch +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}}. -H4: LDBMLIB +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}} -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. +The {{EX:configure}} script will also look at certain environment variables +for certain settings. These environment variables are: -Example to link with {{EX: libdb.a}}, contained in {{EX: /usr/local/lib}}: +!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 -E: LDBMLIB= -L/usr/local/lib -ldb +Now run the configure script with any desired configure options or +environment variables. -H4: THREADS +> [[env] settings] ./configure [options] -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. +As an example, let's 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. -H4: THREADSLIB +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.) -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. +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.) -H4: PHONETIC +> env CPPFLAGS="-I/usr/local/BerkeleyDB.3.1/include" \ +> LDFLAGS="-L/usr/local/BerkeleyDB.3.1/lib" \ +> ./configure --enable-dnssrv -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}}. +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. -H3: Editing the {{EX: include/ldapconfig.h}} file +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. -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. -H4: SLAPD_DEFAULT_CONFIGFILE +H2: Building the Software -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. +Once you have run the {{EX:configure}} script the last line of output +should be: +> Please "make depend" to build dependencies -H4: SLAPD_DEFAULT_SIZELIMIT +If the last line of output does not match, {{EX:configure}} has failed. +You should not proceed until {{EX:configure}} completes successfully. -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. +To build dependencies, run: +> make depend -H4: SLAPD_DEFAULT_TIMELIMIT - -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 - -This define sets the location of the file to which slapd will write its -process ID when it starts up. - -H4: SLAPD_ARGSFILE - -This define sets the location of the file to which slapd will write its -argument vector when it starts up. - -H4: SLAPD_MONITOR_DN - -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 - -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 +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 and slurpd. +libraries and associated clients as well as {{slapd}}(8) and {{slurpd}}(8). -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. +H2: Testing the Software +Once the software has been properly configured and successfully +made, you should run the test suite to verify the build. -H2: Installing the Software +> make test -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 +The test will run a number of tests. -E: make install -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. +H2: Installing the Software -This command will install the entire LDAP distribution. If you only want -to install slapd and slurpd, you could do something like this: +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. -E: (cd servers/slapd; make install) +Typically, the installation is done as {{root}}. From the top level OpenLDAP +source directory, type: -E: (cd servers/slurpd; make install) +> make install -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 in {{F:/usr/local/etc/openldap}} by default. See the +{{SECT:The slapd Configuration File}} chapter for additional information.