Skip to main content



You've heard of Cliff's Notes? These are mine on FreeSWITCH ("FS").

I'm Mike, a telephony newbie living near Washington, D.C., and often A.K.A. zoiks or MikesNotes on freenode's IRC #freeswitch. These are my Notes, learned and earned slowly and painfully with lots of bumps and bruises from braving technology's endless learning curves. Like Unix/Linux/GNU, FS is a great platform with a steep learning curve that pays off grandly over time. Embrace it. Love it. Lots of nice, smart people have helped me. Maybe the following info will help you. Read on.

HELP -- the best way I found to get help, often directly from the top developers themselves, was to install Opera browser and use its built-in IRC client ("chat") to connect to and enter the channel "#freeswitch" (i.e., "/join #freeswitch"). FS is fast moving target; if you're not on IRC you may as well give up.

Update 2011-12-23 -- Ditched Opera browser in favor of HYDRA IRC on windows.

Click here to expand Table of Contents

My subpages

Subpages can be created under User profiles, by adding slash pagename, like so: [ [ User:username/subpage_name ] ]

Here are mine:

  • Archived pages take on setting up FS to support multiple companies, multiple domains, multiple tenants, whatever you want to call it. MultipleCompanies MultipleTenants

FS Console / Reload config

How do you cause FS to reload its config? In the FS console, should you use 'reloadxml' or 'fsctl shutdown restart' or something else?

2009-06-19 reloadxml causes FS to reload the xml registry. However, not everything loaded or running will notice right away, if ever. Some modules read the xml registry often; others read it only once at startup or invocation.

MC: It depends on exactly what you're doing. For example, if you want to restart a gateway or a profile then use "sofia profile <profile_name> restart <reloadxml>" - the reloadxml is optional but if you've made a change somewhere in a profile or a gateway on a profile then the reloadxml is a shortcut to keep you from having to reloadxml and then sofia profile <profile_name> restart

Multiple Extensions in Multiple Companies ("multiple domains" and "multi-tenant")

Oh so many names (!) that mean the same thing: get FS to support many companies, many extensions, many domains, all independently, as if we're a VoIP provider... My take on this is at Multiple Companies

FS of course can provide service to any number of extensions in any number of companies. As of FS 1.0.4 (2009-09), the stock install requires adjustment to make it all work. 2009-09-29: User "diegoviola" (on channel #freeswitch on freenode IRC) was kind enough to share his knowledge, experience and config files necessary to make one FS server support both extensions 1000 and 1001 in two separate companies, and, along with two distinct dialplans, one for each company. Read it here: Multiple Companies

Strange problems caused by having a multiple-tenant Domain name set to the Default Domain

You'd think this would be self-evident. But you'd also think that FS would throw an error or at least a warning ...or something. Instead, it just doesn't work, silently, angrily, it stews and fails in strange ways.

Near the top of the file conf/vars.xml, is something like this line, depending upon how much you've mucked around with the file:

<X-PRE-PROCESS cmd="set" data=""/>

At some point in time, I'd set it to "" and everything had been working fine in default mode, so I'd forgotten about it.

However, in trying to get multiple-tenant hosting working, I'd added "" as one of the multiple tenants. Problem was it already existed as the Default (domain) name.

I haven't tried changing the Default (domain) name back to "default" and then also adding a multiple-tenant Domain named "default". I wonder if it would all break in the same strange ways?

The Logging Problem

FS comes with dozens of config files, a "loading tree" whose root is conf/freeswitch.xml. Those dozens of config files are all parsed into one huge config file that is stored at (and memory-mapped from) conf/log/freeswitch.xml.fsxml. Any error messages displayed on the FS console refer to the line number in this single, huge, built-on-the-fly master config file. Don't change the file when FS is running, however, because some or all of it is memory-mapped into FS, or so I read somewhere in the dogcs, uh docs.

Great Providers

Creating technology from the bottom up (circuit design level) but with little tolerance for it, I can come across as harsh and acerbic. Everything's a proverbial trade-off...there are faults everywhere, most often. When I say something is good, that means my experience has been great.Flowroute is a good SIP provider. Fast, smart, consistent, zero problems, great web interface, excellent technology and service. Top drawer.

It's been two years now with FlowRoute. I use them for everything, never any reason to look elsewhere. Excellent.


See Provider_Configuration:OneSuite offers several incoming phone numbers, but all incoming calls arrive as if coming from one account name -- there is no way to see (on the FS box) which phone number the remote caller originally called because all incoming calls arrive from onesuite as if coming from the single master account name (it's not even a number!). There are no numbers, no way to discern what number was originally dialed. That's pretty much inexcusably absurd. Too bad it's honestly faster and easier to have your teeth pulled than to wrench "portable" phone numbers from the grip of these evil clowns. I can't get away from them fast enough!

jaybinks__ on #freeswitch channel of freenode IRC helped me understand how to see all info passed by a sip provider during incoming calls:

In conf/dialplan/public/onesuite.xml, add the line <action application="info" />. This causes the FS console to display all incoming variables and info presented by the incoming SIP provider. Very useful!

My file looks like:

<extension name="in.2025551212">
<condition field="destination_number" expression="^(UserName00713\-voip\.onesuite\.com)$">
<action application="set" data=""/>
<action application="set" data=""/>
<action application="info" />
<action application="transfer" data="1521 XML"/>

Upping the logging of sip providers in the FS console (via sofia loglevel all 7) reveals a huge amount of junk traffic from onesuite. I don't know what it all is, but it's just nearly constant chatter...MD5 registrations every ten seconds or so, lots of "nta" and "nua" lines... Meanwhile, not a peep about the several working lines (on the same FS server) coming from my favorite sip provider FLOWROUTE.COM. Sorry to sound harsh, but, hey, I call it like it looks.

2009-10-02: Discovered that my recent spate of hard lockups (FS 1.0.4) was most likely being caused by all the chatter from! I'll email my conf/sip_profile/external/ to any curious developers.

VoIP Phones

20009-10: SPA942, 3102, GXP2000 Linksys / cisco SPA942 has good industrial design. If you disable as many of its internal features as possible and put all the smarts on the server then the phone is decent. In two years or so my (then $250+ but now $130) SPA942 has presented all kinds of goofiness, including bizarre failures (and ultimately success) at upgrading to latest 6.1.5a firmware. I've had better experience with the $80 Linksys / cisco 3102 (a glorified ATA), except that it seems to only support one SIP account. The new $85 Grandstream GXP2000 is bare-bones and has some bizarre quirks, not the least of which is how its SIP password fields appear to be blank despite being filled out. All in all, I'd get another $130 SPA942 and disable everything, leaving all smarts to FS. YMMV.

Digium TDM400P analog 4port FXO/FXS interface

My experiences in setting up Digium's TDM400P analog 4-port card (2 FXS ports, 2 FXO ports). Thanks to Moc on's #freeswitch channel, 2009-10-08.

From the top of the card down towards the motherboard connector, the ports are 1, 2, 3, 4. My card has two green subcards in positions 1 and 2, and two red subcards in positions 3 and 4.

Green is an FXS, which connects to desk phones. Red is an FXO, which connects to phone lines, i.e., phone office.

Digium software / drivers

-2. Get and install latest "dahdi" drivers from site (version 2.2.0). Install both the dadhi-linux kernel drivers and also the dadhi-tools kit. Install both and test. All four green LEDs should light up when everything is working. A linux reboot, of course, is not required!

-1. Edit freeswitch-1.0.4/modules.conf to uncomment the line:

  1. ../../libs/openzap/mod_openzap

(i.e., remove the leading "#") This causes the necessary openzap module to be compiled. Recompile FS.

FS needs several config files added and/or changed:


0. This wiki is very good: Configuration_OpenZAP-_DigiumTDM400P_Example#Zaptel_Driver_Installation. Note the configuration changes suggested to the /etc/zaptel.conf file, mine is this:

loadzone = us
defaultzone = us


Note that the wiki covers zt-1.4 drivers and tools, but I installed the latest drivers and tools, which digium has renamed to "dahdi-linux" and "dahdi-tools" (version 2.2.0).


1. Per Openzap.conf_Examples, create conf/openzap.conf and add this:

[span zt FXS1]
name => OpenZAP-FXS
number => 1
fxs-channel => 1

[span zt FXS2]
name => OpenZAP-FXS
number => 2
fxs-channel => 2

[span zt FXO1]
name => OpenZAP-FXO1
number => 3
fxo-channel => 3

[span zt FXO2]
name => OpenZAP-FXO2
number => 4
fxo-channel => 4


2. Per Openzap.conf.xml_Examples, create conf/autoload_configs/openzap.conf.xml and add this:

<configuration name="openzap.conf" description="OpenZAP Configuration">
<param name="debug" value="9"/>
<span id="1">
<param name="tonegroup" value="us"/>
<param name="digit-timeout" value="2000"/>
<param name="max-digits" value="11"/>
<param name="dialplan" value="XML"/>
<param name="context" value="default"/>
<param name="enable-analog-option" value="3-way"/>
<param name="moh" value="$${base_dir}/sounds/Dardedisco.wav"/>
<span id="2">
<param name="tonegroup" value="us"/>
<param name="digit-timeout" value="2000"/>
<param name="max-digits" value="11"/>
<param name="dialplan" value="XML"/>
<param name="context" value="default"/>
<param name="enable-analog-option" value="3-way"/>
<param name="moh" value="$${base_dir}/sounds/Dardedisco.wav"/>
<span id="3">
<param name="tonegroup" value="us"/>
<param name="digit-timeout" value="2000"/>
<param name="max-digits" value="11"/>
<param name="dialplan" value="XML"/>
<param name="context" value="default"/>
<span id="4">
<param name="tonegroup" value="us"/>
<param name="digit-timeout" value="2000"/>
<param name="max-digits" value="11"/>
<param name="dialplan" value="XML"/>
<param name="context" value="default"/>


3. In this file: /usr/local/freeswitch/conf/autoload_configs/modules.conf.xml, uncomment the line: <load module ="mod_openzap"/>

Dialplan Config

4. From the wiki mentioned in Step 0. above: tell FS how to use the card's ports:

1. To bridge an inbound call to your FXS1 port (i.e., to make the phone that's plugged into FXS port #1 ring when a call comes in from somewhere), for an UA registered as, configure as below: --In plain English, this basically makes "extension 507" ring on the FXS port #1:

<extension name="incoming-fxs-channel-1">
<condition field="destination_number" expression="^(507)$">
<action application="bridge" data="openzap/1/1"/>

2. To send an outbound call out through the FXO4, for any 10-digit destination, configure as below

<extension name="outgoing-fxo-channel-4">
<condition field="destination_number" expression="^([0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9])$">
<action application="set" data="dialed_ext=$1"/>
<action application="bridge" data="openzap/2/2/${dialed_ext}"/>

See Also

X. These pages are also mentioned and informative: OpenZAP and Zaptel_Tutorial

Conference Server


Ring Group, Hunt Group, Fork Dial, and how to get one phone number to ring on several phones

FS is excessively more powerful than necessary for establishing traditional "ring groups". In fact, the term Ring Group didn't even appear, until now, in the FS parlance or wiki. This is how to get one incoming phone number to ring on several desk phones: Ring group

Difference between BRIDGE and TRANSFER

"One creates an outbound call and connects it to you, the other just sends you to somewhere else in the dialplan." --anthm

Bridging a leg to your present session lets you commandeer that leg, so what you do to your present session/leg/whatever gets also done to the leg you've just bridged. Bridge is like an acquisition. Transfer, on the other hand, is like a jump. This is my present understanding 2011-12-23

External control, interfacing, PHP

This goes way beyond beyond. See mod_event_socket

Phone tones and DTMF goofiness

VoIP audio compression codecs are severe; most seem to severely munge solid audio tones, such as DTMF tones. The alternative is to either run something relatively less compressed, or even nearly uncompressed, e.g., G711u, that will not munge the "in band" audio tones, or use some kind of VoIP tone signalling. FMI read about the codecs on wikipedia. I asked about this on IRC.

MikesNotes: i've got a bunch of different sip phones, all set to send DTMF tones as INBAND. But the FS demo doesn't respond to the tones. Any ideas? Is there some setting that will enable inband DTMF recognition or something??

rupa: MikesNotes, you can't put your phones into rfc2822 mode? there is a tonedetect app to turn on inband detection if you want

rupa: MikesNotes, dtmf works fine with my poly 450/320, snom m3, and siemens ip4something

Bug in Linksys SPA-942 (and SPA-3102) firmware

RTP packet size should be set to 0.020, not 0.030. Not sure why, but several sources confirm this.

Getting SPA-3102 to work: SIP and PSTN

This works: SPA3102_FreeSwitch_HowTo There also this site but I didn't need it.