FreeSWITCH SIP Trunk Configuration Tutorial: From Installation to Production

1. Installing FreeSWITCH

Ubuntu/Debian Installation

# Add FreeSWITCH repository
wget -O - https://files.freeswitch.org/repo/deb/debian-release/fsstretch-archive-keyring.asc | apt-key add -
echo "deb http://files.freeswitch.org/repo/deb/debian-release/ `lsb_release -sc` main" > /etc/apt/sources.list.d/freeswitch.list
apt-get update

# Install FreeSWITCH
apt-get install -y freeswitch-meta-all

CentOS/RHEL Installation

yum install -y https://files.freeswitch.org/repo/yum/centos-release/freeswitch-release-repo-0-1.noarch.rpm
yum install -y freeswitch-config-vanilla

2. Configuring SIP Gateway (Using Cainiao Voice as Example)

Create a Gateway configuration file:

<!-- /etc/freeswitch/sip_profiles/external/cainiao.xml -->
<include>
  <gateway name="cainiao-voice">
    <!-- SIP server address -->
    <param name="realm" value="sip.cainiaovoice.com"/>
    <param name="username" value="your_account"/>
    <param name="password" value="your_password"/>

    <!-- Registration settings -->
    <param name="register" value="true"/>
    <param name="register-transport" value="udp"/>
    <param name="retry-seconds" value="30"/>
    <param name="ping-interval" value="30"/>

    <!-- Caller ID settings -->
    <param name="caller-id-in-from" value="true"/>
    <param name="extension" value="your_did_number"/>
  </gateway>
</include>

For IP whitelist mode (no registration required), use the following configuration:

<include>
  <gateway name="cainiao-ipauth">
    <param name="realm" value="sip.cainiaovoice.com"/>
    <param name="register" value="false"/>
    <param name="caller-id-in-from" value="true"/>
  </gateway>
</include>

3. Codec Configuration

Edit the SIP Profile codec settings:

<!-- /etc/freeswitch/vars.xml -->
<X-PRE-PROCESS cmd="set" data="global_codec_prefs=G722,PCMU,PCMA,G729"/>
<X-PRE-PROCESS cmd="set" data="outbound_codec_prefs=PCMU,PCMA,G729"/>

4. Dialplan Configuration (Outbound Routing)

<!-- /etc/freeswitch/dialplan/default.xml -->
<extension name="international-outbound">
  <condition field="destination_number" expression="^(011\d+|00\d+|\+\d+)$">
    <!-- Set caller ID -->
    <action application="set" data="effective_caller_id_number=your_did_number"/>
    <action application="set" data="effective_caller_id_name=YourCompany"/>
    <!-- Bridge outbound through Cainiao Voice gateway -->
    <action application="bridge" data="sofia/gateway/cainiao-voice/$1"/>
  </condition>
</extension>

<!-- Route by country -->
<extension name="route-us">
  <condition field="destination_number" expression="^(\+1\d{10})$">
    <action application="set" data="effective_caller_id_number=1XXXXXXXXXX"/>
    <action application="bridge" data="sofia/gateway/cainiao-voice/$1"/>
  </condition>
</extension>

5. NAT Traversal

If FreeSWITCH is behind NAT (common with cloud servers), configure the following:

<!-- /etc/freeswitch/autoload_configs/switch.conf.xml -->
<param name="rtp-ip" value="YOUR_PUBLIC_IP"/>
<param name="sip-ip" value="YOUR_PUBLIC_IP"/>
<param name="ext-rtp-ip" value="YOUR_PUBLIC_IP"/>
<param name="ext-sip-ip" value="YOUR_PUBLIC_IP"/>
<param name="rtp-timeout-sec" value="300"/>
<param name="rtp-hold-timeout-sec" value="1800"/>

6. Security Hardening

• ACL Restrictions: Only allow IP addresses from your SIP trunk provider
• Strong Passwords: Gateway passwords should be at least 16 random characters
• Firewall: Only open ports 5060/5061 (SIP) and the RTP port range
• fail2ban: Automatically block suspicious IP addresses
• Disable Unused Services: Disable unnecessary SIP Profiles

7. Monitoring and Operations

• fs_cli: FreeSWITCH command-line console
• ESL (Event Socket Library): Programmatic monitoring and control
• CDR: Configure CDR output to database or files
• show channels: View current call status
• sofia status: View Gateway registration status

# Common operations commands
fs_cli -x "sofia status profile external"     # View SIP Profile status
fs_cli -x "sofia status gateway cainiao-voice" # View gateway registration status
fs_cli -x "show channels count"                # View current concurrent calls
fs_cli -x "reloadxml"                          # Reload config (no call interruption)

8. Common Issue Troubleshooting