Previous     Contents     Index     DocHome     Next     
iPlanet Directory Server Administrator's Guide



Chapter 8   Managing Replication


Replication 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 iPlanet Directory Server Deployment Guide.



Replication Overview


Replication is the mechanism by which directory data is automatically copied from one Directory Server to another. Using replication, you can copy entire directory trees or subtrees between servers. Updates of any kind—entry additions, modifications, or even deletions—are automatically mirrored to other Directory Servers using replication.


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 refer 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 iPlanet Directory Server 5.0, 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 iPlanet Directory Server allowed consumer-initiated replication where you could configure consumer servers to pull data from a supplier server.


Change Log

Every supplier server maintains a change log. A change log is a record that describes the modifications that have occurred on a replica. The supplier server then replays these modifications on the replicas stored on consumer servers, or on other masters 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 change log.

In iPlanet Directory Server 5.0, the format of the change log has changed. It is now intended only for internal use by the server. If you have applications that need to read the change log, you can use the Retro Change log plug-in for backward compatibility. For more information, refer to "Using the Retro Change Log Plug-In".


Unit of Replication

In iPlanet Directory Server 5.0, 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 iPlanet 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".


Replication Identity

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

  • You must create the entry on every server that receives updates from another server (a hub supplier or a dedicated consumer).

  • When you configure a replica that receives updates from another server, you must specify this entry as the one authorized to perform replication updates.

  • On the supplier server, when you configure the replication agreement, you must specify the DN of this entry.

  • This entry must not be part of the replicated database

  • This entry bypasses all access control rules defined on the consumer server.


    Note In the Directory Server Console, this entry is referred to as the supplier bind DN. This can be misleading because the entry does not exist on the supplier server but on the consumer server.


For more information on creating the Replication Manager entry, refer to "Creating the Bind DN for Suppliers".


Replication Agreement

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

  • The database to replicate

  • The consumer server to which the data is pushed

  • The times during which replication can occur

  • The DN and credentials that the supplier server must use to bind (called the Replication Manager, or supplier bind DN)

  • How the connection is secured (SSL, client authentication)


Compatibility with Earlier Versions of Directory Server

The replication mechanism in iPlanet Directory Server 5.0 is different from the mechanism used in earlier versions of Directory Server. Compatibility is provided in the following manner:

  • Through the Legacy Replication Plug-in

  • Through the Retro Changelog Plug-in

The legacy replication plug-in makes Directory Server 5.0 behave as a 4.x directory server in a consumer role. For information on how to implement legacy replication using this plug-in, refer to "Replication with Earlier Releases".

The retro change log plug-in can be used when you want a Directory Server 5.0 supplier to maintain a 4.x style change log. This is sometimes necessary for applications that have a dependency on the Directory Server 4.x change log format, because they read information from the change log. For more information on the retro change log plug-in, refer to "Using the Retro Change Log Plug-In".



Replication Scenarios


This section describes the most commonly used replication scenarios:

  • Single master replication

  • Multi-master replication

  • Cascading replication

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, refer to iPlanet Directory Server Deployment Guide.



Single-Master Replication

In the most simple replication scenarios, the master copy of directory data is held in a single read-write replica on one server. The server also maintains a change log for this replica. You can have as many read-only replicas as you like. Such scenarios are called single-master configurations. Figure 8-1 shows an example of single-master replication.

Figure 8-1   

Single-Master Replication

The ou=people,dc=siroe,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".


Multi-Master Replication

iPlanet Directory Server 5.0 also supports complex replication scenarios in which the same subtree can be mastered on two servers. This subtree is held in a read-write replica on each server. This means that each server maintains a change log for the 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 both suppliers. The consumers also have referrals defined for both suppliers which are used to forward any update requests that they receive. Such scenarios are called multi-master configurations.

Figure 8-2 shows an example of multi-master replication scenario.

Figure 8-2   

Multi-Master Replication

Multi-master configurations have the following advantages:

  • Automatic write failover when one master/supplier is inaccessible

  • Updates are made on the local supplier in a geographically distributed environment


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


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


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 change log. It receives updates from the supplier server that holds the master copy of the data, and in turn supplies those updates to the consumer.

Figure 8-3 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-3    Cascading Replication

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


Note You can combine multi-master and cascading replication. For example, in the mult-master scenario illustrated in Figure 8-2, Server C and Server D could be hub suppliers that would replicated to any number of consumer servers.




Configuring Single-Master Replication


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


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".

  2. 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.

    1. In the Directory Server Console, click 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 password expiration, or intend to do so in future, disable the password expiration policy on this attribute, by adding the passwordExpirationTime attribute with a value of 20380119031407Z.


      Note This entry must not be part of the replicated database.


  3. Specify the replication parameters required for a read-only replica.

    1. In the Directory Server Console, click 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.

    3. Check the Enable Replica checkbox.

    4. In the Replica Role section, select the Dedicated Consumer radio button.

    5. In the Common Settings section, specify a Replica ID (an integer between 1 and 254 inclusive).

      You must specify the same replica ID as for the read-write replica that supplies updates to this replica. The replica ID must be unique for a given suffix.

    6. Specify a purge delay.

      This option indicates how often the state information stored in the replicated entries is purged.

    7. In the Replica Update Settings section, specify the bind DN that the supplier will use to bind to the replica.

      This bind DN should correspond to the entry created in Step 2. Note that the bind DN corresponds to a privileged user, because it is not subject to access control.

    8. 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://servername: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://servername:port.

  4. Click Save to save the replication parameters for the replica.

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, click the Configuration tab.

    2. In the navigation tree, highlight the Replication node.

    3. In the right-hand side of the window, click the Supplier Settings tab.

    4. Check the Enable Change Log checkbox.

      This activates all of the fields in the pane below that were previously greyed out.

    5. Specify a change log by clicking the Use Default button, or click the Browse button to display a file selector.

    6. Set the change log parameters (number and age).

      You must clear the unlimited checkboxes if you want to specify different values.

    7. Click Save to save the supplier settings.

  2. Specify the replication parameters 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.

    2. Check the Enable Replica checkbox.

    3. In the Replica Role section, select the Single Master radio button.

    4. 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. Make sure you specify an ID that is different from the IDs used for read-write replicas on this server and on other servers.

    5. Specify a purge delay.

      This option indicates how often the state information stored in the replicated entries is purged.

    6. Click Save to save the replication parameters for the database.

  3. Create a replication agreement.

    You must create one replication agreement for each read-only replica. For example, in the case illustrated in Figure 8-1, Server A holds two replication agreements, one for Server B, and one for Server C.

    1. In the navigation tree on the Configuration tab, right-click the database to replicate, and select New Replication Agreement.

      Alternatively, highlight the database and select New Replication Agreement from the Object menu. This will start the Replication Agreement Wizard.

    2. 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".

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



Configuring Multiple-Master Replication

In a multi-master replication configuration, two suppliers can accept updates, synchronize with each other, and update all consumers. The consumers can send referrals for updates to both masters.

To set up multi-master replication such as the configuration shown in Figure 8-2, between two suppliers Server A and Server B that each hold a read-write replica, and two consumers Server C and Server D that each hold a read-only replica, you must perform the following tasks:


Configuring the Read-Only Replicas on the Consumer Servers

Perform these steps on each consumer server:

  1. Create the database for the read-only replica, if it does not exist.

    For instructions, refer to "Creating Suffixes".

  2. 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.

    1. In the Directory Server Console, click 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 password expiration, or intend to do so in future, disable the password expiration policy on this attribute, by adding the passwordExpirationTime attribute with a value of 20380119031407Z.


      Note This entry must not be part of the replicated database.


  3. Specify the replication parameters required for a read-only replica.

    1. In the Directory Server Console, click 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.

    3. Check the Enable Replica checkbox.

    4. In the Replica Role section, select the Dedicated Consumer radio button.

    5. In the Common Settings section, specify a Replica ID (an integer between 1 and 254 inclusive).

      You must specify the same replica ID as for the read-write replica that supplies updates to this replica. The replica ID must be unique for a given suffix.

    6. Specify a purge delay.

      This option indicates how often the state information stored in the replicated entries is purged.

    7. In the Replica Update Settings section, specify the bind DN that the supplier will use to bind to the replica.

      This bind DN should correspond to the entry created in Step 2. Note that the bind DN corresponds to a privileged user, because it is not subject to access control.

    8. 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://servername: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://servername:port.

  4. Click Save to save the replication parameters for the replica.

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:

  1. On Server A and Server B, specify the supplier settings for each server.

    1. In the Directory Server Console, click the Configuration tab.

    2. In the navigation tree, highlight the Replication node.

    3. In the right-hand side of the window, click the Supplier Settings tab.

    4. Check the Enable Change Log checkbox.

      This activates all of the fields in the pane below that were previously greyed out.

    5. Specify a change log by clicking the Use Default button, or click the Browse button to display a file selector.

    6. Set the change log parameters (number and age).

      You must clear the unlimited checkboxes if you want to specify different values.

    7. Click Save to save the supplier settings.

  2. Create the entry corresponding to the supplier bind DN, if it does not exist. This entry is necessary so that the two masters can replicate changes to one another.

    1. In the Directory Server Console, click 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 password expiration, or intend to do so in future, disable the password expiration policy on this attribute, by adding the passwordExpirationTime attribute with a value of 20380119031407Z.


      Note This entry must not be part of the replicated database.


  3. On Server A and Server B, specify the replication parameters for the multi-mastered 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.

    2. Check the Enable Replica checkbox.

    3. In the Replica Role section, select the Multiple Master radio button.

    4. 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. Make sure you specify an ID that is different from the IDs used for read-write replicas on this server and on other servers.

    5. Specify a purge delay.

      This option indicates how often the state information stored in the replicated entries is purged.

    6. In the Replica Update Settings section, specify the bind DN that the supplier will use to bind to the replica.

      This bind DN should correspond to the entry created in Step 2. Note that the bind DN corresponds to a privileged user, because it is not subject to access control.

    7. Specify the supplier server to which you want to refer updates (the other master 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://.

    8. Click Save to save the replication parameters for the database.

  4. On Server A, set up the following replication agreements:

    • One with supplier Server B, where B is configured as a consumer for the replica.

    • One for each consumer, Server C and Server D.

    • In the navigation tree on the Configuration tab, right-click the database to replicate, and select New Replication Agreement.

      Alternatively, 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 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", and "Initializing Consumers".

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

  5. On Server B, set up the following replication agreements:

    • One with supplier Server A, where 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, Server C and Server D.


      Note This means that Server A and Server B have mutual replication agreements so 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

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

  1. Ensure one master has the complete set of data to replicate. Use this master to initialize the replica on the other master in the multi-master replication set.

  2. Initialize the replicas on the consumer servers from any one of the two masters.

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



Configuring Cascading Replication


This section provides information on setting up cascading replication.


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, click the Configuration tab.

    2. In the navigation tree, highlight the Replication node.

    3. In the right-hand side of the window, click the Supplier Settings tab.

    4. Check the Enable Change Log checkbox.

      This activates all of the fields in the pane below that were previously greyed out.

    5. Specify a change log by clicking the Use Default button, or click the Browse button to display a file selector.

    6. Set the change log parameters (number and age).

      You must clear the unlimited checkboxes if you want to specify different values.

    7. Click Save to save the supplier settings.

  2. Specify the required replication parameters.

    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.

    2. Check the Enable Replica checkbox.

    3. In the Replica Role section, select the Single Master radio button.

    4. 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. Make sure you specify an ID that is different from the IDs used for read-write replicas on this server and on other servers.

    5. Specify a purge delay.

      This option indicates how often the state information stored in the replicated entries is purged.

    6. Click Save to save the replication parameters for the database.


Configuring the Read-Only Replica on the Hub Supplier

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

  1. Create the database for the replica, if it does not exist.

    For instructions, refer to "Creating Suffixes".

  2. 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.

    1. In the Directory Server Console, click 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 password expiration, or intend to do so in future, disable the password expiration policy on this attribute, by adding the passwordExpirationTime attribute with a value of 20380119031407Z.


      Note This entry must not be part of the replicated database.


  3. Specify the required replication parameters.

    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.

    2. Check the Enable Replica checkbox.

    3. In the Replica Role section, select the Hub radio button.

    4. In the Common Settings section, specify a Replica ID (an integer between 1 and 254 inclusive).

      You must specify the same replica ID as for the read-write replica that supplies updates to this replica. The replica ID must be unique for a given suffix.

    5. Specify a purge delay.

      This option indicates how often the state information stored in the replicated entries is purged.

    6. In the Replica Update Settings section, specify the bind DN that the supplier will use to bind to the replica.

      This bind DN should correspond to the entry created in Step 2. Note that the bind DN corresponds to a privileged user, because it is not subject to access control.

    7. 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://servername: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://servername:port.

    8. Click Save to save the replication parameters for the database.


Configuring the Read-Only Replica on the Consumer Server

  1. On the consumer server, create the database for the replica if it does not exist.

    For instructions, refer to "Creating Suffixes".

  2. On the consumer server, create the entry corresponding to the supplier bind DN, if it does not exist.

  3. On the consumer server, specify the replication parameters for the read-only replica.

    1. In the Directory Server Console, click 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.

    3. Check the Enable Replica checkbox.

    4. In the Replica Role section, select the Dedicated Consumer radio button.

    5. In the Common Settings section, specify a Replica ID (an integer between 1 and 254 inclusive).

      You must specify the same replica ID as for the read-write replica that supplies updates to this replica. The replica ID must be unique for a given suffix.

    6. Specify a purge delay.

      This option indicates how often the state information stored in the replicated entries is purged.

    7. In the Replica Update Settings section, specify the bind DN that the supplier will use to bind to the replica.

      This bind DN should correspond to the entry created in Step 2. Note that the bind DN corresponds to a privileged user, because it is not subject to access control.

    8. 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 master. Therefore, you should set a referral to the original master to replace the automatically generated referral.

  4. On the supplier server, set up the replication agreement between this server and the hub supplier.

    1. In the navigation tree on the Configuration tab, right-click the database to replicate, and select New Replication Agreement.

      Alternatively, highlight the database and select New Replication Agreement from the Object menu. This will start the Replication Agreement Wizard.

    2. 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".

  5. 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 between 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.


Initializing the Replicas

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".



Configuration Tips


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 entry

    • Specify the replica settings for a read-only replica

  2. On all hub suppliers:

    • Create the replica databases

    • Create the Replication Manager entry

    • Specify the supplier settings for replication (includes change log configuration)

    • Specify the replica settings for a read-write replica

  3. On all suppliers:

    • Create the replica databases

    • Specify the supplier settings for replication (includes change log 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.

  5. 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.




Detailed Procedures

This section contains a description of the tasks you need to perform to configure replication.


Creating the Bind DN for Suppliers

A critical part of setting up replication is to create the 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:

  • It must be unique

  • It must correspond to an actual entry on the consumer server

  • It must not be part of the replicated database

  • It must be defined in the replication agreement on the supplier server

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 suppliers would use to bind to the consumer to perform replication operations.

To create the supplier bind entry:

  1. 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.

  2. Specify a userPassword attribute-value pair.

  3. If you have enabled password expiration, or intend to do so in future, disable the password expiration policy on this attribute, by adding the passwordExpirationTime attribute with a value of 20380119031407Z.

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 parameters.

To configure supplier settings:

  1. In the Directory Server Console, click the Configuration tab.

    For information on starting the Directory Server Console, "Using the Directory Server Console".

  2. In the left navigation tree, highlight the Replication node.

  3. In the right navigation window, click the Supplier Settings tab.

  4. Check the Enable Change Log checkbox.

    This activates all of the fields in the pane below that were previously grayed out.

  5. Specify a change log by clicking the Use Default button, or click Browse to display a file selector.

  6. Set the change log number and age parameters.

    You must clear the unlimited checkboxes to specify different values.

  7. Click Save to save the supplier settings.


Configuring a Read-Write Replica

For each read-write replica, you must specify the appropriate replication parameters.

To configure a read-write replica:

  1. In the Directory Server Console, click the Configuration tab.

    For information on starting the Directory Server Console, "Using the Directory Server Console".

  2. In the left navigation tree, expand the Replication folder and highlight the database to replicate.

    The Replication tab is displayed in the right navigation window.

  3. Check the Enable Replica checkbox.

  4. In the Replica Role section, select the Single Master or Multi-Master radio button.

  5. 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. Make sure you specify an ID that is different from the IDs used for read-write replicas on this server and on other servers.

  6. Specify a purge delay.

    This option indicates how often the state information stored in the replicated entries is purged.

  7. Click Save to save the replication parameters for the database.


Configuring a Read-Only Replica

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

  1. In the Directory Server Console, click the Configuration tab.

    For information on starting the Directory Server Console, "Using the Directory Server Console".

  2. In the left navigation tree, expand the Replication folder, and highlight the replica database.

    The Replica Settings tab is displayed in the right navigation window.

  3. Check the Enable Replica checkbox.

  4. In the Replica Role section, select the Dedicated Consumer radio button.

  5. In the Common Settings section, specify a Replica ID (an integer between 1 and 254 inclusive).

    You must specify the same replica ID as for the read-write replica that supplies updates to this replica. The replica ID must be unique for a given suffix.

  6. Specify a purge delay.

    This option indicates how often the state information stored in the replicated entries is purged.

  7. In the Replica Update Settings section, specify the bind DN that the supplier will use to bind to the replica.

    This bind DN should correspond to the entry created in Step 2. Note that the bind DN corresponds to a privileged user, because it is not subject to access control.

  8. 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://servername: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://servername:port.

    In the case of cascading replication, referrals are automatically sent to the hub supplier, which in turn refers the request to the original master. Therefore, you should set a referral to the original master to replace the automatically generated referral.

  9. Click Save to save the replication parameters for the replica.


Configuring a Hub Supplier

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

  1. On the Directory Server Console, click the Configuration tab.

    For information on starting the Directory Server Console, "Using the Directory Server Console".

  2. In the left navigation tree, expand the Replication folder and highlight the database to replicate.

    The Replica Settings tab is displayed in the right navigation window.

  3. Check the Enable Replica checkbox.

  4. In the Replica Role section, select the Hub radio button.

  5. In the Common Settings section, specify a Replica ID (an integer between 1 and 254 inclusive).

    You must specify the same replica ID as for the read-write replica that supplies updates to this replica. The replica ID must be unique for a given suffix.

  6. Specify a purge delay.

    This option indicates how often the state information stored in the replicated entries is purged.

  7. In the Replica Update Settings section, specify the bind DN that the supplier will use to bind to the replica.

    This bind DN should correspond to the entry created in Step 2. Note that the bind DN corresponds to a privileged user, because it is not subject to access control.

  8. 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 to either 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.

  9. Click Save to save the replication parameters 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:

To create a replication agreement:

  1. On the Directory Server Console, click the Configuration tab.

    For information on starting the Directory Server Console, "Using the Directory Server Console".

  2. In the navigation tree, expand the Replication folder, right-click the database to replicate, and select New Replication Agreement.

    Alternatively, highlight the database and select New Replication Agreement from the Object menu. This will start the Replication Agreement Wizard.

  3. 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. An icon representing the replication agreement is displayed under the database icon.



Removing the Change Log


Note If you remove the change log, you will need to reinitialize your consumer servers.


You can remove the change log using the Directory Server Console. On the supplier server:

  1. On 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 Change Log checkbox.

    This deletes the change log.

  4. Click Save.

  5. Restart the Directory Server.

  6. Reinitialize your consumers.

    See "Initializing Consumers" for information.

You can actually remove an old change log without stopping to log changes by modifying the change log location. When you do this, a new change log is created in the directory you specify, and the old change log is deleted.



Initializing Consumers


There are two ways to initialize a consumer:

This section first describes consumer initialization in detail and then provides instructions on both consumer creation methods.


When to Initialize a Consumer

After you have created a replication agreement, you must initialize the consumer. That is, you must physically copy directory data from the supplier server to the consumer server so that future changes can be replayed to consumer servers.

Consumer initialization involves copying a directory subtree 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 use one of the following methods to initialize a consumer:

  • Online consumer creation

  • Manual consumer creation

Online consumer creation is an effective method of initializing a small number of consumers. Each replica is initialized in sequence; therefore, this method is not adapted for initializing a large number of replicas.

Online consumer creation is the method used when you initialize the consumer while configuring the replication agreement on the supplier server.

Manual consumer creation is an effective method of initializing a large number of consumers from a single LDIF file.

The process that you use to initialize or reinitialize a consumer differs depending on the type of consumer creation you use. See "Online Consumer Creation" or "Manual Consumer Creation" for more information.


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



Online Consumer Creation

Online consumer creation 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 that manual consumer creation is a more appropriate approach (refer to "Manual Consumer Creation" for more information).


How to Use Online Consumer Creation

This method assumes that you have already created a replication agreement, but that you have not yet initialized the consumer identified in the agreement. For details on creating replication agreements, see "Creating a Replication Agreement".

  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.

  3. Click Yes in the confirmation box.

Online consumer creation begins immediately. You can check the status of the online consumer creation on the Summary tab in the Status box. If online consumer creation 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 creation finishes, the status changes to reflect this.

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


Manual Consumer Creation

Manual consumer creation is the fastest method of consumer initialization for sites that are replicating very large numbers of entries. However, the manual process is more complicated than the online creation process.

You should use the manual process whenever you find that the online process is inappropriate due to performance concerns.

To manually initialize or reinitialize a server:

  1. Create a replication agreement.

    See "Creating a Replication Agreement".

  2. Export the replica to an LDIF file.

    See "Exporting a Replica to LDIF".

  3. Import the LDIF file to the consumer server.

    See "Importing the LDIF File to the Consumer Server" for instructions.


Exporting a Replica to LDIF

You can convert the replica to LDIF:

  • When you create a replication agreement by selecting "Create consumer initialization file" in the Initialize Consumer dialog box of the Replication Wizard.

  • 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.

  • From the command line, by using the export command as described in "Exporting to LDIF From the Command Line".


Importing the LDIF File to the Consumer Server

Create the read-only replica on the consumer server from the LDIF file by using either the import features in the Directory Server Console, or the ldif2db scripts. These available methods are described in "Importing From the Command Line".

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



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 by through replication immediately. In the case of a master in a multi-master environment, the directory information needs to be updated by the other master 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.

Note that if you have configured replication agreements to always keep the supplier server and the consumer server in sync, 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.


Several methods are available for ensuring that directory information will be synchronized immediately when a server comes back online:

  • From the Directory Server Console on the supplier server that holds the reference copy of the directory information.

  • By using a customizable script on the server that needs to be updated.


Forcing Replication Updates from the Console

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

  1. On 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 Code Example 8-1.

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

Code Example 8-1    Replicate_Now Script
#!/bin/sh
SUP_HOST=supplier_hostname
SUP_PORT=supplier_portnumber
SUP_MGRDN=supplier_directoryManager
SUP_MGRPW=supplier_directoryManager_passwd
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 variable parameters 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_passwd  

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 information on the ldapmodify command, refer to iPlanet 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:

  • Configure both your supplier and consumer servers to use SSL.

  • Configure your consumer server to recognize your supplier server's certificate as the supplier DN. You do this only if you want to use SSL client authentication rather than simple authentication.

These procedures are described in Chapter 11, "Managing SSL."


Note Replication over SSL will fail in the following cases:

  • If the supplier's certificate is a self-signed certificate

  • If the supplier's certificate is an SSL server-only certificate, that is it can't act as a client during an SSL handshake.


When your servers are configured to use SSL, the following methods are available to ensure replication operations occur over SSL connections:

  • Using the Replication Wizard, when you set up the replication agreement between two Directory Servers.

  • From the Directory Server Console, at any time after the initial replication agreement was configured.


Configuring Replication Over SSL From the Replication Wizard

  1. On 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.

  3. Go through each step in the Replication Agreement Wizard until you reach the Source and Destination window.

  4. In the Connection section, check "Using Encrypted SSL Connnection".

  5. 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.

  6. Click Next, and proceed with the replication setup.


Configuring Replication Over SSL From the Console

  1. On the Directory Server Console of the supplier server, click the Configuration tab, expand the Replication folder and select the replication agreement that you want to modify to enable replication over SSL.

  2. Click the Connection tab in the right navigation window.

    This displays the replication connection parameters.

  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.

  4. Click Save.



Replication with Earlier Releases

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

  • Directory Server 5.0 is defined as a consumer in the replication agreement.

  • The legacy suppliers can be Directory Server 4.0, 4.1, 4.11, and 4.12.

The following restrictions apply:

  • A legacy Directory Server and a 5.0 Directory Server cannot update the same replica. However, a 5.0 Directory Server can have different replicas, where one is supplied by a legacy Directory Server, and the other is supplied by a 5.0 Directory Server.

  • Directory Server 5.0 cannot be a supplier for other replicas.

The main advantage of being able to use a Directory Server 5.0 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 iPlanet Directory Server Installation Guide.


Configuring Directory Server 5.0 as a Legacy Consumer

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

  1. On the Directory Server Console, click the Configuration tab.

    For information on starting the Directory Server Console, "Using the Directory Server Console".

  2. On the Configuration tab, select the Replication node and click the Legacy Consumer Settings tab in the right pane.

  3. Check the Enable Legacy Consumer checkbox.

    This activates the fields in the Authentication box.

  4. 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.

  5. Click Save.

    You must now configure legacy consumer settings for each replica that will receive updates from a legacy supplier.

  6. In the navigation tree, expand the Replication node and select a replica that will receive updates from the legacy supplier.

  7. On the Replication tab in the right pane, check the Enable Replication and the Enable Legacy Consumer 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.

  8. Click Save.

    Repeat Step 7 and Step 8 for each read-only replica that will receive updates from a legacy supplier.

    To complete your legacy replication setup, you must now configure the legacy supplier to replicate to the 5.0 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 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 5.0 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 Change Log Plug-In

The retro change log plug-in enables you to configure iPlanet Directory Server 5.0 to maintain a change log that is compatible with the change log implemented in Directory Server 4.0, 4.1, 4.11, 4.12, and 4.13.

Maintaining a retro change log is important in deployments where iPlanet Directory Server 5.0 coexists with iPlanet Meta Directory. You might also need to maintain a retro change log if you have directory clients that depend on a Directory Server 4.x style change log.

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

When you have configured iPlanet Directory Server 5.0 to maintain a retro change log, this change log is stored in a separate database with the suffix cn=changelog.

The change log consists of a single level of entries. Each entry in the change log has the object class changeLogEntry, and can include the attributes listed in Table 8-2.


Table 8-2    Attributes of a Retro Change Log Entry

Attribute

Definition

changeNumber  

This single-valued atttribute 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. The 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 explains how to perform the following procedures:


Enabling the Retro Change Log Plug-In

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

To enable the retro change log 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

  2. Use the ldapmodify command to import the LDIF file into the directory.

    For detailed information on the ldapmodify command, refer to iPlanet Directory Server Configuration, Command, and File Reference.

  3. Restart the server.

    For information on restarting the server, refer to "Starting and Stopping the Directory Server".

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

The procedure for enabling the retro change log 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 439.


Trimming the Retro Change Log

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

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

changelogMaximumAge: 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.


Note There should be no 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 changelogMaximumAge value:

changelogMaximumAge: 2d


Searching and Modifying the Retro Change Log

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

  • Read, search and compare rights are granted to all authenticated users (userdn=anyone, not to be confused with anonymous access where userdn=all) to the change log top entry cn=changelog.

  • Write and delete access are not granted, except implicitly to the Directory Manager.

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

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

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

You should not perform add or modify operations on change log entries, although you can delete entries. However, if you want to modify the default access control policy for the change log database, you can modify the aci attribute of the cn=changelog entry.



Monitoring Replication Status


You can monitor replication status using the Directory Server Console.

To view a summary of replication status:

  1. On the Directory Server Console, select the Status tab and then select Replication Status in the left navigation tree.

    In the right pane, a table appears that contains information about each of the replication agreements configured for this server.

  2. Click Refresh to update the contents of the tab.

The status information displayed is described in Table 8-3.


Table 8-3    Directory Server Console - Status Tab

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.  



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. Namely:

  • When two entries are created on different servers with the same DN.

    The procedure for solving this type of conflict is described in "Naming Conflicts".

  • When an entry is deleted on one server, while it has child entries on the other server.

    The procedure for solving this type of conflict is described in "Deleted Entries with Child Entries".

Entries that have a change conflict that cannot be resolved automatically by the replication process include a conflict marker attribute nsds5ReplConflict. The nsdsReplConflict attribute is an operational attribute. This makes it simple to search for entries that contain this attribute.

For example, you could use the following ldapsearch command:

prompt% ldapsearch -D adminDN -w passwd -b "dc=siroe,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 Chapter 10, "Managing Indexes."


Naming Conflicts

When two entries are created with the same DN on different servers, during replication, the automatic conflict resolution procedure renames the last entry created by 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=siroe,dc=com is created on Server A at time t1, and on Server B at time t2, and t2 is greater (or later) than t1. After replication, Server A and Server B both hold the following entries:

  • uid=adamss,ou=people,dc=siroe,dc=com (created at time t1)

  • nsuniqueid=66446001-1dd211b2+uid=adamss,dc=siroe,dc=com (created at time t2)

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 passwd

    >dn: nsuniqueid=66446001-1dd211b2+uid=adamss,dc=Siroe,dc=com
    >changetype: modrdn
    >newrdn: uid=NewValue
    >deleteoldrdn: 0

  2. Remove the old RDN value of the naming attribute, and the conflict marker attribute. For example:

    prompt% ldapmodify -D adminDN -w passwd

    >dn: uid=NewValue,dc=Siroe,dc=com
    >changetype: modify
    >delete: uid
    >uid: adamss
    >-
    >delete: nsds5ReplConflict
    >-


    Note You cannot delete the unique identifier attribute nsuniqueid.



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 passwd

    >dn: nsuniqueid=66446001-1dd211b2+dc=pubs,dc=Siroe,dc=com
    >changetype: modrdn
    >newrdn: cn=TempValue
    >deleteoldrdn: 0

  2. Remove the old RDN value of the naming attribute, and the conflict marker attribute. For example:

    prompt% ldapmodify -D adminDN -w passwd

    >dn: cn=TempValue,dc=Siroe,dc=com
    >changetype: modify
    >delete: dc
    >dc: pubs
    >-
    >delete: nsds5ReplConflict
    >-


    Note You cannot delete the unique identifier attribute nsuniqueid.


  3. Rename the entry with the intended attribute-value pair. For example:

    prompt% ldapmodify -D adminDN -w passwd

    >dn: cn=TempValue,dc=Siroe,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.


Deleted Entries with Child Entries

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:

  • If the conflict resolution procedure finds a deleted entry with a matching unique identifier, the glue entry is a resurrection of that entry, with the addition of the glue object class, and the nsds5ReplConflict attribute.

    In such cases, you can either 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.

  • The server creates a minimalistic entry with the glue and extensibleObject object classes.

    In such cases, you must modify the entry to turn it into a meaningful entry, or delete it and all of its child entries.


Controlling Access to Conflicting Entries

For reasons of interoperability with applications that rely on attribute uniqueness such as a mail server, you might need to restrict access to entries which contain the nsds5ReplConflict attribute.

This can be done by modifying the default ACI that grants anonymous read access, using the following command:

ldapmodify -h hostname -D "cn=Directory Manager" -w passwd

> dn: dc=siroe,dc=com
> changetype: modify
> delete: aci
> aci: (target ="ldap:///dc=siroe,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=siroe,dc=com")(targetattr!="userPassword") (targetfilter="(!(nsds5ReplConflict=*))")(version 3.0;acl "Anonymous read-search access";allow (read, search, compare) (userdn="ldap:///anyone");)

> -

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


Previous     Contents     Index     DocHome     Next     
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated March 23, 2001