FreeSWITCH 1.0.6

Table of Contents

FreeSWITCH 1.0.6

Credits

About the Authors

About the Reviewer

Preface

What this book covers

Who this book is for

Conventions

Reader feedback

Customer support

Errata

Piracy

Questions

1. Architecture of FreeSWITCH

A revolution has begun and secrets have been revealed

The FreeSWITCH design: modular, scalable, and stable

Important modules: Endpoint and Dialplan

Complex applications made simple

Voicemail

Multi-party conferencing

The FreeSWITCH API (FSAPI)

The XML registry

Language modules

The default configuration

Summary

2. Building and Installation

Setting up the FreeSWITCH environment

Operating system

Operating system prerequisites

Linux/Unix

Mac OS X

Windows

Text editors and XML

Downloading the source

Building from the latest code

Compiling FreeSWITCH for Linux/Unix/Mac OS X

Compiling FreeSWITCH

Step 1: Edit modules.conf

Step 2: Run configure script

Step 3: Run make and make install

Step 4: Edit modules.conf.xml

Step 5: Install sound and music files

Compiling FreeSWITCH for Windows

Building the solution with MSVC/MSVCEE

Starting FreeSWITCH

Running FreeSWITCH in the background

Summary

3. Test Driving the Default Configuration

Important concepts to understand

Putting FreeSWITCH to work

Controlling FreeSWITCH with the CLI

Configuring a SIP phone to work with FreeSWITCH

SIP settings

X-Lite softphone

Hard phones

Aastra phones

Polycom phones

Snom phones

Testing the default Dialplan

Test calls for a single phone

The Tetris extension

Echo test

Music on hold

Demonstration IVR

The Information application

Test calls for two or more phones

Calling another telephone

Parking a call

Calling a conference

Summary

4. SIP and the User Directory

Understanding the FreeSWITCH user directory

Working with the FreeSWITCH user directory

User features

Adding a user

Testing voicemail

Groups of users

Connecting to the world with gateways

Setting up a new gateway

Making calls

Receiving calls

Making calls without a gateway

SIP profiles and user agents

Summary

5. Understanding the XML Dialplan

FreeSWITCH XML Dialplan elements

Call legs and channel variables

Accessing channel variables

Regular expressions

Contexts

Default

Public

Features

Extensions

Conditions

Actions and anti-actions

How Dialplan processing works

Creating a new extension

Important Dialplan applications

bridge

playback

say

play_and_get_digits

ivr

sleep

answer

hangup

set

Dialstring formats

Summary

6. Using the Built-in XML IVR Engine

IVR engine overview

IVR XML configuration file

IVR menu definitions

greet-long

greet-short

invalid-sound

exit-sound

timeout

inter-digit-timeout

max-failures

max-timeouts

digit-len

tts-voice

tts-engine

confirm-key

IVR menu destinations

menu-exec-app

menu-exec-api

menu-play-sound

menu-back

menu-top

Routing calls to your IVR

Nesting IVRs

Using phrases with IVRs

Calling Phrase Macros

Phrase Macro examples: voicemail

Advanced routing

Summary

7. Building IVR Applications with Lua

Getting started with Lua

Running Lua scripts from the Dialplan

Basic Lua syntax

Building voice applications

Simple IVR—interacting with the caller

Conditions and looping

Advanced IVR concepts

Connecting to a database with LuaSQL

Making a web call with curl

Lua patterns versus regular expressions

Scripting tips

Summary

8. Advanced Dialplan Concepts

Dialplan overview

General Dialplan concepts

Contexts

Conditions

Actions

Putting it all together

XML Dialplan module review

Extensions

Conditions

Special condition variables

Inline execution

Actions and anti-actions

Pitfalls to avoid

XML Dialplan commands

Hunting versus executing

Utilizing variables

Testing variables with regular expressions

Caller profile fields

Channel variables

Channel variables and call setup

Global variables

Dialplan functions

Real-time condition evaluation

String conditioning

Database queries

SIP contact parameters

Set, export, and legs

Set versus export

Passing variables via call headers

XML Dialplan cookbook

Match by IP address and call a number

Match IP address and Caller ID

Match number and strip digits

Match number, strip digits, and add prefix

Call registered device

Try party A, then party B

Check for authenticated user

Route DIDs to extensions

Try a local extension, failback to voicemail

Alternate outbound gateways

Alternatives to XML

YAML

Asterisk Dialplan

Summary

9. Controlling FreeSWITCH Externally

General overview

Event system architecture

Event-based modules

mod_event_socket

Configuring event socket settings

Reading events

Minimum event information

Sending events

Events from the Dialplan

mod_event_multicast

Port/address

Bindings

TTL

mod_erlang_event

FreeSWITCH event system commands

auth

api

bgapi

event

divert_events

filter

filter delete

sendevent

sendmsg

execute

hangup

nomedia

log

nolog

noevents

Event-based applications

FreeSWITCH Console application

PHP Socket connections

Perl Socket connections

Event Socket Library

Supported libraries

ESLObject

eslSetLogLevel($loglevel)

ESLevent object

serialize([$format])

setPriority([$number])

getHeader($header_name)

getBody()

getType()

addBody($value)

addHeader($header_name, $value)

delHeader($header_name)

firstHeader()

nextHeader()

ESLconnection object

new($host, $port, $password)

new($fd)

socketDescriptor()

connected()

getInfo()

send($command)

sendRecv($command)

api($command[, $arguments])

bgapi($command[, $arguments])

sendEvent($send_me)

recvEvent()

recvEventTimed($milliseconds)

filter($header, $value)

events($event_type,$value)

execute($app[, $arg][, $uuid])

executeAsync($app[, $arg][, $uuid])

setAsyncExecute($value)

setEventLock($value)

disconnect()

Events in practice

Event Socket Library example: running a command

Examples of sending events to FreeSWITCH

Setting phone lights

Turn lights on

Turn lights off

Rebooting a phone

Requesting phone reconfiguration

Custom notify messages

Summary

10. Advanced Features and Further Reading

Multi-user conferencing

Configuration

Conference profiles

Caller controls

Advertise

Sending and receiving XMPP events

Connecting callers to the conference

Controlling active conferences

Nibblebill

Use cases

Billing (pre-pay)

Billing (post-pay)

Pay-per-call service billing

Maximum credit and/or fraud prevention

Design goals

Installation and configuration

Database tables

Creating the database table for PostgreSQL

Creating the database table for MySQL

Billing a call

Nibble method (default)

Alternative to nibble billings

Examples

Different rates per user

Single rate for all users

Different rates per area code

Different rates per service delivery

Hang up the call when the balance is depleted

Application/CLI/API commands

Check

Flush

Pause

Resume

Reset

Adding and deducting funds

Enabling session heartbeat

Bill based on B leg only

XML/Curl

Installation

Configuration

Bindings

HTTP requests

HTTP response

Optimization

Order of requests

Request/response examples

mod_sofia

ACL

Authorization

Voicemail request

Dialplan bindings

Request

Reply

Other bindings

General Not found reply

Debugging

Failing back

Alternative endpoints

Skype and GSM endpoints

Skype with mod_skypopen

GSM with mod_gsmopen

TDM with OpenZAP and FreeTDM

Configuration tools and related projects

Web GUIs

WikiPBX

FreePBX v3

FusionPBX

2600hz

Supporting libraries

Liverpie (Ruby)

FreeSWITCHeR (Ruby)

Librevox (Ruby)

EventSocket (Python/Twisted)

FSSocket (Perl)

Summary

A. The FreeSWITCH Online Community

The FreeSWITCH mailing lists

Talking in real-time via IRC

The FreeSWITCH main website and wiki

The main FreeSWITCH page—www.freeswitch.org

The FreeSWITCH Wiki page—wiki.freeswitch.org

The annual ClueCon open source developer conference

B. The History Of FreeSWITCH

Index

FreeSWITCH 1.0.6

FreeSWITCH 1.0.6

Copyright © 2010 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 2010

Production Reference: 1190710

Published by Packt Publishing Ltd.

32 Lincoln Road

Olton

Birmingham, B27 6PA, UK.

ISBN 978-1-847199-96-6

www.packtpub.com

Cover Image by Leisha Bryant (<leishabryant@gmail.com>)

Credits

Authors

Anthony Minessale

Michael S. Collins

Darren Schreiber

Reviewer

Justin Zimmer

Acquisition Editor

Usha Iyer

Development Editors

Neha Patwari

Tarun Singh

Technical Editors

Rupal J

Charumathi Sankaran

Copy Editors

Neha Shetty

Leonard D'Silva

Indexer

Tejal Daruwale

Editorial Team Leader

Aanchal Kumar

Project Team Leader

Priya Mukherji

Project Coordinator

Prasad Rai

Proofreader

Lynda Sliwoski

Graphics

Geetanjali Sawant

Production Coordinator

Shantanu Zagade

Cover Work

Shantanu Zagade

About the Authors

Anthony Minessale has been involved in telephony since 2003. Prior to that, he had spent over ten years as a CTO and platform designer for various companies during the height of the Internet revolution. He has spent over half a decade working as the creator and lead developer of the FreeSWITCH open source project and several years before that as a volunteer developer for the Asterisk open source PBX, and is a noted contributor of several features on that project as well.

Anthony is the creator and owner of FreeSWITCH Solutions LLC, responsible for the popular annual VoIP conference, ClueCon, held every summer in Chicago. Anthony also works for Barracuda Networks as the director of Engineering for the CudaTEL PBX appliance, a product he and his team handcrafted to work with FreeSWITCH as the telephony engine.

I would like to thank the awesome FreeSWITCH community for their dedication to our project and the invaluable feedback they provide on a daily basis. A really big thank you to Michael Collins and Darren Schreiber for helping to put this book together. I would also like to thank Brian West and Michael Jerris for helping make FreeSWITCH even possible with all the time they devote to making it work. Finally I would like to thank the original Asterisk community who inspired us all to relentlessly push forward in open source telephony.

Michael S. Collins is a telephony and open source software enthusiast. He is a PBX veteran, having worked as a PBX technician for five years and as the head of IT for a call center for more than nine years. Michael is an active member of the FreeSWITCH community. He currently works for Barracuda Networks, Inc.

I would like to thank, first and foremost, my wife, Lisa, my daughter, Katherine, and my son, Sean, who keep me going each day. I would also like to thank the many FreeSWITCH experts around the world who are so willing to answer technical questions: Michael Jerris, Moises Silva, Raymond Chandler, Mathieu Réné and more. I would especially like to thank Brian K. West for taking me under his wing and educating me in the ways of VoIP. Finally, I would like to say thank you to Anthony Minessale for authoring an amazing piece of software and inviting me to work with the core FreeSWITCH development team.

Darren A. Schreiber is helping pioneer the way to distributed cloud telephony solutions. He is the founder of the 2600hz Project, the TCAI project, and is the author of the latest version of FreePBX, a popular open source telephony management system. He has worked in Enterprise IT for over 15 years and has lead teams in successful projects in telecom, marketing, and web-based SaaS spaces. He has been a serious telephony enthusiast from a young age and has been working extensively with VoIP technologies for the past seven years. Darren graduated from Rensselaer with a degree in Computer Science and Business Entrepreneurship.

About the Reviewer

Justin Zimmer has worked in the contact center technology field for over twelve years. During that time, he has performed extensive software and computer telephony integrations using both PSTN and IP telephony. His current projects include system designs utilizing open source softswitches over more traditional proprietary hardware-based telephony, and the integration of these technologies into market-specific CRM products.

As the Technical Partner of Unicore Technologies out of Phoenix, AZ, Justin is developing hosted contact center solutions for the low-end market. Unicore's solutions present contact centers with low startup costs in a turbulent economy, and allows those centers to scale their business while maintaining a consistent and familiar user interface.

I'd like to thank the countless community contributors that have provided enough online documentation to make this book as accurate and helpful as possible. And I'd like to thank my wife Nicole for putting up with the extra hours spent reviewing this book, as well as my boys Micah, Caden, and daughter Keira for giving up some of their daddy-time for this project.

Preface

In 1999, the first shot of the telephony revolution was fired when the Asterisk PBX was released to the world. In the ensuing decade, open source telephony took the world by storm, lead by Asterisk and a host of other software packages such as OpenSER and YATE.

In 2006, an Asterisk developer named Anthony Minessale announced an ambitious project: a new telephony software engine, built from the ground up. Some thought this was crazy considering the wild success of the Asterisk platform. However, Anthony's vision was to create a telephony platform unlike any in existence—open source or proprietary. In May 2008, this new project reached a critical milestone with the release of FreeSWITCH 1.0.0.

Now that FreeSWITCH has been available for several years, some developers have migrated from Asterisk to FreeSWITCH. Others have added FreeSWITCH to an existing environment, having it work together with Asterisk, OpenSER, OpenSIPS, Kamailio, and other telephony applications.

Is FreeSWITCH right for you? The correct answer is, of course: It depends. When people ask the FreeSWITCH developers which telephony software they should use, the developers always reply with another correct answer: Use what works for your situation. To know the answer you will need to investigate further.

What FreeSWITCH is and what it is not

FreeSWITCH is a scalable softswitch. In practical terms this means that it can do anything a traditional PBX can do and much more. It can (and does) act as the core switching software for commercial carriers. It can scale up to handle thousands of simultaneous calls. It can also scale down to act as a simple softphone for your laptop or personal computer. It can also work in a cluster of servers.

FreeSWITCH is not a proxy server. If you need proxy server functionality, then consider OpenSIPS, Kamailio, or other similar software. FreeSWITCH is a back-to-back user agent or B2BUA. In this regard, it is similar to Asterisk and other IP PBX software.

Version and licensing

At the time of this writing this book, the FreeSWITCH developers were putting the finishing touches on FreeSWITCH version 1.2. While the examples presented in this book were specifically tested with version 1.0.6, they have also been confirmed to work with the latest FreeSWITCH development versions that form the basis of version 1.2. Do not be concerned about the fact that this material does not cover version 1.2—it certainly does. The FreeSWITCH user interface is very stable between versions; therefore, this text will be applicable for years to come.

FreeSWITCH is released under the Mozilla Public License (MPL) version 1.1. Since FreeSWITCH is a library that can be implemented in other software applications and projects, the developers felt it important to strike a balance between the extremely liberal BSD license and the so-called viral GPL. The MPL fits this paradigm well and allows businesses to create commercial products based on FreeSWITCH without licensing concerns.

However, what about using FreeSWITCH with GPL-based software? It should suffice if we said that the developers wanted to make sure that anyone, including proprietary and GPL-based software users, could use FreeSWITCH. The powerful event socket gives us this functionality—a simple TCP socket-based interface that allows an external program to control FreeSWITCH. Regardless of the license you may be using for your own software, you can still connect to a FreeSWITCH server without any licensing issues.

What this book covers

Chapter 1, Architecture of FreeSWITCH gives a brief, but thorough introduction to the underlying architecture of FreeSWITCH.

Chapter 2, Building and Installation shows how to download and install FreeSWITCH on Windows and Unix-like operating systems.

Chapter 3, Test Driving the Default Configuration provides a hands-on look at the powerful and feature-rich default FreeSWITCH configuration.

Chapter 4, SIP and the User Directory offers an introduction to the concept of users and the directory as well as brief look at SIP user agents.

Chapter 5, Understanding the XML Dialplan explains the basics of creating and editing Dialplan extensions to add advanced functionality to a FreeSWITCH install.

Chapter 6, Using the Built-In XML IVR Engine discusses how to create menus and sound phrases for interacting with callers.

Chapter 7, Building IVR Applications with Lua introduces the concept of advanced call handling using the lightweight scripting language Lua.

Chapter 8, Advanced Dialplan Concepts builds upon the foundation laid in Chapter 5 and shows how to handle more challenging routing scenarios.

Chapter 9, Controlling FreeSWITCH Externally introduces the incredibly powerful Event Socket and the Event Socket library that can be used to access and control a FreeSWITCH server.

Chapter 10, Advanced Features and Further Reading highlights some of the more powerful FreeSWITCH features like conferencing and offers some ideas on where to learn more about FreeSWITCH.

Appendix A, The FreeSWITCH Online Community gives a brief introduction to the worldwide online community and the tools used to stay in contact.

Appendix B, The History Of FreeSWITCH is a description of how FreeSWITCH came to be from one of the authors, Anthony Minessale.

Who this book is for

This book is for prospective FreeSWITCH administrators as well as enthusiasts who wish to learn more about how to set up, configure, and extend a FreeSWITCH installation. If you are already using FreeSWITCH, you will find that the information in this book compliments what you have already learned from your personal experience.

A solid understanding of basic networking concepts is very important. Previous experience with VoIP is not required, but will certainly make the learning process go faster.

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 are shown as follows:If there is a match, (and there always will be), then this macro plays the vm-goodbye.wav file.

A block of code is set as follows:

playbackdata=phrase:myphrase:arg1:arg2:arg3/>

play_and_get_digits data=2 5 3 7000 #phrase:myphrase:arg1 /invalid.wav my_var \d+/>

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):(.*)$ break_on_match=true>

      play-file data=voicemail/vm-you_have.wav/>

      say data=$1 method=pronouncedtype=items/>

      play-file data=voicemail/vm-$2.wav/>

      play-file data=voicemail/vm-message.wav/>

Any command-line input or output is written as follows:

freeswitch@localhost>version FreeSWITCH Version 1.0.6 (exported)

New terms and important words are shown in bold. Words that you see on the screen, in menus or dialog boxes for example, appear in the text like this: New users should join only the FreeSWITCH-users list, until they are comfortable with the project.

Note

Warnings or important notes appear in a box like this.

Note

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 <feedback@packtpub.com>, and mention the book title via the subject of your message.

If there is a book that you need and would like to see us publish, please send us a note in the SUGGEST A TITLE form on www.packtpub.com or e-mail .

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.

Note

Downloading the example code for the book

You can download the example code files for all Packt books you have purchased 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.

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 would 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/support, selecting your book, clicking on the let us know link, and entering the details of your errata. Once your errata are verified, your submission will be accepted and the errata will be uploaded on our website, or added to any list of existing errata, under the Errata section of that title. Any existing errata can be viewed by selecting your title from http://www.packtpub.com/support.

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 <copyright@packtpub.com> 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 <questions@packtpub.com> if you are having a problem with any aspect of the book, and we will do our best to address it.

Chapter 1. Architecture of FreeSWITCH

Welcome to FreeSWITCH! If you are reading this, then, undoubtedly, you are interested in things like telecommunications and Voice over Internet Protocol (VoIP). FreeSWITCH is revolutionary software created during a telephony revolution. Before looking at the architecture of this powerful software, let's take a look at the colorful world of telecommunications. This will help to put FreeSWITCH into perspective.

In this chapter, we cover:

A telephony revolution

Advantages of FreeSWITCH

Endpoint and Dialplan modules

How FreeSWITCH simplifies complex applications like Voicemail

A revolution has begun and secrets have been revealed

How and why the telephone works is a mystery to most people. It has been kept secret for years. We just plugged our phones into the wall and they worked, and most people do just that and expect it to work. The telephony revolution has begun, and we have begun to pry the secrets from the clutches of the legacy of the telephony industry. Now, everyday individuals like you and me are able to build phone systems that outperform traditional phone services and offer advanced features for relatively low cost. Some people even use FreeSWITCH to provide telephone services for making a profit. FreeSWITCH has been designed to make all of this easier, so we will go over the architecture to get a better understanding of how it works.

Do not be concerned if some of these concepts seem unnaturally abstract. Learning telephony takes time, especially VoIP. In fact, we recommend that you read this chapter more than once. Absorb as much as you can on the first pass, then come back after you complete Chapter 5, Understanding the XML Dialplan. You will be surprised at how much your understanding of VoIP and FreeSWITCH has improved. Then come back and skim it a third time after you have completed Chapter 9, Controlling FreeSWITCH Externally, at this point, you will have a firm grasp of VoIP and FreeSWITCH concepts. Give yourself plenty of time to digest all of these strange new concepts, and soon you will find that you are a skilled FreeSWITCH administrator. If you keep at it, you will be rewarded with a meaningful understanding of this strange and wonderful world we call telephony.

Telephones and the systems are very complicated and have evolved over the years into several varieties. The most popular type of phone in the U.K. and the U.S. is the traditional analog phone, which we affectionately refer to as POTS lines or Plain Old Telephone Service. From the traditional Ma Bell phone up to the long-range cordless phones that most of us have today, one thing has remained the same—the underlying technology. In the last 10-15 years, there has been a convergence of technology between computers and telephones that has produced a pair of affordable alternatives to POTS lines—Mobile phones and VoIP phones (also called Internet Phones).

FreeSWITCH fits into this big tangled mess of various telephone technologies by bridging them together, so that they can communicate despite being otherwise completely incompatible. FreeSWITCH also bridges telephone calls with computer programs that you can write yourself, and controls what happens in ways like never before. FreeSWITCH is software that runs on Windows and several UNIX varieties such as Mac OS X, Linux, Solaris, and BSD. This means you can install FreeSWITCH on your home PC or even a high-end server and use it to process phone calls. Installing FreeSWITCH is discussed in detail in Chapter 2, Building and Installation. We will be doing this as soon as we review the basic architecture.

The FreeSWITCH design: modular, scalable, and stable

The design goal of FreeSWITCH is to provide a modular, scalable system around a stable switching core, and provide a robust interface for developers to add to and control the system. Various elements in FreeSWITCH are independent of each other and do not have much knowledge about how the other parts are working, other than what is provided in what are called ''exposed functions''. The functionality of FreeSWITCH can also be extended with loadable modules, which tie a particular external technology into the core.

FreeSWITCH has many different module types that revolve around the central core, much like satellites orbiting a planet. The list includes: