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

3.5. Compiling Asterisk

Once you've compiled and installed the zaptel and libpri packages (if you need them), you can move on to Asterisk. This section walks you through a standard installation and introduces some of the alternative make arguments that you may find useful. We'll also look at how you can edit the Makefile to optimize the compilation of Asterisk.

3.5.1. Standard Installation

Asterisk is compiled with gcc through the use of the GNU make program. Unlike many other programs, there is no need to run a configuration script for Asterisk. To get started compiling Asterisk, simply run the following commands (replace version with your version of Asterisk):

    # cd /usr/src/asterisk-version
    # make clean
    # make
    # make install
    # make samples

Be aware that compile times will vary between systems. On a current-generation processor, you shouldn't need to wait more than five minutes. At Astricon, someone reported successfully compiling Asterisk on a 133-MHz Pentium, but it took approximately five hours. You do the math.

Run the make samples command to install the default configuration files. Installing these files (instead of configuring each file manually) will allow you to get your Asterisk system up and running much faster. Many of the default values are fine for Asterisk. Files that require editing will be explained in future chapters.

If you already have configuration files installed in /etc/asterisk/ when you run the make samples command, .old will be appended to the end of each of your current configuration filesfor example, extensions.conf will be renamed extensions.conf.old. Be careful, though, because if you run make samples more than once you will overwrite your original configuration files!

The sample configuration files can also be found in the configs/ subdirectory within your Asterisk sources directory.


If you're using a system that makes use of the /etc/rc.d/init.d/ or /etc/init.d/ directories, you may wish to run the make config command as well. This will install the startup scripts and configure the system (through the use of the chkconfig command) to execute Asterisk automatically at startup.

3.5.2. Alternative make Arguments

There are several other make arguments that you can pass at compile time. While some of these will be discussed here, the remainder are used internally within the file and really have no bearing or use for the end user. (Of course, new functions may have been added, so be sure to check the Makefile for other options.)

Let's take a look at some useful make arguments.

3.5.2.1. make clean

The make clean command is used to remove the compiled binaries from within the source directory. This command should be run before you attempt to recompile or, if space is an issue, if you would like to clean up the files.

3.5.2.2. make update

This command is used to update the existing code from the Digium CVS server. If you downloaded the source code from the FTP server, you will receive an error stating so.

A common problem that you may find if you update with the cvs update command is that when you then do a show version at the Asterisk command-line interface (CLI), your version does not appear to have been updated. This problem can be resolved by removing the hidden .version file within the Asterisk source code directory before recompiling, or by using the make update command (which will remove the file for you).


3.5.2.3. make upgrade

If you run the make install command to install Asterisk after using the make update command to update from CVS, the .version file will not be updated. If you do not want to manually delete the .version file before running make and make install, you can use the make upgrade command instead.

3.5.2.4. make webvmail

The Asterisk Web Voicemail script is used to give a graphical interface to your voicemail account, allowing you to manage and interact with your voicemail remotely from a web browser.

When you run the make webvmail command, the Asterisk Web Voicemail script will be placed into the cgi-bin/ directory of your HTTP daemon. If you have specific policies with respect to security, be aware that it uses a setuid root Perl script. This command will install only on a Red Hat or Fedora box, as other distributions may have different paths to their cgi-bin/ directories. (This, of course, can be changed by editing the Makefile.)

3.5.2.5. make progdocs

This command will create documentation using the doxygen software from comments placed within the source code by the developers. You must have the appropriate doxygen software installed on your system in order for this to work. Note that doxygen assumes that the source code is well documented, which, sadly, is not always the case.

3.5.2.6. make mpg123

Asterisk uses the mpg123 program to stream MP3s during the use of Music on Hold (MoH). Because Asterisk only works with mpg123 v0.59r, this shortcut will determine if the correct version of mpg123 is installed on your system and, if not, will attempt to download, extract, and compile it for you. Be aware that newer versions will not work, and some distributions even symbolically link mpg321 and mpg123, which are entirely different programs. If you run the make install command after running this command, Asterisk will detect the directory and install it for you as well.

3.5.2.7. make config

The make config command will install Red Hat-style initialization scripts , if the /etc/rc.d/init.d or /etc/init.d directories are found to exist. If they do exist, the scripts are installed with file permissions equal to 755. If the script detects that /etc/rc.d/init.d/ exists, the chkconfig add asterisk command will also be run to cause Asterisk to be started automatically at boot time. This is not the case, however, with distributions that only use the /etc/init.d/ directory. Running make config will not do anything to an already running Asterisk process, or start one if it's not running.

This script currently is only really useful on a Red Hat-based system, although initialization scripts are available for other distributions (such as Gentoo, Mandrake, and Slackware) in the ./contrib./init.d/ directory of your Asterisk source directory.

3.5.3. Editing the Makefile

At the top of the Makefile contained within the Asterisk source directory are several options for optimizing the compilation of Asterisk. You can enable GSM codec optimizations (with the use of MMX instructions ), disable configuration file overwrites, add extra debugging information, change Asterisk's installation and staging directories, and modify which type of processor you are compiling for. While you may never edit or require any of these options, they are mentioned here for completeness.

3.5.3.1. Enabling GSM optimizations

Uncomment the following line in your Asterisk Makefile to enable GSM codec optimizations on x86 CPU architectures that support MMX instructions:

    #K6OPT = -DK6OPT

This includes newer Pentium processors, Pentium Pros, and the AMD K6 and K7 processors; however, you may not want to enable MMX support unless you have a true Intel processor, as problems have been reported with the MMX instructions on non-Intel processors.

3.5.3.2. Disabling configuration file overwrites

By default, Asterisk will overwrite your configuration files if you run make samples more than once. To change this behavior, change the y in the line below to n:

    OVERWRITE=y

3.5.3.3. Enabling debug profiling information

Debug symbols allow you to do symbolic debugging. The profiling information (-pg) flag will produce a file when you run Asterisk that can be processed in order to obtain information about how long (relatively) Asterisk spends in each function. Use of the -pg flag is not recommended for a normal build, but it may be useful during development. To enable profiling information, replace the -g in the following line with -pg:

    DEBUG=-g

3.5.3.4. Specifying where to install Asterisk after compiling

You can change the directory where Asterisk is installed by specifying a path on the following line:

    INSTALL_PREFIX=

3.5.3.5. Changing the staging directory

The staging directory is where Asterisk temporarily copies its files during the install process. You may want the files to be copied to a directory such as /tmp/asterisk/. If no staging directory is specified (the default), Asterisk will use the source directory. To specify a staging directory, enter the desired directory on this line:

    DESTDIR=

3.5.3.6. Compiling on VIA motherboards

On VIA-based motherboards, you need to set the processor to i586. If Asterisk detects the processor as i686, you may get random core dumps. To force Asterisk to compile using i586, remove the comment from the following PROC line in the Makefile (line 81, at the time of this writing):

    # Pentium & VIA processors optimize
    # PROC=i586

3.5.4. Using Precompiled Binaries

While the documented process of installing Asterisk expects you to compile the source code yourself, there are Linux distributions (such as Debian) that include precompiled Asterisk binaries . Failing that, you may be able to install Asterisk with the package managers that those distributions of Linux provide (such as apt-get for Debian and portage for Gentoo). However, you may also find that many of these prebuilt binaries are quite out of date and do not follow the same furious development cycle as Asterisk.

Finally, there do exist basic, precompiled Asterisk binaries that can be downloaded and installed in whatever Linux distribution you have chosen. However, the use of precompiled binaries doesn't really save much time, and we have found that compiling Asterisk with each install is not a very cumbersome task. We believe that the best way to install Asterisk is to compile from the source code, so we won't discuss prebuilt binaries very much in this book. In the next chapter, we'll look at how to initially configure Asterisk and several kinds of channels.


Previous Page
Next Page
Asterisk