Why Is My OD LDAP Server Stopped & How To Fix It

I take care of several OS X mail servers for my customers and I always use the widely deployed OpenDirectory LDAP server for user management. However, from time to time one of these OD servers stops working. Based on my experience, there are two (and a half) main reasons for this malfunction:

1. Power outage: After a power outage the database got corrupted. (This is a valid reason for a service outage 😉
2. OD Backup: After creating an OpenDirectory backup the launchd org.openldap.slapd.plist configuration file is disabled. This means, that the LDAP server will not be started and all services (Mail, iCal, Address Book) stop working.
3. OD Backup^2: There is an even more serious OD Backup Bug. Thankfully I have seen it only once. If this bug is triggered, not only is the default org.openldap.slapd.plist configuration disabled but there is a second hidden dot-file temporary configuration file with the same launchd key. Thereby we trigger undefined behaviour (two configuration files with the same key) and no usable error message is logged! (It was quite hard to find this problem).

After finding and fixing the cause you still have to repair your OpenDirectory database. Use the following three easy steps to do so:

1. First you have to stop a possible running OD instance by unloading the launchd configuration:

   sudo launchctl unload /System/Library/LaunchDaemons/org.openldap.slapd.plist

2. Then run the db_recover utility with the following parameters to recover your OpenDirectory database:

   sudo db_recover -v -h /var/db/openldap/openldap-data/

3. And restart your OpenDirectory server:

   sudo launchctl load /System/Library/LaunchDaemons/org.openldap.slapd.plist

Voilà your OpenDirectory is working again and you have earned yourself another coffee 😉