FreeSWITCH – Wunderbare Welt der Informatik

FreeSWITCH is a scalable open source cross-platform telephony platform designed to route and interconnect popular communication protocols using audio, video, text or any other form of media. It was created in 2006 to fill the void left by proprietary commercial solutions. FreeSWITCH also provides a stable telephony platform on which many telephony applications can be developed using a wide range of free tools.

FreeSWITCH supports many advanced SIP features such as presence/BLF/SLA as well as TCP TLS and sRTP. It also can be used as a transparent proxy with and without media in the path to act as a SBC (session border controller) and proxy T.38 and other end to end protocols.

FreeSWITCH supports both wide and narrow band codecs making it an ideal solution to bridge legacy devices to the future. The voice channels and the conference bridge module all can operate at 8, 12, 16, 24, 32 or 48 kilohertz and can bridge channels of different rates. The G.729 codec is also available under a commercial license.

FreeSWITCH builds natively and runs standalone on several operating systems including Windows, Max OS X, Linux, BSD and Solaris on both 32 and 64 bit platforms.

FreeSWITCH supports FAX, both over audio and T.38, and can gateway between the two.

Before you install FreeSWITCH like described below, rather think about installing it together with the web admin GUI FusionPBX (or another Freeswitch GUI like FreePyBX). It’s much easier!

Info Sources

Build and install packages

# update the package repository
apt-get update

# install the prerequisites (required packages)
apt-get install autoconf automake bison devscripts g++ gawk gettext git-core libasound2-dev libcurl4-openssl-dev libdb-dev libedit-dev libexpat1-dev libgdbm-dev libjpeg-dev libldns-dev libmemcached-dev libncurses-dev libncurses5-dev libogg-dev libpcre3-dev libperl-dev libpq-dev libspeex-dev libspeexdsp-dev libsqlite3-dev libssl-dev libtiff5-dev libtool libvorbis-dev libx11-dev libzrtpcpp-dev make memcached pkg-config python-de python-dev python2.6-dev unixodbc-dev uuid-dev zlib1g-dev

# download the source code of the latest stable release (currently version 1.4)
cd /usr/local/src git clone -b v1.4 https://freeswitch.org/stash/scm/fs/freeswitch.git

# prepare to compile
cd /usr/local/src/freeswitch

# you can build and install all with the following command chain
# and skip the rest until the back up the original config files
./bootstrap.sh && ./configure && make && make install && make hd-sounds-install && make hd-moh-install && make cd-sounds-install && make cd-moh-install && make samples

# otherwise follow these steps …
./bootstrap.sh
# the -j argument spawns multiple threads to speed the build process
./bootstrap.sh -j

# optional: edit modules.conf (e.g. if you want to use the IVR)
# if you want to add or remove modules from the build, edit modules.conf
# see also http://wiki.freeswitch.org/wiki/Installation_Guide#Edit_modules.conf
nano /usr/local/src/freeswitch/modules.conf
# add a module by removing ‚#‘ comment character at the beginning of the line.
# remove a module by adding the ‚#‘ comment character at the beginning of the
# line containing the name of the module to be skipped.
#
# if you want to use the web admin GUI FusionPBX
# uncomment the FreeSWITCH modules that are needed:
mod_avmd
mod_callcenter
mod_memcache
mod_cidlookup
# the following module is needed for MP3 support:
mod_shout

# pre-process the configuration
./configure

# compile and install FreeSWITCH
make && make install

# compile and install sounds
make hd-sounds-install && make hd-moh-install
make cd-sounds-install && make cd-moh-install
# install other languages (if supported)
make cd-sounds-de-install && make cd-moh-de-install

# install / re-install default config
make samples

Back up the original config files for your reference

cp /usr/local/freeswitch/conf/dialplan/public.xml /usr/local/freeswitch/conf/dialplan/public.xml.original
cp /usr/local/freeswitch/conf/vars.xml /usr/local/freeswitch/conf/vars.xml.original
cp /usr/local/freeswitch/conf/autoload_configs/modules.conf.xml /usr/local/freeswitch/conf/autoload_configs/modules.conf.xml.original
cp /usr/local/freeswitch/conf/autoload_configs/lua.conf.xml /usr/local/freeswitch/conf/autoload_configs/lua.conf.xml.original
cp /usr/local/freeswitch/conf/autoload_configs/acl.conf.xml /usr/local/freeswitch/conf/autoload_configs/acl.conf.xml.original

Set owner and permissions

# create user ‚freeswitch‘
# add it to group ‚daemon‘
# change owner and group of the freeswitch installation
cd /usr/local
adduser --disabled-password --quiet --system --home /usr/local/freeswitch --gecos "FreeSWITCH Voice Platform" --ingroup daemon freeswitch
chown -R freeswitch:daemon /usr/local/freeswitch/
chmod -R ug=rwX,o= /usr/local/freeswitch/
chmod -R u=rwx,g=rx /usr/local/freeswitch/bin/*

Configure FreeSWITCH

# switch to the application directory
cd /usr/local/freeswitch/conf

# check and adjust some properties (like ports)
nano /usr/local/freeswitch/conf/vars.xml

# edit PATH to include path to FreeSWITCH binaries (/usr/local/freeswitch/bin):

create /etc/profile.d/freeswitch.sh
add the line „export PATH=$PATH:/usr/local/freeswitch/bin„
change access rights to this file: chmod 755 /etc/profile.d/freeswitch.sh
log off and log back on
echo $PATH

Test your installation

# start FreeSWITCH
/usr/local/freeswitch/bin/freeswitch
# or without the path if already in PATH
freeswitch

# get some help about the command line switches
/usr/local/freeswitch/bin/freeswitch -help

Automatic start at boot

# to start FreeSWITCH™ automatically at system boot, the init script must
# be modified to point to the file locations built from source instead of
# the F.H.S. locations installed by the package.

# edit the init script to point the startup directory to where FS was
# just built from source code
nano /usr/src/freeswitch/debian/freeswitch-sysvinit.freeswitch.init

# near line 20, edit these lines to look like this:

DAEMON=/usr/local/freeswitch/bin/freeswitch
CONFDIR=/usr/local/freeswitch/conf
GROUP=daemon

mkdir /var/lib/freeswitch
chown freeswitch:daemon /var/lib/freeswitch
chmod -R ug=rwX,o= /var/lib/freeswitch cp /usr/src/freeswitch/debian/freeswitch-sysvinit.freeswitch.default /etc/default/freeswitch cp /usr/src/freeswitch/debian/freeswitch-sysvinit.freeswitch.init /etc/init.d/freeswitch
chmod ug=rwX,o= /etc/init.d/freeswitch
chown freeswitch:daemon /etc/init.d/freeswitch
update-rc.d freeswitch defaults

Built-in portal GUI

The built-in FreeSWITCH GUI can be used out of the box. It is based on mod_xml_rpc, the module is built by default but not loaded, so you just need to load it. Therefore add the following lines at the bottom of /usr/local/freeswitch/conf/autoload_configs/modules.conf.xml:

<!-- Built-in Portal GUI -->
<load module="mod_xml_rpc"/>

Open your browser (Chrome and Firefox tested) and go to
http://localhost:8080/portal

Optionally you can enable web-socket support in /usr/local/freeswitch/conf/autoload_configs/xml_rpc.conf.xml by adding the following lines:

<!-- Enable web-sockets -->
<param name="enable-websocket" value="true"/>

Stop FreeSWITCH

# stop the FreeSWITCH process
/usr/local/freeswitch/bin/freeswitch -stop

Upgrade or rebuild

# upgrade to latest:
# the make current command will clean your build environment,
# do a git pull, and then do a make install.
cd /usr/local/src/freeswitch
make current

# rebuild all
cd /usr/local/src/freeswitch
make sure

Uninstall FreeSWITCH

# stop the FreeSWITCH process
/usr/local/freeswitch/bin/freeswitch -stop

# delete the auto startup script
rm -f /etc/init.d/freeswitch

# delete the FreeSWITCH directories
rm -r -f /usr/local/freeswitch
rm -r -f /var/lib/freeswitch

# delete the source files (optional)
rm -r -f /usr/local/src/freeswitch

Configuration files

/usr/local/freeswitch/conf/
This is the directory holding all config files.

/usr/local/freeswitch/conf/dialplan/public.xml
Starting from the freshly installed default FreeSWITCH „public“ (eg: from outside, not trusted to access services and features) dialplan, you insert as the first „extension“, aptly named „from_opensips“, an instruction that checks if the call is coming from the SIP server IP address, in which case the call is transferred to the corresponding destination_number in the „default“ dialplan (eg: can access the services and features as an internal user). You must edit the SIP server’s IP address.

/usr/local/freeswitch/scripts/config.lua
This file you create ex-nihilo (i.e. it is not installed by FreeSWITCH). It is read by the xml_handler script, and configure it with the correct values for directories and database name, user and password. Edit it all, or at least edit „mydbpassword“.

/usr/local/freeswitch/scripts/xml_handler.lua
This file you create ex-nihilo (i.e. it is not installed by FreeSWITCH). It is executed by the mod_lua Lua module, and fetch from SIP server database the values with which it constructs an xml directory snippet that is passed in real time to FreeSWITCH when FS needs info about users.
You don’t need to edit this file, but can be interesting to read.
This file comes originally from FusionPBX ( www.fusionpbx.com ), an opensource web interface to configure and manage FreeSWITCH, and has been cannibalized for our tutorial purposes.
Particularly, you can find there almost all the fields that are supported in FS directory (eg user management), so it can be extended easyly sourcing values from the same or other databases.

/usr/local/freeswitch/conf/vars.xml
This file contains the variables that are interpolated into FreeSWITCH configuration files when they are sourced the first time at FreeSWITCH startup (eg: NOT when you „reload“ FreeSWITCH).
Here you do not have to change nothing, we configured FreeSWITCH ports before.

/usr/local/freeswitch/conf/autoload_configs/modules.conf.xml
This file controls which FreeSWITCH modules are loaded at startup time.
No changes from standard original FreeSWITCH configuration, just be sure mod_lua is not commented out. We use Lua for database user management.

/usr/local/freeswitch/conf/autoload_configs/lua.conf.xml
This is the configuration file for mod_lua.
Start with the standard installed file, and then add the name of the script that will provide the XML data (in our case „xml_handler.lua“) for which part of FreeSWITCH (in our case just for the „directory“ part).

/usr/local/freeswitch/conf/autoload_configs/acl.conf.xml
This file configure the Access Control List (ACL) for FreeSWITCH.
Starting from the original installed file, you insert one line that allows (without further checking for authorization) any call coming from the OpenSIPS IP address.
You need to customize that IP address.

Test a SIP phone

Configure a SIP phone or softphone with the IP address of the FreeSWITCH computer and user „1000“ and password „1234“. The default FreeSWITCH™ configuration provides pre-defined definitions for extensions 1000-1019, all passwords are 1234.

Dial 9664 to hear music.
Dial 5000 to test the sample IVR.
Configure a second SIP phone as user 1001, dial 1001 from 1000, and 1000 from 1001 to test between phones.
Check out more:
http://wiki.freeswitch.org/wiki/Getting_Started_Guide#Some_stuff_to_try_out.21