(ITS#6277) Missing documentation for cn=config

[ryans@aweber.com]

Full_Name: Ryan Steele
Version: 2.4.15
OS: Ubuntu 8.04 LTD
URL: ftp://ftp.openldap.org/incoming/
Submission from: (NULL) (207.106.239.81)


According to chapter 5 of the admin guide, "some of the backends and of the
distributed overlays do not support runtime configuration yet. In those cases,
the old style slapd.conf(5) file must be used."  However, there is no
documentation on which backends and overlays do and don't have said support. 
Without grokking the code, it is a trial-and-error operation at best.

Also, there is no documentation on how to add overlay-specific directives (man
pages or otherwise).  Take, for example, autogroup-attrset; the olcAGattrSet
directive is only described in autogroup.c, and nowhere else.  This is not the
only instance of missing module documentation, but it should give a general idea
of where to look.

Of course, grepping the code is easy enough, but you shouldn't have to do that
to learn how to achieve simple configurations. If there's going to be a
fundamental paradigm shift from slapd.conf to cn=config, there has to be
documentation (man pages, admin guide sections, et. al.) on the appropriate
methods for achieving what once was done through slapd.conf.  IMHO, that should
include concrete examples, such as the following, pulled from the Courier
documentation:

The following LDIF could be used to add [the auditlog] overlay to cn=config
(adjust to suit):

    dn: olcOverlay=auditlog,olcDatabase={1}hdb,cn=config 
    changetype: add
    objectClass: olcOverlayConfig
    objectClass: olcAuditLogConfig
    olcOverlay: auditlog
    olcAuditlogFile: /tmp/auditlog.ldif