Asterisk™: The Definitive Guide Asterisk Guide, 4th Edition
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 845
www.it-ebooks.info
www.it-ebooks.info
FOURTH EDITION
Asterisk™: The Definitive Guide
Russell Bryant, Leif Madsen, and Jim Van Meggelen
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
May 2013:
Indexer: Fred Brown
Cover Designer: Karen Montgomery
Interior Designer: David Futato
Illustrator: Rebecca Demarest
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
The Zapata Telephony Project
Massive Change Requires Flexible Technology
Asterisk: The Hacker’s PBX
Asterisk: The Professional’s PBX
The Asterisk Community
The Asterisk Mailing Lists
Asterisk Wiki Sites
The IRC Channels
Asterisk User Groups
The Asterisk Documentation Project
The Business Case
Conclusion
2
2
3
4
5
5
6
7
7
7
8
8
8
2. Asterisk Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Modules
Applications
Bridging Modules
Call Detail Recording Modules
Channel Event Logging Modules
Channel Drivers
Codec Translators
Format Interpreters
Dialplan Functions
10
12
15
16
17
17
18
19
20
iii
www.it-ebooks.info
PBX Modules
Resource Modules
Add-on Modules
Test Modules
File Structure
Configuration Files
Modules
The Resource Library
The Spool
Logging
The Dialplan
Hardware
Asterisk Versioning
Previous Release Methodologies
The Current Release Methodology
Simplifying the Version Numbers
Conclusion
22
22
26
27
27
27
27
28
28
28
28
29
29
30
31
32
33
3. Installing Asterisk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Installation Cheat Sheet
Distribution Installation
RHEL Server
Ubuntu Server
Software Dependencies
Downloading What You Need
Getting the Source via Subversion
Getting the Source via wget
How to Install It
DAHDI
LibPRI
Asterisk
Setting File Permissions
Base Configuration
Initial Configuration
make menuselect
Updating Asterisk
Common Issues
-bash: wget: command not found
configure: error: no acceptable C compiler found in $PATH
make: gcc: command not found
configure: error: C++ preprocessor “/lib/cpp” fails sanity check
iv |
Table of Contents
www.it-ebooks.info
37
41
41
45
49
50
51
51
52
52
54
55
56
56
56
64
70
72
73
73
73
73
configure: error: *** Please install GNU make. It is required to build
Asterisk!
configure: *** XML documentation will not be available because the
‘libxml2’ development package is missing.
configure: error: *** termcap support not found
You do not appear to have the sources for the 2.6.18-164.6.1.el5 kernel
installed.
E: Unable to lock the administration directory (/var/lib/dpkg/), are you
root?
Upgrading Asterisk
Conclusion
73
74
74
74
74
74
76
4. Initial Configuration Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
asterisk.conf
The [directories] Section
The [options] Section
The [files] Section
The [compat] Section
modules.conf
The [modules] Section
indications.conf
musiconhold.conf
Converting Music to a Format That Works Best with Asterisk
Default musiconhold.conf file
Additional Configuration Files
Conclusion
77
77
78
82
82
83
84
84
86
87
89
91
91
5. User Device Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Telephone Naming Concepts
Hardphones, Softphones, and ATAs
Configuring Asterisk
How Channel Configuration Files Work with the Dialplan
sip.conf
iax.conf
Modifying Your Channel Configuration Files for Your Environment
Digium Phones with Asterisk
Loading Your New Channel Configurations
The Asterisk CLI
Testing to Ensure Your Devices Have Registered
Analog Phones
A Basic Dialplan to Test Your Devices
Under the Hood: Your First Call
Table of Contents
www.it-ebooks.info
94
96
98
99
101
107
112
113
113
113
114
115
118
119
|
v
Conclusion
120
6. Dialplan Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Dialplan Syntax
Contexts
Extensions
Priorities
Applications
The Answer(), Playback(), and Hangup() Applications
A Simple Dialplan
Hello World
Building an Interactive Dialplan
The Goto(), Background(), and WaitExten() Applications
Handling Invalid Entries and Timeouts
Using the Dial() Application
Using Variables
Pattern Matching
Includes
Conclusion
121
122
124
125
127
128
129
129
131
131
133
134
137
140
145
145
7. Outside Connectivity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
The Basics of Trunking
Fundamental Dialplan for Outside Connectivity
PSTN Circuits
Traditional PSTN Trunks
Installing PSTN Trunks
VoIP
Coping with Network Address Translation
PSTN Termination
PSTN Origination
VoIP to VoIP
Configuring VoIP Trunks
Emergency Dialing
Conclusion
147
148
150
150
152
161
161
170
171
173
173
181
183
8. Voicemail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Comedian Mail
The [general] Section
The [zonemessages] Section
The Contexts Section
An Initial voicemail.conf File
Standard Voicemail KeyMap
vi
|
Table of Contents
www.it-ebooks.info
185
186
195
196
200
201
Dialplan Integration
The VoiceMail() Dialplan Application
The VoiceMailMain() Dialplan Application
Creating a Dial-by-Name Directory
Using a Jitterbuffer
Storage Backends
Linux Filesystem
ODBC
IMAP
Using Asterisk as a Standalone Voicemail Server
Integrating Asterisk into a SIP Environment as a Standalone
Voicemail Server
SMDI (Simplified Message Desk Interface)
Database Integration
Conclusion
201
201
204
205
205
206
206
207
207
208
208
212
213
213
9. Internationalization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Devices External to the Asterisk Server
PSTN Connectivity, DAHDI, Digium Cards, and Analog Phones
DAHDI Drivers
Asterisk
Caller ID
Language and/or Accent of Prompts
Time/Date Stamps and Pronunciation
Conclusion—Easy Reference Cheat Sheet
217
219
221
224
224
225
226
228
10. Deeper into the Dialplan. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Expressions and Variable Manipulation
Basic Expressions
Operators
Dialplan Functions
Syntax
Examples of Dialplan Functions
Conditional Branching
The GotoIf() Application
Time-Based Conditional Branching with GotoIfTime()
Macros
Defining Macros
Calling Macros from the Dialplan
Using Arguments in Macros
GoSub
Defining Subroutines
231
231
232
234
235
235
236
236
240
242
243
244
245
246
246
Table of Contents
www.it-ebooks.info
|
vii
Calling Subroutines from the Dialplan
Using Arguments in Subroutines
Returning from a Subroutine
Local Channels
Using the Asterisk Database (AstDB)
Storing Data in the AstDB
Retrieving Data from the AstDB
Deleting Data from the AstDB
Using the AstDB in the Dialplan
Creating a Hot-Desking Application with AstDB
Handy Asterisk Features
Zapateller()
Call Parking
Conferencing with MeetMe()
Conferencing with ConfBridge()
Conclusion
247
248
249
250
253
254
254
254
255
256
261
261
261
263
264
266
11. Parking, Paging, and Conferencing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
features.conf
The [general] section
The [featuremap] Section
The [applicationmap] Section
Application Map Grouping
Parking Lots
Overhead and “Underchin” Paging (a.k.a. Public Address)
Places to Send Your Pages
Zone Paging
Advanced Conferencing
The [general] Section
Options for User Profiles
Options for Bridge Profiles
ConfBridge Menu Options
Enabling a PIN
Waiting for the Marked User to Join
Using ConfBridge() Menus
Enabling Videoconferencing
Conclusion
267
268
271
272
275
276
277
278
284
284
285
285
287
289
290
292
293
296
298
12. Internet Call Routing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
DNS and SIP URIs
The SIP URI
SRV Records
viii
|
300
300
301
Table of Contents
www.it-ebooks.info
Accepting Calls to Your System
Dialing SIP URIs from Asterisk
ENUM and E.164
E.164 and the ITU
ENUM
Asterisk and ENUM
ISN, ITAD, and freenum.org
Got ISN?
ITAD Subscriber Numbers (ISNs)
Management of Internet Numbering
IP Telephony Administrative Domains (ITADs)
Create a DNS Entry for Your ITAD
Testing Your ITAD
Using ISNs in Your Asterisk System
Security and Identity
Toll Fraud
Spam over Internet Telephony (SPIT)
Distributed Denial of Service Attacks
Phishing
Security Is an Ongoing Process
Conclusion
302
309
310
310
311
312
313
314
315
315
316
317
318
318
320
321
322
323
323
323
323
13. Automatic Call Distribution (ACD) Queues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Creating a Simple ACD Queue
Queue Members
Controlling Queue Members via the CLI
Defining Queue Members in the queues.conf File
Controlling Queue Members with Dialplan Logic
Automatically Logging Into and Out of Multiple Queues
An Introduction to Device State
The queues.conf File
The agents.conf File
Advanced Queues
Priority Queue (Queue Weighting)
Queue Member Priority
Changing Penalties Dynamically (queuerules.conf)
Announcement Control
Overflow
Using Local Channels
Queue Statistics: The queue_log File
326
331
331
333
333
335
339
341
349
351
351
353
354
356
361
363
367
Table of Contents
www.it-ebooks.info
|
ix
Conclusion
370
14. Device States. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Device States
Checking Device States
Extension States
Hints
Checking Extension States
SIP Presence
Asterisk Configuration
Using Custom Device States
An Example
Distributed Device States
Using Corosync
Using XMPP
Shared Line Appearances
Installing the SLA Applications
Configuration Overview
Key System Example with Analog Trunks
Key System Example with SIP Trunks
Alternate Key System Example with SIP Trunks
Shared Extension Example
Additional Configuration
Limitations
Creating a Callback Service
Conclusion
371
372
373
374
375
376
376
378
378
380
380
385
389
389
390
390
394
396
399
401
402
403
405
15. The Automated Attendant. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
An Auto Attendant Is Not an IVR
Designing Your Auto Attendant
The Greeting
The Main Menu
Timeout
Invalid
Dial by Extension
Building Your Auto Attendant
Recording Prompts
The Dialplan
Delivering Incoming Calls to the Auto Attendant
IVR
x
|
Table of Contents
www.it-ebooks.info
407
408
409
410
411
411
412
412
412
414
416
416
Conclusion
416
16. Relational Database Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
Installing and Configuring PostgreSQL and MySQL
Installing PostgreSQL for RHEL
Installing PostgreSQL for Ubuntu
Installing MySQL for RHEL
Installing MySQL for Ubuntu
Configuring PostgreSQL
Configuring MySQL
Installing and Configuring ODBC
Configuring ODBC for PostgreSQL
Configuring ODBC for MySQL
Configuring ODBC for Microsoft SQL
Validating the ODBC Connector
Compiling the ODBC Modules for Asterisk
Configuring res_odbc to Allow Asterisk to Connect Through ODBC
Managing Databases
Troubleshooting Database Issues
SQL Injection
Powering Your Dialplan with func_odbc
A Gentle Introduction to func_odbc
Getting Funky with func_odbc: Hot-Desking
Using Realtime
Static Realtime
Dynamic Realtime
Storing Call Detail Records (CDR)
ODBC Voicemail Message Storage
Compiling the app_voicemail Module to Support ODBC Storage
Creating the Large Object Type for PostgreSQL
ODBC Voicemail Storage Table Layout
Configuring voicemail.conf for ODBC Storage
Testing ODBC Voice Message Storage
Database Integration of ACD Queues
Storing queues.conf in a Database
Storing Dialplan Parameters for a Queue in a Database
Writing queue_log to Database
Conclusion
418
418
418
419
419
419
421
422
424
425
426
427
428
428
429
430
430
431
432
433
449
450
453
458
463
464
465
467
468
469
473
473
476
477
478
17. Interactive Voice Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
What Is IVR?
Components of an IVR
479
480
Table of Contents
www.it-ebooks.info
|
xi
IVR Design Considerations
Asterisk Modules for Building IVRs
CURL
func_odbc
AGI
AMI
A Simple IVR Using CURL
Installing the cURL Module
The Dialplan
A Prompt-Recording Application
Speech Recognition and Text-to-Speech
Text-to-Speech
Speech Recognition
Conclusion
482
483
483
483
483
483
483
484
484
484
486
486
486
487
18. External Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
Calendar Integration
Compiling Calendaring Support into Asterisk
Configuring Calendar Support for Asterisk
Triggering Calendar Reminders to Your Phone
Controlling Calls Based on Calendar Information
Writing Call Information to a Calendar
Additional Features
Voicemail IMAP Integration
Compiling IMAP Voicemail Support into Asterisk
Using XMPP (Jabber) with Asterisk
Compiling XMPP Support into Asterisk
Jabber Dialplan Commands
chan_motif
Out-of-Band Messaging (Messaging Infrastructure)
xmpp.conf Configuration
sip.conf Configuration
Dialplan Configuration
LDAP Integration
Configuring OpenLDAP
Compiling LDAP Support into Asterisk
Configuring Asterisk for LDAP Support
Text-to-Speech Utilities
Festival
Cepstral
xii
|
Table of Contents
www.it-ebooks.info
490
490
492
494
499
501
503
503
504
511
512
512
518
522
522
523
524
525
526
528
529
531
531
534
Conclusion
534
19. Fax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
What Is a Fax?
Ways to Handle Faxes in Asterisk
spandsp
Obtaining spandsp
Compiling and Installing spandsp
Adding the spandsp Library to Your libpath
Recompiling Asterisk with spandsp Support
Disabling spandsp (Should You Want to Test Digium Fax)
Digium Fax For Asterisk
Obtaining Digium FFA
Disabling Digium FFA (Should You Want to Test spandsp)
Incoming Fax Handling
Fax to TIFF
Fax to Email
Fax Detection
Using T.38
Outgoing Fax Handling
Transmitting a Fax from Asterisk
File Format for Faxing
An Experiment in Email to Fax
Fax Pass-Through
Using Fax Buffers in chan_dahdi.conf
T.38 Gateway
Conclusion
535
535
536
536
537
537
537
538
538
538
539
539
540
541
542
543
544
544
545
546
549
549
550
551
20. Asterisk Manager Interface (AMI). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
Quick Start
AMI over TCP
AMI over HTTP
Configuration
manager.conf
http.conf
Protocol Overview
Message Encoding
AMI over HTTP
Call Files
Example Usage
Originating a Call
Redirecting a Call
553
554
555
556
556
561
562
563
564
569
571
571
573
Table of Contents
www.it-ebooks.info
|
xiii
Originating a Call Using Python and StarPy
Development Frameworks
CSTA
Interesting Applications
Flash Operator Panel
Conclusion
574
579
580
580
580
581
21. Asterisk Gateway Interface (AGI). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
Quick Start
AGI Variants
Process-Based AGI
DeadAGI Is Dead
FastAGI—AGI over TCP
Async AGI—AMI-Controlled AGI
AGI Communication Overview
Setting Up an AGI Session
Commands and Responses
Ending an AGI Session
Example: Account Database Access
Development Frameworks
Conclusion
583
585
585
586
586
587
588
588
590
594
596
599
599
22. Clustering. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601
Traditional PBXs
Hybrid Systems
Pure Asterisk, Nondistributed
Asterisk and Database Integration
Single Database
Replicated Databases
Asterisk and Distributed Device States
Distributing Device States over a LAN
Distributing Device States over a WAN
Multiple Queues, Multiple Sites
Conclusion
602
603
605
606
606
608
609
610
611
613
614
23. Distributed Universal Number Discovery (DUNDi). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
How Does DUNDi Work?
The dundi.conf File
Configuring Asterisk for Use with DUNDi
General Configuration
Initial DUNDi Peer Definition
Creating Mapping Contexts
xiv
| Table of Contents
www.it-ebooks.info
617
619
621
622
623
625
Using Mapping Contexts with Peers
Allowing Remote Connections
Controlling Responses
Performing Lookups from the Dialplan
Conclusion
627
629
630
634
637
24. System Monitoring and Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639
logger.conf
Reviewing Asterisk Logs
Logging to the Linux syslog Daemon
Verifying Logging
Log Rotation
Call Detail Records
CDR Contents
Dialplan Applications
cdr.conf
Backends
Example Call Detail Records
Caveats
CEL (Channel Event Logging)
Channel Event Types
Channel Event Contents
Dialplan Applications
cel.conf
Backends
Example Channel Events
SNMP
Installing the SNMP Module for Asterisk
Configuring SNMP for Asterisk Using OpenNMS
Monitoring Asterisk with OpenNMS
Conclusion
639
641
642
643
643
643
644
645
645
646
653
653
654
654
655
656
657
657
663
668
668
669
672
673
25. Web Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
Flash Operator Panel
Queue Status and Reporting
Queue Status Display
Queue Reporting
Call Detail Records
A2Billing
Conclusion
676
676
677
677
677
678
678
26. Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679
Table of Contents
www.it-ebooks.info
|
xv
Scanning for Valid Accounts
Authentication Weaknesses
Fail2ban
Installation
Configuration
Encrypted Media
Dialplan Vulnerabilities
Securing Asterisk Network APIs
IAX2 Denial of Service
Other Risk Mitigation
CLI Permissions
Resources
Conclusion—A Better Idiot
679
681
681
682
683
687
687
689
689
691
693
694
694
27. Asterisk: A Future for Telephony. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695
The Problems with Traditional Telephony
Closed Thinking
Limited Standards Compliance
Slow Release Cycles
Refusing to Let Go of the Past and Embrace the Future
Paradigm Shift
The Promise of Open Source Telephony
The Itch that Asterisk Scratches
Open Architecture
Standards Compliance
Lightning-Fast Response to New Technologies
Passionate Community
Some Things that Are Now Possible
The Future of Asterisk
Speech Processing
High-Fidelity Voice
Video
WebRTC
Wireless
Unified Messaging
Peering
Challenges
Opportunities
695
696
697
697
698
698
698
698
699
700
700
700
701
705
705
706
707
709
709
710
710
711
714
A. Understanding Telephony. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
B. Protocols for VoIP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737
xvi
| Table of Contents
www.it-ebooks.info
C. Preparing a System for Asterisk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787
Table of Contents
www.it-ebooks.info
|
xvii
www.it-ebooks.info
Foreword
When we were thinking of who we could ask to write a foreword for the fourth edition
of the book, lots of names were tossed around. We had already had Mark Spencer (author
of Asterisk) write it for the first two editions of the book. Next, John Todd did a fantastic
job for the third edition. After batting around several names (of which you will see
below), we thought, “This is a book written by the community, how about we do a
community foreword?” With that idea in mind, we picked several people whom we
respect, and who have been using Asterisk as long as (if not longer than) ourselves.
When we were thinking of people, we wanted to get several perspectives and loosely
answer several 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. After posing those questions 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 following question: “Where has Asterisk been and where is
it going?” This means some prognostication is ahead—you’ve been warned!
To answer the first part, I looked at how Asterisk has evolved over the past several
versions. Each version has built upon the previous in an iterative fashion, while still
xix
www.it-ebooks.info
remaining true to what made Asterisk great: a free and open source platform to build
telephony applications. 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
of my local grocery store, drug store, and pizza chain—it is the engine of choice that
powers the PBXs of everyone from hobbyists to large enterprises.
The second part is trickier. As Asterisk nears its 15th birthday, the question in my mind
isn’t so much “where is Asterisk going,” but “where is the telephony industry going?”
The convergence of mobile platforms, hosted solutions, and WebRTC will fundamen‐
tally change not only our definition of a phone, but how businesses deploy their com‐
munication infrastructure and what it means to communicate. So how does Asterisk
respond to fundamental shifts in deployment, operability, and usage?
In my mind, the way it always has—by being innovative. By leading the way in adopting
standards for communication. By exposing new APIs that make it easier for anyone to
use Asterisk to build communication applications for a wide range of business needs.
And finally, by being willing to change. Asterisk has traditionally provided applications
for you—if you wanted call queues, you used the Queue application. If you wanted voice
mail, you used VoiceMail. As we go forward in the next major versions of Asterisk, I
see the emphasis being less on providing functionality for you and more on providing
the building blocks to build whatever communications functionality you need.
It is an exciting time to be a user and developer of Asterisk—and I look forward to
building Asterisk with you.
Alex Balashov (Principal, Evariste Systems)
Asterisk is most often celebrated for its free licensing and its generous feature set. How‐
ever, as most adopters of open source technology know, or quickly discover, it has im‐
plementation costs, too. The essential value of Asterisk does not, in my view, lie in the
economic or technical efficiency of a free PBX, but in the disruptive structural effect it
has had upon the larger domain of innovation in which it participates. It has irrevocably
shifted the conversation about possibilities in telephony.
Asterisk did not merely offer an open source challenge to incumbent PBX vendors. The
fact that it could run on commodity PC hardware and small, PC-compatible embedded
devices set off a tectonic shift toward the commoditization of business problems that
were previously solvable only by complex data interchange performed on expensive,
proprietary hardware or expensively licensed software, such as, for instance, interactive
voice response (IVR) systems that provide self-service interfaces to banks. Asterisk has
numerous integration pathways and APIs that allow it to connect to other commodity
xx
|
Foreword
www.it-ebooks.info
services using open standards and ubiquitous protocols, drastically lowering the cost
of making it talk to other systems. It is impossible to overstate the transformative impact
this has had, enabling entirely new business models to take flight, untethered by hitherto
prohibitive capital 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 vocabulary, the thought process,
the basic economic assumptions—of business telephony systems.
Asterisk’s interoperability and attachment to commodity hardware has also weakened
the walls of formidable fortresses of telecom monopoly that were previously thought
impregnable. I have witnessed its use with libss7 as an interconnection element by
competitive operators in several emerging-market countries, and as the backbone of
toll bypass applications and cost-efficient calling card services. The impact of this
Asterisk-driven pressure wave of innovative, low-cost alternatives is titanic, having cre‐
ated entirely new social connections, jobs, and livelihoods around the world, enriching
the lives of many people. My own family is scattered around the globe, and my Asterisk
PBX has made that world a whole lot smaller. We simply could not afford to commu‐
nicate so closely, regularly, and richly before.
In sum, I think that in the overall continuum of technological development, Asterisk
may well be remembered less for what is inside of it and more for what it has shoved
aside outside of it with its powerful elbows.
Kevin McAllister (VP of Engineering, CoreDial, LLC)
In the late summer of 2005 I was offered a job at a startup that planned to deliver hosted
IP PBX services to businesses. At the time I knew Linux system administration, IP
networking, and 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 service to be more reliable than electricity. I would be re‐
sponsible for trying to make feature after feature work under these demanding
circumstances.
The plan was to build on top of an existing prototype based on Asterisk. So not only
would I have the daunting task of pushing voice through my network, but also learning
how to use a complex piece of open source software that traditionally offers documen‐
tation that is incomplete and often inaccurate. So the situation was I didn’t know what
Foreword
www.it-ebooks.info
|
xxi
I wanted it to do, I didn’t 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 to build
complex and reliable features demanded by my customers.
Now—almost eight years and countless millions of successful calls later—I have learned
firsthand the things that do and do not work when building Internet VoIP systems. But
I continue to rely heavily on Asterisk and on the authors of this book to help me quickly
understand this constantly changing and improving software. You’ve chosen a great
starting point for working with Asterisk. I wish you even more success than I have had.
Brian Capouch (Computer Science Department, Saint
Joseph’s College [Indiana])
“Well, you can actually do that pretty easily.” That observation, over and over, burned
itself into my brain back when I first began hacking with Asterisk. I had already been
playing around—enjoying some success but suffering a lot of misery, too—with some
early IP telephony products, when one day I first saw mention of Asterisk on a mailing
list. I fetched the code and built it (before it was versioned!), and I’ll forever remember
the first sound I heard: Allison Smith’s “Comedian Mail” voice prompt. I laughed and
laughed. What was going on here??!!??
I dug in, and it changed my life. At the time, I operated a wireless ISP. It was an inde‐
scribable thrill that I was able to set up a network of Asterisk servers running on cheap
eBay hardware, connected to local telco lines at fifteen POPs scattered over 500 square
miles of mostly desolate Indiana farmland. I not only got my own wide-area toll-free
calling zone, it was free—back in the days when minutes actually cost something.
For another project, I hooked up Asterisk and a $20 USB camera I bought on eBay, and
got live video surveillance of an old railroad hotel I own in Medaryville, Indiana. It was
built in 1853, and had not yet been outfitted with modern electrical service. The system
ran off a marine battery that I replaced every few days.
Later on, one summer evening my friend Bob staged a faux break-in at the hotel while
I was giving a late-afternoon presentation at a technical conference in faraway Califor‐
nia. My audience and I watched the entrance door through a live feed from the camera,
and before the image of Bob’s entry had refreshed on the display monitor, a portable
SIP phone in my pocket rang, annunciating a “security situation” at my hotel. Asterisk
servers handled the call point-to-point between the hotel and the conference center.
xxii
|
Foreword
www.it-ebooks.info
Asterisk is about all kinds of telephony functionality, for all kinds of situations, perfectly
free for anyone to use. It’s another example of the way open source products not only
save a lot of money, but do a better job than the commercial products from the big
players. For me, Asterisk is about empowerment, about freedom from the dying tyranny
of the greedy monopolists, and about new worlds yet to come. No matter what new
communications trick you could think to try, the answer is likely, “Well, you can do that
pretty easily.” This book was created by great friends who were, like me, almost present
at the creation. They energetically and creatively maintain an invaluable, friendly, and
comprehensive guide to one of the greatest open source products ever. Enjoy!
Foreword
www.it-ebooks.info
|
xxiii
www.it-ebooks.info
Preface
This is a book for anyone who uses 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 com‐
pliance. No other private branch exchange (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
PBXs can scarcely dream of.
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 name because Asterisk has been so wildly successful that it is no
longer an up-and-coming technology. Asterisk has arrived.
This book was written for, and by, members of the Asterisk community.
Audience
This book is intended to be gentle toward 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).
xxv
www.it-ebooks.info
However, this book will also be useful for the more experienced Asterisk administrator.
We ourselves use the book as a reference for features that we haven’t used for a while.
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. 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 files required for all Asterisk installations.
Chapter 5, User Device Configuration
Provides guidance on configuring Asterisk to allow devices such as telephones to
connect and make calls.
Chapter 6, Dialplan Basics
Introduces the heart of Asterisk, the dialplan.
Chapter 7, Outside Connectivity
Discusses how to configure Asterisk to connect to other systems, such as other
Asterisk servers, Internet telephony service providers, or the plain old telephone
network.
Chapter 8, Voicemail
Covers using one of the most popular applications included with Asterisk, the voi‐
cemail system.
Chapter 9, Internationalization
Focuses on issues that an Asterisk administrator should be aware of when deploying
a system outside of North America.
Chapter 10, Deeper into the Dialplan
Goes over some more advanced dialplan concepts.
Chapter 11, Parking, Paging, and Conferencing
Describes the usage of popular telephony features included with Asterisk: call park‐
ing, paging, and conferencing.
xxvi
|
Preface
www.it-ebooks.info
Chapter 12, Internet Call Routing
Covers techniques for routing calls between different administrative domains on
the Internet.
Chapter 13, Automatic Call Distribution (ACD) Queues
Discusses how to build call queues in Asterisk.
Chapter 14, Device States
Introduces the concept of device states and how they can be used as presence
indicators.
Chapter 15, The Automated Attendant
Covers how to build a menuing system using the Asterisk dialplan.
Chapter 16, Relational Database Integration
Discusses various ways that Asterisk can be integrated with a database.
Chapter 17, Interactive Voice Response
Goes over how Asterisk can be used to build applications that act on input provided
by a caller.
Chapter 18, External Services
Provides instructions on how to connect to external services including LDAP, cal‐
endars, IMAP for voicemail, XMPP, out-of-band messaging, and text-to-speech.
Chapter 19, Fax
Discusses the various options for integrating sending and receiving faxes with an
Asterisk system.
Chapter 20, Asterisk Manager Interface (AMI)
Introduces a network API for monitoring and controlling an Asterisk system.
Chapter 21, Asterisk Gateway Interface (AGI)
Introduces the Asterisk API that allows call control to be implemented in any pro‐
gramming language.
Chapter 22, Clustering
Discusses a number of approaches for clustering multiple Asterisk servers together
once the demands of a deployment exceed the capabilities of a single server.
Chapter 23, Distributed Universal Number Discovery (DUNDi)
Covers a peer-to-peer protocol native to Asterisk that can be used for call routing.
Chapter 24, System Monitoring and Logging
Introduces some of the interfaces available for logging and monitoring an Asterisk
system.
Chapter 25, Web Interfaces
A survey of some of the web interfaces that complement an Asterisk installation.
Preface
www.it-ebooks.info
|
xxvii
Chapter 26, Security
Discusses some common security issues that Asterisk administrators should be
aware of.
Chapter 27, Asterisk: A Future for Telephony
In conclusion, we discuss some of the things we expect to see from open source
telephony in the near future.
Appendix A, Understanding Telephony
Explores the technologies in use in traditional telecom networks.
Appendix B, Protocols for VoIP
Delves into all the particularities of Voice over IP.
Appendix C, Preparing a System for Asterisk
Contains information you should be aware of and take into consideration when
planning an Asterisk deployment.
Software
This book is focused on documenting Asterisk version 11; however, many of the con‐
ventions and much of the information in this book is version-agnostic. Linux is the
operating system we have run and tested Asterisk on, and we have documented instal‐
lation instructions for both Red Hat Enterprise Linux (RHEL) and Ubuntu (Debianbased) where they differ from each other.
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 package names, as well as Unix utilities, commands, modules,
parameters, and arguments.
Constant width
Used to display code samples, file contents, command-line interactions, database
commands, library names, and options.
Constant width bold
Indicates 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.
xxviii
| Preface
www.it-ebooks.info
[ 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, if this book includes code
examples, you may use the code 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 ex‐
ample 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 Definitive Guide, Fourth Ed‐
ition, by Russell Bryant, Leif Madsen, and Jim Van Meggelen (O’Reilly). Copyright 2013
Russell Bryant, Leif Madsen, and Jim Van Meggelen, 978-1-449-332342-6.”
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
Safari Books Online (www.safaribooksonline.com) is an on-demand
digital library that delivers expert content in both book and video
form from the world’s leading authors in technology and business.
Technology professionals, software developers, web designers, and business and crea‐
tive professionals use Safari Books Online as their primary resource for research, prob‐
lem solving, learning, and certification training.
Preface
www.it-ebooks.info
|
xxix
Safari Books Online offers a range of product mixes and pricing programs for organi‐
zations, government agencies, and individuals. Subscribers have access to thousands of
books, training videos, and prepublication manuscripts in one fully searchable database
from publishers like O’Reilly Media, Prentice Hall Professional, Addison-Wesley Pro‐
fessional, Microsoft Press, Sams, Que, Peachpit Press, Focal Press, Cisco Press, John
Wiley & Sons, Syngress, Morgan Kaufmann, IBM Redbooks, Packt, Adobe Press, FT
Press, Apress, Manning, New Riders, McGraw-Hill, Jones & Bartlett, Course Technol‐
ogy, and dozens more. For more information about Safari Books Online, please visit us
online.
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://bit.ly/asterisk_tdg_4E.
To comment or ask technical questions about this book, send email to bookques
tions@oreilly.com.
For more information about our books, courses, conferences, and news, see our website
at http://www.oreilly.com.
Find us on Facebook: http://facebook.com/oreilly
Follow us on Twitter: http://twitter.com/oreillymedia
Watch us on YouTube: http://www.youtube.com/oreillymedia
Acknowledgments
To David Duffett, thanks for the excellent chapter on internationalization, which would
not have been served well by being written by us North Americans.
Next, we want to thank our fantastic editor, Michael Loukides, for your patience with
the first, second, and third editions of this book, which took too long to get off the
ground, and many long months to finally get written. Mike offered invaluable feedback
and found incredibly tactful ways to tell us to rewrite a section (or chapter) when it was
needed, and make us think it was our idea. Mike built us up when we were down, and
xxx
|
Preface
www.it-ebooks.info
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.
Also thanks to 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.
During the course of writing this book, we had the pleasure of being able to consult with
many people with specific experience in various areas. Their generous contributions of
time and expertise were instrumental in our research. Thanks to Randy Resnick, or‐
ganizer of the VoIP User Group; Kevin Fleming; Lee Howard, author of iaxmodem and
hylafax; Joshua Colp of Digium; Phillip Mullis of the Toronto Asterisk Users Group;
Allison Smith, the Voice of Asterisk; Flavio E. Goncalves, author of books on Asterisk,
OpenSER, and OpenSIPS; J. Oquendo, Security Guru; Tzafrir Cohen, font of knowledge
about security and lots of other stuff; Jeff Gehlbach, for SNMP; Ovidiu Sas, for your
encyclopedic knowlege of SIP; Tomo Takebe, for some SMDI help; Michael S. White
and e4 Strategies for Polycom hardware; Steve Underwood, for help with fax and
spandsp; and Richard Genthner and John Covert, for helping with LDAP; Kinsey Moore
for reviewing the Python AMI example; Lisa Ulevich, who helped Alex Balashov with
his foreword contribution; and to Kevin McAllister, for letting the authors play on his
Minecraft server.
Additionally, we’d like to thank Tilghman Lesher for helping to update the chapter on
that which will not die, fax, and for providing solid review of other sections of the book.
A special thanks should also go to John Todd for being one of the first to write com‐
prehensive Asterisk how-tos, all those years ago, and for all the many other things you
do (and have done) for the Asterisk community.
Open Feedback Publishing System (OFPS)
While we were writing this book, we used the O’Reilly Open Feedback Publishing System
(OFPS), which allowed our book to appear on the Web as we were writing it. Community
members were able to submit feedback and comments, which was of enormous help to
us. The following is a list of their names or handles:1
Matthew McAughan, Matt Pusateri, David Van Ginneken, Asterisk Mania, Jared Smith,
Jason Parker, Giovanni Vallesi, Mark Petersen, thp4, David Row, tvc123, Frederic Jean,
John Todd, Steven Sokol, Laurent Steffan, Robert Dailey, Howard Harper, Joseph
Rensin, Howard White, Jay Eames, Vincent Thomasset, Dave Barnow, Sebastien Dio‐
nne, Igor Nikolaev, Arend van der Kolk, Anwar Hossain, craigesmith, nkabir, anest,
Nicholas Barnes, Alex Neuman, Justin Korkiner, Stefan Schmidt, Paul Belanger,
1. We tried wherever possible to include the contributors’ names, but in some cases could not, and therefore
included their handles instead.
Preface
www.it-ebooks.info
|
xxxi
jfinstrom, Rod Montgomery, Shae Erisson, Gaston Draque, Richard Genthner, Michael
S Collins, JoeBobCooter, reconwireless, prepro, stgnet, Mathieu D., Jeff Peeler, Billy
Chia, Antti Kallaskari, Alan Graham, Mark Petersen, and Walter Doekes.
A special thanks to Matt Jordan for an in-depth review of AMI and other sections of the
fourth edition of the book.
Thanks to all of you for your valuable contribution to this book.
Thanks to Sean Bright, Ed Guy, Simon Ditner, and Paul Belanger for assisting us with
clarifying best practices for user and group policies for Asterisk installation. In the past
it was common to just install Asterisk with root permissions, but we have elected to
describe an installation process that is more in keeping with Linux best practices
(without starting a holy war!), and these fine gents contributed to our discussions on
that.
Kudos to all the folks working on the FreeSWITCH, YATE, SER, Kamailio, OpenSIPS,
SER, sipXecs, Woomera, and any other open source telecom projects, for stimulating
new thoughts, and for pushing the envelope.
Everyone in the Asterisk community also needs to thank Jim Dixon for creating the first
open source telephony hardware interfaces, starting the revolution, and giving his cre‐
ations to the community at large.
Finally, and most importantly, thanks go to Mark Spencer, the original author of Asterisk
and founder of Digium, for Asterisk, for Pidgin, and for contributing his creations to
the open source community. Asterisk is your legacy!
Leif Madsen
It sort of amazes me where I started with Asterisk, and where I’ve gone with it. In 2002,
while attending school, a bunch of friends and myself were experimenting with voice
over the Internet using Microsoft’s MSN product. It worked quite well, and allowed us
to play video games while conversing with each other—at least, until we wanted to add
a third participant. So, I went out searching for some software that could handle multiple
voices (the word was conferencing, but I didn’t even know that at the time, having had
little exposure to PBX platforms). I searched the Internet but didn’t find anything in
particular I liked (or that was free).2 I turned to IRC and explained what I was looking
for. Someone (I wish I knew who) mentioned that I should check out some software
called Asterisk (he presumably must have thought I was looking for MeetMe(), which I
was).
2. Years later while playing an MMORPG (massively multiplayer online role-playing game), I learned about
applications such as TeamSpeak; it’s probably a good thing I didn’t find that first.
xxxii
|
Preface
www.it-ebooks.info
Having the name, I grabbed the software and started looking at what it could do. In‐
credibly, the functionality I was looking for, which I thought would be the entirety of
the software, was only one component in a sea of functionality. And having run a BBS
for years prior to going to college, the fact that I could install a PCI card and connect it
to the phone network was not lost on me. After a couple of hours of looking at the
software and getting it compiled, I started telling one of my teachers about the PCI cards
and how maybe we could get some for the classroom for labs and such (our classroom
had 30 computers at 10 tables of 3). He liked the idea and started talking to the program
coordinator, and within about 30 minutes an order had been placed for 20 cards. Pretty
amazing considering they were TDM400Ps decked out with four daughtercards, and
they had only heard about them an hour prior to that.
Then the obsession began. I spent every extra moment of that semester with a couple
of computers dedicated to Asterisk use. In those two months, I learned a lot. Then we
had a co-op break. I didn’t find any work immediately, so I moved home and continued
working on Asterisk, spending time on IRC, reading through examples posted by John
Todd, and just trying to wrap my head around how the software worked. Luckily, I had
a lot of help on IRC (for these were the days prior to any documentation on Asterisk),
and I learned a lot more during that semester.
Seeing that the people who took a great interest in Asterisk at the time had a strong
sense of community, it caused me to also want to contribute back. Having no practical
level of coding knowledge, I decided documentation would be something useful to start
doing. Besides, I had been writing a lot of papers at school, so I was getting better at it.
One night I put up a website called The Asterisk Documentation Assignment (TADA)
and started writing down any documentation I could. A couple of weeks later Jared
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 single
AstriCon since 2004 (at which Jared and I spoke about the Asterisk Documentation
Project; I still have the AsteriskDocs magnet his wife made), and become a consultant
specializing in database integration (thanks Tilghman for func_odbc) and clustering
(thanks Mark Spencer for DUNDi). I really love Asterisk and all that it’s allowed me to
do. I’m now the Lead Unified Communications Systems Engineer at Thinking Phone
Networks, where I get to continue building and enhancing a huge breadth of telecom‐
munications functionality.
First, thanks to my parents Rick and Carol, for the understanding and support in ev‐
erything I’ve done in my life. From the first computer they purchased for far too much
money when I was in grade 6 (I started taking an interest in computers in grade 2 using
a Commodore 64, and they got me a computer after a parent-teacher interview a few
Preface
www.it-ebooks.info
|
xxxiii
years later) to letting me use the home phone line for my BBS endeavors (and eventually
getting me my own phone line), and everything else they have ever done for me, I can
never thank them enough. I love you both more than you’ll ever imagine.
Thanks to my Grandma T for letting me use her 286 during the years when I didn’t have
a computer at home, and for taking me shopping every year on my birthday for 15 years.
Love lots!
To my beautiful wife, Danielle, for setting the alarm every morning before she left for
work, letting me sleep those extra 10 minutes before starting on this book, and under‐
standing when I had to work late because I went past my 9 A.M. stop-writing time, thank
you and I love you so much. (Also to our soon-to-be-born son, who helped me put a
firm date on delivery of the draft of this book :))
There are so many people who help me and teach me new things every day, but the most
influential on my life in Asterisk are the following: Mark Spencer for writing software
that has given me a fantastic career; John Todd for his early examples; Brian K. West for
his early help and enthusiasm on IRC; Steve Sokol and Olle Johansson for flying me to
my first AstriCon (and subsequent ones!) and letting me be part of the first Asterisk
training classes; Jared Smith for helping start the documentation project and doing all
the infrastructure that I could never have done; Jim Van Meggelen for joining in early
on the project and teaching me new ways to look at life; and Russell Bryant for being a
great friend and confidant, for never breaking our FriendDA, and for not holding a
grudge about the bush.
Jim Van Meggelen
When we 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
telecom landscape is nowadays complemented by more than just Asterisk. Projects like
FreeSWITCH, sipXecs (from SIPfoundry), OpenSER/Kamailio/OpenSIPS, and many,
many more (and more to come) help to round out the ecosystem.
I want to take this opportunity to thank my very good friend Leif Madsen, who has been
with me through all four editions. In our daily lives, we don’t always have many oppor‐
tunities to work with each other (or even grab a pint, these days!), and it’s always a delight
to work with you. I also want to thank Russell Bryant, who joined us for this edition,
and whose dedication to this project and the Asterisk project in general is an inspiration
to me. You’re a Renaissance man, Russell. To Jared Smith, who helped found the Asterisk
Documentation Project and coauthored the first two editions with Leif and me (but has
since moved on to the Fedora project), I can only say: Asterisk’s loss is Fedora’s gain.
xxxiv
|
Preface
www.it-ebooks.info
I would like to thank my business partners at Core Telecom Innovations and iConverged
LLC, without whom I could not do all the cool things I get to do in my professional
career.
I would like to thank all my friends in the improv community, for helping me to keep
laughing at all the challenges that life presents.
Thanks to all my family, who bring love into my life.
Finally, thanks to you, the Asterisk community. This book is our gift to you. We hope
you enjoy reading it as much as we’ve enjoyed writing it.
Russell Bryant
I started working on Asterisk in 2004. I was a student at Clemson University and was
working as a co-op engineer at ADTRAN in Huntsville, Alabama. My first job at
ADTRAN was working in the Product Qualification department. I remember working
with Keith Morgan to use Asterisk as a VoIP traffic generator for testing QoS across a
router test network. Meanwhile, a fellow co-op and friend, Adam Schreiber, introduced
me to Mark Spencer. Over the next six months, I immersed myself in Asterisk. I learned
as much as I could about Asterisk, telephony, and C programming. When Asterisk 1.0
was released in the fall of 2004, I was named the release maintainer.
At the beginning of 2005, I was hired by Digium to continue my work on Asterisk
professionally. I spent seven amazing years working with Digium to improve Asterisk.
I worked as a software developer, a software team lead, and as the engineering manager
of the Asterisk development team. I am extremely grateful for the opportunity to con‐
tribute to so many areas of the Asterisk project. There are many people that deserve
thanks for the support they have provided along the way.
To my wife, Julie, I cannot thank you enough for all the love and support you have given
me. Thank you for keeping my life balanced and happy. You are the best. I love you!
To my parents, thank you for giving me so many great opportunities in my life to explore
different things and find what I really enjoy. You taught me to work hard and never give
up.
To Leif and Jim, thank you for your invitation to contribute to this book. It has been a
fun project, largely due to the pleasure of working with the two of you. Thanks for the
laughs and for your dedication to this book as a team effort.
I have learned a lot from many people at Digium. There are three people who stand out
the most as my mentors: Mark Spencer, Kevin P. Fleming, and David Deaton. Thank
you all for going the extra mile to teach me along the way. I am extremely grateful.
Preface
www.it-ebooks.info
|
xxxv
To the Asterisk development community, thank you all for your hard work and dedi‐
cation. I have learned a lot from you all. It has been a pleasure to work with you over
the years.
To Travis Axtell, thank you for your help in my early days of learning about Linux and
for being a good friend.
To my dogs, Chloe and Baxter, thanks for keeping me company while I worked on the
book every morning.
To all of my friends and family, thank you for your love, support, and fun times.
To the entire Asterisk community, thank you for using, enjoying, and contributing to
Asterisk. We hope you enjoy the book!
xxxvi
|
Preface
www.it-ebooks.info
CHAPTER 1
A Telephony Revolution
First they ignore you, then they laugh at you,
then they fight you, then you win.
—Mahatma Gandhi
When we first set out in 2004 to write a book about Asterisk, we confidently predicted
that Asterisk would fundamentally change the telecommunications industry. Today, the
revolution we predicted is all but complete. Asterisk is now the most successful private
branch exchange (PBX) in the world, and is an accepted (albeit perhaps not always
loved) technology in the telecom industry.
Unfortunately, over the past nine years the telecom industry has continued to lose its
way. The methods by which we communicate have changed. Whereas 20 years ago
phone calls were the preferred way to converse across distances, the current trend is to
message via text (email, IM, etc.). The phone call is seen as a bit of a dead thing, especially
by up-and-coming generations.
Asterisk remains pretty awesome technology, and we believe it is still one of the best
hopes for any sort of sensible integration between telecom and all the other technologies
businesses might want to interconnect with.
With Asterisk, no one is telling you how your phone system should work, or what
technologies you are limited to. If you want it, you can have it. Asterisk lovingly em‐
braces 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; on 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 thou‐
sands of ways to achieve a result, the process naturally requires extra effort. Perhaps it
1
www.it-ebooks.info
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.
Asterisk and VoIP: Bridging the Gap Between Traditional
and Network Telephony
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.
Technologies such as Asterisk lower the barriers to entry.
The Zapata Telephony Project
When the Asterisk project was started (in 1999), there were other open source telephony
projects in existence. However, Asterisk, in combination with the Zapata Telephony
Project, was able to provide public switched telephone network (PSTN) interfaces,
which represented an important milestone in transitioning the software from some‐
thing purely network-based to something more practical in the world of telecom at that
time, which was PSTN-centric.
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)1 would be handled in the CPU by software. While this would impose a tremen‐
dous 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‐
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
1. The term DSP also means digital signal processor, which is a device (usually a chip) that is capable of inter‐
preting and modifying signals of various sorts. In a voice network, DSPs are primarily responsible for en‐
coding, decoding, and transcoding audio information. This can require a lot of computational effort.
2
|
Chapter 1: A Telephony Revolution
www.it-ebooks.info
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 Tel‐
ephony 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.2
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 con‐
tribution, Asterisk’s public switched telephone network (PSTN) engine came to be.
Over the years, the Zapata Telephony interface in Asterisk has been modified and im‐
proved. The Digium Asterisk Hardware Device Interface (DAHDI) telephony interface
in use today is the offspring of Jim Dixon’s contribution.
Massive Change Requires Flexible Technology
Every PBX in existence suffers from 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.3
As with many other open source projects, such as Linux and so much of the critical
software running the Internet, the development of Asterisk was fueled by the dreams
of folks who knew that there had to be something more than what traditional industries
were producing. These people knew that if one could take the best parts of various PBXs
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
2. Jim Dixon, “The History of Zapata Telephony and How It Relates to the Asterisk PBX”.
3. We realize that the technology of the Internet formed out of government and academic institutions, but what
we’re talking about here is not the technology of the Internet so much as the cultural phenomenon of it, which
exploded in the early ’90s.
Massive Change Requires Flexible Technology
www.it-ebooks.info
|
3
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.4
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.5
Asterisk’s success can be directly attributed to nurturing 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 PBXs have a worldwide support
team comprising 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 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 telecommunica‐
tions industry needs a proper revolution.6
Asterisk is the catalyst.
Asterisk: The Hacker’s PBX
Telecommunications companies that 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.
The term hacker has, of course, been twisted by the mass media into meaning “malicious
cracker.” This is unfortunate, because the term actually existed long before the media
corrupted its meaning. 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
4. Between the releases of Asterisk 1.2 and Asterisk 1.4, over 4,000 updates were made to the code in the SVN
repository. Between the releases of Asterisk 1.4 and 1.8, over 10,000 updates were made.
5. 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 the FreePBX interface (and the
multitude of projects based on it). These interfaces—the VoIP-Info website can give you an idea of how many
there are—do not make it easier to learn Asterisk, because they separate you from the platform or dialplan
configuration, but many of them will deliver a working PBX to you much faster than the more hands-on
approach we employ in this book.
6. The telecom industry has been predicting a revolution since before the crash; time will tell how well it responds
to the open source revolution.
4
|
Chapter 1: A Telephony Revolution
www.it-ebooks.info
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 busi‐
ness 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.
• End users are fed up with incompatible and limited functionality, and horrible
support. Asterisk solves the first two problems; entrepreneurs 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 the fine folks at Digium, is keenly aware of the
cultural significance of Asterisk and has an optimistic view of the future.
One of the more powerful side effects of the Asterisk community’s energy is the coop‐
eration it has spawned among telecommunications, networking, and information tech‐
nology professionals who share a love for this phenomenon. While these cadres 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.
If the dream of Asterisk is to be realized, the community must continue to 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
Asterisk: The Professional’s PBX
www.it-ebooks.info
|
5
asked the kinds of questions whose answers can often be obtained independently, if one
is willing to devote some time to research and experimentation.
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 tribu‐
lations of others, many people who have become enthusiastic about this technology are
completely uninterested in such pursuits. They want a simple, straightforward, step-bystep guide that’ll get them up and running, followed by some sensible examples de‐
scribing 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 it includes people with many different skill sets and attitudes.
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.
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 three 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 list’s purpose is the discussion of de‐
veloping 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 specifically relating
to programming or development of the Asterisk code base. General coding ques‐
tions (such as queries on interfacing with AGI or AMI) should be directed to the
Asterisk-Users list.
6
|
Chapter 1: A Telephony Revolution
www.it-ebooks.info
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 de‐
velopment, and questions about interfacing your external pro‐
grams 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 Wiki Sites
Digium maintains a wiki for Asterisk at wiki.asterisk.org. This site is constantly kept up
to date by the Digium team, and scripts export the XML-based documentation from
the Asterisk source into the wiki itself, making you sure that the data you’re reading is
an accurate representation of the world.
An older wiki exists at www.voip-info.org, which is these days somewhat of an historical
curiosity, and a source of much enlightenment and confusion. While there is a massive
amount of information contained here, much of it is out of date.
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.7 To cut
down on spambot intrusions, both of these channels require registration to join. To
register, run /msg nickserv help when you connect to the service via your favorite IRC
client.
Asterisk User Groups
Over the past decade, in many cities 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 one another’s websites and welcome
members from anywhere. Type “Asterisk User Group” into Google to track down one
in your area.
7. 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 As‐
terisk via AGI or AMI are meant to be in #asterisk.
The Asterisk Community
www.it-ebooks.info
|
7
The Asterisk Documentation Project
The Asterisk Documentation Project was started by Leif Madsen and Jared Smith, but
several people in the community have contributed.
As part of the efforts of the Asterisk Docs project, this book has been released 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 communica‐
tions 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, 2002), 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.”
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 open‐
ness and the value of continuous innovation.
Conclusion
So where to begin? Well, when it comes to Asterisk, there is far more to talk about than
we can fit into one book. This book can only lay down the basics, but from this foun‐
dation you will be able to come to an understanding of the concept of Asterisk—and
from that, who knows what you will build?
8
|
Chapter 1: A Telephony Revolution
www.it-ebooks.info
CHAPTER 2
Asterisk Architecture
First things first, but not necessarily in that order.
—Doctor Who
Asterisk is very different from other, more traditional PBXs, in that the dialplan in
Asterisk treats all incoming channels in essentially the same manner.
In a traditional PBX, there is a logical difference between stations (telephone sets) and
trunks (resources that connect to the outside world). This means, for example, that you
can’t install an external gateway on a station port and route external calls to it without
requiring your users to dial the extension number first. Also, the concept of an off-site
resource (such as a reception desk) is much more difficult to implement on a traditional
PBX, because the system will not allow external resources any access to internal features.
To be fair, many traditional PBXs do offer this sort of functionality. However, it is gen‐
erally kludgy, limited in features, and requires complex, proprietary software to be in‐
stalled in the PBX (such as vendor-specific protocol extensions).
Asterisk, on the other hand, does not have an internal concept of trunks or stations. In
Asterisk, everything that comes into or goes out of the system passes through a channel
of some sort. There are many different kinds of channels; however, the Asterisk dialplan
handles all channels in a similar manner, which means that, for example, an internal
user can exist on the end of an external trunk (e.g., a cell phone) and be treated by the
dialplan in exactly the same manner as that user would be if she were on an internal
extension. Unless you have worked with a traditional PBX, it may not be immediately
obvious how powerful and liberating this is. Figure 2-1 illustrates the differences be‐
tween the two architectures.
9
www.it-ebooks.info
Figure 2-1. Asterisk versus PBX architecture
Modules
Asterisk is built on modules. A module is a loadable component that provides a specific
functionality, such as a channel driver (for example, chan_sip.so), or a resource that
allows connection to an external technology (such as func_odbc.so). Asterisk modules
are loaded based on the /etc/asterisk/modules.conf file. We will discuss the use of many
modules in this book. At this point we just want to introduce the concept of modules,
and give you a feel for the types of modules that are available.
It is actually possible to start Asterisk without any modules at all, although in this state
it will not be capable of doing anything. It is useful to understand the modular nature
of Asterisk in order to appreciate the architecture.
You can start Asterisk with no modules loaded by default and load each
desired module manually from the console, but this is not something
that you’d want to put into production; it would only be useful if you
were performance-tuning a system where you wanted to eliminate ev‐
erything not required by your specific application of Asterisk.
The types of modules in Asterisk include the following:
• Applications
• Bridging modules
• Call detail recording (CDR) modules
10
|
Chapter 2: Asterisk Architecture
www.it-ebooks.info
• Channel event logging (CEL) modules
• Channel drivers
• Codec translators
• Format interpreters
• Dialplan functions
• PBX modules
• Resource modules
• Add-on modules
• Test modules
In the following sections we will list each module available within these categories,
briefly identify its purpose, and give our opinion on its relative popularity and/or im‐
portance (while some modules are proven and deservedly popular, others are quite old,
are barely ever used anymore, and are only maintained for the purpose of backwardcompatibility). The details of how specific modules work will be covered in various
chapters throughout the book, depending on what the module is and what it does. Some
modules will be covered thoroughly; others may not be covered at all.
Regarding the Popularity/Status column in the tables that follow, the following list con‐
tains our opinions with respect to the meanings we have chosen (your mileage may
vary):
Insignificant
This module is ancient history. If you use it, be aware that you are mostly on your
own when it comes to any sort of community support.
Unreliable
This module is new or experimental, and is not suitable for production.
Useful
This module is current, maintained, popular, and recommended.
Usable
This module works but may be incomplete or unpopular, and/or is not recom‐
mended by the authors.
New
This module is quite new, and its completeness and popularity are difficult to gauge
at this time.
Deprecated
This module has been replaced by something that is considered superior.
Modules
www.it-ebooks.info
|
11
Limited
This module has limitations that may make it unsuitable to your requirements.
Essential
This module is one you’ll never want to be without.
In addition to our opinions on the various modules, there is also an official list of support
status types included within menuselect. Within each grouping of the module types, the
list is sorted by subgroups, such as:
core
Core modules that ship with Asterisk receive the greatest level of support. In ad‐
dition to community development, these are the modules that the Digium devel‐
opment team focus their efforts on. Asterisk is a vast piece of software, and in order
to maintain it effectively, the greatest amount of Digium-sponsored resources are
applied to the modules of this support level.
extended
Extended modules are those supported by the community. Finding issues and re‐
porting them to the issue tracker will continue to be triaged as with all issues filed,
but may not recieve a great amount of attention.
deprecated
Deprecated modules receive no support and are generally unmaintained. Modules
that fall into the deprecated category should have alternative modules in either
extended or core support status.
Instead of duplicating data that could go out of date quickly, we’ll point you to menu‐
select to obtain the official supported list. The status of the variable modules is also
dynamic among major releases of Asterisk, as new functionality is added and existing
modules are moved to extended and deprecated status.
And now, without further ado, let’s take a look at the modules, grouped by module type.
Applications
Dialplan applications are used in extensions.conf to define the various actions that can
be applied to a call. The Dial() application, for example, is responsible for making
outgoing connections to external resources and is arguably the most important dialplan
application. The available applications are listed in Table 2-1.
Table 2-1. Dialplan applications
Name
Purpose
Popularity/Status
app_adsiprog
Loads Analog Display Services Interface (ADSI) scripts into
compatible analog phones
Insignificant
app_alarmreceiver
Supports receipt of reports from alarm equipment
Insignificant
12
|
Chapter 2: Asterisk Architecture
www.it-ebooks.info
Name
Purpose
Popularity/Status
app_amd
Detects answering machines
Unreliable
app_authenticate
Compares dual-tone multifrequency (DTMF) input against a
provided string (password)
Useful
app_cdr
Writes ad hoc record to CDR
Useful
app_celgenuserevent Generates user-defined events for CEL
New
app_chanisavail
Unreliable
Checks the status of a channel
app_channelredirect Forces another channel into a different part of the dialplan
Useful
app_chanspy
Allows a channel to listen to audio on another channel
Useful
app_confbridge
Provides conferencing (new version)
Useful as of Asterisk 10,
Limited in Asterisk 1.8
app_controlplayback Plays back a prompt and offers fast forward and rewind functions
Useful
app_dahdibarge
Deprecated—see
Allows barging in on a DAHDI channel
app_chanspy
app_dahdiras
Creates a RAS (Remote Access Server) over a DAHDI channel (no
modem emulation)
Insignificant
app_db
Used to add/change/delete records in Asterisk’s built-in SQLite
database
Deprecated—see
app_dial
Used to connect channels together (i.e., make phone calls)
Essential
app_dictate
Plays back a recording and offers start/stop functions
func_db
Useful
app_directed_pickup Answers a call for another extension
Useful
app_directory
Presents the list of names from voicemail.conf
Useful
app_disa
Provides dialtone and accepts DTMF input
Usefula
app_dumpchan
Dumps channel variables to Asterisk command-line interface (CLI)
Useful
app_echo
Loops received audio back to source channel
Useful
app_exec
Contains Exec(), TryExec(), and ExecIf(); executes a
dialplan application based on conditions
Useful
app_externalivr
Controls Asterisk as with an AGI, only asynchronously
Useful
app_fax
Provides SendFax() and ReceiveFax()
Usefulb
app_festival
Enables basic text to speech using Festival TTS engine
Usable
app_flash
Performs a hook-switch flash on channels (primarily analog)
Useful
app_followme
Performs find me/follow me functionality based on followme.conf
Useful
app_forkcdr
Starts new CDR record on current call
Usable
app_getcpeid
Gets the ADSI CPE ID
Insignificant
app_ices
Sends audio to an Icecast server
Usable
app_image
Transmits an image to supported devices
Limited
app_ivrdemo
Sample application for developers
Insignificant
Modules
www.it-ebooks.info
|
13
Name
Purpose
Popularity/Status
app_jack
Works with JACK Audio Connection Kit to share audio between
compatible applications
Useful
app_macro
Triggers dialplan macros
Deprecated—see Go
Sub()
app_meetme
Provides multiparty conferencing
Useful—fully featured,
but deprecated in favor of
ConfBridge() as of
Asterisk 10 since Conf
Bridge() does not
require DAHDI.
app_milliwatt
Generates 1,004 Hz tone for testing loss on analog circuits
Useful
app_minivm
Provides primitive functions to allow you to build your own
voicemail application in dialplan
Usable
app_mixmonitor
Records both sides of a call and mixes them together
Useful
app_morsecode
Generates Morse code
Usable
app_mp3
Uses mpg123 to play an MP3
Insignificant
app_nbscat
Streams audio from Network Broadcast Stream (NBS)
Insignificant
app_originate
Allows origination of a call
Useful
app_osplookup
Performs Open Settlement Protocol (OSP) lookup
Usable
app_page
Creates multiple audio connections to specified devices for public
address (paging)
Useful
app_parkandannounce Enables automated announcing of parked calls
Usable
app_playback
Plays a file to the channel (does not accept input)
Useful
app_playtones
Plays pairs of tones of specified frequencies
Useful
app_privacy
Requests input of caller’s phone number if no CallerID is received
Insignificant
Useful
app_queue
Provides Automatic Call Distribution (ACD)
app_read
Requests input of digits from callers and assigns input to a variable Useful
app_readexten
Requests input of digits from callers and passes call to a
designated extension and context
Usable
app_readfile
Loads contents of a text file into a channel variable
Deprecated—see the
FILE() function in
app_record
Records received audio to a file
Useful
app_sayunixtime
Plays back time in specified format
Useful
func_env
app_senddtmf
Transmits DTMF to calling party
Useful
app_sendtext
Sends a text string to compatible channels
Insignificant
app_setcallerid
Sets CallerID on a channel
app_skel
14
|
Sample application for developers
Chapter 2: Asterisk Architecture
www.it-ebooks.info
Deprecated—see
func_callerid
Usefulc
Name
Purpose
Popularity/Status
app_sms
Sends SMS message in compatible countries
Limited
app_softhangup
Requests hangup of channel
Useful
app_speech_utils
Provides utilities relating to speech recognition
Usefuld
app_stack
Provides Gosub(), GoSubIf(), Return(), StackPop(),
LOCAL(), and LOCAL_PEEK()
Essential
app_system
Executes commands in a Linux shell
Useful
app_talkdetect
Similar to app_background, but allows for any received audio
to interrupt playback
Useful
app_test
Client/server testing application
Usable
app_transfer
Performs a transfer on the current channel
Useful
app_url
Passes a URI to the called channel
Limited
app_userevent
Generates a custom event in the Asterisk Manager Interface (AMI)
Useful
app_verbose
Generates a custom event in the Asterisk CLI
Useful
app_voicemail
Provides voicemail
Essential
app_waitforring
Waits for a RING signaling event (not to be confused with
RINGING); most likely unnecessary, as only chan_dahdi with
analog channels where ringing is received (such as an FXO port)
generates the RING signaling event
Insignificant
app_waitforsilence
Includes WaitForSilence() and WaitForNoise();
listens to the incoming channel for a specified number of
milliseconds of noise/silence
Useful
app_waituntil
Waits until current Linux epoch matches specified epoch
Useful
app_while
Includes While(), EndWhile(), ExitWhile(), and Con
tinueWhile(); provides while-loop functionality in the
Useful
dialplan
app_zapateller
Generates SIT (Special Information Tone) to discourage
telemarketers
Usable
a The use of (DISA) can be a security risk if you are not careful with dialplan access control.
b Requires a suitable DSP engine to handle encoding/decoding of fax signaling (see Chapter 19).
c If you are a developer.
d Requires an external speech recognition application.
Bridging Modules
Bridging modules perform the actual bridging of channels in the new bridging API.
Each provides different features, which get used in different situations depending on
what a bridge needs. These modules, listed in Table 2-2, are currently only used for (and
are essential to) app_confbridge.
Modules
www.it-ebooks.info
|
15
Table 2-2. Bridging modules
Name
Purpose
Popularity/Status
bridge_builtin_features Performs bridging when utilizing built-in user features (such as
New
those found in features.conf).
bridge_multiplexed
Performs complex multiplexing, as would be required in a large
conference room (multiple participants). Currently only used by
app_confbridge.
Useful
bridge_simple
Performs simple channel-to-channel bridging.
Useful
bridge_softmix
Performs simple multiplexing, as would be required in a large
conference room (multiple participants). Currently only used by
app_confbridge.
Useful
Call Detail Recording Modules
The CDR modules, listed in Table 2-3, are designed to facilitate as many methods of
storing call detail records as possible. You can store CDRs to a file (the default), a da‐
tabase, Remote Authentication Dial In User Service (RADIUS), or syslog.
Call detail records are not intended to be used in complex billing ap‐
plications. If you require more control over billing and call reporting,
you will want to look at channel event logging, discussed next. The
advantage of CDR is that it just works.
Table 2-3. Call detail recording modules
Name
Purpose
Popularity/Status
cdr_adaptive_odbc
Allows writing of CDRs through ODBC
framework with ability to add custom fields
Useful
cdr_csv
Writes CDRs to disk as a comma-separated
values file
Usable
cdr_custom
Writes CDRs to a CSV file, but allows addition Useful
of custom fields
cdr_manager
Outputs CDRs to Asterisk Manager Interface
(AMI)
Useful
cdr_odbc
Writes CDRs through ODBC framework
Usable
cdr_pgsql
Writes CDRs to PostgreSQL
Useful
cdr_radius
Writes CDRs to RADIUS
Usable—does not support custom fields
cdr_sqlite
Writes CDRs to SQLite2 database
Deprecated—use sqlite3_custom
cdr_sqlite3_custom
Writes CDRs to SQLite3 with custom fields
Useful
cdr_syslog
Writes CDRs to syslog
Useful
cdr_tds
Writes CDRs to Microsoft SQL or Sybase
Usable—requires an old version of libtds
16
|
Chapter 2: Asterisk Architecture
www.it-ebooks.info
We will discuss some reporting packages that you may wish to use with CDR in
Chapter 25.
Channel Event Logging Modules
Channel event logging (CEL) provides much more powerful control over reporting of
call activity. By the same token, it requires more careful planning of your dialplan, and
by no means will it work automatically. Asterisk’s CEL modules are listed in
Table 2-4.
Table 2-4. Channel event logging modules
Name
Purpose
Popularity/Status
cel_custom
CEL to disk/file
Useful
cel_manager
CEL to AMI
Useful
cel_odbc
CEL to ODBC
Useful
cel_pgsql
CEL to PostgreSQL
Useful
cel_radius
CEL to RADIUS
Usable—does not support custom fields
cel_sqlite3_custom CEL to SQLite3
cel_tds
Useful
CEL to Microsoft SQL or Sybase Usable—requires an old version of libtds
Channel Drivers
Without channel drivers, Asterisk would have no way to make calls. Each channel driver
is specific to the protocol or channel type it supports (SIP, ISDN, etc.). The channel
module acts as a gateway to the Asterisk core. Asterisk’s channel drivers are listed in
Table 2-5.
Table 2-5. Channel drivers
Name
Purpose
Popularity/Status
chan_agent
Provides agent channel for Queue()
Useful
chan_alsa
Provides connection to Advanced Linux Sound Architecture
Useful
chan_bridge
Used internally by the ConfBridge() application; should
not be used directly
Essentiala
chan_console
Utilizes the portaudio library to provide a cross-platform
console channel driver that uses the system sound device
Useful
chan_dahdi
Provides connection to PSTN cards that use DAHDI channel
drivers
Useful
chan_gtalk
Provides connection to Google Talk
Deprecated as of Asterisk 11—
see chan_motif
chan_h323
Provides connection to H.323 endpoints
Deprecated—see
chan_ooh323 in Table 2-17
Modules
www.it-ebooks.info
|
17
Name
Purpose
Popularity/Status
chan_iax2
Provides connection to IAX2 endpoints
Useful
chan_jingle
Provides connection to Jingle-enabled endpoints
Deprecated as of Asterisk 11—
see chan_motif
chan_local
Provides a mechanism to treat a portion of the dialplan as a
channel
Useful
chan_mgcp
Media Gateway Control Protocol channel driver
Usable
chan_misdn
Provides connection to mISDN-supported ISDN cards
Limited
chan_motif
Implements the Jingle protocol, including the ability to
connect to Google Talk and Google Voice; introduced in
Asterisk 11
Useful
chan_multicast_rtp Provides connection to multicast Realtime Transport Protocol
Useful
(RTP) streams
chan_nbs
Network Broadcast Sound channel driver
Insignificant
chan_oss
Open Sound System driver
Useful
chan_phone
Linux telephony interface driver (very old)
Insignificant
chan_sip
Session Initiation Protocol (SIP) channel driver
Essential
chan_skinny
Cisco Skinny Client Control Protocol (SCCP) channel driver
Usable
chan_unistim
Nortel Unistim protocol channel driver
Usable
a If you are using the ConfBridge() application.
Codec Translators
The codec translators (Table 2-6) allow Asterisk to convert audio stream formats be‐
tween calls. So if a call comes in on a PRI circuit (using G.711) and needs to be passed
out a compressed SIP channel (e.g., using G.729, one of many codecs that SIP can han‐
dle), the relevant codec translator would perform the conversion.1
If a codec (such as G.729) uses a complex encoding algorithm, heavy
use of transcoding can place a massive burden on the CPU. Speci‐
alized hardware for the decoding/encoding of G.729 is available
from hardware manufacturers such as Sangoma and Digium (and
likely others).
1. More information about what codecs are and how they work is available in “Codecs” on page 746.
18
|
Chapter 2: Asterisk Architecture
www.it-ebooks.info
Table 2-6. Codec translators
Name
Purpose
Popularity/Status
codec_adpcm
Adaptive Differential Pulse Coded Modulation (ADPCM) codec
Insignificant
codec_alaw
A-law PCM codec used all over the world (except Canada/USA) on the PSTN
Essential
codec_g729
Does not come with Asterisk due to the fact that it is not a public domain codec,
but can be purchased from Digium; a very popular codec if compression is desired
(and CPU use is not an issue)
Useful
codec_a_mu
A-law to mu-law direct converter
Useful
codec_dahdi
Utilizes proprietary Digium hardware transcoding card
Essentiala
codec_g722
Wideband audio codec
Useful
codec_g726
Flavor of ADPCM
Insignificant
codec_gsm
Global System for Mobile Communications (GSM) codec
Useful
codec_ilbc
Internet Low Bitrate Codec
Insignificant
codec_lpc10
Linear Predictive Coding vocoder (extremely low bandwidth)
Insignificant
codec_resample Resamples between 8-bit and 16-bit signed linear
Usable
codec_speex
Speex codec
Usable
codec_ulaw
Mu-law PCM codec used in Canada/USA on PSTN
Essential
a If you are using a Digium codec transcoder card.
Digium distributes some additional useful codec modules: co
dec_g729, codec_silk, codec_siren7, and codec_siren14. These co‐
dec modules are not open source for various reasons. You must pur‐
chase a license to use codec_g729, but the others are free. You can find
them on the Digium site.
Format Interpreters
Format interpreters (Table 2-7) perform the function of codec translators, but they do
their work on files rather than channels. If you have a recording on a menu that has
been stored as GSM, a format interpreter would need to be used to play that recording
to any channels not using the GSM codec.2
If you store a recording in several formats (such as WAV, GSM, etc.), Asterisk will
determine the least costly format3 to use when a channel requires that recording.
2. It is partly for this reason that we do not recommend the default GSM format for system recordings. WAV
recordings will sound better and use fewer CPU cycles.
3. Some codecs can impose a significant load on the CPU, such that a system that could support several hundred
channels without transcoding might be able to handle only a few dozen when transcoding is in use.
Modules
www.it-ebooks.info
|
19
Table 2-7. Format interpreters
Name
Plays files stored in
Popularity/Status
format_g723
G.723: .g723
Insignificant
format_g726
G.726: .g726
Insignificant
format_g729
G.729: .g729
Useful
format_gsm
RPE-LTP (original GSM codec): .gsm
Usable
format_h263
H.263—video: .h263
Usable
format_h264
H.264—video: .h264
Usable
format_ilbc
Internet Low Bitrate Codec: .ilbc
Insignificant
format_jpeg
Graphic file: .jpeg, .jpg
Insignificant
format _ogg_
vorbis
Ogg container: .ogg
Usable
format_pcm
Various Pulse-Coded Modulation
formats: .alaw, .al, .alw, .pcm, .ulaw, .ul, .mu, .ulw, .g722, .au
Useful
format_siren14
G.722.1 Annex C (14 kHz): .siren14
New
format_siren7
G.722.1 (7 kHz): .siren7
New
format_sln16
16-bit signed linear: .sln16
New
format_sln
8-bit signed linear: .sln, .raw
Useful
format_vox
.vox
Insignificant
format_wav
.wav
Useful
format_wav_gsm
GSM audio in a WAV container: .wav, .wav49
Usable
Dialplan Functions
Dialplan functions, listed in Table 2-8, complement the dialplan applications (see “Ap‐
plications” on page 12). They provide many useful enhancements to things like string
handling, time and date wrangling, and ODBC connectivity.
Table 2-8. Dialplan functions
Name
Purpose
Popularity/Status
func_aes
Encrypts/decrypts an AES string
Useful
func_audiohookinherit Allows calls to be recorded after transfer
Useful
func_base64
Encodes/decodes a base-64 string
Usable
func_blacklist
Writes/reads blacklist in astdb
Useful
func_callcompletion
Gets/sets call-completion configuration parameters for the channel
New
func_callerid
Gets/sets CallerID
Useful
func_cdr
Gets/sets CDR variable
Useful
func_channel
Gets/sets channel information
Useful
20
|
Chapter 2: Asterisk Architecture
www.it-ebooks.info
Name
Purpose
Popularity/Status
func_config
Includes AST_CONFIG(); reads variables from config file
Usable
func_connectedline
Changes connected-line information on supported handsets
New
func_curl
Uses cURL to obtain data from a URI
Useful
func_cut
Slices and dices strings
Useful
func_db
Provides astdb functions
Useful
func_devstate
Gets state of device
Useful
func_dialgroup
Creates a group for simultaneous dialing
Useful
func_dialplan
Validates that designated target exists in dialplan
Useful
func_enum
Performs ENUM lookup
Useful
func_env
Includes FILE(), STAT(), and ENV(); performs operating system
actions
Useful
func_extstate
Returns status of a hinted extension
Useful
func_global
Gets/sets global variables
Useful
func_groupcount
Gets/sets channel count for members of a group
Useful
func_hangupcause
Gets/sets hangupcause information from the channel
Useful
func_iconv
Converts between character sets
Usable
func_jitterbuffer
Includes the JITTERBUFFER() function, which allows you to place
a jitterbuffer on a channel.
Useful
func_lock
Includes LOCK(), UNLOCK(), and TRYLOCK(); sets a lock that can Useful
be used to avoid race conditions in the dialplan
func_logic
Includes ISNULL(), SET(), EXISTS(), IF(), IFTIME(), and
IMPORT(); performs various logical functions
Useful
func_math
Includes MATH(), INC(), and DEC(); performs mathematical
functions
Useful
func_md5
Converts supplied string to an MD5 hash
Useful
func_module
Checks to see if supplied module is loaded into memory
Usable
func_odbc
Allows dialplan integration with ODBC resources
Useful
func_pitchshift
Shifts the pitch of an audio stream
Useful
func_presencestate
Gets/sets presence state; this is primarily used by Asterisk integration
with Digium phones
Useful
func_rand
Returns a random number within a given range
Useful
func_realtime
Performs lookups within the Asterisk Realtime Architecture (ARA)
Useful
func_redirecting
Provides access to information about where this call was redirected
from
Useful
func_sha1
Converts supplied string to an SHA1 hash
Useful
func_shell
Performs Linux shell operations and returns results
Useful
func_speex
Reduces noise and performs dB gain/loss on an audio stream
Useful
Modules
www.it-ebooks.info
|
21
Name
Purpose
Popularity/Status
func_sprintf
Performs string format functions similar to C function of same name
Useful
func_srv
Performs SRV lookups in the dialplan
Useful
func_strings
Includes over a dozen string manipulation functions
Useful
func_sysinfo
Gets system information such as RAM, swap, load average, etc.
Useful
func_timeout
Gets/sets timeouts on channel
Useful
func_uri
Converts strings to URI-safe encoding
Useful
func_version
Returns Asterisk version information
Usable
func_vmcount
Returns count of messages in a voicemail folder for a particular user
Useful
func_volume
Sets volume on a channel
Useful
PBX Modules
The PBX modules are peripheral modules that provide enhanced control and config‐
uration mechanisms. For example, pbx_config is the module that loads the traditional
Asterisk dialplan. The currently available PBX modules are listed in Table 2-9.
Table 2-9. PBX modules
Name
Purpose
Popularity/Status
pbx_ael
Asterisk Extension Logic (AEL) offers a dialplan scripting language that looks like a
modern programming language.
Usablea
pbx_config
This is the traditional, and most popular, dialplan language for Asterisk. Without this
module, Asterisk cannot read extensions.conf.
Useful
pbx_dundi
Performs data lookups on remote Asterisk systems.
Useful
pbx_loopback Performs something similar to a dialplan include, but in a deprecated manner.
Insignificantb
pbx_lua
Useful
Allows creation of a dialplan using the Lua scripting language.
pbx_realtime Provides functionality related to the Asterisk Realtime Architecture.
Useful
pbx_spool
Useful
Provides outgoing spool support relating to Asterisk call files.
a We have not found too many people using AEL. We suspect this is because most developers will tend to use AGI/AMI if they do
not want to use traditional dialplans.
b We’ve never heard of this being used in production.
Resource Modules
Resource modules integrate Asterisk with external resources. This group of modules
has effectively turned into a catchall for things that do not fit in other categories. We
will break them into some subgroups of modules that are related.
22
|
Chapter 2: Asterisk Architecture
www.it-ebooks.info
Configuration backends
Asterisk is configured using text files in /etc/asterisk by default. These modules, listed
in Table 2-10, offer alternative configuration methods. See Chapter 16 for detailed doc‐
umentation on setting up database-backed configuration.
Table 2-10. Configuration backend modules
Name
Purpose
Popularity/Status
res_config_curl
Pulls configuration information using cURL
Useful
res_config_ldap
Pulls configuration information using LDAP
Usable
res_config_odbc
Pulls configuration information using ODBC
Useful
res_config_pgsql
Pulls configuration information using PostgreSQL
Usable
res_config_sqlite
Pulls configuration information using SQLite (version 2) Usable
res_config_sqlite3 Pulls configuration information using SQLite (version 3) Usable
Timing interfaces
Some operations in Asterisk require a timing source. These modules provide timing to
Asterisk from a variety of sources. Some cases where Asterisk needs a timing source
include file playback and conferencing using the ConfBridge() application.
A common point of confusion is assuming that conferencing using the
MeetMe() application also requires the use of one of these timing
sources. That is not the case. MeetMe() does not use the Asterisk timing
interface and instead uses DAHDI directly. While DAHDI provides a
timing interface, MeetMe() does not use it. DAHDI provides a full con‐
ferencing engine which is the core of the MeetMe() application.
If you are unable to use res_timing_dahdi for some reason, such as running on a
machine where you cannot add the DAHDI kernel modules, you should use res_tim
ing_timerfd. Avoid using the res_timing_pthread module if at all possible, as it is
much less efficient and will impact the performance of Asterisk. Table 2-11 lists the
timing interface modules.
Table 2-11. Timing interface modules
Name
Purpose
Popularity/Status
res_timing_dahdi
Provides timing using the DAHDI kernel interface
Useful
res_timing_kqueue
Provides timing using a kernel feature in some BSDs, including Mac OS X
res_timing_pthread Provides timing using only parts of the standard pthread API; less
Useful
Usable
efficient but more portable than other timing modules
res_timing_timerfd Provides timing using the timerfd API provided by newer versions of the
Useful
Linux kernel
Modules
www.it-ebooks.info
|
23
Calendar integration
Asterisk includes some integration with calendar systems. You can read and write cal‐
endar information from the dialplan. You can also have calls originated based on cal‐
endar entries. The core calendar integration is provided by the res_calendar module.
The rest of the modules provide the ability to connect to specific types of calendar
servers. Table 2-12 lists the calendar integration modules.
Table 2-12. Calendar integration modules
Name
Purpose
Popularity/Status
res_calendar
Enables base integration to calendaring systems
Useful
res_calendar_caldav
Allows features provided by res_calendar to connect to
calendars via CalDAV
Useful
res_calendar_exchange
Allows features provided by res_calendar to connect to MS
Exchange
Useful
res_calendar_icalendar Allows features provided by res_calendar to connect to Apple/
Useful
Google iCalendar
RTP implementations
The core of Asterisk does not include an RTP implementation. If you are using one of
the VoIP channel drivers that uses RTP, you must also load the res_rtp_asterisk
module. This RTP implementation could be replaced with a custom one if Asterisk was
used on a system that included custom hardware such as a DSP with more efficient RTP
processing.
The multicast RTP implementation is only used by the chan_multicast_rtp channel
driver, which is useful for paging a large number of phones. For more information on
multicast RTP, see Chapter 11. RTP implementation modules are listed in Table 2-13.
Table 2-13. RTP implementation modules
Name
Purpose
Popularity/Status
res_rtp_asterisk
Provides RTP
Essential
res_rtp_multicast Provides multicast RTP New
Format attribute handlers
One of the interfaces that an Asterisk module can implement is for processing attributes
associated with certain audio and video formats. The group of modules listed in
Table 2-14 implements that interface.
24
|
Chapter 2: Asterisk Architecture
www.it-ebooks.info
Table 2-14. Format attribute handler modules
Name
Purpose
Popularity/Status
res_format_attr_celt Handles format attribute details for the CELT audio format
Useful
res_format_attr_h263 Handles format attribute details for the H.263 video format Useful
res_format_attr_h264 Handles format attribute details for the H.264 video format Useful
res_format_attr_silk Handles format attribute details for the SILK audio format
Useful
CLI extensions
This group of modules includes optional features for the Asterisk command-line
interface (CLI).
Table 2-15. CLI extension modules
Name
Purpose
Popularity/Status
res_clialiases
Creates CLI aliases
Useful
res_clioriginate Provides an Asterisk CLI command for originating calls
Usable
res_convert
Provides an Asterisk CLI command to perform file-format conversions Usable
res_limit
Enables adjusting of system limits on the Asterisk process
Usable
res_realtime
Provides CLI commands for the Asterisk Realtime Architecture (ARA)
Useful
Other resource modules
Table 2-16 includes the rest of the resource modules that did not fit into one of the
subgroups we defined earlier in this section.
Table 2-16. Resource modules
Name
Purpose
Popularity/Status
res_adsi
Provides ADSI
Essentiala
res_ael_share
Provides shared routines for use with pbx_ael
Essential if you’re using AEL
res_agi
Provides the Asterisk Gateway Interface (see Chapter 21)
Useful
res_corosync
Provides distributed message waiting indication (MWI) and
device state notifications via the Corosync Cluster Engine
Useful
res_crypto
Provides cryptographic capabilities
Useful
res_curl
Provides common subroutines for other cURL modules
Useful
res_fax
Provides common subroutines for other fax modules
Useful
res_fax_spandsp
Plug-in for fax using the spandsp package
Useful
res_http_post
Provides POST upload support for the Asterisk HTTP server
Usable
res_http_websocket Provides WebSocket support for the Asterisk internal HTTP server; Usable
also utilized by chan_sip to provide SIP over a WebSocket
connection, which is useful for rtcweb
Modules
www.it-ebooks.info
|
25
Name
Purpose
Popularity/Status
res_jabber
Provides Jabber/XMPP resources
Deprecated (as of Asterisk
11)—see res_xmpp
res_monitor
Provides call-recording resources
Useful
res_musiconhold
Provides music on hold (MOH) resources
Essential
res_mutestream
Allows muting/unmuting of audio streams
New
res_odbc
Provides common subroutines for other ODBC modules
Useful
res_phoneprov
Provisions phones from Asterisk HTTP server
New
res_pktccops
Provides PacketCable COPS resources
New
res_security_log
Enables logging of security events generated by other parts of
Asterisk
New
res_smdi
Provides voicemail notification using the SMDI protocol
Limited
res_snmp
Provides system status information to an SNMP-managed
network
Usable
res_speech
Generic speech recognition API
Limitedb
res_xmpp
Provides Jabber/XMPP resources
Useful
a While most of the ADSI functionality in Asterisk is never used, the voicemail application uses this resource.
b Requires a separately licensed product in order to be used.
Add-on Modules
Add-on modules are community-developed modules with different usage or distribu‐
tion rights from those of the main code. They are kept in a separate directory and are
not compiled and installed by default. To enable these modules, use the menuselect build
configuration utility. Currently available add-on modules are listed in Table 2-17.
Table 2-17. Add-on modules
Name
Purpose
Popularity/Status
app_mysql
Executes MySQL queries with a dialplan
application
Deprecated—see func_odbc
app_saycountpl
Says Polish counting words
Deprecated—now integrated in
say.conf
cdr_mysql
Logs CDRs to a MySQL database
Usable—we recommend
chan_mobile
Enables making and receiving phone calls using
cell phones over Bluetooth
Limiteda
chan_ooh323
Enables making and receiving VoIP calls using
the H.323 protocol
Usable
format_mp3
Allows Asterisk to play MP3 files
Usable
26
|
Chapter 2: Asterisk Architecture
www.it-ebooks.info
cdr_adaptive_odbc instead
Name
Purpose
Popularity/Status
res_config_mysql
Uses a MySQL database as a realtime
configuration backend
Useful
a While chan_mobile works great with many phones, problems have been reported with some models. When a problem does
occur, it is very difficult for developers to solve unless they have a phone of the same model to test with.
Test Modules
Test modules are used by the Asterisk development team to validate new code. They are
constantly changing and being added to, and are not useful unless you are developing
Asterisk software.
If you are an Asterisk developer, however, the Asterisk Test Suite may be of interest to
you, as you can build automated tests for Asterisk and submit those back to the project,
which runs on several different operating systems and types of machines. By expanding
the number of tests constantly, the Asterisk project avoids the creation of regressions
in code. By submitting your own tests to the project, you can feel more confident in
future upgrades.
More information about installing the Asterisk Test Suite is available in this blog post.
More information about building tests is available in this document, or you can join the
#asterisk-testing channel on the Freenode IRC network.
File Structure
Asterisk is a complex system, composed of many resources. These resources make use
of the filesystem in several ways. Since Linux is so flexible in this regard, it is helpful to
understand what data is being stored, so that you can understand where you are likely
to find a particular bit of stored data (such as voicemail messages or logfiles).
Configuration Files
The Asterisk configuration files include extensions.conf, sip.conf, modules.conf, and
dozens of other files that define parameters for the various channels, resources, modules,
and functions that may be in use.
These files will be found in /etc/asterisk. You will be working in this folder a lot as you
configure and administer your Asterisk system.
Modules
Asterisk modules are usually installed to the /usr/lib/asterisk/modules folder. You will
not normally have to interact with this folder; however, it will be occasionally useful to
know where the modules are located. For example, if you upgrade Asterisk and select
File Structure
www.it-ebooks.info
|
27
different modules during the menuselect phase of the install, the old (incompatible)
modules from the previous Asterisk version will not be deleted, and you will get a
warning from the install script. Those old files will need to be deleted from the modules
folder. This can be done either manually or with the “uninstall” make (make uninstall)
target.
The Resource Library
There are several resources that require external data sources. For example, music on
hold (MOH) can’t happen unless you have some music to play. System prompts also
need to be stored somewhere on the hard drive. The /var/lib/asterisk folder is where
system prompts, AGI scripts, music on hold, and other resource files are stored.
The Spool
The spool is where applications store files on a Linux system that are going to change
frequently, or that will be processed by other processes at a later time. For example,
Linux print jobs and pending emails are normally written to the spool until they are
processed.
In Asterisk, the spool is used to store transient items such as voice messages, call re‐
cordings,4 call files, and so forth.
The Asterisk spool will be found under the /var/spool/asterisk directory.
Logging
Asterisk is capable of generating several different kinds of log files. The /var/log/aster
isk folder is where things such as call detail records (CDRs), channel events from CEL,
debug logs, queue logs, messages, errors, and other output are written.
This folder will be extremely important for any troubleshooting efforts you undertake.
We will talk more about how to make use of Asterisk logs in Chapter 24.
The Dialplan
The dialplan is the heart of Asterisk. All channels that arrive in the system will be passed
through the dialplan, which contains the call-flow script that determines how the in‐
coming calls are handled.
4. Not call detail records (CDRs), but rather audio recordings of calls generated by the MixMonitor() and
related applications.
28
| Chapter 2: Asterisk Architecture
www.it-ebooks.info
A dialplan can be written in one of three ways:
• Using traditional Asterisk dialplan syntax in /etc/asterisk/extensions.conf
• Using Asterisk Extension Logic (AEL) in /etc/asterisk/extensions.ael
• Using Lua in /etc/asterisk/extensions.lua
Later in this book, we devote several chapters to the subject of how to write a dialplan
using traditional dialplan syntax (by far the most popular choice). Once you learn this
language, it should be fairly easy to transition to AEL or Lua, should you desire.
Hardware
Asterisk is capable of communicating with a vast number of different technologies. In
general, these connections are made across a network connection; however, connections
to more traditional telecom technologies, such as the PSTN, require specific hardware.
Many companies produce this hardware, such as Digium (the sponsor, owner, and
primary developer of Asterisk), Sangoma, Rhino, OpenVox, Pika, Voicetronix,
Junghanns, Dialogic, Xorcom, beroNet, and many others. The authors prefer cards from
Digium and Sangoma; however, the products offered by other Asterisk hardware man‐
ufacturers may be more suitable to your requirements.
The most popular hardware for Asterisk is generally designed to work through the
Digium Asterisk Hardware Device Interface (known as DAHDI). These cards will all
have different installation requirements and different file locations.
In Chapter 7, we will discuss DAHDI in more detail; however, we will limit our discus‐
sion to DAHDI only. You will need to refer to the specific documentation provided by
the manufacturers of any cards you install for details on those cards.
Asterisk Versioning
The Asterisk release methodology has gone through a couple of iterations over the last
few years, and this section is designed to help you understand what the version numbers
mean. Of particular relevance is the change in versioning that happened with the
1.6.x series of releases, which followed a different numbering logic than all other Asterisk
releases (1.0 to 1.8), and where we’re at currently.
Hardware
www.it-ebooks.info
|
29
Previous Release Methodologies
This section is of historical value, but it can be skipped unless you’ll be
working with older versions of Asterisk.
When we had just Asterisk 1.2 and 1.4, all new development was carried out in trunk
(it still is), and only bug fixes went into the 1.2 and 1.4 branches. (All branches prior to
1.8 have been marked as EOL [End of Life], and are no longer receiving bug fixes or
security updates.)
Because all new development was done in trunk, until the 1.6 branch was created people
were unable to get access to the new features and functionality. This isn’t to say the new
functionality wasn’t available, but with all the changes that can happen in trunk, running
a production server based on it requires a very Asterisk-savvy (and C code–savvy)
administrator.
To try to relieve the pressure on administrators, and to enable faster access to new
features (in the time frame of months, rather than years), a new methodology was cre‐
ated. Branches in 1.6 would actually be marked as 1.6.0, 1.6.1, 1.6.2, etc., with the third
number increasing by one each time a new feature release was created. The goal was to
provide new feature releases every three to four months (which would be branched from
trunk), providing a shorter and clearer upgrade path for administrators. If you needed
a new feature, you’d only have to wait a few months and could then upgrade to the next
branch.
Tags from these branches look like this:
• 1.6.0.1 -- 1.6.0.2 -- 1.6.0.3 -- 1.6.0.4 -- etc.
• 1.6.1.1 -- 1.6.1.2 -- 1.6.1.3 -- 1.6.1.4 -- etc.
• 1.6.2.1 -- 1.6.2.2 -- 1.6.2.3 -- 1.6.2.4 -- etc.
Figure 2-2 gives a visual representation of the branching and tagging process in relation
to Asterisk trunk.
30
|
Chapter 2: Asterisk Architecture
www.it-ebooks.info
Figure 2-2. The Asterisk 1.6.x release process
So far we have branches, which are 1.2, 1.4, 1.6.0, 1.6.1, and 1.6.2 (there is no 1.6 branch).
Within each of those branches, we create tags (releases), which look like 1.2.14, 1.4.30,
1.6.0.12, 1.6.1.12, and 1.6.2.15.
Unfortunately, it ended up not working out that 1.6.x branches were created from trunk
every three to four months: the development process has led to a minimum release time
of six to eight months. Not only that, but the 1.6.x numbering methodology adds prob‐
lems of its own. People got confused as to what version to run, and the 1.6.0, 1.6.1, and
1.6.2 branches were all separate major version upgrades. When you increase the number
from 1.2 to 1.4, and then to 1.8, it is obvious that those are distinct branches and major
version changes. With 1.6.0, 1.6.1, and 1.6.2, it is less obvious.
Luckily, this is all behind us, and generally for new deployments, you’ll be using the
latest LTS (long-term support) or latest regular release branches, which have a more
sane structure, as we’ll delve into in the next section.
The Current Release Methodology
The development team learned a lot of things during the 1.6.x releases. The idea sur‐
rounding the releases was noble, but the implementation ended up being flawed when
put into real use. So, with Asterisk 1.8, the methodology reverted to look a lot like what
was used in the 1.2 and 1.4 releases.
While the development team still wants to provide access to new features and core
changes on a more regular basis (every 12 months being the goal), there is recognition
that it is also good to provide long-term support to a stable, popular version of Asterisk.
You can think of the Asterisk 1.4 branch as being an LTS version. The 1.6.0, 1.6.1, and
1.6.2 branches can be thought of as feature releases that continue to receive bug fixes
after release, but are supported for a shorter period of time (about a year). The first
official LTS version was Asterisk 1.8, receiving bug fixes for four years with an additional
year of security releases after that. Overall, the Digium development team chose to
provide five years of support from initial release for Asterisk 1.8.
Asterisk Versioning
www.it-ebooks.info
|
31
Asterisk 1.8 was released on 2010-10-21 and will move into security release–only mode
after four years (2014-10-21), at which point it will receive fixes for security issues, but
not general bug fixes, for one additional year. On 2015-10-21, Asterisk 1.8 will be given
a status of EOL, at which point no changes will be made to the 1.8 branch. (The source
code, as always, will continue to be widely available for those continuing to support
Asterisk 1.8 in their own private environments.)
This book is based on Asterisk 11, which was released on 2012-10-25 and will receive
bug fix support until 2016-10-25 and security support for a year beyond that.
The current status of all Asterisk branches—their release dates, when they will go into
security release–only mode, and when they will reach EOL status—are all documented
on the Asterisk wiki.
Simplifying the Version Numbers
In the past, it was said by Mark Spencer that the number 1 in front of the version numbers
1.0, 1.2, etc., would never change unless a major, fundamental shift in design had hap‐
pened in the Asterisk code base. Now that Asterisk is so popular and widely deployed,
any fundamental shift in the design would be incredibly disruptive to both development
contributors and those who deploy Asterisk on a regular basis. In an excellent blog
article by Kevin Fleming, it is explained why instead of moving from Asterisk 1.8 to
1.10, the Asterisk numbering scheme was shifted to drop the leading 1 and move just
to Asterisk 10. Essentially, what it comes down to is this: instead of having versions like
1.10, 1.12, 1.14 (where odd numbers are skipped for historical reasons), which leads to
potential version numbers that look like 1.10.3.1, and since the underlying base of As‐
terisk will not change so fundamentally over a single release that it would justify the 2.0
moniker, it made the most sense to just drop the 1 from the begininning of the version.
A look at the current branch structure is shown in Figure 2-3.
Figure 2-3. Current Asterisk branching process
32
|
Chapter 2: Asterisk Architecture
www.it-ebooks.info
Versions going forward will follow the same release methodology (that of alternating
LTS and regular releases on a well-known schedule with a predefined scale-down of
support), except version numbering will now be simplified. Asterisk 10 was the first
version with the 1 moniker dropped, and was a regular support release. The first LTS
release was Asterisk 11. In this way, releases will alternate between regular and LTS.
Conclusion
Asterisk is composed of many different technologies, most of which are complicated in
their own right. As such, the understanding of Asterisk architecture can be overwhelm‐
ing. Still, the reality is that Asterisk is well-designed for what it does and, in our opinion,
has achieved a remarkable balance between flexibility and complexity.
Conclusion
www.it-ebooks.info
|
33
www.it-ebooks.info
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 this chapter we’re going to walk through the installation of Asterisk from the source
code. Many people shy away from this method, claiming that it is too difficult and timeconsuming. Our goal here is to demonstrate that installing Asterisk from source is not
actually that difficult to do. More importantly, we want to provide you with the best
Asterisk platform on which to learn.
In this book we will be helping you build a functioning Asterisk system from scratch.
In this chapter you will build a base platform for your Asterisk system. Given that we
are installing from source, there is potentially a lot of variation in how you can do this.
The process we discuss here is one that we’ve used for many years, and following it will
provide you with a suitable foundation for Asterisk.
As part of this process we will also explain installation of some of the software depen‐
dencies on the Linux platform that will be needed for topics we’ll cover later (such as
database integration). We will show instructions for installing Asterisk on both RHEL
(Red Hat Enterprise Linux) version 6.3 and Ubuntu (a Debian-based distribution) ver‐
sion 12.04, which we believe covers the vast majority of Linux distributions being in‐
stalled today. We’ll try to keep the instructions general enough that they should be useful
on any distribution of your choice.1
1. If you are using another distribution, we’re willing to bet you are quite comfortable with Linux and should
have no trouble installing Asterisk.
35
www.it-ebooks.info
We have chosen to install on RHEL and Ubuntu because these distributions and others
based on them are the most popular, but Asterisk is generally distribution-agnostic.
Asterisk will even install on Solaris, BSD, or OS X2 if you like. We won’t be covering
them in this book, though, as Asterisk is most heavily developed on the Linux platform.
Asterisk Packages
There are also packages that exist for Asterisk that can be installed using popular
package-management programs such as yum or apt-get. You are encouraged to use them
once you are familiar with Asterisk.
If you are using RHEL, Asterisk is available from the EPEL repository from the Fedora
project. Asterisk packages are available in the universe repository for Ubuntu.
Some commands you see in this chapter will be split into separate rows, each labeled
for the distribution on which the command should be performed. Commands for which
distributions are not specified are for common commands that can be run on both
distributions.
Asterisk-Based Projects
Many projects have been created that use Asterisk as their underlying platform. Some
of these, such as The FreePBX GUI, have become so popular that many people mistake
them for the Asterisk product itself (the FreePBX GUI is used in several Asterisk-based
projects). These projects generally will take the base Asterisk product and add a webbased administration interface, a complex database, and a set of constraints on how
changes can be made to the configuration.
We have chosen not to cover these projects in this book, for several reasons:
1. This book tries, as much as possible, to focus on Asterisk and only Asterisk.
2. Books have already been written about many of these Asterisk-based projects.
3. We believe that if you learn Asterisk in the way that we will teach you, the knowledge
will serve you well regardless of whether or not you eventually choose to use one
of these prepackaged versions of Asterisk.
4. For us, the power of Asterisk is that it does not attempt to solve your problems for
you. These projects are truly amazing examples of what can be built with Asterisk.
However, if you are looking to build your own Asterisk application (which is really
what Asterisk is all about), these projects will impose limitations on you, because
2. Leif calls this “Oh-Eh-Sex,” but Jim thinks it should be pronounced “OS Ten.” We wasted several precious
minutes arguing about this.
36
|
Chapter 3: Installing Asterisk
www.it-ebooks.info
they are focused on simplifying the process of building a business PBX, not on
making it easier to access the full potential of the Asterisk platform.
Some of the most popular Asterisk-based projects include:
AsteriskNOW
Managed by Digium. Uses FreePBX GUI.
Elastix
Uses the FreePBX GUI.
FreePBX Distro Uses the FreePBX GUI.
PBX in a Flash
Uses the FreePBX GUI.
We recommend that you check them out.3
Installation Cheat Sheet
If you just want the nitty-gritty on how to get Asterisk up and running quickly, perform
the following at the shell prompt. We encourage you to read through the entire chapter
at least once, though, in order to better understand the full process.4
The instructions provided here assume you’ve already installed either RHEL or Ubuntu
using the steps outlined in “Distribution Installation” on page 41.
1. Perform a system update and reboot:
RHEL
# yum update -y && reboot
Ubuntu
sudo apt-get update && sudo apt-get upgrade && sudo reboot
2. Synchronize time and install the NTP (Network Time Protocol) daemon:
RHEL
# yum install -y ntp && ntpdate pool.ntp.org && \
chkconfig ntpd on && service ntpd start
Ubuntu
sudo apt-get install ntp
Some additional configuration of text files is required on
Ubuntu. See “Enable NTP for accurate system time” on page
48.
3. After you read our book, of course.
4. Once you have experience with several Asterisk installations, you’ll agree that it’s a quick and painless process.
Nevertheless, this chapter may make the process look complex. This is simply because we have an obligation
to ensure you are provided with all the information you need to accomplish a successful install.
Installation Cheat Sheet
www.it-ebooks.info
|
37
3. On RHEL, add a new system user (see “Adding a system user” on page 44 for specific
information):
RHEL # adduser asteriskpbx && passwd asteriskpbx && \
yum install sudo && visudo
For an Ubuntu install, we are assuming that the user created during
the installation process is asteriskpbx.
4. Install software dependencies:
RHEL
sudo yum install gcc gcc-c++ make wget subversion \
libxml2-devel ncurses-devel openssl-devel \
libxml2-devel sqlite-devel libuuid-devel vim-enhanced
Ubuntu sudo apt-get install build-essential subversion \
libncurses5-dev libssl-dev libxml2-dev libsqlite3-dev \
uuid-dev vim-nox
5. Create your directory structure:
$ mkdir -p ~/src/asterisk-complete/asterisk
$ cd ~/src/asterisk-complete/asterisk
6. Get the latest release in the Asterisk 11 series with wget:
$ wget \
http://downloads.asterisk.org/pub/telephony/asterisk/ \
asterisk-11-current.tar.gz
Alternatively, you can get the latest changes in the Asterisk 11 branch via
Subversion:
$ svn co http://svn.asterisk.org/svn/asterisk/branches/11
Or check out a specific tag (version) from Subversion:
$ svn co http://svn.asterisk.org/svn/asterisk/tags/11.3.0
7. Build and install the software:
$ cd ~/src/asterisk-complete/asterisk/11
If you are running 64-bit RHEL, run the configure script with the libdir option:
$ ./configure --libdir=/usr/lib64
On any other platform, run the configure script without any arguments:
$ ./configure
Finally, compile and install Asterisk:
38
|
Chapter 3: Installing Asterisk
www.it-ebooks.info
$ make
$ sudo make install
$ sudo make config
8. Install additional sound prompts (Extra Sounds Packages) from menuselect:
$ cd ~/src/asterisk-complete/asterisk/11/
$ make menuselect
$ sudo make install
9. Modify the file permissions of the directories Asterisk was installed to:
$
$
$
$
sudo
sudo
sudo
sudo
chown
chown
chown
chown
-R
-R
-R
-R
asteriskpbx:asteriskpbx
asteriskpbx:asteriskpbx
asteriskpbx:asteriskpbx
asteriskpbx:asteriskpbx
/var/lib/asterisk/
/var/spool/asterisk/
/var/log/asterisk/
/var/run/asterisk/
Alternatively, you could update all the permissions in one line with:
sudo chown -R asteriskpbx:asteriskpbx {/var/lib,/var/spool,/var/
log,/var/run}/asterisk
10. Create the /etc/asterisk directory and copy the indications.conf sample file into it:
$ sudo mkdir -p /etc/asterisk
$ sudo chown asteriskpbx:asteriskpbx /etc/asterisk
$ cd /etc/asterisk/
$ cp ~/src/asterisk-complete/asterisk/11/configs/indications.conf.sample \
./indications.conf
11. Copy the sample asterisk.conf file into /etc/asterisk and change runuser and run
group to have values of asteriskpbx:
$ cp ~/src/asterisk-complete/asterisk/11/configs/asterisk.conf.sample \
/etc/asterisk/asterisk.conf
$ vim /etc/asterisk/asterisk.conf
See “indications.conf and asterisk.conf ” on page 58 for more information.
12. Create the modules.conf file. Enable loading of modules automatically, and disable
extra modules:
$ cat >> /etc/asterisk/modules.conf
; The modules.conf file, used to define which modules Asterisk should load (or
; not load).
;
[modules]
autoload=yes
; Resource modules currently not needed
noload => res_speech.so
noload => res_phoneprov.so
Installation Cheat Sheet
www.it-ebooks.info
|
39
noload => res_ael_share.so
noload => res_clialiases.so
noload => res_adsi.so
; PBX modules currently not needed
noload => pbx_ael.so
noload => pbx_dundi.so
; Channel
noload =>
noload =>
noload =>
noload =>
noload =>
noload =>
noload =>
modules currently not needed
chan_oss.so
chan_mgcp.so
chan_skinny.so
chan_phone.so
chan_agent.so
chan_unistim.so
chan_alsa.so
; Application modules currently not needed
noload => app_nbscat.so
noload => app_amd.so
noload => app_minivm.so
noload => app_zapateller.so
noload => app_ices.so
noload => app_sendtext.so
noload => app_speech_utils.so
noload => app_mp3.so
noload => app_flash.so
noload => app_getcpeid.so
noload => app_setcallerid.so
noload => app_adsiprog.so
noload => app_forkcdr.so
noload => app_sms.so
noload => app_morsecode.so
noload => app_followme.so
noload => app_url.so
noload => app_alarmreceiver.so
noload => app_disa.so
noload => app_dahdiras.so
noload => app_senddtmf.so
noload => app_sayunixtime.so
noload => app_test.so
noload => app_externalivr.so
noload => app_image.so
noload => app_dictate.so
noload => app_festival.so
Ctrl+D
40
|
Chapter 3: Installing Asterisk
www.it-ebooks.info
13. Configure musiconhold.conf:
$ cat > musiconhold.conf
; musiconhold.conf
[general]
[default]
mode=files
directory=moh
Ctrl+D
14. Save your changes and your module configuration is done. Your system is ready to
configure your dialplan and channels.
Distribution Installation
Because Asterisk relies so heavily on having priority access to the CPU, it is essential
that you install Asterisk onto a server without any graphical interface, such as the X
Windowing system (Gnome, KDE, etc.). Both RHEL and Ubuntu ship a GUI-free dis‐
tribution designed for server usage. We will cover instructions for both distributions.
RHEL Server
You will need to download an RHEL Server ISO from the Red Hat website. Download
instructions can be found on their site as well. Once you’ve downloaded the ISO file,
burn it to a CD or DVD and start the installation process. If you’re installing into a
virtual machine, you should be able to mount the ISO file directly and install from there.
Base system installation
Upon booting from the CD, select “Install or upgrade an existing system.” You will first
be asked whether you want to test the media. You should select OK the first time you
start an install from this CD. After the media checking is complete, the installation
interface will start. Select Next to proceed to the first step of the installer.
Choose your language and make a keyboard selection. If you’re in North America, you
will probably just select the defaults. You will then be asked what type of storage devices
your installation will involve. If you are not sure which option to select, choose Basic
Storage Devices.
In the next step you will be prompted to set the hostname for this machine. Set whatever
is appropriate for your installation and select Next.
You will then be prompted to choose a time zone. Again, select whatever is appropriate
for your installation and select Next.
Distribution Installation
www.it-ebooks.info
|
41
At this point, you will be asked for a root password. Enter a secure password and type
it again to confirm. After entering your secure password, select Next.
The next screen will ask about the installation type. If you intend to use all of the storage
for this installation, select Use All Space. Otherwise, select the option most appropriate
for your situation. There are two checkboxes on this screen in the installer. One enables
hard drive encryption. The other allows you to review and potentially modify the par‐
titioning layout that the installer sets up for you. Feel free to choose either or both of
those options if you would like to. Once you have made the necessary choices, select
Next to continue. You may be asked for additional confirmation that you would like
your changes applied, as any data on the hard drive prior to the install will be lost after
this point.
Separating the /var Mount Point to Its Own Partition
On a system dedicated to Asterisk, the directory with the largest storage requirement
is /var. This is where Asterisk will store recordings, voicemails, logfiles, prompts, and a
myriad of constantly growing information. In normal operation, it is unlikely that As‐
terisk will fill the hard disk. However, if you have extensive logging turned on or are
recording all calls, this could, in theory, occur. (This is likely to happen several months
after you’ve completed the install and take your entire staff by surprise.)
If the drive on which the operating system is mounted fills up, there is the potential for
a kernel panic. By separating /var from the rest of the hard drive, you significantly lower
the risk of a system failure.
Having a full volume is still a major problem; however, you will at
least be able to log into the system to rectify the situation.
At the “Review and modify the partitioning layout” screen, you can create a separate
volume for /var. Selecting Yes will bring up the Partitioning tool. To partition the drive
accurately, you need to know what the hard drive size is; this may not jibe with what is
stamped on the outside of the drive because you have to tell the tool how to chop up the
drive. A limitation of the tool is that there is no option to say “use all available space”;
that is, you can’t simply use 500 MB on the / partition and then say “use the rest for /
var.” The workaround is to make a note of the size it has selected for / currently, as that
is the full space, subtract 500 MB from that, and make that the size for the / partition.
The subtracted amount will then be reserved for /var.
42
|
Chapter 3: Installing Asterisk
www.it-ebooks.info
You will now be prompted to select a set of software to install. The default of Basic Server
is sufficient unless you know of a reason you need to select another choice based on
your specific deployment. It will be easy to install additional packages later. Once you
have made a choice, select Next to continue. The installer will then install all of the
packages necessary based on your selection. This will take a while.
At this point the installer is complete. It will ask you to reboot the system. Select Reboot.
Base system update
Once you’ve rebooted your system, you need to run the yum update command to make
sure you have the latest base packages. To do this, log in using the username root and
the password you created during installation. Once logged in, run the following:
# yum update
Is this ok [y/N]: y
When prompted to install the latest packages, press y and wait for the packages to
update. If you’re asked to accept a GPG key, press y. When complete, reboot the system
as it is likely the kernel will have been updated:5
# reboot
Congratulations! You’ve successfully installed and updated the base RHEL system.
Enabling NTP for accurate system time
Keeping accurate time is essential on your Asterisk system, both for maintaining accu‐
rate call detail records and for synchronization with your other programs. You don’t
want the times of your voicemail notifications to be off by 10 or 20 minutes, as this can
lead to confusion and panic from those who might think their voicemail notifications
are taking too long to be delivered. The ntpd command can be used to ensure that the
time on your Asterisk server remains in sync with the rest of the world:
# yum install ntp
...
Is this ok [y/N]: y
...
# ntpdate pool.ntp.org
# chkconfig ntpd on
# service ntpd start
The defaults shipped with RHEL are sufficient to synchronize the time and keep the
machine’s time in sync with the rest of the world.
5. This reboot step is essential prior to installing Asterisk.
Distribution Installation
www.it-ebooks.info
|
43
Adding a system user
The Ubuntu server install process asks you to add a system user other than root, but
RHEL does not. In order to be consistent in the book, we’re going to add another system
user and provide it sudo access.6 To add the new user, execute the adduser command:
# adduser asteriskpbx
# passwd asteriskpbx
Changing password for user asteriskpbx.
New UNIX password:
Retype new UNIX password:
Now we need to provide the asteriskpbx user sudo access. We do this by modifying the
sudoers file with the visudo command.
Execute the visudo command and look for the lines shown below:
# visudo
## Allows people in group wheel to run all commands
%wheel ALL=(ALL)
ALL
With the %wheel line uncommented as shown in our example, save the file by pressing
Esc, then typing :wq and pressing Enter. Now open the /etc/group file in your favorite
editor (nano is easy to use) and find the line that starts with the word wheel. Add
asteriskpbx to the wheel group, like so:
wheel:x:10:asteriskpbx
Save the file, log out from root by typing exit, and log in as the asteriskpbx user you
created. Test your sudo access by running the following command:
$ sudo ls /root/
[sudo] password for asteriskpbx:
After typing your password, you should get the output of the /root directory. If you
don’t, go back and verify the steps to make sure you didn’t skip or mistype anything.
The rest of the instructions in this chapter will assume that you’re the asteriskpbx user
and that you have sudo access.
With the operating system installed, you’re ready to install the dependencies required
for Asterisk. The next section deals with Ubuntu, so you can skip ahead to the section
“Software Dependencies” on page 49, which provides an in-depth review of the Asterisk
installation process. Alternatively, if you’ve already reviewed the information in that
section, you may want to refer back to the “Installation Cheat Sheet” on page 37 for a
high-level review of how to install Asterisk.
6. sudo is an application that allows a user to execute commands as another user, such as root, or the superuser.
44
|
Chapter 3: Installing Asterisk
www.it-ebooks.info
Ubuntu Server
Ubuntu Server is a popular Linux distribution loosely based on Debian. There is also a
popular desktop version of the software. The Ubuntu Server package contains no GUI
and is ideal for Asterisk installations.
To get the latest version of Ubuntu Server,7 visit http://www.ubuntu.com and select the
Server tab at the top of the page. You will be provided with a page that contains infor‐
mation about Ubuntu Server Edition. Clicking the orange Download button in the
upper-right corner will take you to a page where you can select either the 32-bit or 64bit version of Ubuntu Server. After selecting one of the options, you can press the “Start
download” button.
Once you’ve downloaded the ISO file, burn it to a CD and start the installation process.
If you’re installing into a virtual machine (which we don’t recommend for production
use, although it can be a great way to test out Asterisk), you should be able to mount
the ISO file directly and install from there.
Base system installation
Upon booting from the CD, you will be presented with a screen where you can select
your language of choice. By default English is the selected language, and after a timeout
period, it will be automatically selected. After selecting your language, press Enter.
The next screen will give you several options, the first of which is Install Ubuntu Server.
Select it by pressing Enter.
You will then be asked which language to use for the installation (yes, this is slightly
redundant). Select your language of choice (the default is English), and press Enter.
You will be presented with a list of countries. Once you’ve found your country and
highlighted it, press Enter.
You will then be asked if you would like to use the keyboard layout detector. If you know
which keyboard type you have, you can select No and then pick it from a list of formats.
If you are utilizing the keyboard layout detector, you will be prompted to press a series
of keys. If you use the keyboard detector and it does not detect your keyboard correctly
(typical when installing into a virtual machine via a remote console), you can go back
and select from a list manually.8
7. Of course, projects can change their websites whenever they want. Hopefully the instructions we’ve provided
here are accurate enough to help guide you through the site even in the event of changes.
8. It is probably easiest to manually select a US keyboard, so unless you have special keyboard requirements,
save yourself some time, skip the autodetect process, and specify the US keyboard manually.
Distribution Installation
www.it-ebooks.info
|
45
Once you’ve picked your keyboard, the installation will continue by attempting to set
up your network automatically. If all goes well, you will be prompted to enter a hostname
for your system. You can pick anything you want here, unless your network requires
your system to a have a specific hostname. Input it now and then press Enter.
When the file installation is complete, you’ll be asked to enter the full name of the new
user, from which a username will be generated.9 Once you’ve entered a full name, the
system should suggest a username based on that name, however you are free to change
the username to whatever you like.10
After entering your username, you’ll be asked to supply a password, and then asked to
confirm the password you’ve entered. You’ll use these to log into the system once the
installer ends.11
The installer will then ask you if you want to encrypt your home directory. This is not
necessary and will add CPU overhead. Select No and press Enter.
The rest of the installation instructions will assume that aster‐
iskpbx was chosen as the username.
The installer will attempt to contact a Network Time Protocol (NTP) server to syn‐
chronize your clock. Ubuntu will then try to autodetect your time zone and present you
with its choice. If correct, select Yes, otherwise, select No and you’ll be presented with
a list of time zones to select from. Select your time zone, or select from the worldwide
list if your time zone is not shown. Once you’ve selected your time zone, press Enter to
continue.
The installer will then ask you some questions about partitioning your system. Typically
the defaults are fine; these are using the guided system, utilizing the entire disk, and
setting up the Logical Volume Manager (LVM). Press Enter once you’ve made your
selection. Then you’ll be asked which partition to install to, which likely is the only one
on your system. Press Enter to continue, at which point you’ll be asked to confirm the
changes to the partition table. Select Yes and press Enter to continue.
You will now be asked how much space to use (the default value will be to use the entire
disk). Press Enter once you’ve entered and confirmed the amount of space you want to
9. We have chosen to use Asterisk PBX as the full name for the account.
10. We will use the username asteriskpbx. Note that Ubuntu has reserved the username asterisk internally, which
is why we’ve chosen asteriskpbx as our username.
11. Ubuntu does not provide direct access to root, but instead uses the sudo application, which allows you to run
commands as root without being the root user.
46
|
Chapter 3: Installing Asterisk
www.it-ebooks.info
use. The installer will then request one last confirmation before making the changes to
the disk. Select Yes to write the changes to disk. The installer will now format the hard
disk, write the partitioning scheme to disk, copy the files, and perform the file
installation.
If you are comfortable with more advanced filesystem configuration
techniques, you may want to consider placing the /var folder into a
separate partition from the rest of the filesystem. The thinking behind
this is that logfiles and spool files (asterisk uses the spool to store
voicemail and other recordings) are the files most likely to fill up your
hard drive, and if you place /var in a separate partition, you will have a
somewhat easier time getting access to the filesystem to perform emer‐
gency maintenance if needed.
If your system is behind a web proxy, enter the proxy information now. If you’re not
behind a proxy or don’t know if you are, simply press Enter.
You will then be asked if you want to install updates automatically. The default is to
perform No automatic updates, which is what we recommend. Should a system reboot
occur, an update to the kernel will render Asterisk nonstartable until you recompile
it12 (which won’t make you popular). It is better practice to identify updates on a regular
basis and perform them manually in a controlled manner. Normally, you would want
to advise your users of the expected downtime and schedule the downtime to happen
after business hours (or while a redundant system is running). Select No automatic
updates and press Enter. (The requirement to make sure your system is up to date is
another reason we use a minimal base install, as it will greatly reduce the number of
updates required.)
Since you’ll be installing our dependencies with apt-get, you only need to select one
package during the install: OpenSSH server. SSH is essential if you wish to perform
remote work on the system. However, if your local policy states that your server needs
to be managed directly, you may not want to install the OpenSSH server.
Pressing the Enter key will accept the current selections and move
on with the install. You need to use the space bar to toggle your
selections.
After you’ve selected OpenSSH server, press Enter.
12. While we say Asterisk here, specifically it is DAHDI that is the problem. DAHDI is a set of Linux kernel
modules used with Asterisk.
Distribution Installation
www.it-ebooks.info
|
47
If this is the only operating system on the machine (which it likely is), Ubuntu will give
you the option to install the GRUB bootloader on your system. It provides this prompt
in order to give you the option of skipping the GRUB installation, as it will modify the
master boot record (MBR) on your system. If there is another operating system it has
failed to detect that has information loaded into the MBR, it’s nice to be able to skip
modifying it. If this is the only operating system installed on your server, select Yes.
When the system has finished the install, you’ll be asked to remove any media in the
drives and to reboot the system by selecting Continue, at which point the installation
will be complete and the system will reboot.
Base system update
Now that you’ve completed installing Ubuntu Server, you need to perform a system
update with apt-get to make sure you have the latest packages installed. You’ll be pre‐
sented with a login prompt where you’ll log in with the username and password you
created in the installer (e.g., asteriskpbx). Once logged in, run the following command:
$ sudo apt-get update
[sudo] password for asteriskpbx:
...
Reading package lists... Done
$ sudo apt-get upgrade
Reading state information... Done
...
Do you want to continue [Y/n]? y
The password that sudo wants is the password you just logged in with.
Press Enter when prompted to continue, at which point the latest package updates will
be installed. When complete, reboot the system so the changes can take effect, as the
kernel has probably been updated:
$ sudo reboot
Congratulations! You’ve successfully installed and updated the base Ubuntu Server
system.
Enable NTP for accurate system time
Keeping accurate time is essential on your Asterisk system, both for maintaining accu‐
rate call detail records as well as for synchronization with your other programs. You
don’t want the times of your voicemail notifications to be off by 10 or 20 minutes, as
48
|
Chapter 3: Installing Asterisk
www.it-ebooks.info
this can lead to confusion and panic from those who might think their voicemail noti‐
fication took too long to be delivered:
$ sudo apt-get install ntp
Now restart the NTP daemon:
$ sudo /etc/init.d/ntp restart
With the operating system installed, you’re ready to install the dependencies required
for Asterisk. The next section provides an in-depth review of the installation process.
If you’ve already reviewed the information in “Software Dependencies” on page 49, you
may want to refer back to “Installation Cheat Sheet” on page 37 for a high-level review
of how to install Asterisk.
Software Dependencies
The first thing you need to do once you’ve completed the installation of your operating
system is to install the software dependencies required by Asterisk. The commands
listed in Table 3-1 have been split into two columns, for Ubuntu Server and RHEL Server.
These packages will allow you to build a basic Asterisk system, along with DAHDI and
LibPRI. Not every module will be available at compile time with these dependencies;
only the most commonly used modules will be built. If additional dependencies are
required for other modules used later in the book, instructions will be provided as
necessary.
Table 3-1. Software dependencies for Asterisk on Ubuntu Server and RHEL Server
Ubuntu
RHEL
sudo apt-get install build-essential \
subversion libncurses5-dev libssl-dev \
libxml2-dev libsqlite3-dev uuid-dev
vim-nox
sudo yum install gcc gcc-c++ make wget \
subversion libxml2-devel ncurses-devel \
openssl-devel sqlite-devel libuuid-devel
vim-enhanced
These packages will get you most of what you’ll need to get started with installing As‐
terisk, DAHDI, and LibPRI. Note that you will also need the software dependencies for
each package that we indicate must be installed. These will be resolved automatically
for you when you use either yum or apt-get.
We have also included the OpenSSL development libraries, which are not strictly nec‐
essary to compile Asterisk but are good to have: they enable key support and other
encryption functionality.
We have installed vim as our editor, but you can choose anything you want, such as
nano, joe, or emacs.
Software Dependencies
www.it-ebooks.info
|
49
Asterisk contains a script that will install the dependencies for all fea‐
tures in Asterisk. Once you have downloaded Asterisk using the in‐
structions in “Downloading What You Need” on page 50, use the fol‐
lowing commands if you would like to run it:
$ cd ~/src/asterisk-complete/asterisk/11
$ sudo ./contrib/scripts/install_prereq install
$ sudo ./contrib/scripts/install_prereq install-unpackaged
Third-Party Repositories
For certain software dependencies, a third-party repository may be necessary. This ap‐
pears to be most often the case when using RHEL. A couple of repositories that seem
to be able to provide all the extra dependencies required are RPMforge and EPEL (Extra
Packages for Enterprise Linux).
We may occasionally refer to these third-party repositories when they are required to
obtain a dependency for a module we are trying to build and use.
Downloading What You Need
There are several methods of getting Asterisk: via the Subversion code repository, via
wget from the downloads site, or via a package-management system such as apt-get or
yum. We’re only going to cover the first two methods, since we’re interested in building
the latest version of Asterisk from source. Typically, package-management systems will
have versions that are older than those available from Subversion or the downloads site,
and we want to make sure we have the most recent fixes available to us, so we tend to
avoid them.
Before we start getting the source files, let’s create a directory structure to house the
downloaded code. We’ll create the directory structure within the home directory for
the asteriskpbx user on the system. Once everything is built, it will be installed with the
sudo command. We’ll then go back and change the permissions and ownership of the
installed files in order to build a secure system. To begin, issue the following command:
$ mkdir -p ~/src/asterisk-complete/asterisk
Now that we’ve created a directory structure to hold everything, let’s get the source code.
Choose one of the following two methods to get your files:
• Subversion
• wget
50
|
Chapter 3: Installing Asterisk
www.it-ebooks.info
Getting the Latest Version
Asterisk is a constantly evolving project, and there are many different versions of the
software that you can implement.
In Chapter 2, we talked about Asterisk versioning. The concept of how Asterisk is ver‐
sioned is important to understand because the versioning system has undergone a few
changes of methodology over the years. So, if you’re not up to speed, we strongly rec‐
ommend that you go back and read “Asterisk Versioning” on page 29.
Having said all that, in most cases all you need to do is grab the latest version from the
Asterisk website. We will be installing and using Asterisk 11 throughout this book.
Getting the Source via Subversion
Subversion is a version control system that is used by developers to track changes to
code over a period of time. Each time the code is modified, it must first be checked out
of the repository; then it must be checked back in, at which point the changes are logged.
Thus, if a change creates a regression, the developers can go back to that change and
remove it if necessary. This is a powerful and robust system for development work. It
also happens to be useful for Asterisk administrators seeking to retrieve the software.
To download the source code to the latest version of Asterisk 11, use these commands:
$ cd ~/src/asterisk-complete/asterisk
$ svn co http://svn.asterisk.org/svn/asterisk/branches/11
You can now skip directly to “How to Install It” on page 52.
The preceding commands will retrieve the latest changes to the source
in that particular branch, which are changes that have been made after
the latest release. If you would prefer to use a released version, please
refer to the next section.
Getting the Source via wget
To obtain the latest released versions of DAHDI, LibPRI, and Asterisk using the wget
application, issue the following commands:
$ cd ~/src/asterisk-complete/asterisk
$ wget \
http://downloads.asterisk.org/pub/telephony/asterisk/asterisk-11-current.tar.gz
$ tar zxvf asterisk-11-current.tar.gz
$ wget \
http://downloads.asterisk.org/pub/telephony/libpri/libpri-1.4-current.tar.gz
$ tar zxvf libpri-1.4-current.tar.gz
Downloading What You Need
www.it-ebooks.info
|
51
$ wget \
http://downloads.asterisk.org/pub/telephony/dahdi-linux-complete/\
dahdi-linux-complete-current.tar.gz
$ tar zxvf dahdi-linux-complete.tar.gz
The next step is to compile and install the software, so onward to the next section.
How to Install It
With the source files downloaded you can compile the software and install it.
Normally, all that is needed to run Asterisk is the Asterisk software itself, however if
you are running a physical PSTN interface (such as a PRI circuit) into your system, there
are two software packages you will need in order to connect the PSTN interface to
Asterisk. Those two packages are named LibPRI and DAHDI. Later on we will discuss
these in more detail. For now, we are going to have you install them simply for com‐
pleteness. If you prefer, you can skip installation of LibPRI and DAHDI, however since
there is no harm or penalty in having them, we recommend building them into your
system right from the get go.
The order for installing is:
1. DAHDI13
2. LibPRI14
3. Asterisk15
Installing in this order ensures that any dependencies for DAHDI and Asterisk are
installed prior to running the configuration scripts, which will subsequently ensure that
any modules dependent on LibPRI or DAHDI will be built.
So, let’s get started.
DAHDI
The Digium Asterisk Hardware Device Interface, or DAHDI (formerly known as Zaptel),
is the software Asterisk uses to interface with telephony hardware. We recommend that
you install it even if you have no hardware installed, because DAHDI is a dependency
13. This package contains the kernel drivers to allow Asterisk to connect to traditional PSTN circuits. It is also
required for the MeetMe() conferencing application. Again, we will install this for completeness.
14. Strictly speaking, if you are not going to be using any ISDN connections (BRI and PRI), you can install
Asterisk without LibPRI. However, we are going to install it for the sake of completeness.
15. If you don’t install this, this book’s examples will not work, but it could still make a great bathroom reader.
Just sayin’.
52
|
Chapter 3: Installing Asterisk
www.it-ebooks.info
required for building the timing module res_timing_dahdi and is used for Asterisk
dialplan applications such as MeetMe().
DAHDI-tools and DAHDI-linux
DAHDI is actually a combination of two separate code bases: DAHDI-tools, which pro‐
vides various administrator tools such as dahdi_cfg, dahdi_scan, etc.; and DAHDIlinux, which provides the kernel drivers. Unless you’re only updating one or the other,
you’ll be installing both at the same time, which is referred to as DAHDI-linuxcomplete. The version numbering for DAHDI-linux-complete will look something like
2.6.1+2.6.1, where the number to the left of the plus sign is the version of DAHDIlinux included, and the version number to the right of the plus sign is the DAHDItools version included.
There are also FreeBSD drivers for DAHDI, which are maintained by the community.
These drivers are available at the Asterisk website.
Another dependency is required for installing DAHDI, and that is the kernel source. It
is important that the kernel version being used match exactly that of the kernel source
being installed. You can use uname -a to verify the currently running kernel version:
RHEL
sudo yum install kernel-devel
Ubuntu
sudo apt-get install linux-headers-`uname -r`
The use of uname -r surrounded by backticks (`) is for filling in the currently running
kernel version so the appropriate package is installed.
The following commands show how to install DAHDI-linux-complete 2.6.1+2.6.1.
There may be a newer version available by the time you are reading this, so check
downloads.asterisk.org first.
To list the current tags (versions) of DAHDI, you can run the command:
svn ls http://svn.asterisk.org/svn/dahdi/linux-complete/tags
If there is a newer version available, just replace the version number in the commands:
$
$
$
$
$
cd ~/src/asterisk-complete/
mkdir dahdi
cd dahdi/
svn co http://svn.asterisk.org/svn/dahdi/linux-complete/tags/2.6.1+2.6.1
cd 2.6.1+2.6.1
How to Install It
www.it-ebooks.info
|
53
If you are using 64-bit RHEL, use the following commands to compile and install
DAHDI:
$
$
$
$
$
$
$
$
$
cd tools
./configure --libdir=/usr/lib64
make
sudo make install
cd ../linux
make
sudo make install
cd ..
sudo make config
For any other platform, use this set of commands to compile and install DAHDI:
$ make all
$ sudo make install
$ sudo make config
You will need to have Internet access when running the make all com‐
mand, as it will attempt to download the latest hardware firmware from
the Digium servers.
After installing DAHDI, we can move on to installing LibPRI. Information about con‐
figuring DAHDI is available in “PSTN Circuits” on page 150.
You can also download the source via wget from the Asterisk site. Check
the website for the most current version, as these versions will most
likely be out of date by the time you read this.
LibPRI
LibPRI is a library that adds support for ISDN (PRI and BRI). The use of LibPRI is
optional, but since it takes very little time to install, doesn’t interfere with anything, and
will come in handy if you ever want to add cards to a system at a later point, we rec‐
ommend that you install it now. Be sure to install DAHDI prior to installation of LibPRI
as there is a dependency on a DAHDI header file during compilation.
Check out the latest version of LibPRI and compile it thus:
$
$
$
$
$
$
54
cd ~/src/asterisk-complete/
mkdir libpri
cd libpri/
svn co http://svn.asterisk.org/svn/libpri/tags/1.4.
cd 1.4.
make
| Chapter 3: Installing Asterisk
www.it-ebooks.info
Use the following command to install LibPRI if you are using 64-bit RHEL:
$ sudo make install libdir=/usr/lib64
For any other platform, use this command to install LibPRI:
$ sudo make install
You can also download the source via wget from the Asterisk website.
To list the current tags (versions) of LibPRI, you can run the command:
svn ls http://svn.asterisk.org/svn/libpri/tags.
Asterisk
With both DAHDI and LibPRI installed, we can now install Asterisk:
$ cd ~/src/asterisk-complete/asterisk/11
If you are running 64-bit RHEL, run the configure script with the libdir option:
$ ./configure --libdir=/usr/lib64
On any other platform, run the configure script without any arguments:
$ ./configure
Finally, compile and install Asterisk:
$ make
$ sudo make install
$ sudo make config
(make compiles the code, make install moves the compiled code to the correct location
on the filesystem, and make config configures the operating system to treat Asterisk as
a service, so that it will start at boot time.)
Even More Documentation Goodness
In Asterisk 11, full documentation for the Asterisk Manager Interface (and in the future,
likely even more documentation articles) can be had if Asterisk is built with make full
versus just make. The resulting files are located in the /doc subdirectory of your Asterisk
source, and are also installed into /var/lib/asterisk/documentation.
With the files now installed in their default locations, we need to modify the permissions
of the directories and their contents.
How to Install It
www.it-ebooks.info
|
55
There is an additional step that is not strictly required but is quite com‐
mon (and arguably important): the make menuselect command, which
provides a graphical interface that allows detailed selection of which
modules and features will be compiled. We will discuss this in “make
menuselect” on page 64.
Setting File Permissions
In order to run our system more securely, we’ll be installing Asterisk and then running
it as the asteriskpbx user. After installing the files into their default locations, we need
to change the file permissions to match those of the user we’ll be running as. Execute
the following commands after running make install (which we did previously):
$
$
$
$
sudo
sudo
sudo
sudo
chown
chown
chown
chown
-R
-R
-R
-R
asteriskpbx:asteriskpbx
asteriskpbx:asteriskpbx
asteriskpbx:asteriskpbx
asteriskpbx:asteriskpbx
/var/lib/asterisk/
/var/spool/asterisk/
/var/log/asterisk/
/var/run/asterisk/
In order to use MeetMe() and DAHDI with Asterisk as non-root, you must change
the /etc/udev/rules.d/dahdi.rules so that the OWNER and GROUP fields match the non-root
user Asterisk will be running as. In this case, we’re using the asteriskpbx user.
Change the last line of the dahdi.rules file to the following:
SUBSYSTEM=="dahdi", OWNER="asteriskpbx", GROUP="asteriskpbx", MODE="0660"
With that out of the way, we can move on to performing the base configuration that
should be done after all installations.
Base Configuration
Now that we’ve got Asterisk installed, we can get our system up and running. The pur‐
pose here is to get Asterisk loaded up and ready to go, as it isn’t doing anything useful
yet. These are the steps that all system administrators will need to start out with when
installing a new system. If the commands that need to be run differ on RHEL and
Ubuntu, you will see a table with rows labeled for each distribution; otherwise, you will
see a single command that should be run regardless of which Linux distribution you
have chosen.
Initial Configuration
In order to get Asterisk up and running cleanly, we need to create some configuration
files. We could potentially install the sample files that come with Asterisk (by executing
the make samples command in our Asterisk source) and then modify those files to suit
our needs, but the make samples command installs many sample files, most of them for
modules that you will never use. We want to limit which modules we are loading, and
56
|
Chapter 3: Installing Asterisk
www.it-ebooks.info
we also believe that it’s easier to understand Asterisk configuration if you build your
config files from scratch, so we’re going to create our own minimal set of configuration
files.16
The first thing we need to do (assuming it does not already exist) is create the /etc/
asterisk directory where our configuration files will live:
$ sudo mkdir -p /etc/asterisk/
$ sudo chown asteriskpbx:asteriskpbx /etc/asterisk/
You only need write permissions on /etc/asterisk for the instructions
below and for certain optional Asterisk features like file-based
voicemail configuration. (Users changing their voicemail PIN, for
example.)
Using make samples to Create Sample
Configuration Files for Future Reference
Even though we are not going to use the sample configuration files that come with
Asterisk, the fact is that they are an excellent reference. If there is a module that you are
not currently using but wish to put into production, the sample file will show you exactly
what syntax to use and what options are available for that module.
Running the sudo make samples command in your Asterisk source directory17 is harm‐
less on a new system that has just been built, but it is very dangerous to run on a system
that already has configuration files, as this command will overwrite any existing files
(which would be a disaster for you if you do not have a current backup).
If you’ve run the sudo make samples command, you will want to move the files that it
has created in /etc/asterisk to another folder. We like to create a folder called /etc/asterisk/
unused and put any sample/unused configuration files in there, but feel free to store
them wherever you like.
Running make samples on a system that already has configura‐
tion files will overwrite the existing files.
16. If your /etc/asterisk folder has files in it already, move those files to another directory, or delete them if you
are sure you don’t need what is there.
17. /usr/src/asterisk-complete/asterisk/asterisk-11./
Base Configuration
www.it-ebooks.info
|
57
We’re now going to step through all the files that are required to get a simple Asterisk
system up and running.
indications.conf and asterisk.conf
The first file needed is indications.conf, a file that contains information about how to
detect different telephony tones for different countries. There is a perfectly good sample
file that we can use in the Asterisk source, so let’s copy it into our /etc/asterisk directory:
$ cp ~/src/asterisk-complete/asterisk/11/configs/indications.conf.sample \
/etc/asterisk/indications.conf
Because we’re running Asterisk as non-root, we need to tell Asterisk which user to run
as. This is done with the asterisk.conf file. We can copy a sample version of it from the
Asterisk source to /etc/asterisk:
$ cp ~/src/asterisk-complete/asterisk/11/configs/asterisk.conf.sample \
/etc/asterisk/asterisk.conf
The asterisk.conf file contains many options that we won’t go over here (they are covered
in “asterisk.conf ” on page 77), but we do need to make an adjustment. Near the end of
the [options] section, there are two options we need to enable: runuser and rungroup.
Open the asterisk.conf file with an editor such as nano or vim: uncomment the runus
er and rungroup lines, and modify them so that they each contain asteriskpbx as the
assigned value. Open the /etc/asterisk/asterisk.conf file with vim:
$ vim /etc/asterisk/asterisk.conf
Then modify the file by uncommenting the two lines starting with runuser and run
group and modifying the value to asteriskpbx:
runuser=asteriskpbx
rungroup=asteriskpbx
We now have all the configuration files required to start a very minimal version of
Asterisk.18 Give it a shot by starting Asterisk up in the foreground:
$ /usr/sbin/asterisk -cvvv
We are specifying the full path to the asterisk binary, but if you mod‐
ify your PATH system variable to include the /usr/sbin directory you
don’t need to specify the full path. See “Adding a system user” on
page 44 for information about modifying the $PATH environment
variable.
18. So minimal, in fact, that it’s completely useless at this point. But we digress.
58
| Chapter 3: Installing Asterisk
www.it-ebooks.info
Asterisk will start successfully without any errors or warnings (although it does warn
you that some files are missing), and present to you the Asterisk command-line interface
(CLI). At this point there are no modules, minimal core functionality, and no channel
modules with which to communicate, but Asterisk is up and running.
Executing the module show command at the Asterisk CLI shows that there are no ex‐
ternal modules loaded:19
*CLI> module show
Module
0 modules loaded
Description
Use Count
We’ve done this simply to demonstrate that Asterisk can be run in a very minimal state,
and doesn’t require the dozens of modules that a default install will enable. Let’s stop
Asterisk with the core stop now CLI command:
*CLI> core stop now
The Asterisk Shell Command
Asterisk can be run either as a daemon or as an application. In general, you will want
to run it as an application when you are building, testing, and troubleshooting, and as
a daemon when you put it into production.
The command to start Asterisk is the same regardless of whether you’re running it as a
daemon or an application:
asterisk
However, without any arguments, this command will assume certain defaults and start
Asterisk as a background application. In other words, you never want to run the com‐
mand asterisk on its own, but rather will want to pass some options to it to better define
the behavior you are looking for. The following list provides some examples of common
usages:
-h
-c
This command displays a helpful list of the options you can use. For a complete list
of all the options and their descriptions, run the command man asterisk.
This option starts Asterisk as an application (in the foreground). This means that
Asterisk is tied to your user session. In other words, if you close your user session
by logging out or losing the connection, Asterisk dies. This is the option you will
typically use when building, testing, and debugging, but you would not want to use
19. You might see the res_adsi module, but you can ignore this, as it’s a bug with certain distro versions and
nothing to be concerned about.
Base Configuration
www.it-ebooks.info
|
59
it in production. If you started Asterisk in this manner, type core stop now at the
CLI prompt to stop Asterisk and exit.
-v, -vv, -vvv, -vvvv, etc.
This option can be used with other options (e.g., -cvvv) in order to increase the
verbosity of the console output. It does exactly the same thing as the CLI command
core set verbose n where n is any integer between 0 and 5 (any integer greater than
5 will work, but will not provide any more verbosity). Sometimes it’s useful to not
set the verbosity at all. For example, if you are looking to see only startup errors,
notices, and warnings, leaving verbosity off will prevent all the other startup mes‐
sages from being displayed.
-d, -dd, -ddd, -dddd, etc.
This option can be used in the same way as -v, but instead of normal output, this
will specify the level of debug output (which is primarily useful for developers who
wish to troubleshoot problems with the code). You will also need to enable output
of debugging information in the logger.conf file (which we will cover in more detail
in Chapter 24).
-r
This command is essential if you want to connect to the CLI of an Asterisk process
running as a daemon. You will probably use this option more than any other for
Asterisk systems that are in production. This option will only work if you have a
daemonized instance of Asterisk already running. To exit the CLI when this option
has been used, type exit.
-T
-x
-g
This option will add a timestamp to CLI output.
This command allows you to pass a string to Asterisk that will be executed as if it
had been typed at the CLI. As an example, to get a quick listing of all the channels
in use without having to start the Asterisk console, simply type asterisk -rx 'core
show channels' from the shell, and you’ll get the output you are looking for.
This option instructs Asterisk to dump a core file if it crashes.
We recommend you try out a few combinations of these commands to see what they
do.
60
| Chapter 3: Installing Asterisk
www.it-ebooks.info
safe_asterisk
When you install Asterisk using the make config directive, it will create a script called
safe_asterisk, which is run during the init process of Linux each time you boot.
The safe_asterisk script provides the following benefits:
• Restarts Asterisk automatically after a crash
• Can be configured to email the administrator if a crash has occurred
• Defines where crash files are stored (/tmp by default)
• Executes a script if a crash has occurred
You don’t need to know too much about this script, other than to understand that it
should normally be running. In most environments this script works fine in its default
format.
modules.conf
So, we’ve managed to get Asterisk running, but it’s not able to do anything useful for us
yet. To tell Asterisk what modules we expect it to load, we’ll need a modules.conf file.
Create the file modules.conf in your /etc/asterisk directory with the following command
(replace the >> with > if you instead want to overwrite an existing file):
$ cat >> /etc/asterisk/modules.conf
Type (or paste) the following lines, and press Ctrl+D on a new line when you’re
finished:
; The modules.conf file, used to define which modules Asterisk should load (or
; not load).
;
[modules]
autoload=yes
Ctrl+D
Base Configuration
www.it-ebooks.info
|
61
Using cat to Quickly Create Files and Add Content to Them
There are many cases in a Linux system where it is necessary to create a file, and then
add some content to it. This is commonly done by using the touch command to create
the file, and then opening it with an editor to add the content. However, there is a lessknown way of doing this that lets you create the file and add the content all at once:
• Use the cat program to redirect output to the file you want (use >> to append, or
> to overwrite).
• Paste or type the content you want to add to the file.
• Press Ctrl+D to complete your changes.
Presto! File created and content added.
The autoload=yes line will tell Asterisk to automatically load all modules located in
the /usr/lib/asterisk/modules directory. If you wanted to, you could leave the file like
this, and Asterisk would simply load any modules it found in the modules folder.
With your new modules.conf file in place, starting Asterisk will cause a whole slew of
modules to be loaded. You can verify this by starting Asterisk and running the module
show command:
$ asterisk -c
*CLI> module show
Module
app_adsiprog.so
app_alarmreceiver.so
...
res_timing_timerfd.so
195 modules loaded
Description
Asterisk ADSI Programming Application
Alarm Receiver for Asterisk
Use Count
0
0
Timerfd Timing Interface
0
We now have many modules loaded, and many additional dialplan applications and
functions at our disposal.
You’ll notice some modules not getting loaded because their configu‐
ration files have not been created. We’ll deal with the modules we care
about later.
We don’t need all these resources loaded, though, so let’s filter out some of the more
obscure modules that we don’t need at the moment. Modify your modules.conf file to
contain the following noload lines, which will tell Asterisk to skip loading the identified
modules:
62
|
Chapter 3: Installing Asterisk
www.it-ebooks.info
; The modules.conf file, used to determine which modules Asterisk should load (or
; not load.
;
[modules]
autoload=yes
; Resource modules
noload => res_speech.so
noload => res_phoneprov.so
noload => res_ael_share.so
noload => res_clialiases.so
noload => res_adsi.so
; PBX modules
noload => pbx_ael.so
noload => pbx_dundi.so
; Channel
noload =>
noload =>
noload =>
noload =>
noload =>
noload =>
noload =>
modules
chan_oss.so
chan_mgcp.so
chan_skinny.so
chan_phone.so
chan_agent.so
chan_unistim.so
chan_alsa.so
; Application modules
noload => app_nbscat.so
noload => app_amd.so
noload => app_minivm.so
noload => app_zapateller.so
noload => app_ices.so
noload => app_sendtext.so
noload => app_speech_utils.so
noload => app_mp3.so
noload => app_flash.so
noload => app_getcpeid.so
noload => app_setcallerid.so
noload => app_adsiprog.so
noload => app_forkcdr.so
noload => app_sms.so
noload => app_morsecode.so
noload => app_followme.so
noload => app_url.so
noload => app_alarmreceiver.so
noload => app_disa.so
noload => app_dahdiras.so
noload => app_senddtmf.so
noload => app_sayunixtime.so
noload => app_test.so
noload => app_externalivr.so
noload => app_image.so
Base Configuration
www.it-ebooks.info
|
63
noload => app_dictate.so
noload => app_festival.so
There are, of course, other modules that you could remove, and others that you may
find extremely useful, so feel free to tweak this file as you wish. Ideally, you should be
loading only the modules that you need for the system you are running. The examples
in this book assume that your modules.conf file looks like our example here.
Additional information about the modules.conf file can be found in the section “mod‐
ules.conf ” on page 83.
musiconhold.conf
The musiconhold.conf file defines the classes for music on hold (MOH) in your Asterisk
system. By defining different classes, you can specify different hold music to be used in
various situations, such as different announcements to be played while holding in a
queue, or different hold music if you have multiple PBXs hosted on the same system.
For now, we’ll just create a default MOH class, so we have at least some music to play
when placing callers on hold:
$ cd /etc/asterisk/
$ cat > musiconhold.conf
; musiconhold.conf
[general]
[default]
mode=files
directory=moh
Ctrl+D
We’ve created a musiconhold.conf file and defined our [default] hold music class. We’re
also assuming you installed the hold music from the menuselect system; by default there
is at least one MOH package installed, so unless you disabled it, you should have music
in at least one format.
Additional information about musiconhold.conf can be found in the section “musicon‐
hold.conf ” on page 86.
make menuselect
menuselect is a text-based menu system in Asterisk used to configure which modules
to compile and install. The modules are what give Asterisk its power and functionality.
New modules are constantly being created.
64
|
Chapter 3: Installing Asterisk
www.it-ebooks.info
Within each of the different categories, the list of modules is further
broken down into three sections, which represent the support states of
the modules. More information about the module support states is
available in “Modules” on page 10 and on the Asterisk wiki.
In the installation sections, we conveniently skipped over using the menuselect system
in order to keep the instructions simple and straightforward. However, it is important
enough that we have given menuselect its own section.
In addition to specifying which modules to install, menuselect also allows you to set
flags that can aid in debugging issues (see Chapter 2), set optimization flags, choose
different sound prompt files and formats, and do various other nifty things.
Uses for menuselect
We would need a whole chapter in order to fully explore menuselect, and for the most
part you won’t need to make many changes to it. However, the following example will
give you an idea of how menuselect works, and it is recommended for any installation.
By default Asterisk only installs the core sound prompt files, and only in GSM format.
Also, the three OpSound MOH files available for download are only selected in .wav
format.20
We’re going to want extra sound prompts installed instead of just the default core sound
prompts, and in a better-sounding format than GSM. We can do this with the
menuselect system by running make menuselect in the Asterisk source directory. Before
exploring that, though, let’s talk about the different menuselect interfaces.
menuselect interfaces
There are two interfaces available for menuselect: curses and newt. If the libnewt li‐
braries are installed, you will get the blue and red interface shown in Figure 3-1. Other‐
wise, by default menuselect will use the curses (black and white) interface shown in
Figure 3-2.
20. A good way to put the final touches on your new system is to install some appropriate sound files to be used
as MOH. There are only three songs installed by default, and callers will quickly tire of listening to the same
three songs over and over again. We’ll discuss this more in “musiconhold.conf ” on page 86.
Base Configuration
www.it-ebooks.info
|
65
The minimum screen size for the curses interface is 80×27 pixels, which
means it may not load if you’re using the default terminal size for a
simple distribution installation. This is not a problem when you’re using
SSH to reach the server remotely, as typically your terminal can be re‐
sized, but if you’re working at the terminal directly you may need to
have screen buffers installed to enable a higher resolution, which is not
recommended for a system running Asterisk. The solution is to use the
newt-based menuselect system.
Figure 3-1. menuselect using the newt interface
66
| Chapter 3: Installing Asterisk
www.it-ebooks.info
Figure 3-2. menuselect using the curses interface
Installing Dependencies for newt-Based menuselect
To get the newt-based menuselect working, you need to have the libnewt development
libraries installed:
RHEL
sudo yum install libnewt-devel
Ubuntu
sudo apt-get install libnewt-dev
If you’ve previously used menuselect with the curses interface, you need to rebuild. You
can do this with the following commands:
$
$
$
$
$
$
cd ~/src/asterisk-complete/asterisk/11./
cd menuselect
make clean
./configure
cd ..
make menuselect
After that you should have the newt-based interface available to you.
Base Configuration
www.it-ebooks.info
|
67
Using menuselect
Run the following commands to start menuselect:
$ cd ~/src/asterisk-complete/asterisk/11./
$ make menuselect
You will be presented with a screen like the one in either Figure 3-1 or Figure 3-2. You
can use the arrow keys on your keyboard to move up and down. The right arrow key
will take you into a submenu, and the left arrow key will take you back. You can use the
space bar or Enter key to select and deselect modules. Pressing the q key will quit
without saving, while the x key will save your selections and then quit.
Module Dependencies
Modules that have XXX in front of them cannot be compiled because the configure script
was not able to find the dependencies required (for example, if you don’t have the
unixODBC development package installed, you will not be able to compile func_odbc21).
Whenever you install a dependency, you will always need to rerun configure before you
run menuselect, so that the new dependency will be properly located. The dependent
module will at that point be available in menuselect. If the module selection still contains
XXX, either the configure script is still unable to find the dependency or not all depen‐
dencies have been satisfied.
Once you’ve started menuselect, scroll down to Core Sound Packages and press the
right arrow key (or Enter) to open the menu. You will be presented with a list of available
options. These options represent the core sound files in various languages and formats.
By default, the only set of files selected is CORE-SOUNDS-EN-GSM, which is the Englishlanguage Core Sounds package in GSM format.
Select CORE-SOUNDS-EN-WAV and CORE-SOUNDS-EN-ULAW (or ALAW if you’re outside of
North America or Japan22), and any other sound files that may be applicable in your
network.
The reason we have multiple formats for the same files is that As‐
terisk can play back the appropriate format depending on which
codec is negotiated by an endpoint. This can lower the CPU load
on a system significantly.
21. Which we will cover in Chapter 16, along with many other cool things.
22. If you want to understand all about mu-law and A-law, read the section “Logarithmic companding” on page
727. All you need to know here is that outside of North America and Japan, A-law is used.
68
|
Chapter 3: Installing Asterisk
www.it-ebooks.info
After selecting the appropriate sound files, press the left arrow key to go back to the
main menu. Then scroll down two lines to the Extra Sound Packages menu and press
the right arrow key (or Enter). You will notice that by default there are no packages
selected. As with the core sound files, select the appropriate language and format to be
installed. A good option is probably to install the English sound files in the WAV, ULAW,
and ALAW formats.
Once you’ve completed selecting the sound files, press the x key to save and exit
menuselect. You then need to install your new prompts by downloading them from the
Asterisk downloads site. This is done simply by running make install again:
$ sudo make install
$ sudo chown -R asteriskpbx:asteriskpbx /var/lib/asterisk/sounds/
The files will be downloaded, extracted, and installed into the appropriate location
(/var/lib/asterisk/sounds/ by default). Your Asterisk server will need to have
a working Internet connection in order to retrieve the files.
Scripting menuselect
Administrators often build tools when performing installations on several machines,
and Asterisk is no exception. If you need to install Asterisk onto several machines, you
may wish to build a set of scripts to help automate this process. The menuselect system
contains command-line options that you can use to enable or disable the modules that
are built and installed by Asterisk.
If you are starting with a fresh checkout of Asterisk, you must first execute the
configure script in order to determine what dependencies are installed on the system.
Then you need to build the menuselect application and run the make menuselect-tree
command to build the initial tree structure:
$ cd ~/src/asterisk-complete/asterisk/11./
$ ./configure
$ cd menuselect
$ make menuselect
$ cd ..
$ make menuselect-tree
Generating input for menuselect ...
For details about the options available, run menuselect/menuselect --help from the top
level of your Asterisk source directory. You will see output similar to this:
Usage: menuselect/menuselect [--enable