Migrating BDB/HDB to MDB (cn=config)

DOCUMENT CONVERSION TASKS:

2. BACK UP AND COPY YOUR CURRENT CONFIGURATION 
3. LOAD THE MDB BACKEND MODULE
4. DATABASE CONFIGURATION
   • REQUIRED SETTINGS
   • OPTIONAL SETTINGS
5. BDB/HDB SETTINGS CLEANUP
6. CONFIGURATION TESTING
7. DATABASE MIGRATION
   • MIGRATION STEPS
   • POST MIGRATION TASKS
8. References

BACK UP AND COPY YOUR CURRENT CONFIGURATION 

Using the slapcat utility, make a backup copy of your current configuration database (cn=config). Create a second copy to be used for modification.  Archive the original cn-config-backup.ldif and keep on hand in case it becomes necessary to revert to the old configuration.

/opt/symas/etc/openldap> slapcat -n0 -F /opt/symas/etc/openldap/slapd.d -l cn-config-backup.ldif
cp cn-config-backup.ldif cn-config-new.ldif

LOAD THE MDB BACKEND MODULE

Create an ldif file named “Add_MDB_Module.ldif” with the following content:

Add_MDB_Module.ldif

dn: cn=module{0},cn=config
changetype: modify
add: olcModuleLoad
olcModuleLoad: back_mdb.la
-

Add the MDB module to the list of modules to load in the cn=module{0},cn=config with the ldapmodify command (do a dry run with the “-n” parameter first):

/opt/symas/etc/openldap> ldapmodify -H ldap://localhost:389/ -x -D cn=config -W -f Add_MDB_Module.ldif

Check the module list in cn=config to verify the MDB backend module was successfully added:

Verify MDB backend module addition

/opt/symas/etc/openldap> ldapsearch -H ldap://localhost:389/ -D cn=config -W -s sub -LLL -b "cn=module{0},cn=config" olcModuleLoad
Enter LDAP Password:
dn: cn=module{0},cn=config
olcModuleLoad: {0}back_hdb.la
olcModuleLoad: {1}back_monitor.la
olcModuleLoad: {2}back_mdb.la

Notice the back_hdb.la module is still in the list of modules to be loaded.  It’s presence will not cause any issues and will be removed from the configuration later in the procedure. 

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

OPTIONAL SETTINGS

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

Optional MDB Per-Database Configuration

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

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 and 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.

OpenLDAP Configuration References

OpenLDAP Admin Guide: slapd configuration (cn=config): [[Chapter 5|http://www.openldap.org/doc/admin24/slapdconf2]]

OpenLDAP Admin Guide: MDB backend configuration: Chapter 11.4

Man page: MDB backend: slapd-mdb(5)

Man page: BDB backend: slapd-bdb(5)

Man page: Dynamic configuration (cn=config): slapd-config(5)

Notes

• All commands in this guide assume that /opt/symas/bin or %PROGRAM ROOT%\symas-openldap are included in your command shell’s path.
• All operations performed in this guide must be performed as root or as a user with appropriate administrative privileges.
• All ladpadd/ldapmodify operations performed in this guide use the “-W” parameter which prompts for the rootpw for the rootDN being used to bind for the command. This is done in preference to “-w” which allows the rootpw to be included in the command and execute without a prompt, but also gets stored in your command shell’s history.
• Never directly edit the .ldif configuration files in the /opt/symas/etc/openldap/slapd.d directory. Configuration edits must be done with the ldapadd/ldapmodify utility, a graphical directory editor such as Apache Directory Studio or in some cases by editing a backup of cn=config taken with the slapcat utility and re-importing with the slapadd utility.
• Backend database changes are invisible to the outside world. LDAP client connections and operations, including replication are unaffected by these changes.
• When working with ldif files, make sure to remove all trailing spaces from each line and have an empty line between each operation.
• When executing updates to cn=config with the slapadd and ldapadd/ldapmodify utilities, it is recommended to do a dry run of each update before an actual update. The dry run will alert you to issues with the syntax of your .ldif or of any conflicts your modifications may have. To do a dry run with slapadd, add the “-u” parameter to the command. To do a dry run with ldapadd/ldapmodify, add the “-n” parameter to the command.