# vegardit/openldap 
[](https://github.com/vegardit/docker-openldap/actions?query=workflow%3ABuild)
[](#license)
[](https://hub.docker.com/r/vegardit/openldap)
[](https://hub.docker.com/r/vegardit/openldap)
[](CODE_OF_CONDUCT.md)
1. [What is it?](#what-is-it)
1. [Configuration](#config)
1. [Initial configuration](#initial-config)
1. [Initial LDAP tree](#initial_ldaptree)
1. [Customizing the Password Policy](#ppolicy)
1. [Changing UID/GID of OpenLDAP service user](#uidgid)
1. [Periodic LDAP Backup](#backup)
1. [Synchronizing timezone/time with docker host](#timesync)
1. [Performance tuning](#performance-tuning)
1. [Troubleshooting](#troubleshooting)
1. [References](#references)
1. [License](#license)
## What is it?
Opinionated docker image currently based on the [Debian](https://www.debian.org/) docker image [`debian:bookworm-slim`](https://hub.docker.com/_/debian?tab=tags&name=bookworm-slim) to run an [OpenLDAP 2.5](https://www.openldap.org/doc/admin25/) server.
It is automatically built **weekly** 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](https://traefik.io) [TCP service](https://docs.traefik.io/routing/services/#configuring-tcp-services) with e.g. an auto-renewing [Let's Encrypt configuration](https://docs.traefik.io/https/acme/) 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:
```sh
LDAP_INIT_ORG_DN='DC=example,DC=com'
LDAP_INIT_ORG_NAME='Example Corporation'
LDAP_INIT_ORG_ATTR_O='' # optional, if not defined will be derived from LDAP_INIT_ORG_DN, e.g. DC=example,DC=com -> example.com
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.
```sh
docker run -itd \
-e LDAP_INIT_ORG_DN='DC=example,DC=com' \
-e LDAP_INIT_ROOT_USER_PW='newpassword' \
-e LDAP_INIT_ORG_NAME='Example Corporation' \
-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
```
1. Using an [env-file](https://docs.docker.com/compose/env-file/) to store all changed variables and use the option `--env-file` with `docker run`, e.g.:
```sh
docker run -itd --env-file environment vegardit/openldap
```
In the env-file values must not be enclosed using quotes (`'` or `"`), please remove them. See this example file: [example/docker/example.env](example/docker/example.env).
1. Setting the environment variable `INIT_SH_FILE` pointing to a shell script that should be sourced during the container start.
```sh
# /path/on/docker/host/my_init.sh
LDAP_INIT_ORG_DN='DC=example,DC=com'
LDAP_INIT_ROOT_USER_PW='newpassword'
LDAP_INIT_ORG_NAME='Example Corporation'
LDAP_INIT_PPOLICY_PW_MIN_LENGTH='12'
```
```sh
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](image/ldifs/init_org_tree.ldif).
You can mount a custom file at that path if you need changes.
LDAP entries (users, groups) are imported from [/opt/ldifs/init_org_entries.ldif](image/ldifs/init_org_entries.ldif).
You can mount a custom file at that path if you need changes.
### Customizing the Password Policy
On **initial** container launch, the [password policy](https://www.openldap.org/doc/admin24/overlays.html#Password%20Policies) is imported from [/opt/ldifs/init_org_ppolicy.ldif](image/ldifs/init_org_ppolicy.ldif).
The following parameters can be modified via environment variables **before** initial container launch:
```sh
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](https://www.meddeb.net/pqchecker/) is configured as the 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.:
```sh
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:
```bash
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 image with:
```sh
--volume /etc/localtime:/etc/localtime:ro \
--volume /etc/timezone:/etc/timezone:ro
```
Docker compose file example:
```yaml
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 configured during initial container launch are imported from [/opt/ldifs/init_backend_indexes.ldif](image/ldifs/init_mdb_indexes.ldif).
To use other indexes, mount a custom file at that path **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](https://github.com/docker/docker/issues/8231).
Increase this limit with the following environment variable:
```sh
LDAP_NOFILE_LIMIT=2048
```
### Troubleshooting
The slapd service logs to stdout. You can change the active log levels by setting this environment variable:
```sh
LDAP_LOG_LEVELS='Config Stats'
```
Available [log levels](https://www.openldap.org/doc/admin24/slapdconfig.html#loglevel%20%3Clevel%3E):
```
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
- OpenLDAP Software 2.5 Administrator's Guide https://www.openldap.org/doc/admin25/guide.html
- OpenLDAP Online Configuration Reference https://tylersguides.com/guides/openldap-online-configuration-reference/
- `slapd-config(5)` - Linux man page https://linux.die.net/man/5/slapd-config
## License
All files in this repository are released under the [Apache License 2.0](LICENSE.txt).
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/.