This document provides an overview for configuring the Sangoma Session Border Controller (SBC) with the Sipxcom High Availability (HA) configuration. The following telephony features have been lab-tested with this configuration:

This document assumes working knowledge of Sipxcom HA, the Sangoma SBC, SIP, basic Freeswitch concepts, and regex expressions.

Step 1 - Plan Your SBC Configuration

Per the above reference diagram, the Sangoma SBC sits behind Pfsense  in a private network. Given that the Pfsense firewall protects the private network from malicious public Internet traffic, the SBC firewall was turned off. The Sangoma SBC has several high availability and clustering settings - those settings were not tested or validated with the Sipxcom HA configuration.

Sipxcom 18.04 and Sangoma NSC  2.3.19-102 releases were used in the lab testing. The Sipxcom HA cluster has 3 servers - one primary and two secondary servers; it also uses the SIP realm  for failover. The Sipxcom default DNS settings were used during testing where phone registrations are spread evenly across all three servers in the HA cluster. The user extensions for the lab phones are 11-digit extensions (North American Dialplan) with 4 digit aliases that facilitates least-cost PSTN routing.For transfer testing, the Mongo Registrar was queried to ascertain successful call transfers through the SBC occurred to internal phones registered to different HA servers.

For incoming external calls that use DISA or calls that are transferred back out to the PSTN via a Polycom phone (e.g. cell phone), the SBC dialplan facing the Internet Telephony Service provider(ITSP) must distinguish between a call transfer going out to the PSTN versus a call being transferred to another user extension within Sipxcom (remember that the Sipxcom user extensions are 11 digits). When the SIP REFER is received as a result of a DISA call or call transfer, Sipxcom issues a REFER back out to the SBC. The SBC looks at the 11-digit number in the REFER-TO header - if the number begins with 1914417xxxx then the subsequent INVITE is sent back to the PBX.

In the SBC, the ITSPtoSBC SIP Profile is first defined for incoming external calls that assigns the 5062 port number that the profile will act upon. This profile is then linked to the ITSPTrunk SIP trunk which defines the far endpoint of the trunk, and optionally, whether the SIP trunk is registered along with registration credentials. Finally the ITSPRoute dialplan is defined and mapped to the profile that determines how the incoming call will be routed. There is the SBCtoPBX SIP profile, SBCtoPBX trunk, and PBXRoute dialplan with port 5063 that processes incoming  calls from Sipxcom. 

This wiki page provides good guidance on building dialplans using the Sangoma SBC It is important to understand how the SBC processes REFERs. If an incoming external call arrives at the SBC, is routed to Sipxcom, and is then call-transferred, the REFER coming back from Sipxcom is processed by the ITSPtoSBC SIP profile and corresponding ITSPRoute dialplan, as that is where the original call is anchored. Likewise if a Sipxcom user placed an external call to the ITSP and the call is transferred, the incoming REFER to the SBC is processed by the SBCtoPBX Profile and PBXRoute dialplan as that is where the original call is anchored.

Step 2 - Set Port Forward and Outbound NAT on Pfsense

The Internet Telephony Service Provider used for Sipxcom HA and Sangoma SBC interoperability testing has its servers in the class C sub-network range. For incoming traffic from the ITSP, Pfsense must be configured to allow all incoming traffic from this subnetwork destined for the public IP address of 108.xx.yy.zzz with the port ranges of 5062-65535 to be forwarded to the SBC in the private network with the IP address of It should be noted that the Pfsense WAN interface supports multiple public IP addresses and by leveraging the Pfsense Virtual IP address feature, the 108.xx.yy.zzz address has been reserved for SBC traffic.

For outbound traffic from the SBC to the ITSP, Pfsense must be programmed to NAT outgoing traffic from to the public IP address reserved for SBC traffic - this is done via a mapping entry on the Psense Firewall->NAT->Outbound menu. 

Step 3 - Sipxcom Configuration to Support SBC

The key configuration changes to support the SBC are in the following areas:

Create an Unmanaged Gateway

Create an unmanaged gateway to the SBC at using TCP transport and port 5063.

Assign the SBC Unmanaged Gateway to Dial Plan

Assign the SBC unmanaged gateway to the appropriate dial plans such as the Long Distance Dialplan.

NAT Traversal Settings

In the System -> Nat Traversal Settings menus, disable the Enable NAT Traversal and Server Behind NAT options. Also change Address Type to Specify IP address and provision the Public IP address with the IP address of the SipXcom primary voice server. Repeat this step for each of the secondary servers ( and

Change Firewall Settings for SAA/BLA

By default, the firewall settings to allow 5170 traffic from the phones to Sipxcom are disabled - this is used by bridge line appearance (BLA) lines on Sipxcom. Go to the System->Firewall menu and change the SAA/BLA TCP and UDP firewall settings from CLUSTER to PUBLIC. This change allows BLA to work on shared lines using Polycom phones in order to perform interoperability testing with the Sangoma SBC.

Step 4 - Configuring the Sangoma SBC

The Vmware version of the Sangoma SBC was used for this interoperability testing work and assumes the SBC has already been installed and operational. The changes to support Sipxcom HA include:

Pointing the SBC DNS Addresses at Sipxcom HA Servers

Go to the Configuration->IP Settings->Network menu on the SBC and validate the IP Address assigned to the Eth0 interface and default gateway from the installation. Point the SBC DNS addresses to the three Sipxcom HA servers.

Create G.711 Media Profile for the ITSP

The ITSP used for interoperability testing with the PSTN only supports G.711 codecs. Go into the Configuration->Media->Media Profiles menu of the SBC and create an ITSP profile that only supports PCMU and PCMA codecs.The aceprofile will be assigned to the ITSP and PBX SIP profiles of the SBC.

Build the SIP Profiles

From the planning diagram in step 1, there are two SIP Profiles required:

These two profiles are first created so that they can then be linked to the SIP trunks. The SIP profiles will then be updated after the corresponding Call Routing dialplans have been created.

Create the ITSPtoSBC profile using the default SBC profile settings except for the following fields:

Create the SBCtoPBX profile using the default SBC profile settings except for the following fields:

Build the SIP Trunks

From the planning diagram in Step 1, there are two SIP trunks to be configured on the SBC:

The SBC must be stopped prior to building the SIP Trunks and assigning the SIP Profile to the Trunk. The following configuration parameters are defined on the ITSPTrunk SIP Trunk:

Step 6 - Build the SBC Dialplans

Building the Call Routing Dialplans is an iterative process - for the lab system defined in step 1, two dialplans are defined:

Go to the Configuration->Call Routing menu and build these two dialplans.


Once the call routing dialplans have been defined, they need to be mapped to the correct SIP profile as follows:

Once these configurations are applied to the SBC, the rules for each dialplan can be defined and tested.

Before working through the details of the call routing dialplan rules, some simple call flow examples will provide clarity on the dialplan logic. Let's start with an incoming external call to 914-417-2292 (see architecture diagram in step 1), which is a Polycom phone behind Sipxcom. Because the call originated from the ITSP, the SBC processes the call using the ITSPtoSBC SIP Profile and corresponding ITSPRoute dialplan. The 19144172292 user answers the call and transfers the call to 2293 (which is an alias of 19144172293). To complete the transfer, Sipxcom issues a SIP REFER back to the SBC. Because the call being transferred originated from the ITSP, the ITSPRoute dialplan will process the REFER even though the REFER came from Sipxcom. The REFER from Sipxcom will have a Refer-To: header that begins with;user=phone; the SBC dialplan regex must parse this header, look at the 2293 destination address, and instruct the SBC to send an INVITE to back to Sipxcom in order to complete the call transfer.

Let's use the same call flow but instead of transferring the call to 2293, the 19144172292 user transfers the call to the full 11-digit extension 19144172293. The REFER from Sipxcom will have a Refer-To: header that begins with;user=phone; - the ITSPRoute dialplan must have a rule defined that sends the SIP INVITE for 19144172293 back to Sipxcom and not to the ITSP.

The Sipxcom 19144172292 user places an external call to the ITSP - because the call originated from Sipxcom,the  SBCtoPBX SIP Profile and corresponding PBXRoute dialplan  on the SBC processes the call. When the 19144172292 user transfers the call to 19144172293 or its 2293 alias, the REFER that is sent to the SBC is handled by the SBCtoPBX SIP profile and PBXRoute dialplan as the original outgoing call is anchored to this path. The PBXRoute dialplan must have dialplan rules that correctly routes calls for 1914417xxxx and 4-digit aliases back to Sipxcom.

Final example - Sipxcom user 19144172292 has a call forwarding rule that forwards incoming calls to 16465551212 after 1 secondAn external ITSP 9145551212 caller places a call to 19144172292. Sipxcom after 1 second sends an INVITE back to the SBC with a Request-line URI of INVITE sip:16465551212@ but the SIP TO: header has the original URI. Almost all SIP INVITES have Request-line URIs that are identical to the TO: header URI. However when call forwards are initiated by Sipxcom due to a call forwarding rule, the telephone numbers in the R-URI header and To: headers are different - the SBC must account for this when a call forwarding rule is applied to a Sipxcom user.

The Call Routing dialplan rules for both the ITSPRoute and PBXRoute dialplans are identical except for dialplan rule 9. In the following dialplan rule illustration, rule number 4 is a best practice and checks that SIP signaling comes from either the Sipxcom high availability servers or the ITSP - if not, processing stops with a SIP 405 error message and further dialplan processing terminates. 

Dialplan rules 5 through 8 handle REFER processing - let's start with dialplan rule 5. In the dialplan assumptions documented in the architecture diagram in step 1, Sipxcom users are 11 digits and follow the North American telephone numbering plan. The numbering plan also assumes that 9144170000-9144179999 are assigned to Sipxcom users. If an external caller dialed 19144172292, the Sipxcom user answered the call, and then transferred the call to 19144172294, the REFER back to the SBC from Sipxcom would have Refer-To header of The regex in dialplan rule 5 checks whether the cialing number is 11 digits and begins with 1914417 - if it does, the regex populates the $1 variable with the called number and then sends the subsequent INVITE to Sipxcom.

Dialplan rules 6 and 7 go together and are a workaround to regex processing on the Sangoma SBC where some statements with multiple brackets fails to populate the $1 variable. In dialplan rule number 6, a check is made on whether the incoming packet is a SIP REFER packet - if so, the REFER-TO variable is populated with the contents of the $1 variable containing the called telephone number. The regex in dialplan 7 checks whether the called number in the Refer-To: header is an 11 digit long-distance number or international call beginning with 011 - if so, then the subsequent INVITE is sent to the ITSP using the REFER-TO variable.

Dialplan plan rule 8 covers the case of a REFER containing any other called number - e.g. user 19144172292 transfers the call to alias 2294. The regex in this dialplan takes the the called number populated in the $1 variable and sends the INVITE to Sipxcom.

Note that dialplan processing stops for REFER dialplan rules 5, 7, and 8 if the matching condition was successful. 

Further guidance on how to bridge REFERs with SIP Trunks is found here document provides useful regex examples for the Sangoma SBC

The final dialplan rule 9 forwards an incoming call from the ITSP to the Sipxcom PBX, and vice-versa. In the ITSPRoute dialplan rule (illustrated), the called number is custom bridged to the PBXTrunk  which connects to Sipxcom. For an incoming call from Sipxcom to the ITSP, the PBXRoute dialplan would custom bridge the call to the ITSPTrunk in rule 9. Note that in the conditional query for the SIP INVITE packet, the request-line URI is queried and populated in the $1 variable by the underlying regex..

Step 7 - Test Your SBC Configuration

Session Border controllers, and dialplan configurations (regex plans in particular) are detailed - a simple misspelling or an errant forward-slash in a trunk bridging operation can be problematic to trouble-shoot. In putting together this document, the following tests were performed to validate the configuration:

The primary Sipxcom server in the high availability cluster was powered off, and the above tests were repeated. The tests using DISA (Authorization codes) and bridged line appearance failed as these features are only available when the primary server is operational - all other calls were successfully completed.