How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I search and view the changelog records in DS (All versions)?

Last updated Jun 10, 2021

The purpose of this article is to provide information on searching and viewing the changelog information in DS.


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.

Overview

The External Changelog (cn=changelog) records all replication changes.

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

Note

The changelog only shows the value of the new change by default. To view the original values that were changed, you must configure the changelog to record additional information for deleted data as described in Recover From User Error.

Changelog availability by replication topology

The availability of the External Changelog depends on your replication topology as outlined below. Once it is available, you can query the changelog and revert changes as needed.

DS+RS replication topology

The changelog is automatically set up in a DS+RS replication topology once replication is configured for a suffix. 

Standalone replication servers (RS)

As of DS 6.5, you can also read the changelog from a RS instance. Typically, a RS instance does not expose any external LDAP connection handlers because a RS does not have any data backends (so a connection handler is not a setup option). If you want to read the changelog from a RS instance, you must:

  1. Enable the External Chaneglog as detailed in: Enable the External Changelog.
  2. Enable an LDAP/LDAPS connection handler on the RS so that you can externally read cn=changelog. For example, to enable an LDAPS connection handler:
    • DS 7.1 and later: $ ./dsconfig create-connection-handler --hostname ds1.example.com --port 4444 --bindDN uid=admin --bindPassword password --handler-name LDAPS --type ldap --set enabled:true --set listen-port:1636 --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --no-prompt
    • DS 7: $ ./dsconfig create-connection-handler --hostname ds1.example.com --port 4444 --bindDN uid=admin --bindPassword password --handler-name LDAPS --type ldap --set enabled:true --set listen-port:1636 --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --no-prompt
    • Pre-DS 7: $ ./dsconfig create-connection-handler --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --handler-name LDAPS --type ldap --set enabled:true --set listen-port:1636 --trustAll --no-prompt

Standalone directory servers (DS)

A standalone DS (with no replication server) does not host a changelog because there is no replication element.

Querying the changelog

You can query your changelog for specific changes using the ldapsearch command. You can filter the search based on different attributes, for example, the change number or change time. 

DS 7 and later

The following example demonstrates querying and decoding the changelog by changenumber in DS 7 and later.

  1. Query the changelog using a command similar to the following (this example looks at change 5 only):
    • DS 7.1 and later: $ ./ldapsearch --hostname ds1.example.com --port 1636 --useSsl --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --bindDN uid=admin --bindPassword password --baseDN cn=changelog --searchScope one "(changenumber=5)" "*" "+"
    • DS 7:  $ ./ldapsearch --hostname ds1.example.com --port 1636 --useSsl --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --bindDN uid=admin --bindPassword password --baseDN cn=changelog --searchScope one "(changenumber=5)" "*" "+"

This gives an output similar to this: dn: changeNumber=5,cn=changelog objectClass: top objectClass: changeLogEntry changeNumber: 5 changeTime: 20140501152505Z changeType: modify targetDN: o=test organization,dc=example,dc=com changes:: cmVwbGFjZTogZGVzY3JpcHRpb24KZGVzY3JpcHRpb246IE1vZGlmaWVkIHZhbHVlCi0Kcm VwbGFjZTogbW9kaWZpZXJzTmFtZQptb2RpZmllcnNOYW1lOiBjbj1EaXJlY3RvcnkgTWFuYWdlcixjb  j1Sb290IEROcyxjbj1jb25maWcKLQpyZXBsYWNlOiBtb2RpZnlUaW1lc3RhbXAKbW9kaWZ5VGltZXN0  YW1wOiAyMDE0MDUwMTE1MjUwNVoKLQo= subschemaSubentry: cn=schema numSubordinates: 0 hasSubordinates: false entryDN: changeNumber=5,cn=changelog replicationCSN: 00000145b86396664d4b00000005 replicaIdentifier: 19787 changeInitiatorsName: uid=admin targetEntryUUID: d1f8fa64-d0ef-42a8-b551-038415a2ae3b changeLogCookie: dc=example,dc=com:00000145b86396664d4b00000005; includedAttributes:: b2JqZWN0Q2xhc3M6IHRvcApvYmplY3RDbGFzczogb3JnYW5pemF0aW9uCmR  lc2NyaXB0aW9uOiBPcmlnaW5hbCB2YWx1ZQpvOiBUZXN0IE9yZ2FuaXphdGlvbgpkcy1zeW5jLWhpc3  Q6IGRuOjAwMDAwMTQ1Yjg2MzQzNDg0ZDRiMDAwMDAwMDQ6YWRkCmVudHJ5VVVJRDogZDFmOGZhNjQtZ  DBlZi00MmE4LWI1NTEtMDM4NDE1YTJhZTNiCmNyZWF0ZVRpbWVzdGFtcDogMjAxNDA1MDExNTI0NDRa  CmNyZWF0b3JzTmFtZTogY249RGlyZWN0b3J5IE1hbmFnZXIsY249Um9vdCBETnMsY249Y29uZmlnCmV  0YWc6IDAwMDAwMDAwM2E5ZjQ2ODcKc3RydWN0dXJhbE9iamVjdENsYXNzOiBvcmdhbml6YXRpb24KcH  dkUG9saWN5U3ViZW50cnk6IGNuPURlZmF1bHQgUGFzc3dvcmQgUG9saWN5LGNuPVBhc3N3b3JkIFBvb  GljaWVzLGNuPWNvbmZpZwpudW1TdWJvcmRpbmF0ZXM6IDAKaGFzU3Vib3JkaW5hdGVzOiBmYWxzZQpz  dWJzY2hlbWFTdWJlbnRyeTogY249c2NoZW1hCmVudHJ5RE46IG89dGVzdCBvcmdhbml6YXRpb24sZGM  9ZXhhbXBsZSxkYz1jb20KThis change represents a modification to the <o=test organization,dc=example,dc=com> entry.

  1. Decode the changes attribute using a Base64 decoder. This provides details of the change (along with changes the server is making to the standard modifiersName and modifyTimestamp attributes): replace: description description: Modified value - replace: modifiersName modifiersName: uid=admin - replace: modifyTimestamp modifyTimestamp: 20140501152505Z -In this example, the type of modification (replace) that was used does not include the old values of the attribute that's changed. To view the original value you must first configure the changelog to record additional information for deleted data if you want the DS to store old values as shown in this example includedAttributes entry.
  2. Decode the includedAttributes attribute using a Base64 decoder: objectClass: top objectClass: organization description: old description o: Test Organization ds-sync-hist: dn:00000145b86343484d4b00000004:add entryUUID: d1f8fa64-d0ef-42a8-b551-038415a2ae3b createTimestamp: 20140501152444Z creatorsName: uid=admin etag: 000000003a9f4687 structuralObjectClass: organization pwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config numSubordinates: 0 hasSubordinates: false subschemaSubentry: cn=schema entryDN: o=test organization,dc=example,dc=comNow we can see the original value (in this example, it is old description).

Pre-DS 7

The following example demonstrates querying and decoding the changelog by changenumber in pre-DS 7.

  1. Query the changelog using a command similar to the following (this example looks at change 5 only): $ ./ldapsearch --port 1389 --hostname ds1.example.com --bindDN "cn=Directory Manager" --bindPassword password --baseDN cn=changelog --searchScope one "(changenumber=5)" "*" "+"This gives an output similar to this: dn: changeNumber=5,cn=changelog objectClass: top objectClass: changeLogEntry changeNumber: 5 changeTime: 20140501152505Z changeType: modify targetDN: o=test organization,dc=example,dc=com changes:: cmVwbGFjZTogZGVzY3JpcHRpb24KZGVzY3JpcHRpb246IE1vZGlmaWVkIHZhbHVlCi0Kcm VwbGFjZTogbW9kaWZpZXJzTmFtZQptb2RpZmllcnNOYW1lOiBjbj1EaXJlY3RvcnkgTWFuYWdlcixjb  j1Sb290IEROcyxjbj1jb25maWcKLQpyZXBsYWNlOiBtb2RpZnlUaW1lc3RhbXAKbW9kaWZ5VGltZXN0  YW1wOiAyMDE0MDUwMTE1MjUwNVoKLQo= subschemaSubentry: cn=schema numSubordinates: 0 hasSubordinates: false entryDN: changeNumber=5,cn=changelog replicationCSN: 00000145b86396664d4b00000005 replicaIdentifier: 19787 changeInitiatorsName: cn=Directory Manager targetEntryUUID: d1f8fa64-d0ef-42a8-b551-038415a2ae3b changeLogCookie: dc=example,dc=com:00000145b86396664d4b00000005; includedAttributes:: b2JqZWN0Q2xhc3M6IHRvcApvYmplY3RDbGFzczogb3JnYW5pemF0aW9uCmR  lc2NyaXB0aW9uOiBPcmlnaW5hbCB2YWx1ZQpvOiBUZXN0IE9yZ2FuaXphdGlvbgpkcy1zeW5jLWhpc3  Q6IGRuOjAwMDAwMTQ1Yjg2MzQzNDg0ZDRiMDAwMDAwMDQ6YWRkCmVudHJ5VVVJRDogZDFmOGZhNjQtZ  DBlZi00MmE4LWI1NTEtMDM4NDE1YTJhZTNiCmNyZWF0ZVRpbWVzdGFtcDogMjAxNDA1MDExNTI0NDRa  CmNyZWF0b3JzTmFtZTogY249RGlyZWN0b3J5IE1hbmFnZXIsY249Um9vdCBETnMsY249Y29uZmlnCmV  0YWc6IDAwMDAwMDAwM2E5ZjQ2ODcKc3RydWN0dXJhbE9iamVjdENsYXNzOiBvcmdhbml6YXRpb24KcH  dkUG9saWN5U3ViZW50cnk6IGNuPURlZmF1bHQgUGFzc3dvcmQgUG9saWN5LGNuPVBhc3N3b3JkIFBvb  GljaWVzLGNuPWNvbmZpZwpudW1TdWJvcmRpbmF0ZXM6IDAKaGFzU3Vib3JkaW5hdGVzOiBmYWxzZQpz  dWJzY2hlbWFTdWJlbnRyeTogY249c2NoZW1hCmVudHJ5RE46IG89dGVzdCBvcmdhbml6YXRpb24sZGM  9ZXhhbXBsZSxkYz1jb20KThis change represents a modification to the <o=test organization,dc=example,dc=com> entry.
  2. Decode the changes attribute using a Base64 decoder. This provides details of the change (along with changes the server is making to the standard modifiersName and modifyTimestamp attributes): replace: description description: Modified value - replace: modifiersName modifiersName: cn=Directory Manager - replace: modifyTimestamp modifyTimestamp: 20140501152505Z -In this example, the type of modification (replace) that was used does not include the old values of the attribute that's changed. To view the original value you must first configure the changelog to record additional information for deleted data if you want the DS to store old values as shown in this example includedAttributes entry.
  3. Decode the includedAttributes attribute using a Base64 decoder: objectClass: top objectClass: organization description: old description o: Test Organization ds-sync-hist: dn:00000145b86343484d4b00000004:add entryUUID: d1f8fa64-d0ef-42a8-b551-038415a2ae3b createTimestamp: 20140501152444Z creatorsName: cn=Directory Manager etag: 000000003a9f4687 structuralObjectClass: organization pwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config numSubordinates: 0 hasSubordinates: false subschemaSubentry: cn=schema entryDN: o=test organization,dc=example,dc=comNow we can see the original value (in this example, it is old description).

Reverting a change

Once you have identified the original value (description: old description in the above example), you can restore it as follows:

  1. Create a ldif file with the current value and the value you want to restore. For example: $ cat revert-changes.ldif dn: o=test organization,dc=example,dc=com changetype: modify  replace: description description: old description
  2. Apply the changes using the following ldapmodify command depending on your version:
    • DS 7.1  and later: $ ./ldapmodify --hostname ds1.example.com --port 1636 --useSsl --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --bindDN uid=admin --bindPassword password revert-changes.ldif
    • DS 7: $ ./ldapmodify --hostname ds1.example.com --port 1636 --useSsl --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --bindDN uid=admin --bindPassword password revert-changes.ldif
    • Pre-DS 7: $ ./ldapmodify --hostname ds1.example.com --port 1389 --bindDN "cn=Directory Manager" --bindPassword password revert-changes.ldif

See Also

How do I understand the changelogDb directory in DS (All versions)?

How do I control how long replication changes are retained in DS (All versions)?

How do I troubleshoot replication issues in DS 5.x and 6.x?

Replication in DS

Changelog for Notifications

Related Training

N/A

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.