OpenLDAP is an open-source implementation of the LDAP protocol. An LDAP server basically is a non-relational database which is optimised for accessing, but not writing, data. It is mainly used as an address book (for e.g. email clients) or authentication backend to various services (such as Samba, where it is used to emulate a domain controller, or Linux system authentication, where it replaces
/etc/passwd) and basically holds the user data.
ldapsearch) are client-side utilities, while commands that begin with
slapcat) are server-side.
This page is a starting point for a basic OpenLDAP installation and a sanity check.
OpenLDAP contains both a LDAP server and client. Install it with the package .
slapd.confconfiguration, you can simply convert it into the new
/var/lib/openldap/openldap-data/. So, backup your
Slapd, the server, stores its configuration directly inside its database. Thus, we need to write our configuration as an LDIF file and import it.
First, create a file
config.ldif containing the following minimal sane configuration. This file declares the basic config structure and a database stored at
# The root config entry dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /run/openldap/slapd.args olcPidFile: /run/openldap/slapd.pid # Schemas dn: cn=schema,cn=config objectClass: olcSchemaConfig cn: schema # TODO: Include further schemas as necessary include: file:///etc/openldap/schema/core.ldif # The config database dn: olcDatabase=config,cn=config objectClass: olcDatabaseConfig olcDatabase: config olcRootDN: cn=Manager,$BASEDN # The database for our entries dn: olcDatabase=mdb,cn=config objectClass: olcDatabaseConfig objectClass: olcMdbConfig olcDatabase: mdb olcSuffix: $BASEDN olcRootDN: cn=Manager,$BASEDN olcRootPW: $PASSWD olcDbDirectory: /var/lib/openldap/openldap-data # TODO: Create further indexes olcDbIndex: objectClass eq
There are a few options you will need to change:
- Every occurence of
$BASEDNmust be replaced with a valid DN. If you own a domain
example.comyou will most likely want to choose
$PASSWDmust be replaced by a salted and hashed password, which you may generate by running
Additionally, you might consider to add further schemas and create additional indexes to tune the performance of your database. The specifics will depend on your use case, but here are a few recommendations:
# Additional schemas include: file:///etc/openldap/schema/cosine.ldif # RFC1274: Cosine and Internet X.500 schema include: file:///etc/openldap/schema/inetorgperson.ldif # RFC2798: Internet Organizational Person include: file:///etc/openldap/schema/nis.ldif # RFC2307: An Approach for Using LDAP as a Network Information Service # Additional indexes olcDbIndex: objectClass eq olcDbIndex: uid pres,eq olcDbIndex: mail pres,sub,eq olcDbIndex: cn,sn pres,sub,eq olcDbIndex: dc eq
To import these settings as the
ldap user using
# sudo -u ldap slapadd -n 0 -F /etc/openldap/slapd.d/ -l ./config.ldif
Alternatively, you may also run this directly as
root. However, if you do, make sure
/etc/openldap/slapd.d/ is accessible by
# slapadd -n 0 -F /etc/openldap/slapd.d/ -l ./config.ldif # chown -R ldap:ldap /etc/openldap/*
By default, OpenLDAP will listen unencrypted on all interfaces. To make it only listen on local IP interfaces, you may edit the service file:
systemctl edit slapd
[Service] ExecStart= ExecStart=/usr/bin/slapd -u ldap -g ldap -h "ldap://127.0.0.1/ ldap://[::1]"
Finally, start the slapd daemon with
slapd.service using systemd.
The client config file is located at
It is quite simple: you will only have to alter
BASE to reflect the suffix of the server, and
URI to reflect the address of the server, like:
BASE dc=example,dc=com URI ldap://localhost
If you decide to use SSL:
- The protocol (ldap or ldaps) in the
URIentry has to conform with the slapd configuration
- If you decide to use self-signed certificates, add a
TLS_REQCERT allowline to
- If you use a signed certificate from a CA, add the line
Create initial entry
Once your client is configured, you probably want to create the root entry, and an entry for the Manager role:
$ ldapadd -x -D 'cn=Manager,dc=example,dc=com' -W dn: dc=example,dc=com objectClass: dcObject objectClass: organization dc: example o: Example description: Example directory dn: cn=Manager,dc=example,dc=com objectClass: organizationalRole cn: Manager description: Directory Manager ^D
The text after the first line is entered on stdin, or could be read from a file either with the -f option or a file redirect.
Test your new OpenLDAP installation
This is easy, just run the command below:
$ ldapsearch -x '(objectclass=*)' -b 'dc=example,dc=com'
Or authenticating as the rootdn (replacing
-D <user> -W), using the example configuration we had above:
$ ldapsearch -D "cn=Manager,dc=example,dc=com" -W '(objectclass=*)' -b 'dc=example,dc=com'
Now you should see some information about your database.
OpenLDAP over TLS
If you access the OpenLDAP server over the network and especially if you have sensitive data stored on the server you run the risk of someone sniffing your data which is sent clear-text. The next part will guide you on how to setup an SSL connection between the LDAP server and the client so the data will be sent encrypted.
In order to use TLS, you must have a certificate. For testing purposes, a self-signed certificate will suffice. To learn more about certificates, see OpenSSL.
Create a self-signed certificate
To create a self-signed certificate, type the following:
$ openssl req -new -x509 -nodes -out slapdcert.pem -keyout slapdkey.pem -days 365
You will be prompted for information about your LDAP server. Much of the information can be left blank. The most important information is the common name. This must be set to the DNS name of your LDAP server. If your LDAP server's IP address resolves to example.org but its server certificate shows a CN of bad.example.org, LDAP clients will reject the certificate and will be unable to negotiate TLS connections (apparently the results are wholly unpredictable).
Now that the certificate files have been created copy them to
/etc/openldap/ssl/ (create this directory if it does not exist) and secure them.
slapdcert.pem must be world readable because it contains the public key.
slapdkey.pem on the other hand should only be readable for the ldap user for security reasons:
# mv slapdcert.pem slapdkey.pem /etc/openldap/ssl/ # chmod -R 755 /etc/openldap/ssl/ # chmod 400 /etc/openldap/ssl/slapdkey.pem # chmod 444 /etc/openldap/ssl/slapdcert.pem # chown ldap /etc/openldap/ssl/slapdkey.pem
Configure slapd for SSL
Edit the configuration to tell LDAP where the certificate files reside by executing the following command:
ldapmodify -D 'cn=Manager,dc=example,dc=com' -W
dn: cn=config add: olcTLSCertificateFile olcTLSCertificateFile: /etc/openldap/ssl/slapdcert.pem - add: olcTLSCertificateKeyFile olcTLSCertificateKeyFile: /etc/openldap/ssl/slapdkey.pem
If you are using a signed SSL Certificate from a certification authority such as Let’s Encrypt, you will also need to specify the path to the root certificates database and your intermediary certificate. You will also need to change ownership of the
.pem files and intermediary directories to make them readable to the user
ldapmodify -D 'cn=Manager,dc=example,dc=com' -W
dn: cn=config add: olcTLSCACertificateFile olcTLSCACertificateFile: /etc/letsencrypt/live/ldap.my-domain.com/chain.pem - add: olcTLSCertificateFile olcTLSCertificateFile: /etc/letsencrypt/live/ldap.my-domain.com/cert.pem - add: olcTLSCertificateKeyFile olcTLSCertificateKeyFile: /etc/letsencrypt/live/ldap.my-domain.com/privkey.pem - add: olcTLSCACertificatePath olcTLSCACertificatePath: /usr/share/ca-certificates/trust-source
Disable SSLv2/v3 and use strong ciphers.
ldapmodify -D 'cn=Manager,dc=example,dc=com' -W
dn: cn=config add: olcTLSCipherSuite olcTLSCipherSuite: HIGH:MEDIUM:!SSLv2:!SSLv3
The TLSCipherSuite specifies a list of OpenSSL ciphers from which slapd will choose when negotiating TLS connections, in decreasing order of preference. In addition to those specific ciphers, you can use any of the wildcards supported by OpenSSL. NOTE: DEFAULT is a wildcard. Seefor description of ciphers, wildcards and options supported.
openssl ciphers -v ALL:COMPLEMENTOFALL. Always test which ciphers will actually be enabled by TLSCipherSuite by providing it to OpenSSL command, like this:
openssl ciphers -v 'DEFAULT'
Start slapd with SSL
You will have to edit
slapd.service to change the protocol slapd listens on.
Create the override unit:
systemctl edit slapd.service
[Service] ExecStart= ExecStart=/usr/bin/slapd -u ldap -g ldap -h "ldaps:///"
Localhost connections do not need to use SSL. So, if you want to access the server locally you should change the
ExecStart line to:
ExecStart=/usr/bin/slapd -u ldap -g ldap -h "ldap://127.0.0.1 ldaps:///"
slapd.service. If it was enabled before, reenable it now.
/etc/openldap/ldap.confon the client, or it will not be able connect to the server.
You now have a basic LDAP installation. The next step is to design your directory. The design is heavily dependent on what you are using it for. If you are new to LDAP, consider starting with a directory design recommended by the specific client services that will use the directory (PAM, Postfix, etc).
A directory for system authentication is the LDAP authentication article.
A nice web frontend is phpLDAPadmin.
It is imperative that we have a backup of our LDAP database and configuration in case we ever need to restore for any number of reasons.
$ slapcat -F /etc/openldap/slapd.d -n 0 -l "$(hostname)-ldap-mdb-config-$(date '+%F').ldif"
$ slapcat -l "$(hostname)-ldap-database-$(date '+%F').ldif"
slapd configuration checking
You can check config settings with
$ slaptest -F /etc/openldap/slapd.d/ -v
Client authentication checking
If you cannot connect to your server for non-secure authentication
$ ldapsearch -x -H ldap://ldaservername:389 -D cn=Manager,dc=example,dc=exampledomain
and for TLS secured authentication with:
$ ldapsearch -x -H ldaps://ldaservername:636 -D cn=Manager,dc=example,dc=exampledomain
LDAP server stops suddenly
If you notice that slapd seems to start but then stops, try running:
# chown -R ldap:ldap /var/lib/openldap
to allow slapd write access to its data directory as the user "ldap".
LDAP server does not start
Try starting the server from the command line with debugging output enabled:
# slapd -u ldap -g ldap -h ldaps://ldaservername:636 -d Config,Stats
- Official OpenLDAP Software 2.4 Administrator's Guide
- phpLDAPadmin is a web interface tool in the style of phpMyAdmin.
- LDAP authentication
- Arch User Repository is an Eclipse-based LDAP viewer. Works perfect with OpenLDAP installations. AUR from the