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

4.6. Configuring SIP

The Session Initiation Protocol (SIP), often used in VoIP phones (either hard phones or soft phones), takes care of the setup and teardown of calls, along with any renegotiations during a call. Basically, it helps two endpoints talk to each other (if possible, directly to each other). SIP does not carry media; rather, it uses the Real-time Transport Protocol (RTP) to transfer the media[*] directly between phone A and phone B once the call has been set up.

[*] We use the term media to refer to the data transferred between endpoints and used to reconstruct your voice at the other end. It may also refer to music or prompts from the PBX.

4.6.1. SIP and RTP

SIP is an application-layer signaling protocol that uses the well-known port 5060 for communications. SIP can be transported with either the UDP or TCP transport-layer protocols. Asterisk does not currently have a TCP implementation for transporting SIP messages, but it is possible that future versions may support it (and patches to the code base are gladly accepted). SIP is used to "establish, modify, and terminate multimedia sessions such as Internet telephony calls."[*] SIP does not transport media between endpoints.

[*] RFC 3261, SIP: Session Initiation Protocol, p. 9, Section 2.

RTP is used to transmit media (i.e., voice) between endpoints. RTP uses high-numbered, unprivileged ports in Asterisk (10,000 through 20,000, by default).

A common topology to illustrate SIP and RTP, commonly referred to as the "SIP trapezoid," is shown in Figure 4-2. When Alice wants to call Bob, Alice's phone contacts her proxy server, and the proxy tries to find Bob (often connecting through his proxy). Once the phones have started the call, they communicate directly with each other (if possible), so that the data doesn't have to tie up the resources of the proxy.

Figure 4-2. The SIP trapezoid

SIP was not the first, and is not the only, VoIP protocol in use today (others include H.323, MGCP, IAX, and so on), but currently it seems to have the most momentum with hardware vendors. The advantages of the SIP protocol lie in its wide acceptance and architectural flexibility (and, we used to say, simplicity!).

4.6.2. SIP Configuration

Here is a basic sip.conf file:

    [general]
    context=default
    srvlookup=yes

    [john]
    type=friend
    secret=welcome
    qualify=yes                     ; Qualify peer is no more than 2000 ms away
    nat=no                          ; This phone is not natted
    host=dynamic                    ; This device registers with us
    canreinvite=no                  ; Asterisk by default tries to redirect
    context=internal                ; the internal context controls what we can do

The sip.conf file starts with a [general] section, which contains the channel settings and default options for all users and peers defined within sip.conf. You can override the default settings on a per-user/peer basis by configuring them within the user/peer definition.

Domain Name System Service records (DNS SRV records) are a way of setting up a logical, resolvable address where you can be reached. This allows calls to be forwarded to different locations without the need to change the logical address. By using SRV records, you gain many of the advantages of DNS, whereas disabling them breaks the SIP RFC and removes the ability to place SIP calls based on domain names. (Note that if multiple records are returned, Asterisk will use only the first.) DNS SRV record lookups are disabled by default in Asterisk, but it's highly recommended that you turn them on. To enable them, set srvlookup=yes in the [general] section of sip.conf.

Each connection is defined as a user, peer, or friend. A user type is used to authenticate incoming calls, a peer type is used for outgoing calls, and a friend type is used for both. The extension name is defined within square brackets ([]). In this case, we have defined the extension john as a friend.

A secret is a password used for authentication. Our secret is defined as welcome. We can monitor the latency between our Asterisk server and the phone with qualify=yes, thereby determining whether the remote device is reachable. qualify=yes can be used to monitor any end device, including other Asterisk servers. By default, Asterisk will consider an extension reachable if the latency is less than 2,000 ms (2 seconds). You can configure the time Asterisk should use when determining whether or not a peer is reachable by replacing yes with the number of milliseconds.

If an extension is behind a device performing Network Address Translation (NAT), such as a router or firewall, configure nat=yes to force Asterisk to ignore the contact information for the extension and use the address from which the packets are being received. Setting host=dynamic will require the extension to register so that Asterisk knows how to reach the phone. To limit an endpoint to a single IP address or fully qualified domain name (FQDN) , replace dynamic with the IP address or domain name. Note that this limits only where you place calls to, as the user is allowed to place calls from anywhere (assuming she has authenticated successfully). If you set host=static, the end device is not required to register.

We've also set canreinvite=no. In SIP, invites are used to set up calls and to redirect media. Any invite issued after the initial invite in the same dialog is referred to as a reinvite. For example, suppose two parties are exchanging media traffic. If one client goes on hold and Asterisk is configured to play Music on Hold (MoH), Asterisk will issue a reinvite to the secondary client, telling it to redirect its media stream toward the PBX. Asterisk is then able to stream music or an announcement to the on-hold client.

The primary client then issues an off-hold command in a reinvite to the PBX, which in turn issues a reinvite to the secondary party requesting that it redirect its media stream toward the primary party, thereby ending the on-hold music and reconnecting the clients.

Normally, when two endpoints set up a call they pass their media directly from one to the other. Asterisk generally breaks this rule by staying within the media path, allowing it to listen for digits dialed on the phone's keypad. This is necessary because if Asterisk cannot determine the call length, inaccurate billing can occur. Configuring canreinvite=no forces Asterisk to stay in the media path, not allowing RTP messages to be exchanged directly between the endpoints.

Asterisk will not issue a reinvite in any of the following situations:

  • If either of the clients is configured with canreinvite=no

  • If the clients cannot agree on a common set of codecs and Asterisk needs to perform codec conversion

  • If either of the clients is configured with nat=yes

  • If Asterisk needs to listen to Dual Tone Multi-Frequency (DTMF) tones during the call (for transfers or any other features)

Lastly, context=internal specifies the location of the instructions used to control what the phone is allowed to do, and what to do with incoming calls for this extension. The context name configured in sip.conf matches the name of the context in extensions.conf, which contains the instructions. More information about contexts and dialplans will be presented in the following chapter.

If you are configuring a number of clients with similar configurations, you can place like commands under the [general] heading. Asterisk will use the defaults specified in the [general] section unless they are explicitly changed within a client's configuration block.

4.6.3. Client Configuration

While it would be impossible to show all the possible configurations for all the end devices that can communicate with Asterisk, we feel it beneficial to provide the configuration for at least one free soft phone, which you can use in determining if Asterisk is right for your organization. We've chosen to use X-ten's X-Lite client , which you can download from their web site (http://www.xten.com).

The configuration of the client is generally straightforward. The most important parts are the username and password for registration, plus the address of the Asterisk server with which you wish to register. Figure 4-3 shows a sample configuration for the X-Lite client. Be sure to modify the values of the fields to reflect your configuration.

Figure 4-3. X-Lite soft phone configuration screen

The display name is the string that will be used for Caller ID. The username and authorization user are used for authentication, along with the password. The domain/realm should be the IP address or FQDN of your Asterisk server. The SIP proxy is the same as the one entered for the domain/realm, but with :5060 appended (this specifies the port number to use for SIP signalingbe sure it matches the port you have configured in sip.conf).

After entering all this information, verify that Enabled is set to Yes, and then close the configuration menu. X-Lite will then register to Asterisk. If X-Lite doesn't appear to register, simply restart the client. Because X-Lite is minimized to the task tray when you close the application with the X button, you will need to exit the program by right-clicking on the icon in the tray and then clicking "Exit" in the pop-up menu before restarting.

4.6.4. Dialplan Configuration

Many SIP phones, both soft and hard, are multi-line phones. This means they can accept multiple incoming calls at the same time. Thus, to test your X-Lite soft phone you can simply call yourself, and the call will loop back from the Asterisk server and onto line two of the client. To call yourself, dial extension 100. If your preferred client doesn't support multi-line functionality, you can use extension 611 to enter the Echo( ) test application.

    [internal]
    exten => 100,1,Dial(SIP/john)
    exten => 611,1,Echo( )


Previous Page
Next Page
Asterisk