FreeSwitch FAQ
From FreeSWITCH Wiki
General
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
Raymond Chandler ([intra]lanman) - http://www.amazon.com/gp/registry/wishlist/27XDISBBI4NOU
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 its 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 specified for "export" to only set variable for leg B by doing the 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, IAX2, H.323 (with OPAL), Skype, Jingle (GoogleTalk), 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 GoogleTalk?
Yes in March of 2006 I developed my own XMPP telephony signaling library that is capable of communicating with Google’s GoogleTalk. With a single Jabber account you can receive endless simultaneous calls from GoogleTalk 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 GoogleTalk to SIP calls through FreeSWITCH here http://www.alijawad.org/cms/index.php?option=com_content&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 four more tagged releases. Last version, 1.0.4, has been released on August 6, 2009. All releases can be found on the files web site.
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 http://wiki.freeswitch.org/wiki/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 Mac/OSX, 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:
- SIP: 888@conference.freeswitch.org
- H.323: 888@conference.freeswitch.org
- Google Talk/Jingle: freeswitch@gmail.com
- Google Talk/Jingle: 888@jabber.asterlink.com
- IAX: guest@conference.freeswitch.org/888
Q: Do you have a mailing list where I can ask questions about FreeSWITCH?
We sure do. To sign up you can goto http://lists.freeswitch.org
Troubleshooting
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 rfc3711" 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: I get svn: PROPFIND of '/svn/openzap/trunk': could not connect to server (http://svn.openzap.org:81) when I try to check out FreeSWITCH how can I fix it?
This is because port 81 is blocked by a firewall or proxy. You can issue this command in the freeswitch source directory "svn propedit svn:externals ." And change the port back to 80 then save. "svn update" and you should be set to go.
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 fresh 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 FS does not find the sqlite database/table that it needs. As long as the message is not repeated upon a restart of FreeSWITCH, you can ignore this error.
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)
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.
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... 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 dir where you build FS and running: $ cd libs/libedit $ make clean $ sh configure.gnu $ make $ cd ../.. $ make clean $ make install
Running as service
Q: How can I run freeswitch on background?
Just run freeswitch with the option -nc
Q: Is there something like telnet available when running FS 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 running in 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
Q: How do I intall 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. 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
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 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 opened Freeswitch.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: 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: http://wiki.freeswitch.org/wiki/Installation_Guide#Precompiled_Binaries
SIP
Q: How do I setup SIP client authentication?
See the Sofia 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 FS console?
To show SIP registrations with the profile information type:
freeswitch> sofia status profile internal
To show SIP registrations without the profile information type:
freeswitch> sofia status profile internal reg
IAX2
Q: How do I setup IAX2 client authentication?
Since we have the user directory but we have no desire to modify libiax2 to support registration, authentication can happen for outbound call like this iax/user:pass@remotehost/exten. To support everything properly someone will need to write a new IAX stack from scratch.
PSTN
Q: Can I use FreeSWITCH with analog lines (FXS/FXO)?
OpenZAP supports analog cards. Please see OpenZAP for current status.
Q: Can I use FreeSWITCH with isdn BRI/BRA lines (S0 Basic Rate Interface)?
Initial BRI support has been added to the default ISDN module (ozmod_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 (ozmod_zt) and a single port HFC-S PCI card. NOTE: Advanced features (transfer, hold etc.) are not supported by the ozmod_isdn ISDN stack.
Q: Can I use FreeSWITCH with a PRI (E1/J1/T1)?
OpenZAP supports PRI cards (as well as analog cards). OpenZAP replaces mod_wanpipe. Previously, support was added for Sangoma PRI cards via mod_wanpipe.
Applications
Q: How can I use the JavaScript (ECMA Script) 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
- eg: <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?
"freeswitch -nc" for No Console
- Other options available are:
- "freeswitch -hp" for high priority mode.
- "freeswitch -vg" for valgrind (useful for debugging)
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?
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 difft 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?
The FreePBX developers are working on FreePBX version 3 which supports FreeSWITCH. As of this writing you can obtain the pre-release version of FreePBX v3. It is a very promising project and we encourage any who are interested in seeing an open-source GUI front-end for FreeSWITCH to support the FreePBX version 3 effort.
FusionPBX, has been released as a multi-platform, open source web interface for FreeSWITCH licensed under the BSD license. It provides a customizable and flexible web interface to FreeSWITCH. It uses a database backend which can use SQLite, PostgreSQL, or MySQL. Once installed it is quite stable and has been used production in small to large environments.
Another option is WikiPBX, which is Open Source under the MPL, written in Python and based on the Django web application framework.
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.
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.
