How do I configure DS 6.x to ensure accidentally deleted or changed data can be restored when replication is enabled?

Last updated Jan 11, 2023

The purpose of this article is to provide information on configuring DS to provide a simple way of restoring accidentally deleted or changed data when replication is enabled.

Warning

Do not compress, tamper with, or otherwise alter changelog database files directly unless specifically instructed to do so by a qualified ForgeRock technical support engineer. External changes to changelog database files can render them unusable by the server. By default, changelog database files are located under the /path/to/ds/changelogDb directory.

Note

This article does not apply to DS 7 and later, because DS 7 introduces improvements to simplify replication and backup/restore. If you need to revert accidental deletions of data in DS 7 and later, you should refer to the appropriate documentation:

Overview

Accidental deletions of data in DS can be reverted in two ways:

The first way, described in this article, configures the replication changelog to record additional information about each change. This allows changes to be reverted at a very fine-grained level and with very little impact on the servers in the replication topology. However, reverting each change requires several manual steps.
The second way, described in How do I roll back an entire network of DS 6.x replicas to a previous backup?, uses the backup and restore tools. This is comparatively coarse as you can only restore up until a given backup and it does require that every replicating server is reinitialized.

Using the External Changelog

The External Changelog (cn=changelog) records all changes but you must configure it to record additional details if you want to use it for restoring deleted or changed data. You can then manually re-apply each change, for example, using ldapmodify.

Caution

Configuring the changelog to include this additional data will increase the size of the changelog; you must ensure you have sufficient disk space for this prior to making these changes. Information is kept in the changelog for three days by default; you can increase this retention period if required, although you should be aware that this will also increase the size of the changelog. The changelog is stored in the replication changes database (changelogDb directory).

This article contains the following sections to guide you through this process:

Configuring the changelog
Retrieving deleted or changed data from the changelog
Finding change numbers

Configuring the changelog

You can configure the changelog to ensure it contains sufficient information as follows:

Enter the following command in your terminal window to record additional information for deleted data: $ ./dsconfig set-external-changelog-domain-prop --port 4444 --hostname ds1.example.com --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --domain-name dc=example,dc=com --add ecl-include-for-deletes:"*" --add ecl-include-for-deletes:"+" When an entry is deleted, the changelogEntry will now have an additional includedAttributes attribute that contains the encoded contents of the deleted entries.
Enter the following command in your terminal window to record additional information for changed data: $ ./dsconfig set-external-changelog-domain-prop --port 4444 --hostname ds1.example.com --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --domain-name dc=example,dc=com --add ecl-include:"*" --add ecl-include:"+" When an entry is changed, the changelogEntry will now have an additional includedAttributes attribute that contains the encoded contents of the changed entries.

Retrieving deleted or changed data from the changelog

You can query your changelog for specific changes using a command similar to the following in your terminal window:

$ ./ldapsearch --hostname ds1.example.com --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN cn=changelog --searchScope one "(changenumber>=100)" "*" "+"

This example will return changes for change 100 onwards; you can filter the search on other attributes, for example, change time.

The changelog shows a changeType attribute for each entry so you can identify if it resulted from a change or delete action. The original data that was changed or deleted is encoded in the includedAttributes attribute. You can decode this using a Base64 decoder (for example, the base64 program provided with DS or http://www.base64decode.org/) to retrieve the original data.

See How do I search and view the changelog records in DS (All versions)? for further information on querying the changelog.

Finding change numbers

If you do not know the change number, you can use one of the following approaches to find it depending on which is the most appropriate to your setup:

Return the firstchangenumber and lastchangenumber attributes

You can use an ldapsearch command to return the firstchangenumber and lastchangenumber attributes. For example:

$ ./ldapsearch --port 1389 --hostname ds1.example.com --bindDN "cn=Directory Manager" --bindPassword password --baseDN "" --searchScope base '(objectclass=*)' firstchangenumber lastchangenumber

Example output:

dn: firstchangenumber: 1 lastchangenumber: 6

Return a range of change numbers

You can use an ldapsearch command to return change numbers for a known range. For example:

$ ./ldapsearch --port 1389 --hostname ds1.example.com --bindDN "cn=Directory Manager" --bindPassword password --baseDN cn=changelog --searchScope one "(&(changeNumber>=2)(changeNumber<=5))"

Return change numbers for a specific change time

You can use an ldapsearch command to return change numbers with a known change time. For example:

$ ./ldapsearch --port 1389 --hostname ds1.example.com --bindDN "cn=Directory Manager" --bindPassword password --baseDN cn=changelog --searchScope one '(changeTime<=20180417224638Z)'

Return all change numbers

You can use an ldapsearch command to check the changelog status. For example:

$ ./ldapsearch --port 1389 --hostname ds1.example.com --bindDN "cn=Directory Manager" --bindPassword password --baseDN cn=changelog --searchScope one changelog=*

The above ldapsearch provides a detailed output of your changelog history. If you make extensive or frequent changes to your Directory Server, checking the entire changelog can result in producing a substantial amount of data.

Related Training

ForgeRock Directory Services Core Concepts (DS-400)

Related Issue Tracker IDs

N/A