This topic provides examples of the different replication topologies
that can be configured. It provides example LDIF data that includes
the host names, IP addresses, ports, server IDs, and passwords.
Suppliers and consumers
In advanced replication, updates are propagated from one LDAP server
to another through a replication queue. The server that enters 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.
Host names and ports: Provide the supplier with enough
information to connect to the consumer.
Server IDs: Strings that enable one LDAP server to identify
other LDAP servers in the topology.
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.
The following examples demonstrate setup for a topology consisting
of a maximum of three servers.
Note: The host name of the consumer
resolves correctly from the supplier. If not, the supplier cannot
connect to the consumer and advanced replication fails.
Table 1. Topology setup
Server
Host name
Server 1
server1.us.ibm.com
Server 2
server2.us.ibm.com
Server 3
server3.us.ibm.com
Each LDAP server in Table 1 is listening
on port 389, which is the default LDAP port.
These examples assume that a simple bind is being done from the
supplier server to the consumer server. Each example assumes the following
bind DN and password for all supplier-consumer agreements.
DN:cn=bindtoconsumer
Password:iamsupplier
Server ID
In the examples, the server ID of each server is the role of that
server in the topology. That is, in the Master-Replica topology, the
master identifies the server ID as Master and the
replica is identified as Replica. In the Peer-to-Peer
topology, one peer is Peer1 and the other is Peer2.
In the Master-Forwarder-Replica topology, the master is Master,
the forwarder is Forwarder, and the replica is Replica.
In the Gateway topology, the gateway servers are Gateway1 and
the other is Gateway2 and the replica is Replica.
Do not change the server ID for a server. When the z/OS® LDAP server is first configured with a
CDBM backend, the server ID is generated as an IBM® entry UUID value in the ibm-slapdServerID attribute
value in the cn=configuration entry. For convenience, the
server ID is published in the rootDSE entrys attribute ibm-serverID.
The server ID is only allowed to be modified when there are no replica
subentries defined in the server. See Table 1 for more information about the ibm-slapdServerID attribute
value.
Advanced replication related entries summary
For convenience, this section quickly summarizes the various types
of entries that are used to build an advanced replication topology.
Supplier server entries
Replication context: This is the root entry for the subtree
that is to be replicated. It must have an auxiliary objectclass of ibm-replicationContext. To
replicate a subtree o=ibm,c=us, the replication context
might be:
dn: o=ibm,c=us
objectclass: top
objectclass: organization
objectclass: ibm-replicationContext
o: ibm
All other replication entries except for the credential
and schedule entries must be under the replication context. The credential
and schedule entries can be anywhere in the DIT.
Replica group: This entry is not important apart from the
fact that all the advanced replication-related entries exist under
this entry. It must have the ibm-replicaGroup objectclass.
For example:
dn: ibm-replicaGroup=default, o=ibm,c=us
objectclass: top
objectclass: ibm-replicaGroup
ibm-replicaGroup: default
Replica subentry: These types of entries declare the servers
that are taking part in the advanced replication topology. Each server
participating in the topology has one subentry. If a server is represented
by more than one subentry under a replication context, unexpected
behavior might result. This is done by having more than one subentry
under a replication context containing the same ibm-replicaServerID attribute
value. This entry has the ibm-replicaSubentry objectclass.
For example:
As shown in the replica subentry example,
the entry has the server ID of the participating server, Peer1.
It has an attribute called ibm-replicationServerIsMaster. When
this attribute is set to true, the server is a read/write copy.
Replication 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. For example:
dn: cn=Peer2, ibm-replicaServerId=Peer1,ibm-replicaGroup=default,o=ibm,c=us
objectclass: top
objectclass: ibm-replicationAgreement
cn: Peer2
ibm-replicaConsumerId: Peer2
ibm-replicaUrl: ldap://server2.us.ibm.com:389
ibm-replicaCredentialsDN: cn=Peer1BindCredentials, cn=localhost
description: Replication agreement from Peer1 to Peer2
The
replication agreement example 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.us.ibm.com and
is listening on port 389. Peer1 binds
to Peer2 using the credentials defined in the entry
(cn=Peer1BindCredentials,cn=localhost).
Replication credentials: If a simple bind is used by the
supplier server to authenticate with the consumer server, this entry
defines the bind DN and password that is used. This credential entry
uses the ibm-replicationCredentialsSimple objectclass. If
a SASL EXTERNAL bind is used by the supplier server to authenticate
with the consumer server, see Credentials entries for
information about the ibm-replicationCredentialsExternal objectclass.
For example:
dn: cn=Peer1BindCredentials, cn=localhost
objectclass: ibm-replicationCredentialsSimple
cn: ReplicaBindCredentials
replicaBindDN: cn=bindtoconsumer
replicaCredentials: iamsupplier
description: Bind Credentials on Peer1 to be used to bind to other servers.
The
replication credential example defines the replicaBindDN as cn=bindtoconsumer and
the password as iamsupplier. Take note of the description.
The same credentials entry can be used for multiple replication agreements.
Consumer server entries
If the consumer server is a read only replica server, the only
required replication-related entry is the consumer server credentials
entry. If the consumer server is a peer or forwarding server, a
replica subentry and a consumer server credentials entry are required.
The consumer server credentials entry identifies the distinguished
name and optionally the password value that the supplier server uses
to authenticate with the consumer server. There are two types of credential
entries that can be used on the consumer.
The use of the credential established by type 2 is limited to the
ibm-slapdReplicaSubtree only. Therefore, suppliers binding with bind DN as
cn=bindtoconsumer and password as iamsupplier supplies only to the
o=ibm,c=us subtree, unless another credential entry gives rights to another
subtree. The type 1 credential entry is global across the LDAP server. When a type 2 entry is
defined in the cn=configuration suffix in the CDBM backend, any subtree can be supplied to if
a supplier authenticates with bind DN of cn=bindtoconsumer and password of
iamsupplier.
Note: The consumer server credentials entry must be present on both
the consumer and supplier servers and exist under the cn=configuration suffix in
the CDBM backend. The topology entries are the only way for the servers to know their roles in the
topology as a whole, therefore, are needed on all the servers in the topology.
Creating a master-replica topology
This example describes deploying the most basic of all the topologies, the master-replica
topology. It has one read/write server and one read-only server.Figure 1. Master-replica topology
The first step when building a topology is to define:
Replication context:o=ibm,c=us
Suppliers: LDAP server on server1.us.ibm.com:389 is the only supplier.
The server ID is Master. It supplies updates to the LDAP server on
server2.us.ibm.com:389.
Consumers: LDAP server on server2.us.ibm.com:389 is the only consumer.
The server ID is Replica. It consumes updates from the LDAP server on
server1.us.ibm.com:389.
read/write servers: LDAP server on server1.us.ibm.com:389, with ID
Master is the only read/write server.
Read-only servers: LDAP server on server2.us.ibm.com:389, with ID
Replica is the only read-only server.
Configuration changes: Because of these examples, some CDBM changes are needed for the
master and the replica server for replication to work correctly.
Note: These are done here for this
example ONLY. The server ID is only allowed to be modified when there are no replica subentries
defined in the server. See Table 1 for more information about the
ibm-slapdServerID attribute value.
The next step is to build the LDIF file for the topology. This
LDIF file is called masterreplica.ldif. Copy each of these
entries to masterreplica.ldif with the necessary changes in
the subtree, server IDs, host names, and ports.
Replication context:
If the subtree entry exists, use the ldapmodify utility
to modify the existing entry. For example:
Replica subentries: Because this topology is using a master
and a read-only replica server, a replica subentry is only needed
for the master server. Read-only replicas do not need a replica subentry.
For example, for a subentry for the master:
dn: ibm-replicaServerId=Master,ibm-replicaGroup=default, o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicaSubentry
ibm-replicaServerId: Master
ibm-replicationServerIsMaster: true
cn: Master
description: Master server of the topology
Take note of
the master subentry carefully. The subentry for the master uses the
server ID Master and has the server declared as a
master server. This server receives updates from clients.
Note: The
number of subentries is not dependent on the number of physical servers
in the topology. Rather, it is dependent on the number and role of
the LDAP servers in the topology.
Supplier server credentials entry: This step defines the
credentials that the master uses to bind to the replica. Add an entry
with the ldapadd utility. For example:
dn: cn=ReplicaBindCredentials, o=ibm,c=us
changetype: add
objectclass: ibm-replicationCredentialsSimple
cn: ReplicaBindCredentials
replicaBindDN: cn=bindtoconsumer
replicaCredentials: iamsupplier
description: Bind Credentials on master to bind to replica
Note
the DN and password are the same as the pair that was added in the
consumer server credentials entry section above. Add the entry with
the ldapadd utility. As a result, updates to this object results
in the server attempting to replicate.
Replication agreements: There is one supplier-consumer
relationship in this advanced replication topology. The master supplies
updates to the o=ibm,c=us subtree to the replica
that consumes the changes. Therefore, there is only 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. For example:
dn: cn=Replica, ibm-replicaServerId=Master,ibm-replicaGroup=default,o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Replica
ibm-replicaConsumerId: Replica
ibm-replicaUrl: ldap://server2.us.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm,c=us
description: Replication agreement from master to replica
The
entry above is under the subentry for the master. It supplies to a
consumer with an ID as Replica. The replica URL is ldap://server2.us.ibm.com:389 meaning
that the replica is listening on server2.us.ibm.com on port
389. This agreement uses the credentials that were created
in the last step for the master to bind to the replica. That means
the master binds 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,
therefore, 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 file
is as follows:
dn: o=ibm,c=us
changetype: add
objectclass: top
objectclass: organization
objectclass: ibm-replicationContext
o: ibm
dn: ibm-replicaGroup=default, o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicaGroup
ibm-replicaGroup: default
dn: ibm-replicaServerId=Master,ibm-replicaGroup=default, o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicaSubentry
ibm-replicaServerId: Master
ibm-replicationServerIsMaster: true
cn: Master
description: Master server of the topology.
dn: cn=ReplicaBindCredentials, o=ibm,c=us
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=us
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Replica
ibm-replicaConsumerId: Replica
ibm-replicaUrl: ldap://server2.us.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm,c=us
description: Replication agreement from master to replica.
The
LDIF is different if the replication context exists. Rather than:
dn: o=ibm,c=us
changetype: add
objectclass: top
objectclass: organization
objectclass: ibm-replicationContext
o: ibm
For the sake of simplicity,
it is assumed that the subtree entry does not exist at all.
Next, add the masterreplica.ldif file on the master server.
Use the ldapadd utility on the master where the masterreplica.ldif file
was created. For example:
The –L option
on the ldapadd utility sends the Do Not Replicate control
to the server that indicates not to replicate the topology now. The -k option
sends the Server Administration control to the server so that
the addition of entries continues even when the subtree becomes read-only
because of a server ID mismatch.
Next add the replication topology to the replica also. Use the ldapexop utility.
For example:
This is an example of the Replication
topology extended operation. It propagates the advanced replication
topology to all the consumers defined under the o=ibm,c=us replication
context. See ldapexop utility for additional information
about the ldapexop utility.
After the ldapadd and ldapexop commands are performed
successfully, the master-replica topology is ready. The master accepts
updates on the o=ibm,c=us subtree and propagates
them to the replica. The replica does not accept updates. It returns
a referral to the master in case a client tries to update it, however,
it can handle searches.
Creating a peer-to-peer replication topology
The peer-to-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.Figure 2. Peer-to-peer topology
The first step when building a topology is to define:
Replication context:o=ibm,c=us
Supplier: LDAP server on server1.us.ibm.com:389 with server ID
Peer1 supplies updates to the LDAP server with server ID Peer2 on
server2.us.ibm.com:389. LDAP server on server2.us.ibm.com:389 with
server ID Peer2 supplies updates to the LDAP server with server ID
Peer1 on server1.us.ibm.com:389.
Consumer: LDAP server with server ID Peer2 on
server2.us.ibm.com:389 consumes updates from LDAP server with server ID
Peer1 on server1.us.ibm.com:389. LDAP server with Server ID
Peer1 on server1.us.ibm.com:389 consumes updates from LDAP server
with server ID Peer2 on server2.us.ibm.com:389.
read/write server: LDAP servers Peer1 and Peer2 on
server1.us.ibm.com and server2.us.ibm.com are read/write
servers.
Read-only server: There are no read-only servers in this topology.
Configuration changes: Some CDBM changes must be done to both the Peer1
and Peer2 servers for replication to work correctly. Configured servers are
current. If you are using the same servers that you used for the Master-Replica setup, undo the
changes that you made in Creating a master-replica topology.
Note: These are done here for this example
only. The server ID is only allowed to be modified when there are no replica subentries defined in
the server. See Table 1 for more information about the
ibm-slapdServerID attribute value.
Consumer server credentials entry: Add this first entry to the Peer1
server and the second entry to the Peer2 server using the
ldapadd utility. See z/OS IBM Tivoli Directory Server Client Programming for z/OS for additional information about the
ldapadd utility.
Note: An alternative is to add entries with an
ibm-slapdSupplier objectclass. Also, each peer uses the other peer as the referral.
This is useful if a peer must become a read only replica or a forwarding server.
For example,
for a consumer side credentials entry for the
Peer1:
The next step is to build the LDIF file for the replication topology.
This LDIF file is called peer2peer.ldif. Copy each of these
entries to peer2peer.ldif with the necessary changes in the
subtree, server IDs, host names, and ports.
Replication context:
If the subtree entry exists, use the ldapmodify utility to modify the
existing entry. For
example:
Replica subentries: Because there are two LDAP servers
in the topology, you must add two replica subentries; one for Peer1 and
another one for the Peer2 server by using the ldapadd utility.
For example, for a subentry for Peer1:
dn: ibm-replicaServerId=Peer1,ibm-replicaGroup=default, o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicaSubentry
ibm-replicaServerId: Peer1
ibm-replicationServerIsMaster: true
cn: Peer1
description: Subentry for Peer1
For example, for a subentry
for Peer2:
dn: ibm-replicaServerId=Peer2,ibm-replicaGroup=default, o=ibm,c=us
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 also has the server declared as a master server. This server
can also receive updates from LDAP clients that bind to it.
Supplier server credentials entry: This step defines the credentials that
Peer1 and Peer2 use to bind to each other. Add the entry with the
ldapadd utility. For
example:
dn: cn=ReplicaBindCredentials, o=ibm,c=us
changetype: add
objectclass: ibm-replicationCredentialsSimple
cn: ReplicaBindCredentials
replicaBindDN: cn=bindtoconsumer
replicaCredentials: iamsupplier
description: Bind Credentials on Peer1 and Peer2 to bind to each other.
Replication agreements: There are two supplier-consumer
relationships in this topology. Peer1 supplies updates
made to the o=ibm,c=us subtree to Peer2,
that consumes the changes. Peer2 also accepts updates
from clients on the o=ibm,c=us subtree and sends
them to Peer1, that consumes the changes. Therefore,
there are two agreements:
from Peer1 to Peer2
from Peer2 to Peer1
Note: The number of agreements is dependent upon the number
of supplier-consumer relationships in the topology.
For example,
a replication agreement from Peer1 to Peer2:
dn: cn=Peer2, ibm-replicaServerId=Peer1,ibm-replicaGroup=default,o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Peer2
ibm-replicaConsumerId: Peer2
ibm-replicaUrl: ldap://server2.us.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm,c=us
description: Replication agreement from Peer1 to Peer2
For
example, a replication agreement from Peer2 to Peer1:
dn: cn=Peer1, ibm-replicaServerId=Peer2,ibm-replicaGroup=default,o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Peer1
ibm-replicaConsumerId: Peer1
ibm-replicaUrl: ldap://server1.us.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm,c=us
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 is under the Peer1 subentry. The second one is
from Peer2 to Peer1 and it is under
the Peer2 subentry. Note the use of the same credentials
entry for both agreements. This is acceptable. The credentials entry
is added to both Peer1 and Peer2.
Now that the replication entries have been added, the peer2peer.ldif file
is as follows:
dn: o=ibm,c=us
changetype: add
objectclass: top
objectclass: organization
objectclass: ibm-replicationContext
o: ibm
dn: ibm-replicaGroup=default, o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicaGroup
ibm-replicaGroup: default
dn: ibm-replicaServerId=Peer1,ibm-replicaGroup=default, o=ibm,c=us
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=us
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=us
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=us
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Peer2
ibm-replicaConsumerId: Peer2
ibm-replicaUrl: ldap://server2.us.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm,c=us
description: Replication agreement from Peer1 to Peer2.
dn: cn=Peer1, ibm-replicaServerId=Peer2,ibm-replicaGroup=default,o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Peer1
ibm-replicaConsumerId: Peer1
ibm-replicaUrl: ldap://server1.us.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm,c=us
description: Replication agreement from Peer2 to Peer1
Next, add the peer2peer.ldif file on the Peer1 server. Use the
ldapadd utility on the Peer1 where the peer2peer.ldif
file was created. For example:
The
–L option on the ldapadd utility sends the Do Not Replicate control
to the server that indicates not to replicate the topology now. The -k option sends
the Server Administration control to the server so that the addition of entries continues
even when the subtree becomes read-only because of a server ID mismatch.
Next, add the replication topology to the Peer2 also. Use the
ldapexop utility. For
example:
This
is an example of the Replication topology extended operation. It propagates the advanced
replication topology to all the consumers defined under the o=ibm,c=us replication
context. See ldapexop utility for additional information about the
ldapexop utility.
After the ldapadd and ldapexop commands are performed
successfully, the peer-to-peer topology is ready. Both peers accept updates on and send them to the
other peer.
Creating a master-forwarder-replica (cascading) topology
Another advanced replication topology is the master-forwarder-replica or cascading replication
topology.Figure 3. Master-forwarder-replica topology
The forwarder server is a specialized replica server. As previously
stated, replica servers are read-only as is a forwarder server. Replica
servers do not transmit changes that are consumed by them. However,
forwarder servers replicate changes that they have consumed. To supply
changes further down the topology, forwarders have agreements under
their subentries.
Note: Gateway replication topologies are similar,
however, forwarders are specialized replicas while gateways are specialized
masters.
This topology must have one more server included: server3.us.ibm.com
The first step when building a topology is to define:
Replication context:o=ibm,c=us
Supplier: LDAP server on server1.us.ibm.com:389 with server ID
Master supplies updates to the LDAP server with server ID
Forwarder on server2.us.ibm.com:389. LDAP server on
server2.us.ibm.com:389 with server ID Forwarder supplies updates
to the LDAP server with server ID Replica on
server3.us.ibm.com:389.
Consumer: LDAP server with server ID Forwarder on
server2.us.ibm.com:389 consumes updates from LDAP server with server ID
Master working on server1.us.ibm.com:389. LDAP server with server
ID Replica on server3.us.ibm.com:389 consumes updates from the
LDAP server with server ID Forwarder working on
server2.us.ibm.com:389.
read/write server: LDAP server on server1.us.ibm.com:389, with ID
Master is the only read/write server.
Read-only server: LDAP server on server2.us.ibm.com:389 and
server3.us.ibm.com:389, with IDs, Forwarder and
Replica are read-only.
Configuration changes: Some configuration changes must
be made to the Master, Forwarder, and Replica servers
for replication to work correctly. Configured servers are current.
If reusing the same servers that were used for the Master-Replica
setup, undo the changes that were made in Creating a master-replica topology.
If reusing the same servers that were used for the Peer-Peer setup,
undo the changes that were made in Creating a peer-to-peer replication topology.
Note: These are done here for this example only. The server ID is
only allowed to be modified when there are no replica subentries defined
in the server. See Table 1 for
more information about the ibm-slapdServerID attribute value.
Consumer server credentials entry: Add this first entry to the Forwarder
server and the second entry to the Replica server using the
ldapadd utility. See z/OS IBM Tivoli Directory Server Client Programming for z/OS for additional information about the
ldapadd utility.
Note: An alternative is to add entries with an
ibm-slapdSupplier objectclass.
For example, for a consumer server credentials entry for
the
Forwarder:
The next step is to build the LDIF file for the replication topology. This LDIF file is called
mfr.ldif. Copy each of these entries to mfr.ldif with the
necessary changes in the subtree, server IDs, host names, and ports.
Replication context:
If the subtree entry exists, use the ldapmodify utility to modify the
existing entry. For
example:
Replica subentries: Because this topology is using a master, a forwarding, and a
read-only replica server, replica subentries are only needed for the Master and for
the Forwarder servers. The read-only Replica server does not need
a replica subentry. The following entries can be added using the ldapadd utility.
For example, for a subentry for
Master:
dn: ibm-replicaServerId=Master,ibm-replicaGroup=default, o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicaSubentry
ibm-replicaServerId: Master
ibm-replicationServerIsMaster: true
cn: Master
description: Subentry for Master
For
example, for a subentry for
Forwarder:
dn: ibm-replicaServerId=Forwarder,ibm-replicaGroup=default, o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicaSubentry
ibm-replicaServerId: Forwarder
ibm-replicationServerIsMaster: false
cn: Forwarder
description: Subentry for the Forwarder
The
subentry for Master identifies the server ID as Master and has the
server declared as a master server. 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.
Supplier server credentials entry: This step defines the credentials that the
Master uses to bind to the Forwarder. Add the entry with the
ldapadd utility. For
example:
dn: cn=ReplicaBindCredentials, o=ibm,c=us
changetype: add
objectclass: ibm-replicationCredentialsSimple
cn: ReplicaBindCredentials
replicaBindDN: cn=bindtoconsumer
replicaCredentials: iamsupplier
description: Bind Credentials on master to bind to forwarder
Replication agreements: There are two supplier-consumer relationships in this topology.
Master supplies updates made to the o=ibm,c=us subtree to
Forwarder, that consumes the changes and then supplies these changes to the
Replica. Therefore, there are two agreements:
from Master to Forwarder
from Forwarder to Replica
Note: The number of replication agreements is dependent upon the number of supplier-consumer
relationships in the topology.
For example, a replication agreement from
Master to
Forwarder:
dn: cn=Forwarder, ibm-replicaServerId=Master,ibm-replicaGroup=default,o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Forwarder
ibm-replicaConsumerId: Forwarder
ibm-replicaUrl: ldap://server2.us.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm,c=us
description: Replication agreement from Master to Forwarder
For
example, a replication agreement from Forwarder to
Replica:
dn: cn=Replica, ibm-replicaServerId=Forwarder,ibm-replicaGroup=default,o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Replica
ibm-replicaConsumerId: Replica
ibm-replicaUrl: ldap://server3.us.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm,c=us
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 is under the Master
subentry. The second one is from Forwarder to Replica and it is
under the Forwarder subentry. Note the use of the same credentials entry for both
agreements. This is acceptable. The consumer server credentials entry is added to both
Master and Forwarder servers.
Now that the replication entries have been added, the mfr.ldif file is as
follows:
dn: o=ibm,c=us
changetype: add
objectclass: top
objectclass: organization
objectclass: ibm-replicationContext
o: ibm
dn: ibm-replicaGroup=default, o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicaGroup
ibm-replicaGroup: default
dn: ibm-replicaServerId=Master,ibm-replicaGroup=default, o=ibm,c=us
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=us
changetype: add
objectclass: top
objectclass: ibm-replicaSubentry
ibm-replicaServerId: Forwarder
ibm-replicationServerIsMaster: false
cn: Forwarder
description: Subentry for the Forwarder.
dn: cn=ReplicaBindCredentials, o=ibm,c=us
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=us
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Forwarder
ibm-replicaConsumerId: Forwarder
ibm-replicaUrl: ldap://server2.us.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm,c=us
description: Replication agreement from Master to Forwarder
dn: cn=Replica, ibm-replicaServerId=Forwarder,ibm-replicaGroup=default,o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Replica
ibm-replicaConsumerId: Replica
ibm-replicaUrl: ldap://server3.us.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm,c=us
description: Replication agreement from Forwarder to Replica
Next, add the mfr.ldif file on the Master server. Use the
ldapadd utility on the Master where the
mfr.ldif file was created. For example:
The
–L option on the ldapadd utility sends the Do Not Replicate
control to the server that indicates not to replicate the topology now. The -k
option sends the Server Administration control to the server so that the addition of entries
continues even when the subtree becomes read-only because of a server ID mismatch.
Next, add the replication topology to the Replica also. Use the
ldapexop utility. For
example:
This
is an example of the Replication topology extended operation. It propagates the advanced
replication topology to the Replica defined under the o=ibm,c=us
replication context. See ldapexop utility for additional information about the
ldapexopldapexop utility.
After the ldapadd and ldapexop commands are performed
successfully, the master-forwarder-replica topology is ready. The Master accepts
updates, that go to the Forwarder and then to the Replica. If you
intend to add another replica to the topology, under the forwarder, you must add another subentry
for the replica, and add an agreement from the forwarder to that replica.
Creating a gateway topology
A gateway topology requires at least two gateway servers. Gateway topologies are created in a
similar manner to a master-forwarder-replica (cascading) topology. A gateway topology includes
gateway master servers that forward all replication traffic from the local replication site where it
exists to other gateway servers in the replicating network. A gateway server also receives
replication traffic from other gateway servers within the replication network and forwards updates
to all servers on its local replication site.Figure 4. Gateway topology
In a gateway topology, gateway servers are distinguished from normal
master servers by including the ibm-replicaGateway objectclass
for the replica subentry in the replication context. As previously
stated, a server is a master if the server ID in the replica subentry
within the replication context equals the servers server ID and the subentrys ibm-replicationServerIsMaster attribute
is set to true. See Replica subentries for more information about replica subentries.
The first step when building a topology is to define:
Replication context:o=ibm,c=us
Supplier: LDAP server on server1.us.ibm.com:389 with server ID
Gateway1 supplies updates to the LDAP server with server ID
Gateway2 on server2.us.ibm.com:389. LDAP server on
server2.us.ibm.com:389 with server ID Gateway2 supplies updates to
the LDAP server with server ID Gateway1 on server1.us.ibm.com:389
and to the LDAP server with server ID Replica on
server3.us.ibm.com:389.
Consumer: LDAP server with server ID Gateway2 on
server2.us.ibm.com:389 consumes updates from LDAP server with server ID
Gateway1 on server1.us.ibm.com:389. LDAP server with Server ID
Gateway1 on server1.us.ibm.com:389 consumes updates from LDAP
server with server ID Gateway2 on server2.us.ibm.com:389. LDAP
server with server ID Replica on server3.us.ibm.com:389 consumes
updates from LDAP server with server ID Gateway2 on
server2.us.ibm.com:389.
read/write servers: LDAP servers Gateway1 and Gateway2
on server1.us.ibm.com and server2.us.ibm.com are read/write
servers.
Read-only server: LDAP server Replica on
server3.us.ibm.com is a read-only server.
Configuration changes: Some configuration changes must
be made to the Gateway1, Gateway2,
and Replica servers for replication to work correctly.
Configured servers should be current. If reusing the same servers
that were used for the Master-Replica setup, undo the changes that
were made in Creating a master-replica topology. If reusing the same
servers that were used for the Peer-Peer setup, undo the changes that
were made in Creating a peer-to-peer replication topology. If reusing the same
servers that were used for the Master-forwarder-replica setup, undo
the changes that were made in Creating a master-forwarder-replica (cascading) topology.
Note: These
are done here for this example only. The server ID is only allowed
to be modified when there are no replica subentries defined in the
server. See Table 1 for more information about the ibm-slapdServerID attribute value.
Consumer server credentials entry: Add the first entry to the Gateway1
server, the second entry to the Gateway2 server, and the third entry to the
Replica server using the ldapadd utility. See z/OS IBM Tivoli Directory Server Client Programming for z/OS for additional
information about the ldapadd utility.
Note: An alternative is to add entries
with an ibm-slapdSupplier objectclass.
For example, for a consumer server
credentials entry for
Gateway1:
The next step is to build the LDIF file for the replication topology.
This LDIF file is called gateway.ldif. Copy each of these entries
to gateway.ldif with the necessary changes in the subtree,
server IDs, host names, and ports.
Replication context:
If the subtree entry exists, use the ldapmodify utility to modify the
existing entry. For
example:
Replica subentries: Because this topology is using two gateways and a read-only replica
server, replica subentries are only needed for the Gateway1 and for the
Gateway2 servers. The read-only Replica server does not need a
replica subentry. The following entries can be added using the ldapadd utility.
For example, for a subentry for Gateway1 (note that an objectclass of
ibm-replicaGateway has been added to this entry to indicate that it is a gateway
server):
For
example, for a subentry for Gateway2 (note that an objectclass of
ibm-replicaGateway has been added to this entry to indicate that it is a gateway
server):
The
subentry for Gateway1 identifies the server ID as Gateway1 and has
the server declared as a gateway server. The Gateway1 server can receive updates
from clients. The subentry for Gateway2 identifies the server ID as
Gateway2 and has the server declared as a gateway server. The
Gateway2 server can receive updates from clients.
Supplier server credentials entry: This step defines the credentials that
Gateway1 uses to bind to Gateway2, Gateway2 uses
to bind to Gateway1, and Gateway2 uses to bind to
Replica. Add the entry with the ldapadd utility. For
example:
dn: cn=ReplicaBindCredentials, o=ibm,c=us
changetype: add
objectclass: ibm-replicationCredentialsSimple
cn: ReplicaBindCredentials
replicaBindDN: cn=bindtoconsumer
replicaCredentials: iamsupplier
description: Bind Credentials used on the gateway servers.
Replication agreements: There are three supplier-consumer
relationships in this topology. Gateway1 supplies
updates made to the o=ibm,c=us subtree to Gateway2.
Gateway2 supplies updates made to the o=ibm,c=us subtree
to Gateway1 and to Replica. Therefore,
there are three agreements:
from Gateway1 to Gateway2
from Gateway2 to Gateway1
from Gateway2 to Replica
Note: The number of replication agreements is dependent upon
the number of supplier-consumer relationships in the topology.
For
example, a replication agreement from Gateway1 to Gateway2:
dn: cn=Gateway2,ibm-replicaServerId=Gateway1,ibm-replicaGroup=default,o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Gateway2
ibm-replicaConsumerId: Gateway2
ibm-replicaUrl: ldap://server2.us.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm,c=us
description: Replication agreement from Gateway1 to Gateway2.
For
example, a replication agreement from Gateway2 to Gateway1:
dn: cn=Gateway1,ibm-replicaServerId=Gateway2,ibm-replicaGroup=default,o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Gateway1
ibm-replicaConsumerId: Gateway1
ibm-replicaUrl: ldap://server1.us.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm,c=us
description: Replication agreement from Gateway2 to Gateway1.
For
example, a replication agreement from Gateway2 to Replica:
dn: cn=Replica, ibm-replicaServerId=Gateway2,ibm-replicaGroup=default,o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Replica
ibm-replicaConsumerId: Replica
ibm-replicaUrl: ldap://server3.us.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm,c=us
description: Replication agreement from Gateway2 to Replica.
The
three agreements for this topology are shown above. The first one
is the agreement from Gateway1 to Gateway2.
It is under the Gateway1 subentry. The second one
is from Gateway2 to Gateway1 and
it is under the Gateway2 subentry. The third one
is from Gateway2 to Replica and
it is also under the Gateway2 subentry. Note the
use of the same credentials entry for all three agreements. This
is acceptable. The consumer server credentials entry is added to Gateway1,
Gateway2, and Replica servers.
Now that the replication entries have been added, the gateway.ldif file
is as follows:
dn: o=ibm,c=us
changetype: add
objectclass: top
objectclass: organization
objectclass: ibm-replicationContext
o: ibm
dn: ibm-replicaGroup=default, o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicaGroup
ibm-replicaGroup: default
dn: ibm-replicaServerId=Gateway1,ibm-replicaGroup=default, o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicaSubentry
objectclass: ibm-replicaGateway
ibm-replicaServerId: Gateway1
ibm-replicationServerIsMaster: true
cn: Gateway1
description: Subentry for Gateway1.
dn: ibm-replicaServerId=Gateway2,ibm-replicaGroup=default, o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicaSubentry
objectclass: ibm-replicaGateway
ibm-replicaServerId: Gateway2
ibm-replicationServerIsMaster: true
cn: Gateway2
description: Subentry for Gateway2.
dn: cn=replicaBindCredentials, o=ibm,c=us
changetype: add
objectclass: ibm-replicationCredentialsSimple
cn: replicaBindCredentials
replicaBindDN: cn=bindtoconsumer
replicaCredentials: iamsupplier
description: Bind Credentials used on the gateway servers.
dn: cn=Gateway2,ibm-replicaServerId=Gateway1,ibm-replicaGroup=default,o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Gateway2
ibm-replicaConsumerId: Gateway2
ibm-replicaUrl: ldap://server2.us.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm,c=us
description: Replication agreement from Gateway1 to Gateway2.
dn: cn=Gateway1,ibm-replicaServerId=Gateway2,ibm-replicaGroup=default,o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Gateway1
ibm-replicaConsumerId: Gateway1
ibm-replicaUrl: ldap://server1.us.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm,c=us
description: Replication agreement from Gateway2 to Gateway1.
dn: cn=Replica, ibm-replicaServerId=Gateway2,ibm-replicaGroup=default,o=ibm,c=us
changetype: add
objectclass: top
objectclass: ibm-replicationAgreement
cn: Replica
ibm-replicaConsumerId: Replica
ibm-replicaUrl: ldap://server3.us.ibm.com:389
ibm-replicaCredentialsDN: cn=ReplicaBindCredentials, o=ibm,c=us
description: Replication agreement from Gateway2 to Replica.
Next, add the gateway.ldif file on the Gateway2 server. Use the
ldapadd utility on Gateway2 where the gateway.ldif file
was created. For
example:
The
-L option on the ldapadd utility sends the Do Not Replicate control
to the server that indicates not to replicate the topology now. The -k option sends
the Server Administration control to the server so that the addition of entries continues
even when the subtree becomes read-only because of a server ID mismatch.
Next, add the replication topology to the Gateway1 and Replica
servers. Use the ldapexop utility. For example:
This
is an example of the Replication topology extended operation. It propagates the advanced
replication topology to the Gateway1 and Replica servers defined
under the o=ibm,c=us replication context. See ldapexop utility for more
information about the ldapexop utility.
After the ldapadd and ldapexop commands are performed
successfully, the gateway topology is ready. The Gateway1 server accepts updates
that go to the Gateway2 server. The Gateway2 server also accepts
updates that are then forwarded to the Gateway1 and Replica
servers.
