DS 7.4.0

Manual initialization

Manual initialization is not always required. Replication can proceed automatically over the network when replicas start from the same initial data.

If this is not the case, manually initialize replication.

Test the initialization process to make sure you understand the duration and ramifications of the chosen initialization method.

Use the results to make an evidence-based decision on whether to use backup/restore or export/import instead of online initialization.

How you initialize replication depends on your situation:

Initialization options
Use cases Recommendations

Replicas installed with same data

Nothing to do (no manual initialization required)

Evaluating DS software

Developing a directory solution

Plenty of bandwidth to replicate data

Initialize over the network

Limitations:

  • Transmits all data over the network, so requires ample bandwidth; can be a problem for slow links.

  • Rebuilds indexes and consumes significant system resources; can impact service performance.

New directory service, medium to large data set (> 1 million entries; limited bandwidth)

Initialize from LDIF

Limitations:

  • Rebuilds indexes and consumes significant system resources; can impact service performance.

Existing directory service, medium to large data set (> 1 million entries; limited bandwidth)

Initialize from backup

Limitations:

  • All DS servers must be the same version. Backups are not guaranteed to be compatible across major and minor server releases.

New backend

Create a backend, then one of:

Limitations:

  • The limitations depend on how you initialize the new backend, and are described above.

Broken data set

Restore to a known state

Limitations:

  • This method permanently loses recent changes.

  • Applications using the changelog must be reinitialized after you restore the data.

Initialize over the network

Review Initialization options before following these steps:

  1. Manually initialize replication using the replication protocol’s total update capability in one of these ways:

    1. Overwrite the data in all replicas with the data from the replica where the command runs:

      $ dsrepl \
 initialize \
 --baseDN dc=example,dc=com \
 --toAllServers \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --trustStorePath /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

    2. Initialize a single other replica, identified by its server ID, from the replica where the command runs:

      $ dsrepl \
 initialize \
 --baseDN dc=example,dc=com \
 --toServer ds-1 \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --trustStorePath /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

Initialize from LDIF

If you aim to return to a previous state of the data, or to initialize replicas with LDIF from a non-replicated environment, follow the steps in Restore to a known state instead.

Review Initialization options before following these steps:

Initialize each replica with the same LDIF:

  1. Stop the server.

  2. If desired, enable data confidentiality.

    For details, refer to Data encryption and Encrypt External Changelog Data.

  3. Import the LDIF.

    For details, refer to Import LDIF.

  4. Start the server.

Initialize from backup

Review Initialization options before following these steps:

  1. Stop the replica.

  2. Restore the backend from backup.

    For details, refer to Restore.

  3. Start the replica.

    Replication replays changes from other replicas that have happened since the backup was created.

Restore to a known state

When you restore all replicas to a known state, all updates that happened since the last backup or LDIF export operation are permanently lost. You might make a separate backup copy of the data before the procedure for subsequent analysis.

Applications that use the changelog for change notifications must be reinitialized after this procedure.

DS replication makes all replicas converge on the same data. It mechanically applies new changes everywhere, with newer changes taking precedence over older changes. This behavior is a good thing when the newer changes are correct.

This behavior is a bad thing when a client application bug, or a user error causes many unwanted new changes. You recover from a disaster like this by restoring all replicas to a good, known state.

Review Initialization options before following these steps:

  1. On each replica, prevent changes to the affected data.

    The following example prevents changes to dc=example,dc=com data in the evaluation backend on the target replica:

    # Run the command to prevent changes to the affected data
# on each replica before starting disaster recovery:
$ dsconfig \
 set-backend-prop \
 --backend-name dsEvaluation \
 --set writability-mode:internal-only \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

  2. On a single replica, run the command to force all replicas' generation IDs for the affected data to an invalid state:

    # All replicas should be read-only before you run this command.
# This command stops replication for all replicas; run it once:
$ dsrepl \
 start-disaster-recovery \
 --baseDN dc=example,dc=com \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --trustStorePath /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

    Replication halts on all replicas as the command takes effect.

    No changes made to the affected data while replication is stopped are ever replicated, even after replication resumes.

  3. Restore the data to the same known state in one of these ways:

    • From backup

    • From LDIF

    • Over the network

    On each replica, restore the data from backup files.

    On each replica, import the data from LDIF.

    On a single replica:

    1. Replace the data either by restoring from backup files or by importing from LDIF.

    2. Make sure the replica can connect to all other servers in the topology.

    3. Overwrite the data in other replicas with the dsrepl initialize --toAllServers command.

  4. On a single replica, run the command to recalculate all replicas' generation IDs for the affected data:

    # This command resumes replication for all replicas; run it once.
#
# The replica where you run the command connects to the other servers
# to ensure the generation IDs are the same on all servers.
#
# Stopped replicas do not receive the information to update the generation ID.
# Make sure the replica where you run the command can connect to
# all other servers in the topology at this time:
$ dsrepl \
 end-disaster-recovery \
 --baseDN dc=example,dc=com \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --trustStorePath /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

    Replication resumes on all replicas as the command takes effect.

  5. On each replica, allow write operations on the base DN.

    The following example allows changes to dc=example,dc=com data in the evaluation backend on the target replica:

    # Run the command to allow changes to the affected data
# on each replica after ending disaster recovery:
$ dsconfig \
 set-backend-prop \
 --backend-name dsEvaluation \
 --set writability-mode:enabled \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt
Copyright © 2010-2023 ForgeRock, all rights reserved.