Skip to main content

Converting Asterisk to FreeSWITCH


This document is an effort to help with the roadbumps that come up in the conversion from Asterisk to FreeSWITCH™.

Click here to expand Table of Contents


If you've been involved in open source VoIP and are now looking into FreeSWITCH, chances are you came from a background in Asterisk. In some ways, this is actually a handicap compared to discovering FreeSWITCH first, because you have to, in a sense, unlearn 'the Asterisk way'. FreeSWITCH works differently, and it can be somewhat frustrating to rebuild a telephony system in FreeSWITCH that was originally built in Asterisk. This document is an effort to help with the roadbumps that come up in the conversion. It is far from comprehensive, but instead a place to hold the various tricks and lessons that people learn in the process. The time spent reviewing these pointers will almost assuredly pay off in time saved from beating your head off a wall, saying "I know how to do this in Asterisk, but..."


  • SIP is the assumed protocol
  • Not all implementation methods are necessarily discussed in each section. More focus is put on clarifying the most common methods.

Setting global variables


Global variables are usually set in extensions.conf.


  • In conf/vars.xml -- the default config has examples of how to do it
  • In any other XML file included in the XML diaplan -- nice if you have some need to group the variable definitions
  • In a script called by the dialplan -- for example, in a Lua script you would use a global_setvar call via the freeswitch.API() object
  • via the event socket -- using global_setvar via an API command

SIP configuration


A single SIP profile is configured via sip.conf, which stores basic SIP configuration parameters, registrations to gateways, and credentials and configuration for SIP endpoints registering to the server.


Multiple SIP profiles can be configured -- in fact, it's encouraged. By default, FreeSWITCH includes all profiles defined in conf/sip_profiles, and each profile runs independently on it's own IP:port, and can have it's own settings, gateways, etc.

Defining new profiles

Create an XML definition in conf/sip_profiles with a .xml extension -- check the existing examples in conf/sip_profiles for the layout.

Defining gateways

For the default internal and external profiles, drop a gateway configuration file with a .xml extension in either conf/sip_profiles/internal or conf/sip_profiles/external. Check the SIP Provider Examples for the format of the file -- it lists example configurations for most of the common providers.

Defining users

Create an XML definition in conf/directory with a .xml extension -- check the existing examples in conf/directory for the layout.

Routing incoming calls


Incoming calls are pointed to contexts in sip.conf, via a default context or the user configurations.

Extensions are defined using a custom pattern method, and the call is routed to the extension that matches a defined pattern.


Incoming calls can be routed per SIP profile, via the 'context' setting in the profile settings or in the gateway settings, or via the 'user_context' setting in the user settings.

Extensions are commonly defined via XML, matching against one or more conditions via Perl regular expressions. Multiple actions can be taken based on a matching or non-matching condition.

See Also