Asterisk: The Definitive Guide

(1)

FOURTH EDITION

Asterisk:

The

Definitive

Guide

Russell

_Bryant,

_LeifMadsen,

and

_Jim

Van

_Meggelen

O'REILLY8

Beijing

•

(2)

Foreword

xix

Preface

xxv

1. A

_Telephony

Revolution 1

Asterisk and VoIP:

_Bridging

the

_Gap

Between Traditional and Network

Telephony

2

The

_{Zapata Telephony Project}

2

Massive

_{Change Requires}

Flexible

_Technology

3

Asterisk: The Hackers PBX 4

Asterisk: TheProfessional's PBX 5

The

Asterisk

_Community

5

The Asterisk

_Mailing

Lists 6

AsteriskWikiSites 7

The IRC Channels 7

AsteriskUser

_Groups

7 The Asterisk Documentation

_Project

8

TheBusiness Case 8

Conclusion 8

2. Asterisk Architecture

9

Modules 10

Applications

12

Bridging

Modules 15

Call Detail

_Recording

Modules 16

Channel Event

_Logging

Modules 17

Channel Drivers 17

Codec Translators 18

Format

_Interpreters

19

Dialplan

Functions 20

(3)

PBX Modules 22 Resource

Modules

22 Add-on Modules 26 Test Modules 27 FileStructure 27

Configuration

Files 27 Modules 27

TheResource

_Library

28

The

_Spool

28

Logging

28

The

_Dialplan

28

Hardware 29

Asterisk

_Versioning

29 Previous Release

_{Methodologies}

30 The Current Release

_Methodology

31

Simplifying

the VersionNumbers 32

Conclusion 33

3.

_Installing

Asterisk

35

Installation Cheat Sheet 37 Distribution Installation 41

RHEL Server 41

UbuntuServer 45

Software

_Dependencies

49

Downloading

WhatYouNeed 50

Getting

theSource viaSubversion 51

Getting

theSource via

_wget

51

Howto InstallIt 52

DAHDI 52

LibPRI 54

Asterisk 55

Setting

File Permissions 56

Base

_{Configuration}

56

Initial

_{Configuration}

56

make menuselect 64

Updating

Asterisk 70

Common Issues 72

-bash:

_wget:

commandnotfound 73

configure:

error: no

acceptable

C

compiler

foundin $PATH 73 make: gcc: commandnot found 73

configure:

error: C++_preprocessor

"/lib/cpp"

fails

_sanity

check 73

(4)

configure:

error: *** Pleaseinstall GNUmake. It is

_required

tobuild

Asterisk! 73

configure:

***_{XML documentation will}

not beavailable becausethe

'libxml2'

_{development package}

is

_missing.

74

configure:

error: ***

_{termcap support}

notfound 74 Youdo not_appearto have thesourcesfor the 2.6.18-164.6.1.el5 kernel

installed. 74

E: Unabletolock the administration

_{directory (/var/lib/dpkg/),}

are_you

root? 74

Upgrading

Asterisk 74

Conclusion 76

4.

Initial

_{Configuration}

Tasks

77

asterisk.conf 77

The

[directories]

Section 77

The

_[options]

Section 78

The

[files]

Section 82

The

_[compat]

Section 82

modules.conf 83

The

_[modules]

Section 84

indications.conf 84 musiconhold.conf 86

Converting

Musictoa Format ThatWorks BestwithAsterisk 87

Default musiconhold.conf file 89

Additional

_{Configuration}

Files 91

Conclusion 91

5.

User

Device

_{Configuration}

93

Telephone Naming Concepts

94

Hardphones, Softphones,

and ATAs 96

Configuring

Asterisk 98

HowChannel

_{Configuration}

Files Work with the

_Dialplan

99

sip.conf

101

iax.conf

107

Modifying

YourChannel

_{Configuration}

Files for Your Environment 112

Digium

Phones withAsterisk 113

Loading

YourNew

Channel

_{Configurations}

113

The Asterisk CLI 113

Testing

toEnsure Your Devices Have

_Registered

114

Analog

Phones 115

A Basic

_Dialplan

toTest YourDevices 118 Under the Hood: Your First Call 119

(5)

Conclusion 120 6.

_Dialplan

Basics

121

Dialplan Syntax

121 Contexts 122 Extensions 124 Priorities 125

Applications

127

The

_Answer(),

_Playback^),

and

_{HangupQ Applications}

128

A

_{Simple Dialplan}

129

Hello World 129

Building

anInteractive

Dialplan

131

The

_Goto(),

_{Background(),}

and

_{WaitExten() Applications}

131

Handling

Invalid Entries and Timeouts 133

Using

the

_Dial()

_Application

134

Using

Variables 137

Pattern

_Matching

140

Includes 145

Conclusion 145

7.

Outside

_Connectivity

₁₄₇

The Basics of

_Trunking

147

Fundamental

_Dialplan

for Outside

_Connectivity

148

PSTNCircuits 150

TraditionalPSTNTrunks 150

Installing

PSTN Trunks 152

VoIP ₁₆₁

Coping

with

Network Address Translation 161

PSTN Termination 170

PSTN

_Origination

₁₇₁

VoIPtoVoIP ₁₇₃

Configuring

VoIPTrunks ₁₇₃

Emergency Dialing

181

Conclusion ₁₈₃

8.

Voicemail

185

Comedian Mail ₁₈₅

The

_[general]

Section ₁₈₆

The

_{[zonemessages]}

Section ₁₉₅

The ContextsSection ₁₉₆

An Initial

voicemail.conf

File 200

Standard Voicemail

_KeyMap

₂₀₁

(6)

Dialplan Integration

201 The

_VoiceMail()

_{Dialplan Application}

₂₀₁ The

_{VoiceMailMain()}

_Dialplan

_Application

204

Creating

a

_{Dial-by-Name Directory}

₂₀₅

Using

a

Jitterbuffer

205

Storage

Backends

206

Linux

_Filesystem

206

ODBC 207

IMAP 207

Using

Asteriskas aStandalone Voicemail Server 208

Integrating

Asterisk intoaSIPEnvironmentas aStandalone

VoicemailServer 208

SMDI

_{(Simplified Message}

Desk

_Interface)

212

Database

_Integration

213

Conclusion 213

9. Internationalization

215

DevicesExternaltothe AsteriskServer 217

PSTN

_{Connectivity,}

DAHDI,

_Digium

Cards,and

_Analog

Phones 219

DAHDIDrivers 221

Asterisk 224

Caller ID 224

Language

and/or

Accentof

_Prompts

225

Time/Date

_Stamps

andPronunciation 226

Conclusion—Easy

Reference CheatSheet 228

10.

_Deeper

into

the

_Dialplan

231 Expressions

and Variable

_Manipulation

231

Basic

_Expressions

231

Operators

232

Dialplan

Functions 234

Syntax

235

Examples

of

_Dialplan

Functions 235

Conditional

_Branching

236

The

_{GotoIf() Application}

236

Time-Based Conditional

_Branching

with

_GotoIfTime()

240

Macros 242

Defining

Macros 243

Calling

Macros from the

_Dialplan

244

Using Arguments

in Macros 245

GoSub 246

Defining

Subroutines 246

(7)

Calling

Subroutines fromthe

_Dialplan

247

Using Arguments

in Subroutines 248

Returning

from aSubroutine 249

Local Channels 250

Using

the Asterisk Database

(AstDB)

253

Storing

Data in the AstDB 254

Retrieving

Data fromthe AstDB 254

Deleting

Data from the AstDB 254

Using

the AstDB in the

_Dialplan

255

Creating

a

Hot-Desking Application

with AstDB 256

Handy

AsteriskFeatures 261

Zapateller()

261

Call

_Parking

261

Conferencing

with

MeetMe()

263

Conferencing

with

_ConfBridge()

264

Conclusion 266

11.

_{Parking, Paging,}

and

_Conferencing

267

features.conf 267

The

_[general]

section 268

The

_[featuremap]

Section 271

The

_{[applicationmap]}

Section 272

Application Map Grouping

275

Parking

Lots 276

Overheadand"Underchin"

_{Paging (a.k.a.}

Public

Address)

277

PlacestoSendYour

_Pages

278

Zone

_Paging

284

Advanced

_Conferencing

284

The

_[general]

Section 285

Options

forUserProfiles 285

Options

for

_Bridge

Profiles 287

ConfBridge

Menu

_Options

289

Enabling

aPIN 290

Waiting

for the Marked Userto

_Join

292

Using ConfBridge()

Menus 293

Enabling

Videoconferencing

296

Conclusion 298

12. Internet

Call

_Routing

299

DNS and SIP URIs 300

The SIP URI 300

SRV Records 301

(8)

Accepting

CallstoYour

_System

302

Dialing

SIP URIsfromAsterisk 309

ENUMandE.164 310

E. 164and theITU 310

ENUM 311

Asterisk and ENUM 312

ISN, ITAD,

and

_freenum.org

313

GotlSN? 314

ITAD Subscriber Numbers

(ISNs)

315

Management

of Internet

_Numbering

315

IP

_Telephony

Administrative Domains

_(ITADs)

316

CreateaDNS

Entry

for Your ITAD 317

Testing

Your ITAD 318

Using

ISNsinYour Asterisk

_System

318

Security

and

_Identity

320

Toll Fraud 321

Spam

overInternet

_Telephony

(SPIT)

322

Distributed Denial

of

Service Attacks 323

Phishing

323

Security

Isan

Ongoing

Process 323

Conclusion 323

13. Automatic

Call Distribution

_(ACD)

Queues

325

Creating

a

Simple

ACD

Queue

326

Queue

Members 331

Controlling

Queue

Membersviathe CLI 331

Defining

Queue

Members in the

_queues.conf

File 333

Controlling

Queue

Members with

_{Dialplan Logic}

333

Automatically Logging

Into and Out of

_Multiple

Queues

335 An

Introduction

toDevice State 339

The

_queues.conf

File 341

The

_agents.conf

File 349

Advanced

_Queues

3 51

Priority

Queue (Queue

Weighting)

351

Queue

Member

_Priority

353

Changing

Penalties

_{Dynamically (queuerules.conf)}

354

Announcement Control 356

Overflow 361

Using

Local

Channels

363

Queue

Statistics:The

_{queue_log}

File 367

(9)

Conclusion 370

14. Device States 371

Device States 371

Checking

Device States 372

Extension States 373

Hints 374

Checking

Extension States 375

SIP Presence .

376

Asterisk

_{Configuration}

376

Using

Custom Device States 378

An

_Example

378

Distributed DeviceStates 380

Using Corosync

380

Using

XMPP 385

Shared Line

_Appearances

389

Installing

theSLA

_Applications

389

Configuration

Overview 390

Key System Example

with

_Analog

Trunks 390

Key System Example

with SIPTrunks 394

Alternate

_{Key System}

_Example

with SIP Trunks 396

SharedExtension

_Example

399

Additional

_{Configuration}

401

Limitations 402

Creating

aCallbackService 403

Conclusion 405

15.

The Automated Attendant

407

An Auto AttendantIs NotanIVR 407

Designing

Your AutoAttendant 408

The

_Greeting

409

TheMain Menu 410

Timeout 411

Invalid 411

Dial

_by

Extension 412

Building

YourAutoAttendant 412

Recording

Prompts

412

The

_Dialplan

414

Delivering

Incoming

Callsto theAuto Attendant 416

IVR 416

(10)

Conclusion 416

16.

Relational Database

_Integration

417

Installing

and

_Configuring

_PostgreSQL

and

_MySQL

418

Installing

PostgreSQL

forRHEL 418

Installing

PostgreSQL

for Ubuntu 418

Installing MySQL

forRHEL 419

Installing MySQL

for Ubuntu 419

Configuring PostgreSQL

419

Configuring MySQL

421

Installing

and

_Configuring

ODBC 422

Configuring

ODBC for

_PostgreSQL

424

Configuring

ODBC for

_MySQL

425

Configuring

ODBC for Microsoft

SQL

426

Validating

theODBC Connector 427

Compiling

theODBC Modules for Asterisk 428

Configuring

res_odbc

toAllow AsterisktoConnect

_Through

ODBC 428

Managing

Databases 429

Troubleshooting

Database Issues 430

SQL

Injection

430

Powering

Your

_Dialplan

with

_{func_odbc}

431

A Gentle Introductionto

_{func_odbc}

432

Getting

Funky

with

_{func_odbc: Hot-Desking}

433

Using

Realtime 449

Static Realtime 450

Dynamic

Realtime 453

Storing

Call DetailRecords

(CDR)

458

ODBC Voicemail

_{Message Storage}

463

Compiling

the

_{app_voicemail}

Moduleto

_Support

ODBC

_Storage

464

Creating

the

_{Large Object Type}

for

_PostgreSQL

465

ODBC Voicemail

_Storage

Table

_Layout

467

Configuring

voicemail.conf for ODBC

_Storage

468

Testing

ODBC Voice

_Message

_Storage

469

Database

_Integration

of ACD

Queues

473

Storing queues.conf

ina Database 473

Storing Dialplan

Parameters fora

Queue

in aDatabase 476

Writing queue_log

toDatabase 477

Conclusion 478

17.

Interactive

Voice

_Response

479

WhatIs IVR? 479

Components

ofanIVR 480

(11)

IVR

_Design

Considerations 482 AsteriskModulesfor

_Building

IVRs 483

CURL 483

func_odbc

483

AGI 483

AMI 483

A

_Simple

IVR

_Using

CURL 483

Installing

thecURLModule 484

The

_Dialplan

484

A

_{Prompt-Recording Application}

484

Speech Recognition

and

_{Text-to-Speech}

486

Text-to-Speech

486

Speech Recognition

486

Conclusion 487

18.

External

Services 489

Calendar

_Integration

490

Compiling

Calendaring Support

intoAsterisk 490

Configuring

Calendar

_Support

for Asterisk 492

Triggering

Calendar ReminderstoYourPhone 494

Controlling

Calls BasedonCalendar Information 499

Writing

Call Information to aCalendar 501

Additional Features 503

Voicemail IMAP

_Integration

503

Compiling

IMAP Voicemail

_Support

intoAsterisk 504

Using

XMPP

(Jabber)

with Asterisk 511

Compiling

XMPP

_Support

into Asterisk 512

Jabber

Dialplan

Commands 512

chan_motif

518

Out-of-Band

_{Messaging (Messaging Infrastructure)}

522

xmpp.conf Configuration

522

sip.conf

Configuration

523

Dialplan Configuration

524

LDAP

_Integration

₅₂₅

Configuring

OpenLDAP

526

Compiling

LDAP

_Support

into Asterisk 528

Configuring

AsteriskforLDAP

_Support

529

Text-to-Speech

Utilities 531

Festival ₅₃₁

Cepstral

534

(12)

Conclusion ₅₃₄

19.

Fax

535

WhatIsaFax? 535

Ways

toHandleFaxes in Asterisk 535

spandsp

536

Obtaining spandsp

536

Compiling

and

_Installing

_spandsp

537

Adding

the

_{spandsp Library}

toYour

_libpath

537

Recompiling

Asterisk with

_{spandsp Support}

537

Disabling spandsp

(Should

You WanttoTest

_Digium

_Fax)

538

Digium

Fax ForAsterisk 538

Obtaining Digium

FFA 538

Disabling

Digium

FFA

_(Should

You WanttoTest

_spandsp)

539

Incoming

Fax

_Handling

539

FaxtoTIFF 540

FaxtoEmail 541

FaxDetection 542

Using

T.38 543

Outgoing

Fax

_Handling

544

Transmitting

aFax from Asterisk 544

File Format for

_Faxing

545

An

_Experiment

in Emailto Fax 546

Fax

_Pass-Through

549

Using

Fax Buffers in

chan_dahdi.conf

549

T.38

_Gateway

₅₅₀

Conclusion

551

20. Asterisk

_Manager

_{Interface (AMI)}

₅₅₃

Quick

Start 553 AMI overTCP ₅₅₄ AMI overHTTP ₅₅₅

Configuration

556

manager.conf

556

http.conf

561 ProtocolOverview 562

Message Encoding

563 AMIoverHTTP 564 CallFiles 569

Example Usage

571

Originating

aCall 571

Redirecting

aCall 573

(13)

Originating

aCall

Using

Python

and

StarPy

574

Development

Frameworks 579

CSTA 580

Interesting

Applications

580

Flash

_Operator

Panel 580

Conclusion 581

21.

Asterisk

_Gateway

Interface

_(AGI)

583 Quick

Start 583

AGI Variants 585

Process-Based AGI 585

DeadAGI Is Dead 586

FastAGI—AGIoverTCP 586

Async

AGI—AMI-Controlled AGI 587

AGI CommunicationOverview 588

Setting Up

anAGI Session 588

Commands

and

_Responses

590

Ending

anAGI Session 594

Example:

AccountDatabaseAccess 596

Development

Frameworks 599

Conclusion 599

22. _Clustering

601

TraditionalPBXs 602

Hybrid

Systems

603

Pure

Asterisk,

Nondistributed 605

Asterisk and Database

_Integration

606

Single

Database 606

Replicated

Databases 608

Asterisk

and Distributed Device States 609

Distributing

Device Statesover aLAN 610

Distributing

Device Statesover aWAN 611

Multiple

Queues,

Multiple

Sites 613

Conclusion 614

23.

Distributed Universal Number

_Discovery

(DUNDi)

617

How Does DUNDiWork? 617

Thedundi.conf File 619

Configuring

Asterisk forUsewith DUNDi 621

General

_{Configuration}

622

InitialDUNDi PeerDefinition 623

Creating Mapping

Contexts 625

(14)

Using

Mapping

Contexts withPeers ₆₂₇

Allowing

Remote Connections ₆₂₉

Controlling

Responses

₆₃₀

Performing

Lookups

from the

_Dialplan

₆₃₄

Conclusion

637

24.

_System

_Monitoring

and

_Logging.

639 logger.conf

₆₃₉

Reviewing

Asterisk

_Logs

641

Logging

to the Linux

_syslog

_Daemon

642

Verifying Logging

₆₄₃

Log

Rotation

643

Call Detail Records

643 CDRContents 644

Dialplan Applications

₆₄₅

cdr.conf

645

Backends

646

Example

CallDetail Records ₆₅₃

Caveats

653

CEL

_(Channel

Event

_Logging)

654

Channel

Event

_Types

654

Channel

Event Contents ₆₅₅

Dialplan

Applications

₆₅₆

cel.conf

657

Backends

657

Example

Channel Events ₆₆₃

SNMP

668

Installing

theSNMP _{Module for Asterisk}

668

Configuring

SNMP for Asterisk

_Using

_OpenNMS

669

Monitoring

Asteriskwith

_OpenNMS

₆₇₂

Conclusion

673

25.

Web

Interfaces

675

Flash

_Operator

_Panel

676

Queue

Status and

_Reporting

676

Queue

Status

_Display

677

Queue

_Reporting

₆₇₇

Call Detail

Records

₆₇₇

A2Billing

₆₇₈

Conclusion

678

26. _Security

679 Table of Contents

_|

xv

(15)

Scanning

for Valid Accounts 679 Authentication Weaknesses 681 Fail2ban 681 Installation 682

Configuration

683

Encrypted

Media 687

Dialplan

Vulnerabilities 687

Securing

Asterisk Network APIs 689

IAX2 Denial of Service 689

Other Risk

_Mitigation

691

CLI Permissions 693

Resources 694

Conclusion—A BetterIdiot 694

27. Asterisk: A Future

for

_Telephony

695

TheProblemswith Traditional

_Telephony

695

Closed

_Thinking

696

Limited Standards

_Compliance

697

SlowRelease

_Cycles

697

Refusing

to Let Goof thePastand Embrace theFuture 698

Paradigm

Shift 698

The Promise of

_Open

Source

_Telephony

698

The Itch that Asterisk Scratches 698

Open

Architecture 699

Standards

_Compliance

700

Lightning-Fast

Response

to New

_Technologies

700

Passionate

_Community

700

Some

_Things

that Are Now Possible 701

TheFutureofAsterisk 705

Speech Processing

705

High-Fidelity

Voice 706 Video 707 WebRTC 709 Wireless 709 Unified

_Messaging

₇₁₀

Peering

710

Challenges

712

Opportunities

714 A.

_{Understanding Telephony}

₇₁₇

B.

Protocols for VoIP

₇₃₇

(16)

C. _Preparing

a

System

for Asterisk

761