osixia/container-openldap

osixia/openldap 🐳🪪🌴

OpenLDAP container image with built-in bootstrap, backup helpers, TLS, replication and upgrade support.

⚠️ WARNING v2 is a breaking release. Existing v1 deployments are not migrated automatically and require a manual migration to move to v2. Automatic upgrade paths are intended only between future v2 versions (for example, v2.x to v2.y).

110M+ pulls 🎉 Thanks to everyone using, testing, reporting issues, and contributing to this image. 🙏

• osixia/openldap 🐳🪪🌴
  • ⚡ Quickstart
  • 🛟 Backup / Restore
  • 🔐 TLS
  • 🔁 Replication
  • 🛠️ LDAP Toolkit
    • OpenLDAP Utilities
    • Validate LDIF
    • Password Helpers
    • Convert Schema to LDIF
  • 🔤 Environment Variables
  • 📄 Documentation
  • 🔀 Contributing
  • 🔓 License

⚡ Quickstart

Run a basic OpenLDAP server:

docker run --name openldap --hostname ldap.example.org -p 389:3890 -p 636:6360 \
  -e OPENLDAP_BOOTSTRAP_ORGANIZATION="Keycloakers Org" \
  -e OPENLDAP_BOOTSTRAP_SUFFIX="dc=keycloakers,dc=org" \
  osixia/openldap:2.6.15-rc

For persistent deployments, mount config, data, and backup directories:

docker run --name openldap --hostname ldap.example.org -p 389:3890 -p 636:6360 \
  -e OPENLDAP_BOOTSTRAP_ORGANIZATION="Keycloakers Org" \
  -e OPENLDAP_BOOTSTRAP_SUFFIX="dc=keycloakers,dc=org" \
  -v openldap-conf:/etc/openldap/slapd.d \
  -v openldap-data:/var/lib/openldap/openldap-data \
  -v openldap-backups:/var/lib/openldap/openldap-backups \
  osixia/openldap:2.6.15-rc

Notes:

• Default internal listener ports are 3890 (LDAP) and 6360 (LDAPS), as defined by OPENLDAP_URLS.
• On first start, passwords are generated if hashed values are empty and printed in logs.
• Bootstrap runs only when config/data are empty.
• OPENLDAP_BOOTSTRAP_SUFFIX must start with dc= (for example dc=example,dc=org).

Verify the server is up

Retrieve the generated admin password from the container logs:

docker logs openldap 2>&1 | grep -i password

Then search the base DN to confirm the server is responding, replacing <database root password> with the password from the logs:

docker exec openldap container run -- \
  ldapsearch -H ldap://localhost:3890 \
  -D "cn=admin,dc=keycloakers,dc=org" -w '<database root password>' \
  -b "dc=keycloakers,dc=org" "(objectClass=*)"

A successful response returns the organization entry. The root DN cn=admin authenticates without requiring a directory entry.

Passing command-line arguments to OpenLDAP

The osixia/openldap container allows you to pass additional command-line arguments directly to the OpenLDAP binary.

Arguments specified after -- are forwarded to the slapd process inside the container:

docker run osixia/openldap:2.6.15-rc -- -d -1

Customizing bootstrap configuration and data

To customize bootstrap configuration or initial data, see the custom LDIF documentation.

Debugging

To debug the container manually, you can start it with an interactive shell.

The --log-level debug --bash options from osixia/baseimage enables debug logging and launches an interactive shell.

If OpenLDAP keeps crashing, you can add --skip-process to start the container without launching service processes.

docker run -it osixia/openldap:2.6.15-rc --log-level debug --bash
docker run -it osixia/openldap:2.6.15-rc --skip-process --log-level debug --bash

You can also increase the OpenLDAP daemon (slapd) log level with OPENLDAP_DEBUG_LEVEL:

docker run -e OPENLDAP_DEBUG_LEVEL=-1 osixia/openldap:2.6.15-rc

OPENLDAP_DEBUG_LEVEL only affects OpenLDAP (slapd) logging. To increase container/runtime logs, use the baseimage flag --log-level (for example --log-level debug).

To see all available command-line options:

docker run --rm osixia/openldap:2.6.15-rc --help # osixia/baseimage options
docker run --rm osixia/openldap:2.6.15-rc -x openldap -- --help # slapd command-line options

🛟 Backup / Restore

The image includes the openldap-ctl helper with backup and restore commands.

Create a full backup:

docker exec openldap container run -- openldap-ctl backup my-backup

Create only a data backup and remove backups older than 15 days whose name starts with my-:

docker exec openldap container run -- openldap-ctl backup my-backup --data --clean 15 --clean-prefix my-

Without --clean-prefix, --clean removes all old backups in OPENLDAP_BACKUP_DIR. Other files are never removed.

This creates files in OPENLDAP_BACKUP_DIR:

• my-backup-config.gz
• my-backup-data.gz

Restore a backup:

docker exec openldap container run -- openldap-ctl restore my-backup --force

--force stops the OpenLDAP process if needed, replaces existing data in the target directories with the selected databases, then starts OpenLDAP again. Backup files are checked first: if one is missing or corrupted, nothing is stopped or deleted. If the restore fails, the previous data is put back.

The cron service is disabled by default. To schedule regular backups, run it in a separate container alongside OpenLDAP, sharing its configuration, data, and backup volumes:

docker run --name openldap-cron \
  -u root \
  -v openldap-conf:/etc/openldap/slapd.d \
  -v openldap-data:/var/lib/openldap/openldap-data \
  -v openldap-backups:/var/lib/openldap/openldap-backups \
  osixia/openldap:2.6.15-rc -x openldap-cron

See the OPENLDAP_CRON_JOB environment variable to adjust the cron schedule and behavior.

🔐 TLS

Set OPENLDAP_BOOTSTRAP_TLS=true to configure TLS during bootstrap.

The default certificate paths are:

• /container/services/openldap/assets/certs/tls.crt
• /container/services/openldap/assets/certs/tls.key
• /container/services/openldap/assets/certs/ca.crt

The simplest way is to mount a directory that contains files with exactly those names:

docker run --name openldap --hostname ldap.example.org -p 389:3890 -p 636:6360 \
  -e OPENLDAP_BOOTSTRAP_TLS=true \
  -v $PWD/certs:/container/services/openldap/assets/certs \
  osixia/openldap:2.6.15-rc

If you also set OPENLDAP_BOOTSTRAP_TLS_REQUIRED=true, bootstrap adds TLS-required access rules. That setting is stricter than plain TLS enablement and is intended for deployments where non-TLS client access should be rejected.

The optional openldap-tls-reload service restarts slapd when certificate contents change. See certificate renewal.

🔁 Replication

Set OPENLDAP_BOOTSTRAP_REPLICATION=true to bootstrap syncrepl replication.

OPENLDAP_BOOTSTRAP_REPLICATION_HOSTS must contain between two and nine hosts, in the same order on every server. The current node FQDN must match one of them.

When replication is enabled, set OPENLDAP_URLS with the node hostname in LDAP/LDAPS URLs (for example ldap://ldap1.example.org:3890 ldaps://ldap1.example.org:6360 ldapi:///) so advertised endpoints match replication hosts.

For a local Docker setup, put both containers on the same user-defined network so each host can resolve the other one:

docker network create openldap-net

Minimal example for ldap1.example.org:

docker run --name ldap1 --network openldap-net --hostname ldap1.example.org \
  -e OPENLDAP_URLS="ldap://ldap1.example.org:3890 ldaps://ldap1.example.org:6360 ldapi:///" \
  -e OPENLDAP_BOOTSTRAP_ORGANIZATION="Keycloakers Org" \
  -e OPENLDAP_BOOTSTRAP_SUFFIX="dc=keycloakers,dc=org" \
  -e OPENLDAP_BOOTSTRAP_REPLICATION=true \
  -e OPENLDAP_BOOTSTRAP_REPLICATION_HOSTS="ldap://ldap1.example.org:3890 ldap://ldap2.example.org:3890" \
  -e OPENLDAP_BOOTSTRAP_REPLICATION_DATA_READONLY_PASSWORD="passw0rd" \
  osixia/openldap:2.6.15-rc

Minimal example for ldap2.example.org:

docker run --name ldap2 --network openldap-net --hostname ldap2.example.org \
  -e OPENLDAP_URLS="ldap://ldap2.example.org:3890 ldaps://ldap2.example.org:6360 ldapi:///" \
  -e OPENLDAP_BOOTSTRAP_ORGANIZATION="Keycloakers Org" \
  -e OPENLDAP_BOOTSTRAP_SUFFIX="dc=keycloakers,dc=org" \
  -e OPENLDAP_BOOTSTRAP_REPLICATION=true \
  -e OPENLDAP_BOOTSTRAP_REPLICATION_HOSTS="ldap://ldap1.example.org:3890 ldap://ldap2.example.org:3890" \
  -e OPENLDAP_BOOTSTRAP_REPLICATION_DATA_READONLY_PASSWORD="passw0rd" \
  osixia/openldap:2.6.15-rc

If TLS is required for replication, set OPENLDAP_BOOTSTRAP_REPLICATION_TLS=true or rely on its default value from OPENLDAP_BOOTSTRAP_TLS_REQUIRED.

🛠️ LDAP Toolkit

OpenLDAP Utilities

This image ships with the full suite of OpenLDAP utilities — both server-side database tools and LDAP client tools.

Database tools

slapcat, slapadd, slapindex, and slaptest operate directly on local configuration and database files. They can also run in a temporary container with the corresponding volumes mounted.

Export the data database to LDIF:

docker exec openldap container run -- slapcat -n 1

Export the config database (cn=config):

docker exec openldap container run -- slapcat -n 0

Note: slapadd and slapindex require OpenLDAP to be stopped first. Use docker exec openldap container processes stop openldap to stop OpenLDAP and docker exec openldap container processes start openldap to restart OpenLDAP.

LDAP client tools

ldapsearch, ldapwhoami, ldapadd, ldapmodify, ldapdelete, and ldappasswd connect to any LDAP server over the network.

Search for all entries under a base DN:

docker run --rm osixia/openldap:2.6.15-rc run -- \
  ldapsearch -H ldap://172.16.0.1 \
  -D "cn=admin,dc=example,dc=org" -w passw0rd \
  -b "dc=example,dc=org" "(objectClass=*)"

Verify bind credentials:

docker run --rm osixia/openldap:2.6.15-rc run -- \
  ldapwhoami -H ldap://172.16.0.1 \
  -D "cn=admin,dc=example,dc=org" -w passw0rd

Add entries from a local LDIF file:

docker run --rm -v /path/to/entries.ldif:/tmp/entries.ldif \
  osixia/openldap:2.6.15-rc run -- \
  ldapadd -H ldap://172.16.0.1 \
  -D "cn=admin,dc=example,dc=org" -w passw0rd \
  -f /tmp/entries.ldif

Change a user's password:

docker run --rm osixia/openldap:2.6.15-rc run -- \
  ldappasswd -H ldap://172.16.0.1 \
  -D "cn=admin,dc=example,dc=org" -w passw0rd \
  -s newpassword "uid=jdoe,ou=people,dc=example,dc=org"

Validate LDIF

Check data entries against the instance's initialized configuration without importing them or stopping slapd:

docker exec openldap container run -- openldap-ctl validate-ldif /data/users.ldif

Pass multiple file paths or a directory; all paths must be accessible inside the container. Directories are searched recursively for *.ldif, sorted by version and excluding hidden paths. Each file must contain complete entries. All files are checked; any validation failure returns a non-zero status. Checks LDIF syntax, attribute values and schemas. Does not check existing entries, ACLs or overlay rules, and does not accept ldapmodify change records.

Password Helpers

Generate a random password:

docker run --rm osixia/openldap:2.6.15-rc run -- openldap-ctl password generate

Hash a password:

docker run --rm osixia/openldap:2.6.15-rc run -- openldap-ctl password hash passw0rd

Read a password from a mounted secret or standard input:

docker run --rm --user "$UID" -v "$PWD/password.txt:/run/secrets/password:ro" \
  osixia/openldap:2.6.15-rc run -- openldap-ctl password hash --file /run/secrets/password
docker run --rm -i osixia/openldap:2.6.15-rc run -- \
  openldap-ctl password hash --stdin < password.txt

Contents are hashed exactly, including trailing newlines. Use hash -- password for a literal password named --file, --stdin or --.

Convert Schema to LDIF

docker run --rm --user $UID -v $(pwd)/schema:/data   \
  osixia/openldap:2.6.15-rc run -- openldap-ctl schema2ldif /data/test.schema

🔤 Environment Variables

Core

Bootstrap

TLS

RefInt

PPolicy

When ppolicy and the data read-only account are enabled, bootstrap explicitly denies that account access to pwdHistory before its general read grant. Other identities continue through the usual ACLs: administrators and replication retain access, while ordinary users are denied by the final catch-all unless a custom ACL grants access. Override 64-database-readonly-ppolicy-acl.ldif through the custom config directory to change the read-only restriction. This ACL is added on new bootstraps only; existing databases need an explicit ACL update.

Unique

MemberOf

Replication

Helpers and Maintenance

📄 Documentation

See full documentation and complete features list on osixia/openldap documentation.

This image is based on osixia/baseimage.

🔀 Contributing

If you find this project useful here's how you can help:

• Send a pull request with new features and bug fixes.
• Help new users with issues they may encounter.
• Support the development of this image and star this repo and the image docker hub repository.

This project uses a CI/CD tool to build, test, and deploy images. See the source code and useful command lines in build directory.

🔓 License

This project is licensed under the terms of the MIT license. See LICENSE.md file for more information.