VoIP.infoThe independent guide to business communications.
VoIP.info Guide

FreePBX 17 macro-to-Gosub migration for custom dialplan

Inventory every custom Macro dependency before a FreePBX 17 restore, translate its call and return semantics into explicit Gosub frames, and prove the loaded route without editing generated dialplan.

Reviewed 2026-10-14Sangoma FreePBX 17 migration and platform guidance plus Asterisk 20 Macro semantics and current branch-23 Gosub, Return, LOCAL, LOCAL_PEEK and StackPop documentation reviewed October 14, 2026; Sangoma says the supported FreePBX 17 install defaults to Asterisk 22, where Macro is unavailable and custom dialplan or AGI macro calls require manual conversion, but installed FreePBX, Asterisk, modules, custom files, includes, generated dialplan, subroutine stack, variables, channels, routes and calls remain deployment specific, and no PBX, backup, restore, file, dialplan, AGI script, channel, route or call was inspected or testedAdvancedDocumentation based · not lab tested

Treat the Asterisk engine change as a compatibility gate

Sangoma says the supported FreePBX 17 install defaults to Asterisk 22 and that Asterisk 22 does not support the Macro dialplan application. Its migration page warns that restored custom dialplan or AGI scripts using macros will not work until those calls are converted manually to Gosub. FreePBX-generated dialplan has already moved away from Macro, but that does not rewrite site-owned files or external integrations.

Record the source FreePBX and Asterisk versions, target versions, backup hash, restore transaction, installed module inventory and every custom include. A successful restore proves archive processing, not that every custom application exists or every route reached its former destination.

Inventory callers, macro contexts and hidden contracts

Search supported custom include files, Custom Destinations, AGI source and deployment tooling for Macro(, MacroIf, MacroExit, MacroExclusive, macro- contexts and MACRO_ variables. Preserve each caller, argument order, branch, destination and expected continuation before changing syntax. Do not edit FreePBX-generated files, because Apply Config can replace them.

Asterisk 20 documented Macro as entering extension s in macro-name, exposing ARG1 onward and saving the original location in MACRO_EXTEN, MACRO_CONTEXT and MACRO_PRIORITY. A mechanical name change does not recreate those hidden values, MacroExit behavior, offset continuation or exclusivity.

Translate the call target and return path explicitly

Current Asterisk documents Gosub([[context,]extension,]priority(args)) as a jump that saves a return address. Convert one caller at a time to a complete context, extension and priority, pass reviewed arguments in parentheses and end every returning branch with Return(). A fall-through, Goto() away from the subroutine or hangup is a different outcome.

Return(value) removes the last Gosub stack frame and stores the value in GOSUB_RETVAL. Preserve whether the legacy caller expected a variable side effect, an offset, a jump, a hangup or a value. Do not invent a return contract simply because the new subroutine reaches its last priority.

Replace implicit Macro variables deliberately

Gosub arguments remain available as ARG1, ARG2 and so on, but Macro location variables are not a portable substitute for the caller identity in a Gosub frame. Pass the original extension or context as explicit arguments when the business rule genuinely needs them, and document the exact owner.

Use LOCAL(name) for scratch values that must belong only to the current Gosub frame; Asterisk says the value disappears or restores its previous value after Return(). LOCAL_PEEK() can inspect a variable hidden by a specified number of frames, but an empty result can also mean the requested depth does not exist. Ordinary channel variables, inherited variables and local frame variables remain separate scopes.

Preserve FreePBX ownership and supported entry points

Keep the converted routine in an approved custom include or other site-controlled source. Point the existing FreePBX Custom Destination or authorized hook to the stable public entry point, then Apply Config and inspect the loaded dialplan. Do not paste a replacement into module-generated contexts or rename a module-owned destination merely to match the old macro label.

Draw the complete call path from inbound or internal source through the FreePBX destination, custom entry, Gosub frame, returned value or side effect and next supported destination. A subroutine that works from asterisk -rx inspection is not proof that the production route enters it on the intended channel.

Accept the migration with stack and route evidence

On an isolated restored target, load the exact custom revision, confirm no obsolete Macro application is referenced, inspect the public entry and subroutine priorities, and run a bounded matrix covering normal return, each conditional branch, invalid input, hangup and nested calls. Correlate channel, unique and linked identifiers, Gosub entry, arguments, local values, GOSUB_RETVAL, return priority and final destination.

Use StackPop() only when the intended behavior is explicitly to discard the most recent return address; it is not a generic repair for an unbalanced routine. Keep the prior target available for rollback and do not register production trunks or route public calls from an isolated restore. No PBX, restore, dialplan, channel or call was tested for this guide.

Asterisk custom include — explicit Gosub contract
[from-custom-entry]
exten => migrate-check,1,Gosub(site-route,s,1(${EXTEN},normal))
 same => n,NoOp(Subroutine result: ${GOSUB_RETVAL})
 same => n,Goto(from-internal,${EXTEN},1)

[site-route]
exten => s,1,Set(LOCAL(original_extension)=${ARG1})
 same => n,Set(LOCAL(mode)=${ARG2})
 same => n,Return(ok)

Sources & applicability

Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.

Examples require adaptation to your topology. No live PBX or hardware testing is claimed.

Continue your research

Hub

FreePBX

Plan and administer a FreePBX 17 system on Debian 12 using the supported project installation path.

Explore topic →
Guide · FreePBX 16-to-17 migration target and Debian lifecycle evidence reviewed October 8, 2026; FreePBX still directs FreePBX 17 installations to Debian 12.x while Debian 12 is oldstable under LTS through June 30, 2028, and no source PBX, target host, archive, package, module, trunk, endpoint, compatibility or call was inspected or tested

Migrate FreePBX 16 to 17: restore and validate

Plan a separate Debian 12 target, inspect converted SIP objects and rehearse cutover and rollback.

Read guide →
Guide · Sangoma Custom Destinations, Misc Applications and Misc Destinations guidance; FreePBX Custom Applications 17.0.1 and Misc Applications 17.0.3 release/17.0 metadata and current dialplan sources; and current Asterisk Goto, Gosub, Return and dialplan documentation reviewed October 11, 2026; older screen guides establish concepts rather than an exact FreePBX 17 field map, and no installed module, code, application, destination, generated or loaded dialplan, caller path or call was inspected or tested

FreePBX Custom Destinations: publish custom dialplan without losing ownership

Register a reviewed context, extension and priority as a managed destination, choose transfer or subroutine behavior deliberately, and keep source, generated state and call results separate.

Read guide →
Guide · FreePBX Backup & Restore release/17.0 source, FreePBX advisories GHSA-5v7h-49gr-jcwr and GHSA-f6hc-rqxg-ch86, and Sangoma Filestore, backup, fwconsole and FreePBX 17 migration documentation reviewed October 12, 2026; the advisories identify affected Backup & Restore versions below 17.0.6 and 17.0.30 respectively, but repository or advisory state does not prove the installed module, archive custody, target handlers or restored runtime, and no PBX, archive, storage destination, credential, job, restore, module, endpoint, trunk or call was inspected or tested

FreePBX backup and restore: prove the recovery path

Choose backup scope, protect off-host storage and validate an isolated restore before relying on it.

Read guide →
Guide · Asterisk subroutine documentation and Asterisk 22 application references reviewed October 12, 2026; exact application syntax, channel behavior and available functions remain dependent on the installed Asterisk branch and modules, and no PBX, dialplan, channel, stack frame, handler, endpoint, bridge, header, call or media path was inspected or tested

Asterisk Gosub subroutines: stack, scope and channel ownership

Use Gosub and Return while keeping stack frames, arguments, return values and caller- or callee-channel execution independently observable.

Read guide →
Guide · Current Asterisk 22 dialplan, CLI, application and hangup-cause documentation reviewed October 1, 2026; no Asterisk host, dialplan, endpoint, trunk, call, media or emergency route was tested

Testing an Asterisk dialplan change safely

Prove context entry, extension matching, priority execution, call-leg outcomes and rollback without treating a successful reload as a successful call.

Read guide →
Troubleshooting · Sangoma FreePBX 17 migration and platform guidance plus Asterisk 20 Macro semantics and current branch-23 Gosub, Return, LOCAL, LOCAL_PEEK and StackPop documentation reviewed October 14, 2026; Sangoma says the supported FreePBX 17 install defaults to Asterisk 22, where Macro is unavailable and custom dialplan or AGI macro calls require manual conversion, but installed FreePBX, Asterisk, modules, custom files, includes, generated dialplan, subroutine stack, variables, channels, routes and calls remain deployment specific, and no PBX, backup, restore, file, dialplan, AGI script, channel, route or call was inspected or tested

FreePBX 17 restored custom macro is missing or returns incorrectly

Find the first divergence among restored custom files, unavailable Macro calls, FreePBX entry points, Gosub targets, argument and variable scope, stack balance, return value and downstream destination.

Read guide →