Re: LDAP authenticaton against PAM how-to

[TechnoSophos <technosophos@gmail.com>]

On 2/11/07, Adam Tauno Williams <awilliam@whitemice.org> wrote:
> > Emmanuel's point is worth noting: it is very difficult to learn the
> > OpenLDAP  jargon, and the official documentation (the admin guide plus
> > the FAQ, plus the man pages) quite simply don't cut it. They are
> > steeped through and through with LDAP technical jargon (often used
> > inconsistently, like "slave","shadow," "replica," and "subordinate"
> > all referring to the server receiving replication by SLURPD or
> > SyncRepl).
>
> Sorry, but this is rubbish.  Is the Samba documentation expected to
> explain how Windows works or serve as an introduction to SMB/CIFS
> networking?  Half the terms above are generic LDAP terms;  is someone
> wants to use LDAP then start with reading up on *LDAP*.  Seems
> reasonable to become familiar with a technology before moving on to a
> specific implementation.  If you think this applies only to OpenLDAP pop
> over to the Samba, Sendmail, Cyrus, etc... lists for people asking
> questions that are really about CIFS, SMTP, IMAP, etc...

Again, my main point was on the general tone of the list, not the
quality of the documentation, though I see those two as strongly
causally related. But I do see the point you are trying to make, Adam,
so let me try to address your response.

I have the following problems with the argument presented above:

*. It is something of a straw-man argument. I am NOT arguing that one
ought not need any knowledge to configure OpenLDAP. Nor am I arguing
that BER or ASN.1 needs to be explained in detail in the admin guide
(just as HTTP is not explained in Apache's docs, nor CIFS in Samba's).

But clarity in the documentation is certainly a desired feature, and
as it stands now, it seems (based on responses to the list, as well as
my own personal experience) that going from a small LDAP server
following basically the default configuration to a more complex
directory environment requires a pretty steep learning curve. Good
documentation could improve that situation.

*. I don't find the argument that other products have bad
documentation to be justification for not creating good documentation.
To be honest, I think Cyrus' documentation is abysmal, and it took me
years to get the hang of all of its quirks and inconsistencies. But I
don't particularly care about that project. Samba documentation is
awful, too -- and was the subject of a sustained rant from Eric
Raymond some years ago. Sendmail does better... but perhaps not much
better. At least it has the bat book.

I would even go so far as to suggest that much of the growth in
postfix, exim, and the like is due to the poor documentation in
sendmail and cyrus.

*. I don't actually think the problem with OpenLDAP is a *lack* of
documentation (which is certainly a problem with Cyrus). Again, the
man pages are very thorough and very complete. And if one reads the
RFCs (which are also exceptionally good) and some of the code, then
one can get along pretty well with OpenLDAP. But that seems to be a
high barrier of entry. I'd like to see it get lower.

> > My opinion may be in the minority here, but I don't think that a
> > prerequisite to running OpenLDAP ought to be the thorough and careful
> > reading of the whole bundle of LDAP RFCs.
>
> It isn't.  There is *LOTS* and *LOTS* and *LOTS* of well cooked LDAP
> documentation - see Amazon.
> http://www.amazon.com/gp/reader/0672323168/ref=sib_dp_pt/105-2231389-9349228#reader-link

Tim Howes' book is excellent. I would certainly not dispute that. But
at nearly 1000 pages, it's not exactly a breeze compared to the RFCs.

There is something to be said for trying to get people into LDAP from
OpenLDAP. It comes with almost every major Linux distribution. Why not
make it attractive to people who haven't yet discovered what LDAP can
do?

Long ago, I read something Howard had written lamenting the fact that
some of the more advanced LDAP applications he had conceived were
beyond what people could comprehend a directory server doing. I feel
the same way. The standard treatment of LDAP is as an authentication
service provider. This is, of course, one area where LDAP excels. But
it could be used for a lot more. Could lowering the barrier to entry
with OpenLDAP contribute to resolving this misperception? I'd like to
think so.

> Asking the OpenLDAP project to re-document LDAP is unreasonable.  Or
> SASL for that matter.

I'm not, per se, suggesting this.

As Howard pointed out, we know that the documentation could use
improvement, and yet that doesn't seem to happen. Why? What I am
suggesting, though I can see how it got lost in the fray, is that this
list is on the tough side. And this generally negative attitude
impedes improvement because it turns people away. And I am using
Emmanuel's attempt to contribute to the documentation as a case in
point.

Matt