DS 7.5.0

Cross-region replication

Simulate deploying replicated DS servers across multiple regions.


Estimated time to complete: 25 minutes

DS replication works well across LANs and WANs. While some large and very high-performance deployments could call for optimizations to reduce latency or network bandwidth to a minimum, most deployments don’t need them.

If you are running in Kubernetes, there’s an easier way. Try the ForgeOps Cloud Deployment Model (CDM) reference implementation instead.

In this use case, you:

  • Set up DS servers as if you were replicating across the WAN to different regions.

  • Validate DS replicates data changes as expected.

  • Review additional options to optimize performance if necessary.


In completing this use case, you learn to:

  • Set up DS servers.

  • Share secrets to protect network connections and encrypted data.

  • Use appropriate bootstrap replication servers.

  • Show replication in action.

Example scenario

As a directory service administrator, Pat plans to deploy directory services in multiple locations for redundancy.

Pat plans to show other identity administrators how the deployment would look and discuss whether the deployment would call for any optimizations.



Before you start:

  • Make sure you are familiar with the command line on your operating system.

  • If you’re new to directory services, work through the examples to learn LDAP and to learn replication.


When deploying replicated DS servers, be aware of these constraints:

  • All DS servers must be able to connect to each other; their network must be routed.

  • Each server FQDN must be unique and resolvable by all other DS servers; don’t reuse FQDNs across regions.

  • To recover from network partitions without intervention, DS servers must connect often enough to replay each other’s changes before the end of the replication purge delay (default: 3 days).

DS configuration

Each DS server must:

  • Share the same deployment ID.

  • Have a unique server ID.

  • Be able to contact its bootstrap replication servers.

    A bootstrap replication server is one of the replication servers in a deployment other DS servers contact to discover all the other DS servers in the deployment.

  • Be able to verify and trust the digital certificates other DS servers use to establish their identities.

    DS tools must trust the server certificates to connect to DS servers securely. DS servers must trust each other’s certificates to use secure connections for replication.

    This sample uses DS tools to simplify setting up a private PKI for this purpose. Your organization can use its own PKI in deployment.


This sample deployment shows the steps to simulate a cross-region, replicated deployment on your computer. Use the same steps with geographically distributed computers or virtual machines for a real deployment.

Cross-region deployment with four servers
  • Two regions, each with two DS servers.

  • The DS servers are fully meshed for replication; each server connects to the other server.

  • You don’t necessarily need this many DS servers. Two DS servers are the minimum for replication and availability. If the WAN has high bandwidth and low latency, one DS server per region is enough.

  • DS servers function the same in a simulated cross-region deployment and an actual cross-region deployment.

    Replication requires distinct, stable server IDs and FQDNs. For replication, it doesn’t matter whether the DS servers are on the same network interface or separated by a WAN.

Perform these tasks to simulate replicated DS servers across multiple regions.

Task 1: Prepare for installation

  1. Make sure the DS server systems can connect to each other.

    This sample simulates DNS on your computer by updating the hosts file with an alias for each DS server:

    # Simulate DNS in a cross-region deployment
    # with FQDN aliases for the loopback address:       r1-ds1.example.com       r1-ds2.example.com       r2-ds1.example.com       r2-ds2.example.com

    When deploying in a production environment, make sure you have properly configured the DNS.

  2. Unpack the DS server files once for each server to install.

    This sample uses folder locations aligned with the hostnames:

    Base path Description


    Region 1, first server


    Region 1, second server


    Region 2, first server


    Region 2, second server

  3. Define the key configuration details for the deployment.

    This sample uses the following settings:

    Server ID Bootstrap replication servers






  4. Define how the DS servers trust each other’s certificates.

    This sample uses a private PKI based on the deployment ID. You generate a deployment ID for all DS servers using the dskeymgr command:

    $ /path/to/r1-ds1/bin/dskeymgr \
     create-deployment-id \
     --deploymentIdPassword password

    The deployment ID is a string. To use it, you must have the deployment ID password.

  5. Determine the port numbers for the service.

    This sample uses different port numbers for each DS server because all the servers are on the same computer:

    Sample server Port numbers


    LDAP: 1389
    LDAPS: 1636
    HTTPS: 8443
    Admin: 4444
    Replication: 8989


    LDAP: 11389
    LDAPS: 11636
    HTTPS: 18443
    Admin: 14444
    Replication: 18989


    LDAP: 21389
    LDAPS: 21636
    HTTPS: 28443
    Admin: 24444
    Replication: 28989


    LDAP: 31389
    LDAPS: 31636
    HTTPS: 38443
    Admin: 34444
    Replication: 38989

    When installing each DS server on a different host, use the same port numbers everywhere.

Task 2: Install servers in "region 1"

Install servers in the first simulated region on your computer. In deployment, you would install each DS server on a separate host system:

  1. Make sure you have the deployment ID required to install each DS server.

    $ export DEPLOYMENT_ID=<deployment-id>
  2. Install the first server in "region 1".

    $ /path/to/r1-ds1/setup \
     --serverId r1-ds1 \
     --deploymentId $DEPLOYMENT_ID \
     --deploymentIdPassword password \
     --rootUserDn uid=admin \
     --rootUserPassword password \
     --monitorUserPassword password \
     --hostname r1-ds1.example.com \
     --ldapPort 1389 \
     --ldapsPort 1636 \
     --httpsPort 8443 \
     --adminConnectorPort 4444 \
     --replicationPort 8989 \
     --profile ds-evaluation \
     --bootstrapReplicationServer r1-ds1.example.com:8989 \
     --bootstrapReplicationServer r2-ds1.example.com:28989 \
     --start \
  3. Install the second server in "region 1".

    $ /path/to/r1-ds2/setup \
     --serverId r1-ds2 \
     --deploymentId $DEPLOYMENT_ID \
     --deploymentIdPassword password \
     --rootUserDn uid=admin \
     --rootUserPassword password \
     --monitorUserPassword password \
     --hostname r1-ds2.example.com \
     --ldapPort 11389 \
     --ldapsPort 11636 \
     --httpsPort 18443 \
     --adminConnectorPort 14444 \
     --replicationPort 18989 \
     --profile ds-evaluation \
     --bootstrapReplicationServer r1-ds1.example.com:8989 \
     --bootstrapReplicationServer r2-ds1.example.com:28989 \
     --start \

Task 3: Install servers in "region 2"

Install servers in the second simulated region on your computer. In deployment, you would install each DS server on a separate host system:

  1. Make sure you have the deployment ID required to install each DS server.

    $ export DEPLOYMENT_ID=<deployment-id>
  2. Install the first server in "region 2".

    $ /path/to/r2-ds1/setup \
     --serverId r2-ds1 \
     --deploymentId $DEPLOYMENT_ID \
     --deploymentIdPassword password \
     --rootUserDn uid=admin \
     --rootUserPassword password \
     --monitorUserPassword password \
     --hostname r2-ds1.example.com \
     --ldapPort 21389 \
     --ldapsPort 21636 \
     --httpsPort 28443 \
     --adminConnectorPort 24444 \
     --replicationPort 28989 \
     --profile ds-evaluation \
     --bootstrapReplicationServer r1-ds1.example.com:8989 \
     --bootstrapReplicationServer r2-ds1.example.com:28989 \
     --start \
  3. Install the second server in "region 2".

    $ /path/to/r2-ds2/setup \
     --serverId r2-ds2 \
     --deploymentId $DEPLOYMENT_ID \
     --deploymentIdPassword password \
     --rootUserDn uid=admin \
     --rootUserPassword password \
     --monitorUserPassword password \
     --hostname r2-ds2.example.com \
     --ldapPort 31389 \
     --ldapsPort 31636 \
     --httpsPort 38443 \
     --adminConnectorPort 34444 \
     --replicationPort 38989 \
     --profile ds-evaluation \
     --bootstrapReplicationServer r1-ds1.example.com:8989 \
     --bootstrapReplicationServer r2-ds1.example.com:28989 \
     --start \


Show updates to one simulated region getting replicated to the other region.

  1. Modify an entry in the first region.

    The following command changes a description to Description to replicate:

    $ /path/to/r1-ds1/bin/ldapmodify \
     --hostname r1-ds1.example.com \
     --port 1636 \
     --useSsl \
     --usePkcs12TrustStore /path/to/r1-ds1/config/keystore \
     --trustStorePassword:file /path/to/r1-ds1/config/keystore.pin \
     --bindDn uid=bjensen,ou=People,dc=example,dc=com \
     --bindPassword hifalutin <<EOF
    dn: uid=bjensen,ou=People,dc=example,dc=com
    changetype: modify
    replace: description
    description: Description to replicate
  2. Read the entry in the other region:

    $ /path/to/r2-ds2/bin/ldapsearch \
     --hostname r2-ds2.example.com \
     --port 31636 \
     --useSsl \
     --usePkcs12TrustStore /path/to/r2-ds2/config/keystore \
     --trustStorePassword:file /path/to/r2-ds2/config/keystore.pin \
     --bindDn uid=bjensen,ou=People,dc=example,dc=com \
     --bindPassword hifalutin \
     --baseDn dc=example,dc=com \
     "(uid=bjensen)" description
    dn: uid=bjensen,ou=People,dc=example,dc=com
    description: Description to replicate

    Notice description: Description to replicate in the output.

You have shown replication works across regions.

What’s next

After successfully showing the demonstration to other administrators, Pat doesn’t stop there.

Pat leads the administrators to review the tradeoffs they can choose to make for the production deployment. Some of the questions to discuss include the following:

  • Are there any applications we must direct to the nearest DS server on the network? For example, there could be applications with very low latency requirements, or the cost of network connections to remote servers could be much higher.

    If so, can those applications configure their own failover rules? Do we need a load balancer to do this for them?

  • Do our DS replicas generate so much replication traffic that we should take steps to limit traffic between regions?

    If so, would standalone replication and directory servers be a good tradeoff? Should we configure replication group IDs to have directory servers in a region connect preferentially to replication servers in the same region?

  • Should we use our own PKI to protect client-facing network connections over LDAP and HTTP?

    This sample uses the server and CA certificates generated with the deployment ID and deployment ID password. You can set up DS with your own keys, using your own PKI to protect secure connections.

  • How many DS servers do we really need?

    At a bare minimum, we need at least two DS servers to keep the service running while we upgrade, for example. The fewer servers we have, the easier it is to manage the service.

The answers to these questions depend on costs and service-level performance requirements. Don’t optimize or pay extra for high performance unless you need it.

Explore further

Reference material

Reference Description

On Kubernetes? Use the ForgeOps CDM reference implementation instead.

Configure bootstrap replication servers.

Understand how DS uses secrets and keys.

Install directory services.

Optimize network bandwidth for deployments with many servers.

Read this before configuring a load balancer.

When performance is a concern, measure, tune, and test.

Background and procedures for working with DS replication.

Opt for your own PKI to protect network connections.

Copyright © 2010-2024 ForgeRock, all rights reserved.