Symas OpenLDAP Knowledge Base

Migrating BDB/HDB to MDB (slapd.conf)

Created by Greg Noe, last modified on Jun 16, 2016

Steps for migrating from BDB/HDB backends to MDB using static configuration (slapd.conf)

References

Configurable settings for MDB backend: slapd-mdb(5)

Configurable settings for BDB backend: slapd-bdb(5)

Slapd configuration reference: slapd.conf(5)

MDB configuration in OpenLDAP Admin Guide: Chapter 11.4

Notes

  • All operations performed in this guide must be performed as root or as a user with appropriate administrative privileges.
  • Backend database changes are invisible to the outside world. LDAP client connections and operations, including replication are unaffected by these changes.
  • Startup and shutdown of the slapd daemon/service varies by operating system. Linux/Unix: Generally /etc/init.d/solserver (stop|start|restart|status) or /opt/symas/etc/solserver (stop|start|restart|status) Windows: The “OpenLDAP-slapd” service can be controlled in the Services manager, PowerShell console or command window

VERIFY MDB BACKEND AVAILABILITY

The MDB backend is available from OpenLDAP version 2.4.34 forward.  The release notes in /opt/symas/etc will indicate the release level of the installation.

BACK UP AND COPY YOUR CURRENT CONFIGURATION

Make a backup copy of your current configuration, along with a second copy that will be used for modification.  The original slapd.conf file should remain in place until the new configuration is tested and put in place.

$ cp /opt/symas/etc/openldap/slapd.conf /opt/symas/etc/openldap/slapd.conf.bak
$ cp /opt/symas/etc/openldap/slapd.conf /opt/symas/etc/openldap/slapd.new.conf

CREATE THE NEW CONFIGURATION

GLOBAL CONFIGURATION

In the global configuration section of slapd.conf, add the back_mdb module to the existing group of moduleload items:  

Add MDB Module

moduleload back_mdb.la

Your slapd.conf may define multiple backend databases.  If this is the case, it is recommended that each database is migrated separately (slapd can handle multiple databases with different backends in one instance).  This helps avoid confusion and makes troubleshooting easier if something goes wrong. If no BDB/HDB backend databases are present on the server after migrating to MDB, remove the BDB/HDB moduleload items:

Remove BDB/HDB Module

moduleload back_bdb.la
moduleload back_hdb.la

DATABASE CONFIGURATION

REQUIRED SETTINGS

The four items in the following table are required for all MDB databases.  MDB backends do not require the same number of tuning parameters as BDB/HDB databases.  It is recommended that when migrating, start with these four settings and add other settings as needed.

Required MDB Per-Database Configuration Setting Action/Change To Notes database (bdb | hdb) Change to mdb   directory N/C Original BDB/HDB database directory may be reused index N/C Original BDB/HDB indexes do not need to be changed maxsize Add Projected maximum database size in bytes

OPTIONAL SETTINGS

The following settings are optional and under most circumstances, not needed.

Optional MDB Per-Database Configuration Setting Notes checkpoint See checkpoint in slapd-mdb man page dbnosync See dbnosync in slapd-mdb man page envflags See envflags in slapd-mdb man page maxreaders See maxreaders in slapd-mdb man page mode See mode in slapd-mdb man page searchstack See searchstack in slapd-mdb man page

BDB/HDB SETTINGS CLEANUP

Remove the following BDB/HDB related settings from the database configuration.  They are not used by the MDB backend, and their presence will prevent slapd from starting.

BDB/HDB Settings to Remove cachefree dirtyread cachesize dncachesize checksum idlcachesize cryptfile linearindex cryptkey lockdetect dbconfig shm_key dbpagesize  

When finished, save the new configuration file.

CONFIGURATION TESTING

Once the configuration changes have been made they need to be tested with the slaptest utility.  The slaptest utility may be run while an instance of slapd is running, so taking the server offline is not necessary for testing.

$> /opt/symas/bin/slaptest -f /opt/symas/etc/openldap/slapd.new.conf

If there are any issues with the new configuration, slaptest will display the problem and the line number of the problem in the configuration file.

If you see the following error message:

   slap_startup failed (test would succeed using the -u switch)

That means that the configuration test has succeeded, but the .mdb database files in the database directory are not present.  This is normal and you may proceed with the migration.

For any other error that comes from slaptest, please refer to the following:  slapd-mdb man page | slapd.conf man page | OpenLDAP 2.4 Admin Guide

DATABASE MIGRATION

With a successfully tested configuration, you’re now ready to migrate the database.

MIGRATION STEPS

  1. Export your current database with the slapcat utility.  If you have a single database on your server use:

    $ /opt/symas/bin/slapcat -f /opt/symas/etc/openldap/slapd.conf -l /tmp/mydb_export.ldif

    If you have multiple databases defined in your slapd.conf, repeat this for each database suffix defined:

    $ /opt/symas/bin/slapcat -f /opt/symas/etc/openldap/slapd.conf -b <suffix> -l /tmp/mydb_<suffix>_export.ldif

  2. Stop the slapd daemon/service

  3. Rename/move the current slapd.conf file:

    $ mv /opt/symas/etc/openldap/slapd.conf /opt/symas/etc/openldap/slapd.conf.out

  4. Rename/move the new slapd.new.conf file to slapd.conf:

    $> mv /opt/symas/etc/openldap/slapd.new.conf /opt/symas/etc/openldap/slapd.conf

  5. Import the ldif(s) created from step 1 with the slapadd utility.  Use the -q flag for faster imports:

    $ /opt/symas/bin/slapadd -q -f /opt/symas/etc/openldap/slapd.conf -l /tmp/mydb_export.ldif

  6. Start the slapd daemon/service 

  7. Test connections and searches

POST MIGRATION TASKS

When satisfied that the MDB backend is working properly, perform the following tasks:

  • Remove all old BDB/HDB files (DB_CONFIG, *.bdb, __db.nnn, alock) from your database directory
  • Archive the exported database .ldif files created in step one of the migration steps and the original slapd.conf file in case a database restoration is needed