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.
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 Backupscovers the database only. Files andconfiguration.phpneed their own backup. - Without the matching
configuration.php, a restored database keeps passwords, security answers and card data permanently encrypted. - Use
mysqldump --single-transactionso 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.
| Item | Default location | Why it matters | How often |
|---|---|---|---|
| Database | MySQL or MariaDB, named in configuration.php | Clients, services, invoices, transactions, tickets, settings | Daily at minimum, hourly for busy installs |
configuration.php | WHMCS root directory | Database credentials and cc_encryption_hash, the key that decrypts stored data | After every change, stored apart from the database dump |
| Client files and ticket attachments | /attachments (and /attachments/projects) | Files clients and staff uploaded | Daily |
| Downloads and email template attachments | /downloads | Files you offer to clients | Weekly or after changes |
| Custom code | /templates, /modules, /includes/hooks, /lang/overrides | Your theme, third-party modules and hooks | After every change, ideally in Git |
| Cron and moved directories | /crons or a custom $crons_dir | Needed to rebuild the cron job | After 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:
| Method | What it sends | Requirements | Limits |
|---|---|---|---|
| SFTP/FTP Backup | A zipped SQL file to a remote server | Host, port, user, password, folder, and a passing Test Connection | FTP and SFTP only, no FTPS |
| cPanel Backups | Asks cPanel to run a full account backup, to remote FTP, SCP or the home directory | A cPanel API token with basic-system-info and cpanel-api permissions | WHMCS only starts the backup; it doesn't confirm completion or move the file |
| Daily Email Backups | The backup file to an email address | An address, ideally not hosted on the same server | Can 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.
- Create a read-only database user for backups with
SELECT,SHOW VIEWandTRIGGER(dump with--no-tablespacesso it doesn't also needPROCESS), and store its password in an option file readable only by root, so it never appears in the process list. - Dump with a consistent snapshot. The MySQL mysqldump manual says
--single-transactiondumps InnoDB tables in a consistent state without blocking applications. Avoid schema changes, such as a WHMCS update, while it runs. - Archive the directories in the table above, including
configuration.php. - 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.
- 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.
- 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.
| Copy | Keep | Purpose |
|---|---|---|
| Hourly or twice-daily database | 48 to 72 hours | Undo a bad bulk action or failed update |
| Daily full backup | 14 days | Recover from most incidents |
| Weekly | 8 weeks | Find a clean point before a compromise you spotted late |
| Monthly | 12 months | Audit, 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.
- Stop automation. Disable the cron on the old server if it still runs, so it can't suspend or invoice from bad data.
- 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.
- Restore files and
configuration.phpfrom 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. - Restore the database into a new, empty database with
gunzip < db.sql.gz | mysql whmcs_dbor phpMyAdmin's Import tab, then update the database settings and any absolute paths inconfiguration.php. - Turn on Maintenance Mode while you check things.
- Point DNS to the new server and update the System URL in
Configuration > System Settings > General Settingsif it changed. - Reissue the license. For licenses bought from WHMCS, use
Services > My Licensesin the WHMCS Member Area and click Reissue; licenses from a hosting provider are reissued by that provider. - Recreate the cron pointing at
crons/cron.php, then check gateway callbacks, email piping and storage locations. - 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.phpmatches 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.
| Tool | Covers | Best for | Watch out for |
|---|---|---|---|
| WHMCS Database Backups | Database | A basic daily copy on any install | No files, no failure alerts |
| WHM Backup Configuration | Full cPanel accounts | cPanel servers, with destinations such as Amazon S3, Backblaze B2, Google Drive, SFTP and WebDAV | Account-level schedule, usually daily |
| restic or BorgBackup with a script | Database dumps and files | VPS and dedicated servers | You own the monitoring |
| Provider snapshots | The whole server disk | Fast rollback before updates | Same provider and account, so not off-site |
| WHMCS Security module | Automatic secure backups and one-click rollback, plus hardening | Recovery from inside the WHMCS admin | Pair 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.
Tagged with: