How to Back Up WHMCS: Database, Files and a Restore Test

What does a complete WHMCS backup have to include?

Four things: the database, configuration.php, the writeable directories, and any code you wrote. The Database Backups page says you can restore WHMCS as long as you have the database. That is true of the data, not of a ticket attachment or an edited invoice template.

Secure Writeable Directories recommends moving the three writeable folders above the document root. Follow that advice and a backup aimed at the WHMCS folder alone misses two of them.

How do you turn on automatic WHMCS database backups?

Go to Configuration > System Settings > Database Backups, click the option you want, enter the destination, run Test Connection, then Save & Activate. The system cron runs the --DatabaseBackup task daily, listed last in the task order on the System Cron page. If the cron is not running, no backup is either, as my WHMCS cron jobs guide covers.

Read the cPanel row twice. That type only asks cPanel to start a full backup. It does not detect completion, move the file, or notify anyone. It is a trigger, not a backup.

The SFTP/FTP destination is relative to the login folder, not absolute: if logging in lands you at /home/user and the file belongs in /home/user/backups, the value is backups/. Two manual routes also exist: download a backup at Utilities > System > Database Status, or run the task yourself.

php -q cron.php do --DatabaseBackup

Which parts of WHMCS does the database backup leave out?

Every file. The automatic backup produces a zipped SQL dump and nothing else, so the configuration file, the uploads and your code all sit outside it.

Storage Settings lists eight file types WHMCS keeps outside the database, from Client Files and Downloads to Knowledgebase Images and Ticket Attachments. Note where each points: a local path and an Amazon S3 bucket need different treatment.

Custom work is the other gap. A theme change, a custom invoice template, a provisioning module, a hook in /includes/hooks: none of it is in the database. Keep that code in Git, which gives you history rather than yesterday's copy.

Why does the configuration.php encryption hash matter so much?

Because it decides how much of a restored database you can actually read. WHMCS stores ordinary data unencrypted and sensitive data encrypted, and the key is the cc_encryption_hash value inside configuration.php.

The configuration.php reference describes it as a random 64-character string of a-z, A-Z and 0-9, and says that if you lose it the system cannot decrypt your data. Restore the WHMCS Database gives the result: with a database backup but no configuration file, passwords, security questions and card data stay permanently encrypted.

So treat that file as a secret, not as part of a folder sync:

• Keep a copy off the server, in a password manager or secrets store, and out of the Git repository that holds your custom code.
• Set permissions as Secure the Configuration File describes: chmod 400 configuration.php, falling back to 440 then 444 if WHMCS will not load, and 755 only while you update a license key.
• Refresh the copy after any change to the file, such as a license key change or a database move.

The same hash is what goes wrong on server moves, so read my WHMCS migration guide first if one is coming.

How do you back up the WHMCS files with cPanel?

At server level with WHM's Backup Configuration, and at account level with the Backup Wizard. The WHMCS settings cover the database; these cover the files next to it. Four settings in Backup Configuration are worth deciding on purpose:

• Scheduling and Retention. Daily, weekly and monthly runs each take their own retention number, any value from 1 to 9999. Strictly enforce retention removes old backups whether or not they succeeded.
• Back up System Files. cPanel says you must enable this for server restoration.
• Back up SQL Databases. Per Account Only uses mysqldump and writes .sql files. Entire MySQL Directory copies /var/lib/mysql/ without stopping MySQL, which the docs warn can leave InnoDB problems, and those backups cannot be restored through the interface.
• Additional Destinations. cPanel recommends also saving to a remote destination, and advises against remote filesystems such as NFS or CIFS.

At account level, the Backup Wizard writes a full backup as a .tar.gz tarball, to Home Directory, Remote FTP, passive FTP or SCP. Two limits from that same page: a full backup cannot be restored automatically from cPanel, only from WHM, and a backup for an account near its quota can fail.

Where should WHMCS backups be stored, and for how long?

Somewhere a bad day on the WHMCS server cannot reach, and long enough that a problem you notice late is still recoverable. A backup in the account's own home directory survives a mistake inside WHMCS. It does not survive the server.

Both vendors push back on it. WHMCS says a cPanel backup saved to Home Directory counts against the account's disk space limits and should be moved. cPanel recommends a remote destination too, because the backup and transfer queues are separate, so files can pile up and fill the drive.

This is the retention shape I recommend. It is mine, not the documentation's.

Short checklist, the one I work through on an install:

• Automation Status is green and the daily cron run completes.
• The latest file is at the destination, and its size matches the ones before.
• The copy sits on different hardware, behind a different provider login.
• configuration.php is backed up separately and still has 400 permissions.
• A restore test has been run and dated in the last three months.

If the storage layer is the work rather than the WHMCS settings, that is what I do under server migration and backup.

In words: no backup from today means turn automatic backups on first. A backup without configuration.php restores the data but not the encrypted fields. One that exists only on the WHMCS server dies with it. One nobody has restored this quarter is unproven.

How do you run a WHMCS restore test on staging?

Rebuild the install somewhere private from the backup files alone, then read the restored data. These steps combine Restore the WHMCS Database with Set Up a Test Environment.

1. Get a development license. WHMCS gives one free per active license bought directly from it, and up to three on Business licenses. Reseller customers buy theirs. The install must be private, returning a Forbidden error or a login prompt.
2. Restore the database. In phpMyAdmin, select the staging database, Check all, choose Drop under With Selected, then import the backup file from the Import tab.
3. Put the files back. Upload a clean copy of the WHMCS release files, then your templates, modules and hooks on top.
4. Restore the configuration file. Upload your backed-up configuration.php, with credentials and paths changed for staging.
5. Change the system URL. Set it in the General tab of General Settings, or in the database if you cannot log in yet: UPDATE `tblconfiguration` SET value ='https://staging.example.com/whmcs/' WHERE setting='SystemURL';
6. Stop it talking to the outside world. Set Disable Email Sending to ON in the Mail tab, put gateways and registrars in test mode, and password-protect the directory. WHMCS also suggests adding extra characters to the staging encryption hash, so the install cannot read encrypted data or charge a card.
7. Check the data, not the login screen. Review General Settings, Payment Gateways, Servers and Domain Registrars, open recent invoices and tickets, confirm a ticket attachment opens, and place a test order through to provisioning.

Step 6 is the one people skip, and the one that sends real invoices to real clients from a test box.

The test answers what a backup file cannot: does this restore into a working billing system, with attachments present and encrypted fields readable? Run it after a migration, before an upgrade, and once a quarter otherwise. My WHMCS upgrade guide asks for the same staging copy.