THIS PAGE IS BEING RETIRED, USE Debian 8 Jessie INSTEAD. MOST OF THESE STEPS HAVE ALREADY BEEN INTEGRATED INTO THE PACKAGES.

About

Detailed information on how to properly build and test the new
FreeSWITCH™ 1.6 with awesome video conferencing support.

Click here to expand Table of Contents

Introduction

FreeSWITCH™ 1.6 introduces new video features. See a working demonstration on the VoIP User Conference 539 of 1 May, 2015 putting the
FreeSWITCH™ video conference through its paces.

What's new

FreeSWITCH™ now features video transcoding.

A few new modules were added with video codec support, such as mod_av, mod_vlc, mod_vpx, and others. Based on that, mod_conference can now do a video MCU, which introduces the new video layouts and group layouts. The video layouts feature allows you to set specific locations for the videos participants, floor holder and presenter.

Because
FreeSWITCH™ core now supports video, you can do playback and record with video support, so you can do things like 'record' and stream to a live YouTube event over RTMP, etc. Also, mod_verto now adds the ability to select video settings like resolution, bandwidth, camera selection and desktop sharing, all these features are demonstrated in the Verto HTML Demo page.

For more info, check out mod_conference page. Let's get all these new features configured!

Installation

Setting up the repos

Debian Jessie is required for this setup. A clean installation would make things easier and if you just follow the following steps everything will work smoothly.

A new set of dependencies was added to support the new features. Some of these dependencies were developed by the
FreeSWITCH™ core team and the packages were added to our repository.

Let's configure the Jessie repo:

Double click to select all commands, then copy and paste in your shell session.

Enable Debian Jessie repository

Get FreeSWITCH

Choose from the packages listed to complete your FreeSWITCH™ installation.

apt-cache search freeswitch | less

We suggest that you install the Vanilla meta package to get a basic running installation.

apt-get install freeswitch-all

If you desire other FreeSWITCH modules, run the apt-cache search command above and choose from those listed by running apt-get install <module_name>

You might get systemd errors. Replace freeswitch.service in /lib/systemd/system/ with this in that case:

freeswitch.service Unit File for FS Package

After that do:

The packages might not set up the configuration in /etc/freeswitch, you then can copy the files manually:

cp -a /usr/share/freeswitch/conf/vanilla /etc/freeswitch

Installing from Source

Now that we have our repo configured, let's install the deps:

Dependencies

Compiling

With all the dependencies installed, we can now properly build
FreeSWITCH™ 1.6:

Checkout FreeSWITCH source

Enable mod_av:

Enabling optional modules

Let's make and install the project:

Compiling the code

Configuring

Certificates

It's mandatory that you use valid certificates on this setup. If you're setting up your own CA we can't guarantee that it'll work and we can't help you.

Let's create our directory to store the certificates that will be used by
FreeSWITCH™ and Apache:

After creating the certs dir, we need to set our wss.pem, agent.pem and cafile.pem:

Certs files

Make sure you generate those files with proper layout, as described above, otherwise you'll get WS SETUP FAILED messages in
FreeSWITCH™ console and things won't work.

Self-signed certificates

If you really really want to use your own self-signed certificates, knowing that we will not support it, follow these steps:

Certs files

WS SETUP FAILED with Self-signed certificates

You cannot login, and FreeSWITCH is reporting (in debug) WS SETUP FAILED : this is because you have not imported your new self-signed certification authority in the browser. It will fail forever.Import the self signed CA in browser, or visit with the browser the same address and port you will use as wss. Eg: if you have wss://192.168.1.34 then visit from same browser https://192.168.1.34 , then accept the certificate.

This (accept the certificate from https) is not the optimal solution, and can bring problems and failures to connect.

Optimal solution is to import into your browser your self signed Certification Authority.

Apache with SSL

Note that the HTML does not have to be served from the FreeSWITCH server, it can come from anywhere – the only requirement is that the SSL certificates on the FreeSWITCH server must be trusted.

Enable required Apache modules:

Apache Required Modules

Copy the CHAIN, CERT and KEY files to /etc/ssl/private:

Copy cert files to /etc/ssl/private

Setup Apache default SSL enabled host:

Apache SSL Configuration

Rewrite HTTP to HTTPS access:

Rewrite HTTP to HTTPS

Make sure to replace MY.DOMAIN.NAME with your FQDN in the commands above.

Improving Apache SSL Security settings:

Apache SSL Tweaks

Now restart Apache to reflect the new settings:

Test Certificates

You can use the following script to test your certificate setup. Create a file called test_tls.sh and paste this content:

Test TLS domain

Then you can run the script:

If one of the above tests fail you MUST stop now and try to fix the issue before continuing this guide.

Demo Files

Verto demo pages uses some videos to demonstrate the new video features. Let's get this environment set up:

Dialplan:

FreeSWITCH™ default dialplan checks if you're using the default password and warns you in the console about this security role, this extensions has an sleep of 10 seconds. Let's disable this for now so we don't have to wait 10 seconds each time we make a test call:

The proper way to fix this is by changing your default password to something more secure. Change it ASAP.

Bridging from WebRTC (mod_verto) to PSTN/ITSPs

WebRTC is slow to establish media. So we need to provide SDP asap.

We can do this by answering and sending some silent packets, instead of waiting for normal call setup:

Dialplan:

Starting FreeSWITCH

The default and preferred init system on Debian 8 (and CentOS 7) is Systemd. If you didn't revert to system V and you're compiling Freeswitch like you are, the building mechanism now recognises that you're using a Systemd based distribution and it will offer you a script that will create the required user and group and install the Systemd files, so you can just start Freeswitch. You can install it using:

If this works out for you, you can skip the following two sections (about owners/permissions and Systemd).

Set Owner and Permissions

Because you most likely built
FreeSWITCH™ as root you must now create the user 'freeswitch' in group 'freeswitch' and change the FS files to owner = freeswitch and group = freeswitch and set the file mode appropriately. Execute the following commands as user root:

Set owner and permissions

systemd

systemd is the replacement service management system that replaces System V init. It is quite thorough and requires much simpler configuration scripts called Unit Files. systemd can start
FreeSWITCH™ at boot time, monitor the application, restart it if it fails, and take other useful actions.

At the time of this writing (August 2015) the optimum systemd unit file is not certain, but the following have been proven to work on Debian 8.1 systems. If you have discovered a better approach, please update this section or submit a JIRA ticket so that we can capture this knowledge for the community. If you prefer to use the old sysvinit system, then use the instructions on the Debian 7 page.

The systemd unit file you're going to use should be something similar to this, this works fine when Freeswitch is installed using the methods above. The pre-compiled packages come with their own systemd files and scripts to install them, although you may certainly use this as a guide if you have trouble; but be sure to observe the correct file locations as they differ between compiled installations and package installations.

When troubleshooting systemd difficulties look for messages in /var/log/syslog and /var/log/daemon.log and grep for freeswitch messages.

The unit file start Freeswitch as root, so Freeswitch can setup priority, create some directories if needed, etc. Then it will continue running as user/group Freeswitch.

systemd unit file FreeSWITCH built from MASTER

Now that the systemd unit file has been set up, you can copy it to the /etc/systemd/system directory where systemd looks for local customized files that won't be overwritten by systemd updates. Linking is possible to, but will give you issues when enabling (https://bugzilla.redhat.com/show_bug.cgi?id=955379)

Now you are ready to start FreeSWITCH for the first time. Because FS is owned by user freeswitch it should create its databases and log files under that user (instead of root) so that those files will still be accessible to it under future runs.

systemctl start freeswitch

To stop FreeSWITCH:

systemctl stop freeswitch

To install FreeSWITCH to start at boot time:

systemctl enable freeswitch

Testing Video

At this time you have a fully functional
FreeSWITCH™ 1.6 demo system. You can now point your RTC-enabled browser to https://MY.DOMAIN.NAME/verto and you'll see the Verto Demo Page.

You can call for example extension 3500 to enter your first video conference. This is a conference with the video-mcu-stereo profile, that has the video features enabled by default.

After dialing to the conference, you'll hear that you are the only person in the conference and your video will appear on the screen:

When you place your mouse closer to 'Outbound Call' you'll see your user controls:

Now you can invite another caller and your video will be mixed together with the other caller video, and both video swill appear on the screen. The video disposition will behave according to the layout that was configured for this conference room.

FreeSWITCH™ 1.6 has a few layouts configured by default and you can change the video layout on the fly using the conference API, for example:

Video Layouts

Conference

All the new APIs and variables of
FreeSWITCH™ 1.6 are already documented on mod_conference page.

Layouts

Definition

With video layouts you can configure specific video locations for your conference members, video floor holder and presenter.
FreeSWITCH™ ships with many pre-defined examples and so you can start using the layouts right now.