Sync with HEAD

doc/guide/admin/Makefile

+## Makefile for OpenLDAP Administrator's Guide
+# $OpenLDAP$
+## This work is part of OpenLDAP Software <http://www.openldap.org/>.
+##
+## Copyright 2005 The OpenLDAP Foundation.
+## All rights reserved.
+##
+## Redistribution and use in source and binary forms, with or without
+## modification, are permitted only as authorized by the OpenLDAP
+## Public License.
+##
+## A copy of this license is available in the file LICENSE in the
+## top-level directory of the distribution or, alternatively, at
+## <http://www.OpenLDAP.org/license.html>.
+all: guide.html index.html
+
+sdf-src: \
+	../plain.sdf \
+	../preamble.sdf \
+	abstract.sdf \
+	config.sdf \
+	dbtools.sdf \
+	guide.sdf \
+	install.sdf \
+	intro.sdf \
+	master.sdf \
+	monitoringslapd.sdf \
+	preface.sdf \
+	proxycache.sdf \
+	quickstart.sdf \
+	referrals.sdf \
+	replication.sdf \
+	runningslapd.sdf \
+	sasl.sdf \
+	schema.sdf \
+	security.sdf \
+	slapdconfig.sdf \
+	syncrepl.sdf \
+	title.sdf \
+	tls.sdf \
+	tuning.sdf
+
+sdf-img: \
+	../images/LDAPlogo.gif \
+	config_local.gif \
+	config_ref.gif \
+	config_repl.gif \
+	config_x500fe.gif \
+	config_x500ref.gif \
+	intro_dctree.gif \
+	intro_tree.gif \
+	replication.gif
+
+guide.html: guide.sdf sdf-src sdf-img
+	sdf -2html guide.sdf
+
+index.html: index.sdf sdf-src sdf-img
+	sdf -2topics index.sdf
+
+admin.html: admin.sdf sdf-src sdf-img
+	sdf -DPDF -2html admin.sdf
+
+guide.pdf: admin.html
+	htmldoc --book --duplex --bottom 36 --top 36 \
+		--toclevels 2 \
+		-f guide.pdf admin.html

doc/guide/admin/admin.sdf

+# $OpenLDAP$
+# Copyright 1999-2005, The OpenLDAP Foundation, All Rights Reserved.
+# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
+#
+# guide.sdf 
+#
+
+!define DOC_TOC 0
+
+!macro build_html_cover
+!endmacro
+
+!include "master.sdf"

doc/guide/admin/intro.sdf

 # $OpenLDAP$
-# Copyright 1999-2003, The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2005, The OpenLDAP Foundation, All Rights Reserved.
 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
 H1: Introduction to OpenLDAP Directory Services
 
@@ -132,10 +132,10 @@ be useful to you.
 
 {{How is the information protected from unauthorized access?}} Some
 directory services provide no protection, allowing anyone to see
-the information. LDAP provides a mechanism for a client to
-authenticate, or prove its identity to a directory server, paving
-the way for rich access control to protect the information the
-server contains.  LDAP also supports privacy and integrity security
+the information. LDAP provides a mechanism for a client to authenticate,
+or prove its identity to a directory server, paving the way for
+rich access control to protect the information the server contains.
+LDAP also supports data security (integrity and confidentiality)
 services.
 
 
@@ -172,8 +172,8 @@ servers.
 
 The stand-alone LDAP daemon, or {{slapd}}(8), can be viewed as a
 {{lightweight}} X.500 directory server.  That is, it does not
-implement the X.500's DAP.  As a {{lightweight directory}} server,
-{{slapd}}(8) implements only a subset of the X.500 models.
+implement the X.500's DAP nor does it support the complete X.500
+models.
 
 If you are already running a X.500 DAP service and you want to
 continue to do so, you can probably stop reading this guide.  This
@@ -194,19 +194,19 @@ 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 via {{TERM:SASL}}
- - Integrity and Confidentiality Protection via {{TERM:TLS}} (SSL)
+ - 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 implementations
-(including {{slapd}}(8)) of LDAPv2 do not conform to the LDAPv2
-technical specification, interoperatibility amongst implementations
-claiming LDAPv2 support will be limited.  As LDAPv2 differs
-significantly from LDAPv3, deploying both LDAPv2 and LDAPv3
-simultaneously can be quite problematic.  LDAPv2 should be avoided.
+LDAPv2 is historic ({{REF:RFC3494}}).  As most {{so-called}} LDAPv2
+implementations (including {{slapd}}(8)) do not conform to the
+LDAPv2 technical specification, interoperatibility amongst
+implementations claiming LDAPv2 support is limited.  As LDAPv2
+differs significantly from LDAPv3, deploying both LDAPv2 and LDAPv3
+simultaneously is quite problematic.  LDAPv2 should be avoided.
 LDAPv2 is disabled by default.
 
 
@@ -223,12 +223,14 @@ interesting features and capabilities include:
 {{slapd}} supports LDAP over both IPv4 and IPv6 and Unix IPC.
 
 {{B:{{TERM[expand]SASL}}}}: {{slapd}} supports strong authentication
-services through the use of SASL.  {{slapd}}'s SASL implementation
-utilizes {{PRD:Cyrus}} {{PRD:SASL}} software which supports a number
-of mechanisms including DIGEST-MD5, EXTERNAL, and GSSAPI.
-
-{{B:{{TERM[expand]TLS}}}}: {{slapd}} provides privacy and integrity
-protections through the use of TLS (or SSL).  {{slapd}}'s TLS
+and data security (integrity and confidentiality) services through
+the use of SASL.  {{slapd}}'s SASL implementation utilizes {{PRD:Cyrus}}
+{{PRD:SASL}} software which supports a number of mechanisms including
+DIGEST-MD5, EXTERNAL, and GSSAPI.
+
+{{B:{{TERM[expand]TLS}}}}: {{slapd}} supports certificate-based
+authentication and data security (integrity and confidentiality)
+services through the use of TLS (or SSL).  {{slapd}}'s TLS
 implementation utilizes {{PRD:OpenSSL}} software.
 
 {{B:Topology control}}: {{slapd}} can be configured to restrict
@@ -239,8 +241,8 @@ This feature utilizes {{TCP wrappers}}.
 control facility, allowing you to control access to the information
 in your database(s). You can control access to entries based on
 LDAP authorization information, {{TERM:IP}} address, domain name
-and other criteria.  {{slapd}} supports both {{static}} and
-{{dynamic}} access control information.
+and other criteria.  {{slapd}} supports both {{static}} and {{dynamic}}
+access control information.
 
 {{B:Internationalization}}: {{slapd}} supports Unicode and language
 tags.
@@ -248,11 +250,12 @@ tags.
 {{B:Choice of database backends}}: {{slapd}} comes with a variety
 of different database backends you can choose from. They include
 {{TERM:BDB}}, a high-performance transactional database backend;
+{{TERM:HDB}}, a hierarchical high-performance transactional backend;
 {{TERM:LDBM}}, a lightweight DBM based backend; {{SHELL}}, a backend
 interface to arbitrary shell scripts; and PASSWD, a simple backend
-interface to the {{passwd}}(5) file.  The BDB backend utilizes
-{{ORG:Sleepycat}} {{PRD:Berkeley DB}}.  The LDBM utilizes either
-{{PRD:Berkeley DB}} or {{PRD:GDBM}}.
+interface to the {{passwd}}(5) file.  The BDB and HDB backends
+utilize {{ORG:Sleepycat}} {{PRD:Berkeley DB}}.  The LDBM utilizes
+either {{PRD:Berkeley DB}} or {{PRD:GDBM}}.
 
 {{B:Multiple database instances}}: {{slapd}} can be configured to
 serve multiple databases at the same time. This means that a single
@@ -264,7 +267,7 @@ backends.
 {{slapd}} lets you write your own modules easily. {{slapd}} consists
 of two distinct parts: a front end that handles protocol communication
 with LDAP clients; and modules which handle specific tasks such as
-database operations. Because these two pieces communicate via a
+database operations.  Because these two pieces communicate via a
 well-defined {{TERM:C}} {{TERM:API}}, you can write your own
 customized modules which extend {{slapd}} in numerous ways.  Also,
 a number of {{programmable database}} modules are provided.  These
@@ -273,8 +276,8 @@ programming languages ({{PRD:Perl}}, {{shell}}, {{PRD:SQL}}, and
 {{PRD:TCL}}).
 
 {{B:Threads}}: {{slapd}} is threaded for high performance.  A single
-multi-threaded {{slapd}} process handles all incoming requests
-using a pool of threads.  This reduces the amount of system overhead
+multi-threaded {{slapd}} process handles all incoming requests using
+a pool of threads.  This reduces the amount of system overhead
 required while providing high performance.
 
 {{B:Replication}}: {{slapd}} can be configured to maintain shadow

doc/guide/admin/master.sdf

 # $OpenLDAP$
-# Copyright 1999-2003, The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2005, The OpenLDAP Foundation, All Rights Reserved.
 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
 #
 # master file for the OpenLDAP Administrator's Guide
@@ -36,6 +36,9 @@ PB:
 !include "install.sdf"; chapter
 PB:
 
+!include "slapdconf2.sdf"; chapter
+PB:
+
 !include "slapdconfig.sdf"; chapter
 PB:
 

doc/guide/admin/schema.sdf

 # $OpenLDAP$
-# Copyright 1999-2003, The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2005, The OpenLDAP Foundation, All Rights Reserved.
 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
 
 H1: Schema Specification
@@ -81,15 +81,13 @@ There are five steps to defining new schema:
 
 H3: Object Identifiers
 
-Each schema element is identified by a globally unique
-{{TERM[expand]OID}} (OID).  OIDs are also used to identify
-other objects.
-They are commonly found in protocols described by {{TERM:ASN.1}}.  In
+Each schema element is identified by a globally unique {{TERM[expand]OID}}
+(OID).  OIDs are also used to identify other objects.  They are
+commonly found in protocols described by {{TERM:ASN.1}}.  In
 particular, they are heavily used by the {{TERM[expand]SNMP}} (SNMP).
-As OIDs are hierarchical, your organization
-can obtain one OID and branch it as needed.  For example,
-if your organization were assigned OID {{EX:1.1}}, you could branch
-the tree as follows:
+As OIDs are hierarchical, your organization can obtain one OID and
+branch it as needed.  For example, if your organization were assigned
+OID {{EX:1.1}}, you could branch the tree as follows:
 
 !block table; colaligns="LR"; coltags="EX,N"; align=Center; \
 	title="Table 8.2: Example OID hierarchy"
@@ -129,10 +127,7 @@ you.  OIDs obtained using this form may be used for any purpose
 including identifying LDAP schema elements.
 
 Alternatively, OID name space may be available from a national
-authority (e.g., ANSI, BSI).
-
-For private experiments, OIDs under {{EX:1.1}} may be used.  The
-OID {{EX:1.1}} arc is regarded as dead name space.
+authority (e.g., {{ORG:ANSI}}, {{ORG:BSI}}).
 
 
 H3: Name Prefix

doc/guide/admin/security.sdf

-# Copyright 1999-2003, The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2005, The OpenLDAP Foundation, All Rights Reserved.
 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
 
 H1: Security Considerations
 
 OpenLDAP Software is designed to run in a wide variety of computing
 environments from tightly-controlled closed networks to the global
-Internet.  Hence, OpenLDAP Software provides many different security
+Internet.  Hence, OpenLDAP Software supports many different security
 mechanisms.  This chapter describes these mechanisms and discusses
 security considerations for using OpenLDAP Software.
 
@@ -37,12 +37,9 @@ H3: IP Firewall
 to restrict access based upon the client's IP address and/or network
 interface used to communicate with the client.
 
-Generally, {{slapd}}(8) listens on port 389/tcp for LDAP over
-{{TERM:TCP}} (e.g.  {{F:ldap://}}) and port 636/tcp for LDAP over
-{{TERM:SSL}} (e.g.  {{F:ldaps://}}).  Note that LDAP over TCP
-sessions can be protected by {{TERM:TLS}} through the use of
-{{StartTLS}}.  StartTLS is the Standard Track mechanism for protecting
-LDAP sessions with TLS.
+Generally, {{slapd}}(8) listens on port 389/tcp for {{F:ldap://}}
+sessions and port 636/tcp for {{F:ldaps://}}) sessions.  {{slapd}}(8)
+may be configured to listen on other ports.
 
 As specifics of how to configure IP firewall are dependent on the
 particular kind of IP firewall used, no examples are provided here.
@@ -51,9 +48,9 @@ See the document associated with your IP firewall.
 
 H3: TCP Wrappers
 
-OpenLDAP supports {{TERM:TCP}} Wrappers.  TCP Wrappers provide a rule-based
-access control system for controlling TCP/IP access to the server.
-For example, the {{host_options}}(5) rule:
+{{slapd}}(8) supports {{TERM:TCP}} Wrappers.  TCP Wrappers provide
+a rule-based access control system for controlling TCP/IP access
+to the server.  For example, the {{host_options}}(5) rule:
 
 >	slapd: 10.0.0.0/255.0.0.0 127.0.0.1 : ALLOW
 >	slapd: ALL : DENY
@@ -71,15 +68,16 @@ of TCP wrappers.
 See {{hosts_access}}(5) for more information on TCP wrapper rules.
 
 
-H2: Integrity and Confidentiality Protection
+H2: Data Integrity and Confidentiality Protection
 
-{{TERM[expand]TLS}} (TLS) can be used to provide integrity and
-confidentiality protection.  OpenLDAP supports both StartTLS and
-{{F:ldaps://}}.  See the {{SECT:Using TLS}} chapter for more
-information.
+{{TERM[expand]TLS}} (TLS) can be used to provide data integrity and
+confidentiality protection.  OpenLDAP supports negotiation of
+{{TERM:TLS}} ({{TERM:SSL}}) via both StartTLS and {{F:ldaps://}}.
+See the {{SECT:Using TLS}} chapter for more information.  StartTLS
+is the standard track mechanism.
 
 A number of {{TERM[expand]SASL}} (SASL) mechanisms, such as DIGEST-MD5
-and {{TERM:GSSAPI}}, also provide integrity and confidentiality
+and {{TERM:GSSAPI}}, also provide data integrity and confidentiality
 protection.  See the {{SECT:Using SASL}} chapter for more information.
 
 
@@ -124,41 +122,42 @@ to the "simple" bind operation.  Unauthenticated access is obtained
 by providing a name but no password.  Authenticated access is obtain
 by providing a valid name and password.
 
-An anonymous bind results in an {{anonymous}} authorization.
-Anonymous bind mechanism is enabled by default, but can be disabled
-by specifying "{{EX:disallow bind_anon}}" in {{slapd.conf}}(5).
+An anonymous bind results in an {{anonymous}} authorization
+association.  Anonymous bind mechanism is enabled by default, but
+can be disabled by specifying "{{EX:disallow bind_anon}}" in
+{{slapd.conf}}(5).
 
-An unauthenticated bind results in an {{anonymous}} authorization.
-Unauthenticated bind mechanism is disabled by default, but can be
-enabled by specifying "{{EX:allow bind_anon_cred}}" in {{slapd.conf}}(5).
-As a number of LDAP applications mistakenly generate unauthenticated
-bind request when authenticated access was intended (that is, they
-do not ensure a password was provided), this mechanism should
-generally not be enabled.
+An unauthenticated bind also results in an {{anonymous}} authorization
+association.  Unauthenticated bind mechanism is disabled by default,
+but can be enabled by specifying "{{EX:allow bind_anon_cred}}" in
+{{slapd.conf}}(5).  As a number of LDAP applications mistakenly
+generate unauthenticated bind request when authenticated access was
+intended (that is, they do not ensure a password was provided),
+this mechanism should generally remain disabled.
 
 A successful user/password authenticated bind results in a user
 authorization identity, the provided name, being associated with
 the session.  User/password authenticated bind is enabled by default.
-However, as this mechanism offers no evesdropping protection (e.g.,
-the password is set in the clear), it is recommended that it be
-used only in tightly controlled systems or when the LDAP session
-is protected by other means (e.g., TLS, {{TERM:IPSEC}}).  Where the
-administrator relies on TLS to protect the password, it is recommended
-that unprotected authentication be disabled.  This is done by setting
-"{{EX:disallow bind_simple_unprotected}}" in {{slapd.conf}}(5).
-The {{EX:security}} directive's {{EX:simple_bind}} option provides
-fine grain control over the level of confidential protection to
-require for {{simple}} user/password authentication.
+However, as this mechanism itself offers no evesdropping protection
+(e.g., the password is set in the clear), it is recommended that
+it be used only in tightly controlled systems or when the LDAP
+session is protected by other means (e.g., TLS, {{TERM:IPSEC}}).
+Where the administrator relies on TLS to protect the password, it
+is recommended that unprotected authentication be disabled.  This
+is done by setting "{{EX:disallow bind_simple_unprotected}}" in
+{{slapd.conf}}(5).  The {{EX:security}} directive's {{EX:simple_bind}}
+option provides fine grain control over the level of confidential
+protection to require for {{simple}} user/password authentication.
 
 The user/password authenticated bind mechanism can be completely
 disabled by setting "{{EX:disallow bind_simple}}".
 
 Note:  An unsuccessful bind always results in the session having
-an {{anonymous}} authorization state.
+an {{anonymous}} authorization association.
 
 
 H3: SASL method
 
-The LDAP SASL method allows use of any SASL authentication
+The LDAP {{TERM:SASL}} method allows use of any SASL authentication
 mechanism.  The {{SECT:Using SASL}} discusses use of SASL.
 

doc/guide/admin/slapdconfig.sdf

 # $OpenLDAP$
-# Copyright 1999-2003, The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2005, The OpenLDAP Foundation, All Rights Reserved.
 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
 
 H1: The slapd Configuration File
@@ -287,13 +287,12 @@ perform" error.
 H4: replica
 
 >	replica uri=ldap[s]://<hostname>[:<port>] | host=<hostname>[:<port>]
->		[bindmethod={simple|kerberos|sasl}]
+>		[bindmethod={simple|sasl}]
 >		["binddn=<DN>"]
 >		[saslmech=<mech>]
 >		[authcid=<identity>]
 >		[authzid=<identity>]
 >		[credentials=<password>]
->		[srvtab=<filename>]
 
 This directive specifies a replication site for this database. The
 {{EX:uri=}} parameter specifies a scheme, a host and optionally a port where
@@ -316,20 +315,14 @@ database.  Since DNs are likely to contain embedded spaces, the
 entire {{EX:"binddn=<DN>"}} string should be enclosed in double
 quotes.
 
-The {{EX:bindmethod}} is {{EX:simple}} or {{EX:kerberos}} or {{EX:sasl}},
-depending on whether simple password-based authentication or Kerberos
-authentication or {{TERM:SASL}} authentication is to be used when connecting
-to the slave slapd.
+The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}}, depending
+on whether simple password-based authentication or {{TERM:SASL}}
+authentication is to be used when connecting to the slave slapd.
 
-Simple authentication should not be used unless adequate integrity
-and privacy protections are in place (e.g. TLS or IPSEC).  Simple
-authentication requires specification of {{EX:binddn}} and
-{{EX:credentials}} parameters.
-
-Kerberos authentication is deprecated in favor of SASL authentication
-mechanisms, in particular the {{EX:KERBEROS_V4}} and {{EX:GSSAPI}}
-mechanisms.  Kerberos authentication requires {{EX:binddn}} and
-{{EX:srvtab}} parameters.
+Simple authentication should not be used unless adequate data
+integrity and confidentiality protections are in place (e.g. TLS
+or IPSEC).  Simple authentication requires specification of
+{{EX:binddn}} and {{EX:credentials}} parameters.
 
 SASL authentication is generally recommended.  SASL authentication
 requires specification of a mechanism using the {{EX:saslmech}} parameter.
@@ -430,7 +423,6 @@ H4: syncrepl
 >		[sizelimit=<limit>]
 >		[timelimit=<limit>]
 >		[schemachecking=on|off]
->		[updatedn=<DN>]
 >		[bindmethod=simple|sasl]
 >		[binddn=<DN>]
 >		[saslmech=<mech>]
@@ -507,15 +499,6 @@ required by the schema definition.
 If it is turned off, entries will be stored without checking
 schema conformance. The default is off.
 
-The {{EX:updatedn}} parameter specifies the DN in the consumer site
-which is allowed to make changes to the replica. This DN is used
-locally by the syncrepl engine when updating the replica with the
-entries received from the provider site by using the internal
-operation mechanism. The update of the replica content is subject
-to the access control privileges of the DN.  The DN should have
-read/write access to the replica database.  Generally, this DN
-{{should not}} be the same as {{EX:rootdn}}.
-
 The {{EX:binddn}} parameter gives the DN to bind as for the
 syncrepl searches to the provider slapd. It should be a DN
 which has read access to the replication content in the
@@ -526,10 +509,10 @@ depending on whether simple password-based authentication or
 {{TERM:SASL}} authentication is to be used when connecting
 to the provider slapd.
 
-Simple authentication should not be used unless adequate integrity
-and privacy protections are in place (e.g. TLS or IPSEC). Simple
-authentication requires specification of {{EX:binddn}} and
-{{EX:credentials}} parameters.
+Simple authentication should not be used unless adequate data
+integrity and confidentiality protections are in place (e.g. TLS
+or IPSEC). Simple authentication requires specification of {{EX:binddn}}
+and {{EX:credentials}} parameters.
 
 SASL authentication is generally recommended.  SASL authentication
 requires specification of a mechanism using the {{EX:saslmech}} parameter.
@@ -597,33 +580,6 @@ containing the database and associated indices live.
 >	directory /usr/local/var/openldap-data
 
 
-H4: sessionlog <sid> <limit>
-
-This directive specifies a session log store in the syncrepl 
-replication provider server which contains information on
-the entries that have been scoped out of the replication
-content identified by {{EX:<sid>}}.
-The first syncrepl search request having the same {{EX:<sid>}} value
-in the cookie establishes the session log store in the provider server.
-The number of the entries in the session log store is limited
-by {{EX:<limit>}}. Excessive entries are removed from the store
-in the FIFO order. Both {{EX:<sid>}} and {{EX:<limit>}} are
-non-negative integers. {{EX:<sid>}} has no more than three decimal digits.
-
-The LDAP Content Synchronization operation that falls into a pre-existing
-session can use the session log store in order to reduce the amount
-of synchronization traffic. If the replica is not so outdated that
-it can be made up-to-date by the information in the session store,
-the provider slapd will send the consumer slapd the identities of the
-scoped-out entries together with the in-scope entries added to or
-modified within the replication content. If the replica status is
-outdated too much and beyond the coverage of the history store,
-then the provider slapd will send the identities of the unchanged
-in-scope entries along with the changed in-scope entries.
-The consumer slapd will then remove those entries in the replica
-which are not identified as present in the provider content.
-
-
 H3: LDBM Database Directives
 
 Directives in this category only apply to a {{TERM:LDBM}} database.