Asterisk upgrades and rollback planning
An upgrade changes a running dependency of your call routes and integrations. Choose the exact target, identify the configuration owner and prepare recovery before replacing software. A successful installation command is not evidence that every call path still behaves correctly.
Source-reviewed, 18 October 2026. Prepared from the cited documentation. This procedure has not been independently tested by Phone Guides. Scope: planning an Asterisk 22 maintenance change or migration to that branch; installation commands remain specific to the package or product owner.
Inventory the starting point
Record the installed release/package, OS, update repository or source tag, build options, loaded modules and effective configuration/data locations. Include databases, endpoint/provisioning dependencies, provider authentication, certificates and external applications. A product such as FreePBX may limit the Asterisk versions it supports.
Use version and installation choices and files/CLI to organise that record. Keep secrets in their protected location; a change ticket needs ownership and recovery references, not passwords.
Review every relevant change boundary
Consult the target release's change log and upgrade notes, plus the boundaries crossed from the starting branch. The official Asterisk 22 upgrade entry points to the release change log. Read actual option/module changes rather than assuming a higher branch number preserves every old behaviour.
Examples to investigate when migrating older systems include removed chan_sip and app_macro support, old queue argument positions, and integration APIs tied to an older schema. Asterisk 21's change notes document removals relevant when crossing that boundary. Treat a conversion tool's output as a candidate configuration that still needs review.
Check applicable published security advisories against the exact target and source of patches. A distribution package revision may differ from an upstream release identifier. Record who supplies future fixes and how to establish that a particular fix is included.
Prepare a consistent recovery set
Preserve configuration, required runtime/user data, database state and the information needed to obtain the previous software environment. Include service ownership, permissions and certificates. Follow backup and restore planning for the data categories.
Do not define rollback as only reinstalling an older executable. A schema or data change can make that insufficient. Describe which parts must be restored together and whether writes during the change need reconciliation. For a managed product, use its supported recovery route.
Plan the service window
| Decision | What to state |
|---|---|
| Traffic handling | How new calls are diverted or held and existing calls are treated |
| Target installation | Exact package/source/product procedure and responsible operator |
| Success checks | Routes, registration, media, features and integrations that must work |
| Rollback trigger | The observed condition or elapsed window that stops the change |
| Recovery owner | Who can restore the previous service and dependencies |
Do not promise active calls survive a restart or failover without evidence for that design. Keep an ordinary authorised test path ready; arrange any emergency-path checks with the service provider rather than placing casual emergency calls.
Read back and compare behaviour
After the upgrade, inspect version, startup errors, modules, endpoints and loaded dialplan. Check both inbound/outbound ordinary calling where relevant, audio, DTMF, voicemail, queues and each required integration. Include a denied route so you know permissions were retained, not merely that a call succeeded.
Record actual results when your operator performs these checks. If the success conditions fail, follow the defined recovery sequence and verify the recovered service independently. Keep the old recovery set until the change is accepted under your retention policy.
Return to Asterisk documentation.