Administrator’s Guide
Red Hat Directory Server                                                            

Previous
Contents
Index
Next

Chapter 8

Managing Replication


Replication is the mechanism by which directory data is automatically copied from one Red Hat Directory Server (Directory Server) to another; it is an important mechanism for extending your directory service beyond a single server configuration. This chapter describes the tasks to be performed on the supplier servers and the consumer servers to set up single-master replication, multi-master replication, and cascading replication. This chapter includes the following topics:

For conceptual information on how you can use replication in your directory deployment, see the Red Hat Directory Server Deployment Guide.

Replication Overview

Replication is the mechanism by which directory data is automatically copied from one Directory Server to another. Updates of any kind - entry additions, modifications, or even deletions - are automatically mirrored to other Directory Servers using replication. This section contains information on the following replication concepts:

Read-Write Replica/Read-Only Replica

A database that participates in replication is defined as a replica. There are two kinds of replicas: read-write or read-only. A read-write replica contains master copies of directory information and can be updated. A read-only replica refers all update operations to read-write replicas. A server can hold any number of read-only or read-write replicas.

Supplier/Consumer

A server that holds a replica that is copied to a replica on a different server is called a supplier for that replica. A server that holds a replica that is copied from a different server is called a consumer for that replica. Generally, the replica on the supplier server is a read-write replica and the one on the consumer server is a read-only replica. There are exceptions to this statement:

In Directory Server, replication is always initiated by the supplier server, never by the consumer. This operation is called supplier-initiated replication. It allows you to configure a supplier server to push data to one or more consumer servers.

Earlier versions of the Directory Server allowed consumer-initiated replication, where you could configure consumer servers to pull data from a supplier server.

Changelog

Every supplier server maintains a changelog. A changelog is a record that describes the modifications that have occurred on a replica. The supplier server then replays these modifications to the replicas stored on consumer servers or to other suppliers, in the case of multi-master replication.

When an entry is modified, a change record describing the LDAP operation that was performed is recorded in the changelog.

In Directory Server, the format of the changelog has changed. It is now only intended for internal use by the server. If you have applications that need to read the changelog, you need to use the Retro Changelog Plug-in for backward compatibility. For more information, refer to "Using the Retro Changelog Plug-in," on page 363.

Unit of Replication

The smallest unit of replication is a database. This means that you can replicate an entire database but not a subtree within a database. Therefore, when you create your directory tree, you must take your replication plans into consideration. For more information on how to set up your directory tree, refer to the Red Hat Directory Server Deployment Guide.

The replication mechanism also requires that one database correspond to one suffix. This means that you cannot replicate a suffix (or namespace) that is distributed over two or more databases using custom distribution logic. For more information on this topic, refer to "Creating and Maintaining Databases," on page 92.

Replication Identity

When replication occurs between two servers, the replication process uses a special entry, often referred to as the Replication Manager entry, to identify replication protocol exchanges. The Replication Manager entry, or any entry you create to fulfill that role, must meet the following criteria:

Note

In the Directory Server Console, this Replication Manager entry is referred to as the supplier bind DN, which may be misleading as the entry does not actually exist on the supplier server. It is called the supplier bind DN because it is the entry which must be present on the consumer for the supplier to be able to bind to the consumer.


For more information on creating the Replication Manager entry, refer to "Creating the Supplier Bind DN Entry," on page 318.

Replication Agreement

Directory Servers use replication agreements to define their replication configuration. A replication agreement describes replication between one supplier and one consumer only. The agreement is configured on the supplier server. It specifies:

Compatibility with Earlier Versions of Directory Server

The replication mechanism in current versions of Directory Server is different from the mechanism used in earlier versions (4.x) of Directory Server. Compatibility is provided through the following:

Replication Scenarios

This section describes the most commonly used replication scenarios:

You can combine these basic scenarios to build the replication environment that best suits your needs.

Note

Whatever replication scenario you choose to implement, remember to consider schema replication. For details, see Red Hat Directory Server Deployment Guide.

To avoid conflict resolution loops, the Referential Integrity Plug-in should only be enabled on one supplier replica in a multi-master replication environment. The plug-in is off by default.


Single-Master Replication

In the simplest replication scenario, the master copy of directory data is held in a single read-write replica on one server called the supplier server. The supplier server also maintains changelog for this replica. On another server, called the consumer server, you have as many read-only replicas as you like. Such scenarios are called single-master configurations. <Z_Online>Figure 8-1 shows an example of single-master replication.

Figure 8-1 Single-Master Replication

In this particular configuration, the ou=people,dc=example,dc=com suffix receives a large number of search requests. Therefore, to distribute the load, this tree, which is mastered on server A, is replicated to two read-only replicas located on server B and server C.

For information on setting up a single-master replication environment, refer to "Configuring Single-Master Replication," on page 326.

Multi-Master Replication

Directory Server also supports complex replication scenarios in which the same suffix (database) can be mastered on many servers. This suffix is held in a read-write replica on each server. This means that each server maintains a changelog for the read-write replica.

This type of configuration can work with any number of consumer servers. Each consumer server holds a read-only replica. The consumers can receive updates from all the suppliers. The consumers also have referrals defined for all the suppliers to forward any update requests that the consumers receive. Such scenarios are called multi-master configurations.

<Z_Online>Figure 8-2 shows an example of multi-master replication scenario with two supplier servers and two consumer servers.

Figure 8-2 Multi-Master Replication (Two Suppliers)

<Z_Online>Figure 8-3 shows a sample of multi-master replication scenario with four supplier servers and eight consumer servers. In this sample setup, each supplier server is configured with ten replication agreements to feed data to two other supplier servers and all eight consumer servers.

Figure 8-3 Multi-Master Replication (Four Suppliers)



Multi-master configurations have the following advantages:

Note

Replication, especially multi-master replication, works better over high speed links than over slow links, such as a WAN, in geographically distributed environments.


For information on setting up multi-master replication with two supplier servers and two consumer servers, refer to "Configuring Multi-Master Replication," on page 330.

Cascading Replication

In a cascading replication scenario, one server, often called a hub supplier, acts both as a consumer and a supplier for a particular replica. It holds a read-only replica and maintains a changelog. It receives updates from the supplier server that holds the master copy of the data and, in turn, supplies those updates to the consumer. Cascading replication is very useful when you need to balance heavy traffic loads or have supplier servers based locally in geographically distributed environments.

<Z_Online>Figure 8-4 shows an example of cascading replication. This example shows a simple cascading replication scenario. You can create more complex scenarios with several hub suppliers.

Figure 8-4 Cascading Replication

For information on setting up cascading replication, refer to "Configuring Cascading Replication," on page 343.

Note

You can combine multi-master and cascading replication. For example, in the multi-master scenario illustrated in <Z_Online>Figure 8-2, on page 314,, server C and server D could be hub suppliers that would replicate to any number of consumer servers.


Handling Complex Replication Configurations

If you are configuring replication for a large number of servers and your configuration is relatively complex, for reasons of efficiency, you should proceed in the following order:

  1. On all consumer servers:
    • Create the replica databases.
    • Create the Replication Manager, or supplier bind DN, entry.
    • Specify the replica settings for a read-only replica.
  2. On all hub suppliers:
    • Create the replica databases.
    • Create the Replication Manager, or supplier bind DN, entry.
    • Specify the supplier settings for replication (includes changelog configuration).
    • Specify the replica settings for a read-only replica.
  3. On all suppliers:
    • Create the replica databases.
    • Specify the supplier settings for replication (includes changelog configuration).
    • Specify the replica settings for a read-write replica.
  4. Configure replication agreements on all suppliers:
    • Between suppliers in a multi-master set.
    • Between suppliers and dedicated consumers.
    • Between suppliers and hub suppliers.
Optionally, you can initialize the replicas on the consumer servers at this stage.
  1. Configure replication agreements on all hub suppliers between the hub supplier and the dedicated consumers.
Optionally, you can initialize the replicas on the consumer servers at this stage.
Note

It is very important to create and configure all replicas before you attempt to create a replication agreement. This also means that when you create the replication agreement, you can choose to initialize consumers immediately.


These sections contain a description of the tasks you need to perform to configure replication:

Creating the Supplier Bind DN Entry

A critical part of setting up replication is to create the entry, referred to as the Replication Manager or supplier bind DN entry, that the suppliers will use to bind to the consumer servers to perform replication updates.

The supplier bind DN must meet the following criteria:

For example, you could create an entry cn=Replication Manager,cn=config under the cn=config tree on the consumer server. This would be the supplier bind DN that all supplier servers would use to bind to the consumer to perform replication operations.

Note

Avoid creating simple entries under the cn=config entry in the dse.ldif file. The cn=config entry in the simple, flat dse.ldif configuration file is not stored in the same highly scalable database as regular entries. As a result, if many entries, and particularly entries that are likely to be updated frequently, are stored under cn=config, performance will probably suffer.

However, although we recommend you do not store simple user entries under cn=config for performance reasons, it can be useful to store special user entries such as the Directory Manager entry or Replication Manager (supplier bind DN) entry under cn=config, as this allows you to centralize configuration information.


On each server that acts as a consumer in replication agreements, create a special entry that the supplier will use to bind.

This entry must not be part of the replicated database. For example, you could use cn=Replication Manager,cn=config. Make sure you create the entry with the attributes required by the authentication method you specify in the replication agreement.

  1. Stop the Directory Server. If you do not stop the server, the changes you make to the dse.ldif file will not be saved. See "Starting and Stopping the Directory Server," on page 37, for more information on stopping the server.
  2. Create a new entry, such as cn=replication manager,cn=config, in the dse.ldif file.
  3. Specify a userPassword attribute-value pair.
  4. If you have enabled the password expiration policy or intend to do so in the future, you must remember to disable it to prevent replication from failing due to passwords expiring. To disable the password expiration policy on the userPassword attribute, add the passwordExpirationTime attribute with a value of 20380119031407Z, which means that the password will never expire.
  5. The final entry should resemble this example:
dn: cn=replication manager,cn=config
objectClass: inetorgperson
objectClass: person
objectClass: top
cn: replication manager
sn: RM
userPassword: password
passwordExpirationTime: 20380119031407Z

  1. Restart the Directory Server. See "Starting and Stopping the Directory Server," on page 37, for more information on starting the server.

When you configure a replica as a consumer, you must use the DN of this entry to define the supplier bind DN.

Configuring Supplier Settings

On any server that holds the master copy of a replica, you must specify supplier settings.

To configure supplier settings:

  1. In the Directory Server Console, select the Configuration tab.
For information on starting the Directory Server Console, see "Using the Directory Server Console," on page 34.
  1. In the left navigation tree, highlight the Replication node.
  2. In the right pane, select the Supplier Settings tab.
  3. Check the Enable Changelog checkbox.
This activates all of the fields in the pane below that were previously grayed out.
  1. Specify a changelog by clicking the "Use default" button, or click Browse to display a file selector.
  2. Set the changelog number and age parameters.
You must clear the unlimited checkboxes to specify different values.
  1. Click Save to save the supplier settings.

Configuring a Read-Write Replica

For each read-write replica on the supplier server, you must specify the appropriate replication settings.

To configure a read-write replica:

  1. In the Directory Server Console, select the Configuration tab.
For information on starting the Directory Server Console, see "Using the Directory Server Console," on page 34.
  1. In the left navigation tree, expand the Replication folder, and highlight the database to replicate.
The Replication tab is displayed on the right pane.
  1. Check the Enable Replica checkbox.
  2. In the Replica Role section, select the Single Master or Multi-Master radio button.
  3. In the Common Settings section, specify a Replica ID (an integer between 1 and 254, both inclusive).
The replica ID must be unique for a given suffix. Make sure you specify an ID that is different from the IDs used for read-write replicas on this server and on other servers.
  1. In the Common Settings section, specify a purge delay in the "Purge delay" field.
This option indicates how often the state information stored in the replicated entries is purged.
  1. Click Save to save the replication settings for the database.

Configuring a Read-Only Replica

For each read-only replica on the consumer server, you must specify the appropriate replication settings.

  1. In the Directory Server Console, click the Configuration tab.
For information on starting the Directory Server Console, see "Using the Directory Server Console," on page 34.
  1. In the left navigation tree, expand the Replication folder, and then highlight the replica database.
The Replica Settings tab is displayed on the right pane.
  1. Check the Enable Replica checkbox.
  2. In the Replica Role section, select the Dedicated Consumer option.
  3. In the Common Settings section, specify a purge delay in the "Purge delay" field.
This option indicates how often the state information stored in the replicated entries is purged.
  1. In the Update Settings section, specify the supplier bind DN that the supplier will use to bind to the replica.
This supplier bind DN or entry DN must correspond to the entry you created on the server that acts as a consumer in the replication agreement. You can now specify multiple supplier bind DNs per replica but only one supplier DN per replication agreement. To specify your supplier bind DN, enter your supplier bind DN in the "Enter a new Supplier DN" field and click Add. Your supplier bind DN will appear in the Current Supplier DNs list. Repeat the operation for every supplier bind DN you want to include in the list.
The supplier bind DN corresponds to a privileged user because it is not subject to access control.
  1. Specify any supplier servers to which you want to refer updates.
By default, all updates are first referred to the supplier servers that you specify here. If you specify none, updates are referred to the supplier servers that have a replication agreement that includes the current replica.
Automatic referrals assume that clients will bind over a regular connection, and, therefore, are of the form ldap://hostname:port. If you want clients to bind to the supplier using SSL, you can use this field to specify a referral of the form ldaps://hostname:port, where the s in ldaps indicates secure connections.
In the case of cascading replication, referrals are automatically sent to the hub supplier, which in turn refers the request to the original supplier. Therefore, you should set a referral to the original supplier to replace the automatically generated referral.
  1. Click Save to save the replication settings for the replica.

Configuring a Hub Supplier

In a cascading replication environment, configure the hub supplier as follows:

  1. In the Directory Server Console, select the Configuration tab.
For information on starting the Directory Server Console, see "Using the Directory Server Console," on page 34.
  1. In the left navigation tree, expand the Replication folder, and then highlight the database to replicate.
The Replica Settings tab is displayed on the right pane.
  1. Check the Enable Replica checkbox.
  2. In the Replica Role section, select the Hub radio button.
  3. In the Common Settings section, specify a purge delay in the "Purge delay" field.
This option indicates how often the state information stored in the replicated entries is purged.
  1. In the Update Settings section, specify the supplier bind DN that the supplier will use to bind to the replica.
This bind DN should correspond to the entry created in Step 2. The bind DN corresponds to a privileged user because it is not subject to access control.
  1. Specify any supplier servers to which you want to refer updates.
By default, all updates are first referred to the supplier servers that you specify here. If you specify none, updates are referred to the supplier servers that have a replication agreement that includes the current replica.
You can choose either to add the supplier servers that you specify to the automatically generated list or to use the supplier servers that you specify to replace the automatically generated list of servers.
  1. Click Save to save the replication settings for the database.

Creating a Replication Agreement

This section explains how to create a replication agreement. You must create a replication agreement on the supplier server for each read-write replica that is supplied to a consumer server or a hub supplier.

Before you can create a replication agreement, you must have:

To create a replication agreement:

  1. In the Directory Server Console, select the Configuration tab.
For information on starting the Directory Server Console, see "Using the Directory Server Console," on page 34.
  1. In the navigation tree, expand the Replication folder, right-click the database to replicate, and select New Replication Agreement.
Or highlight the database, and select New Replication Agreement from the Object menu. This will start the Replication Agreement Wizard.
Go through the steps in the Replication Agreement Wizard by clicking Next to move to the following step.
  1. In the first screen, fill in the name of your replication agreement. You may also fill in a description, such as Supplier1 to Supplier2, 4-way MMR.
  2. On the next screen, fill in the consumer hostname and port. Unless you have more than one instance of Directory Server configured, by default, there are no consumers available in the drop-down menu.
Also, select the bind method for replication. If you have enabled SSL on your servers, you may select "Using encrypted SSL connection" radio button and use SSL client authentication. Otherwise, fill in the supplier bind DN and password.
Note

If you have enabled attribute encryption, you must use a secure connection in order for those attributes to be replicated.


  1. Optionally, you can enable fractional replication. By default, all attributes are replicated to the consumer server. If you want to select attributes that will not be replicated to the consumer, enable fractional replication by checking the "Enable Fractional Replication" checkbox. Then, highlight the attribute (or attributes) in the "Included" column on the right, and click "Remove." All attributes that will not be replicated will be listed in the "Excluded" column on the left, as well as in the summary when you hae finished your replication agreement.
Note

The consumer of this replication agreement must be a dedicated consumer for fractional replication to work as a safeguard against potential data integrity problems. This is not enforced at the time you make the replication agreement, but replication will fail if your consumer is not a read-only replica. See "Replication Overview," on page 308, for more information on read-only replicas and dedicated consumers.


  1. Set the replication schedule.
By default, the servers are always kept in sync. If, for example, the connection is slow or the information being replicated doesn't change frequently, you can set a different schedule for replication, such as Monday between 12:00 p.m. and 3:00 p.m.
  1. Select when to initialize the consumer.
The default is to create an initialization file; you may also choose to initialize the consumer as soon as you finish the replication agreement or not to initialize it at all. See "Initializing Consumers," on page 350, for more information on methods and circumstances for consumer initialization.
  1. The last screen is a summary of your replication agreement. Check that this is accurate, and hit "Done."
When you have finished, an icon representing the replication agreement is displayed under the database icon. This replication agreement icon indicates that your replication agreement is set up.
Note

Once you create a replication agreement, you cannot change the connection type (SSL or non-SSL) defined in the agreement; this is because LDAP and LDAPS connections use different ports. To change the connection type, you should re-create the replication agreement.


Configuring Single-Master Replication

This section provides information on configuring single-master replication. The steps described in this section provide a high level overview of the procedure you need to follow. Cross-references to the detailed task descriptions are provided at each step.

To set up single-master replication such as the configuration shown in <Z_Online>Figure 8-1, on page 313,, between supplier server A, which holds a read-write replica, and the two consumers server B and server C, which each hold a read-only replica, you need to perform the following procedures:

Configuring the Read-Only Replica on the Consumer Server

  1. Create the database for the read-only replica if it does not exist.
For instructions, refer to "Creating Suffixes," on page 82.
  1. Create the entry corresponding to the supplier bind DN on the consumer server if it does not exist. This is the special entry that the supplier will use to bind to the consumer.
    1. In the Directory Server Console, select the Directory tab, and create an entry. For example, you could use cn=Replication Manager,cn=config.
    2. Specify a userPassword attribute-value pair.
    3. If you have enabled the password expiration policy or intend to do so in future, you must remember to disable it to prevent replication from failing due to passwords expiring.
To disable the password expiration policy on the userPassword attribute, add the passwordExpirationTime attribute with a value of 20380119031407Z ,which means that the password will never expire.
Note

This entry must not be part of the replicated database.


  1. Specify the replication settings required for a read-only replica.
    1. In the Directory Server Console, select the Configuration tab.
    2. In the navigation tree, expand the Replication folder, and highlight the replica database.
The Replica Settings tab is displayed in the right-hand side of the window.
    1. Check the Enable Replica checkbox.
    2. In the Replica Role section, select the Dedicated Consumer radio button.
    3. In the Common Settings section, specify a purge delay in the "Purge delay" field.
This option indicates how often the state information stored in the replicated entries is purged.
    1. In the Update Settings section, specify the bind DN that the supplier will use to bind to the replica.
This supplier bind DN should correspond to the entry created in Step 2. The supplier bind DN corresponds to a privileged user because it is not subject to access control.
You can now specify multiple supplier bind DNs per replica but only one supplier DN per replication agreement. To specify your supplier bind DN, enter your supplier bind DN in the "Enter a new Supplier DN" field, and click Add. You supplier bind DN will appear in the Current Supplier DNs list. Repeat the operation for every supplier bind DN you want to include in the list.
    1. Specify any supplier servers to which you want to refer updates.
By default, all updates are first referred to the supplier servers that you specify here. If you specify none, updates are referred to the supplier servers that have a replication agreement that includes the current replica.
Automatic referrals assume that clients will bind over a regular connection and, therefore, are of the form ldap://hostname:port. If you want clients to bind to the supplier using SSL, you can use this field to specify a referral of the form ldaps://hostname:port, where the s in ldaps indicates secure connections.
  1. Click Save to save the replication settings for the replica.
  2. Repeat these steps for every read-only replica in your replication configuration.

Configuring the Read-Write Replica on the Supplier Server

  1. Specify the supplier settings for the server.
    1. In the Directory Server Console, select the Configuration tab.
    2. In the navigation tree, highlight the Replication node.
    3. In the right-hand side of the window, select the Supplier Settings tab.
    4. Check the Enable Changelog checkbox.
This activates all of the fields in the pane below that were previously greyed out.
    1. Specify a changelog by clicking the "Use default" button, or click the Browse button to display a file selector.
    2. Set the changelog parameters (number and age).
You must clear the unlimited checkboxes if you want to specify different values.
    1. Click Save to save the supplier settings.
  1. Specify the replication settings required for a read-write replica.
    1. In the navigation tree on the Configuration tab, expand the Replication node, and highlight the database to replicate.
The Replica Settings tab is displayed in the right-hand side of the window.
    1. Check the Enable Replica checkbox.
    2. In the Replica Role section, select the Single Master radio button.
    3. In the Common Settings section, specify a Replica ID (an integer between 1 and 254 inclusive).
The replica ID must be unique for a given suffix, different from the IDs used for read-write replicas on this server and on other servers.
    1. In the Common Settings section, specify a purge delay in the "Purge delay" field.
This option indicates how often the state information stored in the replicated entries is purged.
    1. Click Save to save the replication settings for the database.
  1. Create a replication agreement.
You must create one replication agreement for each read-only replica. For example, in the case illustrated in <Z_Online>Figure 8-1, on page 313,, server A holds two replication agreements, one for server B and one for server C.
    1. In the navigation tree of the Configuration tab, right-click the database to replicate, and select New Replication Agreement.
Or highlight the database, and select New Replication Agreement from the Object menu. This will start the Replication Agreement Wizard.
    1. Go through the steps in the replication wizard by clicking Next to move to the following step.
    2. When you have finished, the replication agreement is set up.

Initializing the Replicas for Single-Master Replication

You can initialize the read-only replicas from the Replication Agreement Wizard or at anytime afterwards. For information on initializing read-only replicas, refer to "Initializing Consumers," on page 350.

When you have finished, the replication agreement is set up.

Configuring Multi-Master Replication

This section provides information on configuring multi-master replication. In a multi-master configuration, many suppliers can accept updates, synchronize with each other, and update all consumers. The consumers can send referrals for updates to all masters. The steps described in this section provide a high-level overview of the procedures you need to follow for two sample multi-master replication scenarios.

Configuring 2-Way Multi-Master Replication

To set up multi-master replication such as the configuration shown in <Z_Online>Figure 8-2, on page 314,, between two suppliers server A and server B, which each hold a read-write replica, and two consumers server C and server D, which each hold a read-only replica, you need to perform the following procedures:

Configuring the Read-Only Replicas on the Consumer Servers

Perform these steps on each consumer server, server C and server D:

  1. Create the database for the read-only replica, if it does not exist.
For instructions, refer to "Creating Suffixes," on page 82.
  1. Create the entry corresponding to the supplier bind DN if it does not exist.
Note

This is the special entry that the supplier will use to bind. The entry must not be part of the replicated database.


    1. In the Directory Server Console, select the Directory tab.
    2. Create an entry.
For example you could use cn=Replication Manager,cn=config.
    1. Specify a userPassword attribute-value pair.
    2. If you have enabled the password expiration policy or intend to do so in the future, disable it for this entry to prevent replication from failing due to expiration of passwords.
To disable the password expiration policy on the userPassword attribute, add the passwordExpirationTime attribute with a value of 20380119031407Z, which means that the password will never expire.
  1. Specify the replication settings required for a read-only replica.
    1. In the Directory Server Console, select the Configuration tab.
    2. In the navigation tree, expand the Replication folder, and then select the replica database.
The Replica Settings tab is displayed on the right pane.
    1. Check the Enable Replica checkbox.
    2. In the Replica Role section, select the Dedicated Consumer radio button.
    3. In the Common Settings section, specify a purge delay in the "Purge delay" field.
This option indicates how often the state information stored in the replicated entries is purged.
    1. In the Update Settings section, specify the bind DN or entry DN that the supplier will use to bind to the replica.
This supplier bind DN should correspond to the entry created in Step 2. The supplier bind DN corresponds to a privileged user because it is not subject to access control.
You can specify multiple supplier bind DNs per replica but only one supplier DN per replication agreement. To specify your supplier bind DN, enter your supplier bind DN in the "Enter a new Supplier DN" field, and click Add. You supplier bind DN will appear in the Current Supplier DNs list. Repeat the operation for every supplier bind DN you want to include in the list.
    1. Specify any supplier servers to which you want to refer updates.
By default, all updates are first referred to the supplier servers that you specify here. If you specify none, updates are referred to the supplier servers that have a replication agreement that includes the current replica.
Automatic referrals assume that clients will perform a simple bind and, therefore, are of the form ldap://hostname:port. If you want clients to bind to the supplier using SSL, you can use this field to specify a referral of the form ldaps://hostname:port, where the s in ldaps indicates secure connections.
  1. Click Save to save the replication settings for the replica.
  2. Repeat these steps for every read-only replica in your replication configuration.

Configuring the Read-Write Replicas on the Supplier Servers

Perform these steps on each supplier server, server A and server B:

  1. Specify the supplier settings for each server.
    1. In the Directory Server Console, select the Configuration tab.
    2. In the navigation tree, highlight the Replication node.
    3. In the right-hand side of the window, select the Supplier Settings tab.
    4. Check the Enable Changelog checkbox.
This activates all of the fields in the pane below.
    1. Specify a changelog by clicking the "Use default" button, or click the Browse button to display a file selector.
    2. Set the changelog parameters (number and age).
You must clear the unlimited checkboxes if you want to specify different values.
    1. Click Save to save the supplier settings.
  1. Create the entry corresponding to the supplier bind DN if it does not exist.
For multi-master replication, it is necessary to create this supplier bind DN on the supplier servers (as well as the consumers) because they act as both consumer and supplier to the other supplier servers.
Note

This is the special entry that the supplier will use to bind. The entry must not be part of the replicated database.


    1. In the Directory Server Console, select the Directory tab.
    2. Create an entry.
For example, you could use cn=Replication Manager,cn=config.
    1. Specify a userPassword attribute-value pair.
    2. If you have enabled the password expiration policy or intend to do so in the future, disable it to prevent replication from failing due to expiration of passwords.
To disable the password expiration policy on the userPassword attribute, add the passwordExpirationTime attribute with a value of 20380119031407Z, which means that the password will never expire.
  1. On server A and server B, specify the replication settings for the multi-mastered read-write replica.
    1. In the Directory Server Console, select the Configuration tab.
    2. Expand the Replication node, and select the database to replicate.
The Replica Settings tab is displayed on the right pane.
    1. Check the Enable Replica checkbox.
    2. In the Replica Role section, select the Multiple Master radio button.
    3. In the Common Settings section, specify a Replica ID.
The replica ID must be an integer between 1 and 254, both inclusive, and must be unique for a given suffix. Make sure you specify an ID that is different from the IDs used for read-write replicas on this server and on other servers.
    1. In the Common Settings section, specify a purge delay in the "Purge delay" field.
This option indicates how often the state information stored in the replicated entries is purged.
    1. In the Update Settings section, specify the supplier bind DN or entry DN that the supplier will use to bind to the replica.
This supplier bind DN should correspond to the entry created in Step 2. The supplier bind DN corresponds to a privileged user because it is not subject to access control.
    1. Specify the supplier server to which you want to refer updates (the other supplier in the multi-master set).
Only specify the URL for the supplier server if you want clients to bind using SSL. In such a case, you must specify a URL beginning with ldaps://.
    1. Click Save to save the replication settings for the database.
  1. On server A, set up the following replication agreements:
    • One with supplier server B, where server B is configured as a consumer for the replica.
    • One for each consumer servers, server C and server D.
To do this:
    1. In the Directory Server Console, select the Configuration tab.
    2. In the navigation tree, right-click the database to replicate, and select New Replication Agreement.
Or highlight the database, and select New Replication Agreement from the Object menu. This will start the Replication Agreement Wizard.
    1. Go through the steps in the replication wizard by clicking Next to move to the following step.
You can initialize the read-only replicas and the read-write replica on server B from the Replication Agreement Wizard or at anytime afterwards. For information on the order and procedure for initializing read-only replicas, refer to "Initializing the Replicas for Multi-Master Replication," on page 335, and "Initializing Consumers," on page 350.
When you have finished, the replication agreement is set up.
  1. On server B, set up the following replication agreements:
    • One with supplier server A, where server A is declared as a consumer for the replica. During this operation, do not initialize server A from server B if you have already initialized server B from server A in Step 4.
    • One for each consumer servers, server C and server D.
Note

Once you have completed these procedures, server A and server B have mutual replication agreements, which means that they can accept updates from each other.


When you have configured the servers holding the read-write replicas, the necessary replication agreements, and the servers holding the read-only replicas, you are ready to initialize replication. You can perform this task when you create the replication agreements on the supplier servers or at any time afterwards.

Initializing the Replicas for Multi-Master Replication

In the case of multi-master replication, you should initialize replicas in the following order:

  1. Ensure one supplier has the complete set of data to replicate. Use this supplier to initialize the replicas on the other masters in the multi-master replication set.
  2. Initialize the replicas on the consumer servers from any one of the two suppliers.

For information on initializing replicas, refer to "Initializing Consumers," on page 350.

Configuring 4-Way Multi-Master Replication

Directory Server supports 4-way multi-master replication. To set up multi-master replication such as the configuration shown in <Z_Online>Figure 8-3, on page 315,, between four supplier servers, server M1 through server M4, that each hold a read-write replica, and eight consumer servers, server C1 through server C8, that each hold a read-only replica, you need to perform the following procedures:

Note

If you have more than 10 databases running with replication, you may see performance degradation. Also, if you have more than 20 replication agreements on a supplier, you may see performance degradation. If you need to support that many consumers, you may have to introduce one or more hub replicas between your supplier(s) and consumers. See "Configuring Cascading Replication," on page 343.


Configuring the Read-Only Replicas on the Consumer Servers

Perform these steps on each consumer server, server C1 through server C8:

  1. Create the database for the read-only replica if it does not exist.
For instructions, refer to "Creating Suffixes," on page 82.
  1. Create the entry corresponding to the supplier bind DN if it does not exist.
Note

This is the special entry that the supplier will use to bind. The entry must not be part of the replicated database.


    1. In the Directory Server Console, select the Directory tab.
    2. Create an entry.
For example, you could use cn=Replication Manager,cn=config.
    1. Specify a userPassword attribute-value pair.
    2. If you have enabled the password expiration policy or intend to do so in the future, disable it to prevent replication from failing due to expiration of passwords.
To disable the password expiration policy on the userPassword attribute, add the passwordExpirationTime attribute with a value of 20380119031407Z, which means that the password will never expire.
  1. Specify the replication settings required for a read-only replica.
    1. In the Directory Server Console, select the Configuration tab.
    2. In the navigation tree, expand the Replication folder, and select the replica database.
The Replica Settings tab is displayed on the right pane.
    1. Check the Enable Replica checkbox.
    2. In the Replica Role section, select the Dedicated Consumer radio button.
    3. In the Common Settings section, specify a purge delay in the "Purge delay" field.
This option indicates how often the state information stored in the replicated entries is purged.
    1. In the Update Settings section, specify the bind DN that the supplier will use to bind to the replica.
This supplier bind DN should correspond to the entry created in Step 2. The supplier bind DN corresponds to a privileged user because it is not subject to access control.
You can specify multiple supplier bind DNs per replica but only one supplier DN per replication agreement. To specify your supplier bind DN, enter your supplier bind DN in the "Enter a new Supplier DN" field, and click Add. You supplier bind DN will appear in the Current Supplier DNs list. Repeat the operation for every supplier bind DN you want to include in the list.
    1. Specify the supplier servers to which you want to refer updates.
By default, all updates are first referred to the supplier servers that you specify here. If you specify none, updates are referred to the supplier servers that have a replication agreement that includes the current replica.
Automatic referrals assume that clients will perform a simple bind and, therefore, are of the form ldap://hostname:port. If you want clients to bind to the supplier using SSL, you can use this field to specify a referral of the form ldaps://hostname:port, where the s in ldaps indicates secure connections.
  1. Click Save to save the replication settings for the replica.
  2. Repeat these steps for every read-only replica in your replication configuration.

Configuring the Read-Write Replicas on the Supplier Servers

Perform these steps on each supplier server, server M1 through server M4:

  1. Specify the supplier settings for each server.
    1. In the Directory Server Console, select the Configuration tab.
    2. In the navigation tree, highlight the Replication node, and, on the right pane, select the Supplier Settings tab.
    3. Check the Enable Changelog checkbox.
This activates all of the fields in the pane below.
    1. Specify a changelog by clicking the Use Default button, or click the Browse button to display a file selector.
    2. Set the changelog parameters (number and age).
You must clear the unlimited checkboxes if you want to specify different values.
    1. Click Save to save the supplier settings.
  1. Create the entry corresponding to the supplier bind DN if it does not already exist.
For multi-master replication, it is necessary to create this supplier bind DN on the supplier servers (as well as the consumers) because they act as both consumer and supplier to the other supplier servers.
Note

This is the special entry that the supplier will use to bind. The entry must not be part of the replicated database.


    1. In the Directory Server Console, select the Directory tab.
    2. Create an entry.
For example, you could use cn=Replication Manager,cn=config.
    1. Specify a userPassword attribute-value pair.
    2. If you have enabled the password expiration policy or intend to do so in the future, disable it to prevent replication from failing due to expiration of passwords.
To disable the password expiration policy on the userPassword attribute, add the passwordExpirationTime attribute with a value of 20380119031407Z, which means that the password will never expire.
  1. Specify the replication settings for the multi-mastered read-write replica.
    1. In the navigation tree of the Configuration tab, expand the Replication node, and then select the database to replicate.
The Replica Settings tab is displayed on the right pane.
    1. Check the Enable Replica checkbox.
    2. In the Replica Role section, select the Multiple Master radio button.
    3. In the Common Settings section, specify a Replica ID.
The replica ID must be an integer between 1 and 254, both inclusive, and must be unique for a given suffix. Make sure you specify an ID that is different from the IDs used for read-write replicas on this server and on other servers.
    1. In the Common Settings section, specify a purge delay in the "Purge delay" field.
This option indicates how often the state information stored in the replicated entries is purged.
    1. In the Update Settings section, specify the supplier bind DN or entry DN that the supplier will use to bind to the replica.
This supplier bind DN should correspond to the entry created in Step 2. The supplier bind DN corresponds to a privileged user because it is not subject to access control.
    1. Specify the supplier server to which you want to refer updates (the other suppliers in the multi-master set).
Only specify the URL for the supplier server. If you want clients to bind using SSL, you must specify a URL beginning with ldaps://.
    1. Click Save to save the replication settings for the database.
  1. Set up replication agreements on all the supplier servers:
    • On server M1, set up the following replication agreements: one with supplier server M2, where server M2 is configured as a consumer for the replica; one with supplier server M4, where server M4 is configured as a consumer for the replica; and one for each consumer servers, server C1 through server C8.
    • On server M2, set up the following replication agreements: one with supplier server M1, where server M1 is declared as a consumer for the replica; one with supplier server M3, where server M3 is declared as a consumer for the replica; and one for each consumer servers, server C1 through server C8.
    • On server M3, set up the following replication agreements: one with supplier server M2, where server M2 is declared as a consumer for the replica; one with supplier server M4, where server M4 is declared as a consumer for the replica; and one for each consumer, server C1 through server C8.
    • On server M4, set up the following replication agreements: one with supplier server M3, where server M3 is declared as a consumer for the replica; one with supplier server M1, where server M1 is declared as a consumer for the replica; and one for each consumer servers, server C1 through server C8.
To set up a replication agreement:
    1. In the Directory Server Console, select the Configuration tab.
    2. In the navigation tree, right-click the database to replicate, and then select New Replication Agreement.
Or highlight the database, and select New Replication Agreement from the Object menu. This will start the Replication Agreement Wizard.
    1. Go through the steps in the replication wizard by clicking Next to move to the following step.
When you have finished, the replication agreement is set up.
Note

Once you have completed these procedures, all four servers - server M1 through server M4 - have mutual replication agreements, which means that they can accept updates from each other.


When you have configured the servers holding the read-write replicas, the necessary replication agreements, and the servers holding the read-only replicas, you are ready to initialize replication. You can perform this task when you create the replication agreements on the supplier servers or at any time afterwards. For information on the order and procedure for initializing read-only replicas, refer to "Initializing the Replicas for Multi-Master Replication," on page 335, and "Initializing Consumers," on page 350.

During this operation, do not try to reinitialize the servers. For example, do not initialize server M1 from server M2 if you have already initialized server M2 from server M1.

Initializing the Replicas for Multi-Master Replication

In the case of multi-master replication, you should initialize replicas in the following order:

  1. Ensure one supplier has the complete set of data to replicate. Use this supplier to initialize the replica on the other supplier in the multi-master replication set.
  2. Initialize the replicas on the consumer servers from either of the four suppliers.

For information on initializing replicas, refer to "Initializing Consumers," on page 350.

Preventing Monopolization of the Consumer in Multi-Master Replication

One of the features of multi-master replication is that a supplier acquires exclusive access to the consumer for the replicated area. During this time, other suppliers are locked out of direct contact with the consumer. If a supplier attempts to acquire access while locked out, the consumer sends back a busy response, and the supplier sleeps for several seconds before making another attempt.

A problem can arise if the locking supplier is under a heavy update load or has a lot of pending updates in the changelog. If the locking supplier finishes sending updates and then has more pending changes to send, it will immediately attempt to reacquire the consumer and will most likely succeed, since the other suppliers usually will be sleeping. This can cause a single supplier to monopolize a consumer for several hours or longer.

Two attributes address this issue:

Amount of time in seconds a supplier should wait after a consumer sends back a busy response before making another attempt to acquire access. The default is 3 seconds.
Amount of time in seconds a supplier should wait between update sessions. Set this interval so that it is at least 1 second longer than the interval specified for nsds5ReplicaBusyWaitTime. Increase the interval as needed until you reach an acceptable distribution of consumer access among the suppliers. The default is 0.

These two attributes may be present in the nsds5ReplicationAgreement object class, which is used to describe replication agreements. You can set the attributes at any time by using changetype:modify with the replace operation. The change takes effect for the next update session if one is already in progress.

Note

If you set either attribute to a negative value, Directory Server sends the client a message and an LDAP_UNWILLING_TO_PERFORM error code.


The two attributes are designed so that the nsds5ReplicaSessionPauseTime interval will always be at least 1 second longer than the interval specified for nsds5ReplicaBusyWaitTime. The longer interval gives waiting suppliers a better chance to gain consumer access before the previous supplier can re-access the consumer.

If Directory Server has to automatically reset the value of nsds5ReplicaSessionPauseTime, the value is changed internally only. The change is not visible to clients, and it not saved to the configuration file. From an external viewpoint, the attribute value appears as originally set.

Replica busy errors are no longer logged by default because they are usually benign. If you want to see them, turn on the replication error log level.

Configuring Cascading Replication

This section provides information on setting up cascading replication. The steps described in this section provide a high-level overview of the procedures you need to follow, and cross-references to the detailed task descriptions are provided at each step.

To set up cascading replication such as the configuration shown in <Z_Online>Figure 8-4, on page 316,, between the supplier on server A, which holds a read-write replica; the consumer/supplier on hub server B, which holds a read-only replica; and the consumer on server C, which holds a read-only replica, you need to perform the following procedures:

Configuring the Read-Only Replica on the Consumer Server

To configure the read-only replica in a consumer server:

  1. On the consumer server, create the database for the replica if it does not exist.
For instructions, refer to "Creating Suffixes," on page 82.
  1. On the consumer server, create the entry corresponding to the supplier bind DN if it does not exist. This is the special entry that the supplier will use to bind.
  2. On the consumer server, specify the replication settings for the read-only replica.
    1. In the Directory Server Console, select the Configuration tab.
    2. In the navigation tree, expand the Replication folder, and highlight the replica database.
The Replica Settings tab is displayed on the right pane.
    1. Check the Enable Replica checkbox.
    2. In the Replica Role section, select the Dedicated Consumer radio button.
    3. In the Common Settings section, specify a purge delay in the "Purge delay" field.
This option indicates how often the state information stored in the replicated entries is purged.
    1. In the Update Settings section, specify the bind DN that the supplier will use to bind to the replica.
This supplier bind DN should correspond to the entry created in Step 2. The supplier bind DN corresponds to a privileged user because it is not subject to access control.
You can specify multiple supplier bind DNs per replica but only one supplier DN per replication agreement. To specify your supplier bind DN, enter your supplier bind DN in the "Enter a new Supplier DN" field, and click Add. You supplier bind DN will appear in the Current Supplier DNs list. Repeat the operation for every supplier bind DN you want to include in the list.
    1. Specify any supplier servers to which you want to refer updates.
By default, all updates are first referred to the supplier servers that you specify here. If you specify none, updates are referred to the supplier servers that have a replication agreement that includes the current replica.
In the case of cascading replication, referrals are automatically sent to the hub supplier, which in turn refers the request to the original supplier. Therefore, you should set a referral to the original supplier to replace the automatically generated referral.
  1. On the supplier server, set up the replication agreement between this server and the hub supplier.
    1. In the navigation tree of the Configuration tab, right-click the database to replicate, and then select New Replication Agreement.
Or highlight the database, and select New Replication Agreement from the Object menu. This will start the Replication Agreement Wizard.
    1. Go through the steps in the replication wizard by clicking Next to move to the following step.
You can initialize the read-only replicas from the Replication Agreement Wizard or at anytime afterwards. For information on initializing read-only replicas, refer to "Initializing Consumers," on page 350.
  1. On the hub supplier, set up the replication agreement between this server and the consumer.

When you have configured the replicas on each server and the necessary replication agreements among servers, you can initialize the read-only replicas on the hub supplier and on the consumer. You can perform this task from the Replication Agreement Wizard while you are configuring the supplier server and the hub supplier server or at any time afterwards.

Configuring the Read-Only Replica on the Hub Supplier

Perform these steps on the hub supplier that receives replication updates from the supplier and propagates them to consumers:

  1. Create the database for the replica if it does not exist.
For instructions, refer to "Creating Suffixes," on page 82.
  1. Create the entry corresponding to the supplier bind DN if it does not exist.
Note

This is the special entry that the supplier will use to bind. The entry must not be part of the replicated database.


    1. In the Directory Server Console, select the Directory tab.
    2. Create an entry.
For example you could use cn=Replication Manager,cn=config.
    1. Specify a userPassword attribute-value pair.
    2. If you have enabled the password expiration policy or intend to do so in the future, disable it to prevent replication from failing due to expiration of passwords.
To disable the password expiration policy on the userPassword attribute, add the passwordExpirationTime attribute with a value of 20380119031407Z, which means that the password will never expire.
  1. Specify the required replication settings.
    1. In the Directory Server Console, select the Configuration tab.
    2. In the navigation tree, expand the Replication node, and then select the database to replicate.
The Replica Settings tab is displayed on the right pane.
    1. Check the Enable Replica checkbox.
    2. In the Replica Role section, select the Hub radio button.
    3. In the Common Settings section, specify a purge delay in the "Purge delay" field.
This option indicates how often the state information stored in the replicated entries is purged.
    1. In the Update Settings section, specify the supplier bind DN that the supplier will use to bind to the replica.
This supplier bind DN should correspond to the entry created in Step 2. The supplier bind DN corresponds to a privileged user because it is not subject to access control.
You can specify multiple supplier bind DNs per replica but only one supplier DN per replication agreement. To specify your supplier bind DN, enter your supplier bind DN in the "Enter a new Supplier DN" field, and click Add. Your supplier bind DN will appear in the Current Supplier DNs list. Repeat the operation for every supplier bind DN you want to include in the list.
    1. Specify any supplier servers to which you want to refer updates.
By default, all updates are first referred to the supplier servers that you specify here. If you specify none, updates are referred to the supplier servers that have a replication agreement that includes the current replica.
Automatic referrals assume that clients will bind over a regular connection and, therefore, are of the form ldap://hostname:port. If you want clients to bind to the supplier using SSL, you can use this field to specify a referral of the form ldaps://hostname:port.
    1. Click Save to save the replication settings for the database.

Configuring the Read-Write Replica on the Supplier Server

Perform these steps on the supplier server that holds the original copy of the database:

  1. Specify the supplier settings for the server.
    1. In the Directory Server Console, select the Configuration tab.
    2. In the navigation tree, highlight the Replication node.
    3. On the right pane, select the Supplier Settings tab.
    4. Check the Enable Changelog checkbox.
This activates all of the fields in the pane.
    1. Specify a changelog by clicking the "Use default" button, or click the Browse button to display a file selector.
    2. Set the changelog parameters (number and age).
You must clear the unlimited checkboxes if you want to specify different values.
    1. Click Save to save the supplier settings.
  1. Specify the required replication settings.
    1. In the navigation tree of the Configuration tab, expand the Replication node, and then highlight the database to replicate.
The Replica Settings tab is displayed in the right-hand side of the window.
    1. Check the Enable Replica checkbox.
    2. In the Replica Role section, select the Single Master radio button.
    3. In the Common Settings section, specify a Replica ID.
The replica ID must be an integer between 1 and 254, both inclusive, and must be unique for a given suffix. Make sure you specify an ID that is different from the IDs used for read-write replicas on this server and on other servers.
    1. In the Common Settings section, specify a purge delay in the "Purge delay" field.
This option indicates how often the state information stored in the replicated entries is purged.
    1. Click Save to save the replication settings for the database.

Initializing the Replicas for Cascading Replication

In the case of cascading replication, you should initialize replicas in the following order:

  1. Use the supplier server to initialize the replica on the hub supplier.
  2. From the hub supplier, initialize the replica on the consumer.

For information on initializing replicas, refer to "Initializing Consumers," on page 350.

Making a Replica Updatable

To make a read-only server writable, follow this procedure:

  1. Make sure there are no updates in progress.
  2. Stop the supplier server.
  3. Open the Directory Server Console for the read-only replica.
  4. In the configuration tab, select Replication, and then, on the right pane, enable changelog.
  5. Select the suffix, and, in the Replica Settings tab, change Replica Role to Single Master, and assign a unique replica ID.
  6. Save your changes, and restart the server.

Deleting the Changelog

The changelog is a record of all modifications on a given replica that the supplier uses to replay these modifications to replicas on consumer servers (or suppliers in the case of multi-master replication). In the event of a supplier server going offline, it is important to be able to delete the changelog because it no longer holds a true record of all modifications and, as a result, should not be used as a basis for replication. Once you have deleted the changelog, you can initialize your consumers and begin the replication process afresh. To delete the changelog, you can either remove it or move it to a new location.

This section contains the information for the following procedures:

Removing the Changelog

You can remove the changelog using the Directory Server Console. To remove the changelog from the supplier server:

  1. In the Directory Server Console, select the Configuration tab.
  2. Select the Replication Agreements folder in the left navigation tree and then the Supplier Server Settings tab in the right pane.
  3. Clear the Enable Changelog checkbox.
This deletes the changelog.
  1. Click Save.
  2. Restart the Directory Server.
  3. Reinitialize your consumers.
See "Initializing Consumers," on page 350, for information.
Note

If you remove the changelog, you will need to reinitialize your consumer servers.


Moving the Changelog to a New Location

To delete the changelog while the server is still running and continuing to log changes, you simply move the changelog to a new location. By moving the changelog, a new changelog is created in the directory you specify, and the old changelog is deleted. If you change the location of the changelog, it is as if you are reinitializing it, which in turn requires consumer reinitialization.

For example, you could move the changelog from the default location of

serverRoot/slapd-serverID/changelogdb
 

to

serverRoot/slapd-serverID/newchangelogdb
 

Initializing Consumers

Once you have created a replication agreement, you must initialize the consumer; that is, you must physically copy data from the supplier server to the consumer servers. This section first describes consumer initialization in detail and then provides instructions on the two different methods for initializing consumers. This section is divided into the following parts:

When to Initialize a Consumer

Consumer initialization involves copying data from the supplier server to the consumer server. Once the subtree has been physically placed on the consumer, the supplier server can begin replaying update operations to the consumer server.

Under normal operations, the consumer should not ever have to be initialized again. However, if the data on the supplier server is restored from backup for any reason, then you should reinitialize all of the consumers supplied by it.

You can either initialize the consumer online using the Console or manually using the command-line. Online consumer initialization using the Console is an effective method of initializing a small number of consumers. However, since each replica is initialized in sequence, this method is not suited to initializing a large number of replicas. Online consumer initialization is the method to use when you initialize the consumer while configuring the replication agreement on the supplier server.

Manual consumer initialization using the command-line is a more effective method of initializing a large number of consumers from a single LDIF file.

Online Consumer Initialization Using the Console

Online consumer initialization using the Console is the easiest way to initialize or reinitialize a consumer. However, if you are replicating across a slow link, this process can be very time-consuming, and you may find manual consumer initialization using the command-line to be a more efficient approach. Refer to "Manual Consumer Initialization Using the Command-Line," on page 352, for more information.

Note

When a consumer server is being initialized using the online consumer creation method, all operations (including searches) on the replica are referred to the supplier server until the initialization process is completed.


Performing Online Consumer Initialization

To initialize or reinitialize a consumer online:

  1. Create a replication agreement.
See "Creating a Replication Agreement," on page 324.
  1. On the supplier server, on the Directory Server Console, select the Configuration tab.
  2. Expand the Replication folder, then expand the replicated database. Right-click the replication agreement, and choose Initialize Consumer from the pop-up menu.
A message is displayed to warn you that any information already stored in the replica on the consumer will be removed.
  1. Click Yes in the confirmation box.

Online consumer initialization begins immediately. You can check the status of the online consumer initialization on the Summary tab in the Status box. If online consumer initialization is in progress, the status shows that a replica is being initialized.

To update this window, right-click the replicated database icon in the navigation tree, and choose Refresh Replication Agreements. When online consumer initialization finishes, the status changes to reflect this.

For more information about monitoring replication and initialization status, see "Monitoring Replication Status," on page 366.

Manual Consumer Initialization Using the Command-Line

Manual consumer initialization using the command-line is the fastest method of consumer initialization for sites that are replicating very large numbers of entries. However, the manual consumer initialization process is more complex than the online consumer initialization process. We suggest you use the manual process whenever you find that the online process is inappropriate due to performance concerns.

This section is divided into the following parts:

Manual Consumer Initialization Overview

To initialize or reinitialize a server manually:

  1. Create a replication agreement.
See "Creating a Replication Agreement," on page 324.
  1. Export the replica on the supplier server to an LDIF file.
See "Exporting a Replica to LDIF," on page 353.
  1. Import the LDIF file with the supplier replica contents to the consumer server.
See "Importing the LDIF File to the Consumer Server," on page 353, for instructions.

Exporting a Replica to LDIF

You can convert the replica to LDIF using one of the following three procedures:

  1. When you create a replication agreement by selecting "Create consumer initialization file" in the Initialize Consumer dialog box of the Replication Agreement Wizard.
  2. From the Directory Server Console at any time by right-clicking the replication agreement under the Replication folder and choosing "Create LDIF File" from the pop-up menu.
  3. From the command-line by using the export command as described in "Exporting to LDIF from the Command-Line," on page 161.

Importing the LDIF File to the Consumer Server

You can import the LDIF file which contains the supplier replica contents to the consumer server by using the import features in the Directory Server Console or by using either the ldif2db script or ldif2db.pl script. Both import methods are described in "Importing from the Command-Line," on page 155.

If you use the ldif2db script, remember to bind using the supplier bind DN configured on the consumer server.

Note

If you use the ldif2db.pl script, the LDIF file import operation does not require a server restart. For more information on command-line scripts, see Red Hat Directory Server Configuration, Command, and File Reference.


Filesystem Replica Initialization

If you have a very large database, such as one with several million entries, it can take an hour or more to initialize a consumer from the Console or even with manual initialization. To save time, you can use filesystem replica initialization.

Directory Server has the capability to initialize a replica using the database files from the supplier server. This avoids the need to rebuild the consumer database and can be done at essentially the speed of the network between the two servers by transferring the files with FTP or NFS, for example. Instead of sending entries via LDAP to replica servers, filesystem replica initialization populates the new database on the destination server by "backing up" the supplier database on one server and "restoring" the database on the destination server.

This method of initializing consumers is especially useful in replication over wide-area networks or over networks with slow or unstable connections.

For smaller databases, it is recommended that you still use the manual initialization or initialize consumers from the Console.

Note

The destination server must have the same architecture and the same bit size as the supplier server for the initialization to succeed. For example, Sun Solaris 32-bit to Sun Solaris 32-bit, HP-UX 64-bit to HP-UX 64-bit.


Initializing the Consumer Replica from the Backup Files

  1. Create a new database on the destination server to match the database from the source server.
Before you begin initializing the consumer from the backup files, be certain that you have created the appropriate database on your destination server so that the database exists to be "restored" and initialized.
  1. Enable replication on the backend as a dedicated consumer.
  2. If you already have a replication agreement to that host and port, than replication should resume immediately after running the restore script. Otherwise, create the replication agreement on your source server (or whatever server you will use as the supplier), and select the "Do not initialize consumers at this time" radio button.
  3. At the command prompt, change to the following directory on the source Directory Server:
cd serverRoot/slapd-serverID
 
  1. Stop the source Directory Server if it is running by typing the following:
./stop-slapd
  1. From the command-line, run the db2bak utility, and archive your current directory installation. You can also create a new backup by hitting the "Back Up Directory Server" button in the Tasks tab of the Directory Server Console and then putting the name of your archive directory in the "Directory:..." field.
You can select any previous back-up to initialize the consumer if you prefer.
This information is recovered in the destination replica.
  1. Restart the source Directory Server by typing the following:
./start-slapd
  1. Copy the archived files to a directory on your destination server, such as archiveDirectory.
  2. At the command prompt, change to the following directory on the destination Directory Server:
cd serverRoot/slapd-serverID
 
  1. Stop the destination Directory Server if it is running by typing the following:
./stop-slapd
  1. On the destination server, restore the archives with the bak2db script, using the optional -n parameter to specify the backend instance name. This -n parameter is similar to the -n used with ldif2db and db2ldif. For example:
./bak2db /redhat/servers/slapd-serverID/archiveDirectory -n 
userRoot
 
  1. Restart the destination Directory Server by typing the following:
./start-slapd

Replication will begin on schedule as soon as the destination server is restarted.

For more information on using these scripts, see the Red Hat Directory Server Configuration, Command, and File Reference.

Forcing Replication Updates

When you stop a Directory Server involved in replication for regular maintenance, when it comes back online, you need to ensure that it gets updated through replication immediately. In the case of a supplier in a multi-master environment, the directory information needs to be updated by the other supplier in the multi-master set. In other cases, when a hub supplier or a dedicated consumer is taken offline for maintenance, when they come back online, they need to be updated by the supplier server.

If you have configured replication agreements to keep the supplier server and the consumer server in sync always, this is not sufficient to bring back up-to-date a server that has been offline for over five minutes. The reason is that, with the "Always Keep in Sync" option, the server generates a replication operation for every update operation it processes. However, if this replication operation cannot be performed because the consumer is offline, the operation times out after 10 minutes.

Note

The procedures described in this section can only be used when replication is already set up and consumers have been initialized.


To ensure that directory information will be synchronized immediately when a server comes back online, you can use either the Directory Server Console on the supplier server that holds the reference copy of the directory information or a customizable script.

Forcing Replication Updates from the Console

To ensure that replication updates are sent immediately when a consumer or a supplier in a multi-master replication configuration comes back online after a period of time, you can perform these steps on the supplier server that holds the most recent version of the directory information:

  1. In the Directory Server Console, click the Configuration tab, expand the Replication folder and the database nodes until you select the replication agreement corresponding to the replica that you must update.
  2. Right click the replication agreement, and choose Send Updates Now from the drop-down list.
This initiates replication toward the server that holds the information that needs to be updated.

Forcing Replication Updates from the Command-Line

From the consumer that requires updating, you can run a script that prompts the supplier to send replication updates immediately. This script is shown in <Z_Online>Code Example 8-1.

You can copy this example and give it a meaningful name, such as replicate_now.sh. You must provide actual values for the variables listed in <Z_Online>Code Example 8-1.

Note

You must run this script since it cannot be configured to run automatically as soon as the server, which was offline, comes back online again.


Code Example 8-1 Replicate_Now Script Example  
 
#!/bin/sh
SUP_HOST=supplier_hostname
SUP_PORT=supplier_portnumber
SUP_MGRDN=supplier_directoryManager
SUP_MGRPW=supplier_directoryManager_password
MY_HOST=consumer_hostname
MY_PORT=consumer_portnumber
 
ldapsearch -1 -T -h ${SUP_HOST} -p ${SUP_PORT} -D "${SUP_MGRDN}" \
-w ${SUP_MGRPW} -b "cn=mapping tree, cn=config" \
"(&(objectclass=nsds5replicationagreement)(nsDS5ReplicaHost=${MY_HOST}) \
(nsDS5ReplicaPort=${MY_PORT}))" dn nsds5ReplicaUpdateSchedule > /tmp/$$
 
cat /tmp/$$ |
awk '
BEGIN { s = 0 }
/^dn: / { print $0;
print "changetype: modify";
print "replace: nsds5ReplicaUpdateSchedule";
print "nsds5ReplicaUpdateSchedule: 0000-2359 0123456";
print "-";
print "";
print $0;
print "changetype: modify";
print "replace: nsds5ReplicaUpdateSchedule";
}
 
/^nsds5ReplicaUpdateSchedule: / { s = 1; print $0; }
 
/^$/ {
if ( $s == 1 )
{ print "-" ; print ""; }
else
{ print "nsds5ReplicaUpdateSchedule: 0000-2359 0123456";
print "-" ; print ""; };
s = 0; }
 
' > /tmp/ldif.$$
 
echo "Ldif is in /tmp/ldif.$$"
echo
 
ldapmodify -c -h ${SUP_HOST} -p ${SUP_PORT} -D "${SUP_MGRDN}" \
-w ${SUP_MGRPW} -f /tmp/ldif.$$

If you intend to use this script, you must replace the variables with actual values in your replication environment.

Table 8-1 Replicate_Now Variables  
Variable
Definition
supplier_hostname
Hostname of the supplier to contact for information on replication agreements with the current consumer.
supplier_portnumber
LDAP port in use on the supplier.
supplier_directoryManager
DN of the privileged Directory Manager user on the supplier.
supplier_directoryManager_password
Password of the privileged Directory Manager user on the supplier.
consumer_hostname
Hostname of the current consumer.
consumer_portnumber
LDAP port in use on the consumer.

If you want the update operation to occur over an SSL connection, you must modify the ldapmodify command in the script with the appropriate parameters and values. For more information on the ldapmodify command, refer to "Managing Entries from the Command-Line," on page 57, and Red Hat Directory Server Configuration, Command, and File Reference.

Replication over SSL

You can configure Directory Servers involved in replication so that all replication operations occur over an SSL connection.

To use replication over SSL, you must first do the following:

These procedures are described in <Z_Online>Chapter 11, "Managing SSL and SASL."

Note

Replication configured over SSL with certificate-based authentication will fail in the following cases:

  • If the supplier's certificate is a self-signed certificate.
  • If the supplier's certificate is only capable of behaving as an SSL server certificate, meaning it is unable to play the role of the client during an SSL handshake.

When your servers are configured to use SSL, you can ensure replication operations occur over SSL connections by using the Replication Agreement Wizard, which enables you to set up a replication agreement between two Directory Servers. Keep in mind that once you create a replication agreement, you cannot change the connection type (SSL or nonSSL) defined in the agreement; this is because LDAP and LDAPS connections use different ports. To change the connection type, you must re-create the replication agreement.

Note

If you have enabled attribute encryption, you must use a secure connection for replication.


Configuring Replication over SSL Using the Replication Agreement Wizard

  1. In the Directory Server Console of the supplier server, click the Configuration tab, expand the Replication folder, and select the database that you want to replicate.
  2. Right-click the database, and choose New Replication Agreement from the drop-down menu.
The Replication Agreement Wizard is displayed.
  1. Go through each step in the Replication Agreement Wizard until you reach the Source and Destination window.
  2. In the Connection section, check "Using Encrypted SSL Connection."
  3. Select "SSL Client Authentication" or "Simple Authentication."
If you select SSL Client Authentication, the supplier and consumer servers will use certificates to authenticate to each other.
If you select Simple Authentication, the supplier and consumer servers will use a bind DN and password to authenticate to each other. You must specify this information in the text fields provided. When you specify this option, simple authentication takes place over a secure channel but without certificates.
  1. Click Next, and proceed with the replication setup.

Replication with Earlier Releases

This section provides information on how to optimize replication with earlier releases of Directory Server. This version of Directory Server can be involved in replication scenarios with earlier releases of Directory Server, providing the following conditions are met:

The following restrictions apply:

The main advantage of being able to use this version of Directory Server as a consumer of a legacy Directory Server is to ease the migration of a replicated environment. For more information on the steps to follow to migrate a replicated environment, refer to the Red Hat Directory Server Installation Guide.

Configuring Directory Server as a Consumer of a Legacy Directory Server

If you intend to use your Directory Server as a consumer of an earlier release of Directory Server, you must configure it as follows:

  1. In the Directory Server Console, click the Configuration tab.
For information on starting the Directory Server Console, "Using the Directory Server Console," on page 34.
  1. In the Configuration tab, select the Replication node, and click the Legacy Consumer Settings tab in the right pane.
  2. Check the Enable Legacy Consumer checkbox.
This activates the fields in the Authentication box.
  1. Specify the Supplier DN that the legacy supplier server will use to bind.
Optionally, you can specify a password. The password must contain at least 8 characters.
  1. Click Save.
You must now configure legacy consumer settings for each replica that will receive updates from a legacy supplier.
  1. In the navigation tree, expand the Replication node, and select a replica that will receive updates from the legacy supplier.
  2. In the Replica Settings tab, select the Enable Replica and "Updatable by a 4.x Replica" checkboxes.
These options are the only ones required for replication to work. You can optionally specify a Replica ID. It is not necessary to specify a Supplier DN because the one you specified in Step 4 will be used.
  1. Click Save.
  2. Repeat Step 7 and Step 8 for each read-only replica that will receive updates from a legacy supplier.
  3. To complete your legacy replication setup, you must now configure the legacy supplier to replicate to the Directory Server. For instructions on configuring a replication agreement on a 4.x Directory Server, refer to the documentation for your legacy Directory Server.
Note

The Directory Server Console will not prevent you from configuring a database as a read-write replica and enabling legacy consumer settings. This makes migration easier because you can configure your Directory Server as you want it to be after the migration and activate legacy consumer settings just for the duration of the transition.


Using the Retro Changelog Plug-in

The retro changelog plug-in enables you to configure Directory Server to maintain a changelog that is compatible with the changelog implemented in Directory Server 4.0, 4.1, and 4.1x. Maintaining a retro changelog is essential in deployments where Directory Server coexists with the retired Netscape Meta Directory application. You might also need to maintain a retro changelog if you have directory clients that depend on a Directory Server 4.x style changelog.

To use the retro changelog plug-in, Directory Server must be configured as a supplier server in a single-master replication scenario.

When you have configured Directory Server to maintain a retro changelog, this changelog is stored in a separate database under a special suffix cn=changelog.

The retro changelog consists of a single level of entries. Each entry in the changelog has the object class changeLogEntry and can include the attributes listed in <Z_Online>Table 8-2.

Table 8-2 Attributes of a Retro Changelog Entry  
Attribute
Definition
changeNumber
This single-valued attribute is always present. It contains an integer which uniquely identifies each change. This number is related to the order in which the change occurred. The higher the number, the later the change.
targetDN
This attribute contains the DN of the entry that was affected by the LDAP operation. In the case of a modrdn operation, the targetDN attribute contains the DN of the entry before it was modified or moved.
changeType
Specifies the type of LDAP operation. This attribute can have one of the following values: add, delete, modify, or modrdn.
changes
For add and modify operations, contains the changes made to the entry in LDIF format.
newRDN
In the case of modrdn operations, specifies the new RDN of the entry.
deleteOldRdn
In the case of modrdn operations, specifies whether the old RDN was deleted.
newSuperior
In the case of modrdn operations, specifies the newSuperior attribute of the entry.

This section contains information on the following retro changelog items:

Enabling the Retro Changelog Plug-in

The retro changelog plug-in configuration information is stored in the cn=Retro Changelog Plugin,cn=plugins,cn=config entry in dse.ldif.

To enable the retro changelog plug-in from the command-line:

  1. Create an LDIF file that contains the following LDIF update statements:
dn: cn=Retro Changelog Plugin,cn=plugins,cn=config
cn: Retro Changelog Plugin
changetype: modify
replace: nsslapd-pluginenabled
nsslapd-pluginenabled: on

  1. Use the ldapmodify command to import the LDIF file into the directory.
For more information on the ldapmodify command, refer to "Managing Entries from the Command-Line," on page 57, and Red Hat Directory Server Configuration, Command, and File Reference.
  1. Restart the server.
For information on restarting the server, refer to "Starting and Stopping the Directory Server," on page 37.

The retro changelog is created in the directory tree under a special suffix, cn=changelog.

The procedure for enabling the retro changelog plug-in from Directory Server Console is the same as for all Directory Server plug-ins. For information, refer to "Enabling and Disabling Plug-ins from the Server Console," on page 516.

Trimming the Retro Changelog

The entries in the changelog can be automatically removed after a specified period of time. To configure the period of time after which entries are automatically deleted from the changelog, you must set the nsslapd-changelogmaxage configuration attribute in the cn=Retro Changelog Plugin,cn=plugins,cn=config entry.

The nsslapd-changelogmaxage attribute is a single-valued attribute. Its syntax is as follows:

nsslapd-changelogmaxage: Integer timeUnit
 

where Integer represents a number and timeUnit can be one of the following: s for seconds, m for minutes, h for hours, d for days, or w for weeks.

There should not be a space between the Integer and timeUnit variables. The space in the syntax above is intended to show that the attribute value is composed of two variable parts, not just one.

Example of nsslapd-changelogmaxage value:

nsslapd-changelogmaxage: 2d
 

Searching and Modifying the Retro Changelog

The changelog supports search operations. It is optimized for searches that include filters of the form:

(&(changeNumber>=X)(changeNumber<=Y))
 

As a general rule, you should not perform add or modify operations on the retro changelog entries, although you can delete entries to trim the size of the changelog. You will only need to perform a modify operation on the retro changelog is to modify the default access control policy.

Retro Changelog and the Access Control Policy

When the retro changelog is created, the following access control rules apply by default:

You should not grant read access to anonymous users because the changelog entries can contain modifications to sensitive information, such as passwords. Only authenticated applications and users should be allowed to access this information.

To modify the default access control policy which applies to the retro changelog, you can modify the aci attribute of the cn=changelog entry.

Monitoring Replication Status

You can monitor replication status using the Directory Server Console and Red Hat Administration Express. This section explains both these procedures:

Monitoring Replication Status from the Directory Server Console

To view a summary of replication status via the Directory Server Console:

  1. Open the Directory Server Console.
  2. Select the Status tab, and then, in the left navigation tree, select Replication Status.
In the right pane, a table appears that contains information about each of the replication agreements configured for this server.
  1. Click Refresh to update the contents of the tab.
The status information displayed is described in <Z_Online>Table 8-3.
Table 8-3 Directory Server Console - Replication Status  
Table Header
Description
Agreement
Contains the name you provided when you set up the replication agreement.
Replica suffix
Contains the suffix that is replicated.
Supplier
Specifies the supplier server in the agreement.
Consumer
Specifies the consumer server in the agreement.
Number of changes
Indicates the number of changes sent to this replica since the server started.
Last replica update began
Indicates when the most recent replication update started.
Last replica update ended
Indicates when the most recent replication update ended.
Last update message
Provides the status for the most recent replication updates.
Consumer initialization
Provides current status on consumer initialization (in progress or not).
Last consumer initialization update message
Provides status on the last initialization of the consumer.
Last consumer initialization began
States when the initialization of the consumer replica started.
Last consumer initialization ended
States when the initialization of the consumer replica ended.

Monitoring Replication Status from Administration Express

Although the replication status report that you view via the Directory Server Console shows many details, it does not show the progress of the replication. Additionally, because one report is generated per agreement, you need to navigate among the status reports for different agreements.

The template-repl-monitor.pl script, which is explained in detail in the Red Hat Directory Server Configuration, Command, and File Reference, enables you to monitor replication status to a greater extent by providing these functionalities:

The time lag field uses different colors to indicate the degree of time lag. The threshold for each color is configurable.

The script is integrated into the Red Hat Administration Express, enabling you to view the replication status via an HTTP interface. (The Administration Express is an HTML-based version of Red Hat Console that provides quick access to servers running Administration Server.)

To view in-progress status of replication via the Administration Express interface:

  1. Prepare a configuration file following the guidelines provided in the "template-repl-monitor.pl (Monitor replication status)" section of the Red Hat Directory Server Configuration, Command, and File Reference.
  2. Open a web browser window.
  3. In the URL field, enter the Administration Server URL in this format:
http://hostname:admin_port
 
  1. Click Red Hat Administration Express, and, when prompted, log in.
  2. Select a supplier Directory Server instance, and click Replication Status.
This brings up a page for specifying the runtime parameters of the replication-monitoring tool.
  1. In the "Configuration file" field, type the path to the configuration file you created in Step 1, and click OK.
The replication-status page appears; by default, the page gets refreshed every 300 seconds.
Each table shows the status of the changes originated from a supplier replica.
  • Table Header - The table header shows the replica ID of the supplier replica, the replica root, and the maximum Change State Number (CSN) on the supplier. The important thing is to make sure that each supplier LDAP server has its unique replica ID. Multiple replica roots on one LDAP server, however, could share the same replica ID.
  • Table Row - Each row represents a direct or indirect consumer of the supplier (identified in the Table Header).
  • Max CSN - It is the most recent CSN the consumer has replayed that was originated from the supplier (identified in the Table Header).
  • Time Lag - It shows the time difference between the supplier and the consumer's max CSNs for the changes originated from the supplier (identified in the Table Header). A consumer is in sync with its supplier when its time lag is 0.
  • Last Modify Time - It is roughly the time when the consumer's max CSN was replayed.
  • Supplier - This column lists all the suppliers of the consumer.
  • Sent/Skipped - Each supplier lists roughly how many changes originated from the supplier (identified in the Table Header) have been replayed or skipped by the consumer. The numbers are kept in suppliers' memory only. They will be cleared if the supplier is restarted.
  • Update Status - The number is the status code, and the string is the implication of the status code. Watch this column for possible deadlock if all the suppliers complain that they cannot acquire busy replica. It is normal if one of the suppliers is doing an update while the others can't acquire busy replica.

Solving Common Replication Conflicts

Multi-master replication uses a loose consistency replication model. This means that the same entries can be changed on different servers. When replication occurs between the two servers, the conflicting changes need to be resolved. Mostly, resolution occurs automatically, based on the timestamp associated with the change on each server. The most recent change takes precedence.

However, there are some cases where change conflicts require manual intervention in order to reach a resolution. Entries that have a change conflict that cannot be resolved automatically by the replication process contain a conflict marker attribute nsds5ReplConflict. The nsds5ReplConflict attribute is an operational attribute, which makes it simple to search for entries that contain this attribute.

For example, you could use the following ldapsearch command:

ldapsearch -D adminDN -w password -b "dc=example,dc=com" 
"nsds5ReplConflict=*"
 

For performance reasons, if you find that you have many conflicting entries every day, you may want to index the nsds5ReplConflict attribute. For information on indexing, refer to <Z_Online>Chapter 10, "Managing Indexes."

This section contains the procedures for the following conflict resolution procedures:

Solving Naming Conflicts

When two entries are created with the same DN on different servers, the automatic conflict resolution procedure during replication renames the last entry created, including the entry's unique identifier in the DN. Every directory entry includes a unique identifier given by the operational attribute nsuniqueid. When a naming conflict occurs, this unique ID is appended to the non-unique DN.

For example, the entry uid=adamss,ou=people,dc=example,dc=com is created on server A at time t1 and on server B at time t2, where t2 is greater (or later) than t1. After replication, server A and server B both hold the following entries:

The second entry needs to be renamed in such a way that it has a unique DN. The renaming procedure depends on whether the naming attribute is single-valued or multi-valued. Each procedure is described below.

Renaming an Entry with a Multi-Valued Naming Attribute

To rename an entry that has a multi-valued naming attribute:

  1. Rename the entry using a new value for the naming attribute, and keep the old RDN. For example:
prompt> ldapmodify -D adminDN -w password
 
>dn: 
nsuniqueid=66446001-1dd211b2+uid=adamss,dc=example,dc=com

>changetype: modrdn

>newrdn: uid=NewValue

>deleteoldrdn: 0
 
  1. Remove the old RDN value of the naming attribute and the conflict marker attribute. For example:
prompt> ldapmodify -D adminDN -w password
 
>dn: uid=NewValue,dc=example,dc=com

>changetype: modify

>delete: uid

>uid: adamss

>-

>delete: nsds5ReplConflict

>-
 
Note

You cannot delete the unique identifier attribute nsuniqueid.


For more information on the ldapmodify command, refer to "Managing Entries from the Command-Line," on page 57, and Red Hat Directory Server Configuration, Command, and File Reference.

The Console does not support editing of multi-valued RDNs. For example, assume you configured two servers in a multi-master mode, created an entry on each server with the same user ID, and changed the new entries' RDN to the nsuniqueid uid value. If you attempt to modify this entry from the Console, you get the following error: Changes cannot be saved for entries with multi-valued RDNs.

When you open the entry in the advanced mode, you will be able to see that the naming attribute has been set to nsuniqueid uid. However, you cannot change or correct the entry by changing the user ID and RDN values to something different. For example, if jdoe was the user ID and if you want to change it to jdoe1, you cannot do so from the Console. Instead, use the ldapmodify command:

ldapmodify:

ldapmodify

changetype: modify

replace: uid

uid: jdoe
 
ldapmodify

changetype: modrdn

newrdn: uid=jdoe1

deleteoldrdn: 1
 

Renaming an Entry with a Single-Valued Naming Attribute

To rename an entry that has a single-valued naming attribute:

  1. Rename the entry using a different naming attribute, and keep the old RDN. For example:
prompt> ldapmodify -D adminDN -w password
 
>dn: nsuniqueid=66446001-1dd211b2+dc=pubs,dc=example,dc=com

>changetype: modrdn

>newrdn: cn=TempValue

>deleteoldrdn: 0
 
  1. Remove the old RDN value of the naming attribute and the conflict marker attribute. For example:
prompt> ldapmodify -D adminDN -w password
 
>dn: cn=TempValue,dc=example,dc=com

>changetype: modify

>delete: dc

>dc: pubs

>-

>delete: nsds5ReplConflict

>-
 
Note

You cannot delete the unique identifier attribute nsuniqueid.


  1. Rename the entry with the intended attribute-value pair. For example:
prompt> ldapmodify -D adminDN -w password
 
>dn: cn=TempValue,dc=example,dc=com

>changetype: modrdn

>newrdn: dc=NewValue

>deleteoldrdn: 1
 
By setting the value of the deleteoldrdn attribute to 1, you delete the temporary attribute-value pair cn=TempValue. If you want to keep this attribute, you can set the value of the deleteoldrdn attribute to 0.

For more information on the ldapmodify command, refer to "Managing Entries from the Command-Line," on page 57, and Red Hat Directory Server Configuration, Command, and File Reference.

Solving Orphan Entry Conflicts

When a delete operation is replicated and the consumer server finds that the entry to be deleted has child entries, the conflict resolution procedure creates a glue entry to avoid having orphaned entries in the directory.

In the same way, when an add operation is replicated and the consumer server cannot find the parent entry, the conflict resolution procedure creates a glue entry representing the parent so that the new entry is not an orphan entry.

Glue entries are temporary entries that include the object classes glue and extensibleObject. Glue entries can be created in several ways:

In such cases, either you can modify the glue entry to remove the glue object class and the nsds5ReplConflict attribute to keep the entry as a normal entry or you can delete the glue entry and its child entries.
In such cases, you must modify the entry to turn it into a meaningful entry or delete it and all of its child entries.

Solving Potential Interoperability Problems

For reasons of interoperability with applications that rely on attribute uniqueness, such as a mail server, you might need to restrict access to the entries which contain the nsds5ReplConflict attribute. If you do not restrict access to these entries, then the applications requiring one attribute only will pick up both the original entry and the conflict resolution entry containing the nsds5ReplConflict, and operations will fail.

To restrict access, you need to modify the default ACI that grants anonymous read access, using the following command:

ldapmodify -h hostname -D "cn=Directory Manager" -w password
 
> dn: dc=example,dc=com

> changetype: modify

> delete: aci

> aci: (target ="ldap:///dc=example,dc=com")(targetattr 
!="userPassword")(version 3.0;acl "Anonymous read-search 
access";allow (read, search, compare)(userdn = 
"ldap:///anyone");)

> -

> add: aci
 
> aci: 
(target="ldap:///dc=example,dc=com")(targetattr!="userPassword"
) (targetfilter="(!(nsds5ReplConflict=*))")(version 3.0;acl 
"Anonymous read-search access";allow (read, search, compare) 
(userdn="ldap:///anyone");)
 
> -
 

The new ACI filters out all entries that contain the nsds5ReplConflict attribute from search results.

For more information on the ldapmodify command, refer to "Managing Entries from the Command-Line," on page 57, and Red Hat Directory Server Configuration, Command, and File Reference.

Troubleshooting Replication-Related Problems

This section covers the following:

Interpreting Error Messages and Symptoms

This section lists some error messages, explains possible causes, and offers remedies.

It is possible to get more debugging information for replication by setting the error log level to 8192, which is replication debugging. For details on error log level, check the Red Hat Directory Server Configuration, Command, and File Reference.

To change the error log level to 8192, run the following ldapmodify command:

dn: cn=config

changetype: modify

replace: nsslapd-errorlog-level

nsslapd-errorlog-level: 8192
 

Because log level is additive, running the above command will result in excessive messages in the error log. So, use it judiciously.

To turn off replication debugging log, set the same attribute to 0.

Error Message:

agmt=%s (%s:%d) Replica has a different generation ID than the local data

Reason: The consumer specified at the beginning of this message has not been (successfully) initialized yet, or it was initialized from a different root supplier.
Impact: The local supplier will not replicate any data to the consumer.
Remedy: Ignore this message if it occurs before the consumer is initialized. Otherwise, reinitialize the consumer if the message is persistent. In a multi-master environment, all the servers should be initialized only once from a root supplier, directly or indirectly. For example, M1 initializes M2 and M4, M2 then initializes M3, and so on. The important thing to note is that M2 must not start initializing M3 until M2's own initialization is done (check the total update status from the M1's Console or M1 or M2's error log). Also, M2 should not initialize M1 back.
Error Message:

Warning: data for replica %s was reloaded, and it no longer matches the data in the changelog. Recreating the changelog file. This could affect replication with replica's consumers, in which case the consumers should be reinitialized.

Reason: This message may appear only when a supplier is restarted. It indicates that the supplier was unable to write the changelog or did not flush out its RUV at its last shutdown. The former is usually because of a disk-space problem, and the latter because a server crashed or was ungracefully shut down.
Impact: The server will not be able to send the changes to a consumer if the consumer's maxcsn no longer exists in the server's changelog.
Remedy: Check the disk space and the possible core file (under the server's logs directory). If this is a single-master replication, reinitialize the consumers. Otherwise, if the server later complains that it can't locate some CSN for a consumer, see if the consumer can get the CSN from other suppliers. If not, reinitialize the consumer.
Error Message:

agmt=%s(%s:%d): Can't locate CSN %s in the changelog (DB rc=%d). The consumer may need to be reinitialized.

Reason: Most likely the changelog was recreated because of the disk is full or the server ungracefully shutdown.
Impact: The local server will not be able to send any more change to that consumer until the consumer is reinitialized or gets the CSN from other suppliers.
Remedy: If this is a single-master replication, reinitialize the consumers. Otherwise, see if the consumer can get the CSN from other suppliers. If not, reinitialize the consumer.
Error Message:

Too much time skew

Reason: The system clocks on the host machines are extremely out of sync.
Impact: The system clock is used to generate a part of the CSN. In order to reflect the change sequence among multiple suppliers, suppliers would forward-adjust their local clocks based on the remote clocks of the other suppliers. Because the adjustment is limited to a certain amount, any difference that exceeds the permitted limit will cause the replication session to be aborted.
Remedy: Synchronize the system clocks on the Directory Server host machines. If applicable, run the network time protocol (ntp) daemon on those hosts.
Error Message:

agmt=%s(%s:%d): Warning: Unable to send endReplication extended operation (%s)

Reason: The consumer is not responding.
Impact: If the consumer recovers without being restarted, there is a chance that the replica on the consumer will be locked forever if it did not receive the release lock message from the supplier.
Remedy: Watch if the consumer can receive any new change from any of its suppliers, or start the replication monitor, and see if all the suppliers of this consumer warn that the replica is busy. If the replica appears to be locked forever and no supplier can get in, restart the consumer.
Symptom:

Changelog is getting too big.

Reason: Either changelog purge is turned off, which is the default setting, or changelog purge is turned on, but some consumers are way behind the supplier.
Remedy: By default changelog purge is turned off. To turn it on from the command-line, run ldapmodify as follows:
dn: cn=changelog5,cn=config
changetype: modify
add: nsslapd-changelogmaxage
nsslapd-changelogmaxage: 1d

where 1d means 1 day. Other valid time units are s(econds), m(inutes), h(ours), and w(eeks). A value of 0 turns off the purge.
With changelog purge turned on, a purge thread that wakes up every five minutes will remove a change if its age is greater than the value of nsslapd-changelogmaxage and if it has been replayed to all the direct consumers of this supplier (supplier or hub).
If it appears that the changelog is not purged when the purge threshold is reached, check the maximum time lag from the replication monitor among all the consumers. Irrespective of what the purge threshold is, no change will be purged before it is replayed by all the consumers.
Symptom:

The Replication Monitor is not responding. (For information on Replication Monitor, see "Monitoring Replication Status," on page 366.)

Reason: The SSL port is specified in some replication agreement, but the certificate database is not specified or not accessible by the Replication Monitor. If there is no SSL port problem, one of the servers in the replication topology might hang.
Remedy: Map the SSL port to a non-SSL port in the configuration file of the Replication Monitor. For example, if 636 is the SSL port and 389 is the non-SSL port, add the following line in the [connection] section:
*:636=389:*:password
Symptom:

In the Replication Monitor, some consumers show just the header of the table. (For information on Replication Monitor, see "Monitoring Replication Status," on page 366.)

Reason: No change has originated from the corresponding suppliers. In this case, the MaxCSN: in the header part should be "None".
Remedy: There is nothing wrong if there is no change originated from a supplier.

Useful Tools

The template-cl-dump.pl script, which is explained in detail in the Red Hat Directory Server Configuration, Command, and File Reference, enables you to troubleshoot replication-related problems. Depending on the usage options, the script can selectively dump a particular replica:




Previous
Contents
Index
Next

© 2001 Sun Microsystems, Inc. Used by permission. © 2005 Red Hat, Inc. All rights reserved.
Read the Full Copyright and Third-Party Acknowledgments.

last updated May 20, 2005