Misc cleanup

doc/guide/admin/replication.sdf

@@ -57,16 +57,20 @@ slapd via LDAP.
 returns a success code to the slurpd process. 
 
 
+Note: {{ldapmodify}}(1) and other tools distributed as part of
+OpenLDAP Software do not support automatic referral chasing.
+
+
+
 H2: Replication Logs
 
-When slapd is configured to generate a replication logfile,
-it writes out a file containing {{TERM:LDIF}} change records.
-The replication log gives the replication site(s), a
-timestamp, the DN of the entry being modified, and a series
-of lines which specify the changes to make. In the
-example below, Barbara ({{EX:uid=bjensen}}) has replaced the {{EX:description}}
-value.  The change is to be propagated
-to the slapd instance running on {{EX:slave.example.net}}
+When slapd is configured to generate a replication logfile, it
+writes out a file containing {{TERM:LDIF}} change records.  The
+replication log gives the replication site(s), a timestamp, the DN
+of the entry being modified, and a series of lines which specify
+the changes to make. In the example below, Barbara ({{EX:uid=bjensen}})
+has replaced the {{EX:description}} value.  The change is to be
+propagated to the slapd instance running on {{EX:slave.example.net}}
 Changes to various operational attributes, such as {{EX:modifiersName}}
 and {{EX:modifyTimestamp}}, are included in the change record and
 will be propagated to the slave slapd.
@@ -97,10 +101,9 @@ This section details commonly used {{slurpd}}(8) command-line options.
 >	-d <level> | ?
 
 This option sets the slurpd debug level to {{EX: <level>}}. When
-level is a `?' character, the various debugging levels are
-printed and slurpd exits, regardless of any other options
-you give it. Current debugging levels (a subset of slapd's
-debugging levels) are
+level is a `?' character, the various debugging levels are printed
+and slurpd exits, regardless of any other options you give it.
+Current debugging levels (a subset of slapd's debugging levels) are
 
 !block table; colaligns="RL"; align=Center; \
 	title="Table 13.1: Debugging Levels"
@@ -110,39 +113,36 @@ Level	Description
 65535	enable all debugging
 !endblock
 
-Debugging levels are additive. That is, if you want heavy
-trace debugging and want to watch the config file being
-processed, you would set level to the sum of those two
-levels (in this case, 68).
+Debugging levels are additive. That is, if you want heavy trace
+debugging and want to watch the config file being processed, you
+would set level to the sum of those two levels (in this case, 68).
 
 >	-f <filename>
 
-This option specifies an alternate slapd configuration file.
-Slurpd does not have its own configuration file. Instead, all
-configuration information is read from the slapd
-configuration file.
+This option specifies an alternate slapd configuration file.  Slurpd
+does not have its own configuration file. Instead, all configuration
+information is read from the slapd configuration file.
 
 >	-r <filename>
 
 This option specifies an alternate slapd replication log file.
-Under normal circumstances, slurpd reads the name of
-the slapd replication log file from the slapd configuration
-file. However, you can override this with the -r flag, to
-cause slurpd to process a different replication log file. See
-the {{SECT:Advanced slurpd Operation}} section for a discussion
-of how you might use this option.
+Under normal circumstances, slurpd reads the name of the slapd
+replication log file from the slapd configuration file. However,
+you can override this with the -r flag, to cause slurpd to process
+a different replication log file. See the {{SECT:Advanced slurpd
+Operation}} section for a discussion of how you might use this
+option.
 
 >	-o
 
-Operate in "one-shot" mode. Under normal
-circumstances, when slurpd finishes processing a
-replication log, it remains active and periodically checks to
-see if new entries have been added to the replication log.
-In one-shot mode, by comparison, slurpd processes a
-replication log and exits immediately. If the -o option is
-given, the replication log file must be explicitly specified
-with the -r option.  See the {{SECT:One-shot mode and reject files}}
-section for  a discussion of this mode.
+Operate in "one-shot" mode. Under normal circumstances, when slurpd
+finishes processing a replication log, it remains active and
+periodically checks to see if new entries have been added to the
+replication log.  In one-shot mode, by comparison, slurpd processes
+a replication log and exits immediately. If the -o option is given,
+the replication log file must be explicitly specified with the -r
+option.  See the {{SECT:One-shot mode and reject files}} section
+for  a discussion of this mode.
 
 >	-t <directory>
 
@@ -152,72 +152,67 @@ replication logs. The default location is {{F:/usr/tmp}}.
 
 H2: Configuring slurpd and a slave slapd instance
 
-To bring up a replica slapd instance, you must configure
-the master and slave slapd instances for replication, then
-shut down the master slapd so you can copy the
-database. Finally, you bring up the master slapd instance,
-the slave slapd instance, and the slurpd instance. These
-steps are detailed in the following sections. You can set
-up as many slave slapd instances as you wish.
+To bring up a replica slapd instance, you must configure the master
+and slave slapd instances for replication, then shut down the master
+slapd so you can copy the database. Finally, you bring up the master
+slapd instance, the slave slapd instance, and the slurpd instance.
+These steps are detailed in the following sections. You can set up
+as many slave slapd instances as you wish.
 
 
 H3: Set up the master {{slapd}}
 
-The following section assumes you have a properly
-working {{slapd}}(8) instance. To configure your working
-{{slapd}}(8) server as a replication master, you need
-to make the following changes to your {{slapd.conf}}(5).
+The following section assumes you have a properly working {{slapd}}(8)
+instance. To configure your working {{slapd}}(8) server as a
+replication master, you need to make the following changes to your
+{{slapd.conf}}(5).
 
 ^ Add a {{EX:replica}} directive for each replica. The {{EX:binddn=}}
-parameter should match the {{EX:updatedn}} option in the
-corresponding slave slapd configuration file, and should
-name an entry with write permission to the slave database
-(e.g., an entry listed as {{EX:rootdn}}, or allowed access via
-{{EX:access}} directives in the slave slapd configuration file).
+parameter should match the {{EX:updatedn}} option in the corresponding
+slave slapd configuration file, and should name an entry with write
+permission to the slave database (e.g., an entry listed as
+{{EX:rootdn}}, or allowed access via {{EX:access}} directives in
+the slave slapd configuration file).
 
 + Add a {{EX:replogfile}} directive, which tells slapd where to log
 changes. This file will be read by slurpd.
 
 
-
 H3: Set up the slave {{slapd}}
 
-Install the slapd software on the host which is to be the
-slave slapd server. The configuration of the slave server
-should be identical to that of the master, with the following
-exceptions:
+Install the slapd software on the host which is to be the slave
+slapd server. The configuration of the slave server should be
+identical to that of the master, with the following exceptions:
 
-^ Do not include a {{EX:replica}} directive. While it is
-possible to create "chains" of replicas, in most cases this is
-inappropriate.
+^ Do not include a {{EX:replica}} directive. While it is possible
+to create "chains" of replicas, in most cases this is inappropriate.
 
 + Do not include a {{EX:replogfile}} directive.
 
-+ Do include an {{EX:updatedn}} line. The DN given should
-match the DN given in the {{EX:binddn=}} parameter of the
-corresponding {{EX:replica=}} directive in the master slapd
-config file.
++ Do include an {{EX:updatedn}} line. The DN given should match the
+DN given in the {{EX:binddn=}} parameter of the corresponding
+{{EX:replica=}} directive in the master slapd config file.
 
 + Make sure the DN given in the {{EX:updatedn}} directive has
 permission to write the database (e.g., it is listed as {{EX:rootdn}}
 or is allowed {{EX:access}} by one or more access directives).
 
-+ Use the {{EX:updateref}} directive to define the URL the
-slave should return if an update request is received.
++ Use the {{EX:updateref}} directive to define the URL the slave
+should return if an update request is received.
 
 
 H3: Shut down the master {{slapd}}
 
-In order to ensure that the slave starts with an exact copy
-of the master's data, you must shut down the master
-slapd. Do this by sending the master slapd process an
-interrupt signal with {{EX:kill -INT <pid>}}, where
-{{EX:<pid>}} is the process-id of the master slapd process.
+In order to ensure that the slave starts with an exact copy of the
+master's data, you must shut down the master slapd. Do this by
+sending the master slapd process an interrupt signal with {{EX:kill
+-INT <pid>}}, where {{EX:<pid>}} is the process-id of the master
+slapd process.
 
-If you like, you may restart the master slapd in read-only
-mode while you are replicating the database. During this
-time, the master slapd will return an "unwilling to perform"
-error to clients that attempt to modify data.
+If you like, you may restart the master slapd in read-only mode
+while you are replicating the database. During this time, the master
+slapd will return an "unwilling to perform" error to clients that
+attempt to modify data.
 
 
 H3: Copy the master slapd's database to the slave
@@ -228,40 +223,38 @@ in the database {{EX:directory}} specified in {{slapd.conf}}(5).
 In general, you should copy each file found in the database {{EX:
 directory}} unless you know it is not used by {{slapd}}(8).
 
-Note: This copy process assumes homogeneous servers with
-identically configured OpenLDAP installations. Alternatively,
-you may use {{slapcat}} to output the master's database in LDIF
-format and use the LDIF with {{slapadd}} to populate the
-slave. Using LDIF avoids any potential incompatibilities due
-to differing server architectures or software configurations.
-See the {{SECT:Database Creation and Maintenance Tools}}
-chapter for details on these tools.
+Note: This copy process assumes homogeneous servers with identically
+configured OpenLDAP installations. Alternatively, you may use
+{{slapcat}} to output the master's database in LDIF format and use
+the LDIF with {{slapadd}} to populate the slave. Using LDIF avoids
+any potential incompatibilities due to differing server architectures
+or software configurations.  See the {{SECT:Database Creation and
+Maintenance Tools}} chapter for details on these tools.
 
 
 H3: Configure the master slapd for replication
 
-To configure slapd to generate a replication logfile, you
-add a "{{EX: replica}}" configuration option to the master slapd's
-config file. For example, if we wish to propagate changes
-to the slapd instance running on host
-{{EX:slave.example.com}}:
+To configure slapd to generate a replication logfile, you add a
+"{{EX: replica}}" configuration option to the master slapd's config
+file. For example, if we wish to propagate changes to the slapd
+instance running on host {{EX:slave.example.com}}:
 
 >	replica host=slave.example.com:389
 >		binddn="cn=Replicator,dc=example,dc=com"
 >		bindmethod=simple credentials=secret
 
-In this example, changes will be sent to port 389 (the
-standard LDAP port) on host slave.example.com. The slurpd
-process will bind to the slave slapd as 
-"{{EX:cn=Replicator,dc=example,dc=com}}" using simple authentication
-with password "{{EX:secret}}".  Note that the DN given by the {{EX:binddn=}}
-directive must exist in the slave slapd's database (or be
-the rootdn specified in the slapd config file) in order for the
-bind operation to succeed.  The DN should also be listed as
-the {{EX:updatedn}} for the database in the slave's slapd.conf(5).
+In this example, changes will be sent to port 389 (the standard
+LDAP port) on host slave.example.com. The slurpd process will bind
+to the slave slapd as "{{EX:cn=Replicator,dc=example,dc=com}}" using
+simple authentication with password "{{EX:secret}}".  Note that the
+DN given by the {{EX:binddn=}} directive must exist in the slave
+slapd's database (or be the rootdn specified in the slapd config
+file) in order for the bind operation to succeed.  The DN should
+also be listed as the {{EX:updatedn}} for the database in the slave's
+slapd.conf(5).
 
-Note: The use of strong authentication and transport security
-is highly recommended.
+Note: The use of strong authentication and transport security is
+highly recommended.
 
 
 H3: Restart the master slapd and start the slave slapd
@@ -287,14 +280,13 @@ H2: Advanced slurpd Operation
 
 H3: Replication errors
 
-When slurpd propagates a change to a slave slapd and
-receives an error return code, it writes the reason for the
-error and the replication record to a reject file. The reject
-file is located in the same directory as the per-replica
-replication logfile, and has the same name, but with the
-string "{{F:.rej}}" appended. For example, for a replica running
-on host {{EX:slave.example.com}}, port 389, the reject file, if it
-exists, will be named
+When slurpd propagates a change to a slave slapd and receives an
+error return code, it writes the reason for the error and the
+replication record to a reject file. The reject file is located in
+the same directory as the per-replica replication logfile, and has
+the same name, but with the string "{{F:.rej}}" appended. For
+example, for a replica running on host {{EX:slave.example.com}},
+port 389, the reject file, if it exists, will be named
 
 >	/usr/local/var/openldap/replog.slave.example.com:389.rej
 
@@ -315,29 +307,26 @@ A sample rejection log entry follows:
 >	modifyTimestamp: 20000805073308Z
 >	-
 
-Note that this is precisely the same format as the original
-replication log entry, but with an {{EX:ERROR}} line prepended to
-the entry.
+Note that this is precisely the same format as the original replication
+log entry, but with an {{EX:ERROR}} line prepended to the entry.
 
 
 
 H3: One-shot mode and reject files
 
-It is possible to use slurpd to process a rejection log with
-its "one-shot mode." In normal operation, slurpd watches
-for more replication records to be appended to the
-replication log file. In one-shot mode, by contrast, slurpd
-processes a single log file and exits. Slurpd ignores
-{{EX:ERROR}} lines at the beginning of replication log entries, so
-it's not necessary to edit them out before feeding it the
-rejection log.
-
-To use one-shot mode, specify the name of the rejection
-log on the command line as the argument to the -r flag,
-and specify one-shot mode with the -o flag. For example,
-to process the rejection log file
-{{F:/usr/local/var/openldap/replog.slave.example.com:389}}
-and exit, use the command
+It is possible to use slurpd to process a rejection log with its
+"one-shot mode." In normal operation, slurpd watches for more
+replication records to be appended to the replication log file. In
+one-shot mode, by contrast, slurpd processes a single log file and
+exits. Slurpd ignores {{EX:ERROR}} lines at the beginning of
+replication log entries, so it's not necessary to edit them out
+before feeding it the rejection log.
+
+To use one-shot mode, specify the name of the rejection log on the
+command line as the argument to the -r flag, and specify one-shot
+mode with the -o flag. For example, to process the rejection log
+file {{F:/usr/local/var/openldap/replog.slave.example.com:389}} and
+exit, use the command
 
 >	slurpd -r /usr/tmp/replog.slave.example.com:389 -o
 
@@ -345,41 +334,38 @@ and exit, use the command
 
 H2: Replication to an X.500 DSA
 
-In mixed environments where both {{TERM:X.500}} DSAs and slapd
-are used, it may be desirable to replicate changes from a
-slapd directory server to an X.500 {{TERM:DSA}}. This section
-discusses issues involved with this method of replication,
-and describes the currently-available facilities.
+In mixed environments where both {{TERM:X.500}} DSAs and slapd are
+used, it may be desirable to replicate changes from a slapd directory
+server to an X.500 {{TERM:DSA}}. This section discusses issues
+involved with this method of replication, and describes the
+currently-available facilities.
 
-To propagate changes from a slapd directory server to an
-X.500 DSA, slurpd runs on the master slapd host, and
-sends changes to an ldapd which acts as a gateway to
-the X.500 DSA:
+To propagate changes from a slapd directory server to an X.500 DSA,
+slurpd runs on the master slapd host, and sends changes to an ldapd
+which acts as a gateway to the X.500 DSA:
 
 !import "replication.gif"; align="center"; \
 	title="Replication from slapd to an X.500 DSA"
 FT: Figure 10.1: Replication from slapd to an X.500 DSA
 
-Note that the X.500 DSA must be a read-only copy. Since
-the replication is one-way, updates from {{TERM:DAP}} clients
-connecting to the X.500 DSA simply cannot be handled.
-
-A problem arises where attribute names differ between the
-slapd directory server and the X.500 DSA. At present,
-slapd and slurpd do not support selective replication of
-attributes, nor do they support translation of attribute
-names and values. For example, slurpd will attempt to
-update the {{EX:modifiersName}} and {{EX:modifyTimeStamp}}
-attributes on the slave it connects to. However, the X.500
-DSA may expect these attributes to be named
+Note that the X.500 DSA must be a read-only copy. Since the replication
+is one-way, updates from {{TERM:DAP}} clients connecting to the
+X.500 DSA simply cannot be handled.
+
+A problem arises where attribute names differ between the slapd
+directory server and the X.500 DSA. At present, slapd and slurpd
+do not support selective replication of attributes, nor do they
+support translation of attribute names and values. For example,
+slurpd will attempt to update the {{EX:modifiersName}} and
+{{EX:modifyTimeStamp}} attributes on the slave it connects to.
+However, the X.500 DSA may expect these attributes to be named
 {{EX:lastModifiedBy}} and {{EX:lastModifiedTime}}.
 
-A solution to this attribute naming problem is to have the
-LDAP/DAP gateway to map {{EX:modifiersName}} to the Object
-Identifier ({{TERM:OID}}) for the {{EX:lastModifiedBy}}
-attribute and {{EX:modifyTimeStamp}} to the OID for the
-{{EX:lastModifiedTime}} attribute. Since attribute names
-are carried as OIDs over DAP, this should perform the
-appropriate translation of attribute names.
+A solution to this attribute naming problem is to have the LDAP/DAP
+gateway to map {{EX:modifiersName}} to the Object Identifier
+({{TERM:OID}}) for the {{EX:lastModifiedBy}} attribute and
+{{EX:modifyTimeStamp}} to the OID for the {{EX:lastModifiedTime}}
+attribute. Since attribute names are carried as OIDs over DAP, this
+should perform the appropriate translation of attribute names.
 
 !endif