SYSADMIN FreeSWITCH Mateusz Radek, Fotolia
VoIP with FreeSWITCH TALK SOFT FreeSWITCH is a powerful and versatile telephony platform that can scale from a softphone to a PBX and even to a carrier-class softswitch. BY MICHAEL S. COLLINS
pen source projects have lowered ship between cURL (application) and Some pre-compiled binaries are known the barrier to entry into tele- libcurl (library). to exist; however, I recommend compil- Ophony for hobbyists and busi- FreeSWITCH has been used in some ing from source. nesses alike. The popular Asterisk PBX exotic scenarios; however, those new to First, unpack and install the source. In tool, for instance, is a high-functioning telephony applications are best served this example, I will download into /usr/ and low-budget telephony alternative starting out with FreeSWITCH in its de- src and install from there: that has proven disruptive in the world of fault configuration as a SOHO PBX. Al- business telephone systems [1]. Perhaps though you might find the numerous tar zxvf freeswitch-1.0.4.tar.gz the most disruptive software of all, how- Free SWITCH configuration files and set- cd freeswitch-1.0.4 ever, comes in the form of the scalable tings overwhelming, in a short time, you ./configure softswitch library called FreeSWITCH. will appreciate the power and flexibility make install The FreeSWITCH website [2] says that of this versatile telephony tool. it can be used as a “simple switching en- I recommend getting the sound files: gine, a PBX, a media gateway, or a Installing FreeSWITCH media server to host IVR applications.” As of this writing, the current, stable make cd-sounds-install True to that chameleon-like descrip- version of FreeSWITCH is 1.0.4, which make cd-moh-install tion, FreeSWITCH has appeared in pro- can be downloaded from the project duction environments as a telco switch, website [3], or you can use the Subver- FreeSWITCH comes with and can han- in numerous business scenarios as a sion repository to install the latest ver- dle sound files at 8, 16, 32, and 48kHz PBX, as a softphone for laptop users, sion. Unlike many projects, the SVN sampling rates. Few, if any, telephony and even as a voice routing engine for trunk is extremely stable, so it might be systems – open source or proprietary – the OpenSim project. convenient for you simply to use the lat- can do the kinds of things FreeSWITCH Additionally, you can deploy est trunk. can do with calls at multiple sampling FreeSWITCH as an application or use it In any case, the FreeSWITCH develop- rates. as a library (libfreeswitch) that can be ers have made it very easy to update to The installation will take some time, embedded in third-party software. This the latest trunk, even if you have in- so feel free to chain the commands to- double identity is similar to the relation- stalled from the latest stable version. gether with the && operator.
54 ISSUE 106 SEPTEMBER 2009 FreeSWITCH SYSADMIN
When the process is complete, you load mod_portaudio will have a basic FreeSWITCH installa- tion. Because it is handy to have the two After several debug lines, you’ll see main FreeSWITCH executable files avail- +OK when the module is loaded. Now able in the bin path, I use symlinks: list the PortAudio devices available on your system: ln -s U /usr/local/freeswitch/bin/freeswitch U pa devlist /usr/local/bin/freeswitch ln -s /usr/local/freeswitch/binU API CALL [pa(devlist)] output: /fs_cli /usr/local/bin/fs_cli 0;Built-in Microphone;2;0;i 1;Built-in Input;2;0; To launch the application, enter 2;Built-in Output;0;2;r,o freeswitch, and use the fs_cli utility to ac- 3;Logitech USB Headset;0;2; cess the command line of any 4;Logitech USB Headset;1;0; FreeSWITCH server to which you have access, even if it is on another server. At The i and o are next to the currently se- Figure 2: A successfully registered X-Lite first, you’ll see quite a bit of debug/ log lected input and output devices. To client. information, but don’t worry about er- change the input device, use the pa rors or warnings at this point. indev command with the device number, softphone. In this way, you will be able to use any codec that your FreeSWITCH Your New Softswitch pa indev #x installation supports – and there are The first basic command is version, some very high quality codecs available which displays the version of Free- where x is the number of the input de- – without installing a softphone client. SWITCH you are running, including the vice. The output device can be changed SVN revision. The status command with the pa outdev command. In my Connecting a SIP Phone shows information about your instance setup, I’ll use device 4 as output and de- The most common way to use Free- of FreeSWITCH, including uptime and vice 5 as input. SWITCH is with a SIP phone. A physical the number of currently active sessions. If you have the MOH (music on hold) handset is often called a hard phone, Another basic command is the self-de- files installed, this command will make a whereas a software-based phone is ap- scriptive help. call to the MOH extension and send the propriately called a softphone. Numer- To exit FreeSWITCH, type fsctl shut- MOH to the PortAudio output device: ous types of hard phones are available down or use the shortcut command ... from manufacturers. Softphones come in (three periods). pa call 9999 both proprietary and FLOSS varieties. A If you have a sound card or headset on popular free – but not open source – your system then try this: If you hear music, it was a successful softphone is X-Lite from CounterPath call. If not, make sure [4], which is available for Linux, Mac OS the MOH files were in- X, and Windows. Even if your Free- stalled properly. Hang SWITCH server runs on Linux, your soft- up with the pa phones can run on any operating sys- hangup command. tem, as long as they are SIP compliant. To make sure both To begin, download X-Lite for your input and output de- desktop or laptop operating system and vices are working, do perform a default install. (Installing a an echo test: softphone on the same system that is running FreeSWITCH is not recom- pa call 9996 mended; however, in many cases, it will work for the sake of testing.) Now when you speak into the input device, Session Initiation Protocol your voice should be SIP is a TCP/IP-based Application Layer echoed to the output protocol used for multimedia sessions device. The pa over the Internet. The text-based proto- hangup command dis- col is similar to HTTP, with requests and connects. responses, header fields, encoding As you can see, it is rules, and status codes. In addition to possible to use Free- VoIP, SIP is used in instant messaging, SWITCH and PortAu- online gaming, and distribution of streaming multimedia. Figure 1: The X-Lite SIP account configuration screen. dio to create a simple
SEPTEMBER 2009 ISSUE 106 55 SYSADMIN FreeSWITCH
Now launch X-Lite and open the SIP configuration without sift- Table 1: Dialplan Highlights Account Settings menu by clicking the ing through a particularly Show Menu button. (The button is the large file. Extension Function small down-arrow at the top of the 1000-1019 Default extensions phone, just left of center.) FreeSWITCH as a 2000-2002 Sample dial groups Only one SIP account is available in X- Daemon 30xx Narrowband conferences (8kHz) Lite, so click on it then click the Proper- To start FreeSWITCH as a 31xx Wideband conferences (16kHz) ties button. As shown in Figure 1, fill in daemon, use the -nc (no 32xx Ultra-wideband conferences (32kHz) the fields and use 1234 as the password console) command-line ar- 33xx CD-quality conferences (48kHz) for extension 1000. gument: 4000 Voicemail retrieval Next, clear out the Dialing plan field 5000 Sample IVR 5900 Call park because it is not needed with freeswitch -nc FreeSWITCH. Now click OK then Close, 5901 Call park retrieval and the phone will attempt to register. FreeSWITCH will report 9888 FreeSWITCH conference Figure 2 shows a successful registration. that it is backgrounding 9992 Information application To make a test call, dial 9999 and click and will give the process ID 9996 Echo test the green button to send. In a few mo- (PID). To stop Free- 9999 Music on hold ments you should hear music on hold. SWITCH, simply execute Figure 3 shows a call in progress to ex- freeswitch -stop at the Linux prompt. For cp 1000.xml 1500.xml tension 9999. now, leave FreeSWITCH running and use To shut down FreeSWITCH, use the the fs_cli command to connect: You will In an editor, open 1500.xml, replace fsctl shutdown (...) command. be greeted with a brief welcome message 1000 with 1500, and change the effec- and a CLI prompt and perhaps some tive_caller_id_name to Katherine. Your Configuration Highlights debug messages on the screen. To turn new file should look similar to Listing 1. The default FreeSWITCH configuration down the debug level, type: Now open $CONF/dialplan/default. has many features. Table 1 shows Dial- xml and locate the Dialplan entry (or plan highlights, and Table 2 shows some /log info “extension”) named Local_Extension. In of the more important files and subdi- the line rectories in the FreeSWITCH configura- This will restrict log messages to the tion. INFO level and lower and keep you from
56 ISSUE 106 SEPTEMBER 2009 FreeSWITCH SYSADMIN
Table 2: Notable Configuration Files “Sofia” is the name of the SIP library [7] used by FreeSWITCH and is also the Subdirectory/File Description name of the command to perform SIP- $CONF/vars.xml Defines a number of customizable sys- related functions. (Just type sofia to see tem variables, like default passwords and the syntax.) The above command tells codec preference lists FreeSWITCH to restart the external pro- $CONF/dialplan/default.xml The bulk of the default Dialplan is config- ured here file after reloading the XML data. The re- $CONF/directory/default/*.xml Individual users are defined here, e.g., loadxml is optional; however, if you’ve 1000.xml made changes to the XML data (by cre- $CONF/sip_profiles/internal.xml A “SIP profile,” or SIP UA to service an IP/ ating or editing a file), you will want port (usually port 5060) those changes loaded when restarting $CONF/sip_profiles/external.xml Another SIP UA to handle outbound reg- the profile. istrations to SIP providers (port 5080) To see whether your system registered $CONF/autoload_configs/modules.conf.xml Modules loaded automatically when with iptel.org, issue the command: FreeSWITCH starts
sofia status rization user name fields to 1500 before outbound registrations to providers. If saving the settings. Your client will mo- you already have a SIP provider, you will If your registration was successful, you mentarily say registering and then will want to use the settings for that provider. will see a line like the following: say Ready in the display. Now you can The FreeSWITCH wiki has sample con- make calls from your new extension. If figurations for a number of providers iptel gateway U you have a second phone, you can regis- [5]. In this example, I will show you how sip:[email protected] REGED ter it as 1000 and use it to call 1500. to set up a gateway for iptel.org, which offers free SIP accounts. The REGED state means that the gateway Outside the Local Switch First, create an account on the iptel. is successfully registered to the provider. One advantage of VoIP is that you can org website [6] and note your username If you see FAIL_WAIT, then most likely make free or very low cost phone calls and password. Next, create a new file you have a configuration problem. on the Internet. FreeSWITCH can route called iptel.org.xml in $CONF/sip_pro- The last step to receiving calls is to calls to and from the Internet, even if it files/external. Be sure to put your user- allow incoming calls in the Dialplan. The is behind a NAT device. NAT devices name and password in the appropriate default configuration has a “public” cause all sorts of trouble for SIP calls; fields. The file should look like Listing 2. Dialplan context that treats incoming however, FreeSWITCH does a good job Now save the file, then at the Free- calls from the Internet as inherently of working around these issues. SWITCH prompt, issue the command: untrusted. In many cases, the default configura- First you need to allow calls to your tion will work without any changes. A sofia profile external U new iptel.org user, then you need to simple test is to call the FreeSWITCH restart reloadxml specify where to route those calls. To do public conference server. The SIP URI of this server is sip:888@conference. Listing 1: New User 1500.xml freeswitch.org, and the default Dialplan 01
If your call is successful, you will hear 04 a text-to-speech (TTS) voice announce 05 your caller ID name or number. If you 06 are the only person in the conference, 07
11
SEPTEMBER 2009 ISSUE 106 57 SYSADMIN FreeSWITCH
so, create a new file called $CONF/dial- high-quality, voice-quality calls with free Now make a call to your friend or call plan/public/00_inbound_iptel.xml (or and open source codecs. The CELT [8] the FreeSWITCH conference: make a copy of the example file named open source codec is high quality and 00_inbound_did.xml). It should look like lossless. pa call 9888 Listing 3. Also included with FreeSWITCH are Be sure to specify your iptel.org user- the Siren [9] codecs from Polycom. The audio quality should be much bet- name in the regular expression. Your These high-quality codecs are closed ter, especially if you have a fast Internet username is the destination number. source but royalty free. The default con- connection. FreeSWITCH conferences (Destination numbers are not restricted figuration loads the Siren codecs. can mix calls of any codec and any sam- to numeric characters.) To load the CELT codec, issue the load pling rate. In fact, you can call in to the The call is routed to the extension mod_celt command. Free-SWITCH conference via the PSTN specified in parameters that are fed to One thing to keep in mind is that by dialing +1-213-799-1400 and com- the transfer application. higher quality codecs could expose limi- pare the difference between the high- In my case, I routed to the MOH exten- tations in your headset equipment. Most quality VoIP codecs and the low quality sion for the sake of testing. Also, you newer headsets and those that are listed of the PSTN. can route to your SIP phone. If you are as “Skype certified” will generally per- registered as 1000, then the transfer des- form well with the higher quality codecs. Where to Go Next tination is 1000 XML default. Save the Personally, I use a Logitech Clear Chat This brief introduction to FreeSWITCH file and then go to the FreeSWITCH Pro USB headset with good success. barely scratches the surface of what this prompt and press F6 (or type reloadxml) For testing, I recommend making a open source software can do. One way at the FreeSWITCH prompt. call to a friend who also has Free- to put FreeSWITCH to practical use is To receive a call on your new account, SWITCH installed. presented by IBM’s Rob Smart, who you will need someone to make a SIP To start, make a PSTN or mobile wrote a tutorial called “Home VOIP sys- call to your new iptel.org SIP URI. In a phone call, then hang up and immedi- tem using FreeSwitch and a Linksys 3102 pinch, you can test with PortAudio. At ately make a call with a high-quality voice gateway” [10] on how to set up the FreeSWITCH prompt type: codec. With the use of PortAudio, it is FreeSWITCH as a home communications easy to test. First, edit $CONF/autoload_ server in the UK. pa call sip:[email protected] configs/portaudio.xml. Locate the line A vibrant and growing community of- , change the value to 48000, alike, so join this community and con- extension. and save the file. tinue learning about the amazing possi- At the FreeSWITCH prompt issue these bilities of VoIP. n High-Quality Codecs commands: Traditional telephone calls are of mar- INFO ginal sound quality and mobile phone reloadxml [1] “How does FreeSWITCH compare to calls are worse. FreeSWITCH delivers reload mod_portaudio Asterisk?” http://www. freeswitch. org/ node/ 117 Listing 2: Setting Up a Gateway for a SIP Account [2] FreeSWITCH website: 01
08 Provider_Examples [6] iptel.org website: http:// www. iptel. org Listing 3: 00_inbound_iptel.xml [7] Sofia-SIP library: 01
58 ISSUE 106 SEPTEMBER 2009