THIS PAGE IS BEING RETIRED, USE Debian 8 Jessie INSTEAD. MOST OF THESE STEPS HAVE ALREADY BEEN INTEGRATED INTO THE PACKAGES.
Detailed information on how to properly build and test the new FreeSWITCH™ 1.6 with awesome video conferencing support.
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.
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!
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.
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:
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:
With all the dependencies installed, we can now properly build FreeSWITCH™ 1.6:
Let's make and install the project:
Add the following lines to /etc/sysctl.d/vid.conf:
Activate the changes, running:
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.
You can set up your certs at http://www.startssl.com/ .
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:
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.
If you really really want to use your own self-signed certificates, knowing that we will not support it, follow these steps:
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:
Copy the CHAIN, CERT and KEY files to /etc/ssl/private:
Setup Apache default SSL enabled host:
Rewrite HTTP to HTTPS access:
Make sure to replace MY.DOMAIN.NAME with your FQDN in the commands above.
Improving Apache SSL Security settings:
Now restart Apache to reflect the new settings:
You can use the following script to test your certificate setup. Create a file called test_tls.sh and paste this content:
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.
Verto demo pages uses some videos to demonstrate the new video features. Let's get this environment set up:
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:
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:
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/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.
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)
cp /usr/src/freeswitch.git/debian/freeswitch-systemd.freeswitch.service /etc/systemd/system/freeswitch.service
Next, notify systemd to look for changes in its configuration:
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
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:
All the new APIs and variables of FreeSWITCH™ 1.6 are already documented on mod_conference page.
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.
These are the pre-defined layouts that comes with FreeSWITCH™: