mail us  |  mail this page

contact us
isp services  | 
company  | 
products  | 
support  | 

Chapter 6: OpenLDAP using cn=config

OpenLDAP overview cn=config
Converting from slapd.conf to cn=config
Using cn=config


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 run-time configuration (RTC) (our favorite), zero down-time configuration, cn=config and slapd.d configuration. First a number of points:

  1. The feature is (at version 2.4) still optional which means that slapd.conf will continue to work.

  2. OpenLDAP has a history of being quite brutal about withdrawing support of older capabilities. This means that migration to run-time configuration 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.

  3. Run-time configuration 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 LDAP Browser or ldapadd'd LDIF files) immediate changes to slapd's operational behaviour are triggered without having to reload slapd as you would after making changes to slapd.conf.

Converting to use cn=Config

To create the 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 defined 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 cn=config DIT. If the slapd.d directory is not found then slapd looks for slapd.conf.

To migrate/convert from slapd.conf to run-time configuration (RTC or cn=config) do the following:

  1. Make sure the slapd.conf configuration file is stable and reflects the required functionality. This is a precautionalty 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 require to use it. Best to have a bit of peace and tranquility and slowly acquire knowlege.

  2. Stop the LDAP server.

  3. 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.

  4. Convert to run-time configuration (RTC) (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/ 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 *
    # 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
    # if slapd fails to load use 
    slapd -d -1 -u ldap -g ldap
    # and debug


    1. Unlike slapd.conf, cn=config files maintained in slapd.d require read and write permission for the user/group under which you run slapd (normally ldap). We ran the slaptest conversion under root which left us with unaccessible files and the load defaulted to use slapd.conf not cn=config. Assuming you are running slapd under user ldap (-u ldap) issue the chown for ldap:ldap as shown. File permissions of 0600 keep tight access to the files and should not require changing.

    2. 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/ 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.

    3. Beware: You can configure 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 oldRootDn 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.

    4. 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.

    5. 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.

  5. To access the 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
  6. 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) 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 stonger 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 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 cn=config features until you are committed to proceeding.

Up Arrow

Using cn=config

The 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 run-time configuration. The alternative is to use an LDAP browser to interactively read and write the attributes and entries. Access cn=config from LDAPBrowser/Editor.

Up Arrow

Copyright 1994 - 2010 ZyTrax, Inc.
All rights reserved. Legal and Privacy
site by zytrax
Hosted by
web-master at zytrax
Page modified: September 22 2008.


tech info
guides home
1 objectives
big picture
2 concepts
3 ldap objects
4 install ldap
5 samples
6 config files
7 replicate & refer
8 ldif
9 protocol
10 ldap api
11 howtos
12 trouble
13 performance
14 ldap tools
15 security
notes & info
ldap resources
rfc's & x.500
ldap objects
change log

Creative Commons License
This work is licensed under a Creative Commons License.

If you are happy it's OK - but your browser is giving a less than optimal experience on our site. You could, at no charge, upgrade to a W3C STANDARDS COMPLIANT browser such as Mozilla

add page to facebook add page to add page to add page to add page to add page to stumbleupon add page to mail this page feature print this page

RSS Feed Icon RSS Feed





GNU-Free SW Foundation


Open Source Initiative
Creative Commons


Ibiblio - Library
Open Book Project
Open Directory

printer friendly

Print Page

SPF Record Conformant Domain Logo