LDAP Resources

Install and Configure OpenLDAP on CentOS 5

by Jeff Hunter, Sr. Database Administrator

Contents

• Introduction
• Install OpenLDAP Server
• slapd Configuration – (slapd.conf)
• Start / Stop LDAP Server
• Configure System-Wide Defaults
• Further Reading
• About the Author

Introduction

The Lightweight Directory Access Protocol (LDAP) is an application protocol used to access information in a directory over an IP network. Most information in a directory is organized with a hierarchical structure much like a file system. A directory can contain any type of data but most often consists of organizations, user accounts, address books, and other types of resources like files and devices on a network. If you have a number of Oracle databases in your organization, you can even become adventurous and use LDAP directory naming to resolve SQL*Net service names for Oracle databases which allows storing net service names in a centralized LDAP-compliant directory server in place of a client-side tnsnames.ora file.

OpenLDAP Software is a free, open source implementation of the LDAP protocol developed by the OpenLDAP Project. Directory service is controlled by a stand-alone LDAP daemon (slapd) and the stand-alone LDAP update replication daemon (slurpd) when replication is configured. Propagating changes using replication falls outside the scope of this document and therefore will not include configuring the slurpd daemon.

This guide presents the steps required to install and configure OpenLDAP Software on the CentOS 5 platform. This tutorial will also work for Red Hat Enterprise Linux 5 and Oracle Linux 5.

Install OpenLDAP Server

The installation of OpenLDAP Software performed in this guide will be done using the yum package manager. Yum is available on any of the Red Hat Enterprise Linux distributions including its clones like CentOS. Building OpenLDAP Software from source will not be discussed here. If you need to compile from source, please see Building and Installing OpenLDAP Software from the OpenLDAP Software website.

Install OpenLDAP Software using Yum

Log in to the server as root and install the basic OpenLDAP Software package and related management tools needed for LDAP administration from the yum repository. This will update any previously installed release of the OpenLDAP Software packages.

# yum -y install openldap openldap-servers openldap-clients nss_ldap

The following table summarizes the OpenLDAP Software packages installed in the above step.

openldap	Contains all configuration files, libraries, and documentation for OpenLDAP.
openldap-servers	Contains files needed to host an LDAP server (slapd and slurpd).
openldap-clients	Contains the client programs needed for accessing and modifying LDAP directories.
nss_ldap	Contains access client software for using LDAP as a method of user authentication for Linux.

OpenLDAP Configuration Files

After installing OpenLDAP Software, the next step is to modify the necessary configuration files to customize the LDAP server. As with any new application, it is highly recommended to understand the purpose of each configuration file and to create a backup of the original version of those configuration files before modifying them.

The following table describes the client and server configuration files used to customize OpenLDAP Software.

Configuration File	Description	Used in this Guide?
/etc/openldap/slapd.conf	Main server configuration file that contains information needed by the slapd LDAP server. The slapd.conf file will be edited in this guide to set all server-wide directives, directory configuration information specific to your domain and server, database type and location, and ACL definitions that define authorization to your directory.
/etc/openldap/DB_CONFIG.example	Example DB_CONFIG file for use with slapd(8) BDB/HDB databases.
/var/lib/ldap/*	Contains all files that make up the LDAP directory database. None of the files contained in this directory should be manually edited. The LDAP directory database type and location will be defined in the /etc/openldap/slapd.conf file later in this guide.
/etc/openldap/schema/*	Directory that contains a set of default schema specifications which describe the different object classes that are available by default with the OpenLDAP Software. Each set is defined in a file (i.e. core.schema) suitable for inclusion using the include directive in the global definitions portion of the slapd.conf(5) file. It is helpful to browse the contents of these files to determine the required and available attributes for a particular object class.
/etc/ldap.conf	Client configuration file that is used for authentication and is required to be configured when LDAP is added as a lookup in /etc/nsswitch.conf. This guide does not include instructions for modifying this client configuration file. This is not the same as /etc/openldap/ldap.conf file which is discussed next.
/etc/openldap/ldap.conf	Used to set system-wide defaults to be applied when running LDAP client tools like ldapsearch and ldapadd.
/etc/nsswitch.conf	This configuration file controls the Name Service Switch (NSS) facility which provides information to the client to determine the sources from which to obtain name-service information in a range of categories, and in what order. Although not used in this guide, this file can be used by the client to tell the name service subsystem to use LDAP to obtain information. This is necessary when configuring LDAP authentication in the UNIX/Linux environment.
/etc/rc.d/init.d/ldap	Shell script used to start and stop the LDAP server (slapd and slurpd). Prior to starting the LDAP server, the script performs a syntax check of the slapd.conf configuration file.
/usr/sbin/slap*	The /usr/sbin directory contains non-vital system utilities that are used after the system starts. In OpenLDAP, any file that begins with "slap" is a server utility.
/usr/bin/ldap*	/usr/bin is a standard directory on UNIX/Linux operating systems that contains most of the executable files that are not needed for booting or repairing the operating system. In OpenLDAP, any file that begins with "ldap" is a client utility. This includes ldapsearch for searching a directory, ldapadd for adding records from the client, ldapmodify for modifying existing directory records, and ldapdelete for removing records from the directory.

Backup the original version of any OpenLDAP Software configuration file before making modifications.

# cp /etc/openldap/slapd.conf /etc/openldap/slapd.conf.orig # cp /etc/openldap/ldap.conf /etc/openldap/ldap.conf.orig

slapd Configuration – (slapd.conf)

This section provides instructions on how to configure the LDAP server by modifying the /etc/openldap/slapd.conf file. As previously noted, this file is the main configuration file needed by the LDAP server (slapd) and contains server-wide directives, directory configuration information specific to your domain and server, database type and location, and ACL definitions that define authorization to your directory.

Include

The include directive is used to import other files. The default configuration file includes the main schema files which are used to tell the LDAP server the different object classes and attributes that are available.

There is no need to modify the included default schema files for this guide.

include /etc/openldap/schema/core.schema include /etc/openldap/schema/cosine.schema include /etc/openldap/schema/inetorgperson.schema include /etc/openldap/schema/nis.schema

LDAP v2 Client Access

The LDAP server can be configured to allow LDAP v2 clients by specifying "allow bind_v2" in the configuration file. Without explicitly specifying this option, the LDAP server will reject any v2 clients.

If you don't know ahead of time the version of your LDAP clients, it is safe to leave it un-commented which enables v2 client access.

allow bind_v2

pidfile / argsfile

The pidfile option specifies the absolute name of a file what will hold the slapd server's process ID while the argsfile option specifies the absolute name of a file that will hold the slapd server's command line options.

Both settings can be left at their default values.

pidfile /var/run/openldap/slapd.pid argsfile /var/run/openldap/slapd.args

Logging

Although not included by default in the configuration file, logging can be setup using the loglevel directive. This directive specifies the level at which debugging statements and operation statistics should be logged. Log levels may be specified as integers or by keyword; however, most people stick to using loglevel integers. Multiple log levels may be used and the levels are additive. For example, when setting multiple log levels, add up the integers for the levels you want to use and use that integer when specifying the loglevel directive. I typically specify logging for trace function calls, connection management, ACL processing, and stats log connections/operations/results so the log level is determined by adding the integers 1, 8, 128, and 256 together for a loglevel of 393. The standard (default) log level is 256. The possible log level values are described in the following table.

loglevel	Keyword	Logging Description
-1	Any	enable all debugging
0		no debugging
1	(0x1 trace)	trace function calls
2	(0x2 packets)	debug packet handling
4	(0x4 args)	heavy trace debugging (function args)
8	(0x8 conns)	connection management
16	(0x10 BER)	print out packets sent and received
32	(0x20 filter)	search filter processing
64	(0x40 config)	configuration file processing
128	(0x80 ACL)	access control list processing
256	(0x100 stats)	stats log connections/operations/results
512	(0x200 stats2)	stats log entries sent
1024	(0x400 shell)	print communication with shell backends
2048	(0x800 parse)	print entry parsing debugging
4096	(0x1000 cache)	caching (unused)
8192	(0x2000 index)	data indexing (unused)
16384	(0x4000 sync)	LDAPSync replication
32768	(0x8000 none)	only messages that get logged whatever log level is set

Another setting related to logging that is not included by default is the logfile directive. By default, log entries for LDAP are sent to syslog. While this has its benefits, I find it more convenient to direct log entries to a file using the logfile directive. Below are the logging options I used for the LDAP server configuration described in this guide.

# Logging # - trace function calls (1) # - connection management (8) # - ACL processing (128) # - stats log connections/operations/results (256) # (1 + 8 + 128 + 256)=393 loglevel 393 logfile /var/log/ldap.log

When specifying the logfile directive, you need to make certain that the log file exists prior to starting the LDAP server.

# touch /var/log/ldap.log

Password-Hash

Another global directive that should be set and is not included by default is password-hash. This option configures one or more hashes to be used in generation of user passwords stored in the userPassword attribute during processing of LDAP Password Modify Extended Operations (RFC 3062). This allows the directory server to handle hashing instead of the client. The password hash to use for new passwords must be one of SSHA, SHA, SMD5, MD5, CRYPT, and CLEARTEXT. When the password-hash directive is not specified, the default is SSHA.

Including this option in the configuration file conforms to best practices and will be specified in this guide using the SSHA hashing algorithm.

# Set password hashing algorithm to use by default password-hash {SSHA}

Dynamic Backend Modules

Use the moduleload option to specify the name of a dynamically loadable module to load. The filename may be an absolute path name or a simple filename. Non-absolute names are searched for in the directories specified by the modulepath option. This option and the modulepath option are only usable if slapd was compiled with --enable-modules.

A default OpenLDAP Software installation includes a number of module load statements; all of which are commented out. Loading modules falls outside the scope of this guide and will not be covered.

# Load dynamic backend modules: # modulepath /usr/lib64/openldap # Modules available in openldap-servers-overlays RPM package # Module syncprov.la is now statically linked with slapd and there # is no need to load it here # moduleload accesslog.la # moduleload auditlog.la # moduleload denyop.la # moduleload dyngroup.la # moduleload dynlist.la # moduleload lastmod.la # moduleload pcache.la # moduleload ppolicy.la # moduleload refint.la # moduleload retcode.la # moduleload rwm.la # moduleload smbk5pwd.la # moduleload translucent.la # moduleload unique.la # moduleload valsort.la # modules available in openldap-servers-sql RPM package: # moduleload back_sql.la

TLS - (Connection Encryption)

By default, LDAP network connections are not encrypted. All network transmission is performed in plain text. Enabling Transport Layer Security (TLS) provides added security through its framework by requiring a valid X.509 certificate on the server. Client certificates are optional.

Although highly recommended with a production directory server, building slapd with support for TLS is beyond the scope of this guide and will not be covered.

# The next three lines allow use of TLS for encrypting connections using a # dummy test certificate which you can generate by changing to # /etc/pki/tls/certs, running "make slapd.pem", and fixing permissions on # slapd.pem so that the ldap user or group can read it. Your client software # may balk at self-signed certificates, however. # TLSCACertificateFile /etc/pki/tls/certs/ca-bundle.crt # TLSCertificateFile /etc/pki/tls/certs/slapd.pem # TLSCertificateKeyFile /etc/pki/tls/certs/slapd.pem

Global ACLs

The next section allows you to specify any global ACLs. The default configuration file includes several ACL statements that are commented out.

# Sample access control policy: # Root DSE: allow anyone to read it # Subschema (sub)entry DSE: allow anyone to read it # Other DSEs: # Allow self write access # Allow authenticated users read access # Allow anonymous users to authenticate # Directives needed to implement policy: # access to dn.base="" by * read # access to dn.base="cn=Subschema" by * read # access to * # by self write # by users read # by anonymous auth # # if no access controls are present, the default policy # allows anyone and everyone to read anything but restricts # updates to rootdn. (e.g., "access to * by * read") # # rootdn can always read and write EVERYTHING!

Adding the following ACLs are common when the directory is being used for authentication.

Global Read ACL

This permission grants anonymous users to log in, and all authenticated users to read any entries in the directory. For example, users may lookup other users' profiles.

# Global Read ACL access to * by self write by * read

Change User Password ACL

This permission lets users update their own passwords (i.e., using ldappasswd).

# Change User Password ACL access to attrs=userPassword by self write by anonymous auth by * none

LDAP Domain and Administrator

Determining an LDAP domain for an enterprise takes careful consideration. This is where questions regarding how you intend to use the directory and how the data will be organized to enhance efficiency needs to be answered. The domain used in this guide to serve LDAP will simply be the name of my website — idevelopment.info. The LDAP domain gets specified using the suffix directive. Also discussed in this section is how to configure the administrator of the directory (rootdn).

Suffix

The suffix option is your base Distinguished Name (DN) and names the domain for which the LDAP server provides information. You can set this to anything you like, but remember that it will be included in the DN for each and every record in your directory.

Edit the line that specifies suffix "dc=my-domain,dc=com", and change it accordingly. In this guide, I am using the domain suffix "dc=idevelopment,dc=info". Note that it is a convention not to have any white space characters in this string.

suffix "dc=idevelopment,dc=info"

Rootdn

Below suffix is the rootdn. The rootdn entry is the full Distinguished Name (DN) for the user who is unrestricted by access controls or administrative limit parameters set for operations on the LDAP directory. The rootdn user can be thought of as the root user for the LDAP directory. The default is Manager, but you can change that to root or any other value. Note that this entry is not the same as the root user account on your Linux/UNIX operating system. If you choose to add the root user account in LDAP, it will be a different user than the rootdn.

For the domain used in this example, I specified rootdn as "cn=Manager,dc=idevelopment,dc=info".

rootdn "cn=Manager,dc=idevelopment,dc=info"

Rootpw

The rootpw option is the password for the rootdn that you specified in the previous step. Although you can include the password in clear text, it is not recommended for obvious security reasons. To encrypt the password, OpenLDAP Software comes with a tool called slappasswd which accepts clear text passwords and converts them. In addition, slappasswd can also be passed the hash method you want to use. The most basic hash method is crypt, but it is not very secure. There are two other methods available, and each has two variations. The first is the standard MD5 encryption. You can also use MD5 with a salt, which is designated as SMD5. The most secure method is SHA-1 encryption. If you want to include a salt, which is recommended, it is designated as SSHA. SSHA is the default hash method, so you shouldn't need to pass in this option.

Run /usr/sbin/slappasswd to generate an encrypted password for the Manager (or root) LDAP user. When prompted, type and then re-type the password. The program displays the resulting encrypted password version for you to copy into the configuration file.

# /usr/sbin/slappasswd New password: myRootDNPassword Re-enter new password: myRootDNPassword {SSHA}LqNwNyscXdzJWRiK4d7dlaqQ6wfk71wA

Copy the generated hash and then add it to the rootpw directive.

rootpw {SSHA}LqNwNyscXdzJWRiK4d7dlaqQ6wfk71wA

LDAP Directory Database

The information in an LDAP directory tree is stored in a directory database. There are two Berkley DB types that are available by default. BDB is the original Berkley DB, and HDB is the newer variation. Both are good for smaller networks, but HDB is a bit faster when you have a large number of users. If you will be using LDAP on a larger scale, consider using HDB for greater efficiency.

Use the database directive to select the LDAP directory database type and the directory directive to specify the location of the backend database. The example presented in this guide uses the bdb database located at /var/lib/ldap. In addition to BDB and HDB, the OpenLDAP Software data storage type can also be configured using Oracle, MySQL, PostgreSQL, and several other backend databases; however, those will not be discussed in this guide.

database bdb # The database directory MUST exist prior to running slapd AND # should only be accessible by the slapd and slap tools. # Mode 700 recommended. directory /var/lib/ldap

Using OpenLDAP Software with a BDB backend requires a DB_CONFIG database configuration file for optimum performance. An example DB_CONFIG file exists at /etc/openldap/DB_CONFIG.example. To create an LDAP database configuration file for BDB, simply copy the example configuration file to the LDAP directory database location as follows:

# cp /etc/openldap/DB_CONFIG.example /var/lib/ldap/DB_CONFIG

The final step is to verify the file system directory for the LDAP directory database is owned by the correct user and group. As with all externally-accessible daemons running on your system, LDAP should never be run as the root user for security reasons. Because of this, OpenLDAP Software automatically creates a user and group on the local system; both named ldap. The owner and group for the database directory should be ldap:

# ls -ld /var/lib/ldap drwx------ 2 ldap ldap 4096 Aug 7 15:07 /var/lib/ldap

Miscellaneous slapd Settings

The rest of the slapd.conf file can be left at defaults. The only other part of the configuration file to point out is the index section at the bottom. Here you can specify indices for the directory database just like you would create indices in any relational database. This provides better lookup efficiency that can speed up a client's ability to access the most commonly used attributes in the directory. It's common to index entries like uid, gid, and loginShell to provide faster access to those attributes. You don't need nor would you want to index fields that are rarely accessed since it requires more memory to do so.

Modified slapd Configuration File

For clarity, I am displaying the entire contents of the /etc/openldap/slapd.conf file used in this guide with non-default (modified) entries highlighted in blue.

# # See slapd.conf(5) for details on configuration options. # This file should NOT be world readable. # include /etc/openldap/schema/core.schema include /etc/openldap/schema/cosine.schema include /etc/openldap/schema/inetorgperson.schema include /etc/openldap/schema/nis.schema # Allow LDAPv2 client connections. This is NOT the default. allow bind_v2 # Do not enable referrals until AFTER you have a working directory # service AND an understanding of referrals. #referral ldap://root.openldap.org pidfile /var/run/openldap/slapd.pid argsfile /var/run/openldap/slapd.args # Logging # - trace function calls (1) # - connection management (8) # - ACL processing (128) # - stats log connections/operations/results (256) # (1 + 8 + 128 + 256)=393 loglevel 393 logfile /var/log/ldap.log # Set password hashing algorithm to use by default password-hash {SSHA} # Load dynamic backend modules: # modulepath /usr/lib64/openldap # Modules available in openldap-servers-overlays RPM package # Module syncprov.la is now statically linked with slapd and there # is no need to load it here # moduleload accesslog.la # moduleload auditlog.la # moduleload denyop.la # moduleload dyngroup.la # moduleload dynlist.la # moduleload lastmod.la # moduleload pcache.la # moduleload ppolicy.la # moduleload refint.la # moduleload retcode.la # moduleload rwm.la # moduleload smbk5pwd.la # moduleload translucent.la # moduleload unique.la # moduleload valsort.la # modules available in openldap-servers-sql RPM package: # moduleload back_sql.la # The next three lines allow use of TLS for encrypting connections using a # dummy test certificate which you can generate by changing to # /etc/pki/tls/certs, running "make slapd.pem", and fixing permissions on # slapd.pem so that the ldap user or group can read it. Your client software # may balk at self-signed certificates, however. # TLSCACertificateFile /etc/pki/tls/certs/ca-bundle.crt # TLSCertificateFile /etc/pki/tls/certs/slapd.pem # TLSCertificateKeyFile /etc/pki/tls/certs/slapd.pem # Sample security restrictions # Require integrity protection (prevent hijacking) # Require 112-bit (3DES or better) encryption for updates # Require 63-bit encryption for simple bind # security ssf=1 update_ssf=112 simple_bind=64 # Sample access control policy: # Root DSE: allow anyone to read it # Subschema (sub)entry DSE: allow anyone to read it # Other DSEs: # Allow self write access # Allow authenticated users read access # Allow anonymous users to authenticate # Directives needed to implement policy: # access to dn.base="" by * read # access to dn.base="cn=Subschema" by * read # access to * # by self write # by users read # by anonymous auth # # if no access controls are present, the default policy # allows anyone and everyone to read anything but restricts # updates to rootdn. (e.g., "access to * by * read") # # rootdn can always read and write EVERYTHING! # Global Read ACL access to * by self write by * read # Change User Password ACL access to attrs=userPassword by self write by anonymous auth by * none ####################################################################### # ldbm and/or bdb database definitions ####################################################################### database bdb suffix "dc=idevelopment,dc=info" rootdn "cn=Manager,dc=idevelopment,dc=info" # Cleartext passwords, especially for the rootdn, should # be avoided. See slappasswd(8) and slapd.conf(5) for details. # Use of strong authentication encouraged. # rootpw secret # rootpw {crypt}ijFYNcSNctBYg rootpw {SSHA}LqNwNyscXdzJWRiK4d7dlaqQ6wfk71wA # The database directory MUST exist prior to running slapd AND # should only be accessible by the slapd and slap tools. # Mode 700 recommended. directory /var/lib/ldap # Indices to maintain for this database index objectClass eq,pres index ou,cn,mail,surname,givenname eq,pres,sub index uidNumber,gidNumber,loginShell eq,pres index uid,memberUid eq,pres,sub index nisMapName,nisMapEntry eq,pres,sub # Replicas of this database #replogfile /var/lib/ldap/openldap-master-replog #replica host=ldap-1.example.com:389 starttls=critical # bindmethod=sasl saslmech=GSSAPI # authcId=host/ldap-master.example.com@EXAMPLE.COM

Test the Configuration

After saving the LDAP configuration file, test the slapd configuration using slaptest.

# slaptest -u config file testing succeeded

This will tell you if you have issues with your config file. Initially it may say that it cannot find the file id2entry.bdb along with other possible errors. This specific warning is OK. The id2entry.bdb file will be created the first time the LDAP server is run. The results should indicate that a test without checking for those files would have passed.

Start / Stop LDAP Server

This section contains instructions for starting and stopping the LDAP server.

Start LDAP Server (slapd)

The LDAP server is now ready to be started for the first time.

# service ldap start Starting slapd: [ OK ]

Modify the LDAP server to start when the machine boots.

# chkconfig --levels 235 ldap on

Running the LDAP server the first time may give you the following lines:

Performing database recovery to activate new settings. bdb_db_open: Recovery skipped in read-only mode. Run manual recovery if errors are encountered.

This message should disappear the next time slapd is restarted.

Stop LDAP Server (slapd)

The LDAP server can be stopped using the following:

# service ldap stop Stopping slapd: [ OK ]

Configure System-Wide Defaults

The /etc/openldap/ldap.conf configuration file is used to set system-wide defaults to be applied when running LDAP clients. It is common to set these system-wide defaults on both client and server hosts configured to use LDAP.

Modify the LDAP client configuration file (/etc/openldap/ldap.conf) and change the URI and BASE options for your LDAP server.

# # LDAP Defaults # # See ldap.conf(5) for details # This file should be world readable but not world writable. #BASE dc=example, dc=com #URI ldap://ldap.example.com ldap://ldap-master.example.com:666 #SIZELIMIT 12 #TIMELIMIT 15 #DEREF never URI ldap://ldapsrv.idevelopment.info/ BASE dc=idevelopment,dc=info TLS_CACERTDIR /etc/openldap/cacerts

Further Reading

At this point the LDAP server is running and the backend database was created; however, the directory doesn't contain any data. The directory starts out completely empty, without even a root structure present. Initializing the directory with a root record and other supporting directory sub-structures (i.e., sub-directories) is required before you can add any user data.

Initialize the new LDAP directory using the following document:

• Initialize a New LDAP Directory

About the Author

Jeffrey Hunter is an Oracle Certified Professional, Java Development Certified Professional, Author, and an Oracle ACE. Jeff currently works as a Senior Database Administrator for The DBA Zone, Inc. located in Pittsburgh, Pennsylvania. His work includes advanced performance tuning, Java and PL/SQL programming, developing high availability solutions, capacity planning, database security, and physical / logical database design in a UNIX, Linux, and Windows server environment. Jeff's other interests include mathematical encryption theory, programming language processors (compilers and interpreters) in Java and C, LDAP, writing web-based database administration tools, and of course Linux. He has been a Sr. Database Administrator and Software Engineer for over 18 years and maintains his own website site at: http://www.iDevelopment.info. Jeff graduated from Stanislaus State University in Turlock, California, with a Bachelor's degree in Computer Science.