How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I tune Background Database Verification in DS (All versions)?

Last updated Jun 15, 2021

The purpose of this article is to provide information on tuning Background Database Verification in DS. The JE database periodically performs automatic database verification, which can impact service availability.


Overview

The JE embedded database used in DS backends includes a feature that verifies the entire database at midnight every night to check for some common types of database corruption. The extra disk I/O can result in problems for performance-critical deployments. All the servers in a single timezone will run the verification at exactly the same time, which can also cause more widespread issues.

Note

Recovering from any database corruption would typically involve reinitializing the replica directory server or restoring it from a backup taken before the corruption occurred. See Backup and Restore (DS 7 and later) or FAQ: Backup and restore in DS 5.x and 6.x for further information.

See the following sections for information on configuring the JE verifier depending on version:

The functionality described here does not apply if you use the PDB backend. The PDB backend type was deprecated in DS 5 and removed in DS 6. 

DS 6 and later

DS 6 and later provides advanced properties for configuring the JE verifier (db-run-log-verifier and db-log-verifier-schedule), which allow you to:

  • Configure the JE verifier schedule
  • Disable the JE verifier

See Advanced Properties for further information.

Configuring the JE verifier schedule

By default, the JE verifier runs automatically at midnight local time. It is best practice to alter the verification schedule on each server to avoid all servers simultaneously using extra disk I/O and potentially impacting the entire service.

The verifier schedule is a cron-style field and can be set using the dsconfig command. The following example sets the verifier for the exampleBackend backend to run at 1am (local time):

  • DS 7.1 and later: $ ./dsconfig set-backend-prop --backend-name exampleBackend --set db-run-log-verifier:true --set 'db-log-verifier-schedule:0 1 * * *' --hostname ds1.example.com --port 4444 --bindDN uid=admin --bindPassword password --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --no-prompt
  • DS 7: $ ./dsconfig set-backend-prop --backend-name exampleBackend --set db-run-log-verifier:true --set 'db-log-verifier-schedule:0 1 * * *' --hostname ds1.example.com --port 4444 --bindDN uid=admin --bindPassword password --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --no-prompt
  • DS 6.x: $ ./dsconfig set-backend-prop --backend-name exampleBackend --set db-run-log-verifier:true --set 'db-log-verifier-schedule:0 1 * * *' --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --trustAll --no-prompt

You must restart the DS server to apply these changes.

Disabling the JE verifier

The JE verifier can be completely disabled, which means that some types of database corruption will not be reported.

You can use the dsconfig command to disable verification on a single backend. For example, to disable it on the exampleBackend backend:

  • DS 7.1 and later: $ ./dsconfig set-backend-prop --backend-name exampleBackend --set db-run-log-verifier:false --hostname ds1.example.com --port 4444 --bindDN uid=admin --bindPassword password --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --no-prompt
  • DS 7: $ ./dsconfig set-backend-prop --backend-name exampleBackend --set db-run-log-verifier:false --hostname ds1.example.com --port 4444 --bindDN uid=admin --bindPassword password --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --no-prompt
  • DS 6.x: $ ./dsconfig set-backend-prop --backend-name exampleBackend --set db-run-log-verifier:false --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --trustAll --no-prompt

You must restart the DS server to apply these changes.

DS 5.x

In DS 5.x, you can configure the JE verifier in one of two ways:

  • Configure the JE verifier schedule
  • Disable the JE verifier

Configuring the JE verifier schedule

By default, the JE verifier runs automatically at midnight local time. It is best practice to alter the verification schedule on each server to avoid all servers simultaneously using extra disk I/O and potentially impacting the entire service.

The verifier schedule is a cron-style field and can be set using the dsconfig command. The following example sets the verifier for the userRoot backend to run at 1am (local time):

$ ./dsconfig set-backend-prop --backend-name userRoot --set 'je-property:je.env.verifySchedule:0 1 * * *' --hostname ds1.example.com --port 4444 --bindDn "cn=Directory Manager" --bindPassword password --trustAll --no-prompt

You must restart the DS server to apply these changes.

Disabling the JE verifier

The JE verifier can be completely disabled, which means that some types of database corruption will not be reported.

You can use the dsconfig command to disable verification on a single backend. For example, to disable it on the userRoot backend:

$ ./dsconfig set-backend-prop --backend-name userRoot --set je-property:je.env.runVerifier=false --hostname ds1.example.com --port 4444 --bindDn "cn=Directory Manager" --bindPassword password --trustAll --no-prompt

You must restart the DS server to apply these changes.

See Also

Installing and Administering DS

Performance tuning and monitoring ForgeRock products

Related Training

N/A

Related Issue Tracker IDs

OPENDJ-4465 (Facilitate configuration of JE backend's DB verification feature)

OPENDJ-4418 (Investigate how to disable automatic JE database verification using JE properties)


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