Restoring WHMCS

From WHMCS Documentation

Data loss is a catastrophic, but not unheard of occurrence. This is often mitigated by good backup practices which can turn a potentially disastrous situation into manageable downtime.

If a complete backup is not available for restoration, then it may be necessary to get WHMCS running again using only a database backup. This guide aims to cover the steps required to restore a WHMCS installation from backups of its constituent parts.


WHMCS is effectively comprised of three key parts: the database, the files, and the configuration file; the database contains all of the settings and data used by WHMCS, the files tell the software how to operate and control its appearance, and the configuration file allows the files to communicate with the database.

Since the database itself contains all of the data, then this means that a WHMCS installation can be restored as long as you have a copy of that database. With that said, restoration can be performed via the following steps:

  1. Restore the Database Backup
  2. Replace the WHMCS Files
  3. Replace or Creating the Configuration File
  4. Perform Post Restoration Steps

It is recommended that all of these steps be reviewed in full before attempting to recover an installation.

Restore the Database Backup

The first step towards recovering from catastrophic data loss is to restore the database backup to your server.

Database backups can usually be restored to your hosting account via a web interface such as PHPMyAdmin. For instructions on how to restore a database backup using PHPMyAdmin specifically, please refer to the Restoring a Database Backup section of the documentation.

Should you run into problems while restoring your database backup, then your hosting provider will be able to assist in this process.

Replace the WHMCS Files

With the database restored, the next step is to replace any missing WHMCS files. This can be done by first downloading a fresh copy of the WHMCS full release files.

  • If your license was purchased through WHMCS, these can be acquired via the Download WHMCS page
  • If your license was purchased elsewhere, then a download can be provided by your reseller

Once you acquired a copy of a full release archive, you'll then want to unzip the contents of the file to a folder on your computer, and upload the contents from the "whmcs" directory to your existing installation folder.

Replace or Creating the Configuration File

There are two types of data stored in the WHMCS database: unencrypted and encrypted data.

  • Most of the data in WHMCS is not sensitive in nature, and is unencrypted. This consists of things like configuration settings, client details, and orders.
  • Some of the data in WHMCS is sensitive in nature, and is encrypted. This consists of items such as credit card details, passwords, and security questions.

If you have a database backup, then all of the unencrypted data is salvageable. If you also happen to have a backup of your configuration file, also known as the configuration.php file, then all of the encrypted data can be recovered as well.

Restoring an Existing Configuration File

Should you have a backup of your configuration.php file, then you will want to upload that file to your installation directory. At this point you should be up and running with WHMCS once again, and can proceed onto the Perform Post Restoration Steps section.

Creating a New Configuration File

Should you not have a backup of the configuration.php file then all password, security questions, and credit card data will be permanently encrypted and unsalvageable.

In this instance, a new configuration.php file will need to be created from scratch using the template found in the Configuration File Template section of this guide.

  • The license value should be the full licence key
  • The db_host value should be the database hostname
  • The db_username value should be the database username
  • The db_password value should be the database password
  • The db_name value should be the database name
  • The cc_encryption_hash value should be a random 50 character string consisting of numbers and letters of varying cases

If you are uncertain of the correct database connection details (db_host, db_username, db_password, and db_name), then your hosting provider will be able to advise which values should be used.

Once the configuration.php file has been saved and uploaded to your installation directory, you should then be up and running once again with most of your data in tact.

Configuration File Template

$db_host = "localhost";
$db_username = "";
$db_password = "";
$db_name = "";
$cc_encryption_hash = "";
$templates_compiledir = "templates_c/";

Perform Post Restoration Steps

After restoring a WHMCS installation, it is a good idea to review all configuration sections of the Admin Area and to place a few test orders to ensure that everything is functioning as expected. Below is a short list of steps to take which will address this.

  1. Log into the WHMCS Admin Area, and reset your Administrator User password as needed
  2. Review the General Settings
  3. Review the configuration of any existing Gateway Modules
  4. Review the configuration of any existing Server Modules
  5. Review the configuration of any existing Registar Modules
  6. Recreate any needed Cron Jobs and Email Forwarders
  7. Place some test orders on your website to check everything works as expected