Skip to main content

FAQ

(This FAQ will be farmed into explanatory narratives in the appropriate sections)​

Q: So where do I find wishlists for the developers of this awesome software?​

A: You can find the wish list for each developer here:

Anthony Minessale (anthm) - http://www.amazon.com/gp/registry/wishlist/1NQC79YV4RB83
Mike Jerris (MikeJ) - http://www.amazon.com/gp/registry/wishlist/1ELF2W9FAIN2N
Brian West (bkw_) - http://www.amazon.com/gp/registry/wishlist/1BWDJUX5LYQE0
Ken Rice (SwK) - http://amzn.com/w/38CG44Z1MZA87

Travis Cross (tc) - http://amzn.com/w/1BY8VBIYBK8BI

William King (quentusrex) - http://amzn.com/w/3CB0LGARUGVB3

Q: What is the difference between using a % and @ in a sofia dial string?​

This one is simple. You have a couple of options.

If the domain is an alias on the profile then you can use sofia/domain/user, If the domain is NOT an alias on the profile then you can use sofia/profile/user%domain, If you're dialing a remote SIP URI that doesn't require authentication it would be sofia/profile/remoteuser@remoteip

Q: What is the difference between using a ${var} and $${var} in the configuration files?​

The ${var} is expanded as it's encountered in the dialplan. The $${var} variation is used as a preprocessor variable and is expanded at load or reloadxml. See vars.xml in the conf folder for more information.

Q: What is the difference between using action application "set" and "export"?​

The "set" is to set channel variable for current channel, while by default "export" sets the variable for both legs (leg A and leg B). You can also use "export" to set a variable for leg B only by using "nolocal:" like the following example:

<action application="export" data="nolocal:foo=bar"/>

Q: What's the difference between PBX and soft-switch? Isn't this just semantics?​

A PBX is an entity that allows a private company to have its own mini phone company providing services like voicemail, extensions and conferencing to phones. The primary focus of a PBX is for multiple phones to find each other and communicate.

A soft-switch is a software application that can connect phone lines from one network to another, often routing calls from one protocol to another or to a termination point such as a PBX. FreeSWITCH has the potential to also implement a PBX but it is not mandated to. Think of it as a lower level application than a PBX. It's possible to load several modules into FreeSWITCH to make it behave exactly like a cluster of PBX applications. This is entirely easier than trying to make a single monolithic PBX behave as a switch especially when much of the PBX functionality is permanently built into the core of the PBX application.

Q: What language is FreeSWITCH™ written in?​

There are several languages, the core is written in C. Modules are mostly in C but some are C++. Some modules give you the ability to write applications in different languages, including, but not limited to, JavaScript/ECMAScript, Lua, Perl, Python, Ruby, Java and .NET.

Q: What about all that Asterisk development you did?​

It was not in vain, I still use the software, heck I even do consulting on it for people all the time. I spent several years contributing to it and I have developed many third-party modules for Asterisk located on my asterisk stuff page.

FreeSWITCH simply represents my concept of the future of Telephony.

Q: What are some of the things FreeSWITCH can do?​

FreeSWITCH has endpoints that implement SIP, SCCP, H.323 (with OPAL), Skype, Jingle (Google Talk), sound cards (via mod_portaudio), and TDM cards (Sangoma or Zaptel-compatible). You can use it as both a client and a server for VoIP communications, gateway a call from one protocol to another and execute IVR scripts written in one of several languages such as JavaScript, Perl, Lua, or C#. There is an extensive event engine that will inform you of anything that happens on the system as well as an XML-RPC interface that allows you to send and receive data from the core via HTTP.

There is abstraction in place to allow data to be pulled from XML, external HTTP requests, flat file (INI format) and via directory look-up, LDAP for example. The dial plan combines the power of XML and Perl Compatible Regular Expressions to allow one to route calls based on most any criteria from the call details.

Q: What? Did you say it can talk to Google Talk?​

Yes, in March of 2006 I developed my own XMPP telephony signaling library that is capable of communicating with Google's Google Talk. With a single Jabber account you can receive endless simultaneous calls from Google Talk clients and gateway those calls to IVR or another voice protocol like SIP or H.323. When FreeSWITCH is on both ends of the call you can bypass NAT and send extended data such as Caller ID and DNIS. You can find a tutorial on how to do Google Talk to SIP calls through FreeSWITCH here: http://www.alijawad.org/cms/index.php?option=com%5Fcontent&task=view&id=21&Itemid=2

Q: Is anyone running FreeSWITCH in production?​

Yes.

Q: How many concurrent calls can it support? Any benchmarks?​

This all depends on your application. You will need to load test with your application to know your limits, your mileage will vary depending on your specific requirements.

Please do not ask this question on the mailing lists as you will always get the same official response from the FreeSWITCH project; "we only perform benchmarking and confirm these results per FreeSWITCH deployment, as each deployment will result in varying figures. Commercial support is available from the project for this task. The project has learned from experience the dangers of entertaining such questions and its policy is to not do so over the free public forum."

Q: How long have you been working on this project?​

The initial release of the code that actually did anything interesting was in early January 2006. I started actual development in private sometime in the beginning of October 2005.

Q: When will you have the first tagged release?​

The first tagged release, version 1.0.0, hit the Web on Monday, May 26, 2008. Since then there have been more tagged releases.

Q: What is ClueCon?​

ClueCon http://www.cluecon.com is an annual telephony developer conference in Chicago where leaders of various popular VoIP projects and other telephony developers adjourn to speak and share ideas as well as give informative presentations. It's a three-day opportunity to be immersed in this emerging technology by day and spend the evenings in downtown Chicago!

Q: Which phones work with FreeSWITCH?​

Check this list: Interop List

Q: Does FreeSWITCH have to run as root?​

No.

Getting Help​

Q: Is there any documentation available?​

Yes. There are over 500 pages of documentation available at Documentation.

Q: Do you guys support IRC?​

Yes. Volunteers who are both novice and experts with FreeSWITCH (and everything in between) gather in #freeswitch on irc.freenode.net. You can use many IRC chat clients to connect such as mIRC for Windows, Limechat for macOS, Irssi or XChat for Unix-like systems, ChatZilla for Mozilla browsers or any other standard IRC program. We primarily speak English there, however, we do have an automated translation service for many other languages.

Q: Do you guys run a teleconference where I can talk about FreeSWITCH?​

Yes! We support a variety of methods to call us - these all go to the same place:

We run a Weekly conference call on the above every Wednesday at 1700 UTC. Past conferences are recorded, and can be found on that page.

At other times the conference channel is normally idle, but plenty of volunteers can be found on IRC at all times of day.

Q: Do you have a mailing list where I can ask questions about FreeSWITCH?​

We sure do. To sign up you can go to http://lists.freeswitch.org. We strongly recommend that you review this great article on how to ask smart questions on a mailing list.

Troubleshooting​

Q: Is it bad to see "Rejected by acl domains. Falling back to Digest auth"​

DO NOT PANIC! This is OK! This is an informational message that says that FreeSWITCH could not match the remote i.p. address in the Access Control List named "domains", so it is falling back to digest authentication. If you want FS to admit the remote machine on the basis of its i.p. address, then add it to conf/autoload_configs/acl.conf.xml or if it's a registered extension add the cidr="w.x.y.z/ab" attribute to the end of the user id= line. Beware that this might cause problems with some multi-line SIP phones.

Q: Are there any guidelines for troubleshooting and reporting bugs? Where do I start?​

Start with this wiki page: Reporting Bugs - it will answer many questions for you.

Q: I see this on my console when calling FreeSWITCH with a Snom phone "a=crypto in RTP/AVP, refer to RFC 3711" how can I fix this?​

You need to go to the Identity -> RTP and set the RTP/SAVP to optional. That will correct this.

Q: Why doesn't FreeSWITCH send a=rtpmap lines for some codecs in the SDP? My device expects this and doesn't work!​

For static payload types the a=rtpmap line is optional, since the codec defines what it would be. They are only required for dynamic payload types.

FreeSWITCH prefers to omit the a=rtpmap for static payload types since it means the SDP is smaller. This not only uses less bandwidth, but avoids (but doesn't prevent) fragmenting SIP packets where the codec list would be long enough to exceed the MTU.

Your device doesn't correctly support the SDP standard if it requires a=rtpmap lines for static payload types. However since there are quite a few of these devices in the wild, FreeSWITCH can be configured to send these lines to be compatible with these devices using the verbose_sdp variable.

Q: My FreeSWITCH install isn't responding to any SIP traffic or I see SIP traffic when I use tcpdump but I still don't get a response?​

This usually happens when you have a firewall enabled. You will still see traffic hitting your machine when you use tcpdump but the sure fire way to make sure the traffic gets through is to turn off iptables i.e. "service iptables stop"

Q: My install of FreeSWITCH is throwing SQL ERR[no such table: <table_name>]​

This is usually followed by an "Auto Generating Table!" message. This is normal behavior when FreeSWITCH does not find the database/table that it needs. As long as the message is not repeated upon a restart of FreeSWITCH, you can ignore this error. You may also see this error you load a module you have not used before, or when performing upgrades.

If are seeing a continuous stream of these errors and you are using a mixture of old-style/SQLite DSNs and ODBC DSNs of the same name then it is also possible you're hitting FS-5664.

Q: Show channels, conference list, and other console commands show no output​

You probably have an old copy of the db schema where that information is tracked.

Do this (Linux/Unix):

rm -rf /usr/local/freeswitch/db/*

and restart FreeSWITCH to see if that fixes the issue.

Q: What do I have to check if my Win32 FreeSWITCH doesn't start?​

For the correct functioning you need msvcr80d.dll which can be on your system already. If you don't have this DLL, it's recommended to try installing the 'Microsoft Visual C++ 2005 Redistributable Package' e.g. for x86

Q: How can I troubleshoot SIP?​

Check: Debugging FreeSWITCH and FreeSWITCH Endpoint Sofia

Q: How can I compile FreeSWITCH with debug symbols?​

export CFLAGS="-g -ggdb"

export MOD_CFLAGS="-g -ggdb"

./configure

make megaclean (if you want every lib with it)

make sure (if you want just FreeSWITCH)

Alternatively you can simply run the devel-bootstrap.sh script in the root freeswitch source directory. Notice that the devel-bootstrap script sets -O0 (optimizations to disabled). This can be useful for stepping through your code.

Q: Why do I get the error "Invalid Application <name>"?​

The most common reason for error is that you have not loaded the correct module.

Example:

2010-09-13 11:01:50.353264 [ERR] switch_core_session.c:1791 Invalid Application hash

How to troubleshoot:

Modify conf/autoload_configs/modules.conf.xml, and add:

<load module="mod_hash"/>

Q: mod_spidermonkey_odbc throwing the following error:​

::Error SQLConnect=-1 errno=0 [unixODBC][Driver Manager]Data source name not found, and no default driver specified

Make sure your ODBC driver (odbc.ini) and data source (odbcinst.ini) are in the /usr/local/freeswitch/etc directory.
(usually they are in /etc directory - symlink them). See also unixODBC configuration.

Q: What does this ICMP error mean?​

For one reason or another your connection was refused.

If you're getting Port Unreachabe Try correctly setting STUN on the device that's having problems (i.e. your IP phone)

For first-time installation, ensure your freeswitch server hostname is resolved to IP on the server. You need a DNS entry or /etc/hosts entry matching the HOSTNAME value in /etc/sysconfig/network file

See Connection Refused for more details.

Q: Ubuntu 64-bit (Gutsy/Intrepid) segmentation fault on start​

There is an issue with the ncurses lib, the solution is to:

apt-get install ncurses-devel

rebuild the libedit in FreeSWITCH by cd'ing to the directory where you build FreeSWITCH and running:

cd libs/libedit

make clean

sh configure.gnu

make

cd ../..

make clean

make install

Q: Why does FreeSWITCH keep its own time and not use the system time, instead?​

Allowing any software to trust the system time is very dangerous. Something that was depending on the system time to calculate a duration etc can be considerably compromised if the time suddenly changes by hours or years in either direction. Things like daylights savings time can break CDR etc.

The clock in FS is the onboard monotonic clock and the offset to real time is preserved. If you want FS to sync to system time when desired there are commands to perform this operation. Use command fsctl sync_clock

Q: I've upgraded and my ODBC DSNs no longer work!​

ODBC DSN syntax changed in v1.2.4. "datasource:username:password" DSNs will still work, but "datasource" DSNs (without username/password) will not. Prefix your DSNs with odbc://

See the v1.2.4 Release Notes, or the DSN page.

Running as a service​

Q: How can I run freeswitch in the background?​

Just run freeswitch with the option -nc

Q: Is there something like telnet available when running FreeSWITCH in the background?​

Yes. Make sure that mod_event_socket is loaded and then run fs_cli which is in the FreeSWITCH bin directory.

Q: How do I stop a freeswitch daemon from running in the background?​

freeswitch -stop

or,

fs_cli> shutdown

Q: How do I setup high priority to my freeswitch daemon?​

Just run freeswitch with the option -hp

You can also use the following;

-np – normal (system) default priority -lp – low priority -hp - high priority -rp – high real time priority

Q: How do I install as a Win32 Service​

From the directory you installed FreeSWITCH - run: freeswitch -install

Q: How do I juggle multiple instances on the same box?​

See the advanced configuration guide

Hardware/OS compatibility​

Q: Does it run on Amazon Elastic Cloud?​

Yes, see Amazon EC2.

Q: Does it run on Xen?​

Yes, it sure does. Amazon EC2 uses Xen.

Q: Does it run on machines without an MMU, like the Blackfin?​

Not right now, and probably not in the future. Without an MMU it is not possible to run the popular servers OSes, like Linux. ucLinux is well supported on the Blackfin, but ucLinux is a cut down Linux, designed to live within the limitations a lack of an MMU imposes.

Some other telephony software has been ported to Blackfin based boxes, like the IP04 at http://www.rowetel.com. If the application is clean and simple, the results can be very satisfactory. However, users must take care not to run tasks with can result in ever increasing memory fragmentation. If they don't, frequent reboots may be required. So far a version of FreeSWITCH has not been defined which lives with such restrictions. Therefore, no port to a ucLinux platform has so far been undertaken.

Compilation​

Q: Do I need to download all those external libs?​

No, make install downloads the ones you need based on what modules you selected to compile.

Q: How do I use my local dir instead of /usr/local/freeswitch?​

./configure --prefix=/my/install/dir

The above command will cause all subsequent "make install" commands to install FreeSWITCH to the directory /my/install/dir/ (without adding a "freeswitch" subdirectory). If you later re-run configure without using the --prefix parameter, the install directory will revert to /usr/local/freeswitch.

Q: How do I select modules to build?​

Edit modules.conf in the source directory and put a # in front of any module you don't want and remove any # from the ones you do (in Windows you use the normal Visual Studio methods to change dependencies via the configuration manager)

Q: How can I compile FreeSWITCH with Microsoft Visual C++ 2008/2010 Express Edition?​

Be sure to follow the install instructions from Microsoft. The Visual C++ page is found here. Once you have installed VC++ 2008 Express, open the solution file Freeswitch.2008.express.sln. If you see a lot of errors about folders not being supported then you probably openedFreeswitch.2008.sln which is the solution file for the full MS Visual C++ edition. Click Build, Build Solution and wait for compilation to finish. The executable freeswitch.exe will be in the debug folder. Note, early results indicate that Visual C++ 2010 Express can be used as well.

NOTE: Microsoft Visual C++ 2005 is no longer supported.

Q: I have problems on CentOS (possible other distros) with "/lib/cpp" failing sanity check?​

"./configure" on CentOS 4.4 spits out the following error: "configure: error: C++ preprocessor "/lib/cpp" fails sanity check". Try "yum install gcc-c++ compat-gcc-32 compat-gcc-32-c++". Check the dependencies and agree (if you agree!).

Q: I get an error while issuing "make megaclean"​

Try running the commands in the following order: "./bootstrap.sh", "./configure", "make megaclean" and finally "make installall"

Q: I don't have Microsoft Visual C++. Will there be a binary download for Windows?​

Pre-compiled Windows binaries are available. See section: Precompiled Binaries

SIP​

Q: How do I setup SIP client authentication?​

See the Sofia-SIP module documentation for information on this.

Q: How do I set up Music on Hold (MOH)?​

See the hold-music option in the Sofia Configuration Files for per-trunk settings, or the per-channel variable hold_music in the dialplan XML.

Q: Can the channel be automatically hung-up after RTP inactivity?​

Yes, This can be turned on via two params on the sofia profile. They are rtp-timeout-sec and rtp-hold-timeout-sec.

Q: How do you see SIP registrations in the FreeSWITCH console?​

To show SIP registrations in the internal profile:

freeswitch> sofia status profile internal reg

PSTN​

Q: Can I use FreeSWITCH with analog lines (FXS/FXO)?​

FreeTDM supports analog cards. Please see FreeTDM for current status.

Q: Can I use FreeSWITCH with ISDN BRI/BRA lines (S0 Basic Rate Interface)?​

BRI is supported via FreeTDM using Sangoma ISDN module (ftmod_sangoma_isdn) or via libpri module (ftmod_libpri)

Initial BRI support has been added to the default ISDN module (ftmod_isdn). TE (user) and NT (net) mode are supported, including dialtone in NT mode and overlap receiving. This has been tested/developed with zaptel + bristuff / DAHDI (ftmod_zt) and a single port HFC-S PCI card. NOTE: Advanced features (transfer, hold, etc.) are not supported by the ftmod_isdn ISDN stack.

  • See FreeTDM for more information.

Q: Can I use FreeSWITCH with a PRI (E1/J1/T1)?​

FreeTDM supports PRI cards (as well as analog cards).

Q: Can I use FreeSWITCH with MFC-R2 (E1)?​

FreeTDM supports MFC-R2 signaling using the openr2 library. See FreeTDM_OpenR2

Applications​

Q: How can I use the JavaScript (ECMAScript) dialplan?​

  • make sure that mod_spidermonkey is compiled (modules.conf in the src dir)
  • make sure mod_spidermonkey is enabled in freeswitch.xml
  • in your dialplan call 'javascript' with the path to the script as the argument
    • e.g., <action application="javascript" data="/tmp/test.js"/>
  • Visit the Javascript documentation for the FreeSWITCH specific extensions to JavaScript.

Q: How can I run FreeSWITCH without console?​

To run with no console;

freeswitch -nc

If you wish to access the pretty FreeSWITCH console when your process has been backgrounded (as shown above), you can use fs_cli.

fs_cli

Other options available are:

To run in high priority mode;

freeswitch -hp

To run for Valgrind (useful for debugging);

freeswitch -vg

Q: How can I use FreeSWITCH as a Win32 service?​

To install as a Win32 service use "freeswitch -install" and "freeswitch -uninstall" for removing. Currently, the service is installed under the user "Network Service", which may not have adequate permission to actually run FreeSWITCH. If this is the case, you can change the user by double-clicking on the service, going to the "Log On" tab and changing it to a more appropriate user such as "Local System account" or one that you created. You can start the service from command line with "net start freeswitch" and stop with "net stop freeswitch".

If the service created by "freeswitch -install" fails to start then try the following as an alternative. http://sw4me.com/wiki/Winserv

Download winserv and move it to so that the path looks like: "C:\Program Files\winserv".

To install the service run the following from the command prompt. "C:\Program Files\winserv\winserv.exe" install FreeSWITCH "C:\Program Files\FreeSWITCH\freeswitch.exe" -nc

Q: How can I stop running FreeSWITCH?​

freeswitch -stop

or,

freeswitch> shutdown

Command Line Interface​

Q: How can I originate a call?​

See API Commands: Originate

For more info on the Sofia-SIP URL syntax see: FreeSWITCH Endpoint Sofia

Q: Does reloadxml reload all XML files?​

It reloads the core XML cache, which doesn't mean all changes take effect.

  • Dialplan and Directory both get fully refreshed.
  • An event is fired (based on the ENUM config) that causes ENUM to reload.
  • Profile settings for Sofia don't, but you can bounce a profile in Sofia for new settings to take effect.
  • Conference settings will take affect next time a conf is created, but will not go away while the conference is up and running.

Call Routing​

Q: How do I assign endpoints to contexts with different sets of extensions​

Here are the different possible approaches:

  • use 1 profile per context you want to route to (each one needs a distinct ip:port)
  • use different domains in the registration data and use the auto context thing
  • send them all to a common context and execute_exten or transfer to somewhere else
  • send them to an IVR to decide where they go
  • use xml_curl to make it dish out a different dialplan based on who they are in the list of data you are fed

Q: How do I use a single domain for the entire server​

If you want your server to respond to all requests sent to it, and be handled under a single domain. Look for force-register-domain in sip_profiles/internal.xml uncomment the line and set it to the domain specified in vars.xml. Not exactly sure but you can't set a unique domain in directory.xml it has to match vars.xml.

If you want all registrations to be listed/stored at the same domain then: use force-register-db-domain

<param name="force-register-domain" value="domainname"/> <param name="force-register-db-domain" value="domainname"/>

Configuring FreeSWITCH​

Q: Is there a GUI for configuring FreeSWITCH?​

There are several free open source projects being actively maintained, an older abandoned one, and several commercial options. See Freeswitch Gui

Q: XML sucks! Do I have any other options?​

Yes and no. There are other options, but they may not be better options. The discussion about the use of XML in the FreeSWITCH configuration is plentiful. Check out these threads for some background:

See also mod_dialplan_asterisk for more information on configuring FreeSWITCH's dialplan using the extensions.conf INI-style configuration. (NOTE: this is less flexible and less powerful than using the XML configuration.)

That all being said, if XML is the only reason you're holding off from trying FreeSWITCH then we recommend you try it out with the default configuration and give it a test drive. You'll be surprised at how much you can do with a minimal amount of tinkering in the XML configs. And you'll be downright amazed at what you can do with a healthy amount of tinkering in the XML configs.

NOTE: Another way to program your call logic without using Dialplan XML is to use mod_dptools and/or mod_commands through mod_event_socket or ESL. This way you can avoid using Dialplan XML and you can do all your call logic from a compiled or interpreted programming language.