Chapter 6. Configuring cascading replication using the command line
In a cascading replication scenario, one server, a hub, acts both as a consumer and a supplier. The hub is a read-only replica that maintains a changelog. It receives updates from the supplier and supplies these updates to a consumer. Use cascading replication for balancing heavy traffic loads or to keep suppliers based locally in geographically-distributed environments.
6.1. Preparing the new hub server using the command line
To prepare the hub.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 hub 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://hub.example.com replication enable --suffix "dc=example,dc=com" --role "hub" --bind-dn "cn=replication manager,cn=config" --bind-passwd "password"
This command configures the
hub.example.com
host as a hub for thedc=example,dc=com
suffix. Additionally, the command creates thecn=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://hub.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 nsDS5ReplicaId: 65535 ...These parameters indicate:
-
nsDS5ReplicaBindDN
specifies the replication manager account. -
nsDS5ReplicaRoot
sets the suffix that is replicated. -
nsDS5ReplicaType
set to2
defines that this host is a consumer, which is also valid for a hub. -
nsDS5ReplicaId
set to65535
defines that this host is a hub. Thedsconf
utility automatically sets this value if you define the--role "hub"
option.
-
6.2. Configuring the existing server as a supplier to the hub server using the command line
To prepare the existing server as a supplier, you need to:
- Enable replication for the suffix.
- Create a replication agreement to the hub.
- Initialize the hub.
Perform this procedure on the existing supplier in the replication topology.
Prerequisites
-
You enabled replication for the
dc=example,dc=com
suffix on the hub to join.
Procedure
Enable replication for the
dc=example,dc=com
suffix:# [command]`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 thedc=example,dc=com
suffix, and sets the replica ID of this entry to1
.ImportantThe replica ID must be a unique integer between
1
and65534
for a suffix across all suppliers in the topology.Add the replication agreement and initialize the new server:
#
dsconf -D "cn=Directory Manager" ldap://supplier.example.com repl-agmt create --suffix "dc=example,dc=com" --host "hub.example.com" --port 389 --conn-protocol LDAP --bind-dn "cn=replication manager,cn=config" --bind-passwd "password" --bind-method SIMPLE --init example-agreement-supplier-to-hub
This command creates a replication agreement named
example-agreement-supplier-to-hub
. The replication agreement defines settings, such as the hub’s host name, protocol, and authentication information that the supplier uses when connecting and replicating data to the hub.After the agreement was created, Directory Server initializes
hub.example.com
. Depending on the amount of data to replicate, initialization can be time-consuming.
Verification
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 to3
defines that this host is a supplier.
-
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-supplier-to-hub
Agreement successfully initialized.Display the replication status:
#
dsconf -D "cn=Directory Manager" ldap://supplier.example.com repl-agmt status --suffix "dc=example,dc=com" example-agreement-supplier-to-hub
Status For Agreement: "example-agreement-supplier-to-hub" (hub.example.com:389) Replica Enabled: on Update In Progress: FALSE Last Update Start: 20210331105030Z Last Update End: 20210331105030Z Number Of Changes Sent: 0 Number Of Changes Skipped: None Last Update Status: Error (0) Replica acquired successfully: Incremental update succeeded Last Init Start: 20210331105026Z Last Init End: 20210331105029Z Last Init Status: Error (0) Total update succeeded Reap Active: 0 Replication Status: Not in Synchronization: supplier (Unknown) consumer (Unknown) State (green) Reason (error (0) replica acquired successfully: incremental update succeeded) Replication Lag Time: UnavailableVerify the
Replication Status
andLast Update Status
fields.
Troubleshooting
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 to7200
(2 hours), enter:#
dsconf -D "cn=Directory Manager" ldap://supplier1.example.com config replace nsslapd-idletimeout=7200
To set an unlimited period, set
nsslapd-idletimeout
to0
.
Additional resources
6.3. Preparing the new consumer of the hub 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 hub 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. For details, see Setting up a new instance on the command line using a .inf file.
-
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 thedc=example,dc=com
suffix. Additionally, the command creates thecn=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 to2
defines that this host is a consumer.
-
6.4. Configuring the hub server as a supplier for the consumer using the command line
To prepare the hub, you need to:
- Create a replication agreement to the consumer.
- Initialize the consumer.
Perform this procedure on the hub in the replication topology.
Prerequisites
- The hub is initialized, and replication from the supplier to the hub works.
-
You enabled replication for the
dc=example,dc=com
suffix on the hub.
Procedure
Add the replication agreement and initialize the consumer:
#
dsconf -D "cn=Directory Manager" ldap://hub.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-hub-to-consumer
This command creates a replication agreement named
example-agreement-hub-to-consumer
. 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
Verify whether the initialization was successful:
#
dsconf -D "cn=Directory Manager" ldap://hub.example.com repl-agmt init-status --suffix "dc=example,dc=com" example-agreement-hub-to-consumer
Agreement successfully initialized.Display the replication status:
#
dsconf -D "cn=Directory Manager" ldap://hub.example.com repl-agmt status --suffix "dc=example,dc=com" example-agreement-hub-to-consumer
Status For Agreement: "example-agreement-hub-to-consumer" (consumer.example.com:389) Replica Enabled: on Update In Progress: FALSE Last Update Start: 20210331131534Z Last Update End: 20210331131534Z Number Of Changes Sent: 0 Number Of Changes Skipped: None Last Update Status: Error (0) Replica acquired successfully: Incremental update succeeded Last Init Start: 20210331131530Z Last Init End: 20210331131533Z Last Init Status: Error (0) Total update succeeded Reap Active: 0 Replication Status: Not in Synchronization: supplier (Unknown) consumer (Unknown) State (green) Reason (error (0) replica acquired successfully: incremental update succeeded) Replication Lag Time: UnavailableVerify the
Replication Status
andLast Update Status
fields.
Troubleshooting
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 to7200
(2 hours), enter:#
dsconf -D "cn=Directory Manager" ldap://hub .example.com config replace nsslapd-idletimeout=7200
To set an unlimited period, set
nsslapd-idletimeout
to0
.