[Date Prev][Date Next]
RE: Overlay Documentation
> -----Original Message-----
> From: owner-openldap-devel@OpenLDAP.org
> [mailto:owner-openldap-devel@OpenLDAP.org]On Behalf Of Pierangelo
> > 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
> 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
> 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
> 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
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
Symas: Premier OpenSource Development and Support