Asterisk

Asterisk™

: The Future of Telephony

Other resources from O’Reilly

Related titles Ethernet: The Definitive

Guide

Switching to VoIP

T1: A Survival Guide

TCP/IP Network

Administration

VoIP Hacks™

oreilly.com oreilly.com is more than a complete catalog of O’Reilly books.

You’ll also find links to news, events, articles, weblogs, sample

chapters, and code examples.

oreillynet.com is the essential portal for developers interested in

open and emerging technologies, including new platforms, pro￾gramming languages, and operating systems.

Conferences O’Reilly brings diverse innovators together to nurture the ideas

that sparkrevolutionary industries. We specialize in document￾ing the latest tools and systems, translating the innovator’s

knowledge into useful skills for those in the trenches. Please

visit conferences.oreilly.com for our upcoming events.

Safari Bookshelf (safari.oreilly.com) is the premier online refer￾ence library for programmers and IT professionals. Conduct

searches across more than 1,000 books. Subscribers can zero in

on answers to time-critical questions in a matter of seconds.

Read the books on your Bookshelf from cover to cover or sim￾ply flip to the page you need. Try it today for free.

,roadmap_asterisk.21163 Page i Tuesday, August 14, 2007 1:43 PM

SECOND EDITION

Asterisk™

: The Future of Telephony

Jim Van Meggelen, Leif Madsen, and Jared Smith

Beijing Cambridge Farnham Köln Paris Sebastopol Taipei Tokyo

Asterisk™: The Future of Telephony, Second Edition

by Jim Van Meggelen, Leif Madsen, and Jared Smith

Copyright © 2007, 2005 O’Reilly Media, Inc. All rights reserved.

Printed in the United States of America.

Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472

O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions

are also available for most titles (http://safari.oreilly.com). For more information, contact our corporate/

institutional sales department: (800) 998-9938 or [email protected].

Editor: Mike Loukides

Copy Editor: Sanders Kleinfeld

Production Editor: Laurel R.T. Ruma

Proofreader: Tolman Creek Design

Indexer: Joe Wizda

Cover Designer: Karen Montgomery

Interior Designer: David Futato

Illustrators: Robert Romano and Jessamyn Read

Printing History:

June 2005: First Edition.

August 2007: Second Edition.

Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of

O’Reilly Media, Inc. Asterisk™: The Future of Telephony, the image of starfish, and related trade dress

are trademarks of O’Reilly Media, Inc. Asterisk™ is a trademark of Digium, Inc.

Asterisk: The Future of Telephony is published under the Creative Commons “Commons Deed” license

(http://creativecommons.org/licenses/by-nc-nd/2.5/ca/).

While every precaution has been taken in the preparation of this book, the publisher and authors assume

no responsibility for errors or omissions, or for damages resulting from the use of the information con￾tained herein.

TM

This book uses RepKover™, a durable and flexible lay-flat binding.

ISBN-10: 0-596-51048-9

ISBN-13: 978-0-596-51048-0

[M]

This book is dedicated to Rich Adamson

(1947–2006).

Thanks for showing us the meaning of

community.

Table of Contents

Foreword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

1. A Telephony Revolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

VoIP: Bridging the Gap Between Traditional and Network Telephony 2

Massive Change Requires Flexible Technology 3

Asterisk: The Hacker’s PBX 5

Asterisk: The Professional’s PBX 5

The Asterisk Community 6

The Business Case 8

This Book 9

2. Preparing a System for Asterisk . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Server Hardware Selection 13

Environment 21

Telephony Hardware 25

Types of Phones 29

Linux Considerations 34

Conclusion 34

3. Installing Asterisk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

What Packages Do I Need? 38

Obtaining the Source Code 40

Menuselect 42

Compiling Zaptel 43

Compiling libpri 47

Compiling Asterisk 48

Installing Additional Prompts 50

Common Compiling Issues 51

Loading Asterisk and Zaptel Quickly 54

Loading Zaptel Modules Without Scripts 55

vii

Loading libpri Without Script 57

Starting Asterisk Without Scripts 57

Directories Used by Asterisk 59

AsteriskNOW™ 62

Conclusion 67

4. Initial Configuration of Asterisk . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

What Do I Really Need? 70

Working with Interface Configuration Files 71

Setting Up the Dialplan for Some Test Calls 73

FXO and FXS Channels 73

Configuring an FXO Channel for a PSTN Connection 75

Configuring an FXS Channel for an Analog Telephone 79

Configuring SIP Telephones 81

Connecting to a SIP Service Provider 97

Connecting Two Asterisk Boxes Together via SIP 101

Configuring an IAX Softphone 106

Connecting to an IAX Service Provider 110

Connecting Two Asterisk Boxes Together via IAX 111

Using Templates in Your Configuration Files 115

Debugging 116

Conclusion 117

5. Dialplan Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Dialplan Syntax 119

A Simple Dialplan 124

Building an Interactive Dialplan 127

Conclusion 144

6. More Dialplan Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Expressions and Variable Manipulation 145

Dialplan Functions 148

Conditional Branching 149

Voicemail 153

Macros 157

Using the Asterisk Database (AstDB) 160

Handy Asterisk Features 163

Conclusion 165

7. Understanding Telephony . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Analog Telephony 167

Digital Telephony 170

The Digital Circuit-Switched Telephone Network 180

viii | Table of Contents

Packet-Switched Networks 184

Conclusion 184

8. Protocols for VoIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

The Need for VoIP Protocols 186

VoIP Protocols 187

Codecs 193

Quality of Service 197

Echo 200

Asterisk and VoIP 202

VoIP Security 204

Conclusion 206

9. The Asterisk Gateway Interface (AGI) . . . . . . . . . . . . . . . . . . . . 207

Fundamentals of AGI Communication 207

Writing AGI Scripts in Perl 210

Creating AGI Scripts in PHP 214

Writing AGI Scripts in Python 219

Debugging in AGI 223

Conclusion 225

10. Asterisk Manager Interface (AMI) and Adhearsion . . . . . . . . 227

The Manager Interface 227

The Flash Operator Panel 231

Asterisk Development with Adhearsion 231

11. The Asterisk GUI Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Why a GUI for Asterisk? 245

What Is the GUI? 246

Architecture of the Asterisk GUI 248

Installing the Asterisk GUI 249

Developing for the Asterisk GUI 251

12. Relational Database Integration . . . . . . . . . . . . . . . . . . . . . . . . . . 263

Introduction 263

Installing the Database 263

Installing and Configuring ODBC 265

Using Realtime 268

Storing Call Detail Records 272

Getting Funky with func_odbc: Hot-Desking 274

ODBC Voicemail 286

Conclusion 291

Table of Contents | ix

13. Managing Your Asterisk System . . . . . . . . . . . . . . . . . . . . . . . . . 293

Call Detail Recording 293

Managing Logs 295

Running Asterisk As a Non-root User 295

Customizing System Prompts 298

Music on Hold 299

Conclusion 302

14. Potpourri . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

Festival 303

Call Files 306

DUNDi 307

Alternative Voicemail Storage Methods 312

Asterisk and Jabber (XMPP) 315

Conclusion 316

15. Asterisk: The Future of Telephony . . . . . . . . . . . . . . . . . . . . . . . . 317

The Problems with Traditional Telephony 317

Paradigm Shift 320

The Promise of Open Source Telephony 320

The Future of Asterisk 327

A. VoIP Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

B. Application Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

C. AGI Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449

D. Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461

E. Asterisk Dialplan Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493

F. Asterisk Manager Interface Actions . . . . . . . . . . . . . . . . . . . . . . . 515

G. An Example of func_odbc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557

x | Table of Contents

Foreword

Once upon a time, there was a boy

...with a computer

...and a phone.

This simple beginning begat much trouble!

It wasn’t that long ago that telecommunications, both voice and data, as well as soft￾ware, were all proprietary products and services, controlled by one select club of

companies that created the technologies, and another select club of companies who

used the products to provide services. By the late 1990s, data telecommunications had

been opened by the expansion of the Internet. Prices plummeted. New and innovative

technologies, services, and companies emerged. Meanwhile, the work of free software

pioneers like Richard Stallman, Linus Torvalds, and countless others was culminating

in the creation of a truly open software platform called Linux (or GNU/Linux). How￾ever, voice communications, ubiquitous as they were, remained proprietary. Why?

Perhaps it was because voice on the old public telephone network lacked the glamor

and promise of the shiny new World Wide Web. Or, perhaps it was because a telephone

just wasn’t as effective at supplying adult entertainment. Whatever the reason, one

thing was clear. Open source voice communications was about as widespread as open

source copy protection software.

Necessity (and in some cases simply being cheap) is truly the mother of invention. In

1999, having started Linux Support Services to offer free and commercial technical

support for Linux, I found myself in need (or at least in perceived need) of a phone

system to assist me in providing 24-hour technical support. The idea was that people

would be able to call in, enter their customer identity, and leave a message. The system

would in turn page a technician to respond to the customer’s request in short order.

Since I had started the company with about $4,000 of capital, I was in no position to

be able to afford a phone system of the sort that I needed to implement this scenario.

Having already been a Linux user since 1994, and having already gotten my feet wet in

open source software development by starting l2tpd, Gaim, and cheops, and in the

complete absence of anyone having explained the complexity of such a task, I decided

that I would simply make my own phone system using hardware borrowed from

xi

Adtran, where I had worked as a co-op student. Once I got a call into a PC, I fantasized,

I could do anything with it. In fact, it is from this conjecture that the official Asterisk

motto (which any sizable, effective project must have) is derived:

It’s only software!

For better or worse, I rarely think small. Right from the start, it was my intent that

Asterisk would do everything related to telephony. The name “Asterisk” was chosen

because it was both a key on a standard telephone and also the wildcard symbol in

Linux (e.g., rm -rf *).

So, in 1999, I had a free telephony platform I’d put out on the Web and I went about

my business trying to eke out a living at providing Linux technical support. However,

by 2001, as the economy was tanking, it became apparent that Linux Support Services

might do better by pursuing Asterisk than general-purpose Linux technical support.

That year, we would make contact with Jim “Dude” Dixon of the Zapata Telephony

project. Dude’s exciting work was a fantastic companion to Asterisk and provided a

business model for us to start pursuing Asterisk with more focus. After creating our

first PCI telephony interface card in conjunction with Dude, it became clear that “Linux

Support Services” was not the best name for a telephony company, and so we changed

the name to “Digium,” which is a whole other story that cannot be effectively conveyed

in writing. Enter the expansion of Voice over IP (VoIP) with its disruptive transition of

voice from the old, circuit-switched networks to new IP-based networks, and things

really started to take hold.

Now, as we’ve already covered, clearly most people don’t get very excited about tele￾phones. Certainly, few people could share my excitement the moment I heard a dial

tone coming from a phone connected to my PC. However, those who do get excited

about telephones get really excited about telephones. And facilitated by the Internet,

this small group of people were now able to unite and apply our bizarre passions to a

common, practical project for the betterment of many.

To say that telecom was ripe for an open source solution would be an immeasurable

understatement. Telecom is an enormous market due to the ubiquity of telephones in

work and personal life. The direct market for telecom products has a highly technical

audience that is willing and able to contribute. People demand their telecom solutions

be infinitely customizable. Proprietary telecom is very expensive. Creating Asterisk was

simply the spark in this fuel-rich backdrop.

Asterisk sits at the apex of a variety of transitions (proprietary → open source; circuit

switched → VoIP; voice only → voice, video, and data; digital signal processing → host

media processing; centralized directory → peer to peer) while easing those transitions

by providing bridges back to the older ways of doing things. Asterisk can talk to any￾thing from a 1960s-era pulse-dial phone to the latest wireless VoIP devices, and provide

features from simple tandem switching all the way to Bluetooth presence and DUNDi.

Most important of all, though, Asterisk demonstrates how a community of motivated

people and companies can work together to create a project with a scope so significant

xii | Foreword

that no one person or company could have possibly created it on its own. In making

Asterisk possible, I particularly would like to thank Linus Torvalds, Richard Stallman,

the entire Asterisk community, and whoever invented Red Bull.

So where is Asterisk going from here? Think about the history of the PC. When it was

first introduced in 1980, it had fairly limited capabilities. Maybe you could do a spread￾sheet, maybe do some word processing, but in the end, not much. Over time, however,

its open architecture led to price reductions and new products allowing it to slowly

expand its applications, eventually displacing the mini computer, then the mainframe.

Now, even Cray supercomputers are built using Linux-based x86 architectures. I an￾ticipate that Asterisk’s future will look very similar. Today, there is a large subset of

telephony that is served by Asterisk. Tomorrow, who knows what the limit might be?

So, what are you waiting for? Read, learn, and participate in the future of open tele￾communications by joining the Asterisk revolution!

—Mark Spencer

Foreword | xiii