Asterisk™ · The Definitive Guide by Horn, KielVan -- Read -- Imperial Library of Trantor

Index

Asterisk™: The Definitive Guide Asterisk™: The Definitive Guide

Russell Bryant Leif Madsen Jim Van Meggelen Special Upgrade Offer Foreword Matt Jordan (Engineering Manager, Digium) Alex Balashov (Principal, Evariste Systems) Kevin McAllister (VP of Engineering, CoreDial, LLC) Brian Capouch (Computer Science Department, Saint Joseph’s College [Indiana]) Preface Audience Organization Software Conventions Used in This Book

Tip Warning

Using Code Examples Safari® Books Online

Note

How to Contact Us Acknowledgments

Leif Madsen Jim Van Meggelen Russell Bryant

Chapter 1. A Telephony Revolution 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 Warning Asterisk Wiki Sites The IRC Channels Asterisk User Groups The Asterisk Documentation Project

The Business Case Conclusion Chapter 2. Asterisk Architecture Modules

Note Applications Bridging Modules Call Detail Recording Modules Note Channel Event Logging Modules Channel Drivers Codec Translators Note Tip Format Interpreters Dialplan Functions PBX Modules Resource Modules

Configuration backends Timing interfaces

Note

Calendar integration RTP implementations Format attribute handlers CLI extensions Other 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 Tip The Current Release Methodology Simplifying the Version Numbers

Conclusion Chapter 3. Installing Asterisk Installation Cheat Sheet

Note Note Tip

Distribution Installation

RHEL Server

Base system installation

Note

Base system update Enabling NTP for accurate system time Adding a system user

Ubuntu Server

Base system installation

Tip Note Warning

Base system update

Tip

Enable NTP for accurate system time

Software Dependencies

Tip

Downloading What You Need

Getting the Source via Subversion Note Getting the Source via wget

How to Install It

DAHDI Tip Warning Note LibPRI Note Asterisk Note Setting File Permissions

Base Configuration

Initial Configuration Tip Warning

indications.conf and asterisk.conf

Tip

modules.conf

Note

musiconhold.conf

make menuselect Note

Uses for menuselect menuselect interfaces

Tip

Using menuselect

Note

Scripting menuselect

Tip

Updating Asterisk

Note Tip Tip Warning

Common Issues

Note -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 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

Note

Conclusion Chapter 4. Initial Configuration Tasks asterisk.conf

Note The [directories] Section Note The [options] Section The [files] Section The [compat] Section

modules.conf

The [modules] Section Note

indications.conf

Note

musiconhold.conf

Tip Converting Music to a Format That Works Best with Asterisk

RHEL

Tip

Ubuntu

Note

Completing file conversion

Default musiconhold.conf file Note

The [general] section The music on hold classes sections

Additional Configuration Files Conclusion Chapter 5. User Device Configuration Telephone Naming Concepts Hardphones, Softphones, and ATAs Configuring Asterisk

Note Tip How Channel Configuration Files Work with the Dialplan sip.conf Note Warning Note Tip Tip Warning Tip iax.conf Tip Note Warning Tip Warning Modifying Your Channel Configuration Files for Your Environment Tip

Digium Phones with Asterisk Loading Your New Channel Configurations

The Asterisk CLI Note

Testing to Ensure Your Devices Have Registered

Note Note

Analog Phones

Tip Tip Tip

A Basic Dialplan to Test Your Devices Under the Hood: Your First Call

Asterisk as a B2BUA

Conclusion Chapter 6. Dialplan Basics Dialplan Syntax

Tip Contexts Note Note Warning Extensions Tip Priorities

Unnumbered priorities The same => operator Priority labels

Warning Applications Tip The Answer(), Playback(), and Hangup() Applications Tip

A Simple Dialplan

Hello World Tip Warning

Building an Interactive Dialplan

The Goto(), Background(), and WaitExten() Applications Note Tip Handling Invalid Entries and Timeouts Using the Dial() Application

Argument 1: destination Argument 2: timeout Argument 3: option Argument 4: URI

Tip

Updating the dialplan Blank arguments

Using Variables Tip

Global variables Channel variables Environment variables Adding variables to our dialplan

Pattern Matching

Pattern-matching syntax

Warning Note Warning

Pattern-matching examples Using the ${EXTEN} channel variable

Includes

Conclusion Chapter 7. Outside Connectivity The Basics of Trunking Fundamental Dialplan for Outside Connectivity

Warning

PSTN Circuits

Traditional PSTN Trunks

Analog telephony Digital telephony

Installing PSTN Trunks

Downloading and installing DAHDI

Note Tip

Configuring digital circuits

Tip

PRI ISDN

Note

BRI ISDN

Note

MFC/R2 Configuring analog circuits

Note

The s extension

VoIP

Coping with Network Address Translation

Devices behind NAT

Warning

Asterisk behind NAT

Note

Media (RTP) handling

Note PSTN Termination Warning PSTN Origination Note VoIP to VoIP Configuring VoIP Trunks

Configuring SIP trunks between Asterisk systems

Connecting two Asterisk systems together with SIP

Note Note

Connecting an Asterisk system to a SIP provider Encrypting SIP calls

Warning

Configuring IAX trunks between Asterisk systems

IAX trunking IAX encryption

Emergency Dialing Conclusion Chapter 8. Voicemail Comedian Mail

The [general] Section The [zonemessages] Section The Contexts Section Note Warning An Initial voicemail.conf File Note Standard Voicemail KeyMap

Dialplan Integration

The VoiceMail() Dialplan Application The VoiceMailMain() Dialplan Application Creating a Dial-by-Name Directory Using a Jitterbuffer

Storage Backends

Linux Filesystem Note Note ODBC IMAP

Using Asterisk as a Standalone Voicemail Server

Integrating Asterisk into a SIP Environment as a Standalone Voicemail Server Note

Dialplan requirements

Note

sip.conf requirements

SMDI (Simplified Message Desk Interface)

Database Integration Conclusion Chapter 9. Internationalization

David Duffett

Devices External to the Asterisk Server PSTN Connectivity, DAHDI, Digium Cards, and Analog Phones

Note DAHDI Drivers Tip Tip

Asterisk

Caller ID Language and/or Accent of Prompts Time/Date Stamps and Pronunciation

Conclusion—Easy Reference Cheat Sheet Chapter 10. Deeper into the Dialplan Expressions and Variable Manipulation

Note Basic Expressions Operators Note

Dialplan Functions

Note Syntax Examples of Dialplan Functions

Conditional Branching

The GotoIf() Application Note Time-Based Conditional Branching with GotoIfTime() Note Note Tip

Macros

Note Tip Tip Defining Macros Calling Macros from the Dialplan Using Arguments in Macros Note

GoSub

Defining Subroutines Calling Subroutines from the Dialplan Note Using Arguments in Subroutines Returning from a Subroutine

Local Channels Using the Asterisk Database (AstDB)

Tip 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 Tip Note Warning

Handy Asterisk Features

Zapateller() Call Parking Tip Conferencing with MeetMe() Warning Conferencing with ConfBridge() Note Note

Conclusion Chapter 11. Parking, Paging, and Conferencing features.conf

The [general] section Note The [featuremap] Section Note The [applicationmap] Section Note Note Application Map Grouping Note Parking Lots

Overhead and “Underchin” Paging (a.k.a. Public Address)

Places to Send Your Pages

External paging Set paging

Warning

Multicast paging via the MulticastRTP channel VoIP paging adapters Combination paging Bringing it all together

Zone Paging

Advanced Conferencing

The [general] Section Options for User Profiles Options for Bridge Profiles

Customizable conference bridge sounds

ConfBridge Menu Options Tip Enabling a PIN Waiting for the Marked User to Join Note Using ConfBridge() Menus

Our first menu: volume control

Note

Advanced menus: using dialplan_exec

Note Enabling Videoconferencing

Conclusion Chapter 12. Internet Call Routing DNS and SIP URIs

The SIP URI SRV Records Accepting Calls to Your System

Modifying sip.conf Standard dialplan File parsing

Tip Note

Database lookup

Warning Note Dialing SIP URIs from Asterisk

ENUM and E.164

E.164 and the ITU Warning ENUM Asterisk and ENUM

ISN, ITAD, and freenum.org

Got ISN? Tip ITAD Subscriber Numbers (ISNs) Management of Internet Numbering IP Telephony Administrative Domains (ITADs) Create a DNS Entry for Your ITAD Note Testing Your ITAD Using ISNs in Your Asterisk System Note

Receiving calls to your ITAD

Security and Identity

Toll Fraud Note Spam over Internet Telephony (SPIT) Distributed Denial of Service Attacks Phishing Security Is an Ongoing Process

Conclusion Chapter 13. Automatic Call Distribution (ACD) Queues

Note Note

Creating a Simple ACD Queue

Note Note Note Note

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) Note Announcement Control Overflow

Controlling timeouts Controlling when to join and leave a queue

Using Local Channels Tip Warning

Queue Statistics: The queue_log File Conclusion Chapter 14. Device States Device States

Checking Device States Note

Extension States

Hints Checking Extension States

SIP Presence

Asterisk Configuration Tip Note

Using Custom Device States

An Example

Distributed Device States

Using Corosync

Installation

Note

Corosync configuration

Tip

Asterisk configuration Testing device state changes

Using XMPP

Installation

Note

Creating XMPP accounts Asterisk configuration Testing

Shared Line Appearances

Installing the SLA Applications Note Configuration Overview Key System Example with Analog Trunks

sla.conf extensions.conf

Warning

Additional phone configuration tasks

Key System Example with SIP Trunks

sla.conf extensions.conf

Alternate Key System Example with SIP Trunks Tip Shared Extension Example

sla.conf extensions.conf

Additional Configuration Limitations

Creating a Callback Service Conclusion Chapter 15. The Automated Attendant An Auto Attendant Is Not an IVR Designing Your Auto Attendant

The Greeting The Main Menu

Selection 1 Selection 2 Selection # Selection 3 Selection 9 Selection 0

Timeout Invalid Dial by Extension Note

Building Your Auto Attendant

Recording Prompts Note

Using the dialplan to create recordings

The Dialplan Delivering Incoming Calls to the Auto Attendant IVR

Conclusion Chapter 16. Relational Database Integration Installing and Configuring PostgreSQL and MySQL

Installing PostgreSQL for RHEL Installing PostgreSQL for Ubuntu Installing MySQL for RHEL Installing MySQL for Ubuntu Configuring PostgreSQL Note Note Configuring MySQL

Installing and Configuring ODBC

Tip Warning Configuring ODBC for PostgreSQL Note Configuring ODBC for MySQL Note Note Configuring ODBC for Microsoft SQL Note Validating the ODBC Connector Note Compiling the ODBC Modules for Asterisk Configuring res_odbc to Allow Asterisk to Connect Through ODBC Note

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

Note Tip Tip Tip Note Note

Using Realtime

Tip Static Realtime Note Dynamic Realtime

Storing Call Detail Records (CDR)

Note Note

ODBC Voicemail Message Storage

Note Note Compiling the app_voicemail Module to Support ODBC Storage Note Creating the Large Object Type for PostgreSQL Note ODBC Voicemail Storage Table Layout Configuring voicemail.conf for ODBC Storage Tip Testing ODBC Voice Message Storage Note Tip

Verifying binary data stored in PostgreSQL Verifying binary data stored in MySQL

Tip Note

Database Integration of ACD Queues

Storing queues.conf in a Database

Storing queues.conf using Static Realtime Storing queues.conf using Dynamic Realtime

Warning Storing Dialplan Parameters for a Queue in a Database Writing queue_log to Database

Conclusion Chapter 17. Interactive Voice Response What Is IVR?

Caution

Components of an IVR IVR Design Considerations Asterisk Modules for Building IVRs

CURL func_odbc AGI AMI

A Simple IVR Using CURL

Note Installing the cURL Module The Dialplan

A Prompt-Recording Application Speech Recognition and Text-to-Speech

Text-to-Speech Speech Recognition

Conclusion Chapter 18. External Services Calendar Integration

Compiling Calendaring Support into Asterisk

RHEL dependencies

Note Note

Ubuntu dependencies

Note Configuring Calendar Support for Asterisk Tip Tip Tip Triggering Calendar Reminders to Your Phone

Triggering a wakeup call

Tip Tip

Scheduling calls between two participants

Note

Calling meeting participants and placing them into a conference

Controlling Calls Based on Calendar Information Writing Call Information to a Calendar Additional Features

Voicemail IMAP Integration

Compiling IMAP Voicemail Support into Asterisk

RHEL dependencies Ubuntu dependencies

Note

Compiling the IMAP library

Note Note

Compiling Asterisk

Tip

Configuring Asterisk

Enabling IMAP on Gmail Configuring voicemail.conf for IMAP

Note

Using XMPP (Jabber) with Asterisk

Compiling XMPP Support into Asterisk

RHEL dependencies

Note

Ubuntu dependencies Installing res_xmpp

Jabber Dialplan Commands

Connecting to an XMPP server

Note

Sending messages with JabberSend() Receiving messages with JABBER_RECEIVE()

Tip chan_motif

motif.conf Accepting calls from Google Talk Accepting calls from Google Voice Outgoing calls via Google Talk

Note

Outgoing calls via Google Voice

Out-of-Band Messaging (Messaging Infrastructure)

xmpp.conf Configuration sip.conf Configuration Tip Dialplan Configuration Note

LDAP Integration

Configuring OpenLDAP Note Compiling LDAP Support into Asterisk

Ubuntu dependencies RHEL dependencies

Configuring Asterisk for LDAP Support

Configuring res_ldap.conf Configuring extconfig.conf

Tip

Configuring sip.conf for realtime

Note

Text-to-Speech Utilities

Festival

Installing Festival on RHEL Installing Festival on Ubuntu Using Festival with Asterisk

Cepstral

Conclusion Chapter 19. Fax 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

Warning Fax to TIFF Note Fax to Email Fax Detection Using T.38 Tip

Outgoing Fax Handling

Transmitting a Fax from Asterisk File Format for Faxing An Experiment in Email to Fax Note

Fax Pass-Through

Using Fax Buffers in chan_dahdi.conf T.38 Gateway

Conclusion Chapter 20. Asterisk Manager Interface (AMI) Quick Start

Note AMI over TCP AMI over HTTP Note

Configuration

manager.conf Warning http.conf Note

Protocol Overview

Message Encoding

Events

Note

Actions

AMI over HTTP

Authentication and session handling /rawman encoding /manager encoding /mxml encoding Manager events

Call Files

Warning

Example Usage

Originating a Call Redirecting a Call Tip Originating a Call Using Python and StarPy Note

Development Frameworks

CSTA

Interesting Applications

Flash Operator Panel

Conclusion Chapter 21. Asterisk Gateway Interface (AGI) Quick Start AGI Variants

Process-Based AGI Tip

EAGI

Tip DeadAGI Is Dead FastAGI—AGI over TCP Async AGI—AMI-Controlled AGI Tip

AGI Communication Overview

Setting Up an AGI Session

Process-based AGI/FastAGI Async AGI

Note Commands and Responses Note

Process-based AGI/FastAGI

Tip

Async AGI

Ending an AGI Session

Process-based AGI/FastAGI

Warning

Async AGI

Example: Account Database Access Development Frameworks Conclusion Chapter 22. Clustering Traditional PBXs Hybrid Systems Pure Asterisk, Nondistributed Asterisk and Database Integration

Single Database Replicated Databases Note

Asterisk and Distributed Device States

Distributing Device States over a LAN Distributing Device States over a WAN

Multiple Queues, Multiple Sites

Note

Conclusion Chapter 23. Distributed Universal Number Discovery (DUNDi) How Does DUNDi Work? The dundi.conf File Configuring Asterisk for Use with DUNDi

General Configuration Initial DUNDi Peer Definition Note Creating Mapping Contexts Warning Using Mapping Contexts with Peers Allowing Remote Connections Tip Tip Controlling Responses

Manually adding responses Using pattern matches Dynamically adding extension numbers Using dialplan functions in mappings

Tip Note Tip Performing Lookups from the Dialplan Note

Conclusion Chapter 24. System Monitoring and Logging logger.conf

Warning Reviewing Asterisk Logs Logging to the Linux syslog Daemon Note Verifying Logging Log Rotation

Call Detail Records

CDR Contents Note Dialplan Applications cdr.conf Backends

cdr_adaptive_odbc cdr_csv cdr_custom

Note

cdr_manager cdr_mysql cdr_odbc cdr_pgsql cdr_radius cdr_sqlite cdr_sqlite3_custom

Note

cdr_syslog cdr_tds

Example Call Detail Records

Single-party call Two-party call

Caveats

CEL (Channel Event Logging)

Channel Event Types Channel Event Contents Dialplan Applications cel.conf Tip Backends

cel_odbc cel_custom

Note

cel_manager cel_pgsql cel_radius cel_sqlite3_custom

Note

cel_tds

Example Channel Events

Single-party call Two-party call Blind transfer

SNMP

Installing the SNMP Module for Asterisk

RHEL dependency Ubuntu dependency

Tip

Recompiling Asterisk with the res_snmp module

Configuring SNMP for Asterisk Using OpenNMS

Installing OpenNMS

Warning

Editing /etc/asterisk/res_snmp.conf to work with your OpenNMS server Editing /etc/snmp/snmpd.conf to work with your OpenNMS server

Tip Monitoring Asterisk with OpenNMS

Conclusion Chapter 25. Web Interfaces Flash Operator Panel Queue Status and Reporting

Queue Status Display Queue Reporting

Call Detail Records A2Billing Conclusion Chapter 26. Security Scanning for Valid Accounts Authentication Weaknesses Fail2ban

Installation Note

iptables Sending email

Configuration

Encrypted Media Dialplan Vulnerabilities Securing Asterisk Network APIs IAX2 Denial of Service Other Risk Mitigation CLI Permissions Resources Conclusion—A Better Idiot Chapter 27. Asterisk: A Future for Telephony 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

Legacy PBX migration gateway Low-barrier IVR Conference rooms Home automation

The Future of Asterisk

Speech Processing

Festival and text-to-speech Speech recognition

High-Fidelity Voice Video

The challenge of videoconferencing Why we love videoconferencing Why videoconferencing may never totally replace voice

WebRTC Wireless

WiFi WiMAX

Unified Messaging Peering

E.164 ENUM e164.org freenum.org

Challenges

Too much change, too few standards Toll fraud VoIP spam Fear, uncertainty, and doubt Bottleneck engineering Regulatory wars Quality of service Complexity

Opportunities

Tailor-made private telecommunications networks Low barrier to entry Creative possibilities Proper integration of communications technologies

Appendix A. Understanding Telephony Analog Telephony

Parts of an Analog Telephone

Ringer

Warning

Dialpad Hybrid (or network)

Hook switch (or switch hook) Handset

Tip and Ring

Digital Telephony

Pulse-Code Modulation

Digitally encoding an analog waveform Increasing the sampling resolution and rate

Tip Tip

Nyquist’s Theorem Logarithmic companding Aliasing

The Digital Circuit-Switched Telephone Network

Circuit Types

The humble DS-0—the foundation of it all T-carrier circuits

Tip

SONET and OC circuits

Digital Signaling Protocols

Channel-associated signaling (CAS) ISDN

ISDN-BRI/BRA ISDN-PRI/PRA

Tip

Signaling System 7

Packet-Switched Networks Conclusion Appendix B. Protocols for VoIP The Need for VoIP Protocols VoIP Protocols

IAX (the “Inter-Asterisk eXchange” Protocol)

History Future Security considerations IAX and NAT

SIP

History Future Security considerations SIP and NAT

H.323 Tip

History Future Security considerations H.323 and NAT

MGCP Proprietary Protocols

Skinny/SCCP UNISTIM

Codecs

G.711 G.726 G.729A GSM iLBC Speex G.722 MP3 Tip

Quality of Service

TCP, UDP, and SCTP

Transmission Control Protocol User Datagram Protocol

Tip

Stream Control Transmission Protocol

Differentiated Service Guaranteed Service

MPLS RSVP

Best Effort

Echo

Why Echo Occurs Managing Echo on DAHDI Channels Hardware Echo Cancellation

Asterisk and VoIP

Users and Peers and Friends—Oh My!

Users Peers Friends

VoIP Security

Spam over Internet Telephony (SPIT) Encrypting Audio with Secure RTP Spoofing What Can Be Done?

Basic network security

Segregating voice and data traffic DMZ Server hardening

Encryption Physical security

Conclusion Appendix C. Preparing a System for Asterisk

Note Note

Server Hardware Selection

Performance Issues Tip Choosing a Processor

Small systems Medium systems Large systems

Choosing a Motherboard Tip Power Supply Requirements

Computer power supplies Redundant power supplies

Environment

Power Conditioning and Uninterruptible Power Supplies

Power-conditioned UPSs

Grounding Tip Tip Electrical Circuits Warning The Equipment Room

Humidity Temperature Dust Security

Telephony Hardware

Connecting to the PSTN

Analog interface cards Digital interface cards Channel banks Other types of PSTN interfaces

Connecting Exclusively to a Packet-Based Telephone Network Echo Cancellation Note

Types of Phones

Physical Telephones

Analog telephones Proprietary digital telephones ISDN telephones

Tip

IP telephones

Softphones Telephony Adapters Communications Terminals

Linux Considerations Conclusion Index

A note on the digital index Symbols A B C D E F G H I J K L M N O P Q R S T U V W X Z

About the Authors Colophon Special Upgrade Offer

Asterisk™: The Definitive Guide

Russell Bryant Leif Madsen Jim Van Meggelen

Editor

Mike Loukides

← Prev
Back
Next →

← Prev
Back
Next →