Misc cleanup

doc/guide/admin/install.sdf

@@ -19,14 +19,14 @@ The {{ORG[expand]OLP}} also maintains an extensive site
 makes available a number of resources which you may utilize to
 properly install OpenLDAP Software.  This includes:
 
-!block table; align=center
+!block table; align=Center; coltags="N,URL"
 Resource			URL
-Documentation Catalog		{{URL:http://www.OpenLDAP.org/doc/}}
+Documentation Catalog		http://www.OpenLDAP.org/doc/
-Frequently Asked Questions	{{URL:http://www.OpenLDAP.org/faq/}}
+Frequently Asked Questions	http://www.OpenLDAP.org/faq/
-Issue Tracking System		{{URL:http://www.OpenLDAP.org/its/}}
+Issue Tracking System		http://www.OpenLDAP.org/its/
-Mailing Lists			{{URL:http://www.OpenLDAP.org/lists/}}
+Mailing Lists			http://www.OpenLDAP.org/lists/
-Software Pages 			{{URL:http://www.OpenLDAP.org/software/}}
+Software Pages 			http://www.OpenLDAP.org/software/
-Support Page 			{{URL:http://www.OpenLDAP.org/support/}}
+Support Page 			http://www.OpenLDAP.org/support/
 !endblock
  
 H2: Prerequisite software
@@ -39,7 +39,7 @@ you might have to install.  Note that some of these third party
 packages may depend on additional software packages.  Install each
 package per installation instructions provided with it.
 
-H3: TLS Software
+H3: {{TERM[expand]TLS}}
 
 OpenLDAP clients and servers require installation of {{PRD:OpenSSL}}
 {{TERM:TLS}} libraries to provide {{TERM[expand]TLS}} services.  Though
@@ -50,20 +50,25 @@ requires separate installation.
 OpenSSL is available from {{URL: http://www.openssl.org/}}.
 
 OpenLDAP will not be fully LDAPv3 compliant unless OpenLDAP's
-configure detects a usable OpenSSL installation.
+{{EX:configure}} detects a usable OpenSSL installation.
 
-H3: Kerberos Software
+H3: Kerberos Authentication Services
 
 OpenLDAP clients and servers support Kerberos based authentication
-services.  In particular, OpenLDAP supports SASL/GSSAPI based
+services.
-authentication using either Heimdal or MIT Kerberos V packages.
+In particular, OpenLDAP supports {{TERM:SASL}}/{{TERM:GSSAPI}} based
+authentication using either {{PRD:Heimdal}} or {{PRD:MIT Kerberos}}
+V packages.
 If you desire to use Kerberos based authentication, you should
 install either Heimdal or MIT Kerberos V.
 
-Heimdal Kerberos is available from {{URL:http://kth.se/}}.
+Heimdal Kerberos is available from {{URL:http://www.pdc.kth.se/heimdal/}}.
-MIT Kerberos is available from {{URL:http://mit.edu/}}.
+MIT Kerberos is available from {{URL:http://web.mit.edu/kerberos/www/}}.
 
-H3: SASL Software
+Use of strong authentication services, such as those provided by
+Kerberos, is highly recommended.
+
+H3: {{TERM[expand]SASL}}
 
 OpenLDAP clients and servers require installation of {{PRD:Cyrus}}
 SASL libraries to provide {{TERM[expand]SASL}} services.  Though
@@ -72,7 +77,8 @@ base system or as an optional software component, Cyrus SASL
 often requires separate installation.
 
 Cyrus SASL is available from {{URL:http://asg.cmu.edu/cyrus/sasl/}}.
-Cyrus SASL will make use of Kerberos libraries if preinstalled.
+Cyrus SASL will make use of OpenSSL and Kerberos/GSSAPI libraries
+if preinstalled.
 
 OpenLDAP will not be fully LDAPv3 compliant unless OpenLDAP's
 configure detects a usable Cyrus SASL installation.
@@ -93,12 +99,29 @@ need may need to obtain the software and install it yourself.
 {{PRD:BerkeleyDB}} is available from {{ORG[expand]Sleepy}}'s
 download page {{URL: http://www.sleepycat.com/download.html}}.
 There are several versions available.  At the time of this writing,
-version 3.1, the latest release, is recommended. 
+the latest release, version 3.1, is recommended. 
 
 {{PRD:GDBM}} is available from {{ORG:FSF}}'s download site
 {{URL: ftp://ftp.gnu.org/pub/gnu/gdbm/}}.
 At the time of this writing, version 1.8 is the latest release.
 
+H3: Threads
+
+OpenLDAP is designed to take advantage of threads.  OpenLDAP
+supports POSIX {{pthreads}}, Mach {{CThreads}}, and a number of
+other varieties.  {{EX:configure}} will complain if it cannot
+find a suitable thread subsystem.   If this occurs, please
+consult the {{F:Software|Installation|Platform Hints}} section
+of the OpenLDAP FAQ {{URL: http://www.openldap.org/faq/}}.
+
+H3: TCP Wrappers
+
+{{slapd}}(8) supports TCP wrappers (IP level access control filters)
+if preinstalled.  Use of TCP wrappers or other IP level access
+filters (such as those provided by IP firewalls) is recommended
+for servers containing non-public information.
+
+
 H2: Configuring OpenLDAP
 
 If you haven't already done so, extra the distribution for the
@@ -110,6 +133,10 @@ distribution:
 
 Replacing {{EX:VERSION}} with the appropriate version string.
 
+Note: If you intend to build OpenLDAP for multiple platforms from a
+single source tree you should consult the {{F: INSTALL}} file in the
+top level distribution directory before running {{EX:configure}}.
+
 Now you should probably run the {{EX:configure}} script with the
 {{EX:--help}} option.
 This will give you a list of options that you can change when building
@@ -121,13 +148,13 @@ of configure options, and their usage.
 The {{EX:configure}} script will also look at certain environment variables
 for certain settings.  These environment variables are:
 
-!block table; align=center
+!block table; align=Center; coltags="EX,N"; title="Table 4.1: Environment Variables"
 Variable	Description
-{{EX:CC}}      	Specify alternative C Compiler
+CC      	Specify alternative C Compiler
-{{EX:CFLAGS}}  	Specify additional compiler flags
+CFLAGS  	Specify additional compiler flags
-{{EX:CPPFLAGS}}	Specify C Preprocessor flags
+CPPFLAGS	Specify C Preprocessor flags
-{{EX:LDFLAGS}} 	Specify linker flags
+LDFLAGS 	Specify linker flags
-{{EX:LIBS}}    	Specify additional libraries
+LIBS    	Specify additional libraries
 !endblock
 
 Now run the configure script with any desired configure options or
@@ -153,7 +180,7 @@ entered on a single line (it has been split onto seperate lines for clarity.)
 ..{{EX: LDFLAGS="-L/usr/local/BerkeleyDB.3.1/lib" \ }}
 ..{{EX: ./configure --enable-dnssrv}}
 
-Note: that some shells, such as those derived from the Bourne {{sh}}(1),
+Note: Some shells, such as those derived from the Bourne {{sh}}(1),
 do not require use of the {{env}}(1) command.  In some cases, environmental
 variables have to be specified using alternative syntaxes.
 
@@ -172,20 +199,16 @@ should be:
 If the last line of output does not match, {{EX:configure}} has failed.
 You should not proceed until {{EX:configure}} completes sucessfuly.
 
-Now run make depend.
+To build dependencies, run:
 .{{EX: make depend}}
 
-Now run make, this step will actually compile OpenLDAP.
+Now build the software, this step will actually compile OpenLDAP.
 .{{EX: make}}
 
 You should examine the output of this command carefully to make sure
 everything is built correctly. Note that this command builds the LDAP
 libraries and associated clients as well as {{slapd}}(8) and {{slurpd}}(8).
 
-Note that the OpenLDAP distribution can support building for multiple
-platforms from a single source tree. If you want to do this, consult the
-{{F: INSTALL}} file in the top level distribution directory.
-
 H2: Testing the Software
 
 Once the software has been properly configured and successfully

doc/guide/admin/runningslapd.sdf

@@ -3,7 +3,7 @@
 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
 H1: Running slapd
 
-{{Slapd}}(8) is designed to be run as a stand-alone server.  This allows
+{{slapd}}(8) is designed to be run as a stand-alone server.  This allows
 the server to take advantage of caching, manage concurrency issues
 with underlying databases, and conserve system resources.  Running
 from {{inetd}}(8) is {{NOT}} an option.
@@ -11,7 +11,14 @@ from {{inetd}}(8) is {{NOT}} an option.
 
 H2: Command-Line Options
 
-{{I:Slapd}} supports the following command-line options.
+{{slapd}}(8) supports a number of command-line options as detailed
+in manual page.  This section details a few commonly used options.
+
+E: -f <filename>
+
+This option specifies an alternate configuration file for slapd.
+The default is normally {{F:/usr/local/etc/openldap/slapd.conf}}.
+
 
 E: -d <level> | ?
 
@@ -20,19 +27,23 @@ This option sets the slapd debug level to <level>. When level is a
 exits, regardless of any other options you give it. Current
 debugging levels are
 
-E:     1 trace function calls
+!block table; colaligns="RL"; align=Center; title="Table 6.1: Debugging Levels"
-E:     2 debug packet handling
+Level	Description
-E:     4 heavy trace debugging
+-1	enable all debugging
-E:     8 connection management
+0	no debugging
-E:    16 print out packets sent and received
+1	trace function calls
-E:    32 search filter processing
+2	debug packet handling
-E:    64 configuration file processing
+4	heavy trace debugging
-E:   128 access control list processing
+8	connection management
-E:   256 stats log connections/operations/results
+16	print out packets sent and received
-E:   512 stats log entries sent
+32	search filter processing
-E:  1024 print communication with shell backends
+64	configuration file processing
-E:  2048 print entry parsing debugging
+128	access control list processing
-E: 65535 enable all debugging
+256	stats log connections/operations/results
+512	stats log entries sent
+1024	print communication with shell backends
+2048	print entry parsing debugging
+!endblock
 
 You may enable multiple levels by specifying the debug option
 once for each desired level.  Or, since debugging levels are
@@ -40,54 +51,33 @@ additive, you can do the math yourself. That is, if you want
 to trace function calls and watch the config file being
 processed, you could set level to the sum of those two levels
 (in this case, {{EX: -d 65}}).  Or, you can let slapd do the
-math, (e.g. {{EX: -d 1 -d 64}}).  Consult {{EX: <ldap.h>}} for
+math, (e.g. {{EX: -d 1 -d 64}}).  Consult {{F: <ldap.h>}} for
 more details.
 
 Note: slapd must have been compiled with {{EX:-DLDAP_DEBUG}}
 defined for any debugging information beyond the two stats levels
 to be available.
 
-E: -f <filename>
-
-This option specifies an alternate configuration file for slapd.
-
-E: -p <port>
-
-This option specifies an alternate TCP port on which slapd should
-listen for connections. The default port is 389.
-
 
 H2: Starting slapd
 
 In general, slapd is run like this:
 
-E: 	$(ETCDIR)/slapd [<option>]*
+E: 	/usr/local/etc/libexec/slapd [<option>]*
 
-where ETCDIR has the value you gave in the Make-common file
+where {{F:/usr/local/etc/libexec}} is determined by {{EX:configure}}.
-during the pre-build configuration, and <option> is one of the
+and <option> is one of the options described above (or in {{slapd}}(8)).
-options described below. Unless you have specified a debugging
+Unless you have specified a debugging level (including level {{EX:0}}),
-level, slapd will automatically fork and detach itself from its
+slapd will automatically fork and detach itself from its controlling
-controlling terminal and run in the background. Any of the options
+terminal and run in the background.
-given above can be given to slapd to point it at a different
-configuration file, listen on another port, etc.
 
 H2: Stopping slapd
 
 To kill off slapd safely, you should give a command like this
 
-E: 	kill -TERM `cat $(ETCDIR)/slapd.pid`
+E: 	kill -TERM `cat /usr/local/var/slapd.pid`
 
-Killing slapd by a more drastic method may cause its LDBM
+where {{F:/usr/local/var}} is determined by {{EX:configure}}.
-databases to be corrupted, as it may need to flush various buffers
-before it exits. Note that slapd writes its pid to a file called 
-{{EX: slapd.pid}} in the {{EX: ETCDIR}} you configured in 
-{{EX: Make-common}}. You can change
-the location of this pid file by changing the {{EX: SLAPD_PIDFILE}}
-variable in {{EX: include/ldapconfig.h.edit}}.
-
-{{I: Slapd}} will also write its arguments to a file called 
-{{EX: slapd.args}} in the {{EX: ETCDIR}} you configured 
-in {{EX: Make-common}}. You can change the
-location of the args file by changing the {{EX: SLAPD_ARGSFILE}}
-variable in {{EX: include/ldapconfig.h.edit}}.
 
+Killing slapd by a more drastic method may cause its information
+loss or database corruption.

doc/guide/preamble.sdf

@@ -46,6 +46,7 @@ OpenSSL  OpenSSL				http://www.openssl.org/
 Cyrus	 Cyrus					http://asg.cmu.edu/cyrus/
 Sleepy	 Sleepycat Software			http://www.sleepycat.com/
 FSF	 Free Software Foundation		http://www.fsf.org/
+GNU	 Gnu Not Unix 				http://www.gnu.org/
 !endblock
 
 !block products; data
@@ -55,6 +56,8 @@ CVS		http://www.cyclic.com/
 Cyrus		http://asg.cmu.edu/cyrus/sasl/
 GNU		http://www.gnu.org/software/
 GDBM		http://www.gnu.org/software/gdbm/
+Heimdal		http://www.pdc.kth.se/heimdal/
+MIT Kerberos	http://web.mit.edu/kerberos/www/
 OpenLDAP	http://www.openldap.org/software/
 OpenSSL		http://www.openssl.org/
 Perl		http://www.perl.com/
@@ -78,6 +81,7 @@ DSA	Directory System Agent
 DUA	Directory User Agent
 FAQ	Frequently Asked Questions
 FYI	For Your Information
+GSSAPI	Generic Security Services Application Programming Interface
 I-D	Internet Draft
 IP	Internet Protocol
 IPSEC	Internet Protocol Security