Mastering FreeSWITCH

By Anthony Minessale II and Giovanni Maruzzelli

About This Book

• Forget the hassle - make FreeSWITCH work for you
• Discover how FreeSWITCH integrates with a range of tools and APIs
• From high availability to IVR development use this book to become more confident with this useful communication software

Who This Book Is For

If you are a systems admin, a VoIP engineer, a web programmer interested in WebRTC, or someone who uses FreeSWITCH on a regular basis, this book is for you. Whether you are a FreeSWITCH expert or are just getting started, this book will take your skills to the master level.

• Language: English
• Publisher: Packt Publishing
• Release date: Jul 29, 2016
• ISBN: 9781784395551

Book preview

Table of Contents

Mastering FreeSWITCH

Credits

About the Authors

About the Reviewers

Contributors

www.PacktPub.com

eBooks, discount offers, and more

Why subscribe?

Preface

What this book covers

What you need for this book

Who this book is for

Conventions

Reader feedback

Customer support

Downloading the example code

Errata

Piracy

Questions

1. Typical Voice Uses for FreeSWITCH

Understanding routing calls in FreeSWITCH

Wholesale (provider to providers)

Residential uses of FreeSWITCH

Routing with federated VoIP

Dialers/telemarketing

FreeSWITCH Products and Services

Business PBX services (hosted and on-premises)

Call centers

Value added services and games, prizes, and polls

Class 4 vs Class 5 operations (and SBCs)

WebRTC / web services / Internet-only services

Mobile over-the-top SIP

Development

Strict on output, broad on input

Very structured, very reusable techniques

Polyglot by vocation and destiny

Extreme scalability, from embedded to big irons

Born internationalist

Telcos internal integration (FreeSWITCH is the Perl of VoIP)

Rapid new services prototyping

Accounting and billing

Call Detail Records (CDRs)

Mod_nibblebill / CGrateS

Other billing options (open source - commercial)

Summary

2. Deploying FreeSWITCH

Network requirements

Understanding QoS

LANs, WANs, and peering

Testing with SIPp

Running scenarios

Load testing

Logging with FreeSWITCH

Call Detail Records

Monitoring

SNMP

SNMP and FreeSWITCH

Installation and configuration (on Linux)

Getting more information

Monitoring tools

Monitoring with Nagios

Monitoring with Cacti

HA deployment

Storage, network, switches, power supply

Virtualization

Load balancing and integration with Kamailio and OpenSIPS

In the Web world

In the FreeSWITCH world

DNS SRV records for geographical distribution and HA

Summary

3. ITSP and Voice Codecs Optimization

ITSPs – what they do

Routes (to numbers)

DIDs (aka DDIs) – numbers

Quality of routes

White, black, and grey

Codecs and bandwidth

Infrastructure capability

Various important features

Support, redundancy, high availability, and number portability

Summary

4. VoIP Security

Latest versions of it all

Default configuration is a demo

Change passwords

Lock all that's not trusted

Dropping root privileges (file permissions)

Fail2ban on all services

FreeSWITCH jail

SIP(S) and (S|Z)RTP

Encrypting SIP with TLS (SIPS)

Encrypting (S)RTP via SDES (key exchange in SDP)

Encrypting (S)RTP via ZRTP (key exchange in RTP)

New frontiers of VoIP encryption (WebRTC, WebSockets, DTLS)

Summary

5. Audio File and Streaming Formats, Music on Hold, Recording Calls

Traditional telephony codecs constrain audio

HD audio frontiers are pushed by cellphones, right now

FreeSWITCH audio, file, and stream formats

Audio file formats

MP3 and streaming

Music on Hold

Playing and recording audio files and streams

Recording and modifying prompts and audio files

Recording calls

Tapping audio

Summary

6. PSTN and TDM

OpenZap

FreeTDM

I/O modules

Signaling modules

ISDN signaling modules

Analog modules

MFC-R2

SS7

Cellular GSM / CDMA (ftmod_gsm)

FreeTDM installation

Wanpipe drivers

DAHDI drivers

LibPRI

Sangoma ISDN stack

OpenR2

LibWAT

Analog modules

Configuring FreeTDM

Wanpipe

DAHDI

FreeTDM library configuration

FreeSWITCH configuration

Operation

Outbound calls

Inbound calls

Debugging

Checking the physical layer

Enabling ISDN tracing

Audio tracing

Summary

7. WebRTC and Mod_Verto

WebRTC

Browsers are already out there, waitin'

Web Real-Time Communication is coming

Under the hood

Encryption – security

Beyond peer to peer – WebRTC to communication networks and services

WebRTC gateways and application servers

Which architecture? Legacy on the Web, or Web on the Telco?

FreeSWITCH accommodates them ALL

What is Verto (module and jslib)?

Configure mod_verto

Test with Communicator

Build Your Own Verto App

Summary

8. Audio and Video Conferencing

Conference basics

Conference.conf.xml (profiles, DTMF interaction, and so on)

Configuration sections logic

Profile

Caller-Controls group

Conference invocation, dialplan, channel variables

Outbound conference

Moderating and managing conferences – API

Video conference

Video conference configuration

Mux profile settings

Video conference screen layouts

Screen sharing

Screen sharing dialplan extension

Managing video conferences

Conference performances

Summary

9. Faxing and T38

What is Fax on PSTN?

How it works

What is Fax over IP?

Enter T38

T38 terminals and gateways

Fax and FreeSWITCH

The mod_spandsp configuration

mod_spandsp usage

Debugging faxes

How to maximize reliability of fax traffic

PDF to fax and fax to PDF

Fax to mail

HylaFax and FreeSWITCH

ITSPs and Real World Fax Support

Summary

10. Advanced IVR with Lua

Installing IVR

Structure of welcome.lua

Incoming call processing

Before answering

First voice menu

Second and third voice menus

Fourth menu – asynch! Nonblocking! Fun with threads!

After hangup

Utility functions

Summary

11. Write Your FreeSWITCH Module in C

What is a FreeSWITCH module?

Developing a module

Mod_Example outline

Mandatory functions

Load function

Runtime function

Shutdown function

Configuration using XML

Reacting to channel state changes

Receiving and firing events

Dialplan application

API command

Summary

12. Tracing and Debugging VoIP

What can go wrong?

What else can go wrong? (NAT problems)

Other things can go wrong too

SIP, RTP, SDP, RTCP, OH MY!

Tools

Firewall

FreeSWITCH as SIP self tracer

Tcpdum – the mother of all packet captures

ngrep – network grep

tshark – pure packet power

pcapsipdump

sngrep – the holy grail

Sipgrep, Ngrep on steroids for VoIP

Wireshark – the packet overlord

Audacity – audio Swiss army knife

SoX – audio format converter

Summary

13. Homer, Monitoring and Troubleshooting Your Communication Platform

What is Homer?

Installing Homer and the Capture Server

Feeding SIP signaling from FreeSWITCH to Homer

Searching signaling with Homer

Feeding SIP signaling, QoS, MOS and RTP/RTCP stats from CaptAgent to Homer

Correlating A-leg and B-leg

Feeding logs and events to Homer

Logs to Homer

FreeSWITCH events to Homer

Summary

Index

Mastering FreeSWITCH

---

Mastering FreeSWITCH

Copyright © 2016 Packt Publishing

All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews.

Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the authors, nor Packt Publishing, and its dealers and distributors will be held liable for any damages caused or alleged to be caused directly or indirectly by this book.

Packt Publishing has endeavored to provide trademark information about all of the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.

First published: July 2016

Production reference: 1260716

Published by Packt Publishing Ltd.

Livery Place

35 Livery Street

Birmingham B3 2PB, UK.

ISBN 978-1-78439-888-0

www.packtpub.com

Credits

Authors

Anthony Minessale II

Giovanni Maruzzelli

Reviewers

Ayobami Adewole

Brian West

Commissioning Editor

Amarabha Banerjee

Acquisition Editors

Neha Nagwekar

Rahul Nair

Content Development Editor

Kajal Thapar

Technical Editors

Pramod Kumavat

Mohita Vyas

Copy Editors

Dipti Mankame

Safis Editing

Project Coordinator

Shweta H. Birwatkar

Proofreader

Safis Editing

Indexer

Tejal Daruwale Soni

Graphics

Disha Haria

Production Coordinator

Arvindkumar Gupta

Cover Work

Arvindkumar Gupta

About the Authors

Anthony Minessale II is the primary author and founding member of the FreeSWITCH Open Source Soft-Switch. Anthony has spent around 20 years working with open source software. In 2001, Anthony spent a great deal of time contributing code to the Asterisk PBX and has authored numerous features and fixes to that project. In 2005, Anthony started coding a new idea for an open source voice application. The FreeSWITCH project was officially open to the public on January 1 2006. In the years that followed, Anthony has been actively maintaining and leading the software development of the FreeSWITCH project. Anthony also founded the ClueCon Technology Conference in 2005, and he continues to oversee the production of this annual event.

Anthony has been the author of several FreeSWITCH books, including FreeSWITCH 1.0.6, FreeSWITCH 1.2, FreeSWITCH Cookbook, and FreeSWITCH 1.6 Cookbook.

I'd like to thank my wife Jill and my kids, Eric and Abbi, who were in grade school when this project started and are now grown up. I'd also like to thank everyone who took the time to try FreeSWITCH and submit feedback. I finally thank my coauthor Giovanni Maruzzelli for working on this book.

Giovanni Maruzzelli (<[e-mail]>) is heavily engaged with FreeSWITCH. In it, he wrote a couple of endpoint modules, and he is specialized in industrial grade deployments and solutions. He's the curator and coauthor of FreeSWITCH 1.6 Cookbook (Packt Publishing, 2015).

He's a consultant in the telecommunications sector, developing software and conducting training courses for FreeSWITCH, SIP, WebRTC, Kamailio, and OpenSIPS.

As an Internet technology pioneer, he was the cofounder of Italia Online in 1996, which was the most popular Italian portal and consumer ISP. Also, he was the architect of its Internet technologies (www.italiaonline.it). Back then, Giovanni was the supervisor of Internet operations and the architect of the first engine for paid access to www.ilsole24ore.com, the most-read financial newspaper in Italy, and its databases (migrated from the mainframe). After that, he was the CEO of the venture capital-funded company Matrice, developing telemail unified messaging and multiple-language phone access to e-mail (text to speech). He was also the CTO of the incubator-funded company Open4, an open source managed applications provider. For 2 years, Giovanni worked in Serbia as an Internet and telecommunications investment expert for IFC, an arm of the World Bank.

Since 2005, he has been based in Italy, and he serves ICT and telecommunication companies worldwide.

I'd like to thank all people who made writing this book a challenging journey for me, all who helped, all who supported, all who gave me obstacles to overcome. This book has been brought to you by the knowledge that was socially cumulated by humans through the centuries, let's praise them. I finally want to thank my coauthor Anthony Minessale II for being so patient and Always See Everything.

About the Reviewers

Ayobami Adewole is a software engineer and technical consultant with experience spanning over 5 years. Ayobami has worked on mission critical systems; these include solutions for customer relationship management, land administration and geographical information systems, enterprise-level application integrations, and unified communication and software applications for the education and business sectors.

Ayobami is very passionate about VoIP technologies, and he continues to work on cutting-edge PBX solutions built on FreeSWITCH. In his spare time, he enjoys experimenting with new technologies. His blog is at http://ayobamiadewole.com.

My unending gratitude goes to my parents for instilling in me the culture of discipline and hard work.

Brian West is a founding member of the FreeSWITCH team. He has been involved in open source telephony since 2003. Brian was heavily involved in the Asterisk open source PBX Project as a Bug Marshal and developer. In 2005, Brian joined the initiative that eventually lead to the FreeSWITCH Open Source Soft-Switch. Today, Brian serves as the general manager of the FreeSWITCH project and keeps the software moving forward. Brian has countless skills as a developer, tester, manager, and technologist, and he fills a vital role in the FreeSWITCH Community.

Contributors

Moises Silva wrote the entire 6th chapter, PSTN and TDM.

The following people contributed substantially to this book:

Darren Schreiber

Benjamin Tietz

Russell Treleaven

Seven Du (Du Jinfang)

Muhammad Naseer Bhatti

Florent Krieg

Michael Jerris

Iwada Eja

Martyn Davies

Charles Bujold

Christian Bergamaschi

Alexandr Dubovikov

Lorenzo Mangani

Dan Christian Bogos

www.PacktPub.com

eBooks, discount offers, and more

Did you know that Packt offers eBook versions of every book published, with PDF and ePub files available? You can upgrade to the eBook version at www.PacktPub.com and as a print book customer, you are entitled to a discount on the eBook copy. Get in touch with us at for more details.

At www.PacktPub.com, you can also read a collection of free technical articles, sign up for a range of free newsletters and receive exclusive discounts and offers on Packt books and eBooks.

https://www2.packtpub.com/books/subscription/packtlib

Do you need instant solutions to your IT questions? PacktLib is Packt's online digital book library. Here, you can search, access, and readPackt's entire library of books.

Why subscribe?

Fully searchable across every book published by Packt

Copy and paste, print, and bookmark content

On demand and accessible via a web browser

Preface

Real Time Communication (RTC) is a huge sector, in perennial growth. It spans from VoIP to FAXes, from VideoConferencing to CallCenters, from PBXes to WebRTC, using many interworking technologies to connect the past with the future, legacy applications to new users and markets, creating and developing new ways for saving time and money, fostering collaboration, and enjoying leisure.

FreeSWITCH covers it all; it is the most reliable, scalable, and flexible open source foundation, and is used to build services and products worldwide.

This book adopts a professional approach and attitude, making available a wealth of cumulated actual industry experience in each aspect of FreeSWITCH implementation.

Written for professionals, each chapter contains the knowledge needed to frame and understand its domain, and a thorough explanation of FreeSWITCH wheels and knobs, best practices, and real-world solutions.

What this book covers

Chapter 1, Typical Voice Uses for FreeSWITCH, gives an overview and analyzes each sector where FreeSWITCH is in production.

Chapter 2, Deploying FreeSWITCH, shows best practices in FreeSWITCH installation and management.

Chapter 3, ITSP and Voice Codecs Optimization, suggests what to look for when choosing an Internet Telephony Service Provider, and how to get the best from DIDs, terminations, T38, and voice traffic.

Chapter 4, VoIP Security, exposes specific measures and tools used to keep FreeSWITCH protected from unwanted attention and hostile behavior.

Chapter 5, Audio File and Streaming Formats, Music on Hold, Recording Calls, covers all that is related to audio manipulation with FreeSWITCH, from prompts optimization to call center barge in, from playing live streams to HD codecs.

Chapter 6, PSTN and TDM, happens to be the first published, thorough explanation of all possible interactions between FreeSWITCH and Sangoma, Digium, and other compatible hardware for interfacing traditional and legacy telephony networks.

Chapter 7, WebRTC and Mod_Verto, provides a detailed overview of what WebRTC is and what techniques it entails, and then follows the development of a complete FreeSWITCH implementation.

Chapter 8, Audio and Video Conferencing, delves into the intricacies of setting and managing FreeSWITCH multiuser conferences both via SIP and WebRTC, with chatting, screen sharing, moderation, and advanced techniques for videocomposing the screen.

Chapter 9, Faxing and T38, explores all facsimile transmission aspects, and how to reliably fax via VoIP, send office documents, and integrate with mail.

Chapter 10, Advanced IVR with Lua, proves that it is not your average code snippet or more of the same example. Starting from the thoroughly described script techniques, it will be possible to build your industry-grade applications.

Chapter 11, Write Your FreeSWITCH Module in C, describes exactly what is needed to add or modify FreeSWITCH functionalities at the most fundamental level: interfacing your custom hardware, or your legacy OSS, or whatever.

Chapter 12, Tracing and Debugging VoIP, shows the art of SIP packet tracing, using the latest open source tools.

Chapter 13, Homer, Monitoring and Troubleshooting Your Communication Platform, walks through the operation of the most advanced VoIP/WebRTC monitoring and data warehousing solution: Homer. Once implemented, your support staff will reach Nirvana!

What you need for this book

For implementing the same solutions described in this book, you will need a (virtual) machine with Debian 8 (Jessie) 64 bit, and some Linux admin and networking knowledge.

Who this book is for

This book is for skilled professionals who want to jump right into the depths of FreeSWITCH, such as system administrators, programmers, and telephony technicians who want to augment their ability to create real-world VoIP and WebRTC products and services.

Conventions

In this book, you will find a number of styles of text that distinguish between different kinds of information. Here are some examples of these styles, and an explanation of their meaning.

Code words in text, database table names, folder names, filenames, file extensions, pathnames, dummy URLs, user input, and Twitter handles are shown as follows: Several built-in modules exist to assist in this, such as mod_lcr and mod_nibblebill, but the real beauty of FreeSWITCH's handling of calls in a wholesale scenario is due to four core building blocks.

A block of code is set as follows:

1.0 encoding=ISO-8859-1 ?>

sipp.dtd>

FreeSWITCH: call extension 1001>

500 start_rtd=mer>

When we wish to draw your attention to a particular part of a code block, the relevant lines or items are set in bold:

1.0 encoding=ISO-8859-1 ?>

sipp.dtd>

FreeSWITCH: call extension 1001>

 

500 start_rtd=mer>

New terms and important words are shown in bold.

Note

Warnings or important notes appear in a box like this.

Tip

Tips and tricks appear like this.

Reader feedback

Feedback from our readers is always welcome. Let us know what you think about this book—what you liked or may have disliked. Reader feedback is important for us to develop titles that you really get the most out of.

To send us general feedback, simply send an e-mail to <[e-mail]>, and mention the book title via the subject of your message.

If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, see our author guide on www.packtpub.com/authors.

Customer support

Now that you are the proud owner of a Packt book, we have a number of things to help you to get the most from your purchase.

Downloading the example code

You can download the example code files for this book from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.

You can download the code files by following these steps:

Log in or register to our website using your e-mail address and password.

Hover the mouse pointer on the SUPPORT tab at the top.

Click on Code Downloads & Errata.

Enter the name of the book in the Search box.

Select the book for which you're looking to download the code files.

Choose from the drop-down menu where you purchased this book from.

Click on Code Download.

You can also download the code files by clicking on the Code Files button on the book's webpage at the Packt Publishing website. This page can be accessed by entering the book's name in the Search box. Please note that you need to be logged in to your Packt account.

Once the file is downloaded, please make sure that you unzip or extract the folder using the latest version of:

WinRAR / 7-Zip for Windows

Zipeg / iZip / UnRarX for Mac

7-Zip / PeaZip for Linux

The code bundle for the book is also hosted on GitHub at https://github.com/PacktPublishing/Mastering-FreeSWITCH. We also have other code bundles from our rich catalog of books and videos available at https://github.com/PacktPublishing/. Check them out!

Errata

Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you find a mistake in one of our books—maybe a mistake in the text or the code—we would be grateful if you could report this to us. By doing so, you can save other readers from frustration and help us improve subsequent versions of this book. If you find any errata, please report them by visiting http://www.packtpub.com/submit-errata, selecting your book, clicking on the Errata Submission Form link, and entering the details of your errata. Once your errata are verified, your submission will be accepted and the errata will be uploaded to our website or added to any list of existing errata under the Errata section of that title.

To view the previously submitted errata, go to https://www.packtpub.com/books/content/support and enter the name of the book in the search field. The required information will appear under the Errata section.

Piracy

Piracy of copyright material on the Internet is an ongoing problem across all media. At Packt, we take the protection of our copyright and licenses very seriously. If you come across any illegal copies of our works, in any form, on the Internet, please provide us with the location address or website name immediately so that we can pursue a remedy.

Please contact us at <[e-mail]> with a link to the suspected pirated material.

We appreciate your help in protecting our authors, and our ability to bring you valuable content.

Questions

You can contact us at <[e-mail]> if you are having a problem with any aspect of the book, and we will do our best to address it.

Chapter 1. Typical Voice Uses for