How to plan a PBX migration without uncontrolled downtime

Start with a matrix, not a list of screens#

A PBX is more than users and extensions. A production platform may include tenants, gateways, ring groups, queues, IVR, schedules, recording, voicemail, fax, provisioning, classes of service, emergency numbers, WebRTC and reporting integrations. Two configurations that look similar in a GUI may behave differently in the dialplan.

The migration matrix should have a row for each feature or customer and columns for:

• source state,
• the target-system equivalent,
• migration method,
• test owner,
• acceptance criterion,
• dependencies,
• rollback plan.

This identifies what can move automatically, what needs transformation and what must be redesigned.

Traffic inventory reveals undocumented features#

Alongside configuration, analyse CDRs and traces from a representative period. Look for:

• domestic, international and special-service calls,
• forwarding and transfers,
• backup routes and failover,
• calls to queues, IVR and conferences,
• T.38 and passthrough fax,
• devices registering from unusual networks,
• WebRTC and TURN clients,
• tenant-dependent carrier headers,
• rarely used but critical numbers.

Configuration may contain unused rules, while traffic may reveal features created outside the standard process. Compare both sources.

Separate migration layers#

A safe plan divides the work into layers:

Do not proceed to cutover without knowing who owns each layer and how it will be tested.

Build a parallel environment#

The new PBX should run before production switches. It needs a separate FQDN or controlled host mapping, a test trunk or prefix, media access and a set of test devices.

A parallel environment allows testing of:

• registration over UDP/TCP/TLS/WSS,
• internal and external calls,
• caller ID and PAI,
• forwarding and Diversion,
• IVR, queues, voicemail and recording,
• DTMF, codecs and RTP,
• gateway failover,
• provisioning of specific phone models,
• reports and CDRs.

Test both directions. A working outbound call does not confirm DID routing or behaviour after forwarding.

Data and secrets need a separate plan#

Not everything should be copied one to one. SIP passwords may be stored as hashes that cannot be transferred between platforms. That requires credential rotation and controlled device reprovisioning.

Recordings and voicemail may be large and subject to retention requirements. Decide:

• whether to migrate, archive or leave them read-only,
• how users will access their history,
• how completeness will be confirmed,
• whether file and metadata formats are compatible,
• when the source copy can be deleted.

Gateway, API and SMTP secrets must reach the new system without being placed in a release package or open repository.

DNS and endpoint registrations#

If phones register to an FQDN, lower TTL and inspect the device resolver's behaviour. Some phones resolve DNS only at startup, others at each registration, and some cache the result regardless of TTL.

Cutover strategies include:

• changing the DNS record,
• updating provisioning and restarting in waves,
• using a floating IP or load balancer,
• parallel SRV records with controlled priorities,
• DNS failover with a health check.

Each strategy has a different convergence time. Old and new PBXs may handle registrations simultaneously during transition. Avoid a situation where an incoming call reaches the new system while the phone remains registered only on the old one.

Carrier trunks and change ordering#

A carrier may authorise by IP, credentials or both. Agree allowlist changes in advance when changing the public address. If two addresses can coexist, test the new trunk without disabling the old one.

Verify:

• carrier signalling and media addresses,
• transport and port,
• number formats,
• PAI, From, Diversion and required carrier headers,
• codecs and DTMF,
• timeouts and session timers,
• behaviour for 4xx/5xx and backup routes,
• channel and CPS limits.

Save the test call as a reference trace for comparison after cutover.

Phased migration limits the blast radius#

Choose a representative but non-critical first wave, including different devices and features. After migration, observe at least a full business cycle: office-hours calls, night schedules, reports and backups.

Example waves:

1. a test tenant and technical users,
2. a small customer with standard features,
3. a customer with queues, IVR and forwarding,
4. a customer using WebRTC or MPLS,
5. the largest and most critical environments.

Update the runbook after each wave. If the first tenant reveals a provisioning issue, improve the process before subsequent tenants rather than repeatedly applying a manual workaround.

Cutover runbook#

1. Freeze changes in the old PBX.
2. Export configuration and data for the final time.
3. Import the differences into the new system.
4. Validate consistency: extension, DID, gateway and rule counts.
5. Confirm trunks and media with the carrier.
6. Switch DNS, IP or provisioning.
7. Monitor endpoint registrations.
8. Test incoming and outgoing calls, transfers, DTMF and audio.
9. Confirm CDRs, recordings, voicemail and alerts.
10. Begin the observation period and keep rollback ready.

Record a deadline for reaching the expected registration count. If 40% of devices are active after 15 minutes rather than the expected 90%, a decision is needed instead of unplanned waiting.

Rollback must restore routing and registrations#

Returning is more than reverting DNS. If endpoints received new provisioning or the carrier changed its allowlist, every element must be restored. Prepare:

• previous DNS records and TTLs,
• a copy of provisioning configuration,
• the ability to restart the old PBX,
• the active old trunk or a restoration procedure,
• a way to stop new writes,
• a message for users and the helpdesk.

Define the point of no return. Voicemail migration, password changes or a new data schema can mean rollback needs additional synchronisation.

Stabilisation and evidence after migration#

Compare metrics with the baseline after cutover:

• answer-seizure ratio and failure reasons,
• registration count,
• setup latency,
• codec distribution,
• RTP loss and jitter,
• abandoned queues,
• provisioning and authentication errors,
• CPU, RAM and RTP port use.

Collect good-call examples for the most important scenarios. They become reference material for later incidents.

A PBX migration without uncontrolled downtime is not a promise of absolutely zero seconds of unavailability. It means the duration and scope of risk are known, cutover is measured, and returning remains possible before pressure forces improvisation.