Show Table of Contents
15.2. Configuring Replication from the Command Line
Replication can be configured on the command line by creating the appropriate replica and agreement entries on the servers. The process follows the same order as setting up replication through the Directory Server Console:
- Create the supplier bind DN on every consumer, hub, and multi-master supplier (Section 15.4, “Creating the Supplier Bind DN Entry”).
- If the corresponding database and suffix do not exist on one of the replicas, create it (Section 2.1.1, “Creating Suffixes”).
- Configure the supplier replicas (Section 15.2.1, “Configuring Suppliers from the Command Line”).
- Configure consumers (Section 15.2.2, “Configuring Consumers Using the Command Line”).
- Configure hubs for cascading replication (Section 15.2.3, “Configuring Hubs from the Command Line”).
- Create the replication agreements (Section 15.2.4, “Configuring Replication Agreements from the Command Line”). For cascading replication, create the agreement between the supplier and hub, then between the hub and consumers; for multi-master, create the agreements between all suppliers, then between the suppliers and consumers.
- Lastly, initialize all of the consumers (Section 15.2.5, “Initializing Consumers Online from the Command Line”), if the consumers were not initialized when the replication agreement was created.
15.2.1. Configuring Suppliers from the Command Line
There are two steps to setting up the supplier replica. First, the changelog must be enabled, which allows the supplier to track changes to the Directory Server. Then, the supplier replica is created.
- On the supplier server, use
ldapmodifyto create the changelog entry.Example 15.1. Example Changelog Entry
# ldapmodify -D "cn=Directory Manager" -W -x -h supplier1.example.com -v -a dn: cn=changelog5,cn=config changetype: add objectclass: top objectclass: extensibleObject cn: changelog5 nsslapd-changelogdir: /var/lib/dirsrv/slapd-instance/changelogdb nsslapd-changelogmaxage: 10d
There are two important attributes with the changelog.nsslapd-changelogdirsets the directory where the changelog is kept.nsslapd-changelogmaxagesets how long the changelog is kept; since the changelog can get very large, this helps trim the changelog to prevent affecting server performance and using up disk space. If this parameter is not set, the default is for the changelog to be kept forever.
The changelog entry attributes are described in the Red Hat Directory Server Configuration, Command, and File Reference. - Create the supplier replica.
Example 15.2. Example Supplier Replica Entry
# ldapmodify -D "cn=Directory Manager" -W -x -h supplier1.example.com -v -a dn: cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config changetype: add objectclass: top objectclass: nsds5replica objectclass: extensibleObject cn: replica nsds5replicaroot: dc=example,dc=com nsds5replicaid: 7 nsds5replicatype: 3 nsds5flags: 1 nsds5ReplicaPurgeDelay: 604800 nsds5ReplicaBindDN: cn=replication manager,cn=config
Important
You must set thecnparameter of the replica entry toreplicaas shown in the example. Directory Server ignores the entry if you set the parameter to a different value.The changelog entry attributes are described in the Red Hat Directory Server Configuration, Command, and File Reference.
After creating every supplier which will take part in the replication setup, then begin creating the replication agreements.
15.2.2. Configuring Consumers Using the Command Line
To configure a consumer using the command line, the following settings are required on the consumer host:
- Create the replica entry:
# ldapadd -D "cn=Directory Manager" -W -p 389 -h consumer.example.com -x dn: cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config objectclass: top objectclass: nsds5replica objectclass: extensibleObject cn: replica nsds5replicaroot: dc=example,dc=com nsds5replicaid: 65535 nsds5replicatype: 2 nsds5ReplicaBindDN: cn=replication manager,cn=config nsds5flags: 0
Important
You must set thecnparameter of the replica entry toreplicaas shown in the example. Directory Server ignores the entry if you set the parameter to a different value.This entry identifies the database and suffix as participating in replication and sets what kind of replica the database is. - Set the
nsslapd-referralparameter to the LDAP URL of the supplier server and thensslapd-statetoreferral on update. For example:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h consumer.example.com -x dn: cn=dc\=example\,dc\=com,cn=mapping tree,cn=config changetype: modify replace: nsslapd-referral nsslapd-referral: ldap://supplier.example.com:389/dc\=example\,dc\=com - replace: nsslapd-state nsslapd-state: referral on update
For further details about the attributes used in the examples, see the corresponding sections in the Red Hat Directory Server Configuration, Command, and File Reference.
15.2.3. Configuring Hubs from the Command Line
Hubs are intermediate read-only replicas which receive updates from suppliers and pass them on to other consumers. These are part of the cascading replication scenario, described in Section 15.3.3, “Cascading Replication”.Creating the hub has two steps: first, creating the changelog database since the hub keeps a record of changes sent by the supplier, and second, configuring the hub replica.
- On the hub server, such as
hub1.example.com, useldapmodifyto create the changelog entry.# ldapmodify -D "cn=Directory Manager" -W -x -h hub1.example.com -v -a dn: cn=changelog5,cn=config changetype: add objectclass: top objectclass: extensibleObject cn: changelog5 nsslapd-changelogdir: /var/lib/dirsrv/slapd-instance/changelogdb
There is one important attribute with the changelog,nsslapd-changelogdir, which sets the directory where the changelog is kept.The changelog entry attributes are described in the Red Hat Directory Server Configuration, Command, and File Reference. - On the hub host, create the replica entry. This
ldapmodifycommand creates a new hub replica on thehub1.example.comhost for thedc=example,dc=comsubtree.# ldapmodify -D "cn=Directory Manager" -W -x -h hub1.example.com -v -a dn: cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config changetype: add objectclass: top objectclass: nsds5replica objectclass: extensibleObject cn: replica nsds5replicaid: 65535 nsds5replicaroot: dc=example,dc=com nsds5replicatype: 2 nsds5ReplicaPurgeDelay: 604800 nsds5ReplicaBindDN: cn=replication manager,cn=config nsds5flags: 1
Important
You must set thecnparameter of the replica entry toreplicaas shown in the example. Directory Server ignores the entry if you set the parameter to a different value.This entry identifies the database and suffix as participating in replication and sets what kind of replica the database is.
The changelog entry attributes are described in the Red Hat Directory Server Configuration, Command, and File Reference.
15.2.4. Configuring Replication Agreements from the Command Line
When setting up replication agreements, first set them up between all suppliers, then between the suppliers and the hubs, and last between the hub and the consumers.
The replication agreement has to define eight separate attributes:
- The consumer host (
nsds5replicahost) and port (nsds5replicaport). - The DN for the supplier to use to bind with the consumer (
nsds5ReplicaBindDN). - The way that the supplier binds (
nsds5replicabindmethod). - Any credentials required (
nsDS5ReplicaCredentials) for that bind method and specified DN. - The subtree being replicated (
nsds5replicaroot). - The replication schedule (
nsds5replicaupdateschedule). - Any attributes which will not be replicated (
nsds5replicatedattributelistandnsDS5ReplicatedAttributeListTotal).
Use
ldapmodify to add a replication agreement to every supplier for every consumer which it will updated. For example:
Example 15.3. Example Replication Agreement Entry
dn: cn=ExampleAgreement,cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config objectclass: top objectclass: nsds5ReplicationAgreement cn: ExampleAgreement nsds5replicahost: consumer1 nsds5replicaport: 389 nsds5ReplicaBindDN: cn=replication manager,cn=config nsds5replicabindmethod: SIMPLE nsds5replicaroot: dc=example,dc=com description: agreement between supplier1 and consumer1 nsds5replicaupdateschedule: 0000-0500 1 nsds5replicatedattributelist: (objectclass=*) $ EXCLUDE authorityRevocationList accountUnlockTime memberof nsDS5ReplicatedAttributeListTotal: (objectclass=*) $ EXCLUDE accountUnlockTime nsds5replicacredentials: secret
For descriptions of the parameters used in the example, and additional parameters you can set in the
cn=agreement_name,cn=replica,cn=suffix_DN,cn=mapping tree,cn=config entry, see the Red Hat Directory Server Configuration, Command, and File Reference.
After creating every replication agreement, begin initializing consumers.
15.2.4.1. Configuring Replication Partners to use Certificate-based Authentication
Instead of using a bind DN and password to authenticate to a replication partner, you can use certificate-based authentication.
The following procedure describes how to add a new server named
server2.example.com to the replication topology and how to set up replication agreements between the new host and the existing server1.example.com using certificate-based authentication:
- On both hosts, set up certificate-based authentication. For details, see Section 9.8.1, “Setting up Certificate-based Authentication”.
- On the
server1.example.comhost:- Create accounts for both servers, such as
cn=server1,example,dc=comandcn=server2,dc=example,dc=comand add the client certificates to the corresponding accounts. For details, see:Both servers will later use these accounts and certificates to authenticate when they establish a replication connection to each other. - Create a group, such as
cn=repl_server,ou=Groups,dc=example,dc=com, and add both server accounts. See Section 8.1.3, “Creating Groups in the Command Line”. - Create the replica entry and set the
nsds5ReplicaBindDNGroupattribute to the DN of the group created in the previous step:# ldapmodify -D "cn=Directory Manager" -W -p 636 -h server1.example.com -x dn: cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config changetype: add objectclass: top objectclass: nsds5replica objectclass: extensibleObject cn: replica nsds5replicaroot: dc=example,dc=com nsds5replicaid: 7 nsds5replicatype: 3 nsds5flags: 1 nsds5ReplicaPurgeDelay: 604800 nsds5replicabinddngroup: cn=repl_server,ou=Groups,dc=example,dc=com nsDS5ReplicaBindDNGroupCheckInterval: 0Important
You must set thecnparameter of the replica entry toreplicaas shown in the example. Directory Server ignores the entry if you set the parameter to a different value.
- Initialize the new server:
- Create a temporary replication manager account, such as
cn=Replication Manager,cn=config, onserver2.example.com. See Section 15.4, “Creating the Supplier Bind DN Entry”. - On
server1.example.com, create a temporary replication agreement which uses the account from the previous step for authentication:# ldapmodify -D "cn=Directory Manager" -W -p 636 -h server1.example.com -x dn: cn=temporary_agreement,cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config objectclass: top objectclass: nsds5ReplicationAgreement cn: temporary_agreement nsds5replicahost: server2.example.com nsds5replicaport: 636 nsds5replicabindmethod: SIMPLE nsds5ReplicaBindDN: cn=Replication Manager,cn=config nsds5replicacredentials: password_of_replication_manager_account nsds5replicaroot: dc=example,dc=com description: Temporary agreement between server1 and server2 nsds5replicaupdateschedule: 0000-0500 1 nsds5replicatedattributelist: (objectclass=*) $ EXCLUDE authorityRevocationList accountUnlockTime memberof nsDS5ReplicatedAttributeListTotal: (objectclass=*) $ EXCLUDE accountUnlockTime nsds5BeginReplicaRefresh: start
This agreement uses the previously-created replication manager account to initialize the database. Before this initialization, the database onserver2.example.comis empty and the accounts with the associated certificates do not exist. Therefore, replication using certificates is not possible before the database is initialized.
- After the new server has been initialized:
- Remove the temporary replication agreement from
server1.example.com:# ldapdelete -D "cn=Directory Manager" -W -p 636 -h server1.example.com -x "cn=temporary_agreement,cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config"
- Remove the temporary replication manager account from
server2.example.com:# ldapdelete -D "cn=Directory Manager" -W -p 636 -h server2.example.com -x "cn=Replication Manager,cn=config"
- Create a replication agreement on both servers that use certificate-based authentication:
- On
server1.example.com:# ldapmodify -D "cn=Directory Manager" -W -p 636 -h server1.example.com -x dn: cn=example_agreement,cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config objectclass: top objectclass: nsds5ReplicationAgreement cn: example_agreement nsds5replicahost: server2.example.com nsds5replicaport: 636 nsds5replicabindmethod: SSLCLIENTAUTH nsds5replicaroot: dc=example,dc=com description: Agreement between server1 and server2 nsds5replicaupdateschedule: 0000-0500 1 nsds5replicatedattributelist: (objectclass=*) $ EXCLUDE authorityRevocationList accountUnlockTime memberof nsDS5ReplicatedAttributeListTotal: (objectclass=*) $ EXCLUDE accountUnlockTime nsDS5ReplicaTransportInfo: SSL
- On
server2.example.com:# ldapmodify -D "cn=Directory Manager" -W -p 636 -h server2.example.com -x dn: cn=example_agreement,cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config objectclass: top objectclass: nsds5ReplicationAgreement cn: example_agreement nsds5replicahost: server1.example.com nsds5replicaport: 636 nsds5replicabindmethod: SSLCLIENTAUTH nsds5replicaroot: dc=example,dc=com description: Agreement between server2 and server1 nsds5replicaupdateschedule: 0000-0500 1 nsds5replicatedattributelist: (objectclass=*) $ EXCLUDE authorityRevocationList accountUnlockTime memberof nsDS5ReplicatedAttributeListTotal: (objectclass=*) $ EXCLUDE accountUnlockTime nsDS5ReplicaTransportInfo: SSL
- To verify the replication works correctly, display the
nsds5replicaLastUpdateStatusattribute in the replication agreement:# ldapsearch -D "cn=Directory Manager" -W -p 636 -h server1.example.com -b "cn=example_agreement,cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config" nsds5replicaLastUpdateStatus
For details about possible statuses, see the Replication Agreement Status appendix in the Red Hat Directory Server Configuration, Command, and File Reference.
15.2.5. Initializing Consumers Online from the Command Line
An online initialization can be initiated from the command line by adding the
nsds5replicarefresh attribute to the replication agreement entry. If the attribute is included when the replication agreement is created, initialization begins immediately. It can be added later to initialize the consumer at any time. This attribute is absent by default, and it will be automatically deleted once the consumer initialization is complete.
- Find the DN of the replication agreement on the supplier server that is for the consumer to be initialized. For example:
# ldapsearch -x -h supplier1.example.com -p 389 -D "cn=Directory Manager" -W -s sub -b cn=config "(objectclass=nsds5ReplicationAgreement)"
This command returns all of the replication agreements configured on the supplier in LDIF format. Get the DN of the replication agreement with the consumer to be initialized. This is the replication agreement which will be edited. - Edit the replication agreement, and add the
nsds5BeginReplicaRefreshattribute:# ldapmodify -D "cn=Directory Manager" -W -x -h supplier1.example.com dn: cn=ExampleAgreement,cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config changetype: modify replace: nsds5BeginReplicaRefresh nsds5BeginReplicaRefresh: start
ldapmodifydoes not prompt for input; simply type in the LDIF statement, and then hit enter twice when the LDIF statement is complete. Close theldapmodifyutility by hitting Ctrl+C.
When the initialization is complete, the
nsds5BeginReplicaRefresh attribute is automatically deleted from the replication agreement entry.
Important
For multi-master replication, be sure that consumers are only initialized once, by one supplier. When checking the replication status, be sure to check the replication agreement entry, on the appropriate supplier, which was used to initialize the consumer.
Initializing consumers from the command line is also explained in Section 15.17.3, “Initializing Consumers Online Using the Command Line”. Manually initializing consumers is explained in Section 15.17.4, “Manual Consumer Initialization Using the Command Line”. The replication monitoring attributes are described in more detail in the Red Hat Directory Server Configuration, Command, and File Reference.
Note
For large databases, the
nsslapd-idletimeout setting must be set to a large enough time period (or even an unlimited period) to allow the entire database to be initialized before the operation times out. Alternatively, the nsIdleTimeout setting for the supplier bind DN entry can be set high enough to allow the online initialization operation to complete, without having to change the global setting.
To keep data integrity, initialize the consumer databases from the appropriate supplier. Determining the correct supplier can be more difficult in mixed replication environments, but, even when manually initializing consumers, consider four things:
- Use one supplier, a data master, as the source for initializing consumers.
- Do not reinitialize a data master when the replication agreements are created. For example, do not initialize server1 from server2 if server2 has already been initialized from server1.
- For a multi-master scenario, initialize all of the other master servers in the configuration from one master.
- For cascading replication, initialize all of the hubs from a supplier, then initialize the consumers from the hubs.
Where did the comment section go?
Red Hat's documentation publication system recently went through an upgrade to enable speedier, more mobile-friendly content. We decided to re-evaluate our commenting platform to ensure that it meets your expectations and serves as an optimal feedback mechanism. During this redesign, we invite your input on providing feedback on Red Hat documentation via the discussion platform.