RE: Overlay Documentation

["Pierangelo Masarati" <ando@sys-net.it>]

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

Actually, in UMich's AG there was a very essential documentation on how to
write a backend... I think that overlays, as well as SLAPI, could become a
very easy, and, as such, widely exploited means to customize slapd; widely
useful extensions could easily make into the distributed source as
contribs, so I think it might be worth the effort to document this part of
the API as soon as it stabilizes.  Of course, one to do interesting stuff
needs to know also the rest of the API, but this is a different point.  I
also note that the API, in some sense, is getting simpler and simpler
after your large effort to turn the function calls in a uniform layout.

>
>> 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 ?

sure.

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

I already did it, only to make it cleaner.

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

Well, this can mean two things: we're close to a back-config, or we're far
from 2.3! ;)  In any case, I'd prefer to have names split as much as
possible in the meanwhile; of course I plan to preserve compatibility, and
I'm more concerned on future overlays.

Ando.

-- 
Pierangelo Masarati
mailto:pierangelo.masarati@sys-net.it