--- title: Retaining backups description: The backup tool can use the --retainPreviousFullBackupCount or --retainPreviousFullBackupAge arguments to identify which previous backups to preserve. component: pingdirectory version: 11.0 page_id: pingdirectory:pingdirectory_server_administration_guide:pd_ds_retain_backups canonical_url: https://docs.pingidentity.com/pingdirectory/11.0/pingdirectory_server_administration_guide/pd_ds_retain_backups.html revdate: September 13, 2023 page_aliases: ["pd_ds_list_available_backups_on_system.adoc", "pd_ds_back_up_all_backends.adoc", "pd_ds_back_up_single_backend.adoc", "pd_ds_perform_offline_restore.adoc", "pd_ds_assign_id_to_backup.adoc", "pd_ds_schedule_online_backup.adoc", "pd_ds_schedule_online_restore.adoc", "pd_ds_encrypt_backup.adoc", "pd_ds_sign_hash_backup.adoc", "pd_ds_restore_backup.adoc"] section_ids: listing-the-available-backups-on-the-system: Listing the available backups on the system steps: Steps result: Result: backing-up-all-backends: Backing up all backends about-this-task: About this task steps-2: Steps backing-up-a-single-backend: Backing up a single backend steps-3: Steps performing-an-offline-restore: Performing an offline restore about-this-task-2: About this task steps-4: Steps assigning-an-id-to-a-backup: Assigning an ID to a backup steps-5: Steps result-2: Result: scheduling-an-online-backup: Scheduling an online backup about-this-task-3: About this task steps-6: Steps example: Example: result-3: Result: scheduling-an-online-restore: Scheduling an online restore about-this-task-4: About this task steps-7: Steps example-2: Example: encrypting-a-backup: Encrypting a backup about-this-task-5: About this task steps-8: Steps example-3: Example: signing-a-hash-of-the-backup: Signing a hash of the backup steps-9: Steps choose-from: Choose from: restoring-a-backup: Restoring a backup about-this-task-6: About this task steps-10: Steps example-4: Example: --- # Retaining backups The backup tool can use the `--retainPreviousFullBackupCount` or `--retainPreviousFullBackupAge` arguments to identify which previous backups to preserve. Any other backups in that directory are removed. A new backup is always preserved. However, older backups in the same directory are eligible to be removed. If you include the `--retainPreviousFullBackupCount` argument, that number of the most recent previous full backups are preserved and any other previous full backups are removed. A value of zero can be specified for the `--retainPreviousFullBackupCount` argument so that only the most recent backup is preserved and all previous backups are removed. If you include the `--retainPreviousFullBackupAge` argument, its value must be a duration represented as an integer followed by a time unit. Any full backups created longer ago than that duration are eligible to be removed. If you include both the `--retainPreviousFullBackupCount` and `--retainPreviousFullBackupAge` arguments, then only backups that don't satisfy either condition are deleted. The `remove-backup` tool also supports the `--retainFullBackupCount` and `--retainFullBackupAge` arguments to delete any backups outside the provided retention criteria. ## Listing the available backups on the system Use the `restore` tool to list the backups in a `backup` directory. ### Steps * To list the existing backups in a specific backup directory, run the following command. ```shell $ bin/restore --listBackups --backupDirectory ``` #### Result: ``` [13:26:21] The console logging output is also available in '/ds/PingDirectory/logs/ tools/restore.log' Backup ID: 20120212191715Z Backup Date: 12/Feb/2012:13:17:19 -0600 Is Compressed: false Is Encrypted: false Has Unsigned Hash: false Has Signed Hash: false ``` ## Backing up all backends Use `backup` to save the all of the server's backends. ### About this task The `--compress` option can reduce the amount of space that the backup consumes, but can also significantly increase the time required to perform the backup. ### Steps * To back up all backends and compress the backups, run the following. ```shell $ bin/backup --backUpAll --compress --backupDirectory ``` ## Backing up a single backend Use the `–-backendID` argument to specify a single backend to back up. ### Steps * To back up the `userRoot` directory and compress the backup, use the following command. ```shell $ bin/backup --backendID userRoot --compress --backupDirectory ``` ## Performing an offline restore Use the `restore` command to restore a backed up backend. ### About this task Only a single backend can be restored at a time. The PingDirectory server must be shut down before performing an offline restore. | | | | - | ----------------------------------------------------------------------------------------- | | | The server root directory should never be restored from a file system backup or snapshot. | ### Steps 1. To stop the PingDirectory server run the following command. ```shell $ bin/stop-server ``` 2. To restore a saved backup, run the following command. ```shell $ bin/restore --backupDirectory ``` 3. To start the server, run the following command. ```shell $ bin/start-server ``` ## Assigning an ID to a backup Use the `--backupID` argument to assign an ID to a backup. ### Steps * To back up the userRoot directory, run the following command. ```shell $ bin/backup --backupDirectory userRoot \ --backendID userRoot --backupID weekly ``` The `--backupID` argument identifies the backup being created as "weekly". #### Result: The backup file appears under `backups/userRoot` directory as `userRoot-backup-weekly`. ## Scheduling an online backup ### About this task You can schedule a backup to run as a task by specifying the timestamp with the `--task` and `--start` options. The option is expressed in "YYYYMMDDhhmmss'" format. If the option has a value of `0`, then the task is scheduled for immediate execution. Because you can't run recurring tasks, you must run daily operations using cron or another system that can submit the task. For online (remote) backups, you can conduct the backup operation while the PingDirectory server is online if you provide information about how to connect and to authenticate to the target PingDirectory server. ### Steps * To schedule the backup to occur at a specific time, use the task-based `--start YYYYMMDDhhmmss` option. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | To specify a time in the UTC time zone format, add a trailing `Z` to the time. Otherwise, the time is treated as a local time in the time zone configured on the server. | #### Example: ```shell $ bin/backup --backUpAll --task --start 20111025010000 \ --backupDirectory /path/to/backup --completionNotify admin@example.com \ --errorNotify admin@example.com ``` #### Result: ``` Backup task 2011102500084110 scheduled to start Oct 28, 2011 1:00:00 AM CDT ``` ## Scheduling an online restore ### About this task To perform an online restore, use the Tasks subsystem and enter connection and authentication information and an optional start time. | | | | - | -------------------------- | | | The server must be online. | The Tasks subsystem allows you to schedule certain operations, such as `import-ldif`, `backup`, `restore`, `start-server`, and `stop-server`. ### Steps * Schedule an online restore. #### Example: ```shell $ bin/restore --task --start 20111025010000 \ --backupDirectory /path/to/backup/userRoot \ --completionNotify admin@example.com --errorNotify admin@example.com ``` You can schedule a restore to run as a task by specifying the timestamp with the `--task` and `--start` options. The option is expressed in `YYYYMMDDhhmmss` format. If the option has a value of `0`, then the task is scheduled for immediate execution. You can't run recurring tasks, so you must run daily operations using cron or another system that can submit the task. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To specify a time in the UTC time zone, add a trailing `Z` to the time. If you do not specify a time, the configured time zone on the server will be set to a local time.The backend is unavailable while the restore is in progress. | ## Encrypting a backup ### About this task To encrypt a backup: ### Steps * Go to the server root directory and use the `backup` tool to back up the single backend, `userRoot`, and encrypt it with the `--encrypt` option. #### Example: ```shell $ bin/backup --encrypt --backendID userRoot --compress --backupDirectory /path/to/backup ``` ## Signing a hash of the backup Run the `backup` tool to backup a backend and generate and digitally sign the hash of the backup contents. ### Steps * To backup the single backend from the server root directory, run the `backup` tool. #### Choose from: * To generate and digitally sign the hash of the backup contents, run the `-signHash` option. ```shell $ bin/backup --signHash --backupDirectory backups/userRoot --backendID userRoot \ --backupDirectory /path/to/backup ``` * To only generate a hash of the backup contents, run `backup` with the `--hash` option. ## Restoring a backup You can use the `restore` command to restore a backup created with the `backup` command. ### About this task You can only restore a single backend at a time, and that backend will be offline for the duration of the restore process. The directory containing the backup used for the restoration includes a `backup.info` file with information about the backup, including when the backup was generated and whether the backup is compressed, signed, or encrypted. You can use the `restore` command for the following data recovery scenarios: ### Steps * To restore a single backend in a replicated topology, run the `dsreplication initialize` command. This command streams the contents of the backend database from the source to the destination and ensures that the server receives the most up-to-date version of the data. * To restore a backup in a non-replicated instance, run the `restore` command and specify the path to the directory containing the backup. #### Example: ```shell $ bin/restore --backupDirectory /path/to/backup ``` * To restore a backup to a point-in-time: 1. Run `dsreplication pre-external-initialization` on a server in the topology. 2. Choose the required `baseDN`. 3. Stop the server. 4. Restore that server to your desired point-in-time backup. 5. Re-start the server. 6. Run `dsreplication initialize-all`. 7. Initialize all other servers in the topology from the restored server. 8. Run `dsreplication post-external-initialization` on the restored server. * If all of your servers have been compromised: 1. Build a directory server. 2. Restore from the latest backup. 3. If available, use the `extract-data-recovery-log-changes` command to replay changes in the data recovery log. Learn more in [Reverting or replaying changes](pd_ds_revert_replay_changes.html). 4. Add and initialize new directory servers from the one that you just restored.