How to Back Up and Restore OpenLDAP

Back up and restore OpenLDAP data and configuration with consistent snapshots, appropriate tools, verification, and a tested recovery sequence.

Type
Tutorial
Level
Advanced
Technologies
OpenLDAP, LDAP
On this page

Why OpenLDAP Backup and Restore Requires Precision

Backing up OpenLDAP is deceptively complex: incomplete or incorrect procedures can leave your directory unusable, unrecoverable, or running under a misconfigured state. It is not enough to back up only user and group entries (“the data DIT”); all runtime configuration—such as overlays, access controls, module settings, and even schemas—lives in the cn=config tree. Missing a backup of this configuration database renders a full recovery impossible or causes slapd to start in a default or broken state, even if user data is present.

Risks often stem from misunderstanding where OpenLDAP stores data and configuration. For example, copying only database files or exporting just the main data tree without preserving cn=config may result in a directory that refuses to load modules, apply custom ACLs, or even accept connections. Simply copying database files at the filesystem level, outside supported tools, risks data corruption and subtle consistency errors, as these files can be written to during regular LDAP operations. Skipping validated, official backup and restore procedures can turn routine maintenance into full outage, with lost or unrecoverable data.

Backup Methods: slapcat (LDIF) vs. mdb_copy (LMDB Binary)

OpenLDAP provides two official backup strategies:

  • slapcat (LDIF export): This tool generates a complete LDIF dump from a given database directory, creating a human-readable export suitable for migration, archival, or disaster recovery. The resulting LDIF can be reimported using slapadd.
  • mdb_copy (LMDB binary copy): For installations using the back-mdb database backend, mdb_copy allows you to take a direct, binary-level backup of the LMDB data file. This is significantly faster on large, high-throughput directories and ensures snapshot consistency, especially during heavy writes.

When should you use one over the other?

  • Use slapcat when: You prioritize portability and human readability, require migration across OpenLDAP versions or platforms, or need to backup configuration as well as data using a unified, text-based approach. slapcat can generally run with slapd online, though some risk of inconsistency exists if heavy writes are happening.
  • Use mdb_copy when: Your directory is large, under frequent transaction load, or you need a point-in-time, atomically consistent backup. mdb_copy is safe for use even while slapd is online and avoids the subtle risks inherent in direct filesystem copying. However, mdb_copy produces binary outputs which are only usable with the same backend (and generally the same OpenLDAP version).

Direct file copying of LMDB (or other backend) files is explicitly unsupported and dangerous unless slapd is stopped and you follow official procedures. This approach risks open file handles, partial data, and irrecoverable corruption.

Backing Up: What Must be Saved (Data and cn=config)

A restorable OpenLDAP backup consists of both:

  • The data DIT (typically database 1): This includes all user, group, and application objects.
  • The configuration DIT (cn=config, usually database 0): This subtree contains every slapd tunable—modules, backends, password policies, overlays, schemas, and access controls.

You must locate each database in your configuration and perform a backup for both. Skipping either—particularly cn=config—means your restore will lack critical context, settings will be lost, and slapd may not function as before. A common scenario: restoring only data but not cn=config may result in a server unable to enforce previous security controls or interpret schema.

Operating slapcat and mdb_copy: Real-World Considerations

slapcat can generally be run against a live slapd server using the back-mdb backend. However, if the server is under active use—with frequent writes, deletes, or multi-step LDAP transactions—there is risk of producing an inconsistent backup: operations crossing slapcat's snapshot window may be only partially reflected. For best reliability, perform backups during quiet periods, or set the server to read-only during backup.

mdb_copy avoids most of these issues. For LMDB backends, it duplicates the data file with transactional atomicity, guaranteeing a consistent snapshot even during active writes. It is indifferent to slapd’s running state and outperforms slapcat on very large datasets.

Both methods require awareness of filesystem behaviors—especially with sparse files (mdb_copy may produce them, depending on flags and filesystem). Transfers may need adjustment to handle these efficiently.

Direct copying of database files using operating system tools (e.g., cp, rsync) while slapd is running is not supported and can result in backups that are unrecoverable or silently corrupted. Only mdb_copy (for LMDB) or slapcat should be relied upon.

Restoration: Reliable, Supported Procedures

Restoring OpenLDAP is destructive and order-dependent. Official documentation highlights this sequence:

  1. Stop slapd completely to prevent file access or locking issues.
  2. Restore cn=config first. Without the original configuration, slapd cannot interpret or import the data DIT. Use slapadd with the LDIF export for cn=config, or restore the LMDB binary copied file to the configuration database directory.
  3. Restore data DIT(s). Only after cn=config is in place should you import user and group data. Use slapadd or restore the corresponding binary.
  4. Set correct file ownership and permissions so slapd can access its directory and files (the official documentation stresses this point).
  5. Start slapd, monitor logs, and explicitly validate that all objects, access controls, and overlays load as expected.

A common pitfall is restoring data DIT before configuration: slapd may initialize with defaults, misinterpret data, or reject objects using custom schema, breaking directory functionality.

Always remember, restoration overwrites any existing state—backup the current system before restoring if possible.

Replicated Topologies and Advanced Scenarios

Backup and restore procedures for replicated environments (like multi-master or MirrorMode clusters) require extra caution. Each LDAP server in such a topology tracks internal state (e.g., contextCSN, serverID) to maintain data convergence and conflict avoidance.

Restoring a backup to one node without carefully synchronizing server IDs and context state may create split-brain, divergence, or replication storms. Official documentation does not provide stepwise disaster recovery for replicated clusters, but it is clear that simply following standalone restore approaches leads to problems. In these environments, consult advanced OpenLDAP guidance or coordinate restores across all cluster nodes, ensuring consistency for contextCSN and replication metadata.

Automation, Validation, and Ongoing Safety

Hand-crafted CLI usage is not enough. For stability and auditability:

  • Automate backups using cron, systemd timers, or similar orchestration. Automated scripts should perform both configuration and data DIT backups and report status.
  • Validate backups regularly by performing a restore on a test environment. A backup you cannot restore is not a backup.
  • Verify backup completeness. Check for both cn=config and data DIT artifacts.
  • Integrate backup management into DevOps workflows, using scripts or configuration management to version, encrypt, and retention-manage backups.

Official best practices emphasize not just taking backups, but making restores a routine, tested operation.

Common Pitfalls and Misconceptions to Avoid

  • Omitting cn=config from backups: Restores will lack overlays, schema, and runtime configuration, leaving slapd broken or misconfigured.
  • Assuming slapcat is always consistent: While care is taken for read consistency, concurrent write operations can introduce subtle backup inconsistencies. Avoid running slapcat during periods of heavy change unless using read-only mode.
  • Relying on OS-level file copying: Backing up LMDB, BDB, or other backend files directly, while slapd is running, is not supported and risks unrecoverable corruption.
  • Believing all restore scenarios are equal: Procedures for standalone servers do not safely handle replicated, multi-master, or upgraded environments. State and replication metadata must be considered.
  • Expecting plug-and-play version migration: Restoration to a different OpenLDAP version (or different OS) may need schema or config adaptation, and is not guaranteed compatible.

A disciplined approach—covering both configuration and data, using supported tools, and validating restores—is critical. Any shortcut risks not only data loss, but time-consuming recovery scenarios.

Sources

  • OpenLDAP Software 2.6 Administrator’s Guide: Maintenance
  • OpenLDAP Software 2.6 Administrator’s Guide
  • OpenLDAP Software 2.4 Administrator’s Guide: Configuring slapd
  • OpenLDAP Software 2.5 Administrator’s Guide: Maintenance
  • OpenLDAP technical mailing list archives

Sources

Related resources