upstream/openldap
1
0
Fork 0
mirror of https://git.openldap.org/openldap/openldap.git synced 2025-12-22 23:59:34 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

Misc cleanup

Browse source
This commit is contained in:
Kurt Zeilenga 2002-10-27 21:45:17 +00:00
parent 293158f432
commit 492c5b83f8
1 changed files with 136 additions and 150 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

286
doc/guide/admin/replication.sdf
View file

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