Chapter 1. Configuring single-supplier replication using the command line

In a single-supplier replication environment, one writable supplier replicates data to one or multiple read-only consumers. For example, set up single-supplier replication if a suffix receives a large number of search requests but only a small number of write requests. To distribute the load, clients can then search for the suffix on read-only consumers and send write requests to the supplier.

This section assumes that you have an existing Directory Server instance running on a host named supplier.example.com that will act as a supplier in the replication topology to be set up. The procedures describe how to add a read-only consumer named consumer.example.com to the topology, and how to configure single-supplier replication for the dc=example,dc=com suffix.

1.1. Preparing the new consumer using the command line

To prepare the consumer.example.com host, enable replication. This process:

  • Configures the role of this server in the replication topology
  • Defines the suffix that is replicated
  • Creates the replication manager account the supplier uses to connect to this host

Perform this procedure on the consumer that you want to add to the replication topology.

Prerequisites

  • You installed the Directory Server instance.
  • The database for the dc=example,dc=com suffix exists.

Procedure

  • Enable replication for the dc=example,dc=com suffix: 

    # dsconf -D "cn=Directory Manager" ldap://consumer.example.com replication enable --suffix "dc=example,dc=com" --role "consumer" --bind-dn "cn=replication manager,cn=config" --bind-passwd "password"

    This command configures the consumer.example.com host as a consumer for the dc=example,dc=com suffix. Additionally, the command creates the cn=replication manager,cn=config user with the specified password and allows this account to replicate changes for the suffix to this host.

Verification

  • Display the replication configuration: 

    # dsconf -D "cn=Directory Manager" ldap://consumer.example.com replication get --suffix "dc=example,dc=com"
dn: cn=replica,cn=dc\3Dexample\2Cdc\3Dcom,cn=mapping tree,cn=config
...
nsDS5ReplicaBindDN: cn=replication manager,cn=config
nsDS5ReplicaRoot: dc=example,dc=com
nsDS5ReplicaType: 2
...

    These parameters indicate:

    • nsDS5ReplicaBindDN specifies the replication manager account.
    • nsDS5ReplicaRoot sets the suffix that is replicated.
    • nsDS5ReplicaType set to 2 defines that this host is a consumer.

Additional resources

1.2. Configuring the existing server as a supplier to the consumer using the command line

To prepare the supplier.example.com host, you need to:

  • Enable replication for the suffix.
  • Create a replication agreement to the consumer.
  • Initialize the consumer.

Perform this procedure on the existing supplier in the replication topology.

Prerequisites

  • You enabled replication for the dc=example,dc=com suffix on the consumer.

Procedure

  1. Enable replication for the dc=example,dc=com suffix: 

    # dsconf -D "cn=Directory Manager" ldap://supplier.example.com replication enable --suffix "dc=example,dc=com" --role "supplier" --replica-id 1

    This command configures the supplier.example.com host as a supplier for the dc=example,dc=com suffix, and sets the replica ID of this entry to 1.

    Important

    The replica ID must be a unique integer between 1 and 65534 for a suffix across all suppliers in the topology.

  2. Add the replication agreement and initialize the consumer: 

    # dsconf -D "cn=Directory Manager" ldap://supplier.example.com repl-agmt create --suffix "dc=example,dc=com" --host "consumer.example.com" --port 389 --conn-protocol=LDAP --bind-dn "cn=replication manager,cn=config" --bind-passwd "password" --bind-method=SIMPLE --init example-agreement

    This command creates a replication agreement named example-agreement. The replication agreement defines settings, such as the consumer’s host name, protocol, and authentication information that the supplier uses when connecting and replicating data to this consumer.

    After the agreement was created, Directory Server initializes consumer.example.com. Depending on the amount of data to replicate, initialization can be time-consuming.

Verification

  1. Display the replication configuration: 

    # dsconf -D "cn=Directory Manager" ldap://supplier.example.com replication get --suffix "dc=example,dc=com"
dn: cn=replica,cn=dc\3Dexample\2Cdc\3Dcom,cn=mapping tree,cn=config
...
nsDS5ReplicaRoot: dc=example,dc=com
nsDS5ReplicaType: 3
...

    These parameters indicate:

    • nsDS5ReplicaRoot sets the suffix that is replicated.
    • nsDS5ReplicaType set to 3 defines that this host is a supplier.

  2. Verify whether the initialization was successful: 

    # dsconf -D "cn=Directory Manager" ldap://supplier.example.com repl-agmt init-status --suffix "dc=example,dc=com" example-agreement
Agreement successfully initialized.

  3. Display the replication status: 

    # dsconf -D "cn=Directory Manager" ldap://supplier.example.com repl-agmt status --suffix "dc=example,dc=com" example-agreement
Status For Agreement: "example-agreement" (consumer.example.com:389)
Replica Enabled: on
Update In Progress: FALSE
Last Update Start: 20210330075608Z
Last Update End: 20210330075608Z
Number Of Changes Sent: 1:3/0
Number Of Changes Skipped: None
Last Update Status: Error (0) Replica acquired successfully: Incremental update succeeded
Last Init Start: 20210330074603Z
Last Init End: 20210330074606Z
Last Init Status: Error (0) Total update succeeded
Reap Active: 0
Replication Status: Not in Synchronization: supplier (6062d73c000000010000) consumer (Unavailable) State (green) Reason (error (0) replica acquired successfully: incremental update succeeded)
Replication Lag Time: Unavailable

    Verify the Replication Status and Last Update Status fields.

Troubleshooting

  1. By default, the replication idle timeout for all agreements on a server is 1 hour. If the initialization of large databases fails due to timeouts, set the nsslapd-idletimeout parameter to a higher value. For example, to set the parameter to 7200 (2 hours), enter: 

    # dsconf -D "cn=Directory Manager" ldap://supplier.example.com config replace nsslapd-idletimeout=7200

    To set an unlimited period, set nsslapd-idletimeout to 0.

Additional resources