Child pages
  • Backup Restoration
For cPanel & WHM version 74

Skip to end of metadata
Go to start of metadata


(WHM >> Home >> Backup >> Backup Restoration)

Overview

Important:

To use this feature, you must enable account backups in WHM's Backup Configuration interface (WHM >> Home >> Backup >> Backup Configuration).

This interface allows you to restore accounts from the backup archives that the system stores in the backups directory. You can restore a single account, several accounts, or accounts from a specific date.

Note:

The blue border around a section indicates the next required step.

In this example, the blue border indicates that the next step is to select a date from the calendar.

Restore by Account

This option allows you to choose which accounts to restore. You can restore multiple accounts, but you must add each account separately.

To restore an account, perform the following steps:

  1. Select one or more accounts that you wish to restore. For more information on how to restore multiple accounts, read the Restore Multiple Account Backups section below.

    Notes:

    • This menu includes accounts that possess at least one backup archive.
    • Enter an account name in the Filter Accounts text box to filter the list.
    • If you add an account to the queue, it will appear in gray and you cannot select it again.
    • You can restore an account as many times as you wish, but you must wait for the restoration process to finish before you add that account to the queue again.
  2. Select a date from the Available Restoration Dates calendar.

    Note:

    You can only click a date that has a backup for the selected account.

  3. Select any desired options from the Additional Options section.

    • Restore Subdomains — Restores any subdomains that appear in the account's backup archive.

      Note:

      If you do not enable this option, the restoration process will not restore subdomains, but will restore aliases (parked domains).

    • Restore Mail Config — Restores the account's email.
    • Restore MySQL — Restores the account's MySQL® databases.
    • Give Dedicated IP Address — Assigns the account a dedicated IP address during the restoration process.

      Note:

      If an account has a dedicated IP address at the time of restoration, it maintains that same IP address.

  4. Click Add Account to Queue. The account will appear with a status of Pending in the Restoration Queue table below. This table displays the status of the restoration.
  5. Click Restore to start the restoration process.

    Note:

    You may add additional accounts to the queue while restoration is in progress, and the system automatically restores them.

Restore by Date

This option allows you to restore accounts with backup archives from a specific date. You can restore multiple accounts, but you must add each account separately.

To restore an account's backup archives from a specific date, perform the following steps:

  1. Select a date from the Available Restoration Dates calendar.

    Note:

    You can only click a date that has a backup for the selected account.

  2. Select one or more accounts that you wish to restore. For more information on how to restore multiple accounts, read the Restore Multiple Account Backups section below.

    Notes:

    • This list includes accounts that possess at least one backup archive.
    • Enter an account name in the Filter Accounts field to filter the list.
    • You can restore multiple accounts, but you must add each account separately.
    • If you add an account to the queue, it will appear in gray and you cannot select it again.
    • You can restore an account as many times as you wish, but you must wait for the restoration process to finish before you add that account to the queue again.
  3. Select any desired Additional Options.
    • Restore Subdomains — Restores any subdomains that appear in the account's backup archive.

      Note:

      If you do not enable this option, the restoration process will not restore subdomains, but will restore aliases (parked domains).

    • Restore Mail Config — Restores the account's email.
    • Restore MySQL — Restores the account's MySQL databases.
    • Give Dedicated IP Address — Assigns the account a dedicated IP address during the restore process.

      Note:

      If an account has a dedicated IP address at the time of restoration, it maintains that same IP address.

  4. Click Add Account to Queue. The account will appear with a status of Pending in the Restoration Queue table below. This table shows the status of the restoration.
  5. Click Restore to start the restoration process.

    Note:

    You may add more accounts to the queue during the restoration process, and the system automatically restores them.

Give Dedicated IP Address behavior

The following table shows potentially unexpected behavior of the Give Dedicated IP Address option in certain circumstances.

The account exists 
at the time of the restoration
The account had a dedicated IP 
address at the time of the backup
Give dedicated IP address 
is selected
Result
YesYesNoThe system assigns the account the same dedicated IP address.
YesNoYesThe system assigns the account a dedicated IP address.
NoYesYes

The system assigns the account a new dedicated IP address, which may or may not match the account's IP address that you used when you backed it up.

Note:

When an account does not exist at the time of restoration, the system behaves as though the account does not possess a dedicated IP address.

Restoration Queue

The Restoration Queue table contains the following columns:

ColumnDescription
AccountThe name of the account.
Restoration DateThe date of the backup archive.
Status
  • Pending — The account is ready for restoration.
  • Restoring Account — The restoration is in process. You cannot remove an account from the queue during the restoration process. 
  • Completed — The restoration completed successfully. 
  • Failed — The restoration failed. The red failure notice box includes a reason for the failure. Click X on the right to close the red box.
Actions
  • Clear This option clears the associated entry from the queue. 

    Note:

    To clear an account that failed to restore, you must click X on the failure notice.

  • View Log — This option opens the restoration log file so that you can correct any errors or warnings.

 


  • Clear pending accounts This option clears all Pending restorations from the queue.
  • Clear completed accounts — This option clears all Complete and Failed restorations from the queue.
  • Clear all error notices — This option clears all error notices from the queue.
  • Clear all accounts — This option clears all Pending, Complete, and Failed restorations. It does not clear an account that has a status of Restoring Account.

Note:

The system automatically moves completed accounts to the bottom of the Restoration Queue table.

Restoration Queue Script

Advanced users can use the backup_restore_manager script to manage the Restoration Queue table. To manage backup restorations, run the following script on the command line:

/usr/local/cpanel/bin/backup_restore_manager [options]

You can use the following options with this script:

OptionsDescriptionRequirements
activateThis option processes the current queue.None
addThis option adds a user to the restoration queue for a specified date. I.e. In YYYY-MM-DD format.user,restore_point
deleteThis option deletes a user from the pending restoration queue.user
delete_all_failedThis option deletes all failed entries in the finished restorations queue.None
delete_all_finishedThis option deletes all passed entries in the finished restorations queue.user
delete_all_pendingThis option deletes all entries in the pending queue.None
delete_all_regardlessThis option deletes all entries in all queues regardless of their status.None
delete_finishedThis option deletes a user from the finished restorations queue.None
is_activeThis option determines the status of a current restoration process in progress.None
listThis option lists all entries in the restoration queue.None
list_activeThis option lists the currently restoring accounts.None
list_finishedThis option lists all restored accounts.None
stateThis option lists all restore states and determines the status of a restoration process.None


Notes:

  • When you add backups to the Backup Restoration queue, you can enable Additional Options with the additional_option=1 argument.
  • The system does not enable these options by default.

  • To restore backups with subdomains, email, MySQL databases, and a dedicated IP address, you must enable the following options when you add the backup to the queue:

    Variable NameDescription
    give_ipThis option assigns the account a dedicated IP address during the restore process.
    mail_configThis option restores the account's email.
    mysqlThis option restores the account's MySQL databases.
    subdomainsThis option restores any subdomains that appear in the account's backup archive.

Script example

For example, if you want to add a backup for the cPanel user "temptest" from February 26, 2016, restore the account's default data, email, MySQL databases, and subdomains, run the following command:

/usr/local/cpanel/bin/backup_restore_manager add user=temptest restore_point=2016-02-26 mail_config=1 mysql=1 subdomains=1

If you add a backup successfully, the system will display output similar to the following example:

response:id=TQ:TaskQueue:8
result = 1
reason = OK

If you add a backup unsuccessfully, the system will display output similar to the following example:

response:err
reason = Missing restore point
result = 0


Note:

To find more examples of how to add backups, run the following command:

/usr/local/cpanel/bin/backup_restore_manager --help

Restore multiple account backups

Important:

To use this feature, you must enable account backups in WHM's Backup Configuration interface (WHM >> Home >> Backup >> Backup Configuration).

The Backup Restoration interface allows you to restore accounts from the backup archives that the system stores in the backups directory. You can restore a single account or multiple accounts by account or a specific date.

To symlink all of your account backups to the /backup/cpback/daily/ directory, run the following command:

RESTORE_FROM_DATE="YYYY-MM-DD"; if [ ! -d '/backup/cpbackup/daily/' ]; then mkdir -p '/backup/cpbackup/daily/'; fi; for CP_BACKUP in $(find /backup/"$RESTORE_FROM_DATE"/accounts/ -type f); do CP_ACC=$(echo "$CP_BACKUP" |awk -F/ '{print $5}'); ln -sv "$CP_BACKUP" "/backup/cpbackup/daily/$CP_ACC"; done

Notes:

  • Replace YYYY-MM-DD with the desired date from which you wish to restore backups.
  • After you restore backups, you may wish to remove the symlinks that you created. To do this, run the following command:

    find /backup/cpbackup/daily/ -type l -delete

 

To add all cPanel account backups to the Backup Restoration Queue, perform the following steps:

  1. Restore all backups with the Legacy Restore Multiple Accounts feature.

  2. Run the following command to add all available account packages to the Backup Restoration queue, with all options selected except the dedicatedip option:

    RESTORE_FROM_DATE="2016-02-25"; BACKUP_TYPE="daily"; if [ $BACKUP_TYPE="daily" ]; then BACKUP_BASE="/backup/$RESTORE_FROM_DATE/accounts/"; else BACKUP_BASE="/backup/$BACKUP_TYPE/"$RESTORE_FROM_DATE"/accounts/"; fi; for CP_ACC in $(find "$BACKUP_BASE" -type f -name '*.tar.gz' |awk -F/ '{print $5}' |sed 's/.tar.gz//g'); do /usr/local/cpanel/bin/backup_restore_manager add user="$CP_ACC" restore_point="$RESTORE_FROM_DATE" mail_config=1 mysql=1 subdomains=1; done

    Notes:

    • Replace YYYY-MM-DD with the desired date from which you wish to restore backups.
    • Replace weekly with the desired frequency type of existing backups. For example, monthly, weekly, or daily.
    • This example uses the optional mail_config, mysql, and subdomains options, which you can find in the Additional Options section of the Backup Restoration tool.

Additional documentation