FreePBX Backup and Restore from the Command Line (fwconsole)

Short answer: Create the backup job once in the FreePBX GUI (Admin > Backup & Restore), then work from the shell: fwconsole backup --list shows each job and its Backup ID, fwconsole backup --backup=<id> runs it, and fwconsole backup --restore=/path/to/file.tar.gz restores a backup file. With local storage the files land under /var/spool/asterisk/backup/. Copy them off the server and test a restore on a spare machine, or you do not really have a backup.

Applies to FreePBX 17 (Backup module 17.0), Asterisk 22, Debian 12

We ran fwconsole backup --help and --list and read the Backup module source on our lab server (Debian 12, FreePBX 17.0.33, Backup module 17.0.13, Asterisk 22.11) on 7 October 2026. We did not run a full backup or restore there, because we keep the lab PBX configuration unchanged; those steps follow Sangoma’s documentation (linked below).

How FreePBX 17 backups work

Since FreePBX 15 the Backup & Restore module works with backup jobs. A job is a saved definition: which modules to include, extra folders, where to store the file (one or more Filestore locations), a schedule, and how many old copies to keep. Each job has a Backup ID (a UUID). The command line runs jobs; it does not create them.

• File format: a .tar.gz containing metadata.json, a modulejson/ folder with one JSON file per module, and a files/ folder for module files and any custom directories.
• File name: date, time, Unix time, FreePBX version and a random number, for example 20261007-235901-1791417541-17.0.33-123456789.tar.gz (pattern taken from the module source).
• Local path: the default Local storage location is __ASTSPOOLDIR__/backup/, which is /var/spool/asterisk/backup/ on a standard install. If you tick the option to append the job name, files go into a subfolder named after the job, with spaces replaced by underscores.
• Remote storage: the Filestore module on our lab offers Local, SSH, FTP, S3, Dropbox and Email drivers.
• Call recordings are not included by default. Sangoma’s documentation says to add __ASTSPOOLDIR__/monitor as a custom directory in the job if you want them.

Voicemail, recordings and CDR data can make the file large. Check free space in /var/spool/asterisk and in /tmp before the first run: df -h /var/spool/asterisk /tmp.

List backup jobs and find the Backup ID

After you have saved a job in the GUI, list the jobs from the shell:

fwconsole backup --list

The output is a table with three columns: Backup Name, Description and Backup ID. On our lab, which has no jobs defined, the table is empty, so a blank table simply means no job exists yet. The command also prints a Transaction ID is: ... line; you can ignore it when listing.

The full option list on FreePBX 17.0.33 comes from fwconsole backup --help. The ones you will use most:

Option	What it does
--list	List backup jobs with their IDs
--backup=<id>	Run the job with that Backup ID
--restore=<file>	Restore from a backup file
--backupsingle=<module> and --singlesaveto=<dir>	Back up one module to a folder
--restoresingle=<file>	Restore a single-module backup file
--modules=a,b	Restore only these modules from a full backup
--ignoremodules=a,b	Restore everything except these modules
--dumpextern=<id>	Print a job definition as a Base64 string
--externbackup=<string>	Run a job from such a Base64 string
--output=<file> / --error-log=<file>	Write output or errors to a file

Run a backup job from the CLI

fwconsole backup --backup=<backup-id>

# find the file it produced (last 24 hours)
find /var/spool/asterisk/backup -name '*.tar.gz' -mtime -1 -ls

From the module source, a full run processes each module, then runs local maintenance (deletes copies beyond your retention settings), uploads to every storage location in the job, runs remote maintenance and ends with Backup completed successfully, or prints the errors and warnings it collected. If the job has a pre-backup hook, it runs first. The job’s email settings decide whether you get a success or failure email.

To back up just one module, for example before you change ring groups, use the single-module options:

mkdir -p /var/spool/asterisk/tmp/single
chown asterisk:asterisk /var/spool/asterisk/tmp/single
fwconsole backup --backupsingle=ringgroups --singlesaveto=/var/spool/asterisk/tmp/single

fwconsole switches to the asterisk user, so the target folder must be writable by that user. On our lab, a single-module backup into a root-only folder under /root failed with Failed to create "...": mkdir(): Permission denied. Single-module backups do not include dependencies; the module logs “In single restores mode dependencies are NOT processed”.

Schedule backups (and see the cron line)

Set the schedule in the job (Admin > Backup & Restore > edit job > Schedule). When you save, the module writes a line into the asterisk user’s crontab. Check it with:

crontab -u asterisk -l | grep 'fwconsole backup'

Going by the module source, the line has the form <schedule> /usr/sbin/fwconsole backup --backup=<id> --output=/dev/null --error-log=/dev/null. A new job form suggests a random weekly time at 23:59. Do not edit that line by hand: the module removes and rewrites its backup cron lines when jobs are saved. To change the time, edit the job.

Set retention in the same job: keep the last N runs, or delete files older than N days. Setting the number of runs to 0 keeps everything, which is how disks fill up. Build a cron expression with our cron expression helper if you want to check what a schedule means.

Copy backups off the server

A backup that lives only on the PBX disappears with the PBX. You have two good options:

1. Add a remote storage location to the job. Create it under Admin > Filestore (SSH, S3, FTP and so on), then tick it in the job’s storage list. The module uploads each new file and applies remote maintenance.
2. Pull from a backup host. Let a separate server fetch the files, so the PBX holds no credentials for your backup storage:

# on the backup host (key-based SSH, read-only use of the PBX)
rsync -av --ignore-existing backupuser@pbx.example.com:/var/spool/asterisk/backup/ /srv/backups/pbx1/

The user on the PBX needs read access to /var/spool/asterisk/backup. Encrypt copies stored with a third party; backup files contain SIP secrets, voicemail PINs and your trunk credentials. Our restic offsite backup script adds encryption and retention if you prefer that route.

Restore a backup from the CLI

A restore replaces the current configuration of the modules it contains. Before you restore onto a running PBX, run a fresh backup of that PBX and copy it somewhere safe.

Copy the file to the server, make it readable by asterisk, and restore. Sangoma recommends the CLI for large backups because the browser upload can time out:

chown asterisk:asterisk /var/spool/asterisk/backup/20261007-235901-1791417541-17.0.33-123456789.tar.gz
fwconsole backup --restore=/var/spool/asterisk/backup/20261007-235901-1791417541-17.0.33-123456789.tar.gz

Useful restore options from fwconsole backup --help on FreePBX 17.0.33:

Option	Use it when
--skipremotenat	The new server has a different public IP or local networks
--skipbindport	Keep the target server’s SIP bind ports
--skipdns	Keep the target server’s DNS settings
--skiptrunksandroutes	Restore a test copy that must not register trunks or send calls
--modules= / --ignoremodules=	Restore only part of the backup
--skiprestorehooks	Do not run the post-restore hooks
--restorelegacycdr	Include CDR data from a legacy (pre-15) backup
--convertchansipexts2pjsip / --convertchansiptrunks2pjsip	Convert chan_sip devices while restoring onto Asterisk 21 or later

If /tmp is small, point the temporary files at a larger disk, as in Sangoma’s documentation: TMPDIR=/var/spool/asterisk/tmp fwconsole backup --restore=.... After the restore, run fwconsole reload.

Restoring to a new server

Install the same FreePBX major version on the new server and update its modules first (fwconsole ma upgradeall). Then restore with --skipremotenat if the IP changes, and fix NAT settings by hand. Keep the old server running until phones and trunks work on the new one. Commercial module licences are tied to the old deployment and must be moved separately. If you are moving from FreePBX 16 to 17, follow Upgrade FreePBX 16 to 17, which covers the chan_sip and Macro() issues.

Check that it worked

1. The file exists and is not tiny: ls -lh /var/spool/asterisk/backup/ (and the job subfolder).
2. The archive is readable: tar -tzf FILE.tar.gz | head should list metadata.json, modulejson/ and files/. Corruption shows up as a gzip or tar error. Our backup verify script can automate this check for every new file.
3. The off-server copy matches: compare sha256sum on both sides.
4. A test restore succeeds: restore onto a spare VM with --skiptrunksandroutes so it cannot place calls, then check fwconsole ma list, asterisk -rx "pjsip show endpoints" and a few extensions in the GUI.
5. The schedule is in place: crontab -u asterisk -l | grep "fwconsole backup".

Common problems

• Invalid backup id! The ID does not match any job. Copy it from fwconsole backup --list; it is a UUID, not the job name.
• This backup is already running! A previous run of the same job is still active. Wait for it, or check with ps aux | grep "fwconsole backup" before you start another.
• mkdir(): Permission denied The target folder is not writable by asterisk. Use a folder under /var/spool/asterisk or change its owner.
• Restore stops with disk or memory errors. Set TMPDIR to a larger disk and check df -h. Large recording folders are the usual cause.
• Backups never run on schedule. The job has no schedule saved, or the asterisk crontab line is missing. Re-save the job and check the crontab again.
• Disk full on the PBX. Retention is set to keep everything. Set “delete after runs” or “delete after days” in the job.

Official documentation: Sangoma: Backup and Restore (15+) · Sangoma: fwconsole commands (15+)

Related: Upgrade FreePBX 16 to 17: Backup, Restore and Migration Checklist · Install FreePBX 17 on Debian 12 (Open-Source Only, Tested) · Backup Verify Script · Restic Backup Script for Offsite Backups · Cron Expression Helper

See also: Upgrade FreePBX 16 to 17: Backup, Restore and Migration Checklist · Asterisk CDR Reports from MySQL/MariaDB (FreePBX asteriskcdrdb)

Frequently asked questions

Maintenance record

This guide changes servers, data or security settings, so we re-check it against current versions on a fixed schedule. Take a backup or snapshot before you start.

Maintained by

srvScripts editorial team

Supported versions

FreePBX 17 (Backup module 17.0), Asterisk 22, Debian 12

Last full review

7 Oct 2026

Next review

5 Apr 2027

Sources

sangomakb.atlassian.net/wiki/spaces/PG/pages/20807752/Backup+and+Restore+FreePBX+15
sangomakb.atlassian.net/wiki/x/SQB9Ag