Introduction

The Tivoli Directory Server ships with a Web Administration tool. This tool has numerous applications, one of which is setting up replication topologies. The tool helps administrators with a simple point and click interface to set up complex replication topologies. It has a credential management panel and topology visualization. In some instances though, the use of the command line tools becomes imperative. This can be due to the following reasons:

1. The administrator does not have access to the Web Administration tool.
2. It is easier for support personnel to mention command line steps rather than visual steps.
3. The end user is comfortable using command line tools rather than graphical user interfaces (GUIs).

In any of the above scenarios, it is necessary that administrators understand the concepts and data structures that TDS replication works with; this article can be a starting point. We deliberately attempted not to include definitions in the article. Rather, it takes a bottom-up approach by looking at the entries and then explaining their role in the topology. For practical purposes, the article leads the reader through three commonly used set ups. Administrators can use the steps that we take for building the set ups as an example when designing your own topologies. The definitions and basic concepts that drive replication have been covered in another article titled "Debugging replication in IBM Tivoli Directory Server". The link for that article is in the Resources section.

Back to top

Sample topologies

The master to replica topology is one of the most common topologies. It is the most basic topology and is easy to set up. It has one read-write server and one read-only server.

The peer to peer topology is the second most common topology used. It is mostly used in high availability applications as it has two read-write servers.

Though not used frequently, we included this topology as the Forwarder is a special type of server. It is a read-only server which acts as a "router" to a set of replicas under it.

Back to top

The infrastructure

This section puts the primary data in place. The hostnames, IP addresses, ports, server IDs and passwords need to be assumed, because this does not build real topologies. In real scenarios, these are derived from the actual infrastructure.

1. Hostnames and ports: These provide the supplier with enough information to connect to the consumer.
2. Server IDs: These IDs are strings that enable one LDAP server to identify other LDAP servers in the topology.
3. Bind DNs and Passwords: The supplier connects to the consumer using the LDAP protocol. In LDAP terminology this is called a bind. The bind requires a bind Distinguished Name (DN) and a password.

This article requires a maximum of three servers for the topologies to be covered.

Note: The host name of the consumer should be resolve correctly from the supplier. If not, the supplier cannot connect to the consumer and replication will fail.

All the servers have LDAP servers listening on port 389, which is the default LDAP port. If you are using version 6.0 and have multiple instances, the port numbers might be different.

To do an LDAP bind to the consumer, the supplier requires a bind DN and a bind password. This article assumes the following bind DN and password for all supplier-consumer agreements:

• DN: cn=bindtoconsumer
• Password: iamsupplier

The server ID of each server will be the role of that server in the topology. That is, in the Master-Replica topology, the master will identify the server ID as Master and the replica will be identified as Replica. In the Peer-Peer topology, one peer will be Peer1 and the other will be Peer2. In the Master-Forwarder-Replica topology, the master will be Master, the forwarder will be Forwarder and the replica will be Replica.

Back to top

Replication related entries

This section covers the various types of entries that are used to build a replication topology.

Note: The article does not cover advanced replication topics like replication schedules and SSL-based replication. Therefore, entries for these features will not be mentioned here.

On the supplier side:

• Replication context: This is the entry for the subtree that is to be replicated. It has to have an objectclass called as the ibm-replicationContext. To replicate a subtree (o=ibm,c=in) the replication context will look the example below:
  
  Example replication context
  

  dn: o=ibm, c=in objectclass: top objectclass: organization objectclass: ibm-replicationContext o: ibm

  
  

  All other replication entries except for the credential and schedule entries have to be under the replication context. The credential and schedule entries can be anywhere in the Directory Information Tree (DIT).

• Replica group: This entry is not very important apart from the fact that all the replication related entries exist under this entry. It has to have The ibm-replicaGroup objectclass must be here.
  
  Example replica group
  

  dn: ibm-replicaGroup=default, o=ibm, c=in objectclass: top objectclass: ibm-replicaGroup ibm-replicaGroup: default

  
  
• Replication subentry: These types of entries declare the servers that will be taking part in the replication topology. Each server participating in the topology has one subentry. The entry has the ibm-replicaSubentry objectclass.
  
  Example replica subentry
  

  dn: ibm-replicaServerId=Peer1,ibm-replicaGroup=default, o=ibm, c=in objectclass: top objectclass: ibm-replicaSubentry ibm-replicaServerId: Peer1 ibm-replicationServerIsMaster: true cn: Peer1 description: Peer1

  
  

  As you can see in the above entry, the entry has the server ID of the participating server, Peer1. It has an attribute called ibm-replicationServerIsMaster. This attribute when set to TRUE, means that this server will be a read-write copy.

• Agreements: These types of entries occur under replica subentries. When these entries appear under a specific server's replica subentry, they define a replication agreement from that server to some other server in the topology.
  
  Example replication agreement
  

  dn: cn=Peer2, ibm-replicaServerId=Peer1,ibm-replicaGroup=default,o=ibm,c=in objectclass: top objectclass: ibm-replicationAgreement cn: peer2 ibm-replicaConsumerId: Peer2 ibm-replicaUrl: ldap://server2.in.ibm.com:389 ibm-replicaCredentialsDN: cn=Peer1BindCredentials, cn=localhost description: Replication agreement from Peer1 to Peer2

  
  

  The agreement above is from Peer1 to Peer2. The supplier is Peer1 as the agreement occurs under the subentry for Peer1. The consumer is Peer2. The server Peer2 is on server2.in.ibm.com and is listening on port 389. Peer1 will bind to Peer2 using the credentials defined in the entry (cn=Peer1BindCredentials,cn=localhost).

• Credentials: These entries define the bind DN and password that a supplier uses to bind to a consumer when an agreement for this relationship is defined. These entries have the ibm-replicationCredentialsSimple objectclass in them.
  
  Example replication credential
  

  dn: cn=Peer1BindCredentials, o=ibm, c=in objectclass: ibm-replicationCredentialsSimple cn: ReplicaBindCredentials replicaBindDN: cn=bindtoconsumer replicaCredentials: iamsupplier description: Bind Credentials on Peer1 to be used to bind to other servers.

  
  

  The entry above defines the replicaBindDN to be cn=bindtoconsumer and the password to be iamsupplier. Note the description. The same credential entry can be used for multiple replication agreements.

On the consumer side:

• On the consumer side, only one replication related entry is needed. This entry is used by the consumer to authenticate the supplier when it tries to bind to the consumer, for replication to be initialized. There are two types of credential entries that can be used on the consumer:

  
  
  Example consumer side replication credential - Type 1
  

  dn: cn=Master server, cn=configuration cn: master server ibm-slapdMasterDN: cn=bindtoconsumer ibm-slapdMasterPW: iamsupplier ibm-slapdMasterReferral: ldap://localhost:1389 objectclass: ibm-slapdReplication

  
  

  
  
  Example consumer side replication credential - Type 2
  

  dn: cn=Supplier s1, cn=configuration cn: Supplier s1 ibm-slapdMasterDN: cn=bindtoconsumer ibm-slapdMasterPW: iamsupplier ibm-slapdReplicaSubtree: o=ibm, c=in objectclass: ibm-slapdSupplier

  
  

  The latter type of consumer side credential entry was introduced with subtree replication. The use of that credential is limited to the ibm-slapdReplicaSubtree only. Therefore, suppliers binding with user-id as "cn=bindtoconsumer" and password as "iamsupplier" will supply only to the (o=ibm,c=in) subtree, unless another credential entry gives rights to another subtree. The former type of credential entry is global across the LDAP server. If that type of entry is defined in a server's configuration file, any subtree can be supplied to if a supplier binds with user-id as "cn=bindtoconsumer" and password as "iamsupplier"

  Note: The consumer side credential entry must be present on the consumer in addition to the replication topology itself. The topology entries are the only way for the servers to know their roles in the topology as a whole and hence are needed on all the servers in the topology. Also, the consumer side credential entries are the only type of replication-related entries that exist in the configuration file. If these entries are changed, you must restart the server for the changes to be effective.

Back to top

Building topology 1 (Master-Replica)

The next step is to build the most basic of all the topologies - the Master-Replica topology. The first step when building a topology is to define:

1. Replication context: (o=ibm,c=in)
2. Supplier(s): LDAP server on server1.in.ibm.com:389 will be the only supplier. The server ID is Master. It will supply updates to the LDAP server on server2.in.ibm.com:389.
3. Consumer(s): LDAP server on server2.in.ibm.com:389 will be the only consumer. The server ID is Replica. It will consume updates from the LDAP server on server1.in.ibm.com:389
4. Read-write server(s): LDAP server on server1.in.ibm.com:389, with ID Master will be the only read-write server.
5. Read-only server(s): LDAP server on server2.in.ibm.com:389, with ID Replica will be the only read-only server.

Configuration changes: Some configuration changes are needed for the master and the replica server for replication to work correctly.

1. Server IDs:
   • Open the ibmslapd.conf file for the master server. Search for the ibm-slapdServerId attribute. Change it to "Master".
   • Open the ibmslapd.conf file for the replica server. Search for the ibm-slapdServerId attribute. Change it to "Replica".

2. Consumer side credential entry: Add this entry to the ibmslapd.conf file for the replica server.

   
   
   Credential entry on the replica
   

   dn: cn=Master server, cn=configuration cn: master server ibm-slapdMasterDN: cn=bindtoconsumer ibm-slapdMasterPW: iamsupplier ibm-slapdMasterReferral: ldap://server1.in.ibm.com:389 objectclass: ibm-slapdReplication

   
   

3. Restart the master and replica servers.

Note: Be careful with server IDs. If a server ID is being used in some other topology, changing the server ID can lead to unwanted consequences. It is advisable to use generic server IDs in such a case. For example: Server1 rather than Master. In this article, we will assume that (o=ibm,c=in) is the only subtree being replicated. Hence topology specific server IDs will be used.

The next step is to build the LDAP Data Interchange Format (LDIF) file for the topology. This LDIF file will be called, masterreplica.ldif. Simply copy each of these entries to masterreplica.ldif with the necessary changes in the subtree, server IDs, host names and ports:

1. Replication context:
   • If the subtree entry already exists:
     
     Creating a replication context from an existing entry
     

     dn: o=ibm, c=in changetype: modify add: objectclass objectclass: ibm-replicationContext

     
     
   • If the subtree entry does not exist:
     
     Adding a subtree entry which has the attributes needed to define a replication context
     

     dn: o=ibm, c=in changetype: add objectclass: top objectclass: organization objectclass: ibm-replicationContext o: ibm

     
     
2. Replica group:
   
   Adding a replica group
   

   dn: ibm-replicaGroup=default, o=ibm, c=in changetype: add objectclass: top objectclass: ibm-replicaGroup ibm-replicaGroup: default

   
   
3. Replica subentries:

   Because there are two LDAP servers in the topology, you need to add two replica subentries:

   
   
   Subentry for the master
   

   dn: ibm-replicaServerId=Master,ibm-replicaGroup=default, o=ibm, c=in changetype: add objectclass: top objectclass: ibm-replicaSubentry ibm-replicaServerId: Master ibm-replicationServerIsMaster: true cn: Master description: Master server of the topology.

   
   

   
   
   Subentry for the replica
   

   dn: ibm-replicaServerId=Replica,ibm-replicaGroup=default, o=ibm, c=in changetype: add objectclass: top objectclass: ibm-replicaSubentry ibm-replicaServerId: Replica ibm-replicationServerIsMaster: false cn: Replica description: Replica server of the topology.

   
   

   Note the subentries carefully. The subentry for the master uses the server ID ”Master” and has the server declared as a “master server”. This server can receive updates from clients. The subentry for the replica has the server ID of Replica and has the server declared as a non-master server. This server cannot receive updates from LDAP clients that bind to it.

   Note: The number of subentries is not dependent on the number of physical servers in the topology. Rather, it is dependent on the number of LDAP servers in the topology.

4. Credentials: This step will define the credentials that the master will use to bind to the replica. Add an entry that looks like the one below:
   
   Credentials used by master to bind to replica
   

   dn: cn=ReplicaBindCredentials, o=ibm, c=in changetype: add objectclass: ibm-replicationCredentialsSimple cn: ReplicaBindCredentials replicaBindDN: cn=bindtoconsumer replicaCredentials: iamsupplier description: Bind Credentials on master to bind to replica.

   
   

   Note that the DN and password are the same as the pair that was added in the configuration section above.

5. Replication agreements: There is one supplier-consumer relationship in this topology. The Master supplies updates to the (o=ibm,c=in) subtree to the replica which consumes the changes. So there will be just one agreement: From the master to the replica. Note that the number of agreements is dependent upon the number of supplier-consumer relationships in the topology.
   
   Replication agreement from the master to the replica
   

   dn: cn=Replica, ibm-replicaServerId=Master,ibm-replicaGroup=default,o=ibm,c=in changetype: add objectclass: top objectclass: ibm-replicationAgreement cn: Replica ibm-replicaConsumerId: Replica ibm-replicaUrl: ldap://server2.in.ibm.com:389 ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm, c=in description: Replication agreement from master to replica.

   
   

   The entry above lies under the subentry for the master. It supplies to a consumer with an ID as Replica. The replica URL is ldap://server2.in.ibm.com:389 meaning the replica is listening on server2.in.ibm.com on port 389. This agreement will use the credentials that we created in the last step for the master to bind to the replica. That means the master will bind to the replica with a bind DN cn=bindtoconsumer and the password iamsupplier.

   Note that there is no agreement under the subentry for the replica. This is natural as the replica is a read-only copy and cannot receive any client updates, so there is no point in having an agreement, because there are no updates to propagate.

Now that the replication entries have been added, the masterreplica.ldif should look like this:

			
dn: o=ibm, c=in
changetype: add
objectclass: top
objectclass: organization
objectclass: ibm-replicationContext
o: ibm

dn: ibm-replicaGroup=default, o=ibm, c=in
changetype: add
objectclass: top
objectclass: ibm-replicaGroup
ibm-replicaGroup: default

dn: ibm-replicaServerId=Master,ibm-replicaGroup=default, o=ibm, c=in
changetype: add
objectclass: top
objectclass: ibm-replicaSubentry
ibm-replicaServerId: Master
ibm-replicationServerIsMaster: true
cn: Master
description: Master server of the topology.

dn: ibm-replicaServerId=Replica,ibm-replicaGroup=default, o=ibm, c=in
changetype: add
objectclass: top
objectclass: ibm-replicaSubentry
ibm-replicaServerId: Replica
ibm-replicationServerIsMaster: false
cn: Replica
description: Replica server of the topology.

dn: cn=ReplicaBindCredentials, o=ibm, c=in
changetype: add
objectclass: ibm-replicationCredentialsSimple
cn: ReplicaBindCredentials
replicaBindDN: cn=bindtoconsumer
replicaCredentials: iamsupplier
description: Bind Credentials on master to bind to replica.

dn: cn=Replica, ibm-replicaServerId=Master,ibm-replicaGroup=default,o=ibm,c=in
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Replica
ibm-replicaConsumerId: Replica
ibm-replicaUrl: ldap://server2.in.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm, c=in
description: Replication agreement from master to replica.

Note that the LDIF will be a bit different if the replication context already exists. Rather than:

dn: o=ibm, c=in
changetype: add
objectclass: top
objectclass: organization
objectclass: ibm-replicationContext
o: ibm
		

it will have:

dn: o=ibm, c=in
changetype: modify
add: objectclass
objectclass: ibm-replicationContext

		

For the sake of simplicity, from the next example, this article assumes that the subtree entry does not exist at all.

Now load the masterreplica.ldif file on the master server. Execute the following command on the master from which the masterreplica.ldif file was created (entire command on one line):

ldapmodify -h server1.in.ibm.com -p 389 -D [administrator DN] -w [administrator password] 
-i masterreplica.ldif -k -l
		

The -l option is a version 6.0 feature. It instructs the server to not replicate the topology now. The -k option sends an administrator control to the server so that the addition of entries continues even when the subtree becomes read-only due to a server ID mismatch. If you are using version 5.2, the ldif2db command should be used with -r set to NO. Now the topology needs to be loaded on the replica too. If you are using version 6.0, the following command can be executed:

ldapexop -h server1.in.ibm.com -p 389 -D [administrator DN] -w [administrator password] 
-op repltopology -rc o=ibm,c=in
		

This is an extended operation called repltopology. It transmits the topology to all the consumers defined under the (o=ibm,c=in) replication context. If using version 5.2, the reader will also need to use ldif2db on the replica , again with -r set to NO.

After the above two commands execute successfully, the Master-Replica topology is ready. The master will accept updates on the (o=ibm,c=in) subtree and propagate them to the replica. The replica will not accept updates. It will return a referral to the master in case a client tries to update it. However, it can handle searches .

Back to top

Building topology 2 (Peer-Peer)

The peer-peer replication topology does not differ much from the master-replica topology. It also has two servers, but both the servers are now read-write servers. They both supply changes to each other. As always, the first step when building a topology is to define:

1. Replication context: (o=ibm,c=in)
2. Supplier(s): LDAP server on server1.in.ibm.com:389 with server ID Peer1 will supply updates to the LDAP server with server ID Peer2 on server2.in.ibm.com:389. LDAP server on server2.in.ibm.com:389 with server ID Peer2 will supply updates to the LDAP server with server ID Peer1 on server1.in.ibm.com:389.
3. Consumer(s): LDAP server with server ID Peer2 on server2.in.ibm.com:389 will consume updates from LDAP server with server ID Peer1 on server1.in.ibm.com:389. LDAP server with Server ID Peer1 on server1.in.ibm.com:389 will consume updates from LDAP server with server ID Peer2 on server2.in.ibm.com:389.
4. Read-write server(s): LDAP servers peer1 and peer2 on server1.in.ibm.com and server2.in.ibm.com will be read-write servers.
5. Read-only server(s): There are no read-only servers in this topology.

Configuration changes: Some configuration changes need to be done to both the peer1 and peer2 servers for replication to work correctly. We are assuming freshly configured servers. If you are using the same servers that you used for the Master-Replica setup, just undo the changes that you made in that section.

1. Server IDs:
   • Open the ibmslapd.conf file for the peer1 server (server1.in.ibm.com). Search for the ibm-slapdServerId attribute. Change it to "Peer1".
   • Open the ibmslapd.conf file for the peer2 server (server2.in.ibm.com). Search for the ibm-slapdServerId attribute. Change it to "Peer2".

2. Consumer side credential entries:

   • Add this entry to the ibmslapd.conf file for the peer1 server.
     
     Credential entry on peer1
     

     dn: cn=Master server, cn=configuration cn: master server ibm-slapdMasterDN: cn=bindtoconsumer ibm-slapdMasterPW: iamsupplier ibm-slapdMasterReferral: ldap://server2.in.ibm.com:389 objectclass: ibm-slapdReplication

     
     
   • Add this entry to the ibmslapd.conf file for the peer2 server.
     
     Credential entry on peer2
     

     dn: cn=Master server, cn=configuration cn: master server ibm-slapdMasterDN: cn=bindtoconsumer ibm-slapdMasterPW: iamsupplier ibm-slapdMasterReferral: ldap://server1.in.ibm.com:389 objectclass: ibm-slapdReplication

     
     

3. Restart the peer1 and peer2 servers.

Now build the LDIF file for the topology. This will be called peer2peer.ldif. Simply copy each of these entries to peer2peer.ldif with the necessary changes in subtree, server IDs, host names and ports:

1. Replication context:
   
   Adding the replication context.
   

   dn: o=ibm, c=in changetype: add add: objectclass objectclass: ibm-replicationContext

   
   
2. Replica group:
   
   Adding a replica group
   

   dn: ibm-replicaGroup=default, o=ibm, c=in changetype: add objectclass: top objectclass: ibm-replicaGroup ibm-replicaGroup: default

   
   
3. Replica subentries:

   Because there are two LDAP servers in the topology, we will need two replica subentries:

   
   
   Subentry for the peer1
   

   dn: ibm-replicaServerId=Peer1,ibm-replicaGroup=default, o=ibm, c=in changetype: add objectclass: top objectclass: ibm-replicaSubentry ibm-replicaServerId: Peer1 ibm-replicationServerIsMaster: true cn: Peer1 description: Subentry for Peer1.

   
   

   
   
   Subentry for the peer2
   

   dn: ibm-replicaServerId=Peer2,ibm-replicaGroup=default, o=ibm, c=in changetype: add objectclass: top objectclass: ibm-replicaSubentry ibm-replicaServerId: Peer2 ibm-replicationServerIsMaster: true cn: Peer2 description: Subentry for Peer2.

   
   

   The subentry for peer1 identifies the server ID as Peer1 and has the server declared as a master server. The server can receive updates from clients. The subentry for the peer2 identifies the server ID as Peer2, and it too has the server declared as a master server. This server can also receive updates from LDAP clients that bind to it.

4. Credentials: To define the credentials that peer1 will use to bind to peer2 add an entry like the one below:
   
   Credentials used by peer1 to bind to peer2 and vice versa
   

   dn: cn=ReplicaBindCredentials, o=ibm, c=in changetype: add objectclass: ibm-replicationCredentialsSimple cn: ReplicaBindCredentials replicaBindDN: cn=bindtoconsumer replicaCredentials: iamsupplier description: Bind Credentials on peer1 and peer2 to bind to each other.

   
   
5. Replication agreements: There are two supplier-consumer relationships in this topology. Peer1 supplies updates made to the (o=ibm,c=in) subtree to Peer2, which consumes the changes. Peer2 on the other hand also accepts updates from clients on the (o=ibm,c=in) subtree and sends them to Peer1, which consumes the changes. So there will be two agreements: From Peer1 to Peer2 and from Peer2 to Peer1. Note that the number of agreements is dependent upon the number of supplier-consumer relationships in the topology.
   
   Replication agreement from the peer1 to peer2
   

   dn: cn=Peer2, ibm-replicaServerId=Peer1,ibm-replicaGroup=default,o=ibm,c=in changetype: add objectclass: top objectclass: ibm-replicationAgreement cn: Peer2 ibm-replicaConsumerId: Peer2 ibm-replicaUrl: ldap://server2.in.ibm.com:389 ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm, c=in description: Replication agreement from peer1 to peer2.

   
   
   
   Replication agreement from peer2 to peer1
   

   dn: cn=Peer1, ibm-replicaServerId=Peer2,ibm-replicaGroup=default,o=ibm,c=in changetype: add objectclass: top objectclass: ibm-replicationAgreement cn: Peer1 ibm-replicaConsumerId: Peer1 ibm-replicaUrl: ldap://server1.in.ibm.com:389 ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm, c=in description: Replication agreement from peer2 to peer1.

   
   

   The two agreements for this topology are shown above. The first one is the agreement from Peer1 to Peer2. It lies under the Peer1 subentry. The second one is from Peer2 to Peer1 and it lies under the Peer2 subentry. Note the use of the same credential entry for both the agreements. This is perfectly acceptable. The credential entry will be added to both peer1 and peer2.

Now that the replication entries have been added, the peer2peer.ldif should look like this:

			
dn: o=ibm, c=in
changetype: add
objectclass: top
objectclass: organization
objectclass: ibm-replicationContext
o: ibm

dn: ibm-replicaGroup=default, o=ibm, c=in
changetype: add
objectclass: top
objectclass: ibm-replicaGroup
ibm-replicaGroup: default

dn: ibm-replicaServerId=Peer1,ibm-replicaGroup=default, o=ibm, c=in
changetype: add
objectclass: top
objectclass: ibm-replicaSubentry
ibm-replicaServerId: Peer1
ibm-replicationServerIsMaster: true
cn: Peer1
description: Subentry for Peer1.

dn: ibm-replicaServerId=Peer2,ibm-replicaGroup=default, o=ibm, c=in
changetype: add
objectclass: top
objectclass: ibm-replicaSubentry
ibm-replicaServerId: Peer2
ibm-replicationServerIsMaster: true
cn: Peer2
description: Subentry for Peer2.

dn: cn=ReplicaBindCredentials, o=ibm, c=in
changetype: add
objectclass: ibm-replicationCredentialsSimple
cn: ReplicaBindCredentials
replicaBindDN: cn=bindtoconsumer
replicaCredentials: iamsupplier
description: Bind Credentials on peer1 and peer2 to bind to each other.

dn: cn=Peer2, ibm-replicaServerId=Peer1,ibm-replicaGroup=default,o=ibm,c=in
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Peer2
ibm-replicaConsumerId: Peer2
ibm-replicaUrl: ldap://server2.in.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm, c=in
description: Replication agreement from peer1 to peer2.

dn: cn=Peer1, ibm-replicaServerId=Peer2,ibm-replicaGroup=default,o=ibm,c=in
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Peer1
ibm-replicaConsumerId: Peer1
ibm-replicaUrl: ldap://server1.in.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm, c=in
description: Replication agreement from peer2 to peer1.

Now load the peer2peer.ldif file on the peer1 server. Execute the following command on the peer1 server from where the peer2peer.ldif file was created(whole command on one line):

ldapmodify -h server1.in.ibm.com -p 389 -D [administrator DN] -w [administrator password] 
-i peer2peer.ldif -k -l
		

Now load the topology on the replica too. On version 6.0 you can execute the following command:

ldapexop -h server1.in.ibm.com -p 389 -D [administrator DN] -w [administrator password] 
-op repltopology -rc o=ibm,c=in
		

On version 5.2, use ldif2db on the replica too, again with -r set to no.

When the above two commands execute successfully, the Peer-Peer topology is ready. Both the peers will accept updates and send them to the other peer.

Building topology 3 (Master-Forwarder-Replica)

Next in line is the master-forwarder-replica replication topology. Some notes about the forwarder: It is a specialized replica. Replicas are read-only. Forwarders are read-only, too. Replicas do not transmit changes that are consumed by them. Forwarders on the other hand, replicate changes that they have consumed. To supply changes further down the topology, forwarders have agreements under their subentries. Consider a forwarder as an electrical distribution board. The board gets its supply from an electrical outlet and then provides two or more outlets to be used.

Note: Gateways are also like electrical distribution boards. The only difference is that forwarders are specialized replicas while gateways are specialized masters.

With this information in hand let us start building the topology. This topology will now need to have one more server included: server3.in.ibm.com As always, the first step when building a topology is to define:

1. Replication context: (o=ibm,c=in)
2. Supplier(s): LDAP server on server1.in.ibm.com:389 with server ID Master will supply updates to the LDAP server with server ID Forwarder on server2.in.ibm.com:389. LDAP server on server2.in.ibm.com:389 with server ID Forwarder will supply updates to the LDAP server with server ID Replica on server3.in.ibm.com:389.
3. Consumer(s): LDAP server with server ID Forwarder on server2.in.ibm.com:389 will consume updates from LDAP server with server ID Master working on server1.in.ibm.com:389. LDAP server with server ID Replica on server3.in.ibm.com:389 will consume updates from the LDAP server with server ID Forwarder working on server2.in.ibm.com:389.
4. Read-write server(s): Only the LDAP server with server ID Master will be a read-write server.
5. Read-only server(s): The LDAP servers with server IDs, Forwarder and Replica will be read-only.

Configuration changes: Some configuration changes need to be made to the master, forwarder and replica servers for replication to work correctly. This section assumes that freshly configured servers are being used. For reusing the same servers that were used for the Master-Replica setup, just undo the changes that were made in that section. For reusing the same servers that were used for the Peer-Peer setup, undo the changes that were made in that section

1. Server IDs:
   • Open the ibmslapd.conf file for the master server (server1.in.ibm.com). Search for the ibm-slapdServerId attribute. Change the attribute to "Master".
   • Open the ibmslapd.conf file for the forwarder server (server2.in.ibm.com). Search for the ibm-slapdServerId attribute. Change the attribute to "Forwarder".
   • Open the ibmslapd.conf file for the replica server (server3.in.ibm.com). Search for the ibm-slapdServerId attribute. Change the attribute to "Replica".

2. Consumer side credential entries:

   • Add this entry to the ibmslapd.conf file for the forwarder server.
     
     Credential entry on the forwarder
     

     dn: cn=Master server, cn=configuration cn: master server ibm-slapdMasterDN: cn=bindtoconsumer ibm-slapdMasterPW: iamsupplier ibm-slapdMasterReferral: ldap://server1.in.ibm.com:389 objectclass: ibm-slapdReplication

     
     
   • Add this entry to the ibmslapd.conf file for the replica server.
     
     Credential entry on the replica
     

     dn: cn=Master server, cn=configuration cn: master server ibm-slapdMasterDN: cn=bindtoconsumer ibm-slapdMasterPW: iamsupplier ibm-slapdMasterReferral: ldap://server1.in.ibm.com:389 objectclass: ibm-slapdReplication

     
     

3. Restart the master, forwarder and replica servers.

We will now build the LDIF file for the topology. We will call this LDIF file, mfr.ldif. Simply copy each of these entries to mfr.ldif with the necessary changes in the subtree, server IDs, host names and ports:

1. Replication context:
   
   Adding the replication context
   

   dn: o=ibm, c=in changetype: add add: objectclass objectclass: ibm-replicationContext

   
   
2. Replica group:
   
   Adding a replica group
   

   dn: ibm-replicaGroup=default, o=ibm, c=in changetype: add objectclass: top objectclass: ibm-replicaGroup ibm-replicaGroup: default

   
   
3. Replica subentries:

   Because there are three LDAP servers in the topology we will need three replica subentries:

   
   
   Subentry for the master
   

   dn: ibm-replicaServerId=Master,ibm-replicaGroup=default, o=ibm, c=in changetype: add objectclass: top objectclass: ibm-replicaSubentry ibm-replicaServerId: Master ibm-replicationServerIsMaster: true cn: Master description: Subentry for Master.

   
   

   
   
   Subentry for the forwarder
   

   dn: ibm-replicaServerId=Forwarder,ibm-replicaGroup=default, o=ibm, c=in changetype: add objectclass: top objectclass: ibm-replicaSubentry ibm-replicaServerId: Forwarder ibm-replicationServerIsMaster: false cn: Forwarder description: Subentry for the Forwarder.

   
   

   
   
   Subentry for the replica
   

   dn: ibm-replicaServerId=Replica,ibm-replicaGroup=default, o=ibm, c=in changetype: add objectclass: top objectclass: ibm-replicaSubentry ibm-replicaServerId: Replica ibm-replicationServerIsMaster: false cn: Replica description: Subentry for the Replica.

   
   

   The subentry for the master identifies the server ID as Master and has the server declared as a master server, that is, the server can receive updates from clients. The subentry for the forwarder identifies the server ID as Forwarder and is declared as a non-master server, it cannot get updates from clients. The subentry for the replica has the server ID mentioned as Replica and is declared as a non-master server, it cannot get updates from clients.

4. Credentials: Now define the credentials that the master will use to bind to the forwarder. Add an entry which looks like below to the mfr.ldif:
   
   Credentials used by the master to bind to the forwarder
   

   dn: cn=ReplicaBindCredentials, o=ibm, c=in changetype: add objectclass: ibm-replicationCredentialsSimple cn: ReplicaBindCredentials replicaBindDN: cn=bindtoconsumer replicaCredentials: iamsupplier description: Bind Credentials on master to bind to forwarder.

   
   
5. Replication agreements: There are two supplier-consumer relationships in this topology. Master supplies updates made to the (o=ibm,c=in) subtree to Forwarder, which consumes the changes and then supplies these changes to the Replica. So there will be two agreements: From Master to Forwarder and from Forwarder to Replica. Again, note that the number of agreements are dependent upon the number of supplier-consumer relationships in the topology.
   
   Replication agreement from Master to Forwarder
   

   dn: cn=Forwarder, ibm-replicaServerId=Master,ibm-replicaGroup=default,o=ibm,c=in changetype: add objectclass: top objectclass: ibm-replicationAgreement cn: Forwarder ibm-replicaConsumerId: Forwarder ibm-replicaUrl: ldap://server2.in.ibm.com:389 ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm, c=in description: Replication agreement from Master to Forwarder.

   
   
   
   Replication agreement from Forwarder to Replica
   

   dn: cn=Replica, ibm-replicaServerId=Forwarder,ibm-replicaGroup=default,o=ibm,c=in changetype: add objectclass: top objectclass: ibm-replicationAgreement cn: Replica ibm-replicaConsumerId: Replica ibm-replicaUrl: ldap://server3.in.ibm.com:389 ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm, c=in description: Replication agreement from Forwarder to Replica.

   
   

   The two agreements for this topology are shown above. The first one is the agreement from Master to Forwarder. It lies under the Master's subentry. The second one is from Forwarder to Replica and it lies under the Forwarder's subentry. Note that we use the same credential entry for both the agreements. That is perfectly acceptable. We will add the credential entry to Master and Forwarder. Now that the replication entries have been added, the mfr.ldif should look like this:

Now that the replication entries have been added, the mfr.ldif should look like this:

			
dn: o=ibm, c=in
changetype: add
objectclass: top
objectclass: organization
objectclass: ibm-replicationContext
o: ibm

dn: ibm-replicaGroup=default, o=ibm, c=in
changetype: add
objectclass: top
objectclass: ibm-replicaGroup
ibm-replicaGroup: default

dn: ibm-replicaServerId=Master,ibm-replicaGroup=default, o=ibm, c=in
changetype: add
objectclass: top
objectclass: ibm-replicaSubentry
ibm-replicaServerId: Master
ibm-replicationServerIsMaster: true
cn: Master
description: Subentry for Master.

dn: ibm-replicaServerId=Forwarder,ibm-replicaGroup=default, o=ibm, c=in
changetype: add
objectclass: top
objectclass: ibm-replicaSubentry
ibm-replicaServerId: Forwarder
ibm-replicationServerIsMaster: false
cn: Forwarder
description: Subentry for the Forwarder.

dn: ibm-replicaServerId=Replica,ibm-replicaGroup=default, o=ibm, c=in
changetype: add
objectclass: top
objectclass: ibm-replicaSubentry
ibm-replicaServerId: Replica
ibm-replicationServerIsMaster: false
cn: Replica
description: Subentry for the Replica.

dn: cn=ReplicaBindCredentials, o=ibm, c=in
changetype: add
objectclass: ibm-replicationCredentialsSimple
cn: ReplicaBindCredentials
replicaBindDN: cn=bindtoconsumer
replicaCredentials: iamsupplier
description: Bind Credentials on master to bind to forwarder.

dn: cn=Forwarder, ibm-replicaServerId=Master,ibm-replicaGroup=default,o=ibm,c=in
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Forwarder
ibm-replicaConsumerId: Forwarder
ibm-replicaUrl: ldap://server2.in.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm, c=in
description: Replication agreement from Master to Forwarder.

dn: cn=Replica, ibm-replicaServerId=Forwarder,ibm-replicaGroup=default,o=ibm,c=in
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Replica
ibm-replicaConsumerId: Replica
ibm-replicaUrl: ldap://server3.in.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm, c=in
description: Replication agreement from Forwarder to Replica.

We will now load the mfr.ldif file on the Forwarder server. Execute the following command on the Master server from which you created the mfr.ldif file (entire command on one line):

ldapmodify -h server1.in.ibm.com -p 389 -D [administrator DN] -w [administrator password] 
-i mfr.ldif -k -l
		

We will now load the mfr.ldif file on the Forwarder server. Execute the following command on the Master server from where you created the mfr.ldif file (whole command on one line):

ldapmodify -h server2.in.ibm.com -p 389 -D [administrator DN] -w [administrator password] 
-i mfr.ldif -k -l
		

Now load the topology on the replica too. For version 6.0 execute the following command on the forwarder:

ldapexop -h server2.in.ibm.com -p 389 -D [administrator DN] -w [administrator password] 
-op repltopology -rc o=ibm,c=in
		

For version 5.2, ldif2db needs to be used on the forwarder and replica, with -r set to no.

When the above commands execute successfully, the Master-Forwarder-Replica topology is ready. The Master will accept updates, which then go to the Forwarder and then to the Replica. If you intend to add another replica to the topology, under the Forwarder, you need to just add another subentry for the replica, and add an agreement from the forwarder to that replica.

Back to top

Some golden rules

1. All peers in a topology need to supply to every other server in the topology unless they are separated by gateways. If they are separated by gateways, all the peers under a gateway need to supply to all other servers including the gateway. This is because peers do not replicate changes supplied by other peers. That would lead to peers receiving the updates they initiated.
2. All gateways in a topology need to supply to each other. There have to be at least two gateways in a topology for them to be useful.

Back to top

More about read-only servers

Read-only servers do not accept updates that clients send. If not, what happens to those update requests ? Check the diagram below:

When the clients send an update request to a read-only server, the server returns the referral to the client. The client can then chase the referral and put the update on that server. Usually, the referral points to a supplier of the read-only server. The credential entry of type 2 does not have a referral. The credential entry type above, came from the previous versions of TDS where subtree replication was not used. The type 2 credential entry was introduced when subtree replication was introduced in version 5.1.

In this case, the replication context is used as the placeholder for the referral. The context entry then looks like below:

Back to top

Reverse engineering replication topologies

This article covers only three replication topologies. But you might want to take a look at more complex topologies. Or you might be interested in analyzing the topology created by the Web Administration tool. Using the concepts mentioned here, it is easy to analyze replication topologies created by the tool. In fact, you can even build a complex topology using the Web Administration Tool (in your test environment), extract the necessary entries and attributes and duplicate the exact set up on the target environment.

Resources

Learn

• Debugging replication in the IBM Tivoli Directory Server
  
  
• A simplified approach to IBM Tivoli Directory Server V5.2 Replication
  
  
• Links to all IBM Tivoli Directory Server documentation.
  
  

Get products and technologies

• Download IBM product evaluation versions and to get application development tools and middleware products from DB2®, Lotus ®, Rational®, Tivoli®, and WebSphere®.
  
  

Discuss

• Check out developerWorks blogs and get involved in the developerWorks community.
  
  

About the authors

Darshan is a System Software Engineer at IBM Software Labs, India. He is working as part of the IBM Tivoli Directory Server L2 Support team. Previously, he worked for the Component Verification Team for TDS for almost a year. Replication and distributed directories are his interests.

Neelam is a Systems Software Engineer with the TDS test team at IBM Software Labs, India. She has worked with most directory components. She is interested in replication and the proxy server.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Sample topologies
• The infrastructure
• Replication related entries
• Building topology 1 (Master-Replica)
• Building topology 2 (Peer-Peer)
• Building topology 3 (Master-Forwarder-Replica)
• Some golden rules
• More about read-only servers
• Reverse engineering replication topologies
• Resources
• About the authors
• Comments

Dig deeper into Tivoli on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers