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.
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
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.
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
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 the supplier holds onto its change record before deleting it. 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-.
|
| 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. |
|
||
| nsds5flags: number | Sets whether the replica writes to the changelog. |
|
||
| nsds5ReplicaPurgeDelay: number | Sets the period of time in seconds to wait before purging the entries from the changelog. This is not required for consumers, but is required for hubs and suppliers. |
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.
NOTEFor 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
.
|
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.
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 the hub holds onto its change record before deleting it. 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.
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
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
The times are given in 24 hour clock format, so 0000 is midnight and 2359 is 11:59 PM. For example, the setting
The days ranging from nsds5replicaupdateschedule:
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; any other value is ignored.
|
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.
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 i386. For the default location on other platforms, see Section 1.1, “Directory Server File Locations”.