cepharum/slapd repository overview

This container is managed at our on-premise GitLab instance with limited access.

⁠OpenLDAP docker container

⁠Setup

docker build -t cepharum/slapd docker

⁠Start Server

docker run -d \
	-v /ldap/data:/data \
	-v /ldap/config:/config \
	-v /ldap/certs:/certs \
	-v /ldap/import:/import \
	-p 389:389 -p 636:636 \
	--restart always \
	-e DOMAIN=yourserver.com \
	cepharum/slapd

On first start this will populate the initially empty folder mounted as /config with some initial runtime configuration and start slapd with ldap:// support on port 389, only.

The environment DOMAIN variable is split into second-level domain name and top-level domain name and then rejoined to result in a suffix for your LDAP database. In example here the resulting suffix would be dc=yourserver,dc=com. You can also provide particular suffix in variable SUFFIX, instead.

⁠Instantly Enable Encrypted LDAP

It is possible to enable ldaps:// on first invocation as well. Mounted folder /certs is designed to contain certificate-related files:

• /certs/cert.pem should contain the signed certificate.
• /certs/key.pem should contain the certificate's key without any passphrase.
• /certs/ca.pem is optional and should contain chaining certificates of used CA.

Different pathnames can be provided using environment variables CERTFILE, KEYFILE and CAFILE.

⁠Setting up Root DN

The Root DN is a special DN which isn't actual part of database managed by LDAP server but some virtual entry's DN available for granting full access on all records in that database. So this DN can be used to update any data subordinated to the given suffix.

On initial run pass additional environment variables ROOT_NAME (default: admin) and SECRET (default: password). You can change password later as well using configuration support described below.

⁠Restarting LDAP Server

Whenever restarting container while providing the same host folder mounted as /config previously described environment variables are ignored. This is due to LDAP using runtime configuration folder now.

⁠Configuring LDAP Server

The container includes slapd-config⁠ script for adjusting slapd configuration at runtime:

docker exec -it <container-id> slapd-config db list

Replace <container-id> with ID of container started before so this command will show you list of existing databases.

See the script's README⁠ for additional examples.

For convenience there is a proxy script forwarding invocations of slapd-config to container. This is used in examples below.

Find examples of common configuration tasks below.

⁠Set Password of Root DN

By using proxy script for slappasswd available in docker container you don't need to install ldap client on host just to change a user's password.

./slappasswd -h '{SSHA}' -ns 'mysecretpw' | ./slapd-config db write mdb olcRootPW

⁠Setting SSL/TLS certificates

You need to provide pathnames of files as used inside container. So, if you use LetsEncrypt certificates you might want to copy latest version into folder mounted as /certs in container and invoke this command once for setting up.

./slapd-config ssl write /certs/cert.pem /certs/privkey.pem /certs/chain.pem

When setting certificate files for the first time container needs to be restarted so the container's control script will detect now existing files and start slapd with support for ldaps:/// connections.

./slapd-restart

⁠Injecting Additional Schemata

./slapd-config schema write custom </path/to/custom.schema

This is adding another schema named custom with its definition read from provided file on host.

⁠Controlling Access

By default any user is capable of reading any information in your directory. You should apply some access constraints. Here comes an example.

1. Create temporary file e.g. named temp with text editor containing this example set of access rules:

   to attrs=userPassword,shadowLastChange by self write by anonymous auth by * none
   to dn.base="" by * read
   to * by self write by * read
   

   Copy

   First rule prevents unauthenticated read access on user passwords (assuming proper schema has been injected before). The second is re-establishing initial rule granting any user read access on any information but user password etc. listed in first rule. The final rule is enabling any authenticated user adjusting its own node.

   You might want to use a different set most probably. For example, you should have another rule requiring any request satisfying a minimum security strength factor (ssf) to demand all users connecting via encrypted connection.

2. Invoke this command to apply the given set of rules on LDAP database:

   ./slapd-config db write-access mdb < temp
   

   Copy

⁠Initializing Directory Using Dump

When moving from one server to another you could dump the whole directory on existing server using command slapcat. This generates an LDIF file. Put this LDIF file into folder mounted as /import, make sure its name ends with .ldif and restart the container. The contained control script will try to add all files in that folder using slapadd prior to starting LDAP server.

On successful addition, provided files will be removed.

You may provide multiple LDIF files for input. The order of processing depends on either file's basename. Prefix either file's basename with two digits and a dash to customize processing order.

⁠Start Fresh

If there is no dump of an existing server you still need to import root object representing suffix configured before. Complying with example for invoking LDAP container given above you should put some file named init.ldif into folder mounted as /import in container. It should contain something similar to this:

dn: dc=yourserver,dc=com
objectClass: top
objectClass: dcObject
objectClass: organization
o: Your Company
dc: yourserver

Restart the container so the import is performed:

./slapd-restart

⁠Select Database For Import

By default all LDIF files are imported without selecting any particular database thus heading for the database of suffix configured before. If you need to import data to different database (e.g. to apply complex change of runtime configuration in order to enable some additional module) just rename the provided LDIF file to use the desired database's suffix as name plus mandatory extension .ldif.

⁠Import Schema Files

The import feature detects LDIF files defining some schema differently when named in compliance with this pattern:

<schema-name>.schema.ldif

1. Use the schema's internal name for naming the file.

   Since sorting order of processing files may be imported you can use two digits and a dash as prefix for controlling it. Any such prefix is ignored when it comes to deriving internal name of resulting schema.

2. Replace file's extension .ldif with .schema.ldif.

3. Place this file in import folder as described before.

Those files are basically processed on start-up as well. However there are two differences from a regular import:

1. The import is always targeting database at cn=config suffix.

2. The import of a file is skipped unless the schema named as part of file's name is missing in LDAP server.

Due to pre-selecting cn=config and due to file's name required to select a schema by name this feature can't be combined with selecting database for import as described before.

⁠Import Standard Schema Files

This container relies on OpenLDAP which is distributed with some commonly used schema files included. It is possible to import one of those by providing a schema definition file as described before that complies with these conventions:

1. Striping .schema.ldif off its filename results in name of a schema which is available.

   You may still use two digits and a dash as prefix for controlling sorting order of processing, though.

2. The provided LDIF file itself is empty.

For the first convention these schema names are available:

• collective
• corba
• core
• cosine
• duaconf
• dyngroup
• inetorgperson
• java
• misc
• nis
• openldap
• pmi
• ppolicy

The core schema is installed implicitly on first run of slapd thus you don't have to add it explicitly.

In conclusion, if you want to install cosine and inetorgperson schemata all you have to do is to provide two files named 01-cosine.schema.ldif and 02-inetorgperson.schema.ldif both without any content in designated import folder.

⁠Import Initialization Files

Another feature of file import regards files with extension .init.ldif instead of .ldif. Those files are assumed to either select a particular database as described before or to apply on "default suffix". Those files are imported unless the database's root node exists already.

data.init.ldif

will be processed if root node of default suffix selected by environment as described before is missing.

dc=different,dc=suffix.init.ldif

will be processed if root node of database selected by suffix dc=different,dc=suffix is missing.

⁠Client Tools

Some commonly useful LDAP client tools are available using proxy scripts, as well. By using them you can query the LDAP server in your container without requiring to install LDAP client tools on host first.

./ldapsearch -x -b dc=yourserver,dc=com