Skip to content
Security

WHMCS Backup and Disaster Recovery: What to Back Up and How to Restore

Back up the WHMCS database, configuration.php and file directories daily, keep an off-site copy that can't be deleted, and test a timed restore every quarter.

WHMCSPilot Team Published Updated 9 min read
WHMCS Backup and Disaster Recovery: What to Back Up and How to Restore

A complete WHMCS backup has three parts: the database, the configuration.php file (which holds the encryption key for stored passwords and card data) and the file directories such as attachments, downloads, custom templates, modules and hooks. Back up all three at least daily, keep copies off the server with one that can't be deleted, and prove they work with a timed test restore every quarter. This guide is for hosting, VPS and IPTV business owners running self-hosted WHMCS 8.13 or 9.x; WHMCS Cloud manages its own backups.

Key takeaways

  • The built-in Database Backups feature at Configuration > System Settings > Database Backups covers the database only. Files and configuration.php need their own backup.
  • Without the matching configuration.php, a restored database keeps passwords, security answers and card data permanently encrypted.
  • Use mysqldump --single-transaction so the dump is consistent without locking WHMCS while the cron or customers are writing.
  • Keep at least one off-site copy that the WHMCS server's own credentials can't delete, such as an S3 bucket with Object Lock.
  • After any restore, reconcile payments and provisioning that happened after the backup was taken. The gateway and the panel still hold that data even though WHMCS doesn't.

What do you need to back up in WHMCS?

A WHMCS installation spreads business data across the database, one critical config file and several directories. The table lists what to copy, why it matters and how often.

ItemDefault locationWhy it mattersHow often
DatabaseMySQL or MariaDB, named in configuration.phpClients, services, invoices, transactions, tickets, settingsDaily at minimum, hourly for busy installs
configuration.phpWHMCS root directoryDatabase credentials and cc_encryption_hash, the key that decrypts stored dataAfter every change, stored apart from the database dump
Client files and ticket attachments/attachments (and /attachments/projects)Files clients and staff uploadedDaily
Downloads and email template attachments/downloadsFiles you offer to clientsWeekly or after changes
Custom code/templates, /modules, /includes/hooks, /lang/overridesYour theme, third-party modules and hooksAfter every change, ideally in Git
Cron and moved directories/crons or a custom $crons_dirNeeded to rebuild the cron jobAfter changes

Check Configuration > System Settings > Storage Settings to see where your install actually stores each file type; it may be a custom path or an S3 bucket. Keep a separate, encrypted record (a password manager works) of things a backup can't rebuild: your WHMCS license key, module license keys, gateway and registrar API keys, the server's PHP and ionCube Loader versions, and the exact cron command. Skip templates_c, which is a compiled cache that WHMCS rebuilds.

What does WHMCS's built-in Database Backups feature do?

WHMCS's built-in Database Backups feature, at Configuration > System Settings > Database Backups in 8.x and 9.x, runs from the system cron once a day by default and offers three methods. The WHMCS Database Backups documentation describes them:

MethodWhat it sendsRequirementsLimits
SFTP/FTP BackupA zipped SQL file to a remote serverHost, port, user, password, folder, and a passing Test ConnectionFTP and SFTP only, no FTPS
cPanel BackupsAsks cPanel to run a full account backup, to remote FTP, SCP or the home directoryA cPanel API token with basic-system-info and cpanel-api permissionsWHMCS only starts the backup; it doesn't confirm completion or move the file
Daily Email BackupsThe backup file to an email addressAn address, ideally not hosted on the same serverCan fail on large databases from memory or time limits

You can also download a backup manually at Utilities > System > Database Status, or run php -q cron.php do --DatabaseBackup from the crons directory. Treat the built-in feature as one layer, not the plan: it skips files and configuration.php, emailed backups put your whole client database in a mailbox, and none of the methods tells you when a backup silently stops. If the cron stops, so do these backups, which is one more reason to fix a WHMCS cron that isn't running quickly.

How do you set up automated off-site WHMCS backups?

An automated off-site WHMCS backup on a VPS or dedicated server takes a consistent database dump, archives the WHMCS directories and ships both to encrypted storage you can't delete from the WHMCS server. On a cPanel server without root access, use WHM's Backup Configuration or the cPanel Backups option above instead.

  1. Create a read-only database user for backups with SELECT, SHOW VIEW and TRIGGER (dump with --no-tablespaces so it doesn't also need PROCESS), and store its password in an option file readable only by root, so it never appears in the process list.
  2. Dump with a consistent snapshot. The MySQL mysqldump manual says --single-transaction dumps InnoDB tables in a consistent state without blocking applications. Avoid schema changes, such as a WHMCS update, while it runs.
  3. Archive the directories in the table above, including configuration.php.
  4. Encrypt and ship off-site. restic, for example, encrypts every repository and can write to SFTP, Amazon S3, Backblaze B2 and other services through rclone.
  5. Make one copy immutable. Amazon S3 Object Lock stores objects write-once-read-many; in compliance mode no user, including the account root user, can delete a locked version before its retention date. It requires S3 Versioning.
  6. Prune on a schedule and alert on failure, for example by sending the script's exit status to your monitoring or ops Telegram channel.
# /root/whmcs-backup.sh, run with bash
set -euo pipefail
STAMP=$(date +%F-%H%M)
WHMCS=/var/www/billing
OUT=/backup/whmcs

mysqldump --defaults-extra-file=/root/.whmcs-backup.cnf --single-transaction \
  --no-tablespaces whmcs_db | gzip > "$OUT/db-$STAMP.sql.gz"
tar -czf "$OUT/files-$STAMP.tar.gz" -C "$WHMCS" configuration.php attachments \
  downloads templates modules includes/hooks

restic -r s3:s3.amazonaws.com/your-backup-bucket backup "$OUT"
restic -r s3:s3.amazonaws.com/your-backup-bucket forget \
  --keep-daily 14 --keep-weekly 8 --keep-monthly 12 --prune
find "$OUT" -type f -mtime +2 -delete

Run the script from root's crontab, away from the time your WHMCS cron runs its daily tasks.

How long should you keep WHMCS backups?

WHMCS backup retention is a balance between recovering from slow-burning problems and holding personal data longer than you need. Ransomware and quiet data corruption are often found days or weeks later, so short retention alone isn't enough.

CopyKeepPurpose
Hourly or twice-daily database48 to 72 hoursUndo a bad bulk action or failed update
Daily full backup14 daysRecover from most incidents
Weekly8 weeksFind a clean point before a compromise you spotted late
Monthly12 monthsAudit, disputes and tax questions

Backups contain personal data, so write the retention period into your privacy policy and records. If you delete a client for a GDPR request, note it so the record isn't silently restored later.

What are good RPO and RTO targets for WHMCS?

For WHMCS, the recovery point objective (RPO) is how much recent data you can afford to lose, and the recovery time objective (RTO) is how long billing and the client area can be down. A host taking a few orders a day might accept a 24-hour RPO and a 4-hour RTO; a busy IPTV operator with hourly signups needs hourly dumps or database replication to get RPO under an hour. Whatever you choose, anything after the restore point still exists outside WHMCS: payments sit in Stripe, PayPal or your crypto gateway dashboard, accounts sit on your control panels, and domain changes sit at the registrar. Plan the reconciliation step, not only the restore.

How do you restore WHMCS after a disaster?

Restoring WHMCS after a disaster follows the same order as the official move to a new server procedure. If the cause was a hack, choose a restore point from before the compromise and follow what to do when WHMCS is hacked first, so you don't restore the backdoor.

  1. Stop automation. Disable the cron on the old server if it still runs, so it can't suspend or invoice from bad data.
  2. Build the server to WHMCS system requirements for the version in your backup: PHP 8.2 or later for 9.x, plus the matching ionCube Loader.
  3. Restore files and configuration.php from the same point as the database. If files are missing, download the full release of the same WHMCS version and add your custom code back.
  4. Restore the database into a new, empty database with gunzip < db.sql.gz | mysql whmcs_db or phpMyAdmin's Import tab, then update the database settings and any absolute paths in configuration.php.
  5. Turn on Maintenance Mode while you check things.
  6. Point DNS to the new server and update the System URL in Configuration > System Settings > General Settings if it changed.
  7. Reissue the license. For licenses bought from WHMCS, use Services > My Licenses in the WHMCS Member Area and click Reissue; licenses from a hosting provider are reissued by that provider.
  8. Recreate the cron pointing at crons/cron.php, then check gateway callbacks, email piping and storage locations.
  9. Reconcile payments, new orders and provisioning since the backup against gateway and panel records, then turn off Maintenance Mode.

How do you test a WHMCS backup restore?

A WHMCS backup you haven't restored is a guess. Once a quarter, restore the latest backup to a private test install (WHMCS gives one free development license per active license bought directly) and time it. Before the first page load, disable the cron, turn on Disable Email Sending in the Mail tab of General Settings and set gateways to test mode so the copy can't contact customers or charge cards. Then check:

  • Admin login works and the newest invoice, ticket and order match production.
  • An encrypted value, such as a server password, decrypts, which proves the configuration.php matches the database.
  • Ticket attachments and client files open.
  • The total time against your RTO.

Delete the test copy afterward. The same restore skills matter before a major update, which the WHMCS 9 upgrade guide covers.

Which tools work for WHMCS backups?

Most WHMCS providers combine two or three of these tools.

ToolCoversBest forWatch out for
WHMCS Database BackupsDatabaseA basic daily copy on any installNo files, no failure alerts
WHM Backup ConfigurationFull cPanel accountscPanel servers, with destinations such as Amazon S3, Backblaze B2, Google Drive, SFTP and WebDAVAccount-level schedule, usually daily
restic or BorgBackup with a scriptDatabase dumps and filesVPS and dedicated serversYou own the monitoring
Provider snapshotsThe whole server diskFast rollback before updatesSame provider and account, so not off-site
WHMCS Security moduleAutomatic secure backups and one-click rollback, plus hardeningRecovery from inside the WHMCS adminPair with an off-site copy

Frequently asked questions

Does WHMCS back up files automatically?

No. The SFTP/FTP and email options in Database Backups copy the database only, and the cPanel option asks cPanel to run an account backup without confirming it finished. Back up configuration.php and the WHMCS directories separately.

What happens if I lose configuration.php?

You can still restore the database, but WHMCS can't decrypt stored passwords, security questions or card data without the original encryption hash. You would create a new configuration.php and have clients reset passwords and re-add cards.

How often should I back up the WHMCS database?

Daily at minimum, and hourly if you take orders or payments throughout the day. Match the schedule to how many hours of transactions you could reconcile by hand.

Do I need a new WHMCS license after restoring to a new server?

Not a new license, but a reissue. A license bought from WHMCS is reissued at Services > My Licenses in the Member Area, and the new location is saved on your next visit; a license from a hosting provider is reissued by that provider.

Is WHMCS Cloud backed up?

Yes. WHMCS says it manages backups automatically on WHMCS Cloud, and the Database Backups settings apply only to self-hosted installs.

If you'd like this set up and tested for you, our WHMCS backup and disaster recovery service includes encrypted off-site backups, a verified test restore and a written runbook, and monthly maintenance keeps verifying them.