Installation instructions for FreeSWITCH
Introduction
This guide assumes that you have already purchased or ported in a number and are somewhat familiar with the user portal. For the full guide to using the DID Logic Portal, check this article.
Components used
- FreeSWITCH version: 1.10.9
DID Logic regional gateways:
Regional gateway | FQDN | IP Address |
---|---|---|
Primary regional gateway | sip.se.didlogic.net | 5.150.254.205 |
Secondary regional gateway | sip.nl.didlogic.net | 185.118.63.77 |
Note: Carefully select a primary gateway with minimal ping and a failover option.
Configuring SIP Trunk on the DID Logic portal
Creating SIP Account
On the "SIP" tab click "Create account", then
- Configure Device Name (optional). Device names are especially useful when you manage multiple SIP accounts.
- Set password. Remember that strong passwords are a critical element of account security.
- Repeat password.
- Set Caller ID associated with SIP account. Only DIDs purchased through DID Logic will be available on the dropdown list.
- ‘Send inbound didinfo’ option should be enabled when registering a PBX or an SBC. This feature instructs DID Logic gateways to replace the SIP Account number in the SIP URI and ‘To:’ headers with the originally dialed number (DID). This option should be disabled only if you register SIP Phones directly with DID Logic.
Tip. If you prefer to manage Caller IDs locally on FreeSWITCH, please be sure to either inform your account manager or email [email protected] to have this feature enabled on your account (see Configuring Caller ID Passthrough for more details).
Click the Create button to complete the configuration.
Once SIP Account is created, you will see a 5-digit number that you should use as Username to authenticate your SIP device with DID Logic.
Setting up inbound routing
There are 3 options for the inbound call routing:
- SIP device: incoming calls will be routed to the respective SIP account if there is an active registration on any of the DID Logic gateways
- SIP URI (user_part@domain_part): incoming calls will be routed to the specified SIP URI address
- Phone: incoming calls will be forwarded to a PSTN number
Note:
- Multiple destinations can be configured for a single DID to ensure failover or provide call coverage options
- You can choose the preferred call distribution algorithms: ‘sequential’ or ‘ring all’
Go to the Purchased tab and click Edit on the number you want to be routed to a SIP Account.
Select an account and click Add:
Now that your SIP account has been created and the inbound routing set up, you can start configuring your FreeSWITCH.
Configuring SIP Trunk on FreeSWITCH
Registering SIP Account
To receive inbound calls, you must register your SIP Account with one of the regional DID Logic gateways:
Choose a regional gateway that is closer to your location (for the purpose of this guide, it is sip.se.didlogic.net) and configure external SIP profiles:
1. Create a file named didlogic.xml in the directory containing external SIP profiles:
/usr/local/freeswitch/conf/sip_profiles/external/didlogic.xml
<include>
<gateway name="didlogic">
<param name="username" value="39554"/>
<param name="password" value="YOUR_SIP_ACCOUNT_PASSWORD"/>
<param name="realm" value="sip.se.didlogic.net"/>
<param name="register" value="true"/>
<param name="context" value="didlogic"/>
</gateway>
</include>
Note:
- Authentication “realm” value is different for each gateway and equals its hostname
Once you created the file, change ownership so FreeSWITCH can read it:
root@freeswitch:/usr/local/freeswitch/conf/sip_profiles/external/# chown freeswitch:freeswitch didlogic.xml
2. Create the dialplan file named didlogic_dialplan.xml in the dialplan directory:
/usr/local/freeswitch/conf/dialplan/didlogic_dialplan.xml
<?xml version="1.0" encoding="UTF-8"?>
<include>
<context name="didlogic">
<extension name="unloop">
<condition field="$${unroll_loops}" expression="^true$" />
<condition field="${sip_looped_call}" expression="^true$">
<action application="deflect" data="${destination_number}" />
</condition>
</extension>
<extension name="in-didlogic">
<condition field="destination_number" expression="^(61272534418)$">
<action application="bridge" data="user/1000@$${domain}"/>
<action application="hangup"/>
</condition>
</extension>
<extension name="out-didlogic">
<condition field="destination_number" expression="^(\d{10,15})$">
<action application="bridge" data="sofia/gateway/didlogic/$1"/>
<action application="export" data="sip_from_uri=${sip_from_uri}"/>
<action application="hangup"/>
</condition>
</extension>
<extension name="local">
<condition field="destination_number" expression="^\d{4}$">
<action application="answer" />
<action application="sleep" data="1000" />
<action application="bridge" data="user/${destination_number}@$${domain}" />
<action application="hangup" />
</condition>
</extension>
</context>
</include>
Note:
- condition “destination_number” in the section “in-didlogic” contains regular expression matching DID number you have purchased: "^(61272534418)$"
- condition “destination_number” in the section “out-didlogic” contains regular expression matching PSTN numbers you will be calling from FreeSWITCH: "^(\d{10,15})$"
- grant access to the file didlogic_dialplan.xml so FreeSWITCH can read it.
3. Edit configuration file of the internal number assigned to the phone:
root@freeswitch:/usr/local/freeswitch/conf/directory/default# nano 1000.xml
<include>
<user id="1000">
<params>
<param name="password" value="YOUR_EXTENSION_PASSWORD"/>
<param name="vm-password" value="1000"/>
</params>
<variables>
<variable name="toll_allow" value="domestic,international,local"/>
<variable name="accountcode" value="1000"/>
<variable name="user_context" value="didlogic"/>
<variable name="effective_caller_id_name" value="CALLER_ID_NAME"/>
<variable name="effective_caller_id_number" value="61272534418"/>
<variable name="outbound_caller_id_name" value="$${outbound_caller_name}"/>
<variable name="outbound_caller_id_number" value="$${outbound_caller_id}"/>
<variable name="callgroup" value="techsupport"/>
</variables>
</user>
</include>
Note:
- The value of the <variable name="user_context" value="didlogic"/> parameter must match the gateway name you created in the external SIP profile.
4. Set RTP ports parameters to 10000-20000 in the global configuration file switch.conf.xml:
/usr/local/freeswitch/conf/autoload_configs/switch.conf.xml
<param name="rtp-start-port" value="10000"/>
<param name="rtp-end-port" value="20000"/>
5. In order for FreeSWITCH to reread the configuration files, the fs_cli -x reloadxml command should be executed.
6. Once the configuration is completed, you can verify SIP Account registration using the ‘sofia status gateway <gateway-name>’ command in the fs_cli command prompt:
If registration is successful, you will see ‘REGED’ in the “State” column. Please note that if the SIP gateway is not registered, incoming calls will not be routed to your FreeSWITCH.
Configuring Inbound and Outbound calling for IP-authenticated SIP devices
You can enable IP Authentication for your SIP Account. In this case, DID Logic gateways will accept all outbound calls from the specified IP address without further authentication. To setup IP Authentication, please contact support at [email protected] and provide a public IP Address you will be sending outbound calls from.
Note:
- SIP Accounts with IP Authentication enabled cannot be used as the destination assigned to DIDs on the portal. SIP URI addresses must be used instead.
Steps to configure incoming call routing to the SIP URI:
- Log in to you DID Logic account
- Go to the “PURCHASED” tab and click on “Edit”
- Select "SIP URI" from the drop-down list in the “Forward to:“ field
- Enter a valid SIP URI using the following format: +[did]@<Destination>:port;transport=type,
where:
• Destination is the fully qualified domain name or IP address of your FreeSWITCH
• The port is the SIP connection port used by FreeSWITCH
• The type could be either udp, tcp, or tls. The default transport is udp. - Click “Add” to set up the destination for the DID number
For this guide, let's use [email protected]:5060 as SIP URI (in this example, FreeSWITCH's IP Address is 123.123.123.123):
Let's adjust FreeSWITCH settings:
1. Update vars.xml /usr/local/freeswitch/conf/vars.xml:
add the line
<X-PRE-PROCESS cmd="set" data="outbound-sip-ip=123.123.123.123"/>
edit the lines
<XPREPROCESS cmd="stun-set" data="external_rtp_ip=123.123.123.123"/>
<XPREPROCESS cmd="stun-set" data="external_sip_ip=123.123.123.123"/>
2. Uncomment the lines for “ext-rtp-ip” and “ext-sip-ip” in /usr/local/freeswitch/conf/sip_profiles/external.xml and set them as a reference to the variables in vars.xml:
<param name="ext-rtp-ip" value="$${external_rtp_ip}"/>
<param name="ext-sip-ip" value="$${external_sip_ip}"/>
3. Create an external SIP profile
/usr/local/freeswitch/conf/sip_profiles/external/didlogic_ip.xml
<include>
<gateway name="didlogic_ip">
<param name="proxy" value="sip.se.didlogic.net"/>
<param name="register" value="false"/>
<param name="context" value="didlogic_ip"/>
<param name="caller-id-in-from" value="true"/>
<param name="sip_cid_type" value="none"/>
<param name="retry-seconds" value="30"/>
<param name="expire-seconds" value="600"/>
</gateway>
</include>
4. Add the following line to the dialplan file:
<action application="set" data="sip_from_host=${outbound-sip-ip}"/>
and change the content as follows:
<?xml version="1.0" encoding="UTF-8"?>
<include>
<context name="didlogic_ip">
<extension name="unloop">
<condition field="$${unroll_loops}" expression="^true$" />
<condition field="${sip_looped_call}" expression="^true$">
<action application="deflect" data="${destination_number}" />
</condition>
</extension>
<extension name="out-didlogic_ip">
<condition field="destination_number" expression="^(\d{10,15})$">
<action application="set" data="sip_from_host=${outbound-sip-ip}"/>
<action application="bridge" data="sofia/gateway/didlogic/$1"/>
<action application="export" data="sip_from_uri=${sip_from_uri}"/>
<action application="hangup"/>
</condition>
</extension>
<extension name="in-didlogic">
<condition field="destination_number" expression="^(61394607320)$">
<action application="bridge" data="user/1000@$${domain}"/>
<action application="hangup"/>
</condition>
</extension>
<extension name="local">
<condition field="destination_number" expression="^\d{4}$">
<action application="answer" />
<action application="sleep" data="1000" />
<action application="bridge" data="user/${destination_number}@$${domain}" />
<action application="hangup" />
</condition>
</extension>
</context>
</include>
Now outbound calls should work.
Configuring Caller ID Passthrough
When you configure SIP Account settings on the DID Logic portal, you normally assign one of the purchased DID numbers as Caller ID.
If you want to use your own A-numbers and send them directly from FreeSWITCH, you need to contact your account manager or send an email to [email protected] first and request Caller ID passthrough to be activated. Note that this feature may be unavailable depending on individual eligibility.
Once your request is approved and the feature is enabled, you need to remove the Caller ID assigned to your SIP Account to allow Custom Caller ID passthrough.
Updating SIP Account settings
Log in to the DID Logic Portal, go to the SIP section, and click Edit on the SIP Account. Remove Caller ID and click Update:
You should see your SIP Account updated:
Tip. If there is no Caller ID associated with the SIP Account while the Caller ID passthrough is disabled, your outbound calls will be passed over the public network with the Anonymous Caller ID. Anonymous calls tend to be routinely deprioritized and may even be barred by carriers.
Configuring Custom Caller ID on FreeSWITCH
- Update your external SIP profile with new parameters:
/usr/local/freeswitch/conf/sip_profiles/external/didlogic.xml<include>
<gateway name="didlogic">
<param name="username" value="39554"/>
<param name="password" value="YOUR_SIP_ACCOUNT_PASSWORD"/>
<param name="proxy" value="sip.se.didlogic.net"/>
<param name="expire-seconds" value="600"/>
<param name="register" value="true"/>
<param name="retry-seconds" value="30"/>
<param name="context" value="didlogic"/>
<param name="caller-id-in-from" value="true"/>
<param name="sip_cid_type" value="none"/>
</gateway>
</include - You can set Caller ID in the extension configuration file using the option ‘effective_caller_id_number’:
/usr/local/freeswitch/conf/directory/default/1000.xml<include>
<user id="1000">
<params>
<param name="password" value="YOUR_EXTENSION_PASSWORD"/>
<param name="vm-password" value="1000"/>
</params>
<variables>
<variable name="toll_allow" value="domestic,international,local"/>
<variable name="accountcode" value="1000"/>
<variable name="user_context" value="didlogic"/>
<variable name="effective_caller_id_name" value="CALLER_ID_NAME"/>
<variable name="effective_caller_id_number" value="61272534418"/>
<variable name="outbound_caller_id_name" value="$${outbound_caller_name}"/>
<variable name="outbound_caller_id_number" value="$${outbound_caller_id}"/>
<variable name="callgroup" value="techsupport"/>
</variables>
</user>
</include>
Setting up failover routing
To ensure business continuity and safeguard against potential service interruptions, it's crucial to consider SIP Trunk failover scenarios.
This guide offers configuration options for failover mechanisms for both incoming and outgoing calls.
Inbound call failover
To protect against inbound call disruptions, we’ll use dual registrars. First, let’s allow FreeSWITCH to process incoming calls from both regional gateways.
Create failover profile didlogic_fo.xml in the directory containing external SIP profiles
usr/local/freeswitch/conf/sip_profiles/external/didlogic_fo.xml:
<include>
<gateway name="didlogic_fo">
<param name="username" value="39554"/>
<param name="password" value="<YOUR_SIP_ACCOUNT_PASSWORD>"/>
<param name="proxy" value="sip.nl.didlogic.net"/>
<param name="expire-seconds" value="600"/>
<param name="register" value="true"/>
<param name="retry-seconds" value="30"/>
<param name="context" value="didlogic"/>
<param name="caller-id-in-from" value="true"/>
<param name="sip_cid_type" value="none"/>
</gateway>
</include>
Outbound call failover
Update the dialplan configuration for outbound calls by adding the following lines:
<action application="set" data="continue_on_fail=true"/>
<action application="bridge" data="sofia/gateway/didlogic_fo/$1"/>
usr/local/freeswitch/conf/dialplan/didlogic.xml:
<?xml version="1.0" encoding="UTF-8"?>
<include>
<context name="didlogic">
<extension name="unloop">
<condition field="$${unroll_loops}" expression="^true$" />
<condition field="${sip_looped_call}" expression="^true$">
<action application="deflect" data="${destination_number}" />
</condition>
</extension>
<extension name="in-didlogic">
<condition field="destination_number" expression="^(61394607320)$">
<action application="bridge" data="user/1000@$${domain}"/>
<action application="hangup"/>
</condition>
</extension>
<extension name="out-didlogic">
<condition field="destination_number" expression="^(\d{10,15})$">
<action application="bridge" data="sofia/gateway/didlogic/$1"/>
<action application="set" data="continue_on_fail=true"/>
<action application="bridge" data="sofia/gateway/didlogic_fo/$1"/>
<action application="hangup"/>
</condition>
</extension>
</context>
</include>
Common issues
Common issues with outbound calls
- 603 Declined response might be caused by the lack of active registration. Check registrations as outlined below
- another typical reason for the 603 Declined is a call to the destination with the per minute rate higher than the Max rate set for your account. You can find your effective Max rate on the SIP tab. If you would like to have it changed, please contact [email protected]
- incorrect destination number format. Dial full international numbers (E.164): 12125551212 (US), 442085000000 (UK). Dialing 2125551212 won't work. Do not dial with 0, 00, or 011 in front. This guide explains how you can strip the leading digits before the call is routed to DID Logic.
Common issues with inbound calls
- make sure your internal extensions to which incoming calls are forwarded are registered. To check registrations, enter a command “show registrations” in the fs_cli command prompt:
- when FreeSWITCH is behind a firewall, you may experience one-way audio. DID Logic has numerous media gateways across the globe and their IP addresses change occasionally. This is why you should allow RTP traffic originating from any IP with source ports 10000 - 20000 in your firewall configuration.
- if you are experiencing issues with the call setup, we recommend using the sngrep tool to monitor SIP signaling. You can use various filters to drill down into a specific SIP dialog.