FreeSWITCH VoIP PBX on a VPS

To be reachable via SIP using the same private domain I currently use for email, and even the same ID, I decided to set-up my own SIP PBX. Because I have rented a VPS anyway to host a couple of websites, this would be the right place for it!

Benefits of having the FreeSWITCH on a public server compared to using a PC: public IP without NAT problems, 24h up.

My VPS is a small system using Virtuozzo/OpenVZ virtualization, running Ubuntu 10.04 LTS. Using Virtuozzo means it is not possible to tweak the kernel and I could not change the HZ setting (granularity of the timers) to the recommended 1000 Hz. There are many discussions regarding the timing and some say that the HZ setting does not matter nowadays. Others reported that changing this setting improved the audio quality. Actually one would think that a VPS is not the best place for real time media handling. But so far my FreeSwitch works well and the audio quality is good. There are some cracks sometimes, but I am not sure if this due to the VPS or lost packets. Currently I am located in Bangkok and my VPS is in Germany. The packet loss rate is sometimes quite bad, between 2% - 10%. Probably with an optimized kernel also a medium sized FreeSWITCH deployment on a VPS is no problem. For private use it's definitely a feasible solution.

Installation

FreeSWITCH by itself does not have any GUI. All settings are stored in numerous XML files. There are a couple of GUIs available. I did not install any of them, for two reasons: My VPS is managed by Parallels' Plesk Panel, and it might be a bad idea to apply too many changes "behind Plesk's back", especially in the HTTP server domain. I have bad experiences with this. Secondly, I run only a small configuration and want to understand all applied changes in detail. Therefore editing the XML files is no issue for me.

The "official" FreeSWITCH installation guide is here: FreeSWITCH Installation
I used this guide for my first installation. After messing up the configuration, I decided to re-install instead of wasting too much time for the troubleshooting. I came across an installation script which makes things a bit easier. Its provided by the FUSIONPBX guys, who created a nice GUI for FreeSWITCH. You can find the script here: FreeSWITCH installation script
The script will ask if you want to install FreeSWITCH only or the GUI as well. Make your choice, I opted to get FreeSWITCH only installed.
The FUSIONPBX script downloads the SW, checks prerequisites, creates a user "freeswitch", and I don't know what else. It ran very smoothly and I recommend to use this script instead of doing a manual installation.

Some FreeSWITCH basics

The script starts FreeSWITCH in the background, after the installation is completed. To gain access to a command line interface you can start a CLI client with

/usr/local/freeswitch/bin/fs_cli

To shut down freeswitch use:

/usr/local/freeswitch/bin/freeswitch -stop

And to start it again use:

/usr/local/freeswitch/bin/freeswitch -nc

To have the two commands available without long paths, its a good idea to link them to a directory which is part of the PATH variable, e.g.:

ln -s /usr/local/freeswitch/bin/freeswitch /usr/local/bin/freeswitch
ln -s /usr/local/freeswitch/bin/fs_cli /usr/local/bin/fs_cli

Using just "freeswitch" without "-nc" starts FreeSWITCH in the foreground with a CLI. If you exit this CLI, FreeSWITCH shuts also down.

First tests

FreeSWITCH already ready to handle calls right after the installation script has finished! There are some pre-defined extensions and clients can be registered.

Client configuration:
SIP server: <your server IP address or domain>
SIP user ID: <any PBX extension 1000-1019>
Password: 1234

Also select an HD codec as first choice! I use the G.722 on my Grandstream speaker phone. The quality is so much better than the standard PSTN G.711 codec!

Calls between extensions are possible now, 4000 is voicemail, 9664 music, and 5000 an example IVR.
A couple more pre-configured features exist, see here: Some stuff to try out!

Some more customizations

Having a PBX island is not what I want, I want to be reachable under my well known email address, let's say This email address is being protected from spambots. You need JavaScript enabled to view it.. So I need to add a new extension with my email as SIP URI, e.g. an alphanumerical extension. Furthermore I need to extend the dialplan to terminate calls to this new extension.

SIP profiles

FreeSWITCH assigns different SIP profiles to UAs registered to FreeSWITCH ("internal") and all external communication, e.g. gateways to the PSTN and externally incoming SIP calls ("external"). Incoming requests are treated differently depending on the used port. The SIP profile "internal" is assigned to incoming requests on port 5060, while requests on port 5080 use the profile "external". PBX extensions are internal and should thus register via port 5060.
Depending on the used port / SIP profile, also different dialplans are used to decide about the call handling and restrictions. E.g. internal SIP subscribers would be allowed to use a PSTN breakout gateway, while a call incoming from another SIP exchange should not be allowed to use our FreeSWITCH as a transit to our PSTN gateway and make toll calls.

In the default configuration, incoming calls from other SIP exchanges to port 5060 will be rejected with cause code 407 "proxy authentication required". There are ways to change this, but the proper way is to receive incoming SIP calls via port 5080, which is reserved for trunking and gateways and attached to the SIP profile "external".
To achieve this, the SRV record of our domain (example.com) must point to port 5080 for SIP/UDP, e.g. the entry for _sip._udp.example.com. Any SIP proxy calling example.com must query the SRV record via DNS to find the correct SIP server and port.

To allow a different SIP server than the second-level domain is pointing to, often a dedicated SIP sub domain is used. E.g. sip.example.com.
In my case example.com uses a different server than my SIP server, so I defined a sub-domain sip.example.com.
The SIP SRV record is under the second-level domain, but points to the SIP sub-domain and the specified port (5080). To make SIP endpoint register to port 5060, sip.example.com should be filled into the proxy field and, if possible, SRV queries disabled. This was possible on my Grandstream desktop phone, but I had problems with other SIP clients.

Having set up the SRV record correctly, we can already receive calls from other SIP exchanges, because they are now using the correct  port 5080! The call will use SIP profile "external" and go through the dialplan "public.xml". There we will find a match for the 4 digit extension. The resulting action is a "transfer" to the dialplan "default". The match in dialplan "default" leads to action "bridge", e.g. connect two endpoints, or in other words terminate the call to the PBX extension.

The reason why we go through two dialplans is that we don't have to duplicate the more complex dialplan entries for a specific destination. In this case the dialplan for external calls ("public.xml") acts as a filter, which destinations are allowed for outside callers, while the detailed actions like voicemail and other services are defined in the dialplan "default".

Remark: I used iptel.org as the originating SIP exchange for testing. But calling This email address is being protected from spambots. You need JavaScript enabled to view it. did not lead to my FreeSWITCH under example.com, but to the iptel voicemail! The reason is that many SIP service providers ignore the domain part and use just the numerical user part of the URI. Then instead of forwarding the call to example.com, iptel found a match for "1000", which its terminated to its own voicemail!
Actually most SIP providers hide SIP addressing or make alphanumerical SIP URI dialling even impossible. Instead they do routing based on the numerical user part of the SIP URI. This is a legacy from POTS which has been carried over to SIP because users are used to use numbers and some clients have only numerical key pads. On the other hand, soft clients and mobile phones use integrated phone books / contact lists, and it doesn't matter anymore if the destination is numerical / E.164 or a SIP URI.

Email as PBX extension

Now the 4 digit PBX extensions are pretty meaningless to the outside world. I want to add This email address is being protected from spambots. You need JavaScript enabled to view it. as an extension

1) Create a new subscriber using the email address as URI

cd /usr/local/freeswitch/conf/directory/default
cp 1000.xml sp.xml     # copy the extension 1000 and use the desired userpart of the new SIP uri as new name
nano sp.xml              # change "user id" to "sp" and the other values as desired

2) Add a termination ("bridge") to "sp" in the default dialplan

nano /usr/local/freeswitch/conf/dialplan/default.xml

Copy the whole extension block of name = "Local_Extension"  to below the original block.
Change the name to something meaningful.
Edit the expression of the condition to "sp".
Edit the "dialed_extension" as well to "sp".

3) Add action "transfer" to the public dialplan to allow the new extension to be reached from outside

nano /usr/local/freeswitch/conf/dialplan/public.xml 

Copy the extension block "public_extensions" to below the original block.
Change the name to something meaningful.
Edit the expression of the condition to "sp".
Replace the $1 in the action line to "sp".

Now the new extension sip:This email address is being protected from spambots. You need JavaScript enabled to view it. is reachable from other extensions as well as globally from the Internet!

Note: the domain part is not evaluated, it can be anything in the default configuration.

Multiple registrations

Another goal is to allow multiple registrations under the same SIP user ID, e.g. my desktop phone and the SIP client of my mobile phone, and let them ring in parallel.

To achieve this, following parameter must be uncommented and the value changed to true:

nano /usr/local/freeswitch/conf/sip_profiles/internal.xml 
# uncomment and edit this line <param name="multiple-registrations" value="true"/>Now both phones, my mobile phone's SIP client and my desktop phone ring if someone calls sip:This email address is being protected from spambots. You need JavaScript enabled to view it.. As soon as one SIP UA answers, the other stops to ring.

Final Remarks

This is a short walk through to get a feeling of success quickly! ;)
There is much more to do, especially the SIP passwords should be changed and saved in a separate file. There is plenty of documentation about configuring the FreeSWITCH.
I have one unsolved issue, which is the usage of different ports for external and internal traffic (e.g. trunks and own subscribers). To be reachable on port 5080, the SRV DNS record must point to this port. Some clients query also the SRV record and try to use port 5080 for registration, which is rejected. Sometimes it's possible to disable this or define a proxy, but some clients don't allow this. I would prefer to use only one port and apply different call routing / access restrictions based on user ID and registration status.

The Linux Pro Magazine has also a nice introductory article about FreeSWITCH.