OpenLDAP is an open source implementation of the Lightweight Directory Access Protocol. It includes libraries, clients, and a server. This page is about running the OpenLDAP Standalone LDAP Daemon slapd on Debian.

FixMe: update for (Buster/Bullseye) defaults and recommendations

ToDo: update for Buster/Bullseye; review, organize, refactor; consider moving specific topics (e.g. Samba) to separate pages

Documentation and resources

• The Debian-specific setup and configuration of slapd are documented in /usr/share/doc/slapd/README.Debian.gz.

• Debian users have contributed some wiki pages about LDAP and OpenLDAP.

• OpenLDAP includes comprehensive documentation in the form of man pages. In the beginning you will likely need (at least) slapd-config(5), ldapsearch(1), ldapmodify(1), and ldif(5). There are individual man pages for significant features of slapd(8) such as configuration, access control, backends, and overlays.

• The OpenLDAP project maintains an Administrator's Guide.

• The Ubuntu Server Guide includes a chapter on OpenLDAP, including guides for specific use cases.

• LDAP is defined in a number of RFC documents, beginning with RFC 4510.

• More information about LDAP in general may be found on LDAP.com.

Installing and configuring the OpenLDAP server

The OpenLDAP server package is slapd. The recommended tools for configuring slapd and setting up your directory are ldap-utils.

apt install slapd ldap-utils

You will be prompted to provide a password for the database administrator.

By default, an initial database is created in /var/lib/ldap and configured using the system's DNS domain name. If your system is in the domain example.com, the database suffix is dc=example,dc=com and the administrator is named cn=admin,dc=example,dc=com. The domain name and other details can be changed by preseeding, by running the installation at a different debconf(7) priority, or by running dpkg-reconfigure slapd after installation.

To check the database suffix, once the server is running, use ldapsearch(1) to read the namingContexts attribute of the root DSE:

ldapsearch -x -s base -b "" namingContexts

Tour of the installation

The following are the key files and directories installed by the slapd package:

• slapd(8) and the associated tools such as slapadd(8), slapcat(8), slapindex(8), and others are installed in /usr/sbin.

• The loadable modules included with slapd are installed in /usr/lib/ldap.

• LDAP Schema files included with slapd or other packages are installed in /etc/ldap/schema.

  • Files ending in .schema can be included into a legacy slapd.conf file. By default, the Debian setup does not use these files.

  • Files ending in .ldif can be imported into the configuration using ldapadd(1). This copies them into the configuration database and the source files are no longer used afterward.

• The configuration database cn=config is stored in /etc/ldap/slapd.d, owned by the openldap user.

• The default database is stored in /var/lib/ldap, owned by the openldap user.

The configuration is stored in an LDAP database rooted at cn=config. Debian's default access rules allow access by the system root user only. root may query or search the database using ldapsearch(1) with SASL EXTERNAL authentication:

ldapsearch -H ldapi:// -Y EXTERNAL -b "cn=config"

The package sets up a default directory based on the system's DNS domain. Debian's default access rules allow anyone to search this directory without any authentication:

ldapsearch -x -b "dc=example,dc=com"

To connect as the database administrator, use Simple authentication, and when prompted, enter the password configured during installation:

ldapsearch -x -D "cn=admin,dc=example,dc=com" -W -b "dc=example,dc=com"

Basic tasks

Enable request logging

The server logs are sent to the system log (syslog and/or the journal). The default log level is none.

To enable basic request logging, change the log level to stats:

ldapmodify -H ldapi:// -Y EXTERNAL << EOF
dn: cn=config
changetype: modify
replace: olcLogLevel
olcLogLevel: stats

EOF

If you wish to disable request logging later, repeat the procedure and set the log level back to none.

For more information, read about olcLogLevel in the slapd-config(5) man page.

Advanced tasks

Indexes

For better performance do more indexing than the default.

with slapd.conf

Create or modify /etc/ldap/slapd.conf to contain the following:

index   objectClass             eq
index   cn                      pres,sub,eq
index   sn                      pres,sub,eq
index   uid                     pres,sub,eq
index   displayName             pres,sub,eq
index   default                 sub
index   uidNumber               eq
index   gidNumber               eq
index   mail,givenName          eq,subinitial
index   dc                      eq

After any new indexes have been defined or other major database changes have been made (e.g. slapadd was used) it is best to recreate the indexes. Note that you should stop slapd before recreating the indexes and should fix the permissions afterward.

  # service slapd stop
  # sudo -u openldap slapindex
  # service slapd start

with cn=config

Create a LDIF file in /etc/ldap : olcDbIndex.ldif

dn: olcDatabase={1}mdb,cn=config
changetype: modify
add: olcDbIndex
olcDbIndex: cn pres,sub,eq
-
add: olcDbIndex
olcDbIndex: sn pres,sub,eq
-
add: olcDbIndex
olcDbIndex: uid pres,sub,eq
-
add: olcDbIndex
olcDbIndex: displayName pres,sub,eq
-
add: olcDbIndex
olcDbIndex: default sub
-
add: olcDbIndex
olcDbIndex: uidNumber eq
-
add: olcDbIndex
olcDbIndex: gidNumber eq
-
add: olcDbIndex
olcDbIndex: mail,givenName eq,subinitial
-
add: olcDbIndex
olcDbIndex: dc eq

Note: use the correct database format in the first line, the default type during installation of slapd is mdb.

Use ldapmodify to add the indexing settings to the ldap :

ldapmodify -Y EXTERNAL -H ldapi:/// -f ./olcDbIndex.ldif

Do not leave out the - (dash character) from the file, it is needed. After execution of the ldapmodify command, slapd will launch a internal task to create indexes. Don't stop slapd during indexing.

Access control

Configuring 'chsh' and 'chfn' to work with LDAP

with slapd.conf

Edit '/etc/ldap/slapd.conf' to allow access for users to update their loginShell and gecos entries by adding the following before the 'access to *' entry:

access to attrs=loginShell,gecos
      by dn="cn=admin,dc=example,dc=com" write
      by self write
      by * read

with cn=config

Create a LDIF file olcAccess.ldif with access permissions to loginShell and gecos entries for the user and admins :

dn: olcDatabase={1}hdb,cn=config
changetype: modify
add: olcAccess
olcAccess: {1}to attrs=loginShell,gecos
  by dn="cn=admin,dc=example,dc=com" write
  by self write
  by * read

Instanty apply these new permissions to ldap with :

ldapmodify -Y EXTERNAL -H ldapi:/// -f ./olcAccess.ldif

For SAMBA LDAP support

For Samba LDAP, slapd needs the Samba schema. The Debian package seems to have a samba.schema file which is old and out of date, and a samba.schema.gz file which is actually the correct one. Do the following (as root):

 # this package contains samba.schema.gz :
 aptitude install samba

Copy example samba.schema to ldap configuration directory:

 zcat /usr/share/doc/samba/examples/LDAP/samba.schema.gz > /etc/ldap/schema/samba.schema

with slapd.conf

Add the following line to /etc/ldap/slapd.conf after the other includes.

include /etc/ldap/schema/samba.schema

And restart slapd:

  # /etc/init.d/slapd restart

with cn=config

Create a temporary config file samba.conf:

  include          /etc/ldap/schema/core.schema
  include          /etc/ldap/schema/cosine.schema
  include          /etc/ldap/schema/nis.schema
  include          /etc/ldap/schema/inetorgperson.schema
  include          /etc/ldap/schema/samba.schema

Convert samba.schema into samba.ldif with slaptest:

  # mkdir /tmp/slapd.d
  # slaptest -f samba.conf -F /tmp/slapd.d/

Load the /tmp/slapd.d/cn=config/cn=schema/cn={4}samba.ldif into your cn=config using:

  # cp "/tmp/slapd.d/cn=config/cn=schema/cn={4}samba.ldif" "/etc/ldap/slapd.d/cn=config/cn=schema"
  # chown openldap: '/etc/ldap/slapd.d/cn=config/cn=schema/cn={4}samba.ldif'
  # /etc/init.d/slapd stop
  # /etc/init.d/slapd start

and check you now see the new samba schema:

# ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=schema,cn=config "(objectClass=olcSchemaConfig)" dn
dn: cn=schema,cn=config

dn: cn={0}core,cn=schema,cn=config

dn: cn={1}cosine,cn=schema,cn=config

dn: cn={2}nis,cn=schema,cn=config

dn: cn={3}inetorgperson,cn=schema,cn=config

dn: cn={4}samba,cn=schema,cn=config

Access controls for subtree-specific LDAP Admins

If you choose to use LDAP for many functions, such as having a single server for DNS, Authentication, and networking flat file database replacement, you may wish to have LDAP administrative users for each subtree in addition to the global admin (dn="cn=admin, dc=example, dc=com). The following example is useful when using a separate authentication tree which includes Samba.

 # The manager dn has full write access to the auth subtree
 # Everyone else has read access to not otherwise protected fields and entries
 access to dn.sub="ou=auth,dc=example,dc=com"
         by dn="cn=Manager,ou=auth,dc=example,dc=com" write
         by * read

Configuring TLS/SSL

Once your LDAP server is up and running, be sure to backup your configuration before trying to configure TLS. If you break your configuration with the "cn=config" style, the LDAP server will not restart.

Configuring the certificate (and possibly the CA used) in slapd config :

in /etc/ldap/slapd.conf:

TLSCACertificateFile    /etc/ssl/certs/server-intermediate.pem
TLSCertificateKeyFile   /etc/ssl/private/server-key.pem
TLSCertificateFile      /etc/ssl/certs/server-cert.pem

or add attributes to cn=config (for Debian Squeeze or later). Create a olcSSL.ldif file with:

dn: cn=config
add: olcTLSCACertificateFile
olcTLSCACertificateFile: /etc/ssl/certs/server-intermediate.pem
-
add: olcTLSCertificateKeyFile
olcTLSCertificateKeyFile: /etc/ssl/private/server-key.pem
-
add: olcTLSCertificateFile
olcTLSCertificateFile: /etc/ssl/certs/server-cert.pem

and import the settings with ldapmodify:

  # ldapmodify -Y EXTERNAL -H ldapi:/// -f ./olcSSL.ldif

By default, slapd runs as user/group openldap, so it can't read the key file. On Debian Lenny, the preferred solution to this dilemma seems to be to chown the key to root:ssl-cert, set permissions to 640 and add the user openldap to group ssl-cert:

usermod -a -G ssl-cert openldap

• In Wheezy, not adding openldap to the ssl-cert group caused this in logs:

main: TLS init def ctx failed: -1

Enable LDAPS (if required)

StartTLS is the standard operation for initiating TLS/SSL on an LDAP connection. StartTLS operates on the standard LDAP port (389) and no alternative port is necessary.

Clients using OpenLDAP libldap can be configured to use StartTLS, if they use an LDAP URL for connection configuration, by including the StartTLS extension in the URL. For example:

ldap://ldap.example.com/dc=example,dc=com????!StartTLS

The ldapurl(1) tool is useful for constructing correct LDAP URLs.

Some legacy LDAP clients do not support the StartTLS operation, but are able to use LDAPS (LDAP over SSL) on port 636. To support such clients, add ldaps:/// to the SLAPD_SERVICES list in /etc/default/slapd.

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

Symptoms:

In slapd debug output:

[...] TLS: could not set cipher list HIGH:MEDIUM:-SSLv2.  (or similar)

In /var/log/syslog:

[...] main: TLS init def ctx failed: -1

Diagnosis:

If you try to install the OpenLDAP server (slapd) with Debian Lenny, it comes compiled against the GnuTLS library. It means you cannot use an OpenSSL style directive like TLSCipherSuite HIGH:MEDIUM:-SSLv2 in slapd.conf.

Cure:

In /etc/ldap/slapd.conf, either comment out TLSCipherSuite option to let gnutls choose rather sane default for you, or use something like:

TLSCipherSuite NORMAL

To get all the supported GnuTLS cipher suite names:

# aptitude install gnutls-bin
# man gnutls-cli

And skip to TLS/SSL control options section of man page.

To use only 256 bit cyphers, use this (paranoiac?) setting:

TLSCipherSuite SECURE256:!AES-128-CBC:!ARCFOUR-128:!CAMELLIA-128-CBC:!3DES-CBC:!CAMELLIA-128-CBC

Another useful tool to test server-supported TLS options is to use gnutls-cli-debug. First add ldaps:/// string to the SLAPD_SERVICES option in /etc/default/slapd, restart slapd and then run

gnutls-cli-debug -p 636 <fqdn_of_you_ldap_host>

That will show you cryptographic suits your LDAP server supports.

Symptoms (round 2)

If you are getting messages such as

slapd TLS: can't connect: A TLS packet with unexpected length was received..

or

Could not negotiate a supported cipher suite.

take a wander by this.

Diagnosis:

How did you generate your certificates? If you generated them using OpenSSL, you're going to run into problems. Debian switched over to using gnutls a while ago, and it doesn't play nice with OpenSSL certificates. So, to fix this, check out the next section.

NOTE: On Debian Squeeze openldap is linked with gnutls as well, but works just fine with certificate generated by openssl.

NOTE about the above note: I don't find it to be the case, except for the CA cert. I ended up having to generate a new key & csr to sign with gnutls's certtool and then signing it with my existing openssl created CA like so:

certtool --generate-privkey --outfile ldap.gnutls.key
certtool --generate-certificate --load-privkey ldap.gnutls.key --outfile ldap.gnutls.crt --load-ca-certificate ca.crt --load-ca-privkey ca.key

Again, this allows you to keep your existing OpenSSL CA.

Procedure:

You're going to need the gnutls certificate generator: certtool available in gnutls-bin

Run these two commands to generate a new self-signed key (into the current working directory):

certtool --generate-privkey --outfile ca-key.pem
certtool --generate-self-signed --load-privkey ca-key.pem --outfile ca-cert.pem

Then, update your certificate locations in /etc/ldap/slapd.conf (TLSCertificateFile points to ca-cert.pem and TLSCertificateKeyFile points to ca-key.pem), comment out TLSCACertificateFile, and change TLSVerifyClient to never.

In /etc/ldap/ldap.conf, comment out TLS_CACERT and change TLS_REQCERT to never.

Since the certificate is self-signed, we can't have gnutls trying to verify it (hence the never), otherwise it will never run.

Then restart your services, and you're good (assuming all your links point properly to ldaps://url/).

Configuring MirrorMode LDAP Sync Replication (syncrepl)

See http://www.openldap.org/doc/admin24/replication.html for a clear explanation of OpenLDAP Replication. Several types of replication are possible, this section focusses on how to configure MirrorMode Replication.

with slapd.conf

See the aforementioned http://www.openldap.org/doc/admin24/replication.html for a clear explanation on how to configure MirrorMode LDAP Sync Replication (syncrepl) using the old slapd.conf syntax. No need to repeat this here.

with cn=config

MirrorMode LDAP Sync Replication (syncrepl) is achieved by following the seven small steps below.

1: Create a special user for the replication of the data.

This by default can't be done using the SASL/EXTERNAL authentication, since you will get a 'no write access to parent' error. Please use a basedn suited to your situation, in example change the "dc=nodomain" to the basedn for your server. Please see step 7 for the password chosen and use slappasswd command to format it.

$ ldapmodify -D "cn=admin,dc=nodomain" -W<<EOT
> dn: cn=mirrormode,dc=nodomain
> changetype: add
> objectClass: simpleSecurityObject
> objectClass: organizationalRole
> cn: mirrormode
> description: Syncrepl user for mirrormode operation
> userPassword: e1NTSEF9SktNQmpPV29zOEtPSCtaWmdDeTVUa056U3c5NWF5bis=
> EOT
Enter LDAP Password:
adding new entry "cn=mirrormode,dc=nodomain"

$

All the other steps can easily be done using the SASL/EXTERNAL authentication as explained in Missing slapd.conf. Just save the given information in a file and load it with: $ ldapmodify -Y EXTERNAL -H ldapi:/// -f <file.ldif>

2: Load the syncrepl module

dn: cn=module{0},cn=config
changetype: modify
add: olcModuleLoad
olcModuleLoad: syncprov

3: Set up replicator privileges

Make sure the newly created replication user can read the data to be replicated:

dn: olcDatabase={1}hdb,cn=config
changetype: modify
delete: olcAccess
olcAccess: {0}to attrs=userPassword,shadowLastChange by self write by anonymous auth by dn="cn=admin,dc=nodomain" write by * none
-
add: olcAccess
olcAccess: {0}to attrs=userPassword,shadowLastChange by self write by anonymous auth by dn="cn=admin,dc=nodomain" write by dn="cn=mirrormode,dc=nodomain" read by * none
-

4: Set up the provider slapd

dn: olcOverlay=syncprov,olcDatabase={1}hdb,cn=config
changeType: add
objectClass: olcOverlayConfig
objectClass: olcSyncProvConfig
olcOverlay: syncprov
olcSpCheckpoint: 100 10
olcSpSessionLog: 100

5: Set up indexing for entryUUID

Note that using the session log requires searching on the entryUUID attribute. Setting an eq index on this attribute will greatly benefit the performance of the session log on the provider:

dn: olcDatabase={1}hdb,cn=config
changeType: modify
delete: olcDbIndex
olcDbIndex: objectClass eq
-
add: olcDbIndex
olcDbIndex: objectClass,entryCSN,entryUUID eq
-

6: Set the server ID.

Make sure you use different ID's for different servers, in example 0, 1, etc...:

dn: cn=config
changeType: modify
add: olcServerID
olcServerID: 0
-

7: Enable the replication.

Make sure you use the correct IP number for each ldap server and make sure they point to each other! Also, the credentials are just an example. Choose a password of your own of course:

dn: olcDatabase={1}hdb,cn=config
changeType: modify
add: olcSyncrepl
olcSyncrepl: rid=001 provider=ldap://172.16.42.74:389 bindmethod=simple binddn="cn=mirrormode,dc=nodomain" credentials=_ei7N8o.gh=o44 searchbase="dc=nodomain" schemachecking=on type=refreshAndPersist retry="60 +"
-
add: olcMirrorMode
olcMirrorMode: TRUE
-

And you're up and running. Try adding something to one of the LDAP servers and see it appear automagically at the other. Well done my friend!

CategorySystemAdministration