Notes about Debian's slapd package ---------------------------------- Please see the bottom of this file for the ways in which the Debian OpenLDAP packages differ from the upstream OpenLDAP releases. Please report any bugs that may be related to those changes to Debian via reportbug and not to upstream; upstream is not responsible for changes made in the Debian package. In addition to the man pages shipped with this package, please consult the OpenLDAP Admin Guide for more information, including configuration examples for common use cases. Initial slapd configuration Upon installation the slapd package performs a number of tasks. It initializes the configuration database, stored in LDAP and rooted at the DN "cn=config". It creates an initial directory database with a DN rooted at a suffix derived from the DNS domain configured in debconf (e.g. "dc=example,dc=com"). The default backend for the directory database is the MDB backend. The root (administrative) DN is set to "cn=admin,". The root password is set to the password configured in debconf, or a randomly generated password if none was set. If desired, a new configuration and directory database can be created by running, as root: dpkg-reconfigure slapd Caution: this command completely resets the configuration and all LDAP directory data (saving a backup in /var/backups), resetting slapd to a new initial state. The configuration database ("cn=config") and directory database ("dc=,dc=") have different permissions. Upon installation, the Unix root user has permission to manage the slapd configuration ("cn=config") database. The LDAP directory manager ("cn=admin,") has permission to manage the directory database ("dc=,dc="). This policy is specific to Debian. Maintaining the slapd configuration Since version 2.4.23-3 the default configuration of OpenLDAP has been changed to "/etc/ldap/slapd.d"; configuration is stored in an LDAP directory. The OpenLDAP packages in Debian provide an automatic migration to the new configuration style. With the new configuration style it is possible to change values on the fly without restarting slapd. Changes are made through the use of ldif files and ldap{add,modify}. Debian defaults to granting the Unix root user, and only the Unix root user, administrative privileges to the configuration database. The configuration database is stored in LDAP. Administrative privileges to the configuration database are granted to root when the special SASL mechanism "EXTERNAL" is used for authentication. The OpenLDAP client command option for this is "-Y EXTERNAL". You can use the following shell command, as root, to search the configuration: ldapsearch -Y EXTERNAL -H ldapi:/// -b "cn=config" To modify configuration use the command: ldapmodify -Y EXTERNAL -H ldapi:/// -f For configuration options see the several manpages that exist or the documentation provided upstream. To change the directory administrator's password, the olcRootPW attribute of the database configuration must be updated. The new password should be hashed using the slappasswd(8) command. Then, the root user should update the attribute using ldapmodify(1): ldapmodify -H ldapi:// -Y EXTERNAL << EOF dn: olcDatabase={1}mdb,cn=config changetype: modify replace: olcRootPW olcRootPW: EOF Versions of slapd before 2.4.51+dfsg-1 additionally created a database entry named the same as the rootDN (cn=admin,) and having the same password. If this entry exists in your directory, its password must also be updated using ldappasswd(1), otherwise the old password can still be used. Using the MDB Backend MDB is a new database backend using the LMDB library created by the OpenLDAP developers. The MDB backend has fewer configuration parameters than the former Berkeley DB backend, and generally does not require hand tuning. The database is stored in a sparse file with a specified maximum size. The size should be set larger than the database is ever anticipated to grow, but can be increased later if needed. When the MDB backend is chosen during initial configuration, the Debian package configures the automatically created database with a maximum size of 1 GiB. The space currently used by the database can be found using du(1); for example: du -h /var/lib/ldap/data.mdb When upgrading slapd to a new version where the database's storage format has changed, the database has to be backed up using slapcat(8) before upgrading and restored using slapadd(8) afterwards. Normally the maintainer scripts will handle this automatically, performing the dump and restore as needed. If the database format changes without a corresponding dump and reload, this should be reported as a bug in the slapd package. In this case you will have to downgrade slapd to the previous version as the new tools are unable to dump the old database, and the same error would prevent you from upgrading to the fixed version. Old package versions can be found at if needed. Logging slapd logs to the facility local4. If you want to direct slapd's logs to a separate log file, add a line like: local4.debug /var/log/slapd.log to /etc/syslog.conf. You may also want to add ";local4.none" to the catch-all entry that logs to /var/log/messages so that it doesn't continue to receive slapd logs. SASL Configuration To enable GSSAPI (Kerberos) authentication to slapd, install either the libsasl2-modules-gssapi-mit or libsasl2-modules-gssapi-heimdal packages depending on which Kerberos implementation you want to use. SASL configuration files may be placed either in /usr/lib/sasl2 (the standard path, but not a great place for configuration files) or in /etc/ldap/sasl2. A SASL configuration file should be named after the program that will use it. So, for instance, to configure SASL for slapd, create a file named slapd.conf in /etc/ldap/sasl2 or in /usr/lib/sasl2. TCP Wrappers The Debian slapd package is compiled with TCP wrappers. This means that you are able to restrict access to the LDAP server using /etc/hosts.deny or /etc/hosts.allow. Running slapd under a Different UID/GID By default, slapd runs as openldap in the openldap group. Keeping the default is easiest. If for some reason you need to run slapd as a different user: - Create the user/group for slapd -- usually: adduser --system --group --disabled-login - Stop slapd: /etc/init.d/slapd stop - Tell slapd to run under a different UID by editing /etc/default/slapd and setting SLAPD_USER and SLAPD_GROUP. (For example, SLAPD_USER="ldap", SLAPD_GROUP="ldap") - Tell linux slapd can access all database files -- usually: chown -R : /var/lib/ldap - Tell linux slapd can access configuration files -- usually: chown -R : /etc/ldap/slapd.d - Tell linux slapd can access /var/run/slapd and write a PID file: chgrp /var/run/slapd chmod 0770 /var/run/slapd - Start slapd -- /etc/init.d/slapd start Once you have done so, remember to always run any utilities that access or update the database (such as slapadd) as the same user that slapd is running as. If you forget, you will need to redo the chown noted above. If slapd Depends on Other Service In the event that you are running slapd with a different back-end module that depends on other programs (such as an SQL database) you may need to adjust the runlevels of slapd to start after the SQL database. Creating NSS Flat Files from LDAP If you have need to create passwd/shadow/etc files from an LDAP directory there is now a script included with these Debian packages which may help you. The script is in /usr/share/slapd/ and is named ldiftopasswd. In general you should be able to do: ldapsearch | ldiftopasswd and it will generate the files for you. You will need appropriate privileges, of course, and appropriate arguments to ldapsearch. Modifications Compared to Upstream Compared to stock OpenLDAP as shipped by the OpenLDAP project, the Debian packages make the following modifications. If you see any problems caused by or related to these modifications, please report them via the Debian bug tracking system using reportbug, not to the OpenLDAP project. * The only LDAP library installed is libldap_r, which in the upstream release is only used for slapd, and libldap is a symlink to it. This library has thread safety for use with slapd, but that thread safety is not checked for any application other than slapd by upstream. Upstream does not support using libldap_r for programs other than slapd. The current library installation strategy in the Debian packages is an attempt to deal with problems caused by symbol conflicts between libldap and libldap_r when both are pulled in by the same process (most commonly by libnss-ldap) and the number of packages that use libldap in threaded code expecting thread safety. * libldap and libber have symbol versioning added to prevent problems during partial upgrades from older versions of the libraries. * slapindex has been patched to warn when run as root and the man page has been patched to notify users that slapindex should be run as the user slapd runs as. There is some upstream discussion of a better fix. * slapd is configured to look in /etc/ldap/sasl2 in addition to /usr/lib/sasl2 for SASL configuration files. * Several paths have been adjusted to fit Debian file permissions and for Filesystem Hierarchy Standard compliance, namely: - The ldapi socket is in /var/run/slapd - The slapi error log has been moved to /var/log/slapi-errors - The slapd database location is /var/lib/ldap In addition, upstream patches from CVS may be applied to fix bugs in the current release and will not be noted here unless they're not expected to be in the next release. Finally, note that the Debian OpenLDAP packages have been compiled against GnuTLS instead of OpenSSL to avoid licensing problems for GPL-covered packages that use the LDAP libraries. This is a supported configuration, but it's not widely used outside of Debian. For the exact patches applied to the upstream source and references to the relevant upstream ITS numbers, Debian bugs, and upstream synchronization status, see the debian/patches directory in the openldap source package. -- Russ Allbery , Thu, 14 Feb 2008 18:47:07 -0800 Migrating your installation to OpenLDAP 2.5.x OpenLDAP 2.5 is a major new release and includes several incompatible changes as described in the upstream ANNOUNCEMENT file. Depending on your configuration, completing the upgrade from 2.4.x might require manual intervention. The package upgrade process first exports your databases to LDIF format using slapcat(8), then updates the slapd package, and finally imports the LDIF files using slapadd(8). If the slapadd process fails, it must be completed manually after resolving whatever issues caused the failure. By default, the Debian package uses LDAP-based configuration (cn=config). To resolve configuration issues with a cn=config database, follow the steps below to reload the config database from an LDIF file. If you use a slapd.conf configuration file, configuration issues can be resolved by just editing that file. The following steps assume your configuration database is stored in the default location (/etc/ldap/slapd.d). 1. Locate the backup LDIF file exported by the upgrade process: /var/backups/slapd-/cn=config.ldif Make a copy of this file for working on. 2. Edit your copy of cn=config.ldif to fix the issues noted by slapadd, such as removed or renamed modules or backends. See below for suggestions for some specific issues. 3. Move away or delete the contents of /etc/ldap/slapd.d, so that it is an empty directory. 4. Load your edited cn=config.ldif into the cn=config database: slapadd -F/etc/ldap/slapd.d -n0 -l /var/backups/slapd-/cn=config.ldif 5. If the slapadd command failed, go back to step 2. 6. After the slapadd command succeeds, change the permissions on the slapd.d directory to be owned by the openldap user: chown -R openldap:openldap /etc/ldap/slapd.d Now you can proceed with reloading the remaining databases. For each configured database: 1. Locate the backup LDIF file exported by the upgrade process: /var/backups/slapd-/.ldif where is the database suffix such as dc=example,dc=com. 2. Ensure the directory where the database is stored (for example /var/lib/ldap) is empty. By default the upgrade process moves away the database files to a directory named /var/backups/-.ldapdb. 3. Reload the data using slapadd: slapadd -l /var/backups/slapd-/.ldif 4. Make sure the slapadd command succeeded, and then change the permissions on the data directory: chown -R openldap:openldap /var/lib/ldap After all of your databases have been reloaded successfully, you should be able to start the slapd service again. Known issues for OpenLDAP 2.5.x upgrades * BDB/HDB backends removed: migrating to LMDB backend The slapd-bdb(5) and slapd-hdb(5) backends have been removed. These were configured by default in older versions of the slapd package. If you are still using one of these backends, slapadd fails with the following message: lt_dlopenext failed: (back_hdb) file not found You have to change to the LMDB backend. Edit the exported configuration LDIF as described above, and make the following changes: 1. Change olcModuleLoad: back_bdb or back_hdb to back_mdb. 2. If you have an olcBackend: bdb or hdb entry, change it to mdb, or delete it if you don't have to override any global LMDB settings. 2. For each configured BDB or HDB database: - Change objectClass: olcBdbConfig or olcHdbConfig to olcMdbConfig. Also update structuralObjectClass. - Change olcDatabase: bdb or hdb to mdb. Also update the attribute in the DN, for example: olcDatabase={1}mdb,cn=config. - Delete any olcDbConfig attributes. - Add the olcDbMaxSize attribute to set the maximum size of the database, in bytes. If not configured, the default is 10 MiB. * ppolicy schema changed to internal The slapo-ppolicy(5) module now includes its schema compiled into the module code itself. The external schema is no longer used, and conflicts with the internal copy. If you have the ppolicy schema loaded, slapadd fails with the following message: olcAttributeTypes: value #0 olcAttributeTypes: Duplicate attributeType: "1.3.6.1.4.1.42.2.27.8.1.1" Edit the exported configuration LDIF as described above. Remove the entire ppolicy schema entry. That is, delete from the line like: dn: cn={4}ppolicy,cn=schema,cn=config all the way to the next blank line. * argon2 module renamed The pw-argon2 contrib passwd module was promoted to core and was renamed to argon2. If your config loads the module by its old name, slapadd fails with the following message: lt_dlopenext failed: (pw-argon2) file not found Edit the exported configuration LDIF as described above. Change olcModuleLoad: pw-argon2 to argon2. -- Ryan Tandy Sat, 14 Aug 2021 15:03:31 -0700