Difference between revisions of "OpenLDAP"

From ArchWiki
Jump to: navigation, search
(/etc/openldap/slapd.conf)
(removed the core.schema line since it already exists in the default config, and made a note regarding the samba.schema since it is MIA)
 
(119 intermediate revisions by 27 users not shown)
Line 1: Line 1:
 
[[Category:Networking]]
 
[[Category:Networking]]
[[ru:openLDAP]]
+
[[ja:openLDAP]]
 +
[[ru:OpenLDAP]]
 +
[[zh-CN:OpenLDAP]]
 +
{{Related articles start}}
 +
{{Related|LDAP Authentication}}
 +
{{Related|LDAP Hosts}}
 +
{{Related articles end}}
  
{{Out_of_date|slapd.conf(5) is deprecated; use slapd-config(5)}}
+
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 [[LDAP authentication|Linux system authentication]], where it replaces {{ic|/etc/passwd}}) and basically holds the user data.
  
OpenLDAP, LDAP & Directory services are an enormous topic. Configuration is therefore complex. This page is a starting point for a basic openldap install on Archlinux and a sanity check.  
+
{{note|Commands related to OpenLDAP that begin with {{ic|ldap}} (like {{ic|ldapsearch}}) are client-side utilities, while commands that begin with {{ic|slap}} (like {{ic|slapcat}}) are server-side.}}
  
If you are totally new to those concepts, [http://www.brennan.id.au/20-Shared_Address_Book_LDAP.html here] is an good introduction that is easy to understand and that will get you started, even if you are new to everything LDAP.
+
This page is a starting point for a basic OpenLDAP installation and a sanity check.
 +
 
 +
{{Tip|Directory services are an enormous topic. Configuration can therefore be complex.  If you are totally new to those concepts, [http://www.brennan.id.au/20-Shared_Address_Book_LDAP.html this] is an good introduction that is easy to understand and that will get you started, even if you are new to everything LDAP.}}
  
 
== Installation ==
 
== Installation ==
  
This part is easy:
+
OpenLDAP contains both a LDAP server and client. [[Install]] it with the package {{Pkg|openldap}}.
pacman -S openldap
+
 
+
The openldap package basically contains two things: The LDAP server (slapd) and the LDAP client. You will probably want to run the server on your computer. After you design the directory, the server will be able to provide authentication services for LDAP clients. It is quite likely that you will run services requiring the LDAP authentication on that very computer, in which case the LDAP client will query the LDAP server from the same package.
+
  
 
== Configuration ==
 
== Configuration ==
  
=== The server (slapd) ===
+
=== The server ===
  
First prepare the database directory. You will need to copy the default config file and set the proper ownership.
+
{{Note|If you already have an OpenLDAP database on your machine, remove it by deleting everything inside {{ic|/var/lib/openldap/openldap-data/}}.}}
  
{{Warning|The following snippet wipes out any existing ldap database.}}
+
The server configuration file is located at {{ic|/etc/openldap/slapd.conf}}.
  
rm -rf /var/lib/openldap/openldap-data/*
+
Edit the suffix and rootdn. The suffix typically is your domain name but it does not have to be. It depends on how you use your directory. We will use ''example'' for the domain name, and ''com'' for the tld. The rootdn is your LDAP administrator's name (we will use ''root'' here).
cp /etc/openldap/DB_CONFIG.example /var/lib/openldap/openldap-data/DB_CONFIG
+
chown ldap:ldap /var/lib/openldap/openldap-data/DB_CONFIG
+
 
+
==== /etc/openldap/slapd.conf ====
+
Next we prepare slapd.conf. Add some typically used schemas...
+
{{bc|
+
include        /etc/openldap/schema/cosine.schema
+
include        /etc/openldap/schema/nis.schema
+
include        /etc/openldap/schema/inetorgperson.schema
+
}}
+
Edit the suffix. Typically this is your domain name but it does not have to be. It depends on how you use your directory. We will use 'example' for the domain name, and 'com' for the tld. Also set your ldap administrators name (we'll use 'root' here)
+
 
{{bc|<nowiki>
 
{{bc|<nowiki>
 
suffix    "dc=example,dc=com"
 
suffix    "dc=example,dc=com"
Line 41: Line 35:
  
 
Now we delete the default root password and create a strong one:
 
Now we delete the default root password and create a strong one:
  #find the line with rootpw and delete it
+
  # sed -i "/rootpw/ d" /etc/openldap/slapd.conf #find the line with rootpw and delete it
sed -i "/rootpw/ d" slapd.conf
+
  # echo "rootpw    $(slappasswd)" >> /etc/openldap/slapd.conf #add a line which includes the hashed password output from slappasswd
#add a line which includes the hashed password output from slappasswd
+
  echo "rootpw    $(slappasswd)" >> slapd.conf
+
  
ldap won't find things unless you index them. Read the [http://www.zytrax.com/books/ldap/ch6/#index ldap documentation] for details, you can use the following to start with. (add them to your {{ic|slapd.conf}})
+
You will likely want to add some typically used [http://www.openldap.org/doc/admin24/schema.html schemas] to the top of {{ic|slapd.conf}}:
 +
 
 +
{{Note|currently missing:   
 +
cp /usr/share/doc/samba/examples/LDAP/samba.schema /etc/openldap/schema}}
 +
 
 +
{{bc|
 +
include        /etc/openldap/schema/cosine.schema
 +
include        /etc/openldap/schema/inetorgperson.schema
 +
include        /etc/openldap/schema/nis.schema
 +
#include        /etc/openldap/schema/samba.schema
 +
}}
 +
 
 +
You will likely want to add some typically used [http://www.openldap.org/doc/admin24/tuning.html#Indexes indexes] to the bottom of {{ic|slapd.conf}}:
 
{{bc|
 
{{bc|
 
index  uid            pres,eq
 
index  uid            pres,eq
Line 55: Line 59:
 
}}
 
}}
  
'''Note: '''
+
Now prepare the database directory. You will need to copy the default config file and set the proper ownership:
 +
# cp /etc/openldap/DB_CONFIG.example /var/lib/openldap/openldap-data/DB_CONFIG
 +
# chown ldap:ldap /var/lib/openldap/openldap-data/DB_CONFIG
  
Don't forget to run {{ic|slapindex}} after you populate your directory. (slapd needs to be stopped to do this). Then change the ownership for all the generated files:
+
{{Note|With OpenLDAP 2.4 the configuration of {{ic|slapd.conf}} is deprecated. From this version on all configuration settings are stored in {{ic|/etc/openldap/slapd.d/}}.}}
chown ldap:ldap /var/lib/openldap/openldap-data/*
+
  
If you want to use SSL, you have to specify a path to your certificates here. See [[OpenLDAP Authentication]]
+
To store the recent changes in {{ic|slapd.conf}} to the new {{ic|/etc/openldap/slapd.d/}} configuration settings, we have to delete the old configuration files first, do this every time you change the configuration:
  
Finally you can start the slapd daemon.
+
  # rm -rf /etc/openldap/slapd.d/*
  #systemctl start slapd
+
  
It might be possible that /run/openldap does not exist, starting the daemon won't work. Just create the directory and change the permission:
+
 +
(if you do not have a database yet, you might need to create one by starting and stopping the {{ic|slapd.service}} [[systemd#Using units|using systemd]] )
  
#mkdir /run/openldap
+
Then we generate the new configuration with:
#chown ldap:ldap /run/openldap
+
  
==== /etc/conf.d/slapd ====
+
# slaptest -f /etc/openldap/slapd.conf -F /etc/openldap/slapd.d/
Very important, you define here on which port the server should listen and if you want to use SSL, you will want to use the ldaps:// URI instead of the default ldap://
+
You can also specify additional slapd options here.
+
  
 +
The above command has to be run every time you change {{ic|slapd.conf}}. Check if everything succeeded. Ignore message "bdb_monitor_db_open: monitoring disabled; configure monitor database to enable".
 +
 +
Change ownership recursively on the new files and directory in /etc/openldap/slapd.d:
 +
 +
# chown -R ldap:ldap /etc/openldap/slapd.d
 +
 +
 +
{{note|Index the directory after you populate it. You should stop slapd before doing this.
 +
# slapindex
 +
# chown ldap:ldap /var/lib/openldap/openldap-data/*
 +
 +
or just
 +
 +
$ sudo -u ldap slapindex
 +
}}
 +
 +
Finally, start the slapd daemon with {{ic|slapd.service}} using systemd.
  
 
=== The client ===
 
=== The client ===
The client is usually not such a big deal, just keep in mind that your apps that require LDAP auth use it, so if something goes wrong with LDAP, do not waste your time with the app, start debugging the client instead.
+
The client config file is located at {{ic|/etc/openldap/ldap.conf}}.  
  
The client config file is located at /etc/openldap/ldap.conf
+
It is quite simple: you will only have to alter {{ic|BASE}} to reflect the suffix of the server, and {{ic|URI}} to reflect the address of the server, like:
It is actually very simple.
+
 
 +
{{hc|/etc/openldap/ldap.conf|2=
 +
BASE            dc=example,dc=com
 +
URI            ldap://localhost
 +
}}
  
 
If you decide to use SSL:
 
If you decide to use SSL:
* The protocol (ldap or ldaps) in the URI entry has to conform with the slapd configuration  
+
 
* If you decide to use self-signed certificates, you have to add them to TLS_CACERT
+
* The protocol (ldap or ldaps) in the {{ic|URI}} entry has to conform with the slapd configuration
 +
* If you decide to use self-signed certificates, add a {{ic|TLS_REQCERT allow}} line to {{ic|ldap.conf}}
 +
* If you use a signed certificate from a CA, add the line {{ic|TLS_CACERTDIR  /usr/share/ca-certificates/trust-source}} in {{ic|ldap.conf}}.
 +
 
 +
=== Create initial entry ===
 +
Once your client is configured, you probably want to create the root entry, and an entry for the root role:
 +
 
 +
$ ldapadd -x -D 'cn=root,dc=example,dc=com' -W
 +
dn: dc=example,dc=com
 +
objectClass: dcObject
 +
objectClass: organization
 +
dc: example
 +
o: Example
 +
description: Example directory
 +
 +
dn: cn=root,dc=example,dc=com
 +
objectClass: organizationalRole
 +
cn: root
 +
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 ===
 
=== Test your new OpenLDAP installation ===
  
 
This is easy, just run the command below:
 
This is easy, just run the command below:
  ldapsearch -x -b '' -s base '(objectclass=*)' namingContexts
+
  $ ldapsearch -x '(objectclass=*)'
  
you should see some information on your database.
+
Or authenticating as the rootdn (replacing {{ic|-x}} by {{ic|-D <user> -W}}), using the example configuration we had above:
 +
$ ldapsearch -D "cn=root,dc=example,dc=com" -W '(objectclass=*)'
 +
 
 +
Now you should see some information about your database.
  
 
=== OpenLDAP over TLS ===
 
=== OpenLDAP over TLS ===
{{Note|[http://web.archive.org/web/20130211222328/http://www.openldap.org/pub/ksoper/OpenLDAP_TLS.html#4.0 upstream documentation] is much more useful/complete than this section}}
+
{{Note|[http://www.openldap.org/doc/admin24/ upstream documentation] is much more useful/complete than this section}}
 +
 
 +
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.
  
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]].
  
In order to use TLS, we must first create a certificate. You can have a certificate signed, or create your own Certificate Authority (CA), but for our purposed, a self-signed certificate will suffice.
 
 
{{Warning|OpenLDAP cannot use a certificate that has a password associated to it.}}
 
{{Warning|OpenLDAP cannot use a certificate that has a password associated to it.}}
  
 
==== Create a self-signed certificate ====
 
==== Create a self-signed certificate ====
 
To create a ''self-signed'' certificate, type the following:
 
To create a ''self-signed'' certificate, type the following:
{{bc|openssl req -new -x509 -nodes -out slapdcert.pem -keyout slapdkey.pem -days 365}}
+
$ 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).
 
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 {{ic|/etc/openldap/ssl/}} (if this directory doesn't exist create it) and secure them.  
+
Now that the certificate files have been created copy them to {{ic|/etc/openldap/ssl/}} (create this directory if it does not exist) and secure them.  
'''IMPORTANT:''' 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:
+
{{ic|slapdcert.pem}} must be world readable because it contains the public key. {{ic|slapdkey.pem}} on the other hand should only be readable for the ldap user for security reasons:
{{bc|
+
# mv slapdcert.pem slapdkey.pem /etc/openldap/ssl/
cp slapdcert.pem slapdkey.pem /etc/openldap/ssl/
+
# chmod -R 755 /etc/openldap/ssl/
chown ldap slapdkey.pem
+
# chmod 400 /etc/openldap/ssl/slapdkey.pem
chmod 400 slapdkey.pem
+
# chmod 444 /etc/openldap/ssl/slapdcert.pem
chmod 444 slapdcert.pem
+
# chown ldap /etc/openldap/ssl/slapdkey.pem
}}
+
  
 
==== Configure slapd for SSL ====
 
==== Configure slapd for SSL ====
Line 119: Line 166:
 
{{bc|
 
{{bc|
 
# Certificate/SSL Section
 
# Certificate/SSL Section
TLSCipherSuite HIGH:MEDIUM:+SSLv2
+
TLSCipherSuite DEFAULT
 
TLSCertificateFile /etc/openldap/ssl/slapdcert.pem
 
TLSCertificateFile /etc/openldap/ssl/slapdcert.pem
 
TLSCertificateKeyFile /etc/openldap/ssl/slapdkey.pem
 
TLSCertificateKeyFile /etc/openldap/ssl/slapdkey.pem
 
}}
 
}}
  
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:''' HIGH, MEDIUM, and +SSLv2 are all wildcards.  
+
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 {{ic|.pem}} files and intermediary directories to make them readable to the user {{ic|ldap}}:
 +
{{bc|
 +
# Certificate/SSL Section
 +
TLSCipherSuite DEFAULT
 +
TLSCertificateFile /etc/letsencrypt/live/ldap.my-domain.com/cert.pem
 +
TLSCertificateKeyFile /etc/letsencrypt/live/ldap.my-domain.com/privkey.pem
 +
TLSCACertificateFile /etc/letsencrypt/live/ldap.my-domain.com/chain.pem
 +
TLSCACertificatePath /usr/share/ca-certificates/trust-source
 +
}}
 +
 
 +
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. See {{ic|man ciphers}} for description of ciphers, wildcards and options supported.
 +
 
 +
{{Note|To see which ciphers are supported by your local OpenSSL installation, type the following: {{ic|openssl ciphers -v ALL:COMPLEMENTOFALL}}. Always test which ciphers will actually be enabled by TLSCipherSuite by providing it to OpenSSL command, like this: {{ic|openssl ciphers -v 'DEFAULT'}} }}
  
{{Note|To see which ciphers are supported by your local OpenSSL installation, type the following: {{ic|openssl ciphers -v ALL}} }}
+
Regenerate the configuration directory:
 +
# rm -rf /etc/openldap/slapd.d/*                                  # erase old config settings
 +
# slaptest -f /etc/openldap/slapd.conf -F /etc/openldap/slapd.d/  # generate new config directory from config file
 +
# chown -R ldap:ldap /etc/openldap/slapd.d                        # Change ownership recursively to ldap on the config directory
  
 
==== Start slapd with SSL ====
 
==== Start slapd with SSL ====
In order to tell OpenLDAP to start using encryption, edit /etc/conf.d/slapd, uncomment the SLAPD_SERVICES line and set it to the following:
+
You will have to edit {{ic|slapd.service}} to change to protocol slapd listens on.
{{bc|1=SLAPD_SERVICES="ldaps:///"}}
+
Localhost connections don't need to use SSL so you can use this instead:
+
{{bc|1=SLAPD_SERVICES="ldap://127.0.0.1 ldaps:///:}}
+
  
 +
Create the override unit:
 +
{{hc|systemctl edit slapd.service|<nowiki>
 +
[Service]
 +
ExecStart=
 +
ExecStart=/usr/bin/slapd -u ldap -g ldap -h "ldaps:///"</nowiki>}}
  
'''IMPORTANT:''' If you created a self-signed certificate above be sure to add the following line to /etc/openldap/ldap.conf or you won't be able connect to the server to test it:
+
Localhost connections do not need to use SSL. So, if you want to access the server locally you should change the {{ic|ExecStart}} line to:
 +
ExecStart=/usr/bin/slapd -u ldap -g ldap -h "ldap://127.0.0.1 ldaps:///"
  
TLS_REQCERT allow
+
Then [[restart]] {{ic|slapd.service}}. If it was enabled before, reenable it now.
  
Finally restart the server.
+
{{Note|If you created a self-signed certificate above, be sure to add {{ic|TLS_REQCERT allow}} to {{ic|/etc/openldap/ldap.conf}} on the client, or it will not be able connect to the server.}}
  
 
== Next Steps ==
 
== Next Steps ==
  
You now have a basic ldap installation. The 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).
+
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 directory for system authentication is the [[LDAP authentication]] article.
 +
 
 +
A nice web frontend is [[phpLDAPadmin]].
  
 
== Troubleshooting ==
 
== Troubleshooting ==
If you notice that slapd seems to start but then stops, you may have a permission issue with the ldap datadir. Try running:
+
 
 +
=== 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 ldap:ldap /var/lib/openldap/openldap-data/*
 
  # chown ldap:ldap /var/lib/openldap/openldap-data/*
  
to allow slapd write access to its data directory as the user "ldap"
+
to allow slapd write access to its data directory as the user "ldap".
 +
 
 +
=== LDAP Server Doesn't 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
  
 
== See Also ==
 
== See Also ==
* http://www.openldap.org/doc/admin24/
+
* [http://www.openldap.org/doc/admin24/ Official OpenLDAP Software 2.4 Administrator's Guide]
* [http://phpldapadmin.sourceforge.net/ phpLDAPadmin] is a web interface tool in the style of phpmyadmin.
+
* [[phpLDAPadmin]] is a web interface tool in the style of phpMyAdmin.
* {{AUR|apachedirectorystudio2}} from the [[Arch User Repository]] is an Eclipse-based LDAP viewer. Works perfect for OpenLDAP installations.
+
* [[LDAP authentication]]
 +
* {{AUR|apachedirectorystudio}} from the [[Arch User Repository]] is an Eclipse-based LDAP viewer. Works perfect with OpenLDAP installations.

Latest revision as of 22:03, 6 September 2016

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.

Note: Commands related to OpenLDAP that begin with ldap (like ldapsearch) are client-side utilities, while commands that begin with slap (like slapcat) are server-side.

This page is a starting point for a basic OpenLDAP installation and a sanity check.

Tip: Directory services are an enormous topic. Configuration can therefore be complex. If you are totally new to those concepts, this is an good introduction that is easy to understand and that will get you started, even if you are new to everything LDAP.

Installation

OpenLDAP contains both a LDAP server and client. Install it with the package openldap.

Configuration

The server

Note: If you already have an OpenLDAP database on your machine, remove it by deleting everything inside /var/lib/openldap/openldap-data/.

The server configuration file is located at /etc/openldap/slapd.conf.

Edit the suffix and rootdn. The suffix typically is your domain name but it does not have to be. It depends on how you use your directory. We will use example for the domain name, and com for the tld. The rootdn is your LDAP administrator's name (we will use root here).

suffix     "dc=example,dc=com"
rootdn     "cn=root,dc=example,dc=com"

Now we delete the default root password and create a strong one:

# sed -i "/rootpw/ d" /etc/openldap/slapd.conf #find the line with rootpw and delete it
# echo "rootpw    $(slappasswd)" >> /etc/openldap/slapd.conf  #add a line which includes the hashed password output from slappasswd

You will likely want to add some typically used schemas to the top of slapd.conf:

Note: currently missing: cp /usr/share/doc/samba/examples/LDAP/samba.schema /etc/openldap/schema
include         /etc/openldap/schema/cosine.schema
include         /etc/openldap/schema/inetorgperson.schema
include         /etc/openldap/schema/nis.schema
#include         /etc/openldap/schema/samba.schema

You will likely want to add some typically used indexes to the bottom of slapd.conf:

index   uid             pres,eq
index   mail            pres,sub,eq
index   cn              pres,sub,eq
index   sn              pres,sub,eq
index   dc              eq

Now prepare the database directory. You will need to copy the default config file and set the proper ownership:

# cp /etc/openldap/DB_CONFIG.example /var/lib/openldap/openldap-data/DB_CONFIG
# chown ldap:ldap /var/lib/openldap/openldap-data/DB_CONFIG
Note: With OpenLDAP 2.4 the configuration of slapd.conf is deprecated. From this version on all configuration settings are stored in /etc/openldap/slapd.d/.

To store the recent changes in slapd.conf to the new /etc/openldap/slapd.d/ configuration settings, we have to delete the old configuration files first, do this every time you change the configuration:

# rm -rf /etc/openldap/slapd.d/*


(if you do not have a database yet, you might need to create one by starting and stopping the slapd.service using systemd )

Then we generate the new configuration with:

# slaptest -f /etc/openldap/slapd.conf -F /etc/openldap/slapd.d/

The above command has to be run every time you change slapd.conf. Check if everything succeeded. Ignore message "bdb_monitor_db_open: monitoring disabled; configure monitor database to enable".

Change ownership recursively on the new files and directory in /etc/openldap/slapd.d:

# chown -R ldap:ldap /etc/openldap/slapd.d


Note: Index the directory after you populate it. You should stop slapd before doing this.
# slapindex
# chown ldap:ldap /var/lib/openldap/openldap-data/*

or just

$ sudo -u ldap slapindex

Finally, start the slapd daemon with slapd.service using systemd.

The client

The client config file is located at /etc/openldap/ldap.conf.

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:

/etc/openldap/ldap.conf
BASE            dc=example,dc=com
URI             ldap://localhost

If you decide to use SSL:

  • The protocol (ldap or ldaps) in the URI entry has to conform with the slapd configuration
  • If you decide to use self-signed certificates, add a TLS_REQCERT allow line to ldap.conf
  • If you use a signed certificate from a CA, add the line TLS_CACERTDIR /usr/share/ca-certificates/trust-source in ldap.conf.

Create initial entry

Once your client is configured, you probably want to create the root entry, and an entry for the root role:

$ ldapadd -x -D 'cn=root,dc=example,dc=com' -W
dn: dc=example,dc=com
objectClass: dcObject
objectClass: organization
dc: example
o: Example
description: Example directory

dn: cn=root,dc=example,dc=com
objectClass: organizationalRole
cn: root
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=*)'

Or authenticating as the rootdn (replacing -x by -D <user> -W), using the example configuration we had above:

$ ldapsearch -D "cn=root,dc=example,dc=com" -W '(objectclass=*)'

Now you should see some information about your database.

OpenLDAP over TLS

Note: upstream documentation is much more useful/complete than this section

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.

Warning: OpenLDAP cannot use a certificate that has a password associated to it.

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 daemon configuration file (/etc/openldap/slapd.conf) to tell LDAP where the certificate files reside by adding the following lines:

# Certificate/SSL Section
TLSCipherSuite DEFAULT
TLSCertificateFile /etc/openldap/ssl/slapdcert.pem
TLSCertificateKeyFile /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 ldap:

# Certificate/SSL Section
TLSCipherSuite DEFAULT
TLSCertificateFile /etc/letsencrypt/live/ldap.my-domain.com/cert.pem
TLSCertificateKeyFile /etc/letsencrypt/live/ldap.my-domain.com/privkey.pem
TLSCACertificateFile /etc/letsencrypt/live/ldap.my-domain.com/chain.pem
TLSCACertificatePath /usr/share/ca-certificates/trust-source

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. See man ciphers for description of ciphers, wildcards and options supported.

Note: To see which ciphers are supported by your local OpenSSL installation, type the following: 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'

Regenerate the configuration directory:

# rm -rf /etc/openldap/slapd.d/*                                  # erase old config settings
# slaptest -f /etc/openldap/slapd.conf -F /etc/openldap/slapd.d/  # generate new config directory from config file
# chown -R ldap:ldap /etc/openldap/slapd.d                        # Change ownership recursively to ldap on the config directory

Start slapd with SSL

You will have to edit slapd.service to change to 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:///"

Then restart slapd.service. If it was enabled before, reenable it now.

Note: If you created a self-signed certificate above, be sure to add TLS_REQCERT allow to /etc/openldap/ldap.conf on the client, or it will not be able connect to the server.

Next Steps

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.

Troubleshooting

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 ldap:ldap /var/lib/openldap/openldap-data/*

to allow slapd write access to its data directory as the user "ldap".

LDAP Server Doesn't 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

See Also