This page contains assorted information about OpenLDAP, including how to build OpenLDAP with support for NS-MTA-MD5 passwords and a quick reference for maintaining OpenLDAP on a Debian GNU/Linux server. This is neither an intro to LDAP or OpenLDAP nor a replacement for the documentation at Note also that this was written in 2005 and so the specifics are somewhat obsolete.

Installing OpenLDAP the Debian way

There are numerous ways to install LDAP. As a Debian sarge user, you can simply run apt-get update; apt-get install slapd to get OpenLDAP 2.1. This will get the LDAP server and all of the needed libraries. I recommend also installing ldap-utils and whatever packages are needed for your prefered scripting language (libnet-ldap-perl, python-ldap, etc). Debian woody defaults to 2.0. To get 2.1, add the following line to /etc/apt/sources.list and then follow the above instructions:

  deb woody openldap2 libgcrypt11 

Installing OpenLDAP 2.2 from source

I ended up building OpenLDAP from source in order to get support for old Netscape LDAP passwords (NS-MTA-MD5). Debian provides a number of tools for building packages from source (apt-get source, apt-get build-dep, dpkg-buildpackage, debian/rules, etc.) However, for the sake of generality, these instructions are (with minimal exception) not Debian specific.

First get the source and required libraries (more libraries may be required, especially for SASL support):

  cd /usr/local/src/
  tar xzvf openldap-2.2.23.tgz
  cd openldap-2.2.23
  apt-get install libdb4.2-dev libssl-dev libltdl3-dev

Read the README and INSTALL files and ponder the configure options given by ./configure --help. I used the following (note that --enable-modules is required for the NS-MTA-MD5 module):

  ./configure --enable-modules --enable-crypt

To make and install:

  make depend
  make test
  su -
  make install

Watch the output of all of the above. If you encounter errors, there are likely libraries that you are missing. Install them and try again. Note also that make test will take awhile and is optional.

To make and install the NS-MTA-MD5 module:

  cd contrib/slapd-modules/passwd/
  gcc -shared -I../../../include -Wall -g -o netscape.c
  su -
  mkdir /usr/local/libexec/openldap
  cp /usr/local/libexec/openldap/

Configuring OpenLDAP (slapd.conf)

Paths specified are for a source installation. For Debian installations, the configuration will be in /etc/ldap/, executables are in /usr/sbin/.

First edit the configuration (slapd.conf) and schemata:

  cd /usr/local/etc/openldap/
  edit slapd.conf as needed
  cd schema/
  add additional schema files as needed

A few slapd.conf directives are covered briefly here. For full details, man slapd.conf and see the Administrator's Guide.

After making changes, always test the configuration (using slaptest for 2.2 or slapd for 2.1):

  /usr/local/sbin/slaptest -f /usr/local/etc/openldap/slapd.conf -d2
  /usr/sbin/slapd -t -f /etc/ldap/slapd.conf

Access control: Access is controlled by ACLs in the slapd.conf file. The general form of an ACL in OpenLDAP 2.2 is:

  access to attr=[some_attr|*]
    by [anonymous|users|self|dn.base=some_dn|peername="ip:some_ip"|*]

SSL/TLS: Using SSL/TLS is one way to add encryption (ldaps://). SSL/TLS is covered in detail in the Administrator's Guide. In brief, if you don't already have one, you'll need to generate an SSL certificate:

  /usr/lib/ssl/misc/ -newca
  openssl req -newkey rsa:1024 -nodes -days 365 -keyout newreq.pem -out newreq.pem
  /usr/lib/ssl/misc/ -sign

This should create cacert.pem, newcert.pem, and newreq.pem. Copy these to /usr/local/etc/openldap/. Make sure that newcert.pem and newreq.pem are readable by root only (chmod 400 newcert.pem newreq.pem). You may also wish to rename these files.

Add the following lines to slapd.conf:

  TLSCACertificateFile /usr/local/etc/openldap/cacert.pem
  TLSCertificateFile /usr/local/etc/openldap/newcert.pem
  TLSCertificateKeyFile /usr/local/etc/openldap/newreq.pem

Each client that will access the OpenLDAP server using ldaps:// needs to have a copy of cacert.pem. The ldap.conf file must point to the certificate:

  TLS_CACERT /path/to/cacert.pem

Replication with slurpd: Replication is covered in detail in the Administrator's Guide. In brief, install OpenLDAP on both the master and the slave server. On the master server, add the replica and replog directives. These should look something like the following:

  replica uri=ldaps://
          bindmethod=simple credentials=
  replogfile      /usr/local/var/openldap-slurp/replog

On the slave, add an updatedn directive that matches the binddn line of the replica directive on the master. You must also define an appropriate access list. For example:

  updatedn "cn=replicator,dc=example,dc=edu"
  access to * by dn="cn=replicator,dc=example,dc=edu" write

Starting OpenLDAP the first time

The fastest way to load initial data is from an LDIF file. Make sure slapd is not running when you do this. If you are replicating to a slave, do this on both the master and slave.

  killall slapd
  /usr/local/sbin/slapadd -v -c -l example.ldif -f /usr/local/etc/openldap/slapd.conf
  /usr/local/sbin/slapindex -f /usr/local/etc/openldap/slapd.conf

For Debian installations, you should have the startup script /etc/init.d/slapd. Start slapd with /etc/init.d/slapd start.

For source installations, you'll need to create a startup script, such as /etc/init.d/slapd22. Symlink the startup script into the appropriate rc directories (in Debian, update-rc.d slapd22 defaults will do this automatically). Start slapd with /etc/init.d/slapd22 start.

In Debian, additional startup options are often defined in /etc/defaults/. For example, for SSL/TLS, create the file /etc/default/slapd as follows:

  SLAPD_SERVICES="ldaps:/// ldap:///"

Maintaining an OpenLDAP server

Logs: By default slapd logs to syslogd (LOG_LOCAL4). On a Debian system, this is /var/log/syslog. Extract the slapd logs with grep slapd /var/log/syslog or configure your syslog to keep a separate log file. slapd can be configured to log copious amounts of debugging info by setting loglevel num in the slapd.conf file. The default log level is 256, which is quite verbose. I recommend rotating and compressing the log file daily, as it grows large.

Starting and stopping slapd: In Debian, services are typically controlled with /etc/init.d/service [stop|start|restart] (e.g., /etc/init.d/slapd22 restart). Tail the logs (tail -f /var/log/syslog | grep slapd) and check the process table (ps aux | grep slapd) and open files (lsof -i | grep slapd) to determine the status of slapd. (Note: ldap runs on port 389; ldaps runs on port 636.)

Indexing: Indexing greatly improves speed, offloading work from the CPU and disk to memory. Indexing (of types pres, eq, approx, and sub) is specified in the slapd.conf file. slapd indices are generated by slapindex (e.g., slapindex -v -f /usr/local/etc/openldap/slapd.conf). To ensure data consistency, make sure slapd is not running while generating indices.

Backups: Backup data with slapcat (e.g., slapcat -v -f /usr/local/etc/openldap/slapd.conf -l /path/to/backup/$(date +%Y%m%d).ldif). To ensure consistency, slapd should not be running during backups.

Restoration:To do a full restore from backup, first stop slapd and remove all ldap data (e.g., rm /usr/local/var/openldap-data/ for source installations or rm /var/lib/ldap/* for Debian installations). Then use slapadd to load data from the ldif backup (e.g., slapadd -v -c -l example.ldif -f /usr/local/etc/openldap/slapd.conf for source installations or slapadd -v -c -l backup.ldif -f /etc/ldap/slapd.conf for Debian installations). Then run slapindex and start slapd.

Using ldap-utils: The ldap-utils package provides ldapsearch, ldapadd, ldapmodify, ldapdelete, and other useful tools. However, I'm convinced that no one can ever remember the syntax for these commands, so here are a few examples:

  ldapsearch -x -b 'dc=example,dc=edu' cn='Sgip Wolley' uid ou
  ldapsearch -x -b 'dc=example,dc=edu' "(&(ou=Math)(cn=*Pig*))"
  ldapsearch -ZZ -h -D 'uid=admin,dc=example,dc=edu' -b 'dc=example,dc=us' -W uid='swolley'
  ldapadd -x -D 'uid=admin,dc=example,dc=edu' -W -f newpigs.ldif

See also