E-Book
41,99 €

FreeSWITCH 1.8 E-Book

Anthony Minessale II

0,0

41,99 €

Sammeln Sie Punkte in unserem Gutscheinprogramm und kaufen Sie E-Books und Hörbücher mit bis zu 100% Rabatt.

Mehr erfahren.

Herausgeber: Packt Publishing
Kategorie: Wissenschaft und neue Technologien
Sprache: Englisch

Beschreibung

Build a robust, high-performance telephony system with FreeSWITCH

About This Book

Learn how to install and configure a complete telephony system of your own, from scratch, using FreeSWITCH 1.6
Get in-depth discussions of important concepts such as dialplan, user directory, NAT handling, and the powerful FreeSWITCH event socket
Discover expert tips from the FreeSWITCH experts, including the creator of FreeSWITCH—Anthony Minessale

Who This Book Is For

This book is for beginner-level IT professionals and enthusiasts who are interested in quickly getting a powerful telephony system up and running using FreeSWITCH. It would be good if you have some telephony experience, but it's not a must.

What You Will Learn

Build a complete WebRTC/SIP VoIP platform able to interconnect and process audio and video in real time
Use advanced PBX features to create powerful dialplans
Understand the inner workings and architecture of FreeSWITCH
Real time configuration from database and webserver with mod_xml_curl
Integrate browser clients into your telephony service
Use scripting to go beyond the dialplan with the power and flexibility of a programming language
Secure your FreeSWITCH connections with the help of effective techniques
Deploy all FreeSWITCH features using best practices and expert tips
Overcome frustrating NAT issues
Control FreeSWITCH remotely with the all-powerful event socket
Trace packets, check debug logging, ask for community and commercial help

In Detail

FreeSWITCH is an open source telephony platform designed to facilitate the creation of voice and chat-driven products, scaling from a soft-phone to a PBX and even up to an enterprise-class soft-switch. This book introduces FreeSWITCH to IT professionals who want to build their own telephony system.

This book starts with a brief introduction to the latest version of FreeSWITCH. We then move on to the fundamentals and the new features added in version 1.6, showing you how to set up a basic system so you can make and receive phone calls, make calls between extensions, and utilize basic PBX functionality.

Once you have a basic system in place, we'll show you how to add more and more functionalities to it. You'll learn to deploy the features on the system using unique techniques and tips to make it work better.

Also, there are changes in the security-related components, which will affect the content in the book, so we will make that intact with the latest version. There are new support libraries introduced, such as SQLite, OpenSS, and more, which will make FreeSWITCH more efficient and add more functions to it. We'll cover these in the new edition to make it more appealing for you.

Style and approach

This easy-to-follow guide helps you understand every topic easily using real-world examples of FreeSWITCH tasks. This book is full of practical code so you get a gradual learning curve.

Details

Sie lesen das E-Book in den Legimi-Apps auf:

Android

iOS

von Legimi
zertifizierten E-Readern

Seitenzahl: 459

Veröffentlichungsjahr: 2017

Bewertungen

0,0

Rezensionen(0 Rezensionen)

Leseprobe

< html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">

FreeSWITCH 1.8

VoIP and WebRTC with FreeSWITCH: The definitive source

Anthony Minessale II

Giovanni Maruzzelli

BIRMINGHAM - MUMBAI

FreeSWITCH 1.8

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 2017

Production reference: 1120717

Published by Packt Publishing Ltd.

Livery Place

35 Livery Street

Birmingham

B3 2PB, UK.

ISBN 978-1-78588-913-4

www.packtpub.com

Credits

Authors

Anthony Minessale II

Giovanni Maruzzelli

Copy Editor

Safis Editing

Reviewer

Brian West

Project Coordinator

Judie Jose

Acquisition Editor

Rahul Nair

Indexer

Aishwarya Gangawane

Content Development Editor

Abhishek Jadhav

Graphics

Kirk D'Penha

Technical Editor

Aditya Khadye

Manish Shanbhag

Production Coordinator

Aparna Bhagat

About the Authors

Anthony Minessale IIis 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, includingFreeSWITCH 1.0.6,FreeSWITCH 1.2,FreeSWITCH Cookbook,FreeSWITCH 1.6 Cookbook, andMastering FreeSWITCH

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 ([email protected]) is heavily engaged withFreeSWITCH. In it, he wrote a couple of endpoint modules, and he is specializedin industrial grade deployments and solutions. He's the curator and coauthor ofFreeSWITCH 1.6 Cookbook (Packt Publishing, 2015), and of Mastering FreeSWITCH (Packt Publishing, 2016)

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 Italia Online (IOL). Back then, Giovanni was the supervisor of Internet operations and the architect of the first engine for paid access toil Sole 24 Ore, 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 the Open Source VoIP and RTC Community (that's our ecosystem, where FreeSWITCH is thriving because of the others). The whole FreeSWITCH Community, and each single individual that day in and day out tests, documents, and helps each other in implementing FreeSWITCH. And I like to thank Tony, Brian, Mike, Ken, Italo, and Seven for the incredible efforts they put into FreeSWITCH, and for the incredible results those efforts bears for us all to enjoy. Thanks my guys! Anthony Minessale II, you get a special personal thank you for bearing your role with so much grace.

About the Reviewer

Brian Westis 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

www.PacktPub.com

For support files and downloads related to your book, please visit www.PacktPub.com. 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 [email protected] 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://www.packtpub.com/mapt

Get the most in-demand software skills with Mapt. Mapt gives you full access to all Packt books and video courses, as well as industry-leading tools to help you plan your personal development and advance your career.

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

Customer Feedback

Thanks for purchasing this Packt book. At Packt, quality is at the heart of our editorial process. To help us improve, please leave us an honest review on this book's Amazon page at https://www.amazon.com/dp/1785889133.

If you'd like to join our team of regular reviewers, you can e-mail us at [email protected]. We award our regular reviewers with free eBooks and videos in exchange for their valuable feedback. Help us be relentless in improving our products!

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

Downloading the color images of this book

Errata

Piracy

Questions

Architecture of FreeSWITCH

Real-time communication without mysteries

The FreeSWITCH design - modular, scalable, and stable

Important modules - Endpoint and Dialplan

Complex applications made simple

Voicemail

Multi-party audio/video conferencing

FreeSWITCH API commands (FSAPI)

The XML registry

Scripting language modules

The demo configuration

Summary

Building and Installation

Where to Install FreeSWITCH

Choice of Operating System

Linux

Windows

OS X (Mac)

*BSD

Packages or Source?

Installing FreeSWITCH

Debian 8 Jessie

From Packages

From Source

Windows

Summary

Test Driving the Example Configuration

Important concepts to understand

XML Configuration

Regular Expressions

Call Legs

IVRs, Interactive Voice Response (Systems)

Extensions, Contexts and Profiles

Variables

Caller profile Variables

"Normal" Variables

"Preprocessor" Variables

FS_CLI and Console, Controlling FreeSWITCH

Exiting from Console kills FreeSWITCH

Some useful CLI commands

Configure SIP and make the first calls in demo dialplan

Change demo example password

Configure Linphone on a Desktop

Configure a SNOM SIP "real" phone

Configure Linphone on Android

And now... Fun, fun, fun with the Demo Dialplan

9386, Funny Prompts

1000...1019, Phone to Phone Local Call

5000, Calling the Demo Example IVR

3000, Conference Call

Example Dialplan quick reference

Summary

User Directory, SIP, and Verto

User Directory concepts

AAA: Authentication, Authorization, Accounting

Exploring and Using the Demo Example User Directory

Domains and groups

Users

Adding a user to the demo example directory and dialplan

Adding a new user to the directory

Modifying the dialplan for the new user

Call to a Group

Voicemail

Communicate with the World via SIP Gateways and DIDs

SIP Gateway from Us to the ITSP to the World

SIP DID from World to the ITSP to Us

SIP and Verto Profiles, Dialplan Contexts, ITSPs

SIP Profiles

Dialplan Contexts

Verto Profiles and Dialplan Contexts

ITSPs

Summary

WebRTC, SIP, and Verto

WebRTC concepts

Encryption Everywhere

WebRTC in FreeSWITCH

WebRTC Signaling in FS: SIP and Verto

Why SIP and why Verto?

WebRTC Media Streaming in FS: SRTP

Installing and Configuring WebRTC in FS

Certificates

Installing and Configuring Apache or NginX for HTTPS serving

Apache

NginX

Configuring VERTO

Configuring SIP on WebRTC (WSS)

Writing WebRTC Clients

SIP and JavaScript

Verto and JavaScript

Verto Communicator, an Advanced WebRTC Client

WebRTC Rooms, both SIP and Verto Clients

Conference chat in WebRTC Rooms

FreeSWITCH Conferences

mod_sms and chatplan

Dialplan "chat_proto" extension

HTML

JavaScript

TODO

Summary

XML Dialplan

Forget all you know

Contexts

Default context

Public context

Features

Extensions

Conditions (and "patterns")

Call legs (channels)

Channel Variables

Regular Expressions

Actions and anti-actions

How dialplan processing works

Important dialplan applications

answer

bridge

hangup

ivr

play_and_get_digits

playback

set

sleep

transfer

Dialstring formats

SIP (sofia)

VERTO

Other dialstring formats

Originate Command

Summary

Phrase Macros and XML IVRs

Phrase Macros and Voice Prompts

Voice Prompts history

Sound files in FreeSWITCH

Sound files locations, sampling rate and fallbacks

Phrase Macros: Concatenating Sound files

macro name (pause)

input pattern

match - nomatch

action

Phrase Macros: Invocation, Patterns and Registers

Phrase Macro Invocation

Input Pattern and Registers

XML IVRs

IVR in demo config

XML voice menu fields

name

greet-long

greet-short

invalid-sound

exit-sound

timeout

inter-digit-timeout

max-failures

max-timeouts

digit-len

tts-engine

tts-voice

confirm-key

XML voice menu entries and actions

menu-exec-app

menu-play-sound

menu-sub

menu-back

menu-top

menu-exit

Nesting XML IVRs

Summary

Lua FreeSWITCH Scripting

Many scripting languages

Why Lua?

Basic Lua syntax

Lua and FreeSWITCH

freeswitch

freeswitch.Session and session

freeswitch.API

freeswitch.Dbh

freeswitch.Event

freeswitch.EventConsumer

freeswitch.IVRMenu

Lua scripting IVR Applications

playAndGetDigits

Syntax

Arguments

Behavior

XML demo IVR in Lua

Always checking session:ready()

Summary

Dialplan in Deep

Where are the previous Dialplan seasons?

XML Dialplan Recap

More about conditions

regex operator (multiple variables and/or expressions)

nested conditions

Pitfalls to avoid

Variables

Global variables

Time of Day, Day of Week, Holidays

Channel Variables

Channel Variables and Field shortcuts

Channel Variables and Caller Profile fields

Channel Variables and call setup

setting channel variables in dialstrings

setting channel variables on B-legs: export and nolocal

exporting variables to SIP custom (X-) Headers

API commands from Dialplan

FreeSWITCH string interpreter functions

cond, C-like "expr ? truevalue : falsevalue"

variables' substrings

db and hash: simple key/value stores

"Hotkeys", Listening, Barging

bind_meta_*, DTMFs to actions outside menus

eavesdrop (call barge)

eavesdrop DTMF commands

Dialplan Cookbook

Match by IP address and call a number

Match an IP address and Caller ID

Match a number and strip digits

Match a number, strip digits, and add a prefix

Call a registered device

Try party A, then party B

Route DIDs to extensions

Alternate outbound gateways

Multiple endpoints with enterprise originate

Summary

Dialplan, Directory, and ALL via XML_CURL and Scripts

mod_xml_curl rationale

mod_xml_curl configuration

mod_xml_curl: Caveats and Pitfalls

php/mysql setup for mod_xml_curl

Create and populate the Database

Setup NGINX and xmlhandler.php

mod_xml_curl configuration

Testing php/mysql setup for mod_xml_curl

Lua XML handler

lua xmlhandler script

lua.conf.xml

Lua xml_handler.lua testing

Summary

ESL - FreeSWITCH Controlled by Events

Event System Fundamentals

Event format - Headers and Body

Event Handling modules

mod_event_socket

mod_event_socket configuration

Reading and sending events via telnet

fs_cli

Event System Commands

api

bgapi

event

filter

filter delete

sendevent

exit

auth

log

nolog

nixevent

noevents

sendmsg

call-command

execute

hangup

Outbound Socket - call connects to you

ESL - Event Socket Library

ESL supported languages

ESL Reference

eslSetLogLevel

ESLevent Object

new

serialize

setPriority

getHeader

getBody

getType

addBody

addHeader

delHeader

firstHeader

nextHeader

ESLconnection Object

new

socketDescriptor

connected

getInfo

send

sendRecv

api

bgapi

sendEvent

recvEvent

recvEventTimed

filter

events

execute

executeAsync

setAsyncExecute

setEventLock

disconnect

ESL installation

ESL: Examples in Perl

Display Filtered Events

Use "api" and "bgapi"

Use "sendEvent"

Summary

HTTAPI - FreeSWITCH Asks Webserver Next Action

HTTAPI Rationale

HTTAPI dialplan

data

httapi_profile

url

method

HTTAPI document syntax

Work actions

playback

record

pause

speak

say

execute

sms

dial

recordCall

conference

hangup

break

log

continue

getVar

voicemail

vmname

exiting (param)

storing data across successive requests

mod_httapi configuration file

params

gateway-url

method

permissions

set-params

set-vars

get-vars

extended-data

extended-data longer than max CGI length

execute-apps

expand-vars

dial

dial-set-dialplan

dial-set-context

dial-set-cid-name

dial-set-cid-number

dial-full-originate

conference

conference-set-profile

HTTPAPI libraries for PHP and Python

The demo-ivr in PHP-HTTAPI

Summary

Conferencing and WebRTC Video-Conferencing

Conferencing Concepts

Conferencing Support in FreeSWITCH

Audio conferencing

Video conferencing

Audio Conferencing setup in FreeSWITCH

profiles

rate

caller-controls

auto-record

interval

energy-level

member-flags

conference-flags

tts-engine

tts-voice

max-members

caller-id-name

caller-id-number

comfort-noise

announce-count

suppress-events

sound-prefix

sounds

caller-controls

advertise

Video-WebRTC conferencing setup in FreeSWITCH

profiles additional video parameters

video-mode

video-layout-name

video-canvas-size

video-no-video-avatar

video-mute-banner

caller-controls additional video actions

member-flags additional video options

conference-flags additional video options

screen estate layouts

layout groups

FreeSWITCH conferencing operation

Conference Application (dialplan)

Controlling active conferences

Calling outbound into the conference

Verto Communicator and Video-WebRTC Conferencing

settings

participants list

participant GUI commands and chat

moderator GUI commands

screen sharing

Summary

Handling NAT

A brief introduction to NAT

Understanding the evolution of NAT

The four pitfalls of NAT

Demystifying NAT settings in FreeSWITCH

Making media flow

Advanced options and settings

FreeSWITCH behind NAT

FreeSWITCH speaks to the router

FreeSWITCH behind NAT, leaving the router alone

Additional ways to set the external addresses

Other creative uses of FreeSWITCH in a NAT situation

NAT and WebRTC (SOLVED)

Conclusion

Summary

VoIP Security

Network level protection

Separating interfaces and restricting traffic

Sample setup - simple

Sample setup - complex

VLANs

Intrusion detection

Registration and call attempts monitoring

Fail2Ban

Filter configurations

Jail configurations

Do not lock the good guys out!

Encryption in non-WebRTC SIP: Signaling and Media

Choosing between encryption options

Disabling SSLv3 and SSLv2

Certificates

"Real" certificates, from "real" CAs

Protecting signaling

Encryption with TLS

Protecting media

Encryption with SRTP

Enabling SRTP

Debugging SRTP

Encryption with ZRTP

Enabling ZRTP

Testing media SIP encryption

Protecting WebRTC SIP and VERTO Signaling and Media

Protecting passwords

Registration passwords as hashes

Voicemail passwords

Summary

Troubleshooting, Asking for Help, and Reporting Bugs

Troubleshooting FreeSWITCH

firewall rules and network issues

checking FreeSWITCH configuration and operation

fsctl loglevel 7

sofia global siptrace on

verto debug=10

sngrep: SIP dialogs visualization

tcpdump for saving net traffic in pcap files

Asking for Help

Read the documentation first!

confluence

books

mailing list archives

google

How to ask for Community Help

IRC

HipChat

mailing lists

Official Commercial Support and Consulting

Reporting Problems

don't report a bug on mailing list !

how to file a bug on Jira

ClueCon

Summary

Preface

This is the third book in a Trilogy: FreeSWITCH 1.6 Cookbook, Mastering FreeSWITCH, and yours truly, FreeSWITCH 1.8. Each one of them has its own role in FreeSWITCH's Universe. The call of this one you're reading is to be the reference and foundation, the exhaustive source of FreeSWITCH knowledge.

We've worked hard, we started from the efforts of our co-writers in FreeSWITCH 1.2 book (they were Michael S. Collins, Darren Schreiber and Raymond Chandler), we've updated, rewritten and written anew and we're now proud to introduce you to all you need to know about latest FreeSWITCH.

So much happened in the world of Real Time Communication and VoIP in the last years. And FreeSWITCH was leading innovation, implementation and interoperability in the industry: WebRTC, Video MCU, High Definition Audio, OPUS, VP8/9, JSON, Encryption and Security, you name it, FreeSWITCH was there.

We're about to announce FreeSWITCH 1.8: an evolutionary step from 1.6, that enhance performances and changes a lot of under the hood plumbing that will be the nervous system of The Next Big Things (TM) in FreeSWITCH Universe.

From an operation, administration and application programming point of view 1.8 is completely compatible with 1.6, and this book cover them both.

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 Example Configuration, provides a hands-on look at the powerful and feature-rich example FreeSWITCH configuration.

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

Chapter 5, WebRTC, SIP, and Verto, introduce WebRTC and its FreeSWITCH implementation, for both SIP and Verto signaling protocol, with an example web video conferencing application written for both protocols.

Chapter 6, XML Dialplan, explains the basic dialplan concepts and how to create and edit extensions to add advanced functionality to a FreeSWITCH install.

Chapter 7, Phrase Macros and XML IVRs, discusses how to create menus and sound phrases for interacting with callers as well as the useful Phrase Macro system.

Chapter 8, Lua FreeSWITCH Scripting, introduces the concept of advanced call handling using the lightweight scripting language Lua.

Chapter 9, Dialplan in Deep, builds upon the foundation laid in Chapter 6, and shows how to handle more challenging routing scenarios.

Chapter 10, Dialplan, Directory, and ALL via XML_CURL and Scripts, discusses how to configure and control FreeSWITCH dynamically, such as from a database.

Chapter 11, ESL - FreeSWITCH Controlled by Events, introduce Event System and Event Socket Library, how to tap into FreeSWITCH internal messaging bus to interact with calls in real time.

Chapter 12, HTTAPI - FreeSWITCH Asks Webserver Next Action, explains how to have FreeSWITCH to interrogate a webserver in real time at each step of a call interaction: a handy way to create IVRs.

Chapter 13, Conferencing and WebRTC Video-Conferencing, discusses how to create and manage audio and video conferences that allows for legacy, mainstream and WebRTC users to interact and collaborate. Also shows the special advanced features of Verto Communicator, our sleek Web Real Time Communication client.

Chapter 14, Handling NAT, provides much needed insight into understanding how NAT causes issues with SIP and how to work around them.

Chapter 15, VoIP Security, offers suggestions on how to secure VoIP communications from prying eyes as well as securing a FreeSWITCH server against various attacks.

Chapter 16, Troubleshooting, Asking for Help, and Reporting Bugs, shows how to find out what's wrong when you encounter a problem, how to interact with the wonderful FreeSWITCH community for getting help, and what to do when you think you've hit a bug.

What you need for this book

At the very least you will need a computer on which you can run FreeSWITCH. Typically this is a server although that isn't an absolute requirement. You will also need at least a couple SIP devices, be them softphones or desk phones, and a couple browsers as WebRTC clients.

Who this book is for

This book is for prospective FreeSWITCH administrators and application programmers as well as VoIP professionals 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 text styles 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: "We can see FreeSWITCH status information by issuing the stuts command at the FreeSWITCH console."

A block of code is set as follows:

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

<action application="voicemail"

data="check auth default ${domain_name}"/>

</condition></extension>

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

/usr/local/freeswitch/bin/fs_cli –x version

New terms and important words are shown in bold.

Warnings or important notes appear like this.

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 disliked. Reader feedback is important for us as it helps us develop titles that you will really get the most out of. To send us general feedback, simply [email protected], and mention the book's title in 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 at 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:

Hover the mouse pointer on the

SUPPORT

tab at the top.

Click on

Code Downloads & Errata

Enter the name of the book in the

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

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/FreeSWITCH-1.8. We also have other code bundles from our rich catalog of books and videos available at https://github.com/PacktPublishing/. Check them out!

Downloading the color images of this book

We also provide you with a PDF file that has color images of the screenshots/diagrams used in this book. The color images will help you better understand the changes in the output. You can download this file from https://www.packtpub.com/sites/default/files/downloads/FreeSWITCH1.8_ColorImages.pdf.

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/supportand enter the name of the book in the search field. The required information will appear under the Errata section.

Piracy

Piracy of copyrighted 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 [email protected] 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

If you have a problem with any aspect of this book, you can contact us [email protected], and we will do our best to address the problem.

Architecture of FreeSWITCH

Welcome to FreeSWITCH! If you are reading this, then you're interested in things such as real-time communication, WebRTC, telecommunications, and Voice over Internet Protocol (VoIP). FreeSWITCH is a complete application server and a flexible toolset, used worldwide to build advanced and future-proof communication applications. Before looking at the architecture of this powerful software, let's take a look at the world of telecommunications. This will help to put FreeSWITCH into perspective.

In this chapter, we will cover:

A communication double revolution

Advantages of FreeSWITCH

Endpoint and Dialplan modules

How FreeSWITCH simplifies complex applications such asvoicemail and video-conferences

Real-time communication without mysteries

Real-time communication (RTC) began with telephone during the second half of the 1800s, and almost immediately evolved into a big, worldwide, interconnected network of big companies and infrastructure.

Until a few years ago, telephony was a walled castle strictly guarded by huge corporations and almost nobody was able to completely understand how it was actually working. You got a chance to gain that esoteric knowledge by attending internal technical seminars and in-house schools, and even that knowledge was limited to the part of the system you were to work on (central office, last mile, PBX, and so on). Both the infrastructure carrying and routing the calls, and the applications answering and managing them, were ad hoc, rigid, not compatible with each other, and required huge investments.

Then two revolutions completely obliterated that old world. The first one was the VoIP telephony revolution, which brought an open protocol (SIP) to power, first in the application/PBX realm, and then in the infrastructure too. First to go was that steel box containing a proprietary PBX that could only be expanded by changing internal hardware cards made by that same company, serving only its own kind and model of hardware phones. It was substituted by a standard server with standard PC architecture, using off-the-shelf expansion cards, able to support any kind of standard-compliant phones. SIP then climbed from bottom to top, up to the very core of Big Telcos infrastructure. Today, all telecommunication infrastructures including those of Big Telcos and Carriers are running some version of the SIP protocol.

And the second revolution, which is ongoing right now and will take some more years to complete and bear fruits: WebRTC. This is a very misleading name; WebRTC does not require web pages and browsers at all. WebRTC is a set of standards for the encrypted interconnections of communication endpoints. This WebRTC standard happened to first be implemented in browsers.In the mean time it has become the mainstream way to communicate in the Internet of Things, spanning from smartphone apps to cars, lifts, shop cashiers, and point of sale.

Nowadays it's possible to build communication systems that outperform traditional voice, video, and conference services and offer advanced features for a relatively low cost. FreeSWITCH has been designed to make all of this easier, and we will go over its architecture to get a better understanding of how it works.

Don't be concerned if you don't grasp it all in one swoop. Learning takes time, especially RTC and 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 6, XML Dialplan. You will be surprised at how much your understanding of FreeSWITCH has improved. Then come back and skim it a third time after you have completed Chapter 10, Dialplan, Directory, and ALL via XML_CURL and Scripts; at this point, you will have a firm grasp of FreeSWITCH concepts. Give yourself time to digest all of these new concepts, and soon you will find that you are a skilled FreeSWITCH administrator.

Today, we live in an ecosystem of multiple RTC technologies, all coexisting at the same time: telephony systems (such as telephone switches and PBXs), the traditional analog phone (POTS lines or Plain Old Telephone Service), traditional telephone networks operated by carriers (PSTN or Public Switched Telephone Network), mobile phones (CDMA, GSM, LTE, and so on), faxes, WebRTC, smartphone apps, VoIP phones, and Enterprise systems.

FreeSWITCH's niche is right in the center of this ecosystem: it connects and accepts connections from all those technologies, it bridges and mixes them together, it provides interactive applications and services to users whatever their endpoint happens to be. FreeSWITCH is able to connect to external data services and to legacy in-house systems, to computer programs and business procedures. FreeSWITCH runs on Linux, Windows, and Mac OS X, as well as *BSD and Solaris. We have plenty of hardware choices, from big multiprocessor servers to Raspberry Pi. So, you can develop on your laptop, and then deploy on datacenter, or in an embedded device. Installing FreeSWITCH is discussed in detail in Chapter 2, Building and Installation.

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 to 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 "FreeSWITCH APIs". The functionality of FreeSWITCH can be extended with loadable modules, which tie a particular functionality or an external technology into the core.

FreeSWITCH has many different module types that surround the central core, like sensors and interfaces connect a robot brain to the external environment. The list includes the following:

Module type

Purpose

Endpoint

Telephone protocols such as SIP and PSTN lines.

Application

Performs a task such as playing audio or sending data.

Automated Speech Recognition(ASR)

Interfaces with speech recognition systems.

Chat

Bridges and exchanges various chat protocols.

Codec

Translates between audio formats.

Dialplan

Parses the call details and decides where to route the call.

Important modules - Endpoint and Dialplan

Endpoint modules are critically important and add some of the key features that make FreeSWITCH the powerful platform it is. The primary role of endpoint modules is to take certain common communication technologies and normalize them into a common abstract entity, which we refer to as a session. A session represents a connection between FreeSWITCH and a particular protocol. There are several Endpoint modules that come with FreeSWITCH, which implement several protocols such as SIP, H.323, Jingle, Verto, WebRTC, and some others. We will spend some time examining one of the more popular modules named mod_sofia.

Sofia-SIP (http://sofia-sip.sourceforge.net) is an open source project originally developed by Nokia, which provides a programming interface for the Session Initiation Protocol (SIP). FreeSWITCH developers have worked a lot evolving and fixing its original code base, further enhancing its robustness and features. We use our version of this library in FreeSWITCH (/usr/src/freeswitch/libs/sofia-sip) in a module named mod_sofia. This module registers to all the hooks in FreeSWITCH necessary to make an Endpoint module, and translates the native FreeSWITCH constructs into Sofia SIP constructs and vice versa. Configuration information is taken from FreeSWITCH configuration files, which makes for mod_sofia to load user-defined preferences and connection details. This allows FreeSWITCH to accept registrations from SIP phones and devices, register itself to other SIP servers such as service providers, send notifications, and provide services to the phones such as blinking lights and voicemail.

When a SIP audio/video call is established between FreeSWITCH and another SIP device, it will show up in FreeSWITCH as an active session. If the call is inbound, it can be transferred or bridged to IVR menus, hold music (and/or video), or to one or more extensions. Or, it can be bridged to a newly created outbound call, toward a PSTN subscriber, or a WebRTC browser, for example. Let's examine a typical scenario where an internal SIP phone registered as extension 2000 dials extension 2001 with the hope of establishing a call.

First, the SIP phone sends a call setup message to FreeSWITCH over the network (mod_sofia is listening for such messages). After receiving the message, mod_sofia in turn parses the relevant details, builds the abstract call session data structure the core understands, and passes that call into the core state machine in FreeSWITCH. The state machine (in the FreeSWITCH core) then puts the call into the ROUTING state (meaning looking for a destination).

Core's next step is to locate the Dialplan module based on the configuration data for the calling Endpoint. The default and most widely used Dialplan module is the XML Dialplan module. This module is designed to look up a list of instructions from the XML tree within FreeSWITCH's memory. The XML Dialplan module will parse a series of XML objects using regular expression pattern-matching.

As we are trying to call 2001, we are looking around for an XML extension where the destination_number field matches 2001. Also, let's remember the Dialplan is not limited to matching only a single extension. An incoming call can match more than one extension in the Dialplan, and in Chapter 6, XML Dialplan, you will get an expanded definition of the term extension. The XML Dialplan module builds a TODO list for the call. Each matched extension will have its actions added to the call's TODO list.

Assuming FreeSWITCH finds at least one extension with a matching condition, the XML Dialplan will insert instructions into the session object with the information it needs to try and connect the call to 2001 (the TODO list for this call). Once these instructions are in place, the state of the call session changes from ROUTING to EXECUTE, where the core drills down the list and executes the instructions piled during the ROUTING state. This is where the API comes into the picture.

Each instruction is added to the session in the form of an application name and a data argument that will be passed to that application. The one we will use in this example is the bridge application. The purpose of this application is to create another session with an outbound connection, then connect the two sessions for direct audio exchange. The argument we will supply to bridge will be user/2001, which is the easiest way to generate a call to an internal registered phone at extension 2001. A Dialplan entry for 2001 might look like this:

This extension is named example, and it has a single condition to match. If that condition is matched, it has a single application to execute. It can be understood as: If the caller dialed 2001, then establish a connection between the caller and the endpoint (that is, the phone) at 2001.

Once we have inserted the instructions into the TODO list for the session, the session's state will change to EXECUTE, and the FreeSWITCH core will start to use the data collected to perform the desired action(s). First, it will parse the list and find it must execute bridge on user/2001, then it will look up the bridge application and pass the user/2001 data to it. This will cause the FreeSWITCH core to create a new outbound session (that is, a call) of the desired type. Let's assume that user 2001 is registered to FreeSWITCH using a SIP phone. So user/2001 will resolve into a SIP dialstring, which will be passed to mod_sofia to ask it to create a new outbound session (toward user 2001's SIP phone).

If the setup for that new session is successful, there will be two sessions in the FreeSWITCH core, the new session and the original session (from the caller phone). The bridge application will take those two sessions and call the bridge function on it. This will make the audio and/or the video stream to flow in both directions once the person at extension 2001 answers the phone. If that user is unable to answer or is busy, a timeout (that is, a failure) would occur and a failure message will be sent back to the caller's phone. If a call is unanswered or an extension is busy, many reactions can be built in the Dialplan, including call forwarding or voicemail.

FreeSWITCH takes all the complexity of SIP and reduces it to a common (internal to its core) denominator. Then it reduces the complexity further by allowing us to use a single instruction in the Dialplan for connecting the phone at 2000 to the phone at 2001. If we also want to allow the phone at 2001 to be able to call the phone at 2000, we can add another entry in the Dialplan going the other way:

In this scenario, the Endpoint module (mod_sofia) turned incoming SIP call into a FreeSWITCH session and the Dialplan module (mod_dialplan_xml) turned XML into an extension. The bridge application (from mod_dptools) turned into a simple application/data pair the complex code of creating an outbound call and connecting its media streams. Both the Dialplan module and the application module interface are designed around FreeSWITCH sessions. Not only does the abstraction make life easier for us at the user level, it also simplifies the design of the application and the Dialplan because they can be made agnostic of the actual endpoint technology involved in the call. It is because of this abstraction that when tomorrow we will write a new Endpoint module to the 3D holographic communication network we will be able to reuse all the same applications and Dialplan modules. To the FreeSWITCH core, and to all of the FreeSWITCH modules, an holographic 3D call will then appear as just one more standard abstract session.

It is possible that you may want to work with some specific data provided by the Endpoint's native protocol. In SIP, for instance, there are several arbitrary headers as well as several other bits of interesting data inside the SIP packets. You may need or want to access those specific bits of information. We solve this problem by adding variables to the channel (that is, the part of the session structure that interact with the endpoint). Using channel variables, mod_sofia can create these arbitrary values as they are encountered in the SIP data, and you can retrieve them from the channel by variable name, in your Dialplan or application. Those were originally specific (and arbitrary) parts of the low-level SIP messages. However, the FreeSWITCH core just sees them as arbitrary channel variables that the core can ignore. There are also several special reserved channel variables that can influence the behavior of FreeSWITCH in many useful ways. If you have ever used a scripting language or configuration engine that uses variables (sometimes called attribute-value pairs or AVP, channel variables are pretty much the same concept. There is simply a name and a value that are passed to the channel, and the data is set.

The application interface for this, the set application, lets you set your own variables from the Dialplan:

This example is almost identical to the previous example, but instead of just placing the call, we first set the variable foo equal to the value bar. This variable will remain set throughout the call and can even be referenced at the end of the call in the detail logs (CDRs).

The more we build things by small pieces, the more the same underlying resources can be reused, making the whole system simpler to use. For example, the codec interface knows nothing else about the core, other than its own isolated world of encoding and decoding audio and video packets. Once a proper codec module has been written, it becomes usable by any Endpoint interface capable of carrying that codec in one of its media streams. This means that if we get a text-to-speech module working, we can generate synthesized speech on any and all Endpoints that FreeSWITCH supports. The TTS module becomes more useful because it can use more codecs; the codecs have become more useful because we added a new function that can take advantage of them. The same idea applies to applications. If we write a new application module, the existing endpoints will immediately be able to run and use that application.

Complex applications made simple

FreeSWITCH removes much of the complexity from advanced applications. Let's look at two examples of a more complex application.

Voicemail

The first application we will discuss is the voicemail application. This application is useful to add right after the bridge application as a second option, executed in cases where the call was not completed. We can do this with one of those special variables that we were discussing earlier. Let's look at a version of our last extension that also allows us to leave a voicemail:

Here, we see two uses of channel variables. First, we set hangup_after_bridge=true telling the system to hang up once we have have successfully bridged the call to another phone and to disregard the rest of the instructions. We are using the domain variable in brackets prefixed with a dollar sign, ${domain}. This is a special variable that defaults to the auto-configured domain name, which comes from the XML configuration.

In this example, we check if someone is dialing 2000. We then try to bridge the call to the user which endpoint is registered to extension 2000. If the call fails or if there is no answer (for example, if the bridge attempt has failed, so we do not execute the hangup after the bridge), we will continue to the next instruction, which is to execute the voicemail application. We provide the information the application needs to know (for example, which domain the voicemail belongs to) and which extension the voicemail is for, so the application knows how to handle the situation. Next, the voicemail application plays the pre-recorded greeting or generates one using the Say module's interface, which we briefly discussed earlier. It then plays short sound files one after each other to make a voice say something like The person at extension 2 0 0 0 is not available, please leave a message. Next, mod_voicemail prompts you to record a message. As an additional feature, if you are not convinced with your recording, you can listen and re-record it as many times as you wish. Once you finally commit, a FreeSWITCH MESSAGE_WAITING event is fired into the core event system queue, which is picked up by mod_sofia by way of an event consumer, and the event information is translated into SIP-in this case a SIP NOTIFY message that lets the SIP phone know that there is a message waiting. A blinking lamp (Message Waiting Indicator (MWI)) lights upon the receiving phone.

In this example, not only have we seen how to play a greeting, record a message, and transform it into a voicemail for a user, we have also met an important part of the FreeSWITCH core-the event system. The FreeSWITCH event system is not an additional module interface like the previous examples, it is a core engine feature that you can use to bind to named events and react accordingly when an event is received. In other words, throughout the FreeSWITCH core, there are events that are sent and received. Modules can bind to (that is listen for) various events. They can also fire events into the event engine; other modules can listen for those events. You can think of it as similar to other queuing systems such as RabbitMQ (actually, there is a module to interface the internal event system of a FreeSWITCH server with RabbitMQ, so you can integrate it into an enterprise queuing system, and/or having multiple FreeSWITCH servers be parts of the same big, distributed queue). As we discussed, the Sofia SIP module binds to (subscribes to) the event designated for MESSAGE_WAITING information. This allows our mod_voicemail module to interact with mod_sofia without either system having any knowledge about the other's existence. The event is blindly fired by mod_voicemail (fire and forget, in military parlance), intercepted (received, because has subscribed to) by mod_sofia, and translated into the proper SIP message-all courtesy of the event system.

There are several challenges with such a complex system of concatenating sounds when considering all of the possible languages it may need to support, as well as what files to play for the automated messages and how they are strung together. The Say module supplies a nice way to string files together, but it is limited to something specific, such as spelling a word, counting something, or saying a certain date. The way we overcome this is by defining a more complex layer on top of the Say module called Phrase Macros. Phrase Macros are a collection of XML expressions that pull out a list of arguments by matching a regular expression and executing a string of commands. This is very similar to how the XML Dialplan works, only custom-tailored for IVR scenarios. For example, when mod_voicemail asks you to record your message, rather than coding in the string of files to make it say what you want, the code just calls a phrase macro called voicemail_record_message. This arbitrary series of sound bites is defined in the Phrase Macro section in the XML configuration allowing us, the administrators, to edit the phrase without modifying the Voicemail IVR program:

When mod_voicemail executes the voicemail_record_message macro, it first matches the pattern, which, in this case, is to match everything, because this particular macro has no use for input (that is, whatever input you give it, is not used). If the macro did use the input, the pattern matching could be used to play different sound bites based on different input. Once a match is found, the XML match tag is parsed for action tags just like in our Dialplan example. This macro only plays the file vm-record_message.wav, but more complicated macros, like the ones for verifying your recording or telling you how many messages you have in your inbox, may use combinations of various Say actions and play many different audio files. Phrase Macros are discussed in detail in Chapter 6, XML Dialplan, and used extensively in Chapter 8, Lua FreeSWITCH Scripting.

Here too, we can see co-operation between various parts of FreeSWITCH architecture: the phrase system, the audio file, and the Say modules loaded by the core are used together to enable powerful functionalities. The Say modules are written specifically for a particular language or voice within a language. We can programmatically request to say the current time and have it translated into Spanish or Russian sounds by the proper Say module based on input variables. The Phrase Macro system is a great way to put a layer of abstraction into your code, which can be easily tweaked later by system administrators. For example, if we wanted to make a small IVR that asks us to dial a four-digit number, then reads it back and hangs up, we could make one macro called myapp_ask_for_digits and the other called myapp_read_digits. In our code, we would execute these macros by name-the former when it is time to ask for the digits and the later to read back the digits by passing in the value we entered. Once this is in place, a less-experienced individual (for example, a local administrator) could implement the XML files to play the proper sounds. She can use the Say modules to read back the number, and it should all be working in multiple languages with no further coding necessary. Voicemail is just one example of using FreeSWITCH as an application server. There are endless possibilities when we use FreeSWITCH to connect real-time communication with computers.

Multi-party audio/video conferencing

Another important feature of FreeSWITCH is delivered by the mod_conference conferencing module. The mod_conference provides dynamic conference rooms that can bridge together the audio and video from several users. It may mix video streams together, applying CG (computer graphics) transformations to them, such as composing a live feed of different conference participants together, over imposing a caption with the name and role to each users' video stream, sharing the screen of each participant computer (for example, a PowerPoint presentation), and so on. Also, a real-time chat can be added to the conference, so participants can exchange text messages out of band from the main audio/video stream. Obviously, this same module can also be used for plain regular audio conference calls.

Each new session that connects to the same conference room will join the others, and instantly be able to talk and see all of the other participants at the same time (as per the whim of the conference admin, who can choose who to display, who can talk, and so on). Using an example similar to the one we used for bridging to another phone, we can make an extension to join a conference room:

This is as simple as bridging a call, but with a conference application many callers can call the same extension (3000 in this case) and join the same conference room. If three people joined this conference and one of them decides to leave, the other two would still be able to continue their conversation.