11.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 11.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 the supplier replicas (Section 11.7.1, “Configuring Suppliers from the Command Line”).
  4. Configure consumers (Section 11.7.2, “Configuring Consumers from the Command Line”).
  5. Configure hubs for cascading replication (Section 11.7.3, “Configuring Hubs from the Command Line”).
  6. Create the replication agreements (Section 11.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.
  7. Lastly, initialize all of the consumers (Section 11.7.5, “Initializing Consumers Online from the Command Line”), if the consumers were not initialized when the replication agreement was created.

11.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 entry.

    Example 11.2. Example Changelog Entry

    [root@server ~]# 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_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 11.1, “Changelog Attributes”. These attributes are described in more detail in the Directory Server Configuration and Command-Line Tool Reference.
  2. Create the supplier replica.

    Example 11.3. Example Supplier Replica Entry

    [root@server ~]# 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
    • 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 11.2, “Replica Attributes”.
After creating every supplier which will take part in the replication setup, then begin creating the replication agreements.

Table 11.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 11.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 be set to 65535 for consumers or hubs. For suppliers, this value must be a unique value.
1 to 65534, inclusive, for suppliers.
65535 for consumers and hubs.
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.
The URL can use the format ldap[s]://hostname:port or ldap[s]://IP_address:port, with IPv4 or IPv6 addresses.
Any LDAP URL. For example: 
nsds5replicareferral: ldap://supplier1.example.com:389
nsDS5ReplicaReleaseTimeout: seconds Optional. Sets the timeout in seconds after which a master releases a replica. From 0 to the maximum 32-bit integer: 2147483647. To disable the timeout, set the value to 0. The default value is 60 seconds.

11.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. 
[root@server ~]# ldapmodify -D "cn=directory manager" -W -x -h consumer1.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: 65535
nsds5replicatype: 2
nsds5ReplicaBindDN: cn=replication manager,cn=config
nsds5flags: 0
The replica entry attributes are described in Table 11.2, “Replica Attributes”. These attributes are described in more detail in the Directory Server Configuration and Command-Line Tool Reference.

11.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 11.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 entry. 
    [root@server ~]# 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_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 11.1, “Changelog Attributes”. These attributes are described in more detail in the Directory Server Configuration and Command-Line Tool 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. 
    [root@server ~]# 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
    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.
    • nsds5replicaid sets the ID of the replica. This must be set to 65535 for consumers or hubs.
    • 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 11.2, “Replica Attributes”. These attributes are described in more detail in the Directory Server Configuration and Command-Line Tool Reference.

11.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 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 11.4. 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
nsds5BeginReplicaRefresh: start
The replication agreement attributes are listed in Table 11.3, “Replication Agreement Attributes”. These attributes are described in more detail in the Directory Server Configuration and Command-Line Tool Reference.
After creating every replication agreement, begin initializing consumers.

Table 11.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 host name of the consumer server; the host name can be the fully qualified host and domain name. If TLS/SSL is enabled, the fully-qualified domain name is required.
It is also possible to use IPv4 or IPv6 addresses instead of the host name.
Any host name. 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, 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, 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 supplier server have a Kerberos keytab (as in Section 7.12.2.2, “About the KDC Server and Keytabs”), and the consumer server have a SASL mapping to map the supplier's principal to the real replication manager entry (as in Section 7.11.3.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.

Note

If secure binds are required for simple password authentication (Section 14.8.1, “Requiring Secure Binds”), then any replication operations will fail unless they occur over a secure connection. Using a secure connection (SSL/TLS and Start TLS connections or SASL authentication) is recommended, anyway.
SIMPLE
SSLCLIENTAUTH
SASL/GSSAPI
SASL/DIGEST-MD5
nsDS5ReplicaCredentials: 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.
If this is the only fractional replication attribute set, then it applies to both incremental and total updates. If nsDS5ReplicatedAttributeListTotal is set, then this attribute applies to incremental updates. 
'(objectclass=*)' $ EXCLUDE authorityRevocationList memberof accountUnlockTime
nsds5replicatedattributelisttotal: '(objectclass=*)' $ EXCLUDE attributes Optional. Sets which attributes will not be replicated during a total update.
The nsDS5ReplicatedAttributeList attribute must be set for incremental updates before these attributes can be set for total updates. 
'(objectclass=*)' $ EXCLUDE accountUnlockTime
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.

11.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 -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: 
    [root@server ~]# 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 11.15.3, “Initializing Consumers Online Using the Command Line”. Manually initializing consumers is explained in Section 11.15.4, “Manual Consumer Initialization Using the Command Line”. The replication monitoring attributes are described in more detail in the Directory Server Configuration and Command-Line Tool 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.