How to add a schema in OpenLDAP 2.4

In version prior to 2.4, administrators were used to configure slapd through its /etc/ldap/slapd.conf. That was good ol' time.

Since version 2.4, slapd configuration is stored right in itself !. This may sound as a good idea, but is really unpractical: administrators needs to really master LDAP now to configure slapd: use ldapmodify/ldapsearch/ldapadd, or delve into some LDIF files. Also, simple tasks (as adding a schema definition to the server) are now quite tedious. Although the complete configuration is accessible as ldif files, I concider ldif file format as XML: it's way too verbose and tedious to read and be maintained by a human being. And above all, it's yet another language to master.

In last Ubuntu as of 2010-03-06, this change was not correctly reported in LDAP servers documentation. These are 2 bug reports on this issue: Bug #463684, Bug #442498. A quick glance to these bug reports will show you that this changement is a great source of distress for a lot of casual administrators (as I am).

The last documentation from Ubuntu has not explained the changes and is not that clear.

EDIT (2012-01-05): the last link have now some valuable information despite the fact that it seems not anymore maintained. I would rather hint towards the community help site page on OpenLDAP of ubuntu, which seems a natural and well documented point to get information.

What is the reason behind this change ?

First, openldap changed it's default way to store configuration files. The idea is simple: The configuration is stored in a SEPARATE ldap database identified by the prefix "cn=config". And you'll be able to declare separate databases with different credentials, or backend (bdb or hdb for instance).

With this new way of using the configuration, you can make changes to configuration without restarting slapd.

This thread post is quite clear on what is going at Ubuntu around OpenLDAP.

How to use the config database ?

The configuration database does not need any password for root system user on local connection. You can see its content with ldapsearch this way:

sudo ldapsearch -Y EXTERNAL -H ldapi:/// -b cn=config


if you are on ubuntu, ldapsearch is available in ldap-utils package.

This database contains roughly:
  • some basic slapd daemon configuration parameters (pid file, loglevel ...)
  • loaded schemas
  • and databases configuration

To make addition to this database you'll need to inject ldif files for example through ldapadd:

sudo ldapadd -Y EXTERNAL -H ldapi:/// -f file.ldif

Or, better, use tool like ldapvi

sudo ldapvi -h ldapi:/// -D cn=config -Y EXTERNAL -b cn=config
You'll need to make additions/modifications to this database to:
  • add new schemas
  • add new databases (and you'll require to create at least one database)
  • add indexes to databases
  • modify LogLevel
  • ...

How to add a new schema ?

This is the common way to add a schema:

sudo ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/nis.ldif

How to add a new database ?

The following method will require that nis schema was loaded as it defines rule on the shadowLastChange attribute that is defined in this schema.

Then copy-paste this code into a ldif file /tmp/database.ldif:

# Load dynamic backend modules
dn: cn=module,cn=config
objectClass: olcModuleList
cn: module
olcModulepath: /usr/lib/ldap
olcModuleload: back_hdb

# Database settings
dn: olcDatabase=hdb,cn=config
objectClass: olcDatabaseConfig
objectClass: olcHdbConfig
olcDatabase: {1}hdb
olcSuffix: dc=example,dc=com
olcDbDirectory: /var/lib/ldap
olcRootDN: cn=admin,dc=example,dc=com
olcRootPW: secret
olcDbConfig: set_cachesize 0 2097152 0
olcDbConfig: set_lk_max_objects 1500
olcDbConfig: set_lk_max_locks 1500
olcDbConfig: set_lk_max_lockers 1500
olcDbIndex: objectClass eq
olcLastMod: TRUE
olcDbCheckpoint: 512 30
olcAccess: to attrs=userPassword by dn="cn=admin,dc=example,dc=com" write by anonymous auth by self write by * none
olcAccess: to attrs=shadowLastChange by self write by * read
olcAccess: to dn.base="" by * read
olcAccess: to * by dn="cn=admin,dc=example,dc=com" write by * read
You should change:
  • dc=example,dc=com with your own prefix
  • 'secret' value of olcRootPW should be updated by your password.

EDIT (2012-01-05): You will have to remove the first part about loading the hdb module if you are in recent ubuntu installation, as it is already loaded, and will trigger a fatal error preventing the following ldapadd command to work as expected.

EDIT (2013-12-30): An existing database was created by ubuntu before installation and can spew very annoying error message and block slapcat. Unfortunately, you can't delete it with ldapvi. The best way I found was to stop slapd, then cd /etc/ldap/slapd.d/cn=config, remove olcDatabase={1}hdb.ldif file, and relaunch slapd. Please check that content of the file removed is the one mentionning nodomain.

Once you've created this file, you can add your new database with:

sudo ldapadd -Y EXTERNAL -H ldapi:/// -f /tmp/database.ldif

You can then remove /tmp/database.ldif.

Notice that slapcat should work only after having configured a database. Without any database you'll get this error:

$ slapcat
Available database(s) do not allow slapcat

Because cn=config database doesn't allow slapcat and no other database has been configured.

  • mike

    very nice overview of ldap