Difference between revisions of "Backups"

From WHMCS Documentation

m (Limitations)
 
(23 intermediate revisions by 6 users not shown)
Line 1: Line 1:
It is strongly recommended that you backup your WHMCS Database regularly to ensure you always have a copy of your data should a server or system failure occur. Backing up the database is a very simply task with the built in backup tool and can even be fully automated.
+
We strongly recommend that you back up your WHMCS database regularly, so that you always have a copy of your data if a server or system failure occurs. Backing up the database is a very simply task with the built-in backup tool, and you can automate it.
  
 
==Automated Database Backup==
 
==Automated Database Backup==
  
<div class="docs-alert-info"><i class="fa fa-info"></i> Functionality for automated backups was introduced in WHMCS 7.3 </div>
+
WHMCS can automatically back up your database and upload it to a SFTP/FTP location or email it to a designated email address.  
  
WHMCS can automatically backup your database and upload to a SFTP/FTP location and/or email it to a designated email address.
+
To enable automatic backups, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings  > [[Database Backups]]''' or, prior to WHMCS 8.0, '''Setup > Database Backups'''.
  
From WHMCS 7.3, it is also possible to request a full cPanel backup for a specific user as part of the automatic backup process.
+
==Manual Database Backup==
  
==Enabling Automatic Backups==
+
You can manually download a backup of the WHMCS database at '''Utilities > System > [[Database Status]]'''.
  
All backup configuration is completed in ''Setup'' > ''Other'' > ''Database Backups''.
+
==Executing Backup Task Manually==
  
The available options are SFTP/FTP backup, Email backup and full cPanel Account backup.
+
The backup options configured are executed once per day via the cron. However, the task can be executed manually to check the configured backup options are working or as a separate cron command configured to execute the backup task more often:
  
===Testing Connection===
+
<div class="source-cli">
 +
php -q cron.php do --DatabaseBackup
 +
</div>
 +
For more information, refer to the [[Crons#Task_Options_for_skip_and_do|Cron documentation]],
  
The SFTP/FTP and cPanel Backup options require a connection test being successful before activation. A connection test ensures the details are valid and the WHMCS installation can connect to the server. Any connection issue allows a resolution before a backup attempt occurs meaning less chance of a failed connection.
+
==Configuration.php Backup==
  
==SFTP/FTP Backup==
+
The <tt>configuration.php</tt> file in the main <tt>whmcs</tt> directory. It contains the encryption hash value unique to your particular installation, which encrypts sensitive data. If you lose the encryption hash value, the system won't be able to decrypt your data. Because of this, it is important to keep a backup of this file in a secure location in case reinstallation is necessary.
  
This backup will place the WHMCS generated zipped sql file on the specified remote server.
+
==Limitations==
  
Checking the "Use Secure FTP/SFTP (Recommended)" box will ensure the backup upload is completed using an SFTP connection.  
+
As a database grows, it becomes too big for a PHP script like the WHMCS cron job to handle, due to the amount of data in it exceeding various server limits, usually when the database exceeds 20 MB. The size prevents the system from completing an FTP or Email backup.
  
===FTP Destination===
+
In this case, we recommend switching to the '''[[Database_Backups#cPanel_Backup|cPanel Backup]]''' option instead (if you installed WHMCS on a cPanel server). By off-loading the backup tasks from PHP to the cPanel system processes, it allows you to generate much larger backups without impacting performance of your website.
  
This value should be relative to the login folder for the FTP/SFTP account being used.
+
When switching to cPanel or external backups, you will need to ensure that you have disabled the FTP and Email Backup features in your WHMCS installation to prevent errors with the cron due to the large database size.
No initial slash should be used, for example, if upon logging in using those FTP details the folder is /home/user/ and the backup should be in /home/user/backups, then enter backups/ as the FTP Destination.
 
If the login folder is where the backup file is to be uploaded, leave this field empty.
 
  
<div class="docs-alert-info"><i class="fa fa-question-circle"></i> Why not create a separate FTP account jailed to a certain directory?</div>
+
If you are not on a cPanel server, you can use an external tool such as '''mysqldump''' to export your database. More information can be found in the [https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html MySQL documentation].
  
==cPanel Backup==
+
==Optimise Tables==
  
The cPanel Backup option uses the [https://documentation.cpanel.net/display/ALD/Backup+Wizard#BackupWizard-FullBackup Full Backup] feature of WHM/cPanel's backup wizard.
+
In normal operation, MySQL® tables can generate overhead. You can optimise your databases to reduce this problem at '''Utilities > System > [[Database Status]]'''.
  
===cPanel Username===
+
==Troubleshooting==
<div class="docs-alert-info"><i class="fa fa-info"></i> The cPanel Username is the name of the account to be backed up.</div>
 
 
 
===Backup Destination===
 
* Home Directory — Select this option to save the backup file to the server.
 
* Remote FTP Server — Select this option to use FTP to store the backup file on a remote server.
 
* Remote FTP Server (Passive Mode Transfer) — Select this option to use passive FTP to store the backup file on a remote server.
 
* SCP — Select this option to use SCP to store the backup file on a remote server.
 
 
 
<div class="docs-alert-warning"><i class="fa fa-exclamation-triangle"></i> Using Home Directory will generate the backup file in the home directory of the cPanel user. This will count against any disk space limits and should be manually moved to a better location after completion.</div>
 
 
 
The System Cron will only request the start of a full backup. Completion, and relocation of the backup occurs within cPanel and will not be notified though WHMCS.
 
  
==Manual Database Backup==
+
The most common reason for database backups to fail is that it has grown too large and the PHP process takes too long or uses too much memory and is killed before it can complete the backup process.
To manually download a backup of the WHMCS database at any time:
 
  
#Login to your WHMCS Admin Area
+
For more information, see [[Backups#Limitations|Limitations]].
#Go to '''Utilities > System > Database Status'''
 
#Click the Download Full Database Backup button at the top of the page
 
#You should be prompted for a file to download. Save the file to your computer.  Depending on the database size, this may take a few moments.
 
#Once the download is complete you have now backed up your database.
 
  
==Configuration.php Backup==
+
===Onscreen Errors===
  
The configuration.php file in the main whmcs directory contains the encryption hash value unique to your particular installation, it's used to encrypt sensitive data so should it be lost this data can no longer be decrypted. Therefore it is important for a backup of this file to be kept in a secure location in case re-installation is necessary.
+
A number of errors may occur onscreen when you generate a manual database backup, or in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[System Logs]]''' (or '''Utilities > Logs > Activity Log''' in WHMCS 7.x and earlier) when generating an automated database backup:
  
==Limitations==
+
====Table 'xxx' doesn't exist when using LOCK TABLES====
As a DB grows, it becomes too big for a PHP script like the WHMCS cron to handle backing up due to the amount of data within it causing various server limits to be exceeded, usually around the 20MB mark. Unfortunately being big means that for a PHP script to loop through and save that data into temporary memory in order to generate an FTP or Email backup is not possible - either the memory limits or max execution time limits on the server will be reached and terminate the script.
 
  
In this case we recommend switching to the [[#cPanel_Backup|cPanel backup]] option instead. By off-loading the backup tasks from PHP to the cPanel system processes, it allows much larger backups to be generated without impacting performance of your website.
+
This indicates that the named table <tt>xxx</tt> has crashed or is corrupted. Running a MySQL® repair operation will resolve this. You can repair tables via the '''MySQL Databases''' page within cPanel or using a tool such as phpMyAdmin.
  
==Optimise Tables==
+
====Database backup unavailable due to missing required zip extension====
In normal operation MySQL tables can generate overhead, put simply this is space assigned to the table that isn't being used but is still taking up disk space. MySQL has a function called [http://dev.mysql.com/doc/refman/5.1/en/optimize-table.html optimise tables] which can be used to reduce this. Usually this command is from from the server's command line or phpmyadmin, but it can also be run within WHMCS by clicking the '''Utilities > System > Database Status > Optimise Tables''' button.
 
 
 
==Troubleshooting==
 
A number of errors may occur on-screen when generated a manual database backup, or in the '''Utilities > Logs > Activity Log''' when generated an automated database backup. They are explained below:
 
  
===Table 'xxx' doesn't exist when using LOCK TABLES===
+
This indicates that you need to [http://php.net/manual/en/class.ziparchive.php recompile PHP] after enabling the ZipArchive PHP class, which WHMCS requires to compress the backup.  
Indicates the named table 'xxx' is crashed or corrupted. Running a MySQL repair operation will resolve this. Tables can be repaired via the MySQL Databases page within cPanel or using a tool such as phpmyadmin.
 
  
===Database backup unavailable due to missing required zip extension===
+
====Database backup error 'Please provide a valid dump path'====
This refers to the ZipArchive PHP class which is required by WHMCS to compress the backup. Please recompile PHP with support for this class: http://php.net/manual/en/class.ziparchive.php
 
  
===Database backup error 'Please provide a valid dump path'===
+
This indicates that WHMCS is unable to access the <tt>/tmp</tt> working directory during the backup generation process. Make sure that the <tt>[http://php.net/manual/en/ini.core.php#ini.open-basedir open_basedir]</tt> value is ''Off'' in your PHP configuration, and that the PHP <tt>/tmp</tt> directory is writeable and is not full.
This indicates that WHMCS is unable to access the /tmp working directory during the backup generation process. Please ensure that the [http://php.net/manual/en/ini.core.php#ini.open-basedir open_basedir] value is set to ''Off'' in your PHP configuration, that the PHP /tmp directory is writeable and is not full.
 

Latest revision as of 20:39, 18 April 2022

We strongly recommend that you back up your WHMCS database regularly, so that you always have a copy of your data if a server or system failure occurs. Backing up the database is a very simply task with the built-in backup tool, and you can automate it.

Automated Database Backup

WHMCS can automatically back up your database and upload it to a SFTP/FTP location or email it to a designated email address.

To enable automatic backups, go to Configuration () > System Settings > Database Backups or, prior to WHMCS 8.0, Setup > Database Backups.

Manual Database Backup

You can manually download a backup of the WHMCS database at Utilities > System > Database Status.

Executing Backup Task Manually

The backup options configured are executed once per day via the cron. However, the task can be executed manually to check the configured backup options are working or as a separate cron command configured to execute the backup task more often:

php -q cron.php do --DatabaseBackup

For more information, refer to the Cron documentation,

Configuration.php Backup

The configuration.php file in the main whmcs directory. It contains the encryption hash value unique to your particular installation, which encrypts sensitive data. If you lose the encryption hash value, the system won't be able to decrypt your data. Because of this, it is important to keep a backup of this file in a secure location in case reinstallation is necessary.

Limitations

As a database grows, it becomes too big for a PHP script like the WHMCS cron job to handle, due to the amount of data in it exceeding various server limits, usually when the database exceeds 20 MB. The size prevents the system from completing an FTP or Email backup.

In this case, we recommend switching to the cPanel Backup option instead (if you installed WHMCS on a cPanel server). By off-loading the backup tasks from PHP to the cPanel system processes, it allows you to generate much larger backups without impacting performance of your website.

When switching to cPanel or external backups, you will need to ensure that you have disabled the FTP and Email Backup features in your WHMCS installation to prevent errors with the cron due to the large database size.

If you are not on a cPanel server, you can use an external tool such as mysqldump to export your database. More information can be found in the MySQL documentation.

Optimise Tables

In normal operation, MySQL® tables can generate overhead. You can optimise your databases to reduce this problem at Utilities > System > Database Status.

Troubleshooting

The most common reason for database backups to fail is that it has grown too large and the PHP process takes too long or uses too much memory and is killed before it can complete the backup process.

For more information, see Limitations.

Onscreen Errors

A number of errors may occur onscreen when you generate a manual database backup, or in Configuration () > System Logs (or Utilities > Logs > Activity Log in WHMCS 7.x and earlier) when generating an automated database backup:

Table 'xxx' doesn't exist when using LOCK TABLES

This indicates that the named table xxx has crashed or is corrupted. Running a MySQL® repair operation will resolve this. You can repair tables via the MySQL Databases page within cPanel or using a tool such as phpMyAdmin.

Database backup unavailable due to missing required zip extension

This indicates that you need to recompile PHP after enabling the ZipArchive PHP class, which WHMCS requires to compress the backup.

Database backup error 'Please provide a valid dump path'

This indicates that WHMCS is unable to access the /tmp working directory during the backup generation process. Make sure that the open_basedir value is Off in your PHP configuration, and that the PHP /tmp directory is writeable and is not full.