Migrating from chan_sip

Migrating from chan_sip

chan_sofia is built to be a drop-in replacement for chan_sip. The public compatibility surface — channel type, realtime family, CLI verbs, AMI actions and dialplan functions — is deliberately preserved, so most systems switch with a two-line change to modules.conf and no dialplan, realtime or AMI rewrite.

This page is the migration checklist. The full feature list is Features; the deep dive is Chan-Sofia.

The swap

chan_sofia and chan_sip are mutually exclusive — both register the SIP channel type and the sippeers realtime family, so exactly one may be loaded.

In modules.conf:

noload => chan_sip.so
load   => chan_sofia.so

Then put the peer configuration in sofia.conf (the parser accepts sip.conf-style [peer] blocks), and restart GABPBX so the active SIP driver changes cleanly.

What carries over unchanged

Surface	chan_sip	chan_sofia
Channel type	SIP/<peer>	SIP/<peer> (tech type SIP, channels/sofia/include/chan_sofia_internal.h:50)
Realtime family	sippeers (+ sipregs)	sippeers (+ sipregs), channels/chan_sofia.c:2921
CLI	sip show peers, sip show peer, sip show registry, sip reload, sip set debug, …	same verbs, channels/sofia/sofia_cli.c
AMI actions	SIPpeers, SIPshowpeer, SIPqualifypeer, SIPshowregistry, SIPnotify	same actions, channels/sofia/sofia_ami.c
Dialplan functions	${SIPPEER()}, ${SIP_HEADER()}, ${SIPCHANINFO()}, ${CHECKSIPDOMAIN()}	same names, channels/chan_sofia.c:5789-6128
Per-peer options	host/context/secret/nat/allow/disallow/directmedia/qualify/…	same vocabulary, channels/chan_sofia.c:2556-2910

Because the channel tech is SIP (not Sofia), every ${CHANNEL(...)} consumer, CDR record and AMI event sees SIP/<peer> exactly as before.

Option notes

• directmedia / canreinvite — both accepted; canreinvite is the legacy alias. Keep directmedia=no until RTP paths are proven.
• transport= — accepted for compatibility on a peer block (channels/chan_sofia.c:2905-2910). The actual transport a phone uses is learned from how it registered.
• nat=force_rport,comedia — the standard setting for NATed phones; drives in-dialog routing to the registered source and overrides the SDP RTP remote with the real source.
• insecure=invite — honored, and overridable by force_invite_auth, which also raises an auditable InsecureInviteBypass AMI event.

DTMF parity

DTMF handling matches chan_sip across every mode, so dtmfmode on a migrated peer behaves as it did before:

• dtmfmode — rfc2833, info, inband and auto are all accepted. auto is resolved at SDP commit: the telephone-event payload is advertised only for RFC 2833 modes, and the negotiated mode is reflected in the channel's RTP DTMF property, so runtime behavior tracks the actual answer rather than the configured default. The DSP reconfigure done for auto is fax-safe (CNG detection is preserved).
• Inbound SIP INFO DTMF is parsed in both the named and numeric Signal forms (for example Signal=10 → *, Signal=11 → #), including Flash.
• SIPDtmfMode() re-syncs the mode mid-call, and AST_OPTION_DIGIT_DETECT is honored — same dialplan behavior as chan_sip.

Per-Contact registration

Registration follows RFC 3261 §10.3 per-Contact, like chan_sip: one AOR can hold several simultaneous bindings (for example a desk phone and a browser), and each Contact binds, refreshes and de-registers independently.

• Each Contact honors its own ;expires; a per-binding expires=0 removes only that binding, and the 200 OK returns each binding's own expiry.
• sip show peer <name> detail reports per-binding state (AVAILABLE / EXPIRED / IN-CALL), which is useful for confirming which contacts are live during cutover.
• A call to a peer whose bindings have all expired returns CHANUNAVAIL instead of routing to a stale binding.

Things chan_sofia adds (you do not have to use them)

These are off by default unless configured, so a straight swap behaves like chan_sip and you adopt the extras when ready:

• SIP Outbound (RFC 5626), Path (RFC 3327), Service-Route (RFC 3608), GRUU.
• Outbound PUBLISH, generic outbound SUBSCRIBE, outbound MWI watcher.
• SHA-256 digest auth, mutual TLS, TLS hardening, the local SIP blacklist.
• WebRTC (DTLS-SRTP + ICE-lite, audio and video) — see WebRTC.
• Per-call SIP history with verbose call analysis.

See Features for each, with its source location.

Migration checklist

1. Move (or write) peer blocks into sofia.conf; the sip.conf per-peer vocabulary loads unchanged.
2. If you use realtime, point the sippeers family at the same table; sipregs is auto-detected if present.
3. Confirm [general] bind ports (bindport, tlsbindport, and for browsers wssbindport) are what you expect — these are baked in at load and a sip reload will refuse a change to them.
4. noload chan_sip.so + load chan_sofia.so and restart GABPBX.
5. Verify with sip show settings, sip show peers, and sip show peer <name> (registrations, contacts, codecs, NAT, call counters).
6. Watch AMI registration and security events during cutover.
7. Adopt the new features (TLS, SRTP, WebRTC, history) once the basic call path is proven.

Production checklist

• Use strong secrets; disable guest calls unless required.
• Set the correct external address and localnet.
• Use nat=force_rport,comedia for NATed phones.
• Keep directmedia=no until RTP paths are proven.
• Set call limits for trunks and shared accounts; disable transfers on untrusted trunks.
• Enable TLS/SRTP/WebRTC only after certificates and endpoint support are verified.
• After editing sofia.conf as root, restore ownership (chown gabpbx:gabpbx /etc/gabpbx/sofia.conf).