source: server/other/openldap.xml@ c507fdb3

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   "http://www.oasis-open.org/docbook/xml/4.4/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-ftp "ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release/openldap-&openldap-version;.tgz">
<!ENTITY openldap-md5sum "383691dbabe05ee2b72a3e9db2042a82">
<!ENTITY openldap-size "2.6 MB">
<!ENTITY openldap-buildsize "76.7 MB">
<!ENTITY openldap-time "6.58 SBU">
]>

<sect1 id="openldap" xreflabel="OpenLDAP-&openldap-version;">
<sect1info>
<othername>$LastChangedBy$</othername>
<date>$Date$</date>
</sect1info>
<?dbhtml filename="openldap.html"?>
<title><application>Open<acronym>LDAP</acronym></application>-&openldap-version;
</title>
<indexterm zone="openldap">
<primary sortas="a-OpenLDAP">OpenLDAP</primary></indexterm>

<sect2>
<title>Introduction to 
<application>Open<acronym>LDAP</acronym></application></title>

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

<sect3><title>Package information</title>
<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>
</sect3>

<sect3><title><application>Open<acronym>LDAP</acronym></application> 
dependencies</title>
<sect4><title>Required</title>
<para><xref linkend="db"/></para>
</sect4>

<sect4><title>Recommended</title>
<para><xref linkend="cyrus-sasl"/> and <xref linkend="openssl"/></para>
</sect4>

<sect4><title>Optional</title>
<para><xref linkend="tcpwrappers"/>, 
<xref linkend="gdbm"/>, 
<ulink url="http://www.gnu.org/software/pth/">GNU Pth</ulink>, and 
<xref linkend="heimdal"/> or
<xref linkend="mitkrb"/></para>
</sect4>

</sect3>

</sect2>

<sect2>
<title>Installation of 
<application>Open<acronym>LDAP</acronym></application></title>

<para>Install <application>Open<acronym>LDAP</acronym></application> by
running the following commands:</para>

<screen><userinput><command>./configure --prefix=/usr --libexecdir=/usr/sbin \
    --sysconfdir=/etc --localstatedir=/srv/ldap \
    --enable-ldbm --disable-debug &amp;&amp;
make depend &amp;&amp;
make &amp;&amp;
make test</command></userinput></screen>

<para>Now, as the root user:</para>

<screen><userinput role='root'><command>make install &amp;&amp;
chmod 755 /usr/lib/libl*-2.2.so.7.0.13</command></userinput></screen>

</sect2>

<sect2>
<title>Command explanations</title>

<para><parameter>--libexecdir=/usr/sbin</parameter>: Installs the server 
executables in <filename class="directory">/usr/sbin</filename> instead of 
<filename class="directory">/usr/libexec</filename>.</para>

<para><parameter>--sysconfdir=/etc</parameter>: Sets the configuration file 
directory to avoid the default of 
<filename class="directory">/usr/etc</filename>.</para>

<para><parameter>--localstatedir=/srv/ldap</parameter>: Sets the directory
to use for the <acronym>LDAP</acronym> directory database, replication logs and 
run-time variable data.</para>

<para><parameter>--enable-ldbm</parameter>: Build <command>slapd</command>
with the primary database back end using either 
<application>Berkeley DB</application> or 
<application><acronym>GNU</acronym> Database Manager</application>.</para> 

<para><parameter>--disable-debug</parameter>: Disable debugging code.</para>

<para><command>make test</command>: Validates the correct build of the 
package. 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. If you logged the 
output of the <command>make test</command>, an easy test to see if all the 
tests succeeded is to issue <command>grep ">>>>> Test succeeded" 
<replaceable>[logfilename]</replaceable> | wc -l</command>. You should have 
<computeroutput>39</computeroutput> returned.</para>

<para><command>chmod 755 /usr/lib/libl*-2.2.so.7.0.10</command>: This command 
adds the executable bit to the shared libraries.</para>

</sect2>

<sect2>
<title>Configuring 
<application>Open<acronym>LDAP</acronym></application></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> and <command>slurpd</command> 
servers can be complex. Securing the <acronym>LDAP</acronym> 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>Open<acronym>LDAP</acronym></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 root 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/admin22/">OpenLDAP 2.2 Administrator's
Guide</ulink></para></listitem>
<listitem><para>Documents located at 
<ulink url="http://www.openldap.org/pub/"/></para></listitem>
</itemizedlist></sect3>

<sect3><title>Utilizing <application>GDBM</application></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><application>Mozilla</application> Address Directory</title>
<para>By default, <acronym>LDAP</acronym>v2 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>Init Script</title>
<para>To automate the startup of the <acronym>LDAP</acronym> server at system 
bootup, install the <filename>/etc/rc.d/init.d/openldap</filename> init script 
included in the <xref linkend="intro-important-bootscripts"/> package using the 
following command:</para>
<indexterm zone="openldap openldap-init">
<primary sortas="f-openldap">openldap</primary></indexterm>

<screen><userinput><command>make install-openldap1</command></userinput></screen>

<para><emphasis>Note:</emphasis> The init script you just installed only starts 
the <command>slapd</command> daemon. If you wish to also start the 
<command>slurpd</command> daemon at system startup, install a modified version 
of the script using this command:</para>

<screen><userinput><command>make install-openldap2</command></userinput></screen>

<note><para>The init script starts the daemons without any parameters. You'll 
need to modify the script to include the parameters needed for your specific
configuration. See the <command>slapd</command> and <command>slurpd</command> 
man pages for parameter information.</para></note>
</sect3>

<sect3><title>Testing the Configuration</title>
<para>Start the <acronym>LDAP</acronym> server using the init script:</para>

<screen><userinput><command>/etc/rc.d/init.d/openldap start</command></userinput></screen>

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

<screen><userinput><command>ldapsearch -x -b '' -s base '(objectclass=*)' namingContexts</command></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>
<title>Contents</title>

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

<seglistitem>
<seg>ldapadd, ldapcompare, ldapdelete, ldapmodify, ldapmodrdn, ldappasswd, 
ldapsearch, ldapwhoami, slapadd, slapcat, slapd, slapdn, slapindex, 
slappasswd, slaptest and slurpd</seg>
<seg>liblber.[so,a], libldap.[so,a] and libldap_r.[so,a]</seg>
<seg>/etc/openldap, /srv/ldap and /usr/share/openldap</seg>
</seglistitem>
</segmentedlist>

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

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

<varlistentry id="ldapmodify">
<term><command>ldapmodify</command></term>
<listitem><para>opens a connection to an <acronym>LDAP</acronym> 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 <acronym>LDAP</acronym> server, 
binds and modifies the <acronym>RDN</acronym> 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 <acronym>LDAP</acronym> 
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 <acronym>LDAP</acronym> 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="ldapwhoami">
<term><command>ldapwhoami</command></term>
<listitem><para>opens a connection to an <acronym>LDAP</acronym> server, 
binds and displays whoami information.</para>
<indexterm zone="openldap ldapwhoami">
<primary sortas="b-ldapwhoami">ldapwhoami</primary>
</indexterm></listitem>
</varlistentry>

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

<varlistentry id="slapcat">
<term><command>slapcat</command></term>
<listitem><para>is used to generate an <acronym>LDAP</acronym> 
<acronym>LDIF</acronym> 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 <acronym>LDAP</acronym> 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 <acronym>DN</acronym>s 
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 indices 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>Open<acronym>LDAP</acronym></application> 
password utility.</para>
<indexterm zone="openldap slappasswd">
<primary sortas="b-slappasswd">slappasswd</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="slurpd">
<term><command>slurpd</command></term>
<listitem><para>is the stand-alone <acronym>LDAP</acronym> replication 
server.</para>
<indexterm zone="openldap slurpd">
<primary sortas="b-slurpd">slurpd</primary>
</indexterm></listitem>
</varlistentry>

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

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

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

</sect2>

</sect1>