This is a book for anyone who is new to Asterisk™.
Asterisk is an open source, converged telephony platform, which is designed primarily
to run on Linux. Asterisk combines more than 100 years of telephony knowledge into
a robust suite of tightly integrated telecommunications applications. The power of Asterisk
lies in its customizable nature, complemented by unmatched standards compliance.
No other PBX can be deployed in so many creative ways.
Applications such as voicemail, hosted conferencing, call queuing and agents, music
on hold, and call parking are all standard features built right into the software. Moreover,
Asterisk can integrate with other business technologies in ways that closed,
proprietary PBXes can scarcely dream of.
Asterisk can appear quite daunting and complex to a new user, which is why documentation
is so important to its growth. Documentation lowers the barrier to entry and
helps people contemplate the possibilities.
Produced with the generous support of O’Reilly Media, Asterisk:
The Future of Telephony was inspired by the work started by the Asterisk Documentation
Project. We have come a long way, and this book is the realization of a desire to
deliver documentation that introduces the most fundamental elements of Asterisk—
the things someone new to Asterisk needs to know. It is the first volume in what we
are certain will become a huge library of knowledge relating to Asterisk.
This book was written for, and by, the Asterisk community.
Audience
This book is for those new to Asterisk, but we assume that you’re familiar with basic
Linux administration, networking, and other IT disciplines. If not, we encourage you
to explore the vast and wonderful library of books that O’Reilly publishes on these
subjects. We also assume you’re fairly new to telecommunications, both traditional
switched telephony and the new world of Voice over IP.
xv
Organization
The book is organized into these chapters:
Chapter 1, A Telephony Revolution
This is where we chop up the kindling and light the fire. Asterisk is going to change
the world of telecom, and this is where we discuss our reasons for that belief.
Chapter 2, Preparing a System for Asterisk
Covers some of the engineering considerations you should have in mind when
designing a telecommunications system. Much of this material can be skipped if
you want to get right to installing, but these are important concepts to understand,
should you ever plan on putting an Asterisk system into production.
Chapter 3, Installing Asterisk
Covers the obtaining, compiling, and installation of Asterisk.
Chapter 4, Initial Configuration of Asterisk
Describes the initial configuration of Asterisk. Here we will cover the important
configuration files that must exist to define the channels and features available to
your system.
Chapter 5, Dialplan Basics
Introduces the heart of Asterisk, the dialplan.
Chapter 6, More Dialplan Concepts
Goes over some more advanced dialplan concepts.
Chapter 7, Understanding Telephony
Taking a break from Asterisk, this chapter discusses some of the more important
technologies in use in the Public Telephone Network.
Chapter 8, Protocols for VoIP
Following the discussion of legacy telephony, this chapter discusses Voice over
Internet Protocol.
Chapter 9, The Asterisk Gateway Interface (AGI)
Introduces one of the more amazing components, the Asterisk Gateway Interface.
Using Perl, PHP, and Python, we demonstrate how external programs can be used
to add nearly limitless functionality to your PBX.
Chapter 10, Asterisk Manager Interface (AMI) and Adhearsion
Describes how external applications can connect to Asterisk to manipulate or
monitor various aspects of the system. Also included in this chapter is a gentle
introduction to the Adhearsion framework.
Chapter 11, The Asterisk GUI Framework
The Asterisk GUI Framework, new in Asterisk 1.4, is a framework system that
allows web developers to create graphical interfaces with minimal interference to
the standard configuration files.
xvi | Preface
Chapter 12, Relational Database Integration
Walks you through setting up Asterisk to work with ODBC databases.
Chapter 13, Managing Your Asterisk System
Discusses issues regarding how to best manage your Asterisk phone system, including
CDR, logs, and prompts.
Chapter 14, Potpourri
Briefly covers what is, in fact, a rich and varied cornucopia of incredible features
and functions—all part of the Asterisk phenomenon.
Chapter 15, Asterisk: The Future of Telephony
Predicts a future where open source telephony completely transforms an industry
desperately in need of a revolution.
Appendix A, VoIP Channels
Appendix B, Application Reference
Appendix C, AGI Reference
Appendix D, Configuration Files
Appendix E, Asterisk Dialplan Functions
Appendix F, Asterisk Manager Interface Actions
Appendix G, An Example of func_odbc
Software
This book is focused on documenting Asterisk Version 1.4; however, many of the conventions
and information in this book are version-agnostic. Linux is the operating
system we have run and tested Asterisk on, with a leaning toward Red Hat syntax. We
decided that while Red Hat–based distributions may not be the preferred choice of
everyone, their layout and utilities are nevertheless familiar to many experienced Linux
administrators.
Conventions Used in This Book
The following typographical conventions are used in this book:
Italic
Indicates new terms, URLs, email addresses, filenames, file extensions, pathnames,
directories, and Unix utilities.
Constant width
Indicates commands, options, parameters, and arguments that must be substituted
into commands.
Preface | xvii
Constant width bold
Shows commands or other text that should be typed literally by the user. Also used
for emphasis in code.
Constant width italic
Shows text that should be replaced with user-supplied values.
[ Keywords and other stuff ]
Indicates optional keywords and arguments.
{ choice-1 | choice-2 }
Signifies either choice-1 or choice-2.
This icon signifies a tip, suggestion, or general note.
This icon indicates a warning or caution.
Using Code Examples
This book is here to help you get your job done. In general, you may use the code in
this book in your programs and documentation. You do not need to contact us for
permission unless you’re reproducing a significant portion of the code. For example,
writing a program that uses several chunks of code from this book does not require
permission. Selling or distributing a CD-ROM of examples from O’Reilly books does
require permission. Answering a question by citing this book and quoting example
code does not require permission. Incorporating a significant amount of example code
from this book into your product’s documentation does require permission.
We appreciate, but do not require, attribution. An attribution usually includes the title,
author, publisher, and ISBN. For example: “Asterisk: The Future of Telephony, Second
Edition, by Jim Van Meggelen, Leif Madsen, and Jared Smith. Copyright 2007 O’Reilly
Media, Inc., 978-0-596-51048-0.”
If you feel your use of code examples falls outside fair use or the permission given above,
feel free to contact us at permissions@oreilly.com.
Safari® Books Online
When you see a Safari® Books Online icon on the cover of your favorite
technology book, that means the book is available online through the
O’Reilly Network Safari Bookshelf.
xviii | Preface
Safari offers a solution that’s better than e-books. It’s a virtual library that lets you easily
search thousands of top tech books, cut and paste code samples, download chapters,
and find quick answers when you need the most accurate, current information. Try it
for free at http://safari.oreilly.com.
How to Contact Us
Please address comments and questions concerning this book to the publisher:
O’Reilly Media, Inc.
1005 Gravenstein Highway North
Sebastopol, CA 95472
(800) 998-9938 (in the United States or Canada)
(707) 829-0515 (international or local)
(707) 829-0104 (fax)
We have a web page for this book, where we list errata, examples, and any additional
information. You can access this page at:
http://www.oreilly.com/catalog/9780596510480
To comment or ask technical questions about this book, send email to:
bookquestions@oreilly.com
For more information about our books, conferences, Resource Centers, and the O’Reilly
Network, see our web site at:
http://www.oreilly.com
Acknowledgments
Firstly, we have to thank our fantastic editor Michael Loukides, who offered invaluable
feedback and found incredibly tactful ways to tell us to rewrite a section (or chapter)
when it was needed, and have us think it was our idea. Mike built us up when we were
down, and brought us back to earth when we got uppity. You are a master, Mike, and
seeing how many books have received your editorial oversight contributes to an understanding
of why O’Reilly Media is the success that it is.
Thanks also to Sanders Kleinfeld, our copy editor, Laurel Ruma, our production editor,
and the rest of the unsung heroes in O’Reilly’s production department. These are the
folks that take our book and make it an O’Reilly book.
Everyone in the Asterisk community needs to thank Jim Dixon for creating the first
open source telephony hardware interfaces, starting the revolution, and giving his creations
to the community at large.
Thanks to Tim O’Reilly, for giving us a chance to write this book.
Preface | xix
To our most generous and merciless review team:
• Rich Adamson, President of Network Partners Inc., for your encyclopedic knowledge
of the PSTN, and your tireless willingness to share your experience. Your
generosity, even in the face of daunting challenge, is inspiring to us all.*
• Tilghman Lesher, for an incredibly thorough review of our book, contributing
some much needed time toward Appendixes B and F, in addition to some amazing
new Asterisk applications and functions.
• Andrew Kohlsmith, for helping to write the IMAP voicemail storage section in
Chapter 14.
• David Troy, for providing a technical review, for AstManProxy, and for porting
Asterisk to the Roomba (first PBX to run on a vacuum cleaner!).
• Matthew Gast, fellow O’Reilly author, for reading our book from cover to cover,
and then giving us a comprehensive review, and also for T1, The Definitive Guide.
• Dr. Edward Guy III, for your comprehensive and razor-sharp evaluation of each
and every chapter of the first edition, and for your championing of Asterisk.
• Kristian Kielhofner, President, KrisCompanies, and creator of AstLinux, for the
most excellent AstLinux distribution.
• Russell Bryant, for your rapid and helpful responses to our questions.
• Joshua Colp, for helping us with performance tweaking, and still more questions.
• Kevin Fleming, for raising the bar, and for being a class act, respected (dare we say
loved) by all.
• Brian Capouch, for talking about what is possible, and then going out there and
doing it.
• Stephen Uhler, for championing the port of Zaptel to Solaris, and for giving us
some golden examples.
• Jason Parker, for not being a newb.
• Ekke Loo, for beating up the database chapter.
• Ian Darwin, for tweaking some of the verbiage for us, and for the cherry-red rotary
dial phone (that works with Asterisk!).
• Joel Sisko, CEO, iConverged, for your comprehensive telecom and wiring
knowledge.
Finally, and most importantly, thanks go to Mark Spencer for Gaim (recently renamed
Pidgin, www.pidgin.im), Asterisk, and DUNDi, and for contributing his creations to
the open source community.
* In December of 2006, Rich passed away, as his two-year battle with cancer came to an unfortunate end. Rich
was posting on the Asterisk Users mailing list as late as November of that year. He was giving to the community
right up until the end, which is why we dedicated this book to him.
xx | Preface
Jim Van Meggelen
For me, it all started in the spring of 2004, sitting at my desk in the technical support
department of the telecom company I’d worked at for nearly 15 years. With no challenges
to properly exercise the skills I had developed, I spent my time trying to figure
out what the rest of my career was going to look like. The telecommunications industry
had fallen from the pedestal of being a darling of investors to being a joke known to
even the most uninformed. I was supposed to feel fortunate to be one of the few who
still had work, but what thankless, purposeless work it was. We knew why our industry
had collapsed: the products we sold could not hope to deliver the solutions our customers
required—even though the industry promised that they could. They lacked
flexibility, and were priced totally out of step with the functionality they were delivering
(or, more to the point, were failing to deliver). Nowhere in the industry were there any
signs this was going to change any time soon.
I had been dreaming of an open source PBX for many long years, but I really didn’t
know how such a thing could ever come to be—I’d given up on the idea several years
before. I knew that to be successful, an open source PBX would need to effectively
bridge the worlds of legacy and network-based telecom. I always failed to find anything
that seemed ready.
Then, one fine day in spring, I half-heartedly seeded a Google search with the phrase
“open source telephony,” and discovered a bright new future for telecom: Asterisk, the
open source Linux PBX.†
There it was: the very thing I’d been dreaming of for so many years. I had no idea how
I was going to contribute, but I knew this: open source telephony was going to cause
a necessary and beneficial revolution in the telecom industry, and one way or another,
I was going to be a part of it.
For me, more of a systems integrator than developer, I needed a way to contribute to
the community. There didn’t seem to be a shortage of developers, but there sure was
a shortage of documentation. This sounded like something I could do. I knew how to
write, I knew PBXes, and I desperately needed to talk about this phenomenon that
suddenly made telecom fun again.
If I contribute only one thing to this book, I hope you will catch some of my enthusiasm
for the subject of open source telephony. This is an incredible gift we have been given,
but also an incredible responsibility. What a wonderful challenge. What a cosmic opportunity.
What delicious fun!
† To get a sense of how big the Asterisk phenomenon is, type “PBX” into Google. As you look at the results,
bear in mind that the traditional PBX industry represents billions of dollars. The big players are companies
such as Avaya, Nortel, Siemens, Mitel, Cisco, NEC, and many, many more. It is somewhat telling that they
don’t seem to be concerned about how they rank in a Google search. As a cultural barometer, we’re pretty
sure this matters.
Preface | xxi
First of all, I need to thank Leif and Jared for inviting me to join the Asterisk Documentation
Project. I have immensely enjoyed working with both of you, and I am
constantly amazed at how well our personalities and skills complement each other. A
truly balanced team, are we. Also, thanks goes to Figment for all the typing.
To my wife Killi, and my children Kaara, Joonas, and Joosep (who always remember
to visit me when I disappear into my underground lair for too long): you are a source
of inspiration to me. Your love is the fuel that feeds my fire, and I thank you.
Obviously, I need to thank my parents, Jack and Martiny, for always believing in me,
no matter how many rules I broke. In a few years, I’ll have my own teenagers, and it’ll
be your turn to laugh!
To Mark Spencer: thanks for all of the things that everybody else thanks you for, but
also, personally, thanks for giving generously of your time to the Asterisk community.
The Toronto Asterisk Users’ Group (http://www.taug.ca) made a quantum leap forward
as a result of your taking the time to speak to us, and that event will forever form a part
of our history. Oh yeah, and thanks for the beers, too. :-)
Finally, thanks to the Asterisk Community. This book is our gift to you. We hope you
enjoy reading it as much as we’ve enjoyed writing it.
Leif Madsen
The road to this book is a long one—nearly three years in the making. Back when I
started using Asterisk, possibly much like you, I didn’t know anything about Asterisk,
very little about traditional telephony, and even less about Voice over IP. I delved right
into this new and very exciting world and took in all I could. For two months during a
co-op term, for which I couldn’t immediately find work, I absorbed as much as I could,
asking questions, trying things and seeing what the system could do. Unfortunately
very little to no documentation existed for Asterisk, aside from some dialplan examples
I was able to find by John Todd, and having questions answered by Brian K. West on
IRC. Of course, this method wasn’t going to scale.
Not being much of a coder, I wanted to contribute something back to the community,
and what do coders hate doing more than anything? Documentation! So I started The
Asterisk Documentation Assignment (TADA), a basic outline with some information
for the beginnings of a book.
Shortly after releasing it on my web site, an intelligent fellow by the name of Jared Smith
introduced himself. He had similar aspirations for creating a “dead-tree” format book
for the community, and we humbly started the Asterisk Documentation Project. Jared
set up a simple web site at http://www.asteriskdocs.org, a CVS server, and the very first
DocBook-formatted version of a book for Asterisk. From there we started filling in
information, and soon had information submitted by a number of members of the
community.
xxii | Preface
In June of 2004, an animated chap by the name of Jim Van Meggelen started showing
up on the mailing lists, and contributing lots of information and documentation—this
was definitely a guy we wanted on our team! Jim had the vision and the drive to really
get Jared’s and my butts in gear and to work on something grander. Jim brought us
years of experience and a writing flair that we could have hardly imagined.
With the core documentation team established, we embarked on a plan for the creation
of volumes of Asterisk knowledge, eventually to lead to a complete library and a wealth
of information. This book is essentially the beginning of that dream.
Firstly and mostly, I have to thank my parents, Rick and Carol, for always supporting
my efforts, allowing me to realize my dreams, and always putting my needs ahead of
theirs. Without their vision, understanding, and insight into the future, it would have
been impossible to have accomplished what I have. I love you both very much!
I’d like to thank Felix Carapaica and Bill Farkas of the Sheridan Institute of Technology
for their dedication to the advancement of knowledge. Their teaching has complemented
my prior learning, and has allowed me to expand my understanding of routing and
telecommunications exponentially.
There are far too many people to thank individually, but of particular importance, the
following people were, and are, the most influential to my understanding of Asterisk:
Joshua Colp, Tilghman Lesher, Russell Bryant, Steve Murphy, Olle Johansson, Steven
Sokol, Brian K. West, John Todd, and William Suffill, for my very first VoIP phone
(which I use to this day!). And for those who I said I’d mention in the book…thanks!
And of course, I must thank Jared Smith and Jim Van Meggelen for having the vision
and understanding of how important documentation really is—all of this would have
been impossible without you.

Jared Smith
I first started working with Asterisk in the spring of 2002. I had recently started a new
job with a market research company, and ended up taking a long road trip to a remote
call center with the CIO. On the long drive home we talked about innovation in telephony,
and he mentioned a little open source telephony project he had heard of called
Asterisk. Over the next few months, I was able to talk the company into buying a
developer’s kit from Digium and started playing with Asterisk on company time.
During the next few months, I became more and more involved with the Asterisk community.
I read the mailing lists. I scoured the archives. I hung out in the IRC channel,
just hoping to find nuggets of Asterisk knowledge. As time went on, I was finally able
to figure out enough to get Asterisk up and running.
That’s when the real fun began.
With the help of the CIO and the approval of the CEO, we moved forward with plans
to move our entire telecom infrastructure to Asterisk, including our corporate office
Preface | xxiii
and all of our remote call centers. Along the way, we ran into a lot of uncharted territory,
and I began thinking about creating a good repository of Asterisk knowledge. Over the
course of the project, we were able to do some really innovative things, such as invent
IAX trunking!
When all was said and done, we ended up with around forty Asterisk servers spread
across many different geographical locations, all communicating with each other to
provide a cohesive enterprise-class VoIP phone system. This system currently handles
approximately 1 million minutes of calls per month, serves several hundred employees,
connects to 27 voice T1s, and saves the company around $20,000 (USD) per month
on their telecom costs. In short, our Asterisk project was a resounding success!
While in the middle of implementing this project, I met Leif in one of the Asterisk IRC
channels. We talked about ways we could help out new Asterisk users and lower the
barrier to entry, and we decided to push ahead with plans to more fully document
Asterisk. I really wanted some good documentation in “dead-tree” format —basically
a book that a new user could pick up and learn the basics of Asterisk. About that same
time, the number of new users on the Asterisk mailing lists and in the IRC channels
grew tremendously, and we felt that writing an Asterisk book would greatly improve
the signal-to-noise ratio. The Asterisk Documentation Project was born! The rest, they
say, is history.
Since then, we’ve been writing Asterisk documentation. I never thought it would be
this arduous, yet rewarding. (I joked with Leif and Jim that it might be easier and less
controversial to write an in-depth tome called Religion, Gun Control, and Sushi than
cover everything that Asterisk has to offer in sufficient detail!) What you see here is a
direct result of a lot of late nights and long weekends spent helping the Asterisk community—
after all, it’s the least we could do, considering what Asterisk has given to us.
We hope it will inspire other members of the Asterisk community to help document
changes and new features for the benefit of all involved.
Now to thank some people:
First of all, I’d like to thank my beautiful wife. She’s put up with a lot of lonely nights
while I’ve been slaving away at the keyboard, and I’d like her to know how much I
appreciate her and her endless support. I’d also like to thank my kids for doing their
best to remind me of the important things in life. I love you!
To my parents: thanks for everything you’ve done to help me stretch and grow and
learn over the years. You’re the best parents a person could ask for.
To Dave Carr and Michael Lundberg: thanks for letting me learn Asterisk on company
time. Working with both of you was truly a pleasure. May God smile upon you and
grant you success and joy in all you do.
To Leif and Jim: thanks for putting up with my stupid jokes, my insistence that we do
things “the right way,” and my crazy schedule. Thanks for pushing me along, and
xxiv | Preface
making me a better writer. I’ve really enjoyed working with you two, and hope to
collaborate with you on future projects!
To Mark Spencer: thank you for your continued support and dedication and friendship.
You’ve been an invaluable resource to our effort, and I truly believe that you’ve started
a revolution in the world of telephony. You’re always welcome in my home and at my
dinner table!
To the other great people at Digium: thank you for your help and support. We’re
especially thankful for your willingness to give us more insight into the Asterisk code,
and for donating hardware so that we can better document the Asterisk Developer’s Kit.
To Steven Sokol, Steven Critchfield, Olle E. Johansson, and all the others who have
contributed to the Asterisk Documentation Project and to this book: thank you! We
couldn’t have done it without your help and suggestions.
Preface | xxv

CHAPTER 1
A Telephony Revolution
It does not require a majority to prevail, but rather an
irate, tireless minority keen to set brush fires
in people’s minds.
—Samuel Adams
An incredible revolution is under way. It has been a long time in coming, but now that
it has started, there will be no stopping it. It is taking place in an area of technology
that has lapsed embarrassingly far behind every other industry that calls itself hightech.
The industry is telecommunications, and the revolution is being fueled by an open
source Private Branch eXchange (PBX) called Asterisk™.
Telecommunications is arguably the last major electronics industry that has remained
untouched by the open source revolution.* Major telecommunications manufacturers
still build ridiculously expensive, incompatible systems, running complicated, ancient
code on impressively engineered yet obsolete hardware.
As an example, Nortel’s Business Communications Manager kludges together a 15
year-old Key Telephone Switch and a 1.2 GHz Celeron PC.† All this can be yours for
between $5,000 and $15,000, not including telephones. If you want it to actually do
anything interesting, you’ll have to pay extra licensing fees for closed, limitedfunctionality,
shrink-wrapped applications. Customization? Forget it—it’s not in the
plan. Future technology and standards compliance? Give them a year or two—they’re
working on it.
All of the major telecommunications manufacturers offer similar-minded products.
They don’t want you to have flexibility or choice; they want you to be locked in to their
product cycles.
* Until now.
† To its credit, Nortel finally got rid of Windows NT 4.0 and installed Linux. Technically a good idea, but
rather odd, given that Nortel and Microsoft recently announced a partnership to develop enterprise telecom
applications together.
1
Asterisk changes all of that. With Asterisk, no one is telling you how your phone system
should work, or what technology you are limited to. If you want it, you can have it.
Asterisk lovingly embraces the concept of standards compliance, while also enjoying
the freedom to develop its own innovations. What you choose to implement is up to
you—Asterisk imposes no limits.
Naturally, this incredible flexibility comes with a price: Asterisk is not a simple system
to configure. This is not because it’s illogical, confusing, or cryptic; to the contrary, it
is very sensible and practical. People’s eyes light up when they first see an Asterisk
dialplan and begin to contemplate the possibilities. But when there are literally thousands
of ways to achieve a result, the process naturally requires extra effort. Perhaps it
can be compared to building a house: the components are relatively easy to understand,
but a person contemplating such a task must either a) enlist competent help or b)
develop the required skills through instruction, practice, and a good book on the
subject.
VoIP: Bridging the Gap Between Traditional and Network
Telephony
While Voice over IP (VoIP) is often thought of as little more than a method of obtaining
free long-distance calling, the real value (and—let’s be honest—challenge as well) of
VoIP is that it allows voice to become nothing more than another application in the
data network.
It sometimes seems that we’ve forgotten that the purpose of the telephone is to allow
people to communicate. It is a simple goal, really, and it should be possible for us to
make it happen in far more flexible and creative ways than are currently available to
us. Since the industry has demonstrated an unwillingness to pursue this goal, a large
community of passionate people have taken on the task.
The challenge comes from the fact that an industry that has changed very little in the
last century shows little interest in starting now.
The Zapata Telephony Project
The Zapata Telephony Project was conceived of by Jim Dixon, a telecommunications
consulting engineer who was inspired by the incredible advances in CPU speeds that
the computer industry has now come to take for granted. Dixon’s belief was that far
more economical telephony systems could be created if a card existed that had nothing
more on it than the basic electronic components required to interface with a telephone
circuit. Rather than having expensive components on the card, Digital Signal Processing
(DSP)‡ would be handled in the CPU by software. While this would impose a tremendous
load on the CPU, Dixon was certain that the low cost of CPUs relative to their
performance made them far more attractive than expensive DSPs, and, more impor-
2 | Chapter 1: A Telephony Revolution
tantly, that this price/performance ratio would continue to improve as CPUs continued
to increase in power.
Like so many visionaries, Dixon believed that many others would see this opportunity,
and that he merely had to wait for someone else to create what to him was an obvious
improvement. After a few years, he noticed that not only had no one created these cards,
but it seemed unlikely that anyone was ever going to. At that point it was clear that if
he wanted a revolution, he was going to have to start it himself. And so the Zapata
Telephony Project was born:
Since this concept was so revolutionary, and was certain to make a lot of waves in the
industry, I decided on the Mexican revolutionary motif, and named the technology and
organization after the famous Mexican revolutionary Emiliano Zapata. I decided to call
the card the “tormenta” which, in Spanish, means “storm,” but contextually is usually
used to imply a big storm, like a hurricane or such.§
Perhaps we should be calling ourselves Asteristas. Regardless, we owe Jim Dixon a debt
of thanks, partly for thinking this up and partly for seeing it through, but mostly for
giving the results of his efforts to the open source community. As a result of Jim’s
contribution, Asterisk’s Public Switched Telephone Network (PSTN) engine came to
be.
Massive Change Requires Flexible Technology
The most successful key telephone system in the world has a design limitation that has
survived 15 years of users begging for what appears to be a simple change: when you
determine the number of times your phone will ring before it forwards to voicemail,
you can choose from 2, 3, 4, 6, or 10 ring cycles. Have you any idea how many times
people ask for five rings? Plead as the customers might, the manufacturers of this system
cannot get their head around the idea that this is a problem. That’s the way it works,
they say, and users need to get over it.
Another example from the same system is that the name you program on your set can
only be seven characters in length.‖ Back in the late 1980s, when this particular system
was designed, RAM was very expensive, and storing those seven characters for dozens
of sets represented a huge hardware expense. So what’s the excuse today? None. Are
there any plans to change it? Hardly—the issue is not even officially acknowledged as
a problem.
‡ The term DSP also means Digital Signal Processor, which is a device (usually a chip) that is capable of
interpreting and modifying signals of various sorts. In a voice network, DSPs are primarily responsible for
encoding, decoding, and transcoding audio information. This can require a lot of computational effort.
§ Jim Dixon, “The History of Zapata Telephony and How It Relates to the Asterisk PBX” (http://www.asteriskdocs.org/
modules/tinycontent/index.php?id=10).
‖ If your name is Elizabeth, for example, you will have to figure something else out like elizbth, or elizabe, or
perhaps lizabth. OK, so liz might serve as well, but you get the point.
Massive Change Requires Flexible Technology | 3
Those are just two examples; the industry is rife with them.
Now, it’s all very well and good to pick on one system, but the reality is that every PBX
in existence suffers shortcomings. No matter how fully featured it is, something will
always be left out, because even the most feature-rich PBX will always fail to anticipate
the creativity of the customer. A small group of users will desire an odd little feature
that the design team either did not think of or could not justify the cost of building,
and, since the system is closed, the users will not be able to build it themselves.
If the Internet had been thusly hampered by regulation and commercial interests, it is
doubtful that it would have developed the wide acceptance it currently enjoys. The
openness of the Internet meant that anyone could afford to get involved. So, everyone
did. The tens of thousands of minds that collaborated on the creation of the Internet
delivered something that no corporation ever could have.
As with many other open source projects, such as Linux and the Internet, the development
of Asterisk was fueled by the dreams of folks who knew that there had to be
something more than what the industry was producing. The strength of the community
is that it is composed not of employees assigned to specific tasks, but rather of folks
from all sorts of industries, with all sorts of experiences, and all sorts of ideas about
what flexibility means, and what openness means. These people knew that if one could
take the best parts of various PBXes and separate them into interconnecting components—
akin to a boxful of LEGO bricks—one could begin to conceive of things that
would not survive a traditional corporate risk-analysis process. While no one can seriously
claim to have a complete picture of what this thing should look like, there is no
shortage of opinions and ideas.#
Many people new to Asterisk see it as unfinished. Perhaps these people can be likened
to visitors to an art studio, looking to obtain a signed, numbered print. They often leave
disappointed, because they discover that Asterisk is the blank canvas, the tubes of paint,
the unused brushes waiting.*
Even at this early stage in its success, Asterisk is nurtured by a greater number of artists
than any other PBX. Most manufacturers dedicate no more than a few developers to
any one product; Asterisk has scores. Most proprietary PBXes have a worldwide support
team comprised of a few dozen real experts; Asterisk has hundreds.
The depth and breadth of the expertise that surrounds this product is unmatched in
the telecom industry. Asterisk enjoys the loving attention of old Telco guys who
# From the release of Asterisk 1.2 to Asterisk 1.4, there have been over 4,000 updates to the code in the SVN
repository.
* It should be noted that these folks need not leave disappointed. Several projects have arisen to lower the
barriers to entry for Asterisk. By far the most popular and well known is trixbox (http://www.trixbox.org). If
you have an old PC lying around (or a copy of VMware), trixbox will build a GUI-based PBX for you simply
by answering a few questions during the automated install process. This does not make it easier to learn
Asterisk, because you are no longer involved in the platform or dialplan configuration, but it will deliver a
working PBX to you much faster than the more hands-on approach we employ in this book.
4 | Chapter 1: A Telephony Revolution
remember when rotary dial mattered, enterprise telecom people who recall when voicemail
was the hottest new technology, and data communications geeks and coders
who helped build the Internet. These people all share a common belief—that the telecommunications
industry needs a proper revolution.†
Asterisk is the catalyst.
Asterisk: The Hacker’s PBX
Telecommunications companies who choose to ignore Asterisk do so at their peril. The
flexibility it delivers creates possibilities that the best proprietary systems can scarcely
dream of. This is because Asterisk is the ultimate hacker’s PBX.
If someone asks you not to use the term hacker, refuse. This term does not belong to
the mass media. They stole it and corrupted it to mean “malicious cracker.” It’s time
we took it back. Hackers built the networking engine that is the Internet. Hackers built
the Apple Macintosh and the Unix operating system. Hackers are also building your
next telecom system. Do not fear; these are the good guys, and they’ll be able to build
a system that’s far more secure than anything that exists today. Rather than being
constricted by the dubious and easily cracked security of closed systems, the hackers
will be able to quickly respond to changing trends in security and fine-tune the telephone
system in response to both corporate policy and industry best practices.
Like other open source systems, Asterisk will be able to evolve into a far more secure
platform than any proprietary system, not in spite of its hacker roots, but rather because
of them.
Asterisk: The Professional’s PBX
Never in the history of telecommunications has a system so suited to the needs of
business been available, at any price. Asterisk is an enabling technology and, as with
Linux, it will become increasingly rare to find an enterprise that is not running some
version of Asterisk, in some capacity, somewhere in the network, solving a problem as
only Asterisk can.
This acceptance is likely to happen much faster than it did with Linux, though, for
several reasons:
• Linux has already blazed the trail that led to open source acceptance. Asterisk is
following that lead.
• The telecom industry is crippled, with no leadership being provided by the giant
industry players. Asterisk has a compelling, realistic, and exciting vision.
† The telecom industry has been predicting a revolution since before the crash; time will tell how well they
respond to the open source revolution.
Asterisk: The Hacker’s PBX | 5
• End users are fed up with incompatible, limited functionality, and horrible support.
Asterisk solves the first two problems; entepreneurs and the community are addressing
the latter.
The Asterisk Community
One of the compelling strengths of Asterisk is the passionate community that developed
and supports it. This community, led by Mark Spencer of Digium, is keenly aware of
the cultural significance of Asterisk, and is giddy about the future.
One of the more powerful side effects caused by the energy of the Asterisk community
is the cooperation it has spawned among the telecommunications professionals, networking
professionals, and information technology professionals who share a love for
this phenomenon. While these professions have traditionally been at odds with each
other, in the Asterisk community they delight in each others’ skills. The significance of
this cooperation cannot be underestimated.
Still, if the dream of Asterisk is to be realized, the community must grow—yet one of
the key challenges that the community currently faces is a rapid influx of new users.
The members of the existing community, having birthed this thing called Asterisk, are
generally welcoming of new users, but they’ve grown impatient with being asked the
kinds of questions whose answers can often be obtained independently, if one is willing
to put forth the time needed to research and experiment.
Obviously, new users do not fit any particular kind of mold. While some will happily
spend hours experimenting and reading various blogs describing the trials and tribulations
of others, many people who have become enthusiastic about this technology
are completely uninterested in such pursuits. They want a simple, straightforward, stepby-
step guide that’ll get them up and running, followed by some sensible examples
describing the best methods of implementing common functionality (such as voicemail,
auto attendants, and the like).
To the members of the expert community, who (correctly) perceive that Asterisk is like
a web development language, this approach doesn’t make any sense. To them, it’s clear
that you have to immerse yourself in Asterisk to appreciate its subtleties. Would one
ask for a step-by-step guide to programming and expect to learn from it all that a language
has to offer?
Clearly, there’s no one approach that’s right for everyone. Asterisk is a different animal
altogether, and it requires a totally different mind-set. As you explore the community,
though, be aware that there are people with many different skill sets and attitudes here.
Some of these folks do not display much patience with new users, but that’s often due
to their passion for the subject, not because they don’t welcome your participation.
6 | Chapter 1: A Telephony Revolution
The Asterisk Mailing Lists
As with any community, there are places where members of the Asterisk community
meet to discuss matters of mutual interest. Of the mailing lists you will find at http://
lists.digium.com, these four are currently the most important:
Asterisk-Biz
Anything commercial with respect to Asterisk belongs in this list. If you’re selling
something Asterisk-related, sell it here. If you want to buy an Asterisk service or
product, post here.
Asterisk-Dev
The Asterisk developers hang out here. The purpose of this list is the discussion of
the development of the software that is Asterisk, and its participants vigorously
defend that purpose. Expect a lot of heat if you post anything to this list not relating
to programming or development of the Asterisk code base specifically. General
coding questions (such as interfacing with AGI or AMI), should be directed to the
Asterisk-Users list.
The Asterisk-Dev list is not second-level support! If you scroll
through the mailing list archives, you’ll see this is a strict rule. The
Asterisk-Dev mailing list is about discussion of core Asterisk development,
and questions about interfacing your external programs
via AGI or AMI should be posted on the Asterisk-Users list.
Asterisk-Users
This is where most Asterisk users hang out. This list generates several hundred
messages per day and has over ten thousand subscribers. While you can go here
for help, you are expected to have done some reading on your own before you post
a query.
Asterisk-BSD
This is where users who are implementing Asterisk on FreeBSD (and other BSD
dialects) hang out.
The Asterisk Wiki
The Asterisk Wiki (which exists in large part due to the tireless efforts of James Thompson—
thanks James!) is a source of much enlightenment and confusion. A communitymaintained
repository of VoIP knowledge (http://www.voip-info.org) contains a truly
inspiring cornucopia of fascinating, informative, and frequently contradictory information
about many subjects, just one of which is Asterisk.
Since Asterisk documentation forms by far the bulk of the information on this web
site,‡ and it probably contains more Asterisk knowledge than all other sources put
together (with the exception of the mailing-list archives), it is commonly referred to as
the place to go for Asterisk knowledge.
The Asterisk Community | 7
The IRC Channels
The Asterisk community maintains Internet Relay Chat (IRC) channels on
irc.freenode.net. The two most active channels are #asterisk and #asterisk-dev.§ To cut
down on spam-bot intrusions, both of these channels now require registration to join.‖
Asterisk User Groups
In many cites around the world, lonely Asterisk users began to realize that there were
other like-minded people in their towns. Asterisk User Groups (AUGs) began to spring
up all over the place. While these groups don’t have any official affiliation with each
other, they generally link to each others’ web sites and welcome members from anywhere.
Type “Asterisk User Group” into Google to track down one in your area.
The Asterisk Documentation Project
The Asterisk Documentation Project was started by Leif Madsen and Jared Smith, but
several people in the community have contributed.
The goal of the documentation project is to provide a structured repository of written
work on Asterisk. In contrast with the flexible and ad hoc nature of the Wiki, the Docs
project is passionate about building a more focused approach to various
Asterisk-related subjects.
As part of the efforts of the Asterisk Docs project to make documentation available
online, this book is available at the http://www.asteriskdocs.org web site, under a Creative
Commons license.
The Business Case
It is very rare to find businesses these days that do not have to reinvent themselves every
few years. It is equally rare to find a business that can afford to replace its communications
infrastructure each time it goes in a new direction. Today’s businesses need
extreme flexibility in all of their technology, including telecom.
In his book Crossing the Chasm (HarperBusiness), Geoffrey Moore opines, “The idea
that the value of the system will be discovered rather than known at the time of installation
implies, in turn, that product flexibility and adaptability, as well as ongoing
account service, should be critical components of any buyer’s evaluation checklist.”
‡ More than 30 percent, at last count.
§ The #asterisk-dev channel is for the discussion of changes to the underlying code base of Asterisk and is also
not second-tier support. Discussions related to programming external applications that interface with
Asterisk via AGI or AMI are meant to be in #asterisk.
‖ /msg nickserv help when you connect to the service via your favorite IRC client.
8 | Chapter 1: A Telephony Revolution
What this means, in part, is that the true value of a technology is often not known until
it has been deployed.
How compelling, then, to have a system that holds at its very heart the concept of
openness and the value of continuous innovation.
This Book
So where to begin? Well, when it comes to Asterisk, there is far more to talk about than
we can fit into one book. For now, we’re not going to take you down all the roads that
the über-geeks follow—we’re just going to give you the basics.
In Chapter 2, we cover some of the engineering considerations you should keep in mind
when designing a telecommunications system. You can skip much of this material if
you want to get right to installing, but these are important concepts to understand,
should you ever plan on putting an Asterisk system into production.
Chapter 3 covers obtaining, compiling, and installing Asterisk, and Chapter 4 deals
with the initial configuration of Asterisk. Here we cover the important configuration
files that must exist to define the channels and features available to your system. This
will prepare you for Chapter 5, where we introduce the heart of Asterisk—the dialplan.
Chapter 6 will introduce some more advanced dialplan concepts.
We will take a break from Asterisk in Chapter 7 and discuss some of the more important
technologies in use in the PSTN. Naturally, following the discussion of legacy
telephony, Chapter 8 discusses Voice over IP.
Chapter 9 introduces one of the more amazing components, the Asterisk Gateway
Interface (AGI). Using Perl, PHP, and Python, we demonstrate how external programs
can be used to add nearly limitless functionality to your PBX. In Chapter 14, we briefly
cover what is, in fact, a rich and varied cornucopia of incredible features and functions,
all of which are part of the Asterisk phenomenon. To conclude, Chapter 15 looks forward,
predicting a future where open source telephony completely transforms an
industry desperately in need of a revolution. You’ll also find a wealth of reference information
in the book’s five appendixes.
This book can only lay down the basics, but from this foundation you will be able to
come to an understanding of the concept of Asterisk—and from that, who knows what
you will build?
This Book | 9

CHAPTER 2
Preparing a System for Asterisk
Very early on, I knew that someday in some “perfect”
future out there over the horizon, it would be commonplace
for computers to handle all of the necessary processing
functionality internally, making the necessary
external hardware to connect up to telecom interfaces
very inexpensive and, in some cases, trivial.
—Jim Dixon, “The History of Zapata Telephony and
How It Relates to the Asterisk PBX”
By this point, you must be anxious to get your Asterisk system up and running. If you
are building a hobby system, you can probably jump right to the next chapter and begin
the installation. For a mission-critical deployment, however, some thought must be
given to the environment in which the Asterisk system will run. Make no mistake:
Asterisk, being a very flexible piece of software, will happily and successfully install on
nearly any Linux platform you can conceive of, and several non-Linux platforms as
well.* However, to arm you with an understanding of the type of operating environment
Asterisk will really thrive in, this chapter will discuss issues you need to be aware of in
order to deliver a reliable, well-designed system.
In terms of its resource requirements, Asterisk’s needs are similar to those of an embedded,
real-time application. This is due in large part to its need to have priority access
to the processor and system buses. It is, therefore, imperative that any functions on the
system not directly related to the call-processing tasks of Asterisk be run at a low priority,
if at all. On smaller systems and hobby systems, this might not be as much of an
issue. However, on high-capacity systems, performance shortcomings will manifest as
audio quality problems for users, often experienced as echo, static, and the like. The
symptoms will resemble those experienced on a cell phone when going out of range,
* People have successfully compiled and run Asterisk on WRAP boards, Linksys WRT54G routers, Soekris
systems, Pentium 100s, PDAs, Apple Macs, Sun SPARCs, laptops, and more. Of course, whether you would
want to put such a system into production is another matter entirely. (Actually, the AstLinux distribution,
by Kristian Kielhofner, runs very well indeed on the Soekris 4801 board. Once you’ve grasped the basics of
Asterisk, this is something worth looking into further. Check out http://www.astlinux.org.)
11
although the underlying causes will be different. As loads increase, the system will have
increasing difficulty maintaining connections. For a PBX, such a situation is nothing
short of disastrous, so careful attention to performance requirements is a critical consideration
during the platform selection process.
Table 2-1 lists some very basic guidelines that you’ll want to keep in mind when planning
your system. The next section takes a close look at the various design and
implementation issues that will affect its performance.
The size of an Asterisk system is actually not dictated by the number of
users or sets, but rather by the number of simultaneous calls it will be
expected to support. These numbers are very conservative, so feel free
to experiment and see what works for you.
Table 2-1. System requirement guidelines
Purpose Number of channels Minimum recommended
Hobby system No more than 5 400 MHz x86, 256 MB RAM
SOHO system (small office/home office—
less than three lines and five sets)
5 to 10 1 GHz x86, 512 MB RAM
Small business system Up to 25 3 GHz x86, 1 GB RAM
Medium to large system More than 25 Dual CPUs, possibly also multiple servers in a distributed
architecture
With large Asterisk installations, it is common to deploy functionality across several
servers. One or more central units will be dedicated to call processing; these will be
complemented by one or more ancillary servers handling peripherals (such as a database
system, a voicemail system, a conferencing system, a management system, a web
interface, a firewall, and so on). As is true in most Linux environments, Asterisk is well
suited to growing with your needs: a small system that used to be able to handle all
your call-processing and peripheral tasks can be distributed among several servers when
increased demands exceed its abilities. Flexibility is a key reason why Asterisk is extremely
cost-effective for rapidly growing businesses; there is no effective maximum or
minimum size to consider when budgeting the initial purchase. While some scalability
is possible with most telephone systems, we have yet to hear of one that can scale as
flexibly as Asterisk. Having said that, distributed Asterisk systems are not simple to
design—this is not a task for someone new to Asterisk.
12 | Chapter 2: Preparing a System for Asterisk
If you are sure that you need to set up a distributed Asterisk system, you
will want to study the DUNDi protocol, Asterisk Realtime Architecture
(ARA), func_odbc, and the various other database tools at your disposal.
This will help you to abstract the data your system requires from the
dialplan logic your Asterisk systems will utilize, allowing a generic set
of dialplan logic that can be used across multiple boxes, thereby allowing
you to scale more simply by adding additional boxes to the system.
However, this is far beyond the scope of this book and will be left as an
exercise for the reader. If you want a teaser of some tools you can use
for scaling, see Chapter 12.
A Set of Load Test Results
Joshua Colp was able to produce the results in Table 2-2 on an AMD Athlon64 X2 4200
+ with 1 GB RAM and 80 GB SATA hard drive, testing with the default scenario in
the SIPp application: a simple call setup, Playback() an audio file, and Wait() a short
time. Notice the massive savings in CPU utilization while reading data from the RAM
disk versus the hard drive. This could be interpreted as the CPU waiting for data to
process before delivering it to the requesting channel. However, this is just a simple
test and in no way reflects the amount of calls your system will be able to handle. You
are encouraged to load test your own system to determine the number of simultaneous
calls that can be handled utilizing your dialplan and combination of applications.
Table 2-2. Sample test results for SIPp default scenario using simple Wait() and Playback()
application; SIPp echoed media back to Asterisk
Simultaneous calls 330 330 550
CPU utilization 149% 14.8% 57.6%
Load average 49 25 60
Storage Hard drive RAM disk RAM disk
Server Hardware Selection
The selection of a server is both simple and complicated: simple because, really, any
x86-based platform will suffice, but complicated because the reliable performance of
your system will depend on the care that is put into the platform design. When selecting
your hardware, you must carefully consider the overall design of your system and what
functionality you need to support. This will help you determine your requirements for
the CPU, motherboard, and power supply. If you are simply setting up your first
Asterisk system for the purpose of learning, you can safely ignore the information in
this section. If, however, you are building a mission-critical system suitable for deployment,
these are issues that require some thought.
Server Hardware Selection | 13
Performance Issues
Among other considerations, when selecting the hardware for an Asterisk installation
you must bear in mind this critical question: how powerful must the system be? This
is not an easy question to answer, because the manner in which the system is to be used
will play a big role in the resources it will consume. There is no such thing as an Asterisk
performance-engineering matrix, so you will need to understand how Asterisk uses the
system in order to make intelligent decisions about what kinds of resources will be
required. You will need to consider several factors, including:
The maximum number of concurrent connections the system will be expected to support
Each connection will increase the workload on the system.
The percentage of traffic that will require processor-intensive DSP of compressed codecs
(such as G.729 and GSM)
The Digital Signal Processing (DSP) work that Asterisk performs in software can
have a staggering impact on the number of concurrent calls it will support. A system
that might happily handle 50 concurrent G.711 calls could be brought to its knees
by a request to conference together 10 G.729 compressed channels. We’ll talk more
about G.729, GSM, G.711, and many other codecs in Chapter 8.
Whether conferencing will be provided, and what level of conferencing activity is expected
Will the system be used heavily? Conferencing requires the system to transcode
and mix each individual incoming audio stream into multiple outgoing streams.
Mixing multiple audio streams in near-real-time can place a significant load on the
CPU.
Echo cancellation
Echo cancellation may be required on any call where a Public Switched Telephone
Network (PSTN) interface is involved. Since echo cancellation is a mathematical
function, the more of it the system has to perform, the higher the load on the CPU
will be. † Do not fear. Echo cancellation is another topic for Chapter 8.
Dialplan scripting logic
Whenever Asterisk has to pass call control to an external program, there is a performance
penalty. As much logic as possible should be built into the dialplan. If
external scripts are used, they should be designed with performance and efficiency
as critical considerations.
As for the exact performance impact of these factors, it’s difficult to know for sure. The
effect of each is known in general terms, but an accurate performance calculator has
not yet been successfully defined. This is partly because the effect of each component
of the system is dependent on numerous variables, such as CPU power, motherboard
chipset and overall quality, total traffic load on the system, Linux kernel optimizations,
network traffic, number and type of PSTN interfaces, and PSTN traffic—not to mention
† Roughly 30 MHz of CPU power per channel.
14 | Chapter 2: Preparing a System for Asterisk
any non-Asterisk services the system is performing concurrently. Let’s take a look at
the effects of several key factors:
Codecs and transcoding
Simply put, a codec (short for coder/decoder, or compression/decompression) is a
set of mathematical rules that define how an analog waveform will be digitized.
The differences between the various codecs are due in large part to the levels of
compression and quality that they offer. Generally speaking, the more compression
that’s required, the more work the DSP must do to code or decode the signal.
Uncompressed codecs, therefore, put far less strain on the CPU (but require more
network bandwidth). Codec selection must strike a balance between bandwidth
and processor usage.
Central processing unit (and Floating Point Unit)
A CPU is comprised of several components, one of which is the floating point unit
(FPU). The speed of the CPU, coupled with the efficiency of its FPU, will play a
significant role in the number of concurrent connections a system can effectively
support. The next section (“Choosing a Processor) offers some general guidelines
for choosing a CPU that will meet the needs of your system.
Other processes running concurrently on the system
Being Unix-like, Linux is designed to be able to multitask several different processes.
A problem arises when one of those processes (such as Asterisk) demands
a very high level of responsiveness from the system. By default, Linux will distribute
resources fairly among every application that requests them. If you install a system
with many different server applications, those applications will each be allowed
their fair use of the CPU. Since Asterisk requires frequent high-priority access to
the CPU, it does not get along well with other applications, and if Asterisk must
coexist with other apps, the system may require special optimizations. This primarily
involves the assignment of priorities to various applications in the system
and, during installation, careful attention to which applications are installed as
services.
Kernel optimizations
A kernel optimized for the performance of one specific application is something
that very few Linux distributions offer by default and, thus, it requires some
thought. At the very minimum—whichever distribution you choose—a fresh copy
of the Linux kernel (available from http://www.kernel.org) should be downloaded
and compiled on your platform. You may also be able to acquire patches that will
yield performance improvements, but these are considered hacks to the officially
supported kernel.
IRQ latency
Interrupt request (IRQ) latency is basically the delay between the moment a peripheral
card (such as a telephone interface card) requests the CPU to stop what
it’s doing and the moment when the CPU actually responds and is ready to handle
the task. Asterisk’s peripherals (especially the Zaptel cards) are extremely intoler-
Server Hardware Selection | 15
ant of IRQ latency. This is not due to any problem with the cards so much as part
of the nature of how a software-based TDM engine has to work. If we buffer the
TDM data and send it on the bus as a larger packet, that may be more efficient
from a system perspective, but it will create a delay between the time the audio is
received on the card, and when it is delivered to the CPU. This makes real-time
processing of TDM data next to impossible. In the design of Zaptel, it was decided
that sending the data every 1 ms would create the best trade-off, but a side effect
of this is that any card in the system that uses the Zaptel interface is going to ask
the system to process an interrupt every millisecond. This used to be a factor on
older motherboards, but it has largely ceased to be a cause for concern.
Linux has historically had problems with its ability to service IRQs
quickly; this problem has caused enough trouble for audio developers
that several patches have been created to address this shortcoming.
So far, there has been some mild controversy over how to
incorporate these patches into the Linux kernel.
Kernel version
Asterisk is officially supported on Linux Version 2.6.
Linux distribution
Linux distributions are many and varied. In the next chapter, we will discuss the
challenge of selecting a Linux distribution, and how to obtain and install both
Linux and Asterisk.
Choosing a Processor
Since the performance demands of Asterisk will generally involve a large number of
math calculations, it is essential that you select a processor with a powerful FPU. The
signal processing that Asterisk performs can quickly demand a staggering quantity of
complex mathematical computations from the CPU. The efficiency with which these
tasks are carried out will be determined by the power of the FPU within the processor.
To actually name a best processor for Asterisk in this book would fly in the face of
Moore’s law. Even in the time between the authoring and publishing of this book,
processor speeds will undergo rapid improvements, as will Asterisk’s support for various
architectures. Obviously, this is a good thing, but it also makes the giving of advice
on the topic a thankless task. Naturally, the more powerful the FPU is, the more
concurrent DSP tasks Asterisk will be able to handle, so that is the ultimate consideration.
When you are selecting a processor, the raw clock speed is only part of the
equation. How well it handles floating-point operations will be a key differentiator, as
DSP operations in Asterisk will place a large demand on that process.
Both Intel and AMD CPUs have powerful FPUs. Current-generation chips from either
of those manufacturers can be expected to perform well.‡
16 | Chapter 2: Preparing a System for Asterisk
The obvious conclusion is that you should get the most powerful CPU your budget will
allow. However, don’t be too quick to buy the most expensive CPU out there. You’ll
need to keep the requirements of your system in mind; after all, a Formula 1 Ferrari is
ill-suited to the rigors of rush-hour traffic. Slower CPUs will often run cooler and, thus,
you might be able to build a lower-powered, fanless Asterisk system for a small office,
which could work well in a dusty environment, perhaps.
In order to attempt to provide a frame of reference from which we can contemplate our
platform decision, we have chosen to define three sizes of Asterisk systems: small,
medium, and large.
Small systems
Small systems (up to 10 phones) are not immune to the performance requirements of
Asterisk, but the typical load that will be placed on a smaller system will generally fall
within the capabilities of a modern processor.
If you are building a small system from older components you have lying around, be
aware that the resulting system cannot be expected to perform at the same level as a
more powerful machine, and will run into performance degradation under a much
lighter load. Hobby systems can be run successfully on very low-powered hardware,
although this is by no means recommended for anyone who is not a whiz at Linux
performance tuning.§
If you are setting up an Asterisk system for the purposes of learning, you will be able
to build a fully featured platform using a relatively low-powered CPU. The authors of
this book run several Asterisk lab systems with 433 MHz to 700 MHz Celeron processors,
but the workload of these systems is minimal (never more than two concurrent
calls).
AstLinux and Asterisk on OpenWRT
If you are really comfortable working with Linux on embedded platforms, you will want
to join the AstLinux mailing list and run Kristian Kielhofner’s creation, AstLinux, or
get yourself a Linksys WRT54GL and install Brian Capouch’s version of Asterisk for
that platform.
These projects strip Asterisk down to its essentials, and allow incredibly powerful PBX
applications to be deployed on very inexpensive hardware.
‡ If you want to be completely up to the minute on which CPUs are leading the performance race, surf on over
to Tom’s Hardware (http://www.tomshardware.com) or AnandTech (http://www.anandtech.com), where you
will find a wealth of information about both current and out-of-date CPUs, motherboards, and chipsets.
§ Greg Boehnlein once compiled and ran Asterisk on a 133 MHz Pentium system, but that was mostly as an
experiment. Performance problems are far more likely, and properly configuring such a system requires an
expert knowledge of Linux. We do not recommend running Asterisk on anything less than a 500 MHz system
(for a production system, 2 GHz might be a sensible minimum). Still, we think the fact that Asterisk is so
flexible is remarkable.
Server Hardware Selection | 17
While both projects require a fair amount of knowlege and effort on your part, they
also share a huge coolness factor, are extrememly popular, and are of excellent quality.
Medium systems
Medium-sized systems (from 10 to 50 phones) are where performance considerations
will be the most challenging to resolve. Generally, these systems will be deployed on
one or two servers only and, thus, each machine will be required to handle more than
one specific task. As loads increase, the limits of the platform will become increasingly
stressed. Users may begin to perceive quality problems without realizing that the system
is not faulty in any way, but simply exceeding its capacity. These problems will get
progressively worse as more and more load is placed on the system, with the user experience
degrading accordingly. It is critical that performance problems be identified
and addressed before they are noticed by users.
Monitoring performance on these systems and quickly acting on any developing trends
is key to ensuring that a quality telephony platform is provided.
Large systems
Large systems (more than 120 channels) can be distributed across multiple systems and
sites and, thus, performance concerns can be managed through the addition of machines.
Very large Asterisk systems have been created in this way.
Building a large system requires an advanced level of knowledge in many different
disciplines. We will not discuss it in detail in this book, other than to say that the issues
you’ll encounter will be similar to those encountered during any deployment of multiple
servers handling a single, distributed task.
Choosing a Motherboard
Just to get any anticipation out of the way, we also cannot recommend specific motherboards
in this book. With new motherboards coming out on a weekly basis, any
recommendations we could make would be rendered moot by obsolescence before the
published copy hit the shelves. Not only that, but motherboards are like automobiles:
while they are all very similar in principle, the difference is in the details. And as Asterisk
is a performance application, the details matter.
What we will do, therefore, is give you some idea of the kinds of motherboards that
can be expected to work well with Asterisk, and the features that will make for a good
motherboard. The key is to have both stability and high performance. Here are some
guidelines to follow:
• The various system buses must provide the minimum possible latency. If you are
planning a PSTN connection using analog or PRI interfaces (discussed later in this
chapter), having Zaptel cards in the system will generate 1,000 interrupt requests
18 | Chapter 2: Preparing a System for Asterisk
per second. Having devices on the bus that interfere with this process will result
in degradation of call quality. Chipsets from Intel (for Intel CPUs) and nVidia
nForce (for AMD CPUs) seem to score the best marks in this area. Review the
specific chipset of any motherboard you are evaluating to ensure that it does not
have known problems with IRQ latency.
• If you are running Zaptel cards in your system, you will want to ensure that your
BIOS allows you maximum control over IRQ assignment. As a rule, high-end
motherboards will offer far greater flexibility with respect to BIOS tweaking; valuepriced
boards will generally offer very little control. This may be a moot point,
however, as APIC-enabled motherboards turn IRQ control over to the operating
system.
• Server-class motherboards generally implement a different PCI standard than
workstation-class motherboards. While there are many differences, the most obvious
and well known is that the two versions have different voltages. Depending
on which cards you purchase, you will need to know if you require 3.3V or 5V PCI
slots.‖ Figure 2-1 shows the visual differences between 3.3V and 5V slots. Most
server motherboards will have both types, but workstations will typically have only
the 5V version.
There is some evidence that suggests connecting together two completely
separate, single-CPU systems may provide far more benefits
than simply using two processors in the same machine. You not
only double your CPU power, but you also achieve a much better
level of redundancy at a similar cost to a single-chassis, dual-CPU
machine. Keep in mind, though, that a dual-server Asterisk solution
will be more complex to design than a single-machine solution.
• Consider using multiple processors, or processors with multiple cores. This will
provide an improvement in the system’s ability to handle multiple tasks. For Asterisk,
this will be of special benefit in the area of floating-point operations.
• If you need a modem, install an external unit that connects to a serial port. If you
must have an internal modem, you will need to ensure that it is not a so-called
“Win-modem”—it must be a completely self-sufficient unit (note that these are
very difficult, if not impossible, to find).
• Consider that with built-in networking, if you have a network component failure,
the entire motherboard will need to be replaced. On the other hand, if you install
a peripheral Network Interface Card (NIC), there may be an increased chance of
‖ With the advent of PCI-X and PCI-Express, it is becoming harder and harder to select a motherboard with
the correct type of slots. Be very certain that the motherboard you select has the correct type and quantity of
card slots for your hardware. Keep in mind that most companies that produce hardware cards for Asterisk
offer PCI and PCI-Express versions, but it’s still up to you to make sure they make sense in whatever
motherboard and chassis combination you choose.
Server Hardware Selection | 19
failure due to the extra mechanical connections involved. It can also be useful to
have separate network cards serving sets and users (the internal network) and VoIP
providers and external sites (the external network). NICs are cheap; we suggest
always having at least two.
• The stability and quality of your Asterisk system will be dependent on the components
you select for its architecture. Asterisk is a beast, and it expects to be fed
the best. As with just about anything, high cost is not always synonymous with
quality, but you will want to become a connoisseur of computer components.
Having said all that, we need to get back to the original point: Asterisk can and will
happily install on pretty much any system that will run Linux. The lab systems used to
write this book, for example, included everything from a Linksys WRT to a dual-Xeon
locomotive.# We have not experienced any performance or stability problems running
less than five concurrent telephone connections. For the purposes of learning, do not
be afraid to install Asterisk on whatever system you can scrounge up. When you are
ready to put your system into production, however, you will need to understand the
ramifications of the choices you make with respect to your hardware.
Power Supply Requirements
One often-overlooked component in a PC is the power supply (and the supply of power).
For a telecommunications system,* these components can play a significant role in
the quality of the user experience.
3.3V 32-bit
5V 32-bit
3.3V 64-bit
5V 64-bit
Figure 2-1. Visual identification of PCI slots
# OK, it wasn’t actually a locomotive, but it sure sounded like one. Does anyone know where to get quiet CPU
fans for Xeon processors? It’s getting too loud in the lab here.
* Or any system that is expected to process audio.
20 | Chapter 2: Preparing a System for Asterisk
Computer power supplies
The power supply you select for your system will play a vital role in the stability of the
entire platform. Asterisk is not a particularly power-hungry application, but anything
relating to multimedia (whether it be telephony, professional audio, video, or the like)
is generally sensitive to power quality.
This oft-neglected component can turn an otherwise top-quality system into a poor
performer. By the same token, a top-notch power supply might enable an otherwise
cheap PC to perform like a champ.
The power supplied to a system must provide not only the energy the system needs to
perform its tasks but also stable, clean signal lines for all of the voltages your system
expects from it.
Spend the money and get a top-notch power supply (gamers are pretty passionate about
this sort of thing, so there are lots of choices out there).
Redundant power supplies
In a carrier-grade or high-availability environment, it is common to deploy servers that
use a redundant power supply. Essentially, this involves two completely independent
power supplies, either one of which is capable of meeting the power requirements of
the system.
If this is important to you, keep in mind that best practices suggest that to be properly
redundant, these power supplies should be connected to completely independent uninterruptible
power supplies (UPSes) that are in turn fed by totally separate electrical
circuits. In truly mission-critical environments (such as hospitals), even the main electrical
feeds into the building are redundant, and diesel-powered generators are on-site
to generate electricity during extended power failures (such as the one that hit Northeastern
North America on August 15, 2003).
Environment
Your system’s environment consists of all of those factors that are not actually part of
the server itself but nevertheless play a crucial role in the reliability and quality that can
be expected from the system. Electrical supplies, room temperature and humidity,
sources of interference, and security are all factors that should be contemplated.
Power Conditioning and Uninterruptible Power Supplies
When selecting the power sources for your system, consideration should be given not
only to the amount of power the system will use, but also to the manner in which this
power is delivered.
Environment | 21
Power is not as simple as voltage coming from the outlet in the wall, and you should
never just plug a production system into whatever electrical source is near at
hand.†Giving some consideration to the supply of power to your system can provide a
far more stable power environment, leading to a far more stable system.
One of the benefits of clean power is a reduction in heat, which means less stress on
components, leading to a longer life expectancy.
Properly grounded, conditioned power feeding a premium-quality power supply will
ensure a clean logic ground (a.k.a. 0 volt) reference‡ for the system and keep electrical
noise on the motherboard to a minimum. These are industry-standard best practices
for this type of equipment, which should not be neglected. A relatively simple way to
achieve this is through the use of a power-conditioned UPS.§
Power-conditioned UPSes
The UPS is well known for its role as a battery backup, but the power-conditioning
benefits that high-end UPS units also provide are less well understood.
Power conditioning can provide a valuable level of protection from the electrical environment
by regenerating clean power through an isolation transformer. A quality
power conditioner in your UPS will eliminate most electrical noise from the power feed
and help to ensure a rock-steady supply of power to your system.
Unfortunately, not all UPS units are created equal; many of the less expensive units do
not provide clean power. What’s worse, manufacturers of these devices will often
promise all kinds of protection from surges, spikes, overvoltages, and transients. While
such devices may protect your system from getting fried in an electrical storm, they will
not clean up the power being fed to your system and, thus, will do nothing to contribute
to stability.
Make sure your UPS is power conditioned. If it doesn’t say exactly that, it isn’t.
Grounding
Voltage is defined as the difference in electrical potential between two points. When
considering a ground (which is basically nothing more than an electrical path to earth),
the common assumption is that it represents 0 volts. But if we do not define that 0V in
† Okay, look, you can plug it in wherever you’d like, and it’ll probably work, but if your system has strange
stability problems, please give this section another read. Deal?
‡ In electronic devices, a binary zero (0) is generally related to a 0 volt signal, while a binary one (1) can be
represented by many different voltages (commonly between 2.5 and 5 volts). The grounding reference that
the system will consider 0 volts is often referred to as the logic ground. A poorly grounded system might have
electrical potential on the logic ground to such a degree that the electronics mistake a binary zero for a binary
one. This can wreak havoc with the system’s ability to process instructions.
§ It is a common misconception belief that all UPSes provide clean power. This is not at all true.
22 | Chapter 2: Preparing a System for Asterisk
relation to something, we are in danger of assuming things that may not be so. If you
measure the voltage between two grounding references, you’ll often find that there is
a voltage potential between them. This voltage potential between grounding points can
be significant enough to cause logic errors—or even damage—in a system where more
than one path to ground is present.
One of the authors recalls once frying a sound card he was trying to
connect to a friend’s stereo system. Even though both the computer and
the stereo were in the same room, more than 6 volts of difference was
measured between the ground conductors of the two electrical outlets
they were plugged into! The wire between the stereo and the PC (by way
of the sound card) provided a path that the voltage eagerly followed,
thus frying a sound card that was not designed to handle that much
current on its signal leads. Connecting both the PC and the stereo to the
same outlet fixed the problem.
When considering electrical regulations, the purpose of a ground is primarily human
safety. In a computer, the ground is used as a 0V logic reference. An electrical system
that provides proper safety will not always provide a proper logic reference—in fact,
the goals of safety and power quality are sometimes in disagreement. Naturally, when
a choice must be made, safety has to take precedence.
Since the difference between a binary zero and a binary one is represented
in computers by voltage differences of sometimes less than 3V, it is
entirely possible for unstable power conditions caused by poor grounding
or electrical noise to cause all kinds of intermittent system problems.
Some power and grounding advocates estimate that more than 80 percent
of unexplained computer glitches can be traced to power quality.
Most of us blame Microsoft.
Modern switching power supplies are somewhat isolated from power quality issues,
but any high-performance system will always benefit from a well-designed power environment.
In mainframes, proprietary PBXes, and other expensive computing
platforms, the grounding of the system is never left to chance. The electronics and
frames of these systems are always provided with a dedicated ground that does not
depend on the safety grounds supplied with the electrical feed.
Regardless of how much you are willing to invest in grounding, when you specify the
electrical supply to any PBX, ensure that the electrical circuit is completely dedicated
to your system (as discussed in the next section) and that an insulated, isolated grounding
conductor is provided. This can be expensive to provision, but it will contribute
greatly to a quality power environment for your system.‖
It is also vital that each and every peripheral you connect to your system be connected
to the same electrical receptacle (or, more specifically, the same ground reference). This
Environment | 23
will cut down on the occurrence of ground loops, which can cause anything from
buzzing and humming noises to damaged or destroyed equipment.
Electrical Circuits
If you’ve ever seen the lights dim when an electrical appliance kicks in, you’ve seen the
effect that a high-energy device can have on an electrical circuit. If you were to look at
the effects of a multitude of such devices, each drawing power in its own way, you
would see that the harmonically perfect 50 or 60 Hz sine wave you may think you’re
getting with your power is anything but. Harmonic noise is extremely common on
electrical circuits , and it can wreak havoc on sensitive electronic equipment. For a PBX,
these problems can manifest as audio problems, logic errors, and system instability.
Ideally, you should never install a server on an electrical circuit that is shared with other
devices. There should be only one outlet on the circuit, and you should connect only
your telephone system (and associated peripherals) to it. The wire (including the
ground) should be run unbroken directly back to the electrical panel. The grounding
conductor should be insulated and isolated. There are far too many stories of photocopiers,
air conditioners, and vacuum cleaners wreaking havoc with sensitive electronics
to ignore this rule of thumb.
The electrical regulations in your area must always take precedence over
any ideas presented here. If in doubt, consult a power quality expert in
your area on how to ensure that you adhere to electrical regulations.
Remember, electrical regulations take into account the fact that human
safety is far more important than the safety of the equipment.
The Equipment Room
Environmental conditions can wreak havoc on systems, and yet it is quite common to
see critical systems deployed with little or no attention given to these matters. When
the system is installed, everything works well, but after as little as six months, components
begin to fail. Talk to anyone with experience in maintaining servers and systems,
and it becomes obvious that attention to environmental factors can play a significant
role in the stability and reliability of systems.
Humidity
Simply put, humidity is water in the air. Water is a disaster for electronics for two main
reasons: 1) water is a catalyst for corrosion, and 2) water is conductive enough that it
‖ On a hobby system, this is probably too much to ask, but if you are planning on using Asterisk for anything
important, at least be sure to give it a fighting chance; don’t put anything like air conditioners, photocopiers,
laser printers, or motors on the same circuit. The strain such items place on your power supply will shorten
its life expectancy.
24 | Chapter 2: Preparing a System for Asterisk
can cause short circuits. Do not install any electronic equipment in areas of high humidity
without providing a means to remove the moisture.
Temperature
Heat is the enemy of electronics. The cooler you keep your system, the more reliably
it will perform, and the longer it will last. If you cannot provide a properly cooled room
for your system, at a minimum ensure that it is placed in a location that ensures a steady
supply of clean, cool air. Also, keep the temperature steady. Changes in temperature
can lead to condensation and other damaging changes.
Dust
An old adage in the computer industry holds that dust bunnies inside of a computer
are lucky. Let’s consider some of the realities of dust bunnies:
• Significant buildup of dust can restrict airflow inside the system, leading to increased
levels of heat.
• Dust can contain metal particles, which, in sufficient quantities, can contribute to
signal degradation or shorts on circuit boards.
Put critical servers in a filtered environment, and clean out dust bunnies on a regular
schedule.
Security
Server security naturally involves protecting against network-originated intrusions, but
the environment also plays a part in the security of a system. Telephone equipment
should always be locked away, and only persons who have a need to access the equipment
should be allowed near it.
Telephony Hardware
If you are going to connect Asterisk to any traditional telecommunications equipment,
you will need the correct hardware. The hardware you require will be determined by
what it is you want to achieve.
Connecting to the PSTN
Asterisk allows you to seamlessly bridge circuit-switched telecommunications networks#
with packet-switched data networks.* Because of Asterisk’s open architecture
(and open source code), it is ultimately possible to connect any standards-compliant
# Often referred to as TDM networks, due to the Time Division Multiplexing used to carry traffic through the
PSTN.
Telephony Hardware | 25
interface hardware. The selection of open source telephony interface boards is currently
limited, but as interest in Asterisk grows, that will rapidly change.† At the moment, one
of the most popular and cost-effective ways to connect to the PSTN is to use the interface
cards that evolved from the work of the Zapata Telephony Project (http://www.za
patatelephony.org).
Analog interface cards
Unless you need a lot of channels (or a have lot of money to spend each month on
telecommunications facilities), chances are that your PSTN interface will consist of one
or more analog circuits, each of which will require a Foreign eXchange Office (FXO)
port.
Digium, the company that sponsors Asterisk development, produces analog interface
cards for Asterisk. Check out its web site for its extensive line of analog cards, including
the venerable TDM400P, the latest TDM800P, and the high-density TDM2400P. As
an example, the TDM800P is an eight-port base card that allows for the insertion of up
to two daughter cards, which each deliver either four FXO or four FXS ports.‡ The
TDM800P can be purchased with these modules preinstalled, and a hardware echocanceller
can be added as well. Check out Digium’s web site (http://www.digium.com)
for more information about these cards.
Other companies that produce Asterisk-compatible analog cards include:
• Rhino (http://www.channelbanks.com)
• Sangoma (http://www.sangoma.com)
• Voicetronix (http://www.voicetronix.com)
• Pika Technologies (http://www.pikatechnologies.com)
These are all well-established companies that produce excellent products.
Digital interface cards
If you require more than 10 circuits, or require digital connectivity, chances are you’re
going to be in the market for a T1 or E1 card.§ Bear in mind, though, that the monthly
charges for a digital PSTN circuit vary widely. In some places, as few as five circuits can
justify a digital circuit; in others, the technology may never be cost-justifiable. The more
* Popularly called VoIP networks, although Voice over IP is not the only method of transmitting voice over
packet networks (Voice over Frame Relay was very popular in the late 1990s).
† The evolution of inexpensive, commodity-based telephony hardware is only slightly behind the telephony
software revolution. New companies spring up on a weekly basis, each one bringing new and inexpensive
standards-based devices into the market.
‡ FXS and FXO refer to the opposing ends of an analog circuit. Which one you need will be determined by
what you want to connect to. Chapter 7 discusses these in more detail.
§ T1 and E1 are digital telephony circuits. We’ll discuss them further in Chapter 7.
26 | Chapter 2: Preparing a System for Asterisk
competition there is in your area, the better chance you have of finding a good deal. Be
sure to shop around.
The Zapata Telephony Project originally produced a T1 card, the Tormenta, that is the
ancestor of most Asterisk-compatible T1 cards. The original Tormenta cards are now
considered obsolete, but they do still work with Asterisk.
Digium makes several different digital circuit interface cards. The features on the cards
are the same; the primary differences are whether they provide T1 or E1 interfaces, and
how many spans each card provides. Digium has been producing Zaptel cards for Linux
longer than anyone else, as they were deeply involved with the development of Zaptel
on Linux, and have been the driving force behind Zaptel development over the years.
Sangoma, which has been producing open source WAN cards for many years, added
Asterisk support for its T1/E1 cards a few years ago.‖ Rhino has had T1 hardware for
Asterisk for a while now, and there are many other companies that offer digital interface
cards for Asterisk as well.
Channel banks
A channel bank is loosely defined as a device that allows a digital circuit to be demultiplexed
into several analog circuits (and vice versa). More specifically, a channel
bank lets you connect analog telephones and lines into a system across a T1 line.
Figure 2-2 shows how a channel bank fits into a typical office phone system.
Although they can be expensive to purchase, many people feel very strongly that the
only proper way to integrate analog circuits and devices into Asterisk is through a
channel bank. Whether that is true or not depends on a lot of factors, but if you have
the budget, they can be very useful.# You can often pick up used channel banks on
eBay. Look for units from Adtran and Carrier Access Corp. (Rhino makes great channel
‖ It should be noted that a Sangoma Frame Relay card played a role in the original development of Asterisk
(see http://linuxdevices.com/articles/AT8678310302.html); Sangoma has a long history of supporting open
source WAN interfaces with Linux.
FXO
FXS
Channel bank
T1
PBX
Digital Analog
Central office
FXS
Figure 2-2. One way you might connect a channel bank
Telephony Hardware | 27
banks, and they are very competitively priced, but they may be hard to find used on
eBay.) Don’t forget that you will need a T1 card in order to connect a channel bank to
Asterisk.
Other types of PSTN interfaces
Many VoIP gateways exist that can be configured to provide access to PSTN circuits.
Generally speaking, these will be of most use in a smaller system (one or two lines).
They can also be very complicated to configure, as grasping the interaction between
the various networks and devices requires a solid understanding of both telephony and
VoIP fundamentals. For that reason, we will not discuss these devices in detail in this
book. They are worth looking into, however; popular units are made by Sipura, Grandstream,
Digium, and many other companies.
Another way to connect to the PSTN is through the use of Basic Rate Interface (BRI)
ISDN circuits. BRI is a digital telecom standard that specifies a two-channel circuit that
can carry up to 144 Kbps of traffic. It is very rarely used in North America, but in Europe
it is very widely deployed. Due to the variety of different ways this technology has been
implemented, and a lack of testing equipment, we will not be discussing BRI in very
much detail in this book. Please note, however, that BRI is very popular in Europe, and
Digium has produced the B410P card to address this need.
Connecting Exclusively to a Packet-Based Telephone Network
If you do not need to connect to the PSTN, Asterisk requires no hardware other than
a server with a Network Interface Card (NIC).
However, if you are going to be providing music on hold* or conferencing and you have
no physical timing source, you will need the ztdummy Linux kernel module.
ztdummy is a clocking mechanism designed to provide a timing source to a system
where no hardware timing source exists. Think of it as a kind of metronome to allow
the system to mix multiple audio streams in a properly synchronized manner.
Echo Cancellation
One of the issues that can arise if you use analog interfaces on a VoIP system is echo.
Echo is simply what you say being reflected back to you a short time later. The echo is
caused by the far end, but you are the one that hears it. It is a little known fact that echo
would be a massive problem in the PSTN were it not for the fact that the carriers employ
complex (and expensive) strategies to eliminate it. We will talk about echo a bit more
later on, but with respect to hardware we would suggest that you consider adding echo-
# We use channel banks to simulate a central office. One 24-port channel bank off an Asterisk system can
provide up to 24 analog lines—perfect for a classroom or lab.
* Technically, no timing source is needed for music on hold, but it generally works better with one.
28 | Chapter 2: Preparing a System for Asterisk
cancellation hardware to any card you purchase for use as a PSTN interface. While
Asterisk can do some work with echo in software, it does not provide nearly enough
power to deal with the problem. Also, echo cancellation in software imposes a load on
the processor; hardware echo cancellers built into the PSTN card take this burden away
from the CPU.
Hardware echo cancellation can add several hundred dollars to your equipment cost,
but if you are serious about having a quality system, invest the extra money now instead
of suffering later. Echo problems are not pleasant at all, and your users will hate the
system if they experience it.
As of this writing, several software echo cancellers have become available. We have not
had a chance to evaluate any of them, but we know that they employ the same algorythems
the hardware echo cancellers do. If you have a recently purchased Digium analog
card, you can call Digium sales for a keycode to allow its latest software echo canceller
to work with your system.† There are other software options available for other types
of cards, but you will have to look into whether you have to purchase a license to use
them.‡ Keep in mind that there is a performance cost to using software echo cancellers.
They will place a measureable load on the CPU that needs to be taken into account
when you design a system using these technologies.
Types of Phones
Since the title of this book is Asterisk: The Future of Telephony, we would be remiss if
we didn’t discuss the devices that all of this technology ultimately has to interconnect:
telephones!
We all know what a telephone is—but will it be the same five years from now? Part of
the revolution that Asterisk is contributing to is the evolution of the telephone, from a
simple audio communications device into a multimedia communications terminal providing
all kinds of yet-to-be-imagined functions.
As an introduction to this exciting concept, we will briefly discuss the various kinds of
devices we currently call “telephones” (any of which can easily be integrated with Asterisk).
We will also discuss some ideas about what these devices may evolve into in
the future (devices that will also easily integrate with Asterisk).
† This software is not part of a normal Asterisk download because Digium has to pay to license it separately.
Nevertheless, it has grandfathered it into all of its cards, so it is available for free to anyone who has a Digium
analog card that is still under warranty. If you are running a non-Digium analog card, you can purchase a
keycode for this software echo canceller from Digium’s web site.
‡ Sangoma also offers free software echo cancellation on their analog cards (up to six channels).
Types of Phones | 29
Physical Telephones
Any physical device whose primary purpose is terminating an on-demand audio communications
circuit between two points can be classified as a physical telephone. At a
minimum, such a device has a handset and a dial pad; it may also have feature keys, a
display screen, and various audio interfaces.
This section takes a brief look at the various user (or endpoint) devices you might want
to connect to your Asterisk system. We’ll delve more deeply into the mechanics of
analog and digital telephony in Chapter 7.
Analog telephones
Analog phones have been around since the invention of the telephone. Up until about
20 years ago, all telephones were analog. Although analog phones have some technical
differences in different countries, they all operate on similar principles.
This contiguous connection is referred to as a circuit, which the
telephone network used to use electromechanical switches to create—
hence the term circuit-switched network.
When a human being speaks, the vocal cords, tongue, teeth, and lips create a complex
variety of sounds. The purpose of the telephone is to capture these sounds and convert
them into a format suitable for transmission over wires. In an analog telephone, the
transmitted signal is analogous to the sound waves produced by the person speaking.
If you could see the sound waves passing from the mouth to the microphone, they
would be proportional to the electrical signal you could measure on the wire.
Analog telephones are the only kind of phone that are commonly available in any retail
electronics store. In the next few years, that can be expected to change dramatically.
Proprietary digital telephones
As digital switching systems developed in the 1980s and 1990s, telecommunications
companies developed digital Private Branch eXchanges (PBXes) and Key Telephone
Systems (KTSes). The proprietary telephones developed for these systems were completely
dependent on the systems to which they were connected and could not be used
on any other systems. Even phones produced by the same manufacturer were not crosscompatible
(for example, a Nortel Norstar set will not work on a Nortel Meridian 1
PBX). The proprietary nature of digital telephones limits their future. In this emerging
era of standards-based communications, they will quickly be relegated to the dustbin
of history.
The handset in a digital telephone is generally identical in function to the handset in
an analog telephone, and they are often compatible with each other. Where the digital
30 | Chapter 2: Preparing a System for Asterisk
phone is different is that inside the telephone, the analog signal is sampled and converted
into a digital signal—that is, a numerical representation of the analog waveform.
We’ll leave a detailed discussion of digital signals until Chapter 7; for now, suffice it to
say that the primary advantage of a digital signal is that it can be transmitted over
limitless distances with no loss of signal quality.
The chances of anyone ever making a proprietary digital phone directly compatible
with Asterisk are slim, but companies such as Citel (http://www.citel.com)§ have created
gateways that convert the proprietary signals to Session Initiation Protocol (SIP).‖
ISDN telephones
Prior to VoIP, the closest thing to a standards-based digital telephone was an ISDNBRI
terminal. Developed in the early 1980s, ISDN was expected to revolutionize the
telecommunications industry in exactly the same way that VoIP promises to finally
achieve today.
There are two types of ISDN: Primary Rate Interface (PRI) and
Basic Rate Interface (BRI). PRI is commonly used to provide trunking
facilities between PBXes and the PSTN, and is widely deployed all over
the world. BRI is not at all popular in North America, but is common
in Europe.
While ISDN was widely deployed by the telephone companies, many consider the
standard to have been a flop, as it generally failed to live up to its promises. The high
costs of implementation, recurring charges, and lack of cooperation among the major
industry players contributed to an environment that caused more problems than it
solved.
BRI was intended to service terminal devices and smaller sites (a BRI loop provides two
digital circuits). A wealth of BRI devices have been developed, but BRI has largely been
deprecated in favor of faster, less expensive technologies such as ADSL, cable modems,
and VoIP.
BRI is still very popular for use in video-conferencing equipment, as it provides a fixed
bandwidth link. Also, BRI does not have the type of quality of service issues a VoIP
connection might, as it is circuit-switched.
§ Citel has produced a fantastic product that is limited by the fact that it is too expensive. If you have old
proprietary PBX telephones, and you want to use them with your Asterisk system, Citel’s technology can do
the job, but make sure you understand how the per-port cost of these units stacks up against replacing the
old sets with pure VoIP telephones.
‖ The SIP is currently the most well-known and popular protocol for VoIP. We will discuss it further in
Chapter 8.
Types of Phones | 31
BRI is still sometimes used in place of analog circuits to provide trunking to a PBX.
Whether or not this is a good idea depends mostly on how your local phone company
prices the service, and what features it is willing to provide.#
IP telephones
IP telephones are heralds of the most exciting change in the telecommunications industry.
Already now, standards-based IP telephones are available in retail stores. The
wealth of possibilities inherent in these devices will cause an explosion of interesting
applications, from video phones to high-fidelity broadcasting devices, to wireless mobility
solutions, to purpose-built sets for particular industries, to flexible all-in-one
multimedia systems.
The revolution that IP telephones will spawn has nothing to do with a new type of wire
to connect your phone to, and everything to do with giving you the power to communicate
the way you want.
The early-model IP phones that have been available for several years now do not represent
the future of these exciting appliances. They are merely a stepping-stone, a
familiar package in which to wrap a fantastic new way of thinking.
The future is far more promising.
Softphones
A softphone is a software program that provides telephone functionality on a non-telephone
device, such as a PC or PDA. So how do we recognize such a beast? What might
at first glance seem a simple question actually raises many. A softphone should probably
have some sort of dial pad, and it should provide an interface that reminds users of a
telephone. But will this always be the case?
The term softphone can be expected to evolve rapidly, as our concept of what exactly
a telephone is undergoes a revolutionary metamorphosis.* As an example of this evolution,
consider the following: would we correctly define popular communication
programs such as Instant Messenger as softphones? IM provides the ability to initiate
and receive standards-based VoIP connections. Does this not qualify it as a softphone?
Answering that question requires knowledge of the future that we do not yet possess.
Suffice it to say that while at this point in time, softphones are expected to look and
sound like traditional phones, that conception is likely to change in the very near future.
As standards evolve and we move away from the traditional telephone and toward a
multimedia communications culture, the line between softphones and physical telephones
will become blurred indeed. For example, we might purchase a communica-
# If you are in North America, give up on this idea, unless you have a lot of patience and money, and are a bit
of a masochist.
* Ever heard of Skype?
32 | Chapter 2: Preparing a System for Asterisk
tions terminal to serve as a telephone and install a softphone program onto it to provide
the functions we desire.
Having thus muddied the waters, the best we can do at this point is to define what the
term softphone will refer to in relation to this book, with the understanding that the
meaning of the term can be expected to undergo a massive change over the next few
years. For our purposes, we will define a softphone as any device that runs on a personal
computer, presents the look and feel of a telephone, and provides as its primary function
the ability to make and receive full-duplex audio communications (formerly known as
“phone calls”)† through E.164 addressing.‡
Telephony Adaptors
A telephony adaptor (usually referred to as an ATA, or Analog Terminal Adaptor) can
loosely be described as an end-user device that converts communications circuits from
one protocol to another. Most commonly, these devices are used to convert from some
digital (IP or proprietary) signal to an analog connection that you can plug a standard
telephone or fax machine into.
These adaptors could be described as gateways, for that is their function. However,
popular usage of the term telephony gateway would probably best describe a multiport
telephony adaptor, generally with more complicated routing functions.
Telephony adaptors will be with us for as long as there is a need to connect incompatible
standards and old devices to new networks. Eventually, our reliance on these devices
will disappear, as did our reliance on the modem—obsolescence through irrelevance.
Communications Terminals
Communications terminal is an old term that disappeared for a decade or two and is
being reintroduced here, very possibly for no other reason than that it needs to be
discussed so that it can eventually disappear again—once it becomes ubiquitous.
First, a little history. When digital PBX systems were first released, manufacturers of
these machines realized that they could not refer to their endpoints as telephones—
their proprietary nature prevented them from connecting to the PSTN. They were
therefore called terminals, or stations. Users, of course, weren’t having any of it. It
looked like a telephone and acted like a telephone, and therefore it was a telephone.
You will still occasionally find PBX sets referred to as terminals, but for the most part
they are called telephones.
† OK, so you think you know what a phone call is? So did we. Let’s just wait a few years, shall we?
‡ E.164 is the ITU standard that defines how phone numbers are assigned. If you’ve used a telephone, you’ve
used E.164 addressing.
Types of Phones | 33
The renewed relevance of the term communications terminal has nothing to do with
anything proprietary—rather, it’s the opposite. As we develop more creative ways of
communicating with each other, we gain access to many different devices that will allow
us to connect. Consider the following scenarios:
• If I use my PDA to connect to my voicemail and retrieve my voice messages (converted
to text), does my PDA become a phone?
• If I attach a video camera to my PC, connect to a company’s web site, and request
a live chat with a customer service rep, is my PC now a telephone?
• If I use the IP phone in my kitchen to surf for recipes, is that a phone call?
The point is simply this: we’ll probably always be “phoning” each other, but will we
always be using “telephones” to do so?
Linux Considerations
If you ask anyone at the Free Software Foundation, they will tell you that what we know
as Linux is in fact GNU/Linux. All etymological arguments aside, there is some valuable
truth to this statement. While the kernel of the operating system is indeed Linux, the
vast majority of the utilities installed on a Linux system and used regularly are in fact
GNU utilities. “Linux” is probably only 5 percent Linux, possibly 75 percent GNU,
and perhaps 20 percent everything else.
Why does this matter? Well, the flexibility of Linux is both a blessing and a curse. It is
a blessing because with Linux you can truly craft your very own operating system from
scratch. Since very few people ever do this, the curse is in large part due to the responsibility
you must bear in determining which of the GNU utilities to install, and how to
configure the system.
If this seems overwhelming, do not fear. In the next chapter, we will discuss the selection,
installation, and configuration of the software environment for your Asterisk
system.
Conclusion
In this chapter, we’ve discussed all manner of issues that can contribute to the stability
and quality of an Asterisk installation. Before we scare you off, we should tell you that
many people have installed Asterisk on top of a graphical Linux workstation—running
a web server, a database, and who knows what else—with no problems whatsoever.
§How much time and effort you should devote to following the best practices and
§ Just don’t ever install the X-windowing environment (which is anything that delivers a desktop, such as
GNOME, KDE, and such). You are almost guaranteed to have audio quality problems, as Asterisk and the
GUI will fight for control of the CPU.
34 | Chapter 2: Preparing a System for Asterisk
engineering tips in this chapter all depends on how much work you expect the Asterisk
server to perform, and how much quality and reliability your system must provide. If
you are experimenting with Asterisk, don’t worry too much; just be aware that any
problems you have may not be the fault of the Asterisk system.
What we have attempted to do in this chapter is give you a feel for the kinds of best
practices that will help to ensure that your Asterisk system will be built on a reliable,
stable platform. Asterisk is quite willing to operate under far worse conditions, but the
amount of effort and consideration you decide to give these matters will play a part in
the stability of your PBX. Your decision should depend on how critical your Asterisk
system will be.
Conclusion | 35

CHAPTER 3
Installing Asterisk
I long to accomplish great and noble tasks, but it is my
chief duty to accomplish humble tasks as though they
were great and noble. The world is moved along, not
only by the mighty shoves of its heroes, but also by the
aggregate of the tiny pushes of each honest worker.
—Helen Keller
In the previous chapter, we discussed preparing a system to install Asterisk. Now it’s
time to get our hands dirty!
Although a large number of Linux* distributions and PC architectures are excellent
candidates for Asterisk, we have chosen to focus on a single distribution in order to
maintain brevity and clarity throughout the book. The instructions that follow have
been made as generic as possible, but you will notice a leaning toward CentOS directory
structure and system utilities. We have chosen to focus on CentOS (arguably, the most
popular distro for Asterisk) because its command set, directory structure, and so forth
are likely to be familiar to a larger percentage of readers (we have found that many
Linux administrators are familiar with CentOS, even if they don’t prefer it). This doesn’t
mean that CentOS is the only choice, or even the best one for you. A question that often
appears on the mailing lists is: “Which distribution of Linux is the best to use with
Asterisk?” The multitude of answers generally boils down to “the one you like the
best.Ӡ
* And some non-Linux operating systems as well, such as Solaris, *BSD, and OS X. You should note that while
people have managed to successfully run Asterisk on these alternative systems, Asterisk was, and continues
to be, actively developed for Linux.
† We will be using CentOS Server 4.4 in this book, which we usually install with nothing except the Editors
package selected. If you are not sure what distribution to choose, CentOS is an excellent choice. CentOS can
be obtained from http://www.centos.org.
37
What Packages Do I Need?
Most Asterisk configurations are composed of three main packages : the main Asterisk
program (asterisk), the Zapata telephony drivers (zaptel), and the PRI libraries (libpri).
If you plan on a pure VoIP network, the only real requirement is the asterisk package,
but we recommend installing all three packages; you can choose what modules to activate
later. The zaptel drivers are required if you are using analog or digital hardware,
or if you’re using the ztdummy driver (discussed later in this chapter) as a timing source.
The libpri library is optional unless you’re using ISDN PRI interfaces, and you may save
a small amount of RAM if you don’t load it, but we recommend that it be installed in
conjunction with the zaptel package for completeness.
In the first edition of this book, we recommended that you install the additional
asterisk-sounds package. This was a separate compressed archive that you would
download, extract, and then install. As of Asterisk version 1.4.0, there are now two sets
of sounds packages: the Core Sound package and the Extra Sound package. Since Asterisk
supports several different audio formats, these packages can be obtained in a
number of different sound formats, such as G.729 and GSM. The reason for all of the
different formats is that Asterisk can use the sound format that requires the least amount
of CPU transcode. For example, if you have a lot of connections coming in on VoIP
channels that are running GSM, you would want to have the GSM version of the sound
files. You can select one or more sound prompt types in the menuselect screen (discussed
later in this chapter). We recommend that you install at least one type of sounds
file from both the Core Sound package and Extra Sound package menu items. Since
we may make use of some of the Extra Sound files throughout this book, we will assume
you have at least one of the formats installed.
Linux Package Requirements
To compile Asterisk, you must have the GCC compiler (version 3.x or later) and its
dependencies on your system. Asterisk also requires bison, a parser generator program
that replaces yacc, and ncurses for CLI functionality. The cryptographic library in Asterisk
requires OpenSSL and its development packages.
Zaptel requires libnewt and its development packages for the zttool program (see “Using
ztcfg and zttool later in this chapter). If you’re using PRI interfaces, Zaptel also requires
the libpri package (again, even if you aren’t using PRI circuits, we recommend that you
install libpri along with zaptel).
If you install the Software Development packages in CentOS, you will have all of these
tools. If you are looking to keep things trim, and wish to install the bare minimum to
compile Asterisk and its related packages, Table 3-1 will prove useful.
38 | Chapter 3: Installing Asterisk
In the following table, the -y switch to the yum application means to
answer yes to all prompts, and using it will install the application and
all dependencies without prompting you. If this is not what you want,
omit the -y switch.
If you just want to install all of the above packages in one go, you can
specify more than one package on the command line, e.g.:
# yum install -y gcc ncurses-devel libtermcap-devel [...]
Table 3-1. List of packages required to compile libpri, zaptel, and asterisk
Package name Installation command Note Used by
GCC 3.x yum install -y
gcc
Required to compile zaptel,
libpri, and asterisk
libpri, zaptel, asterisk
ncurses-devel yum install -y
ncurses-devel
Required by menuselect menuselect
libtermcap-devel yum install -y
libtermcap-devel
Required by asterisk asterisk
Kernel Development Headers yum install -y
kernel-devel
Required to compile zaptel zaptel
Kernel Development
Headers (SMP)
yum install -y
kernel-smp-devel
Required to compile zaptel zaptel
GCC C++ 3.x yum install -y
gcc-c++
Required by asterisk asterisk
OpenSSL (optional) yum install -y
openssl-devel
Dependency of OSP, IAX2 encryption,
res_crypto (RSA
key support)
asterisk
newt-devel (optional) yum install -y
newt-devel
Dependency of zttool zaptel
zlib-devel (optional) yum install -y
zlib-devel
Dependency of DUNDi asterisk
unixODBC; unixODBC-devel
(optional)
yum install -y
unixODBC-devel
Dependency of func_odbc,
cdr_odbc, res_config_odbc,
res_odbc, ODBC_STORAGE
asterisk
libtool (optional;
recommended)
yum install -y
libtool
Dependency of ODBC-related
modules
asterisk
GNU make (version 3.80 or
higher) a
yum install -y
make
Required to compile zaptel
and asterisk
asterisk
a It is a common problem among new installs on some Linux distriebutons to see GNU make versions of 3.79 or lower. Note that Asterisk will
no longer build correctly unless you have at least version 3.80 of GNU make.
What Packages Do I Need? | 39
Obtaining the Source Code
The best place to get source code for Asterisk and it’s packages is directly from the
http://www.asterisk.org web site or FTP server.
Release Versus Trunk
The Asterisk code base is under a constant state of change. Developers use a sofware
revision tool called Subversion (SVN)‡ to manage the code base. Subversion allows a
communty of developers to collaborate with each other on complex programming
projects.
There are two main areas where Asterisk is developed, and these are referred to as the
Branch and the Trunk. In the Trunk, new features, architectural changes, and any of
the brand-new stuff that is going on is performed. This place in the code base contains
all the new toys, but at any time can be in a nonworking state, and is absolutely forbidden
from production use (see figure).
Trunk
1.0 1.2 1.4
Just like a tree, a Trunk will have Branches. These Branches have the major revision
numbers such as 1.0, 1.2, and 1.4 (in the future we will likely see 1.6, 1.8, 1.8.2, 1.8.4.
1.8.6, 1.8.8. 1.8.8.2…um…etc…).§ Within the Branch there are no major architectural
changes or new features—simply bug and security fixes. In a production environment,
stability is far more important than feature evolution.
Roughly every 14 months (although Asterisk does not follow a formal release timeline
like many commercial software packages), a version of Asterisk is released intended for
use in production environments. The first version of Asterisk was 1.0, which was released
at the very first AstriCon in Atlanta in September of 2004. Asterisk 1.2 was
released at IP4IT in November 2005, and Asterisk 1.4 was released in December of
2006.
Obtaining Asterisk Source Code
The easiest way to obtain the most recent release is through the use of the program
wget.
‡ Subversion is an excellent code management system, available at http://subversion.tigris.org/. It also has an equally
excellent Creative Commons released book, Version Control with Subversion, by Ben Collins Sussman et al.
(O’Reilly), available online at http://svnbook.red-bean.com/.
§ As of the release date of this book, there has been no determination that the next Asterisk release will be 1.6. It
could just as easily be 2.0. Therefore, when discussing new features, you’ll see us talk about what’s in Trunk or
what will be in the next release—without mentioning the specific version.
40 | Chapter 3: Installing Asterisk
Note that we will be making use of the /usr/src/ directory to extract and compile the
Asterisk source, although some system administrators may prefer to use /usr/local/src.
Also be aware that you will need root access to write files to the /usr/src/ directory and
to install Asterisk and its associated packages.
See Chapter 13 for information on running Asterisk as non-root. All
security professionals will recommend that you run your daemons as a
non-root user in case there are security vulnerabilities in the software.
This helps to lower (but obviously does not eliminate) the risk of someone
compromising the root user.
To obtain the latest release source code via wget, enter the following commands on the
command line:
# cd /usr/src/
# wget http://downloads.digium.com/pub/asterisk/asterisk-1.4-current.tar.gz
# wget http://downloads.digium.com/pub/libpri/libpri-1.4-current.tar.gz
# wget http://downloads.digium.com/pub/zaptel/zaptel-1.4-current.tar.gz
The latest versions of the asterisk, libpri, and zaptel packages may not
necessarily be the same version number.
Alternatively, during development and testing you will probably want to work with the
latest branch. To check it out from SVN, run:
# svn co http://svn.digium.com/svn/asterisk/branches/1.4 asterisk-1.4
If you retrieved the described source code via the release files on the Digium FTP server,
then extract the files as described in the next section before continuing on with
compiling.
Extracting the Source Code
The packages you downloaded from the FTP server are compressed archives containing
the source code; thus, you will need to extract them before compiling. If you didn’t
download the packages to /usr/src/, either move them there now or specify the full path
to their location. We will be using the GNU tar application to extract the source code
from the compressed archive. This is a simple process that can be achieved through the
use of the following commands:
# cd /usr/src/
# tar zxvf zaptel-1.4-current.tar.gz
# tar zxvf libpri-1.4-current.tar.gz
# tar zxvf asterisk-1.4-current.tar.gz
Obtaining the Source Code | 41
In bash (and other shell systems which support it), you can use an extremely
handy feature called Tab completion. This will allow you to type
part of a filename and have the rest of it completed automatically. For
example, if you type tar zxvf zap<tab> that will complete the full
zaptel filename for you. If more than one filename matches the pattern
and you hit Tab twice, it will list the files matching that pattern.
These commands will extract the packages and source code to their respective directories.
When you extract the asterisk-1.4-current.tar.gz file, you will find that the file
will extract to the current version of Asterisk, i.e. asterisk-1.4.4.
It’s always a good idea to keep the source code of the most recently
working version of a package in case you have to “roll back” out of a
new bug introduced, or some other strange behavior you can’t solve
immediately.
Menuselect
In the 1.4.0 version of Asterisk and its related packages, a new build system,
autoconf, was implemented. This has changed the build process slightly, but has given
more flexibilty to control what modules are being built at build time. This has an advantage
in that we only have to build the modules we want and need instead of building
everything.
Along with the new build system, a new menu-based selection system was introduced,
courtesy of Russell Bryant. This new system permits a finer-grained selection to which
modules are built before compiling the software and no longer requires the user to edit
Makefiles. So instead of discussing how to use menuselect in every “Compiling ...”
section, we will discuss it here, so when you see make menuselect you will understand
what to do once inside the menuselect configuration screen.
In Figure 3-1, we see the opening menuselect screen for the Asterisk software. Other
packages will look extremely similar, but with less options. We can navigate up and
down the list using the arrow keys. We can select one of the menu options by pressing
Enter or by using the right arrow key. The left arrow key can be used to go back.
Figure 3-2 shows a list of possible dialplan applications that can be built for use in
Asterisk. Modules to be built are marked as [*]. A module is marked as not being built
by [ ]. Modules that have XXX in front of them are missing a package dependency which
must be satisfied before it will be available to be built. In Figure 3-2, we can see that
the app_flash module cannot be built due to a missing dependency of Zaptel (i.e., the
Zaptel module has not been built and installed on the system since the last
time ./configure was run). If you have satisfied a dependency since the last time you
42 | Chapter 3: Installing Asterisk
ran ./configure, then run it again, and rerun menuselect. Your module should now be
available for building.
After you have finished making changes to menuselect, type x to save and quit. q will
also quit out of menuselect, but it will not save the changes. If you make changes and
type q, your changes may be lost!
Compiling Zaptel
Figure 3-3 shows the layers of interaction between Asterisk and the Linux kernel with
respect to hardware control. On the Asterisk side is the Zapata channel module,
chan_zap. Asterisk uses this interface to communicate with the Linux kernel, where
the drivers for the hardware are loaded.
The Zaptel interface is a kernel loadable module that presents an abstraction layer
between the hardware drivers and the Zapata module in Asterisk. It is this concept that
allows the device drivers to be modified without any changes being made to the Asterisk
Figure 3-1. Sample menuselect screen
Compiling Zaptel | 43
source itself. The device drivers are used to communicate with the hardware directly
and to pass the information between Zaptel and the hardware.
While Asterisk itself compiles on a variety of platforms, the Zaptel drivers
are Linux-specific—they are written to interface directly with the
Linux kernel. There is a project at http://www.solarisvoip.com that provides
Zaptel support for Solaris. There is also a project that is working
to provide Zapata drivers for BSD, located at http://www.voip-info.org/
tiki-index.php?page=FreeBSD+zaptel.
First we will discuss the ztdummy driver, used on systems that require a timing interface
but that do not have hardware. Then we will look at compiling and installing the drivers.
(The configuration of Zaptel drivers will be discussed in the next chapter.)
Figure 3-2. List of modules to be built
44 | Chapter 3: Installing Asterisk
Before compiling the Zaptel drivers on a system running a Linux 2.4
kernel, you should verify that /usr/src/ contains a symbolic link named
linux-2.4 pointing to your kernel source. If the symbolic link doesn’t
exist, you can create it with the following command (assuming you’ve
installed the source in /usr/src/):
# ln -s /usr/src/'uname -r' /usr/src/linux-2.4
Computers running Linux 2.6 kernel-based distributions do not usually
require the use of the symbolic link, as these distributions will search
for the kernel build directory automatically. However, if you’ve placed
the build directory in a nonstandard place (i.e., somewhere other
than /lib/modules/ <kernel version> /build/), you will require the use of
the symbolic link.
While Asterisk and the other related packages run on Linux 2.4.x kernels,
development is done first and foremost on 2.6.x kernels and
support for 2.4.x kernels is not guarenteed in the future.
The ztdummy Driver
In Asterisk, certain applications and features require a timing device in order to operate
(Asterisk won’t even compile them if no timing device is found). All Digium PCI hardware
provides a 1 kHz timing interface that satisfies this requirement. If you lack the
PCI hardware required to provide timing, the ztdummy driver can be used as a timing
device. On Linux 2.4 kernel-based distributions, ztdummy must use the clocking provided
by the UHCI USB controller.
Asterisk
chan_zap.so
/dev/zap
Zaptel
Hardware driver
(wctdm)
Hardware
Linux kernel
Figure 3-3. Layers of device interaction with Asterisk
Compiling Zaptel | 45
Many older systems (and some newer ones) use an OHCI USB controller
chip, which is incompatible with ztdummy. However, if you’re using a
2.6 kernel there is no need to worry about which USB controller chip
your system has.
The driver looks to see that the usb-uhci module is loaded and that the kernel version
is at least 2.4.5. Older kernel versions are incompatible with ztdummy.
On a 2.6 kernel-based distribution, ztdummy does not require the use of the USB controller.
(As of v2.6.0, the kernel now provides 1 kHz timing‖ with which the driver can
interface; thus, the USB controller hardware requirement is no longer necessary.)
The Zapata Telephony Drivers
Compiling the Zapata telephony drivers for use with your Digium hardware is straightforward;
however, the method employed between the 1.2 and 1.4 versions is slightly
different due to the new build environment. First we need to run ./configure in order
to determine what applications and libraries are installed on the system. This will ensure
that everything Zaptel needs is installed. The following commands will build Zaptel
and its modules:
# cd /usr/src/zaptel-version
# make clean
# ./configure
# make menuselect
# make
# make install
While running make clean is not always necessary, it’s a good idea to
run it before recompiling any of the modules, as it will remove the compiled
binary files from within the source code directory. You can also
use it to clean up after installing if you don’t like to leave the compiled
binaries floating around. Note that this removes the binaries only from
the source directory, not from the system.
In addition to the executables, make clean also removes the intermediary
files (i.e., the object files) after compilation. You don’t need them occupying
space on your hard drive.
If you’re using a system that makes use of the /etc/rc.d/init.d/ or /etc/init.d/ directories
(such as CentOS and other Red Hat-based distros), you may wish to run the make con
‖ Note that this is configurable in the kernel, so it is possible certain distributions may not have this set to 1,000
Hz; CentOS, however, does have this set at the correct frequency.
46 | Chapter 3: Installing Asterisk
fig command as well. This will install the startup scripts and configure the system,
using the chkconfig command to load the zaptel module automatically at startup:
# make config
The Debian equivalent of chkconfig is update-rc.d.
While Digium only officially supports Zaptel on Linux, several projects
to port Zaptel to other platforms should be noted:
• Solaris (http://www.solarisvoip.com)
• BSD (http://lists.digium.com/mailman/listinfo/asterisk-bsd)
Using ztcfg and zttool
Two programs installed along with Zaptel are ztcfg and zttool. The ztcfg program is
used to read the configuration in /etc/zaptel.conf to configure the hardware. The
zttool program can be used to check the status of your installed hardware. For instance,
if you are using a T1 card and there is no communication between the endpoints, you
will see a red alarm. If everything is configured correctly and communication is possible,
you should see an “OK.” The zttool application is also useful for analog cards, because
it tells you their current state (configured, off-hook, etc.). The use of these programs
will be explored further in the next chapter.
The libnewt libraries and their development packages (newt-devel on
Red Hat-based distributions) must be installed for zttool to be compiled.
The ztcfg and zttool applications, along with other useful utilities, are
located under the Utilities section of the Zaptel menuselect screen.
Compiling libpri
The libpri libraries do not make use of the autoconf build environment or the menuselect
feature as they are unnecessary; thus, the installation is simplified. libpri is used
by various makers of Time Division Multiplexing (TDM) hardware, but even if you
don’t have the hardware installed, it is safe to compile and install this library. You must
compile and install libpri before Asterisk, as it will be detected and used when Asterisk
is compiled. Here are the commands (replace version with your version of libpri):
# cd /usr/src/libpri-version
# make clean
# make
# make install
Compiling libpri | 47
Compiling Asterisk
Once you’ve compiled and installed the zaptel and libpri packages (if you need them),
you can move on to Asterisk. This section walks you through a standard installation
and introduces some of the alternative make arguments that you may find useful.
Standard Installation
Asterisk is compiled with gcc through the use of the GNU make program. To get started
compiling Asterisk, simply run the following commands (replace version with your
version of Asterisk):
# cd /usr/src/asterisk-version
# make clean
# ./configure
# make menuselect
# make install
# make samples
Be aware that compile times will vary between systems. On a current-generation processor,
you shouldn’t need to wait more than five minutes. At AstriCon (http://
www.astricon.net), someone reported successfully compiling Asterisk on a 133 MHz
Pentium, but it took approximately five hours. You do the math.
Run the make samples command to install the default configuration files. Installing these
files (instead of configuring each file manually) will allow you to get your Asterisk
system up and running much faster. Many of the default values are fine for Asterisk.
Files that require editing will be explained in future chapters.
If you already have configuration files installed in /etc/asterisk/ when you
run the make samples command, .old will be appended to the end of each
of your current configuration files, for example, extensions.conf will be
renamed extensions.conf.old. Be careful, though, because if you run make
samples more than once you will overwrite your original configuration
files!
The sample configuration files can also be found in the configs/ subdirectory
within your Asterisk sources directory.
If you’re using a system that makes use of the /etc/rc.d/init.d/ or /etc/init.d/ directories,
you may wish to run the make config command as well. This will install the startup
scripts and configure the system (through the use of the chkconfig command) to execute
Asterisk automatically at startup:
# make config
48 | Chapter 3: Installing Asterisk
Alternative make Arguments
There are several other make arguments that you can pass at compile time. While some
of these will be discussed here, the remainder are used internally within the file and
really have no bearing or use for the end user. (Of course, new functions may have been
added, so be sure to check the Makefile for other options.)
Let’s take a look at some useful make arguments.
make clean
The make clean command is used to remove the compiled binaries from within the
source directory. This command should be run before you attempt to recompile or, if
space is an issue, if you would like to clean up the files.
make distclean
The make distclean command is used to remove the compiled binaries and to clean
the source directory back to its original state after being extracted from the compressed
archive.
make update
The make update command is used to update the existing code from the Digium SVN
server. If you downloaded the source code from the FTP server, you will receive a notice
stating so.
make webvmail
The Asterisk Web Voicemail script is used to give a graphical interface to your voicemail
account, allowing you to manage and interact with your voicemail remotely from a web
browser.
When you run the make webvmail command, the Asterisk Web Voicemail script will be
placed into the cgi-bin/ directory of your HTTP daemon. If you have specific policies
with respect to security, be aware that it uses a setuid root Perl script. This command
will install only on a CentOS or Fedora box, as other distributions may have different
paths to their cgi-bin/ directories. (This, of course, can be changed by editing the
HTTP_CFGDIR variable in the Makefile at line 133 at the time of this writing.)
make progdocs
The make progdocs command will create documentation using the doxygen software
from comments placed within the source code by the developers. You must have the
appropriate doxygen software installed on your system in order for this to work. Note
that doxygen assumes that the source code is well documented, which, sadly, is not
always the case, although much work was published since the first edition of this book!
The information contained within the doxygen system will be useful only to developers.
Compiling Asterisk | 49
make config
The make config command will install Red Hat-style initialization scripts, if
the /etc/rc.d/init.d or /etc/init.d directories are found to exist. If they do exist, the scripts
are installed with file permissions equal to 755. If the script detects
that /etc/rc.d/init.d/ exists, the chkconfig --add asterisk command will also be run to
cause Asterisk to be started automatically at boot time. This is not the case, however,
with distributions that only use the /etc/init.d/ directory. Running make config will not
do anything to an already running Asterisk process, or start one if it’s not running.
This script currently is really only useful on a Red Hat-based system, although initialization
scripts are available for other distributions (such as Gentoo, Mandrake, and
Slackware) in the ./contrib./init.d/ directory of your Asterisk source directory.
Using Precompiled Binaries
While the documented process of installing Asterisk expects you to compile the source
code yourself, there are Linux distributions (such as Debian) that include precompiled
Asterisk binaries. Failing that, you may be able to install Asterisk with the package
managers that those distributions of Linux provide (such as apt-get for Debian and
portage for Gentoo).# However, you may also find that many of these prebuilt binaries
are quite out of date and do not follow the same furious development cycle as Asterisk.
Finally, there do exist basic, precompiled Asterisk binaries that can be downloaded and
installed in whatever Linux distribution you have chosen. However, the use of precompiled
binaries doesn’t really save much time, and we have found that compiling
Asterisk with each install is not a very cumbersome task. We believe that the best way
to install Asterisk is to compile from the source code, so we won’t discuss prebuilt
binaries very much in this book―and besides, don’t you want to be l33t?* In the next
chapter, we’ll look at how to initially configure Asterisk and several kinds of channels.
Installing Additional Prompts
Additional prompts are installed via the menuselect application in your Asterisk source
directory. There are three sets of audio packages: Core Sound, Extra Sound, and Music
On Hold File. Each set of packages is broken down into different formats (and the Core
Sound packages are available in multiple languages). Using the menuselect application,
# Gentoo doesn’t actually use a precompiled binary, but rather pulls the source from a repository, and builds
and installs the software using its own package management system. But the version you get is still dependant
upon the maintainers packaging it for you, when you could simply build it yourself!
* l33t is a funny way of saying “elite,” known as leetspeak (computer slang). Even more funny is a well-written,
serious article by Microsoft about leetspeak at http://www.microsoft.com/athome/security/children/
leetspeak.mspx.
50 | Chapter 3: Installing Asterisk
you can select combinations of audio packages for use in your environment. Some of
the formats available include:
• WAV
• μlaw
• alaw
• GSM
• G.729
• G.722 (wideband, 16-bit)
As of this writing, the Core Sound packages are available in the following languages:
• English
• Spanish
• French
Selecting any sounds in menuselect will cause the system to download
the files from the Digium FTP server upon install. The size of these files
ranges anywhere from 2 MB to 27 MB, so be aware of this when installing
offline, or on slow and expensive links.
Other Useful Add-ons
The asterisk-addons package contains code to allow the storage of Call Detail Records
(CDRs) to a MySQL database. There is also code that allows Asterisk to natively play
MP3s (which we don’t recommend unless you have a powerful system with very few
phones on it). Some folks may also be interested in the interpreter that allows you to
load Perl code into memory for the life of an Asterisk process (which can be very helpful
if you have a large number of AGI calls to the Perl interpreter). Programs are placed
into asterisk-addons when there are licensing issues preventing them from being implemented
directly into the Asterisk source code, or when they are not considred mature
enough to be integrated with Asterisk.
The http://ftp.digium.com/pub/asterisk/g729/ directory contains the code and registration
program for the proprietary G.729A codec . If you install the g729 sounds packages,
Asterisk will be able to communicate with devices that natively support the G.729A
codec, but will not be able to transcode between other codecs and G.729A until a license
is obtained to use it.
Common Compiling Issues
There are many common compiling issues that users often run into. Here are some of
the more common problems, and how to resolve them.
Common Compiling Issues | 51
Asterisk
First, let’s take a look at some of the errors you may encounter when running the
configure script.
configure: error: no acceptable C compiler found in $PATH
If you receive the following error while attempting to run the configure script, you must
install the gcc compiler and its dependencies:
configure: error: no acceptable C compiler found in $PATH
The following packages are required for gcc:
• gcc
• cpp
• glibc-headers
• glibc-devel
• glibc-kernheaders
These can be installed manually, by copying the files off of your distribution disks, or
through the yum package manager, with the command yum install gcc.
configure: error: C++ preprocessor "/lib/cpp" fails sanity check
The following error will be displayed if no C++ preprocessor is found installed on the
system. You must install the gcc-c++ package and its dependencies:
configure: error: C++ preprocessor "/lib/cpp" fails sanity check
The following packages are required for the gcc-c++ preprocessor; installed by running
yum install gcc-c++:
• gcc-c++
• libstdc++-devel
configure: error: *** termcap support not found
The following error may be encountered during initialization of the configure script if
the libtermcap-devel package is not installed:
configure: error: *** termcap support not found
The following file is required in order to compile Asterisk; it can be installed with the
yum install libtermcap-devel command:
• libtermcap-devel
52 | Chapter 3: Installing Asterisk
Zaptel
You may also run into errors when compiling Zaptel. Here are some of the most commonly
occurring problems, and what to do about them. If your error is not listed below,
see the previous section as your error may be covered there.
make: cc: Command not found
You will receive the following error if you attempt to build Zaptel without the gcc
compiler installed:
make: cc: Command not found
make: *** [gendigits.o] Error 127
Be sure to install gcc and its dependencies. For more information, see “configure: error:
no acceptable C compiler found in $PATH in the previous section.
FATAL: Module wctdm/fxs/fxo not found
The TDM400P cards require the PCI bus to be version 2.2. If you attempt to load the
Zapata telephony drivers with an older version, you may get the following errors:
• When attempting to load the wctdm driver, you may see this error:
FATAL: Module wctdm not found
• When attempting to load the wctdm or wcfxo driver, you may see an error such as
this:
ZT_CHANCONFIG failed on channel 1: No such device or address (6)
FATAL: Module wctdm not found
The only way to resolve these errors is to use a newer motherboard that supports PCI
version 2.2:
You may also encounter these errors if the power has not been attached
to the Molex connector found on the TDM400P card.
Unresolved symbol link when loading ztdummy
The ztdummy driver requires that a UHCI USB controller be available on Linux 2.4
kernels (the USB controller is not a requirement on Linux 2.6 kernels, because they are
capable of generating the 1 kHz timing reference). There exists a secondary kind of
controller, known as OHCI, which is not compatible with the ztdummy driver. If the
UHCI USB controller is not accessible on Linux 2.4 kernels, the following error will
occur:
/lib/modules/2.4.22/misc/ztdummy.o: /lib/modules/2.4.22/misc/ztdummy.o: unresolved
symbol unlink_td
/lib/modules/2.4.22/misc/ztdummy.o: /lib/modules/2.4.22/misc/ztdummy.o: unresolved
Common Compiling Issues | 53
symbol alloc_td
/lib/modules/2.4.22/misc/ztdummy.o: /lib/modules/2.4.22/misc/ztdummy.o: unresolved
symbol delete_desc
/lib/modules/2.4.22/misc/ztdummy.o: /lib/modules/2.4.22/misc/ztdummy.o: unresolved
symbol uhci_devices
/lib/modules/2.4.22/misc/ztdummy.o: /lib/modules/2.4.22/misc/ztdummy.o: unresolved
symbol uhci_interrupt
/lib/modules/2.4.22/misc/ztdummy.o: /lib/modules/2.4.22/misc/ztdummy.o: unresolved
symbol fill_td
/lib/modules/2.4.22/misc/ztdummy.o: /lib/modules/2.4.22/misc/ztdummy.o: unresolved
symbol insert_td_horizontal
/lib/modules/2.4.22/misc/ztdummy.o: insmod /lib/modules/2.4.22/misc/ztdummy.o failed
/lib/modules/2.4.22/misc/ztdummy.o: insmod ztdummy failed
You can verify that you have the correct style of USB controller and its associated drivers
with the lsmod command:
# lsmod
Module Size Used by
usb_uhci 26412 0
usbcore 79040 1 [hid usb-uhci]
As you can see in the example above, you are looking to make sure that the usbcore
and usb_uhci modules are loaded. If these modules are not loaded, be sure that USB
has been activated within your BIOS and that the modules exist.
If the USB drivers are not loaded, you can still check which type of USB controller you
have with the dmesg command:
# dmesg | grep -i usb
To verify that you indeed have a UHCI USB controller, look for the following lines:
uhci_hcd 0000:00:04.2: new USB bus registered, assigned bus number 1
hub 1-0:1.0: USB hub found
uhci_hcd 0000:00:04.3: new USB bus registered, assigned bus number 2
hub 2-0:1.0: USB hub found
Depmod errors during compilation
If you experience depmod errors during compilation, you more than likely don’t have a
symbolic link to your Linux kernel sources. If you don’t have your Linux kernel sources
installed, retrieve the sources for your installed kernel, install them, and create a symbolic
link against /usr/src/linux-2.4. The following is an example of a depmod error:
depmod: *** Unresolved symbols in /lib/modules/2.4.22/kernel/drivers/block/
loop.o
Loading Asterisk and Zaptel Quickly
If you run make config in the Asterisk or Zaptel source directories, then the initialization
scripts used to control Asterisk or Zaptel will be copied to /etc/rc.d/init.d/. The scripts
can be used to easily load and unload Asterisk and Zaptel. They will also run the
54 | Chapter 3: Installing Asterisk
chkconfig command for you so Asterisk and Zaptel will be started automatically upon
system boot. The following shows their usage:
# service zaptel start
# service asterisk start
Each initialization script has several options that can be utilized to control the PBX or
the drivers. Tables 3-2 and 3-3 show the commands run by the script as if you had typed
them into the command-line interface (CLI) yourself:
Table 3-2. Asterisk initialization script options
service asterisk <option> Manual equivalent
start asterisk
stop killproc asterisk
restart stop; start
reload asterisk -rx "reload"
status ps aux | grep [a]sterisk
Table 3-3. Zaptel initialization script options
service zaptel <option> Manual equivalent
start modprobe zaptel; modprobe <module>; /sbin/ztcfg
stop rmmod ztdummy; rmmod zaptel
restart stop; start
reload /sbin/ztcfg
Loading Zaptel Modules Without Scripts
In this section, we’ll take a quick look at how to load the zaptel and ztdummy modules
without the CentOS initialization script. The zaptel module does not require any configuration
if it’s being used only for the ztdummy module. If you plan on loading the
ztdummy module as your timing source (and thus, you will not be running any PCI
hardware in your system), now is a good time to load both drivers.
Systems Running udevd
In the early days of Linux, the system’s /dev/ directory was populated with a list of
devices with which the system could potentially interact. At the time, nearly 18,000
devices were listed. That all changed when devfs was released, allowing dynamic creation
of devices that are active within the system. Some of the recently released
distributions have incorporated the udev daemon into their systems to dynamically
populate /dev/ with device nodes.
Loading Zaptel Modules Without Scripts | 55
To allow Zaptel and other device drivers to access the PCI hardware installed in your
system, you must add some rules. Using your favorite text editor, open up your
udevd rules file. On CentOS, for example, this file is located
at /etc/udev/rules.d/50-udev.rules. Add the following lines to the end of your rules file:
# Section for zaptel
device
KERNEL="zapctl", NAME="zap/ctl"
KERNEL="zaptimer", NAME="zap/timer"
KERNEL="zapchannel", NAME="zap/channel"
KERNEL="zappseudo", NAME="zap/pseudo"
KERNEL="zap[0-9]*", NAME="zap/%n"
Save the file and reboot your system for the settings to take effect.
You may not have to actually edit anything in your system, as the Zaptel
installation script will try to install the rules for you; however, we have
left this here as a reference for those systems that are not automatically
configured.
Loading Zaptel
The zaptel module must be loaded before any of the other modules are loaded and used.
Note that if you will be using the zaptel module with PCI hardware, you must configure
/etc/zaptel.conf before you load it. (We will discuss how to configure zaptel.conf for
use with hardware in Chapter 4.) If you are using zaptel only to access ztdummy, you
can load it with the modprobe command, as follows:
# modprobe zaptel
If all goes well, you shouldn’t see any output. To verify that the zaptel module loaded
successfully, use the lsmod command. You should be returned a line showing the
zaptel module and the amount of memory it is using, as in the following:
# lsmod | grep zaptel
zaptel 201988 0
Loading ztdummy
The ztdummy module is an interface to a device that provides timing, which in turn
allows Asterisk to provide timing to various applications and functions that require it.
Use the modprobe command to load the ztdummy module after zaptel has been loaded:
# modprobe ztdummy
If ztdummy loads successfully, no output will be displayed. To verify that ztdummy is
loaded and is being used by zaptel, use the lsmod command. The following output is
from a computer running the 2.6 kernel:
56 | Chapter 3: Installing Asterisk
# lsmod | grep ztdummy
Module Size Used by
ztdummy 3796 0
zaptel 201988 1 ztdummy
If you happen to be running a 2.4 kernel-based computer, your output from lsmod will
show that ztdummy is using the usb-uhci module:
# lsmod | grep ztdummy
Module Size Used by
ztdummy 3796 0
zaptel 201988 0 ztdummy
usb-uhci 24524 0 ztdummy
Loading libpri Without Script
The libpri libraries do not need to be loaded like modules. Asterisk looks for libpri at
compile time and configures itself to use the libraries if they are found.
Starting Asterisk Without Scripts
Asterisk can be loaded in a variety of ways. The easiest way is to start Asterisk by running
the binary file directly from the Linux command-line interface. If you are running a
system that uses the init.d scripts, you can easily start and restart Asterisk that way as
well. However, the preferred way of starting Asterisk is via the safe_asterisk script.
Console Commands
The Asterisk binary is, by default, located at /usr/sbin/asterisk. If you
run /usr/sbin/asterisk, it will be loaded as a daemon. There are also a few switches you
should be aware of that allow you to (re)connect to the Asterisk CLI, set the verbosity
of CLI output, and allow core dumps if Asterisk crashes (for debugging with gdb). To
explore the full range of options, run Asterisk with the -h switch:
# /usr/sbin/asterisk -h
Here is a list of the most commonly used options:
-c
Console. This will start Asterisk as a user process (not as a server), and will connect
you to the Asterisk CLI. This option is good when you are debugging your startup
parameters, but should not be used for a normal system (if Asterisk is already
running, this option will not work and will issue a complaint).
-v
Verbosity. This is used to set the amount of output for CLI debugging. The more
“v”s, the more verbose.
Loading libpri Without Script | 57
-g
Core dump. If Asterisk were to crash unexpectedly, this would cause a core file to
be created for later tracing with gdb. You generally do not use this in production,
unless you are writing code for Asterisk and want to debug any resulting crashes.
-r
Remote. This is used to reconnect remotely to an already running Asterisk process.
(The process is remote from the standpoint of the console connecting to it but is
actually a local process on the machine. This has nothing to do with connecting to
a remote process over a network using a protocol such as IP, as this is not supported.)
This is the most common option and it is what you would use to connect to
Asterisk on a system where it is running as a daemon/service that was started by
init at boot time.
-x "<CLI command>"
Execute. Using this command in combination with -r allows you to execute a CLI
command without having to connect to the CLI and type it manually. An example
would be to send a restart, which you would do by typing asterisk -rx
"reload" from the command line.
Let’s look at some examples. If you want to start Asterisk as a user program (because
you are tweaking your config and will be starting and stopping it several times), and
you want a verbosity level of 3, use the following command:
# /usr/sbin/asterisk -cvvv
If the Asterisk process is already running (for example, if you have installed Asterisk as
part of the init process of the system), use the reconnect switch, like so:
# /usr/sbin/asterisk -vvvr
If you want Asterisk to dump a core file after a crash, you can use the -g switch when
starting Asterisk:
# /usr/sbin/asterisk -g
To execute a command without connecting to the CLI and typing it (perhaps for use
within a script), you can use the -x switch in combination with the -r switch:
# /usr/sbin/asterisk -rx "restart now"
# /usr/sbin/asterisk -rx "database show"
# /usr/sbin/asterisk -rx "sip show peers"
If you are experiencing crashes and would like to output to a debug file, use the following
command:
# /usr/sbin/asterisk -vvvvc | tee /tmp/debug.log
Note that you do not have to use the v switch if you do not want the system to provide
detailed output of what is going on. On a busy system, you may not want to get any
output, as it can interfere with whatever you are doing on the console.
58 | Chapter 3: Installing Asterisk
Directories Used by Asterisk
Asterisk uses several directories on a Linux system to manage the various aspects of the
system, such as voicemail recordings, voice prompts, and configuration files. This section
discusses the necessary directories, all of which are created during installation and
configured in the asterisk.conf file.
/etc/asterisk/
The /etc/asterisk/ directory contains the Asterisk configuration files. One file, however
—zaptel.conf—is located in the /etc/ directory. The Zaptel hardware was originally
designed by Jim Dixon of the Zapata Telephony Group as a way of bringing reasonable
and affordable computer telephony equipment to the world. Asterisk makes use of this
hardware, but any other software can also make use of the Zaptel hardware and drivers.
Consequently, the zaptel.conf configuration file is not directly located in
the /etc/asterisk/ directory.
/usr/lib/asterisk/modules/
The /usr/lib/asterisk/modules/ directory contains all of the Asterisk loadable modules.
Within this directory are the various applications, codecs, formats, and channels used
by Asterisk. By default, Asterisk loads all of these modules at startup. You can disable
any modules you are not using in the modules.conf file, but be aware that certain modules
are required by Asterisk or are dependencies of other modules. Attempting to load
Asterisk without these modules will cause an error at startup.
/var/lib/asterisk
The /var/lib/asterisk/ directory contains the astdb file and a number of subdirectories.
The astdb file contains the local Asterisk database information, which is somewhat like
the Microsoft Windows Registry. The Asterisk database is a simple implementation
based on v1 of the Berkeley database. The db.c file in the Asterisk source states that this
version was chosen for the following reason: “DB3 implementation is released under
an alternative license incompatible with the GPL. Thus, in order to keep Asterisk licensing
simplistic, it was decided to use version 1 as it is released under the BSD
license.”
The subdirectories within /var/lib/asterisk/ include:
agi-bin/
The agi-bin/ directory contains your custom scripts, which can interface with Asterisk
via the various built-in AGI applications. For more information about AGI,
see Chapter 8.
Directories Used by Asterisk | 59
firmware/
The firmware/ directory contains firmware for various Asterisk-compatible devices.
It currently contains only the iax/ subdirectory, which holds the binary
firmware image for Digium’s IAXy.
images/
Applications that communicate with channels supporting graphical images look
in the images/ directory. Most channels do not support the transmission of images,
so this directory is rarely used. However, if more devices that support and make
use of graphical images are released, this directory will become more relevant.
keys/
Asterisk can use a public/private key system to authenticate peers connecting to
your box via an RSA digital signature. If you place a peer’s public key in your
keys/ directory, that peer can be authenticated by channels supporting this method
(such as the IAX2 channels). The private key is never distributed to the public. The
reverse is also true: you can distribute your public key to your peers, allowing you
to be authenticated with the use of your private key. Both the public and private
keys—ending in the .pub and .key file extensions, respectively—are stored in the
keys/ directory.
mohmp3/
When you configure Asterisk for Music on Hold, applications utilizing this feature
look for their MP3 files in the mohmp3/ directory. Asterisk is a bit picky about how
the MP3 files are formatted, so you should use constant bitrate (CBR) encoding
and strip the ID3 tags from your files.
sounds/
All of the available voice prompts for Asterisk reside in the sounds/ directory. The
contents of the basic prompts included with Asterisk are in the sounds.txt file located
in your Asterisk source code directory. Contents of the additional prompts
are located in the sounds-extra.txt file in the directory to which you extracted the
asterisk-sounds package earlier in this chapter.
/var/spool/asterisk/
The Asterisk spool directory contains several subdirectories, including
dictate/, meetme/, monitor/, outgoing/, system/, tmp/, and voicemail/ (see Figure 3-4).
Asterisk monitors the outgoing directory for text files containing call request information.
These files allow you to generate a call simply by moving the correctly structured
file into the outgoing/ directory.
Call files being placed into the outgoing/ directory can contain useful information, such
as the Context, Extension, and Priority where the answered call should start, or simply
the application and its arguments. You can also set variables and specify an account
code for Call Detail Records. More information about the use of call files is presented
in Chapter 9.
60 | Chapter 3: Installing Asterisk
The dictate/ directory is the default location where the Dictate() application looks for
files.
The meetme/ directory is the location where MeetMe() conference recordings are saved.
Recordings from either one-touch recording (the w and W flags to the Dial() application),
the MixMonitor(), or Monitor() applications are stored in the monitor/ directory.
system/ is used by the System() application for temporary storage of data.
The tmp/ directory is used, funny enough, to hold temporary information. Certain
applications may require a place to write files to before copying the complete files to
their final destinations. This prevents two processes from trying to write to and read
from a file at the same time.
All voicemail and user greetings are contained within the voicemail/ directory. Extensions
configured in voicemail.conf that have been logged in to at least once are created
as subdirectories of voicemail/.
/var/run/
The /var/run/ directory contains the process ID (PID) information for all active processes
on the system, including Asterisk (as specified in the asterisk.conf file). Note
that /var/run/ is OS-dependent and may differ.
var
spool
asterisk
outgoing
qcall
tmp
voicemail
Figure 3-4. /var/spool/asterisk/ directory structure
Directories Used by Asterisk | 61
/var/log/asterisk/
The /var/log/asterisk/ directory is where Asterisk logs information. You can control the
type of information being logged to the various files by editing the logger.conf file located
in the /etc/asterisk/ directory. Basic configuration of the logger.conf file is covered
in Appendix D.
/var/log/asterisk/cdr-csv
The /var/log/asterisk/cdr-csv directory is used to store the CDRs in comma-separated
value (CSV) format. By default information is stored in the Master.csv file, but individual
accounts can store their own CDRs in separate files with the use of the
accountcode option (see Appendix A for more information).
AsteriskNOW™
In the following sections we will provide a gentle introduction to the AsteriskNOW
software, which gives you a complete PBX system with graphical configuration screen
all built into one!
What Is AsteriskNOW?
AsteriskNOW is an open source software appliance, a customized Linux distribution
that includes Asterisk, the Asterisk GUI, and all other software needed for an Asterisk
system. The Asterisk GUI gives you the ability to easily configure your Asterisk system
without being a technical expert.
Note: The complete software appliance distribution is provided under the GPL (http://
www.gnu.org/copyleft/gpl.html) and may legally be used for any purpose, commercial
or otherwise.
Before You Begin
AsteriskNOW installation is easy, because the appliance includes only those components
necessary to run, debug, and build Asterisk. You no longer have to worry about
kernel versions and package dependencies. AsteriskNOW is a custom Linux distribution
for Asterisk based on rPath Linux.
What You Will Need
• A system on which you can install AsteriskNOW
• A CD writer and associated software
• Connection to the Internet
62 | Chapter 3: Installing Asterisk
• Firefox browser
The Asterisk GUI currently requires the Firefox browser (available at
http://www.mozilla.com/en-US/ for optimum performance. Wider
browser support will be available with future versions.
Installation
You should observe all normal precautions when preparing and installing a new distribution.
Any existing operating systems on your hard drive will be removed by the
Express Installation. If you are not sure that you are ready to alter your system, try one
of the alternate installations (discussed in “Alternate Installations”) to give AsteriskNOW
a try. For more help on Asterisk and rPath see the “For More Information”
section at the end of the chapter.
Quick installation
The essential installation of AsteriskNOW is really quite simple and gives you the ability
to get up and running in a short amount of time. Use this quick installation procedure
if you are comfortable with accepting the defaults. Any help you may need is provided
with the installation screens. If you would like more information on the installation
procedure, refer to the “Extended procedure” section below:
1. Download the AsteriskNOW ISO file (http://www.asterisknow.org/downloads) and
create a CD image from the file. This step is required before installation can begin.
The process for creating a CD image will vary depending upon the CD authoring
software you are using.
2. Insert your newly created AsteriskNOW CD into the CD-ROM drive of the PC.
3. Boot from the CD by restarting the PC. A basic AsteriskNOW boot menu with
several options will be provided:
• To install or upgrade in graphical mode, press Enter.
• To install or upgrade in Linux text mode, type linux text and then press Enter.
The recommended, and default, installation mode is graphical. If you do not make
an entry, the installation will continue in graphical mode.
4. From here, follow the self-explanatory, onscreen prompts to guide you through
the installation process.
5. When installation is complete, the system will prompt you to reboot. After rebooting,
a URL to access the Asterisk GUI will be displayed.
6. You are now ready to configure and run AsteriskNOW.
AsteriskNOW™ | 63
Extended procedure
1. Download the AsteriskNOW ISO file (http://www.asterisknow.org/downloads) and
create a CD image from the file. This step is required before installation can begin.
The process for creating a CD image will vary depending upon the CD authoring
software you are using.
2. Insert your newly created AsteriskNOW CD into the CD-ROM drive.
3. Boot from the CD by restarting the PC. A basic AsteriskNOW boot menu with
several options will be provided:
• To install or upgrade in graphical mode, press Enter.
• To install or upgrade in Linux text mode, type linux text and then press Enter.
The recommended, and default, installation mode is graphical. If you do not make
an entry, the installation will continue in graphical mode.
After a bit of processing, the initial installation screen is displayed. The initial screen
is similar to the following illustration:
4. From the initial installation screen you can read the release notes or the Help information.
When you are ready, click Next to continue the installation.
The next installation screen lets you choose the type of installation. The two modes
of installation available are:
Express Installation
The Express Installation installs all of the software needed to install Asterisk.
Debugging and development tools are installed with this installation type.
Expert
Select this installation type if you want to have complete control over all installation
options. Among the options you can control are software package
selection, partitioning, and language selection.
The default installation type is Express Installation. This installation type assumes
an English language reader and that you aren’t concerned with the finer points.
Choose Expert if you don’t read English, and/or want more control over the installation
details. For the purposes of this procedure, Express Installation is
discussed.
5. Choose your installation type and then click Next.
The Automatic Partitioning screen is displayed. The Automatic Partitioning screen
gives you several options to choose from before the software partitions your drive.
This gives you the opportunity to choose which data (if any) is removed from your
system, and how the drive is partitioned. The following options are available:
Remove All Linux Partitions
This option will only remove any Linux partitions created from a previous
Linux installation.
64 | Chapter 3: Installing Asterisk
Remove All Partitions
Select this option if you want to remove all partitions on your system, including
those created by other operating systems (such as Windows).
Keep All Partitions
You should choose this option if you want to retain all of your current data
and partitions. You will need enough hard drive space for your Asterisk implementation.
Twenty GB is a realistic minimum, but the minimum space is
dependent on the needs of the system you want to create.
In most cases, you will want to choose Remove All Partitions. A hard drive dedicated
to your Asterisk implementation is the best way to ensure maximum performance.
Select the Review checkbox on the Automatic Partitioning screen if you
want to review or modify your partition selections.
6. A list of the hard drives available for use is listed on the Automatic Partitioning
screen. Select the checkbox next to the hard drive(s) you want to use for your
system. Click Next to continue with the installation.
• If you selected Remove All Partitions or Remove All Linux Partitions, a warning
dialog will be displayed that asks if you want to proceed. Click Yes to proceed,
or No to change your partition selection.
• If you selected Review on the Automatic Partitioning screen, a screen will be
displayed with the partitions created. You can modify your partitions on this
screen. To proceed, click Next.
7. The Network Configuration screen is displayed.
• You can configure the network devices associated with your system on the Network
Configuration screen. Any network devices attached to your system are
automatically detected by the installation program and displayed in the Network
Devices list. You can either accept the device(s) automatically selected by
the installation program, or you can edit them by selecting Edit.
• Set the Hostname by either selecting Automatically via DHCP, or by selecting
Manually and enter the hostname for your system. Once you have specified the
hostname, click Next to proceed.
8. The Time Zone Selection screen is displayed.
• The Time Zone Selection screen offers several ways for you to select the time
zone appropriate for your installation. You can either use the world map, which
displays major cities, select from a list of locations and time zones, or select the
System Clock Uses UTC to use the system time. Once you have selected a time
zone, click Next.
9. The Administrator Password screen is displayed.
• You must set a password for the AsteriskNOW administrator account, “admin”.
This password will be used to log on to the system, as well as the Asterisk GUI.
Set and confirm an administrator password, and then click Next to proceed.
AsteriskNOW™ | 65
• The About to Install screen is displayed, giving you an opportunity to delay or
abort the installation process. If you are ready to continue with the installation,
click Next.
10. The Installing Packages screen is displayed.
• While AsteriskNOW is being installed, the Installing Packages screen will be
displayed. The installation will continue for a few minutes.
• Once the installation is complete, the system will prompt you to reboot. Remove
the installation disk you created, and click Reboot. After rebooting, a URL to
access the Asterisk GUI will be displayed.
Accessing the GUI
Once you have completed your installation and rebooted your machine, you will be
able to access the Asterisk GUI. The URL used to access the Asterisk GUI is the IP
address or hostname displayed after rebooting your machine. Enter this IP address in
your browser URL. You will be able to refine your AsteriskNOW installation by accessing
the Asterisk GUI.
Alternate Installations
You can also try out AsteriskNOW using the available VMware Player image (http://
www.vmware.com/download/player/), Xen universal guest domain image (http://wi
ki.rpath.com/wiki/Xen_Solutions_Using_rPath_Technologies) or the LiveCD (just burn
and boot). All alternate installations can be downloaded from the AsteriskNOW
download (http://www.asterisknow.org/downloads) page.
Note: When using the LiveCD, the default username is “admin” with “password” as
the password.
For More Information
An AsteriskNOW Users’ Guide is currently under development by the Asterisk community
on the Asterisk Forums. For additional information on AsteriskNOW, including
step-by-step installation screenshots and configuration screenshots showing the
setup wizard, please refer to http://www.asterisknow.org, and visit the Asterisk Forums
at http://forums.digium.com. For more information and help with rPath Linux, please
see rPath’s wiki, http://wiki.rpath.com.
66 | Chapter 3: Installing Asterisk
Conclusion
In this chapter, we have reviewed the procedures for obtaining, compiling, and installing
Asterisk and the associated packages. In the following chapter, we will touch on
the initial configuration of your system with regard to various communications channels,
such as analog devices attached to FXS and FXO ports, SIP channels, and IAX2
endpoints.
Conclusion | 67

CHAPTER 4
Initial Configuration of Asterisk
I don’t always know what I’m talking about,
but I know I’m right.
—Muhammad Ali
Completing all the steps in Chapter 3 should have left you with a working Asterisk
system. If it did not, please take the time to go back and review the steps, consult the
wiki, engage the community, and get your system running.
Unfortunately, we cannot yet make any calls, because we have not yet created any
channels. To get this plane to fly, we’re going to need some runways. While there are
dozens of different channel types, and dozens of different ways to configure each type
of channel, we just want to get some calls happening, so let’s try and keep things simple.
We have decided to guide you through the configuration of four channels: a Foreign
eXchange Office (FXO) channel, a Foreign eXchange Station (FXS) channel, a Session
Initiation Protocol (SIP) channel, and an Inter-Asterisk eXchange (IAX) channel.* We
selected these channel types because they are far and away the most popular channel
types in use in small Asterisk systems, and one of the goals of this book is to keep things
as simple as is reasonable. If we cover the basics of these channels, we will not have
done an exhaustive survey of all channel types or topologies, but we will have created
a base platform on which to develop your telecommunications system. Further scenarios
and channel configuration details can be found in Appendix D.
Our first effort will be to explore the basic configuration of analog interfaces such as
FXS and FXO ports with the use of a Digium TDM11B (which is an analog card with
one FXS port and one FXO port).†
* Officially, the current version is IAX2, but since all support for IAX1 was dropped many years ago, whether
you say “IAX” or “IAX2,” you are talking about the same version.
† This configuration used to be known as the Digium Dev-lite kit. For more information on FXS versus FXO,
keep reading. Put simply, this card will give us one port to connect to a traditional analog line from the phone
company (FXO), and one port to connect to an analog telephone (FXS), which is any type of phone that will
work with a traditional home telephone circuit.
69
Next, we’ll tackle a few Voice over Internet Protocol (VoIP) interfaces: a local SIP and
IAX2 channel connected to a softphone or hardphone, along with connecting two Asterisk
boxes via these two popular protocols.
For SIP, we are going to cover Linksys, Polycom, Aastra, Grandstream, and Cisco sets.
If we do not cover your phone model, we apologize, but what is important to realize is
that while most of these devices have many different parameters that you can define,
generally only a few parameters need to be defined in order to get the device to work.
That will be our goal, because we figure it’s a lot less frustrating to tweak a functioning
device than to get it perfectly set up on the first try. We won’t discuss all the features
you may want your channel to have (such as caller ID or advanced codec and security
settings), but you will be able to make and receive calls with your phone, which should
put a smile on your face—a good state to be in as we dig deeper into things.
Once you’ve worked through this chapter, you will have a basic system consisting of
many useful interfaces, which will provide the foundation we need to explore the
extensions.conf file (discussed in detail in Chapter 5), where the dialplan is stored
(technically, it contains the instructions Asterisk needs to build the dialplan). If you do
not have access to the analog hardware, some of the examples will not be available to
you, but you will still have configured a system suitable for a pure-VoIP environment.
What Do I Really Need?
The asterisk character (*) is used as a wildcard in many different applications. It is a
good name for this PBX for many reasons, one of which is the enormous number of
interface types to which Asterisk can connect. These include:
• Analog interfaces, such as your telephone line and analog telephones
• Digital circuits, such as T1 and E1 lines
• VoIP protocols such as SIP and IAX‡
Asterisk doesn’t need any specialized hardware—not even a sound card—even though
it is common to expect a telephone system to physically connect to a voice network.
There are many types of channel cards that allow you to connect your Asterisk to things
like analog phones or PSTN circuits, but they are not essential to the functioning of
Asterisk. On the user (or station) side of the system, you can choose from all kinds of
softphones that are available for Windows, Linux, and other operating systems—or
use almost any physical IP phone. That handles the telephone side of the system. On
the carrier side, if you don’t connect directly to a circuit from your central office, you
can still route your calls over the Internet using a VoIP service provider.
‡ …and H.323 and SCCP and MGCP and UNISTIM
70 | Chapter 4: Initial Configuration of Asterisk
Working with Interface Configuration Files
In this chapter, we’re going to build an Asterisk configuration on the platform we have
just installed. For the first few sections on FXO and FXS channels, we’ll assume that
you have a Digium TDM11B kit (which comes with one FXO and one FXS interface).
This will allow you to connect to an analog circuit (FXO) and to an analog telephone
(FXS). Note that this hardware interface isn’t necessary; if you want to build an IP-only
configuration, you can skip to the section on configuring SIP.
The configuration we do in this chapter won’t be particularly useful on its own, but it
will be a kernel to build on. We’re going to touch on the following files:
zaptel.conf
Here, we’ll do low-level configuration for the hardware interface. We’ll set up one
FXO channel and one FXS channel. This configures the driver for the Linux kernel.
zapata.conf
In this file, we’ll configure Asterisk’s interface to the hardware. This file contains
a slightly higher-level configuration of the hardware in the Asterisk user-level
process.
extensions.conf
The dialplans we create will be extremely primitive, but they will prove that the
system is working.
sip.conf
This is where we’ll configure the SIP protocol.
iax.conf
This is where we’ll configure incoming and outgoing IAX channels.
In the following sections, you will be editing several configuration files. You’ll have to
reload these files for your changes to take effect. After you edit the zaptel.conf file, you
will need to reload the configuration for the hardware with /sbin/ztcfg -vv (you may
omit the -vv if you don’t need verbose output). Changes made in zapata.conf will require
a module reload from the Asterisk console; however, changing signaling methods requires
a restart. You will need to perform an iax2 reload and a sip reload after editing
the iax.conf and sip.conf files, respectively.
In order to test the new devices we have defined, we must have a dialplan through which
we can make connections. Even though we have not discussed the Asterisk dialplan
(that’s coming up in the next chapter), we want you to create a basic extensions.conf
file so that we can test our work in this chapter.
Make a backup copy of the sample extensions.conf (try the bash command mv exten
sions.conf extensions.conf.sample), and then create a blank extensions.conf file (using
the bash command touch extensions.conf), and insert the following lines:
Working with Interface Configuration Files | 71
[globals]
[general]
autofallthrough=yes
[default]
[incoming_calls]
[internal]
[phones]
include => internal
In the [general] section, we have set autofallthrough=yes, which tells
Asterisk to continue when an extension runs out of things to do. If you
set this to no, then Asterisk will sit and wait for input after all priorities
have executed. This is most prevalent if the Background() application is
the last application executed in an extension. If set to yes (which is now
the default in 1.4), Asterisk will drop the call after Background() finishes
executing (at the end of the prompt(s) supplied to it). In order to force
Asterisk to wait for input after the Background() application finishes
playing the voice prompts supplied to it, we use the WaitExten()
application.
Do not be afraid if what we’ve just written doesn’t make a whole lot of
sense, as we haven’t explored the dialplan, applications, priorities, or
extensions yet (that is coming up in the next chapter). So for now, just
set autofallthrough=yes. It is safest to use the autofallthrough=yes
command as we don’t want Asterisk hanging around waiting for input
unless we explicitly tell it to do so.
There is nothing else for now, but we’ll be using this file as we go through this chapter
to build a test dialplan so we can ensure that all of our devices are working. Also, be
sure to run the dialplan reload command from the Asterisk CLI to update to the latest
changes. Verify your changes by running the CLI command dialplan show:
*CLI> dialplan show
[ Context 'phones' created by 'pbx_config' ]
Include => 'internal' [pbx_config]
[ Context 'internal' created by 'pbx_config' ]
[ Context 'incoming_calls' created by 'pbx_config' ]
[ Context 'default' created by 'pbx_config' ]
[ Context 'parkedcalls' created by 'res_features' ]
'700' => 1. Park((null)) [res_features]
-= 1 extension (1 priority) in 5 contexts. =-
72 | Chapter 4: Initial Configuration of Asterisk
You will see the parkedcalls context because it is an internal context to
Asterisk, specified in the features.conf file.
Setting Up the Dialplan for Some Test Calls
Now let’s expand upon the test dialplan we started in the previous section, allowing
us to dial back into the softphone after we have configured it and to use a dialplan
application called Echo() that will allow us to test bidirectional audio. We’ll learn more
about dialplans in Chapter 5, so for now, just add the italicized bits to your existing
extensions.conf file. We’ll be making use of this dialplan throughout the chapter, and
expanding on it in certain sections. Once you’ve entered the text into extensions.conf,
reload the dialplan by running dialplan reload from the Asterisk console:
[globals]
[general]
[default]
exten => s,1,Verbose(1|Unrouted call handler)
exten => s,n,Answer()
exten => s,n,Wait(1)
exten => s,n,Playback(tt-weasels)
exten => s,n,Hangup()
[incoming_calls]
[internal]
exten => 500,1,Verbose(1|Echo test application)
exten => 500,n,Echo()
exten => 500,n,Hangup()
[phones]
include => internal
FXO and FXS Channels
The difference between an FXO channel and an FXS channel is simply which end of
the connection provides the dial tone. An FXO port does not generate a dial tone; it
accepts one. A common example is the dial tone provided by your phone company. An
FXS port provides both the dial tone and ringing voltage to alert the station user of an
inbound call. Both interfaces provide bidirectional communication (i.e., communication
that is transmitted and received in both directions simultaneously).§
§ Bidirectional communication is also known as full duplex in some circles. Half duplex means communication
is only traveling in one direction at a time.
Setting Up the Dialplan for Some Test Calls | 73
If your Asterisk server has a compatible FXO port, you can plug a telephone line from
your telephone company (or “telco”) into this port. Asterisk can then use the telco line
to place and receive telephone calls. By the same token, if your Asterisk server has a
compatible FXS port, you may plug an analog telephone into your Asterisk server, so
that Asterisk may call the phone and you may place calls.
Ports are defined in the configuration by the signaling they use, as opposed to the
physical type of port they are. For instance, a physical FXO port will be defined in the
configuration with FXS signaling, and an FXS port will be defined with FXO signaling.
This can be confusing until you understand the reasons for it. FX_ cards are named not
according to what they are, but rather according to what is connected to them. An
FXS card, therefore, is a card that connects to a station. Since that is so, you can see
that in order to do its job, an FXS card must behave like a central office and use FXO
signaling. Similarly, an FXO card connects to a central office (CO), which means it will
need to behave like a station and use FXS signaling. The modem in your computer is
a classic example of an FXO device.
The older Digium X100P card used a Motorola chipset, and the X101P
(which Digium sold before completely switching to the TDM400P) is
based on the Ambient/Intel MD3200 chipset. These cards are modems
with drivers adapted to utilize the card as a single FXO device (the telephone
interface cannot be used as an FXS port). Support for the X101P
card has been dropped in favor of the TDM series of cards.
These cards (or their clones) SHOULD NOT be used in production environments.
They are $10 on eBay for a reason.
The X100P/X101P cards are poor cards for production use due to their
tendency to introduce echo into your telephone calls, and their lack of
remote disconnect supervision. Do yourself a favor and don’t waste your
time with this hardware. You will find that if you ask the community
for support of these cards, many responses will be hostile. You have
been warned.
Determining the FXO and FXS Ports on Your TDM400P
Figure 4-1 contains a picture of a TDM400P with an FXS module and an FXO module.
You can’t see the colors, but module 1 is a green FXS module, and module 2 is an
orange-red FXO module. In the bottom-right corner of the picture is the Molex connector,
where power is supplied from the computer’s power supply.
Plugging an FXS port (the green module) into the PSTN may destroy
the module and the card due to voltage being introduced into a system
that wants to produce voltage, not receive it!
74 | Chapter 4: Initial Configuration of Asterisk
Be sure to connect your computer’s power supply to the Molex connector
on the TDM400P if you have FXS modules, as it is used to supply
the voltage needed to drive the ring generator on the FXS ports. The
Molex connector is not required if you have only FXO modules.
Configuring an FXO Channel for a PSTN Connection
We’ll start by configuring an FXO channel. First we’ll configure the Zaptel hardware,
and then the Zapata hardware. We’ll set up a very basic dialplan, and we’ll show you
how to test the channel.
Zaptel Hardware Configuration
The zaptel.conf file located in /etc/ is used to configure your hardware. The following
minimal configuration defines an FXO port with FXS signaling:
fxsks=2
loadzone=us
defaultzone=us
1
2
3
4
1 2 3 4
Figure 4-1. A TDM400P with an FXS module (1 across) and an FXO module (2 across)
Configuring an FXO Channel for a PSTN Connection | 75
In the first line, in addition to indicating whether we are using FXO or FXS signaling,
we specify one of the following protocols for channel 2:
• Loop start (ls)
• Ground start (gs)
• Kewlstart (ks)
The difference between loop start and ground start has to do with how the equipment
requests a dial tone: a ground-start circuit signals the far end that it wants a dial tone
by momentarily grounding one of the leads; a loop-start circuit uses a short to request
a dial tone. Though not common for new installations, analog ground start lines still
exist in many areas of the country.‖ Ground start is really a rather strange thing, because
it doesn’t exist in its analog form in Asterisk, so technically, there is no ground signal
happening, but is rather a signaling bit that is intended for analog circuitry that historically
would have been at the end of the T1. If this does not make much sense, don’t
sweat it; chances are you won’t have to worry about ground-start signaling. All home
lines (and analog telephones/modems/faxes) in North America use loop-start signaling.
Kewlstart is in fact the same as loop start, except that it has greater intelligence and is
thus better able to detect far-end disconnects.# Kewlstart is the preferred signaling
protocol for analog circuits in Asterisk.
To configure a signaling method other than kewlstart, replace the ks in fxsks with either
ls or gs (for loop start or ground start, respectively).
loadzone configures the set of indications (as configured in zonedata.c) to use for the
channel. The zonedata.c file contains information about all of the various sounds that
a phone system makes in a particular country: dial tone, ringing cycles, busy tone, and
so on. When you apply a loaded tone zone to a Zap channel, that channel will mimic
the indications for the specified country. Different indication sets can be configured for
different channels. The defaultzone is used if no zone is specified for a channel.
After configuring zaptel.conf, you can load the drivers for the card. modprobe is used to
load modules for use by the Linux kernel. For example, to load the wctdm driver, you
would run:
# modprobe wctdm
If the drivers load without any output, they have loaded successfully.* You can verify
that the hardware and ports were loaded and configured correctly with the use of the
ztcfg program:
‖ Yes, there is such a thing as ground-start signaling on channelized T1s, but that has nothing to do with an
actual ground condition on the circuit (which is entirely digital).
# A far-end disconnect happens when the far end hangs up. In an unsupervised circuit, there is no method of
telling the near end that the call has ended. If you are on the phone this is no problem, since you will know
the call has ended and will manually hang up your end. If, however, your voicemail system is recording a
message, it will have no way of knowing that the far end has terminated and will, thus, keep recording silence,
or even the dial tone or reorder tone. Kewlstart can detect these conditions and disconnect the circuit.
76 | Chapter 4: Initial Configuration of Asterisk
# /sbin/ztcfg -vv
The channels that are configured and the signaling method being used will be displayed.
For example, a TDM400P with one FXO module has the following output:
Zaptel Configuration
======================
Channel map:
Channel 02: FXS Kewlstart (Default) (Slaves: 02)
1 channels configured.
If you receive the following error, you have configured the channel for the wrong signaling
method (or there is no hardware present at that address):
ZT_CHANCONFIG failed on channel 2: Invalid argument (22)
Did you forget that FXS interfaces are configured with FXO signaling
and that FXO interfaces use FXS signaling?
To unload drivers from memory, use the rmmod (remove module) command, like so:
# rmmod wctdm
The zttool program is a diagnostic tool used to determine the state of your hardware.
After running it, you will be presented with a menu of all installed hardware. You can
then select the hardware and view the current state. A state of “OK” means the hardware
is successfully loaded:
Alarms Span
OK Wildcard TDM400P REV E/F Board 1
Zapata Hardware Configuration
Asterisk uses the zapata.conf file to determine the settings and configuration for telephony
hardware installed in the system. The zapata.conf file also controls the various
features and functionality associated with the hardware channels, such as Caller ID,
call waiting, echo cancellation, and a myriad of other options.
When you configure zaptel.conf and load the modules, Asterisk is not aware of anything
you’ve configured. The hardware doesn’t have to be used by Asterisk; it could very well
be used by another piece of software that interfaces with the Zaptel modules. You tell
Asterisk about the hardware and control the associated features via zapata.conf:
[trunkgroups]
; define any trunk groups
[channels]
; hardware channels
* It is generally safe to assume that the modules have loaded successfully, but to view the debugging output
when loading the module, check the console output (by default this is located on TTY terminal 9, but this is
configurable in the safe_asterisk script—see the previous chapter for details).
Configuring an FXO Channel for a PSTN Connection | 77
; default
usecallerid=yes
hidecallerid=no
callwaiting=no
threewaycalling=yes
transfer=yes
echocancel=yes
echotraining=yes
; define channels
context=incoming ; Incoming calls go to [incoming] in extensions.conf
signaling=fxs_ks ; Use FXS signaling for an FXO channel
channel => 2 ; PSTN attached to port 2
The [trunkgroups] section is used for connections where multiple physical lines are
used as a single logical connection to the telephone network, and won’t be discussed
further in this book. If you require this type of functionality, see the
zapata.conf.sample file and your favorite search engine for more information.
The [channels] section determines the signaling method for hardware channels and
their options. Once an option is defined, it is inherited down through the rest of the
file. A channel is defined using channel =>, and each channel definition inherits all of
the options defined above that line. If you wish to configure different options for different
channels, remember that the options should be configured before the channel
=> definition.
We’ve enabled Caller ID with usecallerid=yes and specified that it will not be hidden
for outgoing calls with hidecallerid=no. Call waiting is deactivated on an FXO line
with callwaiting=no. Enabling three-way calling with threewaycalling=yes allows an
active call to be placed on hold with a hook switch flash (discussed in Chapter 7) to
suspend the current call. You may then dial a third party and join them to the conversation
with another hook switch. The default is to not enable three-way calling.
Allowing call transfer with a hook switch is accomplished by configuring trans
fer=yes; it requires that three-way calling be enabled. The Asterisk echo canceller is
used to remove the echo that can be created on analog lines. You can enable the echo
canceller with echocancel=yes. The echo canceller in Asterisk requires some time to
learn the echo, but you can speed this up by enabling echo training (echotrain
ing=yes). This tells Asterisk to send a tone down the line at the start of a call to measure
the echo, and therefore learn it more quickly.
When a call comes in on an FXO interface, you will want to perform some action. The
action to be performed is configured inside a block of instructions called a context.
Incoming calls on the FXO interface are directed to the incoming context with con
text=incoming. The instructions to perform inside the context are defined within
extensions.conf.
Finally, since an FXO channel uses FXS signaling, we define it as such with signal
ing=fxs_ks.
78 | Chapter 4: Initial Configuration of Asterisk
Dialplan Configuration
The following minimal dialplan makes use of the Echo() application to verify that bidirectional
communications for the channel are working:
[incoming]
; incoming calls from the FXO port are directed to this context
;from zapata.conf
exten => s,1,Answer()
exten => s,n,Echo()
Whatever you say, the Echo() application will relay back to you.
Dialing In
Now that the FXO channel is configured, let’s test it. Run the zttool application and
connect your PSTN line to the FXO port on your TDM400P. Once you have a phone
line connected to your FXO port, you can watch the card come out of a RED alarm.
Now dial the PSTN number from another external phone (such as a cell phone). Asterisk
will answer the call and execute the Echo() application. If you can hear your voice
being reflected back, you have successfully installed and configured your FXO channel.
Configuring an FXS Channel for an Analog Telephone
The configuration of an FXS channel is similar to that of an FXO channel. Let’s take a
look.
Zaptel Hardware Configuration
The following is a minimal configuration for an FXS channel on a TDM400P. The
configuration is identical to the FXO channel configuration above, with the addition
of fxoks=1.
Recall from our earlier discussion that the opposite type of signaling is used for FXO
and FXS channels, so we will be configuring FXO signaling for our FXS channel. In the
example below we are configuring channel 1 to use FXO signaling, with the kewlstart
signaling protocol:
fxoks=1
fxsks=2
loadzone=us
defaultzone=us
After loading the drivers for your hardware, you can verify their state with the use
of /sbin/ztcfg -vv:
Configuring an FXS Channel for an Analog Telephone | 79
Zaptel Configuration
======================
Channel map:
Channel 01: FXO Kewlstart (Default) (Slaves: 01)
Channel 02: FXS Kewlstart (Default) (Slaves: 02)
2 channels configured.
Zapata Hardware Configuration
The following configuration is identical to that for the FXO channel, with the addition
of a section for our FXS port and, of the line immediate=no. The context for our FXS
port is phones, the signaling is fxoks (kewlstart), and the channel number is set to 1.
FXS channels can be configured to perform one of two different actions when a phone
is taken off the hook. The most common (and often expected) option is for Asterisk to
produce a dial tone and wait for input from the user. This action is configured with
immediate=no. The alternative action is for Asterisk to automatically perform a set of
instructions configured in the dialplan instead of producing a dial tone, which you
indicate by configuring immediate=yes.† The instructions to be performed are found in
the context configured for the channel and will match the s extension (both of these
topics will be discussed further in the following chapter).
Here’s our new zapata.conf:
[trunkgroups]
; define any trunk groups
[channels]
; hardware channels
; default
usecallerid=yes
hidecallerid=no
callwaiting=no
threewaycalling=yes
transfer=yes
echocancel=yes
echotraining=yes
immediate=no
; define channels
context=phones ; Uses the [internal] context in extensions.conf
signalling=fxo_ks ; Uses FXO signalling for an FXS channel
channel => 1 ; Telephone attached to port 1
† Also referred to as the Batphone method, and more formally known as an Automatic Ringdown or Private
Line Automatic Ringdown (PLAR) circuit. This method is commonly used at rental car counters and airports.
80 | Chapter 4: Initial Configuration of Asterisk
context=incoming ; Incoming calls go to [incoming] in extensions.conf
signalling=fxs_ks ; Use FXS signalling for an FXO channel
channel => 2 ; PSTN attached to port 2
Dialplan Configuration
We will make use of our minimal dialplan we configured earlier in the chapter to test
our FXS port with the use of the Echo() application. The relevant section, which should
already exist in your dialplan, looks like this:
[internal]
exten => 500,1,Verbose(1|Echo test application)
exten => 500,n,Echo()
exten => 500,n,Hangup()
[phones]
include => internal
Whatever you say, the Echo() application will relay back to you.
Configuring SIP Telephones
The Session Initiation Protocol (SIP),‡ commonly used in VoIP phones (either hard
phones, or softphones), takes care of the setup and teardown of calls, along with any
changes during a call such as call transfers. The purpose of SIP is to help two endpoints
talk to each other (if possible, directly to each other). The SIP protocol is simply a
signaling protocol, which means that its purpose is only to get the two endpoints talking
to each other, and not to deal with the media of the call (your voice). Rather, your voice
is carried using another protocol called the Real-Time Transport Protocol (RTP; RFC
3550) to transfer media directly between the two endpoints.
We use the term media to refer to the data transferred between endpoints
and used to reconstruct your voice at the other end. It may also refer to
music or prompts from the PBX.
In the world of SIP, we call our endpoints user agents, of which there are two types:
client and server. The client is the endpoint that generates the request, and the server
processes the request and generates a response. When an endpoint wishes to place a
call to another endpoint (such as our softphone calling another softphone), we generate
our request and send this to a SIP proxy.§ A proxy server will take the request, determine
‡ RFC 3261 is available at http://www.ietf.org/rfc/rfc3261.txt. While the document is fairly large, we strongly
encourage anyone who wishes to become an Asterisk professional to read at least the first 100 or so pages of
this document and to understand how calls are set up, as this knowledge will be imperative when you’re
looking at a SIP trace (sip debug from the Asterisk console) trying to determine why your calls are not getting
set up correctly.
Configuring SIP Telephones | 81
where the request is destined for, and forward it on. Once the two user agents have
negotiated a successful call setup, the media is transported via the RTP protocol and
sent directly between the two user agents. SIP proxies do not handle media; they simply
deal with the SIP packets.
Asterisk, on the other hand, is called a Back-To-Back User Agent (B2BUA). This means
that Asterisk acts like a user agent in either the server (receiving) or client (sending)
role. So when our softphone dials an extension number, the call is set up between the
softphone and Asterisk directly. If the logic we’ve built into Asterisk determines that
you mean to call another user agent, then Asterisk acts as a user agent client and sets
up another connection (known as a channel) to the other phone. The media between
the two phones then flows directly through Asterisk.‖ From the viewpoint of the
phones, they are talking with Asterisk directly.
Basic SIP Telephone Configuration in Asterisk
Configuring a SIP phone to work with Asterisk does not require much. However, because
there are so many options possible in both Asterisk and the configuration of the
particular telephone set or softphone, things can get confusing. Add to this the fact that
similar things can have different names, and you have a recipe for frustration. What we
are going to do, therefore, is give you the bare-bones basics. If you follow our advice,
you should be able to get the sets we cover working (and be well on your way to getting
a phone that we have not covered to work as well). We are not saying that this is the
best way, or even the right way, but it is the simplest way, and from a working foundation,
it is much easier to take a basic configuration and tweak things until you get
the solution you need.
Just as we did with the extensions.conf file; run the following commands
in your bash shell:
# mv sip.conf sip.conf.sample
# touch sip.conf
Defining the SIP device in Asterisk
If you put the following in a sip.conf file, you will be able to register a phone to the
system.
[general]
§ An excellent open source SIP proxy is OpenSER, available at http://www.openser.org.
‖ Yes, there are ways to making the media flow directly between the phones once the call is set up. This is done
in the sip.conf file using either directrtpsetup=yes (an experimental option allowing the media to be
redirected in the initial call setup) or canreinvite=yes (where media initially goes through Asterisk until a re-
INVITE happens, at which point the media can be sent directly between the phones).
82 | Chapter 4: Initial Configuration of Asterisk
[1000]
type=friend
context=phones
host=dynamic
Not pretty, not secure, not flexible, not fully-featured, but this will work.
Even though we have named this SIP device 1000, and we are probably going to assign
it that extension number, you should note that we could have named it whatever we
wanted. Names such as mysipset, john, 0004f201ab0c are all valid, popular, and may
suit your needs better.# What we are doing is assigning a unique identifier to a device,
which will form part of the credentials when a call is placed using the SIP channel.
Since we want to be able to both send calls to the softphone and allow the client to
place calls, we have defined the type as friend. The other two types are user and
peer. From the viewpoint of Asterisk, a user is configured to enter the dialplan, and a
peer is created for calls leaving the dialplan (via the Dial() application). A friend is
simply a shortcut that defines both a user and a peer. If in doubt, define the type as
friend.
The host option is used to define where the client exists on the network when Asterisk
needs to send a call to it. This can either be defined statically by defining something
like host=192.168.1.100, or if the client has a dynamic IP address, then we set
host=dynamic. When the host option is set as dynamic, and the client is configured to
register, Asterisk will receive a REGISTER packet from the endpoint (i.e., telephone
set or softphone), telling Asterisk which IP address the SIP peer is using.
If you do not trust your network, you should probably also force the use of a password
by adding the following to the device definition. This is one of those things that is not
technically necessary, but is probably a good idea:
secret=guessthis
Configuring the Device Itself
In the configuration menus of the phone itself (which could be via a web GUI, through
menus on the phone itself, or possibly using configuration files that are stored on a
server), the unique identifier (which in this case is 1000) again forms part of the credentials
for the authentication process. Naturally, for a connection to be successful,
this has to match in both Asterisk and in the set itself. The fun begins when you realize
that there is no set rule as to what this identifier is formally called. We have elected
simply to call it the Unique Identifier.
# The maximum length of a username is 255 characters.
Configuring SIP Telephones | 83
In the SIP RFC (http://www.faqs.org/rfcs/rfc3261.html), section 19.1
calls this user token, “the identifier of a particular resource at the host
being addressed,” verbiage consistent with our usage of [1000] as the
set identifier in the sip.conf file of Asterisk.
Instead, you will want to look for fields that are labeled user name, auth name,
authentication name, and so on. The thing to remember is that since you know that the
Asterisk end of the equation is configured simply and correctly, you can experiment
with the phone setting until you find a combination that works. This is much better
than the usual suffering that new users go through, as they change settings in both
places and have no luck getting a phone to register.
We’re gonna say it again: configure sip.conf in the simplest manner possible,
and then don’t change your Asterisk configuration. Trust us; what
we have written here will work. Get your set working (i.e., where you
can make and receive calls), and you will be in a far better position to
begin experimenting with different settings. We have seen too much
suffering (including our own), and we want it to end.
Simplifying sip.conf
The sip.conf file (which was copied to the /etc/asterisk directory by the make samples
command we ran in the previous chapter) contains a large number of options and
documentation inside it, but the file is actually very minimal if you remove all the
commented parameters. The default file really breaks down to just the following few
lines being uncommented by default:
[general]
context=default ; Default context for incoming calls
allowoverlap=no ; Disable overlap dialing support. (Default is yes)
bindport=5060 ; UDP Port to bind to (SIP standard port is 5060)
; bindport is the local UDP port that Asterisk will
; listen on
bindaddr=0.0.0.0 ; IP address to bind to (0.0.0.0 binds to all)
srvlookup=yes ; Enable DNS SRV lookups on outbound calls
; Note: Asterisk only uses the first host
; in SRV records
; Disabling DNS SRV lookups disables the
; ability to place SIP calls based on domain
; names to some other SIP users on the Internet
[authentication]
The [general] section contains the options that will apply to all SIP clients and trunks.
Some settings elsewhere are set only in the [general] section, and others can be set in
the [general] section as defaults for all conditionals unless overridden. These options
are listed under the two columns labeled [users] and [peers] below the
[authentication] header.
84 | Chapter 4: Initial Configuration of Asterisk
Generally, the commented-out options will show you the default setting Asterisk uses,
or will tell you the default option in the option’s description.
You can also check the current state of the SIP channel in Asterisk with the sip show
settings CLI command.
If you are running Asterisk and a softphone on the same system (i.e.,
running an X-Lite softphone and Asterisk on a laptop or desktop), then
you will need to modify the SIP port that client listens on. It will need
to be changed from 5060 to 5061 (or some other unused port) so that
Asterisk and the softphone do not interfere with each other.
Essential Server Components
Before we get into how to define these files, there are a few things that need to be
configured on your server. Running the right services on your network will ensure
your Polycom sets can autoconfigure from the moment you plug them in. There’s a
little work involved here, but we promise that the payoff is worth it. Once you’ve done
this a few times, it only really takes a few minutes on each new system, and going
forward, it’ll save you a lot of mucking about with web interfaces. When you take your
new Polycom phone out of the box, plug it into your network, watch it autoconfigure
itself, and then successfully register with your Asterisk machine, you will know the sort
of joy that only geeks can experience.*
It’s not really that complicated. Where we think people get confused is in making sense
of the various ways this can be achieved, because there are a lot of choices.
DHCP server
Typically, a DHCP server is used to configure basic IP parameters for a device (IP address,
default gateway, and DNS), but the DHCP protocol can actually pass many other
parameters. In our case, we want it to pass some information to the sets that will tell
them where to download their config files from. Here is a sample config from a Linux
DHCP server that will do what is required:
ddns-update-style interim;
ignore client-updates;
subnet 192.168.1.0 netmask 255.255.255.0 {
option routers 192.168.1.1;
option subnet-mask 255.255.255.0;
option domain-name-servers 192.168.1.1;
option ntp-servers pool.ntp.org;
* Typically, it’s at 4 A.M. on the morning of a critical 8 A.M. meeting, after having worked all weekend. Red
Bull is probably the most popular drink of the Asterisk developers. Dr. Pepper would be a close second. Red
Bull, anyone?
Configuring SIP Telephones | 85
option time-offset -18000;
range dynamic-bootp 192.168.1.128 192.168.1.254;
default-lease-time 21600;
max-lease-time 43200;
}
Keep in mind that this assumes that the only things on this network are devices that
belong to the phone system (this setup will hand out an IP address to any device that
requests it). If you have a more complex environment, you will need to configure the
DHCP daemon to handle the various devices it is serving. For example, you might want
to devise a scope that restricts IP addresses in your voice LAN to Polycom phones. Since
all Polycom IP desk phones have 00:04:f2 as their OUI (Organizationally Unique Identifier),
you might choose to restrict scope based on that.
In a Microsoft DHCP environment, the tftp-server-name is referred to
as Boot server host name. It is defined under option 66.
The DHCP protocol is far more flexible than is often realized, because in most environments
it is not used for complex provisioning tasks. With a little care and attention,
you can devise a DHCP environment that serves both your voice and data devices and
greatly simplifies administrative workload when adding new devices.
FTP server
FTP is currently our favorite†way to configure Polycom sets. We would recommend it
over TFTP for any set that allows for both. To install it on your CentOS system, the
following command will install VSFTPD, the Very Secure FTP Daemon:
# yum -y install vsftpd
Then, in order to lock things down, we need to prevent anonymous logins with a simple
change to the vsftpd config file, /etc/vsftpd/vsftpd.conf:
# anonymous_enable=NO
Restart the server with service vsftpd restart. To ensure that the daemon runs after
every reboot, run chkconfig vsftpd on.
Now, we have to create a user account and group for the sets to use. In this case, we
will create an account for the Polycom sets:
† FTP is preferred over TFTP due to the ability of a Polycom phone to see timestamps on FTP files. This allows
the phone to avoid redownloading configuration files and firmware updates that it already has—thus
shortening boot time.
86 | Chapter 4: Initial Configuration of Asterisk
# groupadd PlcmSpIp
# useradd PlcmSpIp -g PlcmSpIp -p PlcmSpIp
# passwd PlcmSpIp
Set the password to PlcmSpIp (the default FTP password for Polycom sets). This can
be changed, but will then require manual configuration from each set in order to advise
them of their nonstandard credentials.‡
For added security, let’s make sure the FTP server keeps that account in a chroot jail:
# echo PlcmSpIp >> /etc/vsftpd/vsftpd.chroot_list
That pretty much does it as far as preparing the operating system to provide the required
services to the phones.
In the next few sections we have provided instructions for various popular SIP telephones.
Choose the section that applies best to the phone that you are planning to use
(whether a hard- or soft-phone). You will note that we have given all of these phones
the exact same unique identifier. If you plan on installing more than one of them, you
will need to ensure that they have unique names, and be sure to update your sip.conf
file to include those device definitions.
CounterPath’s X-Lite Softphone
CounterPath’s X-Lite softphone has become very popular with the Asterisk community.
It is simple, functional, easy on the eyes, and—most importantly—free.
In this section we will be configuring the X-Lite softphone to connect to Asterisk.
The IP address of the phone is 192.168.1.250, and Asterisk is located at 192.168.1.100.
The X-Lite is available for Microsoft Windows, Mac, and Linux. You can obtain a copy
of X-Lite from http://www.counterpath.com/index.php?menu=download.
Now let’s configure our softphone for connecting to our Asterisk box. To configure XLite,
click on the Settings button, as circled in Figure 4-2.
Select System Settings → SIP Proxy → [Default], which will display the default configuration
for the softphone. Configure the screen as shown in Figure 4-3.
If you have not already started Asterisk, then start it now (see Chapter 3 for help installing
and starting Asterisk). If Asterisk is running in the background, you can
reconnect to the CLI by running the following command:
# asterisk -rvvv
‡ You can get into assigning complex and unguessable passwords for the phones to use, but unless you are
going to input the passwords into each phone manually, you’ll have to pass them their FTP username and
password from the DHCP server. Any device that can get on the voice network can get the same information
from the DHCP server. We’re not telling you to ignore security; just don’t assume that creating separate
passwords for each phone is going to improve security.
Configuring SIP Telephones | 87
You will then be given the Asterisk CLI like so:
*CLI>
If Asterisk was already running before changing the sip.conf as instructed in this chapter,
then reload the dialplan and SIP channel with the following two commands:
Settings button
Figure 4-2. X-Lite configuration
Figure 4-3. X-Lite user configuration
88 | Chapter 4: Initial Configuration of Asterisk
*CLI> dialplan reload
*CLI> sip reload
In your X-Lite softphone client, close the Settings windows by clicking the BACK button
until the windows are all closed. You should see X-Lite try to register to Asterisk, and
if successful, you will see the following at the Asterisk CLI:
-- Registered SIP '1000' at 192.168.1.250 port 5061 expires 3600
You can verify the registration status at any time like so:
*CLI> sip show peers
Name/username Host Dyn Nat ACL Port Status
1000/1000 192.168.1.250 D N 5061 OK (63 ms)
1 sip peers [1 online , 0 offline]
More detailed stats of the peer can be shown as follows with sip show peer 1000:
*CLI> sip show peer 1000
* Name : 1000
Secret : <Not set>
MD5Secret : <Not set>
Context : phones
Subscr.Cont. : <Not set>
Language :
AMA flags : Unknown
Transfer mode: open
CallingPres : Presentation Allowed, Not Screened
Callgroup :
Pickupgroup :
Mailbox :
VM Extension : asterisk
LastMsgsSent : 32767/65535
Call limit : 0
Dynamic : Yes
Callerid : "" <>
MaxCallBR : 384 kbps
Expire : 1032
Insecure : no
Nat : RFC3581
ACL : No
T38 pt UDPTL : No
CanReinvite : Yes
PromiscRedir : No
User=Phone : No
Video Support: No
Trust RPID : No
Send RPID : No
Subscriptions: Yes
Overlap dial : Yes
DTMFmode : rfc2833
LastMsg : 0
Configuring SIP Telephones | 89
ToHost :
Addr->IP : 192.168.1.250 Port 5061
Defaddr->IP : 0.0.0.0 Port 5060
Def. Username: 1000
SIP Options : (none)
Codecs : 0x8000e (gsm|ulaw|alaw|h263)
Codec Order : (none)
Auto-Framing: No
Status : Unmonitored
Useragent : X-Lite release 1105d
Reg. Contact : sip:1000@192.168.1.250:5061
Polycom’s IP 430
A lot of folks say configuring Polycom phones is difficult. From what we can tell, they
base this on one of two reasons: 1) The Polycom web-based interface is horrible, or 2)
the automatic provisioning process is painful and confusing.
With respect to item 1, we agree. The web interface on the Polycom phones has got to
be one of the most annoying web interfaces ever developed for an IP telephone. We
don’t use it, and we don’t recommend it.§
So that leaves us with some sort of server-based configuration. Fortunately, in this
regard, the Polycom IP phones are superb—so much so that we can pretty much forgive
the web interface. Set configurations are stored in files on a server, and each set navigates
to the server, downloads the configuration files that are relevant to it, and applies them
to itself.
DHCP server
If you cannot control your DHCP server, you may have to manually specify the FTP
server information on the phone. This is done by rebooting the set, pressing the setup
button before the set begins the load process, and specifying the address of the FTP
server in the small boot menu that these phones offer.
Protocol to use for downloading
The Polycom phones are able to download their configuration by one of three protocols:
TFTP, HTTP, and FTP.
Right off the bat we are going to tell you to avoid TFTP. It is not secure, and the set
cannot use date information to determine which versions of various files are the most
current. It works, but there are better ways, and we are not going to discuss it further.
Polycom phones can pull their config data using HTTP as well, but it has not proven
to be popular, and so we are going to move on.
§ Actually, it does serve one useful purpose, which is to allow you to log on to a set via a browser and query
its configuration.
90 | Chapter 4: Initial Configuration of Asterisk
FTP is currently the preferred method of allowing Polycom phones to obtain their
configuration. It works well, is fairly easy to configure, and is well supported by the
community.
FTP
FTP is currently our favorite way to configure Polycom sets. To install it on your CentOS
system, the following command will install VSFTPD, the Very Secure FTP Daemon:
# yum -y install vsftpd
Then, in order to lock things down, we need to prevent anonymous logins, with a simple
change to the vsftpd config file, /etc/vsftpd/vsftpd.conf:
# anonymous_enable=NO
Restart the server with service vsftpd restart. To ensure that the daemon runs after
every reboot, run chkconfig vsftpd on.
Now, we have to create a user account and group for the Polycom sets to use:
# groupadd PlcmSpIp
# useradd PlcmSpIp -g PlcmSpIp -p PlcmSpIp
# passwd PlcmSpIp
Set the password to PlcmSpIp (the default FTP password for Polycom sets). This can
be changed, but will then require manual configuration from each set in order to advise
them of their nonstandard credentials.‖
For added security, let’s make sure the FTP server keeps that account in a chroot jail:
# echo PlcmSpIp >> /etc/vsftpd/vsftpd.chroot_list
That pretty much does it as far as preparing the operating system to provide the required
services to the phones.
The Polycom configuration files
While there seem to be a lot of different files that are needed to make a Polycom set
work, they are each fairly easy to understand.
This can best be described as the BIOS and operating system of the phone.
Perhaps there is a more technical explanation, but why make things confusing? The
bootROM should not need to be updated regularly, but it is good to keep an eye on
the current releases to see if a newer bootROM has features that will be of benefit in
your environment. This file will be named bootrom.ld.
The bootROM.
‖ You can get into assigning complex and unguessable passwords for the phones to use, but unless you are
going to input the passwords into each phone manually, you’ll have to pass them their FTP user name and
password from the DHCP server. Any device that can get on the voice network can get the same information
from the DHCP server. We’re not telling you to ignore security, just don’t assume that creating separate
passwords for each phone is going to improve security.
Configuring SIP Telephones | 91
Since Polycom sets are capable of supporting other VoIP protocols
(MGCP is supported, for example), the protocol that this set will employ forms part of
the application image that the phone will download and run. If the image on the set is
already correct, this file is not actually needed on the FTP server; however, it is common
to have this file available to ensure that the most recent version of the protocol is available
for the sets to download. You will sometimes receive phones that are not running
the latest version, so having the most current image will ensure that all sets are up-todate.
There is normally only one version of this file on a system, but it can be
named anything you want, and there can be as many different versions of this file as
are needed. For example, if you had an office where there were two different languages
in use, some users might prefer French on their set, and others English. In that case,
you’d create a french.sip.conf file and an english.sip.conf file to handle each case. Name
this file as you see fit, but pick a name that makes sense so that future administrators
have a chance to make sense of your design choices.
This file is very simple and small. It is named to match
the MAC address of each phone (so each set will need its own copy of this file) and tells
the set what other files it needs to download in order to configure itself. This is the first
config file each set will read. In this file will be a reference to the application image this
set will use (currently named sip.ld), as well as the names of the XML files that have the
parameters for this phone (the .cfg files). A master config file for a set might look something
like this:
'<?xml version="1.0" standalone="yes"?>'
'<!-- Default Master SIP Configuration File-->'
'<!-- Edit and rename this file to <Ethernet-address>.cfg for each phone.-->'
'<!-- $Revision: 1.14 $ $Date: 2005/07/27 18:43:30 $ -->'
'<APPLICATION APP_FILE_PATH="sip.ld"
CONFIG_FILES="phone1.cfg, sip.cfg"
MISC_FILES=""
LOG_FILE_DIRECTORY=""
OVERRIDES_DIRECTORY=""
CONTACTS_DIRECTORY=""
/>'
Note the name of the application file that we want this set to use, and the config files
that it will be trying to find and apply.
We recommend giving the phone1.cfg files names that make
sense. For example, SET<xxx>.cfg (such as SET201.cfg) to match the extension number
of the phone, or FLOOR4CUBE23.cfg, or maybe BOB_SMITHS_IP430_SET.cfg,
or whatever seems best to you. What’s the best way to name them? We’re going to
answer that question by asking a question. Let’s say you have 100 of these phones.
When you list the contents of the /home/PlcmSpIp folder, how do you want the 100
config files for the sets to appear?
The application image.
The sip.cfg file.
The master config file for each phone.
The set-specific config file.
92 | Chapter 4: Initial Configuration of Asterisk
Settings that are configured directly on the telephone will be stored on the
filesystem of the set, and may take precedence over parameters passed in config files.
If you are having any problems applying changes to a set, try reformatting the phone.
This will force the set to accept the parameters contained in the config files.
Cisco 7960 Telephone
The venerable old C7960 is now a part of VoIP history. One of the first SIP telephones
that could actually be taken seriously, the only real complaint one can have about this
phone is the price: they are the Cadillac of SIP phones (meaning that they have all the
bells and whistles but are tough to justify at the price, and are a little out of date
sometimes).
If you can get one of these, you are getting an excellent SIP telephone. If you buy one
new, be prepared to pay.
One of the ways this phone is out of date is the lack of remote provisioning from anything
other than TFTP. TFTP has lost favor with networking professionals due to the
lack of authentication and encryption, but since it is the only method of remotely provisioning
the phone, we are going to have to use the tftp-server daemon. We can install
tftp-server with the following command:
# yum install -y tftp-server
Once installed, we need to enable the server by modifying the /etc/xinetd.d/tftp file. To
enable the TFTP server, change the disable=yes line to disable=no.
service tftp
{
socket_type = dgram
protocol = udp
wait = yes
user = root
server = /usr/sbin/in.tftpd
server_args = -s /tftpboot
disable = no
per_source = 11
cps = 100 2
flags = IPv4
}
Then start the TFTP server by running:
# service xinetd restart
We can verify the server is running with the following command:
# chkconfig --list | grep tftp
tftp: on
As long as tftp: on was returned, the server is up and running.
Gotchas.
Configuring SIP Telephones | 93
Cisco phones by default are loaded with their own communication protocol
known as SCCP (or Skinny). We will be showing you how to
configure the phone, but due to the proprietary nature of Cisco and its
phones, you will need to obtain the SIP firmware from your distributor.
Also, there are both chan_sccp and chan_skinny modules for Asterisk,
but they are beyond the scope of this book.
We will be registering our Cisco phone to the SIP friend we configured in “Zaptel
Hardware Configuration.” The following configuration file should be saved into a file
taking the format of SIP<mac>.cnf, where <mac> represents the MAC address of the
telephone device you are configuring. Place this file into the /tftpboot/ directory on your
server:
# Line 1 Configuration
line1_name: "1000"
line1_authname: "1000"
line1_shortname: "Jimmy Carter"
line1_password: ""
line1_displayname: ""
# The phone label, displayed in the upper-righthand corner of the phone
phone_label: "aristotle" ; Has no effect on SIP messaging
# Phone password used for console or telnet access, limited to 31 characters
phone_password: "cisco"
Then configure the address to register in the SIPDefault.cnf file, also placed in
the /tftpboot/ directory of your server. proxy1_address will contain the IP address of
your Asterisk server of where the phone should register for line 1. The image_version
contains the version of the .loads and .sb2 files the phone will load into memory.
image_version: P0S3-08-4-00
proxy1_address: 192.168.1.100
We need one additional file called OS79XX.TXT. This file contains only a single
line―the .bin and .sbn file version to load into memory:
P003-08-4-00
In order for our Cisco 7960 to use these files, we need to tell the phone where to pull
its configuration from. If using the DHCP server from your Linux server, you can modify
the /etc/dhcpd.conf file in order to tell the phone where to pull its configuration from
by adding the line:
option tftp-server-name "192.168.1.100";
which contains the IP address of the server hosting the TFTP server (assuming of course
the TFTP server is configured at that address. This is the address we’ve been using for
our Asterisk server, and we again assume you’ve installed the TFTP server on the same
box as Asterisk). See “DHCP server” for more information about configuring the DHCP
server:
94 | Chapter 4: Initial Configuration of Asterisk
ddns-update-style interim;
ignore client-updates;
subnet 192.168.1.0 netmask 255.255.255.0 {
option routers 192.168.1.1;
option subnet-mask 255.255.255.0;
option domain-name-servers 192.168.1.1;
option tftp-server-name "192.168.1.100";
option ntp-servers pool.ntp.org;
option time-offset -18000;
range dynamic-bootp 192.168.1.128 192.168.1.254;
default-lease-time 21600;
max-lease-time 43200;
}
Alternatively, you can configure from the phone itself to manually use
an alternative TFTP server than that given by the DHCP server. To do
so, press the settings button, (on the G version of the Cisco phones, this
looks like a square with a check mark inside of it; G means Global). You
will then need to unlock the settings by pressing the 9 key. The default
password is cisco. Once the phone is unlocked, press the 3 key on the
dialpad to enter the Network Configuration. Scroll down to option 32
and set the Alternate TFTP to YES. Then scroll up to option 7 and enter
the IP address of the TFTP server you wish to boot from. Accept the
settings and back out of the menu until the phone reboots itself. You
can also use the *-6-settings three finger salute to reboot your phone at
any time.
You can watch the phone pull its configuration from the TFTP server by using tshark
(yum install ethereal). Filter on port 69 using the following command:
# tshark port 69
You should then be able to watch the network traffic from the phone requesting data
from your TFTP server.
If all goes well, then you should see your phone registered to Asterisk!
Linksys SPA-942
Ever since they purchased Sipura Technologies, Linksys has been producing a line of
economical VoIP telephones and ATAs (Analog Terminal Adaptors). Linksys has been
stealing a lot of business from Cisco. If you have read Clayton M. Christensen’s
The Innovator’s Dilemma (HarperCollins), it becomes easier to understand Cisco’s
strategy with respect to Linksys.
Linksys (and Sipura) products are well regarded for their excellent quality, especially
relative to their price, but they are also famous for being painfully difficult to configure.
Configuring SIP Telephones | 95
This is mostly because their configuration GUI offers hundreds of configurable parameters.
We don’t care about that. Here’s what you need to know to get an SPA-942 working
with your Asterisk system (and, we hope, most other Linksys VoIP devices as well).
Logging in to the phone
The first thing you need to do is get the IP address of the phone so you can log in to
the GUI interface. From the phone itself, select the icon that looks like a piece of paper
with a dog-eared corner (right below the envelope icon). This is the Settings button,
and is shown in Figure 4-4.
To get the IP address of the phone, press the Settings button, followed by 9 (or use
directional pad and scroll down to Network). Then press the select button (there is a
row of 4 buttons under the LCD screen—select is the leftmost button). The second field
should show you the IP address of the phone.
Now open your browser, enter the IP address into the address bar, hit Enter, and you
will be at the Info screen of the phone.
Registering your phone to Asterisk
Select the Admin Login link in the upper-right corner of the screen. Once you’ve done
this, you will be given several new tabs, such as Regional, Phone, Ext 1, Ext 2, and User.
Select the Ext 1 tab which will set up our first line. Then make the following menu
selections:
1. General → Line Enable → yes
2. NAT Settings → NAT Mapping Enable → no
3. NAT Settings → NAT Keep Alive Enable → no
Figure 4-4. SPA-942 keypad
96 | Chapter 4: Initial Configuration of Asterisk
4. Proxy and Registration → Proxy → enter the IP address of Asterisk
(e.g., 192.168.1.100)
5. Proxy and Registration → Register → yes
6. Proxy and Registration → Make Call Without Reg → no
7. Proxy and Registration → Ans Call Without Reg → no
8. Subscriber Information → Display Name → Caller ID information
9. Subscriber Information → User ID → 1000
10. Subscriber Information → Password → (leave blank if you’re using the simple configuration
from earlier in this chapter)
11. Subscriber Information → Use Auth ID → yes
12. Subscriber Information → Auth ID → 1000
13. Audio Configuration → Preferred Codec → G711u
14. Audio Configuration → Use Pref Codec Only → no
15. Audio Configuration → Silence Supp Enable → no
16. Audio Configuration → DTMF Tx Method → Auto
17. Submit All Changes
And that’s it! Your phone should be registered to Asterisk now. You’ll know this because
the first lighted line button beside the LCD screen will change from orange to
green.
Configuring the Dialplan for Testing
In order to allow our phone to call other phones (or, if a multiline phone, to call itself),
we need to modify the extensions.conf file. Building on what we had in “Setting Up the
Dialplan for Some Test Calls,” add the following parts to the [internal] context:
exten => 1000,1,Verbose(1|Extension 1000)
exten => 1000,n,Dial(SIP/1000,30)
exten => 1000,n,Hangup()
If you have two phones, or multiple lines configured, you can duplicate the previous
configuration and change the 1000 to the other extension name.
Connecting to a SIP Service Provider
With the advent of Internet telephony, there has been an influx of Internet-based phone
companies springing up all over the world! This gives you a large number of choices
from which to choose. Many of these service providers allow you to connect your Asterisk-
based system to their networks,# and some of them are even running Asterisk
themselves!
Connecting to a SIP Service Provider | 97
The following configuration should get you connected with an Internet Telephony
Service Provider (ITSP),* although it is impossible to know the unique configurations
each service provider will require from you, and ideally the provider will give you the
configuration required to connect your system with its own. However, not all are going
to support Asterisk, so we’re going to provide you with a generic configuration which
should help you get on your way and, ideally, going in a matter of minutes:
[my_service_provider]
type=peer
host=10.251.55.100
fromuser=my_unique_id
secret=my_special_secret
context=incoming_calls
dtmfmode=rfc2833
disallow=all
allow=gsm
allow=ulaw
deny=0.0.0.0/0
permit=10.251.55.100/32
insecure=invite
Configuring a Local Firewall
If you’re running iptables on the same machine as the Asterisk box, then you can run
the following commands to open port 5060 for SIP signaling, and ports 10,000 through
20,000 for the RTP traffic. You can also narrow the range of RTP ports in the rtp.conf
file located in /etc/asterisk. An excellent book on iptables firewalls is Linux Firewalls by
Steve Suehring and Robert Ziegler (Novell Press).
# iptables -I RH-Firewall-1-INPUT -p udp --dport 5060 -j ACCEPT
# iptables -I RH-Firewall-1-INPUT -p udp --dport 10000:20000 -j ACCEPT
# service iptables save
Be aware that this will allow all UDP traffic from any source access to ports 5060 and
10,000 through 20,000.
Most of the previous configuration may be familiar to you by now, but in case it’s not,
here is a brief rundown.
By defining the type as a peer, we are telling Asterisk not to match on the [my_serv
ice_provider] name, but rather to match on the IP address in the INVITE message
(when the provider is sending us a call). The host parameter is the IP address that we’ll
place our calls to, and the IP address we’ll be matching on when receiving a call from
the provider.
# Be sure to check the policy of any service provider you are looking to connect with, as some of them may not
allow you to use a PBX system with its service.
* Also known as a VoIP Service Provider (VSP).
98 | Chapter 4: Initial Configuration of Asterisk
Matching on Username Instead of IP Address
Some service providers may insteadSession Initiation Protocol be sending their calls to
you via multiple IP addresses, requiring you to create a separate peer account for each
IP address. If you don’t know each of these IP addresses, you may need to match on
the username instead. The format for the service provider definition needs to only
change slightly, but the biggest change to note is that you will need to set the [service_
provider_header] as the username your service provider is going to send the call
to. We have also changed the type from a peer to a friend, which from the viewpoint
of Asterisk creates both a type user and type peer, where the type user will be matched
before the peer:
[my_unique_id]
type=friend
host=10.251.55.100
fromuser=my_unique_id
secret=my_special_secret
context=incoming_calls
dtmfmode=rfc2833
disallow=all
allow=gsm
allow=ulaw
insecure=invite
Note that we’ve removed the deny and permit parameters since we may not know the
IP addresses the calls will be coming from. If you do happen to know them and still
wish to match them, you can add back in the deny and permit(s) for the IP addresses.
The fromuser parameter is going to affect the way our INVITE message is structured
when sending the call to the provider. By setting our username in the fromuser parameter,
we will modify the From: and Contact: fields of the INVITE when sending a call
to the provider. This may be required by the provider if it’s using these fields as part of
its authentication routine. You can see the places Asterisk modifies the header in the
next two code blocks.
Without the fromuser:
Audio is at 66.135.99.122 port 18154
Adding codec 0x2 (gsm) to SDP
Adding codec 0x4 (ulaw) to SDP
Adding non-codec 0x1 (telephone-event) to SDP
Reliably Transmitting (no NAT) to 10.251.55.100:5060:
INVITE sip:15195915119@10.251.55.100 SIP/2.0
Via: SIP/2.0/UDP 66.135.99.122:5060;branch=z9hG4bK32469d35;rport
From: "asterisk" <sip:asterisk@66.135.99.122>;tag=as4975f3ff
To: <sip:15195915119@10.251.55.100>
Contact: <sip:asterisk@66.135.99.122>
Call-ID: 58e3dfb2584930cd77fe989c00986584@66.135.99.122
CSeq: 102 INVITE
User-Agent: Asterisk PBX
Max-Forwards: 70
Date: Fri, 20 Apr 2007 14:59:24 GMT
Connecting to a SIP Service Provider | 99
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, SUBSCRIBE, NOTIFY
Supported: replaces
Content-Type: application/sdp
Content-Length: 265
With the fromuser:
Audio is at 66.135.99.122 port 11700
Adding codec 0x2 (gsm) to SDP
Adding codec 0x4 (ulaw) to SDP
Adding non-codec 0x1 (telephone-event) to SDP
Reliably Transmitting (no NAT) to 10.251.55.100:5060:
INVITE sip:15195915119@10.251.55.100 SIP/2.0
Via: SIP/2.0/UDP 66.135.99.122:5060;branch=z9hG4bK635b0b1b;rport
From: "asterisk" <sip:my_unique_id@66.135.99.122>;tag=as3186c1ba
To: <sip:15195915119@10.251.55.100>
Contact: <sip:my_unique_id@66.135.99.122>
Call-ID: 0c7ad6156f92e70b1fecde903550a12f@66.135.99.122
CSeq: 102 INVITE
User-Agent: Asterisk PBX
Max-Forwards: 70
Date: Fri, 20 Apr 2007 15:00:30 GMT
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, SUBSCRIBE, NOTIFY
Supported: replaces
Content-Type: application/sdp
Content-Length: 265
The deny and permit statements are used to deny all incoming calls to this peer except
the IP address defined by the permit parameter. This is simply a security measure used
to make sure nothing else matches on this peer except traffic coming from the IP address
we expect.
At the end is insecure=invite, which may be required for your provider. This is because
the source of the INVITE may originate from its backend platform, but could be directed
through its SIP proxy server. Basically what this means is that the IP address that
the peer is coming from, and which you are matching on, may not be the IP address
that is in the Contact line: field of the INVITE message when you are accepting a call
from your provider. This tells Asterisk to ignore this inconsistency and to accept the
INVITE anyway.
You may need to set invite=invite,port if the port address is also inconsistent
with what Asterisk is expecting.
Now we need one additional parameter set in the [general] section of our sip.conf file:
register. register is going to tell the service provider where to send calls when it has
a call to deliver to us. This is Asterisk’s way of saying to the service provider, “Hey! If
you’ve got a call for me, send it to me at IP address 10.251.55.100.” The register
parameter takes the following form:
100 | Chapter 4: Initial Configuration of Asterisk
register => username:secret@my.service_provider.tld
Now we just need to configure a simple dialplan to handle our incoming calls and to
send calls via the service provider. We’re going to modify the simple dialplan we started
building in the “Setting Up the Dialplan for Some Test Calls” section of this chapter.
The italicized sections are the new parts that we’re adding to the dialplan, with everything
else existing previously.†
[globals]
[general]
[default]
exten => s,1,Verbose(1|Unrouted call handler)
exten => s,n,Answer()
exten => s,n,Wait(1)
exten => s,n,Playback(tt-weasels)
exten => s,n,Hangup()
[incoming_calls]
exten => _X.,1.NoOp()
exten => _X.,n,Dial(SIP/1000)
[outgoing_calls]
exten => _X.,1,NoOp()
exten => _X.,n,Dial(SIP/my_service_provider/${EXTEN})
[internal]
exten => 1000,1,Verbose(1|Extension 1000)
exten => 1000,n,Dial(SIP/1000,30)
exten => 1000,n,Hangup()
exten => 500,1,Verbose(1|Echo test application)
exten => 500,n,Echo()
exten => 500,n,Hangup()
[phones]
include => internal
include => outgoing_calls
Connecting Two Asterisk Boxes Together via SIP
There may come a time when you have a pair of Asterisk boxes, and you’d like to pass
calls between them. Luckily this isn’t very difficult, although it does have some oddities
that we need to deal with, but from the configuration viewpoint it isn’t really all that
difficult.
† We also assume you have configured at least one SIP extension from the previous section.
Connecting Two Asterisk Boxes Together via SIP | 101
Configuring a Local Firewall
If you’re running iptables on the same machine as the Asterisk box, then you can run
the following commands to open port 5060 for SIP signaling, and ports 10,000 through
20,000 for the RTP traffic. You can also narrow the range of RTP ports in the rtp.conf
file located in /etc/asterisk. An excellent book on iptables firewalls is Linux Firewalls by
Steve Suehring and Robert Ziegler (Novell Press):
# iptables -I RH-Firewall-1-INPUT -p udp --dport 5060 -j ACCEPT
# iptables -I RH-Firewall-1-INPUT -p udp --dport 10000:20000 -j ACCEPT
# service iptables save
Be aware that this will allow all UDP traffic from any source access to ports 5060 and
10,000 through 20,000.
Our topology will consist of a SIP phone (Alice) registered to Asterisk A (Toronto), and
a separate SIP phone (Bob) registered to Asterisk B (Osaka). At the end of this section,
you will be able to set up a call from Alice to Bob (and vice versa) through your pair of
Asterisk boxes (see Figure 4-5). This is a common scenario when you have two physical
locations, such as a company with multiple offices that wants a single logical extension
topology.
First, let’s configure our Asterisk boxes.
Configuring Our Asterisk Boxes
We have a pair of Asterisk boxes that we’re going to call Toronto and Osaka and that
we’re going to have register to each other. We’re going to use the most basic sip.conf
file that will work in this scenario. Just like the SIP phone configuration earlier in this
chapter, it’s not necessarily the best way to do it, but it’ll work.
Here is the configuration for the Toronto box:
[general]
register => toronto:welcome@192.168.1.101/osaka
[osaka]
Toronto Osaka
Figure 4-5. SIP trunking topology
102 | Chapter 4: Initial Configuration of Asterisk
type=friend
secret=welcome
context=osaka_incoming
host=dynamic
disallow=all
allow=ulaw
And the configuration for the Osaka box:
[general]
register => osaka:welcome@192.168.2.202/toronto
[toronto]
type=friend
secret=welcome
context=toronto_incoming
host=dynamic
disallow=all
allow=ulaw
Many of the previous options may be familiar to you by now, but let’s take a look at
them further just in case they are not.
The second line of the file tells our Asterisk box to register to the other box, with the
purpose of telling the remote Asterisk box where to send calls when it wishes to send
a call to our local Asterisk box. Remember how we mentioned a little oddity in the
configuration? Notice that at the end of the registration line we tag on a forward slash
and the username of the remote Asterisk box? What this does is tell the remote Asterisk
box what digest name to use when it wants to set up a call. If you forget to add this,
then when the far end tries to send you a call, you’ll see the following at your Asterisk
CLI:
[Apr 22 18:52:32] WARNING[23631]: chan_sip.c:8117 check_auth: username mismatch,
have <toronto>, digest has <s>
So by adding the forward slash and username, we tell the other end what to place in
the Digest username of the Proxy Authorization field in the SIP INVITE message.
The rest of the file is the authorization block we use to control the incoming and outgoing
calls from the other Asterisk box. On the Toronto box, we have the [osaka]
authorization block, and on the Osaka box, we have the [toronto] block. We define
the type as a friend, which allows us to both receive and place calls from the other
Asterisk box. The secret is the password the other system should use when authenticating.
The context is where incoming calls are processed in the dialplan
(extensions.conf). We set the host parameter to dynamic, which tells our Asterisk box
that the other endpoint will register to us, thereby telling us what IP address to set up
calls when we want to send a call to the other end. Finally, the disallow and allow
parameters control the codecs we wish to use with the other end.
If you save the file and reload the SIP channel on both Asterisk boxes (sip reload from
the Asterisk console), you should see something like the following, which will tell you
the remote box successfully registered:
Connecting Two Asterisk Boxes Together via SIP | 103
*CLI> -- Saved useragent "Asterisk PBX" for peer toronto
You should see the status of the Host change from (Unspecified) to the IP address of
the remote box when you run sip show peers:
*CLI> sip show peers
Name/username Host Dyn Nat ACL Port Status
toronto/osaka 192.168.2.202 D 5060 Unmonitored
You can verify that your own registration was successful by running sip show
registry from the Asterisk console:
*CLI> sip show registry
Host Username Refresh State Reg.Time
192.168.1.101:5060 osaka 105 Registered Sun, 22 Apr 2007 19:13:20
Now that our Asterisk boxes are happy with each other, let’s configure a couple of SIP
phones so we can call between the boxes.
SIP Phone Configuration
See the “Configuring an FXS Channel for an Analog Telephone” section of this chapter
for more information about configuring SIP phones with Asterisk. Below is the configuration
for two SIP phones in the sip.conf file for each server, which we’ll be
referencing from the dialplan in the next section, thereby giving us two endpoints to
call between. Append this configuration to the end of the sip.conf file on each respective
server.
Toronto sip.conf:
[1000]
type=friend
host=dynamic
context=phones
Osaka sip.conf:
[1001]
type=friend
host=dynamic
context=phones
You should now have extension 1000 registered to Toronto, and extension 1001 registered
to Osaka. You can verify this with the sip show peers command from the
Asterisk console. Next, we’re going to configure the dialplan logic that will allow us to
call between the extensions.
Configuring the Dialplan
Now we can configure a simple dialplan for each server allowing us to call between the
two phones we have registered: one to Toronto, the other to Osaka. In the “Working
with Interface Configuration Files” section of this chapter, we asked you to create a
104 | Chapter 4: Initial Configuration of Asterisk
simple extensions.conf file. We are going to build up a dialplan based on this simple
configuration. The dialplan for each server will be very similar to the other one, but for
clarity we will show both. The new lines we’re adding to the file will be italicized.
Toronto extensions.conf:
[globals]
[general]
autofallthrough=yes
[default]
[incoming_calls]
[phones]
include => internal
include => remote
[internal]
exten => _2XXX,1,NoOp()
exten => _2XXX,n,Dial(SIP/${EXTEN},30)
exten => _2XXX,n,Playback(the-party-you-are-calling&is-curntly-unavail)
exten => _2XXX,n,Hangup()
[remote]
exten => _1XXX,1,NoOp()
exten => _1XXX,n,Dial(SIP/osaka/${EXTEN})
exten => _1XXX,n,Hangup()
[osaka_incoming]
include => internal
Osaka extensions.conf:
[globals]
[general]
autofallthrough=yes
[default]
[incoming_calls]
[phones]
include => internal
include => remote
[internal]
exten => _1XXX,1,NoOp()
exten => _1XXX,n,Dial(SIP/${EXTEN},30)
exten => _1XXX,n,Playback(the-party-you-are-calling&is-curntly-unavail)
exten => _1XXX,n,Hangup()
[remote]
exten => _2XXX,1,NoOp()
Connecting Two Asterisk Boxes Together via SIP | 105
exten => _2XXX,n,Dial(SIP/toronto/${EXTEN})
exten => _2XXX,n,Hangup()
[toronto_incoming]
include => internal
Once you’ve configured your extensions.conf file, you can reload it from the Asterisk
console with the dialplan reload command. Verify your dialplan loaded with the
dialplan show command.
And that’s it! You should be able to place calls between your two Asterisk servers now.
Configuring an IAX Softphone
A major advantage of using the IAX2 protocol is that it is designed to be more friendly
to working within odd network configurations, especially working behind NAT. This
makes it a fantastic protocol for softphone clients since they are often utilized on laptops
that roam into many different networks, often with no control of the network itself
(such as when traveling between hotel networks).
The Inter-Asterisk eXchange (IAX) protocol is usually used for server-to-server communication;
more hard phones are available that talk SIP. However, there are several
softphones that support the IAX protocol, and work is progressing on several fronts
for hard phone support in firmware. The primary difference between the IAX and SIP
protocols is the way media (your voice) is passed between endpoints.
With SIP, the RTP (media) traffic is passed using different ports than those used by the
signaling methods. For example, Asterisk receives the signaling of SIP on port 5060 and
the RTP (media) traffic on ports 10,000 through 20,000 by default. The IAX protocol
differs in that both the signaling and media traffic are passed via a single port: 4569.
An advantage to this approach is that the IAX protocol tends to be better suited to
topologies involving NAT.
There exist many IAX-based softphones, but not so many hardware based phones. The
most pronounced reason is because IAX2 is not yet an IETF standard, yet many people
have become early adopters and have reaped the benefits.
An excellent IAX2 softphone is idefisk, available at http://www.asteriskguru.com‡ for
free download. The authors have had excellent results with this softphone, and since
it runs on Microsoft Windows, Mac OS X, and Linux, it is an excellent cross-platform
softphone to write about. We will be demonstrating version 1.31 in this book, although
version 2.0 was recently released (April 2007) but is not yet available for Linux.
‡ The Asterisk Guru site is also an excellent source of documentation!
106 | Chapter 4: Initial Configuration of Asterisk
Configuring the Channel Configuration File (iax.conf)
Like the rest of this chapter, we’re attempting to get you up and running quickly with
the smallest configuration file set possible in order to minimize the problems you may
have in configuring your devices. Just like the sip.conf file, iax.conf requires only a few
simple lines to get our IAX phone registered to Asterisk. Let’s take a look:
[general]
autokill=yes
[idefisk]
type=friend
host=dynamic
context=phones
Yes, really, that’s all you need to get your softphone up and running. It’s not the most
secure or feature-rich configuration (we’re not even using a password), but this will
work.
In the [general] section of our iax.conf file, we have a single option: autokill= yes. We
use this option to avoid things from stalling when a peer does not ACK (reply) to our
NEW packet (new call setup request) within 2000 milliseconds. Instead of the reply to
value yes, you can set this to the number of milliseconds to wait for the ACK to our
NEW packet. You can control the autokill option for each individual peer by defining
qualify for those peers that you know may be on poor network connections.
The rest of the file contains the definition for our softphone. We define the type as
friend, which tells Asterisk we will send calls to this device and also accept calls from
this device. A friend is a shortcut for defining a separate peer (send calls to the softphone),
and user (accept calls from the softphone). We could also have defined
individual definitions for the peer and user like so:
[idefisk]
type=user
context=phones
[idefisk]
type=peer
host=dynamic
Once you’ve configured your iax.conf file, save the file and reload the IAX2 channel
module from your Asterisk console with module reload chan_iax2.so. Confirm your
new peer exists by running iax2 show peers.
localhost*CLI> iax2 show peers
Name/Username Host Mask Port Status
idefisk (Unspecified) (D) 255.255.255.255 0 Unmonitored
1 iax2 peers [0 online, 0 offline, 1 unmonitored]
Configuring an IAX Softphone | 107
Configure the Softphone
Once you’ve installed the idefisk softphone, open up the client and you’ll see the main
screen shown in Figure 4-6.
After we’ve started the softphone, we need to configure our softphone so we can place
calls. We also need to register to Asterisk so we can receive calls. To do this, Right-click
on the icon in the top-left corner of the screen, which will open a drop-down menu.
Select Account Options from the drop-down, which will bring up the screen shown in
Figure 4-7.
Figure 4-6. idefisk
Figure 4-7. idefisk Account Options screen
108 | Chapter 4: Initial Configuration of Asterisk
Start by creating a new account on the softphone by clicking the New button and filling
out the relevant information. The Host should point to the IP address or domain name
of your Asterisk system, with the username matching that of the value located between
the square brackets [ ] in your iax.conf file. Leave the password field blank, as we did
not configure a secret in iax.conf, and the Caller ID and Number can be set to whatever
you wish. If you want idefisk to register this account on startup, select the “Register on
startup” checkbox. When done, click the OK button to save the new account.
If you clicked the “Register on startup checkbox,” then the phone will attempt to register
to Asterisk. On the Asterisk console you will see output telling you that the phone
has registered:
-- Registered IAX2 'idefisk' (UNAUTHENTICATED) at 127.0.0.1:32771
You can verify your registration with the iax2 show peers command at the Asterisk
console:
localhost*CLI> iax2 show peers
Name/Username Host Mask Port Status
idefisk 127.0.0.1 (D) 255.255.255.255 32771 Unmonitored
1 iax2 peers [0 online, 0 offline, 1 unmonitored]
Configuring the Dialplan for Testing
One final thing to do is confirm dialing through our phone by configuring a simple
dialplan in extensions.conf. You can simply test that you have audio in both directions
by calling extension 500, or you can modify the dialplan we created in the “Setting Up
the Dialplan for Some Test Calls” section of this chapter to place some test calls. If you
also configured a SIP phone at extension 1000 in the previous sections, then the following
will not overlap with that, as we’ll be using extension 1001 (unless you
configured multiple SIP extensions, in which case just configure a unique extension
number for your IAX2 softphone):
[globals]
[general]
[default]
exten => s,1,Verbose(1|Unrouted call handler)
exten => s,n,Answer()
exten => s,n,Wait(1)
exten => s,n,Playback(tt-weasels)
exten => s,n,Hangup()
[incoming_calls]
[internal]
exten => 500,1,Verbose(1|Echo test application)
exten => 500,n,Echo()
exten => 500,n,Hangup()
Configuring an IAX Softphone | 109
exten => 1001,1,Verbose(1|Extension 1000)
exten => 1001,n,Dial(IAX2/idefisk,30)
exten => 1001,n,Hangup()
[phones]
include => phones
Connecting to an IAX Service Provider
Some Internet Telephony Service Providers (ITSPs) provide the ability to originate and
terminate calls via the IAX2 protocol. Beyond minimizing the number of ports required
to be open on the firewall (IAX2 only requires a single port for both signaling and
media), the protocol’s trunking feature is attractive to both ITSPs and their customers
due to the savings in bandwidth that can be obtained when running many simultaneous
calls between endpoints.
If your ITSP is offering IAX2 termination, there is a strong chance it is running Asterisk;
thus the configuration for connecting to these service providers is more than likely going
to be similar to what we are providing here.
The following configuration is a template for connecting to an IAX2 service provider:
[general]
autokill=yes
register => username:password@my.service-provider.tld
[my_unique_id]
type=user
secret=my_unique_password
context=incoming_calls
trunking=yes
disallow=all
allow=gsm
allow=ulaw
deny=0.0.0.0/0.0.0.0
permit=10.251.100.1/255.255.255.255
[my_unique_id]
type=peer
host=10.251.100.1
trunking=yes
disallow=all
allow=gsm
allow=ulaw
To accept incoming calls from the Direct Inward Dialing (DID) number that your service
provider assigned to you, we need to modify our extensions.conf file. Perhaps you
want to send the call to an auto-attendant, or maybe simply to your desk phone. In
either case, you can accept calls from your service provider and match on the incoming
DID with the following bit of dialplan logic:
110 | Chapter 4: Initial Configuration of Asterisk
[globals]
[general]
autofallthrough=yes
[default]
[incoming_calls]
exten => 14165551212,1,NoOp()
exten => 14165551212,n,Dial(SIP/1000,30)
exten => 14165551212,n,Playback(the-party-you-are-calling&is-curntly-unavail)
exten => 14165551212,n,Hangup()
exten => 4165551212,1,Goto(1${EXTEN})
[internal]
[phones]
include => internal
Connecting Two Asterisk Boxes Together via IAX
Often it is desirable to connect two physical Asterisk boxes together via IAX in order
to send calls between two physical locations (the distance between these locations may
be centimeters or kilometers). One of the advantages to using the IAX protocol to do
this is a feature called trunking, which utilizes a method of sending the voice data for
multiple calls at once with a single header. This has little effect on only one or two
simultaneous calls, but if you are sending tens or hundreds of calls between two locations,
the bandwidth savings by utilizing trunking can be tremendous.
Configuring a Local Firewall
If you’re running iptables on the same machine as the Asterisk box, then you can run
the following commands to open port 4569 for the IAX2 protocol. An excellent book
on iptables firewalls is Linux Firewalls by Steve Suehring and Robert Ziegler (Novell
Press).
# iptables -I RH-Firewall-1-INPUT -p udp --dport 4569 -j ACCEPT
# service iptables save
Be aware that this will allow all UDP traffic from any source access to port 4569.
You will need a timing interface installed on your system, whether it be
hardware from Digium or via the kernel by using the ztdummy driver.
This will require you to have Zaptel installed on your system and running.
See Chapter 3 for more information about installing Zaptel.
Connecting Two Asterisk Boxes Together via IAX | 111
Configuring Our Asterisk Boxes
We’ll be utilizing a simple topology where we have two Asterisk boxes registered to
each other directly, and separate phones registered to each Asterisk box. We’ll call the
two Asterisk boxes Toronto and Osakafi (see “Connecting Two Asterisk Boxes Together
via SIP”). Bob’s phone will be registered and connected to Toronto, while Alice’s
phone will be registered and connected to Osaka.
The first thing we want to do is create a new channel file (iax.conf) by renaming the
current sample file to iax.conf.sample and creating a new blank iax.conf:
# cd /etc/asterisk
# mv iax.conf iax.conf.sample
# touch iax.conf
Next, open up the iax.conf file and enter the following configuration on the Toronto
Asterisk box:
[general]
autokill=yes
register => toronto:welcome@192.168.1.107
[osaka]
type=friend
host=dynamic
trunk=yes
secret=welcome
context=incoming_osaka
deny=0.0.0.0/0.0.0.0
permit=192.168.1.107/255.255.255.255
autokill=yes was explained in the previous section, but its purpose is to make sure new
calls being set up to a remote system that are not acknowledged within a reasonable
amount of time (two seconds by default) are torn down correctly. This saves us from
having a lot of hung channels simply waiting for an acknowledgement that probably
isn’t coming.
The register line is used to tell the remote Asterisk box where we are so that when the
box at 192.168.1.107 is ready to send us a call, it sends it to our IP address (in this case
our IP address is 192.168.1.104, which you’ll see in the iax.conf configuration of the
Osaka box). We send the username Toronto and the password welcome to Osaka, which
authenticates our registration, and if accepted, writes the location of our Asterisk box
into its memory for when it needs to send us a call.
The [Osaka] definition is used to control the authentication of the remote box and
delivery into our dialplan. Osaka is the username used in the incoming authentication.
We set the type to friend because we want to have both the ability to send calls to
Osaka and to receive calls from Osaka. The host option is set to dynamic which tells
Asterisk to send calls to the IP address obtained when the opposite endpoint registers
with us.
112 | Chapter 4: Initial Configuration of Asterisk
In the introduction to this section, we mentioned the possible bandwidth savings when
utilizing IAX2 trunking. It’s simple to enable this functionality in Asterisk, as we just
need to add trunk=yes to our friend definition. As long as a timing interface is installed
and running (i.e., dummy), then we can take advantage of IAX2 trunking.
The secret is straightforward: it’s our authentication password. We’re defining the
[incoming_osaka] context as the place we will process incoming calls for this friend in
the extensions.conf file. Finally, we block all IP addresses with the deny option from
being allowed to authenticate, and explicitly permit 192.168.1.107.
The iax.conf configuration for Osaka is nearly identical, except for the changes in IP
address and names:
[general]
autokill=yes
register => osaka:welcome@192.168.1.104
[toronto]
type=friend
host=dynamic
trunk=yes
secret=welcome
context=incoming_toronto
deny=0.0.0.0/0.0.0.0
permit=192.168.1.104/255.255.255.255
IAX Phone Configuration
In the “Configure the Softphone” section, we configured our first IAX2 softphone using
idefisk. The configuration we’ll be using here is nearly identical except for minor
changes in order to cause the peers to be unique. If you’ve already configured a SIP
softphone, then you can also utilize that on one (or both) of the peers. Remember that
Asterisk is a multiprotocol application, and you can send a call from a SIP phone to
Asterisk, across an IAX2 trunk, and then down to another SIP phone (or H.323, MGCP,
etc.).
On Osaka:
[1001]
type=friend
host=dynamic
context=phones
On Toronto:
[2001]
type=friend
host=dynamic
context=phones
Connecting Two Asterisk Boxes Together via IAX | 113
Next, configure your IAX2 softphone to register to Asterisk. If the phone successfully
registers, you’ll see something like:
*CLI> -- Registered IAX2 '1001' (UNAUTHENTICATED) at 192.168.1.104:4569
Configuring the Dialplan
In order to allow calling between our two Asterisk boxes over the IAX2 trunk, we need
to configure a simple dialplan. The following dialplan will send all extensions in the
1000 range (1000–1999) to Osaka, and all extensions in the 2000 range (2000–2999)
to Toronto. Our example is going to assume that you have configured a pair of IAX2
softphones, but feel free to utilize a SIP phone if you’ve already configured one (or two).
Just be aware that you’ll need to change the Dial() application to send the call to the
SIP phone via the SIP protocol instead of IAX2 (i.e. Dial(SIP/${EXTEN},30) instead of
Dial(IAX2/${EXTEN},30)).
The extensions.conf file on Toronto:
[globals]
[general]
autofallthrough=yes
[default]
[incoming_calls]
[phones]
include => internal
include => remote
[internal]
exten => _1XXX,1,NoOp()
exten => _1XXX,n,Dial(IAX2/${EXTEN},30)
exten => _1XXX,n,Playback(the-party-you-are-calling&is-curntly-unavail)
exten => _1XXX,n,Hangup()
[remote]
exten => _2XXX,1,NoOp()
exten => _2XXX,n,Dial(IAX2/toronto/${EXTEN})
exten => _2XXX,n,Hangup()
[toronto_incoming]
include => internal
The extensions.conf file on Osaka:
[globals]
[general]
autofallthrough=yes
[default]
114 | Chapter 4: Initial Configuration of Asterisk
[incoming_calls]
[phones]
include => internal
include => remote
[internal]
exten => _2XXX,1,NoOp()
exten => _2XXX,n,Dial(IAX2/${EXTEN},30)
exten => _2XXX,n,Playback(the-party-you-are-calling&is-curntly-unavail)
exten => _2XXX,n,Hangup()
[remote]
exten => _1XXX,1,NoOp()
exten => _1XXX,n,Dial(IAX2/osaka/${EXTEN})
exten => _1XXX,n,Hangup()
[osaka_incoming]
include => internal
Using Templates in Your Configuration Files
There is a little-known secret in Asterisk config files that is so brilliant that we had to
devote a little section to it.
Let us say that you have 20 SIP phones that are all pretty much identical in terms of
how they are configured. The documented way to create them is to specify the parameters
for each. Part of such a sip.conf file might look like this:
[1000]
type=friend
context=internal
host=dynamic
disallow=all
allow=ulaw
dtmfmode=rfc2833
maibox=1000
secret=AllYourSetsAreBelongToUs
[1001]
type=friend
context=internal
host=dynamic
disallow=all
allow=ulaw
dtmfmode=rfc2833
maibox=1001
secret=AllYourSetsAreBelongToUs
[1002]
type=friend
context=internal
host=dynamic
Using Templates in Your Configuration Files | 115
disallow=all
allow=ulaw
dtmfmode=rfc2833
maibox=1002
secret=AllYourSetsAreBelongToUs
Seems like a lot of extra typing, cutting, and pasting, yes? And what if you decide that
you are going to change the context for your sets to another name. Not looking good,
is it?
Enter the template. Let’s create the same SIP friends as we did above, only this time
using the template construct:
[sets](!) ; <== note the exclamation point in parenthesis. That makes this a template.
type=friend
context=internal
host=dynamic
disallow=all
allow=ulaw
dtmfmode=rfc2833
secret=AllYourSetsAreBelongToUs
[1000](sets) ; <== note the template name in parenthesis. All of that templates
; settings will be inhereted.
maibox=1000
[1001](sets)
maibox=1001
[1002](sets)
maibox=1002
This is one of the best kept secrets of conf file creation. In our experience, very few
people use this, but for no other reason than that they don’t know about it. Well, that’s
about to change. Our goal is to see everyone using these from now on; and yes, we will
be checking.
Debugging
Several methods of debugging are available in Asterisk. Once you’ve connected to the
console, you can enable different levels of verbosity and debugging output, as well as
protocol packet tracing. We’ll take a look at the various options in this section.
Connecting to the Console
To connect to the Asterisk console, you can either start the server in the console directly
(in which case you will not be able to exit out of the console without killing the Asterisk
process), or start Asterisk as a daemon and then connect to a remote console.
To start the Asterisk process directly in the console, use the console flag:
116 | Chapter 4: Initial Configuration of Asterisk
# /usr/sbin/asterisk -c
To connect to a remote Asterisk console, start the daemon first and then connect with
the -r flag:
# /usr/sbin/asterisk
# /usr/sbin/asterisk -r
If you are having a problem with a specific module not loading, or a module causing
Asterisk to not load, start the Asterisk process with the -c flag to monitor the status of
modules loading. For example, if you attempt to load the OSS channel driver (which
allows the use of the CONSOLE channel), and Asterisk is unable to open /dev/dsp, you will
receive the following error on startup:
WARNING[32174]: chan_oss.c:470 soundcard_init: Unable to open /dev/dsp:
No such file or directory
== No sound card detected -- console channel will be unavailable
== Turn off OSS support by adding 'noload=chan_oss.so' in /etc/
asterisk/modules.conf
Enabling Verbosity and Debugging
Asterisk can output debugging information in the form of WARNING, NOTICE, and ERROR
messages. These messages will give you information about your system, such as registrations,
status, and progression of calls, and various other useful bits of information.
Note that WARNING and NOTICE messages are not errors; however, ERROR messages should
be investigated. To enable various levels of verbosity, use set verbose followed by a
numerical value. Useful values range from 3 to 10. For example, to set the highest level
of verbosity, use:
# set verbose 10
You can also enable core debugging messages with set debug followed by a numerical
value. To enable DEBUG output on the console, you may need to enable it in the
logger.conf file by adding debug to the console => statement, as follows:
console => warning,notice,error,event,debug
Useful values for set debug range from 3 to 10. For example:
# set debug 10
Conclusion
If you've worked through all of the sections in this chapter, you will have configured a
pair of analog interfaces, a local SIP and IAX2 channel connected to a softphone and/
or a hardphone, and placed calls across servers using the SIP and IAX2 protocols. These
configurations are quite basic, but they give us functional channels to work with. We
will make use of them in the following chapters, while we learn to build more useful
dialplans.
Conclusion | 117

CHAPTER 5
Dialplan Basics
Everything should be made as simple as possible, but not
simpler.
—Albert Einstein (1879–1955)
The dialplan is truly the heart of any Asterisk system, as it defines how Asterisk handles
inbound and outbound calls. In a nutshell, it consists of a list of instructions or steps
that Asterisk will follow. Unlike traditional phone systems, Asterisk’s dialplan is fully
customizable. To successfully set up your own Asterisk system, you will need to understand
the dialplan.
If you have attempted to read some sample dialplans and found them overwhelming,
or if you’ve tried to write an Asterisk dialplan and had no success, help is at hand. This
chapter explains how dialplans work in a step-by-step manner and teaches the skills
necessary to create your own. The examples have been designed to build upon one
another, so feel free to go back and reread a section if something doesn’t quite make
sense. Please also note that this chapter is by no means an exhaustive survey of all the
possible things dialplans can do; our aim is to cover just the fundamentals. We’ll cover
more advanced dialplan topics in later chapters.
Dialplan Syntax
The Asterisk dialplan is specified in the configuration file named extensions.conf.
The extensions.conf file usually resides in the /etc/asterisk/ directory, but
its location may vary depending on how you installed Asterisk. Other
common locations for this file include /usr/local/asterisk/etc/
and /opt/asterisk/etc/.
The dialplan is made up of four main concepts: contexts, extensions, priorities, and
applications. In the next few sections, we’ll cover each of these parts and explain how
119
they work together. After explaining the role each of these elements plays in the
dialplan, we will step you though the process of creating a basic, functioning dialplan.
Sample Configuration Files
If you installed the sample configuration files when you installed Asterisk, you will most
likely have an existing extensions.conf file. Instead of starting with the sample file, we
suggest that you build your extensions.conf file from scratch. This will be very beneficial,
as it will give you a better understanding of dialplan concepts and fundamentals.
That being said, the sample extensions.conf file remains a fantastic resource, full of
examples and ideas that you can use after you’ve learned the basic concepts. We suggest
you rename the sample file to something like extensions.conf.sample. That way, you
can refer to it in the future. You can also find the sample configuration files in
the /configs/ directory of the Asterisk source.
Contexts
Dialplans are broken into sections called contexts. Contexts are named groups of extensions,
which serve several purposes.
Contexts keep different parts of the dialplan from interacting with one another. An
extension that is defined in one context is completely isolated from extensions in any
other context, unless interaction is specifically allowed. (We’ll cover how to allow interaction
between contexts near the end of the chapter.)
As a simple example, let’s imagine we have two companies sharing an Asterisk server.
If we place each company’s voice menu in its own context, they are effectively separated
from each other. This allows us to independently define what happens when, say, extension
0 is dialed: people pressing 0 at Company A’s voice menu will get Company
A’s receptionist, and callers pressing 0 at Company B’s voice menu will get Company
B’s receptionist. (This example assumes, of course, that we’ve told Asterisk to transfer
the calls to the receptionists when callers press 0.)
Contexts are denoted by placing the name of the context inside square brackets ([ ]).
The name can be made up of the letters A through Z (upper- and lowercase), the numbers
0 through 9, and the hyphen and underscore.* For example, a context for incoming
calls looks like this:
[incoming]
* Please note that the space is conspicuously absent from the list of allowed characters. Don’t use spaces in
your context names—you won’t like the result!
120 | Chapter 5: Dialplan Basics
Context names have a maximum length of 79 characters (80 characters
–1 terminating null)
All of the instructions placed after a context definition are part of that context, until
the next context is defined. At the beginning of the dialplan, there are two special
contexts named [general] and [globals]. The [general] section contains a list of general
dialplan settings (which you’ll probably never have to worry about), and we will
discuss the [globals] context the “Global variables” section; for now it’s just important
to know that these two contexts are special. As long as you avoid the names [gen
eral] and [globals], you may name your contexts anything you like.
When you define a channel (which is how you connect things to the system), one of
the parameters that is defined in the channel definition is the context. In other words,
the context is the point in the dialplan where connections from that channel will begin.
Another important use of contexts (perhaps the most important) is to provide security.
By using contexts correctly, you can give certain callers access to features (such as longdistance
calling) that aren’t made available to others. If you don’t design your dialplan
carefully, you may inadvertently allow others to fraudulently use your system. Please
keep this in mind as you build your Asterisk system.
The doc/ subdirectory of the Asterisk source code contains a very important
file named security.txt, which outlines several steps you should
take to keep your Asterisk system secure. It is vitally important that you
read and understand this file. If you ignore the security precautions
outlined there, you may end up allowing anyone and everyone to make
long-distance or toll calls at your expense!
If you don’t take the security of your Asterisk system seriously, you may
end up paying—literally! Please take the time and effort to secure your
system from toll fraud.
Extensions
In the world of telecommunications, the word extension usually refers to a numeric
identifier given to a line that rings a particular phone. In Asterisk, however, an extension
is far more powerful, as it defines a unique series of steps (each step containing an
application) that Asterisk will take that call through. Within each context, we can define
as many (or few) extensions as required. When a particular extension is triggered (by
an incoming call or by digits being dialed on a channel), Asterisk will follow the steps
defined for that extension. It is the extensions, therefore, that specify what happens to
calls as they make their way through the dialplan. Although extensions can certainly
be used to specify phone extensions in the traditional sense (i.e., extension 153 will
Dialplan Syntax | 121
cause the SIP telephone set on John’s desk to ring), in an Asterisk dialplan, they can be
used for much more.
The syntax for an extension is the word exten, followed by an arrow formed by the
equals sign and the greater-than sign, like this:
exten =>
This is followed by the name (or number) of the extension. When dealing with traditional
telephone systems, we tend to think of extensions as the numbers you would
dial to make another phone ring. In Asterisk, you get a whole lot more; for example,
extension names can be any combination of numbers and letters. Over the course of
this chapter and the next, we’ll use both numeric and alphanumeric extensions.
Assigning names to extensions may seem like a revolutionary concept,
but when you realize that many VoIP transports support (or even actively
encourage) dialing by name or email address instead of only
dialing by number, it makes perfect sense. This is one of the features
that makes Asterisk so flexible and powerful.
A complete extension is composed of three components:
• The name (or number) of the extension
• The priority (each extension can include multiple steps; the step number is called
the “priority”)
• The application (or command) that performs some action on the call
These three components are separated by commas, like this:
exten => name,priority,application()
Here’s a simple example of what a real extension might look like:
exten => 123,1,Answer()
In this example, the extension name is 123, the priority is 1, and the application is
Answer(). Now, let’s move ahead and explain priorities and applications.
Priorities
Each extension can have multiple steps, called priorities. Each priority is numbered
sequentially, starting with 1, and executes one specific application. As an example, the
following extension would answer the phone (in priority number 1), and then hang it
up (in priority number 2):
exten => 123,1,Answer()
exten => 123,2,Hangup()
122 | Chapter 5: Dialplan Basics
Don’t worry if you don’t understand what Answer() and Hangup() are—we’ll cover
them shortly. The key point to remember here is that for a particular extension, Asterisk
follows the priorities in order.
Unnumbered priorities
In older releases of Asterisk, the numbering of priorities caused a lot of problems.
Imagine having an extension that had 15 priorities, and then needing to add something
at step 2. All of the subsequent priorities would have to be manually renumbered.
Asterisk does not handle missing steps or misnumbered priorities, and debugging these
types of errors was pointless and frustrating.
Beginning with version 1.2, Asterisk addressed this problem. It introduced the use of
the n priority, which stands for “next.” Each time Asterisk encounters a priority named
n, it takes the number of the previous priority and adds 1. This makes it easier to make
changes to your dialplan, as you don’t have to keep renumbering all your steps. For
example, your dialplan might look something like this:
exten => 123,1,Answer()
exten => 123,n,do something
exten => 123,n,do something else
exten => 123,n,do one last thing
exten => 123,n,Hangup()
Internally, Asterisk will calculate the next priority number every time it encounters an
n.† You should note, however, that you must always specify priority number 1. If you
accidentally put an n instead of 1 for the first priority, you’ll find that the extension will
not be available.
Priority labels
Starting with Asterisk version 1.2 and higher, common practice is to assign text labels
to priorities. This is to ensure that you can refer to a priority by something other than
its number, which probably isn’t known, given that dialplans now generally use unnumbered
priorities. To assign a text label to a priority, simply add the label inside
parentheses after the priority, like this:
exten => 123,n(label),application()
A very common mistake when writing labels is to insert a comma between
the n and the (, like this:
exten => 123,n,(label),application() ;<-- THIS IS NOT GOING TO WORK
This mistake will break that part of your dialplan, and you will get an
error that the application cannot be found.
† Asterisk permits simple arithmetic within the priority, such as n+200 or the priority s (for same), but their
usage is considered to be an advanced topic. Please note that extension s and priority s are two distinct
concepts.
Dialplan Syntax | 123
In the next chapter, we’ll cover how to jump between different priorities based on
dialplan logic. You’ll be seeing a lot more of priority labels, and you will be using them
often in your dialplans.
Applications
Applications are the workhorses of the dialplan. Each application performs a specific
action on the current channel, such as playing a sound, accepting touch-tone input,
dialing a channel, hanging up the call, and so forth. In the previous example, you were
introduced to two simple applications: Answer() and Hangup(). You’ll learn more about
how these work momentarily.
Some applications, such as Answer()and Hangup(), need no other instructions to do their
jobs. Other applications require additional information. These pieces of information,
called arguments, can be passed on to the applications to affect how they perform their
actions. To pass arguments to an application, place them between the parentheses that
follow the application name, separated by commas.
Occasionally, you may also see the pipe character (|) being used as a
separator between arguments, instead of a comma. Feel free to use
whichever you prefer. For the examples in this book, we will be using
the comma to separate arguments to an application, as the authors prefer
the look of this syntax. You should be aware, however, that when
Asterisk parses the dialplan, it converts any commas in the application
arguments to pipes.
As we build our first dialplan in the next section, you’ll learn to use applications (and
their associated arguments) to your advantage.
A Simple Dialplan
Now we’re ready to create our first dialplan. We’ll start with a very simple example.
We are going to instruct Asterisk to answer a call, play a sound file, and hang up. We’ll
use this simple example to point out the most important dialplan fundamentals.
For the examples in this chapter to work correctly, we’re assuming that at least one
channel (either Zap, SIP, or IAX2) has been created and configured (as described in the
previous chapter), and that all calls coming into that channel enter the dialplan at the
[incoming] context. If you have been creative with any previous examples, you may
need to make adjustments to fit your particular channel names.
124 | Chapter 5: Dialplan Basics
The s Extension
Because of the technology we are using in our channels, we need to cover one more
thing before we get started with our dialplan. We need to explain extension s. When
calls enter a context without a specific destination extension (for example, a ringing
FXO line), they are passed to the s extension. (The s stands for “start,” as this is where
a call will start if no extension information was passed with the call.)
Since this is exactly what we need for our dialplan, let’s begin to fill in the pieces. We
will be performing three actions on the call (answer it, play a sound file, and hang it
up), so our extension called s will need three priorities. We’ll place the three priorities
below [incoming], because we have decided that all incoming calls should start in this
context.‡
[incoming]
exten => s,1,application()
exten => s,n,application()
exten => s,n,application()
Now all we need to do is fill in the applications, and we’ve created our first dialplan.
Note that we could have numbered each priority as shown below, but
this is no longer the preferred method, as it makes it harder to make
changes to the dialplan at a later time:
[incoming]
exten => s,1,application()
exten => s,2,application()
exten => s,3,application()
The Answer(), Playback(), and Hangup() Applications
If we’re going to answer the call, play a sound file, and then hang up, we’d better learn
how to do just that. The Answer() application is used to answer a channel that is ringing.
This does the initial setup for the channel that receives the incoming call. (A few applications
don’t require that you answer the channel first, but properly answering the
channel before performing any other actions is a very good habit.) As we mentioned
earlier, Answer() takes no arguments.
The Playback() application is used for playing a previously recorded sound file over a
channel. When using the Playback() application, input from the user is simply ignored.
‡ There is nothing special about any context name. We could have named this context
[stuff_that_comes_in], and as long as that was the context assigned in the channel definition in sip.conf,
iax.conf, zaptel.conf, et al., the channel would enter the dialplan in that context. Having said that, it is strongly
recommended that you give your contexts names that help you to understand their purpose. Some good
context names might include [incoming], [local_calls], [long_distance], [sip_telephones], [user_services],
[experimental], [remote_locations], and so forth. Always remember that a context determines how a channel
enters the dialplan, so name accordingly.
A Simple Dialplan | 125
Asterisk comes with many professionally recorded sound files, which
should be found in the default sounds directory (usually
/var/lib/asterisk/sounds/). When you compile Asterisk, you can choose
to install various sets of sample sounds that have been recorded in a
variety of languages and file formats. We’ll be using these files in many
of our examples. Several of the files in our examples come from the Extra
Sound Package, so please take the time to install it (see Chapter 3). You
can also have your own sound prompts recorded in the same voices as
the stock prompts by visiting http://thevoice.digium.com/.
To use Playback(), specify a filename (without a file extension) as the argument. For
example, Playback(filename) would play the sound file called filename.gsm, assuming
it was located in the default sounds directory. Note that you can include the full path
to the file if you want, like this:
Playback(/home/john/sounds/filename)
The previous example would play filename.gsm from the /home/john/sounds/ directory.
You can also use relative paths from the Asterisk sounds directory as follows:
Playback(custom/filename)
This example would play filename.gsm from the custom/ subdirectory of the default
sounds directory (probably /var/lib/asterisk/sounds/custom/filename.gsm). Note that if
the specified directory contains more than one file with that filename but with different
file extensions, Asterisk automatically plays the best file.§
The Hangup() application does exactly as its name implies: it hangs up the active channel.
You should use this application at the end of a context when you want to end the
current call to ensure that callers don’t continue on in the dialplan in a way you might
not have anticipated. The Hangup() application takes no arguments.
Our First Dialplan
Now that we have designed our extension, let’s put together all the pieces to create our
first dialplan. As is typical in many technology books (especially computer programming
books), our first example will be called “Hello World!”
In the first priority of our extension, we’ll answer the call. In the second, we’ll play a
sound file named hello-world.gsm, and in the third we’ll hang up the call. Here’s what
the dialplan looks like:
§ Asterisk selects the best file based on translation cost―that is, it selects the file that is the least CPU-intensive
to convert to its native audio format. When you start Asterisk, it calculates the translation costs between the
different audio formats (they often vary from system to system). You can see these translation costs by typing
show translation at the Asterisk command-line interface. The numbers shown represent how many
milliseconds it takes Asterisk to transcode one second of audio. We’ll cover more about the different audio
formats (known as codecs) in Chapter 8.
126 | Chapter 5: Dialplan Basics
[incoming]
exten => s,1,Answer()
exten => s,n,Playback(hello-world)
exten => s,n,Hangup()
If you have a channel or two configured, go ahead and try it out!‖ Simply create a file
called extensions.conf, (probably in /etc/asterisk) and insert the four lines of dialplan
code we just designed. If it doesn’t work, check the Asterisk console for error messages,
and make sure your channels are assigned to the [incoming] context.
Even though this example is very short and simple, it emphasizes the core concepts of
contexts, extensions, priorities, and applications. If you can get this to work, you have
the fundamental knowledge on which all dialplans are built.
Let’s build upon our example. After all, a phone system that simply plays a sound file
and then hangs up the channel isn’t that useful!
Building an Interactive Dialplan
The dialplan we just built was static; it will always perform the same actions on every
call. We are going to start adding some logic to our dialplan so that it will perform
different actions based on input from the user. To do this, we’re going to need to
introduce a few more applications.
The Background(), WaitExten(), and Goto() Applications
One of the most important keys to building interactive Asterisk dialplans is the Back
ground()# application. Like Playback(), it plays a recorded sound file. Unlike
Playback(), however, when the caller presses a key (or series of keys) on her telephone
keypad, it interrupts the playback and goes to the extension that corresponds with the
pressed digit(s). If a caller presses 5, for example, Asterisk will stop playing the sound
prompt and send control of the call to the first priority of extension 5.
The most common use of the Background() application is to create voice menus (often
called auto-attendants or phone trees). Many companies use voice menus to direct callers
to the proper extensions, thus relieving their receptionists from having to answer
every single call.
‖ In fact, if you don’t have any channels configured, now is the time to do so. There is a real satisfaction that
comes from passing your first call into an Asterisk system that you built from scratch. People get this funny
grin on their face as they realize that they have just created a telephone system. This pleasure can be yours
as well, so please, don’t go any further until you have made this little dialplan work.
# It should be noted that some people expect that Background(), due to its name, would continue in the dialplan
while the sound is being played, but its name refers to the fact that it is playing a sound in the background,
while waiting for DTMF in the foreground.
Building an Interactive Dialplan | 127
Background() has the same syntax as Playback():
exten => 123,1,Answer()
exten => 123,n,Background(main-menu)
In earlier versions of Asterisk, if the Background() application finished playing the sound
prompt and there were no more priorities in the current extension, Asterisk would sit
and wait for input from the caller. Asterisk no longer does this by default. If you want
Asterisk to wait for input from the caller after the sound prompt has finished playing,
you can call the WaitExten() application. The WaitExten() application waits for the
caller to enter DTMF digits, and is frequently called directly after the Background()
application, like this:
exten => 123,1,Answer()
exten => 123,n,Background(main-menu)
exten => 123,n,WaitExten()
If you’d like the WaitExten() application to wait a specific number of seconds for a
response (instead of using the default timeout), simply pass the number of seconds as
the first argument to WaitExten(), like this:
exten => 123,n,WaitExten(5)
Both Background() and WaitExten() allow the caller to enter DTMF digits. Asterisk then
attempts to find an extension in the current context that matches the digits that the
caller entered. If Asterisk finds an unambiguous match, it will send the call to that
extension. Let’s demonstrate by adding a few lines to our example:
exten => 123,1,Answer()
exten => 123,n,Background(main-menu)
exten => 123,n,WaitExten()
exten => 2,1,Playback(digits/2)
exten => 3,1,Playback(digits/3)
exten => 4,1,Playback(digits/4)
If you call into extension 123 in the example above, it will play a sound prompt that
says “main menu.” It will then wait for you to enter either 2, 3, or 4. If you press one
of those digits, Asterisk will read that digit back to you. You’ll also find that if you enter
a different digit (such as 5), it won’t give you what you expected.
It is also possible that Asterisk will find an ambiguous match. This can be easily explained
if we add an extension named 1 to the previous example:
exten => 123,1,Answer()
exten => 123,n,Background(main-menu)
exten => 123,n,WaitExten()
exten => 1,1,Playback(digits/1)
exten => 2,1,Playback(digits/2)
128 | Chapter 5: Dialplan Basics
exten => 3,1,Playback(digits/3)
exten => 4,1,Playback(digits/4)
Dial extension 123, and then at the main menu prompt dial 1. Why doesn’t Asterisk
immediately read back the number one to you? It’s because the digit 1 is ambiguous;
Asterisk doesn’t know whether you’re trying to go to extension 1 or extension 123. It
waits a few seconds to see if you’re going to dial another digit (such as the 2 in extension
123). If you don’t dial any more digits, Asterisk will eventually time out and send the
call to extension 1. (We’ll learn how to choose our own timeout values in Chapter 6.)
Before going on, let’s review what we’ve done so far. When users call into our dialplan,
they will hear a greeting. If they press 1, they will hear the number one, and if they press
2, they will hear the number two, and so on. While that’s a good start, let’s embellish
it a little. We’ll use the Goto() application to make the dialplan repeat the greeting after
playing back the number.
As its name implies, the Goto() application is used to send the call to another part of
the dialplan. The syntax for the Goto() application requires us to pass the destination
context, extension, and priority on as arguments to the application, like this:
exten => 123,n,Goto(context,extension,priority)
Now, let’s use the Goto() application in our dialplan:
[incoming]
exten => 123,1,Answer()
exten => 123,n,Background(main-menu)
exten => 1,1,Playback(digits/1)
exten => 1,n,Goto(incoming,123,1)
exten => 2,1,Playback(digits/2)
exten => 2,n,Goto(incoming,123,1)
These two new lines (highlighted in bold) will send control of the call back to the 123
extension after playing back the selected number.
If you look up the details of the Goto() application, you’ll find that you
can actually pass either one, two, or three arguments to the application.
If you pass a single argument, Asterisk will assume it’s the destination
priority in the current extension. If you pass two arguments, Asterisk
will treat them as the extension and priority to go to in the current
context.
In this example, we’ve passed all three arguments for the sake of clarity,
but passing just the extension and priority would have had the same
effect.
Building an Interactive Dialplan | 129
Handling Invalid Entries and Timeouts
Now that our first voice menu is starting to come together, let’s add some additional
special extensions. First, we need an extension for invalid entries; when a caller presses
an invalid entry (e.g., pressing 9 in the above example), the call is sent to the i extension.
Second, we need an extension to handle situations when the caller doesn’t give input
in time (the default timeout is 10 seconds). Calls will be sent to the t extension if the
caller takes too long to press a digit after WaitExten() has been called. Here is what our
dialplan will look like after we’ve added these two extensions:
[incoming]
exten => 123,1,Answer()
exten => 123,n,Background(enter-ext-of-person)
exten => 123,n,WaitExten()
exten => 1,1,Playback(digits/1)
exten => 1,n,Goto(incoming,123,1)
exten => 2,1,Playback(digits/2)
exten => 2,n,Goto(incoming,123,1)
exten => 3,1,Playback(digits/3)
exten => 3,n,Goto(incoming,123,1)
exten => i,1,Playback(pbx-invalid)
exten => i,n,Goto(incoming,123,1)
exten => t,1,Playback(vm-goodbye)
exten => t,n,Hangup()
Using the i and t extensions makes our dialplan a little more robust and user-friendly.
That being said, it is still quite limited, because outside callers have no way of connecting
to a live person. To do that, we’ll need to learn about another application, called
Dial().
Using the Dial() Application
One of Asterisk’s most valuable features is its ability to connect different callers to each
other. This is especially useful when callers are using different methods of communication.
For example, caller A might be communicating over the traditional analog
telephone network, while user B might be sitting in a café halfway around the world
and speaking on an IP telephone. Luckily, Asterisk takes most of the hard work out of
connecting and translating between disparate networks. All you have to do is learn how
to use the Dial() application.
The syntax of the Dial() application is a little more complex than that of the other
applications we’ve used so far, but don’t let that scare you off. Dial() takes up to four
arguments. The first is the destination you’re attempting to call, which (in its simplest
form) is made up of a technology (or transport) across which to make the call, a forward
130 | Chapter 5: Dialplan Basics
slash, and the remote endpoint or resource. Common technology types include Zap
(for analog and T1/E1/J1 channels), SIP, and IAX2. For example, let’s assume that we
want to call a Zap endpoint identified by Zap/1, which is an FXS channel with an analog
phone plugged into it. The technology is Zap, and the resource is 1. Similarly, a call to
a SIP device (as defined in sip.conf) might have a destination of SIP/Jane, and a call to
an IAX device (defined in iax.conf) might have a destination of IAX2/Fred. If we wanted
Asterisk to ring the Zap/1 channel when extension 123 is reached in the dialplan, we’d
add the following extension:
exten => 123,1,Dial(Zap/1)
We can also dial multiple channels at the same time, by concatenating the destinations
with an ampersand (&), like this:
exten => 123,1,Dial(Zap/1&Zap/2&SIP/Jane)
The Dial() application will ring the specified destinations simultaneously, and bridge
the inbound call with whichever destination channel answers the call first. If the Dial
() application can’t contact any of the destinations, Asterisk will set a variable called
DIALSTATUS with the reason that it couldn’t dial the destinations, and continue on with
the next priority in the extension.*
The Dial() application also allows you to connect to a remote VoIP endpoint not previously
defined in one of the channel configuration files. The full syntax for this type
of connection is:
Dial(technology/user[:password]@remote_host[:port][/remote_extension])
As an example, you can dial into a demonstration server at Digium using the IAX2
protocol by using the following extension:
exten => 500,1,Dial(IAX2/guest@misery.digium.com/s)
The full syntax for the Dial() application is slightly different when dealing with Zap
channels, as shown:
Dial(Zap/[gGrR]channel_or_group[/remote_extension])
For example, here is how you would dial 1-800-555-1212 on Zap channel number 4.
exten => 501,1,Dial(Zap/4/18005551212)
The second argument to the Dial() application is a timeout, specified in seconds. If a
timeout is given, Dial() will attempt to call the destination(s) for that number of seconds
before giving up and moving on to the next priority in the extension. If no timeout
is specified, Dial() will continue to dial the called channel(s) until someone answers
or the caller hangs up. Let’s add a timeout of 10 seconds to our extension:
exten => 123,1,Dial(Zap/1,10)
* Don’t worry, we’ll cover variables (in “Using Variables”) and show you how to have your dialplan make
decisions based on the value of this DIALSTATUS variable.
Building an Interactive Dialplan | 131
If the call is answered before the timeout, the channels are bridged and the dialplan is
done. If the destination simply does not answer, is busy, or is otherwise unavailable,
Asterisk will set a variable called DIALSTATUS and then continue on with the next priority
in the extension.
Let’s put what we’ve learned so far into another example:
exten => 123,1,Dial(Zap/1,10)
exten => 123,n,Playback(vm-nobodyavail)
exten => 123,n,Hangup()
As you can see, this example will play the vm-nobodyavail.gsm sound file if the call goes
unanswered.
The third argument to Dial() is an option string. It may contain one or more characters
that modify the behavior of the Dial() application. While the list of possible options
is too long to cover here, one of the most popular options is the m option. If you place
the letter m as the third argument, the calling party will hear hold music instead of
ringing while the destination channel is being called (assuming, of course, that music
on hold has been configured correctly). To add the m option to our last example, we
simply change the first line:
exten => 123,1,Dial(Zap/1,10,m)
exten => 123,n,Playback(vm-nobodyavail)
exten => 123,n,Hangup()
Since the extensions numbered 1 and 2 in our dialplan are somewhat useless now that
we know how to use the Dial() application, let’s replace them with new extensions
that will allow outside callers to reach John and Jane:
[incoming]
exten => 123,1,Answer()
exten => 123,n,Background(enter-ext-of-person)
exten => 123,n,WaitExten()
exten => 1,1,Dial(Zap/1,10)
exten => 1,n,Playback(vm-nobodyavail)
exten => 1,n,Hangup()
exten => 2,1,Dial(SIP/Jane,10)
exten => 2,n,Playback(vm-nobodyavail)
exten => 2,n,Hangup()
exten => i,1,Playback(pbx-invalid)
exten => i,n,Goto(incoming,123,1)
exten => t,1,Playback(vm-goodbye)
exten => t,n,Hangup()
The fourth and final argument to the Dial() application is a URL. If the destination
channel supports receiving a URL at the time of the call, the specified URL will be sent
(for example, if you have an IP telephone that supports receiving a URL, it will appear
132 | Chapter 5: Dialplan Basics
on the phone’s display; likewise, if you’re using a soft phone, the URL might pop up
on your computer screen). This argument is very rarely used.
Note that the second, third, and fourth arguments may be left blank. For example, if
you want to specify an option but not a timeout, simply leave the timeout argument
blank, like this:
exten => 1,1,Dial(Zap/1,,m)
Adding a Context for Internal Calls
In our examples thus far, we have limited ourselves to a single context, but it is probably
fair to assume that almost all Asterisk installations will have more than one context in
their dialplans. As we mentioned at the beginning of this chapter, one important function
of contexts is to separate privileges (such as making long-distance calls or calling
certain extensions) for different classes of callers. In our next example, we’ll add to our
dialplan by creating two internal phone extensions, and we’ll set up the ability for these
two extensions to call each other. To accomplish this, we’ll create a new context called
[employees].
As in previous examples, we’ve assumed that an FXS analog channel
(Zap/1, in this case) has already been configured, and that your
zapata.conf file is configured so that any calls originated by Zap/1 begin
in the [employees] context. For a few examples at the end of the chapter,
we’ll also assume that an FXO Zap channel has been configured as Zap/
4, with calls coming in on this channel being sent to the [incoming]
context.
We’ve also assumed you have at least one SIP channel (named SIP/
Jane) that is configured to originate in the [employees] context. We’ve
done this to introduce you to using other types of channels.
If you don’t have hardware for the channels listed above (such as Zap/
4), or if you’re using hardware with different channel names (e.g., not
SIP/Jane), just change the examples to match your particular system
configuration.
Our dialplan now looks like this:
[incoming]
exten => 123,1,Answer()
exten => 123,n,Background(enter-ext-of-person)
exten => 123,n,WaitExten()
exten => 1,1,Dial(Zap/1,10)
exten => 1,n,Playback(vm-nobodyavail)
exten => 1,n,Hangup()
exten => 2,1,Dial(SIP/Jane,10)
exten => 2,n,Playback(vm-nobodyavail)
Building an Interactive Dialplan | 133
exten => 2,n,Hangup()
exten => i,1,Playback(pbx-invalid)
exten => i,n,Goto(incoming,123,1)
exten => t,1,Playback(vm-goodbye)
exten => t,n,Hangup()
[employees]
exten => 101,1,Dial(Zap/1)
exten => 102,1,Dial(SIP/Jane)
In this example, we have added two new extensions to the [employees] context. This
way, the person using channel Zap/1 can pick up the phone and dial the person at
channel SIP/Jane by dialing 102. By that same token, the phone registered as SIP/
Jane can dial Zap/1 by dialing 101.
We’ve arbitrarily decided to use extensions 101 and 102 for our examples, but feel free
to use whatever numbering convention you wish for your extensions. You should also
be aware that you’re not limited to three-digit extensions; you can use as few or as many
digits as you like. (Well, almost. Extensions must be shorter than 80 characters long,
and you shouldn’t use single-character extensions for your own use, as they’re reserved.)
Don’t forget that you can use names as well, like so:
[incoming]
exten => 123,1,Answer()
exten => 123,n,Background(enter-ext-of-person)
exten => 123,n,WaitExten()
exten => 1,1,Dial(Zap/1,10)
exten => 1,n,Playback(vm-nobodyavail)
exten => 1,n,Hangup()
exten => 2,1,Dial(SIP/Jane,10)
exten => 2,n,Playback(vm-nobodyavail)
exten => 2,n,Hangup()
exten => i,1,Playback(pbx-invalid)
exten => i,n,Goto(incoming,123,1)
exten => t,1,Playback(vm-goodbye)
exten => t,n,Hangup()
[employees]
exten => 101,1,Dial(Zap/1)
exten => john,1,Dial(Zap/1)
exten => 102,1,Dial(SIP/Jane)
exten => jane,1,Dial(SIP/Jane)
It certainly wouldn’t hurt to add named extensions if you think your users might be
dialed via a VoIP protocol such as SIP that supports dialing by name. You can also see
134 | Chapter 5: Dialplan Basics
that it is possible to have different extensions in the dialplan ring the same endpoint.
For example, you could have extension 200 ring SIP/George, and then have extension
201 play a prompt of some kind and then ring SIP/George.
Now that our internal callers can call each other, we’re well on our way toward having
a complete dialplan. Next, we’ll see how we can make our dialplan more scalable and
easier to modify in the future.
Using Variables
Variables can be used in an Asterisk dialplan to help reduce typing, add clarity, or add
additional logic to a dialplan. If you have some computer programming experience,
you probably already understand what a variable is. If not, don’t worry; we’ll explain
what variables are and how they are used.
You can think of a variable as a container that can hold one value at a time. So, for
example, we might create a variable called JOHN and assign it the value of Zap/1. This
way, when we’re writing our dialplan, we can refer to John’s channel by name, instead
of remembering that John is using the channel named Zap/1.
There are two ways to reference a variable. To reference the variable’s name, simply
type the name of the variable, such as JOHN. If, on the other hand, you want to reference
its value, you must type a dollar sign, an opening curly brace, the name of the variable,
and a closing curly brace. Here’s how we’d reference the variable inside the Dial()
application:
exten => 555,1,Dial(${JOHN})
In our dialplan, whenever we write ${JOHN}, Asterisk will automatically replace it with
whatever value has been assigned to the variable named JOHN.
Note that variable names are case-sensitive. A variable named JOHN is
different than a variable named John. For readability’s sake, all the variable
names in the examples will be written in uppercase. You should
also be aware that any variables set by Asterisk will be uppercase as well.
Some variables, such as CHANNEL or EXTEN are reserved by Asterisk. You
should not attempt to set these variables.
There are three types of variables we can use in our dialplan: global variables, channel
variables, and environment variables. Let’s take a moment to look at each type.
Global variables
As their name implies, global variables apply to all extensions in all contexts. Global
variables are useful in that they can be used anywhere within a dialplan to increase
readability and manageability. Suppose for a moment that you had a large dialplan and
several hundred references to the Zap/1 channel. Now imagine you had to go through
Building an Interactive Dialplan | 135
your dialplan and change all of those references to Zap/2. It would be a long and errorprone
process, to say the least.
On the other hand, if you had defined a global variable with the value Zap/1 at the
beginning of your dialplan and then referenced that instead, you would have to change
only one line.
Global variables should be declared in the [globals] context at the beginning of the
extensions.conf file. They can also be defined programmatically, using the GLOBAL()
dialplan function.† Here is an example of how both methods look inside of a dialplan.
The first shows the setting of a global variable named JOHN with a value of Zap/1. This
variable is set at the time Asterisk parses the dialplan. The second example shows how
a global variable can be set in the dialplan. In this case, the variable named George is
being assigned the value of SIP/George when extension 124 is dialed in the [employees]
context:
[globals]
JOHN=Zap/1
[employees]
exten => 124,1,Set(GLOBAL(GEORGE)=SIP/George)
Channel variables
A channel variable is a variable that is associated only with a particular call. Unlike
global variables, channel variables are defined only for the duration of the current call
and are available only to the channels participating in that call.
There are many predefined channel variables available for use within the dialplan,
which are explained in the channelvariables.txt file in the doc subdirectory of the Asterisk
source. Channel variables are set via the Set() application:
exten => 125,1,Set(MAGICNUMBER=42)
We’ll cover many uses for channel variables in Chapter 6.
Environment variables
Environment variables are a way of accessing Unix environment variables from within
Asterisk. These are referenced using the ENV() dialplan function. The syntax looks like
${ENV(var)}, where var is the Unix environment variable you wish to reference. Environment
variables aren’t commonly used in Asterisk dialplans, but they are available
should you need them.
Adding variables to our dialplan
Now that we’ve learned about variables, let’s put them to work in our dialplan. We’ll
add global variables for two people, John and Jane:
† Don’t worry! We’ll cover dialplan functions in the “Dialplan Functions” section.
136 | Chapter 5: Dialplan Basics
[globals]
JOHN=Zap/1
JANE=SIP/Jane
[incoming]
exten => 123,1,Answer()
exten => 123,n,Background(enter-ext-of-person)
exten => 123,n,WaitExten()
exten => 1,1,Dial(${JOHN},10)
exten => 1,n,Playback(vm-nobodyavail)
exten => 1,n,Hangup()
exten => 2,1,Dial(${JANE},10)
exten => 2,n,Playback(vm-nobodyavail)
exten => 2,n,Hangup()
exten => i,1,Playback(pbx-invalid)
exten => i,n,Goto(incoming,123,1)
exten => t,1,Playback(vm-goodbye)
exten => t,n,Hangup()
[employees]
exten => 101,1,Dial(${JOHN})
exten => john,1,Dial(${JOHN})
exten => 102,1,Dial(${JANE})
exten => jane,1,Dial(${JANE})
Pattern Matching
If we want to be able to allow people to dial through Asterisk and have Asterisk connect
the caller to an outside resource, we need a way to match on any possible phone number
that the caller might dial. Can you imagine how tedious it would be to manually write
a dialplan with an extension for every possible number you could dial? Luckily, Asterisk
has just the thing for situations like this: pattern matching. Pattern matching allows you
to create one extension in your dialplan that matches many different numbers.
Pattern-matching syntax
When using pattern matching, certain letters and symbols represent what we are trying
to match. Patterns always start with an underscore (_). This tells Asterisk that we’re
matching on a pattern, and not on an explicit extension name. (This means, of course,
that you should never start your extension names with an underscore.)
If you forget the underscore on the front of your pattern, Asterisk will
think it’s just a named extension and won’t do any pattern matching.
This is one of the most common mistakes people make when starting
to learn Asterisk.
Building an Interactive Dialplan | 137
After the underscore, you can use one or more of the following characters.
X
Matches any single digit from 0 to 9.
Z
Matches any single digit from 1 to 9.
N
Matches any single digit from 2 to 9.
[15-7]
Matches a single digit from the range of digits specified. In this case, the pattern
matches a single 1, 5, 6, or 7.
. (period)
Wildcard match; matches one or more characters, no matter what they are.
If you’re not careful, wildcard matches can make your dialplans do
things you’re not expecting (like matching built-in extensions such
as i or h). You should use the wildcard match in a pattern only after
you’ve matched as many other digits as possible. For example, the
following pattern match should probably never be used:
_.
In fact, Asterisk will warn you if you try to use it. Instead, use this
one, if at all possible:
_X.
! (bang)
Wildcard match; matches zero or more characters, no matter what they are.
To use pattern matching in your dialplan, simply put the pattern in the place of the
extension name (or number):
exten => _NXX,1,Playback(auth-thankyou)
In this example, the pattern matches any three-digit extension from 200 through 999
(the N matches any digit between 2 and 9, and each X matches a digit between 0 and 9).
That is to say, if a caller dialed any three-digit extension between 200 and 999 in this
context, he would hear the sound file auth-thankyou.gsm.
One other important thing to know about pattern matching is that if Asterisk finds
more than one pattern that matches the dialed extension, it will use the most specific
one (going from left to right). Say you had defined the following two patterns, and a
caller dialed 555-1212:
exten => _555XXXX,1,Playback(digits/1)
exten => _55512XX,1,Playback(digits/2)
In this case the second extension would be selected, because it is more specific.
138 | Chapter 5: Dialplan Basics
Pattern-matching examples
Before we go on, let’s look at a few more pattern-matching examples. In each one, see
if you can tell what the pattern would match before reading the explanation. We’ll start
with an easy one:
_NXXXXXX
This pattern would match any seven-digit number, as long as the first digit was two or
higher. This pattern would be compatible with any North American Numbering Plan
local seven-digit number. In areas with 10-digit dialing, that pattern would look like
this:
_NXXNXXXXXX
Note that neither of these two patterns would handle long distance calls. We’ll cover
those shortly.
The NANP and Toll Fraud
The North American Number Plan (NANP) is a shared telephone numbering scheme
used by 19 countries in North America and the Caribbean. Countries within NANP
share country code 1.
In the United States and Canada, telecom regulations are similar (and sensible) enough
that you can place a long-distance call to most numbers in country code 1 and expect
to pay a reasonable toll. What many people don’t realize, however, is that 19 countries,
many of which have very different telecom regulations, share the NANP. (More information
can be found at http://www.nanpa.com.)
One popular scam using the NANP tries to trick naive North Americans into calling
expensive per-minute toll numbers in a Caribbean country; the callers believe that since
they dialed 1-NPA-NXX-XXXX to reach the number, they’ll be paying their standard
national long-distance rate for the call. Since the country in question may have regulations
that allow for this form of extortion, the caller is ultimately held responsible for
the call charges.
The only way to prevent this sort of activity is to block calls to certain area codes (809,
for example) and remove the restrictions only on an as-needed basis.
Let’s try another:
_1NXXNXXXXXX
This one is slightly more difficult. This would match the number 1, followed by an area
code between 200 and 999, then any 7-digit number. In the NANP calling area, you
would use this pattern to match any long-distance number.‡
Now for an even trickier example:
_011.
Building an Interactive Dialplan | 139
If that one left you scratching your head, look at it again. Did you notice the period on
the end? This pattern matches any number that starts with 011 and has at least one
more digit. In the NANP, this indicates an international phone number. (We’ll be using
these patterns in the next section to add outbound dialing capabilities to our dialplan.)
Using the ${EXTEN} channel variable
We know what you’re thinking… You’re sitting there asking yourself, “So what happens
if I want to use pattern matching, but I need to know which digits were actually dialed?”
Luckily, Asterisk has just the answer. Whenever you dial an extension, Asterisk sets
the ${EXTEN} channel variable to the digits that were dialed. We can use an application
called SayDigits() to test it out:
exten => _XXX,1,SayDigits(${EXTEN})
In this example, the SayDigits() application will read back to you the three-digit extension
you dialed.
Often, it’s useful to manipulate the ${EXTEN} by stripping a certain number of digits off
the front of the extension. This is accomplished by using the syntax ${EXTEN:x}, where
x is where you want the returned string to start, from left to right. For example, if the
value of EXTEN is 95551212, ${EXTEN:1} equals 5551212. Let’s take a look at another
example:
exten => _XXX,1,SayDigits(${EXTEN:1})
In this example, the SayDigits() application would start at the second digit, and thus
read back only the last two digits of the dialed extension.
More Advanced Digit Manipulation
The ${EXTEN} variable properly has the syntax ${EXTEN:x:y}, where x is the starting
position, and y is the number of digits to return. Given the following dial string:
94169671111
we can extract the following digit strings using the ${EXTEN:x:y} construct:
${EXTEN:1:3} would contain 416.
${EXTEN:4:7} would contain 9671111.
${EXTEN:-4:4} would start four digits from the end, and return four digits, giving us
1111.
‡ If you grew up in North America, you may believe that the 1 you dial before a long distance call is “the long
distance code.” This is incorrect. The number 1 is in fact the international country code for all countries in
NANP. Keep this in mind if you ever send your phone number to someone in another country. They may
not know what your country code is, and thus be unable to call you with just your area code and phone
number. Your full phone number with country code should be printed as +1 NPA NXX XXXX (where NPA
is your area code)―e.g., +1 416 555 1212.
140 | Chapter 5: Dialplan Basics
${EXTEN:1} would give us everything after the first digit, 4169671111 (if the number of
digits to return is left blank, it will return the entire remaining string).
This is a very powerful construct, but most of these variations are not very common in
normal use. For the most part, you will be using ${EXTEN:1} to strip off your external
access code.
Enabling Outbound Dialing
Now that we’ve introduced pattern matching, we can go about the process of allowing
users to make outbound calls. The first thing we’ll do is add a variable to the
[globals] context to define which channel will be used for outbound calls:
[globals]
JOHN=Zap/1
JANE=SIP/Jane
OUTBOUNDTRUNK=Zap/4
Next, we will add contexts to our dialplan for outbound dialing.
You may be asking yourself at this point, “Why do we need separate contexts for outbound
calls?” This is so that we can regulate and control which callers have permission
to make outbound calls, and which types of outbound calls they are allowed to make.
To begin, let’s create a context for local calls. To be consistent with most traditional
phone switches, we’ll put a 9 on the front of our patterns, so that users have to dial 9
before calling an outside number:
[outbound-local]
exten => _9NXXXXXX,1,Dial(${OUTBOUNDTRUNK}/${EXTEN:1})
exten => _9NXXXXXX,n,Congestion()
exten => _9NXXXXXX,n,Hangup()
Note that dialing 9 doesn’t actually give you an outside line, unlike with
many traditional PBX systems. Once you dial 9 on an analog line, the
dial tone will stop. If you’d like the dial tone to continue even after
dialing 9, add the following line (right after your context definition):
ignorepat => 9
This directive tells Asterisk to continue to provide a dial tone on an
analog line, even after the caller has dialed the indicated pattern. This
will not work with VoIP telephones, as they usually don’t send digits to
the system as they are input; they are sent to Asterisk all at once. Luckily,
most of the popular VoIP telephones can be configured to emulate the
same functionality.
Let’s review what we’ve just done. We’ve added a global variable called OUTBOUND
TRUNK, which simply defines the channel we are using for outbound calls.§ We’ve also
added a context for local outbound calls. In priority 1, we take the dialed extension,
Building an Interactive Dialplan | 141
strip off the 9 with the ${EXTEN:1} syntax, and then attempt to dial that number on the
channel signified by the variable OUTBOUNDTRUNK. If the call is successful, the caller is
bridged with the outbound channel. If the call is unsuccessful (because either the channel
is busy or the number can’t be dialed for some reason), the Congestion() application
is called, which plays a “fast busy signal” (congestion tone) to let the caller know that
the call was unsuccessful.
Before we go any further, let’s make sure our dialplan allows outbound emergency
numbers:
[outbound-local]
exten => _9NXXXXXX,1,Dial(${OUTBOUNDTRUNK}/${EXTEN:1})
exten => _9NXXXXXX,n,Congestion()
exten => _9NXXXXXX,n,Hangup()
exten => 911,1,Dial(${OUTBOUNDTRUNK}/911)
exten => 9911,1,Dial(${OUTBOUNDTRUNK}/911) ; So that folks who dial “9”
; first will also get through
Again, we’re assuming for the sake of these examples that we’re inside the United States
or Canada. If you’re outside of this area, please replace 911 with the emergency services
number in your particular location. This is something you never want to forget to put
in your dialplan!
Next, let’s add a context for long-distance calls:
[outbound-long-distance]
exten => _91NXXNXXXXXX,1,Dial(${OUTBOUNDTRUNK}/${EXTEN:1})
exten => _91NXXNXXXXXX,n,Playtones(congestion)
exten => _91NXXNXXXXXX,n,Hangup()
Now that we have these two new contexts, how do we allow internal users to take
advantage of them? We need a way for contexts to be able to use the functionality
contained in other contexts.
Includes
Asterisk has a feature that enables us to use the extensions from one context within
another context via the include directive. This is used to control access to different
sections of the dialplan. We’ll use the include functionality to allow users in our
[employees] context the ability to make outbound phone calls. But first, let’s cover the
syntax.
The include statement takes the following form, where context is the name of the
remote context we want to include in the current context:
include => context
§ The advantage of this is that if one day we decide to send all of our calls through some other channel, we
have to edit the channel name assigned to the variable OUTBOUNDTRUNK only in the [globals] context, instead
of having to manually edit every reference to the channel in our dialplan.
142 | Chapter 5: Dialplan Basics
When we include other contexts within our current context, we have to be mindful of
the order in which we are including them. Asterisk will first try to match the dialed
extension in the current context. If unsuccessful, it will then try the first included context
(including any contexts included in that context), and then continue to the other
included contexts in the order in which they were included.
As it sits, our current dialplan has two contexts for outbound calls, but there’s no way
for people in the [employees] context to use them. Let’s remedy that by including the
two outbound contexts in the [employees] context, like this:
[globals]
JOHN=Zap/1
JANE=SIP/Jane
OUTBOUNDTRUNK=Zap/4
[incoming]
exten => 123,1,Answer()
exten => 123,n,Background(enter-ext-of-person)
exten => 123,n,WaitExten()
exten => 1,1,Dial(${JOHN},10)
exten => 1,n,Playback(vm-nobodyavail)
exten => 1,n,Hangup()
exten => 2,1,Dial(${JANE},10)
exten => 2,n,Playback(vm-nobodyavail)
exten => 2,n,Hangup()
exten => i,1,Playback(pbx-invalid)
exten => i,n,Goto(incoming,123,1)
exten => t,1,Playback(vm-goodbye)
exten => t,n,Hangup()
[employees]
include => outbound-local
include => outbound-long-distance
exten => 101,1,Dial(${JOHN})
exten => john,1,Dial(${JOHN})
exten => 102,1,Dial(${JANE})
exten => jane,1,Dial(${JANE})
[outbound-local]
exten => _9NXXXXXX,1,Dial(${OUTBOUNDTRUNK}/${EXTEN:1})
exten => _9NXXXXXX,n,Congestion()
exten => _9NXXXXXX,n,Hangup()
exten => 911,1,Dial(${OUTBOUNDTRUNK}/911)
exten => 9911,1,Dial(${OUTBOUNDTRUNK}/911)
[outbound-long-distance]
exten => _91NXXNXXXXXX,1,Dial(${OUTBOUNDTRUNK}/${EXTEN:1})
Building an Interactive Dialplan | 143
exten => _91NXXNXXXXXX,n,Playtones(congestion)
exten => _91NXXNXXXXXX,n,Hangup()
These two include statements make it possible for callers in the [employees] context
to make outbound calls. We should also note that for security’s sake you should always
make sure that your [inbound] context never allows outbound dialing. (If by chance it
did, people could dial into your system and then make outbound toll calls that would
be charged to you!)
Conclusion
And there you have it—a basic but functional dialplan. It’s not exactly fully featured,
but we’ve covered all of the fundamentals. In the following chapters, we’ll continue to
add features to this foundation.
If parts of this dialplan don’t make sense, you may want to go back and re-read a section
or two before continuing on to the next chapter. It’s imperative that you understand
these principles and how to apply them, as the next chapters build on this information.
144 | Chapter 5: Dialplan Basics
CHAPTER 6
More Dialplan Concepts
For a list of all the ways technology has failed to improve
the quality of life, please press three.
—Alice Kahn
Alrighty. You’ve got the basics of dialplans down, but you know there’s more to come.
If you don’t have the last chapter sorted out yet, please go back and give it another read.
We’re about to get into more advanced topics.
Expressions and Variable Manipulation
As we begin our dive into the deeper aspects of dialplans, it is time to introduce you to
a few tools that will greatly add to the power you can exercise in your dialplan. These
constructs add incredible intelligence to your dialplan by enabling it to make decisions
based on different criteria you want to define. Put on your thinking cap, and let’s get
started.
Basic Expressions
Expressions are combinations of variables, operators, and values that you string together
to produce a result. An expression can test values, alter strings, or perform
mathematical calculations. Let’s say we have a variable called COUNT. In plain English,
two expressions using that variable might be “COUNT plus 1” and “COUNT divided by 2.”
Each of these expressions has a particular result or value, depending on the value of
the given variable.
In Asterisk, expressions always begin with a dollar sign and an opening square bracket
and end with a closing square bracket, as shown here:
$[expression]
Thus, we would write the above two examples like this:
$[${COUNT} + 1]
$[${COUNT} / 2]
145
When Asterisk encounters an expression in a dialplan, it replaces the entire expression
with the resulting value. It is important to note that this takes place after variable substitution.
To demonstrate, let’s look at the following code:*
exten => 321,1,Set(COUNT=3)
exten => 321,n,Set(NEWCOUNT=$[${COUNT} + 1])
exten => 321,n,SayNumber(${NEWCOUNT})
In the first priority, we assign the value of 3 to the variable named COUNT.
In the second priority, only one application—Set()—is involved, but three things actually
happen:
1. Asterisk substitutes ${COUNT} with the number 3 in the expression. The expression
effectively becomes this:
exten => 321,n,Set(NEWCOUNT=$[3 + 1])
2. Asterisk evaluates the expression, adding 1 to 3, and replaces it with its computed
value of 4:
exten => 321,n,Set(NEWCOUNT=4)
3. The value 4 is assigned to the NEWCOUNT variable by the Set() application.
The third priority simply invokes the SayNumber() application, which speaks the current
value of the variable ${NEWCOUNT} (set to the value 4 in priority two).
Try it out in your own dialplan.
Operators
When you create an Asterisk dialplan, you’re really writing code in a specialized scripting
language. This means that the Asterisk dialplan—like any programming language
—recognizes symbols called operators that allow you to manipulate variables. Let’s
look at the types of operators that are available in Asterisk:
Boolean operators
These operators evaluate the “truth” of a statement. In computing terms, that essentially
refers to whether the statement is something or nothing (nonzero or zero,
true or false, on or off, and so on). The Boolean operators are:
expr1 | expr2
This operator (called the “or” operator, or “pipe”) returns the evaluation of
expr1 if it is true (neither an empty string nor zero). Otherwise, it returns the
evaluation of expr2.
* Remember that when you reference a variable you can call it by its name, but when you refer to a variable’s
value, you have to use the dollar sign and brackets around the variable name.
146 | Chapter 6: More Dialplan Concepts
expr1 & expr2
This operator (called “and”) returns the evaluation of expr1 if both expressions
are true (i.e., neither expression evaluates to an empty string or zero). Otherwise,
it returns zero.
expr1 {=, >, >=, <, <=, !=} expr2
These operators return the results of an integer comparison if both arguments
are integers; otherwise, they return the results of a string comparison. The
result of each comparison is 1 if the specified relation is true, or 0 if the relation
is false. (If you are doing string comparisons, they will be done in a manner
that’s consistent with the current local settings of your operating system.)
Mathematical operators
Want to perform a calculation? You’ll want one of these:
expr1 {+, -} expr2
These operators return the results of the addition or subtraction of integervalued
arguments.
expr1 {*, /, %} expr2
These return, respectively, the results of the multiplication, integer division,
or remainder of integer-valued arguments.
Regular expression operator
You can also use the regular expression operator in Asterisk:
expr1 : expr2
This operator matches expr1 against expr2, where expr2 must be a regular
expression.† The regular expression is anchored to the beginning of the string
with an implicit ^.‡
If the match succeeds and the pattern contains at least one regular expression
subexpression—\( ... \)—the string corresponding to \1 is returned; otherwise,
the matching operator returns the number of characters matched. If the
match fails and the pattern contains a regular expression subexpression, the
null string is returned; otherwise, 0 is returned.
In Asterisk version 1.0 the parser was quite simple, so it required that you put at least
one space between the operator and any other values. Consequently, the following
might not have worked as expected:
exten => 123,1,Set(TEST=$[2+1])
† For more on regular expressions, grab a copy of the ultimate reference, Jeffrey E.F. Friedl’s
Mastering Regular Expressions (O’Reilly) or visit http://www.regular-expressions.info.
‡ If you don’t know what a ^ has to do with regular expressions, you simply must obtain a copy of
Mastering Regular Expressions. It will change your life!
Expressions and Variable Manipulation | 147
This would have assigned the variable TEST to the string “2+1”, instead of the value 3.
In order to remedy that, we would put spaces around the operator like so:
exten => 234,1,Set(TEST=$[2 + 1])
This is no longer necessary in Asterisk 1.2 or 1.4 as the expression parser has been made
more forgiving in these types of scenarios, however, for readability’s sake, we still recommend
the spaces around your operators.
To concatenate text onto the beginning or end of a variable, simply place them together
in an expression, like this:
exten => 234,1,Set(NEWTEST=$[blah${TEST}])
Dialplan Functions
Dialplan functions allow you to add more power to your expressions; you can think of
them as intelligent variables. Dialplan functions allow you to calculate string lengths,
dates and times, MD5 checksums, and so on, all from within a dialplan expression.
Syntax
Dialplan functions have the following basic syntax:
FUNCTION_NAME(argument)
Much like variables, you reference a function’s name as above, but you reference a
function’s value with the addition of a dollar sign, an opening curly brace, and a closing
curly brace:
${FUNCTION_NAME(argument)}
Functions can also encapsulate other functions, like so:
${FUNCTION_NAME(${FUNCTION_NAME(argument)})}
^ ^ ^ ^ ^^^^
1 2 3 4 4321
As you’ve probably already figured out, you must be very careful about making sure
you have matching parentheses and braces. In the above example, we have labeled the
opening parentheses and curly braces with numbers and their corresponding closing
counterparts with the same numbers.
Examples of Dialplan Functions
Functions are often used in conjunction with the Set() application to either get or set
the value of a variable. As a simple example, let’s look at the LEN() function. This
function calculates the string length of its argument. Let’s calculate the string length of
a variable and read back the length to the caller:
148 | Chapter 6: More Dialplan Concepts
exten => 123,1,Set(TEST=example)
exten => 123,n,SayNumber(${LEN(${TEST})})
The above example would evaluate the string example as having seven characters, assign
the number of characters to the variable length, and then speak the number to the user
with the SayNumber() application.
Let’s look at another simple example. If we wanted to set one of the various channel
timeouts, we could use the TIMEOUT() function. The TIMEOUT() function accepts one of
three arguments: absolute, digit, and response. To set the digit timeout with the
TIMEOUT() function, we could use the Set() application, like so:
exten => s,1,Set(TIMEOUT(digit)=30)
Notice the lack of ${ } surrounding the function. Just as if we were assigning a value
to a variable, we assign a value to a function without the use of the ${ } encapsulation.
A complete list of available functions can be found by typing core show functions at
the Asterisk command-line interface. You can also look them up in Appendix F.
Conditional Branching
Now that you’ve learned a bit about expressions and functions, it’s time to put them
to use. By using expressions and functions, you can add even more advanced logic to
your dialplan. To allow your dialplan to make decisions, you’ll use
conditional branching. Let’s take a closer look.
The GotoIf() Application
The key to conditional branching is the GotoIf() application. GotoIf() evaluates an
expression and sends the caller to a specific destination based on whether the expression
evaluates to true or false.
GotoIf() uses a special syntax, often called the conditional syntax:
GotoIf(expression?destination1:destination2)
If the expression evaluates to true, the caller is sent to destination1. If the expression
evaluates to false, the caller is sent to the second destination. So, what is true and what
is false? An empty string and the number 0 evaluate as false. Anything else evaluates as
true.
The destinations can each be one of the following:
• A priority label within the same extension, such as weasels
• An extension and a priority label within the same context, such as 123,weasels
• A context, extension, and priority label, such as incoming,123,weasels
Conditional Branching | 149
Either of the destinations may be omitted, but not both. If the omitted destination is
to be followed, Asterisk simply goes on to the next priority in the current extension.
Let’s use GotoIf() in an example:
exten => 345,1,Set(TEST=1)
exten => 345,n,GotoIf($[${TEST} = 1]?weasels:iguanas)
exten => 345,n(weasels),Playback(weasels-eaten-phonesys)
exten => 345,n,Hangup()
exten => 345,n(iguanas),Playback(office-iguanas)
exten => 345,n,Hangup()
You will notice that we have used the Hangup() application following
each Playback() application. This is done so that when we jump to the
weasels label, the call stops before execution gets to the officeiguanas
sound file. It is becoming increasingly common to see extensions
broken up in to multiple components (protected from each other
by the Hangup() command), each one acting as steps executed following
a GotoIf().
Providing Only a False Conditional Path
If we wanted to, we could have crafted the preceding example like this:
exten => 345,1,Set(TEST=1)
exten => 345,n,GotoIf($[${TEST} = 1]?:iguanas) ; we don't have the weasels label anymore,
; but this will still work
exten => 345,n,Playback(weasels-eaten-phonesys)
exten => 345,n,Hangup()
exten => 345,n(iguanas),Playback(office-iguanas)
exten => 345,n,Hangup()
There is nothing between the ? and the :, so if the statement evaluates to true, execution
of the dialplan will continue at the next step. Since that is what we want, a label is not
needed.
We don’t really recommend doing this, because this is hard to read, but you will see
dialplans like this, so it’s good to be aware that this syntax is totally correct.
Typically when you have this type of layout where you end up wanting to limit Asterisk
from falling through to the next priority after you’ve performed that jump, it’s probably
better to jump to separate extensions instead of priority labels. If anything, it makes it
a bit more clear when reading the dialplan. We could rewrite the previous bit of dialplan
like this:
exten => 345,1,Set(TEST=1)
exten => 345,n,GotoIf($[${TEST} = 1]?weasels,1:iguanas,1); now we're going to
; extension,priority
exten => weasels,1,Playback(weasels-eaten-phonesys); this is NOT a label.
; It is a different extension
exten => weasels,n,Hangup()
150 | Chapter 6: More Dialplan Concepts
exten => iguanas,1,Playback(office-iguanas)
exten => iguanas,n,Hangup()
By changing the value assigned to TEST in the first line, you should be able to have your
Asterisk server play a different greeting.
Let’s look at another example of conditional branching. This time, we’ll use both
Goto() and GotoIf() to count down from 10 and then hang up:
exten => 123,1,Set(COUNT=10)
exten => 123,n(start),GotoIf($[${COUNT} > 0]?:goodbye)
exten => 123,n,SayNumber(${COUNT})
exten => 123,n,Set(COUNT=$[${COUNT} - 1])
exten => 123,n,Goto(start)
exten => 123,n(goodbye),Hangup()
Let’s analyze this example. In the first priority, we set the variable COUNT to 10. Next,
we check to see if COUNT is greater than 0. If it is, we move on to the next priority. (Don’t
forget that if we omit a destination in the GotoIf() application, control goes to the next
priority.) From there we speak the number, subtract 1 from COUNT, and go back to
priority label start. If COUNT is less than or equal to 0, control goes to priority label
goodbye, and the call is hung up.
The classic example of conditional branching is affectionately known as the anti-girlfriend
logic. If the Caller ID number of the incoming call matches the phone number
of the recipient’s ex-girlfriend, Asterisk gives a different message than it ordinarily
would to any other caller. While somewhat simple and primitive, it’s a good example
for learning about conditional branching within the Asterisk dialplan.
This example uses the CALLERID function, which allows us to retrieve the Caller ID
information on the inbound call. Let’s assume for the sake of this example that the
victim’s phone number is 888-555-1212:
exten => 123,1,GotoIf($[${CALLERID(num)} = 8885551212]?reject:allow)
exten => 123,n(allow),Dial(Zap/4)
exten => 123,n,Hangup()
exten => 123,n(reject),Playback(abandon-all-hope)
exten => 123,n,Hangup()
In priority 1, we call the GotoIf() application. It tells Asterisk to go to priority label
reject if the Caller ID number matches 8885551212, and otherwise to go to priority label
allow (we could have simply omitted the label name, causing the GotoIf() to fall
through). If the Caller ID number matches, control of the call goes to priority label
reject, which plays back an uninspiring message to the undesired caller. Otherwise,
the call attempts to dial the recipient on channel Zap/4.
Time-Based Conditional Branching with GotoIfTime()
Another way to use conditional branching in your dialplan is with the GotoIfTime()
application. Whereas GotoIf() evaluates an expression to decide what to do, GotoIf
Conditional Branching | 151
Time() looks at the current system time and uses that to decide whether or not to follow
a different branch in the dialplan.
The most obvious use of this application is to give your callers a different greeting before
and after normal business hours.
The syntax for the GotoIfTime() application looks like this:
GotoIfTime(times,days_of_week,days_of_month,months?label)
In short, GotoIfTime() sends the call to the specified label if the current date and time
match the criteria specified by times, days_of_week, days_of_month, and months. Let’s
look at each argument in more detail:
times
This is a list of one or more time ranges, in a 24-hour format. As an example, 9:00
A.M. through 5:00 P.M. would be specified as 09:00-17:00. The day starts at 0:00
and ends at 23:59.
It is worth noting that times will properly wrap around. So if you
wish to specify the times your office is closed, you might write
18:00-9:00 in the times parameter, and it will perform as expected.
Note that this technique works as well for the other components
of GotoIfTime. For example, you can write sat-sun to specify the
weekend days.
days_of_week
This is a list of one or more days of the week. The days should be specified as mon,
tue, wed, thu, fri, sat, and/or sun. Monday through Friday would be expressed as
mon-fri. Tuesday and Thursday would be expressed as tue&thu.
Note that you can specify a combination of ranges and single days,
as in: sun-mon&wed&fri-sat, or, more simply: wed&fri-mon.
days_of_month
This is a list of the numerical days of the month. Days are specified by the numbers
1 through 31. The 7th through the 12th would be expressed as 7-12, and the 15th
and 30th of the month would be written as 15&30.
months
This is a list of one or more months of the year. The months should be written as
jan-apr for a range, and separated with ampersands when wanting to include nonsequencial
months, such as jan&mar&jun. You can also combine them like so:
jan-apr&jun&oct-dec.
152 | Chapter 6: More Dialplan Concepts
If you wish to match on all possible values for any of these arguments, simply put an
* in for that argument.
The label argument can be any of the following:
• A priority label within the same extension, such as time_has_passed
• An extension and a priority within the same context, such as 123,time_has_passed
• A context, extension, and priority, such as incoming,123,time_has_passed
Now that we’ve covered the syntax, let’s look at a couple of examples. The following
example would match from 9:00 A.M. to 5:59 P.M., on Monday through Friday, on
any day of the month, in any month of the year:
exten => s,1,GotoIfTime(09:00-17:59,mon-fri,*,*?open,s,1)
If the caller calls during these hours, the call will be sent to the first priority of the s
extension in the context named open. If the call is made outside of the specified times,
it will be sent to the next priority of the current extension. This allows you to easily
branch on multiple times, as shown in the next example (note that you should always
put your most specific time matches before the least specific ones):
; If it's any hour of the day, on any day of the week,
; during the fourth day of the month, in the month of July,
; we're closed
exten => s,1,GotoIfTime(*,*,4,jul?open,s,1)
; During business hours, send calls to the open context
exten => s,n,GotoIfTime(09:00-17:59|mon-fri|*|*?open,s,1)
exten => s,n,GotoIfTime(09:00-11:59|sat|*|*?open,s,1)
; Otherwise, we're closed
exten => s,n,Goto(closed,s,1)
If you run into the situation where you ask the question, “But I specified
17:58 and it’s now 17:59. Why is it still doing the same thing?” it should
be noted that the granularity of the GotoIfTime() application is only to
a two-minute period. So if you specify 18:00 as the ending time of a
period, the system will continue to perform the same way for an additional
minute, until 18:01:59.
Voicemail
One of the most popular (or, arguably, unpopular) features of any modern telephone
system is voicemail. Naturally, Asterisk has a reasonably flexible voicemail system.
Some of the features of Asterisk’s voicemail system include:
• Unlimited password-protected voicemail boxes, each containing mailbox folders
for organizing voicemail
• Different greetings for busy and unavailable states
Voicemail | 153
• Default and custom greetings
• The ability to associate phones with more than one mailbox and mailboxes with
more than one phone
• Email notification of voicemail, with the voicemail optionally attached as a sound
file§
• Voicemail forwarding and broadcasts
• Message-waiting indicator (flashing light or stuttered dial tone) on many types of
phones
• Company directory of employees, based on voicemail boxes
And that’s just the tip of the iceberg! In this section, we’ll introduce you to the fundamentals
of a typical voicemail setup.
The voicemail configuration is defined in the configuration file called voicemail.conf.
This file contains an assortment of settings that you can use to customize the voicemail
system to your needs. Covering all of the available options in voicemail.conf would be
beyond the scope of this chapter, but the sample configuration file is well documented
and quite easy to follow. For now, look near the bottom of the file, where voicemail
contexts and voicemail boxes are defined.
Just as dialplan contexts keep different parts of your dialplan separate, voicemail contexts
allow you to define different sets of mailboxes that are separate from one another.
This allows you to host voicemail for several different companies or offices on the same
server. Voicemail contexts are defined in the same way as dialplan contexts, with square
brackets surrounding the name of the context. For our examples, we’ll be using the
[default] voicemail context.
Creating Mailboxes
Inside each voicemail context, we define different mailboxes. The syntax for defining
a mailbox is:
mailbox => password,name[,email[,pager_email[,options]]]
Let’s explain what each part of the mailbox definition does:
mailbox
This is the mailbox number. It usually corresponds with the extension number of
the associated set.
password
This is the numeric password that the mailbox owner will use to access her voicemail.
If the user changes her password, the system will update this field in the
voicemail.conf file.
§ No, you really don’t have to pay for this—and yes, it really does work.
154 | Chapter 6: More Dialplan Concepts
name
This is the name of the mailbox owner. The company directory uses the text in this
field to allow callers to spell usernames.
email
This is the email address of the mailbox owner. Asterisk can send voicemail notifications
(including the voicemail message itself) to the specified email box.
pager_email
This is the email address of the mailbox owner’s pager or cell phone. Asterisk can
send a short voicemail notification message to the specified email address.
options
This field is a list of options that sets the mailbox owner’s time zone and overrides
the global voicemail settings. There are nine valid options: attach, serveremail, tz,
saycid, review, operator, callback, dialout, and exitcontext. These options
should be in option = value pairs, separated by the pipe character (|). The tz option
sets the user’s time zone to a time zone previously defined in the [zonemes
sages] section of voicemail.conf, and the other eight options override the global
voicemail settings with the same names.
A typical mailbox definition might look something like this:
101 => 1234,Joe Public,jpublic@somedomain.com,jpublic@pagergateway.net,
tz=central|attach=yes
Continuing with our dialplan from the last chapter, let’s set up voicemail boxes for
John and Jane. We’ll give John a password of 1234 and Jane a password of 4444 (remember,
these go in voicemail.conf, not in extensions.conf):
[default]
101 => 1234,John Doe,john@asteriskdocs.org,jdoe@pagergateway.tld
102 => 4444,Jane Doe,jane@asteriskdocs.org,jane@pagergateway.tld
Adding Voicemail to the Dialplan
Now that we’ve created mailboxes for Jane and John, let’s allow callers to leave messages
for them if they don’t answer the phone. To do this, we’ll use the VoiceMail()
application.
The VoiceMail() application sends the caller to the specified mailbox, so that he can
leave a message. The mailbox should be specified as mailbox @ context, where context
is the name of the voicemail context. The option letters b or u can be added to
request the type of greeting. If the letter b is used, the caller will hear the mailbox owner’s
busy message. If the letter u is used, the caller will hear the mailbox owner’s
unavailable message (if one exists).
Let’s use this in our sample dialplan. Previously, we had a line like this in our
[internal] context, which allowed us to call John:
exten => 101,1,Dial(${JOHN})
Voicemail | 155
Next, let’s add an unavailable message that the caller will be played if John doesn’t
answer the phone within 10 seconds. Remember, the second argument to the Dial()
application is a timeout. If the call is not answered before the timeout expires, the call
is sent to the next priority. Let’s add a 10-second timeout, and a priority to send the
caller to voicemail if John doesn’t answer in time:
exten => 101,1,Dial(${JOHN},10)
exten => 101,n,VoiceMail(101@default,u)
Now, let’s change it so that if John is busy (on another call), it’ll send us to his voicemail,
where we’ll hear his busy message. To do this, we will make use of the ${DIALSTATUS}
variable which contains one of several status values (see core show application dial
at the Asterisk console for a listing of all the possible values):
exten => 101,1,Dial(${JOHN},10)
exten => 101,n,GotoIf($["${DIALSTATUS}" = "BUSY"]?busy:unavail)
exten => 101,n(unavail),Voicemail(101@default,u)
exten => 101,n,Hangup()
exten => 101,n(busy),VoiceMail(101@default,b)
exten => 101,n,Hangup()
Now callers will get John’s voicemail (with the appropriate greeting) if John is either
busy or unavailable. A slight problem remains, however, in that John has no way of
retrieving his messages. Let’s remedy that.
Accessing Voicemail
Users can retrieve their voicemail messages, change their voicemail options, and record
their voicemail greetings by using the VoiceMailMain() application. In its typical form,
VoiceMailMain() is called without any arguments. Let’s add extension 700 to the
[internal] context of our dialplan so that internal users can dial it to access their voicemail
messages:
exten => 700,1,VoiceMailMain()
Creating a Dial-by-Name Directory
One last feature of the Asterisk voicemail system we should cover is the dial-by-name
directory. This is created with the Directory() application. This application uses the
names defined in the mailboxes in voicemail.conf to present the caller with a dial-byname
directory of the users.
Directory() takes up to three arguments: the voicemail context from which to read the
names, the optional dialplan context in which to dial the user, and an option string
(which is also optional). By default, Directory() searches for the user by last name, but
passing the f option forces it to search by first name instead. Let’s add two dial-byname
directories to the [incoming] context of our sample dialplan, so that callers can
search by either first or last name:
156 | Chapter 6: More Dialplan Concepts
exten => 8,1,Directory(default,incoming,f)
exten => 9,1,Directory(default,incoming)
If callers press 8, they’ll get a directory by first name. If they dial 9, they’ll get the
directory by last name.
Macros
Macros‖ are a very useful construct designed to avoid repetition in the dialplan. They
also help in making changes to the dialplan. To illustrate this point, let’s look at our
sample dialplan again. If you remember the changes we made for voicemail, we ended
up with the following for John’s extension:
exten => 101,1,Dial(${JOHN},10)
exten => 101,n,GotoIf($["${DIALSTATUS}" = "BUSY"]?busy:unavail)
exten => 101,n(unavail),Voicemail(101@default,u)
exten => 101,n,Hangup()
exten => 101,n(busy),VoiceMail(101@default,b)
exten => 101,n,Hangup()
Now imagine you have a hundred users on your Asterisk system—setting up the extensions
would involve a lot of copying and pasting. Then imagine that you need to
make a change to the way your extensions work. That would involve a lot of editing,
and you’d be almost certain to have errors.
Instead, you can define a macro that contains a list of steps to take, and then have all
of the phone extensions refer to that macro. All you need to change is the macro, and
everything in the dialplan that references that macro will change as well.
If you’re familiar with computer programming, you’ll recognize that
macros are similar to subroutines in many modern programming languages.
If you’re not familiar with computer programming, don’t worry
—we’ll walk you through creating a macro.
The best way to appreciate macros is to see one in action, so let’s move right along.
‖ Although Macro seems like a general-purpose dialplan subroutine, it has a stack overflow problem that means
you should not try to nest Macro calls more than five levels deep. As of this writing, we do not know whether
the Macro application will be patched for 1.4, or if it will be rewritten for future versions. If you plan to do a
lot of macros within macros (and call complex functions within them), you may run into stability problems.
You will know you have a problem with just one test call, so if your dialplan tests out, you’re good to go. We
also recommend that you take a look at the Gosub and Return applications, as a lot of macro functionality can
be implemented without actually using Macro(). Also, please note that we are not suggesting that you don’t
use Macro(). It is fantastic and works very well; it just doesn’t nest efficiently.
Macros | 157
Defining Macros
Let’s take the dialplan logic we used above to set up voicemail for John and turn it into
a macro. Then we’ll use the macro to give John and Jane (and the rest of their coworkers)
the same functionality.
Macro definitions look a lot like contexts. (In fact, you could argue that they really are
small, limited contexts.) You define a macro by placing macro- and the name of your
macro in square brackets, like this:
[macro-voicemail]
Macro names must start with macro-. This distinguishes them from regular contexts.
The commands within the macro are built almost identically to anything else in the
dialplan; the only limiting factor is that macros use only the s extension. Let’s add our
voicemail logic to the macro, changing the extension to s as we go:
[macro-voicemail]
exten => s,1,Dial(${JOHN},10)
exten => s,n,GotoIf($["${DIALSTATUS}" = "BUSY"]?busy:unavail)
exten => s,n(unavail),Voicemail(101@default,u)
exten => s,n,Hangup()
exten => s,n(busy),VoiceMail(101@default,b)
exten => s,n,Hangup()
That’s a start, but it’s not perfect, as it’s still specific to John and his mailbox number.
To make the macro generic so that it will work not only for John but also for all of his
coworkers, we’ll take advantage of another property of macros: arguments. But first,
let’s see how we call macros in our dialplan.
Calling Macros from the Dialplan
To use a macro in our dialplan, we use the Macro() application. This application calls
the specified macro and passes it any arguments. For example, to call our voicemail
macro from our dialplan, we can do the following:
exten => 101,1,Macro(voicemail)
The Macro() application also defines several special variables for our use. They include:
${MACRO_CONTEXT}
The original context in which the macro was called.
${MACRO_EXTEN}
The original extension in which the macro was called.
${MACRO_PRIORITY}
The original priority in which the macro was called.
${ARG n }
The nth argument passed to the macro. For example, the first argument would be
${ARG1}, the second ${ARG2}, and so on.
158 | Chapter 6: More Dialplan Concepts
As we explained earlier, the way we initially defined our macro was hardcoded for John,
instead of being generic. Let’s change our macro to use ${MACRO_EXTEN} instead of 101
for the mailbox number. That way, if we call the macro from extension 101 the voicemail
messages will go to mailbox 101, and if we call the macro from extension 102
messages will go to mailbox 102, and so on:
[macro-voicemail]
exten => s,1,Dial(${JOHN},10)
exten => s,n,GotoIf($["${DIALSTATUS}" = "BUSY"]?busy:unavail)
exten => s,n(unavail),Voicemail(${MACRO_EXTEN}@default,u)
exten => s,n,Hangup()
exten => s,n(busy),VoiceMail(${MACRO_EXTEN}@default,b)
exten => s,n,Hangup()
Using Arguments in Macros
Okay, now we’re getting closer to having the macro the way we want it, but we still
have one thing left to change; we need to pass in the channel to dial, as it’s currently
still hardcoded for ${JOHN} (remember that we defined the variable JOHN as the channel
to call when we want to reach John). Let’s pass in the channel as an argument, and
then our first macro will be complete:
[macro-voicemail]
exten => s,1,Dial(${ARG1},10)
exten => s,n,GotoIf($["${DIALSTATUS}" = "BUSY"]?busy:unavail)
exten => s,n(unavail),Voicemail(${MCARO_EXTEN}@default,u)
exten => s,n,Hangup()
exten => s,n(busy),VoiceMail(${MCARO_EXTEN}@default,b)
exten => s,n,Hangup()
Now that our macro is done, we can use it in our dialplan. Here’s how we can call our
macro to provide voicemail to John, Jane, and Jack:
exten => 101,1,Macro(voicemail,${JOHN})
exten => 102,1,Macro(voicemail,${JANE})
exten => 103,1,Macro(voicemail,${JACK})
With 50 or more users, this dialplan will still look neat and organized; we’ll simply
have one line per user, referencing a macro that can be as complicated as required. We
could even have a few different macros for various user types, such as executives,
courtesy_phones, call_center_agents, analog_sets, sales_department, and so on.
A more advanced version of the macro might look something like this:
[macro-voicemail]
exten => s,1,Dial(${ARG1},20)
exten => s,n,Goto(s-${DIALSTATUS},1)
exten => s-NOANSWER,1,Voicemail(${MACRO_EXTEN},u)
exten => s-NOANSWER,n,Goto(incoming,s,1)
exten => s-BUSY,1,Voicemail(${MACRO_EXTEN},b)
exten => s-BUSY,n,Goto(incoming,s,1)
exten => _s-.,1,Goto(s-NOANSWER,1)
Macros | 159
This macro depends on a nice side effect of the Dial() application: when you use the
Dial() application, it sets the DIALSTATUS variable to indicate whether the call was successful
or not. In this case, we’re handling the NOANSWER and BUSY cases, and treating all
other result codes as a NOANSWER.
Using the Asterisk Database (AstDB)
Having fun yet? It gets even better!
Asterisk provides a powerful mechanism for storing values called the Asterisk database
(AstDB). The AstDB provides a simple way to store data for use within your dialplan.
For those of you with experience using relational databases such as
PostgreSQL or MySQL, the Asterisk database is not a traditional relational
database. It is a Berkeley DB Version 1 database. There are several
ways to store data from Asterisk in a relational database. Check out
Chapter 12 for a more about relational databases.
The Asterisk database stores its data in groupings called families, with values identified
by keys. Within a family, a key may be used only once. For example, if we had a family
called test, we could store only one value with a key called count. Each stored value
must be associated with a family.
Storing Data in the AstDB
To store a new value in the Asterisk database, we use the Set() application,# but instead
of using it to set a channel variable, we use it to set an AstDB variable. For example, to
assign the count key in the test family with the value of 1, write the following:
exten => 456,1,Set(DB(test/count)=1)
If a key named count already exists in the test family, its value will be overwritten with
the new value. You can also store values from the Asterisk command line, by running
the command database put family key value. For our example, you would type data
base put test count 1.
Retrieving Data from the AstDB
To retrieve a value from the Asterisk database and assign it to a variable, we use the
Set() application again. Let’s retrieve the value of count (again, from the test family),
assign it to a variable called COUNT, and then speak the value to the caller:
# Previous versions of Asterisk had applications called DBput() and DBget() that were used to set values in and
retrieve values from the AstDB. If you’re using an old version of Asterisk, you’ll want to use those applications
instead.
160 | Chapter 6: More Dialplan Concepts
exten => 456,1,Set(DB(test/count)=1)
exten => 456,n,Set(COUNT=${DB(test/count)})
exten => 456,n,SayNumber(${COUNT})
You may also check the value of a given key from the Asterisk command line by running
the command database get family key. To view the entire contents of the AstDB, use
the database show command.
Deleting Data from the AstDB
There are two ways to delete data from the Asterisk database. To delete a key, you can
use the DB_DELETE() application. It takes the path to the key as its arguments, like this:
; deletes the key and returns its value in one step
exten => 457,1,Verbose(0, The value was ${DB_DELETE(test/count)})
You can also delete an entire key family by using the DBdeltree() application. The
DBdeltree() application takes a single argument―the name of the key family―to delete.
To delete the entire test family, do the following:
exten => 457,1,DBdeltree(test)
To delete keys and key families from the AstDB via the command-line interface, use
the database del key and database deltree family commands, respectively.
Using the AstDB in the Dialplan
There are an infinite number of ways to use the Asterisk database in a dialplan. To
introduce the AstDB, we’ll show two simple examples. The first is a simple counting
example to show that the Asterisk database is persistent (meaning that it survives system
reboots). In the second example, we’ll use the BLACKLIST() function to evaluate
whether or not a number is on the blacklist and should be blocked.
To begin the counting example, let’s first retrieve a number (the value of the count key)
from the database and assign it to a variable named COUNT. If the key doesn’t exist, DB
() will return NULL (no value). In order to verify if a value exists in the database or
not, we will introduce the ISNULL() function that will verify whether a value was returned,
and if not, we will initialize the AstDB with the Set() application, where we
will set the value in the database to 1. The next priority will send us back to priority 1.
This will happen the very first time we dial this extension:
exten => 678,1,Set(COUNT=${DB(test/count)})
exten => 678,n,GotoIf($[${ISNULL(${COUNT})}]?:continue)
exten => 678,n,Set(DB(test/count)=1)
exten => 678,n,Goto(1)
exten => 678,n(continue),NoOp()
Next, we’ll say the current value of COUNT, and then increment COUNT:
exten => 678,1,Set(COUNT=${DB(test/count)})
exten => 678,n,GotoIf($[${ISNULL(${COUNT})}]?:continue)
Using the Asterisk Database (AstDB) | 161
exten => 678,n,Set(DB(test/count)=1)
exten => 678,n,Goto(1)
exten => 678,n(continue),NoOp()
exten => 678,n,SayNumber(${COUNT})
exten => 678,n,Set(COUNT=$[${COUNT} + 1])
Now that we’ve incremented COUNT, let’s put the new value back into the database.
Remember that storing a value for an existing key overwrites the previous value:
exten => 678,1,Set(COUNT=${DB(test/count)})
exten => 678,n,GotoIf($[${ISNULL(${COUNT})}]?:continue)
exten => 678,n,Set(DB(test/count)=1)
exten => 678,n,Goto(1)
exten => 678,n(continue),NoOp()
exten => 678,n,SayNumber(${COUNT})
exten => 678,n,Set(COUNT=$[${COUNT} + 1])
exten => 678,n,Set(DB(test/count)=${COUNT})
Finally, we’ll loop back to the first priority. This way, the application will continue
counting:
exten => 678,1,Set(COUNT=${DB(test/count)})
exten => 678,n,GotoIf($[${ISNULL(${COUNT})}]?:continue)
exten => 678,n,Set(DB(test/count)=1)
exten => 678,n,Goto(1)
exten => 678,n(continue),NoOp()
exten => 678,n,SayNumber(${COUNT})
exten => 678,n,Set(COUNT=$[${COUNT} + 1]
exten => 678,n,Set(DB(test/count)=${COUNT})
exten => 678,n,Goto(1)
Go ahead and try this example. Listen to it count for a while, and then hang up. When
you dial this extension again, it should continue counting from where it left off. The
value stored in the database will be persistent, even across a restart of Asterisk.
In the next example, we’ll create dialplan logic around the BLACKLIST() function, which
checks to see if the current Caller ID number exists in the blacklist. (The blacklist is
simply a family called blacklist in the AstDB.) If BLACKLIST() finds the number in the
blacklist, it returns the value 1, otherwise it will return 0. We can use these values in
combination with a GotoIf() to control whether the call will execute the Dial()
application:
exten => 124,1,GotoIf($[${BLACKLIST()]?blocked,1)
exten => 124,n,Dial(${JOHN})
exten => blocked,1,Playback(privacy-you-are-blacklisted)
exten => blocked,n,Playback(vm-goodbye)
exten => blocked,n,Hangup()
To add a number to the blacklist, run the database put blacklist number 1 command
from the Asterisk command-line interface.
162 | Chapter 6: More Dialplan Concepts
Handy Asterisk Features
Now that we’ve gone over some more of the basics, let’s look at a few popular functions
that have been incorporated into Asterisk.
Zapateller()
Zapateller() is a simple Asterisk application that plays a special information tone at
the beginning of a call, which causes auto-dialers (usually used by telemarketers) to
think that the line has been disconnected. Not only will they hang up, but their systems
will flag your number as out of service, which could help you avoid all kinds of telemarketing
calls. To use this functionality within your dialplan, simply call the
Zapateller() application.
We’ll also use the optional nocallerid option so that the tone will be played only when
there is no Caller ID information on the incoming call. For example, you might use
Zapateller() in the s extension of your [incoming] context, like this:
[incomimg]
exten => s,1,Zapateller(nocallerid)
exten => s,n,Playback(enter-ext-of-person)
Call Parking
Another handy feature is called call parking. Call parking allows you to place a call on
hold in a “parking lot,” so that it can be taken off hold from another extension. Parameters
for call parking (such as the extensions to use, the number of spaces, and so
on) are all controlled within the features.conf configuration file. The [general] section
of the features.conf file contains four settings related to call parking:
parkext
This is the parking lot extension. Transfer a call to this extension, and the system
will tell you which parking position the call is in. By default, the parking extension
is 700.
parkpos
This option defines the number of parking slots. For example, setting it to
701-720 creates 20 parking positions, numbered 701 through 720.
context
This is the name of the parking context. To be able to park calls, you must include
this context.
parkingtime
If set, this option controls how long (in seconds) a call can stay in the parking lot.
If the call isn’t picked up within the specified time, the extension that parked the
call will be called back.
Handy Asterisk Features | 163
You must restart Asterisk after editing features.conf, as the file is read
only on startup. Running the reload command will not cause the
features.conf file to be read.
Also note that because the user needs to be able to transfer the calls to the parking lot
extension, you should make sure you’re using the t and/or T options to the Dial()
application.
So, let’s create a simple dialplan to show off call parking:
[incoming]
include => parkedcalls
exten => 103,1,Dial(SIP/Bob,,tT)
exten => 104,1,Dial(SIP/Charlie,,tT)
To illustrate how call parking works, say that Alice calls into the system and dials
extension 103 to reach Bob. After a while, Bob transfers the call to extension 700, which
tells him that the call from Alice has been parked in position 701. Bob then dials Charlie
at extension 104, and tells him that Alice is at extension 701. Charlie then dials extension
701 and begins to talk to Alice. This is a simple and effective way of allowing callers
to be transferred between users.
The t and T arguments to Dial() are not needed on all channel types.
For example, many SIP phones implement this via a softkey or hardkey
and utilize SIP signaling.
Conferencing with MeetMe()
Last but not least, let’s cover setting up an audio conference bridge with the MeetMe()
application.* This application allows multiple callers to converse together, as if they
were all in the same physical location. Some of the main features include:
• The ability to create password-protected conferences
• Conference administration (mute conference, lock conference, kick participants)
• The option of muting all but one participant (useful for company announcements,
broadcasts, etc.)
• Static or dynamic conference creation
Let’s walk through setting up a basic conference room. The configuration options for
the MeetMe conferencing system are found in meetme.conf. Inside the configuration
file, you define conference rooms and optional numeric passwords. (If a password is
* In the world of legacy PBXes, this type of functionality is very expensive. Either you have to pay big bucks
for a dial-in service, or you have to add an expensive conferencing bridge to your proprietary PBX.
164 | Chapter 6: More Dialplan Concepts
defined here, it will be required to enter all conferences using that room.) For our
example, let’s set up a conference room at extension 600. First, we’ll set up the conference
room in meetme.conf. We’ll call it 600, and we won’t assign a password at this
time:
[rooms]
conf => 600
Now that the configuration file is complete, we’ll need to restart Asterisk so that it can
reread the meetme.conf file. Next, we’ll add support for the conference room to our
dialplan with the MeetMe() application. MeetMe() takes three arguments: the name of
the conference room (as defined in meetme.conf), a set of options, and the password
the user must enter to join this conference. Let’s set up a simple conference using room
600, the i option (which announces when people enter and exit the conference), and a
password of 54321:
exten => 600,1,MeetMe(600,i,54321)
That’s all there is to it! When callers enter extension 600, they will be prompted for the
password. If they correctly enter 54321, they will be added to the conference. See Appendix
B for a list of all the options supported by the MeetMe() application.
Another useful application is MeetMeCount(). As its name suggests, this application
counts the number of users in a particular conference room. It takes up to two
arguments: the conference room in which to count the number of participants, and
optionally a variable name to assign the count to. If the variable name is not passed as
the second argument, the count is read to the caller:
exten => 601,1,Playback(conf-thereare)
exten => 601,n,MeetMeCount(600)
exten => 601,n,Playback(conf-peopleinconf)
If you pass a variable as the second argument to MeetMeCount(), the count is assigned
to the variable, and playback of the count is skipped. You might use this to limit the
number of participants, like this:
; limit the conference room to 10 participants
exten => 600,1,MeetMeCount(600,CONFCOUNT)
exten => 600,n,GotoIf($[${CONFCOUNT} <= 10]?meetme:conf_full,1)
exten => 600,n(meetme),MeetMe(600,i,54321)
exten => conf_full,1,Playback(conf-full)
Isn’t Asterisk fun?
Conclusion
In this chapter, we’ve covered a few more of the many applications in the Asterisk
dialplan, and hopefully we’ve given you the seeds from which you can explore the
creation of your own dialplans. As with the previous chapter, we invite you to go back
and reread any sections that require clarification.
Conclusion | 165
The following chapters take us away from Asterisk for a bit, in order to talk about some
of the technologies that all telephone systems use. We’ll be referring to Asterisk a lot,
but much of what we want to discuss are things that are common to many telecom
systems.
166 | Chapter 6: More Dialplan Concepts
CHAPTER 7
Understanding Telephony
Utility is when you have one telephone, luxury is when
you have two, opulence is when you have three—and
paradise is when you have none.
—Doug Larson
We’re now going to take a break from Asterisk for a chapter or two, because we want
to spend some time discussing the technologies with which your Asterisk system will
need to interface. In this chapter, we are going to talk about some of the technologies
of the traditional telephone network—especially those that people most commonly
want to connect to Asterisk. (We’ll discuss Voice over IP in the next chapter.)
While tomes could be written about the technologies in use in telecom networks, the
material in this chapter was chosen based on our experiences in the community, which
helped us to define the specific items that might be most useful. Although this knowledge
may not be strictly required in order to configure your Asterisk system, it will be
of great benefit when interconnecting to systems (and talking with people) from the
world of traditional telecommunications.
Analog Telephony
The purpose of the Public Switched Telephone Network (PSTN) is to establish and
maintain audio connections between two endpoints in order to carry speech.
Although humans can perceive sound vibrations in the range of 20–20,000 Hz,* most
of the sounds we make when speaking tend to be in the range of 250–3,000 Hz. Since
the purpose of the telephone network is to transmit the sounds of people speaking, it
* If you want to play around with what different frequencies look like on an oscilloscope, grab a copy of Sound
Frequency Analyzer, from Reliable Software. It’s a really simple and fun way to visualize what sounds “look”
like. The spectrograph gives a good picture of the complex harmonics our voices can generate, as well as an
appreciation for the background sounds that always surround us. You should also try the delightfully
annoying NCH Tone Generator, from NCH Swift Sound.
167
was designed with a bandwidth of somewhere in the range of 300–3,500 Hz. This
limited bandwidth means that some sound quality will be lost (as anyone who’s had
to listen to music on hold can attest to), especially in the higher frequencies.
Parts of an Analog Telephone
An analog phone is composed of five parts: the ringer, the dial pad, the hybrid (or
network), and the hook switch and handset (both of which are considered parts of the
hybrid). The ringer, the dial pad, and the hybrid can operate completely independently
of one another.
Ringer
When the central office (CO) wants to signal an incoming call, it will connect an alternating
current (AC) signal of roughly 90 volts to your circuit. This will cause the bell
in your telephone to produce a ringing sound. (In electronic telephones, this ringer may
be a small electronic warbler rather than a bell. Ultimately, a ringer can be anything
that is capable of reacting to the ringing voltage; for example, strobe lights are often
employed in noisy environments such as factories.)
Ringing voltage can be hazardous. Be very careful to take precautions
when working with an in-service telephone line.
Many people confuse the AC voltage that triggers the ringer with the direct current
(DC) voltage that powers the phone. Remember that a ringer needs an alternating current
in order to oscillate (just as a church bell won’t ring if you don’t supply the
movement), and you’ve got it.
In North America, the number of ringers you can connect to your line is dependent on
the Ringer Equivalence Number (REN) of your various devices. (The REN must be
listed on each device.) The total REN for all devices connected to your line cannot
exceed 5.0. An REN of 1.0 is equivalent to an old-fashioned analog set with an electromechanical
ringer. Some electronic phones have an REN of 0.3 or even less. If you
connect too many devices that require too much current, you will find that none of
them will be able to ring.
Dial pad
When you place a telephone call, you need some way of letting the network know the
address of the party you wish to reach. The dial pad is the portion of the phone that
provides this functionality. In the early days of the PSTN, dial pads were in fact rotary
devices that used pulses to indicate digits. This was a rather slow process, so the telephone
companies eventually introduced touch-tone dialing. With touch-tone—also
168 | Chapter 7: Understanding Telephony
known as Dual-Tone Multi Frequency (DTMF)—dialing, the dial pad consists of 12
buttons. Each button has two frequencies assigned to it (see Table 7-1).
Table 7-1. DTMF digits
1209 Hz 1336 Hz 1477 Hz 1633 Hz a
697 Hz 1 2 3 A
770 Hz 4 5 6 B
852 Hz 7 8 9 C
941 Hz * 0 # D
a Notice that this column contains letters that are not typically present as keys on a telephone dial pad. They are part of the DTMF standard
nonetheless, and any proper telephone contains the electronics required to create them, even if it doesn’t contain the buttons themselves.
(These buttons actually do exist on some telephones, which are mostly used in military and government applications.)
When you press a button on your dial pad, the two corresponding frequencies are
transmitted down the line. The far end can interpret these frequencies and note which
digit was pressed.
Hybrid (or network)
The hybrid is a type of transformer that handles the need to combine the signals transmitted
and received across a single pair of wires in the PSTN and two pairs of wires in
the handset. One of the functions the hybrid performs is regulating sidetone, which is
the amount of your transmitted signal that is returned to your earpiece; its purpose is
to provide a more natural-sounding conversation. Too much sidetone, and your voice
will sound too loud; too little, and you’ll think the line has gone dead.
This device signals the state of the telephone circuit to the CO.
When you pick up your telephone, the hook switch closes the loop between you and
the CO, which is seen as a request for a dial tone. When you hang up, the hook switch
opens the circuit, which indicates that the call has ended.†
The hook switch can also be used for signaling purposes. Some electronic analog
phones have a button labeled Link that causes an event called a flash. You can perform
a flash manually by depressing the hook switch for a duration of between 200 and 1,200
milliseconds. If you leave it down for longer than that, the carrier may assume you’ve
hung up. The purpose of the Link button is to handle this timing for you. If you’ve ever
used call waiting or three-way calling on an analog line, you have performed a hook
switch flash for the purpose of signaling the network.
Hook switch (or switch hook).
† When referring to the state of an analog circuit, people often speak in terms of “off-hook” and “on-hook.”
When your line is “off-hook,” your telephone is “on” a call. If your phone is “on-hook,” the telephone is
essentially “off,” or idle.
Analog Telephony | 169
The handset is composed of the transmitter and receiver. It performs the conversion
between the sound energy humans use and the electrical energy the telephone
network uses.
Tip and Ring
In an analog telephone circuit, there are two wires. In North America, these wires are
referred to as Tip and Ring.‡ This terminology comes from the days when telephone
calls were connected by live operators sitting at cord boards. The plugs that they used
had two contacts―one located at the tip of the plug and the other connected to the ring
around the middle (Figure 7-1).
The Tip lead is the positive polarity wire. In North America, this wire is typically green
and provides the return path. The Ring wire is the negative polarity wire. In North
America, this wire is normally red. For modern Cat 5 and 6 cables, the Tip is usually
the white wire, and Ring is the coloured wire. When your telephone is on-hook, this
wire will have a potential of –48V DC with respect to Tip. Off-hook, this voltage drops
to roughly –7V DC.
Digital Telephony
Analog telephony is almost dead.
In the PSTN, the famous Last Mile is the final remaining piece of the telephone network
still using technology pioneered well over a hundred years ago.§
One of the primary challenges when transmitting analog signals is that all sorts of things
can interfere with those signals, causing low volume, static, and all manner of other
undesired effects. Instead of trying to preserve an analog waveform over distances that
may span thousands of miles, why not simply measure the characteristics of the original
Handset.
‡ They may have other names elsewhere in the world (such as “A” and “B”).
§ “The Last Mile” is a term that was originally used to describe the only portion of the PSTN that had not been
converted to fiber optics: the connection between the central office and the customer. The Last Mile is more
than that, however, as it also has significance as a valuable asset of the traditional phone companies; they
own a connection into your home. The Last Mile is becoming more and more difficult to describe in technical
terms, as there are now so many ways to connect the network to the customer. As a thing of strategic value
to telecom, cable, and other utilities, its importance is obvious.
Ring Tip
Figure 7-1. Tip and Ring
170 | Chapter 7: Understanding Telephony
sound and send that information to the far end? The original waveform wouldn’t get
there, but all the information needed to reconstruct it would.
This is the principle of all digital audio (including telephony): sample the characteristics
of the source waveform, store the measured information, and send that data to the far
end. Then, at the far end, use the transmitted information to generate a completely new
audio signal that has the same characteristics as the original. The reproduction is so
good that the human ear can’t tell the difference.
The principle advantage of digital audio is that the sampled data can be mathematically
checked for errors all along the route to its destination, ensuring that a perfect duplicate
of the original arrives at the far end. Distance no longer affects quality, and interference
can be detected and eliminated.
Pulse-Code Modulation
There are several ways to digitally encode audio, but the most common method (and
the one used in telephony systems) is known as Pulse-Code Modulation (PCM). To
illustrate how this works, let’s go through a few examples.
Digitally encoding an analog waveform
The principle of PCM is that the amplitude‖of the analog waveform is sampled at specific
intervals so that it can later be re-created. The amount of detail that is captured is
dependent both on the bit resolution of each sample and on how frequently the samples
are taken. A higher bit resolution and a higher sampling rate will provide greater accuracy,
but more bandwidth will be required to transmit this more detailed information.
To get a better idea of how PCM works, consider the waveform displayed in Figure 7-2.
To digitally encode the wave, it must be sampled on a regular basis, and the amplitude
of the wave at each moment in time must be measured. The process of slicing up a
waveform into moments in time and measuring the energy at each moment is called
quantization, or sampling.
The samples will need to be taken frequently enough and will need to capture enough
information to ensure that the far end can re-create a sufficiently similar waveform. To
achieve a more accurate sample, more bits will be required. To explain this concept,
we will start with a very low resolution, using four bits to represent our amplitude. This
will make it easier to visualize both the quantization process itself and the effect that
resolution has on quality.
‖ Amplitude is essentially the power or strength of the signal. If you have ever held a skipping rope or garden
hose and given it a whip, you have seen the resultant wave. The taller the wave, the greater the amplitude.
Digital Telephony | 171
Figure 7-3 shows the information that will be captured when we sample our sine wave
at four-bit resolution.
At each time interval, we measure the amplitude of the wave and record the corresponding
intensity—in other words, we sample it. You will notice that the four-bit
resolution limits our accuracy. The first sample has to be rounded to 0011, and the next
quantization yields a sample of 0101. Then comes 0100, followed by 1001, 1011, and so
forth. In total, we have 14 samples (in reality, several thousand samples must be taken
per second).
1100
1011
1010
1001
1000
0000
0001
0010
0011
0100
0101
1101
0110
Amplitude
Samples
Figure 7-2. A simple sinusoidal (sine) wave
1100
1011
1010
1001
1000
0000
0001
0010
0011
0100
0101
1101
0110
Amplitude
Samples
Figure 7-3. Sampling our sine wave using four bits
172 | Chapter 7: Understanding Telephony
If we string together all the values, we can send them to the other side as:
0011 0101 0100 1001 1011 1011 1010 0001 0101 0101 0000 1100 1100 1010
On the wire, this code might look something like Figure 7-4.
When the far end’s digital-to-analog (D/A) converter receives this signal, it can use the
information to plot the samples, as shown in Figure 7-5.
From this information, the waveform can be reconstructed (see Figure 7-6).
As you can see if you compare Figure 7-2 with Figure 7-6, this reconstruction of the
waveform is not very accurate. This was done intentionally, to demonstrate an important
point: the quality of the digitally encoded waveform is affected by the resolution
and rate at which it is sampled. At too low a sampling rate, and with too low a sample
resolution, the audio quality will not be acceptable.
Increasing the sampling resolution and rate
Let’s take another look at our original waveform, this time using five bits to define our
quantization intervals (Figure 7-7).
0 0
1 1
0
1
0
1
0
1
0 0
1
0 0
1 1
0
1 1 1
0
1 1 1
0
1
0 0 0 0
1
0
1
0
1
0
1
0
1
0 0 0 0
1 1
0 0
1 1
0 0
1
0
1
0
Figure 7-4. PCM encoded waveform
1100
1011
1010
1001
1000
0000
0001
0010
0011
0100
0101
1101
0110
Amplitude
Samples
Figure 7-5. Plotted PCM signal
Digital Telephony | 173
In reality, there is no such thing as five-bit PCM. In the telephone network,
PCM samples are encoded using eight bits.#
1100
1011
1010
1001
1000
0000
0001
0010
0011
0100
0101
1101
0110
Amplitude
Samples
Figure 7-6. Delineated signal
11011
11010
11001
11000
10111
10110
10101
10100
10011
10010
10001
00000
00001
00010
00011
00100
00101
00110
00111
01000
01001
01010
01011
11100
01111
1 2 3 4 5 7 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
Amplitude
Samples
6 8
Figure 7-7. The same waveform, on a higher-resolution overlay
# Other digital audio methods may employ 16 bits or more.
174 | Chapter 7: Understanding Telephony
We’ll also double our sampling frequency. The points plotted this time are shown in
Figure 7-8.
We now have twice the number of samples, at twice the resolution. Here they are:
00111 01000 01001 01001 01000 00101 10110 11000 11001 11001 11000 10111
10100 10001 00010 00111 01001 01010 01001 00111 00000 11000 11010 11010
11001 11000 10110 10001
When received at the other end, that information can now be plotted as shown in
Figure 7-9.
From this information, the waveform shown in Figure 7-10 can then be generated.
As you can see, the resultant waveform is a far more accurate representation of the
original. However, you can also see that there is still room for improvement.
Note that 40 bits were required to encode the waveform at 4-bit resolution,
while 156 bits were needed to send the same waveform using 5-
bit resolution (and also doubling the sampling rate). The point is, there
is a tradeoff: the higher the quality of audio you wish to encode, the
more bits required to do it, and the more bits you wish to send (in real
time, naturally), the more bandwidth you will need to consume.
11011
11010
11001
11000
10111
10110
10101
10100
10011
10010
10001
00000
00001
00010
00011
00100
00101
00110
00111
01000
01001
01010
01011
11100
01111
1 2 3 4 5 7 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
Amplitude
Samples
6 8
Figure 7-8. The same waveform at double the resolution
Digital Telephony | 175
Nyquist’s Theorem
So how much sampling is enough? That very same question was considered in the 1920s
by an electrical engineer (and AT&T/Bell employee) named Harry Nyquist. Nyquist’s
Theorem states: “When sampling a signal, the sampling frequency must be greater than
twice the bandwidth of the input signal in order to be able to reconstruct the original
perfectly from the sampled version.”*
11011
11010
11001
11000
10111
10110
10101
10100
10011
10010
10001
00000
00001
00010
00011
00100
00101
00110
00111
01000
01001
01010
01011
11100
01111
1 2 3 4 5 7 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
Amplitude
Samples
6 8
Figure 7-9. Five-bit plotted PCM signal
11011
11010
11001
11000
10111
10110
10101
10100
10011
10010
10001
00000
00001
00010
00011
00100
00101
00110
00111
01000
01001
01010
01011
11100
01111
1 2 3 4 5 7 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
Amplitude
Samples
6 8
Figure 7-10. Waveform delineated from five-bit PCM
176 | Chapter 7: Understanding Telephony
In essence, what this means is that to accurately encode an analog signal you have to
sample it twice as often as the total bandwidth you wish to reproduce. Since the telephone
network will not carry frequencies below 300 Hz and above 4,000 Hz, a sampling
frequency of 8,000 samples per second will be sufficient to reproduce any frequency
within the bandwidth of an analog telephone. Keep that 8,000 samples per second in
mind; we’re going to talk about it more later.
Logarithmic companding
So, we’ve gone over the basics of quantization, and we’ve discussed the fact that more
quantization intervals (i.e., a higher sampling rate) give better quality but also require
more bandwidth. Lastly, we’ve discussed the minimum sample rate needed to accurately
measure the range of frequencies we wish to be able to transmit (in the case of
the telephone, it’s 8,000 Hz). This is all starting to add up to a fair bit of data being
sent on the wire, so we’re going to want to talk about companding.
Companding is a method of improving the dynamic range of a sampling method without
losing important accuracy. It works by quantizing higher amplitudes in a much coarser
fashion than lower amplitudes. In other words, if you yell into your phone, you will
not be sampled as cleanly as you will be when speaking normally. Yelling is also not
good for your blood pressure, so it’s best to avoid it.
Two companding methods are commonly employed: μlaw† in North America, and
alaw in the rest of the world. They operate on the same principles but are otherwise
not compatible with each other.
Companding divides the waveform into cords, each of which has several steps. Quantization
involves matching the measured amplitude to an appropriate step within a
cord. The value of the band and cord numbers (as well as the sign—positive or negative)
becomes the signal. The following diagrams will give you a visual idea of what companding
does. They are not based on any standard, but rather were made up for the
purpose of illustration (again, in the telephone network, companding will be done at
an eight-bit, not five-bit, resolution).
Figure 7-11 illustrates five-bit companding. As you can see, amplitudes near the zerocrossing
point will be sampled far more accurately than higher amplitudes (either
positive or negative). However, since the human ear, the transmitter, and the receiver
will also tend to distort loud signals, this isn’t really a problem.
* Nyquist published two papers, “Certain Factors Affecting Telegraph Speed” (1924) and “Certain Topics in
Telegraph Transmission Theory” (1928), in which he postulated what became known as Nyquist’s Theorem.
Proven in 1949 by Claude Shannon (“Communication in the Presence of Noise”), it is also referred to as the
Nyquist-Shannon sampling theorem.
† μlaw is often referred to as “ulaw” because, let’s face it, how many of us have μ keys on our keyboards? μ is
in fact the Greek letter Mu; thus, you will also see μlaw written (more correctly) as “Mu-law.” When spoken,
it is correct to confidently say “Mew-law,” but if folks look at you strangely, and you’re feeling generous, you
can help them out and tell them it’s “ulaw.” Many people just don’t appreciate trivia.
Digital Telephony | 177
A quantized sample might look like Figure 7-12. It yields the following bit stream:
00000 10011 10100 10101 01101 00001 00011 11010 00010 00001 01000 10011
10100 10100 00101 00100 00101 10101 10011 10001 00011 00001 00000 10100
10010 10101 01101 10100 00101 11010 00100 00000 01000
Aliasing
If you’ve ever watched the wheels on a wagon turn backward in an old Western movie,
you’ve seen the effects of aliasing. The frame rate of the movie cannot keep up with the
rotational frequency of the spokes, and a false rotation is perceived.
10
00
11
00
11
00
10
11
00
11
00
10
00
01
10
11
10
01
00
00
01
10
11
0
1
Sign-bit Cord-bit Step-bit
Low accuracy
Reduced accuracy
Accurate
Highly accurate
Highly accurate
Accurate
Reduced accuracy
Low accuracy
11
01
10
01
10
01
01
00
01
10
11
01
10
01
11
11
Amplitude
Samples
Figure 7-11. Five-bit companding
178 | Chapter 7: Understanding Telephony
In a digital audio system (which the modern PSTN arguably is), aliasing always occurs
if frequencies that are greater than one-half the sampling rate are presented to the analog-
to-digital (A/D) converter. In PSTN, that includes any audio frequencies above
4,000 Hz (half the sampling rate of 8,000 Hz). This problem is easily corrected by
passing the audio through a low-pass filter‡ before presenting it to the A/D converter.§
10
00
11
00
11
00
10
11
00
11
00
10
00
01
10
11
10
01
00
00
01
10
11
0
1
Sign-bit Cord-bit Step-bit
Low accuracy
Reduced accuracy
Accurate
Highly accurate
Highly accurate
Accurate
Reduced accuracy
Low accuracy
11
01
10
01
10
01
01
00
01
10
11
01
10
01
11
11
Amplitude
Samples
Figure 7-12. Quantized and companded at 5-bit resolution
‡ A low-pass filter, as its name implies, allows through only frequencies that are lower than its cut-off frequency.
Other types of filters are high-pass filters (which remove low frequencies) and band-pass filters (which filter
out both high and low frequencies).
Digital Telephony | 179
The Digital Circuit-Switched Telephone Network
For over a hundred years, telephone networks were exclusively circuit-switched. What
this meant was that for every telephone call made, a dedicated connection was established
between the two endpoints, with a fixed amount of bandwidth allocated to that
circuit. Creating such a network was costly, and where distance was concerned, using
that network was costly as well. Although we are all predicting the end of the circuitswitched
network, many people still use it every day, and it really does work rather well.
Circuit Types
In the PSTN, there are many different sizes of circuits serving the various needs of the
network. Between the central office and a subscriber, one or more analog circuits, or a
few dozen channels delivered over a digital circuit, generally suffice. Between PSTN
offices (and with larger customers), fiber-optic circuits are generally used.
The humble DS-0―the foundation of it all
Since the standard method of digitizing a telephone call is to record an 8-bit sample
8,000 times per second, we can see that a PCM-encoded telephone circuit will need a
bandwidth of eight times 8,000 bits per second, or 64,000 bps. This 64 Kbps channel
is referred to as a DS-0 (that’s “Dee-Ess-Zero”). The DS-0 is the fundamental building
block of all digital telecommunications circuits.
Even the ubiquitous analog circuit is sampled into a DS-0 as soon as possible. Sometimes
this happens where your circuit terminates at the central office, and sometimes
well before.‖
T-carrier circuits
The venerable T1 is one of the more recognized digital telephony terms. A T1 is a digital
circuit consisting of 24 DS-0s multiplexed together into a 1.544 Mbps bitstream.# This
bit stream is properly defined as a DS-1. Voice is encoded on a T1 using the μlaw
companding algorithm.
§ If you ever have to do audio recordings for a system, you might want to take advantage of the band-pass filter
that is built into most telephone sets. Doing a recording using even high-end recording equipment can pick
up all kinds of background noise that you don’t even hear until you downsample, at which point the
background noise produces aliasing (which can sound like all kinds of weird things). Conversely, the phone
records in the correct format already, so the noise never enters the audio stream. Having said all that, no
matter what you use to do recordings, avoid environments that have a lot of background noise. Typical offices
can be a lot noisier than you’d think, as HVAC equipment can produce noise that we don’t even realize is there.
‖ Digital telephone sets (including IP sets) do the analog-to-digital conversion right at the point where the
handset plugs into the phone, so the DS-0 is created right at the phone set.
# The 24 DS-0s use 1.536 Mbps, and the remaining .008 Mbps is used by framing bits.
180 | Chapter 7: Understanding Telephony
The European version of the T1 was developed by the European Conference
of Postal and Telecommunications Administrations* (CEPT),
and was first referred to as a CEPT-1. It is now called an E1.
The E1 is comprised of 32 DS-0s, but the method of PCM encoding is
different: E1s use alaw companding. This means that connecting between
an E1-based network and a T1-based network will always require
a transcoding step. Note that an E1, although it has 32 channels, is also
considered a DS-1. It is likely that E1 is far more widely deployed, as it
is used everywhere in the world except North American and Japan.
The various other T-carriers (T2, T3, and T4) are multiples of the T1, each based on
the humble DS-0. Table 7-2 illustrates the relationships between the different T-carrier
circuits.
Table 7-2. T-carrier circuits
Carrier Equivalent data bitrate Number of DS-0s Data bitrate
T1 24 DS-0s 24 1.544 Mbps
T2 4 T1s 96 6.312 Mbps
T3 7 T2s 672 44.736 Mbps
T4 6 T3s 4,032 274.176 Mbps
At densities above T3, it is very uncommon to see a T-carrier circuit. For these speeds,
optical carrier (OC) circuits may be used.
SONET and OC circuits
The Synchronous Optical Network (SONET) was developed out of a desire to take the
T-carrier system to the next technological level: fiber optics. SONET is based on the
bandwidth of a T3 (44.736 Mbps), with a slight overhead making it 51.84 Mbps. This
is referred to as an OC-1 or STS-1. As Table 7-3 shows, all higher-speed OC circuits
are multiples of this base rate.
Table 7-3. OC circuits
Carrier Equivalent data bitrate Number of DS-0s Data bitrate
OC-1 1 DS-3 (plus overhead) 672 51.840 Mbps
OC-3 3 DS-3s 2,016 155.520 Mbps
OC-12 12 DS-3s 8,064 622.080 Mbps
OC-48 48 DS-3s 32,256 2488.320 Mbps
OC-192 192 DS-3s 129,024 9953.280 Mbps
* Conférence Européenne des Administrations des Postes et des Télécommunications.
The Digital Circuit-Switched Telephone Network | 181
SONET was created in an effort to standardize optical circuits, but due to its high cost,
coupled with the value offered by many newer schemes, such as Dense Wave Division
Multiplexing (DWDM), there is some controversy surrounding its future.
Digital Signaling Protocols
As with any circuit, it is not enough for the circuits used in the PSTN to just carry (voice)
data between endpoints. Mechanisms must also be provided to pass information about
the state of the channel between each endpoint. (Disconnect and answer supervision
are two examples of basic signaling that might need to take place; Caller ID is an example
of a more complex form of signaling.)
Channel Associated Signaling (CAS)
Also known as robbed-bit signaling, CAS is what you will use to transmit voice on a
T1 when ISDN is not available. Rather than taking advantage of the power of the digital
circuit, CAS simulates analog channels. CAS works by stealing bits from the audio
stream for signaling purposes. Although the effect on audio quality is not really noticeable,
the lack of a powerful signaling channel limits your flexibility.
When configuring a CAS T1, the signaling options at each end must match. E&M (Ear
& Mouth or recEive & transMit) signaling is generally preferred, as it offers the best
supervision. Having said that, in an Asterisk environment the most likely reason for
you to use CAS would be for a channel bank, which means you are most likely going
to have to use FXS signaling.
CAS is very rarely used on PSTN circuits anymore, due to the superiority of ISDN-PRI.
One of the limitations of CAS is that it does not allow the dynamic assignment of
channels to different functions. Also, Caller ID information (which may not even be
supported) has to be sent as part of the audio stream. CAS is commonly used on the
T1 link in channel banks.
ISDN
The Integrated Services Digital Network (ISDN) has been around for more than 20
years. Because it separates the channels that carry the traffic (the bearer channels, or
B-channels) from the channel that carries the signaling information (the D-channel),
ISDN allows for the delivery of a much richer set of features than CAS. In the beginning,
ISDN promised to deliver much the same sort of functionality that the Internet has
given us, including advanced capabilities for voice, video, and data transfer.
Unfortunately, rather than ratifying a standard and sticking to it, the respective telecommunications
manufacturers all decided to add their own tweaks to the protocol,
in the belief that their versions were superior and would eventually dominate the market.
As a result, getting two ISDN-compliant systems to connect to each other was often
a painful and expensive task. The carriers who had to implement and support this
182 | Chapter 7: Understanding Telephony
expensive technology, in turn, priced it so that it was not rapidly adopted. Currently,
ISDN is rarely used for much more than basic trunking—in fact, the acronym ISDN
has become a joke in the industry: “It Still Does Nothing.”
Having said that, ISDN has become quite popular for trunking, and it is now (mostly)
standards-compliant. If you have a PBX with more than a dozen lines connected to the
PSTN, there’s a very good chance that you’ll be running an ISDN-PRI (Primary Rate
Interface) circuit. Also, in places where DSL and cable access to the Internet are not
available (or are too expensive), an ISDN-BRI (Basic Rate Interface) circuit might provide
you with an affordable 128 Kbps connection. In much of North America, the use
of BRI for Internet connectivity has been deprecated in favor of DSL and cable modems
(and it is never used for voice), but in many European countries it has almost totally
replaced analog circuits.
Basic Rate Interface (or Basic Rate Access) is the flavor of ISDN, and is
designed to service small endpoints such as workstations.
The BRI flavor of the ISDN specification is often referred to simply as “ISDN,” but this
can be a source of confusion, as ISDN is a protocol, not a type of circuit (not to mention
that PRI circuits are also correctly referred to as ISDN!).
A Basic Rate ISDN circuit consists of two 64 Kbps B-channels controlled by a 16-Kbps
D-channel, for a total of 144 Kbps.
Basic Rate ISDN has been a source of much confusion during its life, due to problems
with standards compliance, technical complexity, and poor documentation. Still, many
European telecos have widely implemented ISDN-BRI, and thus it is more popular in
Europe than in North America.
The Primary Rate Interface (or Primary Rate Access) flavor of ISDN is used
to provide ISDN service over larger network connections. A Primary Rate ISDN circuit
uses a single DS-0 channel as a signaling link (the D-channel); the remaining channels
serve as B-channels.
In North America, Primary Rate ISDN is commonly carried on one or more T1 circuits.
Since a T1 has 24 channels, a North American PRI circuit typically consists of 23 Bchannels
and 1 D-channel. For this reason, PRI is often referred to as 23B+D.†
In Europe, a 32-channel E1 circuit is used, so a Primary Rate ISDN circuit
is referred to as 30B+D (the final channel is used for
synchronization).
ISDN-BRI/BRA.
ISDN-PRI/PRA.
† PRI is actually quite a bit more flexible than that, as it is possible to span a single PRI circuit across multiple
T1 spans. This can give rise, for example, to a 47B+D circuit (where a single D-channel serves two T1s) or a
46B+2D circuit (where primary and backup D-channels serve a pair of T1s). You will sometimes see PRI
described as nB+nD, because the number of B- and D-channels is, in fact, quite variable. For this reason, you
should never refer to a T1 carrying PRI as “a PRI.” For all you know, the PRI circuit spans multiple T1s, as
is common in larger PBX deployments.
The Digital Circuit-Switched Telephone Network | 183
Primary Rate ISDN is very popular, due to its technical benefits and generally competitive
pricing at higher densities. If you believe you will require more than a dozen or so
PSTN lines, you should look into Primary Rate ISDN pricing.
From a technical perspective, ISDN-PRI is always preferable to CAS.
Signaling System 7
Signaling System 7 (SS7) is the signaling system used by carriers. It is conceptually
similar to ISDN, and it is instrumental in providing a mechanism for the carriers to
transmit the additional information ISDN endpoints typically need to pass. However,
the technology of SS7 is different from that of ISDN; one big difference is that SS7 runs
on a completely separate network from the actual trunks that carry the calls.
SS7 support in Asterisk is on the horizon, as there is much interest in making Asterisk
compatible with the carrier networks. An open source version of SS7 (http://
www.openss7.org) exists, but work is still needed for full SS7 compliance, and as of this
writing it is not known whether this version will be integrated with Asterisk. Another
promising source of SS7 support comes from Sangoma Technologies, which offers SS7
functionality in many of its products.
It should be noted that adding support for SS7 in Asterisk is not going to be as simple
as writing a proper driver. Connecting equipment to an SS7 network will not be possible
without that equipment having passed extremely rigorous certification processes. Even
then, it seems doubtful that any traditional carrier is going to be in a hurry to allow
such a thing to happen, mostly for strategic and political reasons.
Packet-Switched Networks
In the mid-1990s, network performance improved to the point where it became possible
to send a stream of media information in real time across a network connection. Because
the media stream is chopped up into segments, which are then wrapped in an addressing
envelope, such connections are referred to as packet-based. The challenge, of course,
is to send a flood of these packets between two endpoints, ensuring that the packets
arrive in the same order in which they were sent, in less than 150 milliseconds, with
none lost. This is the essence of Voice over IP.
Conclusion
This chapter has explored the technologies currently in use in the PSTN. In the next
chapter, we will discuss protocols for VoIP: the carrying of telephone connections
across IP-based networks. These protocols define different mechanisms for carrying
telephone conversations, but their significance is far greater than just that. Bringing the
telephone network into the data network will finally erase the line between telephones
and computers, which holds the promise of a revolutionary evolution in the way we
communicate.
184 | Chapter 7: Understanding Telephony
CHAPTER 8
Protocols for VoIP
The Internet is a telephone system that’s gotten uppity.
—Clifford Stoll
The telecommunications industry spans over 100 years, and Asterisk integrates most
—if not all—of the major technologies that it has made use of over the last century. To
make the most out of Asterisk, you need not be a professional in all areas, but understanding
the differences between the various codecs and protocols will give you a
greater appreciation and understanding of the system as a whole.
This chapter explains Voice over IP and what makes VoIP networks different from the
traditional circuit-switched voice networks that were the topic of the last chapter. We
will explore the need for VoIP protocols, outlining the history and potential future of
each. We’ll also look at security considerations and these protocols’ abilities to work
within topologies such as Network Address Translation (NAT). The following VoIP
protocols will be discussed (some more briefly than others):
• IAX
• SIP
• H.323
• MGCP
• Skinny/SCCP
• UNISTIM
Codecs are the means by which analog voice can be converted to a digital signal and
carried across the Internet. Bandwidth at any location is finite, and the number of
simultaneous conversations any particular connection can carry is directly related to
the type of codec implemented. In this chapter, we’ll also explore the differences between
the following codecs in regards to bandwidth requirements (compression level)
and quality:
185
• G.711
• G.726
• G.729A
• GSM
• iLBC
• Speex
• MP3
We will then conclude the chapter with a discussion of how voice traffic can be routed
reliably, what causes echo and how to deal with it, and how Asterisk controls the authentication
of inbound and outbound calls.
The Need for VoIP Protocols
The basic premise of VoIP is the packetization* of audio streams for transport over
Internet Protocol-based networks. The challenges to accomplishing this relate to the
manner in which humans communicate. Not only must the signal arrive in essentially
the same form that it was transmitted in, but it needs to do so in less than 150 milliseconds.
If packets are lost or delayed, there will be degradation to the quality of the
communications experience, meaning that two people will have difficulty in carrying
on a conversation.
The transport protocols that collectively are called “the Internet” were not originally
designed with real-time streaming of media in mind. Endpoints were expected to resolve
missing packets by waiting longer for them to arrive, requesting retransmission,
or, in some cases, considering the information to be gone for good and simply carrying
on without it. In a typical voice conversation, these mechanisms will not serve. Our
conversations do not adapt well to the loss of letters or words, nor to any appreciable
delay between transmittal and receipt.
The traditional PSTN was designed specifically for the purpose of voice transmission,
and it is perfectly suited to the task from a technical standpoint. From a flexibility
standpoint, however, its flaws are obvious to even people with a very limited understanding
of the technology. VoIP holds the promise of incorporating voice communications
into all of the other protocols we carry on our networks, but due to the special
demands of a voice conversation, special skills are needed to design, build, and maintain
these networks.
The problem with packet-based voice transmission stems from the fact that the way in
which we speak is totally incompatible with the way in which IP transports data.
* This word hasn’t quite made it into the dictionary, but it is a term that is becoming more and more common.
It refers to the process of chopping a steady stream of information into discrete chunks (or packets), suitable
for delivery independently of one another.
186 | Chapter 8: Protocols for VoIP
Speaking and listening consist of the relaying of a stream of audio, whereas the Internet
protocols are designed to chop everything up, encapsulate the bits of information into
thousands of packages, and then deliver each package in whatever way possible to the
far end. Clearly, some way of dealing with this is required.
VoIP Protocols
The mechanism for carrying a VoIP connection generally involves a series of signaling
transactions between the endpoints (and gateways in between), culminating into two
persistent media streams (one for each direction) that carry the actual conversation.
There are several protocols in existence to handle this. In this section, we will discuss
some of those that are important to VoIP in general and to Asterisk specifically.
IAX (The “Inter-Asterisk eXchange” Protocol)
If you claim to be one of the folks in the know when it comes to Asterisk, your test will
come when you have to pronounce the name of this protocol. It would seem that you
should say “eye-ay-ex”, but this hardly rolls off the tongue very well.† Fortunately, the
proper pronunciation is in fact “eeks.”‡ IAX is an open protocol, meaning that anyone
can download and develop for it, but it is not yet a standard of any kind.§
It is expected that IAX2 will become an IETF protocol soon. IAX2 is currently in draft
status with the IETF, and it is widely expected to become an official protocol in a few
years’ time.
In Asterisk, IAX is supported by the chan_iax2.so module.
History
The IAX protocol was developed by Digium for the purpose of communicating with
other Asterisk servers (hence the Inter-Asterisk eXchange protocol). It is very important
to note that IAX is not at all limited to Asterisk. The standard is open for anyone to
use, and it is supported by many other open source telecom projects, as well as by
several hardware vendors. IAX is a transport protocol (much like SIP) that uses a single
UDP port (4569) for both the channel signaling and media streams. As discussed later
in this chapter, this makes it easier to manage when behind NATed firewalls.
IAX also has the unique ability to trunk multiple sessions into one dataflow, which can
be a tremendous bandwidth advantage when sending a lot of simultaneous channels
to a remote box. Trunking allows multiple media streams to be represented with a
† It sounds like the name of a Dutch football team.
‡ Go ahead. Say it. Now that sounds much better, doesn’t it?
§ Officially, the current version is IAX2, but all support for IAX1 has been dropped, so whether you say “IAX”
or “IAX2,” it is expected that you are talking about the same version.
VoIP Protocols | 187
single datagram header, that will lower the overhead associated with individual
channels. This helps to lower latency and reduce the processing power and bandwidth
required, allowing the protocol to scale much more easily with a large number of active
channels between endpoints. If you have a large quantity of IP calls to pass between
two endpoints, you should take a close look at IAX trunking.
Future
Since IAX was optimized for voice, it has received some criticism for not better supporting
video—but in fact, IAX holds the potential to carry pretty much any media
stream desired. Because it is an open protocol, future media types are certain to be
incorporated as the community desires them.
Security considerations
IAX includes the ability to authenticate in three ways: plain text, MD5 hashing, and
RSA key exchange. This, of course, does nothing to encrypt the media path or headers
between endpoints. Many solutions include using a Virtual Private Network (VPN)
appliance or software to encrypt the stream in another layer of technology, which requires
the endpoints to pre-establish a method of having these tunnels configured and
operational. However, IAX is now also able to encrypt the streams between endpoints
with dynamic key exchange at call setup (using the configuration option encryp
tion=aes128), allowing the use of automatic key rollover.
IAX and NAT
The IAX2 protocol was deliberately designed to work from behind devices performing
NAT. The use of a single UDP port for both signaling and transmission of media also
keeps the number of holes required in your firewall to a minimum. These considerations
have helped make IAX one of the easiest protocols (if not the easiest) to implement in
secure networks.
SIP
The Session Initiation Protocol (SIP) has taken the telecommunications industry by
storm. SIP has pretty much dethroned the once-mighty H.323 as the VoIP protocol of
choice—certainly at the endpoints of the network. The premise of SIP is that each end
of a connection is a peer; the protocol negotiates capabilities between them. What
makes SIP compelling is that it is a relatively simple protocol, with a syntax similar to
that of other familiar protocols such as HTTP and SMTP. SIP is supported in Asterisk
with the chan_sip.so module.‖
History
SIP was originally submitted to the Internet Engineering Task Force (IETF) in February
of 1996 as “draft-ietf-mmusic-sip-00.” The initial draft looked nothing like the SIP we
188 | Chapter 8: Protocols for VoIP
know today and contained only a single request type: a call setup request. In March of
1999, after 11 revisions, SIP RFC 2543 was born.
At first, SIP was all but ignored, as H.323 was considered the protocol of choice for
VoIP transport negotiation. However, as the buzz grew, SIP began to gain popularity,
and while there may be a lot of different factors that accelerated its growth, we’d like
to think that a large part of its success is due to its freely available specification.
SIP is an application-layer signaling protocol that uses the well-known port 5060 for
communications. SIP can be transported with either the UDP or TCP transport-layer
protocols. Asterisk does not currently have a TCP implementation for transporting SIP
messages, but it is possible that future versions may support it (and patches to the code
base are gladly accepted). SIP is used to “establish, modify, and terminate multimedia
sessions such as Internet telephony calls.”#
SIP does not transport media between endpoints.
RTP is used to transmit media (i.e., voice) between endpoints. RTP uses high-numbered,
unprivileged ports in Asterisk (10,000 through 20,000, by default).
A common topology to illustrate SIP and RTP, commonly referred to as the “SIP trapezoid,”
is shown in Figure 8-1. When Alice wants to call Bob, Alice’s phone contacts
her proxy server, and the proxy tries to find Bob (often connecting through his proxy).
Once the phones have started the call, they communicate directly with each other (if
possible), so that the data doesn’t have to tie up the resources of the proxy.
SIP was not the first, and is not the only, VoIP protocol in use today (others include H.
323, MGCP, IAX, and so on), but currently it seems to have the most momentum with
hardware vendors. The advantages of the SIP protocol lie in its wide acceptance and
architectural flexibility (and, we used to say, simplicity!).
‖ Having just called SIP simple, it should be noted that it is by no means lightweight. It has been said that if
one were to read all of the IETF RFCs that are relevant to SIP, one would have more than 3,000 pages of
reading to do. SIP is quickly earning a reputation for being far too bloated, but that does nothing to lessen
its popularity.
# RFC 3261, SIP: Session Initiation Protocol, p. 9, Section 2.
SIP signaling
RTP media
Figure 8-1. The SIP trapezoid
VoIP Protocols | 189
Future
SIP has earned its place as the protocol that justified VoIP. All new user and enterprise
products are expected to support SIP, and any existing products will now be a tough
sell unless a migration path to SIP is offered. SIP is widely expected to deliver far more
than VoIP capabilities, including the ability to transmit video, music, and any type of
real-time multimedia. While its use as a ubiquitous general-purpose media transport
mechanism seems doubtful, SIP is unarguably poised to deliver the majority of new
voice applications for the next few years.
Security considerations
SIP uses a challenge/response system to authenticate users. An initial INVITE is sent to
the proxy with which the end device wishes to communicate. The proxy then sends
back a 407 Proxy Authorization Request message, which contains a random set of
characters referred to as a nonce. This nonce is used along with the password to generate
an MD5 hash, which is then sent back in the subsequent INVITE. Assuming the MD5
hash matches the one that the proxy generated, the client is then authenticated.
Denial of Service (DoS) attacks are probably the most common type of attack on VoIP
communications. A DoS attack can occur when a large number of invalid INVITE requests
are sent to a proxy server in an attempt to overwhelm the system. These attacks
are relatively simple to implement, and their effects on the users of the system are
immediate. SIP has several methods of minimizing the effects of DoS attacks, but ultimately
they are impossible to prevent.
SIP implements a scheme to guarantee that a secure, encrypted transport mechanism
(namely Transport Layer Security, or TLS) is used to establish communication between
the caller and the domain of the callee. Beyond that, the request is sent securely to the
end device, based upon the local security policies of the network. Note that the encryption
of the media (that is, the RTP stream) is beyond the scope of SIP itself and
must be dealt with separately.
More information regarding SIP security considerations, including registration hijacking,
server impersonation, and session teardown, can be found in Section 26 of SIP RFC
3261.
SIP and NAT
Probably the biggest technical hurdle SIP has to conquer is the challenge of carrying
out transactions across a NAT layer. Because SIP encapsulates addressing information
in its data frames, and NAT happens at a lower network layer, the addressing information
is not automatically modified and, thus, the media streams will not have the
correct addressing information needed to complete the connection when NAT is in
place. In addition to this, the firewalls normally integrated with NAT will not consider
the incoming media stream to be part of the SIP transaction, and will block the connection.
Newer firewalls and Session Border Controllers are SIP-aware, but this is still
190 | Chapter 8: Protocols for VoIP
considered a shortcoming in this protocol, and it causes no end of trouble to network
professionals needing to connect SIP endpoints using existing network infrastructure.
H.323
This International Telecommunication Union (ITU) protocol was originally designed
to provide an IP transport mechanism for video conferencing. It has become the standard
in IP-based video-conferencing equipment, and it briefly enjoyed fame as a VoIP
protocol as well. While there is much heated debate over whether SIP or H.323 (or
IAX) will dominate the VoIP protocol world, in Asterisk, H.323 has largely been deprecated
in favor of IAX and SIP. H.323 has not enjoyed much success among users and
enterprises, although it might still be the most widely used VoIP protocol among carriers.
The three versions of H.323 supported in Asterisk are handled by the modules
chan_h323.so (supplied with Asterisk), chan_oh323.so (available as a free add-on), and
chan_ooh323.so (supplied in asterisk-addons).
You have probably used H.323 without even knowing it—Microsoft’s
NetMeeting client is arguably the most widely deployed H.323 client.
History
H.323 was developed by the ITU in May of 1996 as a means to transmit voice, video,
data, and fax communications across an IP-based network while maintaining connectivity
with the PSTN. Since that time, H.323 has gone through several versions and
annexes (which add functionality to the protocol), allowing it to operate in pure VoIP
networks and more widely distributed networks.
Future
The future of H.323 is a subject of debate. If the media is any measure, it doesn’t look
good for H.323; it hardly ever gets mentioned (certainly not with the regularity of SIP).
H.323 is often regarded as technically superior to SIP, but, as with so many other technologies,
that sort of thing is seldom the deciding factor in whether technology enjoys
success. One of the factors that makes H.323 unpopular is its complexity—although
many argue that the once-simple SIP is starting to suffer from the same problem.
H.323 still carries by far the majority of worldwide carrier VoIP traffic, but as people
become less and less dependent on traditional carriers for their telecom needs, the
future of H.323 becomes more difficult to predict with any certainty. While H.323 may
not be the protocol of choice for new implementations, we can certainly expect to have
to deal with H.323 interoperability issues for some time to come.
VoIP Protocols | 191
Security considerations
H.323 is a relatively secure protocol and does not require many security considerations
beyond those that are common to any network communicating with the Internet. Since
H.323 uses the RTP protocol for media communications, it does not natively support
encrypted media paths. The use of a VPN or other encrypted tunnel between endpoints
is the most common way of securely encapsulating communications. Of course, this
has the disadvantage of requiring the establishment of these secure tunnels between
endpoints, which may not always be convenient (or even possible). As VoIP becomes
used more often to communicate with financial institutions such as banks, we’re likely
to require extensions to the most commonly used VoIP protocols to natively support
strong encryption methods.
H.323 and NAT
The H.323 standard uses the Internet Engineering Task Force (IETF) RTP protocol to
transport media between endpoints. Because of this, H.323 has the same issues as SIP
when dealing with network topologies involving NAT. The easiest method is to simply
forward the appropriate ports through your NAT device to the internal client.
To receive calls, you will always need to forward TCP port 1720 to the client. In addition,
you will need to forward the UDP ports for the RTP media and RTCP control
streams (see the manual for your device for the port range it requires). Older clients,
such as Microsoft NetMeeting, will also require TCP ports forwarded for H.245 tunneling
(again, see your client’s manual for the port number range).
If you have a number of clients behind the NAT device, you will need to use a
gatekeeper running in proxy mode. The gatekeeper will require an interface attached
to the private IP subnet and the public Internet. Your H.323 client on the private IP
subnet will then register to the gatekeeper, which will proxy calls on the clients’ behalf.
Note that any external clients that wish to call you will also be required to register with
the proxy server.
At this time, Asterisk can’t act as an H.323 gatekeeper. You’ll have to use a separate
application, such as the open source OpenH323 Gatekeeper (http://www.gnugk.org).
MGCP
The Media Gateway Control Protocol (MGCP) also comes to us from the IETF. While
MGCP deployment is more widespread than one might think, it is quickly losing
ground to protocols such as SIP and IAX. Still, Asterisk loves protocols, so naturally it
has rudimentary support for it.
MGCP is defined in RFC 3435.* It was designed to make the end devices (such as
phones) as simple as possible, and have all the call logic and processing handled by
* RFC 3435 obsoletes RFC 2705.
192 | Chapter 8: Protocols for VoIP
media gateways and call agents. Unlike SIP, MGCP uses a centralized model. MGCP
phones cannot directly call other MGCP phones; they must always go through some
type of controller.
Asterisk supports MGCP through the chan_mgcp.so module, and the endpoints are
defined in the configuration file mgcp.conf. Since Asterisk provides only basic call agent
services, it cannot emulate an MGCP phone (to register to another MGCP controller
as a user agent, for example).
If you have some MGCP phones lying around, you will be able to use them with Asterisk.
If you are planning to put MGCP phones into production on an Asterisk system,
keep in mind that the community has moved on to more popular protocols, and you
will therefore need to budget your software support needs accordingly. If possible (for
example, with Cisco phones), you should upgrade MGCP phones to SIP.
Proprietary Protocols
Finally, let’s take a look at two proprietary protocols that are supported in Asterisk.
Skinny/SCCP
The Skinny Client Control Protocol (SCCP) is proprietary to Cisco VoIP equipment. It
is the default protocol for endpoints on a Cisco Call Manager PBX.† Skinny is supported
in Asterisk, but if you are connecting Cisco phones to Asterisk, it is generally recommended
that you obtain SIP images for any phones that support it and connect via SIP
instead.
UNISTIM
Support for Nortel’s proprietary VoIP protocol, UNISTIM, means that Asterisk is the
first PBX in history to natively support proprietary IP terminals from the two biggest
players in VoIP—Nortel and Cisco. UNISTIM support is totally experimental, and does
not work well enough to put into production, but the fact that somebody took the
trouble to do this demonstrates the power of the Asterisk platform.
Codecs
Codecs are generally understood to be various mathematical models used to digitally
encode (and compress) analog audio information. Many of these models take into account
the human brain’s ability to form an impression from incomplete information.
We’ve all seen optical illusions; likewise, voice-compression algorithms take advantage
of our tendency to interpret what we believe we should hear, rather than what we
† Cisco has recently announced that it will be migrating toward SIP in its future products.
Codecs | 193
actually hear.‡ The purpose of the various encoding algorithms is to strike a balance
between efficiency and quality.§
Originally, the term codec referred to a COder/DECoder: a device that converts between
analog and digital. Now, the term seems to relate more to COmpression/
DECompression.
Before we dig into the individual codecs, take a look at Table 8-1—it’s a quick reference
that you may want to refer back to.
Table 8-1. Codec quick reference
Codec Data bitrate (Kbps) License required?
G.711 64 Kbps No
G.726 16, 24, 32, or 40 Kbps No
G.729A 8 Kbps Yes (no for passthrough)
GSM 13 Kbps No
iLBC 13.3 Kbps (30-ms frames) or 15.2 Kbps (20-ms frames) No
Speex Variable (between 2.15 and 22.4 Kbps) No
G.711
G.711 is the fundamental codec of the PSTN. In fact, if someone refers to PCM (discussed
in the previous chapter) with respect to a telephone network, you are allowed
to think of G.711. Two companding methods are used: μlaw in North America and
alaw in the rest of the world. Either one delivers an 8-bit word transmitted 8,000 times
per second. If you do the math, you will see that this requires 64,000 bits to be transmitted
per second.
Many people will tell you that G.711 is an uncompressed codec. This is not exactly
true, as companding is considered a form of compression. What is true is that G.711
is the base codec from which all of the others are derived.
G.711 imposes minimal (almost zero) load on the CPU.
‡ “Aoccdrnig to rsereach at an Elingsh uinervtisy, it deosn’t mttaer in waht oredr the ltteers in a wrod are, the
olny iprmoetnt tihng is taht frist and lsat ltteres are in the rghit pclae. The rset can be a toatl mses and you
can sitll raed it wouthit a porbelm. Tihs is bcuseae we do not raed ervey lteter by istlef, but the wrod as a
wlohe.” (The source of this quote is unknown―see http://www.bisso.com/ujg_archives/000228.html.) We do
the same thing with sound―if there is enough information, our brain can fill in the gaps.
§ On an audio CD, quality is far more important than saving bandwidth, so the audio is quantized at 16 bits
(times 2, as it’s stereo), with a sampling rate of 44,100 Hz. Considering that the CD was invented in the late
1970s, this was quite impressive stuff back then. The telephone network does not require this level of quality
(and needs to optimize bandwidth), so telephone signals are encoded using 8 bits, at a sampling frequency
of 8,000 Hz.
194 | Chapter 8: Protocols for VoIP
G.726
This codec has been around for some time (it used to be G.721, which is now obsolete),
and it is one of the original compressed codecs. It is also known as Adaptive Differential
Pulse-Code Modulation (ADPCM), and it can run at several bitrates. The most common
rates are 16 Kbps, 24 Kbps, and 32 Kbps. As of this writing, Asterisk currently
supports only the ADPCM-32 rate, which is far and away the most popular rate for this
codec.
G.726 offers quality nearly identical to G.711, but it uses only half the bandwidth. This
is possible because rather than sending the result of the quantization measurement, it
sends only enough information to describe the difference between the current sample
and the previous one. G.726 fell from favor in the 1990s due to its inability to carry
modem and fax signals, but because of its bandwidth/CPU performance ratio it is now
making a comeback. G.726 is especially attractive because it does not require a lot of
computational work from the system.
G.729A
Considering how little bandwidth it uses, G.729A delivers impressive sound quality. It
does this through the use of Conjugate-Structure Algebraic-Code-Excited Linear Prediction
(CS-ACELP).‖ Because of patents, you can’t use G729A without paying a
licensing fee; however, it is extremely popular and is, thus, well supported on many
different phones and systems.
To achieve its impressive compression ratio, this codec requires an equally impressive
amount of effort from the CPU. In an Asterisk system, the use of heavily compressed
codecs will quickly bog down the CPU.
G.729A uses 8 Kbps of bandwidth.
GSM
GSM is the darling codec of Asterisk. This codec does not come encumbered with a
licensing requirement the way that G.729A does, and it offers outstanding performance
with respect to the demand it places on the CPU. The sound quality is generally considered
to be of a lesser grade than that produced by G.729A, but much of this comes
down to personal opinion; be sure to try it out. GSM operates at 13 Kbps.
‖ CELP is a popular method of compressing speech. By mathematically modeling the various ways humans
make sounds, a codebook of sounds can be built. Rather than sending an actual sampled sound, a code
corresponding to the sound is determined. CELP codecs take this information (which by itself would produce
a very robot-like sound) and attempt to add the personality back in. (Of course, there is much more to it than
that.) Jason Woodward’s Speech Coding page (http://www-mobile.ecs.soton.ac.uk/speech_codecs/) is a source
of helpful information for the non-mathematically inclined. This is fairly heavy stuff, though, so wear your
thinking cap.
Codecs | 195
iLBC
The Internet Low Bitrate Codec (iLBC) provides an attractive mix of low bandwidth
usage and quality, and it is especially well suited to sustaining reasonable quality on
lossy network links.
Naturally, Asterisk supports it (and support elsewhere is growing), but it is not as
popular as the ITU codecs and, thus, may not be compatible with common IP telephones
and commercial VoIP systems. IETF RFCs 3951 and 3952 have been published
in support of iLBC, and iLBC is on the IETF standards track.
Because iLBC uses complex algorithms to achieve its high levels of compression, it has
a fairly high CPU cost in Asterisk.
While you are allowed to use iLBC without paying royalty fees, the holder of the iLBC
patent, Global IP Sound (GIPS), wants to know whenever you use it in a commercial
application. The way you do that is by downloading and printing a copy of the iLBC
license, signing it, and returning it to GIPS. If you want to read about iLBC and its
license, you can do so at http://www.ilbcfreeware.org.
iLBC operates at 13.3 Kbps (30 ms frames) and 15.2 Kbps (20 ms frames).
Speex
Speex is a variable bitrate (VBR) codec, which means that it is able to dynamically
modify its bitrate to respond to changing network conditions. It is offered in both
narrowband and wideband versions, depending on whether you want telephone quality
or better.
Speex is a totally free codec, licensed under