FreePBX backup and restore — what the module covers, what it doesn't, what you should add

The FreePBX® Backup & Restore module is the in-PBX backup tool — it captures the FreePBX configuration cleanly and can restore to another FreePBX install of the same major version. But it's not a complete VPS backup, and over-relying on it has bitten a lot of people. This article covers what it does, what it doesn't, and the supplementary backups you should layer on.

What Backup & Restore captures

The default backup template (Settings → Backup & Restore → Templates) covers:

• FreePBX framework config (extensions, trunks, routes, IVR, feature codes).
• Module-specific data (queues, paging, conference rooms).
• Voicemail content (recordings, greetings).
• Call recordings (if you store them locally).
• System recordings (custom prompts, music on hold).
• CDR database.
• Certain system files (Asterisk modules.conf, custom dialplan files).

What it does NOT capture

• OS-level config. Custom files outside Asterisk and FreePBX paths. SSH keys you generated. NTP config. Firewall rules. Cron jobs.
• System packages. What you installed with yum/apt outside the FreePBX module system.
• The FreePBX module versions themselves. A restore expects the same module versions to be present on the destination.
• Commercial module activation. EPM, App Manager, and other commercial modules need to be re-activated against the destination's deployment ID.
• SIP credentials from carriers if they're stored outside the FreePBX trunk config. Rare but possible.

Setting up scheduled backups

1. Settings → Backup & Restore → Templates.
2. Edit the default template or create a new one.
3. Pick which items to include (default selections are usually right).
4. Set destination — Local, FTP, SCP/SFTP, AWS S3, Email (don't use email for anything but a tiny config).
5. Set schedule — daily is reasonable for active PBXes.
6. Set retention — how many backups to keep before rotating off.

Test the restore at least once before trusting the schedule. A backup you've never restored from isn't a backup; it's an untested assumption.

The supplementary backups you should add

Backup & Restore covers FreePBX. You also want:

1. VM snapshot before risky changes

Portal → your VPS → Snapshots → New. Takes seconds, captures the entire VM state including OS-level config. Restoring is one click. Free and ridiculously useful.

See VPS snapshots.

2. Off-host backup of /etc and /var

Restic, borg, or rsnapshot pulling /etc, /var/lib/asterisk, /var/spool/asterisk, the MySQL/MariaDB dumps, and any custom directories to off-host storage. Catches the case where the VM itself is lost (e.g., catastrophic disk failure on a hypervisor — rare, but it happens).

See Restic with Backblaze B2 for a concrete pairing.

3. Database dump separately

FreePBX's Backup module dumps the DB as part of its backup, but it's nested inside the .tar of everything. Daily standalone mysqldump --all-databases to off-host storage is easier to restore from when only the DB is the problem.

# /etc/cron.daily/freepbx-db-dump
#!/bin/bash
mysqldump --all-databases --single-transaction \
  | gzip > /var/backups/freepbx-db-$(date +\%F).sql.gz
find /var/backups -name 'freepbx-db-*.sql.gz' -mtime +14 -delete

Restoring

Same VPS — recover from a config mistake

1. Settings → Backup & Restore → Restore.
2. Pick the backup and the restore template.
3. Apply.
4. Run fwconsole reload and verify registration of trunks and extensions.

New VPS — same FreePBX version

1. Install the same FreePBX major version on a new VPS.
2. Install all the same modules (with the same versions if possible).
3. Copy the backup .tar to the new VPS.
4. Settings → Backup & Restore → upload the backup file as a restore source.
5. Restore. Then run fwconsole chown && fwconsole reload.
6. For commercial modules: re-activate against the new Deployment ID under System Admin → Activation.
7. Phones: update their provisioning URL to the new PBX IP. Or set up EPM with the same templates and re-provision.

New VPS — different FreePBX major version

Don't restore directly across major versions. Instead:

1. Install the same major version on the new VPS.
2. Restore there.
3. Upgrade in place to the newer major version.

This avoids the schema-migration issues that come from restoring a backup older than the FreePBX framework expects.

Common pitfalls

• Trusting an untested backup. Restore to a test VPS at least once. The backup that fails to restore at 3am is the most expensive mistake in this article.
• Backing up locally only. Local backups die with the disk. Send a copy off-host.
• Restoring on a different FreePBX major version. Schema mismatch breaks things in subtle ways. Match version first, then upgrade.
• Skipping the database after restore. Run fwconsole chown and fwconsole reload. The restore copies files but doesn't always set permissions right.
• Forgetting to re-activate commercial modules. The Deployment ID is bound to the original install. After restore, you have a new ID. Re-activate.