Chapter 17.

DIRECTORY Servers:

17.1. OpenLDAP
17.1.1. Introduction to LDAP
17.1.2. Installing the OpenLDAP Suite
17.1.3. Configuring an OpenLDAP Server
17.1.4. Running an OpenLDAP Server
17.1.5. Configuring a System to Authenticate Using OpenLDAP
17.1.6. Additional Resources
17.1. OpenLDAP
LDAP (Lightweight Directory Access Protocol) is a set of open protocols used to access
centrally stored information over a network. It is based on the X.500 standard for
directory sharing, but is less complex and resource-intensive. For this reason, LDAP is
sometimes referred to as “X.500 Lite”.

Like X.500, LDAP organizes information in a hierarchical manner using directories.

These directories can store a variety of information such as names, addresses, or
phone numbers, and can even be used in a manner similar to the Network Information
Service (NIS), enabling anyone to access their account from any machine on the LDAP
enabled network.

LDAP is commonly used for centrally managed users and groups, user authentication,
or system configuration. It can also serve as a virtual phone directory, allowing users
to easily access contact information for other users. Additionally, it can refer a user
to other LDAP servers throughout the world, and thus provide an ad-hoc global
repository of information. However, it is most frequently used within individual
organizations such as universities, government departments, and private companies.

This section covers the installation and configuration of OpenLDAP 2.4, an open
source implementation of the LDAPv2 and LDAPv3 protocols.

17.1.1. Introduction to LDAP

Using a client/server architecture, LDAP provides reliable means to create a central
information directory accessible from the network. When a client attempts to modify
information within this directory, the server verifies the user has permission to make
the change, and then adds or updates the entry as requested. To ensure the
communication is secure, the Secure Sockets Layer (SSL) or Transport Layer Security
(TLS) cryptographic protocols can be used to prevent an attacker from intercepting
the transmission.

Using Mozilla NSS

The OpenLDAP suite in Red Hat Enterprise Linux 6 no longer uses OpenSSL. Instead, it
uses the Mozilla implementation of Network Security Services (NSS). OpenLDAP
continues to work with existing certificates, keys, and other TLS configuration. For
more information on how to configure it to use Mozilla certificate and key database,
refer to How do I use TLS/SSL with Mozilla NSS.

The LDAP server supports several database systems, which gives administrators the
flexibility to choose the best suited solution for the type of information they are
planning to serve. Because of a well-defined client Application Programming Interface
(API), the number of applications able to communicate with an LDAP server is
numerous, and increasing in both quantity and quality.

17.1.1.1. LDAP Terminology

The following is a list of LDAP-specific terms that are used within this chapter:

entry
A single unit within an LDAP directory. Each entry is identified by its unique
Distinguished Name (DN).

attribute
Information directly associated with an entry. For example, if an organization
is represented as an LDAP entry, attributes associated with this organization
might include an address, a fax number, etc. Similarly, people can be
represented as entries with common attributes such as personal telephone
number or email address.

An attribute can either have a single value, or an unordered space-separated

list of values. While certain attributes are optional, others are required.
Required attributes are specified using the objectClass definition, and can be
found in schema files located in the
/etc/openldap/slapd.d/cn=config/cn=schema/ directory.

The assertion of an attribute and its corresponding value is also referred to as a

Relative Distinguished Name (RDN). Unlike distinguished names that are unique
globally, a relative distinguished name is only unique per entry.

LDIF
The LDAP Data Interchange Format (LDIF) is a plain text representation of an
LDAP entry. It takes the following form:
 [id] dn: distinguished_name
attribute_type: attribute_value…
attribute_type: attribute_value…
…
The optional id is a number determined by the application that is used to edit
the entry. Each entry can contain as many attribute_type and
attribute_value pairs as needed, as long as they are all defined in a
corresponding schema file. A blank line indicates the end of an entry.

17.1.1.2. OpenLDAP Features

OpenLDAP suite provides a number of important features:

LDAPv3 Support — Many of the changes in the protocol since LDAP version 2 are
designed to make LDAP more secure. Among other improvements, this includes the
support for Simple Authentication and Security Layer (SASL), Transport Layer
Security (TLS), and Secure Sockets Layer (SSL) protocols.
LDAP Over IPC — The use of inter-process communication (IPC) enhances security by
eliminating the need to communicate over a network.
IPv6 Support — OpenLDAP is compliant with Internet Protocol version 6 (IPv6), the
next generation of the Internet Protocol.
LDIFv1 Support — OpenLDAP is fully compliant with LDIF version 1.
Updated C API — The current C API improves the way programmers can connect to
and use LDAP directory servers.
Enhanced Standalone LDAP Server — This includes an updated access control system,
thread pooling, better tools, and much more.

17.1.1.3. OpenLDAP Server Setup

The typical steps to set up an LDAP server on Red Hat Enterprise Linux are as follows:

1. Install the OpenLDAP suite. Refer to Section 17.1.2, “Installing the OpenLDAP Suite”
for more information on required packages.
2. Customize the configuration as described in Section 17.1.3, “Configuring an OpenLDAP
Server”.
3. Start the slapd service as described in Section 17.1.4, “Running an OpenLDAP
Server”.
4. Use the ldapadd utility to add entries to the LDAP directory.
5. Use the ldapsearch utility to verify that the slapd service is accessing the information
correctly.

17.1.2. Installing the OpenLDAP Suite

The suite of OpenLDAP libraries and tools is provided by the following packages:

Table 17.1. List of OpenLDAP packages

Package Description

openldap A package containing the libraries necessary to run the OpenLDAP

server and client applications.

openldap- A package containing the command line utilities for viewing and
clients modifying directories on an LDAP server.

openldap- A package containing both the services and utilities to configure

servers and run an LDAP server. This includes the Standalone LDAP
Daemon, slapd.

openldap- A package containing the SQL support module.

servers-sql

compat- A package containing the OpenLDAP compatibility libraries.

openldap

Additionally, the following packages are commonly used along with the LDAP server:

Table 17.2. List of commonly installed additional LDAP packages

Package Description

nss-pam-ldapd A package containing nslcd, a local LDAP name service that

allows a user to perform local LDAP queries.

mod_authz_ldap A package containing mod_authz_ldap, the LDAP authorization

module for the Apache HTTP Server. This module uses the short
form of the distinguished name for a subject and the issuer of
the client SSL certificate to determine the distinguished name of
the user within an LDAP directory. It is also capable of
authorizing users based on attributes of that user's LDAP
 Package Description

directory entry, determining access to assets based on the user

and group privileges of the asset, and denying access for users
with expired passwords. Note that the mod_ssl module is
required when using the mod_authz_ldap module.

To install these packages, use the yum command in the following form:

yum install package…

For example, to perform the basic LDAP server installation, type the following at a
shell prompt:

~]# yum install openldap openldap-clients openldap-servers

Note that you must have superuser privileges (that is, you must be logged in as root)
to run this command. For more information on how to install new packages in Red Hat
Enterprise Linux, refer to Section 6.2.4, “Installing Packages”.

17.1.2.1. Overview of OpenLDAP Server Utilities

To perform administrative tasks, the openldap-servers package installs the following
utilities along with the slapd service:

Table 17.3. List of OpenLDAP server utilities

Command Description

slapacl Allows you to check the access to a list of attributes.

slapadd Allows you to add entries from an LDIF file to an LDAP directory.

slapauth Allows you to check a list of IDs for authentication and authorization
permissions.

slapcat Allows you to pull entries from an LDAP directory in the default format
and save them in an LDIF file.
 Command Description

slapdn Allows you to check a list of Distinguished Names (DNs) based on

available schema syntax.

slapindex Allows you to re-index the slapd directory based on the current
content. Run this utility whenever you change indexing options in the
configuration file.

slappasswd Allows you to create an encrypted user password to be used with the
ldapmodify utility, or in the slapd configuration file.

slapschema Allows you to check the compliance of a database with the

corresponding schema.

slaptest Allows you to check the LDAP server configuration.

For a detailed description of these utilities and their usage, refer to the
corresponding manual pages as referred to in Section 17.1.6.1, “Installed
Documentation”.

Make sure the files have correct owner

Although only root can run slapadd, the slapd service runs as the ldap user. Because
of this, the directory server is unable to modify any files created by slapadd. To
correct this issue, after running the slapd utility, type the following at a shell
prompt:
~]# chown -R ldap:ldap /var/lib/ldap

Stop slapd before using these utilities

To preserve the data integrity, stop the slapd service before using slapadd, slapcat,
or slapindex. You can do so by typing the following at a shell prompt:
~]# service slapd stop

Stopping slapd: [ OK ]

For more information on how to start, stop, restart, and check the current status of
the slapd service, refer to Section 17.1.4, “Running an OpenLDAP Server”.
17.1.2.2. Overview of OpenLDAP Client Utilities
The openldap-clients package installs the following utilities which can be used to add,
modify, and delete entries in an LDAP directory:

Table 17.4. List of OpenLDAP client utilities

Command Description

ldapadd Allows you to add entries to an LDAP directory, either from a file, or
from standard input. It is a symbolic link to ldapmodify -a.

ldapcompare Allows you to compare given attribute with an LDAP directory entry.

ldapdelete Allows you to delete entries from an LDAP directory.

ldapexop Allows you to perform extended LDAP operations.

ldapmodify Allows you to modify entries in an LDAP directory, either from a file,
or from standard input.

ldapmodrdn Allows you to modify the RDN value of an LDAP directory entry.

ldappasswd Allows you to set or change the password for an LDAP user.

ldapsearch Allows you to search LDAP directory entries.

ldapurl Allows you to compose or decompose LDAP URLs.

ldapwhoami Allows you to perform a whoami operation on an LDAP server.

With the exception of ldapsearch, each of these utilities is more easily used by
referencing a file containing the changes to be made rather than typing a command
for each entry to be changed within an LDAP directory. The format of such a file is
outlined in the man page for each utility.

17.1.2.3. Overview of Common LDAP Client Applications

Although there are various graphical LDAP clients capable of creating and modifying
directories on the server, none of them is included in Red Hat Enterprise Linux.
Popular applications that can access directories in a read-only mode include Mozilla
Thunderbird, Evolution, or Ekiga.

17.1.3. Configuring an OpenLDAP Server

By default, the OpenLDAP configuration is stored in the /etc/openldap/ directory. The
following table highlights the most important directories and files within this
directory:

Table 17.5. List of OpenLDAP configuration files and directories

Path Description

/etc/openldap/ldap.conf The configuration file for client applications that use

the OpenLDAP libraries. This includes ldapadd,
ldapsearch, Evolution, etc.

/etc/openldap/slapd.d/ The directory containing the slapd configuration.

Note that OpenLDAP no longer reads its configuration from the

/etc/openldap/slapd.conf file. Instead, it uses a configuration database located in
the /etc/openldap/slapd.d/ directory. If you have an existing slapd.conf file from a
previous installation, you can convert it to the new format by running the following
command:

~]# slaptest -f /etc/openldap/slapd.conf -F /etc/openldap/slapd.d/

The slapd configuration consists of LDIF entries organized in a hierarchical directory

structure, and the recommended way to edit these entries is to use the server
utilities described in Section 17.1.2.1, “Overview of OpenLDAP Server Utilities”.

Do not edit LDIF files directly

An error in an LDIF file can render the slapd service unable to start. Because of this,
it is strongly advised that you avoid editing the LDIF files within the
/etc/openldap/slapd.d/ directly.
17.1.3.1. Changing the Global Configuration
Global configuration options for the LDAP server are stored in the
/etc/openldap/slapd.d/cn=config.ldif file. The following directives are commonly
used:

olcAllows
The olcAllows directive allows you to specify which features to enable. It takes
the following form:

olcAllows: feature…

It accepts a space-separated list of features as described in Table 17.6,

“Available olcAllows options”. The default option is bind_v2.

Table 17.6. Available olcAllows options

Option Description

bind_v2 Enables the acceptance of LDAP version 2 bind requests.

bind_anon_cred Enables an anonymous bind when the Distinguished Name (DN)

is empty.

bind_anon_dn Enables an anonymous bind when the Distinguished Name (DN)

is not empty.

update_anon Enables processing of anonymous update operations.

proxy_authz_anon Enables processing of anonymous proxy authorization control.

Example 17.1. Using the olcAllows directive

olcAllows: bind_v2 update_anon

olcConnMaxPending
The olcConnMaxPending directive allows you to specify the maximum number of
pending requests for an anonymous session. It takes the following form:

olcConnMaxPending: number
The default option is 100.

Example 17.2. Using the olcConnMaxPending directive

olcConnMaxPending: 100

olcConnMaxPendingAuth
The olcConnMaxPendingAuth directive allows you to specify the maximum
number of pending requests for an authenticated session. It takes the following
form:

olcConnMaxPendingAuth: number

The default option is 1000.

Example 17.3. Using the olcConnMaxPendingAuth directive

olcConnMaxPendingAuth: 1000

olcDisallows
The olcDisallows directive allows you to specify which features to disable. It
takes the following form:

olcDisallows: feature…

It accepts a space-separated list of features as described in Table 17.7,

“Available olcDisallows options”. No features are disabled by default.

Table 17.7. Available olcDisallows options

Option Description

bind_anon Disables the acceptance of anonymous bind requests.

bind_simple Disables the simple bind authentication mechanism.

tls_2_anon Disables the enforcing of an anonymous session when the STARTTLS

command is received.
 Option Description

tls_authc Disallows the STARTTLS command when authenticated.

Example 17.4. Using the olcDisallows directive

olcDisallows: bind_anon

olcIdleTimeout
The olcIdleTimeout directive allows you to specify how many seconds to wait
before closing an idle connection. It takes the following form:

olcIdleTimeout: number

This option is disabled by default (that is, set to 0).

Example 17.5. Using the olcIdleTimeout directive

olcIdleTimeout: 180

olcLogFile
The olcLogFile directive allows you to specify a file in which to write log
messages. It takes the following form:

olcLogFile: file_name

The log messages are written to standard error by default.

Example 17.6. Using the olcLogFile directive

olcLogFile: /var/log/slapd.log

olcReferral
The olcReferral option allows you to specify a URL of a server to process the
request in case the server is not able to handle it. It takes the following form:
 olcReferral: URL

This option is disabled by default.

Example 17.7. Using the olcReferral directive

olcReferral: ldap://root.openldap.org

olcWriteTimeout
The olcWriteTimeout option allows you to specify how many seconds to wait
before closing a connection with an outstanding write request. It takes the
following form:

olcWriteTimeout

This option is disabled by default (that is, set to 0).

Example 17.8. Using the olcWriteTimeout directive

olcWriteTimeout: 180

17.1.3.2. Changing the Database-Specific Configuration

By default, the OpenLDAP server uses Berkeley DB (BDB) as a database back end. The
configuration for this database is stored in the
/etc/openldap/slapd.d/cn=config/olcDatabase={1}bdb.ldif file. The following
directives are commonly used in a database-specific configuration:

olcReadOnly
The olcReadOnly directive allows you to use the database in a read-only mode.
It takes the following form:

olcReadOnly: boolean

It accepts either TRUE (enable the read-only mode), or FALSE (enable

modifications of the database). The default option is FALSE.

Example 17.9. Using the olcReadOnly directive

olcReadOnly: TRUE

olcRootDN
The olcRootDN directive allows you to specify the user that is unrestricted by
access controls or administrative limit parameters set for operations on the
LDAP directory. It takes the following form:

olcRootDN: distinguished_name

It accepts a Distinguished Name (DN). The default option is cn=Manager,dn=my-

domain,dc=com.

Example 17.10. Using the olcRootDN directive

olcRootDN: cn=root,dn=example,dn=com

olcRootPW
The olcRootPW directive allows you to set a password for the user that is
specified using the olcRootDN directive. It takes the following form:

olcRootPW: password

It accepts either a plain text string, or a hash. To generate a hash, type the
following at a shell prompt:

~]$ slappaswd

New password:

Re-enter new password:

{SSHA}WczWsyPEnMchFf1GRTweq2q7XJcvmSxD

Example 17.11. Using the olcRootPW directive

olcRootPW: {SSHA}WczWsyPEnMchFf1GRTweq2q7XJcvmSxD

olcSuffix
 The olcSuffix directive allows you to specify the domain for which to provide
information. It takes the following form:

olcSuffix: domain_name

It accepts a fully qualified domain name (FQDN). The default option is dc=my-
domain,dc=com.

Example 17.12. Using the olcSuffix directive

olcSuffix: dc=example,dc=com

17.1.3.3. Extending Schema

Since OpenLDAP 2.3, the /etc/openldap/slapd.d/ directory also contains LDAP
definitions that were previously located in /etc/openldap/schema/. It is possible to
extend the schema used by OpenLDAP to support additional attribute types and
object classes using the default schema files as a guide. However, this task is beyond
the scope of this chapter. For more information on this topic, refer to
http://www.openldap.org/doc/admin/schema.html.

17.1.4. Running an OpenLDAP Server

This section describes how to start, stop, restart, and check the current status of the
Standalone LDAP Daemon. For more information on how to manage system services
in general, refer to Chapter 10, Services and Daemons.

17.1.4.1. Starting the Service

To run the slapd service, type the following at a shell prompt:

~]# service slapd start

Starting slapd: [ OK ]

If you want the service to start automatically at the boot time, use the following
command:

~]# chkconfig slapd on

Note that you can also use the Service Configuration utility as described in
Section 10.2.1.1, “Enabling and Disabling a Service”.

17.1.4.2. Stopping the Service

To stop the running slapd service, type the following at a shell prompt:

~]# service slapd stop

Stopping slapd: [ OK ]

To prevent the service from starting automatically at the boot time, type:

~]# chkconfig slapd off

Alternatively, you can use the Service Configuration utility as described in

Section 10.2.1.1, “Enabling and Disabling a Service”.

17.1.4.3. Restarting the Service

To restart the running slapd service, type the following at a shell prompt:

~]# service slapd restart

Stopping slapd: [ OK ]

Starting slapd: [ OK ]

This stops the service, and then starts it again. Use this command to reload the
configuration.

17.1.4.4. Checking the Service Status

To check whether the service is running, type the following at a shell prompt:

~]# service slapd status

slapd (pid 3672) is running...

17.1.5. Configuring a System to Authenticate Using OpenLDAP

In order to configure a system to authenticate using OpenLDAP, make sure that the
appropriate packages are installed on both LDAP server and client machines. For
information on how to set up the server, follow the instructions in Section 17.1.2,
“Installing the OpenLDAP Suite” and Section 17.1.3, “Configuring an OpenLDAP
Server”. On a client, type the following at a shell prompt:

~]# yum install openldap openldap-clients nss-pam-ldapd

Chapter 11, Configuring Authentication provides detailed instructions on how to

configure applications to use LDAP for authentication.

17.1.5.1. Migrating Old Authentication Information to LDAP Format

The migrationtools package provides a set of shell and Perl scripts to help you
migrate authentication information into an LDAP format. To install this package, type
the following at a shell prompt:

~]# yum install migrationtools

This will install the scripts to the /usr/share/migrationtools/ directory. Once

installed, edit the /usr/share/migrationtools/migrate_common.ph file and change the
following lines to reflect the correct domain, for example:

# Default DNS domain

$DEFAULT_MAIL_DOMAIN = "example.com";

# Default base

$DEFAULT_BASE = "dc=example,dc=com";

Alternatively, you can specify the environment variables directly on the command
line. For example, to run the migrate_all_online.sh script with the default base set
to dc=example,dc=com, type:

~]# export DEFAULT_BASE="dc=example,dc=com" \

/usr/share/migrationtools/migrate_all_online.sh

To decide which script to run in order to migrate the user database, refer to
Table 17.8, “Commonly used LDAP migration scripts”.

Table 17.8. Commonly used LDAP migration scripts

 Existing Name Service Is LDAP Running? Script to Use

/etc flat files yes migrate_all_online.sh

/etc flat files no migrate_all_offline.sh

NetInfo yes migrate_all_netinfo_online.sh

NetInfo no migrate_all_netinfo_offline.sh

NIS (YP) yes migrate_all_nis_online.sh

NIS (YP) no migrate_all_nis_offline.sh

For more information on how to use these scripts, refer to the README and the
migration-tools.txt files in the /usr/share/doc/migrationtools-version/ directory.

17.1.6. Additional Resources

The following resources offer additional information on the Lightweight Directory
Access Protocol. Before configuring LDAP on your system, it is highly recommended
that you review these resources, especially the OpenLDAP Software Administrator's
Guide.

17.1.6.1. Installed Documentation

The following documentation is installed with the openldap-servers package:

/usr/share/doc/openldap-servers-version/guide.html
A copy of the OpenLDAP Software Administrator's Guide.

/usr/share/doc/openldap-servers-version/README.schema
A README file containing the description of installed schema files.

Additionally, there is also a number of manual pages that are installed with the
openldap, openldap-servers, and openldap-clients packages:

Client Applications
man ldapadd — Describes how to add entries to an LDAP directory.
man ldapdelete — Describes how to delete entries within an LDAP directory.
 man ldapmodify — Describes how to modify entries within an LDAP directory.
man ldapsearch — Describes how to search for entries within an LDAP directory.
man ldappasswd — Describes how to set or change the password of an LDAP
user.
man ldapcompare — Describes how to use the ldapcompare tool.
man ldapwhoami — Describes how to use the ldapwhoami tool.
man ldapmodrdn — Describes how to modify the RDNs of entries.

Server Applications
man slapd — Describes command line options for the LDAP server.

Administrative Applications
man slapadd — Describes command line options used to add entries to a slapd
database.
man slapcat — Describes command line options used to generate an LDIF file
from a slapd database.
man slapindex — Describes command line options used to regenerate an index
based upon the contents of a slapd database.
man slappasswd — Describes command line options used to generate user
passwords for LDAP directories.

Configuration Files
man ldap.conf — Describes the format and options available within the
configuration file for LDAP clients.
man slapd-config — Describes the format and options available within the
configuration directory.

17.1.6.2. Useful Websites

http://www.openldap.org/doc/admin24/
The current version of the OpenLDAP Software Administrator's Guide.

http://www.kingsmountain.com/ldapRoadmap.shtml
Jeff Hodges' LDAP Roadmap & FAQ containing links to several useful resources
and emerging news concerning the LDAP protocol.
 http://www.ldapman.org/articles/
A collection of articles that offer a good introduction to LDAP, including
methods to design a directory tree and customizing directory structures.

http://www.padl.com/
A website of developers of several useful LDAP tools.

17.1.6.3. Related Books

OpenLDAP by Example by John Terpstra and Benjamin Coles; Prentice Hall.
A collection of practical exercises in the OpenLDAP deployment.

Implementing LDAP by Mark Wilcox; Wrox Press, Inc.

A book covering LDAP from both the system administrator's and software
developer's perspective.

Understanding and Deploying LDAP Directory Services by Tim Howes

et al.; Macmillan Technical Publishing.
A book covering LDAP design principles, as well as its deployment in a
production environment.