OpenLDAP: Difference between revisions

From ArchWiki
VisualWikitext
(update zh-cn/tw interlanguage links to zh-hans/hant, see Help talk:I18n#Chinese interlanguage links)
m (Add <nowiki> to fix template issue)
 
(85 intermediate revisions by 28 users not shown)
Line 1: Line 1:
[[Category:Networking]]
[[Category:Directory services]]
[[ja:openLDAP]]
[[ja:openLDAP]]
[[ru:OpenLDAP]]
[[zh-hans:OpenLDAP]]
{{Related articles start}}
{{Related articles start}}
{{Related|LDAP Authentication}}
{{Related|LDAP authentication}}
{{Related|LDAP Hosts}}
{{Related|LDAP Hosts}}
{{Related articles end}}
{{Related articles end}}


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.
[https://www.openldap.org/ 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.


{{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.}}
{{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.}}


This page is a starting point for a basic OpenLDAP installation and a sanity check.
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.}}
{{Tip|Directory services are an enormous topic. Configuration can therefore be complex. If you are totally new to those concepts, [https://www.brennan.id.au/20-Shared_Address_Book_LDAP.html this] is a good introduction that is easy to understand and that will get you started, even if you are new to LDAP.}}


== Installation ==
== Installation ==
Line 24: Line 22:
=== The server ===
=== The server ===


{{Note|If you already have an OpenLDAP database on your machine, remove it by deleting everything inside {{ic|/var/lib/openldap/openldap-data/}}.}}
{{Note|
* If you have an obsolete {{ic|slapd.conf}} configuration, you can simply convert it into the new {{ic|1=cn=config}} database using
$ slaptest -f /etc/openldap/slapd.conf -F /etc/openldap/slapd.d/
* If you already have an OpenLDAP database on your machine and would like to remove it, then it can be removed by deleting everything inside of {{ic|/var/lib/openldap/openldap-data/}}. So, backup your {{ic|DB_CONFIG}}.
}}
 
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 the directory {{ic|/var/lib/openldap/openldap-data/}}, where your LDAP database contents ("database 1", as OpenLDAP calls it):
 
# install -m 0700 -o ldap -g ldap -d /var/lib/openldap/openldap-data/


The server configuration file is located at {{ic|/etc/openldap/slapd.conf}}.
Now we need to create a place for the LDAP configuration database ("database 0"):


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).
# install -m 0670 -o root -g ldap -d /etc/openldap/slapd.d
{{bc|<nowiki>
suffix    "dc=example,dc=com"
rootdn    "cn=root,dc=example,dc=com"
</nowiki>}}


Now we delete the default root password and create a strong one:
Create a file {{ic|/etc/openldap/config.ldif}} containing the following minimal useful configuration:
# 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 [http://www.openldap.org/doc/admin24/schema.html schemas] to the top of {{ic|slapd.conf}}:
{{hc|/etc/openldap/config.ldif|2=
# The root config entry
dn: cn=config
objectClass: olcGlobal
cn: config
olcArgsFile: /run/openldap/slapd.args
olcPidFile: /run/openldap/slapd.pid


{{Note|currently missing:  
# Schemas
cp /usr/share/doc/samba/examples/LDAP/samba.schema /etc/openldap/schema}}
dn: cn=schema,cn=config
objectClass: olcSchemaConfig
cn: schema


{{bc|
# TODO: Include further schemas as necessary
include         /etc/openldap/schema/cosine.schema
include: file:///etc/openldap/schema/core.ldif
include        /etc/openldap/schema/inetorgperson.schema
 
include        /etc/openldap/schema/nis.schema
# The config database
#include        /etc/openldap/schema/samba.schema
dn: olcDatabase=config,cn=config
}}
objectClass: olcDatabaseConfig
olcDatabase: config
olcRootDN: cn=Manager,'''$BASEDN'''


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}}:
# The database for our entries
{{bc|
dn: olcDatabase=mdb,cn=config
index  uid            pres,eq
objectClass: olcDatabaseConfig
index  mail            pres,sub,eq
objectClass: olcMdbConfig
index  cn             pres,sub,eq
olcDatabase: mdb
index  sn              pres,sub,eq
olcSuffix: '''$BASEDN'''
index  dc              eq
olcRootDN: cn=Manager,'''$BASEDN'''
olcRootPW: '''$PASSWD'''
olcDbDirectory: /var/lib/openldap/openldap-data
# TODO: Create further indexes
olcDbIndex: objectClass eq
}}
}}


Now prepare the database directory. You will need to rename the default config:
There are a few options you will need to change:
# mv /var/lib/openldap/openldap-data/DB_CONFIG.example /var/lib/openldap/openldap-data/DB_CONFIG


{{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/}}.}}
* Every occurence of {{ic|$BASEDN}} must be replaced with a valid DN. If you own a domain {{ic|example.com}} you will most likely want to choose {{ic|1=dc=example,dc=com}}.
* {{ic|$PASSWD}} must be replaced by a salted and hashed password, which you may generate by running {{ic|slappasswd}}.


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:
Additionally, you might consider to add further [https://www.openldap.org/doc/admin24/schema.html schemas] and create additional [https://www.openldap.org/doc/admin24/tuning.html#Indexes indexes] to tune the performance of your database. The specifics will depend on your use case, but here are a few recommendations. For [[LDAP authentication]], you should include the three schemas below to be able to use the {{ic|posixAccount}} object class used for storing users.


# rm -rf /etc/openldap/slapd.d/*
{{Note|Additional indexes must be part of the preceeding block. Newlines will result in a corrupted configuration file}}


{{bc|1=
(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]] )
# TODO: Create further indexes
olcDbIndex: objectClass eq
olcDbIndex: uid pres,eq
olcDbIndex: mail pres,sub,eq
olcDbIndex: cn,sn pres,sub,eq
olcDbIndex: dc eq


Then we generate the new configuration with:
# Additional schemas
# RFC1274: Cosine and Internet X.500 schema
include: file:///etc/openldap/schema/cosine.ldif
# RFC2307: An Approach for Using LDAP as a Network Information Service
# Check RFC2307bis for nested groups and an auxiliary posixGroup objectClass (way easier)
include: file:///etc/openldap/schema/nis.ldif
# RFC2798: Internet Organizational Person
include: file:///etc/openldap/schema/inetorgperson.ldif


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


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".
Allow logins to the {{ic|ldap}} user account with {{ic|chsh}}, typically selecting the shell {{ic|/bin/bash}}. Then import these settings as the {{ic|ldap}} user:


Change ownership recursively on the new files and directory in /etc/openldap/slapd.d:
[ldap]$ slapadd -n 0 -F /etc/openldap/slapd.d/ -l /etc/openldap/config.ldif


# chown -R ldap:ldap /etc/openldap/slapd.d
Alternatively, you may also run this directly as {{ic|root}}. However, if you do, make sure {{ic|/etc/openldap/slapd.d/}} remains accessible by {{ic|ldap}}:


# slapadd -n 0 -F /etc/openldap/slapd.d/ -l /etc/openldap/config.ldif
# chown -R ldap:ldap /etc/openldap/*


{{note|Index the directory after you populate it. You should stop slapd before doing this.
If everything worked, you will now have directories underneath {{ic|/etc/openldap/slapd.d}} with names such as {{ic|<nowiki>cn=config</nowiki>}}.
# slapindex
# chown ldap:ldap /var/lib/openldap/openldap-data/*


or just
By default, OpenLDAP will listen unencrypted on all interfaces. To make it only listen on local IP interfaces, you may edit the environment file read by {{ic|slapd.service}}:


$ sudo -u ldap slapindex
{{hc|/etc/conf.d/slapd|2=
SLAPD_URLS="ldap://127.0.0.1/ ldap://[::1]"
SLAPD_OPTIONS=
}}
}}


Finally, start the slapd daemon with {{ic|slapd.service}} using systemd.
Finally, start the ''slapd'' daemon by [[start]]ing {{ic|slapd.service}}.
 
{{Note|
* If you want to have your directory accept requests from the network, you should consider using TLS. See [[#OpenLDAP over TLS]] for details.
* If you plan to use your LDAP server for authentication, you might want to check access control configuration in [[LDAP authentication#LDAP server setup]].
* Berkeley DB (BDB) should no longer be used. The mdb backend to {{man|8|slapd}} is the recommended primary backend for a normal ''slapd'' database. It uses OpenLDAP's own Lightning Memory-Mapped Database (LMDB) library to store data and is intended to replace the Berkeley DB backend. The OpenLDAP package in the [[official repositories]] defaults to mdb.}}


=== The client ===
=== The client ===
The client config file is located at {{ic|/etc/openldap/ldap.conf}}.  
 
The client configuration file is located at {{ic|/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 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:
Line 106: Line 142:


* The protocol (ldap or ldaps) in the {{ic|URI}} entry has to conform with the slapd configuration
* 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 decide to use TLS, 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}}.
* 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 ===
=== 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
{{Note|If you plan to use your LDAP server for authentication, you should import the {{ic|base.ldif}} in the [[LDAP authentication#Populate LDAP tree with base data|LDAP authentication]] article instead of following the instructions here.}}
dn: dc=example,dc=com
 
objectClass: dcObject
Once your client is configured, you probably want to create the root entry, and an entry for the Manager role:
objectClass: organization
 
dc: example
{{bc|1=
o: Example
$ ldapadd -x -D 'cn=Manager,dc=example,dc=com' -W
description: Example directory
dn: dc=example,dc=com
objectClass: dcObject
dn: cn=root,dc=example,dc=com
objectClass: organization
objectClass: organizationalRole
dc: example
cn: root
o: Example
description: Directory Manager
description: Example directory
^D
 
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.
The text after the first line is entered on stdin, or could be read from a file either with the {{ic|-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 '(objectclass=*)'


Or authenticating as the rootdn (replacing {{ic|-x}} by {{ic|-D <user> -W}}), using the example configuration we had above:
$ ldapsearch -x '(objectclass=*)' -b 'dc=example,dc=com'
  $ ldapsearch -D "cn=root,dc=example,dc=com" -W '(objectclass=*)'
 
Or authenticating as the rootdn (replacing {{ic|-x}} by {{ic|-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.
Now you should see some information about your database.


=== OpenLDAP over TLS ===
=== OpenLDAP over TLS ===
{{Note|[http://www.openldap.org/doc/admin24/ upstream documentation] is much more useful/complete than this section}}
 
{{Note|[https://www.openldap.org/doc/ 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.
Line 148: Line 192:


==== 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:
  $ 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/}} (create this directory if it does not exist) 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. {{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:
{{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:
 
  # mv slapdcert.pem slapdkey.pem /etc/openldap/ssl/
  # mv slapdcert.pem slapdkey.pem /etc/openldap/ssl/
  # chmod -R 755 /etc/openldap/ssl/
  # chmod -R 755 /etc/openldap/ssl/
Line 162: Line 208:


==== Configure slapd for SSL ====
==== Configure slapd for SSL ====
Edit the daemon configuration file ({{ic|/etc/openldap/slapd.conf}}) to tell LDAP where the certificate files reside by adding the following lines:
 
{{bc|
Edit the configuration to tell LDAP where the certificate files reside by executing the following command:
# Certificate/SSL Section
 
TLSCipherSuite DEFAULT
{{Note|The latest version of OpenLDAP (2.4.45) uses OpenSSL and <u>not</u> GnuTLS. This means that current versions of OpenLDAP '''do''' in fact know how to handle the [https://www.openssl.org/docs/man1.1.1/man1/ciphers.html#CIPHER-STRINGS DEFAULT TLSCipherSuite]. To prove this one could run {{ic|ldd /usr/bin/slapd}}.}}
TLSCertificateFile /etc/openldap/ssl/slapdcert.pem
 
TLSCertificateKeyFile /etc/openldap/ssl/slapdkey.pem
{{hc|1=ldapmodify -D 'cn=Manager,dc=example,dc=com' -W|2=
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 {{ic|.pem}} files and intermediary directories to make them readable to the user {{ic|ldap}}:
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 {{ic|ldap}}:
{{bc|
 
# Certificate/SSL Section
{{hc|1=ldapmodify -D 'cn=Manager,dc=example,dc=com' -W|2=
TLSCipherSuite DEFAULT
dn: cn=config
TLSCertificateFile /etc/letsencrypt/live/ldap.my-domain.com/cert.pem
add: olcTLSCACertificateFile
TLSCertificateKeyFile /etc/letsencrypt/live/ldap.my-domain.com/privkey.pem
olcTLSCACertificateFile: /etc/letsencrypt/live/ldap.my-domain.com/chain.pem
TLSCACertificateFile /etc/letsencrypt/live/ldap.my-domain.com/chain.pem
-
TLSCACertificatePath /usr/share/ca-certificates/trust-source
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
}}
}}


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.
'''SSLv2/v3'''


{{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'}} }}
Disable SSLv2/v3 and use strong ciphers.


Regenerate the configuration directory:
{{hc|1=ldapmodify -D 'cn=Manager,dc=example,dc=com' -W|2=
# rm -rf /etc/openldap/slapd.d/*                                  # erase old config settings
dn: cn=config
# slaptest -f /etc/openldap/slapd.conf -F /etc/openldap/slapd.d/  # generate new config directory from config file
add: olcTLSProtocolMin
# chown -R ldap:ldap /etc/openldap/slapd.d                        # Change ownership recursively to ldap on the config directory
olcTLSProtocolMin: 3.3
-
add: olcTLSCipherSuite
olcTLSCipherSuite: DEFAULT:!kRSA:!kDHE
-
}}
 
TLSProtocolMin specifies the minimum version in wire format, so "3.3" actually means TLSv1.2.
 
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|1ssl|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'}}.}}


==== Start slapd with SSL ====
==== Start slapd with SSL ====
You will have to edit {{ic|slapd.service}} to change to protocol slapd listens on.


Create the override unit:
{{Note|This is not needed for StartTLS which listens on the same port as unencrypted LDAP.}}
{{hc|systemctl edit slapd.service|<nowiki>
 
[Service]
You will have to edit the environment file read by {{ic|slapd.service}} to change the protocol ''slapd'' listens on:
ExecStart=
 
ExecStart=/usr/bin/slapd -u ldap -g ldap -h "ldaps:///"</nowiki>}}
{{hc|/etc/conf.d/slapd|2=
SLAPD_URLS="ldaps:///"
SLAPD_OPTIONS=
}}
 
Localhost connections do not need to use SSL. So, if you want to access the server locally you should change the {{ic|SLAPD_URLS}} line to:


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:
  SLAPD_URLS="ldap://127.0.0.1 ldaps:///"
  ExecStart=/usr/bin/slapd -u ldap -g ldap -h "ldap://127.0.0.1 ldaps:///"


Then [[restart]] {{ic|slapd.service}}. If it was enabled before, reenable it now.
Then [[restart]] {{ic|slapd.service}}. If it was enabled before, reenable it now.
Line 205: Line 278:
{{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.}}
{{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 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).
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).
Line 212: Line 285:


A nice web frontend is [[phpLDAPadmin]].
A nice web frontend is [[phpLDAPadmin]].
=== Backup LDAP ===
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.
==== Export configuration ====
[ldap]$ slapcat -vF /etc/openldap/slapd.d -n 0 -l "$(hostname)-ldap-mdb-config-$(date '+%F').ldif"
==== Export database ====
[ldap]$ slapcat -v -n 1 -l "$(hostname)-ldap-database-$(date '+%F').ldif"
=== Restore LDAP ===
==== Import configuration ====
[ldap]$ slapadd -v -n 0 -F /etc/openldap/slapd.d -l ''<filename from config export>''
==== Import database ====
[ldap]$ slapadd -v -n 1 -F /etc/openldap/slapd.d -l ''<filename from database export>''


== Troubleshooting ==
== Troubleshooting ==


=== Client Authentication Checking ===
=== slapd configuration checking ===
If you cannot connect to your server for non-secure authentication
 
You can check configuration 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
  $ ldapsearch -x -H ldap://ldaservername:389 -D cn=Manager,dc=example,dc=exampledomain
Line 224: Line 326:
  $ ldapsearch -x -H ldaps://ldaservername:636 -D cn=Manager,dc=example,dc=exampledomain
  $ ldapsearch -x -H ldaps://ldaservername:636 -D cn=Manager,dc=example,dc=exampledomain


=== LDAP Server Stops Suddenly ===
=== LDAP server stops suddenly ===


If you notice that slapd seems to start but then stops, try running:
If you notice that ''slapd'' seems to start but then stops, try running:


  # chown ldap:ldap /var/lib/openldap/openldap-data/*
  # chown -R ldap:ldap /var/lib/openldap


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 ===
=== LDAP server does not start ===


Try starting the server from the command line with debugging output enabled:
Try starting the server from the command line with debugging output enabled:
Line 238: Line 340:
  # slapd -u ldap -g ldap -h ldaps://ldaservername:636 -d Config,Stats
  # slapd -u ldap -g ldap -h ldaps://ldaservername:636 -d Config,Stats


== See Also ==
== See also ==
* [http://www.openldap.org/doc/admin24/ Official OpenLDAP Software 2.4 Administrator's Guide]
 
* [https://www.openldap.org/doc/ Official OpenLDAP Software Administrator's Guide]
* [[phpLDAPadmin]] is a web interface tool in the style of phpMyAdmin.
* [[phpLDAPadmin]] is a web interface tool in the style of phpMyAdmin.
* [[LDAP authentication]]
* [[LDAP authentication]]
* {{AUR|apachedirectorystudio}} from the [[Arch User Repository]] is an Eclipse-based LDAP viewer. Works perfect with OpenLDAP installations.
* {{AUR|apachedirectorystudio}} from the [[Arch User Repository]] is an Eclipse-based LDAP viewer. Works perfect with OpenLDAP installations.

Latest revision as of 10:08, 12 April 2024

Related articles

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 a good introduction that is easy to understand and that will get you started, even if you are new to LDAP.

Installation

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

Configuration

The server

Note:
  • If you have an obsolete slapd.conf configuration, you can simply convert it into the new cn=config database using
$ slaptest -f /etc/openldap/slapd.conf -F /etc/openldap/slapd.d/
  • If you already have an OpenLDAP database on your machine and would like to remove it, then it can be removed by deleting everything inside of /var/lib/openldap/openldap-data/. So, backup your DB_CONFIG.

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 the directory /var/lib/openldap/openldap-data/, where your LDAP database contents ("database 1", as OpenLDAP calls it): 

# install -m 0700 -o ldap -g ldap -d /var/lib/openldap/openldap-data/

Now we need to create a place for the LDAP configuration database ("database 0"): 

# install -m 0670 -o root -g ldap -d /etc/openldap/slapd.d

Create a file /etc/openldap/config.ldif containing the following minimal useful configuration: 

/etc/openldap/config.ldif
# 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 $BASEDN must be replaced with a valid DN. If you own a domain example.com you will most likely want to choose dc=example,dc=com.
  • $PASSWD must be replaced by a salted and hashed password, which you may generate by running slappasswd.

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. For LDAP authentication, you should include the three schemas below to be able to use the posixAccount object class used for storing users.

Note: Additional indexes must be part of the preceeding block. Newlines will result in a corrupted configuration file
# TODO: Create further indexes
olcDbIndex: objectClass eq
olcDbIndex: uid pres,eq
olcDbIndex: mail pres,sub,eq
olcDbIndex: cn,sn pres,sub,eq
olcDbIndex: dc eq

# Additional schemas
# RFC1274: Cosine and Internet X.500 schema
include: file:///etc/openldap/schema/cosine.ldif
# RFC2307: An Approach for Using LDAP as a Network Information Service
# Check RFC2307bis for nested groups and an auxiliary posixGroup objectClass (way easier)
include: file:///etc/openldap/schema/nis.ldif
# RFC2798: Internet Organizational Person
include: file:///etc/openldap/schema/inetorgperson.ldif

Allow logins to the ldap user account with chsh, typically selecting the shell /bin/bash. Then import these settings as the ldap user: 

[ldap]$ slapadd -n 0 -F /etc/openldap/slapd.d/ -l /etc/openldap/config.ldif

Alternatively, you may also run this directly as root. However, if you do, make sure /etc/openldap/slapd.d/ remains accessible by ldap: 

# slapadd -n 0 -F /etc/openldap/slapd.d/ -l /etc/openldap/config.ldif
# chown -R ldap:ldap /etc/openldap/*

If everything worked, you will now have directories underneath /etc/openldap/slapd.d with names such as cn=config.

By default, OpenLDAP will listen unencrypted on all interfaces. To make it only listen on local IP interfaces, you may edit the environment file read by slapd.service: 

/etc/conf.d/slapd
SLAPD_URLS="ldap://127.0.0.1/ ldap://[::1]"
SLAPD_OPTIONS=

Finally, start the slapd daemon by starting slapd.service.

Note:
  • If you want to have your directory accept requests from the network, you should consider using TLS. See #OpenLDAP over TLS for details.
  • If you plan to use your LDAP server for authentication, you might want to check access control configuration in LDAP authentication#LDAP server setup.
  • Berkeley DB (BDB) should no longer be used. The mdb backend to slapd(8) is the recommended primary backend for a normal slapd database. It uses OpenLDAP's own Lightning Memory-Mapped Database (LMDB) library to store data and is intended to replace the Berkeley DB backend. The OpenLDAP package in the official repositories defaults to mdb.

The client

The client configuration 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 TLS, 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

Note: If you plan to use your LDAP server for authentication, you should import the base.ldif in the LDAP authentication article instead of following the instructions here.

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 -x by -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

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 configuration to tell LDAP where the certificate files reside by executing the following command:

Note: The latest version of OpenLDAP (2.4.45) uses OpenSSL and not GnuTLS. This means that current versions of OpenLDAP do in fact know how to handle the DEFAULT TLSCipherSuite. To prove this one could run ldd /usr/bin/slapd.
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 ldap: 

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

SSLv2/v3

Disable SSLv2/v3 and use strong ciphers. 

ldapmodify -D 'cn=Manager,dc=example,dc=com' -W
dn: cn=config
add: olcTLSProtocolMin
olcTLSProtocolMin: 3.3
-
add: olcTLSCipherSuite
olcTLSCipherSuite: DEFAULT:!kRSA:!kDHE
-

TLSProtocolMin specifies the minimum version in wire format, so "3.3" actually means TLSv1.2.

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 ciphers(1ssl) 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'.

Start slapd with SSL

Note: This is not needed for StartTLS which listens on the same port as unencrypted LDAP.

You will have to edit the environment file read by slapd.service to change the protocol slapd listens on: 

/etc/conf.d/slapd
SLAPD_URLS="ldaps:///"
SLAPD_OPTIONS=

Localhost connections do not need to use SSL. So, if you want to access the server locally you should change the SLAPD_URLS line to: 

SLAPD_URLS="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.

Backup LDAP

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.

Export configuration

[ldap]$ slapcat -vF /etc/openldap/slapd.d -n 0 -l "$(hostname)-ldap-mdb-config-$(date '+%F').ldif"

Export database

[ldap]$ slapcat -v -n 1 -l "$(hostname)-ldap-database-$(date '+%F').ldif"

Restore LDAP

Import configuration

[ldap]$ slapadd -v -n 0 -F /etc/openldap/slapd.d -l <filename from config export>

Import database

[ldap]$ slapadd -v -n 1 -F /etc/openldap/slapd.d -l <filename from database export>

Troubleshooting

slapd configuration checking

You can check configuration 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

See also

Retrieved from "https://wiki.archlinux.org/index.php?title=OpenLDAP&oldid=805757"