How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I make a backup of configuration data in AM 5.x or 6.x?

Last updated Apr 13, 2021

The purpose of this article is to provide information on backing up configuration data in AM, using DS tools to provide a more reliable and comprehensive backup than using ssoadm.


2 readers recommend this article

Background information

Note

For AM 7 and later, you should refer to the documentation for these processes: Maintenance Guide › Backing Up Configurations.

The Configuration directory (/path/to/openam) contains files created during the install process. Some of these files contain critical information that is required when AM initializes; AM cannot start if these files become corrupt or are missing. For this reason, it is essential to back up the Configuration directory to enable you to recover AM to its original state if needed. The files used when AM initializes includes all the files in the /opends directory and the following files:

  • boot.json or bootstrap (depending on your version of AM).
  • keystore.jceks or keystore.jks depending on which keystore you are using.
  • certificate stores
  • .version

There are two options available for using DS tools to back up your configuration directory: 

  • DS backup and restore - this option is the preferred approach; it should be used when you want to back up configuration data with the intention that you can restore it at a later date, if needed, and it would be replicated to other servers.
  • Export-ldif and import-ldif commands - this option is only required if you may need to revert changes from all replicating servers in the future. Typically this isn't required for configuration data, as you can simply reverse a change if it is no longer required. For example, if you change a configuration setting to TRUE, you can change it back to FALSE to revert the change.

In a replicated environment, the replication changelog has a purge delay of 3 days (by default). With either of these backup options, If you restore a backup taken within this period, the restored server will be able to re-sync with the other DS servers; if you have an older backup, it will never be able to re-sync. It is therefore important to take periodic backups. 

Caution

It is also recommended that you take a file system backup of the directories for each AM server in your deployment as described in Upgrade Guide › Backing Up the Deployment. If you ever need to restore a corrupted AM server, it is essential to have a backup of your configuration store and the file system backup. Additionally, you should back up the $HOME/.openamcfg/ directory; the file used to bootstrap (the bootstrap locator file) is located in this directory.

Using DS backup and restore

You can use a backup command such as the following to back up your configuration directory:

$ ./backup --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --backUpAll --backupDirectory /path/to/ds/bak --start 0
Note

You only need to specify a start time if you are scheduling the backup; you can use --start 0 to perform the backup immediately.

You can tell that the backup command was successful by checking the error log (located in the /path/to/openam/opends/logs directory). If the backup was successful, you should see messages similar to this:

[30/Oct/2016:10:49:19 +0000] category=BACKEND severity=NOTICE msgID=9896349 msg=Backup task 20131030104919093 started execution [30/Oct/2016:10:49:19 +0000] category=TOOLS severity=NOTICE msgID=10944792 msg=Starting backup for backend schema [30/Oct/2016:10:49:19 +0000] category=TOOLS severity=NOTICE msgID=10944792 msg=Starting backup for backend tasks [30/Oct/2016:10:49:19 +0000] category=TOOLS severity=NOTICE msgID=10944792 msg=Starting backup for backend userRoot [30/Oct/2016:10:49:19 +0000] category=JEB severity=NOTICE msgID=8847446 msg=Archived: 00000000.jdb [30/Oct/2016:10:49:19 +0000] category=TOOLS severity=NOTICE msgID=10944795 msg=The backup process completed successfully [30/Oct/2016:10:49:19 +0000] category=BACKEND severity=NOTICE msgID=9896350 msg=Backup task 20131030104919093 finished execution

You can restore changes using the restore command as follows:

$ ./restore --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --backupDirectory /path/to/ds/bak

Using export-ldif and import-ldif

Note

The export-ldif and import-ldif commands must be on the same deployment as the one where the AM encryption keys are located, as AM stores encrypted data in the configuration store, and the keys must be the same across all the servers in a site deployment:

You can back up and restore the configuration directory using export-ldif and import-ldif as follows:

  1. Back up the configuration directory using an export-ldif command such as: $ ./export-ldif --hostname ds1.example.com --port 4444 --includeBranch dc=example,dc=com --backendID userRoot --ldifFile /path/to/backupfile.ldif
  2. Prepare the replicated domain prior to importing the ldif data: You must specify the baseDN of the data you are going to be changing (that is, the one for which you exported ldif data), for example: $ ./dsreplication pre-external-initialization --hostname ds1.forgerock.com --port 4444 --baseDN dc=example,dc=com --adminUID admin --adminPassword password --trustAll --no-prompt
  3. Restore the configuration on all servers using an import-ldif command such as: $ ./import-ldif --hostname ds1.example.com --port 4444 --includeBranch dc=example,dc=com --backendID userRoot --ldifFile /path/to/backupfile.ldif
  4. Enter the following command on one of the servers to set the new generation ID for the entire domain: $ ./dsreplication post-external-initialization --hostname ds1.forgerock.com --port 4444 --baseDN dc=example,dc=com --adminUID admin --adminPassword password --trustAll --no-prompt

The above steps alter the generation ID of the replicated domain. "Old" changes will not get replayed because they were targeting the data using the previous generation ID. The final step calculates a new generation ID for the domain and broadcasts it to all the servers, which allows them to replicate again.

Replication will now proceed as normal, but from the restored point in time.

See Also

FAQ: Backing up AM

How do I export and import Service configurations for AM (All versions)?

Installing and configuring AM

Setup and Maintenance Guide › Backing Up and Restoring Configurations

Administration Guide › Backing Up and Restoring Data

Administration Guide › Managing Directory Data

Reference › Tools Reference

Related Training

N/A

Related Issue Tracker IDs

N/A


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