Carriers

Moving a VICIdial carrier from chan_sip to PJSIP

How to rewrite a chan_sip carrier as PJSIP in VICIdial, for login-based and IP-based trunks, with the ViciBox 12 port trap and a cutover you can undo.

By Published Updated 6 min read
Telecommunication tower with satellite dishes under a cloudy sky

To the point

Asterisk 21 and later ship without chan_sip, so a VICIdial carrier written for chan_sip has to become PJSIP before the server can move to a current Asterisk. On ViciBox 12 both stacks run side by side, which makes it the safe place to convert one carrier at a time.

  • One chan_sip section becomes three or four PJSIP sections: endpoint, aor, then auth and registration for a login, or identify for an IP trunk.
  • In VICIdial, set Protocol to PJSIP and change Dial(SIP/…) to Dial(PJSIP/…). PJSIP ignores the Registration String field.
  • On ViciBox 12, chan_sip holds UDP 5060 and PJSIP listens on 5061. An IP-based carrier has to send to 5061 after the move.
  • Copy the carrier, give the copy its own dial prefix, and keep the original until the copy has carried real calls.

Why now

chan_sip was marked deprecated in Asterisk 17 and removed in Asterisk 21. On our Ubuntu test build with Asterisk 22, chan_sip is not loaded at all: a carrier saved with Protocol SIP is written into a file that nothing reads, so it never exists.

ViciBox 12 is different. Our test server runs Asterisk 18.26.1-vici with both chan_sip.so (listed as deprecated) and res_pjsip.so running. Phones and old carriers keep working on chan_sip while you move carriers across, which is exactly the window you want.

Login-based or IP-based?

Your carrier works one of two ways, and the PJSIP version differs:

  • Login-based: the carrier gives you a username, a password and a host. Your server registers, and every call proves who it is.
  • IP-based: the carrier allows your server's public address. No password. Calls from their address are trusted.

If you are not sure which you have, look at the chan_sip carrier: a register => line in Registration String means login-based.

What each chan_sip line becomes

chan_sipPJSIP
type=peertype=endpoint, plus an aor
host=sip.example-carrier.comaor contact=sip:sip.example-carrier.com:5060
username and secrettype=auth with username and password
register => user:pass@hosttype=registration with server_uri, client_uri, outbound_auth
insecure=port,invitetype=identify with match= the carrier's address
qualify=yesaor qualify_frequency=30
dtmfmode=rfc2833dtmf_mode=rfc4733
nat=force_rport,comediaforce_rport, rtp_symmetric, rewrite_contact
Dial(SIP/${EXTEN:2}@ID…)Dial(PJSIP/${EXTEN:2}@ID…)

Set it up, step by step

These are real screens from our test server. The four demo carriers use an example host and a documentation-only address, and none of them is active.

In VICIdial's admin

VICIdial carrier list with Copy A Carrier and two demo carriers highlighted
Admin, Carriers: start from a copy of the chan_sip carrier
  1. Copy A Carrier: start from the chan_sip carrier, so the name, server and dialplan come along. Give the copy a new ID.
  2. SUN_SIP_REG: the chan_sip original. Leave it alone for now.
  3. SUN_PJ_REG: the PJSIP copy. VICIdial saves every new carrier as inactive.
The chan_sip carrier with Registration String, Account Entry, Protocol and Dialplan Entry highlighted
Before: a login-based chan_sip carrier
  1. Registration String: register => user:password@host is what logs chan_sip in.
  2. Account Entry: one type=peer section with the host, the login and the codecs.
  3. Protocol: SIP, so VICIdial writes it into sip-vicidial.conf.
  4. Dialplan Entry: Dial(SIP/…@SUN_SIP_REG) sends calls with prefix 72 through it.
The PJSIP copy with Registration String, Account Entry, Protocol, Dialplan Entry and Active highlighted
After: the same carrier as PJSIP, on its own prefix
  1. Registration String: leave it empty. PJSIP ignores it; the registration now lives in the account entry.
  2. Account Entry: four sections named after the carrier: registration, auth, aor and endpoint.
  3. Protocol: PJSIP.
  4. Dialplan Entry: PJSIP/ in place of SIP/, on prefix 73 so both carriers can exist at once.
  5. Active: set Y when you are ready to test. VICIdial writes the files on its next minute run; we measured 27 and 39 seconds until Asterisk had the carrier, so allow about a minute.
An IP-based PJSIP carrier with Account Entry and Protocol highlighted
An IP-based carrier: aor, identify and endpoint, no password
  1. Account Entry: aor, identify and endpoint. No auth and no registration: identify with match= tells Asterisk which incoming calls belong to this carrier.
  2. Protocol: PJSIP.

In the Trustane console

Trustane console Tools, Diagnostics, with the Carrier registrations check highlighted
Tools, then Diagnostics
  1. Carrier registrations: one check that reads both stacks, sip show registry and pjsip show registrations, so a carrier mid-move shows up on whichever side it is.
Trustane console campaign settings with the dial prefixes and their carrier check highlighted
Campaigns, the campaign, Set Up, then Trunk / routing
  1. Campaign dial prefix: the console lists the carriers whose dialplan matches the prefix and warns when no active carrier does, as here. Manual and 3-way calls have their own prefix beside it.

Carrier setup itself is done in VICIdial's admin, as above.

A cutover you can undo

Five steps from copying the carrier to moving the campaigns, with the old carrier kept
Move one carrier at a time

Move campaigns off the old prefix before you switch the old carrier off. In our tests a route that still pointed at a deactivated carrier kept dialing it and failed with CHANUNAVAIL.

Check it worked

asterisk -rx "pjsip show registrations"
asterisk -rx "pjsip show endpoints"
asterisk -rx "pjsip show contacts"
asterisk -rx "sip show registry"

A login carrier should show Registered. An IP carrier should show its contact as Avail once qualify gets an answer. Then place one call through the new prefix and one inbound call to a DID on that carrier.

Questions people ask

Can I convert every carrier at once?

You can, but on ViciBox 12 there is no reason to. Both stacks run, so one carrier at a time always leaves a working way back.

Is there a converter script?

Asterisk ships sip_to_pjsip.py in its contrib scripts. It covers common cases. Read what it writes before you paste it into Account Entry: VICIdial copies that box into the PJSIP file exactly as typed.

Do the phones have to move too?

Not for this. On ViciBox 12 the stock phones use chan_sip and can stay there. They move only when the server moves to an Asterisk without chan_sip.

Next steps

For the full PJSIP definitions and how VICIdial renders them, see setting up a PJSIP carrier. For which SIP answers should send a call to a second carrier, see carrier down or bad number, and to see which carrier took a call, which carrier carried a call. When you want a server that is already on PJSIP, order one, or move your current dialer.

VICIdial is a trademark of its owner. Trustane is an independent hosting provider.

Trustane

Managed VICIdial hosting

Run it on cores of your own

Managed VICIdial, billed by the hour against a balance you top up.

Or try one server free for 7 days, no top-up.