source: server/other/openldap.xml@ 36336d8

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY openldap-download-http " ">
  <!ENTITY openldap-download-ftp  "ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release/openldap-&openldap-version;.tgz">
  <!ENTITY openldap-md5sum        "423c1f23d2a0cb96b3e9baf7e9d7dda7">
  <!ENTITY openldap-size          "5.4 MB">
  <!ENTITY openldap-buildsize     "47 MB (client), 101 MB (server, additional 5 MB for the tests)">
  <!ENTITY openldap-time          "0.6 SBU (client), 1.1 SBU (server, additional 3.4 SBU for the tests)">
]>

<sect1 id="openldap" xreflabel="OpenLDAP-&openldap-version;">
  <?dbhtml filename="openldap.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>OpenLDAP-&openldap-version;</title>

  <indexterm zone="openldap">
    <primary sortas="a-OpenLDAP">OpenLDAP</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to OpenLDAP</title>

    <para>
      The <application>OpenLDAP</application> package provides an open
      source implementation of the Lightweight Directory Access Protocol.
    </para>

    &lfs77_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&openldap-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&openldap-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &openldap-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &openldap-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &openldap-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &openldap-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Required patch:
          <ulink url="&patch-root;/openldap-&openldap-version;-consolidated-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">OpenLDAP Dependencies</bridgehead>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="cyrus-sasl"/> and
      <xref linkend="openssl"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="icu"/>,
      <xref linkend="pth"/>,
      <xref linkend="unixodbc"/>,
        <xref linkend="mariadb"/> or 
        <xref linkend="postgresql"/> or 
        <ulink url="http://www.mysql.com/">MySQL</ulink>, 
      <ulink url="http://www.openslp.org/">OpenSLP</ulink>, and
      <xref linkend="db"/> (not recommended by the developers)
    </para>

    <para condition="html" role="usernotes">User Notes:
      <ulink url="&blfs-wiki;/openldap"/>
    </para>
  </sect2>

  <sect2 role="installation">
    <title>Installation of OpenLDAP</title>

    <note>
      <para>
        If you only need to install the client side <command>ldap*</command>
        binaries, corresponding man pages, libraries and header files (referred
        to as a <quote>client-only</quote> install), issue these commands
        instead of the following ones (no test suite available):
      </para>

<screen><userinput>patch -Np1 -i ../openldap-&openldap-version;-consolidated-1.patch &amp;&amp;
autoconf &amp;&amp;

./configure --prefix=/usr     \
            --sysconfdir=/etc \
            --disable-static  \
            --enable-dynamic  \
            --disable-debug   \
            --disable-slapd &amp;&amp;
make depend &amp;&amp;
make</userinput></screen>

    <para>
      Then, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install</userinput></screen>

    </note>
 
    <warning>
      <para>If upgrading from a previos installation that used Berkeley DB as
      the backend, you will need to dump the database(s) using the
      <command>slapcat</command> utility, relocate all files in
      <filename class="directory">/var/lib/openldap</filename>, change all
      instances of <option>bdb</option> to <option>mdb</option> in
      <filename>/etc/openldap/slapd.conf</filename> and any files in
      <filename class="directory">/etc/openldap/slapd.d</filename>, and import
      using the <command>slapadd</command> utility after the installation is
      completed.
      </para>
    </warning>

    <para>
      There should be a dedicated user and group to take control
      of the <command>slapd</command> daemon after it is
      started. Issue the following commands as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>groupadd -g 83 ldap &amp;&amp;
useradd -c "OpenLDAP Daemon Owner" -d /var/lib/openldap -u 83 \
        -g ldap -s /bin/false ldap</userinput></screen>

    <para>
      Install <application>OpenLDAP</application> by
      running the following commands:
    </para>

<screen><userinput>patch -Np1 -i ../openldap-&openldap-version;-consolidated-1.patch &amp;&amp;
autoconf &amp;&amp;

./configure --prefix=/usr         \
            --sysconfdir=/etc     \
            --localstatedir=/var  \
            --libexecdir=/usr/lib \
            --disable-static      \
            --disable-debug       \
            --with-tls=openssl    \
            --with-cyrus-sasl     \
            --enable-dynamic      \
            --enable-crypt        \
            --enable-spasswd      \
            --enable-slapd        \
            --enable-modules      \
            --enable-backends=mod \
            --disable-ndb         \
            --disable-sql         \
            --disable-shell       \ 
            --disable-bdb         \ 
            --disable-hdb         \ 
            --enable-overlays=mod &amp;&amp;

make depend &amp;&amp;
make</userinput></screen>

    <para>
      To test the results, issue: <command>make test</command>. Tests may fail
      after a long time (~ 5 SBU).
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install &amp;&amp;

install -v -dm700 -o ldap -g ldap /var/lib/openldap     &amp;&amp;
install -v -dm700 -o ldap -g ldap /etc/openldap/slapd.d &amp;&amp;
chmod -v 640       /etc/openldap/slapd.{conf,ldif}      &amp;&amp;
chown -v root:ldap /etc/openldap/slapd.{conf,ldif}      &amp;&amp;

install -v -dm755              /usr/share/doc/openldap-&openldap-version; &amp;&amp;
cp -vfr doc/{drafts,rfc,guide} /usr/share/doc/openldap-&openldap-version;</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/static-libraries.xml"/>

    <para>
      <parameter>--disable-debug</parameter>: This switch disables
      the debugging code in <application>OpenLDAP</application>.
    </para>

    <para>
      <parameter>--enable-dynamic</parameter>: This switch forces the
      <application>OpenLDAP</application> libraries to be dynamically
      linked to the executable programs.
    </para>

    <para>
      <parameter>--enable-crypt</parameter>: This switch enables using of
      <command>crypt(3)</command> passwords.
    </para>

    <para>
      <parameter>--enable-spasswd</parameter>: This switch enables
      <application>SASL</application> password verification.
    </para>

    <para>
      <parameter>--enable-modules</parameter>: This switch enables dynamic
      module support.
    </para>

    <para>
      <parameter>--enable-rlookups</parameter>: This switch enables
      reverse lookups of client hostnames.
    </para>

    <para>
      <parameter>--enable-backends</parameter>: This switch enables
      all available backends.
    </para>

    <para>
      <parameter>--enable-overlays</parameter>: This switch enables
      all available overlays.
    </para>

    <para>
      <parameter>--disable-ndb</parameter>: This switch disables
      <application>MySQL</application> NDB Cluster backend
      which causes configure to fail if
      <application>MySQL</application> is present.
    </para>

    <para>
      <parameter>--disable-sql</parameter>: This switch explicitly
      disables the SQL backend.  Omit this switch if a SQL server is
      installed and you are going to use a SQL backend.
    </para>

    <para>
     <parameter>--libexecdir=/usr/lib</parameter>: This switch controls where
     the <filename class="directory">/usr/lib/openldap</filename> directory is
     installed.  Everything in that directory is a library, so it belongs under
     <filename class="directory">/usr/lib</filename> instead of
     <filename class="directory">/usr/libexec</filename>.
    </para>

    <para>
      <option>--enable-slp</option>: This switch enables
      SLPv2 support. Use it if you have installed
      <ulink url="http://www.openslp.org/">OpenSLP</ulink>.
    </para>
 
    <note>
      <para>
        You can run <command>./configure --help</command> to see if there
        are other switch you can pass to the <command>configure</command>
        command to enable other options or dependency packages.
      </para>
    </note>

    <para>
      <command>install ...</command>, <command>chown ...</command>,
      and <command>chmod ...</command>:
      Having slapd configuration files and ldap databases in /var/lib/openldap
      readable by anyone is a SECURITY ISSUE, especially since a file stores the
      admin password in PLAIN TEXT. That's why mode 640 and root:ldap ownership
      were used. The owner is root, so only root can modify the file, and group is
      ldap, so that the group which owns slapd daemon could read but not modify
      the file in case of a security breach. 
    </para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring OpenLDAP</title>

    <sect3 id="openldap-config">
      <title>Config Files</title>

      <para>
        <filename>/etc/openldap/*</filename>
      </para>

      <indexterm zone="openldap openldap-config">
        <primary sortas="e-etc-openldap">/etc/openldap/*</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <para>
        Configuring the <command>slapd</command> servers can be complex.
        Securing the LDAP directory, especially if you are storing non-public
        data such as password databases, can also be a challenging task. You'll
        need to modify the <filename>/etc/openldap/slapd.conf</filename> and
        <filename>/etc/openldap/ldap.conf</filename> files to set up
        <application>OpenLDAP</application> for your particular needs.
      </para>

      <indexterm zone="openldap openldap-config">
        <primary
        sortas="e-etc-openldap-slapd.conf">/etc/openldap/slapd.conf</primary>
      </indexterm>

      <indexterm zone="openldap openldap-config">
        <primary
        sortas="e-etc-openldap-ldap.conf">/etc/openldap/ldap.conf</primary>
      </indexterm>

      <para>
        Resources to assist you with topics such as choosing a directory
        configuration, backend and database definitions, access control settings,
        running as a user other than <systemitem class="username">root</systemitem>
        and setting a <command>chroot</command> environment include:
      </para>

      <itemizedlist spacing="compact">
        <listitem>
          <para>
            The <command>slapd</command> man page.
          </para>
        </listitem>
        <listitem>
          <para>
            The <filename>slapd.conf</filename> man page.
          </para>
        </listitem>
        <listitem>
          <para>
            The <ulink url="http://www.openldap.org/doc/admin24/"> OpenLDAP 2.4
            Administrator's Guide</ulink> (also installed locally in 
            <filename class='directory'>
            /usr/share/doc/openldap-&openldap-version;/guide/admin</filename>).
          </para>
        </listitem>
        <listitem>
          <para>
            Documents located at
            <ulink url="http://www.openldap.org/pub/"/>.
          </para>
        </listitem>
      </itemizedlist>

    </sect3>

    <sect3>
      <title>Mozilla Address Directory</title>

      <para>
        By default, LDAPv2 support is disabled in the
        <filename>slapd.conf</filename> file. Once the database is properly
        set up and <application>Mozilla</application> is configured to use the
        directory, you must add <option>allow bind_v2</option> to the
        <filename>slapd.conf</filename> file.
      </para>

    </sect3>

    <sect3 id="openldap-init">
      <title>Boot Script</title>

      <para>
        To automate the startup of the LDAP server at system bootup,
        install the <filename>/etc/rc.d/init.d/slapd</filename> init script
        included in the <xref linkend="bootscripts"/> package
        using the following command:
      </para>

      <indexterm zone="openldap openldap-init">
        <primary sortas="f-slapd">slapd</primary>
      </indexterm>

<screen role="root"><userinput>make install-slapd</userinput></screen>

      <note>
        <para>
          You'll need to modify the
          <filename>/etc/sysconfig/slapd</filename> to include the
          parameters needed for your specific configuration. See the
          <command>slapd</command> man page for parameter information.
        </para>
      </note>

    </sect3>

    <sect3>
      <title>Testing the Configuration</title>

      <para>
        Start the LDAP server using the init script:
      </para>

<screen role="root"><userinput>/etc/rc.d/init.d/slapd start</userinput></screen>

      <para>
        Verify access to the LDAP server with the following command:
      </para>

<screen><userinput>ldapsearch -x -b '' -s base '(objectclass=*)' namingContexts</userinput></screen>

      <para>
        The expected result is:
      </para>

<screen><computeroutput># extended LDIF
#
# LDAPv3
# base &lt;&gt; with scope baseObject
# filter: (objectclass=*)
# requesting: namingContexts
#

#
dn:
namingContexts: dc=my-domain,dc=com

# search result
search: 2
result: 0 Success

# numResponses: 2
# numEntries: 1</computeroutput></screen>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          ldapadd, ldapcompare, ldapdelete, ldapexop, ldapmodify, ldapmodrdn,
          ldappasswd, ldapsearch, ldapurl, ldapwhoami, slapacl, slapadd,
          slapauth, slapcat, slapd, slapdn, slapindex, slappasswd, slapschema,
          and slaptest
        </seg>
        <seg>
          liblber.so, libldap.so, libldap_r.so,
          and several under /usr/lib/openldap
        </seg>
        <seg>
          /etc/openldap,
          /usr/lib/openldap,
          /usr/share/doc/openldap-&openldap-version;, and
          /var/lib/openldap
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="ldapadd">
        <term><command>ldapadd</command></term>
        <listitem>
          <para>
            opens a connection to an LDAP server, binds and adds entries.
          </para>
          <indexterm zone="openldap ldapadd">
            <primary sortas="b-ldapadd">ldapadd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ldapcompare">
        <term><command>ldapcompare</command></term>
        <listitem>
          <para>
            opens a connection to an LDAP server, binds and performs
            a compare using specified parameters.
          </para>
          <indexterm zone="openldap ldapcompare">
            <primary sortas="b-ldapcompare">ldapcompare</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ldapdelete">
        <term><command>ldapdelete</command></term>
        <listitem>
          <para>
            opens a connection to an LDAP server, binds and deletes
            one or more entries.
          </para>
          <indexterm zone="openldap ldapdelete">
            <primary sortas="b-ldapdelete">ldapdelete</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ldapexop">
        <term><command>ldapexop</command></term>
        <listitem>
          <para>
            issues the LDAP extended operation specified by
            oid or one of the  special  keywords  whoami,
            cancel, or refresh.
          </para>
          <indexterm zone="openldap ldapexop">
            <primary sortas="b-ldapexop">ldapexop</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ldapmodify">
        <term><command>ldapmodify</command></term>
        <listitem>
          <para>
            opens a connection to an LDAP server, binds and modifies entries.
          </para>
          <indexterm zone="openldap ldapmodify">
            <primary sortas="b-ldapmodify">ldapmodify</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ldapmodrdn">
        <term><command>ldapmodrdn</command></term>
        <listitem>
          <para>
            opens a connection to an LDAP server, binds and modifies
            the RDN of entries.
          </para>
          <indexterm zone="openldap ldapmodrdn">
            <primary sortas="b-ldapmodrdn">ldapmodrdn</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ldappasswd">
        <term><command>ldappasswd</command></term>
        <listitem>
          <para>
            is a tool used to set the password of an LDAP user.
          </para>
          <indexterm zone="openldap ldappasswd">
            <primary sortas="b-ldappasswd">ldappasswd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ldapsearch">
        <term><command>ldapsearch</command></term>
        <listitem>
          <para>
            opens a connection to an LDAP server, binds and performs
            a search using specified parameters.
          </para>
          <indexterm zone="openldap ldapsearch">
            <primary sortas="b-ldapsearch">ldapsearch</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ldapurl">
        <term><command>ldapurl</command></term>
        <listitem>
          <para>
            is a command that allows to either compose or
            decompose LDAP URIs.
          </para>
          <indexterm zone="openldap ldapurl">
            <primary sortas="b-ldapurl">ldapurl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ldapwhoami">
        <term><command>ldapwhoami</command></term>
        <listitem>
          <para>
            opens a connection to an LDAP server, binds and displays
            whoami information.
          </para>
          <indexterm zone="openldap ldapwhoami">
            <primary sortas="b-ldapwhoami">ldapwhoami</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="slapacl">
        <term><command>slapacl</command></term>
        <listitem>
          <para>
            is used to check the behavior of slapd by verifying
            access to directory data according to the access control
            list directives defined in its configuration.
          </para>
          <indexterm zone="openldap slapacl">
            <primary sortas="b-slapacl">slapacl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="slapadd">
        <term><command>slapadd</command></term>
        <listitem>
          <para>
            is used to add entries specified in LDAP Directory Interchange
            Format (LDIF) to an LDAP database.
          </para>
          <indexterm zone="openldap slapadd">
            <primary sortas="b-slapadd">slapadd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="slapauth">
        <term><command>slapauth</command></term>
        <listitem>
          <para>
            is used to check the behavior of the slapd
            in mapping identities for authentication and
            authorization purposes, as specified in slapd.conf.
          </para>
          <indexterm zone="openldap slapauth">
            <primary sortas="b-slapauth">slapauth</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="slapcat">
        <term><command>slapcat</command></term>
        <listitem>
          <para>
            is used to generate an LDAP LDIF output based upon the
            contents of a slapd database.
          </para>
          <indexterm zone="openldap slapcat">
            <primary sortas="b-slapcat">slapcat</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="slapd">
        <term><command>slapd</command></term>
        <listitem>
          <para>
            is the standalone LDAP server.
          </para>
          <indexterm zone="openldap slapd">
            <primary sortas="b-slapd">slapd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="slapdn">
        <term><command>slapdn</command></term>
        <listitem>
          <para>
            checks a list of string-represented DNs based on schema syntax.
          </para>
          <indexterm zone="openldap slapdn">
            <primary sortas="b-slapdn">slapdn</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="slapindex">
        <term><command>slapindex</command></term>
        <listitem>
          <para>
            is used to regenerate slapd indexes based upon the current
            contents of a database.
          </para>
          <indexterm zone="openldap slapindex">
            <primary sortas="b-slapindex">slapindex</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="slappasswd">
        <term><command>slappasswd</command></term>
        <listitem>
          <para>
            is an <application>OpenLDAP</application> password utility.
          </para>
          <indexterm zone="openldap slappasswd">
            <primary sortas="b-slappasswd">slappasswd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="slapschema">
        <term><command>slapschema</command></term>
        <listitem>
          <para>
            is used to check schema compliance of the contents
            of a slapd database.
          </para>
          <indexterm zone="openldap slapschema">
            <primary sortas="b-slapschema">slapschema</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="slaptest">
        <term><command>slaptest</command></term>
        <listitem>
          <para>
            checks the sanity of the <filename>slapd.conf</filename> file.
          </para>
          <indexterm zone="openldap slaptest">
            <primary sortas="b-slaptest">slaptest</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="liblber">
        <term><filename class="libraryfile">liblber.so</filename></term>
        <listitem>
          <para>
            is a set of Lightweight Basic Encoding Rules routines. These
            routines are used by the LDAP library routines to encode and decode
            LDAP protocol elements using the (slightly simplified) Basic
            Encoding Rules defined by LDAP. They are not normally used directly
            by an LDAP application program except in the handling of controls
            and extended operations.
          </para>
          <indexterm zone="openldap liblber">
            <primary sortas="c-liblber">liblber.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libldap">
        <term><filename class="libraryfile">libldap.so</filename></term>
        <listitem>
          <para>
            supports the LDAP programs and provide functionality for
            other programs interacting with LDAP.
          </para>
          <indexterm zone="openldap libldap">
            <primary sortas="c-libldap">libldap.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libldap_r">
        <term><filename class="libraryfile">libldap_r.so</filename></term>
        <listitem>
          <para>
            contains the functions required by the LDAP programs to
            produce the results from LDAP requests.
          </para>
          <indexterm zone="openldap libldap_r">
            <primary sortas="c-libldap_r">libldap_r.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>