8.7. 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 8.3, “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 hubs for cascading replication (Section 8.7.3, “Configuring Hubs from the Command Line”).
  4. Create the replication agreements (Section 8.7.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.
  5. Lastly, initialize all of the consumers (Section 8.7.5, “Initializing Consumers Online from the Command Line”), if the consumers were not initialized when the replication agreement was created.

8.7.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[14] entry.

    Example 8.2. Example Changelog Entry

    /usr/lib/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h supplier1.example.com -v
    
    dn: cn=changelog5,cn=config
    changetype: add
    objectclass: top
    objectclass: extensibleObject
    cn: changelog5
    nsslapd-changelogdir: /var/lib/dirsrv/slapd-instance_name/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 Table 8.1, “Changelog Attributes”. These attributes are described in more detail in the Directory Server Configuration and Command Reference.
  2. Create the supplier replica.

    Example 8.3. Example Supplier Replica Entry

    /usr/lib/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h supplier1.example.com -v
    
    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

    • nsds5replicaroot sets the subtree (suffix) which is being replicated.
    • nsds5replicatype sets what kind of replica this database is. For either a single master or a multi-master supplier, this value must be 3.
    • nsds5replicaid sets the replica ID. The value must be unique among all suppliers and hubs; the valid range is 1 to 65534.
    • nsds5ReplicaPurgeDelay sets how long an entry holds its status information or how long a tombstone entry is kept before deleting the information. The default value is 604800 (one week).
    • nsds5flags sets whether the replica writes to the changelog. For a supplier, this value must be 1.
    The replica entry attributes are described in Table 8.2, “Replica Attributes”.
After creating every supplier which will take part in the replication setup, then begin creating the replication agreements.

Table 8.1. Changelog Attributes

Object Class or Attribute Description Values
objectclass: top Required object class for every entry.
objectclass: extensibleObject An object class which allows any other object class or attribute to be added to an entry.
cn: changelog5 The naming attribute for the changelog entry. Any string; the default usage is to set the common name to changelog5.
nsslapd-changelogdir: directory Sets the file and directory changelog, to which the Directory Server writes changes. Any directory; the default is /var/lib/dirsrv/slapd-instance_name/changelogdb.
nsslapd-changelogmaxage: number unit Sets how long the changelog keeps an entry before purging it. This is not used by consumers, but is recommended for hubs and suppliers, which keep changelogs.
The number is any integer.
The unit can be s for seconds, m for minutes, h for hours, d for days, or w for weeks.

Table 8.2. Replica Attributes

Object Class or Attribute Description Values
objectclass: top Required object class for every entry.
objectclass: extensibleObject An object class which allows any other object class or attribute to be added to an entry.
objectclass: nsds5replica An object class which allows replication attributes to be added to an entry.
cn: replica The naming attribute for the replica. Any string; the default usage is to set the common name to replica for every configured replica.
nsds5replicaroot: suffix Sets which subtree is replicated. A root suffix associated with a database, since the entire database is replicated. For example:
dc=example,dc=com
nsds5replicaid: number The ID of the replica. This must not be set for consumers or hubs, but is required for suppliers. 1 to 65534, inclusive.
nsds5replicatype: number Sets the type of replica, either read-only or read-write.
2 for consumers and hubs (read-only replicas)
3 for both single and multi-master suppliers (read-write replicas)
nsds5flags: number Sets whether the replica writes to the changelog.
0 means the replica does not write to the changelog; this is the default for consumers.
1 means the relics writes to the changelog; this is the default for hubs and suppliers.
nsds5ReplicaPurgeDelay: number Sets the period of time in seconds to wait before purging the state information from an entry or purging tombstone entries. This setting is required for all types of replicas — suppliers, hubs, and consumers. 0 (keep forever) to 2147483647 (the maximum 32-bit integer); the default value is 604800, one week.
nsds5ReplicaBindDN: DN The supplier bind DN used by the supplier to bind to the consumer. This is required for consumers, hubs, and multi-master suppliers, but not for single-master suppliers. Any DN; the recommended DN is cn=Replication Manager,cn=config.

NOTE

For security, it is strongly recommended that you do not use the Directory Manager as the supplier bind DN.
nsds5replicareferral: URL Optional. An LDAP URL which a consumer or hub to which a consumer or hub can forward update requests. By default, update requests are sent to the masters for the consumer; use this parameter to override the default. Any LDAP URL. For example:
nsds5replicareferral: 
     ldap://supplier1.example.com:389
.

8.7.2. Configuring Consumers from the Command Line

On the consumer host, such as consumer1.example.com, create the replica entry. This entry identifies the database and suffix as participating in replication and sets what kind of replica the database is. There are four key attributes:
  • nsds5replicaroot sets the subtree (suffix) which is being replicated.
  • nsds5replicatype sets what kind of replica this database is. For a consumer, this value must be 2.
  • nsds5ReplicaBindDN give the DN as which the supplier will bind to the consumer to make changes.
  • nsds5flags sets whether the replica writes to the changelog. For a consumer, this value must be 0.
This ldapmodify creates a new consumer replica on the consumer1.example.com host for the dc=example,dc=com subtree.
/usr/lib/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h consumer1.example.com -v

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
nsds5replicatype: 2
nsds5ReplicaBindDN: cn=replication manager,cn=config
nsds5flags: 0
The replica entry attributes are described in Table 8.2, “Replica Attributes”. These attributes are described in more detail in the Directory Server Configuration and Command Reference.

8.7.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 8.2.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[14] entry.
    /usr/lib/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h hub1.example.com -v
    
    dn: cn=changelog5,cn=config
    changetype: add
    objectclass: top
    objectclass: extensibleObject
    cn: changelog5
    nsslapd-changelogdir: /var/lib/dirsrv/slapd-instance_name/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 Table 8.1, “Changelog Attributes”. These attributes are described in more detail in the Directory Server Configuration and Command 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.
    /usr/lib/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h hub1.example.com -v
    
    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
    nsds5replicatype: 2
    nsds5ReplicaPurgeDelay: 604800
    nsds5ReplicaBindDN: cn=replication manager,cn=config
    nsds5flags: 1
    This entry identifies the database and suffix as participating in replication and sets what kind of replica the database is. There are five key attributes:
    • nsds5replicaroot sets the subtree (suffix) which is being replicated.
    • nsds5replicatype sets what kind of replica this database is. For a hub, this value must be 2.
    • nsds5ReplicaPurgeDelay sets how long an entry holds its status information or how long a tombstone entry is kept before deleting the information. The default value is 604800 (one week).
    • nsds5ReplicaBindDN give the DN as which the supplier will bind to the hub to make changes.
    • nsds5flags sets whether the replica writes to the changelog. For a hub, this value must be 1.
The replica entry attributes are described in Table 8.2, “Replica Attributes”. These attributes are described in more detail in the Directory Server Configuration and Command Reference.

8.7.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 seven things:
  • 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), and any credentials required (nsds5replicabindcredentials).
  • The subtree being replicated (nsds5replicaroot).
  • The replication schedule (nsds5replicaupdateschedule).
  • Any attributes which will not be replicated (nsds5replicatedattributelist).
Use ldapmodify to add a replication agreement to every supplier for every consumer which it will updated. For example:

Example 8.4. Example Replication Agreement Entry

dn: cn=ExampleAgreement,cn=replica,cn="dc=example,dc=com",cn=mapping tree,cn=config
changetype: add
objectclass: top
objectclass: nsds5replicationagreement
cn: ExampleAgreement
nsds5replicahost: consumer1
nsds5replicaport: 389
nsds5ReplicaBindDN: cn=replication manager
nsds5replicabindmethod: SIMPLE
nsds5replicaroot: dc=example,dc=com
description: agreement between supplier1 and consumer1
nsds5replicaupdateschedule: 0000-0500 1
nsds5replicatedattributelist: (objectclass=*) $ EXCLUDE authorityRevocationList
nsds5replicacredentials: secret
nsds5BeginReplicaRefresh: start

The replication agreement attributes are listed in Table 8.3, “Replication Agreement Attributes”. These attributes are described in more detail in the Directory Server Configuration and Command Reference.
After creating every replication agreement, begin initializing consumers.

Table 8.3. Replication Agreement Attributes

Object Class or Attribute Description Values
objectclass: top Required object class for every entry.
objectclass: nsds5replicationagreement An operational object class which contains the replication agreement attributes.
cn: agreement_name The naming attribute for the replication agreement. Any string.
nsds5replicahost: hostname Gives the hostname of the consumer server; the hostname can be the fully qualified host and domain name. If TLS/SSL is enabled, the fully-qualified domain name is required. Any hostname. For example:
nsds5replicahost: consumer1
nsds5replicaport: number
Gives the LDAP port for the consumer server.
To use TLS/SSL, give the secure port number (636 by default) and set the nsds5ReplicaTransportInfo attribute to SSL.
To use Start TLS, which initiates a secure connection over a standard port, use the standard port, 389, with the nsds5ReplicaTransportInfo attribute to TLS.
To use simple authentication or SASL, use the standard port, 389, with the nsds5ReplicaTransportInfo attribute to LDAP.
Any port number.
nsds5replicatransportinfo: method
To use TLS/SSL, set this parameter to SSL.
To use Start TLS, which initiates a secure connection over a standard port, set this parameter to TLS.
To use simple authentication or SASL, set this parameter to LDAP.
empty or LDAP (standard connection over port 389)
SSL (secure connection over the secure port, such as 636)
TLS (secure connection over the standard port, 389, using Start TLS)
nsds5ReplicaBindDN: DN The supplier bind DN used by the supplier to bind to the consumer. This is required for consumers, hubs, and multi-master suppliers, but not for single-master suppliers. Any DN; the recommended DN is cn=Replication Manager,cn=config.
nsds5replicabindmethod: type
The connection type for replication between the servers. The connection type defines how the supplier authenticates to the consumer.
Leaving the bind method empty or setting it to SIMPLE means that the server uses basic password-based authentication. This requires the nsds5ReplicaBindDN and nsds5ReplicaCredentials attributes to give the bind information.
The SSLCLIENTAUTH option uses a secure connection. This requires setting the nsds5ReplicaTransportInfo attribute be set to SSL or TLS. For certificate-based authentication, the consumer server must also have a certificate mapping to map the subject DN in the supplier's certificate to the replication manager entry.
Using SASL/GSSAPI requires that the nsds5ReplicaTransportInfo attribute is set to LDAP; Directory Server does not support using GSS-API over SSL/TLS. The supplier server must have a Kerberos keytab (as in Section 13.1.4.2, “About the KDC Server and Keytabs”), and the consumer server must have a SASL mapping to map the supplier's principal to the real replication manager entry (as in Section 13.2.1, “Configuring SASL Identity Mapping from the Console”).
The SASL/DIGEST-MD5 setting, like SIMPLE, uses password-based authentication and requires the nsds5ReplicaBindDN and nsds5ReplicaCredentials attributes to give the bind information.
SIMPLE
SSLCLIENTAUTH
SASL/GSSAPI
SASL/DIGEST-MD5
nsds5replicabindcredentials: hash Only for simple authentication. Stores the hashed password used with the bind DN given for simple authentication.
nsds5replicaroot: suffix Sets which subtree is replicated. A root suffix associated with a database, since the entire database is replicated. For example:
dc=example,dc=com
description: text A text description of the replication agreement. Any text string. It is advisable to make this a useful description, such as agreement between supplier1 and consumer1.
nsds5replicatedattributelist: '(objectclass=*)' $ EXCLUDE attributes Optional. Sets which attributes will not be replicated. The filter must be set to "(objectclass=*)", and the list of attributes are separated by a single space.
'(objectclass=*)' $ EXCLUDE userPassword manager cn
nsds5replicaupdateschedule: start_time end_time days
Sets the start and end time for the replication updates and the days on which replication occurs. If the schedule is omitted, replication will take place all the time.
The replication schedule cannot cross midnight (0000). So, it is possible to set a schedule that begins at 0001 and ends at 2359 on the same day, but it is not possible to set one that begins at 2359 on one day and ends at 0001 on the next.
Has the following value, with the start (SSSS) and end (EEEE) times set in the form HHMM
The times are given in 24 hour clock format, so 0000 is midnight and 2359 is 11:59 PM. For example, the setting 1030 1630 schedules replication from 10:30 AM to 4:30 PM. The times cannot wrap around midnight, so the setting 2300 0100 is not valid.
The days ranging from 0 (Sunday) to 6 (Saturday). Setting 06 schedules replication on Sunday and Saturday, while 135 schedules replication on Monday, Wednesday, and Friday.
nsds5replicaupdateschedule: 
     SSSS EEEE DDDDDDD
For example, this schedules replication between midnight (0000) and 5am (0500) on Monday and Tuesday:
nsds5replicaupdateschedule: 
     0000 0500 12
nsds5BeginReplicaRefresh: start
Optional. Performs an online (immediate) initialization of the consumer. If this is set, the attribute is only present as long as the consumer is being initialized; when the initialization is complete, the attribute is deleted automatically.
If this is not set, then consumer initialization must be performed manually.
start
To initialize the consumer, this attribute must have a value of start; any other value is ignored.

8.7.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 -h supplier1.example.com -p 389 -D "cn=directory manager" -w secret -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:
    /usr/lib/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -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.
Initializing consumers from the command line is also explained in Section 8.10.3, “Initializing Consumers Online Using the Command Line”. Manually initializing consumers is explained in Section 8.10.4, “Manual Consumer Initialization Using the Command Line”. The replication monitoring attributes are described in more detail in the Directory Server Configuration and Command 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 nsIdleTimeoutt 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.


[14] The file location here is the default location for Red Hat Enterprise Linux 5 (32-bit). For the default location on other platforms, see Section 1.1, “Directory Server File Locations”.