DEV Community

Benjamin Touchard
Benjamin Touchard

Posted on Originally published at restoreproof.io

Back up an OpenLDAP directory: two exports, one reload, four checks

A directory is the front door to everything else. When it does not come back,
nobody signs in to anything — and it is the kind of backup you discover is
incomplete the day you need it, because an LDIF export of a live directory looks
perfectly valid right up to the moment you try to reload it onto a fresh server.

This guide covers the whole chain. By the end you will know why a directory
backup is two exports and not one, what slapcat guarantees that ldapsearch
does not, what your LDIF really contains — including what will make the reload
fail —, how to reload the export by hand in a throwaway container, and which
four ldapsearch commands tell you a restored directory is usable.

Everything here works with the OpenLDAP tools, docker and the AWS CLI, and nothing else.

A directory backup is two exports

An OpenLDAP directory lives in two databases, and a backup that takes only one
of them does not reload.

The first is the data tree: your organisational units, your accounts, your
groups. That is the one everybody exports, with slapcat or with ldapsearch.

The second is the configuration tree, cn=config: the schemas, the access
rules, the loaded overlays, the indexes. It holds none of your accounts, and yet
it is the one that decides whether the data export can be reloaded at all. A
directory that picked up a home-made attribute over the years — employeeRef,
caseNumber, anything a business application added — describes that attribute
in cn=config, and nowhere else. Without that export, you have a data file that
the restore server refuses to write, entry after entry, without knowing why.

Forgetting cn=config also costs you the access rules. A directory reloaded
without them is a directory whose entries are all there and whose applications
no longer read what they used to read.

slapcat cold, ldapsearch hot

slapcat reads the database files directly, on the server, without going
through slapd. It is fast, it uses no connection, it is subject to no size
limit — but it reads a database that moves. An export taken while writes are
coming in can hold one entry in its state before a change and another in its
state after. For a directory that is almost never serious: entries are
independent. It becomes serious when the change in flight touches an account and
the group that references it: you get a group pointing at a member that is not
there. The only genuinely frozen export is the one taken with slapd stopped.

ldapsearch goes through the server, and so needs neither disk access nor a
service outage: it runs from any machine that can reach port 389. Every entry it
returns is consistent, but the whole is no more consistent than with slapcat:
the read happens entry by entry, with no frozen view.

Two traps are its own. The server applies a size limit to results —
sizelimit, 500 entries by default in slapd: past that it stops, and your
export stops with it. Take the export with the directory's administrator
account, which is not subject to it, and look at the exit code. And by default
ldapsearch only returns application attributes: you have to ask for "*" "+"
to also get what the server built.

What the LDIF really contains

Three things people usually discover at reload time.

The passwords are in there, as hashes. A userPassword: {SSHA}xxxxx
reloads as it is, and the account signs in with its original password. Two
consequences: the export file is worth exactly what the directory is worth, so
it is protected the same way; and the only check that proves people will still
get in is a successful authentication after the restore, not a count of entries.

Operational attributes belong to the server. entryUUID, entryCSN,
structuralObjectClass, creatorsName, createTimestamp, modifiersName,
modifyTimestamp, entryDN, contextCSN, memberOf, the password-policy
attributes in pwd…: the server builds them itself and refuses to have them
written. A slapcat export, or an ldapsearch with "+", contains all of them
— they have to be stripped before reloading. memberOf is the most misleading
case: it is computed by an overlay from the groups, and reimporting it amounts
to freezing memberships the server is going to recompute on its side.

Custom schemas live elsewhere. The entries carrying a home-made attribute
depend on it, and that attribute is not in the data export. That is the whole
point of the second export.

The backup script

On the directory server, both exports and their upload:

#!/bin/bash
set -euo pipefail

ts=$(date +%Y%m%d_%H%M%S)
dest=s3://backups-directory/ldap

slapcat -n 0 -o ldif-wrap=no | gzip > "/backups/config_${ts}.ldif.gz"
slapcat -n 1 -o ldif-wrap=no | gzip > "/backups/directory_${ts}.ldif.gz"

aws s3 cp "/backups/config_${ts}.ldif.gz" "${dest}/"
aws s3 cp "/backups/directory_${ts}.ldif.gz" "${dest}/"
Enter fullscreen mode Exit fullscreen mode

-n 0 names the configuration database, -n 1 the first data database.
-o ldif-wrap=no stops long lines from being folded at 78 columns: without it,
a long attribute is cut and continues on the next line, preceded by a space. A
folded file reloads perfectly well, but it can no longer be filtered line by
line — and that is exactly what you are about to have to do.

If you have no shell access to the directory server, the data export is taken
remotely, along the same lines:

ldapsearch -x -H ldap://ldap.internal \
  -D cn=admin,dc=example,dc=com -w "$LDAP_ADMIN_PASSWORD" \
  -b dc=example,dc=com -LLL -o ldif-wrap=no "(objectClass=*)" "*" "+" \
  | gzip > "/backups/directory_${ts}.ldif.gz"
Enter fullscreen mode Exit fullscreen mode

Without pipefail, a failed export comes out as a success

In slapcat | gzip, the shell only looks at the exit code of the last link.
gzip succeeds at compressing an empty stream, so the script returns 0 and
cron is happy. set -o pipefail — included in the set -euo pipefail
above — makes the whole line fail as soon as slapcat fails. It is the
number one cause of empty backups that stay green for months.

Keep the timestamp in the file names, and keep both exports of the same
timestamp together: a schema that does not match the data being reloaded is of
no use. For retention, a lifecycle rule on the bucket deletes objects older than
N days with no script to maintain.

Reloading once, by hand

An export is only proven once reloaded, onto a server that knows nothing about
the old one. A throwaway container is enough.

docker run -d --name ldap-test \
  -e LDAP_ROOT=dc=example,dc=com \
  -e LDAP_ADMIN_USERNAME=admin \
  -e LDAP_ADMIN_PASSWORD=test \
  -e LDAP_SKIP_DEFAULT_TREE=yes \
  -e LDAP_CONFIG_ADMIN_ENABLED=yes \
  -e LDAP_CONFIG_ADMIN_PASSWORD=test-config \
  bitnamilegacy/openldap:2.6.10-debian-12-r4

until docker exec ldap-test ldapsearch -x -H ldap://localhost:1389 \
  -b "" -s base namingContexts >/dev/null 2>&1; do sleep 1; done
Enter fullscreen mode Exit fullscreen mode

LDAP_SKIP_DEFAULT_TREE is essential: without it, the image creates its own
demonstration tree under LDAP_ROOT, and those entries collide with yours at
reload time ("entry already exists"). A perfectly restorable export then fails
for a reason that has nothing to do with it.

That leaves stripping the operational attributes and loading the data. This is
where the ldif-wrap=no of the export pays off: the filter works line by line.

gunzip -c /backups/directory_20260918_030000.ldif.gz \
  | grep -viE '^(structuralObjectClass|entryUUID|entryCSN|creatorsName|createTimestamp|modifiersName|modifyTimestamp|entryDN|subschemaSubentry|hasSubordinates|numSubordinates|contextCSN|memberOf|pwd[A-Za-z]+):' \
  > /tmp/directory.ldif

docker exec -i ldap-test ldapadd -x -H ldap://localhost:1389 \
  -D cn=admin,dc=example,dc=com -w test < /tmp/directory.ldif
Enter fullscreen mode Exit fullscreen mode

On a directory with a custom schema, this is where it stops:

adding new entry "cn=camille.durand,ou=people,dc=example,dc=com"
ldap_add: Undefined attribute type (17)
    additional info: employeeRef: attribute type undefined
Enter fullscreen mode Exit fullscreen mode

ldapadd stops on the first entry carrying an attribute the server does not
know, and says nothing about the next ones. An export that uses three of them
therefore takes three full reloads to diagnose, and you only learn about the
next missing one once you have fixed the previous one.

The fix is in the cn=config export. You do not replay it whole onto a fresh
server: it describes the file paths, the databases and the overlays of the old
server. What you take out of it are the schema entries, under
cn=schema,cn=config, and only the ones your applications added — core,
cosine, inetorgperson and nis are already in the image. A schema entry
looks like this:

dn: cn=myschema,cn=schema,cn=config
objectClass: olcSchemaConfig
cn: myschema
olcAttributeTypes: ( 1.3.6.1.4.1.99999.1.1 NAME 'employeeRef' DESC 'HR employee number' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )
olcObjectClasses: ( 1.3.6.1.4.1.99999.1.2 NAME 'employee' SUP top AUXILIARY MAY ( employeeRef ) )
Enter fullscreen mode Exit fullscreen mode

It loads into the configuration tree, with that tree's administrator account —
which is not the directory's — before the data:

docker exec -i ldap-test ldapadd -x -H ldap://localhost:1389 \
  -D cn=admin,cn=config -w test-config < /tmp/schema.ldif

docker exec -i ldap-test ldapadd -x -H ldap://localhost:1389 \
  -D cn=admin,dc=example,dc=com -w test < /tmp/directory.ldif
Enter fullscreen mode Exit fullscreen mode

That is also the order you will have to replay them in the day you restore for
real. Note how long it took: that is your real restore duration, the only one
worth comparing to the delay you promised.

What to check in a reloaded directory

A reload that ran without an error does not mean the directory is usable. Four
questions, in this order:

ldapsearch -x -H ldap://localhost:1389 -D cn=admin,dc=example,dc=com -w test \
  -b ou=people,dc=example,dc=com -LLL "(objectClass=inetOrgPerson)" dn \
  | grep -c '^dn:'

ldapsearch -x -H ldap://localhost:1389 -D cn=admin,dc=example,dc=com -w test \
  -b cn=camille.durand,ou=people,dc=example,dc=com -s base -LLL dn

ldapsearch -x -H ldap://localhost:1389 -D cn=admin,dc=example,dc=com -w test \
  -b ou=groups,dc=example,dc=com -LLL "(cn=support)" member

ldapsearch -x -H ldap://localhost:1389 \
  -D cn=camille.durand,ou=people,dc=example,dc=com -w "$CAMILLE_PASSWORD" \
  -b "" -s base -LLL namingContexts
Enter fullscreen mode Exit fullscreen mode
  1. The accounts are there. Compare against the order of magnitude in production, not an exact number. And check the command's exit code: if the server hit its size limit, the count is wrong on the low side.
  2. A known account is there, that one precisely. Six entries are not necessarily the right six: looking an entry up by its full DN is stronger than a count.
  3. The memberships are there. Groups decide privileges. A directory reloaded without its member values is a directory where everyone lost their access — and it is the first symptom of a memberOf reimported in place of the groups themselves.
  4. The passwords work. That last command queries nothing useful: it authenticates as camille.durand. It is the only one that proves the hashes came back usable. An export that reloads everything except the userPassword values gives a directory that looks perfect and lets nobody in.

Then destroy everything: docker rm -f ldap-test.

What this chain does not prove

It proves that the most recent export reloads into a fresh OpenLDAP, that the
expected entries and groups are there, and that a restored account still
authenticates.

It does not prove that the rest of cn=config came back: the access rules, the
overlays and the indexes are not replayed in the throwaway container above, only the schemas are.
It says nothing about replication between your servers, and nothing about how old the export is: a March directory reloads perfectly in September. And the reloaded
directory is not identical byte for byte to the original: the operational
attributes were rebuilt by the test server, which is just as well — what
matters to you is that your users sign back in. Finally, it says nothing about
what has been created since the last export: that gap is your RPO, and it is
tuned with the backup frequency, not with the tests.

FAQ

Is an LDIF export of the right size good enough?

No. A complete data export does not reload onto a fresh server as soon as the
directory uses a custom attribute: ldapadd stops on the first entry carrying
it. File size says nothing about that, and nothing either about the operational
attributes you have to strip before replaying it.

What is in cn=config, and why back it up?

The schemas, the access rules, the loaded overlays and the indexes. None of your
accounts. Yet it is that export which makes the other one reloadable: the custom
attributes your entries depend on are described there, and nowhere else.

Do you have to stop slapd to take a backup?

For a genuinely frozen export, yes. Taken hot, entries stay individually
consistent, but a group and the account it references can be captured on either
side of a change. On most directories that trade-off is worth it; on a directory
that changes constantly, stopping the service is the only export without
surprises.

Why can a restored account no longer sign in?

Because the userPassword values were not reloaded, or not as they were. The
LDIF holds them as hashes, which replay identically — but a filtered export, or
one taken by an account that cannot read them, gives a directory that looks
perfect and lets nobody in. Only a successful authentication after the restore
proves otherwise.

Why does an ldapsearch export stop at 500 entries?

Because the server applies a size limit to results, sizelimit, set to 500
entries by default in slapd. Past that the search stops and the export stops
with it, on a file that looks perfectly normal. Take the export with the
directory's administrator account, which is not subject to it, and read the
command's exit code.


Originally published on restoreproof.io.

RestoreProof runs this kind of restore test on a schedule, inside your own infrastructure, and signs a report proving the backup restores. Your data never leaves your servers. Free plan, no credit card: https://app.restoreproof.io

Top comments (0)