Asterisk Toolkit

Asterisk (Open Source PBX) Training Material
1
Introduction
The Open Source Resource Center (OSRC) is a project of the Pakistan Software Export Board

(PSEB), Ministry of Information Technology. It aims to promote and support open source initiatives
in the country through awarenessraising seminars, training workshops and network migrations.
As part of its new roster of initiatives, the OSRC has fulfilled the IT industry's growing demand for a
freeofcost Asterisk training program. The OSRC has developed this course as an integral part of this
3day program.
Asterisk is the world's leading open source PBX, telephony engine, and telephony applications
toolkit. Offering flexibility unheard of in the world of proprietary communications, Asterisk
empowers developers and integrators to create advanced communication solutions for free.
The target audience for this training program includes call center industry's IT personnel, network
and system administrators, IT managers, telephone company engineers, VoIP service providers, VoIP
traders, CT developers, IT consultants who want to serve the voice/data convergence market, and
students interested in VoIP projects.
This training program covers key points regarding Asterisk's installation, configuration and
administration. Participants will learn how to create dial plans, implement applications and add
important features to Asterisk's box. They will be able to convert a standard Linux machine into a
working PBX.
My thanks to OSRC's Mr. Shah Mansoor for developing this course.
Mr. Shah Mansoor is OSRC’s Server Technologies expert. He holds a Master’s degree in Computer
Science. Prior to this, he configured the whole local loop setup for Web Concepts Private Limited in
Lahore, Gujranwala and Multan’s telecom regions using the open source PBX, Asterisk. He has also
configured Asterisk PBX for various call centers in Lahore.
This course has been edited by OSRC's Content Writer, Ms. Seema Javed Amin.
The OSRC looks forward to your feedback regarding both the course and the training program, and
looks forward to improving them in the future.
Thank you.
Khurram Islam Khan
Project Manager (Open Source Resource Center)
2
Contents
Sr. No Description Page

1. Asterisk Project 4
Brief History Of Open Source Projects and Licenses 4
Benefits Of Open Source 4
About Digium 5
About Asterisk 6
Digium's Other Projects 6
Asterisk Architecture 6
2. Asterisk's VoIP Signaling Protocols 11
H.323 11
SIP 13
IAX 17
3. Asterisk Installation 18
4. Asterisk Configurations 21
Configuration Files 21
VoIP Connections sip.conf and iax.conf 26
Introduction of Dial plan 36
5. Asterisk Dial Plan An Overview 45
Contexts 45
Variables 46
Includes 48
Macros 50
Special Extensions 51
Asterisk's Dial Command 53
6. Implementing Features 62
Call Forwarding 62
Call Monitoring 65
Call Recording 67
Call Transfer 68
Call Parking 69
Route by caller ID 70
Conferencing with Meetme 71
Enhanced Voicemail 73
7. Introduction to Asterisk ACD 84
8. Asterisk to PSTN 91
Overview 91
Analog Connections 91
Digital Connections 97
9. Asterisk Real time 103
10. Adding H323 Channel 109
3
Asterisk Project
A Brief History of Open Source Projects and Licenses
The open source software movement traces its history to the formation of the Free Software
Foundation (FSF) in 1983. The FSF was formed with the goal of creating a free version of the UNIX
operating system. The FSF released a series of programs in source code form under the name "GNU"
("GNU" is an irreverent acronym which stands for GNU’s Not UNIX). The GNU project did not
actually result in a free version of UNIX, but it did result in the creation of some popular tools for
UNIX programmers, including the GNU C compiler and text editor. It also set the stage for even
more ambitious free software development projects in the1990s.
The license agreement accompanying the GNU software known as the General Public License
(GPL) or "copyleft" license was revolutionary for its time. It is written in a nonlegal style with an
informal preamble and a statement of purpose. The GPL gives licensees broad rights to sell, copy and
modify licensed programs, as long as licensees grant downstream licensees the same rights to sell,
copy and modify the modifications to the original program. Licensees are also required to make their
changes available in source code form.
For many years, the FSF filled a relatively small niche in a large and growing market for proprietary
products from large companies. Many UNIX programmers used and continue to use the GNU C
compiler and debugger from the FSF to create new programs targeting variants of the UNIX
operating system offered by companies such as IBM, HewlettPackard and Sun Microsystems.
With the Internet’s rise during the 1990s, there has been a renewed interest in free software, and a
shift in development resources from esoteric development tools to products and technologies having a
broader commercial appeal. In 1998, a group associated with free software introduced the term "open
source" to emphasize a break with the prohacker, antibusiness past associated with GNU and other
free software projects, and to place a new emphasis within the community regarding the possibilities
of extending the free software model to the commercial world. These new "open source" projects
exist in the mainstream of the commercial software market, and include operating systems such as
Linux, the Apache web server, and the Mozilla browser.
Benefits of Open Source
There are many reasons why the "open source" model has been successful and popular with software
developers:
• Access to Source Code. Documentation for commercial software products is notoriously
lacking in detail and often outdated. This is frustrating for developers who try to write
software programs that are designed to inter operate with, or target, other programs. The best
documentation for a program is the source code itself. Access to the source code enables the
4
developer to understand the program at a deeper level, and to debug and optimize his or her
own program at a level of efficiency and skill that is often not possible with programs
available only in binary form.
• Community. Having a common source code pool and the tools provided by the Internet
creates an opportunity for extensive and speedy collaboration on development projects.
• Cost. Most programs distributed as "open source" are free. If the free program is featurerich
and meets the developer’s required performance parameters, this is obviously a compelling
alternative to programs that cost money.
• Broad Rights. The broad license grant which allows licensees to use, modify and redistribute
open source programs is a major advantage of the typical open source license. Typical
commercial software products are distributed only in binary form and may not be modified.
The majority of documentation associated with commercial programs is not detailed enough
to permit some kinds of "valueadded" programming that is possible for developers who have
direct access to source code.
About Digium
Digium®, Inc. is the original creator and primary developer of Asterisk, the software industry's first
open source telephony platform. Digium provides hardware and software products, including
AsteriskNOW™, the complete open source software appliance; Asterisk Business Edition™, the
professionalgrade version of Asterisk; and the Asterisk Appliance™, hardwarebased telephony
solution, to enterprises and telecommunication providers worldwide. Digium also offers a full range
of professional services, including consulting, technical support, and custom software development.
Used in combination with Digium's telephony interface cards, Asterisk offers a strategic, highly cost
effective approach to voice and data transport over IP, TDM, switched and Ethernet architectures.
Digium's offerings include VoIP, conferencing, voicemail, legacy PBX, IVR, auto attendant, media
servers and gateways, and application servers and gateways.
Company History
The Asterisk community has ambassadors and contributors in every corner of the globe.
While still a Computer Engineering student at Auburn University, Mark Spencer founded Linux
Support Services in 1999. When faced with the high cost of buying a PBX, Mark simply used his
Linux PC and knowledge of C code to write his own open source PBX application. This was the
beginning of the worldwide phenomenon known as Asterisk, and caused Mark to shift his business
focus from Linux support to supporting Asterisk and opening up the telecom market. Linux Support
Services is now known as Digium, and is bringing open source to the telecom market while gaining a
foothold in the telecom industry.
Mark strongly believes that every technology he creates should be given back to the community. This
is why Asterisk is fully open source. Today that model has allowed Asterisk to remain available free
ofcharge, while it has become as robust as other leading and expensive PBXs.
5
Mark Spencer holds a degree in Computer Engineering from Auburn University, and is now CTO and
Chairman of the Board of Digium, Inc. He has also led the development of several Linuxbased open
source applications, such as the Gaim Instant Messenger.
About Asterisk
Asterisk’s code, originally written by Mark Spencer of Digium, Inc., is the combined contribution of
open source software engineers around the world. Currently boasting over two million users, Asterisk
supports a wide range of TDM protocols for the handling and transmission of voice over traditional
telephony interfaces, featuring VoIP packet protocols such as SIP and IAX among others. It supports
U.S. and European standard signaling types used in business phone systems, allowing it to bridge
between nextgeneration voicedata integrated networks and existing infrastructure.
Digium’s Other Projects
Trixbox (formerly asterisk@home)
Trixbox is an easytoinstall VOIP phone system based on the Asterisk PBX. Designed for home or
office use, trixbox includes CentOS Linux, SugarCRM, MySQL, HUDlite, freePBX, and more.
AsteriskNOW™
Asterisk® in minutes. AsteriskNOW is an open source software appliance a customized Linux
distribution that includes Asterisk (the leading open source telephony engine and tool kit), the
AsteriskGUI™, and all other software required for an Asterisk system. AsteriskNOW is easyto
install, and offers flexibility, functionality and features unavailable in advanced, highcost proprietary
business systems.
For more information, please visit http://www.asterisk.org/
Asterisk’s Architecture
Asterisk is middleware that connects Internet and telephony technologies with Internet and
telephony applications. Asterisk applications connect any phone, phone line or packet voice
connection to another interface or service. Asterisk scales easily and reliably from very small to
very large systems. Asterisk supports high density, redundant applications.
Asterisk supports every possible kind of telephone technology. These technologies include VoIP,
SIP, H.323, IAX, and MGCP (for gateways and phone). Asterisk can interoperate with almost all
standardsbased telephony equipment. The hardware required to connect your Asterisk system is
inexpensive. Asterisk supports traditional telephone technologies like ISDN PRI and TCarrier
6
including T1 and E1. Telephony applications include calling, conferencing, call bridging,
voicemail, auto attendant, custom Interactive Voice Response (IVR) scripting, call parking,
intercom, and many others.
An Asterisk server connected to a Local Area Network (LAN) can control phones connected to that
LAN. These phones can call each other through the Asterisk server. The Asterisk server can control
phones connected to other networks or the Internet, even if those phones or the Asterisk server are
behind firewalls.
With Digium FXS interface cards, an Asterisk server can control local analog telephones. FXO and
Tcarrier interface boards from Digium can connect an Asterisk server to the PSTN. This allows
calls to be made to and from the PSTN. PSTN users can call phones controlled by the Asterisk
server; Asterisk phones can call users on the PSTN.
Calls can be switched from one Asterisk server to another. A telephone controlled by an Asterisk
server can call a telephone controlled by a second Asterisk server. A call from a telephone
controlled by one Asterisk server can be switched to a second Asterisk server and then on to the
PSTN.
As shown in Figure 1, Asterisk contains engines that perform critical functions. When Asterisk
starts, the Dynamic Module Loader loads and initializes drivers. The drivers provide channel
drivers, file formats, call detail recording backends, codecs, and applications, among others.
The Asterisk PBX Switching Core accepts telephone calls from the interfaces. It handles calls
according to the instructions found in a dial plan. It uses the Application Launcher to ring phones, to
connect to voicemail, or to dial out on outbound trunks.
The PBX Switching Core includes a Scheduler and I/O Manager that is available to drivers and
applications. The Codec Translator seamlessly connects channels compressed with different codecs.
Most of Asterisk's flexibility comes from the applications, codecs, channel drivers, file formats and
other facilities’ interaction with the various programming interfaces.
7
Figure 1
Interfaces and Channels
In order to be able to install, configure and maintain Asterisk, you must understand which interfaces
are available, and how they work and interact with Asterisk.
Any incoming or outgoing call is made through an interface. All calls arrive at or leave an Asterisk
server through an interface such as SIP, Zaptel or IAX.
Every call is placed or received over an interface on its own distinct channel. A channel can be
connected to a physical channel like a POTS line, or to a logical channel like an IAX or SIP channel.
It is very important to differentiate between the arrival of a call on a channel, and what is done with
that incoming call. When a call arrives at Asterisk over a channel, a dial plan determines what is
done with the call. For example, a call might arrive through a SIP channel. The call could be coming
from a SIP telephone, or from a SIP soft phone running on a computer. The dial plan determines if
the call should be answered, connected to another telephone, forwarded or directed to voice mail.
Asterisk provides various applications, such as voice mail. These applications are available to the
dial plan when processing the incoming call. The dial plan and the applications selected for use
within the dial plan determine what Asterisk does.
Different types of interfaces are associated with different kinds of hardware or protocols. For
example, SIP channels are used to route calls in and out of an Asterisk server over IP with Session
Initiation Protocol. A call can come in to an Asterisk server through a SIP channel or leave the
Asterisk server outbound to the Internet through a SIP channel.
8
All calls arrive on a channel, even internal calls. A legacy analog telephone, for example, can be
directly connected to an Asterisk server with the appropriate Digium interface board. When the user
picks up the handset, a channel is activated. The user's call then flows through the activated channel.
The dial plan determines what should happen to this call, for example, dialing another internal
number over another analog channel, or dialing an outside telephone number, or accessing voice
mail.
Asterisk uses a channel driver (typically named chan_xxx.so) to support each type of channel.
The technology used is one of the installed channel modules, i.e. SIP, IAX, IAX2, MGCP, or
modem. The format of the dial string depends on the type of channel selected.
Hardware Interfaces
Asterisk supports a variety of hardware interfaces to connect telephony channels through a Linux
computer.
Zaptel Pseudo TDM Interfaces
All Digium hardware shares a common driver suite and uses a common interface library. Digium
drivers are based on the Zapata telephony driver suite. This set of drivers is often called "Zaptel."
Zapata is an open source project available at http://packages.qa.debian.org/z/zaptel.html. The Zaptel
telephony infrastructure was jointly developed by Mark Spencer of Linux Support Services, Inc. and
Jim Dixon of Zapata Telephony.
Even if no interface cards are installed, you must install at least one Zaptel driver in order to enable
conferencing. Asterisk does not require a sound board to operate, unless you are using a soft phone
on the computer running Asterisk.
NonZaptel Interfaces
Interfaces for connectivity to traditional legacy telephone services which support PseudoTDM

switching include:
NonZaptel Interfaces
Interface Description
ISDN4Linux Basic Rate ISDN interface for Linux
OSS/Alsa Sound card interfaces
Linux Telephony Interface Quicknet Internet Phonejack/Linejack
(LTI)
Dialogic Fullduplex Intel/Dialogic hardware
Table 1
Linux Telephony Interface
9
The Linux Telephony Interface was developed primarily by Quicknet, Inc. with help from Alan
Cox. This interface is geared towards single analog interfaces, and provides support for low bitrate
codecs.
The following products are known to work with Asterisk, although they may not work as well as
Digium’s devices:
 Quicknet Internet Phonejack (ISA, FXS)
• Quicknet Internet Phonejack PCI (PCI, FXS)
• Quicknet Internet Linejack (ISA, FXO or FXS)
• Quicknet Internet Phonecard (PCMCIA, FXS)
• Creative Labs VoIP Blaster (limited support)
ISDN4Linux
The ISDN4Linux interface is used primarily in Europe to connect lines from BRI interfaces to an
Asterisk machine. Any adapter that is supported by ISDN4Linux should work with Asterisk.
OSS/ALSA Console Drivers
The OSS and ALSA console drivers allow a single sound card to function as a "console phone" to
place and receive test calls. The console can create an intercom using auto answer/auto hangup.
Adtran Voice over Frame Relay
Asterisk supports Adtran's proprietary Voice over Frame Relay protocol. The following products are
known to “talk to” Asterisk using VoFR. You will need a Sangoma Wanpipe or other frame relay
interface to “talk to” them:
• Adtran Atlas 800
• Adtran Atlas 800+
• Adtran Atlas 550
Packet Voice Protocols
These are standard protocols for communication over packet networks such as IP or Frame Relay.
These interfaces do not rely on specialized hardware, and will work without them:
• Session Initiation Protocol (SIP)
• InterAsterisk Exchange (IAX)
• Media Gateway Control Protocol (MGCP ITU H.32 )
• Voice over Frame Relay (VoFR)
10
Asterisk’s Voice over IP (VoIP) Signaling Protocols
A signaling protocol is a common language spoken by telephones and callmanagement servers, the
PSTN, and legacy PBX systems as they communicate to set up, monitor, and tear down calls. The
Voice over IP (VoIP) technology family provides several signaling protocols. Some commercial
softPBX systems support one or two of them. Others, like Asterisk, support just about all of them.
Most signaling protocols have the following common features:
• Their purpose is to signal, record, and facilitate key events in a call: the beginning, the end,
and when the users attempt to use telephony features such as transfers or conference calling.
• Although call signals are usually sent using UDP, they are not viewed as realtime traffic,
such as media channels, which also use UDP.
• The traffic patterns they incur on the network are short and in bursts, as opposed to media
channels, which tend to be consistent and lengthy.
• They do not tend to be supported simultaneously on any single IP phone. There are Session
Initiation Protocol (SIP) phones, and there are H.323 phones. None do both.
• Most are available in free implementations such as Asterisk, GnoPhone (an open source
softphone), OpenH323 (an open source softPBX), VOCAL, and others.
There are two primary contenders in VoIP call signaling: the Session Initiation Protocol (SIP),
developed by an Internet Engineering Task Force working group, and H.323, developed by an
International Telecommunications Union working group. Other signaling standards, such as Cisco's
Skinny Client Control Protocol (SCCP), Nortel's UNISTIM, and Digium's IAX, have been developed
by private companies intent on bringing features to call signaling that do not exist in the published
implementations.
H.323
H.323 is an International Telecommunications Union Telecommunications Standardization Sector
(ITUT) specification for transmitting multimedia traffic, including video and voice, over an IP
network. H.323 works with other existing standards such as Q.931. Compliant vendor products and
applications can communicate with each other via this protocol.
H.323 consists of the following components and protocols:
H.323 Protocols
Feature Protocol
Call Signalling H.225
Media Control H.245
Audio Codecs G.711, G.722, G.723, G.728, G.729
Video Codecs H.261, H.263
Data Sharing T.120
Media Transport RTP/RTCP
Table 1
11
H.323 elements include terminals, gateways, gatekeepers and Multipoint Control Units (MCUs).
Terminals, often called endpoints, provide pointtopoint and multipoint conferencing for audio,
video and data. Gateways can interconnect to the PSTN or ISDN networks.
Gateways are used to connect between a Switched Circuit Network (SCN) endpoints and H.323
endpoints. Gateways are only needed when an H.323 endpoint needs to interconnect to a different
network.
Gateways provide address translation services and admission control. They translate between audio,
video and data transmission formats. They also interconnect communication systems and protocols.
A gatekeeper provides precall and calllevel control services to H.323 endpoints. H.323
gatekeepers are separated logically from the other network elements. Intergateway communication
is currently not specified by H.323. A gatekeeper can provide call control signalling, call
authorization, bandwidth management and call management functions.
A Multipoint Controller (MC) supports conferencing between three or more endpoints. A

Multipoint Processor (MP) receives audio, video and data streams, and then redistributes those
streams to the endpoints in a multipoint conference.
An MCU is an endpoint that supports multipoint conferences. An MCU must include at least an MC
and one or more MPs. A typical MCU for centralized multipoint conferences includes an MC, an
audio MP, a video MP and a data MP.
An H.323 proxy server operates at the application layer. It examines packets sent between two
communicating applications. The proxy supports reservations, H.323 traffic routing and Network
Address Translation (NAT).
The H.323 CallSignaling Process
There are five general steps for each leg of a call path in the H.323 signaling process: setup/teardown,
capabilities negotiation, open media channel, perform call, and release.
Setup/Teardown
To initiate an H.323 call, H.225 is required for the setup process. Each endpoint involved in the call is
kept apprised regarding the status of the call setup, expressed in one of H.225's named states, the last
of which does not happen until the call ends:
• Proceeding: The calling endpoint is trying to establish a network connection with the called
endpoint.
• Alerting: The called endpoint is being notified that somebody is trying to reach it. In other
12
words, the called endpoint is ringing, and the calling endpoint is receiving a ring back, an
indication of ringing on the remote end.
• Connect: The called endpoint has accepted and a media channel can be established.
• Release: One of the endpoints has signaled an end to the call. When release is indicated, the
call is actually being torn down, not set up.
Capabilities Negotiation
After setup, H.245 is enlisted to negotiate the call’s application requirements, and select appropriate
codecs. H.245 determines:
• What kinds of application media each terminal can support: audio, video, white board, and so
on
• Which codecs each terminal is capable of and which it may prefer
• How the media channel will be structured, and which packet interval will be used
• Which terminal will be the master and which will be the slave for the duration of the call.
Master and slave roles distinguish the client/server role assumptions for future signals during
the call and are a protocol formality
• How best to notify the caller if negotiation fails. The endpoint will usually display an error
code while playing a busy signal. The busy signal is a standard when a call cannot be
connected on a VoIP network
Open Media Channel
Once capabilities negotiation has succeeded, RTP Control Protocol (RTCP) establishes a UDP socket
for the media channel. The RTP media channel opens, and a stream of encoded UDP packets with
RTP payload flows across the network using the negotiated codec and packet interval.
Perform Call
As the call progresses, RTCP, which runs alongside RTP (usually on separate, consecutive UDP ports
that are selected during call setup), can keep tabs on the media channel, which remains intact via
connectionless UDP for the duration. This continues until the call is finished.
Release
When the call concludes, H.225 enters its release state, signaling an end to the media channel, an end
to the H.245 application capabilities session, and an end to the callaccounting transaction on the
gatekeeper. Depending on the endpoint, both the caller and called will hear a dialtone or a busy
signal.
Session Initiation Protocol (SIP)
Session Initiation Protocol (SIP) is described in RFC.2543. SIP is an applicationlayer control
protocol used to create, modify and terminate a communication session. A SIP invitation can
establish and describe sessions. SIP’s features of user location, user capability, user availability, call
13
setup and call handling can initiate or end communication sessions.
Henning Schulzrinne, one of SIP’s original architects, said that SIP’s objective is the "re
engineering of the telephone system from the ground up" He said that this is an "opportunity that
appears only once after 100 years".
A SIP session can have one or more participants. Sessions can include audio, video and data
streams. SIP is flexible enough to support adhoc conferencing. Multimedia SIP sessions can be
multicast, unicast, pointtopoint, or can combine broadcast methods.
SIP is not as widespread as H.323, yet it is catching up quickly. Most modern application
implementations are relying on SIP rather than H.323. SIP is extensible and will easily support
additional functionality as and when required.
A SIP user agent is a clientend application continuing a UserAgent Client (UAC) and a User
Agent Server (UAS.) These are known as a SIP client and a SIP server. The client initiates SIP
requests as a user's agent. A server gets requests. A SIP server acts as a user's agent.
There are two types of SIP network servers: proxy servers and redirect servers. Proxy servers
contain client and server functions. A proxy server acts on behalf of other clients. It can rewrite
headers to identify the proxy as the request initiator. The proxy server ensures that traffic is sent
back to the correct client.
A redirect server accepts SIP requests and responds to the client with the next server’s address. It
does not manage calls, process or forward SIP requests.
A SIP client must be able to locate a SIP server, and determine a target server’s IP address and port
number. The default SIP port is 5060. The SIP client can query a Domain Name Server (DNS) for a
server’s IP address.
After SIP address resolution, the SIP client sends one or more SIP requests and gets back one or
more SIP responses. All requests and responses are a part of a SIP transaction.
SIP Addressing
SIP Uniform Resource Locators (URLs) provide addressing similar to email addressing. A SIP

URL can have various forms and can include a telephone number, for example:

sip:someone@somewhere.com
sip:14155551212@somewhere.com; user=phone
sip:14155551212@somewhere.com; user=phone; phonecontext=VNET
SIP Methods and Responses
SIP signals fall into ten categories called methods. Each method accomplishes a different function for
SIP:
INVITE: Start sessions and advertise endpoint capabilities.
ACK: Acknowledge to the called SIP peer that an INVITE has succeeded.
BYE: This method occurs when the call is completed, that is, one user at a minimum wishes to end
the call.
14
CANCEL: This method is used during attempts to override a prior request that has not yet been
completed.
OPTIONS: Query a SIP peer for its capabilities information, without actually establishing a media
channel.
REGISTER: This method notifies the SIP server at which endpoints a particular user can be reached.
INFO: Transmit telephony application signals through the SIP signaling path; these signals can
include dialed digits.
PRACK: This method (Provisional ACK) is used to notify an endpoint of an intention to set up a
complex call without actually providing an ACK. PRACK is the SIP equivalent of "All is well".
SUBSCRIBE: This method provides a way of establishing event handlers within SIP telephony
applications, for example, "Tell me when Bob misses a call" or "Tell Bob when I am registered with
the server".
NOTIFY: This method delivers messages between endpoints as events occur, for example, "Bob
missed a call".
SIP Responses: A complete list of SIP responses is described in the following table:
100 Trying
180 Ringing
181 Call Is Being Forwarded
182 Queued
183 Session Progress
200 OK
202 Accepted
300 Multiple Choices
301 Moved Permanently
302 Moved Temporarily
305 Use Proxy
380 Alternative Service
400 Bad Request
401 Unauthorized to Use This Registrar
402 Payment Required
403 Forbidden
404 User Not Found
405 Method Not Allowed
15
406 Not Acceptable
407 Proxy Authentication Required
408 Request Timeout
410 This User Is Gone From Here
413 Request Entity Too Large
414 Request URI Too Long
415 Unsupported Media Type
416 Unsupported URI Scheme
420 Bad Protocol Extension
421 Extension Required
423 Interval Too Brief
480 Temporarily Unavailable
481 Call/Transaction Does Not Exist
482 Loop Detected
483 Too Many Hops
484 Address Incomplete
485 Ambiguous
486 Busy Here
487 Request Terminated
488 Not Acceptable Here
491 Request Pending
493 Undecipherable s/MIME Part
500 Server Internal Error
501 Method Not Implemented On This Server
502 Bad Gateway
503 Service Unavailable
504 Server Timeout
505 Version Not Supported
513 Message Too Large
600 Busy Everywhere
16
603 Decline
604 Does Not Exist Anywhere
606 Not Acceptable
InterAsterisk Exchange (IAX) Protocol
The InterAsterisk Exchange (IAX) Protocol is a signaling protocol for VoIP networks, just like SIP
and H.323. It also provides endpoint and trunk signaling. The primary difference between IAX and
other signaling families is that IAX does not implement RTP as the packaging mechanism. Instead,
IAX has its own way of packaging encoded voice.
IAX is also NATproof, so dozens or hundreds of simultaneous calls from behind a masquerading
firewall will function correctly, just like HTTP.
IAX is implemented in a farsimpler and less applicationexhaustive manner than SIP and H.323. It is
really intended just for telephony applications, while H.323 and especially SIP include far more
extensibility. IAX is therefore much more compact; complete implementations are possible with as
little as 64 kb of object code.
While a complete cycle of registration, call signaling, voice transmission, and teardown can use
several TCP and UDP ports and connections with SIP or H.323, IAX handles all of these functions
using a single UDP port. When the IAX client (endpoint) registers with the IAX server or proxy, this
UDP port is utilized. When a call is placed, this same port is utilized. When voice transmission
occurs, this port is utilized once again. The way IAX distinguishes between registration, signaling,
and voice packets is by including headers and meta data in each packet that defines what the packet's
purpose is and whether it has a payload attached.
The IAX protocol’s documentation describes the order of these header and meta data elements as
control frames, meta frames, and information elements, each with an IAXspecific syntax. IAX is not
encoded using ASCII or ASN.1; it uses a purely proprietary performanceoriented binaryencoding
scheme instead.
Unlike SIP and H.323, IAX is not a standard recommendation, but an independent protocol created
by Mark Spencer, founder of Digium. Although proprietary, the specification for IAX is open and has
been embraced by the VoIP community. As such, it is quite wellimplemented in Digium's products.
Asterisk, the open source softPBX, implements it fully, and Digium manufactures an IAXbased
ATA.
17
Asterisk’s Installation
Asterisk uses three main packages: its main program, the Zapata telephony drivers (zaptel), and the
PRI libraries (libpri). If you are planning a pure VoIP network, the only real requirement is the
Asterisk package. The zaptel drivers are required if you are using analog or digital hardware, or if
you are using the ztdummy driver (discussed later in this chapter) as a timing interface. The libpri
library is technically optional unless you are using ISDN PRI interfaces, and you may save a small
amount of RAM if you do not load it, but its installation is recommended in conjunction with the
zaptel package for completeness.
One other package you may want to install is Asterisksounds. While Asterisk comes with many
sound prompts in the main source distribution, the Asterisksounds package contains many more.
Install Fedora with its development libraries before installing Asterisk. Download the required
sources:
cd /usr/src
wget http://downloads.digium.com/pub/asterisk/oldreleases/asterisk1.4.14.tar.gz
wget http://downloads.digium.com/pub/asterisk/oldreleases/zaptel1.4.8.tar.gz
wget http://downloads.digium.com/pub/asterisk/oldreleases/libpri1.4.3.tar.gz
Check if the kernel sources (for the kernel’s current version) on the machine are installed or not.
Verify by using the command given below:
rpm –qa | grep kerneldevel
If it is not installed, install it by using the following command:
yum install kerneldevel
Ensure that the other required packages have been installed:
rpm q bison
rpm q bisondevel
rpm q ncurses
rpm q ncursesdevel
rpm q zlib
rpm q zlibdevel
rpm q openssl
18
rpm q openssldevel
rpm q gnutlsdevel
rpm q gcc
rpm q gccc++
If not, install them by using yum:
yum install bison
yum install bisondevel
yum install ncurses
yum install ncursesdevel
yum install zlib
yum install zlibdevel
yum install openssl
yum install openssldevel
yum install gnutlsdevel
yum install gcc
yum install gccc++
If yum is unable to locate one or more of these packages, either download, or check the packages in
the installation CDs, and install them from there instead:
rpm i PACKAGE.rpm
rpm uvh PACKAGE.rpm
Install libpri:
cd /usr/src
tar zxvf libpri1.4.3.tar.gz
cd libpri1.4.3
make
make install
Install zaptel:
cd /usr/src/
tar zxvf zaptel1.4.8.tar.gz
cd zaptel1.4.8
./install_prereq test ;Check for dependencies
./install_prereq install ;Install dependencies if not installed
./configure
make
19
make install
make config
In order to be able to play mp3 files for musiconhold, install mpg123 before installing Asterisk:
cd /usr/src/
wget http://mpg123.orgis.org/download/mpg1231.2.0.tar.gz
tar zxvf mpg1231.2.0.tar.gz
cd mpg1231.2.0
./configure
make
make install
ln s /usr/local/bin/mpg123 /usr/bin/mpg123
Install Asterisk:
tar zxvf asterisk1.4.14.tar.gz
cd asterisk1.4.14
make clean
./configure
make
make install
make samples
make config
In order to verify Asterisk’s installation, start the Asterisk daemon by typing ‘safe_asterisk’ and
connect to its console by typing ‘asterisk –vvvvvr’. Reload the entire configuration by typing
‘reload’.
20
Asterisk Configurations
Configuration Files:
asterisk.conf
The asterisk.conf file defines the locations for the configuration files, the spool directory, and the
modules, as well as a location to write log files to. The asterisk.conf file is generated automatically
when you run the make samples command, based on the information it collects about your system.
It will contain a [directories] section similar to the following example:

[directories]
astetcdir => /etc/asterisk ; location where Asterisk configuration files are stored
astmoddir => /usr/lib/asterisk/modules ; location where Asterisk modules are stored
astvarlibdir => /var/lib/asterisk ; location where Asterisk libraries are stored
astagidir => /var/lib/asterisk/agibin ;location where agi scripts are stored
astspooldir => /var/spool/asterisk ; location where all records are stored
astrundir => /var/run ; location where Asterisk will store its PID file
astlogdir => /var/log/asterisk ; location where Asterisk logs are stored
Additionally, you can specify an [options] section, which will allow you to define startup options
(commandline switches) in the configuration file. The following example shows the available
options and the commandline switches that they effectively enforce:
[options]
verbose=<value> ; starting verbosity level (v)
debug=yes|no|<val> ; turn debugging on or off (or value in 1.2) (d)
nofork=yes|no ; don't fork a background process (f)
console=yes|no ; load the Asterisk console (c)
highpriority=yes|no ; run with high priority (p)
initcrypto=yes|no ; initialize crypto at start (i)
nocolor=yes|no ; disable ANSI colors on the console (n)
dumpcore=yes|no ; dump a core file on failure (g)
quiet=yes|no ; run quietly (q)
cache_record_files=yes|no ; cache files recorded with Record( ) in an alternative
; directory in conjunction with record_cache_dir
record_cache_dir=<dir> ; directory in which to cache files recorded with
; Record ( ) until completion
execincludes=yes|no ; enable support of #exec includes in configuration
; files (off by default)
21
Manager.conf
The Asterisk Manager interface is an API that external programs can use to communicate with and
control Asterisk.
The Manager gives programs the ability to run commands and request information from the Asterisk
server. However, it is not very secure; the authentication mechanism uses plaintext passwords, and
all connected terminals receive all events. The Asterisk Manager should only be used on a trusted
Local Area Network (LAN), or locally on the box. The permit and deny constructs allow you to
restrict access to certain extensions or subnets.
The following is a sample of a manager.conf file:
[general]
enabled = no
port = 5038
bindaddr = 0.0.0.0
[magma]
secret = welcome
deny=0.0.0.0/0.0.0.0
permit= 192.168.1.0/255.255.255.0
read = system,call,log,verbose,command,agent,user
write = system,call,log,verbose,command,agent,user
cdr_custom.conf
By default, Asterisk will generate a CDR for every finished call; this file defines exactly what gets
logged in this CDR line.
The CDRs are stored in a CSV file in /var/log/asterisk/cdrcsv by default. This is available in Asterisk
head or Version 1.2 only.
; Mappings for custom config file
;
[mappings]
Master.csv =>
"${CDR(clid)}","${CDR(src)}","${CDR(dst)}","${CDR(dcontext)}","${CDR(channel)}","${CDR(d
stchannel)}","${CDR(lastapp)}","${CDR(lastdata)}","${CDR(start)}","${CDR(answer)}","${CDR(e
nd)}","${CDR(duration)}","${CDR(billsec)}","${CDR(disposition)}","${CDR(amaflags)}","${CDR
(accountcode)}","${CDR(uniqueid)}","${CDR(userfield)}”
Let's have a closer look at the variables we can define here:
22
${CDR(clid)} = callerid for the call (with the name)
${CDR(src)} = callerid number for the call
${CDR(dst)} = destination extension
${CDR(dcontext)} = Destination context
${CDR(channel)} = Src channel
${CDR(dstchannel)} = Destination channel if appropriate
${CDR(lastapp)} = this is the last application in the dialplan used, on an outgoing call this will be
DIAL
${CDR(lastdata)} = these are the parameters given to the last application used in the dialplan
${CDR(start)} = time of the start of the call
${CDR(answer)} = time when the call was answered
${CDR(end)} = time when the call got hung up
${CDR(duration)} = duration of the call
${CDR(billsec)} = duration of the actual call (without the ringing)
${CDR(disposition)} = status of the call (ANSWERED, BUSY, NO ANSWER)
${CDR(amaflags)} = flag for the type of CDR (can be set in a.o. sip.conf)
default: Sets the system default.
omit: Do not record calls
billing: Mark the entry for billing
documentation: Mark the entry for documentation
${CDR(accountcode)} = the accountcode as set for this channel with for example SetAccountcode in
the dialplan (Extensions.conf) or in the channel configuration file (e.g. per user in sip.conf, iax.conf
and per channel in zaptel.conf)
${CDR(uniqueid)} = a unique ID for this call
${CDR(userfield)} = a userfield set by the dialplan command SetCDRUserfield
It is possible to define different "layouts" for different files.
The default file is Master.csv, but if you specify a different accountcode (with SetAccount or in
sip.conf or iax.conf or zaptel.conf) the filename will change.
Musiconhold.conf
The musiconhold.conf file is used to configure different classes of music and their locations for use in
Music on Hold applications. Asterisk makes use of the mpg123 application to play music to channels.
The format up to Asterisk 1.0 was with one line per class under the [classes] section.
[classes]
classname => mode:directory,application
The new format in Asterisk 1.2 and above is with each class in its own section.
23
[classname]
mode => mode
directory => directory
application => application
For using a streaming source, use the "streamplayer" tool that comes with Asterisk (see
musiconhold.conf.sample for more information).
[default]
mode=custom
application=/usr/sbin/streamplayer 192.168.100.52 888
format=ulaw
rtp.conf
The rtp.conf file controls the Realtime Transport Protocol (RTP) ports that Asterisk uses to generate
and receive RTP traffic. The RTP protocol is used by SIP, H.323, MGCP, and possibly other
protocols to carry media between endpoints.
The default rtp.conf file uses the RTP port range of 10,000 through 20,000.
You can change the range that Asterisk will use by modifying /etc/asterisk/rtp.conf – You should
change this to a much more sensible range otherwise you have to open a large range in the firewall.
The range used will depend on how many concurrent calls you are expecting to receive, but you
should be able to cut it down drastically.
Five ports are generally used for every bidirectional SIP call between two endpoints: port 5060 for
SIP signaling, one port for the data stream and one port for the RealTime Control Protocol (RTCP)
in one direction, and an additional two ports for the data stream and RTCP in the opposite direction.
UDP datagrams contain a 16bit field for a Cyclic Redundancy Check (CRC), which is used to verify
the integrity of the datagram header and its data. It uses polynomial division to create the 16bit
checksum from the 64bit header. This value is then placed into the 16bit CRC field of the datagram,
which the remote end can then use to verify the integrity of the received datagram. Setting
rtpchecksums=no requests that the OS not do UDP checksum creating/checking for the sockets used
by RTP. Add this option to the sample rtp.conf file, and it will look like this:
[general]
rtpstart=10000
rtpend=20000
rtpchecksums=no
logger.conf
The logger.conf file specifies the type and verbosity of messages logged to the various log files in the
/var/log/asterisk/ directory. It has two sections, [general] and [logfile].
24
[general]
Settings under the [general] section are used to customize the output of the logs (and can safely be left
blank, as the defaults serve most people very well). Define exactly how you want your timestamps to
look through the use of the dateformat parameter:
dateformat=%F %T
The Linux man page for strftime(3) lists all of the ways in which you can do this. If you want to
append your system's hostname to the names of the log files, set appendhostname=yes. This can be
useful if you have a lot of systems delivering log files to you. If, for some reason, you do not want to
log events from your queues, you can set queue_log=no. If generic events do not interest you, instruct
Asterisk to omit them from the by setting event_log=no.
[logfiles]
The [logfiles] section defines the types of information you wish to log. There are multiple ranks for
the various bits of information that will be logged, and it is preferable to separate log entries into
different files. The general format for lines in the [logfiles] section is filename => levels, where
filename is the name of the file to save the logged information to and levels are the types of
information you wish to save.
A sample [logfiles] section might look like this:
[logfiles]
console => notice,warning,error
messages => notice,warning,error
Using console for the filename is a special exception that allows you to control the type of
information sent to the Asterisk console.
You can specify the logging of the following types of information:
debug
Enabling debugging gives a far more detailed output about what is happening in the system. With
debugging enabled, for example, you can see which MF tones the users entered while accessing their
voicemail boxes. Debugging information should be logged only when you are actually debugging
something, as it will create massive log files very rapidly.
Verbose
When you connect to the Asterisk console and set a verbosity of 3 or higher, you'll see output on the
console showing what Asterisk is doing. You can save this output to a log file by adding a line such
as verbose_log => verbose to your logger.conf file. Note that a high amount of verbosity can quickly
eat up hard drive space.
25
Notice
A notice is used to inform you of minor changes to the system, such as when a peer changes state. It
is normal to see these types of messages, and the events they indicate generally have no adverse
effects on the server.
Warning
A warning occurs when Asterisk attempts to do something and is unsuccessful. These types of errors
are usually not fatal, but they should be investigated, especially if a lot of them are seen.
Error
Errors are often related to Out of Memory errors. They generally indicate serious problems which
may cause Asterisk to crash or freeze.
codecs.conf
Most codecs do not have any configurable parameters. Some codecs, however, are capable of
behaving in different ways. This primarily means that they can be optimized for a particular goal,
such as cutting down on latency, making the best use of a network, or perhaps delivering high quality.
So far, the codecs.conf allows configuration of Speex parameters only.
VOIP Connections Sip.conf and IAX.conf
Sip.conf
Synopsis
The sip.conf file contains parameters relating to the configuration of sip client access to the Asterisk
server. Clients must be configured in this file before they can place or receive calls using the Asterisk
server.
Arrangement
The sip.conf file is read from the top down. The first section is for general server options, such as the
IP address and the port number to bind to. The following sections define client parameters such as the
username, password, and default IP address for unregistered clients. Sections are delineated by a
name in brackets. The first section is called general (which cannot be used as a client name.) The
following sections begin with the client name in brackets, followed by the client options.
Keywords
26
The following keywords are defined in /etc/asterisk/sip.conf.
In the general section:
port:
The port Asterisk should listen for incoming SIP connections. The default is 5060, in keeping with
standards. It takes a port number as an argument (which must not be in use by any other service.)
bindaddr:
The IP address Asterisk should listen on for incoming SIP connections. If the machine has multiple
real or aliased IP addresses, this option can be used to select which IP addresses Asterisk listens on.
The default behavior is to listen on all available interfaces and aliases. It takes an IP address as its
argument (which must be an interface available on the system.)
context:
Sets a default context in which all further clients are placed, unless overridden within their client
definition.
Tos:
Asterisk can set the Type of Service (TOS) bits in the IP header to help improve performance on
routers that respect TOS bits in their routing calculations. The following values are valid:
lowdelay
Minimize delay.
Throughput
Maximize throughput.
Reliability
Maximize reliability.
Mincost
Minimize cost.
None
No bits set.
tos=lowdelay|throughput|reliability|mincost|none
allow and disallow:
Specific codecs can be allowed or disallowed, limiting codec use to those preferred by the system
designer. allow and disallow can also be defined on a perchannel basis. Keep in mind that allow
statements in the [general] section will carry over to each channel, unless you reset them with a
disallow=all. Codec negotiation is attempted in the order in which the codecs are defined. Best
practice suggests that you define disallow=all, followed by explicit allow statements for each codec
you wish to use. If nothing is defined, allow=all is assumed.
27
disallow=all
allow=ulaw
allow=gsm
allow=ilbc
maxexpirey:
This sets the maximum amount of time, in seconds, until a peer's registration expires.
maxexpirey=3600
defaultexpirey:
This sets the default SIP registration expiration time, in seconds, for incoming and outgoing
registrations. A client will normally define this value when it initially registers, so the default value
you set here will be used only if the client does not specify a timeout when it registers. If you are
registering to another User Agent Server (UAS), this is the registration timeout that it will send to the
far end.
defaultexpirey=300
register:
Registers this Asterisk instance with another host. Takes a SIP address (without the sip:) optionally
followed by a forward slash ('/') and an extension to use for contact.
[general]
port = 5060
bindaddr = 192.168.0.1
context = default
disallow = g729
allow = ulaw
allow = gsm
maxexpirey = 180
defaultexpirey = 160
register => 1234@mysipprovider.com/1234
register => 2345@myothersipprovider.com
Client Options
type:
The type option sets the connection class for the client. The options are:
peer: A device which receives calls from the Asterisk server.
28
user: A device that makes calls through the Asterisk server.
friend: A device that can both receive and send calls through the Asterisk server. This makes
sense for most desk handsets and other devices. If unsure, you should probably set type to this value.
Secret:
Sets the password for the client. Takes an alphanumeric string.
Host:
Sets the device’s IP address or resolvable host name. This can also be set to 'dynamic' in which case
the host is expected to come from any IP address. This is the most common option, and normally
necessary within a DHCP network.
Defualtip:
This option can be used when the host keyword is set to dynamic. When set, the Asterisk server will
attempt to send calls to this IP address when a call is received for a SIP client that has not yet
registered with the server.
Username:
This option sets the username the Asterisk server attempts to connect when a call is received. This is
used when, for some reason, the value is not the same as the username the client registered.
Canreinvite:
The SIP protocol tries to connect endpoints directly. Asterisk must, however, remain in the
transmission path between the endpoints if it is required to detect DTMF.
context:
When defined within a client definition, this keyword sets the default context for this client only.
nat:
nat can be set to yes, no, or never. If set to yes, Asterisk ignores the IP address in the SIP and SDP
headers and responds to the address and port in the IP header. The never option is for devices that
cannot handle rport in the SIP header, such as the Uniden UIP200.
qualify:
You can set qualify to yes, no, or a time in milliseconds. If you set qualify=yes, NOTIFY messages
will be sent periodically to the remote peers to determine whether they are available and what the
latency between replies is. A peer is determined unreachable if no reply is received within 2,000 ms
(to change this default, set qualify to the number of milliseconds to wait for the reply). Use this option
in conjunction with nat=yes to keep the path through the NAT device alive.
Complete File Example
29
The following is a complete example of a workable /etc/asterisk/sip.conf file.
[general]
port=5060
bindaddr=192.168.0.10
context=default
[snom]
type=friend
secret=snom100
host=dynamic
defaultip=192.168.0.15
[cisco]
type=friend
secret=mysecret
host=192.168.0.20
canreinvite=no
context=trusted
iax.conf
Synopsis
This file is used to configure clients connecting via the InterAsterisk exchange protocol. IAX is
primarily used for passing calls between Asterisk servers. Frequent multiple Asterisk servers are
configured to intercommunicate with each other using this file. The iax.conf file is shared by both
IAX Version 1 and Version 2 implementations.
Arrangement
The iax.conf file begins with a general section, which sets global server options. Within the general
section, you can also configure the Asterisk server to register as a client with a remote server for
access to the dial plan of another Asterisk system.
Following the general section, clients are defined, one per section. Sections are delineated by their
name in brackets.

Keywords
The following keywords are used in iax.conf.
In the general section:
port:
The port to listen on for incoming connections. The default is port 5036. It takes a port number as its
argument (which must not be in use by another service).
30
bindaddr:
If multiple IP addresses are available in the same system, this option may be set to bind Asterisk to a
single interface.
port = 5036
bindaddr = 0.0.0.0
amaflags:
Sets the AMA flags, affecting the categorization of entries in the call detail records. This keyword
may also be set on a perclient basis within their client definition. Accepts the following values:
billing: Mark the entry for billing
documentation: Mark the entry for documentation
omit: Do not record calls
default: Use the system default
accountcode:
Sets the default account code to log IAX calls to. This keyword can also be used within a client
definition to set the account code for that client.
accountcode = wmeadows
amaflags = documentation
bandwidth:
This option is used to control which codecs are used generally. Rather than allowing or disallowing
specific codecs, this option may be set to 'low' to automatically avoid some codecs which don't work
well in low bandwidth sitiuations. Takes an option of low or high.
allow and disallow:
Specific codecs can be allowed or disallowed, limiting codec use to those preferred by the system
designer. allow and disallow can also be defined on a perchannel basis. Keep in mind that allow
statements in the [general] section will carry over to each channel, unless you reset them with a
disallow=all. Codec negotiation is attempted in the order in which the codecs are defined. Best
practice suggests that you define disallow=all, followed by explicit allow statements for each codec
you wish to use. If nothing is defined, allow=all is assumed.
disallow=all
allow=ulaw
allow=gsm
allow=ilbc
31
jitterbuffer:
Turn the jitterbuffer on or off. The jitterbuffer is used to maximize audio quality by balancing latency
against the number of dropped packets. A number of keywords exist to finetune the jitterbuffer.
Dropcount:
Sets the maximum number of packets per memory size to be dropped in order to reduce latency.
Maxjitterbuffer:
Sets the maximum size of the jitterbuffer.
Maxexcessjitterbuffer:
Sets the maximum excess jitterbuffer, which if exceeded, causes the jitterbuffer to slowly shrink in
order to improve latency.
Register:
Register is used to tell the Asterisk server to register with another Asterisk server. This is normally
only needed if the local server has a dynamic IP address and needs to tell the other server where to
find it. The following is the format of a register statement:
register => username:secret@server
The ‘secret’ field is optional, if no secret has been specified on the server being connected to. If RSA
encryption is in use, specify the key to send to the server with this format:
register => username:[key]@server
Tos:
Asterisk can set the Type of Service (TOS) bits in the IP header to help improve performance on
routers that respect TOS bits in their routing calculations. The following values are valid:
lowdelay
Minimize delay.
Throughput
Maximize throughput.
Reliability
Maximize reliability.
Mincost
Minimize cost.
None
No bits set.
32
tos=lowdelay|throughput|reliability|mincost|none
Client Options
type:
This sets the type of entity for the client. Valid types are:

peer: A device which receives calls from the asterisk server.
user: A device that makes calls through the asterisk server.
friend: a device that can both receive and send calls through the asterisk server. This makes
sense for most desk handsets and other devices. If unsure, you should probably set type to this value.
Context:
When used within a client definition, this keyword overrides the default incoming context set in the
general section for the user only.
Callerid:
Sets the Caller ID string to be used for this entity. This caller ID string will be used internally, and
sent to the PSTN if a PRI line is used to route the call to the outside world. If left blank, the Caller ID
sent by the entity will be used instead:
callerid => “ALI” <51 9205678>
auth:
Sets the authentication type. IAX supports three methods of authentication. The first (and least
secure) is plaintext. The passwords (or secrets) are sent in cleartext over the network. The second is
md5, which uses an md5 challenge response algorithm. Both machines will have cleartext access to
the passwords, but they will be confirmed using an md5 hash while passing over the network. The
most secure option is to use RSA public/private key encryption to store and transmit the secret.
Public/private key pairs can be generated using the included program astgenkey. The public key will
need to be manually transferred to the server and stored in /var/lib/asterisk/keys/name.pub. Server
private keys are stored in the same location as name.key
Important Note: In order to use RSA keys with Asterisk, you will have to ‘init keys’ at the console
during startup. Asterisk will prompt you to do so every time it is launched.
Inkeys:
The public keys used to decrypt authentication for an incoming client request or registration.
Outkey:
The private key to encrypt outgoing authentication communication for this client.
33
auth=md5
secret=password
auth=rsa
inkeys=theirkey
outkey=mykey
permit:
Hosts to permit to connect as this user. This can be a single host or a host/netmask pair.
Deny:
Hosts to deny for any incoming connection attempt as this user. deny takes the same argument format
as permit.
deny = 0.0.0.0/0.0.0.0
permit=192.168.0.1/255.255.255.0
permit=216.207.245.45
host:
Sets the expected outgoing host for this client. Can be set to an IP address or dynamic, which will
allow incoming connections from any host (that is not explicitly denied.)

defaultip:
The default IP address for an IAX client. This field is consulted if Asterisk receives a call for an IAX
client that is dynamic and has not registered to let Asterisk know the current IP address. It takes an IP
address as its argument.
host=dynamic
defaultip=192.168.0.1
accountcode:
When used within a client definition, it sets the account code for that client only. This is used by the
call logging service.
Qualify:
Tells Asterisk to test whether the peer is alive before attempting to connect the call. If set to yes,
Asterisk will periodically contact the peer before forwarding any call information. The argument
specified is the maximum number of milliseconds that a peer can take to respond before it is
considered “unavailable.”
qualify=1000
34
mailbox:
Provides a mailbox to associate with a given peer, so that when it registers it can be notified of any
waiting or pending messages.
mailbox=1234
mailbox=1002,1003
trunk:
Enables or disables trunking for a given user or peer. Trunk mode is a more efficient method of
operating IAX if there are typically many calls running on the link. Trunk mode requires having a
Zaptel interface in the Asterisk server.
trunk=yes
Complete File Example
[general]
port=5036
accountcode=iaxcalls
amaflags=default
bandwidth=low
allow=gsm
disallow=lpc10
jitterbuffer=yes
dropcount=3
maxjitterbuffer=500
maxexcessjitterbuffer=100
register => asterisk1:opensecret@telco.digium.com
context=iax
;from here on it’s client definitions
[trustedhost]
host=192.168.0.50
trunk=yes
context=trusted
[authhost]
secret=foobar
host=dynamic
defaultip=68.62.178.239
[rsahost]
auth=rsa
inkeys=rsapublickey
35
host=dynamic
defaultip=216.207.245.55
accountcode=log1234
callerid=”Mark Spencer” <256 428 6000>
Introduction to Dial Plan
A dial plan determines call routing and processing; it controls all Asterisk call switching. For
example, if a call comes in on any channel, where should that call be directed? If someone doesn't
answer their phone, what should be done with the call?
Two important files in /etc/asterisk make up the dial plan. The first is extensions.conf, which uses the
original and still recommended priority model; the second is extensions.ael, which uses the newer
Asterisk Extensions Language. The traditional priority model is used here.
The dial plan consists of four main parts: contexts, extensions, priorities, and applications.
The Asterisk dial plan is divided into sections, and each section is called a context. Any dialplan must
begin with a [general] context where global configuration entries reside, but the subsequent contexts
can have any name. The configuration for every device, be it a softphone, hardphone or outgoing
trunk, must specify the default context for that device. The following is an example from a sip.conf
file:
[2000]
type=friend
context=internalphones
secret=1234
host=dynamic
This SIP device called 2000 always initiates calls in the internalphones context. This means that if a
caller uses this phone to dial a number, Asterisk will look in the internalphones context for an
extension matching that number. If no matching extension is present, nothing happens.
Individual entries in extensions.conf are called extensions. Extensions are interpreted by Asterisk
every time a call is initiated, but extensions.conf is only read into Asterisk at its starting time. You
can also refresh the dialplan during its operation from the Command Line Interface (CLI) by entering
the command reload now (which reloads all the configurations) or extensions reload (which reloads
only the dialplan).
Syntax
An extension consists of the following parts:
• Extension (Name or number)
• Priority (a kind of program line number)
• Application an instruction which tells Asterisk what it should do with the call.
exten => Extension,Priority,Application
36
Extension Patterns
If we use a pattern, the dial plan becomes instantly more compact and elegant, for example:
The '_10X' extension describes the number range from 100 to 109.
An Asterisk dialplan pattern can have the following elements:
[abc]
The digits a, b and c. For example, to match 34, 37, and 38:
exten => _3[478],1,NoOp(Test)
[ab]
Any digit in the range a to b. For example, to match any number between 31 and 35:
exten => _3[15],1,NoOp(Test)
(e.g. [258] is also acceptable for the digits 2,5,6,7,8)
X
Any digit from 0 to 9. For example, to match any number between 300 and 399:
exten => _3XX,1,NoOp(Test)
Z
exten => _3Z,1,NoOp(Test)
N
exten => _3N,1,NoOp(Test)
.
Any number of digits of any kind. For example, to match all numbers that begin with 011:
exten => _011.,1,NoOp(Test)
Note: Don't use the '_.' pattern! This will also include special extensions such as i, t
and h. Use _X. or _X if you need broad pattern matching.
This special 'wildcard' character will match as soon as the number dialed is unambiguous; i.e.
when the number being dialed cannot match any other extension in the context. Once a match is
made, the outgoing line is picked up and dialing proceeds in realtime with direct feedback (this
is known as 'overlap dialing').
Note: A common error is to forget the underscore ("_") character at the beginning of the
pattern. This convention is necessary because SIP devices, as configured in
sip.conf, can have alphanumeric names (For example, in Asterisk, '333',
'loadingdock' and 'A31' are all acceptable names for a SIP device). It also means
that if you forget to use the underscore, your extension will never match and you
will never see an error message alerting you to your mistake.
37
Testing a pattern using dialplan show
An example dialplan looks like this:
[general]
[myphones]
exten => 23,1,Answer()
exten => 23,2,Playback(helloworld)
exten => 23,3,Hangup()
We can call dialplan show from the CLI (invoked with asterisk r if Asterisk is already running) to
verify that our dialplan has been loaded:
*CLI> dialplan show
[ Context 'default' created by 'pbx_config' ]
[ Context 'myphones' created by 'pbx_config' ]
'23' => 1. Answer() [pbx_config]
2. Playback(helloworld) [pbx_config]
3. Hangup() [pbx_config]
[ Context 'parkedcalls' created by 'res_features' ]
'700' => 1. Park() [res_features]
= 2 extensions (4 priorities) in 3 contexts. =
*CLI>
The output includes all the dialplan rules that Asterisk knows about. Notice that there is a
'parkedcalls' context that we haven't seen before; this is activated by default in features.conf and
needn't concern us further. If we are only interested in the myphones context, we can specify our
request with dialplan show myphones:
*CLI> dialplan show myphones
= 1 extension (3 priorities) in 1 context. =
*CLI>
The command dialplan show can also be used to show what Asterisk will do if we dial a specific
number. If we want to dial '25' from a phone in the myphones context, we can see what will happen
with the command dialplan show 25@myphones:
*CLI> dialplan show 25@myphones
38
There is no existence of 25@myphones extension
*CLI>
Nothing happens because there is no match for '25' in the context. If we dial '23' instead, we get this
output:
*CLI> dialplan show 23@myphones
*CLI>
If we want to check '23' against all the accessible contexts, we use dialplan show 23@:
*CLI> dialplan show 23@
*CLI>
Let's expand our dialplan with an additional context by editing extensions.conf like this:
[general]
[myphones]
exten => 23,3,Hangup()
[departmentq]
exten => _2X,1,Answer()
exten => _2X,2,Playback(helloworld)
exten => _2X,3,Hangup()
Now we go back to the CLI and, after reloading the dialplan with the reload command, run dialplan
show 23@:
[ Context 'departmentq' created by 'pbx_config' ]
'_2X' => 1. Answer() [pbx_config]
39
= 2 extensions (6 priorities) in 2 contexts. =
*CLI>
All the matching extensions are displayed. Let's try it with dialplan show 25@:
[ Context 'departmentq' created by 'pbx_config' ]
'_2X' => 1. Answer() [pbx_config]
*CLI>
There is only one match, in context departmentq. In this example, if you dial '25' from a phone in the
myphones context, you still won't hear the 'hello world' message. Extension '25' only works for
phones in the departmentq context.
Pattern matching order
Employing pattern matching in your Asterisk dialplan, while very powerful, can be tricky. It is easy
to assume that Asterisk runs through the dialplan in a completely sequential manner; while this is
generally the case, it does prioritize patterns based on the quality of the match.
The reason for this is simple: more than one pattern might match a dialed number. If two extensions
match a dialed number, Asterisk will always choose the better match. Before deciding which
extension matches best, it processes the entire context.
An example:
[sales]
exten => _12X.,1,NoOp{12X}
exten => 12345,1,NoOp(12345}
exten => _1234.,1,NoOp{1234.}
It is not immediately clear which extension is executed when we dial '12345'. To find out, we use
dialplan show 12345@sales:
*CLI> dialplan show 12345@sales
[ Context 'sales' created by 'pbx_config' ]
'12345' => 1. NoOp(12345}) [pbx_config]
'_1234.' => 1. NoOp{1234.}() [pbx_config]
'_12X.' => 1. NoOp{12X}() [pbx_config]
= 3 extensions (3 priorities) in 1 context. =
*CLI>
Asterisk shows all the hits, but gives extension 12345,1,NoOP{12345} first priority. The highest
40
priority extension is always displayed at the top.
Let's try it with '12346' using the command dialplan show 12346@sales:
'_1234.' => 1. NoOp{1234.}() [pbx_config]
*CLI>
Again, the pattern with the best match to the dialed digits is listed first.
Note: The order in which the patterned extensions appear in the dialplan makes no
difference. Patterned extensions are matched strictly in order of match precision.
A Special Case the pattern "_." in Asterisk 1.2
Digium has changed the expected behavior for the "_." pattern in Asterisk 1.2. Although it is the most
general pattern and should, therefore, be assigned the lowest priority, the behavior is opposite to the
expected behavior.
Note: In Asterisk 1.2, the extension "_." always gets the highest
priority!
Note: Note that the show dialplan command will work in Asterisk 1.4 but is
deprecated; henceforth, examples for Asterisk 1.2 use show dialplan, while
dialplan show is used for examples in Asterisk 1.4.
Let's try adding the extension "_." to our previous dialplan example:
[sales]
exten => 12345,1,NoOp(12345}
exten => _1234.,1,NoOp{1234.}
exten => _.,1,NoOp{Bingo}
When we try testing '12346' with dialplan show 12346@sales, we get the following output:
'_1234.' => 1. NoOp{1234.}() [pbx_config]
'_.' => 1. NoOp{Bingo}() [pbx_config]
*CLI>
41
In Asterisk 1.2, show dialplan 12346@sales gives a very different result:
*CLI> show dialplan 12346@sales
'_.' => 1. NoOp{Bingo}() [pbx_config]
'_1234.' => 1. NoOp{1234.}() [pbx_config]
*CLI>
This is why it is preferable to use "_X." as the wildcard pattern. The following dialplan example is
processed identically in Asterisk 1.2 and 1.4:
[sales]
exten => 12345,1,NoOp(12345}
exten => _1234.,1,NoOp{1234.}
exten => _X.,1,NoOp{Bingo}
The priorities appear as follows in both versions:
'_1234.' => 1. NoOp{1234.}() [pbx_config]
'_X.' => 1. NoOp{Bingo}() [pbx_config]
*CLI>
Priorities
Priorities are numbered steps in the execution of each command that make up an extension. Each
priority represents one specific application. Typically, priority numbers start at 1 and increment
consecutively for each line in the context. Priority numbers are not always consecutive.
Example
[test]
exten => 555,1,Answer
exten => 555,2,Playback(ttweasels)
exten => 555,3,Voicemail(44)
exten => 555,4,Hangup
This example is a definition of a single extension with the name "555". When a call is made to the
extension 555, Asterisk will answer the call itself, play a sound file called "ttweasels", give the user
42
an opportunity to leave a voicemail message for mailbox 44, and then hangup.
In the example, "exten =>" tells the dialplan that the next thing it sees will be a command.
"555" are the actual digits received (i.e. what the caller dialed, or the "extension" number dialed).
"1", "2", "3", and "4" represent the priority, which determines the order in which commands for that
extension will be executed.
Asterisk does not consider the order in which you put the lines in the extensions.conf file. You can
mix the lines into a different order, like the following example, and it will make no difference
because Asterisk uses the priority of each line to determine the order of execution:
[test]
exten => 555,3,Voicemail(44)
The n Priority (Asterisk 1.2.x and later versions)
Instead of having to manually number (and renumber) priorities within a given extension, you may
use "n" to represent the next priority. The "n" automatically increases a priority's value incrementally.
Previously, if you wanted to insert a command between the third and fourth line of a 20priority
extension, you would need to manually renumber each priority after the inserted line.
Example
[test]
exten => 555,n,Playback(ttweasels)
exten => 555,n,Voicemail(44)
exten => 555,n,Hangup
Using "n" priorities, there are two things you can do that make creating extension logic a lot easier.
You can set labels:
exten => s,n(Start),Answer
Labels can make the dial plan more readable, and be the target of gotos as well:
exten => s,n,Goto(Start)
The second feature that makes using priorities easier is that arbitrary increments can be defined:
exten => s,n+2,Dial(...)
Its utility may not be obvious, but it can be pretty handy in conjunction with labels. In a typical dial
plan, Asterisk must often handle the "+101" priority to handle the failure condition of an application,
like Dial(). Without the n priority, if you were to change one of the lines within an extension, not only
must the Dial() priority change, so must the corresponding +101 priority.
With n priority increments, the following expression is possible:
43
exten => s,n(MainDial),Dial(...);Dial the main numbers for this context
...
...
exten => s,MainDial+101,Voicemail(u100)
Now when new dial plan instructions are added before (MainDial) there is no need to update any
priorities.
Note that the "+101" priority may also use a label:
exten => s,MainDial+101(MainDialNotAnswered),Voicemail(u100)
Dial Applications
Applications are the workhorses of the dialplan. Each application performs a specific action on the
current channel, such as playing a sound, accepting touchtone input, or hanging up the call. We have
two applications: Answer( ) and Hangup( ).
Answer([delay])
If the channel is ringing, answer it, otherwise do nothing. If a delay is specified, Asterisk will wait for
the specified number of milliseconds before answering the call.
Hangup()
Unconditionally hangs up a given channel.
Ringing()
Request that the channel indicate the ringing tone to the user.
Some applications, such as Ringing( ) and Hangup( ), need no other instructions to do their jobs.
Other applications require additional information. These pieces of information, called arguments, can
be passed on to the applications to affect how they perform their actions. To pass arguments to an
application, place them between the parentheses that follow the application name, separated by
commas.
44
Asterisk’s Dialplan An Overview
Contexts
Asterisk’s dial plan consists of a collection of contexts. A context is a collection of extensions. Each
context in a dial plan has a unique name associated with it. Context definitions are an important part
of the extensions.conf file and of Asterisk’s configuration.
Contexts can be used to implement a number of important features, including:
• Security: Permit long distance calls from certain phones only
• Routing: Route calls based on an extension
• Autoattendant: Greet callers and ask them to enter extensions
• Multilevel Menus: Menus for sales, support, etc.
• Authentication: Ask for passwords for certain extensions
• Callback: Reduce long distance charges
• Privacy: Blacklist annoying callers from contacting you
• PBX Multihosting: "Virtual hosts" on your PBX
• Daytime/Nighttime: You can vary behavior after hours
• Macros: Create scripts for commonly used functions
The following example is a diagrammatic representation a simple context (Warning! Not to be typed
into the extensions.conf file):
default
Extension Description
101 Mansoor
102 Ifthikhar
103 Sufyan
104 Check Voice Mail
105 Conference Room
0 0 Operator
In this example, named "default", the first three extensions (101103) will be associated with ringing
phones belonging to various employees. The fourth extension (104) will be associated with allowing
someone to check their voicemail. The fifth extension (105) will be associated with a conference
room. Finally, the "0" extension will be associated with an operator.
45
A practical example in extensions.conf is given below:
[context]
exten => someexten,priority,application(arg1,arg2,...)
exten => someexten,priority,application,arg1|arg2... )
Variables
A variable is a placeholder for an actual value. Exactly what that value is depends on the kind of
variable. In Asterisk, variables can contain numbers, letters and strings (sequences of letters and
numbers). Variables are useful because they help us create rules for call flow that apply in changing
circumstances, and make it easier to accommodate future changes in the telephone application or
system.
Variables are referenced in the dial plan (extensions.conf) using the syntax:
${foo}
where foo is the name of the variable. The variable’s name enclosed in curly brackets is preceded by a
dollar sign referencing the value of the variable.
A variable name may be any alphanumeric string beginning with a letter. Userdefined variable
names are not case sensitive — ${FOO} and ${Foo} refer to the same variable — but Asterisk
defined variables are casesensitive — ${EXTEN} works, but ${exten} does not.
There are three types of variables: global variables, channel variables, and environment variables.
Global Variables
Global variables apply to all extensions in all contexts. They are useful in that they can be used
anywhere within a dial plan to increase readability and manageability. Suppose for a moment that you
had a large dial plan and several hundred references to the Zap/1 channel. Now imagine that you had
to go through your dial plan and change all those references to Zap/2. It would be a long and error
prone process, to say the least. On the other hand, if you had defined a global variable with the value
Zap/1 at the beginning of your dial plan and then referenced that instead, you would only have to
change one line. Global variables should be declared in the [globals] context at the beginning of the
extensions.conf file. They can also be defined programmatically, using the SetGlobalVar( )
application.
Here is how both methods look inside a dial plan:
[globals]
OPEN=Zap/1
[internal]
exten => 123,1,SetGlobalVar(OPEN=Zap/1)
46
Channel Variables
A channel variable is a variable (such as the Caller*IDnumber) that is associated only with a
particular call. Unlike global variables, channel variables are defined only for the duration of the
current call, and are available only to the channel participating in that call. There are many predefined
channel variables available for use within the dialplan.
Channel variables are set via the Set( ) application:
exten => 123,1,Set(MAGICNUMBER=42)
Environment Variables
Environment variables are a way of accessing UNIX environment variables from within Asterisk.
These variables are referenced in the form of ${ENV(var)}, where var is the UNIX environment
variable you wish to reference.
Consider the following example:
[FooTest]
exten => 100,1,SetGlobalVar(FOO=5)
exten => 100,2,NoOp(${FOO})
exten => 100,3,NoOp(${foo})
exten => 100,4,SetVar(foo=8)
exten => 100,5,NoOp(${FOO})
exten => 100,6,NoOp(${foo})
If you dial extension 100 in the context FooTest, and you have Asterisk running with a verbose
console, you will see output similar to the following:
— Executing SetGlobalVar("Zap/11", "FOO=5") in new stack
— Setting global variable 'FOO' to '5'
— Executing NoOp("Zap/11", "5") in new stack
— Executing SetVar("Zap/11", "foo=8") in new stack
After the call to SetGlobalVar, ${FOO} and ${foo} returned the value of the global variable,
giving the value 5. After the call to SetVar, the global variable "foo" was obscured by the channel
variable "foo"; ${FOO} and ${foo} both gave the value 8. The value of the global variable
remains unchanged at 5, however, and any other channels that refer to the global variable ${foo}
will still get the value 5.
Inheritance of Channel Variables
47
Prepending a single _ character to a variable’s name in SetVar will cause that variable to be inherited
by channels created by the main channel. For example, when using Dial(Local/...); once inherited,
these variables will not be further inherited. Prepending two _ characters will cause them to be
inherited indefinitely.
Example
Exten => 104,1,SetVar(FEE=fee)
exten => 104,2,SetVar(_FIE=fie)
exten => 104,3,SetVar(__FUM=fum)
exten => 104,4,Dial(Local/105)
exten => 105,1,NoOp(${FEE})
exten => 105,2,NoOp(${FIE})
exten => 105,3,NoOp(${FUM})
exten => 105,4,Dial(Local/106)
exten => 106,1,NoOp(${FEE})
exten => 106,2,NoOp(${FIE})
exten => 106,3,NoOp(${FUM})
results in:
— Executing SetVar("SIP/oberon365e", "FEE=fee") in new stack
— Executing SetVar("SIP/oberon365e", "_FIE=fie") in new stack
— Executing SetVar("SIP/oberon365e", "__FUM=fum") in new stack
— Executing Dial("SIP/oberon365e", "Local/105") in newstack
— Called 105
— Executing NoOp("Local/105@default7263,2", "") in new stack
— Executing NoOp("Local/105@default7263,2", "fie") in new stack
— Executing NoOp("Local/105@default7263,2", "fum") in new stack
— Executing Dial("Local/105@default7263,2", "Local/106") in new stack
— Called 106
— Executing NoOp("Local/106@default49be,2", "") in new stack
— Executing NoOp("Local/106@default49be,2", "") in new stack
— Executing NoOp("Local/106@default49be,2", "fum") in new stack
Include
Includes are a powerful tool for simplifying and organizing larger dial plans. By using an include
statement, you can include other contexts in the current context.
48
The following is an include statement, where context is the name of the remote context we want to
include in the current context:
include => context
Order of execution when using include statements
Asterisk will always look for a match in the current context before referencing any included contexts.
If a matching entry is found, that entry is used. If a matching entry is not found, Asterisk will look for
a match in the first included context, then the next, and so on. It is also possible to have nested
includes; that is, includes within includes.
In case of doubt, verify which entry Asterisk is using to handle a call by entering show dialplan
number@nameofcontext in Asterisk’s CLI.
Timeconditional include statements
An include statement can be made conditional to the time of day. This makes it easier to implement
different day and night behaviors.
Syntax
include => context|<time>|<day>|<dayofmonth>|<month>
The day and month are specified using the first three letters of the full name. Weekdays, for example,
are specified as mon, tue, wed, thu, fri, sat, sun, and months are specified as jan, feb, mar, apr, etc.
The time is specified in the 24 hour format.
Example
A business opens from 9:00 a.m. until 5:00 p.m. Monday to Friday and from 9:00 a.m. to 2:00 p.m.
on Saturday. The dialplan will look like this:
; Day
include => open|09:0017:00|monfri|*|*
include => open|09:0014:00|sat|*|*
include => closed
[open]
exten => 2000,1,Dial(SIP/2000)
[closed]
exten => 2000,1,VoiceMail(2000,u)
Including Files
Other files are included with the #include <filename> statement in extensions.conf. This way, you
can setup a system where extensions.conf is the main file, users.conf contains your local users, and
49
services.conf contains various services, such as conferencing. This way, the dialplan may be easier to
maintain, depending on the size of your setup. The #include <filename> statement is not the same as
the include <context> statement. The #include statement works in all Asterisk configuration files.
Macros
A macro is a kind of subroutine. It can contain complex workflows, but is called through a single
entry. A macro is used to avoid repetition in the dialplan, make it cleaner and smaller, and also easier
to modify flows on a large scale. Macros are implemented by creating an extension context whose
name starts with “macro” and is enclosed in square brackets. For example:
[macrovoicemail]
exten => s,1,Dial(SIP/${MACRO_EXTEN},10)
exten => s,n,VoiceMail(${MACRO_EXTEN})
The remaining commands are the same as the commands in the contexts, with a few exceptions:
• Only one extension, the s extension, is allowed in macros
• The original ${EXTEN} and ${CONTEXT} variables cannot be used inside a macro.
${MACRO_EXTEN} and ${MACRO_CONTEXT} variables are used instead.
A macro is called with a Macro() application in an extension. When calling a macro, additional
comma (",") or pipeseparated ("|") arguments can be supplied. These arguments are called within the
macro with ${ARGn} (where n is a positive integer indicating which argument in the sequence). Its
syntax is:
Macro(macroname,arg1,arg2...)
Example:
[macrotwoline]
;
; Standard twoline phone.
;
; ${ARG1} – First phone
; ${ARG2} – Second phone
;
exten => s,1,Dial(${ARG1},20)
exten => s,2,Voicemail(u${MACRO_EXTEN})
exten => s,102,Dial(${ARG2},20)
exten => s,103,Voicemail(b${MACRO_EXTEN})

Now call this macro:
[default]
exten => 1001,1,Macro(twoline,SIP/1001,SIP/1002)
50
The application MacroExclusive() ensures that the specific macro can only be called once at any
given time. If another channel is calling the macro, no other channel can call it until it completes.
Special Extensions
All programming logic must occur via extensions; therefore, we need some additional systemdefined
extensions.
The h extension
The h is the standard "hangup" extension. The h extension, if it is configured, is called when a caller
hangs up the phone. Note that as soon as this happens, the content of ${EXTEN} changes to h,i.e.,
when the call is hung up, the channelrelated variables get destroyed.
Example
Let’s assume that we want the global variable CONNECTIONS to reflect the number of currently
active conversations at any given time. This means that we need the value of CONNECTIONS to
increase by one every time a connection is initiated, and decrease by one every time someone hangs
up. The following dial plan illustrates the basic idea:
[global]
CONNECTIONS=0
[frominternal]
exten => _X.,1,Set(CONNECTIONS=$[${CONNECTIONS} + 1]|g)
exten => _X.,2,Dial(SIP/${EXTEN})
exten => h,1,Set(CONNECTIONS=$[${CONNECTIONS} 1]|g)
The i extension
This extension is executed when a caller enters an invalid extension. If a caller dials a number, and no
match is made in extensions, Asterisk will not call 'i' extension. The 'i' extension only gets fired when
there is a prompt, or input been made with 'background'.
When i extension is called, the ${EXTEN} will no longer contain the dialed number. To get the
dialed number when i is called, use ${INVALID_EXTEN}.
Example
In this example, we can only dial extensions 100199 in the sales department. Callers dialing any
other number will hear the message, "I'm sorry. That is not a valid extension. Please try again".
[sales]
exten => _1XX,1,Dial(${EXTEN})
exten => i,1,NoOp(An invalid number ${INVALID_EXTEN} was dialed.)
exten => i,2,Answer()
51
exten => i,3,Playback(invalid)
exten => i,4,Hangup()
The o and a extensions
If operator=yes is set in voicemail.conf, the call will be directed to the o extension (o is for operator)
if the caller presses "0".
Pressing * (asterisk) will direct the call to the a extension (abort).
The t and T extensions
The t and T extensions are for handling timeouts in the context.
t extension
If there is no input in an IVR menu within a certain timeframe, the t extension is called.
Example:
[mainmenu]
exten => 10,n,Background(marryme) ; "Marry me? Press 1 for yes, 2 for no."
exten => 1,1,Playback(thankyoucooperation) ; 1 => "Thank you."
exten => 1,n,Hangup()
exten => 2,1,Playback(hanguptryagain) ; 2 => "Hang up and try again."
exten => 2,n,Hangup()
exten => t,1,Hangup() ; no input => hang up
T extension
The T extension is called after the absolute timeout has been exceeded. You can set this timeout value
with Set(TIMEOUT(absolute)=<seconds>)
Note: Be careful not to have any spaces before and after the "=" character.
The timer starts whenever the timeout value is set (it does not automatically start with the connection,
it must be started explicitly with the Set() command). Set(TIMEOUT(absolute)=0) deactivates the
absolute timeout.
Example:
exten => 20,2,Set(TIMEOUT(absolute)=120)
exten => 20,4,Wait(1)
exten => 20,5,Goto(3)
exten => T,1,Wait(1)
exten => T,2,Playback(thankyouforcalling)
52
exten => T,3,Wait(1)
exten => T,4,Hangup()
The s extension
The first entry in any extension is always the name or number dialed by the caller. When a call comes
in from the PSTN, however, Asterisk does not know what was dialed, or whom the caller is trying to
reach. For any scenario in which we cannot determine the number dialed, use the s extension.
Example:
exten => s,1,Answer()
exten => s,2,Wait(1)
exten => s,3,Play(ttmonkeys)
exten => s,4,Wait(1)
exten => s,5,Hangup()
Asterisk’s Dial Command
The Dial command sends out a call on one or more channels. When one of the dialed channels picks up the call, the
Dial command bridges the two channels. The Dial command can answer a call from an originating channel.
If there is no answer, and the calling party does not hang up, only a timeout tops the Dial command. If a timeout is not
specified, the Dial application waits indefinitely until either one of the called channels answers, the user hangs up, or
all the channels return a busy tone or an error.
The Dial command’s syntax is:
Dial(type1/identifier1[&type2/identifier2[&type3/identifier3... ] ], timeout, options, URL)
Parameters
− Jumping in Asterisk Version (v.) 1.2.14: In [general] you can set priorityjumping=yes/no. The
default as of v. 1.2.14 is "yes". When set to "yes", the dial plan jumps to priority +101 as busy,
congested, and channel unavailable. The wiki "used" implies that the default was "no" if
priorityjumping is not set. This does not appear to be the case in v. 1.2.14.
type specifies the channel type. It should be one of the registered channel types, such as "Zap",
"SIP", "IAX2", and so on.
identifier specifies the "phone number" to dial on that channel. The format of the "phone number"
depends on the channel, and may contain additional parameters.
• To specify more than one channel for the Dial command to try — remembering that it will
dial out on all of them simultaneously — separate them with the & symbol (there must not be
a space before and after the symbol). The channels can be of different types.
• The timeout parameter is optional. If not specified, the Dial command will wait indefinitely,
exiting only when the originating channel hangs up, or all the dialed channels return a busy
tone or an error condition. If the maximum time is specified, in seconds, then the Dial command
53
waits for a channel to answer.
t: Allow the called user to transfer the call by hitting the blind xfer keys (features.conf)
T: Allow the calling user to transfer the call by hitting the blind xfer keys (features.conf)
r: Generate a ringing tone for the calling party, passing no audio from the called channel(s) until
someone answers. Without this option, Asterisk will generate ringtones automatically where it is
appropriate to do so; "r", however, will force Asterisk to generate ringtones, even if it is inadvisable.
If, for example, you use this option to force ringing but the line was busy, the user will hear "RING
RIBEEP BEEP BEEP" which is potentially confusing and/or unprofessional. This option is, however,
necessary in some cases. When you dial multiple channels, for example, call progress information is
inconsistently passed back.
R: Indicate ringing to the calling party when the called party indicates ringing, pass no audio until
answered. This is available only if you are using kapejod's Bristuff.
m: Provide musiconhold to the calling party until the called channel answers. This is mutually
exclusive with option 'r'. Use m(class) to specify a class for the musiconhold.
h: Allow the called person to hang up by dialing *
H: Allow the caller to hang up by dialing *
o: Restore Asterisk’s v. 1.0 CallerID behaviour (send the original caller's ID) in Asterisk v. 1.2
(default: send this extension's number)
j: Asterisk’s v. 1.2 and later: Jump to priority n+101 if all of the requested channels are busy (similar
to the behaviour in Asterisk’s v. 1.0.x)
M(x): Executes the macro (x) once the call connects (i.e. when the called party answers)
i: Asterisk will ignore any forwarding requests it may receive on this dial attempt (this is new in v.
1.4) It is useful if you are ringing a group of people, and one person has set their cellphone to
forwarded direct to voicemail, which normally prevents any of the other phones from ringing.
C: Reset the Call Detail Record (CDR) for this call. This is similar to using the NoCDR command.
Asterisk does not save CDR for a certain call with the nocdr command.
'P(x)' privacy mode, using 'x' as database if provided.
g: When the called party hangs up, exit to execute more commands in the current context.
G(contextêxten^pri): If the call is answered, transfer both parties to the specified context and
extension. The calling party is transferred to priority x, and the called party to priority x+1. This
allows the dialplan to distinguish between the call’s calling and called legs (this is new in v. 1.2).
A(x): Play an announcement (x.gsm) to the called party.
S(n): Hang up the call n seconds AFTER the called party picks up.
D(digits): After the called party answers, send digits as a DTMF stream, then connect the call to the
originating channel. (Use 'w' to produce .5 second pauses.)
The optional URL parameter will also be sent to the called party upon successful connection, if
the channel’s technology supports this feature.
Return Codes Of Dial Command
54
Dial sets DIALSTATUS to indicate its success or failure. Under some circumstances, however,
execution jumps to priority n+101 in the current context. This happens when:
• All channels dialed are busy
• Something exists at n+101 in the current context
• You are running Asterisk’s v. 1.0.x, priorityjumping=yes is set in extensions.conf, or the j
option is specificed in the Dial command
Asterisk’s channel variable DIALSTATUS
Contains a text string outlining the result of the last dial attempt:
• ANSWER: Call is answered. A successful dial. The caller has reached the called person.
• BUSY: Busy signal. The Dial command reached its number, but the number is busy.
• NOANSWER: No answer. The Dial command reached its number, the number rang for too
long, and then the dial timed out.
• CANCEL: Call is cancelled. The Dial command reached its number but the caller hung up
before the called person picked up.
• CONGESTION: Congestion. This status is usually a sign that the dialed number is not
recognized.
• CHANUNAVAIL: Channel unavailable. The peer may not be registered on SIP.
Note: In order to obtain useful DIALSTATUS information when dialing a peer, you will
need to have qualify=yes in that peer's definition (e.g. in sip.conf or iax.conf).
• CONGESTION: The term "Congestion" is a little misleading. Dial() returns

DIALSTATUS=CONGESTION for pretty much every call setup problem. This is because
Dial() can be used for multiple protocols (Zap, SIP, IAX, etc.) It is, therefore, limited to the
lowest common denominator and is unable to return the protocolspecific information (i.e. SIP
404 response).
Examples for using the 'Dial' application
exten => 7100,1,Dial,Zap/1|24
Defines the PBX extension 7100. It dials a Zapatadefined extension '1' with no options and a 24
second timeout. If the call is not answered within 24 seconds, the call fails, and the next “step” in the
extension’s definition will be executed.
exten => 7100,1,Dial,IAX/24
Defines the PBX extension 7100. It dials an IAXdefined extension named '24' with no options. The
call will ring indefinitely.
55
exten => 7101,1,Dial,SIP/32|20
Defines the PBX extension 7101. It dials a SIPdefined extension named '32' with no options and a
20second timeout. If the call is not answered within 20 seconds, the call fails, and the next “step” in
the extension’s definition will be executed.
exten => s,1,Dial,IAX/10&IAX/11&IAX/12&IAX/13
This is an example of ringing multiple extensions. This is typically done in response to an incoming
call from outside the PBX (i.e. a customer). The first extension to answer the call gets it.
Ignorepat => 9
exten => _9911,1,Dial,ZAP/g2/911
exten => _911,2,Dial,ZAP/g2/911
exten => _9NXXNXXX,3,StripMSD,1
exten => _NXXNXXX,4,Dial,ZAP/g2/BYEXTENSION
This example illustrates the Ignorepat option, which is used to instruct the channel driver to keep the
dialtone alive if this “pattern” is seen. This example also shows the StripMSD command which is
used to remove the first digit in this example (see the StripMSD command section of this manual for
more information regarding this command’s use). Finally, use a pattern match in order to ensure a
valid phone number. Once this is verified, the number as dialed is passed out the ZAP channel on
group “g2” as a dial command. This example implements a standard “dial 9 for an outside line” setup
often seen in other PBX systems (but does not implement longdistance dialing).
This example also implements a “911” emergency services number (the US standard for reaching
emergency fire, police and ambulance services). If anyone dials 9911 or 911 within the US, the caller
is immediately connected to the emergency services number.
The following is an example of a local Zap channel callout with an SIP failover:
[macrolocalcallout]
exten => s,1,Dial(${ZAP/1/${ARG1},,T)
exten => s,n,NoOp( Dial Status: ${DIALSTATUS})
exten => s,n,Goto(s${DIALSTATUS},1)
exten => sNOANSWER,1,Hangup
exten => sCONGESTION,1,Congestion
exten => sCANCEL,1,Hangup
exten => sBUSY,1,Busy
exten => sCHANUNAVAIL,1,SetCallerId(${CALLERIDNUM})
exten => sCHANUNAVAIL,2,Dial(SIP/sippeer/${LOCALAREACODE}${ARG1},,T)

56
Huntdial Macro
[default]
include => pstnout
[macrohuntdial]
; ${ARG1} channel
; ${ARG2} Dialed Number
exten => s,1,SetGroup(${ARG1}) ; increment GROUPCOUNT
exten => s,2,GetGroupCount()
exten => s,3,NoOp(GROUPCOUNT:${GROUPCOUNT})
exten => s,4,GotoIf($["${GROUPCOUNT}" = "1"]?5:6) ; if GROUPCOUNT = 1, then it's free for
dialing.
exten => s,5,Dial(SIP/${ARG2}@${ARG1}) ; use it to call out.
exten => s,6,NoOp(${ARG1} is inused)
[pstnout]
exten => _XXXXXXXX,1,Macro(huntdial,line1,${EXTEN}) ; list your SIP channels here in the
hunting order
exten => _XXXXXXXX,n,Macro(huntdial,line2,${EXTEN})
.
.
.
exten => _XXXXXXXX,n,NoOp("No Channel available")
exten => _XXXXXXXX,n,Hangup()
Dial Applications
Background( )
Background(filename)
Plays the specified audio file(s) while waiting for the user to begin entering an extension. Once the
user begins to enter an extension, the playback is terminated. The filename should be specified
without a file extension, as Asterisk will automatically find the file format with the lowest translation
cost.
57
Playback( )
Playback(filename)
Plays back a given filename to the caller. The filename should not contain the file’s extension, as
Asterisk will automatically choose the audio file with the lowest conversion cost.
SayDigits( )
SayDigits(digits)
Says the passed digits, using the current language setting for the channel. See the SetLanguage( )
application to change the current language.
exten => 123,1,SayDigits(1234)
Answer( )
Answer( )
Causes Asterisk to answer the channel if it is currently ringing. If the current channel is not ringing,
this application does nothing. Unless you have a very good reason not to, it is usually a good idea to
use Answer( ) on the channel before calling any other applications. Most applications require that the
channel be answered before they are called, otherwise they may not work correctly.
exten => 123,1,Answer( )
exten => 123,2,Wait(1)

Hangup( )
Unconditionally hangs up the current channel. Always returns 1.
exten => 123,2,Playback(imsorry)
exten => 123,3,Hangup( )
Busy( )
Busy([timeout])
Requests that the channel indicate the busy condition, and then either waits for the user to hang up, or
for the optional timeout (in seconds) to expire. This application only signals a busy condition to the
bridged channel. Each particular channel type has its own way of communicating the busy condition
to the caller. Use Playtones(busy) to play a busy tone to the caller. Always returns 1.
exten => 123,1,Playback(imsorry)
exten => 123,2,Playtones(busy)
58
exten => 123,3,Busy( )
Set( )
Set(n=value)
Sets the variable n to the specified value. If the variable’s name is prefixed with _, a single
inheritance is assumed. If the variable’s name is prefixed with _ _, an infinite inheritance is assumed.
An inheritance is used when you want the outgoing channel to inherit the variable from the
dialplan.Variables set with this application are only valid in the current channel. Use the
SetGlobalVar( ) application to set global variables.
; Set a variable called DIALTIME, and then use it:
exten => 123,1,SetVar(DIALTIME=20)
exten => 123,1,Dial(Zap/4/5551212,,${DIALTIME})
Wait( )
Wait(seconds)
Waits for the specified number of seconds, then returns 0. You can pass fractions of a second (e.g.,
1.5 = 1.5 seconds).
; Wait 1.5 seconds before playing the prompt:
exten => s,1,Answer( )
exten => s,2,Wait(1.5)
exten => s,3,Background(enterextofperson)
WaitExten( )
WaitExten([seconds])
Waits for the user to enter a new extension for the specified number of seconds, then returns 0. You
can pass fractions of a second (e.g., 1.5 = 1.5 seconds). If unspecified, the default extension timeout
will be used.
; Wait 15 seconds for the user to dial an extension:
exten => s,2,Playback(enterextofperson)
exten => s,3,WaitExten(15)
59
Goto( )
Goto([[context,]extension,]priority)
Goto(named_priority)
Sends control of the current channel to the specified priority, optionally setting the destination’s
extension and context. You can also use the application to go to the named priority specified by the
named_priority argument. Named priorities only work within the current extension. Always returns 0,
even if the given context, extension, or priority is invalid.
exten => 123,2,Set(COUNT=1)
exten => 123,3,SayNumber(${COUNT})
exten => 123,4,Set(COUNT=$[ ${COUNT} + 1 ])
exten => 123,5,Goto(3)
; same as above, but using a named priority
exten => 124,2,Set(COUNT=1)
exten => 124,3(repeat),SayNumber(${COUNT})
exten => 124,4,Set(COUNT=$[ ${COUNT} + 1 ])
exten => 124,5,Goto(repeat)
GotoIf( )
GotoIf(condition?label1:label2)
Sends the call to label1 if the condition is true, or to label2 if the condition is false. Either label1 or
label2 may be omitted (in that case, we just don't take the particular branch), but not both. A label can
be any one of the following: a priority, such as 10An extension and a priority, such as 123,10A
context, extension, and priority, such as incoming, 123, 10A named priority within the same
extension, such as passed. Each label’s type is explained in the example given below:
[globals]
; set TEST to something else besides 101 to see what GotoIf( )
; does when the condition is false
TEST=101
;
[incoming]
; set a variable
; go to priority 10 if ${TEST} is 101, otherwise go to priority 20
exten => 123,1,GotoIf($[ ${TEST} = 101 ]?10:20)
exten => 123,10,Playback(themonkeystwice)
exten => 123,20,Playback(ttsomethingwrong)
;
60
; same thing as above, but this time we'll specify an extension
; and a priority for each label
exten => 124,1,GotoIf($[ ${TEST} = 101 ]?123,10:123,20)
;
; same thing as above, but these labels have a context, extension, and
; priority
exten => 125,1,GotoIf($[ ${TEST} = 101 ]?incoming,123,10:incoming,123,20)
;
; same thing as above, but this time we'll go to named priorities
exten => 126,1,GotoIf($[ ${TEST} = 101 ]?passed:failed)
exten => 126,15(passed),Playback(themonkeystwice)
exten => 126,25(failed),Playback(themonkeystwice)
GotoIfTime( )
GotoIfTime(times,days_of_week,days_of_month,months?label)
Branches to the specified extension, if the current time matches the specified time. Each of these
elements may be specified either as * (for always) or as a range.The arguments for this application
are: timesTime ranges, in 24hour formatdays_of_weekDays of the week (mon, tue, wed, thu, fri, sat,
sun)days_of_monthDays of the month (131)monthsMonths (jan, feb, mar, apr, etc.)
; If we're open, then go to the open context
; We're open from 9am to 6pm Monday through Friday
exten => s,1,GotoIfTime(09:0017:59,monfri,*,*?open,s,1)
; We're also open from 9am to noon on Saturday
exten => s,2,GotoIfTime(09:0011:59,sat,*,*?open,s,1)
; Otherwise, we're closed
exten => s,3,Goto(closed,s,1)
61
Asterisk’s Features
Asterisk’s Call Forwarding
If you use this setup, a phone can dial *21*<number> for immediate redirect or
*61*<number> for delayed redirect, and #21# or #61# to cancel the setting.
Abbreviations used
• CFIM: Call forward database family for labels in Asterisk’s database.
• CFBS: Call forward when busy database family for labels in Asterisk’s database.
Asterisk’s Database
Database data is grouped in families and identified with a key that is unique within the family.
Asterisk’s cmd DBput
Description
DBput(family/key=value)
Stores the given value in Asterisk’s database.
Return Codes
Always returns 0
Release 1.2 and Later
DBPut(family/key=${foo}) (deprecated)
Set(DB(family/key)=${foo}) (new syntax)
Release 1.4 and Later
Set(DB(family/key)=${foo})
Asterisk’s cmd DBget
Description
pre Release 12
DBget(varname=family/key)
Retrieves a value from Asterisk’s database and stores it in the given variable.
62
Note: Use Asterisk’s CLI console commands "database show", "database get", "database put",
"database del" and "database deltree" to access Asterisk’s database. This can also be done through
scripts using the "asterisk rx <command>" method.
Return Values
Always returns 0. If the requested key is not found, jumps to priority n+101 if available.
Release 12
DBGet(foo=family/key) (deprecated)
Set(foo=${DB(family/key)})
Release 14 and later
Set(foo=${DB(family/key)})
Asterisk’s cmd DBdel
Description
DBdel(family/key)
Deletes a key from Asterisk’s database.
Asterisk’s cmd DBdeltree
Description
DBdeltree(family/keytree)
Deletes a family or keytree from Asterisk’s database.
Return Codes
Always returns 0.
For example:
[apps]
; Unconditional Call Forward
exten => _*21*X.,1,DBput(CFIM/${CALLERIDNUM}=${EXTEN:4})
exten => _*21*X.,2,Hangup
exten => #21#,1,DBdel(CFIM/${CALLERIDNUM})
exten => #21#,2,Hangup
; Call Forward on Busy or Unavailable
exten => _*61*X.,1,DBput(CFBS/${CALLERIDNUM}=${EXTEN:4})
63
exten => #61#,1,DBdel(CFBS/${CALLERIDNUM})
exten => #61#,2,Hangup
Do not use "#" for SIP adapters such as Grandstream Handytone, because they will not be sent. These
phones and adaptors use # as the character to end the telephone number, so that you do not have to
wait for the timeout. Use something like this for call forwarding instead:
[apps]
;
; Unconditional Call Forward
;
; create call forward
exten => _*21*X.,1,GotoIf($${EXTEN:1} = #?2:3)
exten => _*21*X.,2,StripLSD(1)
exten => _*21*X.,3,DBput(CFIM/${CALLERIDNUM}=${EXTEN:4})
;
; delete call forward
exten => **21,1,DBdel(CFIM/${CALLERIDNUM})
exten => **21,2,Hangup
;
; delete call forward (with #)
exten => **21#,1,Goto(**21,1)
[macrostdexten]
;
; Standard extension macro (with call forwarding):
; ${ARG1} Extension(we could have used ${MACRO_EXTEN} here as well
; ${ARG2} Device(s) to ring
;
exten => s,1,Set(temp=${DB(CFIM/${ARG1})})
exten => s,n,GotoIf(${temp}?cfim:nocfim)
exten => s,n(cfim),Dial(Local/${temp}@default/n) ; Unconditional forward
exten => s,n(nocfim),NoOp
exten => s,n,Dial(${ARG2},15) ; 15sec timeout
exten => s,n,Set(temp=${DB(CFBS/${ARG1})})
exten => s,n,GotoIf(${temp}?cfbs:nocfbs)
exten => s,n(cfbs),Dial(Local/${temp}@default/n) ; Forward on busy or unavailable
64
exten => s,n(nocfbs),Busy
Notes
• This macro reads variables stored in Asterisk’s database.
• The macro executes 'Dial(Local/<number>@pbx)' if a redirection number is found. This
means that the number that was selected is dialable from the pbx context. You should
probably modify this. (If, for instance, you only want outbound redirect, this can be
Dial(Zap/1/<number>).
• If the DBget does not find a key, it exits with the result code 101, making the next step in the
dial plan the current priority+101.
Call Monitoring
Call monitoring involves a supervisor tapping into a phone transaction between an agent and a caller.
There are several methods of monitoring a call:
• Voiceonly monitoring
• Voice and data monitoring (the supervisor monitors the voice call, and views the agent’s
actions on a computer screen)
• Coaching (the supervisor and the agent hear the voice call and can communicate – the caller
only hears the agent)
• Conferencing (the supervisor, agent and caller can all communicate with each other)
Call monitoring is possible with ChanSpy(), ZapBarge(), and ExtenSpy().
ChanSpy()
It is advisable to monitor call center agents by listening in on their telephone calls.
Chanspy([<scanspec>][|<options>])
Valid Options:
b: Only spy on channels involved in a bridged call.
g(grp): Match only channels where their ${SPYGROUP} variable is set to contain 'grp' in an
optional : delimited list.
q: Don't play a beep when beginning to spy on a channel, or mention the selected channel’s name.
r[(basename)]: Record the session to the monitor spool directory. An optional base for the filename
may be specified. The default is 'chanspy'.
v([value]): Adjust the initial volume in the range from 4 to 4. A negative value refers to a quieter
setting.
65
While Spying:
Dialing # cycles the volume level.
Dialing * will stop spying and look for another channel to spy on.
ZapBarge()
ZapBarge(channel)
Lets you listen in on a conversation on a specified Zap channel, or prompts if one is not specified.
You can hear them, but they can't hear you. No indication is given to the two parties that their call is
being listened in on.
Multiple people can use ZapBarge to listen in on the same channel.
Example
;barge monitoring extension
exten => 8159,1,ZapBarge
If you dial 8159 on a phone, you are asked which line you want to listen in on, for Zap/11 you would
press 1#, for Zap/251 you would press 25#.
ExtenSpy()
Eavesdrop on a channel attached to a specific extension and whisper to it if necessary.
ExtenSpy(extension)
Parameters
• The options parameter, which is optional, is a string containing 0 or more of the following
flags and parameters:
• b: Only listens to channels which belong to a bridged call.
• g(grp): Only listens to channels where the channel variable ${SPYGROUP} is set to grp.
${SPYGROUP} can contain a separated list of values.
• q: When listening starts on a channel, do not play a tone or mention the channel’s name.
• r(name): Records the listening session to the spool directory. A filename may be specified if
necessary; chanspy is the default.
• v(value): Sets the initial volume. The value may be between 4 and 4.
• w: Enables "whisper" mode. Lets the spying channel talk to the spiedupon channel.
• W: Enables "private whisper mode". The spying channel can whisper to the spiedupon
66
channel, but cannot listen.
The following key controls are available while listening:
# : Stepwise volume adjustment (4 to 4)
* : Switch to another channel
Example:
[snoop]
exten => _555/705,1,ExtenSpy(|v(4))
[705]
exten => 705,1, dail(IAX2/trunk_3)
include => snoop
Call Recording
Asterisk’s call recording is possible via Monitor() and MixMonitor().
Monitor()
• Monitor(ext,basename)
• Monitor(ext,basename,flags) — New feature added to CVS 20040603
The Monitor command starts recording a channel. The channel's input and output voice packets are
saved to separate sound files. Recording continues until either the StopMonitor command is executed
or the channel hangs up.
If you do not specify a full path, the file will be stored in the "monitor" subdir of the path specified
with astspooldir in asterisk.conf (the default will be /var/spool/asterisk/monitor).
Command Parameters
• ext: The sound file format to save in, which will also be used as the filename extension.
Default: wav
• basename: The base filename to use when saving the sound files. If not supplied, the default
basename is constructed on the channel’s name plus a number, for example, IAX2[foo@bar]
3. The channel's input voice packets will be saved to basenamein.ext and the output voice
packets will be saved to basenameout.ext. The default location for saved files is the
/var/spool/asterisk/monitor directory.
• flags: If flags contains the letter m, then, when recording finishes, Asterisk will execute a
67
UNIX program to combine the two sound files into a single sound file. Asterisk will execute
soxmix and then delete the original two sound files by default.
Example
[recordout]
exten => _8.,1,SetVar(CALLFILENAME=${EXTEN:1}${TIMESTAMP})
exten => _8.,2,Monitor(wav,${CALLFILENAME},m)
exten => _8.,3,Dial(ZAP/g1/${EXTEN:1})
exten => _8.,4,Congestion
exten => _8.,104,Congestion
MixMonitor ()
This application is similar to the Monitor application, except that it is designed to record one audio
and mix it natively as the call progresses in order to avoid the need to spawn external processes which
lead to harmful CPU usage spikes.

Description
MixMonitor(<file>.<ext>[|<options>[|<command>]])
Records the audio on the current channel to the specified file.
Valid Options:
b – Only save audio to the file while the channel is bridged. *does not include conferences*
a – Append to the file instead of overwriting it.
Call Transfer
Call Transfer is used to transfer a call in progress to some other destination.
There are two types of call transfer:
• Supervised call transfer Where the call is placed on hold, a call is placed to another party,
and a conversation takes place privately before the caller on hold is connected to the new
destination. This is also known as an "Attended Call Transfer" as well.
• Blind call transfer Where the call is transferred to the other destination with no intervention
(for instance, the other destination could ring out and not be answered).
In Asterisk
• *2 Attended call transfer.
• # Blind call transfer. Note that the user might end up being forwarded to voicemail or
68
elsewhere.
• This patch looks for the variable GOTO_ON_TRANSFER in a # transferring channel and
sends the transferrer to that context|exten|pri (you can use ^ to represent | to avoid escapes)
exten => 3001,1,SetVar(GOTO_ON_TRANSFER=woohoo^s^1)
exten => 3001,2,Dial(SIP/10.3.3.6|60|Tt)
If you now perform a # transfer you will end up at woohoo,s,1
Call Parking
Call Parking is the ability to place a call on hold into a specific parking location (a fictional
extension) so that the call can then be picked up by another extension. This can be used where a call
can be parked, and the called party can call several other numbers. When the desired party is found,
they can simply pick up the parked call by dialing the parking extension number.
The number used to park a call and the parking extensions are configured in features.conf.
features.conf
Formerly known as parking.conf , renamed features.conf as of 17th July 2004.
Configuration of Asterisk’s call parking.
parkext => 700 ; Which extension to dial to park
parkpos => 701720 ; Which extensions to park calls on
context => parkedcalls ; Which context parked calls are in, need to INCLUDE this in extensions.conf
parkingtime => 45 ; Number of seconds a call can be parked (the default is 45 seconds)
after park times out, the call will ring back to the original extension
Note: must restart * after making changes to features.conf, or reload res_features.so
In addition to the call parking options, you can configure the button mappings for blind and attended
transfers in this file. For example:
[featuremap]
69
blindxfer => #1 ; Blind transfer, default is #
disconnect => *0 ; Disconnect (for attended transfer)
atxfer => *2
blindxfer allows unattended or blind transfers:
While on a conversation with another party, you dial the blindxfer sequence. Asterisk says,
"Transfer", and then gives you a dial tone, while putting the other party on hold. You dial the
transferee’s number and the caller is put through to that number immediately. Your line drops. The
caller ID displayed to the person receiving the transferred call is exactly the same as the caller ID
presented to you.
atxfer allows attended or supervised transfers:
While on conversation with another party, you dial the atxfer key sequence. Asterisk says, "Transfer",
and then gives you a dial tone, while putting the other party on hold. You dial the transferee’s number
and talk with the transferee to introduce the call, then you can hang up and the other party is
connected with the transferee. In case the transferee does not want to answer the call, he/she simply
hangs up and you will be returned to your original conversation. Press the “Disconnect” key
sequence, set to *0 by default, to return yourself to the original caller.
Note: You MUST use the T and/or t options in the command Dial() in order to allow the
caller and/or the called to use any transfer feature
Route by caller ID:
Examples:
exten => 123/100,1,Answer()
exten => 123/100,2,Playback(ttweasels)
exten => 123/100,3,Voicemail(123)
exten => 123/100,4,Hangup()
This will match extension 123 and perform the following options ONLY if the calling user’s ID
number is 100. This can also be accomplished with pattern matching, as given below:
exten => 1234/_256NXXXXXX,1,Answer()
and so on...
This will only match 1234 if the calling user’s ID number begins with 256. This is very useful
because it prevents locals from dialing your tollfree number and charging you for the call.
70
You can even do this:
exten => s,1,Answer
exten => s/9184238080,2,Set(CALLERID(name)=EVIL BASTARD)
exten => s,2,Set(CALLERID(name)=Good Person)
exten => s,3,Dial(SIP/goodperson)
MeetMe Conferencing
To configure MeetMe conferencing, create conference rooms in meetme.conf file. The syntax is:
conf => conference_number [,pin] [,administrative_pin]
Example:
conf => 2222,1821,191871
;This room number 2222 prompts for a password on login 1821 and a password for administration
191871.
The MeetMe application is used in extensions.conf to call a conference:
MeetMe()
The syntax is:
MeetMe([confno][,[options][,pin]])
where confno is a conference number.
The options can be one of the following:
'm' The conference is in socalled monitor mode (only listen, no talking)
't' The conference is in talk mode (talk only, no listening)
'T' Turns on the talker detection. It sends information to the manager’s interface and MeetMe
list.
'i' Announce who is joining/leaving the conference.
'p' – The user can exit the conference by pressing the # key.
'X' – The user can exit the conference by entering a single valid extension
(${MEETME_EXIT_CONTEXT} ), if this variable is not set, uses an extension in the current
context.
'd' Dynamically adds a conference (Cannot set a PIN for the conference).
'D' Dynamically adds a conference (Can set a PIN for the conference).
'e' Selects first empty conference
71
'E' Selects first empty PINless conference
'v' The conference is in video mode
'r' If this option is selected, the conference conversation will be recorded in format
${MEETME_RECORDINGFORMAT} and saved as ${MEETME_RECORDINGFILE
'q' Disable the enter/leave sounds
'C' On entering, announce how many users are in the conference
'M' Musiconhold will be played when there is only one user in the conference
'x' Close conference when last marked user exits
'w' Wait until the marked user enters the conference
'b' Run an AGI script set in the ${MEETME_AGI_BACKGROUND} variable; the default script
is : confbackground.agi
Note: This works only with Zap channels in the same conference)
's' Enter menu (user and administrator) when *key is pressed
'a' Set admin mode
'A' Set marked mode
'P' Always ask for a PIN even if it is specified
If the PIN argument is passed, the caller must enter that PIN number to successfully enter the
conference.
Example
exten => 1234,1,Goto(conf,1)
exten => conf,1,Set(MEETME_RECORDINGFILE=/tmp/Tutorial${TIMESTAMP})
exten => conf,2,Meetme(1234|sr)
exten => conf,3,Hangup()
MeetMeCount()
MeetMe participant count plays back the number of users in the specified MeetMe conference. If var
is specified, playback will be skipped and the value will be returned in the variable. The syntax is:
MeetMeCount(confno[|var])
Examples
You can limit the number of users in a conference with something like this:
72
[globals]
CONFMAX => 10 ; max persons in conference
exten => 8081,1,Macro(stdmeetme,8081))
[macrostdmeetme]
; with limit to max number of persons in conference
exten => s,1,MeetMeCount(${MACRO_EXTEN}|count)
exten => s,2,Gotoif,$[${count} >= ${CONFMAX}]?103
exten => s,3,MeetMe(${MACRO_EXTEN})
exten => s,4,Goto(s|1)
exten => s,103,Background(conffull)
exten => s,104,Hangup
Enhanced Voicemail
Voicemail is used to leave a message if no one is answering your call. The configuration in Asterisk
is in /etc/asterisk and the file is voicemail.conf.
The format of the voicemail.conf file is:
[general]
setting=value
...
[zonemessages]
newzonename=country/city|options
...
[context_section]
extension_number =>
voicemail_password,user_name,user_email_address,user_pager_email_address,user_option(s)
...
[another_context_section]
extension_number =>
73
...
The voicemail.conf file contains one general section, one zonemessages section, and one or more

userdefined context sections. The general section holds global configuration information. The
zonemessages section defines time zones and timereporting formats. The third and final section is
where we create one or more groups of voicemail boxes, each containing the mailbox’s definitions.
Settings for the [general] section of voicemail.conf
This section contains configuration settings which will apply as a common policy across all users.
The general section must be defined and present in voicemail.conf. Configuration entries are coded
in setting=value format. The configuration settings available in the general section are as follows:
attach
Attach causes Asterisk to copy a voicemail message to an audio file, and send it to the user as an
attachment in an email voicemail notification message. The default is set to not do this. Attach takes
two values: yes or no.
delete
Deletes voicemails from the server after notification is sent. This option may be set only on a per
mailbox basis; it is intended for use with users who wish to receive their voicemail messages only by
email.
Note: This setting needs to be prefixed with a |. For example:
823 => 1234,office,office@demo.local,,attach=yes|delete=1
mailcmd
Supplies the full path and filename of the program Asterisk should use to send notification emails.
This option is useful if you want to override the default email program.
Examples:
mailcmd=/usr/sbin/sendmail v t f asteriskpbx@yourdomain.com ; use f to prevent
root@localhost.localdomain or similar
mailcmd=/usr/exim/bin/exim –t
Indicates how many seconds of silence to allow before ending the recording. The default value is 0,
which indicates that the silence detector is disabled, and that the waiting time is infinite. Maxsilence
74
takes a value of 0 or a positive integer value, which is the number of seconds of silence to wait before
disconnecting.
externnotify
Supplies the full path and filename of an external program to be executed when a voicemail is left or
delivered, or when a mailbox is checked.
externpass
Supplies the full path and filename of an external program to be executed whenever a voicemail
password is changed.
silencethreshold
When using the maxsilence setting, it is sometimes necessary to adjust the silence detection threshold
in order to eliminate false triggering on background noise. Silencethreshold allows an administrator
to do this. The default silencethreshold value is 128. Higher numbers raise the threshold so that more
background noise is needed to cause the silence detector to reset. Some experimentation will be
necessary in order to find the best result.
serveremail
This setting identifies the source of a voicemail notification message. The value is a string which can
be encoded in one of two ways. If the string is of the form someone@host.com, then the string will be
used as the source address for all voicemail notification emails. If the string is of the form someone,
then the host name of the machine running Asterisk will be postappended to the string after the
insertion of a '@'.
maxmsg
This limits the number of messages in a voicemail folder. The maximum value is 9999 (hardcoded)
and the default is 100. When a mailbox has more than this number of messages in it, new messages
cannot be recorded, and vmmailboxfull is played to the caller. “No more messages possible” is also
logged. This setting was introduced in v. 1.2. In previous versions it was hardcoded to 100.
minmessage
This setting eliminates messages which are shorter than a given amount of time in seconds. The
default value for this setting is 0, which means that no minimum time limit will be enforced.
format
The format setting selects audio file format(s) to use when storing voicemail messages. The value is a
string defining the audio format(s) of the message file. The default format string is wav49|gsm|wav,
meaning that Asterisk will save the voicemail message in all three supported formats. When e
mailing the attachment, however, it will only send the first of the formats defined here. When playing
75
back (as with all file playback) Asterisk will attempt to use the optimum format based on the codec
used for the current channel, in order to provide the best sound quality, and to reduce transcoding
processing time.
• wav49: In this format, the file size will be small, the quality good, and it is a wise choice for
sending voicemail messages in an email. The file will have a .wav extension, which all
Windows users should have no problems with, and users on other platforms should also be
able to play these sound files easily.
• gsm: Voicemail saved in this format will have the same approximate file size and audio
quality as wav49. It may, however, be illsupported by client operating systems if sent to
users in an email.
• wav: This is an uncompressed sound format with a .wav extension, so the file size is very
large. Although the sound quality will be great, you would probably not want to email it, and
you must have adequate disk space.
• g723sf: The sample voicemail.conf file has this option commented out. If you try to activate
it, you will find that it does not work.
maxgreet
This setting allows the administrator to limit the userrecordable voicemail greeting’s length. Use this
option on systems with a large number of users and limited disk space. The value is an integer
defining the greeting message’s maximum length in seconds. The default value is 0, which means that
the greeting message can be of any length. This setting will control the lengths of an unavailable
greeting, a busy greeting, and user name messages.
skipms
This setting defines an interval (in milliseconds) to use to skip forward or reverse while a voicemail
message is being played. The value entered here should be a positive integer. The default value for
this setting is 3000 (3 seconds).
maxlogins
This setting defines the number of retries a user has to enter voicemail passwords before Asterisk will
disconnect the user. The value should be a positive integer. The default value for this setting is 3.
pbxskip
This setting changes the Subject: line in a voicemail notification message. This setting takes a yes or
no value. The default value is no. When set to yes, the Subject: line will read, “Subject: New message
M in mailbox B". When set to no, the Subject: line will read, "Subject: [PBX]: New message M in
mailbox B".
fromstring
This setting allows the administrator to override a portion of the From: line in the voicemail
76
notification message. By default, Asterisk sends the string "From: Asterisk PBX <who>. The
"Asterisk PBX" portion of the From: line can be overridden by specifying your own string as the
value for this setting. One might use this to customize the voicemail notification message and/or
remove the reference to "Asterisk PBX".
emailsubject
This setting completely overrides the Subject: line in the voicemail notification message, and
substitutes its own text in its place. The value passed is a string containing the text to send in place of
the Subject: line. A list of macrolike expansion tokens is given below.
Note: \t and \n do not expand in this field.
Example:
emailsubject=New voicemail in mailbox ${VM_MAILBOX} from ${VM_CALLERID}
emailbody
This setting overrides the normal message text seen in the body of a voicemail notification message.
It also supports variable substitution, which can be used to make the message more meaningful. The
format looks like this: emailbody=\n\tHi ${VM_NAME},\n\n\tYou have a ${VM_DUR} long new
voicemail message (number ${VM_MSGNUM}) in mailbox ${VM_MAILBOX}\nfrom
${VM_CIDNAME} (${VM_CIDNUM}), on ${VM_DATE}\nso you might want to check it when
you get a chance.\n\n
Note that this is a single line without quotes. Use \n \t for formatting.
exitcontext
This is an optional context to drop the user into after he/she has pressed * or 0 to exit voicemail. If
not set, pressing * or 0 will return the caller to the last context they were in before being sent to
voicemail (assuming that the context has an 'a' or 'o' extension).
nextaftercmd
If set to "yes," the system will automatically play the next message after deleting a voicemail
message.
Variables to use in emailsubject and emailbody:
VM_NAME
VM_DUR
VM_MSGNUM
VM_MAILBOX
VM_CIDNUM
77
VM_CIDNAME
VM_CALLERID
VM_DATE
An example of some settings in the general section
[general]
; Send voice file attachments in email notifications
attach=yes
; Use wav format for all voicemail messages
format=wav
; Limit the maximum message length to 180 seconds
maxmessage=180
; Limit the minimum message length to 3 seconds
minmessage=3
; Announce caller's number before playing message
saycid=yes
; Limit the login retiries to 3 before disconnecting the caller
maxlogins=3
Voicemail Zones
Voicemail users may be located in different geographical locations. Asterisk provides a way to
configure the time zone and the way the time is announced for different callers. Each unique
combination is known as a voicemail zone. Configure your voicemail zones in the [zonemessages]
section of voicemail.conf. Assign your voicemail boxes to use the settings for one of these zones
later.
Each voicemail zone definition consists of a line with the following syntax:
zonename=timezone | time_format
The zonename is an arbitrary name used to identify the zone. The timezone argument is the name of a
system time zone, as found in /usr/share/zoneinfo. The time_format argument specifies how the
voicemail system should announce the times. The time_format argument is composed of the following
elements:
Option Description
78
'filename 'filename of a soundfile (single ticks around the filename required)
${VAR} variable substitution
A or a Day of the week (Saturday, Sunday, and so on)
B or b or h The month’s name (January, February, and so on)
d or e The numeric day of the month (first, second, ..., thirtyfirst)
Y Year
I or i Hour, 12 hour clock
H Hour, 24 hour clock (single digit hours preceded by "oh")
K Hour, 24 hour clock (single digit hours NOT preceded by "oh")
M Minute
P or p AM or PM
Q "today","yesterday" or ABdY (*note: not standard strftime value)
q "" (for today), "yesterday", weekday, or ABdY (*note: not standard
strftime value)
R 24 hour time, including minute
Example for the zonemessages section
[zonemessages]
; Set a 12hour timereporting format for the Pacific time zone
sandiego=America/Tijuana|'vmreceived' Q 'digits/at' IMP
; Set a 24hour timereporting format for the Pacific time zone
sandiego24=America/Tijuana|'vmreceived' Q 'digits/at' R
Settings for the [CONTEXTS] sections of voicemail.conf
The final part of the voicemail.conf configuration file contains one or more context sections where
voice mailboxes are defined and configured.
Multiple voicemail boxes may be defined in a context section. Its format is:
[context_section]
extension_number =>
...
• The voicemail_password field contains the numeric password for this voicemail box entry.
The voicemail system will compare the password entered by the user against this value.
• The user_name is an alpha field which is usually set to the first and last name of the user of
this voicemail box.
• The user_email_address can be set to the email address of the user so that when a voicemail
79
message is left by a caller, an email notification will be sent to the address defined in this
field.
• The pager_email_address can be set to the email address of a pager so that when a
voicemail message is left by a caller, a page will be sent to the pager email address defined in
this field.
• The user_option(s) field can be used to override default settings defined in the general
section, or set a specific time zone for this user. Specifically, there are nine setting=value
pairs which can be specified in the user_option(s) field. There can be multiple setting=value
pairs defined in the user_option(s) field. Each setting=value pair after the first must be
delimited with a vertical bar (|). The nine settings which may be used are: attach,
serveremail, tz, saycid, review, operator, callback, dialout and exitcontext. With the
exception of tz, the functions of the eight remaining settings are exactly the same as those
defined in the [general] section. The tz setting is used to override the default time zone, and it
must be set to a custom time zone defined in the [zonemessages] section.
An example context section:
; All voicemail boxes for this system will be in the default context
[default]
; Define a user on extension 123 with password 2048 named Joe User with an email address for
voicemail notification, no pager, timezone set to sandiego,
; and allow attachment of the voice mail message to the email notification.
123=>2048, Joe User, juser@somewhere.net,,tz=sandiego|attach=yes
; Define a user on extension 456 with password 4096 named Jane User with no email address for
voicemail notification, no pager, and no options
456=>4096,Jane User,,,
Note that there is no whitespace left between fields and options.
VoiceMailMain( ) is used to check or listen to voicemails.
VoiceMailMain( )
VoiceMailMain([[s]mailbox]'@context'>
Enters the main voicemail system to check voicemail. The mailbox can be passed as the option,
which will stop the voicemail system from prompting the user for the mailbox.
If the mailbox is preceded by "s", then the password check will be skipped. If a context is specified,
only logins in that particular context are considered.
80
Menu
— 1 Read voicemail messages
— 3 Advanced options (with option to reply; introduced in Asterisk’s CVS Head 28 April 2004
th
with 'enhanced voicemail')
— 1 Reply
— 2 Call back(1)
— 3 Envelope
— 4 Outgoing call(1)
— 5 Send Message (only available if sendvoicemail=yes in voicemail.conf)
— 4 Play previous message
— 5 Repeat current message
— 6 Play next message
— 7 Delete current message
— 8 Forward message to another mailbox
— 1 Use Voicemailnumber (only available if usedirectory=yes in voicemail.conf)
— 2 Use Voicemail Directory (only available if usedirectory=yes in voicemail.conf)
— 9 Save message in a folder
— 0 Save in new Messages
— 1 Save in old Messages
— 2 Save in Work Messages
— 3 Save in Family Messages
— 4 Save in Friends Messages
— * Help; during msg playback: Rewind
— # Exit; during msg playback: Skip forward
— 2 Change folders
— 0 Switch to new Messages
— 1 Switch to old Messages
— 2 Switch to Work Messages
— 3 Switch to Family Messages
— 4 Switch to Friends Messages
— 3 Advanced Options
— 5 Send Message (only available if sendvoicemail=yes in voicemail.conf)
— 1 Use Voicemailnumber (only available if usedirectory=yes in voicemail.conf)
— 2 Use Voicemail Directory (only available if usedirectory=yes in voicemail.conf)
— 0 Mailbox options
— 1 Record your unavailable message
— 2 Record your busy message
— 3 Record your name
81
— 4 Record your temporary message (new in Asterisk v1.2)
— 5 Change your password
— * Return to the main menu
— * Help
— # Exit
— After recording a message (incoming message, busy/unavailable greeting, or name)
• 1 Accept
• 2 Review
• 3 Rerecord
• 0 Reach operator(1) (not available when recording greetings/name)
(1) Prompts for these are only played if these options are enabled in voicemail.conf.
While listening to a recorded voicemail message: Press # to fastforward, or * to rewind by skipms
increments. Skipms defaults to 3000 ms and is configurable in voicemail.conf. Note that the # and *
keys only work when the message is in the process of being played back
Voicemail Configuration in extensions.conf
voiceMail() is used in extensions.conf to call voicemail box
VoiceMail( )
VoiceMail([flags]boxnumber[@context][&boxnumber2[@context]][&boxnumber3])
or
VoiceMail(boxnumber[@context][&boxnumber2[@context]][&boxnumber3],[flags])
Records the channel, saving an audio file in a given voicemail boxnumber, which must be configured
in voicemail.conf. The boxnumber may be preceded by one or more flags or they may be specified as
the second argument:
• s: The letter s, if present, causes the instructions ("Please leave your message after the tone.
When done, hang up, or press the pound key.") to be skipped.
• u: The letter u, if present, causes the unavailable message to be played. By default, the
message says, "The person at extension ... 1234 ... is unavailable," but the mailbox owner may
record a customized unavailable message with the VoicemailMain command.
• b: The letter b, if present, causes the busy message to be played. By default, the message says,
"The person at extension ... 1234 ... is busy."
− g(#): (Only when specifying the flags as the second argument) Adjust the gain of the recording.
The # is an integer representing the amount of gain in decibels.
Do not specify both u and b flags together. You may, however, combine them with s, giving six
82
possibilities:
• s: Play nothing.
• (no flags): Play instructions.
• su: Play unavailable message.
• u: Play unavailable message, then instructions.
• sb: Play busy message.
• b: Play busy message, then instructions.
Prior to starting to record, the beep.gsm file will also be played in all cases.
This application will set the following channel variable upon completion:
VMSTATUS This indicates the status of the execution of the voicemail application. The possible
values are:
SUCCESS | USEREXIT | FAILED
The voicemail messages will be saved into the inbox directory for that voicemail boxnumber:
• /var/spool/asterisk/voicemail/context/boxnumber/INBOX/
If the caller presses 0 (zero) during the announcement, and the option 'operator=yes' is set in
voicemail.conf either in the general section or for this mailbox, then he or she will be moved to
extension 'o' (as in "Out") in the current voicemail context. This can be used as an escape for a
receptionist. If you do not want it, just configure extension 'o' to go back to voicemail, or configure
operator=no, otherwise the call will hang up due to the fact that extension 'o' does not exist.
Also, during the prompt, if the caller presses:
'*' the call jumps to extension 'a' in the current voicemail context.
'#' the greeting and/or instructions are stopped and recording starts immediately.
Examples
Voicemail(1)
Voicemail(b1234@default)
Voicemail(b1234&1704@home)
Voicemail(su${EXTEN})
Configure sip.conf, Zapata.conf or iax.conf to enable voicemail by defining the mailbox

parameter:
mailbox=1234
or
mailbox=1234@context
Use the 1234@context notation if your mailbox is not located in the default context.
83
Introduction To Asterisk Automatic Call Delivery (ACD)
Asterisk Automatic Call Delivery (ACD) is a feature used to route calls in a call center environment
to the appropriate agents, based on factors such as time available, skillsset, and priority levels.
• ACD systems place calls into a queue, where they are typically handled in the order received.
• ACD systems may handle routing of inbound or outbound calls, or in some cases a
combination of both.
To configure ACD we need to configure queues.conf, agent.conf, extensions.conf and
sip.conf/iax.conf/zapata.conf
queues.conf
ACD distributes incoming calls in order of arrival to the first available agent. The system answers
each call immediately and, if necessary, holds it in a queue until it can be directed to the next
available call center agent. Balancing the workload among agents ensures that each caller receives
prompt and professional service.
Asterisk supports multiple call queues. They are defined in the queues.conf file and then referenced
as arguments to the queue application in extensions.conf. Agents are defined in the agents.conf file.
The [general] section of queues.conf contains settings that will apply to all queues. Currently, the only
parameter that is supported is persistentmembers. If this parameter is set to Yes, a member that is added
to the system via the AddQueueMember( ) application will be stored in the AstDB, and therefore
retained during restarting.
Periodic announce
Periodic announcements are available in queues using the new periodicannounce and periodic
announcefrequency options. This allows a message like "Thank you for holding, your call is
important to us." to be played at regular intervals while a caller is in the queue. e.g:
periodicannounce = thankyoumessage
periodicannouncefrequency = 60 ; every 60 seconds
weight
The weight parameter assigns a rank to the queue. If calls are waiting in multiple queues, the queues
with the highest weight values will be presented to agents first. When designing your queues,
remember that this strategy can prevent a call in a lowerweighted queue from ever being answered.
Always ensure that calls in lowerweighted queues eventually get promoted to higherweighted
queues so that they don't remain on hold forever.
leavewhenempty
If you wish to remove callers from the queue if there are no agents present, add the following line to
84
your queues.conf file:
leavewhenempty = yes
wrapuptime
You can configure this parameter to allow agents a few seconds break after completing a call before
the queue presents them with another one.
wrapuptime=15
memberdelay
This parameter defines whether a delay will be inserted between the time when the queue identifies a
free agent and the time when the call is connected to that agent.
memberdelay = 5
timeoutrestart
If timeoutrestart is set to Yes, then the timeout for an agent to answer is reset if a BUSY or
CONGESTION is received. This can be useful if agents are able to cancel a call with reject or a
similar.
Strategy
One of several strategies is used to distribute calls among the members handling a queue:
• ringall: Ring all available channels until one answers (default)
• roundrobin: Take turns ringing each available interface (depreciated in 1.4, use rrmemory)
• leastrecent: Ring interface which was least recently called by this queue
• fewestcalls: Ring the one with fewest completed calls from this queue
• random: Ring random interface
• rrmemory: Round robin with memory, remember where we left off last ring pass
;strategy=rrmemory
Timeout
Timeout in seconds when calling an agent:
;timeout=15
context=<context>
This allows the caller to exit with a key for further action:
Press "1" to leave a message
announce
85
When a call is presented to a member of the queue, the prompt specified by announce will be
played to that agent before the caller is connected. This can be useful for agents who are
logged into more than one queue. You can specify either the full path to the file, or a path
relative to /var/lib/asterisk/sounds/.
member => member_name
Members of a queue can either be channel types or agents. Any agents you list here must be defined
in the agents.conf file.
Member => Agent/@1 ; a group
member => Agent/501 ; a single agent
Penalties
Queue members can be defined as having a penalty e.g.
member => SIP/200,1
member => SIP/201,2
member => SIP/202,3
member => SIP/203,2
If the strategy is defined as 'ringall', then only those available members with the lowest priorities will
ring. In the example above, if 200 is not busy, then only 200 will ring. If 200 is busy, then only 201
and 203 will ring. If 200, 201 and 203 are busy, then 202 will ring.
Note: If extension 200 does not pick up it will not automatically go to extension 201. It will keep
ringing 200 until they pick up. It will only go to the next extension if the current extension is either
busy or unavailable.
monitorformat
This parameter accepts three possible values: wav, gsm, and wav49. By enabling this option, you are
instructing Asterisk that you wish to record all completed calls in the queue in the specified format. If
this option is not specified, no calls will be recorded.
monitorjoin
The Monitor( ) application in Asterisk normally records either end of the conversation in a separate
file. Setting monitorjoin to yes instructs Asterisk to merge the files at the end of the call.
Extensions.conf applications
Queue()
This application allows you to queue a phone call into a call queue. If somebody calls you, but the
line is busy because you already responding to another call, then the new caller will be put in the
86
queue. The caller will hear music on hold until you are ready to receive the call.
Queue(queuename[|options[|URL][|announceoverride][|timeout]])
List with the possible options
queuename This is the name of the context in queues.conf, where you would like the call to be
queued.
options You can use one or more of the following parameters:
t Allow the called user to transfer the calling one to another number
T Allow the calling user to transfer the call
d Dataquality (modem) call (minimum delay)
h Allow the called person to hang up the line by pressing the asterisk key(*)
H Allow the calling person to hang up the line by pressing the asterisk key(*)
n Forbid the retries if the timeout expires. It will exit and move onto the next extension instead.
r Ring instead of playing music on hold
URL A URL will be sent to the called user if the channel supports this.
announceoverride You can set a sound file to replace the one currently set in the queues.conf file.
timeout The maximum time, in seconds, the call will wait in the queue. When this time period
expires, the next extension will be executed by priority. The default timeout is set to 300 seconds.
agents.conf
This file allows you to create and manage agents for your call center. If you are using the Queue( )
application, you may want to configure agents for the queue. The agents.conf file is used to configure
the AGENT channel driver.
The [general] section in agents.conf currently contains only one parameter the persistentagents. This
option defines whether the agent’s callback logins have to be stored in Asterisk’s database or not. If
this option is set to Yes, the logins will be stored. If it is set to No, they will not be stored. The
persistent logins will be reloaded after Asterisk restarts. The option is set to Yes by default.
The following parameters, which are specified in the [agents] section, are used to define agents and the
way the system interacts with them. These settings apply to all agents, unless otherwise specified in
the individual agent definitions:
autologoff
This option specifies for how long the phone has to ring with no answer before an agent is logged off.
Set the maximum time period in seconds. The default setting is 15 seconds.
ackall
87
If this option is set to Yes and the agent is loggingin with the AgentCallbackLogin application, then
an acknowledgement will be required by pressing the pound key(#).This option is set to No by default
wrapuptime
This option refers to the time after the conversation is over. Set the minimum period of time required
to expire before a new call is received. The time is in milliseconds, and its default is set to 5000.
musiconhold
Define the default music on hold class for the agents. By default, the class is default. The music on
hold classes can be defined in the musiconhold.conf file and in agents.conf. Simply call the name of
the class.
updatecdr
This option accepts the arguments yes and no. It is used to define whether the source channel in the
CDRs should be set to agent/agent_id in order to determine which agent generated the calls.
Group
This option allows you to group your agents into separate groups for easy management. No group is
set by default. Create a group: group=groupnumber. Example: group=1.
To assign an agent to a group, add it after the key phrase group=groupnumber:
group=1
agent => 8888,8888,user1
.....
custom_beep
This option accepts a filename as its argument. It can be used to define a custom notification tone to
signal to an alwaysconnected agent that there is an incoming call.
recordagentcalls
This option accepts the arguments yes and no. It defines whether or not agents’ calls should be
recorded.
recordformat
This option defines the format to record files in. The argument should be specified either in wav, gsm,
or wav49. The default recording format is wav.
savecallsin
This option accepts a filesystem path as its argument. It allows you to override the default path of
/var/spool/asterisk/monitor/ with one of your own choosing.
88
urlprefix
This option accepts a string as its argument. The string can be formed as a URL and is appended to
the start of the text to be added to the name of the recording.
The creation of an agent
The form for creating an agent is given below:
agent => agentnumber,agentpassword,name
agentnumber is the agent’s number.
agentpassword is the agent’s password, which will be asked for authentication purposes in the
Dialplan applications (AgentLogin or AgentCallbackLogin).
name is the agent’s real name of your own choice.
Example
[general]
persistentagents=yes
[agents]
autologoff=15
ackcall=no
wrapuptime=5000
musiconhold => default
recordagentcalls=yes
recordformat=gsm
group=1
agent => 101,101,user1
group=2
agent => 8889,8889,operator
agent => 8888,8888,ivan
89
group=3
agent => 8887,8887,operator3
Extensions.conf Applications
AgentLogin()
AgentLogin([AgentNo][,options])
This application logs the current caller into the call queue system as a call agent (optionally identified
by AgentNo). While logged in, the agent can receive calls and will hear a beep on the line when a new
call comes in. The agent can hang up the call by pressing the asterisk (*) key.
The options argument may contain the letter s, which causes the login to be silent.
; silently log in as agent number 42, as defined in agents.conf
exten => 123,1,AgentLogin(42,s)
AgentCallbackLogin()
AgentCallbackLogin([AgentNo|][exten]@context)
AgentCallbackLogin([AgentNo|][Options|][exten]@context)
This application asks the agent to loginto the system with callback. The agent's callback extension
is called with the specified context. The context must be specified; the system will, however, prompt
for the Agent number, password, and extension if they have not been supplied.
90
Connecting to PSTN
Overview
Asterisk is fully capable of converting Voice over Internet Protocol (VoIP) to TDM. In order to
connect Asterisk to PSTN we need to install some hardware and additional software drivers.
Asterisk’s hardware is divided into two main categories:
• Analog connections (connecting Asterisk to an analog PSTN line)
• Digital connections (connecting Asterisk to digital PSTN lines)
The following table outlines some of the hardware and software required to connect Asterisk with
PSTN.
Hardware and Software Requirements
Application Hardware Software Driver
Analog Connections Digium FXO and FXS cards Zapata
Digital T1/E1 Cards Digium T1/E1 Cards Zapata
Digital T1/E1 Cards Sangoma T1/E1 Cards Zapata
VoIP Connections Network Interface Card ztdummy
For Applications listed No Additional Driver libpri
above
Table 1
The ztdummy driver acts as a timing source when a POTS/T1/E1/J1 card is not used. Applications
such as conferencing, and calls transferred within the Asterisk server require this timing source.
The libpri software is a required part of the Zapata modules.
Analog Connections
FXO and FXS cards are used to connect Asterisk with PSTN using analog lines.
FXO and FXS Channels
The difference between an FXO channel and an FXS channel is which end of the connection provides
the dial tone. An FXO port does not generate a dial tone; it accepts one. A common example is the
dial tone provided by a phone company. An FXS port provides both the dial tone, and the ringing
voltage required to alert the station user to an inbound call. Both interfaces provide bidirectional
communication (i.e., communication that is transmitted and received in both directions
simultaneously).
If your Asterisk server has a compatible FXO port, you can plug a telephone line from your telephone
company (or "telco") into this port. Asterisk can then use the telco line to place and receive telephone
calls. If your Asterisk server has a compatible FXS port, you may plug an analog telephone into your
91
Asterisk server, so that Asterisk may call the phone and you may place calls.
Ports are defined in the configuration by the signaling they use, as opposed to their physical type of
port. A physical FXO port will be defined in configuration with FXS signaling, and an FXS port will
be defined with FXO signaling. This can be confusing until you understand that FX_ cards are named
according to what is connected to them, not according to what they are. An FXS card, therefore, is a
card that connects to a station. In order to do its job, an FXS card must behave like a Central Office
(CO) and use FXO signaling. Similarly, an FXO card connects to a CO, which means that it will need
to behave like a station and use FXS signaling.
We will use the Digium TDM400P card as an example. Digium’s analog cards are modular and can
support FXO and FXS ports in any configuration. Your fourport card can have one, two, or three
FXO cards with one, two, or three FXS ports.
Determining the FXO and FXS Ports on Your TDM400P
Below figure contains a picture of a TDM400P with an FXS module and an FXO module. You can't
see the colors, but module 1 is a green FXS module and module 2 is an orange/red FXO module. In
the bottomright corner of the picture is the Molex connector, where power is supplied from
computer's power supply.
A TDM400P with an FXS module (1 across) and an FXO module (2 across)
FXS FXO
Molex
Connector
Figure 1
92
Configuring an FXO Channel
We'll start by configuring an FXO channel. First we'll configure the Zaptel hardware, and then the
Zapata hardware. We'll set up a very basic dialplan, and demonstrate how to test the channel.
Zaptel Hardware Configuration
The zaptel.conf file located in /etc/ is used to configure your hardware. The following minimal
configuration defines an FXO port with FXS signaling:
fxsks=2
loadzone=us
defaultzone=us
In the first line, in addition to indicating whether we are using FXO or FXS signaling, we specify one
of the following protocols for channel 2:
• Loop start (ls)
• Ground start (gs)
• Kewlstart (ks)
Loopstart signalling is used by virtually all analog phone lines. It allows a phone to indicate on
hook/off hook, and the switch to indicate ring/no ring.
Kewlstart is based on loopstart, but extends the protocol by allowing the switch to drop a battery on
the phone line to indicate to the phone that the caller at the other end has disconnected the call. Most
real phone switches, and almost no PBXs (except Asterisk) support this feature. It is generally
required to receive a hangup notification.
Groundstart signalling is sometimes used by PBXs.
loadzone configures the set of indications (as configured in zonedata.c) to use for the channel. The
zonedata.c file contains information about all the various sounds that a phone system makes in a
particular country: dial tone, ringing cycles, busy tone, and so on. When you apply a loaded tone zone
to a Zap channel, that channel will mimic the indications for the specified country. Different
indication sets can be configured for different channels. The defaultzone is used if no zone is specified
for a channel.
You can load the drivers for the card after configuring zaptel.conf. modprobe is used to load modules
for use by the Linux kernel. To load the wctdm driver, for example, run:
# modprobe wctdm
If the drivers load without any output, they have been loaded successfully. Verify that the hardware
and ports were loaded and configured correctly by using the ztcfg program:
# /sbin/ztcfg vv
93
The configured channels and the signaling method being used will be displayed. A TDM400P with
one FXO module, for example, has the following output:
Zaptel Configuration
======================
Channel map:
Channel 02: FXS Kewlstart (Default) (Slaves: 02)
1 channels configured.
If you receive the following error, you have configured the channel for the wrong signaling method:
ZT_CHANCONFIG failed on channel 2: Invalid argument (22)
Did you forget that FXS interfaces are configured with FXO signalling
and that FXO interfaces use FXS signalling?
To unload drivers from memory, use the rmmod (remove module) command:
# rmmod wctdm
The zttool program is a diagnostic tool used to determine the state of your hardware. After running it,
you will be presented with a menu of all installed hardware. You can then select the hardware and
view its current state. A state of "OK" indicates that the hardware has been successfully loaded:
Alarms Span
OK Wildcard TDM400P REV E/F Board 1
Zapata Hardware Configuration
Asterisk uses the zapata.conf file to determine the settings and configuration for telephony hardware
installed in the system. The zapata.conf file also controls the various features and functionality
associated with the hardware channels, such as Caller ID, call waiting, echo cancellation, and a range
of other options.
When you configure zaptel.conf and load the modules, Asterisk is not aware of anything you have
configured. The hardware doesn't have to be used by Asterisk; it can be used by another piece of
software that interfaces with the Zaptel modules. Inform Asterisk about the hardware and control its
associated features via zapata.conf:
[trunkgroups]
; define any trunk groups
[channels]
; hardware channels

94
; default
usecallerid=yes
hidecallerid=no
callwaiting=no
threewaycalling=yes
transfer=yes
echocancel=yes
echotraining=yes
; define channels
context=incoming ; Incoming calls go to [incoming] in extensions.conf
signalling=fxs_ks ; Use FXS signalling for an FXO channel
channel => 2 ; PSTN attached to port 2
The [trunkgroups] section is for NFAS and GR303 connections
The [channels] section determines the signaling method for hardware channels and their options. Once
an option is defined, it is inherited down through the rest of the file. A channel is defined using channel
=>, and each channel’s definition inherits all the options defined above that line. In order to configure
different options for different channels, remember that the options should be configured before the
channel => definition.
The default setting does not enable threeway calling. We’ve enabled Caller ID with usecallerid=yes
and specified that it will not be hidden for outgoing calls with hidecallerid=no. Call waiting is
deactivated on an FXO line with callwaiting=no. Enabling threeway calling with threewaycalling=yes
allows an active call to be placed on hold with a hook switch flash to suspend the current call. You
may then dial a third party and join them to the conversation with another hook switch.
Allowing call transfer with a hook switch is accomplished by configuring Transfer=yes; it requires
that threeway calling be enabled. The Asterisk echo canceller is used to remove the echo that can be
created on analog lines. Enable the echo canceller with echocancel=yes. The echo canceller in
Asterisk requires some time to “learn” the echo, but you can speed this up by enabling echo training
(echotraining=yes). This tells Asterisk to send a tone down the line at the start of a call to measure the
echo, and therefore “learn” it more quickly.
When a call comes in on an FXO interface, the action required to be performed is configured inside a
block of instructions called a context. Incoming calls on the FXO interface are directed to the incoming
context with context=incoming. The instructions to perform inside the context are defined within
extensions.conf.
Finally, since an FXO channel uses FXS signaling, we define it as such with signalling=fxs_ks.
Dial plan Configuration
The following minimal dial plan uses the Echo( ) application to verify that bidirectional
communications for the channel are working:
[incoming]
95
; incoming calls from the FXO port are directed to this context
from zapata.conf
exten => s,2,Echo( )
The Echo( ) application will relay back whatever you say.
Configuring an FXS Channel
Configuring an FXS channel is similar to that of an FXO channel.
Zaptel Hardware Configuration
The following is a minimal configuration for an FXS channel on a TDM400P. The configuration is
identical to the FXO channel configuration, with the addition of fxoks=1.
Remember that the opposite type of signaling is used for FXO and FXS channels, so we will be
configuring FXO signaling for our FXS channel. In the example given below, we are configuring
channel 1 to use FXO signaling, with the kewlstart signaling protocol:
fxoks=1
fxsks=2
loadzone=us
defaultzone=us
After loading the drivers for your hardware, verify their state by using /sbin/ztcfg vv:
Zaptel Configuration
======================
Channel map:
Channel 01: FXO Kewlstart (Default) (Slaves: 01)
Channel 02: FXS Kewlstart (Default) (Slaves: 02)
2 channels configured.
Zapata Hardware Configuration
The following configuration is identical to that for the FXO channel, with the addition of a section for
our FXS port and of the line immediate=no. The context for our FXS port is internal, the signaling is
fxoks (kewlstart), and the channel number is set to 1.
FXS channels can be configured to perform one of two different actions when a phone is taken off the
hook. The most common (and often expected) option is for Asterisk to produce a dial tone and wait
for the user’s input. This action is configured with immediate=no. The alternative action is for Asterisk
96
to automatically perform a set of instructions configured in the dialplan instead of producing a dial
tone, indicated by configuring immediate=yes.[*]

[*]
Also referred to as the BatPhone method, and more formally known as an Automatic Ringdown or
Private Line Automatic Ringdown (PLAR) circuit. This method is commonly used at rental car
counters and airports.
The following is the new zapata.conf:
[trunkgroups]
; define any trunk groups
[channels]
; hardware channels
; default
usecallerid=yes
hidecallerid=no
callwaiting=no
threewaycalling=yes
transfer=yes
echocancel=yes
echotraining=yes
immediate=no
; define channels
context=internal ; Uses the [internal] context in extensions.conf
signalling=fxo_ks ; Use FXO signalling for an FXS channel

channel => 1 ; Telephone attached to port 1
context=incoming ; Incoming calls go to [incoming] in extensions.conf
signalling=fxs_ks ; Use FXS signalling for an FXO channel
channel => 2 ; PSTN attached to port 2
Dial plan Configuration
In order to test our newly created Zap extension, we need to create a basic dial plan. The following
dial plan contains a context called internal. This is the same context name that we configured in
zapata.conf for channel 1. When we configure context=internal in zapata.conf, we are telling Asterisk
where to look for instructions when a user presses digits on a telephone. In this case, the only
extension number that will work is 611. When you dial 611 on your telephone, Asterisk will execute
the Echo( ) application so that when you talk into the phone whatever you say will be played back to
97
you, thereby verifying bidirectional voice.
The dial plan looks like this:
[internal]
exten => 611,2,Echo( )
Digital Connections
T1/E1 cards are used to connect Asterisk to PSTN using digital lines. We will use Digium’s T1xxxx
and TExxxx cards in our examples.
If you are doing a backtoback configuration, or connecting the card to another PBX or channel bank, then you need a
crossT1/E1 cable with the following pinouts:
1 <> 4
2 <> 5
4 <> 1
5 <> 2
Configuring Digium Digital Cards
For digital connections, we need to configure the span parameter in Zaptel.conf and switchtype and
signaling parameter in Zapata.cong. The span’s syntax is:
Span = (spannum),(timing),(LBO),(framing),(coding)
spannum = Number of the span. This begins at 1, and goes up one integer at a time. You may NOT
have two spans with the same span number.
timing = How to synchronize the timing devices.
0: to not use this span as a sync source; send timing synchronization to other end.
1: to use as primary sync source.
2: to set as secondary and so forth.
If Asterisk is connected directly to the telco, use '1' to accept their timing. If you have multiple spans,
set them as 2, 3, 4, etc.
Note: You cannot use the number '1' more then once, for other spans’ use other numbers
Line Build Out (LBO) = Cable’s length between Zap card and SmartJack/telcoprovided modem. It
98
should almost always be set to 0 unless you have a long cable. This distance does NOT include the
copper in the street to the CO/exchange.
0: 0 dB (CSU) / 0 – 133 feet (DSX1)
1: 133 – 266 feet (DSX1)
2: 266 – 399 feet (DSX1)
3: 399 – 533 feet (DSX1)
4: 533 – 655 feet (DSX1)
5: 7.5 dB (CSU)
6: 15 dB (CSU)
7: 22.5 dB (CSU)
Framing = How to communicate with the hardware at the other end of the line.
For T1: Framing is one of d4 or esf.
For E1: Framing is one of cas or ccs.
Coding = Another parameter of communication with the other end of the line’s hardware.
For T1: coding is one of ami or b8zs.
For E1: coding is one of ami or hdb3 (E1 may also need crc4).
Examples:
span=1,1,0,esf,b8zs
This is the FIRST digital Zaptel span on the system, has PRIMARY priority to receive timing
FROM the other end of the link, the cable to the SmartJack/modem is less than 133 feet in length,
this span uses ESF framing and B8ZS line encoding. A fairly typical T1 span definition.
span=2,2,0,ccs,hdb3,crc4
This is the SECOND digital Zaptel span on the system, has SECONDARY priority to receive
timing FROM the other end of the link, the cable to the SmartJack/modem is less than 133 feet in
length, this span uses CCS framing and HDB3 line encoding, CRC4 error checking is also
enabled. This is a fairly typical second E1 span definition.
Configuration for T100P using a PRI
In /etc/zaptel.conf:
span=1,1,0,esf,b8zs
bchan=123
dchan=24
In /etc/asterisk/zapata.conf:
99
switchtype=national
context=blah
signalling=pri_cpe
group=1
channel => 123
Configuration for T100P using a channel bank
When using a channel bank, define the FXO/FXS channels instead of B and D channels. Now it is
setup just like the FXO/FXS cards. This is for an all FXS channel bank. If you have FXO, change the
signaling. If you have an FXS and FXO channel bank, split the channels according to how the
channel bank is set up.
In /etc/zaptel.conf:
span=1,0,0,esf,b8zs
fxoks=124
In /etc/asterisk/zapata.conf:
signalling=fxo_ks
context=blah
group=1
channel => 124
Configuring Digium’s TExxxx Cards
Selecting T1 or E1 Mode
T1/E1 Select Dual Span
T1 or E1 mode can be set via a row of two jumpers towards the right end of the board, or via a
module parameter, as described below:
Open = T1 ; Close = E1
| 2 | 4 |
| 1 | 3 |
Example:
Span 1 in E1 mode: Jump 12

T1/E1 Select Quad Span
T1 or E1 mode can be set via a row of four jumpers towards the center of the board, or via a module
100
parameter, as described below:
Open = T1 ; Close = E1
| 2 | 4 | 6 | 8 |
| 1 | 3 | 5 | 7 |
Example:
Selecting the Mode without a Jumper Setting
If you do not have physical access to the card and need to set it in T1 or E1 mode, pass a special option when loading
the module to accomplish this task:
insmod wct4xxp t1e1override=0xFF
This will set all four spans into E1 mode.
insmod wct4xxp t1e1override=0x00
This will set all four spans into T1 mode.
If you need some spans T1 and some E1, use the following guidelines:
The settings of the spans must be passed as a bitmask in the module parameter. To create the bitmask,
use the table below, adding the value of the numbers corresponding to the spans you wish to enable:
Span Value
1 1
2 2
3 4
4 8
To enable spans 1 and 4, call modprobe:
modprobe wct4xxp t1e1override=0x09
Add 1 and 8 to get 9. Remember to format it properly if you pass this value in HEX.
To make spans 1, 2, and 4 E1 spans, use the following parameter:
... t1e1override=0x0B
or
... t1e1override=11
An even easier way is to add this to the /etc/modprobe.d/zaptel file:
101
options wct4xxp t1e1override=0xFF
Example for TExxxx card
This is zaptel.conf:
span=1,1,0,ccs,hdb3,crc4
bchan=115
dchan=16
bchan=1731
This is zapata.conf from the same system:
[channels]
language=de
context=default
switchtype=euroisdn
pridialplan=unknown
prilocaldialplan=unknown
signalling=pri_cpe
usecallerid=yes
hidecallerid=no
callwaiting=yes
usecallingpres=yes
callwaitingcallerid=yes
threewaycalling=yes
transfer=yes
cancallforward=yes
callreturn=yes
echocancel=yes
echocancelwhenbridged=yes
rxgain=0.0
txgain=0.0
group=1
callgroup=1
pickupgroup=1
immediate=no
group = 1
channel => 115
channel => 1731
102
Asterisk Real time
Asterisk Real time allows the storage of users/peers data to be stored in a database. You can use any
ODBCsupported database, but we will use MySQL here.
With Asterisk Real time, you can add/remove users, or make call flow changes using a database table.
Once configured, the Asterisk Real Time engine will perform database lookup(s) on a percall basis,
allowing for runtime configuration changes. You do not need to reload configurations after you make
the changes.
Setup and Configurations
Install the MySQL database, client libraries and header. The library and header files are required to
compile the Asterisk Real Time driver, which can be found in the Asterisk distribution’s addons
section.
Install MySQL and its libraries:
cd /usr/src
wget http://downloads.mysql.com/archives/mysql5.0/mysql5.0.33.tar.gz
tar zxvf mysql5.0.33.tar.gz
cd mysql5.0.33
groupadd mysql
useradd g mysql mysql
./configure –prefix = /usr/local/mysql
make
make install
Scripts/mysql_install_db
chown R root /usr/local/mysql
chown R mysql /usr/local/mysql/var
chgrp R mysql /usr/local/mysql
cp Supportfiles/mymedium.cnf /etc/my.cnf
Start MySQL:
/usr/local/mysql/bin/mysql_safe &
Create a symbolic link:
mkdir /var/lib/mysql
103
cd /var/lib/mysql
ln s /tmp/mysql.sock
Install the mysqldevel:
yum install mysqldevel
Download Asterisk’s addon modules.
Note: Asterisk’s 1.2.x distribution will have an addon version which will work properly only with
Asterisk’s 1.2.x distribution. If using Asterisk 1.2.x, download its corresponding Asterisk addon
module.
Wget http://http://downloads.digium.com/pub/asterisk/oldreleases/ asterisk1.4.1x.tar.gz
tar zxvf asteriskaddon1.4.x.tar.gz
cd asteriskaddon1.4.x
To enable the unique ID in Asterisk’s cdrs, add the following line in Makefile:
vi Makefile
CFLAGS += DMYSQL_LOGUNIQUEID
Add the following line on top of cdr_addon_mysql.c
#define MYSQL_LOGUNIQUEID
Compile and install:
make clean
make
make install
Asterisk’s addon module has been installed. Check that the module res_mysql.so is in the
/usr/lib/asterisk/modules directory. The sample configuration file (res_mysql.conf.sample) for
MySQL can be found in {asteriskaddondirectory}/configs.
Copy the configuration files to the /etc/asterisk directory:
cp cdr_mysql.conf.sample /etc/asterisk/cdr_mysql.conf
cp res_mysql.conf.sample /etc/asterisk/res_mysql.conf
104
Create cdr and sip users/peers database tables to be used by Asterisk’s Real time engine:
mysql user=root –password=password
CREATE DATABASE asteriskcdrdb;
GRANT ALL
ON asetriskcdrdb.*
TO asteriskuser@localhost
IDENTIFIED BY 'yourpassword';
USE asteriskcdrdb;
CREATE TABLE `cdr` (
`calldate` datetime NOT NULL default '00000000 00:00:00',
`clid` varchar(80) NOT NULL default '',
`src` varchar(80) NOT NULL default '',
`dst` varchar(80) NOT NULL default '',
`dcontext` varchar(80) NOT NULL default '',
`channel` varchar(80) NOT NULL default '',
`dstchannel` varchar(80) NOT NULL default '',
`lastapp` varchar(80) NOT NULL default '',
`lastdata` varchar(80) NOT NULL default '',
`duration` int(11) NOT NULL default '0',
`billsec` int(11) NOT NULL default '0',
`disposition` varchar(45) NOT NULL default '',
àmaflags` int(11) NOT NULL default '0',
àccountcode` varchar(20) NOT NULL default '',
ùserfield` varchar(255) NOT NULL default ''
);
ALTER TABLE `cdr` ADD INDEX ( `calldate` );
ALTER TABLE `cdr` ADD INDEX ( `dst` );
ALTER TABLE `cdr` ADD INDEX ( àccountcode` );
The unique ID has been enabled. Enter the following command:
ALTER TABLE `cdr` ADD ùniqueid` VARCHAR(32) NOT NULL default '' after àccountcode`;
Create Asterisk’s Real time database for sip users/peers:
105
CREATE DATABASE asteriskrealtime;
GRANT ALL
ON asetriskrealtime.*
TO asteriskuser@localhost
IDENTIFIED BY 'yourpassword';
USE asteriskrealtime;
CREATE TABLE sip_buddies (
id serial NOT NULL primary key,
name varchar(80) NOT NULL default '',
host varchar(31) NOT NULL default '',
nat varchar(5) NOT NULL default 'no',
type varchar(255) NOT NULL,
CHECK (type IN('user','peer','friend')),
accountcode varchar(20) default NULL,
amaflags varchar(13) default NULL,
callgroup varchar(10) default NULL,
callerid varchar(80) default NULL,
cancallforward char(3) default 'yes',
canreinvite char(3) default 'yes',
context varchar(80) default NULL,
defaultip varchar(15) default NULL,
dtmfmode varchar(7) default NULL,
fromuser varchar(80) default NULL,
fromdomain varchar(80) default NULL,
insecure varchar(4) default NULL,
language char(2) default NULL,
mailbox varchar(50) default NULL,
md5secret varchar(80) default NULL,
deny varchar(95) default NULL,
permit varchar(95) default NULL,
mask varchar(95) default NULL,
musiconhold varchar(100) default NULL,
pickupgroup varchar(10) default NULL,
qualify char(3) default NULL,
regexten varchar(80) default NULL,
restrictcid char(3) default NULL,
rtptimeout char(3) default NULL,
rtpholdtimeout char(3) default NULL,
106
secret varchar(80) default NULL,
setvar varchar(100) default NULL,
disallow varchar(100) default 'all',
allow varchar(100) default 'gsm,g726aal2,g726,g729;ilbc;ulaw;alaw',
fullcontact varchar(80) NOT NULL default '',
ipaddr varchar(15) NOT NULL default '',
port smallint NOT NULL default '0',
regserver varchar(100) default NULL,
regseconds integer NOT NULL default '0',
username varchar(80) NOT NULL default''
);
The extensions table is used for dial plans. Note that the “Priority” field is a number; we cannot use
the 'n' priority here as we use in the static (file) configuration:
CREATE TABLE extensions (
id serial,
context varchar(40) NOT NULL default '',
exten varchar(40) NOT NULL default '',
priority int4 NOT NULL default 0,
app varchar(40) NOT NULL default '',
appdata varchar(256) NOT NULL default '',
PRIMARY KEY (context,exten,priority),
UNIQUE (id)
);
Edit the configuration files. Edit cdr_mysql.conf
[global]
hostname=127.0.0.1
dbname=asteriskcdrdb
table=cdr
password='your password'
user=asteriskuser

Edit res_mysql.conf
[general]
dbhost = 127.0.0.1
dbname = asteriskrealtime
dbuser = asteriskuser
dbpass = yourpassword
dbport = 3306
107
dbsock = /var/lib/mysql/mysql.sock
Edit the /etc/asterisk/extconfig.conf as given below:
[settings]
sipusers => mysql,asterisk,sip_buddies
sippeers => mysql,asterisk,sip_buddies
extensions => mysql,asterisk,extensions
To load the database’s extensions, edit the /etc/asterisk/extensions.conf file. Each context getting its
information from the database will need the following: switch => Realtime/@extensions. For
example:
[incoming]
switch => Realtime/@extensions
108
Adding Asterisk’s H.323 Channel
H.323 support can be added in three ways.
h323
Asterisk’s H.323 channel is included in its source distribution in the channels/h323 directory in the
source tree. The chan_h323 only acts like a H.323 gateway, not as a gatekeeper. See the
channels/h323/README for installation instructions and software requirements, and h323.conf for
configuration.
oh323
There is another H.323 channel implementation known as Asteriskoh323, which is actively
developed by InAccess Networks, and can be found at
http://www.inaccessnetworks.com/projects/asteriskoh323.
ooh323c
asteriskooh323c is a part of Asterisk’s addons package. It is yet another channel driver based on
Objective Systems’ open source H.323 stack (ooh323c). This stack is developed in C language, and
contains only the code required to set up H.323 signaling channels. All media processing is handled
by Asterisk itself. This provides scalability for H.323 calls, which depends primarily on Asterisk’s
ability to handle media streams. The channel driver is available on Asterisk’s addon cvs, and also
from Objective Systems’ website at http://www.objsys.com/open.
We will only install Ooh323C. Download Asterisk’s addons:
cd /usr/src
http://downloads.digium.com/pub/asterisk/oldreleases/ asteriskaddons1.4.5.tar.gz
tar –zxvf asteriskaddons1.4.5.tar.gz
Build and install:
cd asteriskaddons1.4/asteriskooh323c
./configure
make
To debug, run "make debug" instead of "make".
109
The library will be generated at asteriskaddons1.4/asteriskooh323c/.libs/libchan_h323.so.1.0.1.
To install libchan_h323.so in the /usr/libs/modules/ directory, change to 'super user' mode and
then run:

make install
Open h323.conf.sample in the asteriskooh323c0.6 directory. Under [general] you will see the global
configuration setting. Modify the IP addresses of Asterisk’s server "bindaddr" to match your
configuration. Install a sample h323.conf in /etc/asterisk
make sample
Run Asterisk as:
/usr/sbin/asterisk vvvc
Check whether the H323 channel is registered properly from Asterisk’s console:
CLI>show channeltypes
To see all the defined H323 users:
CLI>ooh323 show users
To see a specific user’s details:
CLI>ooh323 show user myuser1
To see all the defined peers:
CLI>ooh323 show peers
To see a specific peer’s details:
CLI>ooh323 show peer mypeer1
To use the OH323 channel in extensions.conf use a statement similar to the one given below:
exten => 101, 1, Dial(OOH323/mypeer1)
110
ABBREVIATIONS
ADTRAN General Public Licence SCN Switched Circuit Network
ALSA Advance Linux Sound Architecture SIP Session Initiation Protocol
AMI Alternate Mark Inversion TDM Time Division Multiplexing
ATA Analog Telephony Adapter TOS Type Of Service
B8ZS Bipolar 8 zero substitution UAC User Agent Client
CAS Channel Associated Signaling UAS User Agent Server
CCS Common Channel Signaling UDP User Datagram Protocol
CDR Call Details Record UNISTIM United Network IP Stimulus
CRC Cyclic Redundancy Check VoFR Voice over Frame Relay
CSU Channel Service Unit VoIP Voice Over IP
DHCP Dynamic Host Control Protocol
DSX Digital Signal Crossconnect
DTMF Dual Tone Multi Frequency
ESF Extended Super Frame
FSF Free Software Foundation
FXO Foreign Exchange Office
FXS Foreign Exchange Subscriber
GPL General Public Licence
HDB3 High Density Bipolar Threebit Substitution
HTTP Hyper Text Transfer Protocol
IAX InterAsterisk Exchange
ISDN Integrated Services Digital Network
ITU International Telecommunication Union
IVR Interactive Voice Response
LAN Local Area Network
MC Multi Point Controller
MCU Multi Point Controller
MGCP Media Gateway Control Protocol
NAT Network Address Translation
OSS Operations Support Systems
PBX Private Branch Exchange
POTS Plain Old Telephone Services
PRI Primary Rate Interface
PSTN Public Switched Telephone Network
RTCP Real Time Control Protocol
RTP Real Time Protocol
SCCP Skinny Client Control Protocol
111
References
1. http://www.voipinfo.org/wiki
2. http://www.asteriskguru.com/
3. http://www.asterisk.org
4. http://www.theasteriskbook.com/unstable/index.html
5. VoIP Telephony with Asterisk BY Paul Mahler
6. Asterisk: The Future of Telephony BY Leif Madsen, Jared Smith, Jim Van Meggelen
7. Switching to VoIP By Theodore Wallingford
112

Asterisk Toolkit

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Asterisk Toolkit

Uploaded by

Copyright:

Available Formats

Asterisk (Open Source PBX) Training Material

The Open Source Resource Center (OSRC) is a project of the Pakistan Software Export Board

Sr. No Description Page

10. Adding H323 Channel 109

Interfaces for connectivity to traditional legacy telephone services which support PseudoTDM

A Multipoint Controller (MC) supports conferencing between three or more endpoints. A

SIP Uniform Resource Locators (URLs) provide addressing similar to email addressing. A SIP

• CONGESTION: The term "Congestion" is a little misleading. Dial() returns

The voicemail.conf file contains one general section, one zonemessages section, and one or more

Configure sip.conf, Zapata.conf or iax.conf to enable voicemail by defining the mailbox

You might also like

Asterisk Toolkit

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Asterisk Toolkit

Uploaded by

Copyright:

Available Formats

Asterisk (Open Source PBX) Training Material

The Open Source Resource Center (OSRC) is a project of the Pakistan Software Export Board

Sr. No Description Page

10. Adding H323 Channel 109

Interfaces for connectivity to traditional legacy telephone services which support Pseudo­TDM

A Multipoint Controller (MC) supports conferencing between three or more endpoints. A

SIP Uniform Resource Locators (URLs) provide addressing similar to e­mail addressing. A SIP

• CONGESTION: The term "Congestion" is a little misleading. Dial() returns

The voicemail.conf file contains one general section, one zonemessages section, and one or more

Configure sip.conf, Zapata.conf or iax.conf to enable voicemail by defining the mailbox

You might also like

Interfaces for connectivity to traditional legacy telephone services which support PseudoTDM

SIP Uniform Resource Locators (URLs) provide addressing similar to email addressing. A SIP