<revremark>Migration to DocBook XML standard, revision of the role document.
Introducing OpenLDAP 2.1.</revremark></revision>
<revision><revnumber>1.05</revnumber>
<date>2001/06/22</date>
<authorinitials>lepm</authorinitials>
<revremark>Correction of long lines that were causing
inconsistences on the PDF version of the document.</revremark></revision>
<revision><revnumber>1.04</revnumber>
<date>2001/02/28</date>
<authorinitials>lepm</authorinitials>
<revremark>Correction of more typos and update on the
following sections: Roaming Access, Authentication using LDAP.</revremark>
</revision>
<revision><revnumber>1.03</revnumber>
<date>2000/09/28</date>
<authorinitials>lepm</authorinitials>
<revremark>Presenting OpenLDAP 2.0, which comprises LDAPv3, as defined on <ulinkurl="ftp://ftp.isi.edu/in-notes/rfc2251.txt">RFC2251</ulink></revremark></revision>
<revision><revnumber>1.02</revnumber>
<date>2000/09/13</date>
<authorinitials>lepm</authorinitials>
<revremark>Correction of typos and addition of the section History of Releases.</revremark></revision>
<revision><revnumber>1.01</revnumber>
<date>2000/02/15</date>
<authorinitials>lepm</authorinitials>
<revremark>Added the following sections: LDAP Migration Tools, Authentication using LDAP, Graphical
<para>The main purpose of this document is to set up and use a LDAP Directory Server
on your Linux machine.You will learn how to install, configure, run and
maintain the LDAP server. After you also learn how you can store, retrieve and
update information on your Directory using the LDAP clients and utilities.
The daemon for the LDAP directory server is called <emphasis>slapd</emphasis> and it runs on
many different UNIX platforms. </para>
<para>There is another daemon that cares for replication between LDAP servers. It's
called slurpd and for the moment you don't need to worry about it. In this
document you will run a slapd which provides directory service for your local
domain only, without replication, so without slurpd. Complete information about
replication is available at: <ulinkurl="http://www.openldap.org/doc/admin23/replication.html">OpenLDAP
Administrator's Guide</ulink></para>
<para>The local domain setup represents a simple choice for configuring your server,
good for starting and easy to upgrade to another configuration later if you want.
The information presented on this document represents a nice initialization on
using the LDAP server. Possibly after reading this document you will feel
encouraged to expand the capabilities of your server and even write your own
clients, using the already available C, C++ and Java Development Kits.</para>
<sectionid="WhatisLdap">
<title>What's LDAP ?</title>
<para>LDAP stands for Lightweight Directory Access Protocol. As the name suggests,
it is a lightweight client-server protocol for accessing directory services, specifically X.500-based directory
services. LDAP runs over TCP/IP or other connection oriented transfer services.
LDAP is defined in <ulinkurl="ftp://ftp.isi.edu/in-notes/rfc2251.txt">RFC2251</ulink> "The Lightweight Directory Access Protocol (v3).</para>
<para>A directory is similar to a database, but tends to contain more descriptive,
attribute-based information. The information in a directory is generally read
much more often than it is written. Directories are tuned to give quick-response to
high-volume lookup or search operations. They may have the ability to replicate
information widely in order to increase availability and reliability, while reducing
response time. When directory information is replicated, temporary inconsistencies
between the replicas may be OK, as long as they get in sync eventually.</para>
<para>There are many different ways to provide a directory service. Different methods
allow different kinds of information to be stored in the directory, place
different requirements on how that information can be referenced, queried and
updated, how it is protected from unauthorized access, etc. Some directory
services are local, providing service to a restricted context (e.g., the finger
service on a single machine). Other services are global, providing service to
a much broader context.</para></section>
<sectionid="HowitWorks">
<title>How does LDAP work ?</title>
<para>LDAP directory service is based on a client-server model. One or more LDAP
servers contain the data making up the LDAP directory tree or LDAP backend
database. An LDAP client connects to an LDAP server and asks it a question. The
server responds with the answer, or with a pointer to where the client can get
more information (typically, another LDAP server). No matter what LDAP server
a client connects to, it sees the same view of the directory; a name presented
to one LDAP server references the same entry it would at another LDAP server.
This is an important feature of a global directory service, like LDAP.</para></section>
<sectionid="LdapBackends">
<title>LDAP backends, objects and attributes</title>
<para>The LDAP server daemon is called <emphasis>Slapd</emphasis>. <emphasis>Slapd</emphasis>
supports a variety of different <command>database backends</command> which you can use.</para>
<para>They include the <command>primary choice BDB</command>, a high-performance transactional database backend; LDBM, a lightweight DBM based backend; SHELL, a backend interface to arbitrary shell scripts and PASSWD, a simple backend interface to the passwd(5) file.</para>
<para>BDB utilizes <ulinkurl="http://www.sleepycat.com/">Sleepycat</ulink> Berkeley DB 4. LDBM utilizes
either <ulinkurl="http://www.sleepycat.com/">Berkeley DB</ulink> or <ulinkurl="http://www.gnu.org/software/gdbm/">GDBM</ulink>.</para>
<para>BDB transactional backend is suited for multi-user read/write database access,
with any mix of read and write operations. BDB is used in applications that require:
<itemizedlist>
<listitem><para>Transactions, including making multiple changes to the
database atomically and rolling back uncommitted changes when necessary.</para></listitem>
<listitem><para>Ability to recover from systems crashes and hardware failures without
losing any committed transactions.</para></listitem>
</itemizedlist></para>
<para>In this document I assume that you choose the <command>BDB database.</command></para>
<para>To import and export directory information between LDAP-based directory servers,
or to describe a set of changes which are to be applied to a directory, the
file format known as LDIF, for LDAP Data Interchange Format, is typically used.
A LDIF file stores information in object-oriented hierarchies of entries. The
LDAP software package you're going to get comes with an utility to convert LDIF
files to the BDB format</para>
<para>A common LDIF file looks like this:</para>
<screen>
dn: o=TUDelft, c=NL
o: TUDelft
objectclass: organization
dn: cn=Luiz Malere, o=TUDelft, c=NL
cn: Luiz Malere
sn: Malere
mail: malere@yahoo.com
objectclass: person
</screen>
<para>As you can see each entry is uniquely identified by a distinguished name, or
DN. The DN consists of the name of the entry plus a path of names tracing the
entry back to the top of the directory hierarchy (just like a tree).</para>
<para>In LDAP, an <command>object class</command> defines the collection of <command>attributes</command> that can be used
to define an entry. The LDAP standard provides these basic types of object classes:</para>
<itemizedlist>
<listitem><para>Groups in the directory, including unordered lists of individual objects
or groups of objects.</para></listitem>
<listitem><para>Locations, such as the country name and description.</para></listitem>
<listitem><para>Organizations in the directory.</para></listitem>
<listitem><para>People in the directory.</para></listitem>
</itemizedlist>
<para>An entry can belong to more than one object class. For example, the entry for a
person is defined by the <emphasis>person</emphasis> object class, but may also be
defined by attributes in the inetOrgPerson, groupOfNames, and organization objectclasses.
The server's object class structure (it's schema) determines the total list of required and
allowed attributes for a particular entry.</para>
<para>Directory data is represented as attribute-value pairs. Any specific piece of
information is associated with a descriptive attribute.</para>
<para>For instance, the commonName, or cn, attribute is used to store a person's name
. A person named Jonas Salk can be represented in the directory as</para>
<screen>cn: Jonas Salk</screen>
<para>Each person entered in the directory is defined by the collection of attributes
in the <emphasis>person</emphasis> object class. Other attributes used to define this
entry could include:</para>
<screen>
givenname: Jonas
surname: Salk
mail: jonass@airius.com
</screen>
<para>Required attributes include the attributes that must be present in entries
using the object class. All entries require the objectClass attribute, which
lists the object classes to which an entry belongs.</para>
<para>Allowed attributes include the attributes that may be present in entries using
the object class. For example, in the person object class, the cn and sn
attributes are required. The description, telephoneNumber, seeAlso, and
userpassword attributes are allowed but are not required.</para>
<para>Each attribute has a corresponding syntax definition. The syntax definition
describes the type of information provided by the attribute, for instance:</para>
<itemizedlist>
<listitem><para>bin binary.</para></listitem>
<listitem><para>ces case exact string (case must match during comparisons).</para></listitem>
<listitem><para>cis case ignore string (case is ignored during comparisons).</para></listitem>
<listitem><para>tel telephone number string (like cis but blanks and dashes `- ' are
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts and with no Back-Cover
Texts. A copy of the license is included in the section entitled "GNU
Free Documentation License".</para>
<para>If you have questions, please visit the following url: <ulinkurl="http://www.gnu.org/licenses/fdl.txt">http://www.gnu.org/licenses/fdl.txt</ulink>
and contact the Linux HOWTO coordinator, at: <ulinkurl="guylhem@metalab.unc.edu">guylhem@metalab.unc.edu</ulink></para></section>
</chapter>
<chapterid="Installing"><title>Installing the LDAP Server</title>
<para>Five steps are necessary to install the server:
<itemizedlist>
<listitem><para>Install the pre-required
packages (if not already installed).</para></listitem>
<listitem><para>Download the server.</para></listitem>
<listitem><para>Unpack the software.</para></listitem>
<listitem><para>Configure the Makefiles.</para></listitem>
<listitem><para>Build the server.</para></listitem>
</itemizedlist></para>
<sectionid="PreReq">
<title>Pre-Requirements</title>
<para>To be fully LDAPv3 compliant, OpenLDAP clients and servers require installation
of some additional packages. For writing this document, I've used a Mandrake 9.0 box with
a 2.4.20 Kernel, manually installing the Berkeley BDB package and SASL libraries.</para>
<para>OpenLDAP clients and servers support Kerberos-based authentication services.
In particular, OpenLDAP supports SASL/GSSAPI authentication mechanism using
either Heimdal or MIT Kerberos V packages. If you desire to use Kerberos-based
SASL/GSSAPI authentication, you should install either Heimdal or MIT Kerberos V.
Heimdal Kerberos is available from <ulinkurl="http://www.pdc.kth.se/heimdal">http://www.pdc.kth.se/heimdal</ulink>
MIT Kerberos is available from <ulinkurl="http://web.mit.edu/kerberos/www">http://web.mit.edu/kerberos/www</ulink></para>
<para>The use of strong authentication services, such as those provided by Kerberos,
is highly recommended.</para>
<para><command>Cyrus's Simple Authentication and Security Layer Libraries</command></para>
<para>Cyrus's SASL libraries are normally part of the base system or compose an
optional software component. Cyrus SASL is available from <ulinkurl="http://asg.web.cmu.edu/sasl/sasl-library.html">http://asg.web.cmu.edu/sasl/sasl-library.html</ulink>.
Cyrus SASL will make use of OpenSSL and Kerberos/GSSAPI libraries if preinstalled. By the time of this
<para>This directive specifies the indexes to maintain for the given attribute. If
only an <attrlist> is given, the default indexes are maintained.</para>
<para>Example:</para>
<screen>
index default pres,eq
index uid
index cn,sn pres,eq,sub
index objectClass eq
</screen>
<para>The first line sets the default set of indexes to maintain to present and
equality. The second line causes the default (pres,eq) set of indices to be
maintained for the uid attribute type. The third line causes present, equality and substring
indices to be maintained for cn and sn attribute types. The fourth line causes an equality
index for the objectClass attribute type.</para>
<para>By default, no indices are maintained. It is generally advised that minimally
an equality index upon objectClass be maintained.</para>
<para>index objectClass eq</para>
<screen>mode <integer></screen>
<para>This directive specifies the file protection mode that newly created database
index files should have.</para>
<para>Default:</para>
<para>mode 0600</para></section>
<sectionid="AccessControl">
<title>Access Control Examples</title>
<para>The access control facility provided by the <emphasis>access</emphasis> directive is
quite powerful. This section shows some examples of it's use. First, some simple examples: </para>
<screen>access to * by * read </screen>
<para>This access directive grants read access to everyone.</para>
<para>The following example shows the use of a regular expression to select the
entries by DN in two access directives where ordering is significant. </para>
<screen>access to dn=".*, o=U of M, c=US"
by * search
access to dn=".*, c=US"
by * read </screen>
<para>Read access is granted to entries under the c=US subtree, except for those
entries under the "o=U of M, c=US" subtree, to which search access is granted. No access
is granted to c=US as neither access directive matches this DN.If the order of these
access directives was reversed, the U-M-specific directive would never be matched, since
all U-M entries are also c=US entries. </para>
<para>Another way to implement the same access controls is:</para>
<screen>access to dn.children="dc=example,dc=com"
by * search
access to dn.children="dc=com"
by * read
</screen>
<para>Read access is granted to entries under the dc=com subtree, except for those entries
under the dc=example,dc=com subtree, to which search access is granted. No access is granted
to dc=com as neither access directive matches this DN. If the order of these access directives
was reversed, the trailing directive would never be reached, since all entries under
dc=example,dc=com are also under dc=com entries.</para>
<para><command>Note:</command> Also note that if no access to directive or no "by <who>" clause matches,
<command>access is denied</command>. That is, every <emphasis>access to</emphasis> directive ends with an implicit <emphasis>by * none </emphasis>clause
and every access list ends with an implicit <emphasis>access to * by * none</emphasis> directive.</para>
<para>The next example again shows the importance of ordering, both of the access
directives and the "by <who>" clauses. It also shows the use of an attribute selector
to grant access to a specific attribute and various <who> selectors. </para>
<screen>access to dn.subtree="dc=example,dc=com" attr=homePhone
by self write
by dn.children=dc=example,dc=com" search
by peername=IP:10\..+ read
access to dn.subtree="dc=example,dc=com"
by self write
by dn.children="dc=example,dc=com" search
by anonymous auth
</screen>
<para>This example applies to entries in the "dc=example,dc=com" subtree. To all
attributes except homePhone, an entry can write to itself, entries under
example.com entries can search by them, anybody else has no access (implicit by * none)
excepting for authentication/authorization (which is always done anonymously). The
homePhone attribute is writable by the entry, searchable by entries under example.com,
readable by clients connecting from network 10, and otherwise not readable
(implicit by * none). All other access is denied by the implicit access to * by * none.</para>
<para>Sometimes it is useful to permit a particular DN to add or remove itself from
an attribute. For example, if you would like to create a group and allow people
to add and remove only their own DN from the member attribute, you could accomplish
it with an access directive like this: </para>
<screen>access to attr=member,entry
by dnattr=member selfwrite
</screen>
<para>The dnattr <who> selector says that the access applies to entries listed
in the member attribute. The selfwrite access selector says that such members
can only add or delete their own DN from the attribute, not other values. The
addition of the entry attribute is required because access to the entry is
required to access any of the entry's attributes. </para>
<para>There's plenty of information about Access Control on the OpenLDAP
Administrator's Guide. Take a look at: <ulinkurl="http://www.openldap.org/doc/admin22/slapdconfig.html#Access Control">Access Control</ulink>
for more information about this subject.</para></section>
<sectionid="ConfigurationExample">
<title>Configuration File Example</title>
<para>The following is an example configuration file, interspersed with explanatory
text. It defines two databases to handle different parts of the X.500 tree;
both are BDB database instances. The line numbers shown are provided for
reference only and are not included in the actual file. First, the global
configuration section:</para>
<screen>
1. # example config file - global configuration section
2. include /usr/local/etc/schema/core.schema
3. referral ldap://root.openldap.org
4. access to * by * read</screen>
<para>Line 1 is a comment. Line 2 includes another config file which contains core
schema definitions. The referral directive on line 3 means that queries not
local to one of the databases defined below will be referred to the LDAP server
running on the standard port (389) at the host root.openldap.org.</para>
<para>Line 4 is a global access control. It applies to all entries (after any applicable
database-specific access controls).</para>
<para>The next section of the configuration file defines a BDB backend that will
handle queries for things in the "dc=example,dc=com" portion of the tree. The database
is to be replicated to two slave slapds, one on truelies, the other on judgmentday. Indexes
are to be maintained for several attributes, and the userPassword attribute is to be protected
<para>Lines 11 through 18 are for replication. See the <ulinkurl="http://www.openldap.org/doc/admin22/replication.html">Replication</ulink> link for more information on these directives.</para>
<para>Lines 20 through 22 indicate the indexes to maintain for various attributes.</para>
<para>Lines 24 through 32 specify access control for entries in the this database.
As this is the first database, the controls also apply to entries not held in any
database (such as the Root DSE). For all applicable entries, the userPassword
attribute is writable by the entry itself and by the "admin" entry. It may be used for
authentication/authorization purposes, but is otherwise not readable. All other attributes
are writable by the entry and the "admin" entry, but may be read by all users (authenticated or not).</para>
<para>The next section of the example configuration file defines another BDB database.
This one handles queries involving the dc=example,dc=net subtree but is managed by the same
entity as the first database. Note that without line 39, the read access would be allowed due
to the global access rule at line 4.</para>
<screen>
33. # BDB definition for example.net
34. database bdb
35. suffix "dc=example,dc=net"
36. directory /usr/local/var/openldap-data-net
37. rootdn "cn=Manager,dc=example,dc=com"
38. index objectClass eq
39. access to * by users read</screen></section>
</chapter>
<chapterid="RunningLDAP"><title>Running the LDAP Server</title>
<para>The LDAP daemon <emphasis>slapd</emphasis> is designed to be run as a
stand-alone server. This allows the server to take advantage of caching, manage concurrency
issues with underlying databases, and conserve system resources. Running from inetd(8) is not
an option.</para>
<sectionid="CommandOptions">
<title>Command Line Options</title>
<para><emphasis>Slapd</emphasis> supports a number of command-line options as detailed
in the manual page. This section details a few commonly used options:</para>
<screen>-f <filename></screen>
<para>This option specifies an alternate configuration file for slapd. The default is
<para>To access the LDAP service, the LDAP client first must authenticate itself to
the service. That is, it must tell the LDAP server who is going to be accessing
the data so that the server can decide what the client is allowed to see and
do. If the client authenticates successfully to the LDAP server, then when the
server subsequently receives a request from the client, it will check whether
the client is allowed to perform the request. This process is called access
control. </para>
<para>In LDAP, authentication is supplied in the "bind" operation. Ldapv3 supports
three types of authentication: anonymous, simple and SASL authentication. A
client that sends a LDAP request without doing a "bind" is treated as an
anonymous client. Simple authentication consists of sending the LDAP server the
fully qualified DN of the client (user) and the client's clear-text password.
This mechanism has security problems because the password can be read from the
network. To avoid exposing the password in this way, you can use the simple
authentication mechanism within an encrypted channel (such as SSL), provided
that this is supported by the LDAP server. </para>
<para>Finally, SASL is the Simple Authentication and Security Layer (RFC 2222). It
specifies a challenge-response protocol in which data is exchanged between the
client and the server for the purposes of authentication and establishment of a
security layer on which to carry out subsequent communication. By using SASL,
LDAP can support any type of authentication agreed upon by the LDAP client and
server.
The Cyrus-SASL package is available at the following URL: <ulinkurl="http://asg.web.cmu.edu/sasl/sasl-library.html">http://asg.web.cmu.edu/sasl/sasl-library.html</ulink>.
</para>
<para>Further on authenticating users to access information from your Directory Tree,
your LDAP server can authenticate users from other services too (Sendmail,
Login, Ftp, etc.). This is accomplished migrating specific user information to
your LDAP server and using a mechanism called PAM (Pluggable Authentication
Module). The authentication module for LDAP is available as a tar ball on the following
<para>The username is taken from sasl and inserted into the ldap search string in the place of $1.Your realm is supposed to be your FQDN (fully qualified domain name), but in some cases it isn't, like mine. To find out what your realm is do:</para>
<screen>root@rdnt03:~# sasldblistusers2
admin@rdnt03: userPassword
admin@rdnt03: cmusaslsecretOTP</screen>
<para>In my case, <emphasis>rdnt03</emphasis> is indicated as the realm. If it is your FQDN you shouldn't have any problems. I use the following LDIF file:
</para>
<screen>dn: o=Ever
o: Ever
description: Organization Root
objectClass: top
objectClass: organization
dn: ou=Staff, o=Ever
ou: Staff
description: These are privileged users that can interact with Organization products
objectClass: top
objectClass: organizationalUnit
dn: ou=People, o=Ever
ou: People
objectClass: top
objectClass: organizationalUnit
dn: uid=admin, ou=Staff, o=Ever
uid: admin
cn: LDAP Adminstrator
sn: admin
userPassword: {SHA}5en6G6MezRroT3XKqkdPOmY/BfQ=
objectClass: Top
objectClass: Person
objectClass: Organizationalperson
objectClass: Inetorgperson
dn: uid=admin,ou=People,o=Ever
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
userPassword: {SHA}5en6G6MezRroT3XKqkdPOmY/BfQ=
displayName: admin
mail: admin@eversystems.com.br
uid: admin
cn: Administrator
sn: admin
</screen>
<para>Add the entries to your LDAP directory using the following command:</para>
<para>That's it ! If you prefer to use SASL with Kerberos V or GSSAPI, there's a useful link at
<ulinkurl="http://www.openldap.org/doc/admin22/sasl.html">http://www.openldap.org/doc/admin22/sasl.html</ulink>. This link assumes you've already managed to install and configure the SASL library.
The mailing lists will help you get going with this matter: <ulinkurl="http://asg.web.cmu.edu/sasl/index.html#mailinglists">http://asg.web.cmu.edu/sasl/index.html#mailinglists</ulink></para></section>
<sectionid="Graphicaltools">
<title>Graphical LDAP tools</title>
<para><command>Kldap</command> is a graphical LDAP client written for KDE. Kldap has a nice
interface and is able to show all the information tree stored on your Directory. You can
check some screenshots of the application and download it at: