FAQ
ForgeRock Identity Platform
Does not apply to Identity Cloud

FAQ: Backup and restore in DS 5.x and 6.x

Last updated Apr 8, 2021

The purpose of this FAQ is to provide answers to commonly asked questions regarding backing up and restoring DS. This article does not apply to DS 7 and later because the backup and restore implementation has changed in DS 7.


1 reader recommends this article

Frequently asked questions

Note

This article does not apply to DS 7 and later, because DS 7 introduces a simplified implementation for backup and restore operations. See Release Notes › What's New (Backup and Restore) for further information.

Q. Do I have to do a full backup each time?

A. You should ideally use a mixture of full and incremental backups to ensure you have a comprehensive backup strategy in place.

See How do I design and implement my backup and restore strategies for DS 5.x and 6.x? for further information on designing your backup and restore strategy.

Q. Can I use the backup and restore commands to import directory data into a new server instance?

A. Yes you can provided the DS major versions are the same (for example, 6.0 to 6.5).

Q. What backup ID is used if incrementalBaseID is blank?

A. If you leave the incrementalBaseID option blank when performing a backup, the ID of the last backup is automatically used. If the backup directory is blank, a full backup will be taken; otherwise an incremental backup will be taken based on the last backup performed (regardless of whether it was an incremental or full backup).

Q. My incremental backup is bigger than expected, why is this?

A. The resolution of incremental backups is per JDB file. If your backend is made up of 10MB JDB files, then even with just a single operation between backups, the resulting incremental backup could be up to 10MB. If you have 100MB sized JDB files this could be up to 100MB. This is because the entire 'latest' JDB file would need to be copied for the incremental backup.

Q. Does the backup command back up everything I need to fully restore DS?

A. No, there are a number of files that you should also manually back up, as detailed in the Other Required Files section in How do I design and implement my backup and restore strategies for DS 5.x and 6.x?

Q. How do I check the data integrity of a backup?

A. You can validate the data integrity of a backup as follows:

  1. Restore the backup to a temporary isolated server that is not replicating with the existing topology.
  2. Run a command such as rebuild-index -all, export-ldif or verify-index to force the list of backup *.jdb files to be read. The command will fail if any of the files contain corrupt data.

Q. How should I restore the data if I have done a backup --backupAll?

A. You should restore the userRoot backup using the restore command, and then restore the schema and task backups by copying the relevant files across:

  • For schema, you need the schema directory (located in /path/to/ds/config). In DS 6.x, schema is located in /path/to/ds/db for new installs.
  • For tasks, you just need the tasks.ldif file (located in /path/to/ds/db/tasks in DS 6.x, or /path/to/ds/config in DS 5.x).

You can either use the restore command to copy these files across or you can copy them yourself. If you copy them using the restore command, the backend is automatically taken offline during the copy; if you copy them yourself, you will need to ensure the server is stopped or the schema backend is offline. You can use a restore command such as the following to copy a directory or file across:

$ ./restore --backupDirectory /path/to/bak/schema/ --backupID 20160614031032Z

See How do I design and implement my backup and restore strategies for DS 5.x and 6.x? for further information on the files that are backed up.

Q. If I add new attributes / objectClass and then create a backup, will my backup contain the definition of these entities?

A. When you add new attributes or an objectClass, the changes are written to the cn=schema backend; this is stored in the 99-user.ldif file (located in /path/to/ds/config/schema or /path/to/ds/db if you have a new install on DS 6.x). If you back up this directory and restore it to another server, your schema changes will be preserved.

Schema is also copied across from one server to another when you run the dsreplication configure command.

Q. What impact does a backup have on a running server?

A. There is little impact to LDAP clients. Users can still search and write data while the backup is taking place, and replication continues to work normally. The administrator should see an increased number of reads from the source disk (that is, holding the backend being backed up) as the backup process essentially reads the entire database. The administrator should also see an increased number of writes on the target disk as the backup is written. It is best practice for the source disk and the target disk to be different. There may be some additional CPU utilization if the backup is being compressed.

Q. Can I remove old backup files to free up space?

A. Yes, you can delete or move old backup files to a different location to free up space as required. You must then edit the backup.info file (located in the /path/to/ds/bak directory) to remove the reference to the file(s) you deleted or moved to ensure this file stays in sync with your actual backups.

There is a RFE for managing backups and keeping the backup.info file in sync: OPENDJ-1310 (Manage backup retention). This is resolved in DS 7 as part of the new backup and restore implementation.

Q. What key is used if I encrypt the backup?

A. DS uses a 128-bit secret key stored in the admin-backend, for example, <ds-cfg-key-id=d2d8c278-9fcb-434b-a8cc-0ec237e54644,cn=secret keys,cn=admin data> and encrypts using AES/CBC/PKCS5Padding by default. The key length and cipher are advanced properties of the Crypto Manager; you can use dsconfig --advanced to change them.

Additionally, the keys are shared between replicas, which allows you to restore an encrypted backup to any server.

Q. What happens if the backend being restored is also encrypted?

A. If the backend being restored is also encrypted and you still have operational servers in your replication topology, then you need to first enable replication before restoring the encrypted database. Enabling replication (without initializing) allows the new instance to get all the necessary key material to decrypt the backend. This is described in Administration Guide › To Restore a Replica.

In a disaster recovery type scenario where you do not have access to the servers with the key material, you should follow this process instead (which is noted in the above procedure):

  1. Set up a new server using ./setup. This should just be a basic setup that includes a backend with the correct suffix, but no data.
  2. Stop the new server.
  3. Overwrite the following files from your file-system backup of the original server:
    • admin-backend.ldif (located in /db/adminRoot in DS 6.5.x, /db/admin in DS 6.x or /config in DS 5.x)
    • ads-truststore (located in /path/to/ds/config or /path/to/ds/db/ads-truststore if you have a new install on DS 6.x)
    • ads-truststore.pin (located in /path/to/ds/config or /path/to/ds/db/ads-truststore if you have a new install on DS 6.x)
  4. Restore your encrypted backend data.
  5. Start the new server.

Q. Can I just back up one node if I have replication enabled?

A. This is subjective and can depend on the size of your database. However, you can just back up one node and use that to restore another node, but if you have a large database, transfer times may make this unviable.

It is also worth considering storing your backups offsite incase all nodes need recovering, for example, in a disaster recovery situation.

Q. What changes are applied when I restore a node?

A. When you restore a node, changes are applied according to the replication change log.

For example, if you stopped server 2 and restored it from a previous backup, added a new user on server 1 and restarted server 2, the new user you added on server 1 would be replicated to server 2.

Q. How can I recover accidentally deleted or changed data when replication is enabled?

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

Q. Can I rebuild DS using data from another server if I don't have a current backup?

A. Yes you can, although it is always preferable to have a valid backup to restore. See How do I restore DS 5.x or 6.x from another DS instance? for further information.

Q. How do I change the replication purge delay setting?

A.  You can change the replication purge delay setting (replication-purge-delay) to control how long replication changes are retained in the changelogDb as described in How do I control how long replication changes are retained in DS (All versions)?

Q. What should I change the replication purge delay setting to?

A. This depends on your system and backup schedule. For example, if you back up daily, you could reduce your purge delay to 1.5 or 2 days as you would be able to recover any changes from your backup.

Q. When does the replication purge take place?

A. The replication purge is continually happening in the background, removing individual entries / modifications as they become stale (based on the purge delay setting). For example, if you set your purge delay setting to 1 day, individual changes would be purged from the changelogDb as follows:

  • Change 1: added May 1, 1am - purged May 2, 1am.
  • Change 2: added May 1, 10am - purged May 2, 10am.
  • Change 3: added May 1, 1pm - purged May 2, 1pm.
  • Change 4: added May 1, 2pm - purged May 2, 2pm.
  • Change 5: added May 1, 3pm - purged May 2, 3pm.

Q. Can I recover a corrupted config.ldif file?

A. Yes, DS makes copies of the config files as follows, which should enable you to recover this file if needed:

  • Each time you start the server and it starts without errors, DS copies the config.ldif file to /path/to/ds/var/archived-configs in DS 6.x, or /path/to/ds/config/archived-configs in DS 5.x and adds a timestamp to the filename. If you have changed something that prevents the server starting, you can copy the last known good file from this directory or use the files as a reference as to what has changed.
  • Each time you start the server and it starts without errors, DS copies the config.ldif file to config.ldif.startok. This means that the last time the server started it was using the config.ldif.startok file. If the current config.ldif fails to start the server for some reason, you can manually copy back the config.ldif.startok to config.ldif and restart the server.
  • Each time you use the backup command, the server also saves the config files in the /archived-configs directory to a location within the backup archive itself. You can use these to manually copy (revert) back to a known good configuration.

Restoring an old config file

You can restore an old config file from /archived-configs as follows:

  1. Stop the DS server: $ ./stop-ds
  2. Copy across the required archived config file: $ cp archived-configs/XXXXXXconfigfile ./config.ldif
  3. Restart the DS server: $ ./start-ds

See Also

How do I relocate the backend database files in DS (All versions) on to a separate file system?

Installing and Administering DS

Administration Guide › Backing Up and Restoring Data

Administration Guide › Backing Up Directory Data

Administration Guide › Restoring Directory Data From Backup

Related Training

ForgeRock Directory Services Core Concepts (DS-400)


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