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:
  1. Create the supplier bind DN on every consumer, hub, and multi-master supplier (Section 15.4, “Creating the Supplier Bind DN Entry”).
  2. If the corresponding database and suffix do not exist on one of the replicas, create it (Section 2.1.1, “Creating Suffixes”).
  3. Configure the supplier replicas (Section 15.2.1, “Configuring Suppliers from the Command Line”).
  4. Configure consumers (Section 15.2.2, “Configuring Consumers Using the Command Line”).
  5. Configure hubs for cascading replication (Section 15.2.3, “Configuring Hubs from the Command Line”).
  6. 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.
  7. 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.
  1. On the supplier server, use ldapmodify to 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-changelogdir sets the directory where the changelog is kept.
    • nsslapd-changelogmaxage sets 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.
  2. 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 the cn parameter of the replica entry to replica as 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:
  1. 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 the cn parameter of the replica entry to replica as 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.
  2. Set the nsslapd-referral parameter to the LDAP URL of the supplier server and the nsslapd-state to referral 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.
  1. On the hub server, such as hub1.example.com, use ldapmodify to 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.
  2. On the hub host, create the replica entry. This ldapmodify command creates a new hub replica on the hub1.example.com host for the dc=example,dc=com subtree. 
    # 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 the cn parameter of the replica entry to replica as 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 (nsds5replicatedattributelist and nsDS5ReplicatedAttributeListTotal).
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:
  1. On both hosts, set up certificate-based authentication. For details, see Section 9.8.1, “Setting up Certificate-based Authentication”.
  2. On the server1.example.com host:
    1. Create accounts for both servers, such as cn=server1,example,dc=com and cn=server2,dc=example,dc=com and 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.
    2. 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”.
    3. Create the replica entry and set the nsds5ReplicaBindDNGroup attribute 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: 0

      Important

      You must set the cn parameter of the replica entry to replica as shown in the example. Directory Server ignores the entry if you set the parameter to a different value.
  3. Initialize the new server:
    1. Create a temporary replication manager account, such as cn=Replication Manager,cn=config, on server2.example.com. See Section 15.4, “Creating the Supplier Bind DN Entry”.
    2. 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 on server2.example.com is empty and the accounts with the associated certificates do not exist. Therefore, replication using certificates is not possible before the database is initialized.
  4. After the new server has been initialized:
    1. 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"
    2. 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"
  5. Create a replication agreement on both servers that use certificate-based authentication:
    1. 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
    2. 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
  6. To verify the replication works correctly, display the nsds5replicaLastUpdateStatus attribute 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.
  1. 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.
  2. Edit the replication agreement, and add the nsds5BeginReplicaRefresh attribute: 
    # 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
    ldapmodify does not prompt for input; simply type in the LDIF statement, and then hit enter twice when the LDIF statement is complete. Close the ldapmodify utility 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.18.3, “Initializing Consumers Online Using the Command Line”. Manually initializing consumers is explained in Section 15.18.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.