Personal tools

FreeSWITCH

From PFSenseDocs

Jump to: navigation, search
This article is part of the HOWTO series.


News

The project has been named FusionPBX. More information is available at: http://www.fusionpbx.com

Latest version can be installed using the following instructions. http://wiki.fusionpbx.com/index.php?title=PfSense_Install

Intended Audience

Someone wanting to configure pfSense as a VoIP server via a web GUI.

FreeSWITCH Configuration Guide

This guide will help you prepare X-Lite sip softphone to work with FreeSWITCH.

We will create an extension in this guide, extension 1001. This guide will cover all aspects required to have a running VoIP server.

Support the Project

Donate with PayPal

Hardware

Hardware to use with FreeSWITCH package can be ordered from VoIP Supply which has a large selection of VOIP hardware. This including phones, external sip gateways, FXS, FXO and a lot more. Their prices are hard to beat, they ship quickly, and have a no hassle return policy. A small amount of each purchase will be given towards supporting the project if you use the following affiliate link.

Order your hardware here to support pfSense development.

Features

  • FreeSWITCH gives you complete scalability to have one line or hundreds
  • Install with one click on the pfSense firewall
  • Managed with a web GUI. Perfect when coupled with pfSense for its ease of use and security.
  • Run it as dedicated appliance or run with the pfSense as the firewall.
  • Very small Minimum/Recommended System Requirements 50MB 1MB RAM.
  • Run on the pfSense WAN interface or configured to run on any interface.
  • 8khz, 16khz, 32khz, 48khz, wideband audio, CD quality audios is here. Your cell phone is 8khz
  • Conference Calls at 8khz, 16khz, 32khz: Set up Conference call to unlimited participants
  • Secure SIP and RTP
  • Music on Hold (upload new music in mp3 or wav from the GUI)
  • Voice Mail
  • Voice Mail to e-mail (Outlook or any other Email Server, Also can be sent to special email addresses for SMS Text Messages)
  • Caller ID
  • Auto Attendant (IVR) unlimited
  • Ring Groups
  • Follow Me
  • Intercom
  • Text to Speech
  • Speech Recognition
  • Call Park
  • DISA (Direct Inward System Access)
  • Queues
  • Playback and Rerecord messages before delivery.
  • Callback support from inside voicemail.
  • Podcast of Voicemail (RSS)
  • Message Waiting Indicator (MWI)
  • H.26x standard video codec, can be used with x-lite soft-phone, some providers are starting to use this codec.
  • Video conference.
  • Time of Day Greetings
  • Urgent Message Tagging
  • Call Detail Records (CDR)
  • Auto Dialer can play message or direct calls to an auto attendant
  • Recordings interface for managing recordings used with auto attendant
  • Call Eavesdrop (aka barge)
  • Call Recording
  • Call Intercept by Group, Global, Extension
  • TFTP Server
  • Customizable and Brandable
  • Transfer Calls

Screen Shots

Clidk the link to see a preview of the pfSense FreeSWITCH GUI. [1]

pfSense Installation

To get started first you need to install pfSense.

PFSense Download page where you can download an iso for the installation or a premade vmware image.

http://www.pfsense.org/index.php?option=com_content&task=view&id=58&Itemid=46

FreeSWITCH Installation

One click install from the web interface. System Menu > Packages tab.

After installation you can access it from the pfSense web interface at Services -> FreeSWITCH

Configuration Screenshots

Screenshots of the various tabs with appropriate configuration examples. Some private configuration information pertaining to the author has been deleted from these examples. The SMTP examples are not meant to be input verbatim.

Settings Tab

Dialplan Tab

Extensions Tab

Gateways Tab

Public Tab

Public Tab Conditions and Actions section

Gateways / VOIP Providers

a.k.a. SIP trunk, voice gateway, voip provider, ITSP [Internet Telephony Service Provider]


We recommend Flowoute.com we have had good success with them. They have instant account setup, plans that bill per minute, allow you to send caller id number, and the number of lines is limited only by the speed of your internet connection.

Flowroute will give you a $0.25 cent credit to test your system. Should you need or want more minutes you would need to buy the minimum amount available which at the time of this writing is $35.00. A single DID (Direct Inward Dialing) is $1.35 a month. This will allow you to give out a regular phone number for people to call you from POTS (Plain Old Telephone Service) Lines.


SIP Registration with Provider

1. Setup provider proxy address and user account information. The labels on the gateways tab correspond with the xml tags on the FreeSWITCH wiki.

http://wiki.freeswitch.org/wiki/SIP_Provider_Examples

2. Public tab (inbound routes) defines inbound call and is done the same for both gateways that require and do not require registration. Extension Name: Whatever you like for the name tag: condition type: destination_number data: ^(11231231234)$ tag: action type: transfer data: 1001 XML default Note: use your DID (phone number) in place of 11231231234. In this example the call inbound call is transferred to extension 1001. It can also be transferred to other numbers such as a call group or IVR (auto attendant). Example: 5002 XML default

3. Dialplan entries can be auto generated using the shortcut 'Dialplan Expression' tool on the 'Gateways' tab. The Dialplan Expression is used to direct calls to specific gateways based on digits dialed from the extension. You can select 11 digits and when 11 digits are dialed on the extension it will send the call out the specified gateway. If 7 digits is select on the 'Dialplan Expression' tool it will automatically use the area code defined on the 'Settings' tab. It is also possible to direct calls prefixing the number with an 8 or a 9. The following: ^9(\d{11})$ matches a string with a prefix of 9 and an additional 11 digits. FreeSWITCH uses regular expressions throughout its configuration.

http://wiki.freeswitch.org/wiki/Regular_Expression


No SIP Registration with Provider.

This is typically done for by some voice providers for those with a static IP Addresses.

1. Do no need a gateway defined on the 'Gateway' tab.

2. Public tab directs inbound calls. It is done the same for both gateways that require registration and those that do not require registration. Extension Name: Whatever you like for the name tag: condition type: destination_number data: ^(11231231234)$ tag: action type: transfer data: 1001 XML default Note: use your DID (phone number) in place of 11231231234. In this example the call inbound call is transferred to extension 1001. It can also be transferred to other numbers such as a call group or IVR (auto attendant). Example: 5002 XML default

3. Dialplan Extension Name: provider_name_10digit tag: condition type: destination_number data: ^(\d{10})$ tag: action type: bridge data: sofia/default/1$1@did.voip.les.net

Extension Name: provider_name_11digit tag: condition type: destination_number data: ^(\d{11})$ tag: action type: bridge data: sofia/default/$1@did.voip.les.net


SIP to PSTN (public switched telephone network)

These devices translate standard telephone lines to VOIP and back again so they can be used as a access to and from the PSTN. This is an alternative to a VOIP provider that delivers access to the PSTN over the Internet.

Linksys SPA400

4 port FXO

http://wiki.freeswitch.org/wiki/SPA400_FreeSwitch_HowTo


Audio Codes

4 and 8 port FXO

http://wiki.freeswitch.org/wiki/Configuring_AudioCodes_MP-114/118

VoIP Phones / SIP Soft Phones

X-Lite SoftPhone

x-lite

Wengo Phone

OpenWengo


Linksys PAP2T

Inexpensive FXS that you can plug a standard and/or cordless telephone into.

linksys PAP2T


Interop List

List of devices and softphones that have been tested with FreeSWITCH.

http://wiki.freeswitch.org/wiki/Interop_List


IVR (Interactive Voice Response)/ Auto Attendant Feature

Auto Attendant Feature

Auto Attendant was also known as IVR and can be found under the Features tab-> Auto Attendant. When you create an IVR of 5002 you it will automatically add a dialplan entry on the 'Dialplan' tab for the extension. First you need to make some recordings for the IVR to use. You make the recordings on the 'Rec' tab by calling 732673 (record) it will ask for a pin number which is the 'admin pin' that is defined on the 'Settings' tab. After you make the recording edit it to give it an intuitive name. Then the recording will be available show up in the menu on the 'IVR' tab. The 'timeout' is how long to wait for key presses (DTMF) after the recording has finished playing. The 'Recording Action' drop down is the recording that will be played if the 'Javascript Condition' is true. If the condition is false then it will play the recording that is chosen in the Recording Anti-Action. For most systems the 'Javascript Condition' will a good start and work for most systems. It checks to see if the time is between 9-5 pm, that it is currently Monday - Friday, and not one of the predefined holidays.

Now you need to add the auto attendant 'options.' Start with the 'Action' options first. If my recording said the following: "Thank you for calling press 1 for Sales 2 for Support 3 to hear the options again." Then the first 'Option Number' would be '1' set the drop down 'Type' to 'extension' then the destination could be the extension for the Sales person. If you have more than one Sales person you might want to setup a group and transfer the call to the group. For more information on the groups look at the wiki at: http://doc.pfsense.org/index.php/FreeSWITCH click on 'Save.' Now add the 2. The third option to hear the options again can be done with 'Type' extension and a 'Destination' of 5002. There is special option number 't' it is what will happen when the timeout is reached. The timeout could be redirected back to 5002 or to a specific extension, or omitted and the call will end. With the default condition the 'Action' options are 'Office Hours' and the Anti-Action options are the 'After Hours'. However you can replace the 'Javascript Condition' with the following: condition=true; in this case the Anti-Action options will never be used. This is useful for sub IVR menus such as a Directory. A directory would not make sense to use a time condition. You can access sub IVR by creating an option such as 4 and then creating an IVR at extension 5003. Point the option 4 to use a Type of 'extension' then '5003'.

Calls are directed to the 'Anti-Action' options when the condition does not match. The process for adding them is the same as the 'Action' options.

After setting up the IVR and you have called it at extension 5002 then you can direct inbound calls to it from the 'Public' tab.

Conference

Default config has three sets of conference lines one for 8khz, 16khz and 32khz audio.

 8khz extension *3001-*3099
 16khz extensions *3101-*3199
 32khz extensions *3201-*3299

The default setup will play MOH when you're the only one on the line. When all but one person leaves it will inform you "You're the only one on this conference" and start playing MOH again.

  • To Do: Inform the first person who joins that they are the first to join prior to playing MOH.

Firewall

Access from the Internet

SIP TCP/UDP 5060 - 5090 and RTP UDP 16384 - 32768 ports for the WAN interface. Adding this rule is not necessary unless remote extensions are coming from outside the LAN.

 SIP TCP/UDP  5060 - 5090  
 RTP UDP      16384 - 32768

Screenshot


IP address or Domain

By default FreeSWITCH will bind to the WAN IP address of pfSense. If the WAN IP address is dynamic then you may want to consider using dynamic DNS. After seting up an account with a compatible Dynamic DNS provider setup Dynamic DNS in pfSense using the menu Services->Dynamic. After setting up the dynamic domain name go to FreeSWITCH on the 'Vars' tab set the 'domain' to the dynamic DNS domain name. Alternatively you can also set the domain to the LAN or Optional interface IP address if desired.

If you want FreeSWITCH to bind to an IP other than the WAN then set 'local_ip_v4' at the top of the 'Vars' tab (vars.xml). For this example the LAN IP is 192.168.0.1.

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

Call Park

park *5900

unpark *5901

Call park is a feature that allows a person to put a call on hold at one telephone extension and continue the conversation from any other telephone set.

Call Groups

Ring several phones at once. Ring all phone extensions in a group all at once or in order. Any two digit group number may be used. The following example will use group number 01.


  • Add to Group
*81[2 digit group number]
Calling Extension 8101 will add the current phone to group 01.


  • Delete from Group
*80[2 digit group number]
Calling Extension 8001 will remove the current phone extension from group 01.


  • Ring Group Simultaneous
*82[2 digit group number]
Calling Extension 8201 will ring all phone extensions in group 01.


  • Ring Group Order
*83[2 digit group number]
Calling Extension 8201 will ring the first phone extensions in group 01 followed by the next
phone in the group and then ring the next phone extension in the group until the call is answered.

Intercom (Paging)

Intercom aka. paging will call a phone and automatically place the call on speaker phone.


Intercom (Paging)

*8[extension number]


If the extension number you want to call is 1001 then you would dial *81001 to call using Intercom.

Compatible Phones

Music on Hold

By default music on hold support the .wav file format.

  • The music on hold for 8kHz audio is stored in /usr/local/freeswitch/sounds/music/8000/
  • To enable mp3 support you need to enable mod_shoutcast on the 'Modules' tab, then restart FreeSWITCH
  • To test the music on hold dial *9999 by default.
  • When using mod_shoutcast for MP3 support there are two parameters on the "Settings" tab- Decoder and Volume. i386 is the default decoder and .3 is the default volume.
  • To Access the Music on Hold page in the GUI navigate to the Features tab, then Music on Hold.

Voicemail to Email

Example setup of voicemail to email so that it sends the voicemails as an attachment using Gmail to deliver the email.

Settings tab:

 SMTP Host: smtp.gmail.com:465
 SMTP Secure: tls
 SMTP Auth: true
 SMTP Username: Use your gmail email address here.
 SMTP Password: Use your gmail email password here.
 SMTP From: Use your gmail email address here. It may support any valid email address but this has not been tested.
 SMTP From Name: Can be anything you choose. For my example I used: voicemail.

Extensions tab:

 Select a specific extension.
 Voicemail Mail To: Use any email address here.
 Voicemail Attach File: true or false

Video

  • Setup an extension from the 'Extensions' tab.
  • Connect a webcam to the computer.
  • Setup x-lite to use the extension
  • 'Vars' tab make sure H263 and H264 are in the 'global_codec_prefs'. After making the change run 'reloadxml' from the 'Status' tab.
 <X-PRE-PROCESS cmd="set" data="global_codec_prefs=G722,PCMU,PCMA,GSM,H263,H264"/>
  • 'Modules' tab make sure 'mod_h26x' is enabled. If it was disabled then you will need to restart FreeSWITCH from the Status->Services menu.
  • The last step to enable video is to click 'start' video in x-lite. To enable the other party to receive your video.

General Tips

  • Dial *2 to start recording again to stop recording press *2 again. Recordings are can be downloaded from Features -> Recordings.
  • Dial *870 redial
  • Dial *886 global-intercept
  • Dial *4000 main voicemail access any mailbox by id
  • Dial *9993 video record
  • Dial *9994 video playback
  • Dial *9995 delay echo
  • Dial *9996 echo test
  • Dial *9998 to test tone
  • Dial *9999 to test music on hold
  • Dial *5000 for the FreeSWITCH.org conference call line a second user can conference in by doing the same on another sip phone
  • Help with regular expressions http://wiki.freeswitch.org/wiki/Regular_Expression


Music Tips

FreeSWITCH wiki Tips

The FreeSWITCH wiki has some very helpful information.

This is the most intruiging page on the FreeSWITCH wiki. It tells you what FreeSWITCH cannot do.

Upgrades

The pfSense port of FreeSWITCH is in constant development. If you check System > Packages > Installed Packages, and see an updated package you would like to run, you will first need to backup the XML config for pfSense. This file also contains the FreeSWITCH configuration. If you made any recordings then use the FreeSWITCH package status tab and do a backup, plus save it to /tmp/ directory where it will automatically restore if it is there. Please note that this means that when you upgrade with a backup file there it will restore all your voicemails etc from backup, so do a backup directly prior to every upgrade so you don't go back in time on voicemail etc!

System Specifications

System requirements depend on your deployment needs. We recommend you plan for 50% duty cycle.

System Performance

Performance

These statistics are from other users on other systems. These will give you and idea how FreeSWITCH can scale.

   * Tested under load for over 100 hours
   * 10,000,000+ calls
   * At rates exceeding 50 CPS

Performance will vary depending on application. You will need to test for your particular situation.

Text to Speech

To enable text to speech from the 'Modules' tab select enable for the module mod_flite. Restart FreeSWITCH service and then add the extension in the 'Dialplan' using the GUI or the button 'default.xml'

 Extension Name: flite
 Description: Flite Text to Speech 5003  
                                                                                                                      
 Tag: condition 
 Field: destination_number
 Expression: ^\*(5003)$
  
 Tag: action
 Application: set
 Data: tts_engine=flite
 
 Tag: action
 Application: set
 Data: tts_voice=kal
 
 Tag: action
 Application: speak
 Data: This is flite on FreeSWITCH

Cepstral is currently not available in this package on pfSense. However you can run it on a seperate system, save the WAV files, then upload them to the recordings page.

TFTP Server

Some phones require a TFTP server to host the SIP configuration files. If your phone requires this then you can now a TFTP pfSense package. TFTP server files will be saved to /tftpboot.

The following adds a TFTP DHCP option. The manual patch is designed for pfSense 1.2.1 full release.

Download the two attached files and then remove the .txt file extension. Then you should have one file named services.inc and the other named services_dhcp.php.

Go to the PFSense Menu then Diagnostics -> Command and upload both files. The files will upload to the /tmp/ directory.

Run the following shell commands to copy the files to the correct location. cp /tmp/services.inc /etc/inc/services.inc cp /tmp/usr/local/www/services_dhcp.php

You can now go to Services -> DHCP Server and set the TFTP Server address.

TFTP Option [2]

Using the Console to View Messages/watch FS Work

Ocassionally you'll want to watch the FS console to see what it's doing (when the log file view in the "Status" tab isn't enough). To do so run the following commands while SSH'd to your PFSense box:

  1. cd /usr/local/freeswitch/bin
  2. ./fs_cli -H 192.x.x.x

Where 192.x.x.x is the LAN Ip of your router.

Change Log / Revision History

The latest non-development release of the FreeSwitch Package is .9.5

You can follow the commits to Mainline on Gitorious by following user mcrane here: https://rcs.pfsense.org/users/mcrane.

Note that versions marked with Dev are only available via the freeswitch_dev package, and the regular Freeswitch Package will not see these upgrades.

Version .9.5.3 Dev

  • Remove gzhandler- it seems to make the install fail.

Version .9.5.2 Dev

  • Upgraded to new build for the dev package for testing.

Version .9.5.1 Dev

  • Remove icons from extensions input boxes until 1.2.x is retired icons overlap the text, replace settings xml with php file which provides better flexibility.

Version .9.5

  • Added Optional PIN number to Hunt Groups
  • Added Caller Announce to Hunt Groups
  • Changed dialplan default.xml Added *97 for general voicemail box access
  • Added ability to have 5 digit extensions
  • Added work around for 404 error when clicking on Pfsense Logo on package subpages
  • Enabled ob_gzhandler compression for pages
  • Removed read write, read only, and config lock/unlock commands