Setting up Tivoli Directory Server replication using the command line

A step-by-step method to set up three most commonly used replication topologies

The Web Administration tool that ships with the directory server is the easiest way to setup and manage your replication topology. In some situations administrators might need to set up replication using the command line Lightweight Directory Access Protocol (LDAP) tools. This article is intended to help administrators to understand the basics of setting up Tivoli® Directory Server (TDS) replication using the command line.

Darshan Donni (darshan_donni@in.ibm.com), Systems Software Engineer, IBM Software Labs, India

Darshan DonniDarshan 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 V Kulkarni (neelam.kulkarni@in.ibm.com), Systems Software Engineer, IBM Software Labs, India

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



04 December 2006

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.


Sample topologies

Figure 1. The Master-Replica topology
The Master-Replica topology

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.

Figure 2. The Peer-Peer topology
The Peer-Peer topology

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.

Figure 3. The Master-Forwarder-Replica topology
The Peer-Peer topology

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.


The infrastructure

Suppliers and consumers:

In replication, updates are propagated from one LDAP server to another through a replication queue. The server that pushes updates into the replication queue is called a supplier. The server that absorbs these changes is called the consumer. The queue is maintained on the supplier.

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.

ServerHost name
Server 1server1.in.ibm.com
Server 2server2.in.ibm.com
Server 3server3.in.ibm.com

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.

What are agreements?

Agreements are covered later in the article when the various entries that are needed to define a replication topology, are covered.

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.


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.


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:

Contents of masterreplica.ldif
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 .


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:

Contents of peer2peer.ldif
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:

Contents of mfr.ldif
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.


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.

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:

Figure 4. The credential entry (type 1) with a referral
The credential entry with a referral

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.

Figure 5. The credential entry (type 2) without a referral
The credential entry without a referral

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

Figure 6. Replication context as a placeholder for a referral
Context as placeholder.

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

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

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Tivoli (service management) on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Tivoli, Information Management
ArticleID=173403
ArticleTitle=Setting up Tivoli Directory Server replication using the command line
publish-date=12042006