To see part 1 of this tutorial, which covers the background and planning stages of an LDAP installation, click here.

Installation and Configuration of OpenLDAP

Now that you have a plan in place for how to design your directory, it’s time to start the installation and configuration.  If you’re using CentOS or any other Red Hat based distribution, you have the yum package manager to assist with the installation.  That’s how I’ll demonstrate the installation.  If you need to compile from source, you’ll have to find more details on OpenLDAP’s website or another tutorial.

Installation With Yum

There are a handful of packages you’ll need to install if you’re going to use LDAP for user administration.  Here’s the complete list:

openldap - All standard LDAP libraries for other applications to access LDAP directories
openldap-clients - The binaries for accessing an LDAP server from the client side
openldap-servers - The binaries for hosting an LDAP server
nss_ldap - The binaries and libraries for using LDAP as a means of user authentication for CentOS

The command to install them is very simple.  Just type, as root (or via sudo access):

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

The -y flag automatically selects “yes” for any confirmation dialogs, so omit that option if you want to review everything before making any system changes.  Once this command finishes, there are no more installation tasks.

The Configuration and LDAP Files

There are several important files that we’ll now be accessing, so lets take a moment to review them.

/etc/ldap.conf – This is the client configuration file.  We will not be editing this file directly at first.
/etc/nsswitch.conf – This is the configuration file that tells the system what sources to get information from. Again, we will not be editing this file manually at first.
/etc/openldap/slapd.conf – This is the main server configuration file.  It contains all the server-wide directives, directory configuration information, and ACL definitions that define authorization to the directories.
/etc/openldap/schema/* – These are the schema files that describe the different object classes that you have available to you. You can browse these to get an idea of what attributes are required and available.
/var/lib/ldap/* – These are the files that make up the actual LDAP directory database.
/etc/rc.d/init.d/ldap – This is the Sys-V Init script that controls the LDAP server.  It performs a syntax check of the slapd.conf file prior to starting the server.
/usr/sbin/slap* – These are the server binaries.  In OpenLDAP, any binary that begins with “slap” is a server control binary.  Examples are slapadd for adding records to the directory, slappasswd for creating password hashes, and slaptest for testing the slapd.conf syntax.  Look through the /usr/sbin directory for all the utilities to see what utilities are available.
/usr/bin/ldap* – These are the client binaries.  Any binary that begins with “ldap” is a client binary.  Some examples are ldapadd for adding records from the client side, ldapsearch for searching a directory, and ldapmodify for modifying existing directory records.

Initial Setup

Now that you’ve seen the files and gotten familiar with the location of everything, it’s time to start the actual configuration. The first step, as with any new application configuration, is to make a backup of original versions of the config files. Trust me, you’ll want to have those to fall back on should you ever need them.

cp /etc/ldap.conf /etc/ldap.conf.orig
cp /etc/nsswitch.conf /etc/nsswitch.conf.orig
cp -R /etc/openldap /etc/openldap.orig

You shouldn’t need to make a copy of the directory database files because none of them exist yet.  Once you’ve done that, you can move on to setting up the LDAP server configuration

vi /etc/openldap/slapd.conf

Lets take a moment to look at the different sections of this file before we start editing it. At the top, you’ll see several include statements, module load statements, and other settings that you may have seen in many different applications. This section is for global directives. The include statements that you see are used to import other files. You can import anything you wish, but the default statements are all for schema files. This is how OpenLDAP knows which schemas are available. Below that is the log level directive to set the amount of logging. There are also a bunch of commented module load statements. These are for loading additional modules that do not come with OpenLDAP by default. For our purposes, none of those are necessary, but there are many different reasons to include some module load statements.

The second section of the file is for global ACLs. There are some default ACL statements that are commented out. Later on, we’ll be writing out own ACLs, but these should give you a good idea of what LDAP ACLs look like.

The third section is for our database definition. You can technically have multiple directory databases in one LDAP server, but for our purposes we’ll only be using one. It is in this section that we’ll be defining the location of the database, the root password, the base DN, other directory-specific settings. You can also include ACLs in this spot if you want them to only apply to that specific directory.

Now that we know what the sections of the file contain, lets set some things up to get the directory up and running. By default, you do not need change the include statements. There is also an option to allow LDAP v2 clients. It is uncommented by default (despite what the documenting comment says), and you can leave it this way if you like. If you have no v2 clients that need to connect, you can comment it out and simplify things. If you don’t know what version your clients are, you can leave it uncommented and it won’t hurt anything. Likewise, you can leave the pidfile and argsfile settings alone. The defaults are fine.

The loglevel option is one you might want to look at. The “standard” logging level is 256. There are many different levels for logging though, many of which will be very useful during this initial setup. Here’s the full list:

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) entry parsing
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

The way you set the log level is to add up the numbers for the levels you want to use and put that number as your log level. So if you wanted to trace function calls, see connection management, and see ACL processing, you’d add the numbers 1, 8, and 128 together for a loglevel of 137. For now, standard logging is fine, but you’ll probably want to turn on ACL processing when we work on ACLs.

Another setting that is not included by default is logfile. LDAP logs are, by default, sent to syslog. While this is a good way to handle logging, it’s not really the best way. There are two different ways to specify a different file for logging LDAP information. The first is to use the logfile directive in the slapd file. To do this, simply add this line to your file:

logfile   /var/log/ldap.log

You also need to make sure that the file exists prior to starting LDAP. To do this:

touch /var/log/ldap.log

The second method is to change the syslog configuration file to force that to log LDAP data to a different file. Edit the file /etc/syslog.conf and add this to the end:

#LDAP logging
local4.*    /var/log/ldap.log

The advantage to this is that syslog still handles the logging, so it keeps all the logging information in one place. The advantage to the first is that it keeps all the LDAP configuration in one place. It’s up to you which one is better for your purposes.

One other global directive you’ll want to set is the password-hash option. This tells OpenLDAP what hash to use when a client sends an extended operation request to LDAP. Basically, this means that the client doesn’t want to handle hashing and wants instead to let the directory server take care of it. This is the standard method of handling password hashing and should be used whenever possible. I’ll go into the hashing methods in more detail below, but a good setting to use for this is SSHA, or a salted SHA-1.

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

We’re going to skip the global ACLs for now, so move on to the next section to set up the 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. So if you’ll be using LDAP on a larger scale, you probably want to use HDB for some greater efficiency. For this tutorial, I’ll use BDB, but simply substitute HDB for BDB if you choose the other. The rest of the configuration is the same.

Here are the options you’ll be setting, and I’ll explain them after the example.

database        bdb
suffix          "dc=example,dc=com"
rootdn          "cn=Manager,dc=example,dc=com"
rootpw          {SSHA}IaSNUAJICIThFy/opd6IhtMXgRXBhmjO

The suffix option is your base DN. You can set this to anything you like, but remember that it’ll be included in the DNs for every single record in your directory. The rootdn is the full DN of the root user. Again, you can name it whatever you want. The default is Manager, but you can change that to root if you like. Note that this is not the same as the root user on your Linux system. If you choose to put the root user account in LDAP, it will be a different user than the rootdn. The rootpw option is the password for the rootdn that you specify. You can include this password in clear text, but it is not recommended for obvious security reasons. To encrypt the password, OpenLDAP comes with a tool called slappasswd to accept passwords and convert them. Slappasswd can also be passed the hash method you want to use. The most basic is crypt, but this method also isn’t 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, so you shouldn’t need to pass any options. When you run the command, you’ll be prompted for the password twice, and it will then display the encrypted version for you to copy into your config.

slappasswd
New password:
Re-enter new password:
{SSHA}IaSNUAJICIThFy/opd6IhtMXgRXBhmjO

The rest of the file can be left at defaults unless you wish to locate your directory in a different place than /var/lib/ldap. The only other part of the configuration file I want to point out is the index section at the bottom. Here you can specify indices for your database just like you can set up indices for any relational database. This can speed up a client’s ability to access the most commonly-used attributes in your directory. It’s common to have things like uid, gid, and loginShell indexed to make them faster to access. You don’t need nor want to index fields that are rarely accessed though since it requires a lot of memory to do so. For more information in indices, visit this site:  http://www.zytrax.com/books/ldap/apa/indeces.html

You can now save your configuration file and exit your editor. As a general rule of thumb, you should always test your configuration file when you finish editing it before you start or restart LDAP. To do this, type:

slaptest

This will tell you if you have issues with your config file. Initially it will say that it can’t find id2entry.bdb among other errors, but this is fine. That file will be created the first time you run LDAP. It should say at the bottom of the results that a test without checking for those files would have passed.

We have just two more steps to complete before we start LDAP for the first time. First, there is a file in /etc/openldap called DB_CONFIG.example. We need to copy this file into the LDAP database directory to allow LDAP to self-configure some aspects of the directory. This file mostly contains information about how large the caches should be and other related size variables. You can generally use the defaults from the example unless you run into problems with LDAP throwing cache size or database size errors. Run this command to copy the file:

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

The final step is that we need to make sure that all the files in the /var/lib/ldap directory are owned by the correct user. As with all other externally-accessible daemons that run on  your system, LDAP should never be run as the root user for security reasons. Because of this, OpenLDAP automatically installs a user and group for you to use on your local system. Those are both, surprisingly, named ldap. So to set the proper ownership of the files we type this command:

chown -R ldap:ldap /var/lib/ldap

We’ll be reusing this command a couple more times as files get created while we build our database, so keep it handy.

Now we’re ready to start LDAP for the first time. There are two ways to do this on a Red Hat system. Both function the exact same way and, actually, both execute the exact same script. Those two options are:

1) /sbin/service ldap start
2) /etc/rc.d/init.d/ldap start

You can use whichever you prefer. You will probably see errors that indicate that the database files are not owned by ldap. If this is the case, it will have failed to start. Simply reuse the chown command I mentioned earlier and try starting it again. The problem should go away, and it should say that LDAP has started successfully. If it does start successfully, it’s on to client configuration next. If not, Google should turn up results for any error messages you see.

To see Part 3 of this tutorial, where I explain how to configure and test the client side of LDAP authentication, click here.