osixia/docker-openldap-backup: scheduled OpenLDAP backups inside the container

What osixia/docker-openldap-backup adds to a plain OpenLDAP container

The project is a Docker image that runs OpenLDAP and makes periodic backups. That is the whole scope stated in the README. It is built on top of osixia/openldap, and the README says plainly that only the backup extension is described there, with everything else left to the parent project's repository.

So the audience is narrow: teams already running osixia/openldap in Docker who want the directory dumped on a schedule without writing a sidecar container, a host cron job or an external backup script. If you are not using the osixia base image, this image brings little on its own. The value is the packaging, not a new backup format. The image schedules dumps and rotates them by age; it does not invent a snapshot mechanism.

The repository is mostly Shell plus a Makefile, an image/ directory, a test/ directory and a CHANGELOG.md. That layout matches the README's description of the image as a small layer of environment configuration and cron wiring over the OpenLDAP base.

Cron expressions, TTL and the /data/backup volume

Three environment variables drive the behaviour, and their defaults live in image/environment/default.yaml according to the README. LDAP_BACKUP_CONFIG_CRON_EXP schedules the OpenLDAP config backup and defaults to 0 4 * * *, described as every day at 4am. LDAP_BACKUP_DATA_CRON_EXP does the same for the data backup, with the same default. LDAP_BACKUP_TTL is the backup retention in days and defaults to 15.

The data flow is straightforward: the container runs slapd, cron fires on the configured expression, a dump is written under /data/backup inside the container, and older files fall out of the TTL window. Because /data/backup is a container path, the README's quick start maps a host directory onto it so the files survive the container. That mapping is the only durability mechanism the documentation describes. If you forget it, the backups live and die with the container.

Two separate cron variables for config and data is a deliberate split: you can back up the configuration more or less often than the directory contents. The README does not explain why you would, and it does not document what happens when both expressions fire in the same minute. Treat that as an unknown rather than a feature.

Installing osixia/openldap-backup and taking a first backup

There is no package to install. The image is pulled from Docker Hub, and the README's quick start uses the tag osixia/openldap-backup:1.5.0. The command below sets the config backup cron to 5am, maps a host directory to /data/backup, and detaches. After it starts, the host directory fills with dumps once cron fires.

docker run --env LDAP_BACKUP_CONFIG_CRON_EXP="0 5 * * *" \
  --volume /data/openldap/backup:/data/backup \
  --detach osixia/openldap-backup:1.5.0

For a first run you may not want to wait until the next morning. The README does not document a way to trigger a backup immediately, so the practical check is to set an expression that fires within the next minute and watch /data/openldap/backup on the host. If nothing appears, the volume mapping is the first thing to confirm.

If you prefer to keep the settings in a file rather than on the command line, the README gives this pattern, linking a YAML environment file into /container/environment/01-custom/env.yaml. The 01 prefix matters: the README warns that files must go into a directory named XX-somedir with XX below 99, because /container/environment itself holds base image files that fix INITRD, LANG, LANGUAGE and LC_CTYPE.

docker run --volume /data/ldap/environment/my-env.yaml:/container/environment/01-custom/env.yaml \
  --detach osixia/openldap-backup:1.5.0

For debugging, the default log level is info, and the README lists none, error, warning, info, debug and trace as the available levels. The example it gives passes --loglevel debug as a container argument. Running the image with --help prints all command line options.

docker run --detach osixia/openldap-backup:1.5.0 --loglevel debug

What the documentation does not cover about restoring

The README documents how backups are produced and how long they are kept. It does not document how to restore them. There is no restore command, no verification step, no checksum, and no statement about whether the dumps are consistent with a running slapd at the moment cron fires. For a backup tool, that is the largest gap in the available documentation, and it is a gap you have to close yourself before you trust the output.

The TTL of 15 days is also the only retention control. There is no documented size cap, so a large directory with a short cron interval can grow the backup volume until the TTL window rolls over. The README is silent on compression and on whether the config and data backups are independent files or one archive.

Then there is the age of the project. The last push was on 2021-02-19, and the most recent release listed is v1.5.0 on the same date. The repository is not archived, but nothing in the README or the release list suggests recent changes. The parent image, osixia/openldap, is where the OpenLDAP version and the underlying base image come from, and this project inherits whatever that image ships. If you need a current OpenLDAP build or a maintained backup path, this is the wrong tool, not a tool with a caveat.

How this differs from backing up with a sidecar or the Bitnami image

The obvious alternative is to run osixia/openldap on its own and take the dumps from outside the container: a host cron job calling docker exec, or a separate backup container that mounts the same data volume. That approach is more work but it decouples the backup schedule from the LDAP process lifetime. With osixia/openldap-backup, backups stop when the container stops, and the cron daemon lives in the same container as slapd. The README does not describe any external trigger, so restarting the container is the only documented way to change the schedule.

A second alternative is a different OpenLDAP image, such as the Bitnami one, paired with your own backup mechanism. The difference is not the LDAP server so much as the packaging: osixia/openldap-backup ships the environment-file convention under /container/environment/XX-somedir, the --loglevel flag, and the three LDAP_BACKUP_* variables as a ready-made configuration surface. A generic image gives you none of that, and you would rebuild the cron wiring yourself.

If you want a web interface next to the directory, osixia/phpldapadmin is the companion image people commonly pair with osixia/openldap. This backup image does not include one, and the README does not mention it.

Building your own image and the MIT licence

The repository ships a Makefile with NAME = osixia/openldap-backup and VERSION = 1.5.0, plus targets for build, build-nocache, test, tag-latest, push, push-latest, release and git-tag-version. The release target chains build, test, tag-latest, push and push-latest, and git-tag-version then creates an annotated tag and pushes it. The test target runs Bats, the Bash Automated Testing System, over test/test.bats. If you fork the project, those targets are the upgrade path: change NAME and VERSION, rebuild, and push to your own registry.

The README also shows extending the published image with a Dockerfile that starts FROM osixia/openldap-backup:1.5.0 and adds an environment directory into /container/environment/01-custom. That is the lowest-effort route when you only need extra variables baked in.

The licence is MIT, which permits modification and redistribution provided the copyright notice and permission notice are preserved. That is a statement about the repository's licence file, not legal advice; if you redistribute a modified image, check how you handle attribution. Note that the OpenLDAP server itself and the base image come from osixia/openldap, so their terms apply to those layers, and the README points there for anything under the hood.

Editorial conclusion

Adopt osixia/docker-openldap-backup if you already run osixia/openldap, want slapd backups on a cron expression, and can map /data/backup to storage you control. Do not adopt it if you need an actively maintained image or a documented restore command, because the last push was on 2021-02-19 and the README covers only the backup extension. Before committing, verify the two cron variables, the 15-day TTL, and that a restore path exists for the files it produces.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes