Fix up hyperlinks and revamp slapdconfig and misc other sections

doc/guide/admin/intro.sdf

 # $OpenLDAP$
 # Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
-H1: Introduction to slapd and slurpd
+H1: Introduction to OpenLDAP Directory Services
 
-This document describes how to build, configure, and run the stand-alone
-{{TERM:LDAP}} daemon, {{slapd}}(8) and the stand-alone LDAP update replication
-daemon, {{slurpd}}(8). It is intended for newcomers and experienced
+This document describes how to build, configure, and operate OpenLDAP
+software to provide directory services.  This includes details on
+how to configure and run the stand-alone {{TERM:LDAP}} daemon,
+{{slapd}}(8) and the stand-alone LDAP update replication daemon,
+{{slurpd}}(8). It is intended for newcomers and experienced
 administrators alike. This section provides a basic introduction to
 directory services and, in particular, the directory services provided
 by {{slapd}}(8).
@@ -222,21 +224,20 @@ H2: What about X.500?
 
 Technically, LDAP is a directory access protocol to an {{TERM:X.500}}
 directory service, the {{TERM:OSI}} directory service.  Initial
-LDAP servers were were gateway between LDAP and the X.500
-{{TERM[expand]DAP}} ({{TERM:DAP}}).
-DAP is a heavyweight protocol that runs over a full OSI protocol stack
-and requires a significant amount of computing resources to run.
-LDAP is designed to operate over {{TERM:TCP}}/{{TERM:IP}} and provides
-most of the functionality of DAP at a much lower cost.
+LDAP servers were gateway between LDAP and the X.500 {{TERM[expand]DAP}}
+({{TERM:DAP}}).  DAP is a heavyweight protocol that operates over a full
+OSI protocol stack and requires a significant amount of computing
+resources.  LDAP is designed to operate over {{TERM:TCP}}/{{TERM:IP}}
+and provides most of the functionality of DAP at a much lower cost.
 
 This use of LDAP makes it easy to access the X.500 directory, but still
 requires a full X.500 service to make data available to the many LDAP
 clients being developed. As with full X.500 DAP clients, a full X.500
-DAP server is no small piece of software to run.
+DAP server is no small piece of software to operate.
 
 The stand-alone LDAP daemon, or {{slapd}}(8), is meant to remove much
 of the burden from the server side just as LDAP itself removed much of
-the burden from clients. If you are already running an X.500 DAP service
+the burden from clients. 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, which is all about running LDAP via {{slapd}}, without running
 X.500 DAP. If you are not running X.500 DAP, want to stop running
@@ -245,7 +246,10 @@ X.500 DAP, or have no immediate plans to run X.500 DAP, read on.
 It is possible to replicate data from a {{slapd}} directory 
 server to a X.500 {{TERM:DSA}}, which allows your organization to
 make your data available as part of the global X.500 DAP directory
-service on a "read-only" basis. This is discussed in section 11.6.
+service on a {{read-only}} basis.  See the
+{{SECT:Replication to an X.500 DSA}}
+section in the
+{{SECT:Replication with slurpd}} chapter of this document.
 
 Another way to make data in a {{slapd}} server available to the
 X.500 community would be by using a X.500 DAP to LDAP gateway. At
@@ -264,3 +268,6 @@ replicas might be down or unreachable when a change comes through;
 {{slurpd}} handles retrying failed requests automatically. 
 {{slapd}} and {{slurpd}} communicate through a simple text 
 file that is used to log changes.
+
+See the {{SECT:Replication with slurpd}} chapter for information
+about how to configure and run {{slurpd}}(8).

doc/guide/admin/quickstart.sdf

@@ -7,15 +7,13 @@ H1: A Quick-Start Guide to Running slapd
 This chapter provides a quick step-by-step guide to building,
 installing and running {{slapd}}(8). It is intended to provide
 users with a simple and quick way to get started only.
-If you intend to run slapd seriously, you should read the rest
+If you intend to run {{slapd}} seriously, you should read the rest
 of this guide.
 
 
 Note: This guide does not use strong authentication nor any
 privacy and integrity protection services.  These services are
-described in detail in later chapters.  This guide should
-only be used in isolated environments (such as on a single
-host protected by a firewall).
+described in detail in later chapters.
 
 
 ^{{B:Get the software}}.
@@ -71,7 +69,8 @@ is installed into {{F:/usr/local}}.  This is typically done as root.
 +{{B:Edit the configuration file}}.
 
 .Use this chapter as a brief tutorial.  For more details on the
-configuration file, see slapd.conf(5) and chapter 5.
+configuration file, see slapd.conf(5) and the
+{{SECT:The slapd Configuration File}} chapter of this document.
 
 .Now we need to edit the default configuration file that was
 installed earlier.  The {{slapd}} configuration file {{slapd.conf}}(5)
@@ -133,7 +132,7 @@ mechanisms.  These are described in later chapters.
 . At this point the LDAP server is up and running, but there isn't
 any data in the directory.  You can check to see if the server is
 running and your naming context (the {{EX:suffix}} you specified above)
-by searching it with {{ldapsearch}}(1).  By default ldapsearch is
+by searching it with {{ldapsearch}}(1).  By default, ldapsearch is
 installed as {{F:/usr/local/bin/ldapsearch}}.
 
 ..{{EX:ldapsearch -x -b '' -s base '(objectclass=*)' namingContexts}}
@@ -151,7 +150,8 @@ special characters from interpreted by the shell.  This should return:
 . This is a two-step process. The first step is to create a file
 (we'll call it {{F:example.ldif}}) containing the entries you
 want your database to contain. Use the following example as a
-guide, or see Section 7.3 for more details.
+guide, or see {{Database Creation and Maintenance Tools}} section
+of this document for more details.
 
 ..{{EX:dn: dc=example, dc=net}}
 ..{{EX:objectclass: dcObject}}
@@ -203,7 +203,8 @@ database grants {{read access to everybody}} excepting the
 {{super-user}} (as specified by the {{EX:rootdn}} configuration
 directive).  It is highly recommended that you establish controls
 to restrict access to authorized users.  Access controls are discussed
-in a later chapter.
+in the {{SECT:Access Control}} section of the
+{{SECT:The slapd Configuration File}} chapter.
 
 The following chapters provide more detailed information on making,
 installing, and running {{slapd}}(8).

doc/guide/admin/referrals.sdf

@@ -58,7 +58,7 @@ H2: Immediate Superior Knowledge Information
 
 Immediate superior knowledge information may be provided in the
 entry at the root of a delegated subtree.  The knowledge information
-is contained with {{ref}} operational attribute.
+is contained with {{EX:ref}} operational attribute.
 
 Extending the example above, a {{ref}} attribute can be added
 to the entry {{EX:dc=subtree,dc=example,dc=net}} in server B indicating
@@ -72,7 +72,7 @@ that A holds the immediate superior naming context.
 The server uses this information to generate referrals to
 management operations.
 
-For those familiar with X.500, this use of the {{ref}} attribute
+For those familiar with X.500, this use of the {{EX:ref}} attribute
 is similar to an X.500 knowledge reference held in a
 {{immSupr}} {{TERM:DSE}}.
 !endif
@@ -100,11 +100,11 @@ The server uses this information to generate referrals to
 operations acting upon operations not within or subordinate
 to any of the naming contexts held by the server.
 
-For those familiar with X.500, this use of the {{ref}} attribute
+For those familiar with X.500, this use of the {{EX:ref}} attribute
 is similar to an X.500 knowledge reference held in a
 {{Supr}} {{TERM:DSE}}.
 
-H2: ManageDSAit
+H2: The ManageDsaIT Control
 
 Adding, modify, and deleting referral objects is generally done
 using {{ldapmodify}}(1) or similar tools which support the

doc/guide/admin/replication.sdf

@@ -348,7 +348,7 @@ and exit, use the command
 >	slurpd -r /usr/tmp/replog.slave.example.com:389 -o
 
 
-H2: Replication from a slapd directory server to an X.500 DSA
+H2: Replication to an X.500 DSA
 
 In mixed environments where both X.500 DSAs and slapd
 are used, it may be desirable to replicate changes from a

doc/guide/admin/slapdconfig.sdf

@@ -4,16 +4,15 @@
 
 H1: The slapd Configuration File
 
-Once the software has been built and installed, you are ready to configure it
-for use at your site. All slapd runtime configuration is accomplished through
-the {{I:slapd.conf}}(5) file, normally installed in the
-{{EX:/usr/local/etc/openldap}} directory.
+Once the software has been built and installed, you are ready
+to configure it for use at your site. The slapd runtime configuration
+is primarily accomplished through the {{I:slapd.conf}}(5) file,
+normally installed in the {{EX:/usr/local/etc/openldap}} directory.
 
 An alternate configuration file can be specified via a
-command-line option to slapd or slurpd (see Sections 5 and 8,
-respectively). This section describes the general format of the config file,
-followed by a detailed description of each config file directive.
-
+command-line option to {{slapd}}(8) or {{slurpd}}(8). This chapter
+describes the general format of the config file, followed by a
+detailed description of commonly used config file directives.
 
 
 H2: Configuration File Format
@@ -89,31 +88,40 @@ H4: access to <what> [ by <who> <accesslevel> <control> ]+
 
 This directive grants access (specified by <accesslevel>) to a
 set of entries and/or attributes (specified by <what>) by one or
-more requesters (specified by <who>). See Section 5.3 on
-access control for more details and examples.
+more requesters (specified by <who>).
+See the {{SECT:Access Control}} section of this chapter for more
+details and examples.
 
 
 H4: attributetype <RFC2252 Attribute Type Description>
 
 This directive defines an attribute type.
 
+
 H4: defaultaccess { none | compare | search | read | write }
 
 This directive specifies the default access to grant requesters
-not matched by any other access line (see Section 5.3). Note
-that an access level implies all lesser access levels (e.g.,
-write access implies read, search and compare).
+when no {{EX:access}} directives have been specified.  Access
+levels implies all lesser access levels (e.g., read access
+implies search and compare but no write).
+
+Note: It is recommend that the {{EX:access}} directive be used
+to specify access control.  See the {{SECT:Access Control}}
+section of this chapter for information regarding the {{EX:access}}
+directive.
 
 \Default:
 
 E: defaultaccess read
 
+
 H4: include <filename>
 
 This directive specifies that slapd should read additional
 configuration information from the given file before continuing
 with the next line of the current file. The included file should
-follow the normal slapd config file format.
+follow the normal slapd config file format.  The file is commonly
+used to include files containing schema specifications.
 
 Note: You should be careful when using this directive - there is
 no small limit on the number of nested include directives, and no
@@ -201,19 +209,6 @@ from a search operation.
 >	sizelimit 500
 
 
-H4: srvtab <filename>
-
-This directive specifies the srvtab file in which slapd can find the
-Kerberos keys necessary for authenticating clients using
-Kerberos. This directive is only meaningful if you are using
-Kerberos authentication, which must be enabled at compile
-time by including the appropriate definitions in the
-{{EX:Make-common}} file.
-
-\Default:
-
->	srvtab /etc/srvtab
-
 H4: timelimit <integer>
 
 This directive specifies the maximum number of seconds (in real
@@ -289,8 +284,8 @@ updatedn directive in the slave slapd's config file. Since DNs are
 likely to contain embedded spaces, the entire {{EX:"binddn=<DN>"}}
 string should be enclosed in double quotes.
 
-The {{EX:bindmethod}} is either simple or kerberos, depending on
-whether simple password-based authentication or kerberos
+The {{EX:bindmethod}} is either simple or Kerberos, depending on
+whether simple password-based authentication or Kerberos
 authentication is to be used when connecting to the slave
 slapd. Simple authentication requires a valid password be
 given. Kerberos authentication requires a valid srvtab file.
@@ -299,11 +294,12 @@ The {{EX:credentials=}} parameter, which is only required if using
 simple authentication, gives the password for {{EX:binddn}} on the
 slave slapd.
 
-The {{EX:srvtab=}} parameter, which is only required if using
-kerberos, specifies the filename which holds the kerberos key
-for the slave slapd. If omitted, {{F:/etc/srvtab}} is used.
+The {{EX:srvtab=}} parameter is deprecated in favor of SASL
+based authentication services.
+
+See the {{SECT:Replication}} chapter for more information on how to
+use this directive.
 
-See Section 10 for more details on replication.
 
 H4: replogfile <filename>
 
@@ -315,42 +311,51 @@ However, you can also use it to generate a transaction log, if
 slurpd is not running. In this case, you will need to periodically
 truncate the file, since it will grow indefinitely otherwise.
 
-See Section 10 for more details on replication.
+See the {{SECT:Replication}} chapter for more information on how to
+use this directive.
+
 
 H4: rootdn <dn>
 
-This directive specifies the DN of an entry that is not subject to
+This directive specifies the DN that is not subject to
 access control or administrative limit restrictions for
-operations on this database.
+operations on this database.  The DN need not refer to
+an entry in the directory. The DN may refer to a SASL
+identity.
 
-\Example:
+Entry-based Example:
 
 >	rootdn "cn=Manager, dc=example, dc=com"
 
+SASL-based Example:
+
+>	rootdn "uid=root@EXAMPLE.COM"
+
+
 H4: rootkrbname <kerberosname>
 
-This directive specifies a kerberos name for the DN given above
+This directive specifies a Kerberos name for the DN given above
 that will always work, regardless of whether an entry with the
-given DN exists or has a {{EX:krbName}} attribute. This directive is
-useful when creating a database and also when using slurpd
-to provide replication service (see Section 10).
+given DN exists or has a {{EX:krbName}} attribute.
+This directive is deprecated in favor of SASL based authentication.
 
 \Example:
 
 >	rootkrbname admin@EXAMPLE.COM
 
+
 H4: rootpw <password>
 
 This directive specifies a password for the DN given above that
 will always work, regardless of whether an entry with the given
-DN exists or has a password. This directive is useful when
-creating a database and also when using slurpd to provide
-replication service (see Section 10).
+DN exists or has a password.
+This directive is deprecated in favor of SASL based authentication.
 
 \Example:
 
 >	rootpw secret
 
+
 H4: suffix <dn suffix>
 
 This directive specifies the DN suffix of queries that will be
@@ -373,9 +378,20 @@ prefix of another, it must appear after it in the config file.
 H4: updatedn <dn>
 
 This directive is only applicable in a slave slapd. It specifies the
-DN allowed to make changes to the replica (typically, this is
-the DN slurpd binds as when making changes to the replica).
+DN allowed to make changes to the replica.  This may be the
+the DN slurpd binds as when making changes to the replica or
+the DN associated with a SASL identity.
 
+Entry-based Example:
+
+>	updatedn "cn=Update Daemon, dc=example, dc=com"
+
+SASL-based Example:
+
+>	updatedn "uid=slurpd@EXAMPLE.COM"
+
+See the {{SECT:Replication}} chapter for more information on how to
+use this directive.
 
 
 H3: LDBM Backend-Specific Directives
@@ -421,8 +437,9 @@ containing the database and associated indexes live.
 H4: index {<attrlist> | default} [pres,eq,approx,sub,none]
 
 This directive specifies the indexes to maintain for the given
-attribute. If only an <attrlist> is given, all possible indexes are
-maintained.
+attribute. If only an {{EX:<attrlist>}} is given, the default
+indexes are maintained.
+
 
 \Example:
 
@@ -432,9 +449,9 @@ maintained.
 
 The first line sets the default to indices to maintain to present
 and equality.  The second line causes the default (pres,eq) set
-of indices to be maintained for objectClass and uid attribute
+of indices to be maintained for {{EX:objectClass}} and {{EX:uid}} attribute
 types.  The third line causes equality, substring, and approximate
-filters to be maintained for cn and sn attribute types.
+filters to be maintained for {{EX:cn}} and {{EX:sn}} attribute types.
 
 H4: mode <integer>
 
@@ -954,7 +971,7 @@ through 13 specify the hostname and port for a replicated
 host, the DN to bind as when performing updates, the bind
 method (simple) and the credentials (password) for the
 binddn. Lines 14 through 17 specify a second replication site,
-using kerberos instead of simple authentication. See Section
+using Kerberos instead of simple authentication. See Section
 10 on slurpd for more information on these directives.
 
 Lines 19 through 21 indicate the indexes to maintain for