Why OpenLDAP Configuration Matters
OpenLDAP's configuration is foundational to the stability, security, and interoperability of any directory service it provides. Whether OpenLDAP is supporting authentication, directory search, or acting as a backend for user management, misapplied or misunderstood configuration directly leads to system outages, security flaws, and operational headaches. For developers and administrators integrating OpenLDAP—especially in environments where directory reliability is paramount—knowing exactly how and where to configure the service is critical. A misstep can expose sensitive data, break schema extensions, or render even basic authentication impossible.
OpenLDAP Configuration Paradigms: slapd.conf vs slapd.d
OpenLDAP supports two mutually exclusive configuration paradigms: the legacy static slapd.conf file and the dynamic slapd.d (also called cn=config) directory. It is essential to recognize which configuration mode is in use, as they are structurally and operationally different.
slapd.conf is a single, text-based configuration file. Directives are grouped by their scope—global, backend, or database—and are read once when the server starts. Any configuration change requires a restart of slapd.
slapd.d (cn=config) is a directory containing configuration as a tree of LDIF (LDAP Data Interchange Format) files, mapping directly to an internal LDAP configuration tree. With slapd.d, changes can be made at runtime through LDAP operations—no restart is required for most modifications. The shift to slapd.d was to enable dynamic, live configuration and to support fine-grained access and automation.
Only one configuration backend is used at a time: recent OpenLDAP versions default to slapd.d, and if a slapd.d directory is present, slapd.conf is ignored. These two modes cannot be mixed.
Configuration File Structure and Inheritance
Both configuration paradigms separate settings into three scopes:
- Global: Parameters affecting the entire service.
- Backend: Options for a storage backend (like bdb, hdb, or mdb).
- Database: Database-specific settings tied to a particular suffix (directory root).
slapd.conf Structure:
- All configuration is contained in a single file, typically located at
/etc/openldap/slapd.conf. - Inheritance is strictly top-down: global directives apply unless overridden in a backend section, which are in turn overridden by database-specific settings.
slapd.d Structure:
- Configuration is held in LDAP entries under
cn=config, organized in directories such ascn=config,cn=schema,cn=config,olcDatabase={x}*,cn=config, etc. - Inheritance is explicit via object relationships in the configuration DIT (Directory Information Tree).
- The files reside by default under
/etc/openldap/slapd.d/(location may vary by distribution) and are not meant for direct editing.
With slapd.d, configuration changes are applied live through the LDAP protocol—meaning updates are atomic and can be performed while the server is running.
Managing and Modifying OpenLDAP Configuration
Static configuration with slapd.conf
Configuration is changed by editing the plain text file and then restarting the slapd server. Comments and documentation are supported and preserved.
Dynamic configuration with cn=config
Do not edit slapd.d directly
Change cn=config through LDAP operations such as ldapadd and ldapmodify. Editing files inside slapd.d can corrupt the LDIF structure and invalidate the server configuration.
Schema Management in OpenLDAP
Schemas define the types of entries and attributes your directory can store.
Schemas with slapd.conf
Schemas are included as files using include directives within slapd.conf. Official schema files, like core.schema, are loaded by reference and must not be modified directly; to extend the schema, a new custom file should be created and included.
Schemas with slapd.d
Schemas are represented as entries under cn=schema,cn=config in slapd.d. Schema changes or extensions must be performed using LDAP operations—not by editing LDIF files. This approach allows schemas to be updated at runtime, but, unlike slapd.conf, documentation and comments are not embedded in these configuration entries. Administrators should track schema modification documentation externally.
Altering distributed OpenLDAP schema files directly is not recommended, regardless of configuration mode. Instead, copy the supplied schema, modify the copy, and load it as an additional schema.
Security and Best Practices
- TLS/LDAPS: Always configure TLS (StartTLS or LDAPS) to protect credentials and sensitive data in transit.
- Access Controls (ACLs): Use precise access control lists to ensure only authorized users can read or manipulate directory data.
- File Permissions: The configuration directory (slapd.d) or file (slapd.conf) must be owned by the user running slapd, with restrictive permissions to prevent unauthorized access or tampering.
- Network Exposure: Limit slapd’s listening interfaces and firewall appropriately to restrict access to legitimate clients.
- Schema Extension: Never alter official schema files in-place; extend by copying and modifying as needed.
Migrating from slapd.conf to slapd.d
Migration from slapd.conf to slapd.d is required for modern, dynamic configuration workflows and newer OpenLDAP versions. The migration involves converting the static configuration into LDIF files suitable for slapd.d.
- Use the
slaptestutility to convert:slaptest -f /path/to/slapd.conf -F /path/to/slapd.d/ - Copy original schema and configuration files for reference in case troubleshooting or rollback is needed.
- Be aware that comments in slapd.conf are not carried over; slapd.d LDIF entries do not support comment preservation. Documentation should be maintained externally.
- Before migrating on a production system, test the generated slapd.d on a non-production instance, and always backup both original and generated configurations.
Troubleshooting: Common Errors and How to Avoid Them
File Permission Errors: The most frequent cause of slapd startup failures is incorrect ownership or permissions of configuration files/directories. Ensure slapd.d and all contained files are writable and readable by the slapd user.
DN and Syntax Errors: Wrong distinguished names (DNs) in configuration, or misplaced LDIF formatting in slapd.d, will cause server failures. Pay special attention to blank lines and attribute placement in LDIF files when adding or modifying entries via LDAP tools.
Editing slapd.d Files by Hand: Direct edits to slapd.d LDIF files are a frequent cause of corruption. Always use ldapmodify/ldapadd.
Schema Load Failures: Attempting to modify bundled schema files or referencing invalid schema files will prevent the directory from accepting entries.
For rapid troubleshooting, consult OpenLDAP logs, double-check file permissions, and verify that configuration changes occur through the prescribed mechanisms for your configuration mode.
Frequently Asked Questions and Misconceptions
Can I safely edit files in the slapd.d directory directly?
No. Direct edits are unsupported and can corrupt the configuration. Always use LDAP tools.
Can slapd.conf and slapd.d operate together?
No. Only one configuration backend is active. Presence of slapd.d disables slapd.conf processing.
How are configuration comments preserved in slapd.d?
They are not. Comments from slapd.conf do not migrate, and slapd.d's LDIF files do not support in-file comments. Keep separate documentation.
Should I edit default schema files to extend the schema?
No. Official schema files must remain unmodified. Always use copies for schema extensions.
Building Reliable OpenLDAP Deployments
Effective and secure OpenLDAP operations demand a thorough understanding of the active configuration paradigm. For new deployments, slapd.d is the durable, flexible choice. Always:
- Confirm your configuration mode.
- Use supported tools and workflows for configuration and schema management.
- Maintain external documentation for schema and configuration changes.
- Secure slapd at both the configuration and network level.
- Test migrations and changes prior to production rollouts.
By following these practices and being mindful of the structural differences between slapd.conf and slapd.d, you can avoid many common pitfalls, ensure operational stability, and confidently extend your directory service.