RE: Overlay Documentation

["Howard Chu" <hyc@highlandsun.com>]

> -----Original Message-----
> From: owner-openldap-devel@OpenLDAP.org
> [mailto:owner-openldap-devel@OpenLDAP.org]On Behalf Of Pierangelo
> Masarati

> > I posted a suggestion about the "proxy cache" chapter in the issue
> > tracking system some time ago.
> > In the meantime I played around with the overlay cache. I
> found out that
> > documentation is not very aligned with what the sw is
> actually doing.
> > Therefore I would propose to review the chapter in order to align it
> > more to the actual release.

At this point any difference betwen the code and the doc must be a bug in the
code, because the doc looks right to me... Please point out the
inconsistencies in an ITS report.

> Sure.  I think we should consider the opportunity to document
> the overlay
> mechanism from the user's, but also from the developer's
> perspective,
> and
> find an appropriate place for this documentation in the admin
> guide, as
> the API is freezing.

There has never been any formal documentation of slapd internal APIs before.
I guess the Admin guide is an OK place for it. That would probably be cleaner
than several individual slapd(3) manpages.

> In this framework the documentation of
> the currently
> available overlays could fit more easily.  The most
> authoritative sources
> of info (apart from the code :) currently are:
>
> slapd.conf(5):    how overlays are staked on a database
> slapd-meta(5):    what parameters are given to the proxycache
>                   overlay, and what's its behavior
> slapd-ppolicy(5): a clean and detailed description of how
>                   this overlay works
> slapd-relay(5):   a description of how the (yet incomplete)
>                   rewrite-remap overlay works within the
>                   back-relay to provide DN rewrite and
>                   attributeType/objectClass mapping in relaying
>                   virtual to real naming contexts.
>
> I think we should:
> 1) define a place for overlay documentation and a naming
>    convention for man pages, to separate them from backend man pages

ovl-<name>.5 ?

> 2) document the other currently available overlays, i.e.
>    chain (move it from back-ldap/ into overlays/ ?), denyop,
>    and dyngroup

I figured chain and back-ldap are intimately tied together, so I didn't split
it out. On the other hand, the proxy-cache overlay doc should probably be
pulled out of the slapd-meta manpage.

> 3) define a convention for overlay-specific statements, at least
>    for future ones, to avoid potential name clashing with database
>    specific names (e.g. "<overlay name>-<statement name>" ?);
>    overlays like "chain", which is essentially an invocation of
>    the back-ldap backend, could be implemented by intercepting
>    the prefix "<overlay name>-" and removing it from argv[0]
>    before invoking the ldap_back_db_config() function.
> 4) provide working examples of all overlays.
>
> I'd volunteer for harmonizing the statement naming and for
> separating the chain overlay from back-ldap.  It is questionable
> whether we sould preserve compatibility with the current overlay
> statement naming, since they have been introduced very recently.
> If the overhead is not too much I think we should, with a clear
> notice that it will not be preserved after the next major version
> (2.3?)

By then (2.3) I would hope we have fully transitioned to an LDIF config and
back-config. In that case, the configuration info itself would be
hierarchical, and wouldn't need any special qualifiers to prevent clashing.

  -- Howard Chu
  Chief Architect, Symas Corp.       Director, Highland Sun
  http://www.symas.com               http://highlandsun.com/hyc
  Symas: Premier OpenSource Development and Support