Migrate FreePBX 16 to 17: restore and validate

Use a separate target

For a FreePBX 16 appliance moving to 17, Sangoma describes backup, Debian installation and restore as the supported path. Build a separate FreePBX 17 target on Debian 12 rather than treating an old operating system as an in-place upgrade. Confirm current platform, commercial module and hardware compatibility before a cutover window.

Inventory extensions, trunks, DIDs, outbound routes, custom destinations, voicemail, recordings, certificates, firewall rules, provisioning and integrations. Save installed versions and module lists alongside the source backup. Record the current carrier and device registration destinations so the new host cannot accidentally serve production during rehearsal.

Do not change the supported target because Debian stable changed

Debian 13.7 is now the current stable distribution, but the FreePBX 17 download page and installer repository still specify Debian 12.x. Build the migration target from the current FreePBX instructions rather than replacing their platform choice with Debian's newest release or upgrading the source host's operating system in place.

Debian 12 is now in LTS through June 30, 2028, with some packages potentially outside LTS coverage. Capture debian-security-support findings and every non-Debian repository or module as separate maintenance evidence. The future move away from Debian 12 needs its own supported FreePBX path, rehearsal and rollback; it is not a hidden extra step inside a 16-to-17 restore.

Restore in an isolated rehearsal

Use the supported Backup and Restore module and inspect its job scope and completion logs. Set up the new Debian 12 host through the current FreePBX 17 installer. Keep the rehearsal target from registering live trunks or competing with production phones. If commercial modules are involved, follow Sangoma’s deployment activation order before restoring; open-source-only installations have different latitude.

Inspect every restore warning and compare the result with the source inventory. A successful archive import alone does not establish that licensed features, custom files, external services and endpoints are operational.

Treat chan_sip conversion as a new trunk test

The 17 restore process can convert older chan_sip extensions and trunks to PJSIP. Sangoma explicitly calls for thorough testing of converted trunks because provider settings vary. Port settings from chan_sip can also be reassigned to the restored system’s PJSIP defaults. Compare signaling ports, endpoint identification, credentials, registration, transports, codecs, caller ID and number formatting against the carrier’s current instructions.

Make bounded internal, inbound, outbound, transfer, voicemail and emergency-routing checks through the carrier’s approved test procedure. Verify both directions of audio and hangup, including calls after a registration renewal. Do not use a green registration indicator as the acceptance test.

Cut over with a rollback boundary

Agree on a maintenance window and the operator who controls trunk and device cutover. Preserve the old host and its backup until post-cutover evidence is accepted. Monitor registrations, inbound routing, call detail records and voicemail delivery; document the actual result of each test.

Do not assume that a backup created on 17 can be restored back to 16: Sangoma says that downgrade path is not tested or supported. A practical rollback returns traffic to the intact old system after coordinating carrier and phone changes, rather than attempting a reverse restore. Keep a separate communications path during the window.

Rehearse each chan_sip trunk as a separate PJSIP service

The focused trunk migration guide expands the restore-time conversion boundary into provider evidence, FreePBX ownership, PJSIP object relationships, listener conflicts, route cutover and per-direction acceptance. Do not make the operating-system migration and every trunk conversion one irreversible event.

Prove the migrated target stays dark before cutover

Use the restore-testing procedure to inspect converted PJSIP registrations, endpoints, contacts and routes while carrier egress remains denied. If the target competes with the old PBX, use the restored-PBX diagnostic and recover production ownership before continuing migration tests.

Gate custom Macro compatibility separately from archive restore

Sangoma says FreePBX 17 defaults to Asterisk 22, where Macro is unavailable. Use the macro-to-Gosub migration guide to inventory and convert site-owned dialplan or AGI calls before treating a successful restore as routing acceptance.

Keep Asterisk branch capability inside the FreePBX migration owner

The release lifecycle guide distinguishes upstream branch facts from package and appliance availability. Do not replace FreePBX-owned packages or generated configuration merely to match an upstream page.