Re: ACL Problem, Insufficient access (50)

[Alain Williams <addw@phcomp.co.uk>]

On Thu, 22 Dec 2005 21:56:26 +0100, Pierangelo Masarati <ando@sys-net.it> wrote:
> I don't know if that's part of the problem, but in your ACLs you're
> building up most, if not all, the common errors that are widely
> illustrated in slapd.access(5) and in the FAQ.  Did you read (and
> understand) any of those docs before implementing your own ACLs?  I note
> the OpenLDAP Project routinely gets complaints about the lack of
> documentation; when documentation is available, it appears that people
> don't really bother at reading (and understanding) it, so what really
> pays back for the effort of writing and keeping it updated?
> 
> p.
> Ing. Pierangelo Masarati
> Responsabile Open Solution
> OpenLDAP Core Team

Please take this as *constructive* criticism, it is not a flame.

I also believe that the openldap documentation is poor. I have spent a lot of
time trying to get simple things to work, I have cursed the poor documentation
and the unintelligible diagnostics. I am someone who has spent > 30 years working
with computers, the last 25 with many aspects of Unix, someone like me should be
easily able to pick up openldap and work with it, but I can't, why not ?

Summary: the documentation is too low level, the ''big picture'' and ''how to put
it all together'' are missing.

* I tried looking at the schemas, lots of numbers and names, no real indication
  as to how to use them (either in the .schema files or elsewhere)
* I tried to look at the code: very few internal comments, whole functions without
  any at all, not even ''this function does X, takes A & B as parameters, returns C''.
  I would not let someone working for me write code like that.
* The manual pages seem to explain everything but in small pieces, complete (non
  trivial) examples are lacking.
* There is a lot of it: where do I start first ?

The trouble with many openldap gurus is that you know it well, you cannot see it
from the perspective of someone who is new to it.

What is needed: more entry level examples that are complete, ie this is what the
slapd.conf file looks like, here is a sample of data entries, here is how it is
used for mail/user_logon/...

This needs to be written by people who *really* understand openldap otherwise what
will be put together are examples of poor practice.

Notes:

* RFCs are NOT end user documentation, they are reference for when you have a good
  understanding of the topic. 
* It is not fair to complain that people don't understand it, if the documentation
  is at a level that is much greater than their level of understanding. I know several
  good/competent people who have struggled with openldap and given up frustrated,
  it is not through lack of trying.
* Not everyone reads it with your eyes.

-- 
Alain Williams
Parliament Hill Computers Ltd.
Linux Consultant - Mail systems, Web sites, Networking, Programmer, IT Lecturer.
+44 (0) 787 668 0256  http://www.phcomp.co.uk/

#include <std_disclaimer.h>