Issue 5915 - Some man pages still only talk about slapd.conf
Summary: Some man pages still only talk about slapd.conf
Status: UNCONFIRMED
Alias: None
Product: OpenLDAP
Classification: Unclassified
Component: documentation (show other issues)
Version: unspecified
Hardware: All All
: --- normal
Target Milestone: 2.7.0
Assignee: OpenLDAP project
URL:
Keywords:
Depends on: 7335
Blocks:
  Show dependency treegraph
 
Reported: 2009-01-29 23:33 UTC by Gavin Henry
Modified: 2021-07-13 16:18 UTC (History)
0 users

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this issue.
Description Gavin Henry 2009-01-29 23:33:23 UTC
Full_Name: Gavin Henry
Version: 
OS: 
URL: ftp://ftp.openldap.org/incoming/
Submission from: (NULL) (92.41.236.102)
Submitted by: ghenry


Some discussion will be needed on the best way to talk about config. We don't
want to list everything twice for both formats...lots of slapd.conf written
throughout most (5/8) man pages.

Thanks.

Comment 1 Gavin Henry 2009-01-29 23:33:41 UTC
moved from Incoming to Documentation
Comment 2 Howard Chu 2009-01-29 23:39:58 UTC
ghenry@OpenLDAP.org wrote:
> Full_Name: Gavin Henry
> Version:
> OS:
> URL: ftp://ftp.openldap.org/incoming/
> Submission from: (NULL) (92.41.236.102)
> Submitted by: ghenry
>
>
> Some discussion will be needed on the best way to talk about config. We don't
> want to list everything twice for both formats...lots of slapd.conf written
> throughout most (5/8) man pages.

I guess for this release (and probably for 2.5) we're just going to have to 
document both, as cumbersome as that will be. When we get to to 2.6/3.0 and 
drop support for slapd.conf we'll have to come back thru again and delete the 
slapd.conf references from all the docs. Unless anyone has a better idea...

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

Comment 3 Hallvard Furuseth 2009-01-30 11:42:26 UTC
hyc@symas.com writes:
> I guess for this release (and probably for 2.5) we're just going to
> have to document both, as cumbersome as that will be. When we get to
> to 2.6/3.0 and drop support for slapd.conf we'll have to come back
> thru again and delete the slapd.conf references from all the
> docs. Unless anyone has a better idea...

I'm not sure I see the problem, except that Someone(TM) must do the
work...

For each configuration keyword, use two headers in the manpages: Both
the slapd.conf syntax and the cn=config syntax.  Explain at the
beginning of slapd.conf.5 or slapd-config.5.  We'll be deleting most of
the other one, since they are mostly duplicates.  Other manpages need
just one-line reminder for explanation.

There'll be exceptions that spell things out too differently, or use
slightly different parameters in slapd.conf and cn=config.  Keep them in
just slapd.conf-syntax, and add a separate cn=config attribute
description below.  Likely that'll only need to explain the difference.
Don't go trough literary contortions to fit them both into the same
description.  Some of these will likely be things that could use some
cleanup in the code anyway, bringing the two config formats in sync.

Take a random sample of the slapd.conf-syntax example sections and
replace with their cn=config equivalent.  Ensure all example sections
say either "slapd.conf example" or "cn=config example".

slapd.conf.5 and slapd-config.5 themselves will need sections about how
they work as interfaces to configuration, separate from the
configuration keywords/attributes themselves.  Since we are moving
towards cn=config, I suppose it's that one which should keep the actual
keyword/attribute descriptions.  Or they could move to a third file.

-- 
Hallvard

Comment 4 chris@blueoxsolutions.com 2012-01-04 18:16:22 UTC
Is there any progress on this?  Speaking as a user who wanted to setup 
an ldap server so that I can combine a thunderbird and alpine address 
book in to one and perhaps export to my external memory unit (a 
semi-intelligent phone) I found the documentation on this sight (and 
others) to be very confusing.  Is there gong to be any effort to fix the 
doccumentation in the near future?  Is there a better guide by somone 
else that I can use to set up a simple address book with openldap?


-- 
========================================================================
Chris Oxenreider                   |
chris@blueoxsolutions.com          |
========================================================================
Personal

Comment 5 Gabriele Pohl 2012-01-06 15:05:12 UTC
It was getting on my nerves and I had to spend a lot of time
to clear up the situation. Being a beginner in both areas
Debian Distribution and OpenLDAP-Server I entered the docs
via Quick Start and immediately stuck headover in the mud
of outdated and inconsistent docs / references..

Please add at least a note about the new configuration
method and a link to the explaining wiki page
http://www.openldap.org/doc/admin24/slapdconf2.html

in Quick-Start:
http://www.openldap.org/doc/admin24/quickstart.html

As you link to http://www.openldap.org/doc/admin24/slapdconfig.html
from there in section 8 about Configuration you should
also add a note and link there or even better add an own section
about the dynamic configuration method in Quick-Start.

Thanks in advance and cheers

Gabriele

Comment 6 Gavin Henry 2012-01-06 19:18:08 UTC
Thanks, will do!

----- Original Message -----
> It was getting on my nerves and I had to spend a lot of time
> to clear up the situation. Being a beginner in both areas
> Debian Distribution and OpenLDAP-Server I entered the docs
> via Quick Start and immediately stuck headover in the mud
> of outdated and inconsistent docs / references..
> 
> Please add at least a note about the new configuration
> method and a link to the explaining wiki page
> http://www.openldap.org/doc/admin24/slapdconf2.html
> 
> in Quick-Start:
> http://www.openldap.org/doc/admin24/quickstart.html
> 
> As you link to http://www.openldap.org/doc/admin24/slapdconfig.html
> from there in section 8 about Configuration you should
> also add a note and link there or even better add an own section
> about the dynamic configuration method in Quick-Start.
> 
> Thanks in advance and cheers
> 
> Gabriele
> 

-- 
Kind Regards,

Gavin Henry.
OpenLDAP Engineering Team.

E ghenry@OpenLDAP.org

Community developed LDAP software.

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

Comment 7 Bruno Schrade 2012-03-19 14:51:24 UTC
Sehr geehrter Herr Henry,

i just moved an OpenLDAP-Server from Debian-5 to Debian-6. Expecting it would simply run using the same configuration file i just copied slapd.conf. This resulted in error messages along the line "missing credentials". So i looked up the QuickStartGuide and continued debugging the authorization process - finally found the reason and cure by reading /etc/init.d/slapd.

I would like to suggest two changes:

1  May i suggest a quick fix: add something like "don't read this" 
   to the top of the QuickStartGuide.
2  If possible change your mind on dropping slapd.conf-Support.
   - Dropping it will break existing configurations.
   - People are quite accustomed to /etc/.../.. .conf-files

I would like to add that i really appreciate the work you are doing.

Mit freundlichen Grüssen

Schwarzwald Software Engineering * Bruno Schrade
Theodor-Kreuz-Strasse 6 * D-79868 Feldberg * Tel. +49 (0)7655 618
http://www.schwarzwald-software.de


Comment 8 Gavin Henry 2012-03-19 15:11:42 UTC
It is on the list for updating and a migration section. 

-- 
Kind Regards,

Gavin Henry.
Managing Director.

T +44 (0) 1224 279484
M +44 (0) 7930 323266
F +44 (0) 1224 824887
E ghenry@suretecsystems.com

Open Source. Open Solutions(tm).

http://www.suretecsystems.com/

Suretec Systems is a limited company registered in Scotland. Registered
number: SC258005. Registered office: 24 Cormack Park, Rothienorman, Inverurie,
Aberdeenshire, AB51 8GL.

Subject to disclaimer at http://www.suretecgroup.com/disclaimer.html




On 19 Mar 2012, at 14:51, Bruno Schrade <bs@schwarzwald-software.de> wrote:

> Sehr geehrter Herr Henry,
> 
> i just moved an OpenLDAP-Server from Debian-5 to Debian-6. Expecting it would simply run using the same configuration file i just copied slapd.conf. This resulted in error messages along the line "missing credentials". So i looked up the QuickStartGuide and continued debugging the authorization process - finally found the reason and cure by reading /etc/init.d/slapd.
> 
> I would like to suggest two changes:
> 
> 1  May i suggest a quick fix: add something like "don't read this" 
>   to the top of the QuickStartGuide.
> 2  If possible change your mind on dropping slapd.conf-Support.
>   - Dropping it will break existing configurations.
>   - People are quite accustomed to /etc/.../.. .conf-files
> 
> I would like to add that i really appreciate the work you are doing.
> 
> Mit freundlichen Grüssen
> 
> Schwarzwald Software Engineering * Bruno Schrade
> Theodor-Kreuz-Strasse 6 * D-79868 Feldberg * Tel. +49 (0)7655 618
> http://www.schwarzwald-software.de
>