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:

Create the supplier bind DN on every consumer, hub, and multi-master supplier (Section 8.3, “Creating the Supplier Bind DN Entry”).
If the corresponding database and suffix do not exist on one of the replicas, create it (Section 3.1.1, “Creating Suffixes”).
Configure the supplier replicas (Section 8.7.1, “Configuring Suppliers from the Command Line”).
Configure consumers (Section 8.7.2, “Configuring Consumers from the Command Line”).
Configure hubs for cascading replication (Section 8.7.3, “Configuring Hubs from the Command Line”).
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.
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.

On the supplier server, use ldapmodify to create the changelog^[8] entry.
```
ldapmodify -v -h supplier1.example.com -p 389 -D "cn=directory manager" -w password

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
```
Example 8.2. Example Changelog Entry
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, Command, and File Reference.
Create the supplier replica.
```
ldapmodify -v -h supplier1.example.com -p 389 -D "cn=directory manager" -w password

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
```
Example 8.3. Example Supplier Replica Entry
- 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.

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

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 — supliers, 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

Table 8.2. Replica Attributes

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.

ldapmodify -v -h consumer1.example.com -p 389 -D "cn=directory manager" -w password

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, Command, and File 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.

On the hub server, such as hub1.example.com, use ldapmodify to create the changelog^[8] entry.
```
ldapmodify -v -h hub1.example.com -p 389 -D "cn=directory manager" -w password

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, Command, and File Reference.
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 -v -h hub1.example.com -p 389 -D "cn=directory manager" -w password

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, Command, and File 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:

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: {DES}UXRbhvozeN9LWdueOEbPeQ==
nsds5BeginReplicaRefresh: start

Example 8.4. Example Replication Agreement Entry

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, Command, and File Reference.

After creating every replication agreement, begin initializing consumers.

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. Any port number.

nsds5replicatransportinfo: method To use TLS/SSL, set this parameter to SSL. If TLS/SSL is not used, this attribute can be absent. SSL

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. SIMPLE or SSLCLIENTAUTH

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.

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.

Table 8.3. Replication Agreement Attributes

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.

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 password -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 nsds5BeginReplicaRefresh attribute:
```
ldapmodify -h supplier1.example.com -p 389 -D "cn=directory manager" -w password

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.

NOTE

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, Command, and File Reference.

To keep data integrity, initialize the consumer databases from the appropriate supplier. Depending on the replication scenario, this 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.

^[8] 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”.