<!doctype html public "-//W30//DTD W3 HTML 2.0//EN">
<HTML>
<!-- This file was generated using SDF 2.001 by
Ian Clatworthy (ianc@mincom.com). SDF is freely
available from http://www.mincom.com/mtr/sdf. -->
<HEAD>
<TITLE>OpenLDAP Software 2.4 Administrator's Guide: Notes for Mageia users</TITLE>
</HEAD>
<BODY>
<DIV CLASS="header">
<A HREF="http://www.OpenLDAP.org/">
<P><IMG SRC="../images/LDAPlogo.gif" ALIGN="Left" BORDER=0></P>
</A>
<DIV CLASS="navigate">
<P ALIGN="Center"><A HREF="index.html">Contents</A> | <A HREF="install.html">Parent Topic</A> | <A HREF="install.html">Previous Topic</A> | <A HREF="slapdconf2.html">Next Topic</A> <BR><A HREF="http://www.openldap.org/">Home</A> | <A HREF="../index.html">Catalog</A></P>
</DIV>
<BR CLEAR="Left">
</DIV>
<DIV CLASS="main">
<H2>4.1. Notes for Mageia users</H2>
<P>If you are reading this version of the OpenLDAP Administrator's Guide, it means you have installed the Mageia OpenLDAP documentation package.</P>
<H3><A NAME="File locations">4.1.1. File locations</A></H3>
<P>The <A HREF="https://www.mageia.org">Mageia</A> packages install OpenLDAP with a prefix of /usr, so the daemons are availble in <TT>/usr/sbin</TT>, client utilities in /usr/bin, configuration files under <TT>/etc/openldap</TT>, libraries in <TT>/usr/lib</TT> (or /usr/lib64 on 64bit platforms), and plugins for slapd under <TT>/usr/lib/openldap</TT>. The packages are built with all useable backends and overlays (many as loadable modules), so it should normally not be necessary to build from source.</P>
<P>The OpenLDAP test suite that is shipped with the source code is also shipped, ready-to-run, in the openldap-tests package. To run the test suite (to confirm that all tests passed, investigate some of the example configurations that are shipped, etc.), simply install openldap-tests (with <TT>urpmi openldap-tests</TT>) then (as any user):</P>
<UL>
<TT>cd /usr/share/openldap/tests</TT>
<BR>
<TT>make tests</TT></UL>
<H3><A NAME="Upgrading between major versions of OpenLDAP when upgrading the distribution">4.1.2. Upgrading between major versions of OpenLDAP when upgrading the distribution</A></H3>
<P>Upgrades between major versions should usually proceed cleanly without user intervention, and work as follows:</P>
<UL>
<LI>Before package installation, for each database defined in <TT>/etc/openldap/slapd.conf</TT> and any first level included files
<LI>If no file named <TT>rpm-migrate-to-<OPENLDAP-MAJOR-VERSION>.ldif-imported</TT> or <TT>rpm-migrate-to-<OPENLDAP-MAJOR-VERSION>.ldif-import-failed</TT> exists in the database directory
<LI>the database will be dumped (using <TT>slapcat</TT>) to the file rpm-migrate-to-<OPENLDAP-MAJOR-VERSION>.ldif in the database directory
<LI>After package installation, for each database defined in <TT>/etc/openldap/slapd.conf</TT> or any first level included files
<LI>If a file with the name <TT>rpm-migrate-to-<OPENLDAP-MAJOR-VERSION>.ldif</TT> exists, it will be imported using <TT>slapadd</TT>.
<LI>If the import succeeds, this file will be renamed to <TT>rpm-migrate-to-<OPENLDAP-MAJOR-VERSION>.ldif-imported</TT>
<LI>If the import fails, the file will be renamed to <TT>rpm-migrate-to-<OPENLDAP-MAJOR-VERSION>.ldif-import-failed</TT></UL>
<P>Thus, under normal circumstances, each database should be migrated successfully, leaving a file (which could be quite large) named <TT>rpm-migrate-to-<OPENLDAP-MAJOR-VERSION>.ldif-imported</TT> in each database directory. If you are happy that migration worked successfully and you wish to reclaim the disk space, make this file an empty file (ie <TT> > rpm-migrate-to-<OPENLDAP-MAJOR-VERSION>.ldif-imported</TT>). If import fails, you should be left with complete LDIF for each database.</P>
<P>If the export of the database fails, then you may need to use a compatability package matching your previous OpenLDAP package to export your data. This will require some work (mainly copying your usual slapd.conf to the configuration directory for the compatability version), so even though upgrades should work cleanly, it is recommended to stop slapd and take an ldif backup manually for each database before upgrading.</P>
<P>If you would prefer to handle all database upgrading yourself, you can disable automatic migration by setting <TT>AUTOMIGRATE=no</TT> in your <TT>/etc/sysconfig/slapd</TT></P>
<H3><A NAME="Other versions of OpenLDAP">4.1.3. Other versions of OpenLDAP</A></H3>
<P>The Mageia OpenLDAP packages are usually up-to-date at the time of version freeze in the distribution. The distribution security update policy means that updates for OpenLDAP packages will only be provided in the event of a security vulnerability, and will only address the specific vulnerability (new versions will not be provided, the original version will be patched).</P>
<P>As a service to users who prefer to run more up-to-date versions of OpenLDAP software, the maintainer often provides newer (ie versions not yet marked as stable) versions in the contrib repository that can be installed in parallel, and usually attempts to ensure that the packages rebuild correctly (maintaining their status as they were on the original distribution) on older distributions. However, these packages cannot be supported by Mageia.</P>
<P>Compatability packages are kept in contrib for at least one release after they have been replaced in main by a new version (to ensure that users for whom automatic migration failed can export their data with a slapcat compatible with their data. The BerkeleyDB version that the package used when in main is maintained, even if this means retaining an internal copy.</P>
<TABLE CLASS="columns" BORDER ALIGN='Center'>
<CAPTION ALIGN=top>OpenLDAP versions (db4 version) in Mageia releases</CAPTION>
<TR CLASS="heading">
<TD>
<STRONG>Release</STRONG>
</TD>
<TD>
<STRONG>Main</STRONG>
</TD>
<TD>
<STRONG>Newer</STRONG>
</TD>
<TD>
<STRONG>Compatability</STRONG>
</TD>
</TR>
<TR>
<TD>
Mageia 6
</TD>
<TD>
2.4.45 (system db5.3.28)
</TD>
<TD>
N/A
</TD>
<TD>
N/A
</TD>
</TR>
<TR>
<TD>
Mageia 5
</TD>
<TD>
2.4.40 (system db5.3.28)
</TD>
<TD>
N/A
</TD>
<TD>
N/A
</TD>
</TR>
<TR>
<TD>
Mageia 4
</TD>
<TD>
2.4.38 (system db5.3.21)
</TD>
<TD>
N/A
</TD>
<TD>
N/A
</TD>
</TR>
<TR>
<TD>
Mandriva 2007.1
</TD>
<TD>
2.3.34 (system db4.2.52.4+patch)
</TD>
<TD>
N/A
</TD>
<TD>
2.2.27(system db4.2.42.2)
</TD>
</TR>
</TABLE>
<P>All the files/commands/man pages and OpenLDAP-specific directories (ie /usr/lib/openldap, /etc/openldap) are suffixed with the major version of the software, for instance the <TT>slapd</TT> daemon would be called <TT>slapd2.2</TT> and would use the configuration file /etc/openldap2.2/slapd.conf and plugins from /usr/lib/openldap2.2).</P>
<H3><A NAME="Skip Ahead">4.1.4. Skip Ahead</A></H3>
<P>The rest of this chapter may be skipped if the version you require is available and can be installed with <TT>urpmi</TT> or the Software Installer. Continue on to <A HREF="slapdconf2.html">Configuring slapd</A>.</P>
<HR>
<H2><A NAME="Obtaining and Extracting the Software">4.2. Obtaining and Extracting the Software</A></H2>
<P>You can obtain OpenLDAP Software from the project's download page at <A HREF="http://www.openldap.org/software/download/">http://www.openldap.org/software/download/</A> or directly from the project's <TERM>FTP</TERM> service at <A HREF="ftp://ftp.openldap.org/pub/OpenLDAP/">ftp://ftp.openldap.org/pub/OpenLDAP/</A>.</P>
<P>The project makes available two series of packages for <EM>general use</EM>. The project makes <EM>releases</EM> 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 <EM>release</EM>. The <EM>stable</EM> release is the latest <EM>release</EM> which has demonstrated stability through general use.</P>
<P>Users of OpenLDAP Software can choose, depending on their desire for the <EM>latest features</EM> versus <EM>demonstrated stability</EM>, the most appropriate series to install.</P>
<P>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:</P>
<UL>
<TT>gunzip -c openldap-VERSION.tgz | tar xf -</TT>
<BR>
<TT>cd openldap-VERSION</TT></UL>
<P>You'll have to replace <TT>VERSION</TT> with the version name of the release.</P>
<P>You should now review the <TT>COPYRIGHT</TT>, <TT>LICENSE</TT>, <TT>README</TT> and <TT>INSTALL</TT> documents provided with the distribution. The <TT>COPYRIGHT</TT> and <TT>LICENSE</TT> provide information on acceptable use, copying, and limitation of warranty of OpenLDAP Software. The <TT>README</TT> and <TT>INSTALL</TT> documents provide detailed information on prerequisite software and installation procedures.</P>
<HR>
<H2><A NAME="Prerequisite software">4.3. Prerequisite software</A></H2>
<P>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 <TT>README</TT> 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.</P>
<H3><A NAME="{{TERM[expand]TLS}}">4.3.1. <TERM>Transport Layer Security</TERM></A></H3>
<P>OpenLDAP clients and servers require installation of <A HREF="http://www.openssl.org/">OpenSSL</A>, <A HREF="http://www.gnu.org/software/gnutls/">GnuTLS</A>, or <A HREF="http://developer.mozilla.org/en/NSS">MozNSS</A> <TERM>TLS</TERM> libraries to provide <TERM>Transport Layer Security</TERM> services. Though some operating systems may provide these libraries as part of the base system or as an optional software component, OpenSSL, GnuTLS, and Mozilla NSS often require separate installation.</P>
<P>OpenSSL is available from <A HREF="http://www.openssl.org/">http://www.openssl.org/</A>. GnuTLS is available from <A HREF="http://www.gnu.org/software/gnutls/">http://www.gnu.org/software/gnutls/</A>. Mozilla NSS is available from <A HREF="http://developer.mozilla.org/en/NSS">http://developer.mozilla.org/en/NSS</A>.</P>
<P>OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's <TT>configure</TT> detects a usable TLS library.</P>
<H3><A NAME="{{TERM[expand]SASL}}">4.3.2. <TERM>Simple Authentication and Security Layer</TERM></A></H3>
<P>OpenLDAP clients and servers require installation of <A HREF="http://asg.web.cmu.edu/sasl/sasl-library.html">Cyrus SASL</A> libraries to provide <TERM>Simple Authentication and Security Layer</TERM> 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.</P>
<P>Cyrus SASL is available from <A HREF="http://asg.web.cmu.edu/sasl/sasl-library.html">http://asg.web.cmu.edu/sasl/sasl-library.html</A>. Cyrus SASL will make use of OpenSSL and Kerberos/GSSAPI libraries if preinstalled.</P>
<P>OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's configure detects a usable Cyrus SASL installation.</P>
<H3><A NAME="{{TERM[expand]Kerberos}}">4.3.3. <TERM>Kerberos Authentication Service</TERM></A></H3>
<P>OpenLDAP clients and servers support <TERM>Kerberos</TERM> authentication services. In particular, OpenLDAP supports the Kerberos V <TERM>GSS-API</TERM> <TERM>SASL</TERM> authentication mechanism known as the <TERM>GSSAPI</TERM> mechanism. This feature requires, in addition to Cyrus SASL libraries, either <A HREF="http://www.pdc.kth.se/heimdal/">Heimdal</A> or <A HREF="http://web.mit.edu/kerberos/www/">MIT Kerberos</A> V libraries.</P>
<P>Heimdal Kerberos is available from <A HREF="http://www.pdc.kth.se/heimdal/">http://www.pdc.kth.se/heimdal/</A>. MIT Kerberos is available from <A HREF="http://web.mit.edu/kerberos/www/">http://web.mit.edu/kerberos/www/</A>.</P>
<P>Use of strong authentication services, such as those provided by Kerberos, is highly recommended.</P>
<H3><A NAME="Database Software">4.3.4. Database Software</A></H3>
<P>OpenLDAP's <EM>slapd</EM>(8) <TERM>MDB</TERM> primary database backend uses the <TERM>LMDB</TERM> software included with the OpenLDAP source. There is no need to download any additional software to have <EM>MDB</EM> support.</P>
<P>OpenLDAP's <EM>slapd</EM>(8) <TERM>BDB</TERM> and <TERM>HDB</TERM> deprecated database backends require <A HREF="http://www.oracle.com/">Oracle Corporation</A>'s Berkeley DB. If not available at configure time, you will not be able to build <EM>slapd</EM>(8) with these deprecated database backends.</P>
<P>Your operating system may provide a supported version of Berkeley DB in the base system or as an optional software component. If not, you'll have to obtain and install it yourself. Berkeley DB is available from <A HREF="http://www.oracle.com/">Oracle Corporation</A>'s Berkeley DB download page if required.</P>
<P>There are several versions available from <A HREF="http://www.oracle.com/">Oracle Corporation</A>. Berkeley DB version 6.0.20 and later uses a software license that is incompatible with LDAP technology and should not be used with OpenLDAP.</P>
<P><HR WIDTH="80%" ALIGN="Left">
<STRONG>Note: </STRONG>Please see <A HREF="appendix-recommended-versions.html">Recommended OpenLDAP Software Dependency Versions</A> for more information.
<HR WIDTH="80%" ALIGN="Left"></P>
<H3><A NAME="Threads">4.3.5. Threads</A></H3>
<P>OpenLDAP is designed to take advantage of threads. OpenLDAP supports POSIX <EM>pthreads</EM>, Mach <EM>CThreads</EM>, and a number of other varieties. <TT>configure</TT> will complain if it cannot find a suitable thread subsystem. If this occurs, please consult the <TT>Software|Installation|Platform Hints</TT> section of the OpenLDAP FAQ <A HREF="http://www.openldap.org/faq/">http://www.openldap.org/faq/</A>.</P>
<H3><A NAME="TCP Wrappers">4.3.6. TCP Wrappers</A></H3>
<P><EM>slapd</EM>(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.</P>
<HR>
<H2><A NAME="Running configure">4.4. Running configure</A></H2>
<P>Now you should probably run the <TT>configure</TT> script with the <TT>--help</TT> 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.</P>
<PRE>
./configure --help
</PRE>
<P>The <TT>configure</TT> script also looks for certain variables on the command line and in the environment. These include:</P>
<TABLE CLASS="columns" BORDER ALIGN='Center'>
<CAPTION ALIGN=top>Table 4.1: Variables</CAPTION>
<TR CLASS="heading">
<TD>
<STRONG>Variable</STRONG>
</TD>
<TD>
<STRONG>Description</STRONG>
</TD>
</TR>
<TR>
<TD>
<TT>CC</TT>
</TD>
<TD>
Specify alternative C Compiler
</TD>
</TR>
<TR>
<TD>
<TT>CFLAGS</TT>
</TD>
<TD>
Specify additional compiler flags
</TD>
</TR>
<TR>
<TD>
<TT>CPPFLAGS</TT>
</TD>
<TD>
Specify C Preprocessor flags
</TD>
</TR>
<TR>
<TD>
<TT>LDFLAGS</TT>
</TD>
<TD>
Specify linker flags
</TD>
</TR>
<TR>
<TD>
<TT>LIBS</TT>
</TD>
<TD>
Specify additional libraries
</TD>
</TR>
</TABLE>
<P>Now run the configure script with any desired configuration options or variables.</P>
<PRE>
./configure [options] [variable=value ...]
</PRE>
<P>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 <TT>--enable-wrappers</TT> to include TCP Wrappers support:</P>
<PRE>
./configure --enable-wrappers
</PRE>
<P>However, this will fail to locate dependent software not installed in system directories. For example, if TCP Wrappers headers and libraries are installed in <TT>/usr/local/include</TT> and <TT>/usr/local/lib</TT> respectively, the <TT>configure</TT> script should typically be called as follows:</P>
<PRE>
./configure --enable-wrappers \
CPPFLAGS="-I/usr/local/include" \
LDFLAGS="-L/usr/local/lib -Wl,-rpath,/usr/local/lib"
</PRE>
<P>The <TT>configure</TT> script will normally auto-detect appropriate settings. If you have problems at this stage, consult any platform specific hints and check your <TT>configure</TT> options, if any.</P>
<HR>
<H2><A NAME="Building the Software">4.5. Building the Software</A></H2>
<P>Once you have run the <TT>configure</TT> script the last line of output should be:</P>
<PRE>
Please "make depend" to build dependencies
</PRE>
<P>If the last line of output does not match, <TT>configure</TT> has failed, and you will need to review its output to determine what went wrong. You should not proceed until <TT>configure</TT> completes successfully.</P>
<P>To build dependencies, run:</P>
<PRE>
make depend
</PRE>
<P>Now build the software, this step will actually compile OpenLDAP.</P>
<PRE>
make
</PRE>
<P>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 <EM>slapd</EM>(8).</P>
<HR>
<H2><A NAME="Testing the Software">4.6. Testing the Software</A></H2>
<P>Once the software has been properly configured and successfully made, you should run the test suite to verify the build.</P>
<PRE>
make test
</PRE>
<P>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.</P>
<HR>
<H2><A NAME="Installing the Software">4.7. Installing the Software</A></H2>
<P>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 <TT>/usr/local</TT>. If you changed this setting with the <TT>--prefix</TT> configure option, it will be installed in the location you provided.</P>
<P>Typically, the installation requires <EM>super-user</EM> privileges. From the top level OpenLDAP source directory, type:</P>
<PRE>
su root -c 'make install'
</PRE>
<P>and enter the appropriate password when requested.</P>
<P>You should examine the output of this command carefully to make sure everything is installed correctly. You will find the configuration files for <EM>slapd</EM>(8) in <TT>/usr/local/etc/openldap</TT> by default. See the chapter <A HREF="slapdconf2.html">Configuring slapd</A> for additional information.</P>
<P></P>
</DIV>
<DIV CLASS="footer">
<HR>
<DIV CLASS="navigate">
<P ALIGN="Center"><A HREF="index.html">Contents</A> | <A HREF="install.html">Parent Topic</A> | <A HREF="install.html">Previous Topic</A> | <A HREF="slapdconf2.html">Next Topic</A> <BR><A HREF="http://www.openldap.org/">Home</A> | <A HREF="../index.html">Catalog</A></P>
</DIV>
<P>
<FONT COLOR="#808080" FACE="Arial,Verdana,Helvetica" SIZE="1"><B>
________________<BR>
<SMALL>© Copyright 2011, <A HREF="http://www.OpenLDAP.org/foundation/">OpenLDAP Foundation</A>, <A HREF="mailto:info@OpenLDAP.org">info@OpenLDAP.org</A></SMALL></B></FONT>
</DIV>
</BODY>
</HTML>
