Guide

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== cPanel Backup Restore Process ======

Restoring cPanel accounts is easy. This article contains many of the details here:

https://docs.cpanel.net/whm/transfers/transfer-or-restore-a-cpanel-account/

For instructions on backing up and restoring only MySQL, please click [[wiki:mysqlbackuprestore|here]].

===== Simple Restore =====

For a simple restore transfer one or more of the account backup files to one of the following locations:


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

Once done

  - Go to WHM
  - Go to "Transfer or Restore a cPanel Account". If you previously opened this window, you may need to refresh the page to get it to load.
  - Uncheck Restricted restore
  - Type a few characters of the filename you uploaded in the "select a file"  box
  - Select the file
  - If you are redoing a failed restore or otherwise want to override an existing account, check that box.

The account should be restored. Do note that restoring an account takes a lot of disk space. See Advanced Restore section for more info on how to deal with this.

===== Offsite Restore =====

Follow these steps in the event that the Beacon WHM server needs to be restored off-site.

Note that image level backups should be periodically taken a few times per year, since any customization done outside of cPanel will not be included in the normal cPanel backups.

  - Send a copy of the latest image level backup to the facility for restoration.
  - If restoring fails, an older image could be attempted. If restoring an image is not possible, then the fallback plan would be to perform a fresh WHM install, then restore the latest cPanel backup from Backblaze.
  - The facility will need to restore the image into their infrastructure somehow. There isn't a standard process for this.
  - Once the image is restored, the IP will need to be updated on the server. This will need to  be done by the staff at the new site. If remote staff ask for credentials, they will be the same as they were when the image was taken.
  - Once Beacon has access to WHM, all that needs to be done is to restore the latest cPanel backup from Backblaze.
  - WHM - Backup - Backup Restoration or just search for "restore"
  - When performing the restore, pick the most important accounts first. Restoring is likely to take a long time, possibly more than a day.

===== Advanced Restore =====

This section will require use of the shell.

Updated on 2025-06-30: The information in this section may no longer be relevant due to the change to S3 based backup with Backblaze.

==== Limited Disk Space ====

Restoring cPanel accounts take 2-4x as much space as the account normally uses for various reasons.

  - You need to be able to store the .tar.gz file
  - You need to be able to store the decompressed data in addition to the .tar.gz
  - You need to also be able to store a copy of the decompressed data
  - The web interface is also restrictive on what directories you can have the .tar.gz file in. It is possible that you have plenty of space in /backup but you can't use that directory if you use the web interface.

We can help with this issue by using the following general strategies.

If you read the cPanel documentation, you would see that they have what they call "cpmove-{USER}" types. This is simply the extracted .tar.gz.

We can use this fact to help deal with the issue that we need to store the .tar.gz file in addition to the extracted version.

  - First, extract the .tar.gz using: ''tar -zxvf exampleuser.tar.gz''
  - Now, use the ''mv'' command to rename the extracted directory: ''mv exampleuser cpmove-exampleuser''
  - Then we can just delete the .tar.gz file: ''rm exampleuser.tar.gz''
  - This may save enough disk space to be able to do a successful restore.
  - If the ''cpmove-exampleuser'' is in one of the predefined cPanel restore directories, you can use the web interface to complete the restore. Otherwise, proceed to the next step.
  - Run this command: ''/scripts/restorepkg /path/to/cpmove-exampleuser/''

Note that the above steps can be completed if the .tar.gz file is in any place on the filesystem if you are willing to use the ''restorepkg'' script provided by cPanel. This can help fix the problem if you have enough total space on the machine, but no one partition is big enough to support all the various copies.

==== Excluding Files ====

Sometimes you want to exclude files from a restore for various reasons. To do so, follow these steps:

  - Get the .tar.gz file onto the server
  - Use a command like this: tar -zxvf exampleuser.tar.gz --exclude=session
  - That will cause any directory in the archive named "session" to be excluded from the extraction. This includes sub directories as well. /session and /x/session would both be excluded. Read the GNU tar documentation for more details.
  - ''mv exampleuser cpmove-exampleuser''
  - ''/scripts/restorepkg /path/to/cpmove-exampleuser/''

===== Prior Incidents =====

On or about 7/7/2021, a database restore was requested. The restore process was started, however non database changes were also included.

This was an issue because the account had over 7 million session files which made the restore problematic. We failed for a day or so to get it to restore before finally opening a ticket with cPanel.

They used the following commands to get the desired result.

<code>
# be inside /backup
tar -zxvf beacontechnology.tar.gz --exclude=session
mv beacontechnology cpmove-beacontechnology
/scripts/restorepkg /backup/cpmove-beacontechnology/
</code>