Linux LDAP Configuration


User authentication is the basis for modern, secure computing. Access to resources and services on a host or network depends on the authenticity of a user. The number of available services is constantly increasing as technology advances and traditional services are being connected to computer networks. Resources should be shared based on agreed policies with minimal overhead but in order to guarantee uninterrupted access a set of restrictions might be needed. Managing resources and services efficiently in an always evolving environment calls for centralized and integrated solutions that enable cost effective administration while still allowing for expansion in the future.

Traditional authentication systems on Linux environments have been largely based on either NIS or flat file databases. While these solutions have worked rather well to some degree, their administration and integration to wide range of applications in use today has been suboptimal. LDAP enables a centrally managed source for authentication and access policies and makes integration with applications easier to implement and maintain. This document provides a comprehensive configuration guide to migrate a Linux intranet to a fully LDAP enabled environment where also the applications are seamlessly integrated with LDAP.

LDAP Setup Overview

Reader is expected to be familiar with basic terms and concepts of networked Linux/Unix environments and LDAP terminology. Our Linux Intranet Configuration guide describes a commonly used Linux intranet configuration and it can be thought as a starting point for this guide. Wikipedia article on LDAP provides a good introduction to basics of the protocol and directories and it also describes other essential concepts such as operations, schemas, and naming. Fully understanding terms like bind domain and search base will be very valuable when debugging possible configuration issues.

OpenLDAP is one of the most widely deployed LDAP implementations and it is available for every major computing platform. Thus, components from OpenLDAP will be used to create the LDAP enabled environment. Some parts of the environment are actually implementation independent so those configurations can be used with any LDAP implementation. All configuration files and paths are valid on Red Hat compatible distributions, such as Red Hat Enterprise Linux, CentOS, and Fedora. However, just by using corresponding paths on other distributions the configuration files should be valid also with them. Configuration files that are not mentioned in this guide are suitable in their default form on Red Hat compatible distributions.

Configuration will begin by migrating existing authentication information from a legacy system for the LDAP enabled environment. Server setup using the migrated data will be carried out next. Client configurations can be made then, gradually adding LDAP enabled components in the network. Finally, also server replication for redundancy and integrated application examples will be configured. All the configurations are made in a non-disruptive manner, allowing the legacy system to be used until the LDAP setup is production ready. Pointers to additional documents for further customization are also provided.

It must be emphasized that setting up an LDAP environment is different compared to a usual service configuration on a Linux/Unix network. Configuring the LDAP server or an application are just enabling acts but the use of LDAP in real life deeply involves specifying local needs, policies, processes, and other such aspects that no general guide can definitely provide for any particular case. However, having an initial LDAP environment in place allows for basic use and provides a path for future enhancements.

Data Migration

Existing users, groups, hosts, and other related information in a system can be easily migrated for use by the LDAP server. Migration is done by using a set of migration scripts that are part of the original OpenLDAP package. The migration scripts will generate standard LDIF files both from flat files or from a NIS server. The LDIF standard defines a format for representing and modifying LDAP directory content and the format can be used with most LDAP server implementations. As LDIF files are regular text files they can be also viewed or edited with any text editor.

Below are all the needed commands to migrate user, group, and host data from traditional flat files for an intranet using the domain name intra and mail domain dom.ain. The below mentioned directories (the other is for older distributions and the other is for newer distributions) also contain several other migration scripts that could be used to migrate additional data from flat files or to migrate from a NIS server.

When running the migration commands or using any of the provided configuration files, obviously you must use domain names and IP addresses to match your local environment. The commands should be run as root so that the file /etc/shadow can be read during the migration.

export LDAP_BASEDN="dc=intra"
test -d /usr/share/openldap/migration && \
  cd /usr/share/openldap/migration || \
  cd /usr/share/migrationtools
./ > /tmp/base.ldif
./ /etc/passwd > /tmp/passwd.ldif
./ /etc/group > /tmp/group.ldif
./ /etc/hosts > /tmp/hosts.ldif

The generated LDIF files should be checked so that they look sane and contain expected information. They will be later imported into the LDAP server and the data will be used for testing the setup so integrity of the migrated data is essential.

It should be mentioned that few of the additional migration scripts may fail because some newer distributions include multiple definitions for certain rarely used protocols in their /etc/services file. These definitions cannot be represented in the standard LDAP schema for services. The workaround for these kinds of errors is to temporarily remove the problematic definitions from the file /etc/services while running the affected migration scripts.

Related RPMs: openldap-servers (older distributions) or migrationtools (newer distributions).

Server Configuration

The LDAP server needs to communicate in a secure manner with its clients when transferring sensitive information such as user names or password hashes. To secure all the traffic between the server and a client TLS encryption is used. To achieve this, a certificate needs to be created for the server. During the testing phase and in some cases also in production a self-signed certificate is suitable as such a certificate is enough for the purposes of communication encryption. A properly signed certificate would be needed when peer verification is a requirement. There is external comprehensive documentation available that explains certificate management in more detail as well as a very compact quick guide.

Many distributions provide a Makefile to ease the creation of a self-signed certificate, otherwise command line utilities such as openssl(1) can be used. The following commands utilize the Makefile provided by your distribution. You should back up a possibly existing certificate before creating a new certificate and then provide some meaningful answers to the questions asked. The most important question is about Common Name for which you must provide the server IP address or its fully qualified domain name. This is needed in order to properly establish secure TLS connections between the server and clients.

cd /etc/pki/tls/certs
make slapd.pem

After the certificate has been successfully created with the correct Common Name its owner and permissions must be adjusted so that only the system administrator and the server process are able to access it:

chown root:ldap slapd.pem
chmod 0640 slapd.pem

Actual LDAP server setup begins by creating an internal database directory for the server to store its data and adjusting two configuration files. First a database directory for the domain intra is created and a database configuration file is placed there. Although the database configuration file is not mandatory it provides good default values for a small or medium-sized intranet and of course it can be tuned later on, if needed. To initialize the needed directory and server's internal database configuration, download this database configuration and execute the following commands:

mkdir -p /var/lib/ldap/intra/db
mkdir -p /var/lib/ldap/intra/logs
mv DB_CONFIG /var/lib/ldap/intra/DB_CONFIG
chown -R ldap:ldap /var/lib/ldap/intra
chmod -R 0700 /var/lib/ldap/intra
chmod 0600 /var/lib/ldap/intra/DB_CONFIG

That is all what is needed for the server internal database setup. Basic configuration of the actual server parameters is also a straightforward task. After placing this server configuration file as /etc/openldap/slapd.conf, removing unneeded additional default configuration files, and adjusting the main configuration file owner and permissions the server is ready for testing. At this stage it is best just to try to start up the server and inspect its debugging messages:

chown root:ldap /etc/openldap/slapd.conf
chmod 0640 /etc/openldap/slapd.conf
/bin/rm -rf /etc/openldap/slapd.d
/usr/sbin/slapd -h "ldap:///" -u ldap -d 255

You should see no errors in the output. If there are any errors you should double check file permissions and owners and also make sure that you have created the needed directory structure for the internal database. The path to the previously created certificate should also be correctly defined in the configuration file. Possible error messages usually give hints where a problem might be. However, if the instructions above have been carefully followed no errors will be printed meaning that the server configuration is correct.

Now that the server is correctly configured, the migrated data can be imported. Stop the server by pressing Ctrl-C in order to allow direct database access by the slapadd(8) command. Then execute the following commands to import the migrated data and clean up the LDIF files:

/usr/sbin/slapadd -v -l /tmp/base.ldif
/usr/sbin/slapadd -v -l /tmp/passwd.ldif
/usr/sbin/slapadd -v -l /tmp/group.ldif
/usr/sbin/slapadd -v -l /tmp/hosts.ldif
rm -f /tmp/base.ldif /tmp/passwd.ldif
rm -f /tmp/group.ldif /tmp/hosts.ldif

Again, no errors should be printed when importing the data, only messages indicating that data has been added to the database. The server configuration is in essence now done but one final tweak missing. Since the data in the LDAP server database is now the same as in the flat files it makes testing a bit difficult as there are no, e.g., LDAP only user account available for testing. So, for testing purposes, it is recommended to add a testuser entry into the server database. The entry contains information for a user account testuser in the domain intra with the password usertest. The entry can be added just like the migrated data was added earlier:

/usr/sbin/slapadd -v -l testuser.ldif

You can use the command slappasswd(8) to create a new password hash and replace the example password in the file before adding the account. When the server configuration seems to be complete and data for testing has been imported into the server you can finally configure the server to be started during system boot up and then start the server. File owners need to be also adjusted again as when directly modifying the database files their ownership has changed. Please note that the service name has changed in newest distributions and is called slapd instead of ldap.

chown -R ldap:ldap /var/lib/ldap/intra
/sbin/chkconfig ldap on
/sbin/service ldap start

If there are any problems during the testing phase or at any later stage it is usually a good idea to start the server from command line with proper debugging level as shown a bit earlier. The server configuration will be tested in the next section.

Server configuration files: /var/lib/ldap/intra/DB_CONFIG, /etc/openldap/slapd.conf.

Required services to be started: ldap at the server. Related RPMs: openldap-servers.

Client Configuration

The client configuration instructions presented here are divided in two parts. First the command line client utilities from the OpenLDAP package are configured. Once the client utilities are working properly against the server it is time to configure system level user information and authentication mechanisms to use LDAP. Note that client configuration can be done initially either on the server host or on a client host. After verifying that all the configurations work correctly they should enabled on all hosts in the environment.

The OpenLDAP command line client utilities and client applications using the OpenLDAP libraries use a pleasantly simple configuration file. To test OpenLDAP command line client utilities, place this OpenLDAP client configuration file as /etc/openldap/ldap.conf. Then, testing both the server and the simplest command line client utility is done simple as shown below. See the ldapwhoami(1) manual page for explanation about the given parameters.

ldapwhoami -x -ZZ

The command should print out anonymous to indicate that the binding to the server was anonymous, i.e., no user credentials were used. If an error occurred then either the command output or the server debug log output probably contain information about the cause of the issue. Before proceeding any further make sure that this simplest command works, otherwise errors are likely to appear in other cases, too.

The next test is a bit more sophisticated. It uses the command ldapsearch(1), one of the most useful testing commands, to bind as user testuser and search for user id nobody. You may also experiment with other users, groups, or hosts that have been added to the server database by adjusting the search filter (the last parameter). The password prompted for is always for the user used to bind to the server. It is worthwhile to check the ldapsearch(1) manual page for additional information about the command and its usage. It is also recommended that you experiment with utilities like ldapadd(1) and ldapdelete(1) that will surely be useful later on.

ldapsearch -x -ZZ -D "uid=testuser,ou=People,dc=intra" \
  -W "(uid=nobody)"

It should be noted that the system wide configuration for the OpenLDAP command line clients is /etc/openldap/ldap.conf but users may also use command line parameters or create an optional personal configuration file to override the system wide default file or to use personal certificates. See the ldap.conf(5) manual page for more information about these configuration files.

Now that the LDAP server and OpenLDAP clients have been tested and confirmed to work it is time to wire up system level user information and authentication mechanisms to use LDAP. Information to map user and group ids to user and group names is requested when, e.g., the ls(1) command lists files and their owners. User authentication is carried out when a user is logging in to the system, for example. User information service is provided by the NSS functionality in the C standard library and the user authentication infrastructure used in Linux distributions is PAM. Once PAM is configured to use LDAP as one of its authentication sources, all applications with their PAM support enabled, such as sshd, are then automatically using LDAP, too.

Needless to say, when wiring up system level authentication to use LDAP it is crucial that the configuration is correct and all components are working as expected. After making sure one more time that the LDAP server and OpenLDAP clients are working, place this NSS/PAM LDAP configuration file as /etc/ldap.conf. Both NSS and PAM will use this configuration file. The provided file itself is long but in most setups all the commented out configuration directives can be safely ignored. After making sure the file is adjusted for your local environment NSS can be wired up by copying this NSS configuration file as /etc/nsswitch.conf. Now NSS configuration can be easily tested:

getent passwd | grep ^nobody:

If everything has been set up correctly, the command will return two identical entries, one from the flat file and the other from the LDAP server. If the server is not running or the configuration is incorrect, then only the flat file entry is returned as the LDAP server is not providing the additional entry. In case of errors, double check the configuration file /etc/ldap.conf and inspect the server debugging output, if necessary.

Finally, after all the previous steps have succeeded, PAM can be configured to enable system level authentication to use LDAP. You should backup the existing PAM configuration file /etc/pam.d/system-auth and only then use this PAM configuration file to enable LDAP based authentication. If you have made any earlier local customizations to your PAM configuration you might want to manually merge the LDAP related directives to your local PAM configuration. To test the configuration by utilizing the previously created testuser account you can log in to the system or use the su(1) command:

su - testuser

If the previous command succeeds then the basic LDAP configuration is complete! You may now experiment with additional command line utilities, user account creation and modifications, and maybe also take one more look into all configuration files to fully understand how all parts were made to work in concert. Should you also want to enable LDAP logins via different graphical display managers (like GDM), then corresponding changes to /etc/pam.d/password-auth are needed as were done for /etc/pam.d/system-auth. This is also the time to decide whether you want to leave LDAP based authentication enabled now or do you want to perhaps disable it by reverting the previous changes until you have migrated more data or experimented with server replication and some additional configurations. You may also want to read some detailed LDAP documentation to really deepen your knowledge about LDAP.

Common configuration files: /etc/openldap/ldap.conf, /etc/ldap.conf, /etc/nsswitch.conf.

Related RPMs: nss_ldap, openldap-clients.

Server Replication

LDAP server replication is recommended even in small scale networks to prevent service breaks when a single server fails. Replication with OpenLDAP using a master and a slave server is achieved with few simple steps. First, a replicator user account is added to the LDAP server with the command ldapadd(1). Then, an LDIF database dump with the slapcat(8) utility is created:

ldapadd -x -ZZ -D "cn=Manager,dc=intra" \
  -W -f ./Replicator.ldif
/sbin/service ldap stop
/usr/sbin/slapcat -v -l ./master.ldif

At this stage this server can be made the master server simply by uncommenting the related master side directives at the end of the server configuration file that has been used all the time. Also, a directory needs to be created for some versions of the replication daemon, slurpd:

mkdir -p /var/openldap-slurp/replica
chown -R ldap:ldap /var/openldap-slurp
chmod -R 0700 /var/openldap-slurp

Next time the server is started with its init script, in addition to slapd, also the replication daemon is automatically started if the master side replication directives are defined. During the testing phase slurpd(8) can of course be started also from command line. When both the server and the replication daemon are running it is time to set up the slave LDAP server. On the slave server, use the same procedure to set up the slave server as was described earlier but instead of importing any migrated data you must add the master server dump to the slave server:

/usr/sbin/slapadd -v -l ./master.ldif

Finally, on the slave server again, uncomment the two separate instances of slave server related configuration that are clearly marked in the server configuration file. When done, just start the slave server and LDAP server replication is enabled! To test that the slave server is properly running use, e.g., ldapsearch(1) with the command line option -H using a URI pointing to the slave server. To test the actual replication just modify the contents of the master server with, e.g., ldapadd(1) or ldapdelete(1), and then verify that the change has been propagated to the slave server, too. If that is not the case the servers and the replication daemon should be run in debug mode to see why the changes are not being propagated. As usual, common issues include file owners and permissions, file paths in the configuration files, and the validity of the certificates. When replication is working properly it is then easy to set up additional slave servers, if needed.

Clients can be configured to use both the servers by listing the slave server in the client configuration alongside with the master server. It depends on your local environment whether the clients should be using the master or the slave server as their first option but in many cases the slave should be preferred. Client testing can be carried out by first testing a client with both servers running and then temporarily shutting down one server at a time to see how clients will use the running server instead.

It could be mentioned that for testing purposes the slave LDAP server can also be set up to run on the same host where the master LDAP is running. In that case the slave must configured to use different database directory, different port, and different configuration file than the master server and it must be started from command line.

Required services to be started: ldap at the servers. Related RPMs: openldap-servers.

Additional Configurations

This section provides quick instructions on how to set up some rather useful related additional configurations for your environment. Although these steps are not absolutely required they are very beneficial in some cases and probably needed when going into production.

nscd is a daemon that caches the most common name service requests and greatly helps to reduce load on LDAP servers. Configuration is simple and can be done by copying this file as /etc/nscd.conf. nscd can be then started with the following commands. In general, there are only benefits in using it.

/sbin/chkconfig nscd on
/sbin/service nscd restart

Required services to be started: nscd at the server and the clients. Related RPMs: nscd.

Apache HTTP server and PHP configuration shows how easily applications not using PAM can still be made LDAP aware. For Apache, use this .htaccess file in an Apache served directory where AllowOverride directive includes AuthConfig. Then, users accessing the directory will be authenticated against the LDAP server. A PHP code to query an LDAP server is also self-explaining and trivial to use. As these two small examples demonstrate, connecting applications to LDAP is most of the time easy, making migration from legacy authentication systems yet more appealing.

Related RPMs: httpd, mod_authz_ldap, php, php-ldap for above mentioned application configurations.

SASL is an authentication and security framework for application layer protocols such as SMTP and IMAP. If SASL is needed in your environment the following tips might be helpful. To enable SASL for testing in the setup presented here, copy this file as /etc/saslauthd.conf on the server for the SASL authentication daemon and place this saslauthd system configuration file as /etc/sysconfig/saslauthd. Finally, this LDAP server SASL configuration file must be copied as /etc/sasl2/slapd.conf. Then, restart the LDAP server and also start the SASL authentication daemon:

/sbin/service ldap restart
/sbin/chkconfig saslauthd on
/sbin/service saslauthd start

An example user authentication proxy account entry includes the needed authzTo regular expression mapping which works with the directives included in the server configuration file used earlier. SASL configuration is notoriously difficult so if there is no need to enable it then surely the best thing to do is just ignore it. Otherwise, if it is really needed, now OpenLDAP clients should be able to connect the LDAP server using SASL:

ldapwhoami -ZZ -Y PLAIN -U testuser

And after adding the authentication proxy user SASL proxy authorization should also work:

ldapwhoami -ZZ -Y PLAIN -U AuthProxy -X u:testuser

As said, SASL might be a bit hard to configure correctly so you should be prepared to spend some time with SASL documentation if you intend to use it in a production environment.

Related RPMs: cyrus-sasl, cyrus-sasl-plain, cyrus-sasl-ldap.


This document provided a guide to set up, configure, and migrate to LDAP in a Linux intranet providing all essential configurations as well as examples of integrating applications and reliability enhancements. The presented configuration is suitable for small and medium-sized networks and many individual configuration files can also be utilized in larger networks or at a standalone host. There are numerous enhancements and customizations that could be made depending on local needs, policies, and processes on a particular environment. List of possible enhancements and improvements could include some of the following: Kerberos support, cached credentials during network outages, better laptop and mobility support, graphical tools for administration, performance improvements, policy and auditing management, and especially creation of policies and processes for local needs. These kinds of configurations are, however, outside of scope of this document.

All the configuration files mentioned are browsable and available for download.

Comments and feedback can be sent to oss(at) We would kindly like to note that we cannot promise a personal reply to all e-mails received, especially to those asking for help in some unrelated configuration problems. Inquiries about possible cooperation should be done via addresses listed at our Contact page.

This document was last updated on 2009-03-10.