# Upgrade FreePBX 16 to 17: Backup, Restore and Migration Checklist

Source: https://srvscripts.com/guides/upgrade-freepbx-16-to-17/
Updated: 2026-10-07
Publisher: srvScripts (https://srvscripts.com/)

**Short answer:** There is no in-place upgrade from FreePBX 16 to 17. FreePBX 16 runs on CentOS 7/SNG7, FreePBX 17 on Debian 12, so you build a new Debian 12 server, take a full backup with the Backup & Restore module on 16, copy it across and restore it with `fwconsole backup --restore=/path/to/backup.tar.gz`. Plan for what does not carry over cleanly: chan_sip (Asterisk 22 has none), custom `Macro()` dialplan, commercial module licences (move the Deployment ID) and anything you set up at OS level.

We ran the fwconsole commands below on our lab server (Debian 12, FreePBX 17.0.33, Asterisk 22.11) on 6 October 2026 to confirm their options. The full 16-to-17 restore follows Sangoma’s documentation (linked below); we have not yet run it end to end on our lab.

## Why FreePBX 16 to 17 is a migration, not an upgrade

Sangoma’s upgrade page is direct about it: the supported path is backup on FreePBX 15 or 16, a fresh FreePBX 17 install, then restore. Three things change at once:

- **Operating system:** CentOS 7 based SNG7 to Debian 12. Packages, paths for system services, and the firewall stack all differ.

- **Asterisk:** FreePBX 17 installs Asterisk 22 by default. Asterisk 22 has no chan_sip driver and no `Macro()` application.

- **Hardware fingerprint:** a new server means commercial licences tied to the old one must be moved.

Because the old server keeps running until you cut over, this is also your rollback plan: if the new box misbehaves, point phones and trunks back at the old one.

## Before you start: inventory the FreePBX 16 server

Collect this while the old system is still live. Most migration surprises come from items nobody wrote down.

- **Versions:** FreePBX and Asterisk version (`fwconsole -V`, `asterisk -rx "core show version"`). Update all modules on 16 first (`fwconsole ma upgradeall`) so the backup format is current.

- **chan_sip use:** list chan_sip extensions and trunks in the GUI (Applications > Extensions and Connectivity > Trunks show the technology).

- **Custom dialplan:** `grep -n "Macro(" /etc/asterisk/extensions_custom.conf` and any AGI scripts. These must be rewritten to `Gosub()`.

- **Commercial modules:** note each one (System Admin Pro, EndPoint Manager, Call Recording Reports and so on) and confirm each has a FreePBX 17 release before you commit to a date.

- **Network facts:** public IP, hostname, NAT settings, provider IP allow-lists that include your current IP, and the IPs phones are provisioned with.

- **Things outside FreePBX:** crontabs, custom scripts, SSH keys, mail relay settings, VPNs, monitoring agents, TLS certificates obtained outside Certificate Manager.

Inventory the old PBX’s NAT settings with our [PJSIP NAT generator](/tools/pjsip-nat-generator/) in mind: if the public IP changes, external address and provider allow-lists must change too.

## Take the backup on FreePBX 16

In the FreePBX 16 GUI, go to **Admin > Backup & Restore** and create a backup job that includes all modules. Run it, then download the resulting `.tar.gz` or copy it from the backup storage location. From the shell you can run an existing job by ID:

```
fwconsole backup --list
fwconsole backup --backup=
```

Copy the file to the new server with `scp` or `rsync`. Check its size and keep a second copy off both servers. Do not change the old system after this point, or take a fresh backup just before cut-over.

Call recordings and voicemail can make the backup very large. If you include them, plan disk space on the new server for the backup file plus the restored data, and expect the restore to take a long time.

## Build the FreePBX 17 server

Install Debian 12 and FreePBX 17 using Sangoma’s install script; our draft guide [Install FreePBX 17 on Debian 12](/guides/install-freepbx-17-debian-12/) walks through it. Two choices matter for a migration:

- **Commercial modules or open source only.** The install script has an `--opensourceonly` option. With it, the script removes commercial modules and also removes the Firewall module, because Firewall depends on the commercial System Admin module. If you relied on the FreePBX Firewall or System Admin on 16, install without that option.

- **Same version line for Asterisk.** If you cannot convert chan_sip or Macro dialplan in time, Sangoma documents switching Asterisk to a version below 21 before restoring. Treat that as temporary: Asterisk 20 goes security-fix-only on 19 October 2026.

Update all modules on the new server before restoring (`fwconsole ma upgradeall`, then `fwconsole reload`).

## Restore the backup on FreePBX 17

The GUI restore works for small backups. Sangoma recommends the CLI for large ones, because the browser can time out. Run it as the `asterisk` user:

```
sudo -u asterisk fwconsole backup --restore=/var/spool/asterisk/backup/restore-xxxxxx.tar.gz
```

If `/tmp` is small, point temporary files somewhere with space, as Sangoma’s documentation shows:

```
sudo -u asterisk TMPDIR=/var/spool/asterisk/tmp fwconsole backup --restore=/var/spool/asterisk/backup/restore-xxxxxx.tar.gz
```

`fwconsole backup --help` on our FreePBX 17.0.33 lab lists options that are useful in a migration:

| Option | Use it when |
| --- | --- |
| --convertchansipexts2pjsip | Convert chan_sip extensions to PJSIP during the restore |
| --convertchansiptrunks2pjsip | Convert chan_sip trunks to PJSIP during the restore |
| --skipchansipexts / --skipchansiptrunks | Leave chan_sip extensions or trunks out and rebuild them by hand |
| --skipbindport | Keep the new server’s SIP bind ports instead of the old ones |
| --skipremotenat | Do not restore the old NAT (external IP, local networks) settings |
| --skipdns | Do not restore DNS settings |
| --skiptrunksandroutes | Restore everything except trunks and routes (useful for a staged test) |
| --ignoremodules= | Skip named modules |
| --restorelegacycdr | Also restore CDR data from a legacy backup |

In the GUI, if the backup contains chan_sip devices, Sangoma’s documentation says the restore pauses and offers to convert them to PJSIP or cancel. A typical migration command, converting both and keeping the new server’s NAT settings, looks like this:

```
sudo -u asterisk fwconsole backup --restore=/var/spool/asterisk/backup/restore-xxxxxx.tar.gz \
  --convertchansipexts2pjsip --convertchansiptrunks2pjsip --skipremotenat
fwconsole reload
```

Review the converted trunks in **Connectivity > Trunks** afterwards. Converted settings are a starting point; see our [chan_sip to PJSIP migration guide](/guides/chan-sip-to-pjsip-migration/) for what to check.

## What does not carry over

| Item | What happens | What to do |
| --- | --- | --- |
| chan_sip extensions and trunks | No chan_sip in Asterisk 22 | Convert during restore, or with fwconsole convert2pjsip and fwconsole trunks --convert2pjsip |
| Macro() in custom dialplan or AGI | Asterisk 22 has no app_macro | Rewrite to Gosub() before or right after the restore |
| Commercial module licences | Licences are locked to the old hardware | Reset the hardware lock on the Deployment ID in the Sangoma portal, then register the new server |
| System Admin and Firewall settings | Absent on an open-source-only install | Install with commercial modules, or replace with your own firewall and fail2ban |
| OS-level setup | Not part of a FreePBX backup | Recreate crontabs, scripts, SSH keys, monitoring by hand |
| Phones registered by IP | Still point at the old server | Re-provision, or move the old IP or DNS name to the new server |
| Provider IP allow-lists | Old public IP only | Ask providers to add the new IP before cut-over |

For licences, Sangoma’s “How to Move a Deployment ID to a new PBX” page describes the steps: in **portal.sangoma.com** open the deployment, use **Reset Hardware Lock** on the License tab, then register the Deployment ID on the new server. The portal allows two resets per deployment; after that you have to ask Sangoma support. Do the reset only when you are ready to move.

## Cut-over checklist and verification

- Restore finished without errors; run `fwconsole reload` and `fwconsole ma list` to confirm modules are enabled.

- `asterisk -rx "pjsip show registrations"` shows each provider **Registered** (IP-authenticated trunks will not appear here; test them with a call).

- Set NAT in **Settings > Asterisk SIP Settings**: External Address and Local Networks for the new server.

- Move phones: `pjsip show contacts` should list each phone as **Avail**.

- Test inbound to an IVR, ring group and queue; outbound local, long distance and emergency route (if your provider supports test calls).

- Check voicemail to email, call recording and CDR Reports playback.

- Check `fail2ban-client status` and your firewall rules; see our [fail2ban for Asterisk and FreePBX](/guides/fail2ban-asterisk-freepbx/) guide.

- Take a first FreePBX 17 backup and confirm it completes.

- Keep the FreePBX 16 server powered but disconnected from trunks for a week as a fallback.

Common problems after the restore:

- **Trunk registers but calls fail with 403:** the provider still allow-lists only the old IP.

- **No audio on external calls:** NAT settings restored from the old server, or not set at all. Use `--skipremotenat` and set them fresh.

- **Custom feature stops working:** look for `Macro(` in `/etc/asterisk/extensions_custom.conf` and Asterisk log lines about an unknown application.

- **Commercial module shows unlicensed:** the Deployment ID still holds the old hardware lock.

**Official documentation:** [Sangoma: Upgrading to FreePBX 17](https://sangomakb.atlassian.net/wiki/spaces/FP/pages/230850573) · [Sangoma: Move a Deployment ID to a new PBX](https://sangomakb.atlassian.net/wiki/spaces/PG/pages/39059842) · [Asterisk versions and EOL dates](https://docs.asterisk.org/About-the-Project/Asterisk-Versions/)

**Related:** [Migrate PBX to Cloud: 8-Step Plan From 3CX or Asterisk](/guides/migrate-pbx-to-cloud/) · [PJSIP Behind NAT: Asterisk and FreePBX Settings for Two-Way Audio](/guides/pjsip-nat-asterisk-freepbx/) · [fail2ban for Asterisk and FreePBX: Block SIP Password Guessing](/guides/fail2ban-asterisk-freepbx/) · [PJSIP NAT Settings Generator: Asterisk, FreePBX, Issabel, VitalPBX, 3CX](/tools/pjsip-nat-generator/) · [SIP Ports Firewall Rules: 4 Setups for CSF, firewalld and pfSense](/guides/sip-ports-firewall/)

**See also:** [Install FreePBX 17 on Debian 12 (Open-Source Only, Tested)](/guides/install-freepbx-17-debian-12/) · [FreePBX Responsive Firewall vs Intrusion Detection (FreePBX 17)](/guides/freepbx-responsive-firewall-intrusion-detection/) · [Asterisk and FreePBX Toll Fraud Prevention: 10-Point Checklist](/guides/asterisk-freepbx-toll-fraud-prevention/) · [3CX vs FreePBX: Licensing, Hosting, Features and Lock-in (2026)](/guides/3cx-vs-freepbx/)

**See also:** [FreePBX Backup and Restore from the Command Line (fwconsole)](/guides/freepbx-backup-restore-cli/)

## Frequently asked questions

### Can I upgrade FreePBX 16 to 17 in place?

No. FreePBX 16 runs on CentOS 7/SNG7 and FreePBX 17 on Debian 12, so Sangoma documents backup on 16, fresh install of 17, then restore.

### What happens to chan_sip extensions when I restore on FreePBX 17?

Asterisk 22 has no chan_sip. Convert them during the restore with –convertchansipexts2pjsip and –convertchansiptrunks2pjsip, or skip them and rebuild them as PJSIP.

### Do commercial module licences move automatically?

No. Reset the hardware lock on the Deployment ID in the Sangoma portal and register the new server. The portal allows two resets per deployment.

### Why is the Firewall module missing after I installed FreePBX 17?

The install script’s –opensourceonly option removes commercial modules and also the Firewall module, because Firewall depends on the commercial System Admin module.

### Should I restore from the GUI or the CLI?

The CLI, for anything large. Sangoma recommends sudo -u asterisk fwconsole backup –restore=/path/file.tar.gz because the GUI can time out.