The Hitchhiker's Guide to Asterisk

Leif Madsen

Jared Smith

Steven Sokol

Wasim Baig

Daniel Heinzen

Josh Rollyson

Peter Grace

Nick Bachmann

Mike Preston

Martin List-Petersen

William Suffill

Jim Van Meggelen

Chris Tooley

This document may be distributed subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/ )


Table of Contents
Introductory letter from Mark Spencer (hopefully?)
Introduction to Asterisk
General Concept of Asterisk
Asterisk: The Swiss Army Knife of Telephony
Prerequisite Knowledge and Skills
What to expect
Asterisk Architecture
The Big Picture
Channels
Codecs and Conversions
Protocols
Key Components
Asterisk Software
Zaptel Hardware
Protocols
Applications
Add-On/Optional Components
Soft Phones
Management Tools
Hardware
Installing Asterisk
Requirements
PC Hardware Requirements
Linux Requirements
Hardware Installation
IRQ Sharing Issues
Digium Cards
Downloading Asterisk from CVS
What is CVS?
Your Initial Download
Getting the files from CVS
Getting the files using CVSup
Updates
Compiling Asterisk
Compiling the software
Making the Samples/Demo
Making Code Documentation (Doxygen)
Common Build Errors / Warnings
Loading Drivers
Linux Kernel Loadable Modules
Starting Asterisk
Manually starting Asterisk and the CLI
Starting Asterisk using safe_asterisk
Starting Automatically at Boot Time
Asterisk
Zaptel
Asterisk Channels
What are Asterisk Channels?
Zap Devices/Channels
Channel Configuration Files
Creating Dialplans
Introduction to Creating Dialplans
Contexts
Extensions
Priorities
Applications
A Simple Example
The special 's' extension
The Answer(), Playback(), and Hangup() functions
Our First Dialplan
A more useful example
The Dial() application
Adding Additional Functionality
Adding another FXS port
Creating Voice Menus
Accepting User Input With The Background() Application
Adding a Voice Menu
Handling Calls Between Internal Users
Variables
Global Variables
Call Variables
Adding Variables
Macros
What are Macros?
Attributes of Macros
Adding Macros to our Dial Plan
Jumping Between Priorities Based on Call Status
Call Flow
Pattern Matching
Pattern Sort Order
Linking Contexts with Includes
The other special extensions (i,t,o,h,fax,???)
Using Goto and GotoIf
Advanced Dial Plan Concepts
VoiceMail
Music on Hold
Conferences
Call Parking
Modules, or "Things that make Asterisk work."
Core Asterisk configuration
Defining file locations (asterisk.conf)
The Dialplan (extensions.conf, see chapter 4 and 5)
Mysterious Modules (modules.conf)
Modules
Digium Zaptel Cards (chan_zap)
ISDN CAPI (chan_capi)
mISDN (chan_mISDN)
Voicetronix Cards (chan_vpb)
Defining IAX Channels and connections (chan_iax & chan_iax2)
Defining SIP Channels and connections (chan_sip)
Defining H.323 channels and connections (chan_h323)
asterisk-oh323, or another way of getting H.323 connectivity (chan_oh323)
Configuring E.164 lookups (app_enumlookup)
Voicemail (app_voicemail)
Conferencing (app_meetme)
Call Parking (app_parkandannounce)
The Asterisk Cookbook
Scripting with the Asterisk Gateway Interface (AGI)
What is AGI?
What languages can I use?
AGI Basics
Language-specific AGI notes and examples
C
Perl
Python
PHP
EAGI
Advanced Asterisk Configuration
Agents and the Asterisk ACD
Queues
Agents
Text-To-Speech: Festival
CLASS Features (John Todd?)
Fax (Software Fax) (Steve Underwood?)
Sphinx Speech Recognition (ASR)
Distributed Asterisk (Clustering/TDMoE)
TDMoE (Time Domain Multiplexing over Ethernet)
ENUM/E164 Call Routing (LCR)
Introduction
Making ENUM Work for You
Setting up ENUM Routing on your Asterisk System
Configuring your System to Allow ENUM Calls through your PSTN Interface
Databases and Asterisk
PostgreSQL and Applications
CDR - Call Data Records
AstDB - The built-in database
Auto-Dialout (Call Files)
Call File Caveats
Common Issues
Music on Hold/MP3 Playback
Proper Version of MPG123
Timing: zaptel/ztdummy/zaprtc
Configuration File: /etc/asterisk/musiconhold.conf
Adding Music on Hold to the Dialplan
A Final Note on Choosing Music
DTMF over SIP
Inband
Info
rfc2833
The "Flash"
Internationalization of Asterisk
Tones and Ringback
Call Supervision
SIP and NAT
Optional/Added Codecs
G.729
G.723
Message Waiting Indication
Common Hardware Device Issues
Grandstream BT100 Series
Cisco ATA-186
Cisco 79XX Series
SNOM VoIP Phones
Carrier Access Channel Banks
Zhone Channel Banks
Echo Cancellation Issues
Introduction
Echo Training
Adjusting the rxgain/txgain Settings
Interfacing with Legacy PBX Equipment
Nortel Meridian/Norstar
Avaya Definity Systems
Others (Mitel, Aspect, Telrad, Vodavi, Dialogic, etc.)
How to politely use the Asterisk-Users List
How to politely use the Asterisk IRC channel
Creating Asterisk Applications in C
Sources of Additional Information
Connecting Asterisk to Common VoIP Providers
Overview
Free Service Providers
Free World Dialup (FWD)
IAXTEL
IPTel
Gossiptel
SipGate
SIPPhone.com
XVOIP
Commercial Service Providers
NuFone
VoicePulse
XVOIP
Technical Issues
More Information
Applications Reference
CLI Command Reference
Which Commands Can I Use?
Obtaining Help About a Command
The show Command
show agents
show agi
show application
show applications
show audio
show channel
show channels
show codec
show codecs
show conferences
show config
show dialplan
show file
show image
show indications
show keys
show manager
show modules
show parkedcalls
show queue
show queues
show switches
show translation
show uptime
show version
show video
show voicemail
Manager Commands Reference
The Asterisk C API Reference
Other Open Source Telephony Systems
Other Hardware
Other hardware options
VoiceTronix OpenLine and OpenSwitch Cards
QuickNet Cards
Dialogic Cards (and Proprietary Drivers)
ISDN Cards
Eicon Diva
AVM Fritz!
HFC based ISDN cards, quadBRI, octoBRI
Other Cards (LineJack/PhoneJack/VoiceTronix/Dialogic)
Building Additional Modules
Building additional modules
H323 - McNamara
H323 - Manousos
MySQL CDR
CAPI/ISDN
Glossary of Asterisk & Telecom Terms
Colophon

Introductory letter from Mark Spencer (hopefully?)


Introduction to Asterisk

General Concept of Asterisk

Asterisk: The Swiss Army Knife of Telephony

Welcome to the wonderful world of Asterisk. You are about to discover the most powerful and popular open source PBX available.

Asterisk allows you to craft a telephony system to address your specific requirements. It does this by providing a library of basic telephony functions which you then use as script building-blocks. Calls into the system trigger these functions through digit patterns (referred to as extensions), giving you complete control of complex call routing concepts with relative ease. Common PBX functionality such as voicemail, call queuing, conferencing, music on hold and others are all included. But that's just the beginning. Asterisk is one of the few PBXs in existence that connects legacy telephony technologies such as PRI or Analog trunks through the same switching logic as state of the art VoIP interfaces such as H.323 or SIP. This powerful yet simple core allows complex concepts in other systems to be deployed with ease in Asterisk. For example, building an IVR application or deploying CTI functionality can't be done more inexpensively than with any other system. Why? Because with Asterisk, it's all built right in!

Perhaps Asterisk's most valuable asset is the open nature of the system. As with any open-source application, Asterisk can be further enhanced by the community of people who use it. This powerful concept ensures that Asterisk is prepared to mature in keeping with the demands of the industry. Go ahead and modify the source code to fit your needs, or, better still, contribute to an active and growing development community.

Because Asterisk is so powerful and flexible, in this book we can only begin to cover all the possible uses and configurations. We will therefore focus on the most commonly used features of the system and answer the most frequently asked questions. If you can work through the material we present here, you will be well on your way to becoming a competent Asterisk solutions developer.

We have also included appendices that will serve as excellent reference material, covering subjects such as application programming in C, configuration of various types of hardware, and many samples of configuration files. Also, there is a glossary included to help you find definitions for terms and acronyms used in this book.


Prerequisite Knowledge and Skills

Because of the nearly limitless flexibility of Asterisk, successfully configuring a system requires more than a passing familiarity with several technical concepts, most notably Linux Installation and Administration, as well as an understanding of Telephony. In this document, we will only be scraping the surface of these complex technologies as we discuss concepts relevant to Asterisk design, installation and administration. If you desire more knowledge on either subject, we have suggested several sources which will set you on the path towards the required knowledge.


Telephony

Asterisk is a PBX, and that means that the more Telecommunications knowledge you have, the easier Asterisk will be to learn. If you plan to use analog circuits and telephones, you will want to understand the difference between FXS and FXO interfaces. Digital trunks will require you to be conversant with technologies such as ISDN-PRI (including wiring of T1s). Terms such as PSTN or VoIP should be second nature to you, and you'd do well to obtain an understanding of the concept of analog to digital conversion, and what codecs are.

Before you get overwhelmed, please understand that many excellent references exist to help you obtain this knowledge. A good introductory work is Noll's Introduction to Telephones and Telephone Systems , published by Artech House Publishers. The definitive encyclopaedia of all things Telecom is Newton's Telecom Dictionary , published by CMP Books - this book should be on any telecommunication professional's bookshelf.


Linux Installation and Administration

You will need an i386-compatible system with Linux installed before you can install and use Asterisk. If you do not have a solid grasp of Linux administration concepts you will want to focus on obtaining those skills before attempting an Asterisk install. On the Internet, The Linux Documentation Project (http://www.tldp.org) provides many great resources for beginners. In the bookstore, Frisch's Essential System Administration along with Nemeth, et al.'s Linux Administration Handbook and Unix System Administration Handbook are recommended. Running Linux by Matt Welch, Lar Kaufman et al. is still one of the all-time most successful Linux introductions. Reading one or two of these books can save a lot of headaches down the road.


Non-Linux Platforms

Asterisk works on many operating systems, however the main development and the PSTN hardware support is focused on the Linux i386 platform. On other platforms, you are mostly limited to the use of VoIP protocols in your PBX. Some applications will not run without a timer that currently is implemented only on Linux systems. The FreeBSD operating system has recently got a lot of attention by Asterisk developers and Asterisk is running smoothly on that platform with the above mentioned limitations.

Digium's Asterisk server runs on FreeBSD, OpenBSD and OS X, but the drivers do not yet support these platforms. FreeBSD's 'ports' provides drivers for the most recent stable release of Asterisk, and work is progressing on integrating those drivers into Digium's releases.

Support for non-linux platforms is provided by third-parties, and as a result there are various limitations on features, drivers or release dates versus Asterisk on Linux. As that support becomes integrated into Digium's releases, these limitations will go away.


What to expect

Asterisk is not a turnkey system

The Asterisk PBX system is a complex piece of software. The learning curve is very steep and simply reading any single resource will not teach you everything that Asterisk is capable of. This resource is an attempt to gather some of the most common issues that new comers to Asterisk encounter. Learning how Asterisk works is very much like learning a new programming language. Many hours need to be spent with Asterisk in order to understand how all the configuration files work with each other to control the many interfaces. The ability to understand the dialplan is a key concept that those new to Asterisk need to fully comprehend. Once this is established the configuration of the many different kinds of interfaces that you would like Asterisk to communicate with work in tandem with the dialplan. This relationship extends throughout Asterisk with many other modules that are not compiled by default. The term KISS (Keep It Super Simple) needs to be applied here with great emphasis. The mistake many people make when first discovering Asterisk presuming a production quality system is possible in only a couple of hours. This may be possible once all the concepts are learned, but few are able to do it their first time out. However the intension of this book is to get you up to speed as quickly as possible.


Don't like it? Change it yourself!

Asterisk is open source software. The ability to read the source code is its power. Most (if not all) other PBX systems are entirely closed source with only the abilities that have been provided to you. If something does not work quite the way you would expect it to, you are able to change it.


Asterisk Architecture

The Big Picture

To summarize, a channel generally consists of either an analog signal running on POTS (or Plain Old Telephone System) or some combination of codec and signaling protocol, ie. GSM and SIP, or, ULAW and IAX.


Channels

A channel is a voice path equivalent to a phone line between two points. There are many different ways the information can be sent, but often is split into two groups -- analog and digital. Analog data is the type of signal that has been used on the phone system since it was invented. It can be prone to noise and echo, and can not be sent as-is over a digital network in its raw form. Digital data consist of ones and zeros. Analog data as picked up from a microphone must be converted into a series of discrete levels, or quantized, to be able to form a digital signal. Once the data is in a digital state it will require a fair amount of bandwidth (relatively speaking) to send as-is; 64kbits/sec for uncompressed voice data sampled at 8KHz with 8bits resolution.


Codecs and Conversions

Obviously it is desirable to fit as many calls as possible into a data network. This is done by encoding it into a form that takes up much less space using a codec (short for COder/DECoder). Some examples of these are ulaw, alaw, gsm, ilbc and g.729. Codecs determine the sustained data bit rate which is required for each channel. Different codecs have different advantages but are independent of the type of protocol that is used to establish the channel. The codec converts the analog voice signal to a digitally encoded one. The quality, databit rate required and the computational requirements vary from one codec to the next.


Protocols

Sending data to another phone would be easy if the data found its own way there and knew what to do at the other end. Unfortunately it doesn't which is why we use a signaling protocol to encapsulate the voice data. The common signaling protocol used today is SIP (an acronym for Session Initiation Protocol). Other protocols that Asterisk support include IAX, H.323 and CAPI. CAPI is a special case in that it is used within a computer system to deal with ISDN interfaces.


Key Components

Asterisk Software

Asterisk (Main PBX & Channels)

The Asterisk software is what gives a computer system the logic required to run a PBX system. IP based channels, dialplans, AGI scripting and timing insensitive parts of Asterisk can be used without any additional hardware.


Zaptel (Drivers for Zaptel Hardware)

The drivers for Digium hardware can be obtained from the CVS server. These will allow you to integrate many types of legacy telephony equipment such as T1/E1, PSTN, FXO and FXS devices.


Libpri (ISDN PRI Drivers for Zaptel)

Libpri will allow Asterisk to work with Primary Rate ISDN interfaces. It is based on the Bellcore specification SR-NWT-002343 for National ISDN. You will need to compile and configure these drivers if you need Asterisk to speak with an ISDN interface.


Zaptel Hardware

Overview

Zaptel hardware is designed and built by Digium, the owners of Asterisk. The Asterisk PBX system is designed to work with these devices and so are fully supported. Drivers are provided to run the devices on a Linux based operating system.


X100P and X101P

The X100P and X101P are Foreign Exchange Office (FXO) devices which allow you to connect the Asterisk PBX to a PSTN line. The only difference between an X100P and X101P is a slight difference in their respective chips, but this has no effect on their use with Asterisk. The X100P uses a single PCI slot and supports FXS Loopstart and "Kewlstart" (Loopstart with far end disconnection supervision). With the X100P Asterisk supports both incoming and outgoing calls and supports ring detection and remote hangup.

Note

These cards can not be used as an FXS device for attaching analog telephones to the Asterisk PBX.


S100U - Single Port FXS USB Interface

The S100U is a single port FXS interface for connecting an analog telephone to your Asterisk server via a USB port. This allows you to use any analog telephone for VoIP when connected to Asterisk.


TDM400P

The TDM400P is a half-length PCI 2.2 compliant card which allows you to connect standard analog telephones and analog lines to a computer. The card uses small modules to activate the 4 ports on the card. Which daughter card is plugged onto the board will determine whether the port acts as an FXO or FXS interface. The boards are not selectable between modes; the module used determines the type of interface.

There is an alternate naming convention used as well to reference the type of modules attached to the TDM400P. This is in the form TDM##B where the first hash is the number of FXS (0-4) interfaces and the second hash is the number of FXO (0-4) interfaces.

With the development of the FXO module for the TDM400P it has become the preferred FXO interface device.


T100P/E100P - Single Span T1/E1 Interface

The T100P is a single span T-1 (24-channel) card. This card supports both voice and data modes on its single-T span. The T100P supports standard telephony and data protocols, including both RBS and Primary Rate ISDN (PRI) protocol families for voice and PPP, Cisco HDLC and Frame Relay modes. The T100P can also be connected to channel banks for use with Asterisk.

The E100P version is essentially the same card supporting the E-1 European standard.


T400P, E400P, TE410P, and TE405P - Quad-Span T1/E1 Interface

The T400P and E400P are 4 port versions of the T100P and E100P respectively. The TE410P is a quad T1 or E1, selectable per card or per port, allowing you to do both signaling formats in a single card. This card only supports a 3.3v PCI bus available on newer machines or in 64-bit PCI bus architectures.


Protocols

The IAX Protocol

IAX stands for Inter-Asterisk eXchange and was developed as an alternative to SIP and H.323. Currently there exists 2 versions of IAX, where IAX2 is the most common used. IAX is not submitted by any standards group, but is currently being adopted by different manufacturers for both soft- and hard-phones.

The biggest advantage for IAX is that it uses only one UDP port and thus works very well behind NAT firewalls. It allocates only the the minimum of bandwidth, that is used at any time.


The SIP Protocol

SIP, or the Session Initiation Protocol, is specified by the IETF. It allows text, voice and multimedia sessions and uses port 5060 udp and tcp, but may use other ports. Most VoIP devices on the market currently support this protocol.

This protocol is not always easy to deploy in a firewalled environment, but with the help of a STUN server not impossible. Asterisk is able to translate the information in the packet headers so that it is possible to run in a NAT'd environment. See chapter 8 for more information.


The H.323 Protocol

H.323 is specified by the ITU-T (International Telecommunication Union Stanardization Sector) and was meant for teleconferencing (Speech and Video). It basically should enable you to terminate voice, video, fax and much more over IP, depending on what features your client offers.

There are two implementations for H.323 that can be used with Asterisk: asterisk-oh323 and chan_h323, these are described in detail in a later section.

You might ask yourself now, what module you should choose and quite frankly, there is no all-round answer to that. Implement whichever you have in hands and test it, if you not are happy with that, try the other one.


Applications

Asterisk comes with many applications built into it. These applications are used for manipulating calls and giving the user an interactive system. These applications are then used to build a custom dialplan. You will be learning how applications like Dial and other basics work in a dialplan, plus the actual dialplan scripting.

The voicemail system, called Comedian, will be extensivly covered. This will include the backend configuration of the voicemail system for use within Asterisk as well as the actual use of the Comedian mail system.

You can extend the capabilities of Asterisk through the AGI scripting interface. This allows you to create custom applications in virtually any language and tie them into your Asterisk PBX system.


Add-On/Optional Components

Soft Phones

Softphones are software based interfaces on a modern PC. These softphones allow you to place and receive calls at your computer using a headset and microphone. Softphones have the advantage of being extremely portable, especially with a laptop. There are several freely available softphones working with a variety of protocols. Because of the number of softphones available and their configurations, they will not be covered extensively so you should consult the documentation of any softphone which you wish to use. We will however deal with the configuration of Asterisk for use with softphones.


Hardware

Asterisk officially supports hardware made by Digium (the creators of Asterisk) although many other peices of hardware do work. We will be mostly focusing on the installation and configuration of Digium hardware, though you may be able to find more information in the Other Hardware appendix.

An option from using channel banks and analog telephone devices is to use VoIP hard phones. There are several different models available for a wide range of prices. Some phones have different features, so research before purchasing is recommended. The Asterisk configuration of these devices will be covered, however you should consult the documentation that comes with your hardware devices for their configuration.


Installing Asterisk


Requirements


Linux Requirements

Tested Linux Distributions

Asterisk works with most Linux distributions. Many distributions such as RedHat, Fedora, Debian, Mandrake and Gentoo have all been used successfully by the developers. If you find something doesn't work on any particular system, you may want to file a bug report. See the section regarding filing a bug report.


Minimal Kernel Version

Asterisk is designed to work on Linux kernel version 2.4, however there is some support for kernel 2.6. If you are trying to build a stable system, it is recommended that you use kernel version 2.4. The following sections will assume you are running on a 2.4 kernel based system.


Required Packages

Previously there were some packages which were requirements to install Asterisk such as readline and readline-devel that are no longer required. As well there is no special hardware required such as a soundcard. The only required package is Asterisk itself. If you are using Digium hardware, you will need the zaptel package. For T1 and E1 interfaces the libpri package is required. Bison is required to compile Asterisk, the ncurses and ncurses-devel packages are required if you wish to build the newt tools (e.g. astman).


Hardware Installation

IRQ Sharing Issues

Many telephony cards such as the X100P tend to generate a large amount of interrupts. Servicing them takes time and drivers may not be able to do it on-time. If another device is processing the same shared IRQ, the IRQ line cannot receive another one. It does tend to work better on SMP (APIC) systems. On single chip systems you can get interrupt misses and messed up clocking. Any of Digium's cards or other telephony cards can be subject to this problem. Because the precise delivery of IRQ's is very much necessary in telephony, one should not share IRQ's with anything. This is not to say you will necessarily have IRQ sharing conflicts, but it is something to be aware of.

If you are dedicating the computer to Asterisk, free up the most IRQs as possible by disabling USB, serial and parallel port support in the BIOS. Essencially you want to free as many IRQs as possible. You will *not* want to see a NIC sharing an IRQ with a TDM or FXO card! It's best that these cards have their own IRQ.

Most BIOS' will allow you to manually assign IRQs to specific slots. Go into the BIOS and look for the IRQ area, often on the second page. If it is set to AUTO by default, try setting to manual and see what happens. Chances are, a table will become available for manually assigning an IRQ to each slot.

Note: One thing to watch out for on some motherboards is slots *sharing* IRQs. Look in the BIOS and check if it has an entry like "1/5" in the IRQ table.

Once booted, view /proc/interrupts to see the assigned IRQs.

(output below is just an example with Digium hardware flagged)


			# cat /proc/interrupts
			            CPU0
			    0:   41353058          XT-PIC  timer
			    1:       1988          XT-PIC  keyboard
			    2:          0          XT-PIC  cascade
			    3:  413437739          XT-PIC  wctdm <-- TDM400
			    4:    5721494          XT-PIC  eth0
			    7:  413453581          XT-PIC  wcfxo <-- X100P
			    8:          1          XT-PIC  rtc
			    9:  413445182          XT-PIC  wcfxo <-- X100P
			   12:          0          XT-PIC  PS/2 Mouse
			   14:     179578          XT-PIC  ide0
			   15:          3          XT-PIC  ide1
			NMI:          0
			ERR:          0
			

Above you can see the three Digium cards each on its own IRQ. If this is the case, you can go on to install hardware drivers.


Downloading Asterisk from CVS

What is CVS?

CVS is a central repository which developers use to control the source code. When a change is made it is committed to the CVS server where it is immediately available for download and compilation. Another added benefit to using CVS is that if something was working at one point, but a change causes it to break, the version for any particular file can be rolled back to a certain point. This is true for the entire tree as well. If you find something was working at one point but installing the latest version of Asterisk causes that to break, you can "roll-back" to any point in time (see Getting the files from CVS).


Your Initial Download

Asterisk can be obtained from the Digium CVS server. You will need any packages which your distribution requires to download the sourcecode and to compile. Most modern Linux distributions have a category at installation for development tools, but some may vary. Binaries are available, however they are created on a non-regular basis, so you are best to stick to using the CVS method to obtain and compile the sourcecode.


Getting the files from CVS

The following commands can be used to retrieve the sourcecode. Your server will download all the appropriate files from the CVS server and place them in their respective directories. If you don't need zaptel or libpri simply leave them out of the checkout statement.


Asterisk v1.0 RC1


cd /usr/src
export CVSROOT=:pserver:anoncvs@cvs.digium.com:/usr/cvsroot
cvs login - the password is anoncvs
cvs checkout asterisk libpri zaptel


Getting the files using CVSup

In order to get Asterisk using CVSup, create a file containing the following information. You can call the file anything you want such as "asterisk-sup". Place this file in your /usr/src/ directory.


*default host=cvs.digium.com
*default base=/usr/src/
*default release=cvs tag=.
*default delete use-rel-suffix
asterisk
libpri
zaptel

Once you have create the file, change to the /usr/src/ directory and issue the cvsup asterisk-sup command.


Updates

Updating Asterisk from CVS is relatively straight forward. One note however is that the Asterisk directory has a script to automatically update from CVS, compile and install for you. The only problem is that it doesn't do zaptel and libpri, so those will need to be done manually. Before attempting to unload the modules be sure you have stopped Asterisk as it will be using the modules.


Updating zaptel and libpri


cd /usr/src/
cvs -z3 -d:pserver:anoncvs@cvs.digium.com:/usr/cvsroot login
The password is anoncvs
cvs -z3 -d:pserver:anoncvs@cvs.digium.com:/usr/cvsroot update zaptel libpri

Now we must unload the modules from memory before we recompile them. We can check to see what modules are currently loaded by using the lsmod command. You should get an output similar to the following:


				[root@localhost src]# lsmod
				Module                  Size  Used by
				ipv6                  184672  10
				autofs4                12932  0
				sunrpc                109924  1
				8139too                17920  0
				mii                     3584  1 8139too
				tulip                  36384  0
				ztdummy                 3364  0             <-- ztdummy module
				zaptel                218212  3 ztdummy     <-- zaptel module
				floppy                 47440  0
				sg                     27680  0
				scsi_mod               91984  1 sg
				microcode               4768  0
				dm_mod                 32800  0
				

We are looking to see that the zaptel and libpri modules are loaded. Your output may be different from what is shown above. You will be required to unload whatever modules you have loaded. The rmmod command can now be used to remove these modules from memory.


rmmod zaptel
rmmod libpri

Now we must recompile the drivers. We want to change to our zaptel source directory (ie. /usr/src/zaptel/). The first command we run will clean out any previously compiled drivers and get the directories ready for our new drivers. The second command will then compile the drivers and install them into the appropriate directories for us.


make clean
make install

Follow the same procedure for libpri if you need to recompile that. Once the drivers are recompiled, you can then load them into memory using the modprobe command.


modprobe zaptel
modprobe libpri

[someone should probably verify this works like this, and document any common problems people have with recompiling and installing the modules into memory]


Updating Asterisk with make update

Updating Asterisk is actually very simple. All you need to do is a make update in the /usr/src/asterisk/ directory. This will update Asterisk from the CVS server, compile and install for you. After that is done, simply restart Asterisk for the new changes to take effect.


Compiling Asterisk

Compiling the software


Zaptel

You will need to compile the Zaptel modules if you plan on using any Digium hardware. This will compile and install the modules for any Digium hardware which you might have installed in your system:


cd /usr/src/zaptel/
make clean
make install

The ztdummy module is used when you do not have any Digium hardware for timing but need it - such as for Music On Hold or Conferencing. The ztdummy driver requires that you have a UHCI USB controller chip on your motherboard. If you are using an OHCI USB controller you will need to use zaprtc. You can check to see if your motherboard has the UHCI USB controller by running lsmod from the command line. To compile the ztdummy module you will have to edit the Makefile located in your /usr/src/zaptel directory. Find the line containing:


					MODULES=zaptel tor2 torisa wcusb wcfxo wcfxs \
					        ztdynamic ztd-eth wct1xxp wct4xxp # ztdummy
					

and uncomment the ztdummy module. Perform the compilation as normal. Once you have successfully compiled the ztdummy module you can load it into memory by using modprobe.


modprobe ztdummy


Libpri


cd /usr/src/libpri
make clean
make install

[Lets document problems that people have with libpri, how to setup any options in the Makefile, and maybe we can explain a bit why you would even need or want libpri. It's mentioned briefly above, but maybe they didn't read it...]


Asterisk


cd /usr/src/asterisk
make clean
make install

[Lets document problems that people have with compiling Asterisk, how to setup options in the Makefile. We should mention some of the things you have to change when setting up on a Linux 2.6 kernel at some point (and should probably do that for all sections]


Making the Samples/Demo

The sample configuration files are for the purpose of learning how to create your own configuration files and to give you an idea of the commands you can use. These files are not designed to give you a working Asterisk system right out of the box. Chapter 4 deals with creating a dialplan and writing an extensions.conf file.


cd /usr/src/asterisk
make samples


Common Build Errors / Warnings

Via C3 is *NOT* an i686 processor

[Is this really relevant, and do we need this stuff in the book? I don't hear too many people talking about this, but perhaps I'm wrong - blitzrage]


Building on a little-endian system

[Same thing here as above, comments wise]


Loading Drivers

Linux Kernel Loadable Modules

[I think we have a lot of good stuff in this chapter, but things seem be in a bit of an illogical order. Also, we seem to be saying how to load modules in other sections of this chapter. Should they be moved to this section, or should we forget about this and just build it into the previous sections?]


Starting Asterisk

Manually starting Asterisk and the CLI

Asterisk can be started several ways from the command line. By default Asterisk will run as a daemon if not passed any parameters. You can do this by running /usr/sbin/asterisk. We assume that /usr/sbin/ is the directory where the Asterisk binary has been installed.

We can also pass parameters to Asterisk to allow us to do various things such as connect to the console, control the verbosity of the console, run Asterisk in debugging mode and dump cores upon crashing. These can be very useful tools to help manage your system.

Parameters that can be passed to the Asterisk binary include:

c - console. Starts Asterisk in the foreground (implies -f), with a command line interface (CLI) which you can use to monitor the state of the system and issue commands
v - level of verbosity. Multiple v's give more verbosity
d - enter debugging mode
g - dump core upon crashing
h - help
C <configufile> - Start with a configuration file other than the default /etc/asterisk/asterisk.conf
f - Foreground. Starts Asterisk but does not fork as a background daemon
r - Remote console. Starts a CLI console which connects to an instance of of Asterisk already running as a background daemon
n - Disable console colorization (for use with -c or -r)
i - Prompt for cryptographic initialization passcodes at startup
q - Quiet mode for output supression
x <cmd> - execute command <cmd> (only valid with -r)

If we wish to run Asterisk in console mode we simply append the -c command line paramater after the binary name. If you need to perform multiple commands at the same time you can concatenate multiple parameters together.

For example, lets say we want to start Asterisk in console mode with several levels of verbosity and debugging. That can be done by running /usr/sbin/asterisk -cvvvd.

What if we've started Asterisk as a daemon and we wish to reconnect to the console? To reconnect to the Asterisk console run /usr/sbin/asterisk -r.


Starting Asterisk using safe_asterisk

The safe_asterisk script is the preferred way to run Asterisk. This script starts Asterisk and monitors it to make sure it is still running. If the Asterisk process dies, the script will attempt to restart it.

You can find a copy of the script in /usr/src/asterisk/contrib/scripts/safe_asterisk. The script is copied to /usr/sbin/ during the installation process as well. Inside the script there are several options we can set.


			TTY=9                   # TTY (if you want one) for Asterisk to run on
			CONSOLE=yes             # Whether or not you want a console
			#NOTIFY=ben@alkaloid.net        # Who to notify about crashes
			ASTARGS=""
			

The TTY variable allows you to set which TTY console you would like the Asterisk CLI to run on. If you leave this variable blank then Asterisk will be started as a daemon. When CONSOLE=yes then Asterisk is started in console mode. NOTIFY is used to send an email to the address specified if Asterisk every crashes. The email is sent using the 'mail' program. ASTARGS is used to start Asterisk with any optional arguments which you specify. The Asterisk script will start Asterisk with the -vvvg arguments plus those specified in ASTARGS.


Starting Automatically at Boot Time

Starting processes at boot time are different among the different operating systems so it is best to consult your OS documentation for how to do this. However there are some sample scripts located in /usr/src/asterisk/contrib/init.d/.


Asterisk

You can either start Asterisk using the /usr/sbin/asterisk command, or ideally, use the /usr/sbin/safe_asterisk script which will attempt to reload Asterisk if it crashes. In RedHat based systems you can add this to your /etc/rc.d/rc.local file, however this will not shutdown Asterisk very cleanly during a reboot or shutdown.

In a RedHat environment you may be able to get a working rc.d/init.d script by running the following commands. This will copy the script from /usr/src/asterisk/contrib/init.d/rc.redhat.asterisk to /etc/rc.d/init.d/asterisk. It will then run the /sbin/chkconfig --add asterisk command.


			cd /usr/src/asterisk
			make config
			


Asterisk Channels

What are Asterisk Channels?

[explain what channels are] [how are they identified] [examples of channels] [most channels have their own configuration file] [It's a communication channel... specifically in Asterisk, it's a channel of communcation between some outside resource (phone line, VoIP provider, IP telephone) and Asterisk.] [Mention that each concurrent call must happen on it's own channel] [Some channels offer special features, such as sending or recieving Caller*ID] [Also mention that one of the greatest abilities of Asterisk is to be able to translate from one type of channel to another (POTS to SIP, SIP to POTS, SIP to IAX, etc.)]

In Asterisk a channel is a form of communications between some outside resource such as a phone line, VoIP provider, IP telephone and Asterisk. Every concurrent call that Asterisk controls must happen on it's own channel. A channel is named usually after its interface or protocol such as ZAP for Zaptel, IAX for the Inter-Asterisk eXchange protocol or SIP (Session Initiation Protocol).

Different channels have their own set of features such as sending or receiving Caller*ID, call trunking, call waiting and transfers. One of Asterisks greatest abilities is to be able to translate from one type of chanel to another. This allows different technologies to transparently communicate with each other such as POTS to SIP, SIP to POTS, SIP to IAX, and so on.


Zap Devices/Channels

Zap channels (Zapata/Zaptel) are the channel-type, that is used for FXO, FXS and PRI-cards. There is also a third-party module, that implements zap channels for certain BRI ISDN cards.

The Zap channels were originally given the name by the Zapata Telephony Project, which is an effort to bring affordable computer telephony to the public domain. This is happening because the commercial market is ridiculously expensive and often offers poor support. Besides that, it might be worth to mention that Zapata was a Mexican revolutionary.


Channel Configuration Files

[iax.conf] [zapata.conf and zaptel.conf - just enough to get FXO and FXS devices working] [we should just have enough in this section to use it in dialplans (next chapter)]

In Asterisk most types of channels have their own configuration file. These files are located in /etc/asterisk/ by default. For this chapter we are not going to go in depth for the configuration of these files. The examples given will be a minimum required to configure the Digium DevKit and an IAXtel connection and more advanced configurations will be discussed later. The purpose of this chapter is to give you a sense of what channels are and how they work so that the creation of dialplans appears more logical.


Creating Dialplans

The dialplan is the central piece of any Asterisk system. Simply put, the dialplan is the "road map" for how Asterisk will work. The dialplan specifies how Asterisk should should handle calls. The dialplan consists of a list of instructions or steps that Asterisk should follow. To sucessfully set up your own Asterisk system, it is absolutely vital that you understand dialplans.

This chapter will explain how dialplans work in a step-by-step manner, and give you the skills to create your own dialplan. The examples in this chapter have been designed to build upon one another, so feel free to go back and reread a section if something doesn't make sense. While this chapter is by no means an exhaustive survey of all the possible things that dialplans can do, our aim is to cover all the fundamentals.


Introduction to Creating Dialplans

The majority of the dialplan is specified in the file extension.conf. This file is made up of four main parts: contexts, extensions, priorities, and applications. In this section, we'll cover each of these parts, and explain how they work together to create a dialplan.

If you installed the Asterisk sample files, you probably have an existing extensions.conf file. Instead of modifying the existing file, we recommend you start from scratch in creating your extensions.conf file, so that you can learn about how each part of the file plays a role in the dialplan. The sample extensions.conf is an excellent resource for learning about many of the variables and other subleties of dialplans. You may want to rename your existing extensions.conf file, and refer to it later.


Contexts

Contexts play an organizational role within the dialplan. Contexts also define scope. You can think of contexts as a way to keep different parts of the dialplan separate. As a simple example, contexts can be used to make Asterisk answer one phone line differently than another. All calls that Asterisk handles will begin in a certain context. The instructions defined in this context will determine what things may happen to the call.

NoteContexts and IVR
 

Contexts are often used to create "voice menus" that give callers a list of extensions to choose from by pressing keys on a touch-tone phone. This functionality is commonly called IVR, which stands for Interactive Voice Response. We'll cover IVR in more depth later in the chapter.

Contexts are denoted by their name inside of square brackets. For example, if we were to create a context called "incoming" for incoming calls, we would define it like this:


				[incoming]
				

All of the instructions placed after a context definition are considered part of that context, until another context is defined.

At the very beginning of the extensions.conf file, there is a special context called [globals]. The globals context is where certain settings can be defined that can be used throughout your dialplan. For right now, we won't use the [globals] context, but you should be aware of why it exists.


Extensions

Within each context, we will define one or more extensions. Extensions determine how the call flows. Although extensions can be used to specify phone extensions in the traditional sense (i.e. Please call John at extension 153), they can be used for more than that in Asterisk. In our extensions.conf file, an extensions is declared by the word "exten", followed by an arrow formed by the equal sign and the greater-than sign like this:


				exten =>
				

This is followed by the number (or name) of the extension, a comma, the priority, another comma, and finally the application we'd like to call on the channel. We'll explain priorities and applications next, but first let's finish covering the syntax. The syntax looks like this:


				[context-name]
				exten => extension,priority,application
				


Priorities

Priorities are numbered steps in the execution of each extension. Each priority calls one specific application. Typically these priority numbers simply start at 1 and increment consecutively for each line in the context. Priority numbers aren't always consecutive, but we'll worry about that later.


Applications

Applications perform certain actions on a voice channel, such as playing sounds, accepting touch-tone input, or hanging up the call. Options called arguments can be passed to applications to effect how they perform their actions. To see a listing of the possible applications that are built into Asterisk, see Appendix C. As we build our first dialplan below, you'll learn to use applications to your advantage.


A Simple Example

Now we're ready to create our first extensions.conf file. Because this is our first step, we'll start with a very simple example. We'll assume for this example that all Asterisk needs to do is to answer the channel, play a sound file that says "Goodbye", and then hang up. We'll use this simple example to point out the fundamentals of creating a dialplan.


The special 's' extension

Before we get too far into our example, we need to cover a special extension called 's', which stands for "start". By default, calls will start in a context's 's' extension. (You can think of 's' as the extension that gets automatically executed.) In our example, we'll start by creating a dialplan with this 's' extension.


The Answer(), Playback(), and Hangup() functions

If we're going to answer the call, play a sound file, and then hang up, we'd better learn how to do just that. The Answer() application is used to answer a channel which is ringing. This does the initial setup for the call so that we can perform other functions. A few applications don't necessarily require that we Answer() the channel first, but it is a very good habit to properly Answer() the channel before doing anything else.

The Playback() function is used for playing a previously recorded sound file over a channel. When using the Playback() function, input from the user is simply ignored. If you need to accept input during playback, use the Background() function. Asterisk comes with many professionally recorded sound files which are often found in /var/lib/asterisk/sounds/. Playback() is used by specifying the filename (without a file extension) as the argument. For example, Playback(filename) would play the sound file called filename.gsm, located in the default sounds directory.

The Hangup() function does exactly as it's name implies; it hangs up an active channel. You would use this at the end of a context once you want to drop a caller who no longer needs to be connected to the system.


Our First Dialplan

Now we're ready to start our first example dialplan. Please pay attention to the way that each priority calls an application. Note that in this example, we only have one extension. In later examples we'll add other extensions, and show how to move from one extension to another.

Note

The following examples are not meant to be completely working and usable. We are simply using these examples to explain how dialplans work. For these examples to work, you should have already configured some Zap channels (using a Devkit from Digium, for example), and configured those channels so that incoming calls go to the [incoming] context.

After showing our first example, we'll explain each step.


			[incoming]
			exten => s,1,Answer()
			exten => s,2,Playback(vm-goodbye)
			exten => s,3,Hangup()
			

When a call is sent into this [incoming] context, it will first go to 's' extension. As we learned earlier, calls usually begin in the 's' extension. We have three priorities in this context, numbered 1, 2 and 3. Each priority calls a particular application. Let's take a closer look at these three priorities.

Our first priority calls the Answer() application. Asterisk then takes control of the line and sets up the call. After answering the line, Asterisk goes on to the next priority. In our second priority, we call the Playback() application. This will play a sound file as specified by the filename. In our example we will play the file vm-goodbye. The caller will hear a voice say "goodbye". Notice that there is no filename extension. Asterisk will automatically determine the extension of the sound file. In our third and final priority line, we call the Hangup() function and thus end the call.


A more useful example

Now that we've gone through a simple example, let's build upon it by learning about the Background() and Goto() applications. These two applications will allow us to create dialplans with much more functionality.

The key to interactive Asterisk systems is the Background() application. It gives you the ability to play a recorded sound file, but when the caller presses a key it interrupts the playback and goes to the extension that corresponds with what the caller dialed.

Another very useful application is called GoTo(). As its name implies, it jumps from the current context, extension, and priority to the specified context, extension, and priority. The GoTo() application makes it easy to programatically move between different parts of the dialplan. The syntax for the GoTo() application calls for us to pass the destination context, extension, and priority as arguments to the application, like this:


			exten => extension,priority,Goto(context,extension,priority)
			

In this example, let's assume we've been asked by a local movie theater to create an interactive system where callers can dial in and listen to pre-recorded movie listings. To make this example simple, we'll say that the movie theater only has two screens.

We'll also assume that we have three pre-recorded sound files. The first, called current-moves.gsm, says "Welcome to our movie theatre. To hear what's playing on screen one, press one. To hear what's playing on screen two, press two." The other two sound files, named movie1.gsm and movie2.gsm respectively, tell the caller the information about the movie playing on that particular screen.

Note

We'll cover recording sound files later in this chapter.


			[incoming]
			exten => s,1,Answer()
			exten => s,2,Background(current-movies)
			exten => s,3,Hangup()
			exten => 1,1,Playback(movie1)
			exten => 1,2,Goto(incoming,s,1)
			exten => 2,1,Playback(movie2)
			exten => 2,2,Goto(incoming,s,1)
			

Lets go through this example step by step. When the call enters the system, Asterisk executes the 's' extension automatically, starting with priority one. You may notice that the 's' extesion looks almost identical to our first example. The difference is the use of the Background() application instead of Playback(). With Background() we are able to accept digits from the caller while the sound file is being played. While the current-movies.gsm file is being played to the caller, lets say the user presses 1. Asterisk will then look for an extension in our current context that matches it. When Asterisk finds the '1' extension, it will execute all the priorities for that extension.

Now that the user has pressed '1', Asterisk can perform both priorities for extension 1. The first priority for extension 1 will use the Playback() application to play the movie details for screen one. After the file finishes playing, it will execute the second priority, which is a call to the Goto() application.

Remember that Goto() allows us to send the caller somewhere else in our dialplan. In our example exten => 1,2,Goto(incoming,s,1) we will send the user back to the first priority of the 's' extension in our current context.

If the user doesn't press a key before the Background() application finishes playing the file, the third priority of our 's' extension will be performed, hanging up the user. This is probably not the best way to handle incoming calls, but gives us a good example of how we can manipulate calls.

If the caller presses 2, then the sound file for movie screen number two is played, and then the caller is sent back to the 's' extension.

As you can see, it's quite simple to create interactive dialplans (often referred to as auto-attendants or voice menus) in Asterisk. In less than ten lines, we've been able to create a dialplan that could really be used. Now let's add additional functionality.


The Dial() application

We are going to add to our movie theater example by showing the use of the Dial() application. If someone presses 0 during playback it will ring the ticket office. We are going to assume that the channel for the ticket office has already been setup. For examples of how to setup channels see Chapter 3.


			[incoming]
			exten => s,1,Answer() ; Answer the line
			exten => s,2,Background(current-movies) ; Play back the 'current movies' sound file
			exten => s,3,Hangup() ; Now hangup the line if the caller doesn't press a key
			exten => 1,1,Playback(movie1) ; Now hangup the line if the caller doesn't press a key
			exten => 1,2,Goto(incoming,s,1) ; Now go back to the beginning
			exten => 2,1,Playback(movie2) ; Now hangup the line if the caller doesn't press a key
			exten => 2,2,Goto(incoming,s,1) ; Now go back to the beginning
			exten => 0,1,Dial(Zap/1)
			

Our example has stayed the same except for the addition of another extension to our [incoming] context. We have added a 0 extension which will then execute the Dial application. The Dial() application allows us to call a specified interface using the format of [technology]/[resource]. In this instance we are calling the first channel on our Zaptel interface, which probably has attached to it a telephone and an operator to answer the phone.

By this point in the chapter you should understand the use of several applications such as Answer(), Playback() , Background(), Hangup(), GoTo() and the basics of Dial(). If you are still a little unclear of how these work, please go back and read this section again. The basic understanding of these applications is essential to fully grasp the concepts which will be explored further.


Adding Additional Functionality

Asterisk has the ability to ring multiple phones for the same call. Using the Dial() application we simply add an ampersand (&) between the two or more channels we wish to ring. In our following example we are going to show how the Dial() application can ring multiple interfaces at the same time. This would allow you to answer the incoming channel at either one of the ringing interfaces.


Adding another FXS port


			[incoming]
			exten => s,1,Answer() ; Answer the line
			exten => s,2,Playback(welcome) ; Play back the 'welcome' sound file
			exten => s,3,Dial(Zap/2&Zap/3) ; Dial both channels Zap/2 and Zap/3
			

We are using the 's' extension in our example which as we know allows these commands to be executed automatically. Our first priority will answer the line, the second priority will playback the welcome message. The Dial() application uses an ampersand (&) to build a list of channels (Zap/2 and Zap/3 respectively) which ring concurrently during an incoming call.


Creating Voice Menus

With Asterisk we have the ability to very simply develop custom IVR systems. IVR is an acronym for "Interactive Voice Response" which can be defined as an automated call handling system where a user interacts with a computer controlled voice system using either human recorded or TTS (text-to-speech) prompts which are interacted with through a touch tone phone.

You would recognize this as any system where an auto-attendent attempted to route your call to an appropriate department by asking you to "Press 1 for Sales, Press 2 for Parts or Press 0 to speak with an Operator".


Accepting User Input With The Background() Application

The Background() application allows us to play a pre-recorded file to a user while allowing us to accept input from the user before the file has finished playing. This is different from the Playback() application which will not accept input from the user until the entire file has finished playing. What Background() allows us to do is build a list of options into a single file, which we will call a "menu", to give a user calling our system multiple options. When a user hears the option they wish to use, they can press the appropriate button on their touch tone phone and they will be directed to that extension immediately.


Adding a Voice Menu

Now that we understand what an IVR is and how the Background() application differs from that of Playback() , we can use them in our following example to demonstrate their use within Asterisk.


			[incoming]
			exten => s,1,Answer() ; Answer the line
			exten => s,2,Playback(welcome) ; Play back the 'welcome' sound file
			exten => s,3,Background(menu) ; Play 'menu' file and accept input from caller
			exten => 1,1,Dial(Zap/2) ; Dial channels Zap/2 if the user dials 1
			exten => 2,1,Dial(Zap/3) ; Dial channels Zap/3 if the user dials 2
			

After we Answer() the channel, we Playback() the 'welcome' sound file which will not accept any input from the user - they are forced to listen to the entire file. After the 'welcome' message finishes we execute the Background() application to play out 'menu' file. While this is being played to the user, Asterisk will wait for input and will execute any applications which match the extension numbers being dialed. In the above example, if either 1 or 2 are pressed by the user, they will be redirected to either channel Zap/2 or Zap/3 respectfully.


Handling Calls Between Internal Users

[Explain that we're going to add a second context, and use it for calling between internal extensions.]

So far we have limited ourselves to a single context for incoming calls. It is probably fair to assume that most installations will have more than one extension, and that we would want to call between them. For this we can create a new context called [internal]. This context will contain the extension numbers and what channel to associate with that number. The following example demonstrates that we can associate different extension numbers to the same channel name in different contexts. We assume that these extensions are configured to have access to the [internal] extension in their own configuration file.


			[incoming]
			exten => s,1,Answer() ; Answer the line
			exten => s,2,Playback(welcome) ; Play back the 'welcome' sound file
			exten => s,3,Background(menu) ; Play 'menu' file and accept input from caller
			exten => 1,1,Dial(Zap/2) ; Dial channels Zap/2 if the user dials 1
			exten => 2,1,Dial(Zap/3) ; Dial channels Zap/3 if the user dials 2

			[internal]
			exten => 1001,1,Dial(Zap/2) ; Dialing extension 1001 calls channel Zap/2
			exten => 1002,1,Dial(Zap/3) ; Dialing extension 1002 calls channel Zap/3
			

The above example shows that incoming calls to the [incoming] context can dial Zap/2 by selecting the option "1" from our menu. However we would like to standardize the internal extensions with 4 digit numbers. As we can see, any extension with access to the [internal] context can access the Zap/2 and Zap/3 channels via extension 1001 and 1002 respectfully.


Variables

Variables can be used for many things. They can be used to help reduce typing, or they can be used to limit looping in an error condition too long. When using the value of a variable, you denote it with a dollar sign and the variable name surrounded by curly braces.

There are two types of variables, namely global variables and call variables. As their names imply, global variables apply to all extensions, while call variables only apply to the current call in progress.

Note

The terms arguments and variables are often interchanged to mean the same thing. For our purposes we are going to make a firm distinction between the two. Arguments are values passed to the built in applications to tell them what to do. Variables are named places where data that may change is held. They can either be used by the user or, much more frequently, by Asterisk itself.


Global Variables

Global variables are denoted using the form VARIABLE_NAME=value. Global variables are useful as they allow us to use them within our dialplan to make it more readable, along with only requiring us to change the the value in a single place instead of multiple places, helping to reduce the number of possible errors.


Call Variables

It is also possible to do simple expressions. These expressions are evaluated when placed within square brackets. Expressions are used to either combine values together via addition, subtraction, multiplication, or division.

[example of some simple variable expressions]

For more information on using expressions with variables, see the README.variables file that comes with the Asterisk source code.


Adding Variables

[Take our Widgets Inc. example and add variables for ${RECEPTIONIST}, etc.]


			[global]
			RECEPTIONIST=Zap/2 ; Assign 'Zap/2' to the global variable ${RECEPTIONIST}
			JOHN=Zap/3         ; Assign 'Zap/3' to the global variable ${JOHN}

			[incoming]
			exten => s,1,Answer()
			exten => s,2,Playback(welcome)
			exten => s,3,Background(menu)
			exten => 1,1,Dial(${RECEPTIONIST}) ; Dial the channel assigned to ${RECEPTIONIST}
			exten => 2,1,Dial(${JOHN}) ; Dial channel assigned to ${JOHN}

			[internal]
			exten => 1001,1,Dial(Zap/2) ; Dialing extension 1001 calls channel Zap/2
			exten => 1002,1,Dial(Zap/3) ; Dialing extension 1002 calls channel Zap/3
			


Macros


What are Macros?

Macros are used to reduce the amount of redundent code in the dialplan. This works by allowing you to pass arguments to the macro which then perform a certain set of actions which you specify. Once you have defined your macro and the actions you wish it to perform, you can call it at any time within your dialplan with a single line.


Attributes of Macros

Macros are identified in the dialplan by starting a context name with "macro-". The 's' extension is used within macros since we want the actions to be performed automatically when we call them. Information is passed to the Macro as arguments such as ${ARGn} where 'n' is the argument number.


Adding Macros to our Dial Plan

As an example lets show how you can use a macro to limit the number of lines which are required to setup a new extension.


			[macro-stdexten]
			exten => s,1,Dial(${ARG1},20)
			exten => s,2,Voicemail(u${MACRO_EXTEN}
			exten => s,3,Hangup
			exten => s,102,Voicemail(b${MACRO_EXTEN})
			exten => s,103,Hangup
			

Our simple macro above Dials an extension as supplied by the argument ${ARG1} which is defined when we call the macro. If after 20 seconds the line is not picked up, we go to our second priority which calls Voicemail using the extension number that called the macro (as defined by ${MACRO_EXTEN}). Once voicemail has completed, the call is Hungup. If the line was busy when the Dial application was executed, the macro would jump n+101 priorities to priority 102. The Voicemail application would then be executed, playing the busy message for the extension which called the macro as defined by ${MACRO_EXTEN}.


			[default]
			exten => 1000,1,Macro(stdexten,SIP/1000)
			

The macro is called using the 'Macro' application. The format for calling a macro is Macro(<macro_name>,<ARG1>,<ARG2$gt;,<ARGn>). As we can see in our example, we are calling the 'stdexten' macro with the argument 'SIP/1000'. SIP/1000 is then used in the stdexten macro where you see ${ARG1}. The ${MACRO_EXTEN} is a predefined local variable which passes the extension number calling the macro. In our example above this would be extension 1000 as defined in the [default] context.

Some other local variables you can use in macros include:

${MACRO_CONTEXT} - The context of the extension which calls the macro
${MACRO_PRIORITY} - The priority which the macro was called from
${MACRO_OFFSET} - When complete, return to priority n + ${MACRO_OFFSET}


Jumping Between Priorities Based on Call Status

Asterisk is able to jump to different priorities based on the status returned from Dial(). Using the ${DIALSTATUS} local variable we can perform different actions based on the returned status message. Valid status messages include NOANSWER, BUSY, CHANISUNAVAIL, CONGESTION and ANSWER. We can modify our stdexten macro above to demonstrate how this works.


			[macro-stdexten]
			exten => s,1,Dial(${ARG1},20)
			exten => s,2,Goto(s-${DIALSTATUS},1)
			exten => s-NOANSWER,1,Voicemail(u${MACRO_EXTEN})
			exten => s-NOANSWER,2,Goto(default,s,1)
			exten => s-BUSY,1,Voicemail(b${MACRO_EXTEN})
			exten => s-BUSY,2,Goto(default,s,1)
			exten => s-.,1,Goto(s-NOANSWER,1)
			exten => a,1,VoicemailMain(${MACRO_EXTEN})
			

We can assume that we are going to call the macro using the same example as above (exten => 1000,1,Macro(stdexten,SIP/1000)). Our first line of this macro example will Dial() SIP/1000 for 20 seconds. After the Dial() command has completed the status of the call is saved in the variable ${DIALSTATUS}.

On the second line we use a Goto() statement to jump to the associated extension. The format for the extension name is "s-${DIALSTATUS}" where ${DIALSTATUS} is equal to NOANSWER, BUSY, CHANISUNAVAIL, CONGESTION or ANSWER. If our Dial() command rings for 20 seconds without an answer, the ${DIALSTATUS} variable will contain NOANSWER. The s-NOANSWER extension will then execute all available priorities in order starting with the Voicemail() command (line 3) and play the unavailable message. The second priority of the s-NOANSWER extension will execute a Goto() statement if the user presses "#" before Voicemail hangs up the line. Similarily the busy voicemail message will be played if a ${DIALSTATUS} of BUSY is returned.

The second last line of our macro is a catch all statement. The period (.) after the s- means to match anything that is returned. If neither NOANSWER or BUSY are returned, then we will assume a NOANSWER and execute the Goto() statement. This will send us to the s-NOANSWER extension, which as explained earlier, will execute Voicemail and play the busy message.

Our last line is another new extension type. The 'a' extension will execute if the user presses the asterisk (*) key while the unavailable or busy message is being played. When the asterisk key is pressed, it will execute the VoicemailMain() application and send it to the ${MACRO_EXTEN}. What this essentially does is send the user to their mailbox and prompts them for a password (if configured to require a password). This allows the user to check their voicemail without requiring them to login to a separate extension.


Call Flow


Pattern Matching

[Explain the ${EXTEN} variable, along with the ${EXTEN:i:j} syntax] [Example of a simple "outbound" context]

In extensions.conf we are not limited simply to numbers. We are able to match patterns of numbers to control our call flow. To do this we start an extension "number" with an underscore symbol (_). Asterisk recognizes certain characters to interpret special meaning when doing a pattern match. These characters include:

X - matches any digit from 0-0
Z - matches any digit from 1-9
N - matches any digit from 2-9
[1237-9] - matches any digit or letter in the brackets (ex. 1,2,3,7,8,9)
. - wildcard match which matches one or more characters


Pattern Sort Order

When creating your patterns take note that the order in which you add them to your extensions.conf is not necessarily the order in which they are executed. Asterisk will sort your extensions in numerical order followed by alphabetical order. Lets use an example to show how this works.


			[sort-order]
			exten => _1NXX.,1,Dial(SIP/${EXTEN})
			exten => _1800.,1,Dial(SIP/${EXTEN})
			exten => _.,1,Dial(SIP/${EXTEN})
			exten => t,1,Hangup
			

We can check the order in which Asterisk sorted this example by doing a show dialplan sort-order.


			*CLI>  show dialplan sort-order
			[ Context 'sort-order' created by 'pbx_config' ]
                          '_.' =>           1. Dial(SIP/${EXTEN})                         [pbx_config]
                          '_1800.' =>       1. Dial(SIP/${EXTEN})                         [pbx_config]
                          '_1NXX.' =>       1. Dial(SIP/${EXTEN})                         [pbx_config]
                          't' =>            1. Hangup()                                   [pbx_config]
			

As we can see the order is different than that which we placed in our extensions.conf. To control the order in which Asterisk will sort the pattern matching we have to use includes. When using an include the extension entries within the context are sorted first followed by the included extensions. The includes are then tested in the order which you add them to the context.

The following example shows how we can move the wildcard pattern (_.) to the end of the sort order.


			[sort-order]
			include => sort-order-wildcard
			exten => _1NXX.,1,Dial(SIP/${EXTEN})
                        exten => _1800.,1,Dial(SIP/${EXTEN})
                        exten => t,1,Hangup

			[sort-order-wildcard]
			exten => _.,1,Dial(SIP/${EXTEN})
			


			*CLI>  show dialplan sort-order
			[ Context 'sort-order' created by 'pbx_config' ]
                          '_1800.' =>       1. Dial(SIP/${EXTEN})                         [pbx_config]
                          '_1NXX.' =>       1. Dial(SIP/${EXTEN})                         [pbx_config]
                          't' =>            1. Hangup()                                   [pbx_config]

                          Include =>        'sort-order-wildcard'                         [pbx_config]
			
As we can see, the sort-order-wildcard has been moved to the end of our dialplan. This allows us to control the order in which Asterisk will sort our exten lines.


Linking Contexts with Includes

[How to do it] [Order of includes count! Explain why...] [Time-sensitive includes] [OK, now let's "include" the "outbound" context inside of the "internal" context]


The other special extensions (i,t,o,h,fax,???)

's' - start
'i' - invalid
't' - timeout
'h' - hangup
'T' - Absolute Timeout

The start extension is for most calls that are initiated with no other known information.

Hangup is where calls will go to when hangup is detected, or where you can send calls that you want to hangup on.

Warning

There are currently some problems to be aware of when using the 'h' extension. Specifically, the variables about the call are lost as the information is destroyed with the channel.

Timeout is for when a user is presented with a menu and they do not respond. In the timeout extension you will want to decide if you wish to repeat your menu, or just send the call to a hangup so as to free up the line.

Invalid is for when Asterisk has determined that the input from the call is not valid for the current context. You may wish to play a prompt explaining the extension was invalid, and then send the call back to the extension that contains the menu prompts.

Absolute Timeout is a used when a call is being terminated for exceeding an Absolute Timeout variable set. Be aware of the case difference from the normal timeout. This can be used to warn a user that they exceeded some allowable limit. Or it could be used to request someone to try calling back later if they waited in a queue too long. Essentially it should notify the caller that they are being disconnected so as not to leave them with the impression they had been cut off unintentially.


Advanced Dial Plan Concepts


Modules, or "Things that make Asterisk work."

The Power of Asterisk lies in its modules: applications (app_), channel drivers (chan_), ressources (res_) and much more. The modules are what provides Asterisk with the features, that you use: zap, iax, sip and h.323 telephony, call parking, voicemail, conference bridges etc.

You will very soon see, that most configuration files used for Asterisk are tied together with these modules and we will go through them, while describing the features that each module brings with it.

But let's start with the basics, you will have to define, which modules you want to load:


Core Asterisk configuration


Defining file locations (asterisk.conf)

The asterisk.conf configuration file is used to tell Asterisk where to locate various things for run time.


			[directories]
			astetcdir => /etc/asterisk
			astmoddir => /usr/lib/asterisk/modules
			astvarlibdir => /var/lib/asterisk
			astagidir => /var/lib/asterisk/agi-bin
			astspooldir => /var/spool/asterisk
			astrundir => /var/run
			astlogdir => /var/log/asterisk
			

The above configuration is the default that comes with Asterisk. It lists 7 locations of files that Asterisk looks for while running.

astetcdir points to the folder which holds all the configuration files.

astmoddir reflects the path of all the compiled Asterisk modules.

astvarlibdir is where all the Asterisk database and sound files are stored.

astagidir is the location where Asterisk will attempt to load AGI applications from.

astspooldir includes the location where all outgoing call files are stored as well as voicemail. For more informatoin on call files, see chapter 7.

astrundir point to where the pid files for Asterisk's processes are stored.

astlogdir refers to the location of all the Asterisk log files.


The Dialplan (extensions.conf, see chapter 4 and 5)

extensions.conf is not described in this chapter, because that is where you build your dialplan and the size and complexity of extensions.conf would go beyond the limits of this chapter. We have dedicated extensions.conf a chapter of it's own.


Modules


Digium Zaptel Cards (chan_zap)

chan_zap handles zaptel telephony devices like all newer Digium's cards, ISDN cards based on the HFC chipsets with zaphfc or qozap and alike.


zaptel.conf

This configuration file will most likely be found in /etc and not together with the other Asterisk configuration files. It defines which zaptel interfaces you have installed in your system, what dialtone these cards should use, depending on your country, and how many channels should be utilised.

First of all you should decide what dialtone your system should give the users:


				loadzone=us
				loadzone=uk
				defaultzone=us
				

The configuration example above loads the indication tones typical for the US and the UK. Available zones are: au, at, cl, es, fi, fr, gr, it, jp, nl, no, nz, tw, uk, us, us-old. These are all defined in zonedata.c in the Asterisk sourcetree. The defaultzone option defines, which tonezone should be used, if nothing else is defined.

Next we should define what kind of cards we have in the system. Let's start with two TDM400P cards, where one has 2 FXO modules and the other 6 ports are FXS ports.


				fxsks=1-2 ; FXO ports, card 1
				fxoks=3-8 ; FXS ports, card 1+2
				

You could also have one of the FXO modules on each card:


				fxsks=1,5 ; FXO ports, card 1+2
				fxoks=2-4 ; FXS ports, card 1
				fxoks=5-8 ; FXS ports, card 2
				

The order of the channels depends on which order the cards are in loaded in and what order the modules are sitting on the TDM400P. Notice that the options allways are reverse: fxsks for FXO ports and fxoks for FXS ports. That is the way it should be. There are three options for each type of interface (fxs and fxo): fxsls, which is fxs signaling with loopstart, fxsks, which is fxs signaling with koolstart and fxsgs, which is fxs signaling with groundstart. The same applies for fxols, fxoks and fxogs. The different types are telling the zaptel driver, if you telephone line tells you, that the other side has hung up or not. Some pstn lines, some not.

Loopstart

Loopstart does not include hangup notification unless specifically done through forward-disconnect.

Groundstart

Groundstart does include hangup notification.

Koolstart

Koolstart is also known as Disconnect Supervision, and is what you usually want to have for FXO devices. If your phone provider doesn't support that, the FXO device will basically not detect that the other side has hung up and Asterisk will try to continue servicing the port. If you can't get your Telco to give you Disconnect Supervision on your line there are possibilities to work around that. This can be done with some options in zapata.conf, but we will get to that.

Next in our journey through zaptel.conf we are getting to spans, which covers cards like the HFC-based cards and Digiums T1 and E1 cards. A span definition is in the following format:


				span=(spannum),(timing),(LBO),(framing),(coding)[,(crc)]
				

spannum tells more or less itself: which span are we talking about, there might be multiple, which you configure one by one.

timing tells how you want to syncronize the timing of the spans. '0' tells, that you don't want to use this span as sync source, '1' tells, that it is the primary sync source and '2' tells, that it is the secondary sync source.

LBO stands for "Line Build Out". It can be taken from the following table:

0: 0 db (CSU) / 0-133 feet (DSX-1)
1: 134-266 feet (DSX-1)
2: 267-399 feet (DSX-1)
3: 400-533 feet (DSX-1)
4: 534-655 feet (DSX-1)
5: -7.5 db (CSU)
6: -15 db (CSU)
7: -22.5 db (CSU)

framing and coding define how you will communicate with the hardware at the other end of the line. Here the values that fit for different line types:

T1 - framing is one of d4 or esf, coding is one of ami or b8zs
E1 - framing is one of cas or ccs, coding is one of ami or hdb3. E1's spans may also need to enable crc checking. That would be crc4 for crc

Let's take an example how a Digium T100P (one port T1 card) would look like:


				span=1,1,0,esf,b8zs
				bchan=1-23
				dchan=24
				

span defines the span as primary syncsource, 0 db (CSU), esf framing and b8zs coding. This is probably the most likely configuration that you will see. Channels 1-23 are B channels (data, voice, etc.) and channel 24 is used for signaling.

Another example with a TE410P, 4 E1 spans:


				span=1,1,0,ccs,hdb3,crc4
				span=2,0,0,ccs,hdb3,crc4
				span=3,0,0,ccs,hdb3,crc4
				span=4,0,0,ccs,hdb3,crc4
				
				bchan=1-15,32-46,63-77,94-108
				dchan=16,47,78,109
				bchan=17-31,48-62,79-93,110-124
				

This is a bit more complicated as you can see. We have 4 spans here, span 1 is the sync source, the spans use ccs framing and hdb3 coding, beyond that they are also configured for crc. Channels 1-15 and 17-31, 30 channels in total, on each span are configured as B channels (data, voice, etc.). Channel 16 is allways the D channel used for signaling. This setup is what you see on a DSS1 PRI, the most common ISDN protocol used in Europe. One note for the TE410P (and TE405P of course) should be added: If you configure it, run ztcfg to initialize the card and it comes up and complains about channel 97 then you have forgot to set the jumpers to E1 on the card.

Last but not least a example for a BRI interface using a HFC based ISDN card:


				span=1,1,3,ccs,ami
				bchan=1-2   
				dchan=3
				span=2,1,3,ccs,ami
				bchan=4-5   
				dchan=6
				

The span entries are needed, but actually only dummies, they are not really interpreted by Asterisk. You will however have to define, that you have two B channels and one D channel on each card.

Once the configuration in zaptel.conf has been changed, you should run ztcfg to reinitialize your zaptel hardware and then restart asterisk after that. For having ztcfg run on boot, you should add the following to your modules.conf:


				post-install wct4xxp /sbin/ztcfg
				

wct4xxp should be replaced with the zaptel module that is loaded as the last one, which ever that is.


ISDN CAPI (chan_capi)

To use chan_capi you must have support for CAPI and your ISDN card in your kernel configuration. You will have to check with your vendor to see if your particular card is supported, but Linux has good support for ISDN cards, so most likely it will. Cards such as Eicon and AVM are known to work with Asterisk. However it can be a bit tricky to get CAPI support working for different ISDN cards. chan_capi only provides TE mode, you can only use it for connecting your asterisk box to a ISDN line, not connect phones internally to the ISDN card. Also have a look in the chapter about "Building additional modules" which will give you a good idea, what cards can be used, where you can download kernel drivers for these and how you get them to work. Once that is done, you can continue with this section and configure chan_capi.

This is a list of the features implemented in chan_capi:

  • ISDN connection handling (CID,DNID)

  • multiple controller support

  • digital audio support

  • DTMF detection/generation

  • incoming/outgoing calls

  • CLIP/CLIR

  • early B3 connects

  • native ISDN indications

  • CD, HOLD, RETRIEVE, etc.

  • overlap sending (dialtone)

  • DID on point-to-point (PTP)

  • call progress (INFO_IND)

  • RX/TX gains

  • call deflection on circuit busy

chan_capi is a third party module, that has to be downloaded seperatly from Asterisk. It can be downloaded at: http://www.junghanns.net/asterisk/.


capi.conf

The configuration of capi based devices is fairly straight forward. The first section we need to edit is [general]. section.


				[general]
				nationalprefix=0
				internationalprefix=00
				rxgain=0.8
				txgain=0.8
				

nationalprefix and internationalprefix define which prefix Asterisk should add in front of the caller-id on incoming calls. ISDN works like this; the caller-id is transferred without the prefix and there is a special indicator, on call setup, what kind of call we are talking about. Since Asterisk does not differenciate between different countries, and the prefix can be different from country to country, this can be set here. For example, the international prefix in North America is "011", but in most European countries it is "00". rxgain and txgain allow you to adjust the receiving and transmitting gain (volume) respectfully. These numbers are in decibals (dB) so only adjust in small incremements. Setting these too high will cause Asterisk to produce echo on the channel.

Next up is the [interfaces] section. This section defines which capi interfaces you want to add to Asterisk and which numbers are available. ISDN can be configured two ways: Point to Multi-Point (PMP) or Point to Point (PtP). Here is a typical PMP setup:


				[interfaces]
				msn=2043986,2043987
				incomingmsn=*
				controller=1
				devices=2
				softdtmf=1
				accountcode=
				context=default
				callgroup=1
				;mode=immediate
				;deflect=12345678
				;echosquelch=1
				;echocancel=yes
				;echotail=64
				

msn specifies which MSNs (or DIDs) you want to use for outgoing calls. There is a limitation of up to 5 MSNs, but usually it is enough to specify one of them. You can set the MSN you want to show on outgoing calls by setting the ${CALLERIDNUM} variable in your dialplan. On incomingmsn you can specify, which MSNs Asterisk should react on. A "*" tells Asterisk to react on any call, no matter what MSN it has.

With controller you specify what controller you are configuring. You can have more than one controller in your system and all can be configured individually. devices tells chan_capi how many b-channels your ISDN card can handle. softdtmf=1 will use Asterisk's dsp functions to detect and generate the DTMF tones. softdtmf=0 will use your capi controller to do the detection/generation. Unless you have an active card you should use softdtmf=1.

accountcode is for billing purposes. context defines which context chan_capi should send incoming calls from the ISDN card to. callgroup defines which callgroup the controller is a member of. You can have several controllers in the same callgroup, that then would react in the same way. If mode is set to immediate, the ISDN card answers the call and immediatly passes it on to Asterisk. The default behavior would be, that you need to answer the call in your dialplan.

deflect defines a phone number that you automatically want to deflect calls to if both b-channels on your ISDN card are busy. Deflect on busy has to be enabled during compile, if you want that feature to work.

echosquelch, echocancel and echotail are values, that you normally need not to change. If you are dealing with echo issues, it might be an idea to try testing different values here.

The typical PtP setup would look like this:


				[interfaces]
				isdnmode=ptp
				msn=20439
				controller=1
				devices=30
				softdtmf=0
				accountcode=
				context=default
				callgroup=1
				

The options for a Point to Point setup are basically the same as for the PMP setup. msn now only holds the prefix of your msn, the suffix will be transferred to Asterisk as an extension. isdnmode=ptp tells chan_capi, that the card is to be run in Point to Point mode (Default would be Point to Multi-Point mode). All other values are to be configured the same way with Point to Multi-Point mode.


mISDN (chan_mISDN)

Features at a glance:

  • TE and NT mode (NT mode is currently only supported on HFC based cards)

  • PTP and PMP mode

  • DTMF detection

  • display text messages on isdn phones with alphanumeric display

  • utilizes new isdn4linux mISDN architecture in *

chan_mISDN is a third party channel module, that has to downloaded seperatly. It can be found at: http://www.beronet.com/?PageID=3017.


Voicetronix Cards (chan_vpb)


vpb.conf

vpb.conf holds the configuration for the VoiceTronix line of OpenLine and OpenSwitch hardware. The VoiceTronix hardware can be either FXO or FXS channels, depending on how the card is set up. The OpenSwitch 6 OpenSwitch 12 have 6 or 12 respective Loop-Start (FXO) or Station (FXS) user-configurable analogue ports. The OpenLine 4 has 4 Loop-Start (FXO) ports.

All of the options in the configuration file are shown in the example configuration file that comes with the driver. The one configuration file can handle all of the voicetronix cards/boards in the machine.


				[general]
				cards = 1
				type = v6pci
			
				[interfaces]
				board = 1
				echocancel = on
				callerid = on
				context = default
				txhwgain = 6
				rxhwgain = -3
				txgain = 12
				rxgain = 6
				mode = fxo
				channel = 1
				channel = 2
				channel = 3
				;channel = 4
				;mode = fxs
				;channel = 5
				;channel = 6

				board = 2
				echocancel = on
				callerid = on
				context = default
				txhwgain = 6
				rxhwgain = -3
				txgain = 12
				rxgain = 6
				mode = fxo
				channel = 1
				channel = 2
				channel = 3
				;channel = 4
				;mode = fxs
				;channel = 5
				;channel = 6
			
				

The general section allows you to make settings that affect all boards, as well as define the number of boards (cards),of the same type, in the machine. The type variable setting lets you define the card types that are in the system, valid entries are: v4pci (OpenLine 4) and v12pci (OpenSwitch 6 and 12). The cards variable is the number of VoiceTronix cards in the server.

The interfaces section contains the information about the specific cards in the system. The interfaces section is broken up by board variables. Everything from a board = line to the next board = line is considered part of that board definition. The echocancel variable can be turned on (or off) to effect echo cancellation. This can compensate for lower quality lines when working with a channel in FXO mode. The callerid variable can be turned on for the detection of callerid data on the FXO channels of a card. The context variable is the Asterisk context that incoming calls will be put into. This should point to a context that can answer incoming calls. The txhwgain rxhwgain variables control the amount of gain on the transmit and recieve volumes that is performed in the hardware DSP. The txgain and rxgain variables control the amount of gain on the transmit and recieve volumes performed in software. The channel variable is used to define the existance of a particular channel. If channels 1, 2, and 3 are available on an OpenSwitch 6 card, the above example will work.

Card configurations of 0 FXS and 6 FXO, 2 FXS and 4 FXO, 4 FXS and 2 FXO, 6 FXS and 0 FXO are available for the OpenSwitch 6. Configurations of 0 FXS and 12 FXO, 4 FXS and 8 FXO, 8 FXS and 4 FXO, 12 FXS and 4 FXO are available on the OpenSwitch 12. These must be setup with onboard jumpers before Asterisk can use them. For more information about how to configure the OpenLine and OpenSwitch cards please refer to the driver documentation that comes with the card.


Defining IAX Channels and connections (chan_iax & chan_iax2)


iax.conf

iax.conf holds the basic configuration for IAX and all the accounts, that * uses to communicate with other voip services over IAX. IAX is one of the VoIP protocols, that * can handle.


Defining SIP Channels and connections (chan_sip)


sip.conf

sip.conf holds the basic configuration for SIP and all the accounts, that * uses to communicate with other voip services over SIP. SIP is one of the VoIP protocols, that * can handle.


rtp.conf

The SIP protocol uses port 5060 for control messages between the two talking end points. However the RTP audio stream comes over a different range of ports which need to be opened on any firewall, or forwarded to any NAT'd Asterisk box. This can be configured in the rtp.conf file located in /etc/asterisk/.

By default Asterisk will accept RTP messages in the range of 10000 through 20000. Many people may not need this large of a range, and very well may not want to open that many ports on their firewall. If you want to change the range that Asterisk will listen for the RTP stream on, you simply need to change the start and stop range. The following is the default example that comes with the sample configuration files


				; RTP Configuration
				[general]

				; RTP start and RTP end configure start and end addresses
				rtpstart=10000
				rtpend=20000
				

rtpstart is the first port that Asterisk will accept RTP data on and rtpend is the last port that Asterisk will accept RTP data on. Simply change these values to suit your needs.


Defining H.323 channels and connections (chan_h323)

This channel module is part of the Asterisk CVS tree now. It uses the Asterisk RTP stack and implements H.323 in one shared library.


asterisk-oh323, or another way of getting H.323 connectivity (chan_oh323)

This was the first channel module available to Asterisk, that implemented H.323. It simulates a pseudo soundcard implementation to pass audio from Asterisk to the Open H.323 stack.


Configuring E.164 lookups (app_enumlookup)


enum.conf

enum.conf is used for configuring Enum. Enum is a telephony technology which allows users of disparate networks and technologies to call each other through the use of a common routing database. This database is DNS records on a centralized server. This technology is discussed in depth in chapter 7.


Voicemail (app_voicemail)


voicemail.conf

The voicemail subsystem of asterisk is a powerful tool, able to send emails on the receipt of voicemail, cope with different timezone for different users and even do voicemail virtual hosting.

Voicemail is configured using the voicemail.conf file in the /etc/asterisk directory by default. A simple example is shown below.

voicemail.conf


				[general]
				format=wav|wav49|gsm
				serveremail=root@localhost
				attach=yes
				maxmessage=180
				maxgreet=60

				[default]
				2000 => 4321,Jeffery Alterton,jeff@example.com
				

This is about as simple as you can get for the voicemail system, setting up a single mailbox and sending an email with the message attached when a voicemail is left.

In the dial plan voicemail would be ran using something like one of the following examples.

extensions.conf


				[default]
				exten => 2000,1,Answer  ; answer the channel
				exten => 2000,2,Dial(SIP/2000,16,tr)  ; dial channel supplied by ${ARG1}
				exten => 2000,3,Voicemail(u2000) ; if no answer, goto unavailable vm
				exten => 2000,4,Hangup  ; hangup the channel
				exten => 2000,103,Voicemail(b2000)  ; if the channel is busy, goto busy vm
				exten => 2000,104,Hangup  ; hangup the channel
				

In this example if extension 2000 is dialled then the call is answered and extension 2000 is dialed over sip (see the [2000] section of sip.conf) if the call fails due to being unavailible then it continues running at the next step which in this example is the voicemail system with an unavailible message. If the call fails due to being busy the flow jumps to priority n+101 (2+101 in this example see the section on the extensions.conf file for more details) and starts running from there. Which in this example is voicemail with a busy anouncement. In both cases after voicemail is finished the call is hung up.

To access your voicemail you need a different application. This application is called VoicemailMain and is shown in the example below.


				exten => 1000,1,Answer
				exten => 1000,2,VoicemailMain()
				exten => 1000,3,HangUp
				

Now when the user dials extension 1000 they will be prompted to enter their voicemailbox and pin and dropped into the voicemail system to listen to messages.

VoicemailMain can also take the mailbox number to drop them into requesting only a pin in this case.


				exten => 1000,1,Answer
				exten => 1000,2,VoicemailMain(${CALLERIDNUM})
				exten => 1000,3,HangUp
				

This example would detect the extension the caller is coming from and drop them into the voicemail system.


Conferencing (app_meetme)


meetme.conf

MeetMe is the Asterisk conferencing application, allowing multiple parties to all be part of the same phone call. It can be configured many ways, for example one person talking and many listening or as a many to many conference. It is possible to give certain users the ability to try to control the conference with the admin functions.

It is generally controlled via the dial plan using two applications. MeetMe and MeetMeCount, and requires a timing source to be present in the system being used. ztdummy works fine for this and it is not necessary to use a zaptel card. However, ztdummy does not provide as reliable or scalable timing as a hardware interface, so use with caution.

MeetMeCount returns the number of people active in a certain conference. MeetMe is much more complex in that it can take many options allowing privleges and abilities to be granted or taken away to users. For example you could have two extentions, one allowing the speaker to enter the room with a password and the ability to address the conference and another only allowing people to listen with no password.

This could be done as follows:

in extensions.conf


				[conference]
				exten => 51000,1,MeetMe(1000|tp|1234) ;speaker can speak and can exit with the press of #
				exten => 1000,1,MeetMe(1000|mq) ;listeners can only recieve audio from the conference and when joining or leaving wont produce sound.
				

and in meetme.conf


				[rooms]
				conf => 1000
				

The options are as follows (accurate as of 2004-05-30):

'm' -- set monitor only mode (Listen only, no talking)
't' -- set talk only mode. (Talk only, no listening)
'p' -- allow user to exit the conference by pressing '#'
'd' -- dynamically add conference
'D' -- dynamically add conference, prompting for a PIN
'e' -- select an empty conference
'E' -- select an empty pinless conference
'v' -- video mode
'q' -- quiet mode (don't play enter/leave sounds)
'M' -- enable music on hold when the conference has a single caller
'x' -- exit the conference if the last marked user left
'b' -- run AGI script specified in ${MEETME_AGI_BACKGROUND}
's' -- Present menu (user or admin) when '*' is received ('send' to menu)
'a' -- set admin mode

You can also get this list by typing 'show application meetme' within the asterisk shell.

meetme.conf simply lists all the staticly generated conferences in asterisk in the form:


				conf => 1000
				conf => 1000,1234
				

where the first number is the conference number and the second is the deafult password for the conference.


Call Parking (app_parkandannounce)


parking.conf

The parking.conf file controls the extension numbers for call parking. Call parking allows a caller to be placed into an extension where you can retrieve the call from any other phone attached to Asterisk. This is done by transfering the user to the "call parking" extension. Once transfered to that extension, Asterisk will announce the extension that the call can be retrieved from.

For example, lets say John Smith calls Company XYZ and asks for Jane Doe. Instead of transfering the call to a specific extension, you could place the caller into call parking where Asterisk will tell you which extension the call has been placed into. You could then announce over a PA system for John Smith to call that extension number where he could retrieve the call no matter where he was in the building.

The following is an example parking.conf configuration:


				[general]
				parkext => 501 ; What ext. to dial to park
				parkpos => 502-520 ; What extensions to park calls on
				
				context => parkedcalls ; Which context parked calls are in
				
				parkingtime => 45	; Number of seconds a call can be parked 
				for (default is 45 seconds)
				
To park a call you will press '#' to transfer the caller to an extension. parkext is the configurable extension number to dial in order to park the caller. Once parked, Asterisk will announce the extension which the caller has been parked in. This will be in the range specified by parkpos. Parked calls are placed into the context defined by context. This allows you to use things like Music On Hold (MOH) for your parked callers. parkingtime is the timeout time that the caller will be left parked until the original extension from where the call was parked will ring to tell the operator that the call has not been un-parked yet.


The Asterisk Cookbook


Scripting with the Asterisk Gateway Interface (AGI)

What is AGI?

Asterisk supports advanced scripting with an interface known as AGI. AGI allows your dial plans to do things such as query an external database, lookup weather reports, etc. that would normally be impossible without writing your own application for Asterisk.


What languages can I use?

With AGI scripting, Asterisk passes data to your script via STDIN, and your script passes information back via STDOUT. Arguments passed to the agi() application within Asterisk appear like command line arguments to the script. Because of this, AGI scripting can be done in almost any language, just like CGI scripts.

Commonly used AGI scripting languages include C, Perl, Python, and PHP.


AGI Basics

Communication between the AGI script and Asterisk is accomplished through the standard input, output, and error file descriptors of the AGI script. At initialization, Asterisk sends several important pieces of initialization information to the AGI script. This data needs to be read before any commands are passed to Asterisk; otherwise, it will not be available.

Table 1. Initialization Data

NameSample ValueExplanation/Notes
agi_accountcode123Set by SetAccount in the dialplan
agi_callerid2128675309Remember, this may not always be a number
agi_channelSIP/1001-6476 
agi_contextdefault 
agi_dnid2890Dialed Number Identifier. More likely will show up as "unknown"
agi_enhanced0.0Value is 1.0 if started as an EAGI script
agi_extension100 
agi_languageen 
agi_priority1 
agi_rdnis2494The current referring DNIS number from the Zaptel ISDN subsystem.
agi_requestmyagi.agi???
agi_typeSIPCould also be ZAP, H323, etc.
agi_uniqueid1077328545.0Note that uniqueids are based on Unix time.

Commands are passed to Asterisk in the format [command] <arg1> <arg2> ... <argn>. A list of available commands may be fetched with the Asterisk Console command show agi.

The standard error channel can be used to send messages to the Asterisk console. The test AGI scripts included with Asterisk contain an example of this behavior.


Language-specific AGI notes and examples

Specific examples for languages can be found at http://home.cogeco.ca/~camstuff/agi.html.


Perl

Perl's propensity for data manipulation and quick scripting make it a very popular choice for AGI scripting. To make Perl AGI programming even easier, James Golovich created Asterisk::AGI, a module designed for simplifying AGI interaction. Asterisk::AGI is available from the author's web page at http://asterisk.gnuinter.net/.

Without using Asterisk::AGI, this is what a simple AGI script to tell a user their phone number would look like.


			#!/usr/bin/perl -w
			
			use strict;

			$|=1;
			
			#Get the initial data
			my %input;
			while(<STDIN>) {  
			        chomp;
			        last unless length($_);
			        if (/^agi_(\w+)\:\s+(.*)$/) {
		                	$input{$1} = $2;
		        	}
			}

			print "stream file the-number-is";
			print "say digits $input{callerid}";
			print "exec WaitMusicOnHold 2";
			print "hangup";
			
Note the $| set to force a buffer flush after each print.

Using Asterisk::AGI, we can simplify the previous script a bit:


			#!/usr/bin/perl -w

			use strict;
			use Asterisk::AGI;
			
			$AGI = new Asterisk::AGI;
			my %input = $AGI->ReadParse();  #Read in the initial data
			
			$AGI->stream_file('the-number-is');
			$AGI->say_digits($input{callerid});
			$AGI->exec('WaitMusicOnHold','2');
			$AGI->hangup();
			


Advanced Asterisk Configuration

Agents and the Asterisk ACD

Asterisk provides a flexible call queuing system suitable for call center applications. The Asterisk ACD system utilizes several components, which work together to provide a very robust implementation.


Queues

Call queues are used to route calls in a first-in-first-out manner to the appropriate extensions. These extensions can be agents logged into the system or any other type of channel supported by the system. Various strategies can be used to determine how calls are routed from a queue, these strategies are used to implement fair distribution of workload within a call center, and can be customized through the use of priority levels to fit an organization's policies.

Queues are configured using the queues.conf configuration file.


				; Example queues.conf file for asterisk.
				[general]
				; There are no global settings for queues.

				[default]
				; Default settings are presently unimplemented.


				[support]
				;Which music on hold context (defined in musiconhold.conf) do we wish to use?
				;music = default

				; Announcement to be played to an agent answering a call.
				; This is intended so that agents that are members of more than one queue can
				; determine how to greet callers.
				;announce = queue-support

				; A strategy may be specified.  Valid strategies include:
				;
				; ringall - ring all available channels until one answers (default)
				; roundrobin - take turns ringing each available interface
				; 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

				; The strategy determines how calls will be routed to members of a queue.
				; The default is ringall, which will ring all queue members until a call
				; in answered. Alternatives are:
				; random - ring random queue members until answered.
				; roundrobin - ring each member in turn until answered.
				; leastrecent - ring the member least recently called from this queue.
				; fewestcalls - ring the member with the fewest calls from this queue.

				;strategy = ringall

				; Escape context.
				; If this context is specified, callers can leave the queue by dialing a single
				; digit extension within that context.
				;context = qoutcon

				; How many seconds can the phone ring before we consider it a timeout?
				;timeout = 15


				; How long should asterisk wait between attempts to route a queued call?
				;retry = 5

				; How many callers do we allow to wait in queue? (0 for no limit)
				;maxlen = 0

				; Queue members.
				; Queue members can be any kind of channel supported by Asterisk.
				; Agent channels are generally preferred, as they provide login/logout functionality.

				; Agent number 1000 (agents are defined in agents.conf)
				member => Agent/1000

				; A SIP telephone.
				member => SIP/supportdesk

				; Any agent in group 1 (agent groups are defined in agents.conf)
				member => Agent/@1

				; Agent 2000 is a supervisor that is capable of taking calls, but should only do so
				; when no other agents are available, so we consider with a penalty.
				member => 2000,4


			

Agents

Agents are type of "virtual" channel specifically designed for use with ACD. While agent channels can be utilized directly from extensions.conf, they are most useful as members of an ACD queue. Agents are defined in the agents.conf file.


				; Example agents.conf for asterisk.

				[agents]
				; Automatic log-off if an agent rings for too long, in seconds. 
				; This is not useful for AgentLogin, because calls are automatically
				; answered.
				;autologoff=15

				; FIXME - how does this work.
				;ackcall=yes
				; How much wrap up time (also known as After Call Work time) do 
				; agents get.
				;wrapuptime=5000

				; What music-on-hold class do agents listen to between calls?
				;musiconhold => default

				; Group memberships (these can be redefined before each agent definition or
				; group of definitions)
				;group=3
				;group=1,2
				;group=

				; Agent definitions in the form agent => agentid,agentpassword,name
				group=1
				agent => 1001,4321,Bastard Operator From Hell
				agent => 1002,4321,Pimply Faced Youth
				group=2
				agent  => 2000,4321,Pointy Haired Boss

			

Distributed Asterisk (Clustering/TDMoE)


TDMoE (Time Domain Multiplexing over Ethernet)

To use TDMoE you MUST have a zaptel interface configured somewhere on the network. It can be any zaptel interface, doesn't have to be a E400P, an X100P will do. Why? Timing. Samples. Something like that. Just do it. Of course a dummy ZAP interface like ztdummy or ztrtc might work, but I haven't tried it as yet. If somebody has please do update this.

What is TDMoE?

Well, we all know Ethernet right? Its probably the most popular network infrastructure on Layer2 that the IP world knows. Time-division multiplexing (TDM) puts multiple data streams in a single signal by separating the signal into many segments, each of a short duration (timing). Each individual data stream is reassembled at the receiving end based on this timing.

The circuit that combines signals at the source (transmitting) end of a communications link is known as a multiplexer. It accepts the input from each individual end user, breaks each signal into segments, and assigns the segments to the composite signal in a rotating, repeating sequence. The composite signal thus contains data from multiple senders. At the other end of the long-distance cable, the individual signals are separated out by means of a circuit called a demultiplexer, and routed to the proper end users. A two-way communications circuit requires a multiplexer/demultiplexer at each end of the long-distance, high-bandwidth cable. But, in TDMoE, * serves as the mux/demux. Lets look at the how the configuration is done first, and then do a practical example.

The configuration to define a dynamic span (TDMoX) basically entails FOUR parameters. Look at the sample config from zaptel. Its got an example in it, ala:


				# Next come the dynamic span definitions, in the form:
				# dynamic=<driver>,<address>,<numchans>,<timing>
				#
				# Where <driver> is the name of the driver (e.g. eth), <address> is the
				# driver specific address (like a MAC for eth), <numchans> is the number
				# of channels, and <timing> is a timing priority, like for a normal span.
				# use "0" to not use this as a timing source, or prioritize them as
				# primary, secondary, etc.  Note that you MUST have a REAL zaptel device
				# if you are not using external timing.
				#
				# dynamic=eth,eth0/00:02:b3:35:43:9c,24,0
				

  • First you define the driver (which is eth for Ethernet)

  • Second is the driver dependent address (REMOTE NIC MAC address)

  • Third is the number of channels to be configured

  • And, lastly, what sort of timing to provide

Timing Notes: 0 for no timing, 1 for primary, 2 for secondary, the difference is that it uses the primary to turn the zaptel gears unless it's in alarm, in which case it will take from the secondary and so on.

The driver is generally "eth" since currently we don't have any other TDMoX drivers, although FireWire would be very very nice. [kram]

The address is

<eth interface>/<macaddress>[/subaddr]

The sub address is optional, and allows you to define more than one span on a single eth interface / mac address pair

By configuring this, you end up with a new span, similar to how the T1/E1 spans configured for the E/Tx00P cards. Access to the channels configured above is via /etc/asterisk/zapata.conf.

You can configure signalling and all just as though they were T1's or E1's, so you can run RBS or you can run PRI or whatever, they even generate RED and YELLOW alarm just like real T1's and E1's. We're still debating whether you can run CCS on it.

You do NOT need to configure a specific span=blah,blah in zaptel.conf for this, the dynamic span definition will take care of that.

Remember that TDMoE works at the Ethernet layer, all you need to configure is MAC addresses and Ethernet interfaces.... so in theory you could TDMoE over 802.11 (low-cost last mile) or CIPE (encrypted PRI), the possibilities are limitless (well as limitless as csmacd can get)... IP does not come into play here at all...

-- SIMPLE 2 MINUTE EXAMPLE #1 --

suppose, if i have two * boxen running... lets say merry and pippin...

merry has an X100P in it and a NIC, pippin just has a NIC

in merry zaptel.conf we have --------


				fxsls=1                                 # this be the X100P
				dynamic=eth,eth0/00:D0:B7:89:E3:86,30,0 # put the MAC of pippin NIC here
				e&m=2-31                            # you can use ANY signalling
				

in pippin zaptel.conf we have --------


				dynamic=eth,eth0/00:50:FC:65:33:A1,30,1		# note the timing "1", merry's mac
				e&m=1-30					# same signalling as merry
				

from this point on its like any of the friendly zaptel channels we're already used to....

in merry zapata.conf we have ----------


				signalling=em
				channel=>2-31
				

in pippin zapata.conf we have ---------


				signalling=em
				channel=>1-30
				

load the appropriate modules, ztcfg on merry, zttool, you should have RED in the alarms.... and a dynamic span configured (not up, but configured)

do the same on pippin, bingo, the alarms should turn to OK, and you have the zap channels available for use....


				[root@pippin ~]$ lsmod
				Module                  Size  Used by    Tainted: P
				ztd-eth                 4032   0  (autoclean) (unused)
				ztdynamic               8544  30  (autoclean) [ztd-eth]
				zaptel                177088  60  [ztdynamic]
				ppp_generic            27392   0  [zaptel]
				slhc                    6844   0  [ppp_generic]
				

This listing is with Asterisk running, and zapata using the channels. If you got this far, you're good to go.

Enjoy... and mail any samples, suggestions, improvements... always welcome

Hail Asterisk !

TODO: multiple Ethernet cards (local and remote), other signalling examples, dummy eth driver to loopback test, caveats, benefits of TDMoE, comparison of various signalling, cook dinner


ENUM/E164 Call Routing (LCR)

Introduction

ENUM is a telephony technology that may single-handedly create the greatest changes in both Internet telephony as well as regular telephone service. In a nutshell, ENUM is a technology which allows users of disparate networks and technologies to call each other through the use of a common routing database. This database is stored in DNS records on a centralized server.


				5.4.3.2.1.enum.fierymoon.com.     NAPTR   100 10 "u" "E2U+IAX2" "!^\\+(.*)$!iax2:guest@127.0.0.1/\\1@local!" .
			

Figure 1. A sample ENUM entry in a DNS record

In the above figure, the record would be parsed by an ENUM compatible system to read "Phone number 12345 is to be redirected to iax2:guest@127.0.0.1/12345@local" All of the weird mumbo jumbo in the lines is important - they're called Regular Expressions and it's a topic too big to be covered in this documentation.


Making ENUM Work for You

Imagine you're the phone company, and you want to offer a new service that allows a single phone number (say, your home number) to ring multiple phones at once. With ENUM, this is painfully simple. You would simply create multiple ENUM entries for the same number, and increment the priority in the NAPTR line (For hints on how NATPRs work, check the BIND/DNS documentation.)

For most users, though, ENUM has an even more useful implication: Free long distance calling over the Internet. Take http://enum.fierymoon.com , a production ENUM registry and database. By simply adding what exchanges your system can call locally, suddenly people from all over the world can utilize your Asterisk system to make calls that would otherwise cost an arm and a leg.

As an example, let's take John Q. Public, who's recently moved to India to follow a tech job. He has family back in Seattle that he wishes he could talk to on a daily basis. Before, he would have to have either an expensive calling card, or some other home brew solution for point-to-point Internet dialing. Now, with the beauty of ENUM, John can use enum.fierymoon.com with his hobby asterisk box to see if there is an ENUM entry in Seattle. Let's say that John Smith has a T1 in Seattle and seldom uses it after hours - he can set up his ENUM records to let everyone who uses the ENUM database utilize his local calling area. Suddenly John Q. is making his calls to family and friends for only the cost of his Internet connection.


Setting up ENUM Routing on your Asterisk System

ENUM is a relatively easy item to setup on your asterisk system. If you're looking to dial out, it's as simple as using the EnumLookup application with a properly configured enum.conf (examples below.) If you're looking to be an endpoint of ENUM (i.e., if you'd like to donate some of your phone service to someone in need) then there is just a bit more work to be done.


enum.conf

This configuration file is blindingly simple. It has but one directive type, "search". Let's say you've got five separate ENUM sources you'd like to look up from, you'd simply list them in individual search lines:


					
					; ENUM Configuration for resolving phone numbers over DNS
					;
					
					[general]
					
					;
					; The search list for domains may be customized.  Domains are searched
					; in the order they are listed here.
					;
					
					search => enum.fierymoon.com
					search => e164.org
					search => e164.arpa
				

Figure 2. enum.conf

Remember to restart when you change this file, or else the changes will not be immediately accepted.

A little clarification here: enum.fierymoon.com and e164.org are ENUM/E.164 services, that allow anybody to add their records to the database and maintain them. They more or less were created out of the situation, that the official ENUM registry based on the e164.arpa domain is getting implemented painfully slow and will in many countries not be accessible for updates by individuals.

e164.org for an example took the step of calling you up on any telephone number that you add to their registry, giving you a pinkode, that you need to enter on the website to enable your personal enum records for your regular landline or cellphone. That way nobody can hijack phonenumbers, that he hasn't access to.

enum.fierymoon.com is quite interesting because this ENUM service maintains records of gateways that allow free access to toll free numbers.


extensions.conf

Once you've changed your enum.conf file, it is just a matter of adding some extensions to allow you to dial on ENUM:


					[enumcheck]
					exten => _41NXXNXXXXXX,1,EnumLookup(${EXTEN:1})
					exten => _41NXXNXXXXXX,2,Dial(${ENUM})
					exten => _41NXXNXXXXXX,3,Hangup
					exten => _41NXXNXXXXXX,102,Hangup
				

Figure 3. extensions.conf (snippet)

In this example, the user would dial 4 followed by the number they were attempting to call (This extension example utilizes NANPA numbers, i.e., North America, only.) The EnumLookup application stores the correct URL to dial in the ${ENUM} variable if the lookup succeeds.


Configuring your System to Allow ENUM Calls through your PSTN Interface

Allowing users to dial out of your PSTN interface is quite a noble thing to do! However, you'll want to protect yourself to make sure your nobility is not exploited for someone else's gains! Hopefully in this section you will understand the necessity of protecting your phone bill.

There are a few steps involved in setting up your dial-out ENUM configuration:

  1. Decide which technology you will use for allowing phone calls, be it IAX2, SIP, H323, or any other technology that can be formed into a URI.

  2. Find a list of local exchanges that you can call and keep it handy - you will need it later.

  3. Configure your iax.conf, sip.conf, h323.conf, or any other configuration files that will require modifications for the particular protocol you are intending to interface.

  4. Configure your extensions.conf to have a context specifically for allowing ENUM dial-out.

  5. Add the local exchanges that you found into your astdb so that you can look them up with your extension.

(As a note, I believe that Asterisk only supports IAX2 and SIP as well as PSTN for the URIs ENUM will return - I cannot be 100% sure of this so anyone in-the-know is free to correct me) In our examples, we will be using an IAX2 user for receiving our calls.


iax.conf


					[enumuser]
					type=user
					context=enumloc
					callerid="Enum Lookup" <000>
					disallow=all
					allow=ilbc
					accountcode=enumuser
				

Figure 4. Sample iax.conf configuration for an enum user

Our IAX user setup is pretty simple. All this user needs to do is allow calls into our ENUM outbound context. In this example, I have limited the only available codec to iLBC, so I can cut down on bandwidth consumed in the process. I've also assigned an account code of enumuser, so that when I pull my CDR records I can see who's using the ENUM.


extensions.conf


					[enumloc]
					exten => _1NXXNXXXXXX,1,SetVar(enumok=0)
					exten => _1NXXNXXXXXX,2,ODBCget(enumok=${EXTEN:1:3}/${EXTEN:4:3})
					exten => _1NXXNXXXXXX,3,GotoIf(${enumok}?4:900)
					exten => _1NXXNXXXXXX,4,ChanIsAvail(Zap/1)
					exten => _1NXXNXXXXXX,5,Dial(Zap/1/${EXTEN})
					exten => _1NXXNXXXXXX,6,Hangup
					exten => _1NXXNXXXXXX,105,Playback(enum-inuse)
					exten => _1NXXNXXXXXX,106,Hangup
					exten => _1NXXNXXXXXX,900,Congestion
				

Figure 5. Sample extensions.conf logic for inbound calls

This extension takes a little bit of explanation (There's a lot going on here, so pay attention!) First of all, we initialize a local variable, ${enumok} to 0. This allows us to have a default variable in case our astdb lookup returns nothing. Priority two does the actual astdb lookup. It's pretty simple, it asks whether the area code and prefix are in the astdb database - if they are, great, priority three makes processing continue at step four. If they are not, then they are played a congestion tone at priority 900. At step 4, we ask whether our only FXO device, Zap/1, is in use. If it isn't, we do the dialing required to complete the call. If our Zapata device is in use, we playback the file "enum-inuse" and then hangup.

Now, some of you must be wondering - "How do I get my extensions into the astdb?" Well, that's a hard question to answer, unless you are using ODBCget as opposed to DBGet. I'll give you a bit of a hint here:


					<?
					        $fp=fopen("./lpref","r");
					        while (!feof($fp))
					        {
					                $line=fgets($fp);
					                list($npa,$nxx,$desc,$zone) = split(";", $line, 4);
					                echo "INSERT INTO \"astdb\"
				                        (\"astfamily\",\"astkey\",\"astvalue\")
				                        VALUES('".$npa."','".$nxx."','1');\n";
					        }
					        fclose($fp);
					?>
				

Figure 6. How to create SQL insert queries from a standard NANPA CO/CLEC list

After a reload of asterisk, your box should be ready to receive calls via IAX2 with user name "enumuser", with calls bound to context "enumloc" - your lookups should make sure the call is local to you, and then pass it along.


Databases and Asterisk


CDR - Call Data Records

Call data records can be stored in many different databases or even CSV text.


MSSQL

Asterisk can currently store CDRs into an MSSQL database two different ways: cdr_odbc.c or cdr_tds.c

Call Data Records can be stored using unixODBC (which requires the FreeTDS package) [cdr_odbc.c] or directly by using just the FreeTDS package [cdr_tds.c] The following provide some examples known to get asterisk working with mssql. NOTE: Only choose one db connector.


ODBC [cdr_odbc.c]

Compile, configure, and install the latest unixODBC package:


					tar -zxvf unixODBC-2.2.9.tar.gz &&
					cd unixODBC-2.2.9 &&
					./configure --sysconfdir=/etc --prefix=/usr --disable-gui &&
					make &&
					make install
					

Compile, configure, and install the latest FreeTDS package:


					tar -zxvf freetds-0.62.4.tar.gz &&
					cd freetds-0.62.4 &&
					./configure --prefix=/usr --with -tdsver=7.0 \
					     --with-unixodbc=/usr/lib &&
					make &&
					make install
					

Compile, or recompile, Asterisk so that it will now add support for cdr_odbc.c


					make clean &&
					make update &&
					make &&
					make install
					

Setup odbc configuration files. These are working examples from my system. You will need to modify for your setup. You are not required to store usernames or passwords here.

/etc/odbcinst.ini


					[FreeTDS]
					Description    = FreeTDS ODBC driver for MSSQL
					Driver         = /usr/lib/libtdsodbc.so
					Setup          = /usr/lib/libtdsS.so
					FileUsage      = 1
					

/etc/odbc.ini


					[MSSQL-asterisk]
					description         = Asterisk ODBC for MSSQL
					driver              = FreeTDS
					server              = 192.168.1.25
					port                = 1433
					database            = voipdb
					tds_version         = 7.0
					language            = us_english
					

Only install one database connector. Do not confuse asterisk by using both ODBC (cdr_odbc.c) and FreeTDS (cdr_tds.c). This command will erase the contents of cdr_tds.conf

[ -f /etc/asterisk/cdr_tds.conf ] > /etc/asterisk/cdr_tds.conf

NOTE: unixODBC requires the freeTDS package, but asterisk does not call freeTDS directly.

Setup cdr_odbc configuration files. These are working samples from my system. You will need to modify for your setup. Define your usernames and passwords here, secure file as well.

/etc/asterisk/cdr_odbc.conf


					[global]
					dsn=MSSQL-asterisk
					username=voipdbuser
					password=voipdbpass
					loguniqueid=yes
					

And finally, create the 'cdr' table in your mssql database.


					CREATE TABLE cdr (
					       [calldate]      [datetime]              NOT NULL ,
					       [clid]          [varchar] (80)          NOT NULL ,
					       [src]           [varchar] (80)          NOT NULL ,
					       [dst]           [varchar] (80)          NOT NULL ,
					       [dcontext]      [varchar] (80)          NOT NULL ,
					       [channel]       [varchar] (80)          NOT NULL ,
					       [dstchannel]    [varchar] (80)          NOT NULL ,
					       [lastapp]       [varchar] (80)          NOT NULL ,
					       [lastdata]      [varchar] (80)          NOT NULL ,
					       [duration]      [int]                   NOT NULL ,
					       [billsec]       [int]                   NOT NULL ,
					       [disposition]   [varchar] (45)          NOT NULL ,
					       [amaflags]      [int]                   NOT NULL ,
					       [accountcode]   [varchar] (20)          NOT NULL ,
					       [uniqueid]      [varchar] (32)          NOT NULL ,
					       [userfield]     [varchar] (255)         NOT NULL
					)
					

Start asterisk in verbose mode, you should see that asterisk logs a connection to the database and will now record every call to the database when it's complete.


TDS [cdr_tds.c]

Compile, configure, and install the latest FreeTDS package:


					tar -zxvf freetds-0.62.4.tar.gz &&
					cd freetds-0.62.4 &&
					./configure --prefix=/usr --with-tdsver=7.0
					make &&
					make install
					

Compile, or recompile, asterisk so that it will now add support for cdr_tds.c (Currently only asterisk CVS supports cdr_tds.c)


					make clean &&
					make update &&
					make &&
					make install
					

Only install one database connector. Do not confuse asterisk by using both ODBC (cdr_odbc.c) and FreeTDS (cdr_tds.c). This command will erase the contents of cdr_odbc.conf

[ -f /etc/asterisk/cdr_odbc.conf ] > /etc/asterisk/cdr_odbc.conf

Setup cdr_tds configuration files. These are working samples from my system. You will need to modify for your setup. Define your usernames and passwords here, secure file as well.

/etc/asterisk/cdr_tds.conf


					[global]
					hostname=192.168.1.25
					port=1433
					dbname=voipdb
					user=voipdbuser
					password=voipdpass
					charset=BIG5
					

And finally, create the 'cdr' table in your mssql database.


					CREATE TABLE cdr (
					        [accountcode]   [varchar] (20)          NULL ,
					        [src]           [varchar] (80)          NULL ,
					        [dst]           [varchar] (80)          NULL ,
					        [dcontext]      [varchar] (80)          NULL ,
					        [clid]          [varchar] (80)          NULL ,
					        [channel]       [varchar] (80)          NULL ,
					        [dstchannel]    [varchar] (80)          NULL ,
					        [lastapp]       [varchar] (80)          NULL ,
					        [lastdata]      [varchar] (80)          NULL ,
					        [start]         [datetime]              NULL ,
					        [answer]        [datetime]              NULL ,
					        [end]           [datetime]              NULL ,
					        [duration]      [int]                   NULL ,
					        [billsec]       [int]                   NULL ,
					        [disposition]   [varchar] (20)          NULL ,
					        [amaflags]      [varchar] (16)          NULL ,
					        [uniqueid]      [varchar] (32)          NULL
					)
					

Start asterisk in verbose mode, you should see that asterisk logs a connection to the database and will now record every call to the database when it's complete.


Auto-Dialout (Call Files)

Auto-Dialout is a feature that allows users to initiate calls through Asterisk. By placing files in /var/spool/asterisk/outgoing/, Asterisk can automatically initiate calls. Reported practical uses for call files include automated surveys and automated voicemail callbacks.

In general terms, call files specify an channel to call and an extension or application to connect with the called channel. All call files must have both to be valid. Call files also may specify call options such as Caller*ID or set local variables. Statements are made in format directive: arguments Here is a summary of available call file directives:

Table 1. Call File Directives

NameExplanation/Notes
Channel: <channel>Outbound channel
Callerid: <id>Caller*ID for outbound channel
Application: <application>Application to bridge outbound channel with. Arguments are passed with a Data directive. See note about CDR below.
Data: <data>The data to be passed to an application
MaxRetries: <integer>Number of times to retry outbound channel if it is busy or otherwise unavailable
Context: <context>Context for an extension to bridge the outbound call to
Extension: <extension>Extension in [<context>] to bridge to
Priority: <integer>The priority in <extension>@[<context>] to connect to.
RetryTime: <seconds>Time between retries
WaitTime: <seconds>How long to wait for an answer
Context: <context>Context for an extension to bridge the outbound call to
SetVar: <name=value>Set a variable for the connecting dialplan or application logic to use
Here is an example call file:

		Channel: Zap/1g/12125558910
		MaxRetries: 3
		RetryTime: 40
		WaitTime: 25
		Context: surveys
		Extension: 212 
		Priority: 1
		


Call File Caveats

There a few things to watch out for:


No CDR Data From Applications

If your call file directly connects to an application, and not an extension, no CDR data will be collected for that call. To circumvent this, just connect the call to an extension that starts the application.


Asterisk is Quick

When generating call files, create them in a staging directory and copy them into /var/spool/asterisk/outgoing/ when you are finished. Otherwise, Asterisk may grab a half-way completed call file.


Common Issues

Music on Hold/MP3 Playback

Before using Asterisk's Music On Hold feature, mpg123 and a timing system must be in place.


Proper Version of MPG123

Music on Hold requires mpg123. Note that mpg321, which is often linked to /usr/bin/mpg123, will not work. Additionally, mpg123 must be installed in /usr/bin.

Note

The latest release of mpg123 is mpg123 0.59r. The latest development release of mpg123 is mpg123 pre0.59s. Please use mpg123 0.59r. Using mpg123 pre0.59s can/may/will result in crashes and/or unreliable playback.

mpg123 can be downloaded from http://www.mpg123.de. Before compiling mpg123, change the line in the Makefile that reads


				PREFIX=/usr/local
			
to

				PREFIX=/usr
			
After making the change, mpg123 can be compiled as described in its documentation.


Timing: zaptel/ztdummy/zaprtc

Asterisk's Music On Hold application requires a timing source to work correctly. There are three possible timing sources that can be used:


Zaptel

The Zaptel drivers, which run Digium's Wildcard cards, can be used as a timing source. If you have a Zaptel card, there is no special setup needed other than loading the standard kernel module for the card. Simply set up the Zaptel interface as described previously in this guide.


ztdummy

ztdummy is a Zaptel driver designed for use as a timing source without having a Wildcard board. It uses the USB devices for timing, so the usb-ohci kernel module must be installed (lsmod can be used to check). ztdummy is included with the zaptel tree of Asterisk CVS. By default, however, it is not compiled. To enable the compilation of ztdummy, open the Makefile in zaptel source directory for editing. Find the line that reads


					MODULES=zaptel.o tor2.o torisa.o wcusb.o wcfxo.o wcfxs.o \
					        ztdynamic.o ztd-eth.o wct1xxp.o wct4xxp.o # ztdummy.o
				
and remove the # before 'ztdummy.o'. From there, run make and make install as usual. Before running Asterisk, you'll need to load the ztdummy driver by running modprobe ztdummy.


zaprtc

ztrtc uses the system clock rather than the USB subsystem to get timing information. Note, however, that ztrtc does not work on multiprocessor systems. ztrtc does not come with Asterisk but is available from http://www.junghanns.net/asterisk/.


Configuration File: /etc/asterisk/musiconhold.conf

The musiconhold.conf syntax is simple and similar to other Asterisk files. Here is a sample configuration file:


				[classes]
				default => quietmp3:/var/lib/asterisk/mohmp3
				nirvana => quietmp3:/usr/share/mp3/nirvana-music
				random-nirvana => quietmp3:/usr/share/mp3/nirvana-music,-z
				loud-nirvana => mp3:/usr/share/mp3/nirvana-music
			
In this example, the class default plays MP3s from the directory /var/lib/asterisk/mohmp3/ sequentially. Note the 'quietmp3' directive, which keeps the music at an appropriate volume for most telephony Music on Hold applications. The class nirvana is similar, but uses the directory /usr/share/mp3/nirvana-music/ instead. random-nirvana picks files in the directory randomly, instead of sequentially, due to the '-z' option at the end of the line. The final class, loud-nirvana does not reduce the volume of the output, due to 'quietmp3' being replaced by 'mp3'. The 'mp3' directive is useful for applications targeting the hearing impaired (as well as Nirvana fans).


Adding Music on Hold to the Dialplan

Adding Music on Hold to the dial plan is fairly straightforward and simple. Just add MusicOnHold(class) as you would Dial() or Voicemail(). For example:


				exten => 6789,1,Answer()
				exten => 6789,2,MusicOnHold(nirvana)
			


A Final Note on Choosing Music

In the United States and other countries, playing copyrighted music to strangers who call into your PBX (without a proper license) is illegal. However, high-quality, royalty free music does exist. An excellent source for it is http://www.openmusicregistry.org.

Licensing music from well-known artists is not terribly expensive, however. For sites with 10 or fewer incoming telco lines, a license from BMI (the largest licensor of popular music) can be had for a little less than $200 per annum. With this license, you may use any of BMI's 4.4 million songs for a Music on Hold application. More details are available at http://www.bmi.com.


DTMF over SIP

DTMF (Dual-Tone Multi-Frequency) is the name for the specific sounds ("dial tones") made by the keys on a telephone keypad. The choice of which method to use for DTMF over SIP is made in Asterisk's /etc/asterisk/sip.conf. Carrying DTMF over SIP can be done in one of three ways:


Inband

Inband DTMF is just as it sounds: the sound made by the key press sent in the audio channel where it is decoded by Asterisk (or whatever the termination point of the call is). Inband is only available on A-Law and Mu-Law codecs; it is generally bad practice to use Inband DTMF.


Info

The Info method sends SIP Info messages from phone to Asterisk with the text of the buttons pressed on the phone. SIP Info tends to be a better choice than Inband because the key-presses are sent textually, independent of the audio codec. Users of Grandstream phones should use Info for the Asterisk voicemail; the other methods won't work.


rfc2833

The rfc2833 method uses an RTP mode defined in RFC 2833 to transmit the DTMF digits. rfc2833 is similar to Info, but will not work on Grandstream phones.


SIP and NAT

On your router/firewall, you will need to open port 5060 and forward it to your Asterisk box to allow SIP messages through. You will then need to open and forward your RTP ports to allow audio through (the ports are configurable in rtp.conf. See chapter 3 for more information). The default RTP ports are the range of 10000 -> 20000.

In your sip.conf, you need to add three lines to your [general] context.


			[general]
			port=5060 		; make sure you have this line
			externip=my.domain.com	; this can be either external IP address, or FQDN
			localnet=192.168.0.0/mask	; local network your Asterisk server is in, plus network mask.
			


Message Waiting Indication

SIP phones that support a message waiting indicator (such as a stuttered dial tone or a flashing light) can be associated with a voicemail box. In sip.conf, just add a line like


		mailbox=1234
		
You can associate more than one mailbox with a SIP phone for a message waiting indication by separating the voice mail box numbers with commas:

		mailbox=1234,9999
		

If a mailbox to be checked is not in the default context in voicemail.conf you must explicitly provide the context as in


		mailbox=1000,2000@smokers,2001@drinkers
		
Where mailbox 1000 is in default, 2000 is in a voicemail.conf context called smokers and 2001 is in the context called drinkers.


Echo Cancellation Issues

Introduction

One of the dirty truths about Asterisk is that if you do not configure your Zaptel hardware correctly, you will at one time or another experience serious echo issues with connecting VoIP lines to the PSTN. Thankfully, Asterisk has some pretty useful methods for taking care of echo.


			#KFLAGS+=-DECHO_CAN_STEVE
			#KFLAGS+=-DECHO_CAN_STEVE2
			#KFLAGS+=-DECHO_CAN_MARK
			KFLAGS+=-DECHO_CAN_MARK2
			#KFLAGS+=-DECHO_CAN_MARK3
		

Figure 1. Zaptel Makefile compile options

In Figure 7-1, you can see there are several options for echo cancellation. Commenting out all but one of these lines is required. If you'd like to use the MARK3 echo canceler, for instance, you'd comment out the MARK2 line and uncomment the MARK3 line.

All four of the echo cancelers will do a mediocre to good job of taking care of echo, but it takes a little while for Asterisk to properly adjust. If you use the MARK2 canceler, there's an additional option:


			#KFLAGS+=-DAGGRESSIVE_SUPPRESSOR
		

That can be added for additional echo cancellation. Aggressive suppression works well, but can make the conversation sound scratchy in the beginning.


Echo Training

Now, thanks to the efforts of Brian West and the other Asterisk gang, we now have a feature in Zaptel called Echo Training. Echo training, in my experience, works the best out of all of the echo cancelers.


			[channels]
			echocancel=yes
			echocancelwhenbridged=yes
			echotraining=yes
			rxgain=8.2
			txgain=1.0
			signalling=fxs_ks
			channel=1
			

Figure 2. zapata.conf echo training definition for FXO channel

Echo training is enabled with two separate sets of settings - first of all, make sure you have echocancel=yes, echocancelwhenbridged=yes, and echotraining=yes. These are the first steps to effective cancellation. There is another important setup consideration that you should follow: properly adjusting your rxgain/txgain.


Adjusting the rxgain/txgain Settings

In order to adjust txgain/rxgain properly, you need to use the ztmonitor application to check the power of your audio signal as a call is in progress. The steps for tuning rxgain/txgain are as follows:

  1. Set default values of rxgain/txgain to 1.0

  2. Initiate a call that flows out of your Zapata device.

  3. Look at the ztmonitor visualization (explained below) to see whether the audio is in optimal condition.

  4. If it is not optimal, increase or decrease the txgain/rxgain levels accordingly.

Most people find that they need an rxgain level around 8.0 to have good echo cancellation. The txgain setting varies from installation to installation.


				astpbx1:/usr/src/pbx/zaptel# ./ztmonitor 1 -v
				Rx############                 Tx#####################
			

Figure 3. ztmonitor output

In the above output, we see a text-based VU meter showing the relative power of the audio source. The Rx channel is right where we want it, so the rxgain setting you have in your configuration is good. The Tx level, however, is pegged all the way to the end of the screen (use your imagination), in which case the audio is doing something called "over deviation" - it's the same thing that happens when people get too close to a microphone and the audio is crackly. When this occurs, the echo canceler cannot compensate for the signal as well since it is busy receiving artifacts of the audio that "spill" back into the channel. In this case, we want to lower the txgain level a bit.

Most people who configure echo training correctly will never hear echo in their calls again. The echo canceler works nearly instantaneously in echo training mode.


How to politely use the Asterisk IRC channel

Asterisk power users and developers are often found conversing and socializing in the #asterisk channel of the freenode IRC network. There are some common guidelines that will help you get your questions answered.

  1. Don't be discouraged if someone does not immediately answer your questions. Sometimes questions will not be answered if a simple Google search can solve your issue.

  2. Please do not repeat your question multiple times in a short time frame. This is an easy way to annoy many of the users in the channel. If someone does not acknowledge you within 5 minutes of your query, it is safe to ask your question again. Do not be obnoxious about it, though.

  3. A lot of the users in the channel run professional consulting companies that request payment in exchange for help. Do not be discouraged by this; it is free market capitalization and is for the good of the Asterisk community. If you do not wish to pay for quality support, that is fine; many people will not answer your questions, however. Usually, if you're willing to pay for support, let it be known early on and your chances of receiving quality support will increase.

  4. The normal rules of Internet etiquette apply: please do not use ALL CAPS (which indicates yelling), do not use excessively foul language directed at another person in the channel, and overall, please behave. Being rude and obnoxious will only serve to get you ignored quickly.


Creating Asterisk Applications in C


Sources of Additional Information


Connecting Asterisk to Common VoIP Providers


Free Service Providers

Free World Dialup (FWD)


Description

Free World Dialup is a free SIP Directory Service.


Services

  1. Voicemail

  2. Toll free access to the US, UK, Netherlands and France

  3. Conferencing

  4. Free subscription to a direct phoneno. in the US (Washington, IPKall) and UK (National rate, CallUK)

  5. PSTN access numbers in Germany, the Netherlands, UK and different states of the U.S. enables you to call any FWD subscriber from any regular phone.

This is only a limited list of what they provide you with. FWD also interconnects with a couple of other directory services like iConnectHere, IAXTEL, Intertex, IPTel and NIC.at


What to Expect

FWD is in general very stable and developing their services all the time, remember however that FWD not is a commercial service. Also they don't offer you any possibility to call PSTN no's beyond the access to toll free numbers.


Setup Examples

First the way, how you can connect Asterisk to FWD by using SIP. This is the common setup used, since the IAX gateway is fairly new and considered beta.

Example 1. sip.conf


							register => 12345:password@fwd.pulver.com
							
							[fwdnet]
								type=friend
								secret=password
								host=fwd.pulver.com
								dtmf=inband
								allow=ulaw
							

Example 2. extensions.conf


								exten => _**393.,1,SetCallerID(Your Name <12345>)
								exten => _**393.,2,Dial(SIP/${EXTEN:5}@fwdnet)
								exten => _**393.,3,Hangup
							
If you want to connect to FWD via IAX instead, you can subscribe for that in your profile. Your configuration should look like this:

Example 3. iax.conf


							register => 12345:password@iax2.fwdnet.net
							
							[iaxfwd]
								type=user
								allow=ulaw
								deny=0.0.0.0/0.0.0.0
								permit=65.39.205.0/255.255.255.0
							

Example 4. extensions.conf


								exten => _**393.,1,SetCallerID(Your Name <12345>)
								exten => _**393.,2,Dial(IAX2/12345:password@iax2.fwdnet.net/${EXTEN:5})
								exten => _**393.,3,Hangup
							
The reason why ulaw is enabled is, that FWD's own services (voicemail, gateway to toll free numbers etc. only support ulaw. FWD however passes all codecs through, if the subscriber you are calling supports these.


Technical Setup


Protocols

  1. SIP (fwd.pulver.com)

  2. IAX (iax2.fwdnet.org)


Help

There are various ways of obtaining help with FWD: 55555 is the volunteer welcome line, 514 is the Virtual Coffee House, 611 is the Technical Helpline (limited availability) or just use the user forums on their website, which also can provide you with a lot helpful information.


IAXTEL


Description

IAXTel is a free IAX directory service provided by Digium, the company behind Asterisk.


Services

  1. Toll free access to the US and Netherlands

  2. PSTN access number in U.S. enables you to call any IAXTel subscriber from any regular phone.

  3. Interconnect numbers to FWD and VoicePulse subscribers.


What to Expect

IAXTel is in general quite stable, but don't get confused, when you look at the web interface. It is quite outdated. Once you've subscribed to IAXTel you won't need the web interface anyway anymore.


Setup Examples

Example 5. iax.conf


							register => username:password@iaxtel.com
							
							[iaxtel]
								type=user
								auth=rsa
								inkeys=iaxtel
							
							[iaxtel2]
							;
							; Backwards compatible entry for IAXTel pre-RSA
							;
								type=user
								deny=0.0.0.0/0.0.0.0
								permit=216.207.245.47/255.255.255.255
							

Example 6. extensions.conf


								exten => _17XXNXXXXXX.,1,Dial(IAX2/username:password@iaxtel.com/${EXTEN}@iaxtel)
								exten => _17XXNXXXXXX.,2,Hangup
							


Technical Setup


Protocols

IAXTel only supports IAX.


Help

Normally you won't need any help if you follow the examples on the website (or here). It is straight forward.


IPTel


Description

IPTel is a free SIP Directory Service provided by the company that develops SER (SIP Express Router).


Services

  1. Forwarding to another SIP URI.

  2. Instant Messaging through SIP.


Setup Examples

Example 7. sip.conf


							register => username:password@iptel.org
							
							[iptel]
								type=friend
								username=username
								secret=password
								host=iptel.org
							

Example 8. extensions.conf


								exten => _**478.,1,SetCallerID(Your Name <3400001234>)
								exten => _**478.,2,Dial(SIP/${EXTEN:5}@iptel)
								exten => _**478.,3,Hangup
							


Technical Setup


Protocols

IPTel only supports SIP.


Help

A lot tutorials etc., mostly concerning the products of iptel (SER).


Gossiptel


Description

Gossiptel is a commercial SIP Directory provider based in the UK, that gives you a free national phoneno.


Services

  1. Direct phone number that can be called at national rate (0870).

  2. Online Call details of any incoming, outgoing or missed calls.

  3. Prepaid purchase of outgoing calls to any PSTN number.

  4. Advanced Voicemail.


Setup Examples

Example 9. sip.conf


							register => 1234567:password@sip.gossiptel.com
							
							[gossiptel]
								type=peer
								secret=password
								username=1234567
								host=sip.gossiptel.com
							

Example 10. extensions.conf


								;
								; 0 is needed in front of the area code 
								;
								exten => _44ZX.,1,SetCallerID(Your Name <1234567>)
								exten => _44ZX.,2,Dial(SIP/0${EXTEN:2}@gossiptel)
								exten => _44ZX.,3,Hangup

								;
								; 00 is the international dial code used in Europe.
								;
								exten => _XXXX.,1,SetCallerID(Your Name <1234567>)
								exten => _XXXX.,2,Dial(SIP/00${EXTEN}@gossiptel)
								exten => _XXXX.,3,Hangup
							


Technical Setup


Protocols

Gossiptel only supports SIP.


Help

Telephone support available from 9am to 9pm UK time.


SipGate


Description

SIPGate is a German commercial SIP Directory Service, that gives you a free direct phone number in Germany or the UK and access to toll free numbers in these countries.


Services

  1. Direct phone number in any of the cities in Germany or the UK, where SIPGate has a Gateway.

  2. Toll free access to Germany and the UK.

  3. Call forwarding to an IPTel SIP account, if you have one.

  4. Online Call details of any incoming, outgoing or missed calls.

  5. Prepaid purchase of outgoing calls to any PSTN number, at quite competitive rates.

  6. Free calls to other directory services like FWD, IPTel, SipPhone, IAXTel and Telio.no.


What to Expect

SIPGate is a German commercial provider, so their website is completely in German. If you can live with that, you get a great service. They have been rated as one of the best VoIP providers available in Germany by most magazines.


Setup Examples

Example 11. sip.conf


							register => 1234567:password@sipgate.de
							
							[sipgate]
								type=peer
								secret=password
								username=1234567
								host=sipgate.de
							

Example 12. extensions.conf


								;
								; 0 is needed in front of the area code for German phoneno.'s
								;
								exten => _49ZX.,1,SetCallerID(Your Name <1234567>)
								exten => _49ZX.,2,Dial(SIP/0${EXTEN:2}@sipgate)
								exten => _49ZX.,3,Hangup

								;
								; 00 is the international dial code used in Europe.
								;
								exten => _XXXX.,1,SetCallerID(Your Name <1234567>)
								exten => _XXXX.,2,Dial(SIP/00${EXTEN}@sipgate)
								exten => _XXXX.,3,Hangup
							


Technical Setup


Protocols

SIPGate only supports SIP.


Help

SIPGate has a great deal of online documentation in their "Help-Center". Basically everything you need, however German only.


SIPPhone.com


Description

SIPPhone.com is a free SIP Directory Service that originally only wanted to support hardphones, now they also offer access with Xten.


Services

  1. Voicemail.

  2. Conferencing.

  3. 5 calls of 1 minute each every day for free to Australia, Canada, France, Germany, Hong Kong, Italy, Singapore, Taiwan, UK and the U.S.

  4. For an additional fee you can get a U.S. direct phoneno.


Setup Examples

Example 13. sip.conf


							register => 17471234567:password@proxy01.sipphone.com
							
							[sipphone]
								type=friend
								secret=password
								username=17471234567
								host=proxy01.sipphone.com
							

Example 14. extensions.conf


								exten => _1747XXXXXXX,1,SetCallerID(Your Name <17471234567>)
								exten => _1747XXXXXXX,2,Dial(SIP/${EXTEN}@sipphone)
								exten => _1747XXXXXXX,3,Hangup
							


Technical Setup


Protocols

SIPPhone.com only supports SIP.


Help

Support is mainly done through the forum on SIPPhone.com's website.


Applications Reference

AbsoluteTimeout : Set absolute maximum time of call. AbsoluteTimeout(seconds)

Set the absolute maximum amount of time permitted for a call. A setting of 0 disables the timeout. Always returns 0.


exten=>5551234,1,SetAbsoluteTimeout(600) ;limit calls to ex-girlfriend to 600 seconds
exten=>5551234,2,Dial(Zap/1/5551234)
	

AddQueueMember : Dynamically adds queue members. AddQueueMember(queuename[|interface])

Dynamically adds interface to an existing queue. Returns -1 if there is an error.


exten=>123,1,AddQueueMember(techsupport|SIP/3000);add person at SIP/3000 to the techsupport queue
	

ADSIProg: Load Asterisk ADSI Scripts into phone. ADSIProg(script)

Programs an ADSI Phone with the given script. If none is specified, the default is used.

Returns 0 unless CPE is hung up.

AgentCallbackLogin: Call agent callback login. AgentCallbackLogin([AgentNo][|[options][exten]@context])

AgentCallbackLogin() logs an agent into an extension within a given context. The context i must be specified. All other parameters are optional, and will be prompted for.

When AgentCallbackLogin() is used, calls to the agent will be proxied by way of the Local channel, so that only one call from the queue can arrive at the agent's phone at a time.

Tip

The agent proxy channel is not aware of calls which did not go through the proxy, so it is possible to get an agent call while on another call which was not made through the proxy.

To log out an agent, you must have them AgentCallbackLogin() to a null extension by pressing # at the new extension prompt.

Always returns -1.

AgentLogin: Call agent login. AgentLogin([AgentNo][|options])

Asks the agent to login to the system. Always returns -1. While logged in, the agent can receive calls and will hear a 'beep' when a new call comes in. The agent can dump the call by pressing the star key.

The option string may contain zero or more of the following characters:

's' -- silent login - do not announce the login OK segment

AGI: Executes an AGI compliant application. [E]AGI(command[|args])

Executes an Asterisk Gateway Interface compliant program on a channel. AGI allows Asterisk to launch external programs written in any language to control a telephony channel, play audio, read DTMF digits, etc. by communicating with the AGI protocol on STDIN and STDOUT. Returns -1 on hangup or if application requested hangup, or 0 on non-hangup exit. Using 'EAGI' provides enhanced AGI, with audio available out of band on file descriptor 3.

Answer: Answer a channel if ringing. Answer()

If the channel is ringing, answer it, otherwise do nothing.

Returns 0 unless it tries to answer the channel and fails.

Authenticate: Authenticate a user. Authenticate(password[|options])

Requires a user to enter a given password in order to continue execution. If the password begins with the '/' character, it is interpreted as a file which contains a list of valid passwords (1 per line). an optional set of options may be provided by concatenating any of the following letters:

a - Set account code to the password that is entered

Returns 0 if the user enters a valid password within three tries, or -1 otherwise (or on hangup).

BackGround: Play a file while awaiting extension. Background(filename)

Plays a given file, while simultaneously waiting for the user to begin typing an extension. The timeouts do not count until the last BackGround application as ended.

Always returns 0.

Busy: Indicate busy condition and stop. Busy()

Requests that the channel indicate busy condition and then waits for the user to hang up.

Always returns -1.

CallingPres: Change the presentation for the Caller*ID. CallingPres(number)

Changes the presentation for the Caller*ID. Should be called before placing an outgoing call.

ChangeMonitor: Change monitoring filename of a channel. ChangeMonitor(filename_base)

Changes monitoring filename of a channel. Has no effect if the channel is not monitored The option string may contain the following:

filename_base -- if set, changes the filename used to the one specified.

ChanIsAvail: Check if channel is available. ChanIsAvail(Technology/resource[&Technology2/resource2...])

Checks is any of the requested channels are available. If none of the requested channels are available the new priority will be n+101 (unless such a priority does not exist, in which case ChanIsAvail will return -1). If any of the requested channels are available, the next priority will be n+1, the channel variable ${AVAILCHAN} will be set to the name of the available channel and the ChanIsAvail app will return 0.

Congestion: Indicate congestion and stop. Congestion()

Requests that the channel indicate congestion and then waits for the user to hang up.

Always returns -1.

Cut: Cut out part of a variable. Cut(newvar=varname,delimiter,fieldspec)

Cuts out part of a variable and assigns it to a new variable

newvar

new variable created from result string

varname

variable you want cut

delimiter

defaults to '-'

fieldspec

number of the field you want. Field numbers start at 1. The fieldspec may also be specified as a range (with -) or group of ranges and fields (with &)

Returns 0 or -1 on hangup or error.

DateTime: Say the date and time. DateTime()

Says the current date and time. Returns -1 on hangup or 0 otherwise.

DBdel: Delete a key from the database. DBdel(family/key)

Deletes a key from the Asterisk database. Always returns 0.

DBdeltree: Delete a family or key tree from the database. DBdeltree(family[/keytree])

Deletes a family or key tree from the Asterisk database. Always returns 0.

DBget: Retrieve a value from the database. DBget(varname=family/key)

Retrieves a value from the Asterisk database and stores it in the given variable. Always returns 0. If the requested key is not found, jumps to priority n+101 if available.

DBput: Store a value in the database. DBput(family/key=value)

Stores the given value in the Asterisk database. Always returns 0.

Dial: Place a call and connect to the current channel. Dial(Technology/resource[&Technology2/resource2...][|timeout][|options][|URL])

Requests one or more channels and places specified outgoing calls on them. As soon as a channel answers, the Dial app will answer the originating channel (if it needs to be answered) and will bridge a call with the channel which first answered. All other calls placed by the Dial app will be hung up. If a timeout is not specified, the Dial application will wait indefinitely until either one of the called channels answers, the user hangs up, or all channels return busy or error.

In general, the dialer will return 0 if it was unable to place the call, or the timeout expired. However, if all channels were busy, and there exists an extension with priority n+101 (where n is the priority of the dialer instance), then it will be the next executed extension (this allows you to setup different behavior on busy from no-answer).

This application returns -1 if the originating channel hangs up, or if the call is bridged and either of the parties in the bridge terminate the call. The option string may contain zero or more of the following characters:

t

allow the called user transfer the calling user

T

to allow the calling user to transfer the call.

r

indicate ringing to the calling party, pass no audio until answered.

m

provide hold music to the calling party until answered.

H

allow caller to hang up by hitting *.

C

reset call detail record for this call.

P[(x)]

privacy mode, using x as database if provided.

g

goes on in context if the destination channel hangs up

A(x)

play an announcement to the called party, using x as file

In addition to transferring the call, a call may be parked and then picked up by another user.

The optional URL will be sent to the called party if the channel supports it.

DigitTimeout: Set maximum timeout between digits. DigitTimeout(seconds)

Set the maximum amount of time permitted between digits when the user is typing in an extension. When this timeout expires, after the user has started to type in an extension, the extension will be considered complete, and will be interpreted. Note that if an extension typed in is valid, it will not have to timeout to be tested, so typically at the expiry of this timeout, the extension will be considered invalid (and thus control would be passed to the 'i' extension, or if it doesn't exist the call would be terminated).

Always returns 0.

Directory: Provide directory of voicemail extensions. Directory(context)

Presents the user with a directory of extensions from which they may select by name. The list of names and extensions is discovered from voicemail.conf. The context argument is required, and specifies the context in which to interpret the extensions.

Directory() also sets up the channel on exit to enter the extension the user selected.

Returns 0 unless the user hangs up.

DISA: Direct Inward System Access. DISA(passcode[|context[|caller-id]])

Allows someone from outside the telephone switch (PBX) to obtain an "internal" system dial tone and to place calls from it as if they were placing a call from within the switch. A user calls a number that connects to the DISA application and is given dial tone. The user enters their passcode, followed by the pound sign (#). If the passcode is correct, the user is then given system dial tone on which a call may be placed. Obviously, this type of access has SERIOUS security implications, and GREAT care must be taken not to compromise your security.

There is a possibility of accessing DISA without password. Simply exchange your password with 'no-password'.


exten => s,1,DISA(no-password|local)

but be aware of using this for your security compromising.

The arguments to this application (in extensions.conf) allow either specification of a single global password (that everyone uses), or individual passwords contained in a file. It also allow specification of the context on which the user will be dialing. If no context is specified, the DISA application defaults the context to "disa" presumably that a normal system will have a special context set up for DISA use with some or a lot of restrictions. The arguments are one of the following:

numeric-passcode
numeric-passcode|context
full-pathname-of-file-that-contains-passcodes

The file that contains the passcodes (if used) allows specification of either just a passcode (defaulting to the "disa" context, or passcode|context on each line of the file. The file may contain blank lines, or comments starting with "#" or ";". In addition, the above arguments may have |new-callerid-string appended to them, to specify a new (different) CallerID to be used for this call, for example:

numeric-passcode|context|"My Phone" <(234) 123-4567>

or

full-pathname-of-passcode-file|"My Phone" <(234) 123-4567>

Note that in the case of specifying the numeric-passcode, the context must be specified if the CallerID is specified also.

If login is successful, the application parses the dialed number in the specified (or default) context, and returns 0 with the new extension context filled-in and the priority set to 1, so that the PBX may re-apply the routing tables to it and complete the call normally.

EAGI: Enhanced Application Gateway Interface. See AGI.

Echo: Echo audio read back to the user. Echo()

Echo audio read from channel back to the channel.

Returns 0 if the user exits with the # key, or -1 if the user hangs up.

EnumLookup: Lookup number in ENUM. EnumLookup(exten)

Looks up an extension via ENUM and sets the variable 'ENUM'. For VoIP URIs this variable will look like 'TECHNOLOGY/URI' with the appropriate technology.

Returns -1 on hangup, or 0 on completion regardless of whether the lookup was successful.

Note

Currently, the enumservices SIP, H323, IAX, IAX2 and TEL are recognized. A good SIP, H323, IAX or IAX2 entry will result in normal priority handling, whereas a good TEL entry will increase the priority by 51 (if existing). If the lookup was not successful and there exists a priority n + 101, then that priority will be taken next.

Festival: Say text to the user. Festival(text[|intkeys])

Connect to Festival, send the argument, get back the waveform, play it to the user, allowing any given interrupt keys to immediately terminate and return the value, or 'any' to allow any number back (useful in dialplan)

Note

Remember, you must have the Festival server up and running before using this application.

Flash: Flashes a Zap Trunk. Flash()

Sends a flash on a Zap trunk. This is only a hack for people who want to perform transfers and such via AGI and is generally quite useless otherwise.

Returns 0 on success or -1 if this is not a Zap trunk

GetCPEID: Get ADSI CPE ID. GetCPEID()

Obtains and displays CPE ID and other information in order to properly setup zapata.conf for on-hook operations.

Returns -1 on hangup only.

Goto: Goto a particular priority, extension, or context. Goto([[context|]extension|]priority)

Set the priority to the specified value, optionally setting the extension and optionally the context as well. The extension BYEXTENSION is special in that it uses the current extension, thus permitting you to go to a different context, without specifying a specific extension.

Always returns 0, even if the given context, extension, or priority is invalid.

GotoIf: Conditional goto. GotoIf(Condition?label1:label2)

Go to label1 if condition is true, to label2 if condition is false. Either label1 or label2 may be omitted (in that case, we just don't take the particular branch) but not both.

GotoIfTime: Conditional goto on current time. GotoIfTime(<times>|<weekdays>|<mdays>|<months>?[[context|]extension|]priority)

If the current time matches the specified time, then branch to the specified extension. Each of the elements may be specified either as '*' (for always) or as a range. See the include syntax.

Hangup: Unconditional hangup. Hangup()

Unconditionally hangs up a given channel.

Always returns -1.

HasNewVoicemail: Check to see if a voicemail box contains new messages. HasNewVoicemail(vmbox[@context][|varname])

Branches to priority + 101, if there is new voicemail. Optionally sets varname to the number of new messages.

LookupBlacklist: Look up Caller*ID name/number from blacklist database. LookupBlacklist()

Looks up the Caller*ID number on the active channel in the Asterisk database (family 'blacklist'). If the number is found, and if there exists a priority n + 101, where 'n' is the priority of the current instance, then the channel will be setup to continue at that priority level. Otherwise, it returns 0. Does nothing if no Caller*ID was received on the channel.

LookupCIDName: Look up Caller*ID Name from local database. LookupCIDName()

Looks up the Caller*ID number on the active channel in the Asterisk database (family 'cidname') and sets the Caller*ID name. Does nothing if no Caller*ID was received on the channel. This is useful if you do not subscribe to Caller*ID name delivery, or if you want to change the names on some incoming calls.

Always returns 0.

Macro: Macro Implementation. Macro(macroname[[|arg1]|arg2...])

Executes a macro using the context 'macro-macroname', jumping to the 's' extension of that context and executing each step, then returning when the steps end. The calling extension, context, and priority are stored in ${MACRO_EXTEN}, ${MACRO_CONTEXT} and ${MACRO_PRIORITY} respectively. Arguments become ${ARG1}, ${ARG2}, etc. in the macro context.

Macro returns -1 if any step in the macro returns -1, and 0 otherwise. If you Goto out of the Macro context, the Macro will terminate and control will be return at the location of the Goto. Otherwise if ${MACRO_OFFSET} is set at termination, Macro will attempt to continue at priority MACRO_OFFSET + N + 1 if such a step exists, and N + 1 otherwise.

MeetMe: Simple MeetMe conference bridge. MeetMe(confno[|options])

Enters the user into a specified MeetMe conference. If the conference number is omitted, the user will be prompted to enter one. This application always returns -1.

Warning

A ZAPTEL INTERFACE MUST BE INSTALLED FOR CONFERENCING FUNCTIONALITY! See the chapter on timing interfaces for more information.

The option string may contain zero or more of the following characters:

'a'

set admin mode

'm'

set monitor only mode

'p'

allow user to exit the conference by pressing '#'

's'

send user to admin/user menu if '*' is received

't'

set talk only mode

'd'

dynamically add conference

'v'

video mode

'q'

quiet mode (don't play enter/leave sounds)

'M'

enable music on hold when the conference has a single caller

'b'

run AGI script specified in ${MEETME_AGI_BACKGROUND} (Zap channels only) (does not work with non-Zap channels in the same conference)

MeetMeCount: MeetMe participant count. MeetMeCount(confno[|var])

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.

Warning

A ZAPTEL INTERFACE MUST BE INSTALLED FOR CONFERENCING FUNCTIONALITY! See the chapter on timing interfaces for more information.

Returns 0 on success or -1 on a hangup.

Milliwatt: Generate a Constant 1000Hz tone. Milliwatt()

Generate a Constant 1000Hz tone at 0dBm (mu-law)

Monitor: Monitor a channel. Monitor([file_format|[filename_base]])

Used to start monitoring a channel. The channel's input and output voice packets are logged to files until the channel hangs up or monitoring is stopped by the StopMonitor application.

Monitor takes the following arguments:

file_format

optional, if not set, defaults to "wav"

filename_base

if set, changes the filename used to the one specified

MP3Player: Play an MP3 file or stream. MP3Player(location)

Executes mpg123 to play the given location which typically would be a filename or a URL. User can exit by pressing any key.

Returns -1 on hangup or 0 otherwise.

MusicOnHold: Play Music On Hold indefinitely. MusicOnHold(class)

Plays hold music specified by class. If omitted, the default music source for the channel will be used.

Returns -1 on hangup. Never returns otherwise.

NoCDR: Make sure Asterisk doesn't save CDR for a certain call. NoCDR()

Calling this application makes sure there won't be any CDR written for the current call.

NoOp: No operation. NoOp()

No-operation; Does nothing.

Note

Actually, NoOp() has one very useful side-effect. It prints the argument to the Asterisk console. This can be very helpful when debugging.

ParkAndAnnounce: Park and Announce. ParkAndAnnounce(announce_template|timeout|dial|[return_context])

Park a call into the parking lot and announce the call over the console.

announce_template

colon separated list of files to announce, the word PARKED will be replaced by a say_digits of the ext the call is parked in

timeout

time in seconds before the call returns into the return context.

dial

the app_dial style resource to call to make the announcement. Console/dsp calls the console.

return_context

the goto style label to jump the call back into after timeout. Defaults to current priority + 1

ParkedCall: Answer a parked call. ParkedCall(exten)

Used to connect to a parked call. This Application is always registered internally and does not need to be explicitly added into the dialplan, although you should include the 'parkedcalls' context.

Playback: Play a file. Playback(filename[|option])

Plays back a given filename (do not include the file extension). Options may also be included following a pipe symbol. The only defined option at this time is 'skip', which causes the playback of the message to be skipped if the channel is not in the 'up' state (i.e. it hasn't been answered yet. If 'skip' is specified, the application will return immediately should the channel not be off hook. Otherwise, unless 'noanswer' is specified, the channel channel will be answered before the sound is played. Not all channels support playing messages while on hook.

Returns -1 if the channel was hung up, or if the file does not exist. Returns 0 otherwise.

Playtones: Play a tone list. Playtones()

Play a tone list, either registered (through indications.conf) or a direct list of tones and durations.

Prefix: Prepend leading digits. Prefix(digits)

Prepends the digit string specified by digits to the channel's associated extension. For example, the number 1212 when prefixed with '555' will become 5551212.

This app always returns 0, and the PBX will continue processing at the next priority for the new extension.

For example, if priority 3 of extension 1212 is Prefix 555, the next step executed will be priority 4 of 5551212. If you switch into an extension which has no first step, the PBX will treat it as though the user dialed an invalid extension.

PrivacyManager: Require phone number to be entered, if no CallerID sent. PrivacyManager()

If no Caller*ID is sent, PrivacyManager answers the channel and asks the caller to enter their 10 digit phone number. The caller is given 3 attempts. If after 3 attempts, they do not enter their 10 digit phone number, and if there exists a priority n + 101, where 'n' is the priority of the current instance, then the channel will be setup to continue at that priority level. Otherwise, it returns 0. Does nothing if Caller*ID was received on the channel.

Queue: Queue a call for a call queue. Queue(queuename[|options[|URL][|announceoverride]])

Queues an incoming call in a particular call queue as defined in queues.conf. The option string may contain zero or more of the following characters:

t

allow the called user transfer the calling user

T

to allow the calling user to transfer the call.

d

data-quality (modem) call (minimum delay).

H

allow caller to hang up by hitting *.

n

no retries on the timeout; will exit this application and go to the next step.

In addition to transferring the call, a call may be parked and then picked up by another user. The optional URL will be sent to the called party if the channel supports it.

This application returns -1 if the originating channel hangs up, or if the call is bridged and either of the parties in the bridge terminate the call. Returns 0 if the queue is full, nonexistent, or has no members.

Read: Read a variable. Read(variable[|filename])

Reads a # terminated string of digits from the user, optionally playing a given filename first.

Returns -1 on hangup or error and 0 otherwise.

Record: Record to a file. Record(filename:extension|silence)

Records from the current channel into the given filename. If the file exists it will be overwritten. The extension is the extension of the file type to be recorded (wav, GSM, etc). The silence argument is the number of seconds of silence to allow before returning.

Returns -1 when the user hangs up.

RemoveQueueMember: Dynamically removes queue members. RemoveQueueMember(queuename[|interface])

Dynamically removes interface to an existing queue

Returns -1 if there is an error.


	RemoveQueueMember(techsupport|SIP/3000)
	;remove SIP/3000 from techsupport queue
	

ResetCDR: Resets the Call Data Record. ResetCDR([options])

Causes the Call Data Record to be reset, optionally storing the current CDR before zeroing it out (if 'w' option is specified the record WILL be stored.

Always returns 0.

ResponseTimeout: Set maximum timeout awaiting response. ResponseTimeout(seconds)

Set the maximum amount of time permitted after falling through a series of priorities for a channel in which the user may begin typing an extension. If the user does not type an extension in this amount of time, control will pass to the 't' extension if it exists, and if not the call will be terminated.

Always returns 0.

Ringing: Indicate ringing tone. Ringing()

Request that the channel indicate ringing tone to the user.

Always returns 0.

SayDigits: Say Digits. SayDigits(digits)

Says the passed digits. With this, if you insert a string of digits, Asterisk will say the individual numbers.

Example: SayDigits(12345) will be said as "One Two Three Four Five".

SayNumber: Say Number. SayNumber(number)

Says the passed number. With this, if you insert a string of digits, Asterisk will say the number, and not the individual digits.

Example:

SayNumber(12345)
will be said as "Twelve-Thousand Three-Hundred Forty-Five".

SayUnixTime: Says a specified time in a custom format. SayUnixTime([unixtime][|[timezone][|format]])

unixtime

time, in seconds since Jan 1, 1970. May be negative. Defaults to now.

timezone

timezone, see /usr/share/zoneinfo for a list. Defaults to machine default.

format

a format the time is to be said in. See voicemail.conf. Defaults to "ABdY 'digits/at' IMp"

Returns 0 or -1 on hangup.

SendDTMF: Sends arbitrary DTMF digits. SendDTMF(digits)

Sends DTMF digits on a channel.

Returns 0 on success or -1 on a hangup.

SendImage: Send an image file. SendImage(filename)

Sends an image on a channel. If the channel does not support image transport, and there exists a step with priority n + 101, then execution will continue at that step. Otherwise, execution will continue at the next priority level.

SendImage() only returns 0 if the image was sent correctly or if the channel does not support image transport, and -1 otherwise.

SendURL: Send a URL. SendURL(URL[|option])

Requests client go to URL. If the client does not support HTML transport, and there exists a step with priority n + 101, then execution will continue at that step. Otherwise, execution will continue at the next priority level.

SendURL() only returns 0 if the URL was sent correctly or if the channel does not support HTML transport, and -1 otherwise. If the option 'wait' is specified, execution will wait for an acknowledgment that the URL has been loaded before continuing and will return -1 if the peer is unable to load the URL.

SetAccount: Sets account code. SetAccount([account])

Set the channel account code for billing purposes.

Always returns 0.

SetCallerID: Set Caller*ID. SetCallerID(callerid[|a])

Set Caller*ID on a call to a new value. Sets ANI as well if the a flag is used.

Always returns 0

SetCIDName: Set Caller*ID Name. SetCIDName(cname[|a])

Set Caller*ID Name on a call to a new value, while preserving the original Caller*ID number. This is useful for providing additional information to the called party. Sets ANI as well if a flag is used.

Always returns 0

SetCIDNum: Set Caller*ID Number. SetCIDNum(cnum[|a])

Set Caller*ID Number on a call to a new value, while preserving the original Caller*ID name. This is useful for providing additional information to the called party. Sets ANI as well if a flag is used.

Always returns 0

SetGlobalVar: Set variable to value. SetGlobalVar(#n=value)

Sets global variable n to value

SetLanguage: Sets user language. SetLanguage(language)

Set the channel language to language. This information is used for the generation of numbers, and to select a natural language file when available. For example, if language is set to 'fr' and the file demo-congrats is requested to be played, if the file fr/demo-congrats exists, then it will play that file, and if not will play the normal demo-congrats.

Always returns 0.

SetMusicOnHold: Set default Music On Hold class. SetMusicOnHold(class)

Sets the default class for music on hold for a given channel. When music on hold is activated, this class will be used to select which music is played.

SetVar: Set variable to value. SetVar(#n=value)

Sets variable n to value

SIPDtmfMode: Change the DTMF mode for a SIP call. SIPDtmfMode(option)

Changes the DTMF mode for a SIP call

The option argument can be one of 'inband', 'info', or 'rfc2883'.

SoftHangup: Soft Hangup Application. SoftHangup(Technology/resource)

Hangs up the requested channel. Always returns 0

StopMonitor: Stop monitoring a channel. StopMonitor()

Stops monitoring the current channel. Has no effect if the channel is not monitored

StopPlaytones: Stop playing a tone list. StopPlaytones()

Stop playing a tone list

StripLSD: Strip Least Significant Digits. StripLSD(count)

Strips the trailing count digits from the channel's associated extension. For example, the number 5551212 when stripped with a count of 4 would be changed to 555. This app always returns 0, and the PBX will continue processing at the next priority for the new extension.

So, for example, if priority 3 of 5551212 is StripLSD 4, the next step executed will be priority 4 of 555. If you switch into an extension which has no first step, the PBX will treat it as though the user dialed an invalid extension.

StripMSD: Strip leading digits. StripMSD(count)

Strips the leading count digits from the channel's associated extension. For example, the number 5551212 when stripped with a count of 3 would be changed to 1212. This app always returns 0, and the PBX will continue processing at the next priority for the new extension.

So, for example, if priority 3 of 5551212 is StripMSD 3, the next step executed will be priority 4 of 1212. If you switch into an extension which has no first step, the PBX will treat it as though the user dialed an invalid extension.

SubString: Save substring digits in a given variable. SubString(variable=string_of_digits|count1|count2)

Assigns the substring of string_of_digits to a given variable. Parameter count1 may be positive or negative. If it's positive then we skip the first count1 digits from the left. If it's negative, we move count1 digits counting from the end of the string to the left. Parameter count2 implies how many digits we are taking from the point that count1 placed us. If count2 is negative, then that many digits are omitted from the end.

For example:


	exten => _NXXXXXX,1,SubString,test=2564286161|0|3
	assigns the area code (3 first digits) to variable test.
	exten => _NXXXXXX,1,SubString,test=2564286161|-7|7
	assigns the last 7 digits to variable test.
	exten => _NXXXXXX,1,SubString,test=2564286161|0|-4
	assigns all but the last 4 digits to variable test.
	

If there are no parameters it'll return with -1. If there wrong parameters it go on and return with 0

Suffix: Append trailing digits. Suffix(digits)

Appends the digit string specified by digits to the channel's associated extension. For example, the number 555 when suffixed with '1212' will become 5551212. This app always returns 0, and the PBX will continue processing at the next priority for the new extension.

So, for example, if priority 3 of 555 is Suffix 1212, the next step executed will be priority 4 of 5551212. If you switch into an extension which has no first step, the PBX will treat it as though the user dialed an invalid extension.

System: Execute a system command. System(command)

Executes a command by using system().

Returns -1 on failure to execute the specified command. If the command itself executes but is in error, and if there exists a priority n + 101, where 'n' is the priority of the current instance, then the channel will be setup to continue at that priority level. Otherwise, System returns 0.

Transfer: Transfer caller to remote extension. Transfer(exten)

Requests the remote caller be transferred to the given exten.

Returns -1 on hangup, or 0 on completion regardless of whether the transfer was successful. If the transfer was not supported or successful and there exists a priority n + 101, then that priority will be taken next.

VoiceMail: Leave a voicemail message. Deprecated: See Voicemail2

VoiceMail2: Leave a voicemail message. VoiceMail2([s|u|b]extension[@context])

Leaves voicemail for a given extension (must be configured in voicemail.conf). If the extension is preceded by an s then instructions for leaving the message will be skipped. If the extension is preceded by u then the "unavailable" message will be played (/var/lib/asterisk/sounds/vm/context/exten/unavail) if it exists. If the extension is preceded by a b then the the busy message will be played (that is, busy instead of unavailable). If the requested mailbox does not exist, and there exists a priority n + 101, then that priority will be taken next.

Returns -1 on error or mailbox not found, or if the user hangs up. Otherwise, it returns 0.

VoiceMailMain: Enter voicemail system. Deprecated: See VoiceMailMain2

VoiceMailMain2: Enter voicemail system. VoiceMailMain2([[s]mailbox][@context])

Enters the main voicemail system for the checking of 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, logins are considered in that context only.

Returns -1 if the user hangs up or 0 otherwise.

Wait: Waits for some time. Wait(seconds)

Waits for a specified number of seconds, then returns 0.

WaitForRing: Wait for Ring Application. WaitForRing(timeout)

Returns 0 after waiting at least timeout seconds, and only after the next ring has completed. Returns 0 on success or -1 on hangup

WaitMusicOnHold: Wait, playing Music On Hold. WaitMusicOnHold(delay)

Plays hold music a number of seconds specified by delay.

Returns 0 when done, or -1 on hangup. If no hold music is available, the delay will still occur with no sound.

Zapateller: Block telemarketers with SIT. Zapateller(options)

Generates special information tone to block telemarketers from calling you.

The options argument is a pipe-delimited list of options. The following options are available:

answer

causes the line to be answered before playing the tone

nocallerid

causes Zapateller to only play the tone if there is no CallerID information available.

Returns 0 normally or -1 on hangup.

ZapBarge: Barge in (monitor) Zap channel. ZapBarge([channel])

Barges in on a specified zap channel or prompts if one is not specified.

Returns -1 when caller user hangs up and is independent of the state of the channel being monitored.

ZapRAS: Executes Zaptel ISDN RAS application. ZapRAS(args)

Executes a RAS server using pppd on the given channel. The channel must be a clear channel (i.e. PRI source) and a Zaptel channel to be able to use this function (No modem emulation is included). Your pppd must be patched to be zaptel aware. Arguments should be separated by | characters.

Always returns -1.


CLI Command Reference

The Asterisk Command Line Interface (CLI) has many commands which you can run to help diagnose and maintain your system. This chapter will be dedicated to explain the usage of those commands and when you might use them.


Which Commands Can I Use?

There are many commands which can be used to show you information about the current state of your system. The Asterisk CLI works very similar to many managed switches and routers CLI interfaces. You will find it fairly intuitive if you have used these CLI systems before, but we will assume you have not.

The first thing we need to know is what commands can we use? The Asterisk CLI allows the usage of tab completion which can be quite handy to reduce the amount of typing and help find a command. Pressing Tab twice will give a listing of available commands. If we press Tab twice at a new CLI prompt, we get the following listing of commands.


		*CLI> 
		!           abort       add         database    debug       dont        dump        extensions  help        iax2        include
		init        load        local       logger      meetme      no          pri         reload      remove      restart     save
		set         show        sip         soft        stop        unload      zap
		

Asterisk will show you all the commands available at that level. Since we haven't started typing any commands, Asterisk will show us the very first level. Lets start with the show command as it can be very useful to show us the state of our system. For a listing of the sub-commands we can use with show, we can type show at the CLI and press the Tab key twice. Doing this will give the following listing of commands.


		*CLI>  show
		agents       agi      application   applications  audio       channel     channels    codec         codecs    conferences   config
		dialplan     file     image         indications   keys        manager     modules     parkedcalls   queue     queues        switches
		translation  uptime   version       video         voicemail
		

As we can see, there are a wide range of things that show can tell us about our system. We won't go into details here, but we now have an idea of how we can find a listing of the commands we can use.


Obtaining Help About a Command

You can obtain information about a command by typing the word help from the CLI. This will give you a listing of all the possible command combinations plus a short description of what it will do.


		*CLI>  help
		                        !  Execute a shell command
		               abort halt  Cancel a running halt
		            add extension  Add new extension into context
		            add ignorepat  Add new ignore pattern
		           add indication  Add the given indication to the country
		         add queue member  Add a channel to a specified queue
		...etc...
		

There are over 100 commands listed in the help - that's quite a number of commands!


The show Command


show application

You can view information about the applications available within your dialplan by using the show application command. The format is


			show application application_name
			

If you press the Tab key twice after typing show application you will get a listing of all the applications, without a description, available to you for use within your dialplan. When viewing each specific application, the Asterisk CLI will give you a brief description about the application, its usage within the dialplan and a listing of any options/flags which it may support. This is arguably one of the most useful commands in the Asterisk CLI.

The show applications command compliments this command nicely.


show applications

The show applications command will give you a listing of all the available applications with a brief description for use within your dialplan. The show applications command will give you output like the following example.


			*CLI>  show applications
			    -= Registered Asterisk Applications =-
			       AbsoluteTimeout: Set absolute maximum time of call
			        AddQueueMember: Dynamically adds queue members
			              ADSIProg: Load Asterisk ADSI Scripts into phone
			    AgentCallbackLogin: Call agent callback login
			            AgentLogin: Call agent login
			  AgentMonitorOutgoing: Record agent's outgoing call
			                   AGI: Executes an AGI compliant application
			...etc...
			

Note

As of CVS HEAD 08/27/2004 there is a new command which let you search for applications which contain a word you specify. show applications like text will search for the sub-string text within the application name. show applications describing text will search the descriptions for the sub-string text.


Manager Commands Reference


The Asterisk C API Reference


Other Open Source Telephony Systems


Other Hardware

Other hardware options

VoiceTronix OpenLine and OpenSwitch Cards

The VoiceTronix OpenLine and OpenSwitch Cards are an inexpensive line of FXO and FXS cards for standard analog lines. In low density implmentations they can be a highly effective solution. The OpenLine 4 has 4 FXO ports, the OpenSwitch 6 has 6 user-configurable ports that can either be FXO or FXS, and the OpenSwitch 12 has 12 user-configurable ports that can either be FXO or FXS.

The VoiceTronix hardware is supported by the chan_vpb channel driver in Asterisk. The driver is part of the standard Asterisk source distribution and is compiled as part of the standard build. The ring type code can be modified to specifically support either US (United States) or AU (Australia) ring tones. With the improvements in indications.conf this will be depreciated.

The chan_vpb channel driver is loaded by the use of the vpb directives in either the extensions.conf or somewhere that the channel is used. To configure a specific card, you edit the vpb.conf as per that section of the documentation. The VoiceTronix hardware needs a kernel module to operate, vpb, and that must be acquired from VoiceTronix:

  • http://www.voicetronix.com/downloads.htm


ISDN Cards

ISDN hardware is quite inexpensive in most parts of the world. A basic AVM card that comes with CAPI compatible kernel modules is available for about $40US or less. Sometimes there are several differences between the capacity of the cards such as having more ports and supporting different ISDN standards.

There are several ways of integrating ISDN channels in Asterisk. Out of the box Asterisk only supports isdn4linux (chan_modem_i4l), but there are several more powerful 3rd party channel modules available: chan_capi utilizes capi supported ISDN cards, zaphfc/qozap utilizes ISDN cards based on the HFC chipset, both channel drivers are maintained by Klaus-Peter Junghanns and released under the terms of the GPL. And last but not least there is chan_mISDN, which utilizes the new isdn4linux mISDN architecture. Also this 3rd party channel driver is released under the terms of the GPL.

Currently chan_capi and zapbri will be the channel drivers that are described the best here because chan_modem_i4l doesn't give the best results. chan_mISDN is quite new and the mISDN architecture in isdn4linux has mainly been developed against kernel 2.6, so not too much information there yet.


AVM Fritz!

http://www.avm.de

The AVM Fritz! card is quite interesting, since it's the only passive ISDN card where the manufacturer did mind to write CAPI support (binary though). This driver unfortunately has one limitation: point-to-point (PTP) mode does not work.

With the introduction of the isdn4linux new mISDN architecture and it's capi layer, that problem is fixed. chan_capi supports PTP on the AVM Fritz! card in that case and you even get rid of having a tainted kernel, at least for this module.

ftp://ftp.avm.de/cardware/fritzcrd.pci/linux/suse.82/ (not only for SuSE)
http://www.linux-magazin.de/Artikel/ausgabe/2000/10/Capi/capi.html (German article on getting capi to work with AVM Fritz!)


HFC based ISDN cards, quadBRI, octoBRI

HFC based ISDN cards can also be implemented with the zapbri and qozap kernel modules drivers, that provide zaptel telephony. As with all zaptel drivers you can have any amount of these cards in your Asterisk box, only limted by the amount of PCI ports available in your system.

Features at a glance:

  • TE and NT mode

  • PTP and PMP mode

  • DTMF detection

  • caller name display on alphanumeric isdn phones

  • text messages

  • call parking

The qozap driver is for 4 port (quadBRI) and 8 port (octoBRI) ISDN cards that are also designed and sold by it's developer. These cards can provide power and termination on the port for NT mode and do offer an internal PCM bus, that connects all quadBRI or octoBRI cards together to interconnect up to 64 full duplex connections at 64 kbit/s each without using that bandwidth on the PCI bus or the host CPU.

The zaphfc driver is basically the same driver just for a single port ISDN card available for about $30US in most hardware stores. TE mode, hooking it up against your ISDN line, is trivial and works as good as with the capi based cards, however to get NT mode to work with this card you will need to build yourself an ISDN crossover cable and provide power and termination on the ISDN bus. This can be done by taking an old NT1 that not is in use anymore and modify it a little.

These drivers are quite new and require to patch both Asterisk & libpri sourcetree to get them working. After that you can build the kernel module (zapbri/qozap). Once done you have a full features zaptel interface for these cards, which makes them quite interesting.

"bristuff", as the package is called, also introduces a couple new options to zapata.conf:


				signalling          = bri_cpe_ptmp (or bri_cpe_ptmp for point to point)
				prilocaldialplan    = national (can have the same values as pridialplan, this is used for phones on cards in NT mode)
				nationalprefix      = 0
				internationalprefix = 00 (since asterisk doesn't tell you what dialplan the call came with, these are essential)
				

The package can be downloaded at: http://www.junghanns.net/asterisk/.


Building Additional Modules

Building additional modules

Beyond the base install and drivers, Asterisk contains many additional modules which are not compiled by default. This is to help simplify the installation of Asterisk and not to cause the system to be bloated with extra code that a user may not have a use for.

[This is just a rough introduction, however we should expand upon it. Mention things that your system already needs to have running, what extra software or hardware you need for this to work, and any other issues that should be mentioned briefly before we get in too deep]


H323 - McNamara

[Not sure what the difference is between McNamara and Manousos, but either way lets try and be as detailed as possible]


MySQL CDR

[Lets explain that MySQL support has not been removed from Asterisk but that it has been moved to a different section of CVS due to licensing issues. This might be a good section to explain them a little bit. Instructions should include how to get MySQL support put back into Asterisk plus how to setup any CDR recording as opposed to simply using CSV. Tell them how to compile, what they will need, and common problems people face when trying to get this to work. We may be able to mention about adding extensions and dialplans and other configuration files into MySQL, but maybe that should be a little bit later on, either in the cookbook, or in some advanced configuration sections. This chapter is for installation, and not configuration.]


CAPI/ISDN

[We should give some introduction and clean this up a bit so it flows better in our book here]

The complete source code is available from Kapejod's website

http://www.junghanns.net/asterisk/downloads/chan_capi.0.3.0.tar.gz

Copy the sources to a folder of your choice and type the following commands to untar the source and change into its directory tree.


tar zxf chan_capi.0.3.0.tar.gz
cd chan_capi-0.3.0/

Now edit the file Makefile with your favorite editor to set it to your needs. First set the path to your asterisk include files.


"ASTERISK_HEADER_DIR=/usr/include/asterisk # standard path"

Then you can set some build time configuration parameters like early B3 connects, DEFLECT_ON_CIRCUITBUSY or software DTMF detection/generation. If everything is done simply save the file.


To compile and install the driver type:
make && make install

To install a sample capi.conf in asterisks conf dir:
make config

After this setup add in /etc/asterisk/modules.conf


load => chan_capi.so

and in the [global] section:


"chan_capi.so=yes"

After these steps your channel module is available in Asterisk but it has to be configured. This is done in the main CAPI configuration file capi.conf.

Glossary of Asterisk & Telecom Terms

FXO

Foreign eXchange Office

An FXO device can be an analog phone, answering machine, fax, or anything that handles a call from the telephone company like one. They should also operate the same way when connected to an FXS interface.

An FXO interface will accept calls from FXS or PSTN interfaces. All countries and regions have their own standards.

FXO is complimentary to FXS (and the PSTN).

FXS

Foreign eXchange Station

An FXS device has hardware to generate the ring signal to the FXO extension (usually an analog phone).

An FXS device will allow any FXO device to operate as if it were connected to the phone company. This makes your PBX the POTS+PSTN for the phone.

The FXS Interface connects to FXO devices (by an FXO interface, of course).

PSTN

Public Switched Telephone Network

i.e. the phone service we use for every ordinary phone call.

ADSI

Analog Display Service Interface

A complex set of standards for the telecom industry. Built off of FSK keying used by CallerID, ADSI is capable of remotely controlling a screenphone with softkeys. Effectively, session based applications can be used when the phone is online, or scripts can be preprogrammed into the phone for when no ADSI connection has been established (on or off hook). Originally, this technology was made by Telcos who thought they would use it to offer services to residential customers. They envisioned such features and buying airplane tickets from your screenphone. Adoption has been mixed. In order to protect their interests, all phones appear to be locked with a programming "code" to prevent users from using one phone provided by one company for a competing service. As such, it can be difficult to get a phone that you can program for yourself (if you have the software). Needless to say, getting codes for an existing phone is nearly impossible (it is incomprehensible to the support staff that anybody but a telco will be programming said phones). Rather, you need to order a phone specifically because you already have the code (eventually you can find a contact that will help you here).

ISDN

Integrated Services Digital Network

A set of communications standards to carry voice, digital network services. ISDN consists of a D channel that transmits data about the connections on a ISDN line, and any number of B channels that bear the data or voice traffic.

PRI

Primary Rate Interface

PRI is a standard network interface consisting of 1 D channel and 23 B channels on a T1, or 1 D channel and 30 B channels on a E1.

BRI

Basic Rate Interface

BRI is a standard network interface consisting of 1 D channel and 2 B channels.

VoIP

Voice over IP

VoIP encompasses many protocols. All the protocols do some form of signalling of call capabilities and transport of voice data from one point to another. Examples are SIP, H.323, IAX, and IAX2.

MSN

Multiple Subscriber Line

This is a telephone number associated with an ETS 300 BRI line. Providers of ETS 300 often give you three MSNs with a BRI, although additional MSNs can be purchased. An ISDN terminal will "ring" (provide an alerting signal) only when calls are made to the MSN (or MSNs) entered in that terminal. If a terminal has no MSNs entered it will "ring" whenever there is a call to any of the MSN.s on that BRI.

DID

Direct Inward Dialing

Direct Inward Dialing. The ability for an outside caller to dial to a PBX extension without going through an attendant or auto-attendant.

DTMF

Dual Tone Multi Frequency

The standard tone-pairs used on telephone terminals for dialing using in-band signaling. The standards define 16 tone-pairs (0-9, #, * and A-F) although most terminals support only 12 of them (0-9, * and #).


Colophon

This document was written as an excuse to become more familiar with the DocBook format, and to contribute back to the Asterisk project.