shadow man Administrator's Guide
Red Hat Directory Server
Previous      Contents      Index      DocHome      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".

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

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:

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

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

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.

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)

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:

For information on setting up multi-master replication with two supplier servers and two consumer servers, refer to "Configuring Multi-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 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.

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

Note  

You can combine multi-master and cascading replication. For example, in the multi-master scenario illustrated in Figure 8-2, 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:
  2. On all hub suppliers:
  3. On all suppliers:
  4. Configure replication agreements on all suppliers:
    5. 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.
    6. 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", 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:
    6. dn: cn=replication manager,cn=config
    objectClass: inetorgperson
    objectClass: person
    objectClass: top
    cn: replication manager
    sn: RM
    userPassword: password
    passwordExpirationTime: 20380119031407Z
     
  6. Restart the Directory Server. See "Starting and Stopping the Directory Server", 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.
    2. For information on starting the Directory Server Console, see "Using the Directory Server Console".
     
  2. In the left navigation tree, highlight the Replication node.
  3. In the right pane, select the Supplier Settings tab.
  4. Check the Enable Changelog checkbox.
    5. This activates all of the fields in the pane below that were previously grayed out.
     
  5. Specify a changelog by clicking the "Use default" button, or click Browse to display a file selector.
  6. Set the changelog number and age parameters.
    7. 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 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.
    2. For information on starting the Directory Server Console, see "Using the Directory Server Console".
     
  2. In the left navigation tree, expand the Replication folder, and highlight the database to replicate.
    3. The Replication tab is displayed on the right pane.
     
  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, both inclusive).
    6. 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. In the Common Settings section, specify a purge delay in the "Purge delay" field.
    7. This option indicates how often the state information stored in the replicated entries is purged.
     
  7. 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.
    2. For information on starting the Directory Server Console, see "Using the Directory Server Console".
     
  2. In the left navigation tree, expand the Replication folder, and then highlight the replica database.
    3. The Replica Settings tab is displayed on the right pane.
     
  3. Check the Enable Replica checkbox.
  4. In the Replica Role section, select the Dedicated Consumer option.
  5. In the Common Settings section, specify a purge delay in the "Purge delay" field.
    6. This option indicates how often the state information stored in the replicated entries is purged.
     
  6. In the Update Settings section, specify the supplier bind DN that the supplier will use to bind to the replica.
    7. 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.
     
  7. Specify any supplier servers to which you want to refer updates.
    8. 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.
     
  8. 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.
    2. For information on starting the Directory Server Console, see "Using the Directory Server Console".
     
  2. In the left navigation tree, expand the Replication folder, and then highlight the database to replicate.
    3. The Replica Settings tab is displayed on the right pane.
     
  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 purge delay in the "Purge delay" field.
    6. This option indicates how often the state information stored in the replicated entries is purged.
     
  6. In the Update Settings section, specify the supplier bind DN that the supplier will use to bind to the replica.
    7. 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.
     
  7. Specify any supplier servers to which you want to refer updates.
    8. 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.
     
  8. 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.
    2. For information on starting the Directory Server Console, see "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.
    3. 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.
     
  3. 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.
  4. 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.
    5. 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.



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

    6. 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", for more information on read-only replicas and dedicated consumers.



  6. Set the replication schedule.
    7. 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.
     
  7. Select when to initialize the consumer.
    8. 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", for more information on methods and circumstances for consumer initialization.
     
  8. The last screen is a summary of your replication agreement. Check that this is accurate, and hit "Done."
    9. 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 Figure 8-1, 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.
    2. For instructions, refer to "Creating Suffixes".
     
  2. 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.
      4. 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.



  3. 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.
      3. 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 purge delay in the "Purge delay" field.
      6. This option indicates how often the state information stored in the replicated entries is purged.
       
    6. In the Update Settings section, specify the bind DN that the supplier will use to bind to the replica.
      7. 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.
       
    7. Specify any supplier servers to which you want to refer updates.
      8. 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.
       
  4. Click Save to save the replication settings for the replica.
  5. 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.
      5. This activates all of the fields in the pane below that were previously greyed out.
       
    5. Specify a changelog by clicking the "Use default" button, or click the Browse button to display a file selector.
    6. Set the changelog parameters (number and age).
      7. 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 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.
      2. 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).
      5. 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.
       
    5. In the Common Settings section, specify a purge delay in the "Purge delay" field.
      6. This option indicates how often the state information stored in the replicated entries is purged.
       
    6. Click Save to save the replication settings for the database.
  3. Create a replication agreement.
    4. 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 of the Configuration tab, right-click the database to replicate, and select New Replication Agreement.
      2. Or 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.
    3. 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".

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 Figure 8-2, 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.
    2. For instructions, refer to "Creating Suffixes".
     
  2. Create the entry corresponding to the supplier bind DN if it does not exist.

    3. 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.
      3. For example you could use cn=Replication Manager,cn=config.
       
    3. Specify a userPassword attribute-value pair.
    4. 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.
      5. 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.
       
  3. 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.
      3. The Replica Settings tab is displayed on the right pane.
       
    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 purge delay in the "Purge delay" field.
      6. This option indicates how often the state information stored in the replicated entries is purged.
       
    6. In the Update Settings section, specify the bind DN or entry DN that the supplier will use to bind to the replica.
      7. 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.
       
    7. Specify any supplier servers to which you want to refer updates.
      8. 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.
       
  4. Click Save to save the replication settings for the replica.
  5. 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.
      5. This activates all of the fields in the pane below.
       
    5. Specify a changelog by clicking the "Use default" button, or click the Browse button to display a file selector.
    6. Set the changelog parameters (number and age).
      7. 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.
    3. 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.
      3. For example, you could use cn=Replication Manager,cn=config.
       
    3. Specify a userPassword attribute-value pair.
    4. 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.
      5. 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.
       
  3. 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.
      3. The Replica Settings tab is displayed on the right pane.
       
    3. Check the Enable Replica checkbox.
    4. In the Replica Role section, select the Multiple Master radio button.
    5. In the Common Settings section, specify a Replica ID.
      6. 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.
       
    6. In the Common Settings section, specify a purge delay in the "Purge delay" field.
      7. This option indicates how often the state information stored in the replicated entries is purged.
       
    7. In the Update Settings section, specify the supplier bind DN or entry DN that the supplier will use to bind to the replica.
      8. 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.
       
    8. Specify the supplier server to which you want to refer updates (the other supplier in the multi-master set).
      9. 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://.
       
    9. Click Save to save the replication settings for the database.
  4. On server A, set up the following replication agreements:
    5. 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.
      3. Or 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.
      4. 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", and "Initializing Consumers".
       
      When you have finished, the replication agreement is set up.
       
  5. On server B, set up the following replication agreements:

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

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 Figure 8-3, 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:

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.
    2. For instructions, refer to "Creating Suffixes".
     
  2. Create the entry corresponding to the supplier bind DN if it does not exist.

    3. 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.
      3. For example, you could use cn=Replication Manager,cn=config.
       
    3. Specify a userPassword attribute-value pair.
    4. 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.
      5. 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.
       
  3. 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.
      3. The Replica Settings tab is displayed on the right pane.
       
    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 purge delay in the "Purge delay" field.
      6. This option indicates how often the state information stored in the replicated entries is purged.
       
    6. In the Update Settings section, specify the bind DN that the supplier will use to bind to the replica.
      7. 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.
       
    7. Specify the supplier servers to which you want to refer updates.
      8. 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.
       
  4. Click Save to save the replication settings for the replica.
  5. 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.
      4. This activates all of the fields in the pane below.
       
    4. Specify a changelog by clicking the Use Default button, or click the Browse button to display a file selector.
    5. Set the changelog parameters (number and age).
      6. You must clear the unlimited checkboxes if you want to specify different values.
       
    6. Click Save to save the supplier settings.
  2. Create the entry corresponding to the supplier bind DN if it does not already exist.
    3. 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.
      3. For example, you could use cn=Replication Manager,cn=config.
       
    3. Specify a userPassword attribute-value pair.
    4. 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.
      5. 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.
       
  3. 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.
      2. The Replica Settings tab is displayed on the right pane.
       
    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.
      5. 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.
       
    5. In the Common Settings section, specify a purge delay in the "Purge delay" field.
      6. This option indicates how often the state information stored in the replicated entries is purged.
       
    6. In the Update Settings section, specify the supplier bind DN or entry DN that the supplier will use to bind to the replica.
      7. 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.
       
    7. Specify the supplier server to which you want to refer updates (the other suppliers in the multi-master set).
      8. Only specify the URL for the supplier server. If you want clients to bind using SSL, you must specify a URL beginning with ldaps://.
       
    8. Click Save to save the replication settings for the database.
  4. Set up replication agreements on all the supplier servers:
    5. 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.
      3. Or 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.
     

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

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

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:

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 Figure 8-4, 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.
    2. 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. This is the special entry that the supplier will use to bind.
  3. 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.
      3. The Replica Settings tab is displayed on the right pane.
       
    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 purge delay in the "Purge delay" field.
      6. This option indicates how often the state information stored in the replicated entries is purged.
       
    6. In the Update Settings section, specify the bind DN that the supplier will use to bind to the replica.
      7. 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.
       
    7. Specify any supplier servers to which you want to refer updates.
      8. 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.
       
  4. 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.
      2. Or 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.
      3. 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 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.
    2. For instructions, refer to "Creating Suffixes".
     
  2. Create the entry corresponding to the supplier bind DN if it does not exist.

    3. 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.
      3. For example you could use cn=Replication Manager,cn=config.
       
    3. Specify a userPassword attribute-value pair.
    4. 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.
      5. 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.
       
  3. 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.
      3. The Replica Settings tab is displayed on the right pane.
       
    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 purge delay in the "Purge delay" field.
      6. This option indicates how often the state information stored in the replicated entries is purged.
       
    6. In the Update Settings section, specify the supplier bind DN that the supplier will use to bind to the replica.
      7. 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.
       
    7. Specify any supplier servers to which you want to refer updates.
      8. 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.
       
    8. 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.
      5. This activates all of the fields in the pane.
       
    5. Specify a changelog by clicking the "Use default" button, or click the Browse button to display a file selector.
    6. Set the changelog parameters (number and age).
      7. 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 settings.
    1. In the navigation tree of the Configuration tab, expand the Replication node, and then highlight the database to replicate.
      2. 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.
      5. The replica ID