Re: BDB notes

[Igor Brezac <igor@ipass.net>]

On Tue, 29 Apr 2003, John Fieber wrote:

> On Thursday, April 24, 2003, at 03:58  AM, Howard Chu wrote:
>
> >> -----Original Message-----
> >> From: jimd@siu.edu [mailto:jimd@siu.edu]
> >> Subject: Re: 2.1.17 performance issues
> >>
> >>
> >> Howard - would you please add the question below, and your
> >> execellent answer
> >> to it, to the FAQ? This would help all of us greatly. Thank you.
> >
> > I've added hyperlinked notes on configuring back-bdb here:
> > http://www.openldap.org/faq/index.cgi?file=893
>
> Great!  But shouldn't this text in (a) the Admin Guide and (b) the
> slapd-bdb(5) manpage?  The FAQ is a navigational mess and the search is
> rather broken.
>
> I've been following the rants about bdb problems and documentation.
> I've got some observations:
>
> * It seems that bunches of folks are having problems with the bdb
> backend.
>
> * It seems like most of these folks are having problems because of a
> missing external-to-slapd bdb configuration.
>
> * Other folks cry out RTFM!  Then clarify that TFM includes: all
> bundled READMEs, manual pages, admin guide and FAQ (with its
> navigational and search problem), and the SleepyCat documentation.
>
> * The previous default backend, back-ldbm, was entirely configured and
> operated by slapd.conf and slapd.  No non-OpenLDAP documentation,
> configuration files or tools required, or even particularly relevant.
>
> * back-bdb is billed in assorted places in the TFM as being like
> back-ldbm but better, essentially an upgrade for back-ldbm.
>
> * Many folks, myself included, assumed the "upgrade" version, back-bdb,
> to be essentially a direct replacement configured and managed just like
> back-ldbm.  In the absence of any obvious clue to the contrary in TFM,
> we setup back-bdb like we setup back-ldbm.
>
> * We then go to the list asking about performance problems and are
> tersely told to RTFM, but are still confused.  Yes, we can read TFM.
> The problem is that there is nothing in TFM to clue us into our
> incorrect assumption about back-bdb being operationally the same as
> back-ldbm and I have not seen that detail it clearly articulated on the
> list either.  This is a classic case of developers being too close to
> the software to appreciate what seemingly simple things trip up the
> rest of us who have vastly less intimate knowledge of how everything
> fits together.  This is nothing to be ashamed of, it happens all the
> time which is why, in general, programmers should not write
> documentation.
>
>
> The bottom line appears to be that if you think of back-bdb as a
> drop-in replacement for back-ldbm, you WILL have big problems.  Since
> back-bdb is the default backend, this must be clearly documented in
> multiple obvious places or the above ugly chain of events will
> frequently reoccur.
>
> If this great new FAQ entry, or some shortened proxy with a link to the
> full entry, is placed in the back-bdb manual page and the Admin Guide,
> I predict that the whole ugly chain of events documented above will be
> eliminated for a vast majority of sysadmins using OpenLDAP.
>

Write a patch for the back-bdb man page and the Admin Guide and submit it
to ITS (http://www.openldap.org/its/).

-- 
Igor