www.it-ebooks.info www.it-ebooks.info Russell Bryant, Leif Madsen, and Jim Van Meggelen FOURTH EDITION Asterisk™: The Definitive Guide www.it-ebooks.info Asterisk™: The Definitive Guide, Fourth Edition by Russell Bryant, Leif Madsen, and Jim Van Meggelen Copyright © 2013 Russell Bryant, Leif Madsen, and Jim Van Meggelen. All rights reserved. Printed in the United States of America. Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472. O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://my.safaribooksonline.com). For more information, contact our corporate/ institutional sales department: 800-998-9938 or corporate@oreilly.com. Editors: Mike Loukides and Nathan Jepson Production Editor: Kristen Borg Copyeditor: Becca Freed Proofreader: Kiel Van Horn Indexer: Fred Brown Cover Designer: Karen Montgomery Interior Designer: David Futato Illustrator: Rebecca Demarest May 2013: Fourth Edition Revision History for the Fourth Edition: 2013-05-07: First release See http://oreilly.com/catalog/errata.csp?isbn=9781449332426 for release details. Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of O’Reilly Media, Inc. Asterisk: The Definitive Guide, the image of a starfish, and related trade dress are trademarks of O’Reilly Media, Inc. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O’Reilly Media, Inc., was aware of a trade‐ mark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. ISBN: 978-1-449-33242-6 [LSI] www.it-ebooks.info Table of Contents Foreword. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv 1. A Telephony Revolution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Asterisk and VoIP: Bridging the Gap Between Traditional and Network Telephony 2 The Zapata Telephony Project 2 Massive Change Requires Flexible Technology 3 Asterisk: The Hacker’s PBX 4 Asterisk: The Professional’s PBX 5 The Asterisk Community 5 The Asterisk Mailing Lists 6 Asterisk Wiki Sites 7 The IRC Channels 7 Asterisk User Groups 7 The Asterisk Documentation Project 8 The Business Case 8 Conclusion 8 2. Asterisk Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Modules 10 Applications 12 Bridging Modules 15 Call Detail Recording Modules 16 Channel Event Logging Modules 17 Channel Drivers 17 Codec Translators 18 Format Interpreters 19 Dialplan Functions 20 iii www.it-ebooks.info PBX Modules 22 Resource Modules 22 Add-on Modules 26 Test Modules 27 File Structure 27 Configuration Files 27 Modules 27 The Resource Library 28 The Spool 28 Logging 28 The Dialplan 28 Hardware 29 Asterisk Versioning 29 Previous Release Methodologies 30 The Current Release Methodology 31 Simplifying the Version Numbers 32 Conclusion 33 3. Installing Asterisk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Installation Cheat Sheet 37 Distribution Installation 41 RHEL Server 41 Ubuntu Server 45 Software Dependencies 49 Downloading What You Need 50 Getting the Source via Subversion 51 Getting the Source via wget 51 How to Install It 52 DAHDI 52 LibPRI 54 Asterisk 55 Setting File Permissions 56 Base Configuration 56 Initial Configuration 56 make menuselect 64 Updating Asterisk 70 Common Issues 72 -bash: wget: command not found 73 configure: error: no acceptable C compiler found in $PATH 73 make: gcc: command not found 73 configure: error: C++ preprocessor “/lib/cpp” fails sanity check 73 iv | Table of Contents www.it-ebooks.info configure: error: *** Please install GNU make. It is required to build Asterisk! 73 configure: *** XML documentation will not be available because the ‘libxml2’ development package is missing. 74 configure: error: *** termcap support not found 74 You do not appear to have the sources for the 2.6.18-164.6.1.el5 kernel installed. 74 E: Unable to lock the administration directory (/var/lib/dpkg/), are you root? 74 Upgrading Asterisk 74 Conclusion 76 4. Initial Configuration Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 asterisk.conf 77 The [directories] Section 77 The [options] Section 78 The [files] Section 82 The [compat] Section 82 modules.conf 83 The [modules] Section 84 indications.conf 84 musiconhold.conf 86 Converting Music to a Format That Works Best with Asterisk 87 Default musiconhold.conf file 89 Additional Configuration Files 91 Conclusion 91 5. User Device Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Telephone Naming Concepts 94 Hardphones, Softphones, and ATAs 96 Configuring Asterisk 98 How Channel Configuration Files Work with the Dialplan 99 sip.conf 101 iax.conf 107 Modifying Your Channel Configuration Files for Your Environment 112 Digium Phones with Asterisk 113 Loading Your New Channel Configurations 113 The Asterisk CLI 113 Testing to Ensure Your Devices Have Registered 114 Analog Phones 115 A Basic Dialplan to Test Your Devices 118 Under the Hood: Your First Call 119 Table of Contents | v www.it-ebooks.info Conclusion 120 6. Dialplan Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Dialplan Syntax 121 Contexts 122 Extensions 124 Priorities 125 Applications 127 The Answer(), Playback(), and Hangup() Applications 128 A Simple Dialplan 129 Hello World 129 Building an Interactive Dialplan 131 The Goto(), Background(), and WaitExten() Applications 131 Handling Invalid Entries and Timeouts 133 Using the Dial() Application 134 Using Variables 137 Pattern Matching 140 Includes 145 Conclusion 145 7. Outside Connectivity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 The Basics of Trunking 147 Fundamental Dialplan for Outside Connectivity 148 PSTN Circuits 150 Traditional PSTN Trunks 150 Installing PSTN Trunks 152 VoIP 161 Coping with Network Address Translation 161 PSTN Termination 170 PSTN Origination 171 VoIP to VoIP 173 Configuring VoIP Trunks 173 Emergency Dialing 181 Conclusion 183 8. Voicemail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 Comedian Mail 185 The [general] Section 186 The [zonemessages] Section 195 The Contexts Section 196 An Initial voicemail.conf File 200 Standard Voicemail KeyMap 201 vi | Table of Contents www.it-ebooks.info Dialplan Integration 201 The V oiceMail() Dialplan Application 201 The VoiceMailMain() Dialplan Application 204 Creating a Dial-by-Name Directory 205 Using a Jitterbuffer 205 Storage Backends 206 Linux Filesystem 206 ODBC 207 IMAP 207 Using Asterisk as a Standalone Voicemail Server 208 Integrating Asterisk into a SIP Environment as a Standalone Voicemail Server 208 SMDI (Simplified Message Desk Interface) 212 Database Integration 213 Conclusion 213 9. Internationalization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 Devices External to the Asterisk Ser ver 217 PSTN Connectivity, DAHDI, Digium Cards, and Analog Phones 219 DAHDI Drivers 221 Asterisk 224 Caller ID 224 Language and/or Accent of Prompts 225 Time/Date Stamps and Pronunciation 226 Conclusion—Easy Reference Cheat Sheet 228 10. Deeper into the Dialplan. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 Expressions and V ariable Manipulation 231 Basic Expressions 231 Operators 232 Dialplan Functions 234 Syntax 235 Examples of Dialplan Functions 235 Conditional Branching 236 The GotoIf() Application 236 Time-Based Conditional Branching with GotoIfTime() 240 Macros 242 Defining Macros 243 Calling Macros from the Dialplan 244 Using Arguments in Macros 245 GoSub 246 Defining Subroutines 246 Table of Contents | vii www.it-ebooks.info Calling Subroutines from the Dialplan 247 Using Arguments in Subroutines 248 Returning from a Subroutine 249 Local Channels 250 Using the Asterisk Database (AstDB) 253 Storing Data in the AstDB 254 Retrieving Data from the AstDB 254 Deleting Data from the AstDB 254 Using the AstDB in the Dialplan 255 Creating a Hot-Desking Application with AstDB 256 Handy Asterisk Features 261 Zapateller() 261 Call Parking 261 Conferencing with MeetMe() 263 Conferencing with ConfBridge() 264 Conclusion 266 11. Parking, Paging, and Conferencing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 features.conf 267 The [general] section 268 The [featuremap] Section 271 The [applicationmap] Section 272 Application Map Grouping 275 Parking Lots 276 Overhead and “Underchin” Paging (a.k.a. Public Address) 277 Places to Send Your Pages 278 Zone Paging 284 Advanced Conferencing 284 The [general] Section 285 Options for User Profiles 285 Options for Bridge Profiles 287 ConfBridge Menu Options 289 Enabling a PIN 290 Waiting for the Marked User to Join 292 Using ConfBridge() Menus 293 Enabling Videoconferencing 296 Conclusion 298 12. Internet Call Routing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 DNS and SIP URIs 300 The SIP URI 300 SRV Records 301 viii | Table of Contents www.it-ebooks.info [...]... Smith and I started talking, causing the birth of the Asterisk Documentation Project, with the goal of writing an Asterisk book for the community That project became the basis of the first edition of this book, Asterisk: The Future of Telephony Eleven years later, I’m still writing Asterisk documentation, have become the primary bug marshal and release manager for the Asterisk project, have spoken at every... drag Asterisk can take credit for the fact that there are now entirely new, generational answers to the question, “can we make the phone system do this?” Incumbent telecom vendors, irrespective of the degree to which they view Asterisk as a competitor, have had to reframe their marketing message in terms of the possibilities that it has forced open Asterisk has changed the observational language the. .. to the following authors, they all came back with various viewpoints about the Asterisk soft‐ ware, and how it has changed the telecommunications industry and the lives of people We hope you enjoy reading about their contributions as much as we did Matt Jordan (Engineering Manager, Digium) When Leif asked me to write a foreword for the updated edition of Asterisk: The De‐ finitive Guide, he posed the. .. Asterisk can appear quite daunting and complex to a new user, which is why documen‐ tation 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 Definitive Guide is the fourth edition of what was formerly called Asterisk: The Future of Telephony We decided to change the. .. enough to be scared to death of voice The first reason for the fear of voice was that I knew how the Internet worked Voice is the canary in the coal mine that is the Internet—when the network breaks, the voice dies first The second reason to be afraid is that people are very familiar with phones, and therefore they have strong ideas about what phones should do to help run their business, and expect voice... As time passed and the telephony landscape changed, Asterisk changed with it Asterisk evolved with new functionality to meet the changing needs of the people who used and developed it At times, Asterisk has pushed the telephony industry; at times it has responded to it The result of this push and pull is the state of Asterisk today—it is in many things and in many places It powers the phone systems... know how to make the software do it, and I had no way to find out Luckily, there was only one book available to help at that time: Asterisk : The Future of Telephony That first version of this book helped me to quickly understand not only the Asterisk software, but the basics of VoIP The presentation allowed me to see how I could quickly combine the many and very flexible features of the Asterisk software... set out to write the very first edition of this book in 2004, we were confident that Asterisk was going to be a huge success Now, almost a decade later, we’ve written this fourth edition of what the worldwide Asterisk community calls The Asterisk Book,” and we’ve matured from revolutionaries into Asterisk professionals Asterisk has proven that open source telecom is a lasting idea, and the open source... questions about Asterisk The questions we were looking at included: • How has Asterisk helped in communities? • What worldly endeavors has Asterisk contributed to? • Where has Asterisk been and where is it going? • Why is Asterisk being deployed and what needs does it solve? These are all questions that most people who have used Asterisk for an extended period of time are either asked, or have asked themselves... is where we chop up the kindling and light the fire Welcome to Asterisk! Chapter 2, Asterisk Architecture Discusses the file structure of an Asterisk system Chapter 3, Installing Asterisk Covers obtaining, compiling, and installing Asterisk Chapter 4, Initial Configuration Tasks Describes some initial configuration tasks for your new Asterisk system This chap‐ ter goes over some of the configuration . 4 Asterisk: The Professional’s PBX 5 The Asterisk Community 5 The Asterisk Mailing Lists 6 Asterisk Wiki Sites 7 The IRC Channels 7 Asterisk User Groups 7 The Asterisk Documentation Project 8 The Business. Bryant, Leif Madsen, and Jim Van Meggelen FOURTH EDITION Asterisk : The Definitive Guide www.it-ebooks.info Asterisk : The Definitive Guide, Fourth Edition by Russell Bryant, Leif Madsen, and Jim. 1 Asterisk and VoIP: Bridging the Gap Between Traditional and Network Telephony 2 The Zapata Telephony Project 2 Massive Change Requires Flexible Technology 3 Asterisk: The Hacker’s PBX 4 Asterisk: