/docker-openldap

Opinionated docker image based on debian:bookworm-slim to run an OpenLDAP 2.5 server.

Primary LanguageShellApache License 2.0Apache-2.0

vegardit/openldap

Build Status License Docker Pulls Docker Stars Contributor Covenant

  1. What is it?
  2. Configuration
    1. Initial configuration
    2. Initial LDAP tree
    3. Customizing the Password Policy
    4. Changing UID/GID of OpenLDAP service user
    5. Periodic LDAP Backup
    6. Synchronizing timezone/time with docker host
    7. Performance tuning
    8. Troubleshooting
  3. References
  4. License

What is it?

Opinionated docker image is currently based on the Debian docker image debian:bookworm-slim to run an OpenLDAP 2.5 server.

It is automatically built daily to include the latest OS security fixes.

To keep the image light and simple, it does not configure TLS. Instead we recommend configuring a Traefik 2.x TCP service with e.g. an auto-renewing Let's Encrypt configuration in front of the OpenLDAP service.

Configuration

Initial configuration

Various parts of the LDAP server can be configured via environment variables. All environment variables starting with LDAP_INIT_ are only evaluated on the first container launch. Changing their values later has no effect when restarting or updating the container.

To customize the initial configuration you can set the following environment variables:

LDAP_INIT_ORG_DN='dc=example,dc=com'
LDAP_INIT_ORG_NAME='Example Corporation'
LDAP_INIT_ADMIN_GROUP_DN='cn=ldap-admins,ou=Groups,${LDAP_INIT_ORG_DN}'
LDAP_INIT_PASSWORD_RESET_GROUP_DN='cn=ldap-password-reset,ou=Groups,${LDAP_INIT_ORG_DN}' # users in this group can set password/sshPublicKey attribute of other users
LDAP_INIT_ROOT_USER_DN='uid=admin,${LDAP_INIT_ORG_DN}'
LDAP_INIT_ROOT_USER_PW='changeit'
LDAP_INIT_RFC2307BIS_SCHEMA=0 # 0=use NIS (RFC2307) schema, 1=use RFC2307bis schema
LDAP_INIT_ALLOW_CONFIG_ACCESS='true' # if set to true, the "cn=config" namespace can be read/edited by LDAP admins

Environment variables can for example be set in one of the following ways:

  1. Using docker run with -e, e.g.

    docker run -itd \
  -e LDAP_INIT_ORG_DN='o=yourorg' \
  -e LDAP_INIT_ROOT_USER_PW='newpassword' \
  -e LDAP_INIT_ORG_NAME='Company Inc' \
  -e LDAP_INIT_PPOLICY_PW_MIN_LENGTH='12' \
  -v /my_data/ldap/var/:/var/lib/ldap/ \
  -v /my_data/ldap/etc/:/etc/ldap/slapd.d/ \
  vegardit/openldap

  2. Using an env-file to store all changed variables and use the option --env-file with docker run, e.g.:

    docker run -itd --env-file environment vegardit/openldap

    In environment file values must not be enclosed using quotes (' or "), please remove them. See this example file: example/docker/example.env.

  3. Setting the environment variable INIT_SH_FILE pointing to a shell script that should be sourced during the container start.

    # /path/on/docker/host/my_init.sh
LDAP_INIT_ORG_DN='o=yourorg'
LDAP_INIT_ROOT_USER_PW='newpassword'
LDAP_INIT_ORG_NAME='Company Inc'
LDAP_INIT_PPOLICY_PW_MIN_LENGTH='12'
    docker run -itd
  -e INIT_SH_FILE=/mnt/my_init.sh
  -v /path/on/docker/host/my_init.sh:/mnt/my_init.sh:ro
  vegardit/openldap

Initial LDAP tree

The initial LDAP tree structure is imported from /opt/ldifs/init_org_tree.ldif. You can mount a custom file at /opt/ldifs/init_org_tree.ldif if you require changes.

LDAP entries (users, groups) are imported from /opt/ldifs/init_org_entries.ldif. You can mount a custom file at /opt/ldifs/init_org_entries.ldif if you require changes.

Customizing the Password Policy

On initial container launch, the password policy is imported from /opt/ldifs/init_org_ppolicy.ldif

The following parameters can be modified via environment variables before initial container launch:

LDAP_INIT_PPOLICY_DEFAULT_DN='cn=DefaultPasswordPolicy,ou=Policies,${LDAP_INIT_ORG_DN}'
LDAP_INIT_PPOLICY_PW_MIN_LENGTH=8
LDAP_INIT_PPOLICY_MAX_FAILURES=3
LDAP_INIT_PPOLICY_LOCKOUT_DURATION=300

If more customizations are required, simply mount a custom policy file at /opt/ldifs/init_org_ppolicy.ldif before initial container launch.

Password Quality Checker:

pqChecker is configured as default password quality checker using the rule 0|01010101 with the following meaning:

Pos. Value Effective Rule
0-1 0| Don't broadcast passwords.
2-4 01 Minimum 1 uppercase character.
5-6 01 Minimum 1 lowercase character.
7-8 01 Minimum 1 digit.
9-10 01 Minimum 1 special character.
11-.. empty No characters are disallowed in passwords.

The pqChecker rule syntax is explained here in more detail: https://www.meddeb.net/pqchecker/?Idx=2

A custom rule can be provided via an environment variable, e.g.:

LDAP_PPOLICY_PQCHECKER_RULE='0|01020101@!+-#'

Changing UID/GID of OpenLDAP service user

The UID/GID of the user running the OpenLDAP service can be aligned with the docker host, using the environment variables LDAP_OPENLDAP_UID and LDAP_OPENLDAP_GID.

During each container start it is verified that the given UID/GID matches the currently effective UID/GID. If not, the UID/GID of the openldap user are changed accordingly and chown on /etc/ldap and /var/lib/slapd is executed before the OpenLDAP service is started.

Periodic LDAP Backup

This image automatically generates a daily LDIF export at 2 a.m. to /var/lib/ldap/data.ldif.

The following environment variables can be used to configure the automatic LDAP backup:

LDAP_BACKUP_TIME='02:00'  # Format is "HH:MM", i.e. 24-hour format with minute precision
LDAP_BACKUP_FILE='/var/lib/ldap/data.ldif'

To disable automatic backup set an empty value for the environment variable LDAP_BACKUP_TIME.

Synchronizing timezone/time with docker host

To use the same timezone and/or time of the docker host you can run the docker image with --volume /etc/localtime:/etc/localtime:ro --volume /etc/timezone:/etc/timezone:ro

Docker compose file example:

version: '3.7'
services:
  openldap:
    image: vegardit/openldap:latest
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /etc/timezone:/etc/timezone:ro

Performance tuning

DB Indexes

The database indexes that are configured during initial container launch are imported from /opt/ldifs/init_backend_indexes.ldif

To use other indexes, simply mount a custom file at /opt/ldifs/init_backend_indexes.ldif before initial container launch.

Memory usage

The maximum number of open files is set to 1024 by default to prevent excessive RAM consumption as reported here.

The following environment variable can be used to increase this limit:

LDAP_NOFILE_LIMIT=2048

Troubleshooting

The slapd service logs to stdout. You can change the active log levels by setting this environment variable:

LDAP_LOG_LEVELS='Config Stats'

The following log levels are available:

Any     (-1)     enable all debugging
Trace   (1)      trace function calls
Packets (2)      debug packet handling
Args    (4)      heavy trace debugging
Conns   (8)      connection management
BER     (16)     print out packets sent and received
Filter  (32)     search filter processing
Config  (64)     configuration processing
ACL     (128)    access control list processing
Stats   (256)    stats log connections/operations/results
Stats2  (512)    stats log entries sent
Shell   (1024)   print communication with shell backends
Parse   (2048)   print entry parsing debugging
Sync    (16384)  syncrepl consumer processing
None    (32768)  only messages that get logged whatever log level is set

References

License

All files in this repository are released under the Apache License 2.0.

Individual files contain the following tag instead of the full license text:

SPDX-License-Identifier: Apache-2.0

This enables machine processing of license information based on the SPDX License Identifiers that are available here: https://spdx.org/licenses/.