The restorepkg Script

Valid for versions 88 through the latest version

Version:

82

88


Last modified: April 12, 2021

Overview

You can use the /usr/local/cpanel/scripts/restorepkg script to restore a cPanel account from a backup file.

Note:
Warning:

Do not use the skip-name-resolve setting in your server’s MySQL® configuration. This setting will cause serious issues with server operations. If you are not an advanced MySQL administrator, expect issues with this setting. For example, you will see issues with restoring backups. This setting will also cause issues with phpMyAdmin.

Run the script

To use this script, run the following command as the root user:

/usr/local/cpanel/scripts/restorepkg [options] [input] [filename]

Options

This script accepts the following options:

Option Description Example
--force Restore the account regardless of any errors or warnings. When the system restores the account, any existing data remains intact on the server.
Note:
If the account already exists on the server, this option operates similarly to the --skipaccount option.
--force
--allow_reseller Restore reseller privileges. --allow_reseller
--ip Restore the account to a certain IP address:
  • y — Use the next available IP address in the IP address pool to restore the account.
  • n — Use the share IP address to restore the account.
  • A valid IP address — Use this IP address to restore the account.
Note:
If an IP address is not available, the script uses the next available IP address in the IP address pool. If no IP addresses are available, the script uses the server’s shared IP address.
--ip=192.0.2.169
--newuser Change the restored account’s username. To change the name of a database or database user after you restore the account, use WHM’s Manage Databases interface (WHM >> Home >> SQL Services >> Manage Databases) and WHM’s Manage Database Users interface (WHM >> Home >> SQL Services >> Manage Database Users).
Note:
  • All of the account's database users will keep their current username except for the user that matches the cPanel account.
  • You cannot use this option with the --skipaccount option.
  • The new account name cannot already exist on the server.
  • The username must contain 16 characters or fewer, and the first eight characters must be unique on the server.
--newuser=username
--skipaccount Restore a package for an existing account with the same username as another existing account.
Note:
You cannot use this option with the --newuser option.
--skipaccount
--restricted Run the restoration process with the Restricted Restore feature. This feature performs additional security checks on the backup file in order to mitigate the risk of transfers from unfamiliar sources. If a component of the backup file contains an issue (for example, a compromised MySQL® grant table or a symbolic link attack), the system does not restore that portion of the backup and adds a warning to the log file. If you do not trust the source of the account backup with root access to your server, use the Restricted Restore feature to protect your server.
Note:
If you do not use this option, the script performs an unrestricted restore.
Warning:
  • The Restricted Restore feature is experimental. Do not consider it an effective security control. Exercise extreme caution when using the Restricted Restore feature.
  • When you restore an account with the Restricted Restore feature, the system may leave behind unnecessary account data. This can cause conflicts and leave the account in a broken state. You must remove the account and then restore it without using the Restricted Restore feature.
  • To use the Restricted Restore feature to restore an account that owns PostgreSQL® databases, the target server must use PostgreSQL version 8.4 or newer.
  • The Restricted Restore feature will not restore parked (aliased) or addon domains.
  • The Restricted Restore feature only allows restored accounts to use the noshell or jailshell options. If the restored account uses another shell, the system will set the account to use the noshell option.
--restricted
--disable Disable specific modules during the account restoration process:
  • Use a comma-separated list to specify multiple values.
  • For a list of possible values, run the --help option.
  • Module names are case-sensitive.
Warning:
We strongly recommend that only advanced users apply this option. If you incorrectly configure this option, the cPanel account may restore in a broken state.
--disable=MailRouting,SSL
--mail_location The server on which the account’s email will reside after the system completes the restore process:
  • .local — The local server.
  • .existing — Use the location defined in the account’s backup data. The is the default option.
  • ALIAS — A remote cPanel & WHM linked server node’s alias. For example, the example-alias for the servernode.example.com domain.
Note:
The system will default to the .local option if:
  • The system cannot use the cPanel & WHM linked server node when you use the .existing option.
  • The cPanel & WHM linked server node’s ALIAS value is invalid.
--mail_location=example-alias

Files

The backup filename must use one of the following formats:

  • cpmove-{USER}
  • cpmove-{USER}.tar
  • cpmove-{USER}.tar.gz
  • {USER}.tar
  • {USER}.tar.gz
  • backup-{MM.DD.YYYY}{HH-MM-SS}{USER}.tar
  • backup-{MM.DD.YYYY}{HH-MM-SS}{USER}.tar.gz

The restore package script searches for the archive in the following locations:

  • /home
  • /home2
  • /home3
  • /root
  • /usr
  • /usr/home
  • /web

The script attempts to restore the account on the shared IP address with the following steps:

  1. Adds the package to the AccountLocal queue.
  2. Starts the restoration process.
  3. Uses the tail command to output the log file’s contents after the restoration process begins.

Example

For example, the following command uses the unrestricted restore method to restore the cpmove-testaccount.tar.gz file to the 192.0.2.169 IP address:

/usr/local/cpanel/scripts/restorepkg --ip=192.0.2.169 cpmove-testaccount.tar.gz

Additional Documentation