From 1704b9a081d765583e789aa2dee86905e297e26d Mon Sep 17 00:00:00 2001 From: Gavin Henry Date: Fri, 24 Aug 2007 23:24:34 +0000 Subject: [PATCH] New Changes Appendix, plus various other additions and fixes. --- doc/guide/admin/Makefile | 2 +- doc/guide/admin/appendix-changes.sdf | 54 ++++++++++++++++++++++++++++ doc/guide/admin/backends.sdf | 10 +++--- doc/guide/admin/guide.book | 2 +- doc/guide/admin/intro.sdf | 12 +++---- doc/guide/admin/maintenance.sdf | 14 ++++---- doc/guide/admin/master.sdf | 3 ++ doc/guide/admin/monitoringslapd.sdf | 5 +++ doc/guide/admin/overlays.sdf | 6 ++++ doc/guide/admin/replication.sdf | 14 ++++---- doc/guide/admin/tls.sdf | 2 ++ doc/guide/admin/troubleshooting.sdf | 15 +++++--- doc/guide/admin/tuning.sdf | 8 ++--- 13 files changed, 112 insertions(+), 35 deletions(-) create mode 100644 doc/guide/admin/appendix-changes.sdf diff --git a/doc/guide/admin/Makefile b/doc/guide/admin/Makefile index d417332582..6b33980f98 100644 --- a/doc/guide/admin/Makefile +++ b/doc/guide/admin/Makefile @@ -66,4 +66,4 @@ guide.pdf: admin.html htmldoc --batch guide.book clean: - rm -f *.pdf *.html + rm -f *.pdf *.html *~ diff --git a/doc/guide/admin/appendix-changes.sdf b/doc/guide/admin/appendix-changes.sdf new file mode 100644 index 0000000000..a78e3d6beb --- /dev/null +++ b/doc/guide/admin/appendix-changes.sdf @@ -0,0 +1,54 @@ +# $OpenLDAP$ +# Copyright 2007 The OpenLDAP Foundation, All Rights Reserved. +# COPYING RESTRICTIONS APPLY, see COPYRIGHT. + +H1: Changes Since Previous Release + +Nice intro here to praise everyones hard work! + +H2: New Guide Sections + +* Overlays +* Backends +* Tuning +* complete later......... + +H2: New Features in 2.4 + +Another nice intro here + +H3: More overlays + +* slapo-dds (Dynamic Directory Services, RFC 2589) +* slapo-memberof (reverse group membership maintenance) + +H3: New features in existing ones + +* slapo-pcache allows cache inspection/maintenance/hot restart +* slapo-rwm can safely interoperate with other overlays +* Dyngroup/Dynlist merge, plus security enhancements + +H3: New features in slapd + +* monitoring of back-{b,h}db: cache fill-in, non-indexed searches, +* session tracking control (draft-wahl-ldap-session) +* subtree delete in back-sql (draft-armijo-ldap-treedelete) + +H3: New features in libldap + +* ldap_sync client API (LDAP Content Sync Operation, RFC 4533) + +H3: New clients and tools + +* ldapexop for arbitrary extended operations +* complete support of controls in request/response for all clients + +H3: New build options + +* Support for building against GnuTLS +* Advertisement of LDAP server in DNS + + +H2: Obsolete Features in 2.4 + +H3: Slurpd diff --git a/doc/guide/admin/backends.sdf b/doc/guide/admin/backends.sdf index ae2773c486..1faa9b8cac 100644 --- a/doc/guide/admin/backends.sdf +++ b/doc/guide/admin/backends.sdf @@ -146,11 +146,11 @@ H3: Overview The Null backend to {{slapd}}(8) is surely the most useful part of slapd: -- Searches return success but no entries. -- Compares return compareFalse. -- Updates return success (unless readonly is on) but do nothing. -- Binds other than as the rootdn fail unless the database option "bind on" is given. -- The slapadd(8) and slapcat(8) tools are equally exciting. +* Searches return success but no entries. +* Compares return compareFalse. +* Updates return success (unless readonly is on) but do nothing. +* Binds other than as the rootdn fail unless the database option "bind on" is given. +* The slapadd(8) and slapcat(8) tools are equally exciting. Inspired by the {{F:/dev/null}} device. diff --git a/doc/guide/admin/guide.book b/doc/guide/admin/guide.book index 8cc44b79e1..200a227edd 100644 --- a/doc/guide/admin/guide.book +++ b/doc/guide/admin/guide.book @@ -1,3 +1,3 @@ #HTMLDOC 1.8.27 --t pdf14 -f "guide.pdf" --book --toclevels 3 --no-numbered --toctitle "Table of Contents" --title --titleimage "../images/LDAPwww.gif" --linkstyle plain --size Universal --left 1.00in --right 0.50in --top 36 --bottom 36 --header .t. --header1 ... --footer ..1 --nup 1 --tocheader .t. --tocfooter ..i --duplex --portrait --color --no-pscommands --no-xrxcomments --compression=1 --jpeg=0 --fontsize 11.0 --fontspacing 1.2 --headingfont Helvetica --bodyfont Times --headfootsize 11.0 --headfootfont Helvetica --charset iso-8859-1 --links --embedfonts --pagemode outline --pagelayout single --firstpage p1 --pageeffect none --pageduration 10 --effectduration 1.0 --no-encryption --permissions all --owner-password "" --user-password "" --browserwidth 680 --no-strict --no-overflow +-t pdf14 -f "OpenLDAP-Admin-Guide.pdf" --book --toclevels 3 --no-numbered --toctitle "Table of Contents" --title --titleimage "../images/LDAPwww.gif" --linkstyle plain --size Universal --left 1.00in --right 0.50in --top 0.50in --bottom 0.50in --header .t. --header1 ... --footer ..1 --nup 1 --tocheader .t. --tocfooter ..i --duplex --portrait --color --no-pscommands --no-xrxcomments --compression=1 --jpeg=0 --fontsize 11.0 --fontspacing 1.2 --headingfont Helvetica --bodyfont Times --headfootsize 11.0 --headfootfont Helvetica --charset iso-8859-1 --links --embedfonts --pagemode outline --pagelayout single --firstpage p1 --pageeffect none --pageduration 10 --effectduration 1.0 --no-encryption --permissions all --owner-password "" --user-password "" --browserwidth 680 --no-strict --no-overflow admin.html diff --git a/doc/guide/admin/intro.sdf b/doc/guide/admin/intro.sdf index 4c8afea472..71f4f543fc 100644 --- a/doc/guide/admin/intro.sdf +++ b/doc/guide/admin/intro.sdf @@ -211,12 +211,12 @@ H2: What is the difference between LDAPv2 and LDAPv3? LDAPv3 was developed in the late 1990's to replace LDAPv2. LDAPv3 adds the following features to LDAP: - - Strong authentication and data security services via {{TERM:SASL}} - - Certificate authentication and data security services via {{TERM:TLS}} (SSL) - - Internationalization through the use of Unicode - - Referrals and Continuations - - Schema Discovery - - Extensibility (controls, extended operations, and more) + * Strong authentication and data security services via {{TERM:SASL}} + * Certificate authentication and data security services via {{TERM:TLS}} (SSL) + * Internationalization through the use of Unicode + * Referrals and Continuations + * Schema Discovery + * Extensibility (controls, extended operations, and more) LDAPv2 is historic ({{REF:RFC3494}}). As most {{so-called}} LDAPv2 implementations (including {{slapd}}(8)) do not conform to the diff --git a/doc/guide/admin/maintenance.sdf b/doc/guide/admin/maintenance.sdf index 7ed638fb55..5bba1a5f5a 100644 --- a/doc/guide/admin/maintenance.sdf +++ b/doc/guide/admin/maintenance.sdf @@ -54,10 +54,10 @@ To understand the {{F:db_archive}} interface, the reader should refer to chapter 9 of the Berkeley DB guide. In particular, the following chapters are recommended: -- Database and log file archival -- Log file removal -- Recovery procedures -- Hot failover +* Database and log file archival +* Log file removal +* Recovery procedures +* Hot failover Advanced installations can use special environment settings to fine-tune some Berkeley DB options (change the log file limit, etc). This can be done by using @@ -71,10 +71,10 @@ Use them with extreme caution. Do not use them unless You know what You are doin The advantages of {{F:DB_CONFIG}} usage can be the following: -- to keep data files and log files on different mediums (i.e. disks) to improve +* to keep data files and log files on different mediums (i.e. disks) to improve performance and/or reliability; -- to fine-tune some specific options (such as shared memory region sizes); -- to set the log file limit (please read Log file limits before doing this). +* to fine-tune some specific options (such as shared memory region sizes); +* to set the log file limit (please read Log file limits before doing this). To figure out the best-practice BDB backup scenario, the reader is highly recommended to read the whole Chapter 9: Berkeley DB Transactional Data Store Applications. diff --git a/doc/guide/admin/master.sdf b/doc/guide/admin/master.sdf index 7c7968ee19..f9dc9ee61a 100644 --- a/doc/guide/admin/master.sdf +++ b/doc/guide/admin/master.sdf @@ -85,6 +85,9 @@ PB: PB: # Appendices +!include "appendix-changes.sdf"; appendix +PB: + # Config file examples !include "appendix-configs.sdf"; appendix PB: diff --git a/doc/guide/admin/monitoringslapd.sdf b/doc/guide/admin/monitoringslapd.sdf index f09ec97031..a21ebcaf5b 100644 --- a/doc/guide/admin/monitoringslapd.sdf +++ b/doc/guide/admin/monitoringslapd.sdf @@ -498,3 +498,8 @@ Write waiters: > entryDN: cn=Write,cn=Waiters,cn=Monitor > subschemaSubentry: cn=Subschema > hasSubordinates: FALSE + +Add new monitored things here and discuss, referencing man pages and present +examples + + diff --git a/doc/guide/admin/overlays.sdf b/doc/guide/admin/overlays.sdf index 936102604e..0353ba375e 100644 --- a/doc/guide/admin/overlays.sdf +++ b/doc/guide/admin/overlays.sdf @@ -147,6 +147,12 @@ This overlay allows expansion of dynamic groups and more. H3: Dynamic List Configuration +H2: Reverse Group Membership Maintenance + + +H3: Member Of Configuration + + H2: The Proxy Cache Engine {{TERM:LDAP}} servers typically hold one or more subtrees of a diff --git a/doc/guide/admin/replication.sdf b/doc/guide/admin/replication.sdf index a63dc1d198..0d4b4e6784 100644 --- a/doc/guide/admin/replication.sdf +++ b/doc/guide/admin/replication.sdf @@ -27,11 +27,11 @@ The slurpd daemon was the original replication mechanism inherited from UMich's LDAP and operates in push mode: the master pushes changes to the slaves. It has been replaced for many reasons, in brief: - - It is not reliable - - It is extremely sensitive to the ordering of records in the replog - - It can easily go out of sync, at which point manual intervention is + * It is not reliable + * It is extremely sensitive to the ordering of records in the replog + * It can easily go out of sync, at which point manual intervention is required to resync the slave database with the master directory - - It isn't very tolerant of unavailable servers. If a slave goes down + * It isn't very tolerant of unavailable servers. If a slave goes down for a long time, the replog may grow to a size that's too large for slurpd to process @@ -41,11 +41,11 @@ Syncrepl. {{Why is Syncrepl better?}} - - Syncrepl is self-synchronizing; you can start with a database in any + * Syncrepl is self-synchronizing; you can start with a database in any state from totally empty to fully synced and it will automatically do the right thing to achieve and maintain synchronization - - Syncrepl can operate in either direction - - Data updates can be minimal or maximal + * Syncrepl can operate in either direction + * Data updates can be minimal or maximal {{How do I implement a pushed based replication system using Syncrepl?}} diff --git a/doc/guide/admin/tls.sdf b/doc/guide/admin/tls.sdf index e1fa756cba..78725a6951 100644 --- a/doc/guide/admin/tls.sdf +++ b/doc/guide/admin/tls.sdf @@ -10,6 +10,8 @@ integrity and confidentiality protections and to support LDAP authentication using the {{TERM:SASL}} {{TERM:EXTERNAL}} mechanism. TLS is defined in {{REF:RFC4346}}. +Note: For generating certifcates, please reference {{URL:http://www.openldap.org/faq/data/cache/185.html}} + H2: TLS Certificates TLS uses {{TERM:X.509}} certificates to carry client and server diff --git a/doc/guide/admin/troubleshooting.sdf b/doc/guide/admin/troubleshooting.sdf index 5449003aa7..f1992fa492 100644 --- a/doc/guide/admin/troubleshooting.sdf +++ b/doc/guide/admin/troubleshooting.sdf @@ -31,7 +31,10 @@ The following checklist can help track down your problem. Please try to use if { posting to the list, or in the rare circumstances of reporting a bug. .{{S: }} -^{{B: Is {{slapd}} running?}} +^{{B: Use the {{slaptest}} tool to verify configurations before starting {{slapd}}}} + +.{{S: }} ++{{B: Verify that {{slapd}} is listening to the specified port(s) (389 and 636, generally) before trying the {{ldapsearch}}}} .{{S: }} +{{B: Can you issue an {{ldapsearch}}?}} @@ -60,9 +63,9 @@ the general LDAP forum for non-commercial discussions and information relating t H2: How to contact the OpenLDAP Project -- Mailing Lists: {{URL:http://www.openldap.org/lists/}} -- Project: {{URL: http://www.openldap.org/project/}} -- Issue Tracking: {{URL:http://www.openldap.org/its/}} +* Mailing Lists: {{URL:http://www.openldap.org/lists/}} +* Project: {{URL: http://www.openldap.org/project/}} +* Issue Tracking: {{URL:http://www.openldap.org/its/}} H2: How to present your problem @@ -70,6 +73,10 @@ H2: How to present your problem H2: Debugging {{slapd}}(8) +* Loglevel 256 is generally a good first loglevel to try for getting + information useful to list members on issues +* Running {{slapd -d -1}} can often track down fairly simple issues, such as + missing schemas and incorrect file permissions for the {{slapd}} user to things like certs H2: Commercial Support diff --git a/doc/guide/admin/tuning.sdf b/doc/guide/admin/tuning.sdf index e791e0a9d8..54dd7e6951 100644 --- a/doc/guide/admin/tuning.sdf +++ b/doc/guide/admin/tuning.sdf @@ -300,13 +300,13 @@ A default config can be found in the answer: just change the set_lg_dir to point to your .log directory or comment that line. Quick guide: -- Create a DB_CONFIG file in your ldap home directory (/var/lib/ldap/DB_CONFIG) with the correct "set_cachesize" value -- stop your ldap server and run db_recover -h /var/lib/ldap -- start your ldap server and check the new cache size with: +* Create a DB_CONFIG file in your ldap home directory (/var/lib/ldap/DB_CONFIG) with the correct "set_cachesize" value +* stop your ldap server and run db_recover -h /var/lib/ldap +* start your ldap server and check the new cache size with: db_stat -h /var/lib/ldap -m | head -n 2 -- this procedure is only needed if you use OpenLDAP 2.2 with the BDB or HDB backends; In OpenLDAP 2.3 DB recovery is performed automatically whenever the DB_CONFIG file is changed or when an unclean shutdown is detected. +* this procedure is only needed if you use OpenLDAP 2.2 with the BDB or HDB backends; In OpenLDAP 2.3 DB recovery is performed automatically whenever the DB_CONFIG file is changed or when an unclean shutdown is detected. --On Tuesday, February 22, 2005 12:15 PM -0500 Dusty Doris wrote: -- 2.39.5