Product SiteDocumentation Site

8.5. 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.
Directory Server supports 4-way multi-master replication. To set up multi-master replication such as the configuration shown in Figure 8.3, “Multi-Master Replication (Four Masters)”, set up all of the consumers first, then set up the suppliers, and last, initialize all of the databases:

NOTE

More than 10 databases running with replication or more than 20 replication agreements on a supplier can cause performance degradation. To support that many consumers, introduce hub replicas between the suppliers and consumers. See Section 8.6, “Configuring Cascading Replication”.

8.5.1. Configuring the Read-Write Replicas on the Supplier Servers

Set up each supplier server. The first supplier configured should be used to initialize the other suppliers in the multi-master replication environment.
  1. Specify the supplier settings for the server.
    1. In the Directory Server Console, select the Configuration tab.
    2. In the navigation tree, select the Replication folder.
    3. In the right-hand side of the window, select the Supplier Settings tab.
    4. Check the Enable Changelog checkbox.
      This activates all of the fields in the pane below that were previously grayed 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 for the number and age of the log files.
      Clear the unlimited checkboxes to specify different values.
    7. Click Save.
  2. Create the entry for the supplier bind DN on the consumer server if it does not exist. This is the special entry that the other suppliers will use to bind to this supplier, as in other supplier-consumer relationships. This is described in Section 8.3, “Creating the Supplier Bind DN Entry”.

    NOTE

    For multi-master replication, it is necessary to create this supplier bind DN on the supplier servers as well as the consumers because the suppliers act as both consumer and supplier to the other supplier servers.
  3. Specify the replication settings for the multi-mastered read-write replica.
    1. In the Directory Server Console, select the Configuration tab.
    2. In the navigation tree, expand the Replication folder, and highlight the replica database.
      The Replica Settings tab for that database opens in the right-hand side of the window.
    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, which is an integer between 1 and 65534, inclusive.
      The replica ID must be unique for a given suffix, different from any other ID 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.
      The purge delay is how often the state information stored in the replicated entries is deleted.
    7. In the Update Settings section, specify the bind DN that the supplier will use to bind to the replica. Enter the supplier bind DN in the Enter a new Supplier DN field, and click Add. The supplier bind DN appears in the Current Supplier DNs list.
      The supplier bind DN should be the entry created in step 2. The supplier bind DN is a privileged user because it is not subject to access control in the replicated database.

      NOTE

      There can be multiple supplier bind DNs per consumer but only one supplier DN per replication agreement.
    8. Specify the URL for any supplier servers to which to refer updates, such as the other suppliers in the multi-master replication set. Only specify the URL for the supplier server.
      For clients to bind using SSL, specify a URL beginning with ldaps://.
    9. Click Save.

8.5.2. Configuring the Read-Only Replicas on the Consumer Servers

First, configure every consumer.
  1. Create the database for the read-only replica if it does not exist. See Section 3.1.1, “Creating Suffixes” for instructions on creating suffixes.
  2. Create the entry for the supplier bind DN on the consumer server if it does not exist. The supplier bind DN is the special entry that the supplier will use to bind to the consumer. This is described in Section 8.3, “Creating the Supplier Bind DN Entry”.
  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.
      The Replica Settings tab for that database opens 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.
      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. Enter the supplier bind DN in the Enter a new Supplier DN field, and click Add. The supplier bind DN appears in the Current Supplier DNs list.
      The supplier bind DN should be the entry created in step 2. The supplier bind DN is a privileged user because it is not subject to access control in the replicated database.

      NOTE

      There can be multiple supplier bind DNs per consumer but only one supplier DN per replication agreement.
    7. Specify the URL for any supplier servers to which to refer updates.
      By default, all updates are first referred to the supplier servers that are specified here. If no suppliers are set here, updates are referred to the supplier servers that have a replication agreement that includes the current replica.
      Automatic referrals assume that clients bind over a regular connection; this has a URL in the form ldap://hostname:port. For clients to bind to the supplier using SSL, use this field to specify a referral of the form ldaps://hostname:port, where the s in ldaps indicates a secure connection.
  4. Click Save.
Repeat these steps for every consumer server in the replication configuration.

8.5.3. Setting up the Replication Agreements

First set up replication agreements on a single supplier, the data master, between the other multi-master suppliers, and initialize all of the other suppliers.
Then create replication agreements for all other suppliers in the multi-master replication set, but do not reinitialize any of the suppliers.
Then create replication agreements for all of the consumers from the single data master, and initialize the consumers.
Then create replication agreements for all of the consumers from for all of the other suppliers, but do not reinitialize any of the consumers.
  1. In the navigation tree of 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 to start the Replication Agreement Wizard.
  2. In the first screen, fill in a name and description for the replication agreement, and hit Next.
  3. In the Source and Destination screen, fill in the URL for the consumer and the supplier bind DN and password on that consumer. If the target server is not available, hit in other to fill in the information manually.
    • Unless there is more than one instance of Directory Server configured, by default, there are no consumers available in the drop-down menu.
    • The port listed is the non-SSL port, even if the Directory Server instance is configured to run over SSL. This port number is used only for identification of the Directory Server instance in the Console; it does not specify the actual port number or protocol that is used for replication.
    • If SSL is enabled on the servers, it is possible to select the Using encrypted SSL connection radio button for SSL client authentication. Otherwise, fill in the supplier bind DN and password.

      NOTE

      If attribute encryption is enabled, a secure connection is required for the encrypted attributes to be replicated.
    Hit Next.
  4. Fractional replication controls which entry attributes are replicated between servers. By default, all attributes are replicated. To select attributes that will not be replicated to the consumer, check 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 are listed in the Excluded column on the left, as well as in the summary the replication agreement is complete.

    NOTE

    To safeguard against potential integrity problems, the consumer in fractional replication must be a dedicated consumer, not a multi-master supplier or hub. This is not enforced at the time the replication agreement is made, but replication will fail if the consumer is not a read-only replica.
  5. Set the schedule for when replication runs. By default, replication runs continually.
    Hit Next.
  6. Set when the consumer is initialized. Initializing a consumer manually copies all data over from the supplier to the consumer. The default is to create an initialization file (an LDIF of all supplier data) so that the consumer can be initialized later. It is also possible to initialize the consumer as soon as the replication agreement is completed or not at all. For information on initializing consumers, see Section 8.10, “Initializing Consumers”. For multi-master replication, consider the following:
    • Ensure one supplier has the complete set of data to replicate to the other suppliers. Use this one supplier to initialize the replica on all other suppliers in the multi-master replication set.
    • Initialize the replicas on the consumer servers from any of the multi-master suppliers.
    • Do not try to reinitialize the servers when the replication agreements are set up. For example, do not initialize server1 from server2 if server2 has already been initialized from server1. In this case, select Do not initialize consumer.

    NOTE

    Replication will not begin until the consumer is initialized.
    Hit Next.
  7. The final screen shows the settings for the replication agreement, as it will be included in the dse.ldif file. Hit Done to save the agreement.
The replication agreement is set up.

NOTE

At the end of this procedure, all supplier servers will have mutual replication agreements, which means that they can accept updates from each other.

NOTE

After creating a replication agreement, the connection type (SSL or non-SSL) cannot be changed because LDAP and LDAPS connections use different ports. To change the connection type, re-create the replication agreement.

8.5.4. 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. Normally, this is all right; the supplier simply sends its update to another consumer while the first consumer is locked and then send updates when the first consumer is free again.
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, nsds5ReplicaBusyWaitTime and nsds5ReplicaSessionPauseTime.
These two attributes may be present in the nsds5ReplicationAgreement object class, which is used to describe replication agreements. 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 either attribute is set 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 one 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 not logged by default because they are usually benign. To see the errors, turn on the replication error logging, log level 8192. The log levels are described in more detail in the Directory Server Configuration, Command, and File Reference.