glfs/server/other/openldap.xml

<?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 "http://gd.tuwien.ac.at/infosys/network/OpenLDAP/openldap-release/openldap-&openldap-version;.tgz"> -->
  <!ENTITY openldap-download-http " ">
  <!ENTITY openldap-download-ftp  "ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release/openldap-&openldap-version;.tgz">
  <!ENTITY openldap-md5sum        "4f210937cf87e3467a536dd3fed1b8b4">
  <!ENTITY openldap-size          "5.2 MB">
  <!ENTITY openldap-buildsize     "152 MB">
  <!ENTITY openldap-time          "2.0 SBU and approximately 35 minutes to run the tests (processor independent)">
]>

<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>

    <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;-blfs-paths-1.patch"/></para>
        <para>Required patch: <ulink
        url="&patch-root;/openldap-&openldap-version;-symbol-versions-1.patch"/></para>
        <para>Optional patch: <ulink
        url="&patch-root;/openldap-&openldap-version;-ntlm-1.patch"/></para>
      </listitem>
    </itemizedlist>

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

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required"><xref linkend="db"/></para>

    <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="tcpwrappers"/>,
    <xref linkend="unixodbc"/>,
    <ulink url="http://www.openslp.org/">OpenSLP</ulink>,
    <xref linkend="pth"/>, and either
    <xref linkend="mysql"/> or
    <xref linkend="postgresql"/></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>Without this patch, the Exchange 
      addressbook integration uses simple binds with cleartext 
      passwords. If you are going to build evolution-data-server
      with OpenLDAP support, apply this patch:</para>

<screen><userinput>patch -Np1 -i ../openldap-&openldap-version;-ntlm-1.patch</userinput></screen>
    </note>

    <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 the following
      <command>configure</command> command instead of the other one, and
      then proceed with the remaining commands (no test suite available):</para>

<screen><userinput>patch -Np1 -i ../openldap-&openldap-version;-blfs-paths-1.patch &amp;&amp;
patch -Np1 -i ../openldap-&openldap-version;-symbol-versions-1.patch &amp;&amp;
autoconf &amp;&amp;
./configure --prefix=/usr \
            --sysconfdir=/etc \
            --enable-dynamic \
            --disable-debug \
            --disable-slapd</userinput></screen>
    </note>

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

<screen><userinput>patch -Np1 -i ../openldap-&openldap-version;-blfs-paths-1.patch &amp;&amp;
patch -Np1 -i ../openldap-&openldap-version;-symbol-versions-1.patch &amp;&amp;
autoconf &amp;&amp;
./configure --prefix=/usr \
            --sysconfdir=/etc \
            --localstatedir=/var \
            --libexecdir=/usr/lib \
            --disable-static \
            --disable-debug \
            --enable-dynamic \
            --enable-crypt \
            --enable-modules \
            --enable-rlookups \
            --enable-backends=mod \
            --enable-overlays=mod \
            --disable-ndb \
            --disable-sql &amp;&amp;
make depend &amp;&amp;
make</userinput></screen>

    <para>To test the results, issue: <command>make test</command>. If you've
    enabled <application>tcp_wrappers</application>, ensure you add 127.0.0.1
    to the <parameter>slapd</parameter> line in the
    <filename>/etc/hosts.allow</filename> file if you have a restrictive
    <filename>/etc/hosts.deny</filename> file.</para>

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

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

install -v -m755 -d /usr/share/doc/openldap-&openldap-version;/{drafts,guide,rfc} &amp;&amp;
install -v -m644    doc/drafts/* \
                    /usr/share/doc/openldap-&openldap-version;/drafts &amp;&amp;
install -v -m644    doc/rfc/* \
                    /usr/share/doc/openldap-&openldap-version;/rfc &amp;&amp;
cp -v -R            doc/guide/* \
                    /usr/share/doc/openldap-&openldap-version;/guide</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>: Disable debugging code.</para>

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

    <para><parameter>--enable-crypt</parameter>: Enables crypt(3)
    passwords.</para>

    <para><parameter>--enable-modules</parameter>: Enables dynamic module
    support.</para>

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

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

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

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

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

    <para><parameter>--enable-spasswd</parameter>: This parameter enables
    SASL password verification.</para>
    
    <para><parameter>--enable-slp</parameter>: This parameter enables
    SLPv2 support. Use this switch if you have installed
    <ulink url="http://www.openslp.org/">OpenSLP</ulink>.</para>
    
    <para><parameter>--enable-wrappers</parameter>: This parameter enables
    tcp wrappers support. Use this switch if you have installed
    <xref linkend="tcpwrappers"/>.</para>

    <para><option>--disable-bdb --disable-hdb --with-ldbm-api=gdbm</option>:
    Pass these parameters to the <command>configure</command> command if you
    wish to use <application>GDBM</application> instead of
    <application>Berkeley DB</application> as the primary backend
    database.</para>

    <note>
      <para>You can run <command>./configure --help</command> to see if there
      are other parameters you can pass to the <command>configure</command>
      command to enable other options or dependency packages.</para>
    </note>

  </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>Utilizing GDBM</title>

      <para>To utilize <application>GDBM</application> as the database
      backend, the <quote>database</quote> entry in
      <filename>/etc/openldap/slapd.conf</filename> must be changed from
      <quote>bdb</quote> to <quote>ldbm</quote>. You can use both by
      creating an additional database section in
      <filename>/etc/openldap/slapd.conf</filename>.</para>

    </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/openldap</filename> init script
      included in the <xref linkend="bootscripts"/> package
      using the following command:</para>

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

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

      <note>
        <para>The init script starts the daemon without any parameters.
        You'll need to modify the 
        <filename>/etc/sysconfig/openldap</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/openldap 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 base
# 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,a and libldap_r.so</seg>
        <seg>/etc/openldap, /usr/lib/openldap
        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 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 stand-alone 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>