Re: enhance ACL documentation (ITS#3181)

[Kurt@OpenLDAP.org]

At 12:27 PM 6/7/2004, John.Kloss@jhmi.edu wrote:
>Full_Name: John Kloss
>Version: 2.2.12
>OS: Linux 2.4.+ and Solaris 9
>URL: ftp://ftp.openldap.org/incoming/
>Submission from: (NULL) (162.129.236.40)
>
>
>In regards to ITS# 3165, Kurt D. Zeilenga suggests that complex ACL examples
>should only be displayed in the current OpenLDAP Administrators Guide after
>carefully building them up through previous, simpler examples.

Yes.  I note as well that there is a general need for a
"Advanced Access Control" chapter.  This chapter would
cover access controls features in depth, with extensive
use of examples to illustrate how to implement various
policies can be implemented using access control
statements.

There has been a significant amount of material added
to the FAQ which likely should find its way into this
chapter (or, at least, serve as a basis for that new
chapter).

>I would like to suggest that the ACL section of the OpenLDAP Administrators
>Guide be enhanced in that manner:  simple definitions followed by simple
>examples, moving on to more complex definitions and examples with a possiblity
>of application specific examples given at or near the end.

Note that the Admin Guide should be application neutral.
In particular,
        1) a reader should not have to under a particular
        application to understand the material, and
        2) a reader desiring to configure a particular
        application should not rely on this document
        to cover how to configure this software for that
        application.

Examples in the document should stick to generic (and
standarized) applications such as "white pages" and avoid
mention/discussion of specific applications.  The latter
are better discussed in separate documents.

>The ACL section
>could be made a chapter in it's own right, much like the sections on TLS and
>SASL.

Yes.

>ACL examples are, of course, already provided in the current OpenLDAP
>Administrators Guide, but I feel this section could be enhanced with specific
>query examples and the resulting ACL applications to such queries with
>particular regard to ACLs utilizing groupOfNames, regular expressions, peername,
>and filter parameters.

At this stage, it is hard to see exactly how the addition
of a new chapter would impact material in existing chapters.
I suspect some reorganization would be necessary.  I suggest
we defer discuss in this area for now.

>I am willing to submit such documentation in whatever format is required (the
>guidelines for patch submissions are quite clear, but I was unsure about
>documentation update formats).

You are more than welcomed to contribute in this area.
Please see http://www.openldap.org/faq/index.cgi?file=156
for additional information.  (Note: submission in SDF
format, while preferred, is not required.  Plain ASCII
text will do.)

Regards, Kurt