Chapter 6.1.1: OpenLDAP using OLC (cn=config)

6.1.1.1 OLC (cn=config) Overview
6.1.1.2 Converting from slapd.conf to OLC (cn=config)
6.1.1.3 OLC (cn=config) Layout
6.1.1.4 Using OLC (cn=config)(Read, Modify)

cn=config Overview

Historically OpenLDAP has been statically configured, that is, to make a change to the configuration the slapd.conf file was modified and slapd stopped and started. In the case of larger users this could take a considerable period of time and had become increasingly unacceptable as an operational method. OpenLDAP version 2.3 introduced an optional new feature whereby configuration may be performed at run-time using a DIT entry called cn=config. The feature is known by a varied and confusing number of terms including on-line configuration (OLC) (our favorite), zero down-time configuration, cn=config and slapd.d configuration. First, a number of points:

The feature is (at version 2.4) still optional which means that slapd.conf, while formally deprecated, continues to work though many *nix distributions have made it the default installation configuration.
OpenLDAP has a history of being quite brutal about withdrawing support of older capabilities. This means that migration to on-line configuration (OLC, cn=config) should be contemplated as soon as practical. Better to do it when you don't need the new release than to be forced to take a new release because of a critical bug AND have to migrate to the new configration regime.
On-line configuration (OLC) uses a configuration DIT (with a hardcoded suffix of cn=config) to control the operational configuration. Conceptually by modifying entries in this DIT (using an LDAP Browser or LDIF files) immediate changes to slapd's operational behaviour are triggered without having to restart slapd as you would after making changes to slapd.conf.

Converting to use OLC (cn=config)

To create the OLC (cn=config) DIT you can EITHER create a series of LDIF files that describe the configuration and apply them using slapadd OR convert your existing slapd.conf. If you enjoy pain we recommend the former approach. If you are a normal human being - convert slapd.conf using the process described below. Conversion is a one time process (although it is reversable). From the time you have run the conversion the slapd.conf file is redundant. When loading slapd looks for the configuration directory (default slapd.d) and reads its configuration files from there and initializes the OLC (cn=config) DIT. If the slapd.d directory is not found then slapd looks for slapd.conf.

To migrate/convert from slapd.conf to on-line configuration (cn=config) do the following:

Make sure the slapd.conf configuration file is stable and reflects the required functionality. This is a precautionary measure and assumes familiarity with current slapd.conf based configuration. The last thing you want to do is to move to a major new feature and immediately need to use it. Best to have a bit of peace and tranquility and slowly acquire the required knowlege and expertise.
Stop the LDAP server.

Edit the slapd.conf file and add the following lines:

# before the first database definition
database config
# NOTE: the suffix is hardcoded as cn=config and 
# MUST not have a suffix directive
# normal rules apply - rootdn can be anything you want
# but MUST be under cn=config
rootdn "cn=admin,cn=config"
# use any of the supported password formats e.g. {SSHA} etc
# or plaintext as shown
rootpw config

There is a lot of drivel written about how to convert to slapd.d (cn=config) and it is all correct. However, if you want to actually use the cn=config feature (like reading and adding/changing attributes) using, say, an LDAP browser you must add the above lines.

Convert to on-line configuration (OLC) (cn=config) using the current slapd.conf file by running:
```
# uses slaptest (the most sensible method) but any utility which supports 
# -f file and -F dir arguments will perform the conversion 
# for example slapcat, slapadd etc.

# stop slapd
[fc]/etc/rc.d/init.d/slapd stop
# OR manually
killall slapd
# OR
[bsd]/usr/local/etc/rc.d/slapd.sh stop

[fc]cd /etc/openldap
[bsd]cd /usr/local/etc/openldap
# MUST - create standard default directory
mkdir slapd.d
# convert slapd.conf
slaptest -f slapd.conf -F slapd.d

# depending on the logged in user when you ran slaptest
# you may need to change ownership of slapd.d and all its files
chown -R ldap:ldap slapd.d
# permissions interestingly seem to need 
# a minimum of 0750
chmod -R 0750 slapd.d

# rename slapd.conf
# this step is not necessary but is a useful
# precaution to ensure you access slapd.d
mv slapd.conf slapd.conf.bak

# start slapd
[fc]/etc/rc.d/init.d/slapd start
# OR manually
slapd -u ldap -g ldap

# [bsd] users need to add
# slapd_cn_config="YES" to /etc/rc.conf
 
# if slapd fails to load use 
slapd -d -1 -u ldap -g ldap
# and debug
```
Notes:
1. Renaming the slapd.conf file after running the slaptest conversion is not essential but does ensure that you are using cn=config and not defaulting to use slapd.conf due to some error. The downside of renaming is that your standard start scripts may assume slapd.conf. Certainly that was the case with our FreeBSD start script (/usr/local/etc/rc.d/slapd) which failed to work because it assumes a slapd.conf file is present. We commented out the required_files line and the chown of slapd.conf line in the script - peace and tranquility reigned once more.
2. Beware: You can configure OLC (cn=config) to an unusable state. We changed the rootdn of cn=config via an LDAP browser from cn=config to cn=admin (an invalid change since all config elements must end with a root of cn=config). The change was however accepted. The connection was immediately broken (correctly) but we could not bind under any value - old or new. We stopped and tried to start slapd which also failed because it refused to load under our newly modified rootdn (cn=admin). The only solution was to edit slapd.d/cn=config/olcDatabase={0}config.ldif and restore the olcRootDn attribute to cn=config. We then loaded slapd, changed the olcRootDn attribute via an LDAP browser to cn=admin,cn=config and everything worked perfectly.
  
  The rootDn of cn=config can be anything but it MUST be UNDER cn=config, for example cn=manager,cn=config will work, but cn=manager,cn=admin will be accepted but will fail to allow cn=config access and slapd will subsequently fail to load.
3. Almost Conversion: If you want to see what the future looks like but feel a tad nervous about conversion or just want to do some testing then edit the slapd.conf as shown in step 3 above (add the database config stuff). Do not run the conversion as shown in step 4 but just load slapd. You will able to log into cn=config and change attributes at run-time but when you stop and start slapd they will all be lost. Well we said it was almost a conversion.
4. If you are insatiably curious it is well worth looking through the files and directories in the slapd.d directory once you have done the conversion. One day you may need to repair 'em.

To access the OLC (cn=config) feature from an LDAP browser assuming you have used the configuration above (otherwise modify the values used):

# Use the normal port and hostname settings with
# values shown are for LDAPBrowser/Editor
BaseDN cn=config
BindDN cn=admin,cn=config
password config

# alternatively you can use ldapsearch
ldapsearch -w config -x -D cn=admin,cn=config -b cn=config

If it all goes horribly wrong or you want to revert to old-fashioned(!) slapd.conf configuration (you have seen the future and it does not work for you yet) then the process is reversible:
```
# stop slapd
killall slapd
# OR
[fc]/etc/rc.d/init.d/slapd stop

[fc]cd /etc/openldap
[bsd]cd /usr/local/etc/openldap
# delete the slapd.d directory
rm -r slapd.d

# if you renamed slapd.conf as shown in the conversion
# procedure above you will need to restore slapd.conf
# then comment out the database config lines
# in slapd.conf
# now restart slapd
[fc]/etc/rc.d/init.d/slapd start
# OR manually
slapd -u ldap -g ldap
```
When you are feeling stronger and want to try again just repeat the conversion process. You can do this as often as you want. Note: If you modify the configuration in OLC (cn=config) mode deleting the slapd.d directory (shown above) will lose all the changes. Depending on what changes you have made, say an index change under cn=config, then you may have some restoration work to do if you revert to slapd.conf. In general, limit your use or experimentation with OLC (cn=config) features until you are committed to proceeding.

OLC (cn=config) Layout

The OLC (cn=config) DIT is laid out as shown below:

Notes:

The cn=config (root) entry (1) is based on the olcGlobal objectClass and contains the global attributes affecting the operation of slapd. On initial conversion this contains all the global directives from the slapd.conf file (as well as an exotic set of default values for directives which are not present) with the exception of included schemas - see cn=schema below - and dynamically loaded modules - see cn=module{0}. (Full list of olcGlobal attributes.)
The cn=module{Z} entry (2) is based on the olcModuleList objectClass and contains a list of all dynamically loaded objects and their paths. On initial conversion this contains the items defined by moduleload and modulepath directives from the slapd.conf file. Full list of olcModuleList attributes. If OpenLDAP is built using static overlays this entry will not be present. Adding/Deleting a module using OLC (cn=config).
The cn=schema,cn=config entry (3) uses the olcSchemaConfig objectclass and contains all the objects used by the cn=config system. (Full list of olcSchemaConfig attributes.) Note: The attributes/objectClasses are defined using the olcAttributeTypes and olcObjectClasses attributes respectively. Each Child entry defines an included schema.
The cn={Z}xxx,cn=schema,cn=config child entry (4) uses the olcSchemaConfig objectclass and contains all the objects (attributes and objectclasses) defined by the specific schema. The value {Z} is a numeric count starting from 0 and xxxx is the name of the schema. Thus, if the first included schema is core.schema then this value would be {0}core. (Full list of olcSchemaConfig attributes.) Note: The attributes/objectClasses are transformed from attributetype (when defined in the schema) into olcAttributeTypes attributes and from objectclass (when defined in the schema) into olcObjectClasses attributes when loaded by cn=config. Adding/Deleting schemas using OLC (cn=config)
The olcDatabase={Z}xxx,cn=config entry (5) uses the olcDatabaseConfig objectclass (which contains all the general attributes defined for a database) plus a database type specific objectclass. The value {Z} is a numeric count starting from 0 and xxxx is the database type name. Thus, if the first database definition is of type bdb then this value would be {0}bdb and the olcBdbConfig objectclass would contain the database type specific attributes. Full list of olcDatabaseConfig attributes. (Full list of olcBdbConfig attributes.) Child entries for each overlay used by the database may be present as described below. Adding/Deleting Databases using OLC (cn=config)

Note about olcDatabase={-1}frontend,cn=config entry: This entry is always present and looks horribly like a kluge to contain certain attributes in an olcFrontendConfig objectClasswhich have global'ish properties.
The olcOverlay={Z}xxx,olcDatabase={Z}xxx,cn=config entry (6) uses the olcOverlayConfig objectclass all the general attributes defined for an overlay plus a overlay specific objectclass. The value {Z} is a numeric count starting from 0 and xxx is the overlay name. Thus, if the first overlay definition is for the syncprov overlay then this value would be {0}syncprov and the olcSyncProvConfig objectclass would contain the overlay specific attributes. Similarly, other overlays will use overlay specific objectclasses to contain their unique attributes. (Full list of olcOverlayConfig attributes.) (Full list of olcSyncProvConfig attributes.) Adding/Deleting Overlays using OLC (cn=config).

6.1.1.4 Using cn=config

The OLC (cn=config) DIT can be read using standard LDAP command line tools such as ldapsearch and modified using ldapadd or ldapmodify which, IOHO, rather seems to defeat the objective of having a on-line configuration (OLC). The alternative is to use an LDAP browser to interactively read and write the attributes and entries. Access cn=config from LDAPBrowser/Editor.

6.1.1.4.1 OLC (cn=config) General Notes

The following notes may help when using OLC (cn=config) - then again, they may not:

OLC (cn-config) makes extensive use of {Z}value syntax (braces) within attributes (they have an X-ORDERED element in the attribute definition). This syntax represents an ordered set of attributes. As examples, where multiple schemas are present under cn=schema, cn=config they will have a value of cn={Z}xxxx,cn=schema,cn=config where Z is a sequential number stating from 0 and xxxx is the unique name of the schema. In the case where multiple ACPs/ACLs exist in the global section (under cn=conf) or a database section (under olcDatabase={Z}yyyy, cn=config - in this case Z will have the same meaning as before but yyyy will be the database type) each ACP/ACL will be defined by the olcAccess attribute and have the format {Z}to ...... In most, but not all, cases the editing principle is that if an attribute value is added and the brace form is supplied then the attribute will be added in the position defined by the brace value and any subsequent (displaced) attributes will be renumbered as necessary to maintain the ordered set. If the brace format is not used then the attribute will be added at the end of any numbered set of attributes prepended with the next sequential number in braces. This rule is very powerful and greatly simplifies the insertion (and deletion) of attributes/entries.
Recall that OLC (cn=config) by its nature operates on live data. Modifications are being made while the system is being accessed by its users. Suppose a two step modification is being made, say, purely for illustration, deletion of one attribute and modification of another attribute, the end result of which is some new, highly secure, regime. There is a period, it may or may not be extremely small depending on the nature of the change, when only one of the changes is effective. Users are, however, still using the system. It is vital to consider the state of the system after each change since there may be unintended exposure of data, or other equally gruesome effects, during this interim period. Murphy's law, the law of unintended consequences and every other law governing man-made distasters is constantly waiting to pounce on the unsuspecting, unprepared and naive. It may be that to overcome such 'interim state' problems the two step change may need to be a three, four or more step process.
As of OpenLDAP 2.4.31 it is not possible to delete any entries (attribute deletion is mostly allowed) under OLC (cn=config) using normal LDAP procedures such as ldapdelete or using an LDAP browser. In some cases, such as schemas, this restriction looks permanent in others there are rumours of changes. In all cases such entries may be removed either by reverting to a slapd.conf file making the appropriate changes and re-converting the file or by direct editing of the slapd.d definitions (generally discouraged for all but the most expert - but the process is described below for the adventurous, foolhardy or desperate. In general, due to the current formal restrictions on deletion it is wise to (a) ensure that your slapd.conf file is in good shape before deciding to convert to OLC (cn=config), (b) use the Almost Conversion process described above to experiment before committing to OLC (cn=config) permanently, (c) pray to your chosen god(s) - frequently.

6.1.1.4.2 Add/Delete Schemas using OLC (cn=config)

Adding Schemas

Note: When you initially convert to use OLC (cn=config) using the processes defined above all the included schemas are converted automatically. The following process is required only if you are adding a new schema file to an existing OLC (cn=config) configuration.

Standard LDAP schemas must be converted to LDIF format when used with OLC (cn=config). The resulting LDIF file is then imported using ldapadd or a suitable LDAP browser. Conversion from schema format may be done manually (if not large) or using the slaptest utility with a couple of manual edits which is the quickest method for large files. Both methods are shown below using a trivial schema file with a single attribute and a single objectclass just to illustrate the process (in both cases this file is an edited extract from the standard java.schema file so if you already use this schema and try to use the resulting LDIF from the examples it will fail since the objects already exist - subsitute your target schema instead). Even if your file is large it may be worth reading the Manual Conversion section if you want to understand the process in-depth.

Historically, OpenLDAP issued all its schemas in classic textual format with a .schema file suffix, for example, core.schema. Modern distributions provide both this format and an LDIF format for each schema which may be directly added to cn=config using a command like:

ldapadd -H ldap-url -x -W -D cn=config-bind-dn -f /path-to-schema-ldif

Beware: Once you have added a schema you cannot delete it other than by using a special and potentially dangerous manual process. You can - since 2.4 - modify existing attribute and objectclass definitions in installed or added schemas.

Manual Conversion

Target schema file to be added in the example (test.schema):

# modified java.schema -- Java Object Schema - used for example purposes only
# Copyright Notice
# 
#    Copyright (C) The Internet Society (1999).  All Rights Reserved.
# 
# Attribute definition

attributetype ( 1.3.6.1.4.1.42.2.27.4.1.6
	NAME 'javaClassName'
	DESC 'Fully qualified name of distinguished Java class or interface'
	EQUALITY caseExactMatch
	SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
	SINGLE-VALUE )
 

# Object Class Definition

objectclass ( 1.3.6.1.4.1.42.2.27.4.2.1
	NAME 'javaContainer'
	DESC 'Container for a Java object'
	SUP top
	STRUCTURAL
	MUST cn )

The file above will be edited to create an LDIF file which will add an entry containing all the attribute and objectClass definitions contained in the schema. For schemas these entries are placed under cn=schema, cn=config. We have chosen to use cn=test for the unique name of this schema (a more descriptive name should obviously be used for a real schema). Given this assumption we will load the new schema with dn: cn=test,cn=schema,cn=config. The objectClass used to add schemas is olcSchemaConfig (no MUST attributes which is tad strange, though the necessity of defining the cn attribute essentially makes this a MUST)) which uses the olcAttributeTypes (replacing attributetype) and olcObjectClasses (replacing objectclass)attributes to add the respective object definitions. Save the resulting file as test.ldif or some other appropriate name.

After the manual edit the file looks like this:

# manually edited file
# lines in red were added, lines in green were modified
# there must be one space at the beginning and end of each line 
# in the olcAttributeTypes and olcObjectClasses definitions

dn: cn=test,cn=schema,cn=config
objectClass: olcSchemaConfig
cn: test
olcAttributeTypes: ( 1.3.6.1.4.1.42.2.27.4.1.6 
 NAME 'javaClassName' 
 DESC 'Fully qualified name of distinguished Java class or interface'
 EQUALITY caseExactMatch 
 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )
olcObjectClasses: ( 1.3.6.1.4.1.42.2.27.4.2.1 
 NAME 'javaContainer' 
 DESC 'Container for a Java object' 
 SUP top 
 STRUCTURAL 
 MUST cn )

Use an LDAP browser or ldapadd to add test.ldif (or whatever you called it) file to the OLC (cn=config).

slaptest Conversion

The base schema file used is exactly the same as the one used for the manual conversion:

# modified java.schema -- Java Object Schema - used for example purposes only
# Copyright Notice
# 
#    Copyright (C) The Internet Society (1999).  All Rights Reserved.
# 
# Attribute definition

attributetype ( 1.3.6.1.4.1.42.2.27.4.1.6
	NAME 'javaClassName'
	DESC 'Fully qualified name of distinguished Java class or interface'
	EQUALITY caseExactMatch
	SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
	SINGLE-VALUE )
 

# Object Class Definition

objectclass ( 1.3.6.1.4.1.42.2.27.4.2.1
	NAME 'javaContainer'
	DESC 'Container for a Java object'
	SUP top
	STRUCTURAL
	MUST cn )

We now need to choose a suitable location and create a dummy slapd.conf file to include our test.schema. The dummy file (call it test.conf or something similar) looks like this:

include /path/to/test.schema

You can add as many include files as you like to this file - each one will create a separate ldif file. Now we create a directory (testdir) and run slaptest to convert our test.conf into this directory:

# create directory
mkdir testdir
# run slaptest
slaptest -f test.conf -F testdir

The resulting file will be testdir/cn=config/cn=schema/cn={0}test.ldif and will look something like this:

# AUTO-GENERATED FILE - DO NOT EDIT!! Use ldapmodify.
# CRC32 ed5d248b
dn: cn={0}test
objectClass: olcSchemaConfig
cn: {0}test
olcAttributeTypes: {0}( 1.3.6.1.4.1.42.2.27.4.1.6 NAME 'javaClassName' DESC 'F
 ully qualified name of distinguished Java class or interface' EQUALITY caseEx
 actMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )
olcObjectClasses: {0}( 1.3.6.1.4.1.42.2.27.4.2.1 NAME 'javaContainer' DESC 'Co
 ntainer for a Java object' SUP top STRUCTURAL MUST cn )
structuralObjectClass: olcSchemaConfig
entryUUID: 1cf25098-2f16-1031-9bb3-07590c97897d
creatorsName: cn=config
createTimestamp: 20120510180255Z
entryCSN: 20120510180255.489367Z#000000#000#000000
modifiersName: cn=config
modifyTimestamp: 20120510180255Z

Edit this file as shown below and save it as, say, test.ldif or whatever name takes your fancy:

# AUTO-GENERATED FILE - DO NOT EDIT!! Use ldapmodify.
# CRC32 ed5d248b
# lines in green have been edited, delete lines in red
dn: cn=test,cn=schema,cn=config
objectClass: olcSchemaConfig
cn: test
olcAttributeTypes: {0}( 1.3.6.1.4.1.42.2.27.4.1.6 NAME 'javaClassName' DESC 'F
 ully qualified name of distinguished Java class or interface' EQUALITY caseEx
 actMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )
olcObjectClasses: {0}( 1.3.6.1.4.1.42.2.27.4.2.1 NAME 'javaContainer' DESC 'Co
 ntainer for a Java object' SUP top STRUCTURAL MUST cn )
structuralObjectClass: olcSchemaConfig
entryUUID: 1cf25098-2f16-1031-9bb3-07590c97897d
creatorsName: cn=config
createTimestamp: 20120510180255Z
entryCSN: 20120510180255.489367Z#000000#000#000000
modifiersName: cn=config
modifyTimestamp: 20120510180255Z

Simply add test.ldif (or whatever you called it) to the OLC (cn=config) using an LDAP browser or ldapadd.

Notes:

Those of an insatiably curious disposition (or alternatively those of a highly cynical disposition) may want to understand why this stupid LDIF file has to be edited. Recall that we want to add this new schema to an existing operation configuration. Recall also that schema files already exist in the operational configuration in an ordered sequence. When slaptest does its dastardly work on our included schema file in our dummy slapd.conf file and converts it to an LDIF file it creates a relative ordered set, in the above case this is assumed to be {0}test. In the operational configuration we already have an entry with a {0} ordered value so we have a clash that will either be rejected on the load attempt, overwrite the existing {0} entry or do untold damage to the entire western hemisphere's electrical supply system (depends on which version of OpenLDAP you are using). By removing the {0} sequence number we are forcing OpenLDAP to add the schema at the end of the current schema entries in the operational configuration and allocate this new schema the next available sequence number. The lines in red are simply operational attributes that will be immediately regenerated with current values when we add the entry to the operational configuration. Phew.
A small wrinkle. Using the slaptest conversion method works just fine as long as any objectClass definitions refer only to attributes defined in this schema. If an attribute is contained in another schema slaptest does a check and will croak with AttributeType not found"xxxx". Manual edit time.

Deleting Schemas

It is not possible to delete an entire schema using normal OLC (cn=config) features though it is now - since 2.4 - possible to edit specific attributes (containing the definitions of attributes or objectclasses as shown in the manual conversion above) of any loaded schema. The lack of ability to delete a complete schema is a deliberate design decision by OpenLDAP and looks as if it will not be removed anytime soon - if ever. The reason for the decision is that it would be almost impossible to search through the entire database(s) for any attributes or objectclasses used in the schema being deleted and accept or reject the request on that basis. It is possible, under very precise conditions, to remove any schema by a manual process as shown below:

<warning> If any attribute or objectClass defined in a schema which is deleted by the following process (or any other process) is being used by any database, then that database will become unusuable. Repeat - unuseable. Worthless. Kaput. Be absolutely certain (and have backups/archives ready) that no database uses any attribute or objectClass contained in the schema to be deleted before trying to remove it using this (or any other) method.</warning>

Note: This kind of manual repair process is sometimes disparagingly called a cowboy edit by those who fail to understand the resourcefulness and inventiveness of that tough and hardy breed. Treat it as a compliment to be in such company.

To remove a schema from an operational OLC (cn=config) system, do the following:

Verify the DN of the schema that you wish to delete by reading the cn=schema, cn=config subtree with an LDAP browser or using ldapsearch. Schemas all have a DN of the form cn={Z}xxxx, cn=schema, cn=config. As an example, if you added the schema above it will have a DN similar to cn={6}test,cn=schema, cn=config (the value 6 inside the braces may be higher or lower depending on how many schemas have been loaded). Note this value.
Stop slapd. Navigate to the slapd.d directory(normally [fc]/etc/openldap/slapd.d or [bsd] /usr/local/etc/openldap/slapd.d) and copy the entire directory and its subdirectories and files to a sensible location (this copy can be used to restore everything in the event of problems).
From the slapd.d directory navigate ->cn=config ->cn=schema. In this directory you will find all the schema LDIF files including the file (using the assumption above) cn={6}test.ldif (recall that the value 6 may vary depending on how many other schemas you have loaded). Delete this file (you did make a full copy of the slapd.d directory in step 2 - didn't you?).
If the ldif file you removed had the highest value in braces in this directory skip to the next step. If not, rename all the files with higher values inside the braces in this directory to create a contiguous series starting from 0. Thus, if you remove cn={6}test.ldif but have a file with, say, the name cn={7}splodge.ldif then rename this file to cn={6}splodge.ldif to create a contiguous set.
Take a deep breath and restart slapd. Verify the deleted schema has indeed been deleted.
If things go wrong, immediately stop slapd check any logs for error messages. Restore the entire slapd.d directory and its subdirectories and files copied in step 2 and restart slap. Then try and figure what the devil happened. However, seppuku rarely offers an effective solution.

6.1.1.4.3 Add/Delete ACPs/ACLs using OLC (cn=config)

ACPs/ACLs may appear, as normal, in the global section (in the cn=config entry) or in a database section (under olcDatabase={Z}type, cn=config). In both cases each ACP/ACL is contained in an olcAccess attribute which is part of an ordered set - each attribute starts with a sequential number, starting from 0, contained within braces as shown in the example below (lines are shown split for fomatting puposes only):

olcAccess: {0}to attrs=userpassword  by self write  by anonymous auth  by gro
 up/groupOfNames/member.exact="cn=itpeople,ou=groups,dc=example,dc=com" write
   by * none
olcAccess: {1}to attrs=carlicense,homepostaladdress,homephone  by self write 
  by group/groupOfNames/member.exact="cn=hrpeople,ou=groups,dc=example,dc=com
 " write  by * none
olcAccess: {2}to *  by self write  by group/groupOfNames/member.exact="cn=hrp
 eople,ou=groups,dc=example,dc=com" write  by users read  by * none

Adding an ACL/ACP using the olcAccess attribute (using ldapmodify or an LDAP browser) starting with {1}to... ... in the above example will cause it to be placed immediately below the attribute starting with {0} and subsequent attributes will be renumbered as shown:

olcAccess: {0}to attrs=userpassword  by self write  by anonymous auth  by gro
 up/groupOfNames/member.exact="cn=itpeople,ou=groups,dc=example,dc=com" write
   by * none
olcAccess: {1}to ... ...
olcAccess: {2}to attrs=carlicense,homepostaladdress,homephone  by self write 
  by group/groupOfNames/member.exact="cn=hrpeople,ou=groups,dc=example,dc=com
 " write  by * none
olcAccess: {3}to *  by self write  by group/groupOfNames/member.exact="cn=hrp
 eople,ou=groups,dc=example,dc=com" write  by users read  by * none

If the new attribute is added without the {} syntax then it is appended to the end of the attribute set and allocated the next sequential number as shown below:

olcAccess: {0}to attrs=userpassword  by self write  by anonymous auth  by gro
 up/groupOfNames/member.exact="cn=itpeople,ou=groups,dc=example,dc=com" write
   by * none
olcAccess: {1}to attrs=carlicense,homepostaladdress,homephone  by self write 
  by group/groupOfNames/member.exact="cn=hrpeople,ou=groups,dc=example,dc=com
 " write  by * none
olcAccess: {2}to *  by self write  by group/groupOfNames/member.exact="cn=hrp
 eople,ou=groups,dc=example,dc=com" write  by users read  by * none
olcAccess: {4}to ... ...

When modifying or deleting any olcAccess attribute you must use the {} syntax to identify the specific attribute.

6.1.1.4.4 Add/Delete Modules using OLC (cn=config)

Add Modules

Dynamic run-time modules are defined in the cn=Module{0},cn=config entry using the olcModuleList objectclass with the module being defined using the olcModuleLoad attribute. Simply adding another attribute defining the required module (without using the {} syntax) will enable it to be loaded. This assumes two dependencies are satisfied. First, that the module exists (it was created when the software was installed) and second that it exists in either the default path(s) or the path defined by an olcModulePath attribute which is SINGLE-VALUE - only one is allowed (but a colon or semicolon separated list is allowed - see format specification). olcModuleLoad should be added without the use of {} syntax (there seems little, if any, point in changing the order of dynamically loaded modules) resulting in the new module being added to the attribute set and being given the next sequential ordered set number. If the module name is invalid (not one of the valid set for OpenLDAP) the request to add the attribute will be rejected but if the module is compiled into the base (and no corresponding dynamic module exists) the attribute will be added (but is essentially redundant).

Deleting Modules

You cannot delete any olcModuleLoad attribute as a matter of (current) OpenLDAP implementation policy. Rather strangely attempts to delete the attribute are rejected with error 80 (unknown error - with a good text description) rather than error 53 (Server unwilling to perform).

6.1.1.4.5 Add/Delete Databases using OLC (cn=config)

Adding Databases

Databases are defined using the olcDatabaseConfig objectClass with a MUST attribute of olcDatabase and a database type specific ojectClass which allows definition of the type specific attributes used for the database definition. For example, when a database type of bdb is defined the olcBdbConfig (which has a MUST attribute of olcDbDirectory) is used. The entries created are an ordered set (uses {} syntax) of database types of the form olcDatabase={Z}xxx,cn=config. Where Z is a sequential order number and xxxx is the database type. If the order syntax ({}) is used when adding a new database it will - since 2.4 - be added in sequence and any subsequent databases will be renumbered. If the order syntax is omitted it will be appended to the current list and the next sequential order number prepended.

Life is too short for this nonsense, but: In practise, even though it is not a MUST attribute, the olcSuffix attribute needs to be present or the entry will fail to be created with error 80 fail setup. Sigh.

As an example, assume that the current configuration has database entries of olcDatabase={0}config, cn=config and olcDatabase={1}bdb,cn=config then the following minimal definition will create an entry with the DN olcDatabase={2}bdb, cn=config.

# order value {} not present so entry will be appended 
# to current children
# Note: olcBdbConfig has a sup of olcDatabaseConfig
# and has been omitted - add objectclass: olcDatabaseConfig
# if you enjoy typing stuff
dn: olcDatabase=bdb,cn=config
objectClass: olcBdbConfig
olcDatabase: bdb
olcDbDirectory: /var/db/new-db
olcSuffix: dc=example,dc=net
# if you want DIT SuperUser add
olcRootDN: cn=something,dc=example,dc=net
olcRootPW: somesecret

Because the above entry was created without using the ordering syntax (there is no {Z} value) it is appended to the end of the current ordered set and given the next, in this example case {2}, sequential number. It would have been perfectly acceptable to have used the value olcDatabase: {2}bdb (with an appropriate change also in the dn: line) to achieve the same result. However, if the value olcDatabase: {1}bdb (again with the appropriate change to the dn: line) had been used in our assumed configuration the database with an ordered value of {1} would have been renumbered as {2}, that is the new database would have been inserted in its ordered set sequence. The only must attributes to create an olcDatabase entry are olcDatabase and olcDbDirectory (though the entry creation will croak without olcSuffix). Additional attributes (including such obvious ones as olcRootDN and olcRootPW) could obviously be added when the entry is created, or subsequently. Recall that the directory (defined by the olcDbDirectory attribute) must exist (and with the right permissions) prior to it being used, that is, before the new database entry is created.

Deleting Databases

As of OpenLDAP 2.4.31 you cannot delete a Database entry. Any attempt will fail with error 53 (Server unwilling to perform) which looks pretty definitive. There are vague rumours that experimental code is available but that's it.

There are a number of ways to handle this issue:

By deleting the olcRootDN and olcRootPassword attributes in cn=config and deleting all the database files (with slapd stopped) defined in the olcDbDirectory attribute the Database still exists but in name only. Note: The database directory should not be deleted only the files. When slapd restarts it will initialize new (empty) database files which, apart from occupying disk space, are harmless.
Create a new OpenLDAP system with only the required DITs and either configure syncrepl to copy across the required DITS or use LDIF to export and import.
You can remove the Database by manually editing the slapd.d directory and its associated .ldif files. This is described below.

<warning> Be aware that any referrals to a deleted database will have a negative effect on operations - translation: a database containing one or more referrals to a deleted (non-existant) LDAP database will give errors (made worse by the fact that most LDAP browsers are defaulted to automatically follow referrals). Such referrals will have to be manually modified using an LDAP browser or LDIF.

As an example, assume that the current configuration has database entries of olcDatabase={0}config, olcDatabase={1}monitor, olcDatabse={2}bdb and olcDatabse={3}bdb. Now assume we want to delete olcDatabase={2}bdb. The following procedures does this:

Note: This is not a trivial procedure. Proceed with caution. Make sure you back-up (copy) the slapd.d directory before starting. It can always be restored in the case of an error.

Verify the DN of the database that you wish to delete by reading the cn=config tree with an LDAP browser or using ldapsearch. Databases all have a DN of the form olcDatabase={Z}xxx. As an example, if you added the Database above it will have a DN similar to olcDatabase={3}bdb (the value 3 inside the braces may be higher or lower depending on how many Databases are present). Note this value. Confirm this is the right database by reading the olsSuffix attribute. You really don't want to spend a heart-stopping editing session deleting the wrong Database. Modify the following instructions based on the {Z} value of the Database you want to delete.
Stop slapd. Navigate to the slap.d directory (normally [fc]/etc/openldap/slapd.d or [bsd] /usr/local/etc/openldap/slapd.d) and copy the entire directory and its subdirectories and files to a sensible location (this copy can be used to restore everything in the event of problems).
From the slapd.d directory navigate ->cn=config. In this directory you will find all the Database LDIF files including the file olcDatabase={2}bdb.ldif that we wish to delete (modify the {Z} value based on your actual needs). In addition you will also find directories for these Databases of the form olcDatabase={Z}xxx (no .ldif). Assuming we want to delete olcDatabase={2}bdb then delete the file olcDatabase={2}bdb.ldif and the directory olcDatabase={2}bdb (you did make a full copy of the slapd.d directory in step 2 - didn't you?).
If the ldif file you removed had the highest value in braces ({Z} index) in this directory skip to the next step. If not, rename all the files with higher values inside the braces in this directory to create a contiguous series starting from 0. Thus, if you remove olcDatabase={2}bdb.ldif but have a file with, say, the name olcDatabase={3}bdb.ldif then rename this file to olcDatabase={2}bdb.ldif to create a contiguous set. Rename the corresponding directories. Thus, if you remove the directory olcDatabase={2}bdb but have a directory with, say, the name olcDatabase={3}bdb then rename this directory to olcDatabase={2}bdb to create a contiguous set. Repeat for all olcDatabase={Z}.xxx.ldif files and olcDatabase={Z}.xxx directories until you have a contiguous series.
The final step is to edit the various olcDatabase={Z}xxx.ldif files to change their internal DN. Again assuming that we have deleted the original olcDatabase={2}bdb.ldif (and its corresponding directory) our current olcDatabase={2}bdb.ldif file (and its corresponding directory) are simply copies of our previous olcDatabase={3}bdb.ldif file (and its corresponding directory) and contain information relevant to the old {Z} value, which in our assumed case is {2}. Edit the file olcDatabase={2}bdb.ldif with your favorite editor as shown:
```
vi olcDatabase={2}bdb.ldif
# will show something like that below
dn: olcDatabase={3}bdb
...
olcDatabase: {3}bdb
...

# edit these two values to 
# (or whatever your Z value is)
dn: olcDatabase={2}bdb
olcDatabase: {2}bdb
```
Repeat this process for all olcDatabase={Z}xxx.ldif files whose {Z} index is above (is > than) the one deleted to again create a contiguous set.
We're done. Take a deep breath and restart slapd. Verify the deleted Database has indeed been deleted. You may also want to consider deleteing all the associated database files in the olcdirectory path.
If things go wrong, immediately stop slapd check any logs for error messages. Restore the entire slapd.d directory and its subdirectories and files copied in step 2 and restart slap. Then try and figure what the devil happened. However, seppuku rarely offers an effective solution.

6.1.1.4.6 Add/Delete Overlays using OLC (cn=config)

Adding Overlays

Overlays are described in child entries to the relevant olcDatabse={Z}xxx,cn=config entry to which they apply using the generic objectClass olcOverlayConfig (MUST attribute olcOverlay) and an overlay-specific objectClass (which always has a SUP of olcOverlayConfig) which is a container for the overlay-specific attributes. For example, the overlay syncprov (replication) uses an objectclass of olcSyncProvConfig (no MUST attributes). If the overlay uses an dynamically loaded module then this must be added before the overlay. The following minimal definition will add a new syncprov entry as a child of the database entry olcDatabase={1}bdb,cn=config:

dn: olcOverlay=syncprov, olcDatabase={1}bdb,cn=config
objectclass: olcSyncProvConfig
olcOverlay: syncprov

Because the above entry was created without using the ordering syntax (there is no {Z} value) it is appended to the end of the current ordered set and given the next, or in the first case {0}, sequential number. It would have been perfectly acceptable, assuming this is the first entry, to have used the value olcOverlay: {0}syncprov (with an appropriate change also in the dn: line) to achieve the same result. Recall that the order in which overlays are defined determines the order in which they are processed which can be significant in many cases. In this case the ordered set syntax ({Z}) can be used to insert an overlay in its correct order (all following entries are renumbered to maintain the ordered set). Additional attributes could obviously be added when the entry is created, or subsequently.

Deleteting Overlays

This may come as a surprise but....as of OpenLDAP 2.4.31 you cannot delete an Overlay entry. Any attempt will fail with error 53 (Server unwilling to perform) which looks pretty definitive. There are vague rumours that experimental code is available but that's all for now folks. A variation of the technique identified for removing extraneous schemas could be used to delete any offending overlays(s). Proceed with caution as always.

Problems, comments, suggestions, corrections (including broken links) or something to add? Please take the time from a busy life to 'mail us' (at top of screen), the webmaster (below) or info-support at zytrax. You will have a warm inner glow for the rest of the day.