Asterisk
Asterisk Asterisk
Contents

Asterisk - The Open Source VoIP PBX

Previous Page Next Page
 
Asterisk: The Future of Telephony
Table of Contents
Copyright
Foreword
Preface
Audience
Organization
Software
Conventions Used in This Book
Using Code Examples
Safari® Enabled
How to Contact Us
Acknowledgments
Chapter 1.  A Telephony Revolution
Section 1.1.  VoIP: Bridging the Gap Between Traditional Telephony and Network Telephony
Section 1.2.  Massive Change Requires Flexible Technology
Section 1.3.  Asterisk: The Hacker's PBX
Section 1.4.  Asterisk: The Professional's PBX
Section 1.5.  The Asterisk Community
Section 1.6.  The Business Case
Section 1.7.  This Book
Chapter 2.  Preparing a System for Asterisk
Section 2.1.  Server Hardware Selection
Section 2.2.  Environment
Section 2.3.  Telephony Hardware
Section 2.4.  Types of Phone
Section 2.5.  Linux Considerations
Section 2.6.  Conclusion
Chapter 3.  Installing Asterisk
Section 3.1.  What Packages Do I Need?
Section 3.2.  Obtaining the Source Code
Section 3.3.  Compiling Zaptel
Section 3.4.  Compiling libpri
Section 3.5.  Compiling Asterisk
Section 3.6.  Installing Additional Prompts
Section 3.7.  Updating Your Source Code
Section 3.8.  Common Compiling Issues
Section 3.9.  Loading Zaptel Modules
Section 3.10.  Loading libpri
Section 3.11.  Loading Asterisk
Section 3.12.  Directories Used by Asterisk
Section 3.13.  Conclusion
Chapter 4.  Initial Configuration of Asterisk
Section 4.1.  What Do I Really Need?
Section 4.2.  Working with Interface Configuration Files
Section 4.3.  FXO and FXS Channels
Section 4.4.  Configuring an FXO Channel
Section 4.5.  Configuring an FXS Channel
Section 4.6.  Configuring SIP
Section 4.7.  Configuring Inbound IAX Connections
Section 4.8.  Configuring Outbound IAX Connections
Section 4.9.  Debugging
Section 4.10.  Conclusion
Chapter 5.  Dialplan Basics
Section 5.1.  Dialplan Syntax
Section 5.2.  A Simple Dialplan
Section 5.3.  Adding Logic to the Dialplan
Section 5.4.  Conclusion
Chapter 6.  More Dialplan Concepts
Section 6.1.  Expressions and Variable Manipulation
Section 6.2.  Dialplan Functions
Section 6.3.  Conditional Branching
Section 6.4.  Voicemail
Section 6.5.  Macros
Section 6.6.  Using the Asterisk Database (AstDB)
Section 6.7.  Handy Asterisk Features
Section 6.8.  Conclusion
Chapter 7.  Understanding Telephony
Section 7.1.  Analog Telephony
Section 7.2.  Digital Telephony
Section 7.3.  The Digital Circuit-Switched Telephone Network
Section 7.4.  Packet-Switched Networks
Section 7.5.  Conclusion
Chapter 8.  Protocols for VoIP
Section 8.1.  The Need for VoIP Protocols
Section 8.2.  VoIP Protocols
Section 8.3.  Codecs
Section 8.4.  Quality of Service
Section 8.5.  Echo
Section 8.6.  Asterisk and VoIP
Section 8.7.  Conclusion
Chapter 9.  The Asterisk Gateway Interface (AGI)
Section 9.1.  Fundamentals of AGI Communication
Section 9.2.  Writing AGI Scripts in Perl
Section 9.3.  Creating AGI Scripts in PHP
Section 9.4.  Writing AGI Scripts in Python
Section 9.5.  Debugging in AGI
Section 9.6.  Conclusion
Chapter 10.  Asterisk for the Über-Geek
Section 10.1.  Festival
Section 10.2.  Call Detail Recording
Section 10.3.  Customizing System Prompts
Section 10.4.  Manager
Section 10.5.  Call Files
Section 10.6.  DUNDi
Section 10.7.  Conclusion
Chapter 11.  Asterisk: The Future of Telephony
Section 11.1.  The Problems with Traditional Telephony
Section 11.2.  Paradigm Shift
Section 11.3.  The Promise of Open Source Telephony
Section 11.4.  The Future of Asterisk
Appendix A.  VoIP Channels
Section A.1.  IAX
Section A.2.  SIP
Appendix B.  Application Reference
AbsoluteTimeout( )
AddQueueMember( )
ADSIProg( )
AgentCallbackLogin( )
AgentLogin( )
AgentMonitorOutgoing( )
AGI( )
AlarmReceiver( )
Answer( )
AppendCDRUserField( )
Authenticate( )
Background( )
BackgroundDetect( )
Busy( )
CallingPres( )
ChangeMonitor( )
ChanIsAvail( )
CheckGroup( )
Congestion( )
ControlPlayback( )
Curl( )
Cut( )
DateTime( )
DBdel( )
DBdeltree( )
DBget( )
DBput( )
DeadAGI( )
Dial( )
DigitTimeout( )
Directory( )
DISA( )
DumpChan( )
DUNDiLookup( )
EAGI( )
Echo( )
EndWhile( )
ENUMLookup( )
Eval( )
Exec( )
ExecIf( )
FastAGI( )
Festival( )
Flash( )
ForkCDR( )
GetCPEID( )
GetGroupCount( )
GetGroupMatchCount( )
Goto( )
GotoIf( )
GotoIfTime( )
Hangup( )
HasNewVoicemail( )
HasVoicemail( )
IAX2Provision( )
ImportVar( )
LookupBlacklist( )
LookupCIDName( )
Macro( )
MailboxExists( )
Math( )
MeetMe( )
MeetMeAdmin( )
MeetMeCount( )
Milliwatt( )
Monitor( )
MP3Player( )
MusicOnHold( )
NBScat( )
NoCDR( )
NoOp( )
Park( )
ParkAndAnnounce( )
ParkedCall( )
PauseQueueMember( )
Playback( )
Playtones( )
Prefix( )
PrivacyManager( )
Progress( )
Queue( )
Random( )
Read( )
RealTime
RealTimeUpdate( )
Record( )
RemoveQueueMember( )
ResetCDR( )
ResponseTimeout( )
RetryDial( )
Ringing( )
SayAlpha( )
SayDigits( )
SayNumber( )
SayPhonetic( )
SayUnixTime( )
SendDTMF( )
SendImage( )
SendText( )
SendURL( )
Set( )
SetAccount( )
SetAMAFlags( )
SetCallerID( )
SetCallerPres( )
SetCDRUserField( )
SetCIDName( )
SetCIDNum( )
SetGlobalVar( )
SetGroup( )
SetLanguage( )
SetMusicOnHold( )
SetRDNIS( )
SetVar( )
SIPAddHeader( )
SIPDtmfMode( )
SIPGetHeader( )
SoftHangup( )
StopMonitor( )
StopPlaytones( )
StripLSD( )
StripMSD( )
SubString( )
Suffix( )
System( )
Transfer( )
TrySystem( )
TXTCIDName( )
UnpauseQueueMember( )
UserEvent( )
Verbose( )
VMAuthenticate( )
VoiceMail( )
VoiceMailMain( )
Wait( )
WaitExten( )
WaitForRing( )
WaitForSilence( )
WaitMusicOnHold( )
While( )
Zapateller( )
ZapBarge( )
ZapRAS( )
ZapScan( )
Appendix C.  AGI Reference
ANSWER
CHANNEL STATUS
DATABASE DEL
DATABASE DELTREE
DATABASE GET
DATABASE PUT
EXEC
GET DATA
GET FULL VARIABLE
GET OPTION
GET VARIABLE
HANGUP
NOOP
RECEIVE CHAR
RECORD FILE
SAY ALPHA
SAY DATE
SAY DATETIME
SAY DIGITS
SAY NUMBER
SAY PHONETIC
SAY TIME
SEND IMAGE
SEND TEXT
SET AUTOHANGUP
SET CALLERID
SET CONTEXT
SET EXTENSION
SET MUSIC ON
SET PRIORITY
SET VARIABLE
STREAM FILE
TDD MODE
VERBOSE
WAIT FOR DIGIT
Appendix D.  Configuration Files
Section D.1.  modules.conf
Section D.2.  adsi.conf
Section D.3.  adtranvofr.conf
Section D.4.  agents.conf
Section D.5.  alarmreceiver.conf
Section D.6.  alsa.conf
Section D.7.  asterisk.conf
Section D.8.  cdr.conf
Section D.9.  cdr_manager.conf
Section D.10.  cdr_odbc.conf
Section D.11.  cdr_pgsql.conf
Section D.12.  cdr_tds.conf
Section D.13.  codecs.conf
Section D.14.  dnsmgr.conf
Section D.15.  dundi.conf
Section D.16.  enum.conf
Section D.17.  extconfig.conf
Section D.18.  extensions.conf
Section D.19.  features.conf
Section D.20.  festival.conf
Section D.21.  iax.conf
Section D.22.  iaxprov.conf
Section D.23.  indications.conf
Section D.24.  logger.conf
Section D.25.  manager.conf
Section D.26.  meetme.conf
Section D.27.  mgcp.conf
Section D.28.  modem.conf
Section D.29.  musiconhold.conf
Section D.30.  osp.conf
Section D.31.  oss.conf
Section D.32.  phone.conf
Section D.33.  privacy.conf
Section D.34.  queues.conf
Section D.35.  res_odbc.conf
Section D.36.  rpt.conf
Section D.37.  rtp.conf
Section D.38.  sip.conf
Section D.39.  sip_notify.conf
Section D.40.  skinny.conf
Section D.41.  voicemail.conf
Section D.42.  vpb.conf
Section D.43.  zapata.conf
Section D.44.  zaptel.conf
Appendix E.  Asterisk Command-Line Interface Reference
!
abort halt
Section E.1.  add
Section E.2.  agi
Section E.3.  database
Section E.4.  iax2
Section E.5.  indication
Section E.6.  logger
Section E.7.  meetme
Section E.8.  pri
Section E.9.  remove
Section E.10.  restart
Section E.11.  set
Section E.12.  show
Section E.13.  sip
Section E.14.  stop
Section E.15.  zap
Colophon
About the Authors
Colophon
Index
SYMBOL
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
Previous Page
Next Page

Dial( ) Attempts to connect channels

    Dial(tech/username:password@hostname/extension,ring-timeout,flags)

Allows you to connect together all of the various channel types.[*] Dial( ) is the most important application in Asteriskyou'll want to read through this section a few times.

[*] The fact that Asterisk will happily connect IAX, SIP, H.323, Skinny, PRI, FX(O/S), and anything else is amazing, but possibly the most amazing of all is the Local channel. By allowing a single Dial( ) command to connect to multiple Local channels, one Dial( ) event can trigger a multitude of completely independent and unique actions in other parts of the dialplan. The power of this concept is truly revolutionary and has to be experienced to be believed.

Any valid channel type (such as SIP, IAX2, H.323, MGCP, Local, or Zap) is acceptable to Dial( ), but the parameters that need to be passed to each channel will depend on the information the channel type needs to do its job. For example, a SIP channel will need a network address and user to connect to, whereas a Zap channel is going to want some sort of phone number.

When you specify a channel type that is network-based, you can pass the destination host (name or IP address), username, password, and remote extension as part of the options to Dial( ), or you can refer to the name of a channel entry in the appropriate .conf file; all the required information will then need to be obtained from that file. The username and password can be replaced with the name contained within square brackets ([]) of the channel configuration file. The hostname is optional.

This is a valid Dial statement:

    exten => s,1,Dial(SIP/sake:arigato@thathostoverthere.tld)

This is effectively identical:

    exten => s,1,Dial(SIP/some_SIP_friend)

but will work only if there is a channel defined in sip.conf as [some_SIP_friend], whose channel definition contains fromuser=sake, password=arigato, and host=thathostoverthere.tld.

An extension number is often attached after the address information, like this:

    exten => s,1,Dial(IAX2/user:pass@otherend.com/500)

This asks the far end to connect the call to extension 500 in the context in which the channel arrived. The extension is not required by Dial( ), as the information in the remote end's channel configuration file may be used, or the remote server will pass the call to the s extension in the context in which the call came in. Ultimately, the far end controls what happens to the callyou can only request a specific treatment.

If no ring-timeout is specified, the channel will ring indefinitely. This is not always a bad thing, so don't feel you need to set itjust be aware that "indefinitely" could mean a very long time. ring-timeout is specified in seconds. The ring timeout always follows the addressing information, like this:

    exten => s,1,Dial(IAX2/user:pass@otherend.com/500,ring-timeout)

Much of the power of the Dial( ) application is in the flags. These are assigned following the addressing and timeout information, like this:

    exten => s,1,Dial(IAX2/user:pass@otherend.com/500,60,flags)

Here's something important to note: if you don't have a timeout specified, and you want to assign flags, you must still assign a spot for the timeout. You do this by adding an extra comma in the spot where the timeout would normally go, like this:

    exten => s,1,Dial(IAX2/user:pass@otherend.com/500,,flags)


The valid flags that may be used with the Dial( ) application are:



d

Allows the user to dial a one-digit extension while waiting for a call to be answered. The call will then exit to that extension (either in the current context, if it exists, or in the context specified by ${EXITCONTEXT}).



t

Permits the called party to transfer a call by pressing the # key. Please note that if this option is used, reinvites are disabled, as Asterisk needs to monitor the call to detect when the called party presses the # key.



T

Permits the caller to transfer a connected call by pressing the # key. Again, note that if this option is used, reinvites are disabled, as Asterisk needs to monitor the call to detect when the caller presses the # key.



w

Permits the called user to start and stop recording the call audio to disk by pressing the automon sequence (as configured in features.conf). If the variable TOUCH_MONITOR is set, its value will be passed as the arguments to the Monitor( ) application when recording is started. If it is not set, the default values of WAV||m are passed to Monitor( ).



W

Permits the calling user to record the call audio to disk by pressing the automon sequence (as configured in features.conf).



f

Forces the Caller ID to be set as the extension of the line making or redirecting the outgoing call. This is done because some PSTN providers will not allow the Caller ID to be set to anything other than that which is assigned to you. For example, if you had a PRI, you would use the f flag to override any Caller ID set locally on a SIP phone.



o

Uses the Caller ID received on the inbound leg of the call for the Caller ID on the outbound leg of the call. This is useful if you are accepting a call and then forwarding it to another destination, but you wish to pass the Caller ID from the inbound leg of the call instead of overwriting it with the local Caller ID settings. This is the default behavior on Asterisk versions prior to 1.2.



r

Indicates ringing to the calling party, without passing any audio until the call is answered. This flag is not normally required to indicate ringing, as Asterisk will signal ringing if a channel is actually being called.



m[ class]

Provides music to the calling party until the call is answered. You may also optionally indicate the Music on Hold class.



M( x[ ^arg])

Executes the macro x upon the connection of a call, optionally passing arguments delimited by ^. The macro can also set the MACRO_RESULT channel variable to one of the following:



ABORT

Hangs up both legs of the call



CONGESTION

Acts as if the line encountered congestion



BUSY

Acts as if the line was busy (goes to n+101, where n is the current priority)



CONTINUE

Hangs up the called party and continues on in the dialplan



GOTO:<context>^<extension>^<priority>

Transfers the call to the specified destination



h

Allows the called user to hang up the channel by pressing *.



H

Allows the calling user to hang up the channel by pressing *.



C

Resets the Call Detail Record for the call. Since the CDR time is set to when you Answer( ) the call, you may wish to reset the CDR so the end user is not billed for the time prior to the Dial( ) application being invoked.



P[( x)]

Sets the privacy mode, optionally specifying x as the family/key value in the local AstDB. Useful for accepting calls based on a blacklist (explicitly denying calls from listed numbers) or whitelist (explicitly accepting calls from listed numbers). See also LookupBlacklist( ).



g

Goes on in the context if the destination channel hangs up.



G( context^ extension^ priority)

Transfers both parties to the specified destination, if the call is answered.



A( x)

Plays an announcement to the called party; x is the filename of the sound file to play as the announcement.



D([ called][: calling])

Sends DTMF digits after the call has been answered, but before the call is bridged. The called parameter is passed to the called party, and the calling parameter is passed to the calling party. Either parameter may be used individually.



L( x[: y][: z])

Limits the call to x milliseconds, warning when y milliseconds are left and repeating every z milliseconds until the limit is reached. The x parameter is required; the y and z parameters are optional. The following special variables may also be set to provide additional control:



LIMIT_PLAYAUDIO_CALLER=yes|no

Specifies whether to play sounds to the caller



LIMIT_PLAYAUDIO_CALLEE=yes|no

Specifies whether to play sounds to the callee



LIMIT_TIMEOUT_FILE= filename

Specifies which file to play when time is up



LIMIT_CONNECT_FILE= filename

Specifies which file to play when call begins



LIMIT_WARNING_FILE= filename

Specifies the file to play if the argument y is defined



n

Prevents jumping to priority n+101 (where n is the number of the current priority) if all channels are deemed busy.

A call may also be parked instead of being transferred (which is done with the t or T flags). Calls are normally parked by transferring them to extension 700, but that's configurable in the features.conf file.

The Dial( ) application sets the following variables upon exiting:



DIALEDTIME

The total time elapsed from execution of Dial( ) until completion.



ANSWEREDTIME

The total time elapsed during the call.



DIALSTATUS

The status of the call, set as one of the following values:



CHANUNAVAIL

The channel is unavailable.



CONGESTION

The channel returned a congestion signal, usually indicating that it was unable to complete the connection.



NOANSWER

The channel did not answer in the time indicated by the ring-timeout option.



BUSY

The dialed channel is currently busy.



ANSWER

The channel answered the call.



CANCEL

The call was cancelled.

    ; dial a seven-digit number on Zap channel 4
    exten => 123,1,Dial(Zap/4/2317154)

    ; dial the same number, but this time only have it ring for 
    10 seconds
    ; before continuing on with the dialplan
    exten => 124,1,Dial(Zap/4/2317154,10)
    exten => 124,2,Playback(im-sorry)
    exten => 124,3,Hangup(  )

    ; dial the same number, but this time with no timeout, and using the
    ; t, T, and m flags
    exten => 125,1,Dial(Zap/4/2317154,,tTm)

    ; dial extension 500 at a remote host (over the IAX protocol), using
    ; the specified username and password
    exten => 126,1,Dial(IAX/username:password@remotehost/500)

    ; dial a number, but limit the call to 5 minutes (300,000 
    milliseconds)
    ; start warning the caller 4 minutes (240,000 milliseconds) into 
      the call,
    ; and repeat the warning every 30 seconds (30,000 milliseconds)
    exten => 127,1,Dial(Zap/4/2317154,,L[300000:240000:30000])


Previous Page
Next Page
Asterisk