OpenLDAP
Up to top level
Build   Contrib   Development   Documentation   Historical   Incoming   Software Bugs   Software Enhancements   Web  

Logged in as guest

Viewing Documentation/6277
Full headers

From: ryans@aweber.com
Subject: Missing documentation for cn=config
Compose comment
Download message
State:
1 replies: 1
6 followups: 1 2 3 4 5 6

Major security issue: yes  no

Notes:

Notification:


Date: Thu, 27 Aug 2009 16:03:46 +0000
From: ryans@aweber.com
To: openldap-its@OpenLDAP.org
Subject: Missing documentation for cn=config
Full_Name: Ryan Steele
Version: 2.4.15
OS: Ubuntu 8.04 LTD
URL: ftp://ftp.openldap.org/incoming/
Submission from: (NULL) (207.106.239.81)


According to chapter 5 of the admin guide, "some of the backends and of the
distributed overlays do not support runtime configuration yet. In those cases,
the old style slapd.conf(5) file must be used."  However, there is no
documentation on which backends and overlays do and don't have said support. 
Without grokking the code, it is a trial-and-error operation at best.

Also, there is no documentation on how to add overlay-specific directives (man
pages or otherwise).  Take, for example, autogroup-attrset; the olcAGattrSet
directive is only described in autogroup.c, and nowhere else.  This is not the
only instance of missing module documentation, but it should give a general idea
of where to look.

Of course, grepping the code is easy enough, but you shouldn't have to do that
to learn how to achieve simple configurations. If there's going to be a
fundamental paradigm shift from slapd.conf to cn=config, there has to be
documentation (man pages, admin guide sections, et. al.) on the appropriate
methods for achieving what once was done through slapd.conf.  IMHO, that should
include concrete examples, such as the following, pulled from the Courier
documentation:

The following LDIF could be used to add [the auditlog] overlay to cn=config
(adjust to suit):

    dn: olcOverlay=auditlog,olcDatabase={1}hdb,cn=config 
    changetype: add
    objectClass: olcOverlayConfig
    objectClass: olcAuditLogConfig
    olcOverlay: auditlog
    olcAuditlogFile: /tmp/auditlog.ldif


Followup 1

Download message
Date: Thu, 27 Aug 2009 21:22:12 +0200 (CEST)
Subject: Re: (ITS#6277) Missing documentation for cn=config
From: masarati@aero.polimi.it
To: "Gavin Henry" <openldap-its@OpenLDAP.org>
Cc: ryans@aweber.com, openldap-its@OpenLDAP.org
>> Full_Name: Ryan Steele
>> Version: 2.4.15
>> OS: Ubuntu 8.04 LTD
>> URL: ftp://ftp.openldap.org/incoming/
>> Submission from: (NULL) (207.106.239.81)
>>
>>
>> According to chapter 5 of the admin guide, "some of the backends and of
>> the
>> distributed overlays do not support runtime configuration yet. In those
> cases,
>> the old style slapd.conf(5) file must be used."  However, there is no
>> documentation on which backends and overlays do and don't have said
>> support.
>> Without grokking the code, it is a trial-and-error operation at best.
>
> Point taken. I'm pretty sure they all do now. Will check and update that
> section.

back-meta and back-sql don't yet.  I have half (er, somewhere between 0
and 100%, boundaries not included) in a working dir somewhere, and rough
ideas about what to do with back-meta.

p.



Followup 2

Download message
Date: Thu, 27 Aug 2009 12:27:21 -0700
From: Howard Chu <hyc@symas.com>
To: masarati@aero.polimi.it
CC: openldap-its@openldap.org
Subject: Re: (ITS#6277) Missing documentation for cn=config
masarati@aero.polimi.it wrote:
>>> Full_Name: Ryan Steele
>>> Version: 2.4.15
>>> OS: Ubuntu 8.04 LTD
>>> URL: ftp://ftp.openldap.org/incoming/
>>> Submission from: (NULL) (207.106.239.81)
>>>
>>>
>>> According to chapter 5 of the admin guide, "some of the backends
and of
>>> the
>>> distributed overlays do not support runtime configuration yet. In
those
>> cases,
>>> the old style slapd.conf(5) file must be used."  However, there is
no
>>> documentation on which backends and overlays do and don't have said
>>> support.
>>> Without grokking the code, it is a trial-and-error operation at
best.
>>
>> Point taken. I'm pretty sure they all do now. Will check and update
that
>> section.
>
> back-meta and back-sql don't yet.  I have half (er, somewhere between 0
> and 100%, boundaries not included) in a working dir somewhere, and rough
> ideas about what to do with back-meta.

All of the core overlays now support cn=config. Yes, contrib is trial-and-error.

-- 
   -- Howard Chu
   CTO, Symas Corp.           http://www.symas.com
   Director, Highland Sun     http://highlandsun.com/hyc/
   Chief Architect, OpenLDAP  http://www.openldap.org/project/



Followup 3

Download message
Date: Tue, 01 Sep 2009 15:16:54 -0400
From: Ryan Steele <ryans@aweber.com>
To: openldap-its@OpenLDAP.org
CC: ryans@aweber.com
Subject: Re: (ITS#6277) Missing documentation for cn=config
Gavin,

> Well there are two places that talk about how to convert from slapd.conf
> to cn=config formats. In the guide and man pages, so that is the best
> way to do a full conversion and see the end result.
>
> Where would you like to see these added?
>
> Thanks for the feedback as always!

My vote would be section 5.2.2.3 of the Admin Guide.  Currently, it has 2
examples of loading modules consisting of
libtool libraries, but I would think that it would be good to give an example
which, for pedagogical purposes, explained
how to instantiate an overlay in cn=config.  For example, ppolicy and autogroup:

   dn: olcOverlay=ppolicy,olcDatabase={1}hdb,cn=config
   objectClass: olcOverlayConfig
   objectClass: olcPPolicyConfig
   olcOverlay: ppolicy

   dn: olcOverlay=autogroup,olcDatabase={1}hdb,cn=config
   objectClass: olcOverlayConfig
   objectClass: olcAutomaticGroups
   olcOverlay: autogroup
   olcAGattrSet: groupOfNames labeledURI member

Perhaps it would also be good to emphasize the need for overlay-specific
objectclasses, such as the aforementioned
'olcOverlayConfig' and 'olcPPolicyConfig'.  It probably also wouldn't hurt to
mention that there are certain
overlay-specific attributes, i.e. olcAGattrSet, that are necessary to make full
use of the module, and that grepping
through the contrib module's source can help one identify said attributes' names
in lieu of adequate documentation.
Something like: grep -C3 NAME contrib/slapd-modules/autogroup/autogroup.c,
maybe?


Thanks as always,
Ryan



Followup 4

Download message
Date: Tue, 1 Sep 2009 22:14:38 +0100 (BST)
From: Gavin Henry <ghenry@OpenLDAP.org>
To: ryans@aweber.com
Cc: openldap-its@OpenLDAP.org
Subject: Re: (ITS#6277) Missing documentation for cn=config
----- ryans@aweber.com wrote:

> Gavin,
> 
> > Well there are two places that talk about how to convert from
> slapd.conf
> > to cn=config formats. In the guide and man pages, so that is the
> best
> > way to do a full conversion and see the end result.
> >
> > Where would you like to see these added?
> >
> > Thanks for the feedback as always!
> 
> My vote would be section 5.2.2.3 of the Admin Guide.  

Hi Ryan,

Thanks for the time you spent replying in length. Oh, maybe that time could have
been
spent writing a patch to docs! ;-)

I'll take on board your suggestions and make some changes when I can.

Patches welcome!

Cheers.

-- 
Kind Regards,

Gavin Henry.
OpenLDAP Engineering Team.

E ghenry@OpenLDAP.org

Community developed LDAP software.

http://www.openldap.org/project/



Followup 5

Download message
Date: Tue, 01 Sep 2009 14:19:46 -0700
From: Howard Chu <hyc@symas.com>
To: ryans@aweber.com
CC: openldap-its@openldap.org
Subject: Re: (ITS#6277) Missing documentation for cn=config
ryans@aweber.com wrote:
> Gavin,
>
>> Well there are two places that talk about how to convert from
slapd.conf
>> to cn=config formats. In the guide and man pages, so that is the best
>> way to do a full conversion and see the end result.
>>
>> Where would you like to see these added?
>>
>> Thanks for the feedback as always!
>
> My vote would be section 5.2.2.3 of the Admin Guide.  Currently, it has 2
examples of loading modules consisting of
> libtool libraries, but I would think that it would be good to give an
example which, for pedagogical purposes, explained
> how to instantiate an overlay in cn=config.  For example, ppolicy and
autogroup:

autogroup is a contrib module. We only document usage of core features in the 
Admin Guide.

>     dn: olcOverlay=ppolicy,olcDatabase={1}hdb,cn=config
>     objectClass: olcOverlayConfig
>     objectClass: olcPPolicyConfig
>     olcOverlay: ppolicy

-- 
   -- Howard Chu
   CTO, Symas Corp.           http://www.symas.com
   Director, Highland Sun     http://highlandsun.com/hyc/
   Chief Architect, OpenLDAP  http://www.openldap.org/project/



Followup 6

Download message
Date: Wed, 2 Sep 2009 20:37:35 +0100
Subject: Re: (ITS#6277) Missing documentation for cn=config
From: Gavin Henry <gavin.henry@gmail.com>
To: hyc@symas.com, openldap-its@openldap.org
Of course, but Ryan also mentioned the password policy overlay here
and loading overlays in general via cn=config.

On 01/09/2009, hyc@symas.com <hyc@symas.com> wrote:
> ryans@aweber.com wrote:
>> Gavin,
>>
>>> Well there are two places that talk about how to convert from
slapd.conf
>>> to cn=config formats. In the guide and man pages, so that is the
best
>>> way to do a full conversion and see the end result.
>>>
>>> Where would you like to see these added?
>>>
>>> Thanks for the feedback as always!
>>
>> My vote would be section 5.2.2.3 of the Admin Guide.  Currently, it has
2
>> examples of loading modules consisting of
>> libtool libraries, but I would think that it would be good to give an
>> example which, for pedagogical purposes, explained
>> how to instantiate an overlay in cn=config.  For example, ppolicy and
>> autogroup:
>
> autogroup is a contrib module. We only document usage of core features in
> the
> Admin Guide.
>
>>     dn: olcOverlay=ppolicy,olcDatabase={1}hdb,cn=config
>>     objectClass: olcOverlayConfig
>>     objectClass: olcPPolicyConfig
>>     olcOverlay: ppolicy
>
> --
>    -- Howard Chu
>    CTO, Symas Corp.           http://www.symas.com
>    Director, Highland Sun     http://highlandsun.com/hyc/
>    Chief Architect, OpenLDAP  http://www.openldap.org/project/
>
>
>

-- 
Sent from my mobile device

http://www.suretecsystems.com/services/openldap/
http://www.suretectelecom.com



Reply 1

Resend
From: Gavin Henry <openldap-its@OpenLDAP.org>
To: ryans@aweber.com
Subject: Re: (ITS#6277) Missing documentation for cn=config
Date: Thu Aug 27 16:21:45 2009
CC: openldap-its@OpenLDAP.org
> Full_Name: Ryan Steele
> Version: 2.4.15
> OS: Ubuntu 8.04 LTD
> URL: ftp://ftp.openldap.org/incoming/
> Submission from: (NULL) (207.106.239.81)
> 
> 
> According to chapter 5 of the admin guide, "some of the backends and of
the
> distributed overlays do not support runtime configuration yet. In those
cases,
> the old style slapd.conf(5) file must be used."  However, there is no
> documentation on which backends and overlays do and don't have said
support. 
> Without grokking the code, it is a trial-and-error operation at best.

Point taken. I'm pretty sure they all do now. Will check and update that
section.

> Also, there is no documentation on how to add overlay-specific directives
(man
> pages or otherwise).  Take, for example, autogroup-attrset; the
olcAGattrSet
> directive is only described in autogroup.c, and nowhere else.  This is not
the
> only instance of missing module documentation, but it should give a general
idea
> of where to look.

Some of the contribs one don't come with a man page unfortunately. Core ones
do.

I'll look into the relevant sections and add one or two examples.

> Of course, grepping the code is easy enough, but you shouldn't have to do
that
> to learn how to achieve simple configurations. If there's going to be a
> fundamental paradigm shift from slapd.conf to cn=config, there has to be
> documentation (man pages, admin guide sections, et. al.) on the
appropriate
> methods for achieving what once was done through slapd.conf.  IMHO, that
should
> include concrete examples, such as the following, pulled from the Courier
> documentation:
> 
> The following LDIF could be used to add [the auditlog] overlay to
cn=config
> (adjust to suit):
> 
>     dn: olcOverlay=auditlog,olcDatabase={1}hdb,cn=config 
>     changetype: add
>     objectClass: olcOverlayConfig
>     objectClass: olcAuditLogConfig
>     olcOverlay: auditlog
>     olcAuditlogFile: /tmp/auditlog.ldif
> 

Well there are two places that talk about how to convert from slapd.conf to
cn=config formats. In the guide and man pages, so that is the best way to do a
full conversion and see the end result. 

Where would you like to see these added?

Thanks for the feedback as always!

Gavin.

Up to top level
Build   Contrib   Development   Documentation   Historical   Incoming   Software Bugs   Software Enhancements   Web  

Logged in as guest


The OpenLDAP Issue Tracking System uses a hacked version of JitterBug

______________
© Copyright 2013, OpenLDAP Foundation, info@OpenLDAP.org