PingDirectory

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.

    $ bin/restore --listBackups --backupDirectory  </mybackups>

    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.

    $ bin/backup --backUpAll --compress --backupDirectory  </path/to/backup>

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.

    $ bin/backup --backendID userRoot --compress --backupDirectory  </path/to/backup>

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.

    $ bin/stop-server

  2. To restore a saved backup, run the following command.

    $ bin/restore --backupDirectory  </path/to/backup/userRoot>

  3. To start the server, run the following command.

    $ 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.

    $ bin/backup --backupDirectory  </path/to/backups/>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:

    $ 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:

    $ 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:

    $ 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.

      $ 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:

    $ 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.

      For more information, see Reverting or replaying changes.

    4. Add and initialize new directory servers from the one that you just restored.