Asterisk™: The Future of Telephony

Jim Van Meggelen

Leif Madsen

Jared Smith

Tolman Creek Design

Joe Wizda

Karen Montgomery

David Futato

Robert Romano

Jessamyn Read

Printed in the United States of America.

[M]

O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://safari.oreilly.com). For more information, contact our corporate/institutional sales department: (800) 998-9938 or .

Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of O’Reilly Media, Inc. Asterisk: The Future of Telephony, the image of starfish, and related trade dress are trademarks of O’Reilly Media, Inc. Asterisk™ is a trademark of Digium, Inc. Asterisk: The Future of Telephony is published under the Creative Commons “Commons Deed” license (http://creativecommons.org/licenses/by-nc-nd/2.5/ca/).

While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.

This book uses RepKover™, a durable and flexible lay-flat binding.


Dedication

This book is dedicated to Rich Adamson (1947–2006).

Thanks for showing us the meaning of community.

Table of Contents

Foreword
Preface
Audience
Organization
Software
Conventions Used in This Book
Using Code Examples
Safari® Books Online
How to Contact Us
Acknowledgments
Jim Van Meggelen
Leif Madsen
Jared Smith
1. A Telephony Revolution
VoIP: Bridging the Gap Between Traditional and Network Telephony
The Zapata Telephony Project
Massive Change Requires Flexible Technology
Asterisk: The Hacker’s PBX
Asterisk: The Professional’s PBX
The Asterisk Community
The Asterisk Mailing Lists
The Asterisk Wiki
The IRC Channels
Asterisk User Groups
The Asterisk Documentation Project
The Business Case
This Book
2. Preparing a System for Asterisk
Server Hardware Selection
Performance Issues
Choosing a Processor
Small systems
Medium systems
Large systems
Choosing a Motherboard
Power Supply Requirements
Computer power supplies
Redundant power supplies
Environment
Power Conditioning and Uninterruptible Power Supplies
Power-conditioned UPSes
Grounding
Electrical Circuits
The Equipment Room
Humidity
Temperature
Dust
Security
Telephony Hardware
Connecting to the PSTN
Analog interface cards
Digital interface cards
Channel banks
Other types of PSTN interfaces
Connecting Exclusively to a Packet-Based Telephone Network
Echo Cancellation
Types of Phones
Physical Telephones
Analog telephones
Proprietary digital telephones
ISDN telephones
IP telephones
Softphones
Telephony Adaptors
Communications Terminals
Linux Considerations
Conclusion
3. Installing Asterisk
What Packages Do I Need?
Linux Package Requirements
Obtaining the Source Code
Obtaining Asterisk Source Code
Extracting the Source Code
Menuselect
Compiling Zaptel
The ztdummy Driver
The Zapata Telephony Drivers
Using ztcfg and zttool
Compiling libpri
Compiling Asterisk
Standard Installation
Alternative make Arguments
make clean
make distclean
make update
make webvmail
make progdocs
make config
Using Precompiled Binaries
Installing Additional Prompts
Common Compiling Issues
Asterisk
configure: error: no acceptable C compiler found in $PATH
configure: error: C++ preprocessor "/lib/cpp" fails sanity check
configure: error: *** termcap support not found
Zaptel
make: cc: Command not found
FATAL: Module wctdm/fxs/fxo not found
Unresolved symbol link when loading ztdummy
Depmod errors during compilation
Loading Asterisk and Zaptel Quickly
Loading Zaptel Modules Without Scripts
Systems Running udevd
Loading Zaptel
Loading ztdummy
Loading libpri Without Script
Starting Asterisk Without Scripts
Console Commands
Directories Used by Asterisk
/etc/asterisk/
/usr/lib/asterisk/modules/
/var/lib/asterisk
/var/spool/asterisk/
/var/run/
/var/log/asterisk/
/var/log/asterisk/cdr-csv
AsteriskNOW
What Is AsteriskNOW?
Before You Begin
What You Will Need
Installation
Quick installation
Extended procedure
Accessing the GUI
Alternate Installations
For More Information
Conclusion
4. Initial Configuration of Asterisk
What Do I Really Need?
Working with Interface Configuration Files
Setting Up the Dialplan for Some Test Calls
FXO and FXS Channels
Determining the FXO and FXS Ports on Your TDM400P
Configuring an FXO Channel for a PSTN Connection
Zaptel Hardware Configuration
Zapata Hardware Configuration
Dialplan Configuration
Dialing In
Configuring an FXS Channel for an Analog Telephone
Zaptel Hardware Configuration
Zapata Hardware Configuration
Dialplan Configuration
Configuring SIP Telephones
Basic SIP Telephone Configuration in Asterisk
Defining the SIP device in Asterisk
Configuring the Device Itself
Essential Server Components
DHCP server
FTP server
CounterPath’s X-Lite Softphone
Polycom’s IP 430
DHCP server
Protocol to use for downloading
FTP
The Polycom configuration files
Cisco 7960 Telephone
Linksys SPA-942
Logging in to the phone
Registering your phone to Asterisk
Configuring the Dialplan for Testing
Connecting to a SIP Service Provider
Connecting Two Asterisk Boxes Together via SIP
Configuring Our Asterisk Boxes
SIP Phone Configuration
Configuring the Dialplan
Configuring an IAX Softphone
Configuring the Channel Configuration File (iax.conf)
Configure the Softphone
Configuring the Dialplan for Testing
Connecting to an IAX Service Provider
Connecting Two Asterisk Boxes Together via IAX
Configuring Our Asterisk Boxes
IAX Phone Configuration
Configuring the Dialplan
Using Templates in Your Configuration Files
Debugging
Connecting to the Console
Enabling Verbosity and Debugging
Conclusion
5. Dialplan Basics
Dialplan Syntax
Contexts
Extensions
Priorities
Unnumbered priorities
Priority labels
Applications
A Simple Dialplan
The s Extension
The Answer(), Playback(), and Hangup() Applications
Our First Dialplan
Building an Interactive Dialplan
The Background(), WaitExten(), and Goto() Applications
Handling Invalid Entries and Timeouts
Using the Dial() Application
Adding a Context for Internal Calls
Using Variables
Global variables
Channel variables
Environment variables
Adding variables to our dialplan
Pattern Matching
Pattern-matching syntax
Pattern-matching examples
Using the ${EXTEN} channel variable
Enabling Outbound Dialing
Includes
Conclusion
6. More Dialplan Concepts
Expressions and Variable Manipulation
Basic Expressions
Operators
Dialplan Functions
Syntax
Examples of Dialplan Functions
Conditional Branching
The GotoIf() Application
Time-Based Conditional Branching with GotoIfTime()
Voicemail
Creating Mailboxes
Adding Voicemail to the Dialplan
Accessing Voicemail
Creating a Dial-by-Name Directory
Macros
Defining Macros
Calling Macros from the Dialplan
Using Arguments in Macros
Using the Asterisk Database (AstDB)
Storing Data in the AstDB
Retrieving Data from the AstDB
Deleting Data from the AstDB
Using the AstDB in the Dialplan
Handy Asterisk Features
Zapateller()
Call Parking
Conferencing with MeetMe()
Conclusion
7. Understanding Telephony
Analog Telephony
Parts of an Analog Telephone
Ringer
Dial pad
Hybrid (or network)
Tip and Ring
Digital Telephony
Pulse-Code Modulation
Digitally encoding an analog waveform
Increasing the sampling resolution and rate
Nyquist’s Theorem
Logarithmic companding
Aliasing
The Digital Circuit-Switched Telephone Network
Circuit Types
The humble DS-0―the foundation of it all
T-carrier circuits
SONET and OC circuits
Digital Signaling Protocols
Channel Associated Signaling (CAS)
ISDN
Signaling System 7
Packet-Switched Networks
Conclusion
8. Protocols for VoIP
The Need for VoIP Protocols
VoIP Protocols
IAX (The “Inter-Asterisk eXchange” Protocol)
History
Future
Security considerations
IAX and NAT
SIP
History
Future
Security considerations
SIP and NAT
H.323
History
Future
Security considerations
H.323 and NAT
MGCP
Proprietary Protocols
Skinny/SCCP
UNISTIM
Codecs
G.711
G.726
G.729A
GSM
iLBC
Speex
MP3
Quality of Service
TCP, UDP, and SCTP
Transmission Control Protocol
User Datagram Protocol
Stream Control Transmission Protocol
Differentiated Service
Guaranteed Service
MPLS
RSVP
Best Effort
Echo
Why Echo Occurs
Managing Echo on Zaptel Channels
Hardware Echo Cancellation
Asterisk and VoIP
Users and Peers and Friends—Oh My!
Users
Peers
Friends
register Statements
VoIP Security
Spam over Internet Telephony (SPIT)
Encrypting Audio with Secure RTP
Spoofing
What Can Be Done?
Basic network security
Encryption
Physical security
Conclusion
9. The Asterisk Gateway Interface (AGI)
Fundamentals of AGI Communication
What Are STDIN, STDOUT, and STDERR?
The Standard Pattern of AGI Communication
Calling an AGI Script from the Dialplan
Writing AGI Scripts in Perl
The Perl AGI Library
Creating AGI Scripts in PHP
The PHP AGI Library
Writing AGI Scripts in Python
The Python AGI Library
Debugging in AGI
Debugging from the Operating System
Using Asterisk’s agi debug Command
Conclusion
10. Asterisk Manager Interface (AMI) and Adhearsion
The Manager Interface
Connecting to the Manager Interface
Sending Commands
Transferring a call
Reading a configuration file
Updating configuration files
The Flash Operator Panel
Asterisk Development with Adhearsion
A New Approach to Dialplans
Asterisk Development with Adhearsion
Installing Adhearsion
Installing Ruby/RubyGems on AsteriskNOW
Installing Ruby/RubyGems on Linux
Installing Ruby/RubyGems on Mac OS X
Ruby/RubyGems on Windows
Installing Adhearsion from RubyGems
Exploring a New Adhearsion Project
Adhearsion dialplan writing
Database integration
Distributing and reusing code
Integrate with Your Desk Phone Using Micromenus
Integrating with a Web Application
Using Java
More Information
11. The Asterisk GUI Framework
Why a GUI for Asterisk?
What Is the GUI?
Mark Spencer Talks About the GUI
Using the GUI
GUI elements
Architecture of the Asterisk GUI
Components of the Asterisk GUI
Asterisk Manager Interface
Manager over HTTP and the Asterisk web server
AJAM and JavaScript
Installing the Asterisk GUI
Setting up httpd.conf and manager.conf
Developing for the Asterisk GUI
Issuing Manager Commands over HTTP
LOGIN
Transferring a call
Reading a configuration file
Updating configuration files using UPDATECONFIG
Error response
Ajax, AJAM, and Asterisk
Form processing in a traditional web application
Form processing in an Ajax application
The Prototype framework
Customization of the GUI
Adding a new tab to the GUI
Exposing configuration settings in the GUI
For More Information
12. Relational Database Integration
Introduction
Installing the Database
Installing and Configuring ODBC
Configuring res_odbc for Access to Our Database
Using Realtime
Static Realtime
Dynamic Realtime
Storing Call Detail Records
Getting Funky with func_odbc: Hot-Desking
ODBC Voicemail
Creating the Large Object Type
Configuring voicemail.conf for ODBC Storage
Testing ODBC Voicemail
Conclusion
13. Managing Your Asterisk System
Call Detail Recording
Managing Logs
Running Asterisk As a Non-root User
Customizing System Prompts
Music on Hold
Conclusion
14. Potpourri
Festival
Getting Festival Set Up and Ready for Asterisk
Configuring Asterisk for Festival
Starting the Festival Server
Calling Festival from the Dialplan
Call Files
DUNDi
How Does DUNDi Work?
Configuring Asterisk for Use with DUNDi
The General Peering Agreement
General configuration
Creating mapping contexts
Defining DUNDi peers
Allowing remote connections
Configuring the dialplan
Alternative Voicemail Storage Methods
Storing Voicemail in an IMAP Server
Storing Voicemail in an ODBC Database
Asterisk and Jabber (XMPP)
Conclusion
15. Asterisk: The Future of Telephony
The Problems with Traditional Telephony
Closed Thinking
Limited Standards Compliancy
Slow Release Cycles
Refusing to Let Go of the Past and Embrace the Future
Paradigm Shift
The Promise of Open Source Telephony
The Itch That Asterisk Scratches
Open Architecture
Standards Compliance
Lightning-Fast Response to New Technologies
Passionate Community
Some Things That Are Now Possible
Legacy PBX migration gateway
Low-barrier IVR
Conference rooms
Home automation
The Future of Asterisk
Speech Processing
Festival
Speech recognition
High-Fidelity Voice
Video
The challenge of video-conferencing
Why we love video-conferencing
Why video-conferencing may never totally replace voice
Wireless
Wi-Fi
Wi-MAX
Unified Messaging
Peering
E.164
ENUM
e164.org
DUNDi
Challenges
Too much change, too few standards
VoIP spam
Fear, uncertainty, and doubt
Bottleneck engineering
Regulatory wars
Quality of service
Complexity
Opportunities
Tailor-made private telecommunications networks
Low barrier to entry
Hosted solutions of similar complexity to corporate web sites
Proper integration of communications technologies
A. VoIP Channels
IAX
General IAX Settings
Registering to Other Servers with register Statements
IAX Channel Definitions
Channel-specific parameters
SIP
General SIP Parameters
SIP Channel Definitions
B. Application Reference
AddQueueMember()
ADSIProg()
AgentCallbackLogin()
AgentLogin()
AgentMonitorOutgoing()
AGI()
AlarmReceiver()
AMD()
Answer()
AppendCDRUserField()
Authenticate()
Background()
BackgroundDetect()
Busy()
ChangeMonitor()
ChanIsAvail()
ChannelRedirect()
ChanSpy()
Congestion()
ContinueWhile()
ControlPlayback()
DateTime()
DBdel()
DBdeltree()
DeadAGI()
Dial()
Dictate()
Directory()
DISA()
DumpChan()
EAGI()
Echo()
EndWhile()
Exec()
ExecIf()
ExitWhile()
ExtenSpy()
ExternalIVR()
FastAGI()
Festival()
Flash()
FollowMe()
ForkCDR()
GetCPEID()
Gosub()
GosubIf()
Goto()
GotoIf()
GotoIfTime()
Hangup()
HasNewVoicemail()
HasVoicemail()
IAX2Provision()
ICES()
ImportVar()
Log()
LookupBlacklist()
LookupCIDName()
Macro()
MacroExclusive()
MacroExit()
MacroIf()
MailboxExists()
MeetMe()
MeetMeAdmin()
MeetMeCount()
Milliwatt()
MixMonitor()
Monitor()
MorseCode()
MP3Player()
MusicOnHold()
NBScat()
NoCDR()
NoOp()
Page()
Park()
ParkAndAnnounce()
ParkedCall()
PauseMonitor()
PauseQueueMember()
Pickup()
Playback()
Playtones()
PrivacyManager()
Progress()
Queue()
QueueLog()
Random()
Read()
ReadFile()
RealTime
RealTimeUpdate()
Record()
RemoveQueueMember()
ResetCDR()
RetryDial()
Return()
Ringing()
SayAlpha()
SayDigits()
SayNumber()
SayPhonetic()
SayUnixTime()
SendDTMF()
SendImage()
SendText()
SendURL()
Set()
SetAMAFlags()
SetCallerID()
SetCallerPres()
SetCDRUserField()
SetGlobalVar()
SetMusicOnHold()
SetTransferCapability()
SIPAddHeader()
SIPDtmfMode()
SLAStation()
SLATrunk()
SoftHangup()
StackPop()
StartMusicOnHold()
StopMixMonitor()
StopMonitor()
StopPlaytones()
StopMusicOnHold()
System()
Transfer()
TryExec()
TrySystem()
UnpauseMonitor()
UnpauseQueueMember()
UserEvent()
Verbose()
VMAuthenticate()
VoiceMail()
VoiceMailMain()
Wait()
WaitExten()
WaitForRing()
WaitForSilence()
WaitMusicOnHold()
While()
Zapateller()
ZapBarge()
ZapRAS()
ZapScan()
AddQueueMember()
ADSIProg()
AgentCallbackLogin()
AgentLogin()
AgentMonitorOutgoing()
AGI()
AlarmReceiver()
AMD()
Answer()
AppendCDRUserField()
Authenticate()
Background()
BackgroundDetect()
Busy()
ChangeMonitor()
ChanIsAvail()
ChannelRedirect()
ChanSpy()
Congestion()
ContinueWhile()
ControlPlayback()
DateTime()
DBdel()
DBdeltree()
DeadAGI()
Dial()
Dictate()
Directory()
DISA()
DumpChan()
EAGI()
Echo()
EndWhile()
Exec()
ExecIf()
ExitWhile()
ExtenSpy()
ExternalIVR()
FastAGI()
Festival()
Flash()
FollowMe()
ForkCDR()
GetCPEID()
Gosub()
GosubIf()
Goto()
GotoIf()
GotoIfTime()
Hangup()
HasNewVoicemail()
HasVoicemail()
IAX2Provision()
ICES()
ImportVar()
Log()
LookupBlacklist()
LookupCIDName()
Macro()
MacroExclusive()
MacroExit()
MacroIf()
MailboxExists()
MeetMe()
MeetMeAdmin()
MeetMeCount()
Milliwatt()
MixMonitor()
Monitor()
MorseCode()
MP3Player()
MusicOnHold()
NBScat()
NoCDR()
NoOp()
Page()
Park()
ParkAndAnnounce()
ParkedCall()
PauseMonitor()
PauseQueueMember()
Pickup()
Playback()
Playtones()
PrivacyManager()
Progress()
Queue()
QueueLog()
Random()
Read()
ReadFile()
RealTime
RealTimeUpdate()
Record()
RemoveQueueMember()
ResetCDR()
RetryDial()
Return()
Ringing()
SayAlpha()
SayDigits()
SayNumber()
SayPhonetic()
SayUnixTime()
SendDTMF()
SendImage()
SendText()
SendURL()
Set()
SetAMAFlags()
SetCallerID()
SetCallerPres()
SetCDRUserField()
SetGlobalVar()
SetMusicOnHold()
SetTransferCapability()
SIPAddHeader()
SIPDtmfMode()
SLAStation()
SLATrunk()
SoftHangup()
StackPop()
StartMusicOnHold()
StopMixMonitor()
StopMonitor()
StopPlaytones()
StopMusicOnHold()
System()
Transfer()
TryExec()
TrySystem()
UnpauseMonitor()
UnpauseQueueMember()
UserEvent()
Verbose()
VMAuthenticate()
VoiceMail()
VoiceMailMain()
Wait()
WaitExten()
WaitForRing()
WaitForSilence()
WaitMusicOnHold()
While()
Zapateller()
ZapBarge()
ZapRAS()
ZapScan()
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
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
D. Configuration Files
modules.conf
adsi.conf
adtranvofr.conf
agents.conf
alarmreceiver.conf
alsa.conf
amd.conf
asterisk.conf
cdr.conf
cdr_manager.conf
cdr_odbc.conf
cdr_pgsql.conf
cdr_tds.conf
codecs.conf
dnsmgr.conf
dundi.conf
enum.conf
extconfig.conf
extensions.conf
extensions.ael
features.conf
festival.conf
followme.conf
func_odbc.conf
gtalk.conf
http.conf
iax.conf
iaxprov.conf
indications.conf
jabber.conf
logger.conf
[general]
[logfiles]
manager.conf
meetme.conf
mgcp.conf
modem.conf
musiconhold.conf
osp.conf
oss.conf
phone.conf
privacy.conf
queues.conf
res_odbc.conf
res_snmp.conf
rpt.conf
rtp.conf
say.conf
sip.conf
sip_notify.conf
skinny.conf
sla.conf
smdi.conf
udptl.conf
users.conf
voicemail.conf
General Voicemail Settings
Voicemail Zones
Defining Voicemail Contexts and Mailboxes
vpb.conf
zapata.conf
zaptel.conf
E. Asterisk Dialplan Functions
AGENT
ARRAY
BASE64_DECODE
BASE64_ENCODE
BLACKLIST
CALLERID
CDR
CHANNEL
CHECK_MD5
CHECKSIPDOMAIN
CURL
CUT
DB
DB_DELETE
DB_EXISTS
DUNDILOOKUP
ENUMLOOKUP
ENV
EVAL
EXISTS
FIELDQTY
FILTER
GLOBAL
GROUP
GROUP_COUNT
GROUP_LIST
GROUP_MATCH_COUNT
IAXPEER
IF
IFTIME
ISNULL
KEYPADHASH
LANGUAGE
LEN
MATH
MD5
MUSICCLASS
QUEUE_MEMBER_COUNT
QUEUE_MEMBER_LIST
QUEUE_WAITING_COUNT
QUEUEAGENTCOUNT
QUOTE
RAND
REALTIME
REGEX
SET
SHA1
SIP_HEADER
SIPCHANINFO
SIPPEER
SORT
SPEECH
SPEECH_ENGINE
SPEECH_GRAMMAR
SPEECH_SCORE
SPEECH_TEXT
SPRINTF
STAT
STRFTIME
STRPTIME
TIMEOUT
TXTCIDNAME
URIDECODE
URIENCODE
VMCOUNT
AGENT
ARRAY
BASE64_DECODE
BASE64_ENCODE
BLACKLIST
CALLERID
CDR
CHANNEL
CHECK_MD5
CHECKSIPDOMAIN
CURL
CUT
DB
DB_DELETE
DB_EXISTS
DUNDILOOKUP
ENUMLOOKUP
ENV
EVAL
EXISTS
FIELDQTY
FILTER
GLOBAL
GROUP
GROUP_COUNT
GROUP_LIST
GROUP_MATCH_COUNT
IAXPEER
IF
IFTIME
ISNULL
KEYPADHASH
LANGUAGE
LEN
MATH
MD5
MUSICCLASS
QUEUE_MEMBER_COUNT
QUEUE_MEMBER_LIST
QUEUE_WAITING_COUNT
QUEUEAGENTCOUNT
QUOTE
RAND
REALTIME
REGEX
SET
SHA1
SIP_HEADER
SIPCHANINFO
SIPPEER
SORT
SPEECH
SPEECH_ENGINE
SPEECH_GRAMMAR
SPEECH_SCORE
SPEECH_TEXT
SPRINTF
STAT
STRFTIME
STRPTIME
TIMEOUT
TXTCIDNAME
URIDECODE
URIENCODE
VMCOUNT
F. Asterisk Manager Interface Actions
AbsoluteTimeout
AgentCallbackLogin
AgentLogoff
Agents
ChangeMonitor
Command
DBGet
DBPut
Events
ExtensionState
GetConfig
GetVar
Hangup
IAXNetstats
IAXPeers
ListCommands
Logoff
MailboxCount
MailboxStatus
MeetmeMute
MeetMeUnmute
Monitor
Originate
Park
ParkedCalls
PauseMonitor
Ping
PlayDTMF
QueueAdd
QueuePause
QueueRemove
QueueStatus
Queues
Redirect
SIPpeers
SIPShowPeer
SetCDRUserField
SetVar
Status
StopMonitor
UnpauseMonitor
UpdateConfig
UserEvent
WaitEvent
ZapDNDoff
ZapDNDon
ZapDialOffhook
ZapHangup
ZapRestart
ZapShowChannels
ZapTransfer
AbsoluteTimeout
AgentCallbackLogin
AgentLogoff
Agents
ChangeMonitor
Command
DBGet
DBPut
Events
ExtensionState
GetConfig
GetVar
Hangup
IAXNetstats
IAXPeers
ListCommands
Logoff
MailboxCount
MailboxStatus
MeetmeMute
MeetMeUnmute
Monitor
Originate
Park
ParkedCalls
PauseMonitor
Ping
PlayDTMF
QueueAdd
QueuePause
QueueRemove
QueueStatus
Queues
Redirect
SIPpeers
SIPShowPeer
SetCDRUserField
SetVar
Status
StopMonitor
UnpauseMonitor
UpdateConfig
UserEvent
WaitEvent
ZapDNDoff
ZapDNDon
ZapDialOffhook
ZapHangup
ZapRestart
ZapShowChannels
ZapTransfer
G. An Example of func_odbc
Hot-Desking (extensions.conf)
Hot-Desking (func_odbc.conf)
Hot-Desking (sip.conf)
Hot-Desking (extensions.conf)
Hot-Desking (func_odbc.conf)
Hot-Desking (sip.conf)
Index

List of Figures

2.1. Visual identification of PCI slots
2.2. One way you might connect a channel bank
3.1. Sample menuselect screen
3.2. List of modules to be built
3.3. Layers of device interaction with Asterisk
3.4. /var/spool/asterisk/ directory structure
4.1. A TDM400P with an FXS module (1 across) and an FXO module (2 across)
4.2. X-Lite configuration
4.3. X-Lite user configuration
4.4. SPA-942 keypad
4.5. SIP trunking topology
4.6. idefisk
4.7. idefisk Account Options screen
7.1. Tip and Ring
7.2. A simple sinusoidal (sine) wave
7.3. Sampling our sine wave using four bits
7.4. PCM encoded waveform
7.5. Plotted PCM signal
7.6. Delineated signal
7.7. The same waveform, on a higher-resolution overlay
7.8. The same waveform at double the resolution
7.9. Five-bit plotted PCM signal
7.10. Waveform delineated from five-bit PCM
7.11. Five-bit companding
7.12. Quantized and companded at 5-bit resolution
8.1. The SIP trapezoid
8.2. Call origination relationships of users, peers, and friends to Asterisk
10.1. The Flash Operator Panel management interface
11.1. A screenshot of the Asterisk GUI
12.1. Relationships between func_odbc.conf, res_odbc.conf, /etc/odbc.ini (unixODBC), and the database connection
15.1. Asterisk as a PBX gateway
15.2. Find-me-follow-me
15.3. VoIP-enabling a legacy PBX
A.1. Trunking disabled
A.2. Trunking enabled

List of Tables

2.1. System requirement guidelines
2.2. Sample test results for SIPp default scenario using simple Wait() and Playback() application; SIPp echoed media back to Asterisk
3.1. List of packages required to compile libpri, zaptel, and asterisk
3.2. Asterisk initialization script options
3.3. Zaptel initialization script options
7.1. DTMF digits
7.2. T-carrier circuits
7.3. OC circuits
8.1. Codec quick reference

Foreword

Once upon a time, there was a boy

...with a computer

...and a phone.

This simple beginning begat much trouble!

It wasn’t that long ago that telecommunications, both voice and data, as well as software, were all proprietary products and services, controlled by one select club of companies that created the technologies, and another select club of companies who used the products to provide services. By the late 1990s, data telecommunications had been opened by the expansion of the Internet. Prices plummeted. New and innovative technologies, services, and companies emerged. Meanwhile, the work of free software pioneers like Richard Stallman, Linus Torvalds, and countless others was culminating in the creation of a truly open software platform called Linux (or GNU/Linux). However, voice communications, ubiquitous as they were, remained proprietary. Why? Perhaps it was because voice on the old public telephone network lacked the glamor and promise of the shiny new World Wide Web. Or, perhaps it was because a telephone just wasn’t as effective at supplying adult entertainment. Whatever the reason, one thing was clear. Open source voice communications was about as widespread as open source copy protection software.

Necessity (and in some cases simply being cheap) is truly the mother of invention. In 1999, having started Linux Support Services to offer free and commercial technical support for Linux, I found myself in need (or at least in perceived need) of a phone system to assist me in providing 24-hour technical support. The idea was that people would be able to call in, enter their customer identity, and leave a message. The system would in turn page a technician to respond to the customer’s request in short order. Since I had started the company with about $4,000 of capital, I was in no position to be able to afford a phone system of the sort that I needed to implement this scenario. Having already been a Linux user since 1994, and having already gotten my feet wet in open source software development by starting l2tpd, Gaim, and cheops, and in the complete absence of anyone having explained the complexity of such a task, I decided that I would simply make my own phone system using hardware borrowed from Adtran, where I had worked as a co-op student. Once I got a call into a PC, I fantasized, I could do anything with it. In fact, it is from this conjecture that the official Asterisk motto (which any sizable, effective project must have) is derived:

It’s only software!

For better or worse, I rarely think small. Right from the start, it was my intent that Asterisk would do everything related to telephony. The name “Asterisk” was chosen because it was both a key on a standard telephone and also the wildcard symbol in Linux (e.g., rm -rf *).

So, in 1999, I had a free telephony platform I’d put out on the Web and I went about my business trying to eke out a living at providing Linux technical support. However, by 2001, as the economy was tanking, it became apparent that Linux Support Services might do better by pursuing Asterisk than general-purpose Linux technical support. That year, we would make contact with Jim “Dude” Dixon of the Zapata Telephony project. Dude’s exciting work was a fantastic companion to Asterisk and provided a business model for us to start pursuing Asterisk with more focus. After creating our first PCI telephony interface card in conjunction with Dude, it became clear that “Linux Support Services” was not the best name for a telephony company, and so we changed the name to “Digium,” which is a whole other story that cannot be effectively conveyed in writing. Enter the expansion of Voice over IP (VoIP) with its disruptive transition of voice from the old, circuit-switched networks to new IP-based networks, and things really started to take hold.

Now, as we’ve already covered, clearly most people don’t get very excited about telephones. Certainly, few people could share my excitement the moment I heard a dial tone coming from a phone connected to my PC. However, those who do get excited about telephones get really excited about telephones. And facilitated by the Internet, this small group of people were now able to unite and apply our bizarre passions to a common, practical project for the betterment of many.

To say that telecom was ripe for an open source solution would be an immeasurable understatement. Telecom is an enormous market due to the ubiquity of telephones in work and personal life. The direct market for telecom products has a highly technical audience that is willing and able to contribute. People demand their telecom solutions be infinitely customizable. Proprietary telecom is very expensive. Creating Asterisk was simply the spark in this fuel-rich backdrop.

Asterisk sits at the apex of a variety of transitions (proprietary → open source; circuit switched → VoIP; voice only → voice, video, and data; digital signal processing → host media processing; centralized directory → peer to peer) while easing those transitions by providing bridges back to the older ways of doing things. Asterisk can talk to anything from a 1960s-era pulse-dial phone to the latest wireless VoIP devices, and provide features from simple tandem switching all the way to Bluetooth presence and DUNDi.

Most important of all, though, Asterisk demonstrates how a community of motivated people and companies can work together to create a project with a scope so significant that no one person or company could have possibly created it on its own. In making Asterisk possible, I particularly would like to thank Linus Torvalds, Richard Stallman, the entire Asterisk community, and whoever invented Red Bull.

So where is Asterisk going from here? Think about the history of the PC. When it was first introduced in 1980, it had fairly limited capabilities. Maybe you could do a spreadsheet, maybe do some word processing, but in the end, not much. Over time, however, its open architecture led to price reductions and new products allowing it to slowly expand its applications, eventually displacing the mini computer, then the mainframe. Now, even Cray supercomputers are built using Linux-based x86 architectures. I anticipate that Asterisk’s future will look very similar. Today, there is a large subset of telephony that is served by Asterisk. Tomorrow, who knows what the limit might be?

So, what are you waiting for? Read, learn, and participate in the future of open telecommunications by joining the Asterisk revolution!

—Mark Spencer

Preface

This is a book for anyone who is new to Asterisk™.

Asterisk is an open source, converged telephony platform, which is designed primarily to run on Linux. Asterisk combines more than 100 years of telephony knowledge into a robust suite of tightly integrated telecommunications applications. The power of Asterisk lies in its customizable nature, complemented by unmatched standards compliance. No other PBX can be deployed in so many creative ways.

Applications such as voicemail, hosted conferencing, call queuing and agents, music on hold, and call parking are all standard features built right into the software. Moreover, Asterisk can integrate with other business technologies in ways that closed, proprietary PBXes can scarcely dream of.

Asterisk can appear quite daunting and complex to a new user, which is why documentation is so important to its growth. Documentation lowers the barrier to entry and helps people contemplate the possibilities.

Produced with the generous support of O’Reilly Media, Asterisk: The Future of Telephony was inspired by the work started by the Asterisk Documentation Project. We have come a long way, and this book is the realization of a desire to deliver documentation that introduces the most fundamental elements of Asterisk—the things someone new to Asterisk needs to know. It is the first volume in what we are certain will become a huge library of knowledge relating to Asterisk.

This book was written for, and by, the Asterisk community.

Audience

This book is for those new to Asterisk, but we assume that you’re familiar with basic Linux administration, networking, and other IT disciplines. If not, we encourage you to explore the vast and wonderful library of books that O’Reilly publishes on these subjects. We also assume you’re fairly new to telecommunications, both traditional switched telephony and the new world of Voice over IP.

Organization

The book is organized into these chapters:

Chapter 1, A Telephony Revolution

This is where we chop up the kindling and light the fire. Asterisk is going to change the world of telecom, and this is where we discuss our reasons for that belief.

Chapter 2, Preparing a System for Asterisk

Covers some of the engineering considerations you should have in mind when designing a telecommunications system. Much of this material can be skipped if you want to get right to installing, but these are important concepts to understand, should you ever plan on putting an Asterisk system into production.

Chapter 3, Installing Asterisk

Covers the obtaining, compiling, and installation of Asterisk.

Chapter 4, Initial Configuration of Asterisk

Describes the initial configuration of Asterisk. Here we will cover the important configuration files that must exist to define the channels and features available to your system.

Chapter 5, Dialplan Basics

Introduces the heart of Asterisk, the dialplan.

Chapter 6, More Dialplan Concepts

Goes over some more advanced dialplan concepts.

Chapter 7, Understanding Telephony

Taking a break from Asterisk, this chapter discusses some of the more important technologies in use in the Public Telephone Network.

Chapter 8, Protocols for VoIP

Following the discussion of legacy telephony, this chapter discusses Voice over Internet Protocol.

Chapter 9, The Asterisk Gateway Interface (AGI)

Introduces one of the more amazing components, the Asterisk Gateway Interface. Using Perl, PHP, and Python, we demonstrate how external programs can be used to add nearly limitless functionality to your PBX.

Chapter 10, Asterisk Manager Interface (AMI) and Adhearsion

Describes how external applications can connect to Asterisk to manipulate or monitor various aspects of the system. Also included in this chapter is a gentle introduction to the Adhearsion framework.

Chapter 11, The Asterisk GUI Framework

The Asterisk GUI Framework, new in Asterisk 1.4, is a framework system that allows web developers to create graphical interfaces with minimal interference to the standard configuration files.

Chapter 12, Relational Database Integration

Walks you through setting up Asterisk to work with ODBC databases.

Chapter 13, Managing Your Asterisk System

Discusses issues regarding how to best manage your Asterisk phone system, including CDR, logs, and prompts.

Chapter 14, Potpourri

Briefly covers what is, in fact, a rich and varied cornucopia of incredible features and functions—all part of the Asterisk phenomenon.

Chapter 15, Asterisk: The Future of Telephony

Predicts a future where open source telephony completely transforms an industry desperately in need of a revolution.

Appendix A, VoIP Channels, VoIP Channels

Appendix B, Application Reference, Application Reference

Appendix C, AGI Reference, AGI Reference

Appendix D, Configuration Files, Configuration Files

Appendix E, Asterisk Dialplan Functions, Asterisk Dialplan Functions

Appendix F, Asterisk Manager Interface Actions, Asterisk Manager Interface Actions

Appendix G, An Example of func_odbc, An Example of func_odbc

Software

This book is focused on documenting Asterisk Version 1.4; however, many of the conventions and information in this book are version-agnostic. Linux is the operating system we have run and tested Asterisk on, with a leaning toward Red Hat syntax. We decided that while Red Hat–based distributions may not be the preferred choice of everyone, their layout and utilities are nevertheless familiar to many experienced Linux administrators.

Conventions Used in This Book

The following typographical conventions are used in this book:

Italic

Indicates new terms, URLs, email addresses, filenames, file extensions, pathnames, directories, and Unix utilities.

Constant width

Indicates commands, options, parameters, and arguments that must be substituted into commands.

Constant width bold

Shows commands or other text that should be typed literally by the user. Also used for emphasis in code.

Constant width italic

Shows text that should be replaced with user-supplied values.

[ Keywords and other stuff ]

Indicates optional keywords and arguments.

{ choice-1 | choice-2 }

Signifies either choice-1 or choice-2.

Tip

This icon signifies a tip, suggestion, or general note.

Warning

This icon indicates a warning or caution.

Using Code Examples

This book is here to help you get your job done. In general, you may use the code in this book in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission.

We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Asterisk: The Future of Telephony, Second Edition, by Jim Van Meggelen, Leif Madsen, and Jared Smith. Copyright 2007 O’Reilly Media, Inc., 978-0-596-51048-0.”

If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at .

Safari® Books Online

Note

When you see a Safari® Books Online icon on the cover of your favorite technology book, that means the book is available online through the O’Reilly Network Safari Bookshelf.

Safari offers a solution that’s better than e-books. It’s a virtual library that lets you easily search thousands of top tech books, cut and paste code samples, download chapters, and find quick answers when you need the most accurate, current information. Try it for free at http://safari.oreilly.com.

How to Contact Us

Please address comments and questions concerning this book to the publisher:

O’Reilly Media, Inc.
1005 Gravenstein Highway North
Sebastopol, CA 95472
(800) 998-9938 (in the United States or Canada)
(707) 829-0515 (international or local)
(707) 829-0104 (fax)

We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at:

http://www.oreilly.com/catalog/9780596510480

To comment or ask technical questions about this book, send email to:

For more information about our books, conferences, Resource Centers, and the O’Reilly Network, see our web site at:

http://www.oreilly.com

Acknowledgments

Firstly, we have to thank our fantastic editor Michael Loukides, who offered invaluable feedback and found incredibly tactful ways to tell us to rewrite a section (or chapter) when it was needed, and have us think it was our idea. Mike built us up when we were down, and brought us back to earth when we got uppity. You are a master, Mike, and seeing how many books have received your editorial oversight contributes to an understanding of why O’Reilly Media is the success that it is.

Thanks also to Sanders Kleinfeld, our copy editor, Laurel Ruma, our production editor, and the rest of the unsung heroes in O’Reilly’s production department. These are the folks that take our book and make it an O’Reilly book.

Everyone in the Asterisk community needs to thank Jim Dixon for creating the first open source telephony hardware interfaces, starting the revolution, and giving his creations to the community at large.

Thanks to Tim O’Reilly, for giving us a chance to write this book.

To our most generous and merciless review team:

  • Rich Adamson, President of Network Partners Inc., for your encyclopedic knowledge of the PSTN, and your tireless willingness to share your experience. Your generosity, even in the face of daunting challenge, is inspiring to us all.[1]

  • Tilghman Lesher, for an incredibly thorough review of our book, contributing some much needed time toward Appendixes B and F, in addition to some amazing new Asterisk applications and functions.

  • Andrew Kohlsmith, for helping to write the IMAP voicemail storage section in Chapter 14, Potpourri.

  • David Troy, for providing a technical review, for AstManProxy, and for porting Asterisk to the Roomba (first PBX to run on a vacuum cleaner!).

  • Matthew Gast, fellow O’Reilly author, for reading our book from cover to cover, and then giving us a comprehensive review, and also for T1, The Definitive Guide.

  • Dr. Edward Guy III, for your comprehensive and razor-sharp evaluation of each and every chapter of the first edition, and for your championing of Asterisk.

  • Kristian Kielhofner, President, KrisCompanies, and creator of AstLinux, for the most excellent AstLinux distribution.

  • Russell Bryant, for your rapid and helpful responses to our questions.

  • Joshua Colp, for helping us with performance tweaking, and still more questions.

  • Kevin Fleming, for raising the bar, and for being a class act, respected (dare we say loved) by all.

  • Brian Capouch, for talking about what is possible, and then going out there and doing it.

  • Stephen Uhler, for championing the port of Zaptel to Solaris, and for giving us some golden examples.

  • Jason Parker, for not being a newb.

  • Ekke Loo, for beating up the database chapter.

  • Ian Darwin, for tweaking some of the verbiage for us, and for the cherry-red rotary dial phone (that works with Asterisk!).

  • Joel Sisko, CEO, iConverged, for your comprehensive telecom and wiring knowledge.

Finally, and most importantly, thanks go to Mark Spencer for Gaim (recently renamed Pidgin, www.pidgin.im), Asterisk, and DUNDi, and for contributing his creations to the open source community.

Jim Van Meggelen

For me, it all started in the spring of 2004, sitting at my desk in the technical support department of the telecom company I’d worked at for nearly 15 years. With no challenges to properly exercise the skills I had developed, I spent my time trying to figure out what the rest of my career was going to look like. The telecommunications industry had fallen from the pedestal of being a darling of investors to being a joke known to even the most uninformed. I was supposed to feel fortunate to be one of the few who still had work, but what thankless, purposeless work it was. We knew why our industry had collapsed: the products we sold could not hope to deliver the solutions our customers required—even though the industry promised that they could. They lacked flexibility, and were priced totally out of step with the functionality they were delivering (or, more to the point, were failing to deliver). Nowhere in the industry were there any signs this was going to change any time soon.

I had been dreaming of an open source PBX for many long years, but I really didn’t know how such a thing could ever come to be—I’d given up on the idea several years before. I knew that to be successful, an open source PBX would need to effectively bridge the worlds of legacy and network-based telecom. I always failed to find anything that seemed ready.

Then, one fine day in spring, I half-heartedly seeded a Google search with the phrase “open source telephony,” and discovered a bright new future for telecom: Asterisk, the open source Linux PBX.[2]

There it was: the very thing I’d been dreaming of for so many years. I had no idea how I was going to contribute, but I knew this: open source telephony was going to cause a necessary and beneficial revolution in the telecom industry, and one way or another, I was going to be a part of it.

For me, more of a systems integrator than developer, I needed a way to contribute to the community. There didn’t seem to be a shortage of developers, but there sure was a shortage of documentation. This sounded like something I could do. I knew how to write, I knew PBXes, and I desperately needed to talk about this phenomenon that suddenly made telecom fun again.

If I contribute only one thing to this book, I hope you will catch some of my enthusiasm for the subject of open source telephony. This is an incredible gift we have been given, but also an incredible responsibility. What a wonderful challenge. What a cosmic opportunity. What delicious fun!

First of all, I need to thank Leif and Jared for inviting me to join the Asterisk Documentation Project. I have immensely enjoyed working with both of you, and I am constantly amazed at how well our personalities and skills complement each other. A truly balanced team, are we. Also, thanks goes to Figment for all the typing.

To my wife Killi, and my children Kaara, Joonas, and Joosep (who always remember to visit me when I disappear into my underground lair for too long): you are a source of inspiration to me. Your love is the fuel that feeds my fire, and I thank you.

Obviously, I need to thank my parents, Jack and Martiny, for always believing in me, no matter how many rules I broke. In a few years, I’ll have my own teenagers, and it’ll be your turn to laugh!

To Mark Spencer: thanks for all of the things that everybody else thanks you for, but also, personally, thanks for giving generously of your time to the Asterisk community. The Toronto Asterisk Users’ Group (http://www.taug.ca) made a quantum leap forward as a result of your taking the time to speak to us, and that event will forever form a part of our history. Oh yeah, and thanks for the beers, too. :-)

Finally, thanks to the Asterisk Community. This book is our gift to you. We hope you enjoy reading it as much as we’ve enjoyed writing it.

Leif Madsen

The road to this book is a long one—nearly three years in the making. Back when I started using Asterisk, possibly much like you, I didn’t know anything about Asterisk, very little about traditional telephony, and even less about Voice over IP. I delved right into this new and very exciting world and took in all I could. For two months during a co-op term, for which I couldn’t immediately find work, I absorbed as much as I could, asking questions, trying things and seeing what the system could do. Unfortunately very little to no documentation existed for Asterisk, aside from some dialplan examples I was able to find by John Todd, and having questions answered by Brian K. West on IRC. Of course, this method wasn’t going to scale.

Not being much of a coder, I wanted to contribute something back to the community, and what do coders hate doing more than anything? Documentation! So I started The Asterisk Documentation Assignment (TADA), a basic outline with some information for the beginnings of a book.

Shortly after releasing it on my web site, an intelligent fellow by the name of Jared Smith introduced himself. He had similar aspirations for creating a “dead-tree” format book for the community, and we humbly started the Asterisk Documentation Project. Jared set up a simple web site at http://www.asteriskdocs.org, a CVS server, and the very first DocBook-formatted version of a book for Asterisk. From there we started filling in information, and soon had information submitted by a number of members of the community.

In June of 2004, an animated chap by the name of Jim Van Meggelen started showing up on the mailing lists, and contributing lots of information and documentation—this was definitely a guy we wanted on our team! Jim had the vision and the drive to really get Jared’s and my butts in gear and to work on something grander. Jim brought us years of experience and a writing flair that we could have hardly imagined.

With the core documentation team established, we embarked on a plan for the creation of volumes of Asterisk knowledge, eventually to lead to a complete library and a wealth of information. This book is essentially the beginning of that dream.

Firstly and mostly, I have to thank my parents, Rick and Carol, for always supporting my efforts, allowing me to realize my dreams, and always putting my needs ahead of theirs. Without their vision, understanding, and insight into the future, it would have been impossible to have accomplished what I have. I love you both very much!

I’d like to thank Felix Carapaica and Bill Farkas of the Sheridan Institute of Technology for their dedication to the advancement of knowledge. Their teaching has complemented my prior learning, and has allowed me to expand my understanding of routing and telecommunications exponentially.

There are far too many people to thank individually, but of particular importance, the following people were, and are, the most influential to my understanding of Asterisk: Joshua Colp, Tilghman Lesher, Russell Bryant, Steve Murphy, Olle Johansson, Steven Sokol, Brian K. West, John Todd, and William Suffill, for my very first VoIP phone (which I use to this day!). And for those who I said I’d mention in the book…thanks!

And of course, I must thank Jared Smith and Jim Van Meggelen for having the vision and understanding of how important documentation really is—all of this would have been impossible without you.

Jared Smith

I first started working with Asterisk in the spring of 2002. I had recently started a new job with a market research company, and ended up taking a long road trip to a remote call center with the CIO. On the long drive home we talked about innovation in telephony, and he mentioned a little open source telephony project he had heard of called Asterisk. Over the next few months, I was able to talk the company into buying a developer’s kit from Digium and started playing with Asterisk on company time.

During the next few months, I became more and more involved with the Asterisk community. I read the mailing lists. I scoured the archives. I hung out in the IRC channel, just hoping to find nuggets of Asterisk knowledge. As time went on, I was finally able to figure out enough to get Asterisk up and running.

That’s when the real fun began.

With the help of the CIO and the approval of the CEO, we moved forward with plans to move our entire telecom infrastructure to Asterisk, including our corporate office and all of our remote call centers. Along the way, we ran into a lot of uncharted territory, and I began thinking about creating a good repository of Asterisk knowledge. Over the course of the project, we were able to do some really innovative things, such as invent IAX trunking!

When all was said and done, we ended up with around forty Asterisk servers spread across many different geographical locations, all communicating with each other to provide a cohesive enterprise-class VoIP phone system. This system currently handles approximately 1 million minutes of calls per month, serves several hundred employees, connects to 27 voice T1s, and saves the company around $20,000 (USD) per month on their telecom costs. In short, our Asterisk project was a resounding success!

While in the middle of implementing this project, I met Leif in one of the Asterisk IRC channels. We talked about ways we could help out new Asterisk users and lower the barrier to entry, and we decided to push ahead with plans to more fully document Asterisk. I really wanted some good documentation in “dead-tree” format —basically a book that a new user could pick up and learn the basics of Asterisk. About that same time, the number of new users on the Asterisk mailing lists and in the IRC channels grew tremendously, and we felt that writing an Asterisk book would greatly improve the signal-to-noise ratio. The Asterisk Documentation Project was born! The rest, they say, is history.

Since then, we’ve been writing Asterisk documentation. I never thought it would be this arduous, yet rewarding. (I joked with Leif and Jim that it might be easier and less controversial to write an in-depth tome called Religion, Gun Control, and Sushi than cover everything that Asterisk has to offer in sufficient detail!) What you see here is a direct result of a lot of late nights and long weekends spent helping the Asterisk community—after all, it’s the least we could do, considering what Asterisk has given to us. We hope it will inspire other members of the Asterisk community to help document changes and new features for the benefit of all involved.

Now to thank some people:

First of all, I’d like to thank my beautiful wife. She’s put up with a lot of lonely nights while I’ve been slaving away at the keyboard, and I’d like her to know how much I appreciate her and her endless support. I’d also like to thank my kids for doing their best to remind me of the important things in life. I love you!

To my parents: thanks for everything you’ve done to help me stretch and grow and learn over the years. You’re the best parents a person could ask for.

To Dave Carr and Michael Lundberg: thanks for letting me learn Asterisk on company time. Working with both of you was truly a pleasure. May God smile upon you and grant you success and joy in all you do.

To Leif and Jim: thanks for putting up with my stupid jokes, my insistence that we do things “the right way,” and my crazy schedule. Thanks for pushing me along, and making me a better writer. I’ve really enjoyed working with you two, and hope to collaborate with you on future projects!

To Mark Spencer: thank you for your continued support and dedication and friendship. You’ve been an invaluable resource to our effort, and I truly believe that you’ve started a revolution in the world of telephony. You’re always welcome in my home and at my dinner table!

To the other great people at Digium: thank you for your help and support. We’re especially thankful for your willingness to give us more insight into the Asterisk code, and for donating hardware so that we can better document the Asterisk Developer’s Kit.

To Steven Sokol, Steven Critchfield, Olle E. Johansson, and all the others who have contributed to the Asterisk Documentation Project and to this book: thank you! We couldn’t have done it without your help and suggestions.



[1] In December of 2006, Rich passed away, as his two-year battle with cancer came to an unfortunate end. Rich was posting on the Asterisk Users mailing list as late as November of that year. He was giving to the community right up until the end, which is why we dedicated this book to him.

[2] To get a sense of how big the Asterisk phenomenon is, type “PBX” into Google. As you look at the results, bear in mind that the traditional PBX industry represents billions of dollars. The big players are companies such as Avaya, Nortel, Siemens, Mitel, Cisco, NEC, and many, many more. It is somewhat telling that they don’t seem to be concerned about how they rank in a Google search. As a cultural barometer, we’re pretty sure this matters.

Chapter 1. A Telephony Revolution

It does not require a majority to prevail, but rather an irate, tireless minority keen to set brush fires in people’s minds.

--Samuel Adams

An incredible revolution is under way. It has been a long time in coming, but now that it has started, there will be no stopping it. It is taking place in an area of technology that has lapsed embarrassingly far behind every other industry that calls itself high-tech. The industry is telecommunications, and the revolution is being fueled by an open source Private Branch eXchange (PBX) called Asterisk™.

Telecommunications is arguably the last major electronics industry that has remained untouched by the open source revolution.[3] Major telecommunications manufacturers still build ridiculously expensive, incompatible systems, running complicated, ancient code on impressively engineered yet obsolete hardware.

As an example, Nortel’s Business Communications Manager kludges together a 15 year-old Key Telephone Switch and a 1.2 GHz Celeron PC.[4] All this can be yours for between $5,000 and $15,000, not including telephones. If you want it to actually do anything interesting, you’ll have to pay extra licensing fees for closed, limited-functionality, shrink-wrapped applications. Customization? Forget it—it’s not in the plan. Future technology and standards compliance? Give them a year or two—they’re working on it.

All of the major telecommunications manufacturers offer similar-minded products. They don’t want you to have flexibility or choice; they want you to be locked in to their product cycles.

Asterisk changes all of that. With Asterisk, no one is telling you how your phone system should work, or what technology you are limited to. If you want it, you can have it. Asterisk lovingly embraces the concept of standards compliance, while also enjoying the freedom to develop its own innovations. What you choose to implement is up to you—Asterisk imposes no limits.

Naturally, this incredible flexibility comes with a price: Asterisk is not a simple system to configure. This is not because it’s illogical, confusing, or cryptic; to the contrary, it is very sensible and practical. People’s eyes light up when they first see an Asterisk dialplan and begin to contemplate the possibilities. But when there are literally thousands of ways to achieve a result, the process naturally requires extra effort. Perhaps it can be compared to building a house: the components are relatively easy to understand, but a person contemplating such a task must either a) enlist competent help or b) develop the required skills through instruction, practice, and a good book on the subject.

VoIP: Bridging the Gap Between Traditional and Network Telephony

While Voice over IP (VoIP) is often thought of as little more than a method of obtaining free long-distance calling, the real value (and—let’s be honest—challenge as well) of VoIP is that it allows voice to become nothing more than another application in the data network.

It sometimes seems that we’ve forgotten that the purpose of the telephone is to allow people to communicate. It is a simple goal, really, and it should be possible for us to make it happen in far more flexible and creative ways than are currently available to us. Since the industry has demonstrated an unwillingness to pursue this goal, a large community of passionate people have taken on the task.

The challenge comes from the fact that an industry that has changed very little in the last century shows little interest in starting now.

The Zapata Telephony Project

The Zapata Telephony Project was conceived of by Jim Dixon, a telecommunications consulting engineer who was inspired by the incredible advances in CPU speeds that the computer industry has now come to take for granted. Dixon’s belief was that far more economical telephony systems could be created if a card existed that had nothing more on it than the basic electronic components required to interface with a telephone circuit. Rather than having expensive components on the card, Digital Signal Processing (DSP)[5] would be handled in the CPU by software. While this would impose a tremendous load on the CPU, Dixon was certain that the low cost of CPUs relative to their performance made them far more attractive than expensive DSPs, and, more importantly, that this price/performance ratio would continue to improve as CPUs continued to increase in power.

Like so many visionaries, Dixon believed that many others would see this opportunity, and that he merely had to wait for someone else to create what to him was an obvious improvement. After a few years, he noticed that not only had no one created these cards, but it seemed unlikely that anyone was ever going to. At that point it was clear that if he wanted a revolution, he was going to have to start it himself. And so the Zapata Telephony Project was born:

Since this concept was so revolutionary, and was certain to make a lot of waves in the industry, I decided on the Mexican revolutionary motif, and named the technology and organization after the famous Mexican revolutionary Emiliano Zapata. I decided to call the card the “tormenta” which, in Spanish, means “storm,” but contextually is usually used to imply a big storm, like a hurricane or such.[6]

Perhaps we should be calling ourselves Asteristas. Regardless, we owe Jim Dixon a debt of thanks, partly for thinking this up and partly for seeing it through, but mostly for giving the results of his efforts to the open source community. As a result of Jim’s contribution, Asterisk’s Public Switched Telephone Network (PSTN) engine came to be.

Massive Change Requires Flexible Technology

The most successful key telephone system in the world has a design limitation that has survived 15 years of users begging for what appears to be a simple change: when you determine the number of times your phone will ring before it forwards to voicemail, you can choose from 2, 3, 4, 6, or 10 ring cycles. Have you any idea how many times people ask for five rings? Plead as the customers might, the manufacturers of this system cannot get their head around the idea that this is a problem. That’s the way it works, they say, and users need to get over it.

Another example from the same system is that the name you program on your set can only be seven characters in length.[7] Back in the late 1980s, when this particular system was designed, RAM was very expensive, and storing those seven characters for dozens of sets represented a huge hardware expense. So what’s the excuse today? None. Are there any plans to change it? Hardly—the issue is not even officially acknowledged as a problem.

Those are just two examples; the industry is rife with them.

Now, it’s all very well and good to pick on one system, but the reality is that every PBX in existence suffers shortcomings. No matter how fully featured it is, something will always be left out, because even the most feature-rich PBX will always fail to anticipate the creativity of the customer. A small group of users will desire an odd little feature that the design team either did not think of or could not justify the cost of building, and, since the system is closed, the users will not be able to build it themselves.

If the Internet had been thusly hampered by regulation and commercial interests, it is doubtful that it would have developed the wide acceptance it currently enjoys. The openness of the Internet meant that anyone could afford to get involved. So, everyone did. The tens of thousands of minds that collaborated on the creation of the Internet delivered something that no corporation ever could have.

As with many other open source projects, such as Linux and the Internet, the development of Asterisk was fueled by the dreams of folks who knew that there had to be something more than what the industry was producing. The strength of the community is that it is composed not of employees assigned to specific tasks, but rather of folks from all sorts of industries, with all sorts of experiences, and all sorts of ideas about what flexibility means, and what openness means. These people knew that if one could take the best parts of various PBXes and separate them into interconnecting components—akin to a boxful of LEGO bricks—one could begin to conceive of things that would not survive a traditional corporate risk-analysis process. While no one can seriously claim to have a complete picture of what this thing should look like, there is no shortage of opinions and ideas.[8]

Many people new to Asterisk see it as unfinished. Perhaps these people can be likened to visitors to an art studio, looking to obtain a signed, numbered print. They often leave disappointed, because they discover that Asterisk is the blank canvas, the tubes of paint, the unused brushes waiting.[9]

Even at this early stage in its success, Asterisk is nurtured by a greater number of artists than any other PBX. Most manufacturers dedicate no more than a few developers to any one product; Asterisk has scores. Most proprietary PBXes have a worldwide support team comprised of a few dozen real experts; Asterisk has hundreds.

The depth and breadth of the expertise that surrounds this product is unmatched in the telecom industry. Asterisk enjoys the loving attention of old Telco guys who remember when rotary dial mattered, enterprise telecom people who recall when voicemail was the hottest new technology, and data communications geeks and coders who helped build the Internet. These people all share a common belief—that the telecommunications industry needs a proper revolution.[10]

Asterisk is the catalyst.

Asterisk: The Hacker’s PBX

Telecommunications companies who choose to ignore Asterisk do so at their peril. The flexibility it delivers creates possibilities that the best proprietary systems can scarcely dream of. This is because Asterisk is the ultimate hacker’s PBX.

If someone asks you not to use the term hacker, refuse. This term does not belong to the mass media. They stole it and corrupted it to mean “malicious cracker.” It’s time we took it back. Hackers built the networking engine that is the Internet. Hackers built the Apple Macintosh and the Unix operating system. Hackers are also building your next telecom system. Do not fear; these are the good guys, and they’ll be able to build a system that’s far more secure than anything that exists today. Rather than being constricted by the dubious and easily cracked security of closed systems, the hackers will be able to quickly respond to changing trends in security and fine-tune the telephone system in response to both corporate policy and industry best practices.

Like other open source systems, Asterisk will be able to evolve into a far more secure platform than any proprietary system, not in spite of its hacker roots, but rather because of them.

Asterisk: The Professional’s PBX

Never in the history of telecommunications has a system so suited to the needs of business been available, at any price. Asterisk is an enabling technology and, as with Linux, it will become increasingly rare to find an enterprise that is not running some version of Asterisk, in some capacity, somewhere in the network, solving a problem as only Asterisk can.

This acceptance is likely to happen much faster than it did with Linux, though, for several reasons:

  • Linux has already blazed the trail that led to open source acceptance. Asterisk is following that lead.

  • The telecom industry is crippled, with no leadership being provided by the giant industry players. Asterisk has a compelling, realistic, and exciting vision.

  • End users are fed up with incompatible, limited functionality, and horrible support. Asterisk solves the first two problems; entepreneurs and the community are addressing the latter.

The Asterisk Community

One of the compelling strengths of Asterisk is the passionate community that developed and supports it. This community, led by Mark Spencer of Digium, is keenly aware of the cultural significance of Asterisk, and is giddy about the future.

One of the more powerful side effects caused by the energy of the Asterisk community is the cooperation it has spawned among the telecommunications professionals, networking professionals, and information technology professionals who share a love for this phenomenon. While these professions have traditionally been at odds with each other, in the Asterisk community they delight in each others’ skills. The significance of this cooperation cannot be underestimated.

Still, if the dream of Asterisk is to be realized, the community must grow—yet one of the key challenges that the community currently faces is a rapid influx of new users. The members of the existing community, having birthed this thing called Asterisk, are generally welcoming of new users, but they’ve grown impatient with being asked the kinds of questions whose answers can often be obtained independently, if one is willing to put forth the time needed to research and experiment.

Obviously, new users do not fit any particular kind of mold. While some will happily spend hours experimenting and reading various blogs describing the trials and tribulations of others, many people who have become enthusiastic about this technology are completely uninterested in such pursuits. They want a simple, straightforward, step-by-step guide that’ll get them up and running, followed by some sensible examples describing the best methods of implementing common functionality (such as voicemail, auto attendants, and the like).

To the members of the expert community, who (correctly) perceive that Asterisk is like a web development language, this approach doesn’t make any sense. To them, it’s clear that you have to immerse yourself in Asterisk to appreciate its subtleties. Would one ask for a step-by-step guide to programming and expect to learn from it all that a language has to offer?

Clearly, there’s no one approach that’s right for everyone. Asterisk is a different animal altogether, and it requires a totally different mind-set. As you explore the community, though, be aware that there are people with many different skill sets and attitudes here. Some of these folks do not display much patience with new users, but that’s often due to their passion for the subject, not because they don’t welcome your participation.

The Asterisk Mailing Lists

As with any community, there are places where members of the Asterisk community meet to discuss matters of mutual interest. Of the mailing lists you will find at http://lists.digium.com, these four are currently the most important:

Asterisk-Biz

Anything commercial with respect to Asterisk belongs in this list. If you’re selling something Asterisk-related, sell it here. If you want to buy an Asterisk service or product, post here.

Asterisk-Dev

The Asterisk developers hang out here. The purpose of this list is the discussion of the development of the software that is Asterisk, and its participants vigorously defend that purpose. Expect a lot of heat if you post anything to this list not relating to programming or development of the Asterisk code base specifically. General coding questions (such as interfacing with AGI or AMI), should be directed to the Asterisk-Users list.

Warning

The Asterisk-Dev list is not second-level support! If you scroll through the mailing list archives, you’ll see this is a strict rule. The Asterisk-Dev mailing list is about discussion of core Asterisk development, and questions about interfacing your external programs via AGI or AMI should be posted on the Asterisk-Users list.

Asterisk-Users

This is where most Asterisk users hang out. This list generates several hundred messages per day and has over ten thousand subscribers. While you can go here for help, you are expected to have done some reading on your own before you post a query.

Asterisk-BSD

This is where users who are implementing Asterisk on FreeBSD (and other BSD dialects) hang out.

The Asterisk Wiki

The Asterisk Wiki (which exists in large part due to the tireless efforts of James Thompson—thanks James!) is a source of much enlightenment and confusion. A community-maintained repository of VoIP knowledge (http://www.voip-info.org) contains a truly inspiring cornucopia of fascinating, informative, and frequently contradictory information about many subjects, just one of which is Asterisk.

Since Asterisk documentation forms by far the bulk of the information on this web site,[11] and it probably contains more Asterisk knowledge than all other sources put together (with the exception of the mailing-list archives), it is commonly referred to as the place to go for Asterisk knowledge.

The IRC Channels

The Asterisk community maintains Internet Relay Chat (IRC) channels on irc.freenode.net. The two most active channels are #asterisk and #asterisk-dev.[12] To cut down on spam-bot intrusions, both of these channels now require registration to join.[13]

Asterisk User Groups

In many cites around the world, lonely Asterisk users began to realize that there were other like-minded people in their towns. Asterisk User Groups (AUGs) began to spring up all over the place. While these groups don’t have any official affiliation with each other, they generally link to each others’ web sites and welcome members from anywhere. Type “Asterisk User Group” into Google to track down one in your area.

The Asterisk Documentation Project

The Asterisk Documentation Project was started by Leif Madsen and Jared Smith, but several people in the community have contributed.

The goal of the documentation project is to provide a structured repository of written work on Asterisk. In contrast with the flexible and ad hoc nature of the Wiki, the Docs project is passionate about building a more focused approach to various Asterisk-related subjects.

As part of the efforts of the Asterisk Docs project to make documentation available online, this book is available at the http://www.asteriskdocs.org web site, under a Creative Commons license.

The Business Case

It is very rare to find businesses these days that do not have to reinvent themselves every few years. It is equally rare to find a business that can afford to replace its communications infrastructure each time it goes in a new direction. Today’s businesses need extreme flexibility in all of their technology, including telecom.

In his book Crossing the Chasm (HarperBusiness), Geoffrey Moore opines, “The idea that the value of the system will be discovered rather than known at the time of installation implies, in turn, that product flexibility and adaptability, as well as ongoing account service, should be critical components of any buyer’s evaluation checklist.” What this means, in part, is that the true value of a technology is often not known until it has been deployed.

How compelling, then, to have a system that holds at its very heart the concept of openness and the value of continuous innovation.

This Book

So where to begin? Well, when it comes to Asterisk, there is far more to talk about than we can fit into one book. For now, we’re not going to take you down all the roads that the über-geeks follow—we’re just going to give you the basics.

In Chapter 2, Preparing a System for Asterisk, we cover some of the engineering considerations you should keep in mind when designing a telecommunications system. You can skip much of this material if you want to get right to installing, but these are important concepts to understand, should you ever plan on putting an Asterisk system into production.

Chapter 3, Installing Asterisk covers obtaining, compiling, and installing Asterisk, and Chapter 4, Initial Configuration of Asterisk deals with the initial configuration of Asterisk. Here we cover the important configuration files that must exist to define the channels and features available to your system. This will prepare you for Chapter 5, Dialplan Basics, where we introduce the heart of Asterisk—the dialplan. Chapter 6, More Dialplan Concepts will introduce some more advanced dialplan concepts.

We will take a break from Asterisk in Chapter 7, Understanding Telephony and discuss some of the more important technologies in use in the PSTN. Naturally, following the discussion of legacy telephony, Chapter 8, Protocols for VoIP discusses Voice over IP.

Chapter 9, The Asterisk Gateway Interface (AGI) introduces one of the more amazing components, the Asterisk Gateway Interface (AGI). Using Perl, PHP, and Python, we demonstrate how external programs can be used to add nearly limitless functionality to your PBX. In Chapter 14, Potpourri, we briefly cover what is, in fact, a rich and varied cornucopia of incredible features and functions, all of which are part of the Asterisk phenomenon. To conclude, Chapter 15, Asterisk: The Future of Telephony looks forward, predicting a future where open source telephony completely transforms an industry desperately in need of a revolution. You’ll also find a wealth of reference information in the book’s five appendixes.

This book can only lay down the basics, but from this foundation you will be able to come to an understanding of the concept of Asterisk—and from that, who knows what you will build?



[3] Until now.

[4] To its credit, Nortel finally got rid of Windows NT 4.0 and installed Linux. Technically a good idea, but rather odd, given that Nortel and Microsoft recently announced a partnership to develop enterprise telecom applications together.

[5] The term DSP also means Digital Signal Processor, which is a device (usually a chip) that is capable of interpreting and modifying signals of various sorts. In a voice network, DSPs are primarily responsible for encoding, decoding, and transcoding audio information. This can require a lot of computational effort.

[6] Jim Dixon, “The History of Zapata Telephony and How It Relates to the Asterisk PBX” (http://www.asteriskdocs.org/modules/tinycontent/index.php?id=10).

[7] If your name is Elizabeth, for example, you will have to figure something else out like elizbth, or elizabe, or perhaps lizabth. OK, so liz might serve as well, but you get the point.

[8] From the release of Asterisk 1.2 to Asterisk 1.4, there have been over 4,000 updates to the code in the SVN repository.

[9] It should be noted that these folks need not leave disappointed. Several projects have arisen to lower the barriers to entry for Asterisk. By far the most popular and well known is trixbox (http://www.trixbox.org). If you have an old PC lying around (or a copy of VMware), trixbox will build a GUI-based PBX for you simply by answering a few questions during the automated install process. This does not make it easier to learn Asterisk, because you are no longer involved in the platform or dialplan configuration, but it will deliver a working PBX to you much faster than the more hands-on approach we employ in this book.

[10] The telecom industry has been predicting a revolution since before the crash; time will tell how well they respond to the open source revolution.

[11] More than 30 percent, at last count.

[12] The #asterisk-dev channel is for the discussion of changes to the underlying code base of Asterisk and is also not second-tier support. Discussions related to programming external applications that interface with Asterisk via AGI or AMI are meant to be in #asterisk.

[13] /msg nickserv help when you connect to the service via your favorite IRC client.

Chapter 2. Preparing a System for Asterisk

Very early on, I knew that someday in some “perfect” future out there over the horizon, it would be commonplace for computers to handle all of the necessary processing functionality internally, making the necessary external hardware to connect up to telecom interfaces very inexpensive and, in some cases, trivial.

--Jim Dixon, “The History of Zapata Telephony and How It Relates to the Asterisk PBX”

By this point, you must be anxious to get your Asterisk system up and running. If you are building a hobby system, you can probably jump right to the next chapter and begin the installation. For a mission-critical deployment, however, some thought must be given to the environment in which the Asterisk system will run. Make no mistake: Asterisk, being a very flexible piece of software, will happily and successfully install on nearly any Linux platform you can conceive of, and several non-Linux platforms as well.[14] However, to arm you with an understanding of the type of operating environment Asterisk will really thrive in, this chapter will discuss issues you need to be aware of in order to deliver a reliable, well-designed system.

In terms of its resource requirements, Asterisk’s needs are similar to those of an embedded, real-time application. This is due in large part to its need to have priority access to the processor and system buses. It is, therefore, imperative that any functions on the system not directly related to the call-processing tasks of Asterisk be run at a low priority, if at all. On smaller systems and hobby systems, this might not be as much of an issue. However, on high-capacity systems, performance shortcomings will manifest as audio quality problems for users, often experienced as echo, static, and the like. The symptoms will resemble those experienced on a cell phone when going out of range, although the underlying causes will be different. As loads increase, the system will have increasing difficulty maintaining connections. For a PBX, such a situation is nothing short of disastrous, so careful attention to performance requirements is a critical consideration during the platform selection process.

Table 2.1, “System requirement guidelines” lists some very basic guidelines that you’ll want to keep in mind when planning your system. The next section takes a close look at the various design and implementation issues that will affect its performance.

Note

The size of an Asterisk system is actually not dictated by the number of users or sets, but rather by the number of simultaneous calls it will be expected to support. These numbers are very conservative, so feel free to experiment and see what works for you.

Table 2.1. System requirement guidelines

Purpose

Number of channels

Minimum recommended

Hobby system

No more than 5

400 MHz x86, 256 MB RAM

SOHO system (small office/home office—less than three lines and five sets)

5 to 10

1 GHz x86, 512 MB RAM

Small business system

Up to 25

3 GHz x86, 1 GB RAM

Medium to large system

More than 25

Dual CPUs, possibly also multiple servers in a distributed architecture

With large Asterisk installations, it is common to deploy functionality across several servers. One or more central units will be dedicated to call processing; these will be complemented by one or more ancillary servers handling peripherals (such as a database system, a voicemail system, a conferencing system, a management system, a web interface, a firewall, and so on). As is true in most Linux environments, Asterisk is well suited to growing with your needs: a small system that used to be able to handle all your call-processing and peripheral tasks can be distributed among several servers when increased demands exceed its abilities. Flexibility is a key reason why Asterisk is extremely cost-effective for rapidly growing businesses; there is no effective maximum or minimum size to consider when budgeting the initial purchase. While some scalability is possible with most telephone systems, we have yet to hear of one that can scale as flexibly as Asterisk. Having said that, distributed Asterisk systems are not simple to design—this is not a task for someone new to Asterisk.

Note

If you are sure that you need to set up a distributed Asterisk system, you will want to study the DUNDi protocol, Asterisk Realtime Architecture (ARA), func_odbc, and the various other database tools at your disposal. This will help you to abstract the data your system requires from the dialplan logic your Asterisk systems will utilize, allowing a generic set of dialplan logic that can be used across multiple boxes, thereby allowing you to scale more simply by adding additional boxes to the system. However, this is far beyond the scope of this book and will be left as an exercise for the reader. If you want a teaser of some tools you can use for scaling, see Chapter 12, Relational Database Integration.

Server Hardware Selection

The selection of a server is both simple and complicated: simple because, really, any x86-based platform will suffice, but complicated because the reliable performance of your system will depend on the care that is put into the platform design. When selecting your hardware, you must carefully consider the overall design of your system and what functionality you need to support. This will help you determine your requirements for the CPU, motherboard, and power supply. If you are simply setting up your first Asterisk system for the purpose of learning, you can safely ignore the information in this section. If, however, you are building a mission-critical system suitable for deployment, these are issues that require some thought.

Performance Issues

Among other considerations, when selecting the hardware for an Asterisk installation you must bear in mind this critical question: how powerful must the system be? This is not an easy question to answer, because the manner in which the system is to be used will play a big role in the resources it will consume. There is no such thing as an Asterisk performance-engineering matrix, so you will need to understand how Asterisk uses the system in order to make intelligent decisions about what kinds of resources will be required. You will need to consider several factors, including:

The maximum number of concurrent connections the system will be expected to support

Each connection will increase the workload on the system.

The percentage of traffic that will require processor-intensive DSP of compressed codecs (such as G.729 and GSM)

The Digital Signal Processing (DSP) work that Asterisk performs in software can have a staggering impact on the number of concurrent calls it will support. A system that might happily handle 50 concurrent G.711 calls could be brought to its knees by a request to conference together 10 G.729 compressed channels. We’ll talk more about G.729, GSM, G.711, and many other codecs in Chapter 8, Protocols for VoIP.

Whether conferencing will be provided, and what level of conferencing activity is expected

Will the system be used heavily? Conferencing requires the system to transcode and mix each individual incoming audio stream into multiple outgoing streams. Mixing multiple audio streams in near-real-time can place a significant load on the CPU.

Echo cancellation

Echo cancellation may be required on any call where a Public Switched Telephone Network (PSTN) interface is involved. Since echo cancellation is a mathematical function, the more of it the system has to perform, the higher the load on the CPU will be. [15] Do not fear. Echo cancellation is another topic for Chapter 8, Protocols for VoIP.

Dialplan scripting logic

Whenever Asterisk has to pass call control to an external program, there is a performance penalty. As much logic as possible should be built into the dialplan. If external scripts are used, they should be designed with performance and efficiency as critical considerations.

As for the exact performance impact of these factors, it’s difficult to know for sure. The effect of each is known in general terms, but an accurate performance calculator has not yet been successfully defined. This is partly because the effect of each component of the system is dependent on numerous variables, such as CPU power, motherboard chipset and overall quality, total traffic load on the system, Linux kernel optimizations, network traffic, number and type of PSTN interfaces, and PSTN traffic—not to mention any non-Asterisk services the system is performing concurrently. Let’s take a look at the effects of several key factors:

Codecs and transcoding

Simply put, a codec (short for coder/decoder, or compression/decompression) is a set of mathematical rules that define how an analog waveform will be digitized. The differences between the various codecs are due in large part to the levels of compression and quality that they offer. Generally speaking, the more compression that’s required, the more work the DSP must do to code or decode the signal. Uncompressed codecs, therefore, put far less strain on the CPU (but require more network bandwidth). Codec selection must strike a balance between bandwidth and processor usage.

Central processing unit (and Floating Point Unit)

A CPU is comprised of several components, one of which is the floating point unit (FPU). The speed of the CPU, coupled with the efficiency of its FPU, will play a significant role in the number of concurrent connections a system can effectively support. The next section (the section called “Choosing a Processor”) offers some general guidelines for choosing a CPU that will meet the needs of your system.

Other processes running concurrently on the system

Being Unix-like, Linux is designed to be able to multitask several different processes. A problem arises when one of those processes (such as Asterisk) demands a very high level of responsiveness from the system. By default, Linux will distribute resources fairly among every application that requests them. If you install a system with many different server applications, those applications will each be allowed their fair use of the CPU. Since Asterisk requires frequent high-priority access to the CPU, it does not get along well with other applications, and if Asterisk must coexist with other apps, the system may require special optimizations. This primarily involves the assignment of priorities to various applications in the system and, during installation, careful attention to which applications are installed as services.

Kernel optimizations

A kernel optimized for the performance of one specific application is something that very few Linux distributions offer by default and, thus, it requires some thought. At the very minimum—whichever distribution you choose—a fresh copy of the Linux kernel (available from http://www.kernel.org) should be downloaded and compiled on your platform. You may also be able to acquire patches that will yield performance improvements, but these are considered hacks to the officially supported kernel.

IRQ latency

Interrupt request (IRQ) latency is basically the delay between the moment a peripheral card (such as a telephone interface card) requests the CPU to stop what it’s doing and the moment when the CPU actually responds and is ready to handle the task. Asterisk’s peripherals (especially the Zaptel cards) are extremely intolerant of IRQ latency. This is not due to any problem with the cards so much as part of the nature of how a software-based TDM engine has to work. If we buffer the TDM data and send it on the bus as a larger packet, that may be more efficient from a system perspective, but it will create a delay between the time the audio is received on the card, and when it is delivered to the CPU. This makes real-time processing of TDM data next to impossible. In the design of Zaptel, it was decided that sending the data every 1 ms would create the best trade-off, but a side effect of this is that any card in the system that uses the Zaptel interface is going to ask the system to process an interrupt every millisecond. This used to be a factor on older motherboards, but it has largely ceased to be a cause for concern.

Tip

Linux has historically had problems with its ability to service IRQs quickly; this problem has caused enough trouble for audio developers that several patches have been created to address this shortcoming. So far, there has been some mild controversy over how to incorporate these patches into the Linux kernel.

Kernel version

Asterisk is officially supported on Linux Version 2.6.

Linux distribution

Linux distributions are many and varied. In the next chapter, we will discuss the challenge of selecting a Linux distribution, and how to obtain and install both Linux and Asterisk.

Choosing a Processor

Since the performance demands of Asterisk will generally involve a large number of math calculations, it is essential that you select a processor with a powerful FPU. The signal processing that Asterisk performs can quickly demand a staggering quantity of complex mathematical computations from the CPU. The efficiency with which these tasks are carried out will be determined by the power of the FPU within the processor.

To actually name a best processor for Asterisk in this book would fly in the face of Moore’s law. Even in the time between the authoring and publishing of this book, processor speeds will undergo rapid improvements, as will Asterisk’s support for various architectures. Obviously, this is a good thing, but it also makes the giving of advice on the topic a thankless task. Naturally, the more powerful the FPU is, the more concurrent DSP tasks Asterisk will be able to handle, so that is the ultimate consideration. When you are selecting a processor, the raw clock speed is only part of the equation. How well it handles floating-point operations will be a key differentiator, as DSP operations in Asterisk will place a large demand on that process.

Both Intel and AMD CPUs have powerful FPUs. Current-generation chips from either of those manufacturers can be expected to perform well.[16]

The obvious conclusion is that you should get the most powerful CPU your budget will allow. However, don’t be too quick to buy the most expensive CPU out there. You’ll need to keep the requirements of your system in mind; after all, a Formula 1 Ferrari is ill-suited to the rigors of rush-hour traffic. Slower CPUs will often run cooler and, thus, you might be able to build a lower-powered, fanless Asterisk system for a small office, which could work well in a dusty environment, perhaps.

In order to attempt to provide a frame of reference from which we can contemplate our platform decision, we have chosen to define three sizes of Asterisk systems: small, medium, and large.

Small systems

Small systems (up to 10 phones) are not immune to the performance requirements of Asterisk, but the typical load that will be placed on a smaller system will generally fall within the capabilities of a modern processor.

If you are building a small system from older components you have lying around, be aware that the resulting system cannot be expected to perform at the same level as a more powerful machine, and will run into performance degradation under a much lighter load. Hobby systems can be run successfully on very low-powered hardware, although this is by no means recommended for anyone who is not a whiz at Linux performance tuning.[17]

If you are setting up an Asterisk system for the purposes of learning, you will be able to build a fully featured platform using a relatively low-powered CPU. The authors of this book run several Asterisk lab systems with 433 MHz to 700 MHz Celeron processors, but the workload of these systems is minimal (never more than two concurrent calls).

Medium systems

Medium-sized systems (from 10 to 50 phones) are where performance considerations will be the most challenging to resolve. Generally, these systems will be deployed on one or two servers only and, thus, each machine will be required to handle more than one specific task. As loads increase, the limits of the platform will become increasingly stressed. Users may begin to perceive quality problems without realizing that the system is not faulty in any way, but simply exceeding its capacity. These problems will get progressively worse as more and more load is placed on the system, with the user experience degrading accordingly. It is critical that performance problems be identified and addressed before they are noticed by users.

Monitoring performance on these systems and quickly acting on any developing trends is key to ensuring that a quality telephony platform is provided.

Large systems

Large systems (more than 120 channels) can be distributed across multiple systems and sites and, thus, performance concerns can be managed through the addition of machines. Very large Asterisk systems have been created in this way.

Building a large system requires an advanced level of knowledge in many different disciplines. We will not discuss it in detail in this book, other than to say that the issues you’ll encounter will be similar to those encountered during any deployment of multiple servers handling a single, distributed task.

Choosing a Motherboard

Just to get any anticipation out of the way, we also cannot recommend specific motherboards in this book. With new motherboards coming out on a weekly basis, any recommendations we could make would be rendered moot by obsolescence before the published copy hit the shelves. Not only that, but motherboards are like automobiles: while they are all very similar in principle, the difference is in the details. And as Asterisk is a performance application, the details matter.

What we will do, therefore, is give you some idea of the kinds of motherboards that can be expected to work well with Asterisk, and the features that will make for a good motherboard. The key is to have both stability and high performance. Here are some guidelines to follow:

  • The various system buses must provide the minimum possible latency. If you are planning a PSTN connection using analog or PRI interfaces (discussed later in this chapter), having Zaptel cards in the system will generate 1,000 interrupt requests per second. Having devices on the bus that interfere with this process will result in degradation of call quality. Chipsets from Intel (for Intel CPUs) and nVidia nForce (for AMD CPUs) seem to score the best marks in this area. Review the specific chipset of any motherboard you are evaluating to ensure that it does not have known problems with IRQ latency.

  • If you are running Zaptel cards in your system, you will want to ensure that your BIOS allows you maximum control over IRQ assignment. As a rule, high-end motherboards will offer far greater flexibility with respect to BIOS tweaking; value-priced boards will generally offer very little control. This may be a moot point, however, as APIC-enabled motherboards turn IRQ control over to the operating system.

  • Server-class motherboards generally implement a different PCI standard than workstation-class motherboards. While there are many differences, the most obvious and well known is that the two versions have different voltages. Depending on which cards you purchase, you will need to know if you require 3.3V or 5V PCI slots.[18] Figure 2.1, “Visual identification of PCI slots” shows the visual differences between 3.3V and 5V slots. Most server motherboards will have both types, but workstations will typically have only the 5V version.

    Tip

    There is some evidence that suggests connecting together two completely separate, single-CPU systems may provide far more benefits than simply using two processors in the same machine. You not only double your CPU power, but you also achieve a much better level of redundancy at a similar cost to a single-chassis, dual-CPU machine. Keep in mind, though, that a dual-server Asterisk solution will be more complex to design than a single-machine solution.

Figure 2.1. Visual identification of PCI slots

Visual identification of PCI slots
  • Consider using multiple processors, or processors with multiple cores. This will provide an improvement in the system’s ability to handle multiple tasks. For Asterisk, this will be of special benefit in the area of floating-point operations.

  • If you need a modem, install an external unit that connects to a serial port. If you must have an internal modem, you will need to ensure that it is not a so-called “Win-modem”—it must be a completely self-sufficient unit (note that these are very difficult, if not impossible, to find).

  • Consider that with built-in networking, if you have a network component failure, the entire motherboard will need to be replaced. On the other hand, if you install a peripheral Network Interface Card (NIC), there may be an increased chance of failure due to the extra mechanical connections involved. It can also be useful to have separate network cards serving sets and users (the internal network) and VoIP providers and external sites (the external network). NICs are cheap; we suggest always having at least two.

  • The stability and quality of your Asterisk system will be dependent on the components you select for its architecture. Asterisk is a beast, and it expects to be fed the best. As with just about anything, high cost is not always synonymous with quality, but you will want to become a connoisseur of computer components.

Having said all that, we need to get back to the original point: Asterisk can and will happily install on pretty much any system that will run Linux. The lab systems used to write this book, for example, included everything from a Linksys WRT to a dual-Xeon locomotive.[19] We have not experienced any performance or stability problems running less than five concurrent telephone connections. For the purposes of learning, do not be afraid to install Asterisk on whatever system you can scrounge up. When you are ready to put your system into production, however, you will need to understand the ramifications of the choices you make with respect to your hardware.

Power Supply Requirements

One often-overlooked component in a PC is the power supply (and the supply of power). For a telecommunications system,[20] these components can play a significant role in the quality of the user experience.

Computer power supplies

The power supply you select for your system will play a vital role in the stability of the entire platform. Asterisk is not a particularly power-hungry application, but anything relating to multimedia (whether it be telephony, professional audio, video, or the like) is generally sensitive to power quality.

This oft-neglected component can turn an otherwise top-quality system into a poor performer. By the same token, a top-notch power supply might enable an otherwise cheap PC to perform like a champ.

The power supplied to a system must provide not only the energy the system needs to perform its tasks but also stable, clean signal lines for all of the voltages your system expects from it.

Spend the money and get a top-notch power supply (gamers are pretty passionate about this sort of thing, so there are lots of choices out there).

Redundant power supplies

In a carrier-grade or high-availability environment, it is common to deploy servers that use a redundant power supply. Essentially, this involves two completely independent power supplies, either one of which is capable of meeting the power requirements of the system.

If this is important to you, keep in mind that best practices suggest that to be properly redundant, these power supplies should be connected to completely independent uninterruptible power supplies (UPSes) that are in turn fed by totally separate electrical circuits. In truly mission-critical environments (such as hospitals), even the main electrical feeds into the building are redundant, and diesel-powered generators are on-site to generate electricity during extended power failures (such as the one that hit Northeastern North America on August 15, 2003).

Environment

Your system’s environment consists of all of those factors that are not actually part of the server itself but nevertheless play a crucial role in the reliability and quality that can be expected from the system. Electrical supplies, room temperature and humidity, sources of interference, and security are all factors that should be contemplated.

Power Conditioning and Uninterruptible Power Supplies

When selecting the power sources for your system, consideration should be given not only to the amount of power the system will use, but also to the manner in which this power is delivered.

Power is not as simple as voltage coming from the outlet in the wall, and you should never just plug a production system into whatever electrical source is near at hand.[21]Giving some consideration to the supply of power to your system can provide a far more stable power environment, leading to a far more stable system.

One of the benefits of clean power is a reduction in heat, which means less stress on components, leading to a longer life expectancy.

Properly grounded, conditioned power feeding a premium-quality power supply will ensure a clean logic ground (a.k.a. 0 volt) reference[22] for the system and keep electrical noise on the motherboard to a minimum. These are industry-standard best practices for this type of equipment, which should not be neglected. A relatively simple way to achieve this is through the use of a power-conditioned UPS.[23]

Power-conditioned UPSes

The UPS is well known for its role as a battery backup, but the power-conditioning benefits that high-end UPS units also provide are less well understood.

Power conditioning can provide a valuable level of protection from the electrical environment by regenerating clean power through an isolation transformer. A quality power conditioner in your UPS will eliminate most electrical noise from the power feed and help to ensure a rock-steady supply of power to your system.

Unfortunately, not all UPS units are created equal; many of the less expensive units do not provide clean power. What’s worse, manufacturers of these devices will often promise all kinds of protection from surges, spikes, overvoltages, and transients. While such devices may protect your system from getting fried in an electrical storm, they will not clean up the power being fed to your system and, thus, will do nothing to contribute to stability.

Make sure your UPS is power conditioned. If it doesn’t say exactly that, it isn’t.

Grounding

Voltage is defined as the difference in electrical potential between two points. When considering a ground (which is basically nothing more than an electrical path to earth), the common assumption is that it represents 0 volts. But if we do not define that 0V in relation to something, we are in danger of assuming things that may not be so. If you measure the voltage between two grounding references, you’ll often find that there is a voltage potential between them. This voltage potential between grounding points can be significant enough to cause logic errors—or even damage—in a system where more than one path to ground is present.

Tip

One of the authors recalls once frying a sound card he was trying to connect to a friend’s stereo system. Even though both the computer and the stereo were in the same room, more than 6 volts of difference was measured between the ground conductors of the two electrical outlets they were plugged into! The wire between the stereo and the PC (by way of the sound card) provided a path that the voltage eagerly followed, thus frying a sound card that was not designed to handle that much current on its signal leads. Connecting both the PC and the stereo to the same outlet fixed the problem.

When considering electrical regulations, the purpose of a ground is primarily human safety. In a computer, the ground is used as a 0V logic reference. An electrical system that provides proper safety will not always provide a proper logic reference—in fact, the goals of safety and power quality are sometimes in disagreement. Naturally, when a choice must be made, safety has to take precedence.

Tip

Since the difference between a binary zero and a binary one is represented in computers by voltage differences of sometimes less than 3V, it is entirely possible for unstable power conditions caused by poor grounding or electrical noise to cause all kinds of intermittent system problems. Some power and grounding advocates estimate that more than 80 percent of unexplained computer glitches can be traced to power quality. Most of us blame Microsoft.

Modern switching power supplies are somewhat isolated from power quality issues, but any high-performance system will always benefit from a well-designed power environment. In mainframes, proprietary PBXes, and other expensive computing platforms, the grounding of the system is never left to chance. The electronics and frames of these systems are always provided with a dedicated ground that does not depend on the safety grounds supplied with the electrical feed.

Regardless of how much you are willing to invest in grounding, when you specify the electrical supply to any PBX, ensure that the electrical circuit is completely dedicated to your system (as discussed in the next section) and that an insulated, isolated grounding conductor is provided. This can be expensive to provision, but it will contribute greatly to a quality power environment for your system.[24]

It is also vital that each and every peripheral you connect to your system be connected to the same electrical receptacle (or, more specifically, the same ground reference). This will cut down on the occurrence of ground loops, which can cause anything from buzzing and humming noises to damaged or destroyed equipment.

Electrical Circuits

If you’ve ever seen the lights dim when an electrical appliance kicks in, you’ve seen the effect that a high-energy device can have on an electrical circuit. If you were to look at the effects of a multitude of such devices, each drawing power in its own way, you would see that the harmonically perfect 50 or 60 Hz sine wave you may think you’re getting with your power is anything but. Harmonic noise is extremely common on electrical circuits , and it can wreak havoc on sensitive electronic equipment. For a PBX, these problems can manifest as audio problems, logic errors, and system instability.

Ideally, you should never install a server on an electrical circuit that is shared with other devices. There should be only one outlet on the circuit, and you should connect only your telephone system (and associated peripherals) to it. The wire (including the ground) should be run unbroken directly back to the electrical panel. The grounding conductor should be insulated and isolated. There are far too many stories of photocopiers, air conditioners, and vacuum cleaners wreaking havoc with sensitive electronics to ignore this rule of thumb.

Warning

The electrical regulations in your area must always take precedence over any ideas presented here. If in doubt, consult a power quality expert in your area on how to ensure that you adhere to electrical regulations. Remember, electrical regulations take into account the fact that human safety is far more important than the safety of the equipment.

The Equipment Room

Environmental conditions can wreak havoc on systems, and yet it is quite common to see critical systems deployed with little or no attention given to these matters. When the system is installed, everything works well, but after as little as six months, components begin to fail. Talk to anyone with experience in maintaining servers and systems, and it becomes obvious that attention to environmental factors can play a significant role in the stability and reliability of systems.

Humidity

Simply put, humidity is water in the air. Water is a disaster for electronics for two main reasons: 1) water is a catalyst for corrosion, and 2) water is conductive enough that it can cause short circuits. Do not install any electronic equipment in areas of high humidity without providing a means to remove the moisture.

Temperature

Heat is the enemy of electronics. The cooler you keep your system, the more reliably it will perform, and the longer it will last. If you cannot provide a properly cooled room for your system, at a minimum ensure that it is placed in a location that ensures a steady supply of clean, cool air. Also, keep the temperature steady. Changes in temperature can lead to condensation and other damaging changes.

Dust

An old adage in the computer industry holds that dust bunnies inside of a computer are lucky. Let’s consider some of the realities of dust bunnies:

  • Significant buildup of dust can restrict airflow inside the system, leading to increased levels of heat.

  • Dust can contain metal particles, which, in sufficient quantities, can contribute to signal degradation or shorts on circuit boards.

Put critical servers in a filtered environment, and clean out dust bunnies on a regular schedule.

Security

Server security naturally involves protecting against network-originated intrusions, but the environment also plays a part in the security of a system. Telephone equipment should always be locked away, and only persons who have a need to access the equipment should be allowed near it.

Telephony Hardware

If you are going to connect Asterisk to any traditional telecommunications equipment, you will need the correct hardware. The hardware you require will be determined by what it is you want to achieve.

Connecting to the PSTN

Asterisk allows you to seamlessly bridge circuit-switched telecommunications networks[25] with packet-switched data networks.[26] Because of Asterisk’s open architecture (and open source code), it is ultimately possible to connect any standards-compliant interface hardware. The selection of open source telephony interface boards is currently limited, but as interest in Asterisk grows, that will rapidly change.[27] At the moment, one of the most popular and cost-effective ways to connect to the PSTN is to use the interface cards that evolved from the work of the Zapata Telephony Project (http://www.zapatatelephony.org).

Analog interface cards

Unless you need a lot of channels (or a have lot of money to spend each month on telecommunications facilities), chances are that your PSTN interface will consist of one or more analog circuits, each of which will require a Foreign eXchange Office (FXO) port.

Digium, the company that sponsors Asterisk development, produces analog interface cards for Asterisk. Check out its web site for its extensive line of analog cards, including the venerable TDM400P, the latest TDM800P, and the high-density TDM2400P. As an example, the TDM800P is an eight-port base card that allows for the insertion of up to two daughter cards, which each deliver either four FXO or four FXS ports.[28] The TDM800P can be purchased with these modules preinstalled, and a hardware echo-canceller can be added as well. Check out Digium’s web site (http://www.digium.com) for more information about these cards.

Other companies that produce Asterisk-compatible analog cards include:

These are all well-established companies that produce excellent products.

Digital interface cards

If you require more than 10 circuits, or require digital connectivity, chances are you’re going to be in the market for a T1 or E1 card.[29] Bear in mind, though, that the monthly charges for a digital PSTN circuit vary widely. In some places, as few as five circuits can justify a digital circuit; in others, the technology may never be cost-justifiable. The more competition there is in your area, the better chance you have of finding a good deal. Be sure to shop around.

The Zapata Telephony Project originally produced a T1 card, the Tormenta, that is the ancestor of most Asterisk-compatible T1 cards. The original Tormenta cards are now considered obsolete, but they do still work with Asterisk.

Digium makes several different digital circuit interface cards. The features on the cards are the same; the primary differences are whether they provide T1 or E1 interfaces, and how many spans each card provides. Digium has been producing Zaptel cards for Linux longer than anyone else, as they were deeply involved with the development of Zaptel on Linux, and have been the driving force behind Zaptel development over the years.

Sangoma, which has been producing open source WAN cards for many years, added Asterisk support for its T1/E1 cards a few years ago.[30] Rhino has had T1 hardware for Asterisk for a while now, and there are many other companies that offer digital interface cards for Asterisk as well.

Channel banks

A channel bank is loosely defined as a device that allows a digital circuit to be de-multiplexed into several analog circuits (and vice versa). More specifically, a channel bank lets you connect analog telephones and lines into a system across a T1 line. Figure 2.2, “One way you might connect a channel bank” shows how a channel bank fits into a typical office phone system.

Figure 2.2. One way you might connect a channel bank

One way you might connect a channel bank

Although they can be expensive to purchase, many people feel very strongly that the only proper way to integrate analog circuits and devices into Asterisk is through a channel bank. Whether that is true or not depends on a lot of factors, but if you have the budget, they can be very useful.[31] You can often pick up used channel banks on eBay. Look for units from Adtran and Carrier Access Corp. (Rhino makes great channel banks, and they are very competitively priced, but they may be hard to find used on eBay.) Don’t forget that you will need a T1 card in order to connect a channel bank to Asterisk.

Other types of PSTN interfaces

Many VoIP gateways exist that can be configured to provide access to PSTN circuits. Generally speaking, these will be of most use in a smaller system (one or two lines). They can also be very complicated to configure, as grasping the interaction between the various networks and devices requires a solid understanding of both telephony and VoIP fundamentals. For that reason, we will not discuss these devices in detail in this book. They are worth looking into, however; popular units are made by Sipura, Grandstream, Digium, and many other companies.

Another way to connect to the PSTN is through the use of Basic Rate Interface (BRI) ISDN circuits. BRI is a digital telecom standard that specifies a two-channel circuit that can carry up to 144 Kbps of traffic. It is very rarely used in North America, but in Europe it is very widely deployed. Due to the variety of different ways this technology has been implemented, and a lack of testing equipment, we will not be discussing BRI in very much detail in this book. Please note, however, that BRI is very popular in Europe, and Digium has produced the B410P card to address this need.

Connecting Exclusively to a Packet-Based Telephone Network

If you do not need to connect to the PSTN, Asterisk requires no hardware other than a server with a Network Interface Card (NIC).

However, if you are going to be providing music on hold[32] or conferencing and you have no physical timing source, you will need the ztdummy Linux kernel module. ztdummy is a clocking mechanism designed to provide a timing source to a system where no hardware timing source exists. Think of it as a kind of metronome to allow the system to mix multiple audio streams in a properly synchronized manner.

Echo Cancellation

One of the issues that can arise if you use analog interfaces on a VoIP system is echo. Echo is simply what you say being reflected back to you a short time later. The echo is caused by the far end, but you are the one that hears it. It is a little known fact that echo would be a massive problem in the PSTN were it not for the fact that the carriers employ complex (and expensive) strategies to eliminate it. We will talk about echo a bit more later on, but with respect to hardware we would suggest that you consider adding echo-cancellation hardware to any card you purchase for use as a PSTN interface. While Asterisk can do some work with echo in software, it does not provide nearly enough power to deal with the problem. Also, echo cancellation in software imposes a load on the processor; hardware echo cancellers built into the PSTN card take this burden away from the CPU.

Hardware echo cancellation can add several hundred dollars to your equipment cost, but if you are serious about having a quality system, invest the extra money now instead of suffering later. Echo problems are not pleasant at all, and your users will hate the system if they experience it.

As of this writing, several software echo cancellers have become available. We have not had a chance to evaluate any of them, but we know that they employ the same algorythems the hardware echo cancellers do. If you have a recently purchased Digium analog card, you can call Digium sales for a keycode to allow its latest software echo canceller to work with your system.[33] There are other software options available for other types of cards, but you will have to look into whether you have to purchase a license to use them.[34] Keep in mind that there is a performance cost to using software echo cancellers. They will place a measureable load on the CPU that needs to be taken into account when you design a system using these technologies.

Types of Phones

Since the title of this book is Asterisk: The Future of Telephony, we would be remiss if we didn’t discuss the devices that all of this technology ultimately has to interconnect: telephones!

We all know what a telephone is—but will it be the same five years from now? Part of the revolution that Asterisk is contributing to is the evolution of the telephone, from a simple audio communications device into a multimedia communications terminal providing all kinds of yet-to-be-imagined functions.

As an introduction to this exciting concept, we will briefly discuss the various kinds of devices we currently call “telephones” (any of which can easily be integrated with Asterisk). We will also discuss some ideas about what these devices may evolve into in the future (devices that will also easily integrate with Asterisk).

Physical Telephones

Any physical device whose primary purpose is terminating an on-demand audio communications circuit between two points can be classified as a physical telephone. At a minimum, such a device has a handset and a dial pad; it may also have feature keys, a display screen, and various audio interfaces.

This section takes a brief look at the various user (or endpoint) devices you might want to connect to your Asterisk system. We’ll delve more deeply into the mechanics of analog and digital telephony in Chapter 7, Understanding Telephony.

Analog telephones

Analog phones have been around since the invention of the telephone. Up until about 20 years ago, all telephones were analog. Although analog phones have some technical differences in different countries, they all operate on similar principles.

Tip

This contiguous connection is referred to as a circuit, which the telephone network used to use electromechanical switches to create—hence the term circuit-switched network.

When a human being speaks, the vocal cords, tongue, teeth, and lips create a complex variety of sounds. The purpose of the telephone is to capture these sounds and convert them into a format suitable for transmission over wires. In an analog telephone, the transmitted signal is analogous to the sound waves produced by the person speaking. If you could see the sound waves passing from the mouth to the microphone, they would be proportional to the electrical signal you could measure on the wire.

Analog telephones are the only kind of phone that are commonly available in any retail electronics store. In the next few years, that can be expected to change dramatically.

Proprietary digital telephones

As digital switching systems developed in the 1980s and 1990s, telecommunications companies developed digital Private Branch eXchanges (PBXes) and Key Telephone Systems (KTSes). The proprietary telephones developed for these systems were completely dependent on the systems to which they were connected and could not be used on any other systems. Even phones produced by the same manufacturer were not cross-compatible (for example, a Nortel Norstar set will not work on a Nortel Meridian 1 PBX). The proprietary nature of digital telephones limits their future. In this emerging era of standards-based communications, they will quickly be relegated to the dustbin of history.

The handset in a digital telephone is generally identical in function to the handset in an analog telephone, and they are often compatible with each other. Where the digital phone is different is that inside the telephone, the analog signal is sampled and converted into a digital signal—that is, a numerical representation of the analog waveform. We’ll leave a detailed discussion of digital signals until Chapter 7, Understanding Telephony; for now, suffice it to say that the primary advantage of a digital signal is that it can be transmitted over limitless distances with no loss of signal quality.

The chances of anyone ever making a proprietary digital phone directly compatible with Asterisk are slim, but companies such as Citel (http://www.citel.com)[35] have created gateways that convert the proprietary signals to Session Initiation Protocol (SIP).[36]

ISDN telephones

Prior to VoIP, the closest thing to a standards-based digital telephone was an ISDN-BRI terminal. Developed in the early 1980s, ISDN was expected to revolutionize the telecommunications industry in exactly the same way that VoIP promises to finally achieve today.

Tip

There are two types of ISDN: Primary Rate Interface (PRI) and Basic Rate Interface (BRI). PRI is commonly used to provide trunking facilities between PBXes and the PSTN, and is widely deployed all over the world. BRI is not at all popular in North America, but is common in Europe.

While ISDN was widely deployed by the telephone companies, many consider the standard to have been a flop, as it generally failed to live up to its promises. The high costs of implementation, recurring charges, and lack of cooperation among the major industry players contributed to an environment that caused more problems than it solved.

BRI was intended to service terminal devices and smaller sites (a BRI loop provides two digital circuits). A wealth of BRI devices have been developed, but BRI has largely been deprecated in favor of faster, less expensive technologies such as ADSL, cable modems, and VoIP.

BRI is still very popular for use in video-conferencing equipment, as it provides a fixed bandwidth link. Also, BRI does not have the type of quality of service issues a VoIP connection might, as it is circuit-switched.

BRI is still sometimes used in place of analog circuits to provide trunking to a PBX. Whether or not this is a good idea depends mostly on how your local phone company prices the service, and what features it is willing to provide.[37]

IP telephones

IP telephones are heralds of the most exciting change in the telecommunications industry. Already now, standards-based IP telephones are available in retail stores. The wealth of possibilities inherent in these devices will cause an explosion of interesting applications, from video phones to high-fidelity broadcasting devices, to wireless mobility solutions, to purpose-built sets for particular industries, to flexible all-in-one multimedia systems.

The revolution that IP telephones will spawn has nothing to do with a new type of wire to connect your phone to, and everything to do with giving you the power to communicate the way you want.

The early-model IP phones that have been available for several years now do not represent the future of these exciting appliances. They are merely a stepping-stone, a familiar package in which to wrap a fantastic new way of thinking.

The future is far more promising.

Softphones

A softphone is a software program that provides telephone functionality on a non-telephone device, such as a PC or PDA. So how do we recognize such a beast? What might at first glance seem a simple question actually raises many. A softphone should probably have some sort of dial pad, and it should provide an interface that reminds users of a telephone. But will this always be the case?

The term softphone can be expected to evolve rapidly, as our concept of what exactly a telephone is undergoes a revolutionary metamorphosis.[38] As an example of this evolution, consider the following: would we correctly define popular communication programs such as Instant Messenger as softphones? IM provides the ability to initiate and receive standards-based VoIP connections. Does this not qualify it as a softphone? Answering that question requires knowledge of the future that we do not yet possess. Suffice it to say that while at this point in time, softphones are expected to look and sound like traditional phones, that conception is likely to change in the very near future.

As standards evolve and we move away from the traditional telephone and toward a multimedia communications culture, the line between softphones and physical telephones will become blurred indeed. For example, we might purchase a communications terminal to serve as a telephone and install a softphone program onto it to provide the functions we desire.

Having thus muddied the waters, the best we can do at this point is to define what the term softphone will refer to in relation to this book, with the understanding that the meaning of the term can be expected to undergo a massive change over the next few years. For our purposes, we will define a softphone as any device that runs on a personal computer, presents the look and feel of a telephone, and provides as its primary function the ability to make and receive full-duplex audio communications (formerly known as “phone calls”)[39] through E.164 addressing.[40]

Telephony Adaptors

A telephony adaptor (usually referred to as an ATA, or Analog Terminal Adaptor) can loosely be described as an end-user device that converts communications circuits from one protocol to another. Most commonly, these devices are used to convert from some digital (IP or proprietary) signal to an analog connection that you can plug a standard telephone or fax machine into.

These adaptors could be described as gateways, for that is their function. However, popular usage of the term telephony gateway would probably best describe a multiport telephony adaptor, generally with more complicated routing functions.

Telephony adaptors will be with us for as long as there is a need to connect incompatible standards and old devices to new networks. Eventually, our reliance on these devices will disappear, as did our reliance on the modem—obsolescence through irrelevance.

Communications Terminals

Communications terminal is an old term that disappeared for a decade or two and is being reintroduced here, very possibly for no other reason than that it needs to be discussed so that it can eventually disappear again—once it becomes ubiquitous.

First, a little history. When digital PBX systems were first released, manufacturers of these machines realized that they could not refer to their endpoints as telephones—their proprietary nature prevented them from connecting to the PSTN. They were therefore called terminals, or stations. Users, of course, weren’t having any of it. It looked like a telephone and acted like a telephone, and therefore it was a telephone. You will still occasionally find PBX sets referred to as terminals, but for the most part they are called telephones.

The renewed relevance of the term communications terminal has nothing to do with anything proprietary—rather, it’s the opposite. As we develop more creative ways of communicating with each other, we gain access to many different devices that will allow us to connect. Consider the following scenarios:

  • If I use my PDA to connect to my voicemail and retrieve my voice messages (converted to text), does my PDA become a phone?

  • If I attach a video camera to my PC, connect to a company’s web site, and request a live chat with a customer service rep, is my PC now a telephone?

  • If I use the IP phone in my kitchen to surf for recipes, is that a phone call?

The point is simply this: we’ll probably always be “phoning” each other, but will we always be using “telephones” to do so?

Linux Considerations

If you ask anyone at the Free Software Foundation, they will tell you that what we know as Linux is in fact GNU/Linux. All etymological arguments aside, there is some valuable truth to this statement. While the kernel of the operating system is indeed Linux, the vast majority of the utilities installed on a Linux system and used regularly are in fact GNU utilities. “Linux” is probably only 5 percent Linux, possibly 75 percent GNU, and perhaps 20 percent everything else.

Why does this matter? Well, the flexibility of Linux is both a blessing and a curse. It is a blessing because with Linux you can truly craft your very own operating system from scratch. Since very few people ever do this, the curse is in large part due to the responsibility you must bear in determining which of the GNU utilities to install, and how to configure the system.

If this seems overwhelming, do not fear. In the next chapter, we will discuss the selection, installation, and configuration of the software environment for your Asterisk system.

Conclusion

In this chapter, we’ve discussed all manner of issues that can contribute to the stability and quality of an Asterisk installation. Before we scare you off, we should tell you that many people have installed Asterisk on top of a graphical Linux workstation—running a web server, a database, and who knows what else—with no problems whatsoever.[41]How much time and effort you should devote to following the best practices and engineering tips in this chapter all depends on how much work you expect the Asterisk server to perform, and how much quality and reliability your system must provide. If you are experimenting with Asterisk, don’t worry too much; just be aware that any problems you have may not be the fault of the Asterisk system.

What we have attempted to do in this chapter is give you a feel for the kinds of best practices that will help to ensure that your Asterisk system will be built on a reliable, stable platform. Asterisk is quite willing to operate under far worse conditions, but the amount of effort and consideration you decide to give these matters will play a part in the stability of your PBX. Your decision should depend on how critical your Asterisk system will be.



[14] People have successfully compiled and run Asterisk on WRAP boards, Linksys WRT54G routers, Soekris systems, Pentium 100s, PDAs, Apple Macs, Sun SPARCs, laptops, and more. Of course, whether you would want to put such a system into production is another matter entirely. (Actually, the AstLinux distribution, by Kristian Kielhofner, runs very well indeed on the Soekris 4801 board. Once you’ve grasped the basics of Asterisk, this is something worth looking into further. Check out http://www.astlinux.org.)

[15] Roughly 30 MHz of CPU power per channel.

[16] If you want to be completely up to the minute on which CPUs are leading the performance race, surf on over to Tom’s Hardware (http://www.tomshardware.com) or AnandTech (http://www.anandtech.com), where you will find a wealth of information about both current and out-of-date CPUs, motherboards, and chipsets.

[17] Greg Boehnlein once compiled and ran Asterisk on a 133 MHz Pentium system, but that was mostly as an experiment. Performance problems are far more likely, and properly configuring such a system requires an expert knowledge of Linux. We do not recommend running Asterisk on anything less than a 500 MHz system (for a production system, 2 GHz might be a sensible minimum). Still, we think the fact that Asterisk is so flexible is remarkable.

[18] With the advent of PCI-X and PCI-Express, it is becoming harder and harder to select a motherboard with the correct type of slots. Be very certain that the motherboard you select has the correct type and quantity of card slots for your hardware. Keep in mind that most companies that produce hardware cards for Asterisk offer PCI and PCI-Express versions, but it’s still up to you to make sure they make sense in whatever motherboard and chassis combination you choose.

[19] OK, it wasn’t actually a locomotive, but it sure sounded like one. Does anyone know where to get quiet CPU fans for Xeon processors? It’s getting too loud in the lab here.

[20] Or any system that is expected to process audio.

[21] Okay, look, you can plug it in wherever you’d like, and it’ll probably work, but if your system has strange stability problems, please give this section another read. Deal?

[22] In electronic devices, a binary zero (0) is generally related to a 0 volt signal, while a binary one (1) can be represented by many different voltages (commonly between 2.5 and 5 volts). The grounding reference that the system will consider 0 volts is often referred to as the logic ground. A poorly grounded system might have electrical potential on the logic ground to such a degree that the electronics mistake a binary zero for a binary one. This can wreak havoc with the system’s ability to process instructions.

[23] It is a common misconception belief that all UPSes provide clean power. This is not at all true.

[24] On a hobby system, this is probably too much to ask, but if you are planning on using Asterisk for anything important, at least be sure to give it a fighting chance; don’t put anything like air conditioners, photocopiers, laser printers, or motors on the same circuit. The strain such items place on your power supply will shorten its life expectancy.

[25] Often referred to as TDM networks, due to the Time Division Multiplexing used to carry traffic through the PSTN.

[26] Popularly called VoIP networks, although Voice over IP is not the only method of transmitting voice over packet networks (Voice over Frame Relay was very popular in the late 1990s).

[27] The evolution of inexpensive, commodity-based telephony hardware is only slightly behind the telephony software revolution. New companies spring up on a weekly basis, each one bringing new and inexpensive standards-based devices into the market.

[28] FXS and FXO refer to the opposing ends of an analog circuit. Which one you need will be determined by what you want to connect to. Chapter 7, Understanding Telephony discusses these in more detail.

[29] T1 and E1 are digital telephony circuits. We’ll discuss them further in Chapter 7, Understanding Telephony.

[30] It should be noted that a Sangoma Frame Relay card played a role in the original development of Asterisk (see http://linuxdevices.com/articles/AT8678310302.html); Sangoma has a long history of supporting open source WAN interfaces with Linux.

[31] We use channel banks to simulate a central office. One 24-port channel bank off an Asterisk system can provide up to 24 analog lines—perfect for a classroom or lab.

[32] Technically, no timing source is needed for music on hold, but it generally works better with one.

[33] This software is not part of a normal Asterisk download because Digium has to pay to license it separately. Nevertheless, it has grandfathered it into all of its cards, so it is available for free to anyone who has a Digium analog card that is still under warranty. If you are running a non-Digium analog card, you can purchase a keycode for this software echo canceller from Digium’s web site.

[34] Sangoma also offers free software echo cancellation on their analog cards (up to six channels).

[35] Citel has produced a fantastic product that is limited by the fact that it is too expensive. If you have old proprietary PBX telephones, and you want to use them with your Asterisk system, Citel’s technology can do the job, but make sure you understand how the per-port cost of these units stacks up against replacing the old sets with pure VoIP telephones.

[36] The SIP is currently the most well-known and popular protocol for VoIP. We will discuss it further in Chapter 8, Protocols for VoIP.

[37] If you are in North America, give up on this idea, unless you have a lot of patience and money, and are a bit of a masochist.

[38] Ever heard of Skype?

[39] OK, so you think you know what a phone call is? So did we. Let’s just wait a few years, shall we?

[40] E.164 is the ITU standard that defines how phone numbers are assigned. If you’ve used a telephone, you’ve used E.164 addressing.

[41] Just don’t ever install the X-windowing environment (which is anything that delivers a desktop, such as GNOME, KDE, and such). You are almost guaranteed to have audio quality problems, as Asterisk and the GUI will fight for control of the CPU.

Chapter 3. Installing Asterisk

I long to accomplish great and noble tasks, but it is my chief duty to accomplish humble tasks as though they were great and noble. The world is moved along, not only by the mighty shoves of its heroes, but also by the aggregate of the tiny pushes of each honest worker.

--Helen Keller

In the previous chapter, we discussed preparing a system to install Asterisk. Now it’s time to get our hands dirty!

Although a large number of Linux[42] distributions and PC architectures are excellent candidates for Asterisk, we have chosen to focus on a single distribution in order to maintain brevity and clarity throughout the book. The instructions that follow have been made as generic as possible, but you will notice a leaning toward CentOS directory structure and system utilities. We have chosen to focus on CentOS (arguably, the most popular distro for Asterisk) because its command set, directory structure, and so forth are likely to be familiar to a larger percentage of readers (we have found that many Linux administrators are familiar with CentOS, even if they don’t prefer it). This doesn’t mean that CentOS is the only choice, or even the best one for you. A question that often appears on the mailing lists is: “Which distribution of Linux is the best to use with Asterisk?” The multitude of answers generally boils down to “the one you like the best.”[43]

What Packages Do I Need?

Most Asterisk configurations are composed of three main packages : the main Asterisk program (asterisk), the Zapata telephony drivers (zaptel), and the PRI libraries (libpri). If you plan on a pure VoIP network, the only real requirement is the asterisk package, but we recommend installing all three packages; you can choose what modules to activate later. The zaptel drivers are required if you are using analog or digital hardware, or if you’re using the ztdummy driver (discussed later in this chapter) as a timing source. The libpri library is optional unless you’re using ISDN PRI interfaces, and you may save a small amount of RAM if you don’t load it, but we recommend that it be installed in conjunction with the zaptel package for completeness.

In the first edition of this book, we recommended that you install the additional asterisk-sounds package. This was a separate compressed archive that you would download, extract, and then install. As of Asterisk version 1.4.0, there are now two sets of sounds packages: the Core Sound package and the Extra Sound package. Since Asterisk supports several different audio formats, these packages can be obtained in a number of different sound formats, such as G.729 and GSM. The reason for all of the different formats is that Asterisk can use the sound format that requires the least amount of CPU transcode. For example, if you have a lot of connections coming in on VoIP channels that are running GSM, you would want to have the GSM version of the sound files. You can select one or more sound prompt types in the menuselect screen (discussed later in this chapter). We recommend that you install at least one type of sounds file from both the Core Sound package and Extra Sound package menu items. Since we may make use of some of the Extra Sound files throughout this book, we will assume you have at least one of the formats installed.

Linux Package Requirements

To compile Asterisk, you must have the GCC compiler (version 3.x or later) and its dependencies on your system. Asterisk also requires bison, a parser generator program that replaces yacc, and ncurses for CLI functionality. The cryptographic library in Asterisk requires OpenSSL and its development packages.

Zaptel requires libnewt and its development packages for the zttool program (see the section called “Using ztcfg and zttool” later in this chapter). If you’re using PRI interfaces, Zaptel also requires the libpri package (again, even if you aren’t using PRI circuits, we recommend that you install libpri along with zaptel).

If you install the Software Development packages in CentOS, you will have all of these tools. If you are looking to keep things trim, and wish to install the bare minimum to compile Asterisk and its related packages, Table 3.1, “List of packages required to compile libpri, zaptel, and asterisk” will prove useful.

Note

In the following table, the -y switch to the yum application means to answer yes to all prompts, and using it will install the application and all dependencies without prompting you. If this is not what you want, omit the -y switch.

If you just want to install all of the above packages in one go, you can specify more than one package on the command line, e.g.:

# yum install -y gcc ncurses-devel libtermcap-devel [...]

Table 3.1. List of packages required to compile libpri, zaptel, and asterisk

Package nameInstallation commandNoteUsed by
GCC 3.x yum install -y gcc Required to compile zaptel, libpri, and asterisklibpri, zaptel, asterisk
ncurses-devel yum install -y ncurses-devel Required by menuselectmenuselect
libtermcap-devel yum install -y libtermcap-devel Required by asteriskasterisk
Kernel Development Headers yum install -y kernel-devel Required to compile zaptelzaptel
Kernel Development Headers (SMP) yum install -y kernel-smp-devel Required to compile zaptelzaptel
GCC C++ 3.x yum install -y gcc-c++ Required by asteriskasterisk
OpenSSL (optional) yum install -y openssl-devel Dependency of OSP, IAX2 encryption, res_crypto (RSA key support)asterisk
newt-devel (optional) yum install -y newt-devel Dependency of zttoolzaptel
zlib-devel (optional) yum install -y zlib-devel Dependency of DUNDiasterisk
unixODBC; unixODBC-devel (optional) yum install -y unixODBC-devel Dependency of func_odbc, cdr_odbc, res_config_odbc, res_odbc, ODBC_STORAGEasterisk
libtool (optional; recommended) yum install -y libtool Dependency of ODBC-related modulesasterisk
GNU make (version 3.80 or higher) [a] yum install -y make Required to compile zaptel and asteriskasterisk

[a] It is a common problem among new installs on some Linux distriebutons to see GNU make versions of 3.79 or lower. Note that Asterisk will no longer build correctly unless you have at least version 3.80 of GNU make.

Obtaining the Source Code

The best place to get source code for Asterisk and it’s packages is directly from the http://www.asterisk.org web site or FTP server.

Obtaining Asterisk Source Code

The easiest way to obtain the most recent release is through the use of the program wget.

Note that we will be making use of the /usr/src/ directory to extract and compile the Asterisk source, although some system administrators may prefer to use /usr/local/src. Also be aware that you will need root access to write files to the /usr/src/ directory and to install Asterisk and its associated packages.

Note

See Chapter 13, Managing Your Asterisk System for information on running Asterisk as non-root. All security professionals will recommend that you run your daemons as a non-root user in case there are security vulnerabilities in the software. This helps to lower (but obviously does not eliminate) the risk of someone compromising the root user.

To obtain the latest release source code via wget, enter the following commands on the command line:

# cd /usr/src/
# wget http://downloads.digium.com/pub/asterisk/asterisk-1.4-current.tar.gz
# wget http://downloads.digium.com/pub/libpri/libpri-1.4-current.tar.gz
# wget http://downloads.digium.com/pub/zaptel/zaptel-1.4-current.tar.gz

Note

The latest versions of the asterisk, libpri, and zaptel packages may not necessarily be the same version number.

Alternatively, during development and testing you will probably want to work with the latest branch. To check it out from SVN, run:

          # svn co http://svn.digium.com/svn/asterisk/branches/1.4 asterisk-1.4
        

If you retrieved the described source code via the release files on the Digium FTP server, then extract the files as described in the next section before continuing on with compiling.

Extracting the Source Code

The packages you downloaded from the FTP server are compressed archives containing the source code; thus, you will need to extract them before compiling. If you didn’t download the packages to /usr/src/, either move them there now or specify the full path to their location. We will be using the GNU tar application to extract the source code from the compressed archive. This is a simple process that can be achieved through the use of the following commands:

# cd /usr/src/
# tar zxvf zaptel-1.4-current.tar.gz
# tar zxvf libpri-1.4-current.tar.gz
# tar zxvf asterisk-1.4-current.tar.gz      

Tip

In bash (and other shell systems which support it), you can use an extremely handy feature called Tab completion. This will allow you to type part of a filename and have the rest of it completed automatically. For example, if you type tar zxvf zap<tab> that will complete the full zaptel filename for you. If more than one filename matches the pattern and you hit Tab twice, it will list the files matching that pattern.

These commands will extract the packages and source code to their respective directories. When you extract the asterisk-1.4-current.tar.gz file, you will find that the file will extract to the current version of Asterisk, i.e. asterisk-1.4.4.

Tip

It’s always a good idea to keep the source code of the most recently working version of a package in case you have to “roll back” out of a new bug introduced, or some other strange behavior you can’t solve immediately.

Menuselect

In the 1.4.0 version of Asterisk and its related packages, a new build system, autoconf, was implemented. This has changed the build process slightly, but has given more flexibilty to control what modules are being built at build time. This has an advantage in that we only have to build the modules we want and need instead of building everything.

Along with the new build system, a new menu-based selection system was introduced, courtesy of Russell Bryant. This new system permits a finer-grained selection to which modules are built before compiling the software and no longer requires the user to edit Makefiles. So instead of discussing how to use menuselect in every “Compiling ...” section, we will discuss it here, so when you see make menuselect you will understand what to do once inside the menuselect configuration screen.

In Figure 3.1, “Sample menuselect screen”, we see the opening menuselect screen for the Asterisk software. Other packages will look extremely similar, but with less options. We can navigate up and down the list using the arrow keys. We can select one of the menu options by pressing Enter or by using the right arrow key. The left arrow key can be used to go back.

Figure 3.1. Sample menuselect screen

Sample menuselect screen

Figure 3.2, “List of modules to be built” shows a list of possible dialplan applications that can be built for use in Asterisk. Modules to be built are marked as [*]. A module is marked as not being built by [ ]. Modules that have XXX in front of them are missing a package dependency which must be satisfied before it will be available to be built. In Figure 3.2, “List of modules to be built”, we can see that the app_flash module cannot be built due to a missing dependency of Zaptel (i.e., the Zaptel module has not been built and installed on the system since the last time ./configure was run). If you have satisfied a dependency since the last time you ran ./configure, then run it again, and rerun menuselect. Your module should now be available for building.

Figure 3.2. List of modules to be built

List of modules to be built

After you have finished making changes to menuselect, type x to save and quit. q will also quit out of menuselect, but it will not save the changes. If you make changes and type q, your changes may be lost!

Compiling Zaptel

Figure 3.3, “Layers of device interaction with Asterisk” shows the layers of interaction between Asterisk and the Linux kernel with respect to hardware control. On the Asterisk side is the Zapata channel module, chan_zap. Asterisk uses this interface to communicate with the Linux kernel, where the drivers for the hardware are loaded.

Figure 3.3. Layers of device interaction with Asterisk

Layers of device interaction with Asterisk

The Zaptel interface is a kernel loadable module that presents an abstraction layer between the hardware drivers and the Zapata module in Asterisk. It is this concept that allows the device drivers to be modified without any changes being made to the Asterisk source itself. The device drivers are used to communicate with the hardware directly and to pass the information between Zaptel and the hardware.

Tip

While Asterisk itself compiles on a variety of platforms, the Zaptel drivers are Linux-specific—they are written to interface directly with the Linux kernel. There is a project at http://www.solarisvoip.com that provides Zaptel support for Solaris. There is also a project that is working to provide Zapata drivers for BSD, located at http://www.voip-info.org/tiki-index.php?page=FreeBSD+zaptel.

First we will discuss the ztdummy driver, used on systems that require a timing interface but that do not have hardware. Then we will look at compiling and installing the drivers. (The configuration of Zaptel drivers will be discussed in the next chapter.)

Tip

Before compiling the Zaptel drivers on a system running a Linux 2.4 kernel, you should verify that /usr/src/ contains a symbolic link named linux-2.4 pointing to your kernel source. If the symbolic link doesn’t exist, you can create it with the following command (assuming you’ve installed the source in /usr/src/):

# ln -s /usr/src/'uname -r' /usr/src/linux-2.4   

Computers running Linux 2.6 kernel-based distributions do not usually require the use of the symbolic link, as these distributions will search for the kernel build directory automatically. However, if you’ve placed the build directory in a nonstandard place (i.e., somewhere other than /lib/modules/ <kernel version> /build/), you will require the use of the symbolic link.

While Asterisk and the other related packages run on Linux 2.4.x kernels, development is done first and foremost on 2.6.x kernels and support for 2.4.x kernels is not guarenteed in the future.

The ztdummy Driver

In Asterisk, certain applications and features require a timing device in order to operate (Asterisk won’t even compile them if no timing device is found). All Digium PCI hardware provides a 1 kHz timing interface that satisfies this requirement. If you lack the PCI hardware required to provide timing, the ztdummy driver can be used as a timing device. On Linux 2.4 kernel-based distributions, ztdummy must use the clocking provided by the UHCI USB controller.

Note

Many older systems (and some newer ones) use an OHCI USB controller chip, which is incompatible with ztdummy. However, if you’re using a 2.6 kernel there is no need to worry about which USB controller chip your system has.

The driver looks to see that the usb-uhci module is loaded and that the kernel version is at least 2.4.5. Older kernel versions are incompatible with ztdummy.

On a 2.6 kernel-based distribution, ztdummy does not require the use of the USB controller. (As of v2.6.0, the kernel now provides 1 kHz timing[46] with which the driver can interface; thus, the USB controller hardware requirement is no longer necessary.)

The Zapata Telephony Drivers

Compiling the Zapata telephony drivers for use with your Digium hardware is straightforward; however, the method employed between the 1.2 and 1.4 versions is slightly different due to the new build environment. First we need to run ./configure in order to determine what applications and libraries are installed on the system. This will ensure that everything Zaptel needs is installed. The following commands will build Zaptel and its modules:

# cd /usr/src/zaptel-version
            
# make clean
# ./configure
# make menuselect
# make
# make install   

Tip

While running make clean is not always necessary, it’s a good idea to run it before recompiling any of the modules, as it will remove the compiled binary files from within the source code directory. You can also use it to clean up after installing if you don’t like to leave the compiled binaries floating around. Note that this removes the binaries only from the source directory, not from the system.

In addition to the executables, make clean also removes the intermediary files (i.e., the object files) after compilation. You don’t need them occupying space on your hard drive.

If you’re using a system that makes use of the /etc/rc.d/init.d/ or /etc/init.d/ directories (such as CentOS and other Red Hat-based distros), you may wish to run the make config command as well. This will install the startup scripts and configure the system, using the chkconfig command to load the zaptel module automatically at startup:

            # make config
          

Tip

The Debian equivalent of chkconfig is update-rc.d.

While Digium only officially supports Zaptel on Linux, several projects to port Zaptel to other platforms should be noted:

Using ztcfg and zttool

Two programs installed along with Zaptel are ztcfg and zttool. The ztcfg program is used to read the configuration in /etc/zaptel.conf to configure the hardware. The zttool program can be used to check the status of your installed hardware. For instance, if you are using a T1 card and there is no communication between the endpoints, you will see a red alarm. If everything is configured correctly and communication is possible, you should see an “OK.” The zttool application is also useful for analog cards, because it tells you their current state (configured, off-hook, etc.). The use of these programs will be explored further in the next chapter.

Note

The libnewt libraries and their development packages (newt-devel on Red Hat-based distributions) must be installed for zttool to be compiled.

The ztcfg and zttool applications, along with other useful utilities, are located under the Utilities section of the Zaptel menuselect screen.

Compiling libpri

The libpri libraries do not make use of the autoconf build environment or the menuselect feature as they are unnecessary; thus, the installation is simplified. libpri is used by various makers of Time Division Multiplexing (TDM) hardware, but even if you don’t have the hardware installed, it is safe to compile and install this library. You must compile and install libpri before Asterisk, as it will be detected and used when Asterisk is compiled. Here are the commands (replace version with your version of libpri):

# cd /usr/src/libpri-version
         
# make clean
# make
# make install

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.

Standard Installation

Asterisk is compiled with gcc through the use of the GNU make program. To get started compiling Asterisk, simply run the following commands (replace version with your version of Asterisk):

# cd /usr/src/asterisk-version
            
# make clean
# ./configure
# make menuselect
# 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 (http://www.astricon.net), 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.

Tip

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 files, for 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:

          # make config
        

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.

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.

make distclean

The make distclean command is used to remove the compiled binaries and to clean the source directory back to its original state after being extracted from the compressed archive.

make update

The make update command is used to update the existing code from the Digium SVN server. If you downloaded the source code from the FTP server, you will receive a notice stating so.

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 CentOS or Fedora box, as other distributions may have different paths to their cgi-bin/ directories. (This, of course, can be changed by editing the HTTP_CFGDIR variable in the Makefile at line 133 at the time of this writing.)

make progdocs

The make progdocs 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, although much work was published since the first edition of this book! The information contained within the doxygen system will be useful only to developers.

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 really only 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.

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).[47] 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―and besides, don’t you want to be l33t?[48] In the next chapter, we’ll look at how to initially configure Asterisk and several kinds of channels.

Installing Additional Prompts

Additional prompts are installed via the menuselect application in your Asterisk source directory. There are three sets of audio packages: Core Sound, Extra Sound, and Music On Hold File. Each set of packages is broken down into different formats (and the Core Sound packages are available in multiple languages). Using the menuselect application, you can select combinations of audio packages for use in your environment. Some of the formats available include:

  • WAV

  • μlaw

  • alaw

  • GSM

  • G.729

  • G.722 (wideband, 16-bit)

As of this writing, the Core Sound packages are available in the following languages:

  • English

  • Spanish

  • French

Warning

Selecting any sounds in menuselect will cause the system to download the files from the Digium FTP server upon install. The size of these files ranges anywhere from 2 MB to 27 MB, so be aware of this when installing offline, or on slow and expensive links.

Common Compiling Issues

There are many common compiling issues that users often run into. Here are some of the more common problems, and how to resolve them.

Asterisk

First, let’s take a look at some of the errors you may encounter when running the configure script.

configure: error: no acceptable C compiler found in $PATH

If you receive the following error while attempting to run the configure script, you must install the gcc compiler and its dependencies:

configure: error: no acceptable C compiler found in $PATH

The following packages are required for gcc:

  • gcc

  • cpp

  • glibc-headers

  • glibc-devel

  • glibc-kernheaders

These can be installed manually, by copying the files off of your distribution disks, or through the yum package manager, with the command yum install gcc.

configure: error: C++ preprocessor "/lib/cpp" fails sanity check

The following error will be displayed if no C++ preprocessor is found installed on the system. You must install the gcc-c++ package and its dependencies:

configure: error: C++ preprocessor "/lib/cpp" fails sanity check

The following packages are required for the gcc-c++ preprocessor; installed by running yum install gcc-c++:

  • gcc-c++

  • libstdc++-devel

configure: error: *** termcap support not found

The following error may be encountered during initialization of the configure script if the libtermcap-devel package is not installed:

configure: error: *** termcap support not found

The following file is required in order to compile Asterisk; it can be installed with the yum install libtermcap-devel command:

  • libtermcap-devel

Zaptel

You may also run into errors when compiling Zaptel. Here are some of the most commonly occurring problems, and what to do about them. If your error is not listed below, see the previous section as your error may be covered there.

make: cc: Command not found

You will receive the following error if you attempt to build Zaptel without the gcc compiler installed:

make: cc: Command not found
make: *** [gendigits.o] Error 127

Be sure to install gcc and its dependencies. For more information, see the section called “configure: error: no acceptable C compiler found in $PATH” in the previous section.

FATAL: Module wctdm/fxs/fxo not found

The TDM400P cards require the PCI bus to be version 2.2. If you attempt to load the Zapata telephony drivers with an older version, you may get the following errors:

  • When attempting to load the wctdm driver, you may see this error:

    FATAL: Module wctdm not found
  • When attempting to load the wctdm or wcfxo driver, you may see an error such as this:

    ZT_CHANCONFIG failed on channel 1: No such device or address (6)
    FATAL: Module wctdm not found
    

The only way to resolve these errors is to use a newer motherboard that supports PCI version 2.2:

Tip

You may also encounter these errors if the power has not been attached to the Molex connector found on the TDM400P card.

Unresolved symbol link when loading ztdummy

The ztdummy driver requires that a UHCI USB controller be available on Linux 2.4 kernels (the USB controller is not a requirement on Linux 2.6 kernels, because they are capable of generating the 1 kHz timing reference). There exists a secondary kind of controller, known as OHCI, which is not compatible with the ztdummy driver. If the UHCI USB controller is not accessible on Linux 2.4 kernels, the following error will occur:

/lib/modules/2.4.22/misc/ztdummy.o: /lib/modules/2.4.22/misc/ztdummy.o: unresolved
symbol unlink_td
/lib/modules/2.4.22/misc/ztdummy.o: /lib/modules/2.4.22/misc/ztdummy.o: unresolved
symbol alloc_td
/lib/modules/2.4.22/misc/ztdummy.o: /lib/modules/2.4.22/misc/ztdummy.o: unresolved
symbol delete_desc
/lib/modules/2.4.22/misc/ztdummy.o: /lib/modules/2.4.22/misc/ztdummy.o: unresolved
symbol uhci_devices
/lib/modules/2.4.22/misc/ztdummy.o: /lib/modules/2.4.22/misc/ztdummy.o: unresolved
symbol uhci_interrupt
/lib/modules/2.4.22/misc/ztdummy.o: /lib/modules/2.4.22/misc/ztdummy.o: unresolved
symbol fill_td
/lib/modules/2.4.22/misc/ztdummy.o: /lib/modules/2.4.22/misc/ztdummy.o: unresolved
symbol insert_td_horizontal
/lib/modules/2.4.22/misc/ztdummy.o: insmod /lib/modules/2.4.22/misc/ztdummy.o failed
/lib/modules/2.4.22/misc/ztdummy.o: insmod ztdummy failed

You can verify that you have the correct style of USB controller and its associated drivers with the lsmod command:

# lsmod
Module                  Size  Used by
usb_uhci               26412  0
usbcore                79040  1 [hid usb-uhci]

As you can see in the example above, you are looking to make sure that the usbcore and usb_uhci modules are loaded. If these modules are not loaded, be sure that USB has been activated within your BIOS and that the modules exist.

If the USB drivers are not loaded, you can still check which type of USB controller you have with the dmesg command:

# dmesg | grep -i usb       

To verify that you indeed have a UHCI USB controller, look for the following lines:

uhci_hcd 0000:00:04.2: new USB bus registered, assigned bus number 1
hub 1-0:1.0: USB hub found
uhci_hcd 0000:00:04.3: new USB bus registered, assigned bus number 2
hub 2-0:1.0: USB hub found

Depmod errors during compilation

If you experience depmod errors during compilation, you more than likely don’t have a symbolic link to your Linux kernel sources. If you don’t have your Linux kernel sources installed, retrieve the sources for your installed kernel, install them, and create a symbolic link against /usr/src/linux-2.4. The following is an example of a depmod error:

depmod: *** Unresolved symbols in /lib/modules/2.4.22/kernel/drivers/block/
loop.o

Loading Asterisk and Zaptel Quickly

If you run make config in the Asterisk or Zaptel source directories, then the initialization scripts used to control Asterisk or Zaptel will be copied to /etc/rc.d/init.d/. The scripts can be used to easily load and unload Asterisk and Zaptel. They will also run the chkconfig command for you so Asterisk and Zaptel will be started automatically upon system boot. The following shows their usage:

# service zaptel start
# service asterisk start

Each initialization script has several options that can be utilized to control the PBX or the drivers. Tables 3.2 and 3.3 show the commands run by the script as if you had typed them into the command-line interface (CLI) yourself:

Table 3.2. Asterisk initialization script options

service asterisk <option>Manual equivalent
start asterisk
stop killproc asterisk
restart stop; start
reload asterisk -rx "reload"
status ps aux | grep [a]sterisk

Table 3.3. Zaptel initialization script options

service zaptel <option>Manual equivalent
start modprobe zaptel; modprobe <module>; /sbin/ztcfg
stop rmmod ztdummy; rmmod zaptel
restart stop; start
reload /sbin/ztcfg

Loading Zaptel Modules Without Scripts

In this section, we’ll take a quick look at how to load the zaptel and ztdummy modules without the CentOS initialization script. The zaptel module does not require any configuration if it’s being used only for the ztdummy module. If you plan on loading the ztdummy module as your timing source (and thus, you will not be running any PCI hardware in your system), now is a good time to load both drivers.

Systems Running udevd

In the early days of Linux, the system’s /dev/ directory was populated with a list of devices with which the system could potentially interact. At the time, nearly 18,000 devices were listed. That all changed when devfs was released, allowing dynamic creation of devices that are active within the system. Some of the recently released distributions have incorporated the udev daemon into their systems to dynamically populate /dev/ with device nodes.

To allow Zaptel and other device drivers to access the PCI hardware installed in your system, you must add some rules. Using your favorite text editor, open up your udevd rules file. On CentOS, for example, this file is located at /etc/udev/rules.d/50-udev.rules. Add the following lines to the end of your rules file:

# Section for zaptel 
 
device
   KERNEL="zapctl",     NAME="zap/ctl"
   KERNEL="zaptimer",   NAME="zap/timer"
   KERNEL="zapchannel", NAME="zap/channel"
   KERNEL="zappseudo",  NAME="zap/pseudo"
   KERNEL="zap[0-9]*",  NAME="zap/%n"

Save the file and reboot your system for the settings to take effect.

Note

You may not have to actually edit anything in your system, as the Zaptel installation script will try to install the rules for you; however, we have left this here as a reference for those systems that are not automatically configured.

Loading Zaptel

The zaptel module must be loaded before any of the other modules are loaded and used. Note that if you will be using the zaptel module with PCI hardware, you must configure /etc/zaptel.conf before you load it. (We will discuss how to configure zaptel.conf for use with hardware in Chapter 4, Initial Configuration of Asterisk.) If you are using zaptel only to access ztdummy, you can load it with the modprobe command, as follows:

# modprobe zaptel   

If all goes well, you shouldn’t see any output. To verify that the zaptel module loaded successfully, use the lsmod command. You should be returned a line showing the zaptel module and the amount of memory it is using, as in the following:

# lsmod | grep zaptel
zaptel                201988  0

Loading ztdummy

The ztdummy module is an interface to a device that provides timing, which in turn allows Asterisk to provide timing to various applications and functions that require it. Use the modprobe command to load the ztdummy module after zaptel has been loaded:

# modprobe ztdummy      

If ztdummy loads successfully, no output will be displayed. To verify that ztdummy is loaded and is being used by zaptel, use the lsmod command. The following output is from a computer running the 2.6 kernel:

# lsmod | grep ztdummy
    Module                  Size  Used by
    ztdummy                 3796  0
    zaptel                201988  1 ztdummy

If you happen to be running a 2.4 kernel-based computer, your output from lsmod will show that ztdummy is using the usb-uhci module:

 # lsmod | grep ztdummy
    Module                  Size  Used by
    ztdummy                 3796  0
    zaptel                201988  0 ztdummy
    usb-uhci               24524  0 ztdummy

Loading libpri Without Script

The libpri libraries do not need to be loaded like modules. Asterisk looks for libpri at compile time and configures itself to use the libraries if they are found.

Starting Asterisk Without Scripts

Asterisk can be loaded in a variety of ways. The easiest way is to start Asterisk by running the binary file directly from the Linux command-line interface. If you are running a system that uses the init.d scripts, you can easily start and restart Asterisk that way as well. However, the preferred way of starting Asterisk is via the safe_asterisk script.

Console Commands

The Asterisk binary is, by default, located at /usr/sbin/asterisk. If you run /usr/sbin/asterisk, it will be loaded as a daemon. There are also a few switches you should be aware of that allow you to (re)connect to the Asterisk CLI, set the verbosity of CLI output, and allow core dumps if Asterisk crashes (for debugging with gdb). To explore the full range of options, run Asterisk with the -h switch:

# /usr/sbin/asterisk -h       

Here is a list of the most commonly used options:

-c

Console. This will start Asterisk as a user process (not as a server), and will connect you to the Asterisk CLI. This option is good when you are debugging your startup parameters, but should not be used for a normal system (if Asterisk is already running, this option will not work and will issue a complaint).

-v

Verbosity. This is used to set the amount of output for CLI debugging. The more “v”s, the more verbose.

-g

Core dump. If Asterisk were to crash unexpectedly, this would cause a core file to be created for later tracing with gdb. You generally do not use this in production, unless you are writing code for Asterisk and want to debug any resulting crashes.

-r

Remote. This is used to reconnect remotely to an already running Asterisk process. (The process is remote from the standpoint of the console connecting to it but is actually a local process on the machine. This has nothing to do with connecting to a remote process over a network using a protocol such as IP, as this is not supported.) This is the most common option and it is what you would use to connect to Asterisk on a system where it is running as a daemon/service that was started by init at boot time.

-x "<CLI command>"

Execute. Using this command in combination with -r allows you to execute a CLI command without having to connect to the CLI and type it manually. An example would be to send a restart, which you would do by typing asterisk -rx "reload" from the command line.

Let’s look at some examples. If you want to start Asterisk as a user program (because you are tweaking your config and will be starting and stopping it several times), and you want a verbosity level of 3, use the following command:

# /usr/sbin/asterisk -cvvv      

If the Asterisk process is already running (for example, if you have installed Asterisk as part of the init process of the system), use the reconnect switch, like so:

# /usr/sbin/asterisk -vvvr    

If you want Asterisk to dump a core file after a crash, you can use the -g switch when starting Asterisk:

# /usr/sbin/asterisk -g       

To execute a command without connecting to the CLI and typing it (perhaps for use within a script), you can use the -x switch in combination with the -r switch:

# /usr/sbin/asterisk -rx "restart now"
# /usr/sbin/asterisk -rx "database show"
# /usr/sbin/asterisk -rx "sip show peers"        

If you are experiencing crashes and would like to output to a debug file, use the following command:

# /usr/sbin/asterisk -vvvvc | tee /tmp/debug.log     

Note that you do not have to use the v switch if you do not want the system to provide detailed output of what is going on. On a busy system, you may not want to get any output, as it can interfere with whatever you are doing on the console.

Directories Used by Asterisk

Asterisk uses several directories on a Linux system to manage the various aspects of the system, such as voicemail recordings, voice prompts, and configuration files. This section discusses the necessary directories, all of which are created during installation and configured in the asterisk.conf file.

/etc/asterisk/

The /etc/asterisk/ directory contains the Asterisk configuration files. One file, however—zaptel.conf—is located in the /etc/ directory. The Zaptel hardware was originally designed by Jim Dixon of the Zapata Telephony Group as a way of bringing reasonable and affordable computer telephony equipment to the world. Asterisk makes use of this hardware, but any other software can also make use of the Zaptel hardware and drivers. Consequently, the zaptel.conf configuration file is not directly located in the /etc/asterisk/directory.

/usr/lib/asterisk/modules/

The /usr/lib/asterisk/modules/ directory contains all of the Asterisk loadable modules. Within this directory are the various applications, codecs, formats, and channels used by Asterisk. By default, Asterisk loads all of these modules at startup. You can disable any modules you are not using in the modules.conf file, but be aware that certain modules are required by Asterisk or are dependencies of other modules. Attempting to load Asterisk without these modules will cause an error at startup.

/var/lib/asterisk

The /var/lib/asterisk/ directory contains the astdb file and a number of subdirectories. The astdb file contains the local Asterisk database information, which is somewhat like the Microsoft Windows Registry. The Asterisk database is a simple implementation based on v1 of the Berkeley database. The db.c file in the Asterisk source states that this version was chosen for the following reason: “DB3 implementation is released under an alternative license incompatible with the GPL. Thus, in order to keep Asterisk licensing simplistic, it was decided to use version 1 as it is released under the BSD license.”

The subdirectories within /var/lib/asterisk/ include:

agi-bin/

The agi-bin/ directory contains your custom scripts, which can interface with Asterisk via the various built-in AGI applications. For more information about AGI, see Chapter 8, Protocols for VoIP.

firmware/

The firmware/ directory contains firmware for various Asterisk-compatible devices. It currently contains only the iax/ subdirectory, which holds the binary firmware image for Digium’s IAXy.

images/

Applications that communicate with channels supporting graphical images look in the images/ directory. Most channels do not support the transmission of images, so this directory is rarely used. However, if more devices that support and make use of graphical images are released, this directory will become more relevant.

keys/

Asterisk can use a public/private key system to authenticate peers connecting to your box via an RSA digital signature. If you place a peer’s public key in your keys/ directory, that peer can be authenticated by channels supporting this method (such as the IAX2 channels). The private key is never distributed to the public. The reverse is also true: you can distribute your public key to your peers, allowing you to be authenticated with the use of your private key. Both the public and private keys—ending in the .pub and .key file extensions, respectively—are stored in the keys/ directory.

mohmp3/

When you configure Asterisk for Music on Hold, applications utilizing this feature look for their MP3 files in the mohmp3/ directory. Asterisk is a bit picky about how the MP3 files are formatted, so you should use constant bitrate (CBR) encoding and strip the ID3 tags from your files.

sounds/

All of the available voice prompts for Asterisk reside in the sounds/ directory. The contents of the basic prompts included with Asterisk are in the sounds.txt file located in your Asterisk source code directory. Contents of the additional prompts are located in the sounds-extra.txt file in the directory to which you extracted the asterisk-sounds package earlier in this chapter.

/var/spool/asterisk/

The Asterisk spool directory contains several subdirectories, including dictate/, meetme/, monitor/, outgoing/, system/, tmp/, and voicemail/ (see Figure 3.4, “/var/spool/asterisk/ directory structure”). Asterisk monitors the outgoing directory for text files containing call request information. These files allow you to generate a call simply by moving the correctly structured file into the outgoing/ directory.

Figure 3.4. /var/spool/asterisk/ directory structure

/var/spool/asterisk/ directory structure

Call files being placed into the outgoing/ directory can contain useful information, such as the Context, Extension, and Priority where the answered call should start, or simply the application and its arguments. You can also set variables and specify an account code for Call Detail Records. More information about the use of call files is presented in Chapter 9, The Asterisk Gateway Interface (AGI).

The dictate/ directory is the default location where the Dictate() application looks for files.

The meetme/ directory is the location where MeetMe() conference recordings are saved.

Recordings from either one-touch recording (the w and W flags to the Dial() application), the MixMonitor(), or Monitor() applications are stored in the monitor/ directory.

system/ is used by the System() application for temporary storage of data.

The tmp/ directory is used, funny enough, to hold temporary information. Certain applications may require a place to write files to before copying the complete files to their final destinations. This prevents two processes from trying to write to and read from a file at the same time.

All voicemail and user greetings are contained within the voicemail/ directory. Extensions configured in voicemail.conf that have been logged in to at least once are created as subdirectories of voicemail/.

/var/run/

The /var/run/ directory contains the process ID (PID) information for all active processes on the system, including Asterisk (as specified in the asterisk.conf file). Note that /var/run/ is OS-dependent and may differ.

/var/log/asterisk/

The /var/log/asterisk/ directory is where Asterisk logs information. You can control the type of information being logged to the various files by editing the logger.conf file located in the /etc/asterisk/ directory. Basic configuration of the logger.conf file is covered in Appendix D, Configuration Files.

/var/log/asterisk/cdr-csv

The /var/log/asterisk/cdr-csv directory is used to store the CDRs in comma-separated value (CSV) format. By default information is stored in the Master.csv file, but individual accounts can store their own CDRs in separate files with the use of the accountcode option (see Appendix A, VoIP Channels for more information).

AsteriskNOW

In the following sections we will provide a gentle introduction to the AsteriskNOW software, which gives you a complete PBX system with graphical configuration screen all built into one!

What Is AsteriskNOW?

AsteriskNOW is an open source software appliance, a customized Linux distribution that includes Asterisk, the Asterisk GUI, and all other software needed for an Asterisk system. The Asterisk GUI gives you the ability to easily configure your Asterisk system without being a technical expert.

Note: The complete software appliance distribution is provided under the GPL and may legally be used for any purpose, commercial or otherwise.

Before You Begin

AsteriskNOW installation is easy, because the appliance includes only those components necessary to run, debug, and build Asterisk. You no longer have to worry about kernel versions and package dependencies. AsteriskNOW is a custom Linux distribution for Asterisk based on rPath Linux.

What You Will Need

  • A system on which you can install AsteriskNOW

  • A CD writer and associated software

  • Connection to the Internet

  • Firefox browser

Note

The Asterisk GUI currently requires the Firefox browser (available at http://www.mozilla.com/en-US/ for optimum performance. Wider browser support will be available with future versions.

Installation

You should observe all normal precautions when preparing and installing a new distribution. Any existing operating systems on your hard drive will be removed by the Express Installation. If you are not sure that you are ready to alter your system, try one of the alternate installations (discussed in the section called “Alternate Installations””) to give AsteriskNOW a try. For more help on Asterisk and rPath see the the section called “For More Information”” section at the end of the chapter.

Quick installation

The essential installation of AsteriskNOW is really quite simple and gives you the ability to get up and running in a short amount of time. Use this quick installation procedure if you are comfortable with accepting the defaults. Any help you may need is provided with the installation screens. If you would like more information on the installation procedure, refer to the the section called “Extended procedure”” section below:

  1. Download the AsteriskNOW ISO file (http://www.asterisknow.org/downloads) and create a CD image from the file. This step is required before installation can begin. The process for creating a CD image will vary depending upon the CD authoring software you are using.

  2. Insert your newly created AsteriskNOW CD into the CD-ROM drive of the PC.

  3. Boot from the CD by restarting the PC. A basic AsteriskNOW boot menu with several options will be provided:

    • To install or upgrade in graphical mode, press Enter.

    • To install or upgrade in Linux text mode, type linux text and then press Enter.

    The recommended, and default, installation mode is graphical. If you do not make an entry, the installation will continue in graphical mode.

  4. From here, follow the self-explanatory, onscreen prompts to guide you through the installation process.

  5. When installation is complete, the system will prompt you to reboot. After rebooting, a URL to access the Asterisk GUI will be displayed.

  6. You are now ready to configure and run AsteriskNOW.

Extended procedure

  1. Download the AsteriskNOW ISO file (http://www.asterisknow.org/downloads) and create a CD image from the file. This step is required before installation can begin. The process for creating a CD image will vary depending upon the CD authoring software you are using.

  2. Insert your newly created AsteriskNOW CD into the CD-ROM drive.

  3. Boot from the CD by restarting the PC. A basic AsteriskNOW boot menu with several options will be provided:

    • To install or upgrade in graphical mode, press Enter.

    • To install or upgrade in Linux text mode, type linux text and then press Enter.

    The recommended, and default, installation mode is graphical. If you do not make an entry, the installation will continue in graphical mode.

    After a bit of processing, the initial installation screen is displayed. The initial screen is similar to the following illustration:

  4. From the initial installation screen you can read the release notes or the Help information. When you are ready, click Next to continue the installation.

    The next installation screen lets you choose the type of installation. The two modes of installation available are:

    Express Installation

    The Express Installation installs all of the software needed to install Asterisk. Debugging and development tools are installed with this installation type.

    Expert

    Select this installation type if you want to have complete control over all installation options. Among the options you can control are software package selection, partitioning, and language selection.

    The default installation type is Express Installation. This installation type assumes an English language reader and that you aren’t concerned with the finer points. Choose Expert if you don’t read English, and/or want more control over the installation details. For the purposes of this procedure, Express Installation is discussed.

  5. Choose your installation type and then click Next.

    The Automatic Partitioning screen is displayed. The Automatic Partitioning screen gives you several options to choose from before the software partitions your drive. This gives you the opportunity to choose which data (if any) is removed from your system, and how the drive is partitioned. The following options are available:

    Remove All Linux Partitions

    This option will only remove any Linux partitions created from a previous Linux installation.

    Remove All Partitions

    Select this option if you want to remove all partitions on your system, including those created by other operating systems (such as Windows).

    Keep All Partitions

    You should choose this option if you want to retain all of your current data and partitions. You will need enough hard drive space for your Asterisk implementation. Twenty GB is a realistic minimum, but the minimum space is dependent on the needs of the system you want to create.

    In most cases, you will want to choose Remove All Partitions. A hard drive dedicated to your Asterisk implementation is the best way to ensure maximum performance. Select the Review checkbox on the Automatic Partitioning screen if you want to review or modify your partition selections.

  6. A list of the hard drives available for use is listed on the Automatic Partitioning screen. Select the checkbox next to the hard drive(s) you want to use for your system. Click Next to continue with the installation.

    • If you selected Remove All Partitions or Remove All Linux Partitions, a warning dialog will be displayed that asks if you want to proceed. Click Yes to proceed, or No to change your partition selection.

    • If you selected Review on the Automatic Partitioning screen, a screen will be displayed with the partitions created. You can modify your partitions on this screen. To proceed, click Next.

  7. The Network Configuration screen is displayed.

    • You can configure the network devices associated with your system on the Network Configuration screen. Any network devices attached to your system are automatically detected by the installation program and displayed in the Network Devices list. You can either accept the device(s) automatically selected by the installation program, or you can edit them by selecting Edit.

    • Set the Hostname by either selecting Automatically via DHCP, or by selecting Manually and enter the hostname for your system. Once you have specified the hostname, click Next to proceed.

  8. The Time Zone Selection screen is displayed.

    • The Time Zone Selection screen offers several ways for you to select the time zone appropriate for your installation. You can either use the world map, which displays major cities, select from a list of locations and time zones, or select the System Clock Uses UTC to use the system time. Once you have selected a time zone, click Next.

  9. The Administrator Password screen is displayed.

    • You must set a password for the AsteriskNOW administrator account, “admin”. This password will be used to log on to the system, as well as the Asterisk GUI. Set and confirm an administrator password, and then click Next to proceed.

    • The About to Install screen is displayed, giving you an opportunity to delay or abort the installation process. If you are ready to continue with the installation, click Next.

  10. The Installing Packages screen is displayed.

    • While AsteriskNOW is being installed, the Installing Packages screen will be displayed. The installation will continue for a few minutes.

    • Once the installation is complete, the system will prompt you to reboot. Remove the installation disk you created, and click Reboot. After rebooting, a URL to access the Asterisk GUI will be displayed.

Accessing the GUI

Once you have completed your installation and rebooted your machine, you will be able to access the Asterisk GUI. The URL used to access the Asterisk GUI is the IP address or hostname displayed after rebooting your machine. Enter this IP address in your browser URL. You will be able to refine your AsteriskNOW installation by accessing the Asterisk GUI.

Alternate Installations

You can also try out AsteriskNOW using the available VMware Player image (http://www.vmware.com/download/player/), Xen universal guest domain image (http://wiki.rpath.com/wiki/Xen_Solutions_Using_rPath_Technologies) or the LiveCD (just burn and boot). All alternate installations can be downloaded from the AsteriskNOW download page.

Note: When using the LiveCD, the default username is “admin” with “password” as the password.

For More Information

An AsteriskNOW Users’ Guide is currently under development by the Asterisk community on the Asterisk Forums. For additional information on AsteriskNOW, including step-by-step installation screenshots and configuration screenshots showing the setup wizard, please refer to http://www.asterisknow.org, and visit the Asterisk Forums at http://forums.digium.com. For more information and help with rPath Linux, please see rPath’s wiki, http://wiki.rpath.com.

Conclusion

In this chapter, we have reviewed the procedures for obtaining, compiling, and installing Asterisk and the associated packages. In the following chapter, we will touch on the initial configuration of your system with regard to various communications channels, such as analog devices attached to FXS and FXO ports, SIP channels, and IAX2 endpoints.



[42] And some non-Linux operating systems as well, such as Solaris, *BSD, and OS X. You should note that while people have managed to successfully run Asterisk on these alternative systems, Asterisk was, and continues to be, actively developed for Linux.

[43] We will be using CentOS Server 4.4 in this book, which we usually install with nothing except the Editors package selected. If you are not sure what distribution to choose, CentOS is an excellent choice. CentOS can be obtained from http://www.centos.org.

[44] Subversion is an excellent code management system, available at http://subversion.tigris.org/. It also has an equally excellent Creative Commons released book, Version Control with Subversion, by Ben Collins Sussman et al. (O’Reilly), available online at http://svnbook.red-bean.com/.

[45] As of the release date of this book, there has been no determination that the next Asterisk release will be 1.6. It could just as easily be 2.0. Therefore, when discussing new features, you’ll see us talk about what’s in Trunk or what will be in the next release—without mentioning the specific version.

[46] Note that this is configurable in the kernel, so it is possible certain distributions may not have this set to 1,000 Hz; CentOS, however, does have this set at the correct frequency.

[47] Gentoo doesn’t actually use a precompiled binary, but rather pulls the source from a repository, and builds and installs the software using its own package management system. But the version you get is still dependant upon the maintainers packaging it for you, when you could simply build it yourself!

[48] l33t is a funny way of saying “elite,” known as leetspeak (computer slang). Even more funny is a well-written, serious article by Microsoft about leetspeak at http://www.microsoft.com/athome/security/children/leetspeak.mspx.

Chapter 4. Initial Configuration of Asterisk

I don’t always know what I’m talking about, but I know I’m right.

--Muhammad Ali

Completing all the steps in Chapter 3, Installing Asterisk should have left you with a working Asterisk system. If it did not, please take the time to go back and review the steps, consult the wiki, engage the community, and get your system running.

Unfortunately, we cannot yet make any calls, because we have not yet created any channels. To get this plane to fly, we’re going to need some runways. While there are dozens of different channel types, and dozens of different ways to configure each type of channel, we just want to get some calls happening, so let’s try and keep things simple. We have decided to guide you through the configuration of four channels: a Foreign eXchange Office (FXO) channel, a Foreign eXchange Station (FXS) channel, a Session Initiation Protocol (SIP) channel, and an Inter-Asterisk eXchange (IAX) channel.[49] We selected these channel types because they are far and away the most popular channel types in use in small Asterisk systems, and one of the goals of this book is to keep things as simple as is reasonable. If we cover the basics of these channels, we will not have done an exhaustive survey of all channel types or topologies, but we will have created a base platform on which to develop your telecommunications system. Further scenarios and channel configuration details can be found in Appendix D, Configuration Files.

Our first effort will be to explore the basic configuration of analog interfaces such as FXS and FXO ports with the use of a Digium TDM11B (which is an analog card with one FXS port and one FXO port).[50]

Next, we’ll tackle a few Voice over Internet Protocol (VoIP) interfaces: a local SIP and IAX2 channel connected to a softphone or hardphone, along with connecting two Asterisk boxes via these two popular protocols.

For SIP, we are going to cover Linksys, Polycom, Aastra, Grandstream, and Cisco sets. If we do not cover your phone model, we apologize, but what is important to realize is that while most of these devices have many different parameters that you can define, generally only a few parameters need to be defined in order to get the device to work. That will be our goal, because we figure it’s a lot less frustrating to tweak a functioning device than to get it perfectly set up on the first try. We won’t discuss all the features you may want your channel to have (such as caller ID or advanced codec and security settings), but you will be able to make and receive calls with your phone, which should put a smile on your face—a good state to be in as we dig deeper into things.

Once you’ve worked through this chapter, you will have a basic system consisting of many useful interfaces, which will provide the foundation we need to explore the extensions.conf file (discussed in detail in Chapter 5, Dialplan Basics), where the dialplan is stored (technically, it contains the instructions Asterisk needs to build the dialplan). If you do not have access to the analog hardware, some of the examples will not be available to you, but you will still have configured a system suitable for a pure-VoIP environment.

What Do I Really Need?

The asterisk character (*) is used as a wildcard in many different applications. It is a good name for this PBX for many reasons, one of which is the enormous number of interface types to which Asterisk can connect. These include:

  • Analog interfaces, such as your telephone line and analog telephones

  • Digital circuits, such as T1 and E1 lines

  • VoIP protocols such as SIP and IAX[51]

Asterisk doesn’t need any specialized hardware—not even a sound card—even though it is common to expect a telephone system to physically connect to a voice network. There are many types of channel cards that allow you to connect your Asterisk to things like analog phones or PSTN circuits, but they are not essential to the functioning of Asterisk. On the user (or station) side of the system, you can choose from all kinds of softphones that are available for Windows, Linux, and other operating systems—or use almost any physical IP phone. That handles the telephone side of the system. On the carrier side, if you don’t connect directly to a circuit from your central office, you can still route your calls over the Internet using a VoIP service provider.

Working with Interface Configuration Files

In this chapter, we’re going to build an Asterisk configuration on the platform we have just installed. For the first few sections on FXO and FXS channels, we’ll assume that you have a Digium TDM11B kit (which comes with one FXO and one FXS interface). This will allow you to connect to an analog circuit (FXO) and to an analog telephone (FXS). Note that this hardware interface isn’t necessary; if you want to build an IP-only configuration, you can skip to the section on configuring SIP.

The configuration we do in this chapter won’t be particularly useful on its own, but it will be a kernel to build on. We’re going to touch on the following files:

zaptel.conf

Here, we’ll do low-level configuration for the hardware interface. We’ll set up one FXO channel and one FXS channel. This configures the driver for the Linux kernel.

zapata.conf

In this file, we’ll configure Asterisk’s interface to the hardware. This file contains a slightly higher-level configuration of the hardware in the Asterisk user-level process.

extensions.conf

The dialplans we create will be extremely primitive, but they will prove that the system is working.

sip.conf

This is where we’ll configure the SIP protocol.

iax.conf

This is where we’ll configure incoming and outgoing IAX channels.

In the following sections, you will be editing several configuration files. You’ll have to reload these files for your changes to take effect. After you edit the zaptel.conf file, you will need to reload the configuration for the hardware with /sbin/ztcfg -vv (you may omit the -vv if you don’t need verbose output). Changes made in zapata.conf will require a module reload from the Asterisk console; however, changing signaling methods requires a restart. You will need to perform an iax2 reload and a sip reload after editing the iax.conf and sip.conf files, respectively.

In order to test the new devices we have defined, we must have a dialplan through which we can make connections. Even though we have not discussed the Asterisk dialplan (that’s coming up in the next chapter), we want you to create a basic extensions.conf file so that we can test our work in this chapter.

Make a backup copy of the sample extensions.conf (try the bash command mv extensions.conf extensions.conf.sample), and then create a blank extensions.conf file (using the bash command touch extensions.conf), and insert the following lines:

[globals]

[general]
autofallthrough=yes

[default]

[incoming_calls]

[internal]

[phones]
include => internal

Note

In the [general] section, we have set autofallthrough=yes, which tells Asterisk to continue when an extension runs out of things to do. If you set this to no, then Asterisk will sit and wait for input after all priorities have executed. This is most prevalent if the Background() application is the last application executed in an extension. If set to yes (which is now the default in 1.4), Asterisk will drop the call after Background() finishes executing (at the end of the prompt(s) supplied to it). In order to force Asterisk to wait for input after the Background() application finishes playing the voice prompts supplied to it, we use the WaitExten() application.

Do not be afraid if what we’ve just written doesn’t make a whole lot of sense, as we haven’t explored the dialplan, applications, priorities, or extensions yet (that is coming up in the next chapter). So for now, just set autofallthrough=yes. It is safest to use the autofallthrough=yes command as we don’t want Asterisk hanging around waiting for input unless we explicitly tell it to do so.

There is nothing else for now, but we’ll be using this file as we go through this chapter to build a test dialplan so we can ensure that all of our devices are working. Also, be sure to run the dialplan reload command from the Asterisk CLI to update to the latest changes. Verify your changes by running the CLI command dialplan show:

*CLI> dialplan show
[ Context 'phones' created by 'pbx_config' ]
  Include =>        'internal'                                    [pbx_config]

[ Context 'internal' created by 'pbx_config' ]

[ Context 'incoming_calls' created by 'pbx_config' ]

[ Context 'default' created by 'pbx_config' ]

[ Context 'parkedcalls' created by 'res_features' ]
  '700' =>          1. Park((null))                               [res_features]

-= 1 extension (1 priority) in 5 contexts. =-

Note

You will see the parkedcalls context because it is an internal context to Asterisk, specified in the features.conf file.

Setting Up the Dialplan for Some Test Calls

Now let’s expand upon the test dialplan we started in the previous section, allowing us to dial back into the softphone after we have configured it and to use a dialplan application called Echo() that will allow us to test bidirectional audio. We’ll learn more about dialplans in Chapter 5, so for now, just add the italicized bits to your existing extensions.conf file. We’ll be making use of this dialplan throughout the chapter, and expanding on it in certain sections. Once you’ve entered the text into extensions.conf, reload the dialplan by running dialplan reload from the Asterisk console:

[globals]

[general]

[default]
exten => s,1,Verbose(1|Unrouted call handler)
exten => s,n,Answer()
exten => s,n,Wait(1)
exten => s,n,Playback(tt-weasels)
exten => s,n,Hangup()

[incoming_calls]

[internal]
exten => 500,1,Verbose(1|Echo test application)
exten => 500,n,Echo()
exten => 500,n,Hangup()

[phones]
include => internal

FXO and FXS Channels

The difference between an FXO channel and an FXS channel is simply which end of the connection provides the dial tone. An FXO port does not generate a dial tone; it accepts one. A common example is the dial tone provided by your phone company. An FXS port provides both the dial tone and ringing voltage to alert the station user of an inbound call. Both interfaces provide bidirectional communication (i.e., communication that is transmitted and received in both directions simultaneously).[52]

If your Asterisk server has a compatible FXO port, you can plug a telephone line from your telephone company (or “telco”) into this port. Asterisk can then use the telco line to place and receive telephone calls. By the same token, if your Asterisk server has a compatible FXS port, you may plug an analog telephone into your Asterisk server, so that Asterisk may call the phone and you may place calls.

Ports are defined in the configuration by the signaling they use, as opposed to the physical type of port they are. For instance, a physical FXO port will be defined in the configuration with FXS signaling, and an FXS port will be defined with FXO signaling. This can be confusing until you understand the reasons for it. FX_ cards are named not according to what they are, but rather according to what is connected to them. An FXS card, therefore, is a card that connects to a station. Since that is so, you can see that in order to do its job, an FXS card must behave like a central office and use FXO signaling. Similarly, an FXO card connects to a central office (CO), which means it will need to behave like a station and use FXS signaling. The modem in your computer is a classic example of an FXO device.

Warning

The older Digium X100P card used a Motorola chipset, and the X101P (which Digium sold before completely switching to the TDM400P) is based on the Ambient/Intel MD3200 chipset. These cards are modems with drivers adapted to utilize the card as a single FXO device (the telephone interface cannot be used as an FXS port). Support for the X101P card has been dropped in favor of the TDM series of cards.

These cards (or their clones) SHOULD NOT be used in production environments. They are $10 on eBay for a reason.

The X100P/X101P cards are poor cards for production use due to their tendency to introduce echo into your telephone calls, and their lack of remote disconnect supervision. Do yourself a favor and don’t waste your time with this hardware. You will find that if you ask the community for support of these cards, many responses will be hostile. You have been warned.

Determining the FXO and FXS Ports on Your TDM400P

Figure 4.1, “A TDM400P with an FXS module (1 across) and an FXO module (2 across)” contains a picture of a TDM400P with an FXS module and an FXO module. You can’t see the colors, but module 1 is a green FXS module, and module 2 is an orange-red FXO module. In the bottom-right corner of the picture is the Molex connector, where power is supplied from the computer’s power supply.

Figure 4.1. A TDM400P with an FXS module (1 across) and an FXO module (2 across)

A TDM400P with an FXS module (1 across) and an FXO module (2 across)

Warning

Plugging an FXS port (the green module) into the PSTN may destroy the module and the card due to voltage being introduced into a system that wants to produce voltage, not receive it!

Tip

Be sure to connect your computer’s power supply to the Molex connector on the TDM400P if you have FXS modules, as it is used to supply the voltage needed to drive the ring generator on the FXS ports. The Molex connector is not required if you have only FXO modules.

Configuring an FXO Channel for a PSTN Connection

We’ll start by configuring an FXO channel. First we’ll configure the Zaptel hardware, and then the Zapata hardware. We’ll set up a very basic dialplan, and we’ll show you how to test the channel.

Zaptel Hardware Configuration

The zaptel.conf file located in /etc/ is used to configure your hardware. The following minimal configuration defines an FXO port with FXS signaling:

fxsks=2
loadzone=us
defaultzone=us

In the first line, in addition to indicating whether we are using FXO or FXS signaling, we specify one of the following protocols for channel 2:

  • Loop start (ls)

  • Ground start (gs)

  • Kewlstart (ks)

The difference between loop start and ground start has to do with how the equipment requests a dial tone: a ground-start circuit signals the far end that it wants a dial tone by momentarily grounding one of the leads; a loop-start circuit uses a short to request a dial tone. Though not common for new installations, analog ground start lines still exist in many areas of the country.[53] Ground start is really a rather strange thing, because it doesn’t exist in its analog form in Asterisk, so technically, there is no ground signal happening, but is rather a signaling bit that is intended for analog circuitry that historically would have been at the end of the T1. If this does not make much sense, don’t sweat it; chances are you won’t have to worry about ground-start signaling. All home lines (and analog telephones/modems/faxes) in North America use loop-start signaling. Kewlstart is in fact the same as loop start, except that it has greater intelligence and is thus better able to detect far-end disconnects.[54] Kewlstart is the preferred signaling protocol for analog circuits in Asterisk.

To configure a signaling method other than kewlstart, replace the ks in fxsks with either ls or gs (for loop start or ground start, respectively).

loadzone configures the set of indications (as configured in zonedata.c) to use for the channel. The zonedata.c file contains information about all of the various sounds that a phone system makes in a particular country: dial tone, ringing cycles, busy tone, and so on. When you apply a loaded tone zone to a Zap channel, that channel will mimic the indications for the specified country. Different indication sets can be configured for different channels. The defaultzone is used if no zone is specified for a channel.

After configuring zaptel.conf, you can load the drivers for the card. modprobe is used to load modules for use by the Linux kernel. For example, to load the wctdm driver, you would run:

# modprobe wctdm         

If the drivers load without any output, they have loaded successfully.[55] You can verify that the hardware and ports were loaded and configured correctly with the use of the ztcfg program:

# /sbin/ztcfg -vv         

The channels that are configured and the signaling method being used will be displayed. For example, a TDM400P with one FXO module has the following output:

Zaptel Configuration
======================
Channel map:
Channel 02: FXS Kewlstart (Default) (Slaves: 02)
1 channels configured.

If you receive the following error, you have configured the channel for the wrong signaling method (or there is no hardware present at that address):

ZT_CHANCONFIG failed on channel 2: Invalid argument (22)
Did you forget that FXS interfaces are configured with FXO signaling
and that FXO interfaces use FXS signaling?

To unload drivers from memory, use the rmmod (remove module) command, like so:

# rmmod wctdm         

The zttool program is a diagnostic tool used to determine the state of your hardware. After running it, you will be presented with a menu of all installed hardware. You can then select the hardware and view the current state. A state of “OK” means the hardware is successfully loaded:

Alarms          Span
OK              Wildcard TDM400P REV E/F Board 1

Zapata Hardware Configuration

Asterisk uses the zapata.conf file to determine the settings and configuration for telephony hardware installed in the system. The zapata.conf file also controls the various features and functionality associated with the hardware channels, such as Caller ID, call waiting, echo cancellation, and a myriad of other options.

When you configure zaptel.conf and load the modules, Asterisk is not aware of anything you’ve configured. The hardware doesn’t have to be used by Asterisk; it could very well be used by another piece of software that interfaces with the Zaptel modules. You tell Asterisk about the hardware and control the associated features via zapata.conf:

[trunkgroups]
; define any trunk groups

[channels]
; hardware channels 
 

; default
usecallerid=yes
hidecallerid=no
callwaiting=no
threewaycalling=yes
transfer=yes
echocancel=yes
echotraining=yes

; define channels
context=incoming        ; Incoming calls go to [incoming] in extensions.conf
signaling=fxs_ks       ; Use FXS signaling for an FXO channel
channel => 2            ; PSTN attached to port 2

The [trunkgroups] section is used for connections where multiple physical lines are used as a single logical connection to the telephone network, and won’t be discussed further in this book. If you require this type of functionality, see the zapata.conf.sample file and your favorite search engine for more information.

The [channels] section determines the signaling method for hardware channels and their options. Once an option is defined, it is inherited down through the rest of the file. A channel is defined using channel =>, and each channel definition inherits all of the options defined above that line. If you wish to configure different options for different channels, remember that the options should be configured before the channel => definition.

We’ve enabled Caller ID with usecallerid=yes and specified that it will not be hidden for outgoing calls with hidecallerid=no. Call waiting is deactivated on an FXO line with callwaiting=no. Enabling three-way calling with threewaycalling=yes allows an active call to be placed on hold with a hook switch flash (discussed in Chapter 7, Understanding Telephony) to suspend the current call. You may then dial a third party and join them to the conversation with another hook switch. The default is to not enable three-way calling.

Allowing call transfer with a hook switch is accomplished by configuring transfer=yes; it requires that three-way calling be enabled. The Asterisk echo canceller is used to remove the echo that can be created on analog lines. You can enable the echo canceller with echocancel=yes. The echo canceller in Asterisk requires some time to learn the echo, but you can speed this up by enabling echo training (echotraining=yes). This tells Asterisk to send a tone down the line at the start of a call to measure the echo, and therefore learn it more quickly.

When a call comes in on an FXO interface, you will want to perform some action. The action to be performed is configured inside a block of instructions called a context. Incoming calls on the FXO interface are directed to the incoming context with context=incoming. The instructions to perform inside the context are defined within extensions.conf.

Finally, since an FXO channel uses FXS signaling, we define it as such with signaling=fxs_ks.

Dialplan Configuration

The following minimal dialplan makes use of the Echo() application to verify that bidirectional communications for the channel are working:

[incoming]
; incoming calls from the FXO port are directed to this context 
;from zapata.conf
exten => s,1,Answer()
exten => s,n,Echo()

Whatever you say, the Echo() application will relay back to you.

Dialing In

Now that the FXO channel is configured, let’s test it. Run the zttool application and connect your PSTN line to the FXO port on your TDM400P. Once you have a phone line connected to your FXO port, you can watch the card come out of a RED alarm.

Now dial the PSTN number from another external phone (such as a cell phone). Asterisk will answer the call and execute the Echo() application. If you can hear your voice being reflected back, you have successfully installed and configured your FXO channel.

Configuring an FXS Channel for an Analog Telephone

The configuration of an FXS channel is similar to that of an FXO channel. Let’s take a look.

Zaptel Hardware Configuration

The following is a minimal configuration for an FXS channel on a TDM400P. The configuration is identical to the FXO channel configuration above, with the addition of fxoks=1.

Recall from our earlier discussion that the opposite type of signaling is used for FXO and FXS channels, so we will be configuring FXO signaling for our FXS channel. In the example below we are configuring channel 1 to use FXO signaling, with the kewlstart signaling protocol:

fxoks=1
fxsks=2
loadzone=us
defaultzone=us

After loading the drivers for your hardware, you can verify their state with the use of /sbin/ztcfg -vv:

Zaptel Configuration
======================

Channel map:

Channel 01: FXO Kewlstart (Default) (Slaves: 01)
Channel 02: FXS Kewlstart (Default) (Slaves: 02)

2 channels configured.

Zapata Hardware Configuration

The following configuration is identical to that for the FXO channel, with the addition of a section for our FXS port and, of the line immediate=no. The context for our FXS port is phones, the signaling is fxoks (kewlstart), and the channel number is set to 1.

FXS channels can be configured to perform one of two different actions when a phone is taken off the hook. The most common (and often expected) option is for Asterisk to produce a dial tone and wait for input from the user. This action is configured with immediate=no. The alternative action is for Asterisk to automatically perform a set of instructions configured in the dialplan instead of producing a dial tone, which you indicate by configuring immediate=yes.[56] The instructions to be performed are found in the context configured for the channel and will match the s extension (both of these topics will be discussed further in the following chapter).

Here’s our new zapata.conf:

[trunkgroups]
; define any trunk groups

[channels]
; hardware channels
; default
usecallerid=yes
hidecallerid=no
callwaiting=no
threewaycalling=yes
transfer=yes
echocancel=yes
echotraining=yes
immediate=no

; define channels
context=phones       ; Uses the [internal] context in extensions.conf
signalling=fxo_ks       ; Uses FXO signalling for an FXS channel 
 

channel => 1           ; Telephone attached to port 1

context=incoming       ; Incoming calls go to [incoming] in extensions.conf
signalling=fxs_ks       ; Use FXS signalling for an FXO channel
channel => 2           ; PSTN attached to port 2

Dialplan Configuration

We will make use of our minimal dialplan we configured earlier in the chapter to test our FXS port with the use of the Echo() application. The relevant section, which should already exist in your dialplan, looks like this:

[internal]
exten => 500,1,Verbose(1|Echo test application)
exten => 500,n,Echo()
exten => 500,n,Hangup()

[phones]
include => internal

Whatever you say, the Echo() application will relay back to you.

Configuring SIP Telephones

The Session Initiation Protocol (SIP),[57] commonly used in VoIP phones (either hard phones, or softphones), takes care of the setup and teardown of calls, along with any changes during a call such as call transfers. The purpose of SIP is to help two endpoints talk to each other (if possible, directly to each other). The SIP protocol is simply a signaling protocol, which means that its purpose is only to get the two endpoints talking to each other, and not to deal with the media of the call (your voice). Rather, your voice is carried using another protocol called the Real-Time Transport Protocol (RTP; RFC 3550) to transfer media directly between the two endpoints.

Note

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.

In the world of SIP, we call our endpoints user agents, of which there are two types: client and server. The client is the endpoint that generates the request, and the server processes the request and generates a response. When an endpoint wishes to place a call to another endpoint (such as our softphone calling another softphone), we generate our request and send this to a SIP proxy.[58] A proxy server will take the request, determine where the request is destined for, and forward it on. Once the two user agents have negotiated a successful call setup, the media is transported via the RTP protocol and sent directly between the two user agents. SIP proxies do not handle media; they simply deal with the SIP packets.

Asterisk, on the other hand, is called a Back-To-Back User Agent (B2BUA). This means that Asterisk acts like a user agent in either the server (receiving) or client (sending) role. So when our softphone dials an extension number, the call is set up between the softphone and Asterisk directly. If the logic we’ve built into Asterisk determines that you mean to call another user agent, then Asterisk acts as a user agent client and sets up another connection (known as a channel) to the other phone. The media between the two phones then flows directly through Asterisk.[59] From the viewpoint of the phones, they are talking with Asterisk directly.

Basic SIP Telephone Configuration in Asterisk

Configuring a SIP phone to work with Asterisk does not require much. However, because there are so many options possible in both Asterisk and the configuration of the particular telephone set or softphone, things can get confusing. Add to this the fact that similar things can have different names, and you have a recipe for frustration. What we are going to do, therefore, is give you the bare-bones basics. If you follow our advice, you should be able to get the sets we cover working (and be well on your way to getting a phone that we have not covered to work as well). We are not saying that this is the best way, or even the right way, but it is the simplest way, and from a working foundation, it is much easier to take a basic configuration and tweak things until you get the solution you need.

Note

Just as we did with the extensions.conf file; run the following commands in your bash shell:

            # mv sip.conf sip.conf.sample
# touch sip.conf
          

Defining the SIP device in Asterisk

If you put the following in a sip.conf file, you will be able to register a phone to the system.

[general]

[1000]
type=friend
context=phones
host=dynamic

Not pretty, not secure, not flexible, not fully-featured, but this will work.

Even though we have named this SIP device 1000, and we are probably going to assign it that extension number, you should note that we could have named it whatever we wanted. Names such as mysipset, john, 0004f201ab0c are all valid, popular, and may suit your needs better.[60] What we are doing is assigning a unique identifier to a device, which will form part of the credentials when a call is placed using the SIP channel.

Since we want to be able to both send calls to the softphone and allow the client to place calls, we have defined the type as friend. The other two types are user and peer. From the viewpoint of Asterisk, a user is configured to enter the dialplan, and a peer is created for calls leaving the dialplan (via the Dial() application). A friend is simply a shortcut that defines both a user and a peer. If in doubt, define the type as friend.

The host option is used to define where the client exists on the network when Asterisk needs to send a call to it. This can either be defined statically by defining something like host=192.168.1.100, or if the client has a dynamic IP address, then we set host=dynamic. When the host option is set as dynamic, and the client is configured to register, Asterisk will receive a REGISTER packet from the endpoint (i.e., telephone set or softphone), telling Asterisk which IP address the SIP peer is using.

If you do not trust your network, you should probably also force the use of a password by adding the following to the device definition. This is one of those things that is not technically necessary, but is probably a good idea:

secret=guessthis

Configuring the Device Itself

In the configuration menus of the phone itself (which could be via a web GUI, through menus on the phone itself, or possibly using configuration files that are stored on a server), the unique identifier (which in this case is 1000) again forms part of the credentials for the authentication process. Naturally, for a connection to be successful, this has to match in both Asterisk and in the set itself. The fun begins when you realize that there is no set rule as to what this identifier is formally called. We have elected simply to call it the Unique Identifier.

Note

In the SIP RFC (http://www.faqs.org/rfcs/rfc3261.html), section 19.1 calls this user token, “the identifier of a particular resource at the host being addressed,” verbiage consistent with our usage of [1000] as the set identifier in the sip.conf file of Asterisk.

Instead, you will want to look for fields that are labeled user name, auth name, authentication name, and so on. The thing to remember is that since you know that the Asterisk end of the equation is configured simply and correctly, you can experiment with the phone setting until you find a combination that works. This is much better than the usual suffering that new users go through, as they change settings in both places and have no luck getting a phone to register.

Note

We’re gonna say it again: configure sip.conf in the simplest manner possible, and then don’t change your Asterisk configuration. Trust us; what we have written here will work. Get your set working (i.e., where you can make and receive calls), and you will be in a far better position to begin experimenting with different settings. We have seen too much suffering (including our own), and we want it to end.

Note

If you are running Asterisk and a softphone on the same system (i.e., running an X-Lite softphone and Asterisk on a laptop or desktop), then you will need to modify the SIP port that client listens on. It will need to be changed from 5060 to 5061 (or some other unused port) so that Asterisk and the softphone do not interfere with each other.

Essential Server Components

Before we get into how to define these files, there are a few things that need to be configured on your server. Running the right services on your network will ensure your Polycom sets can autoconfigure from the moment you plug them in. There’s a little work involved here, but we promise that the payoff is worth it. Once you’ve done this a few times, it only really takes a few minutes on each new system, and going forward, it’ll save you a lot of mucking about with web interfaces. When you take your new Polycom phone out of the box, plug it into your network, watch it autoconfigure itself, and then successfully register with your Asterisk machine, you will know the sort of joy that only geeks can experience.[61]

It’s not really that complicated. Where we think people get confused is in making sense of the various ways this can be achieved, because there are a lot of choices.

DHCP server

Typically, a DHCP server is used to configure basic IP parameters for a device (IP address, default gateway, and DNS), but the DHCP protocol can actually pass many other parameters. In our case, we want it to pass some information to the sets that will tell them where to download their config files from. Here is a sample config from a Linux DHCP server that will do what is required:

ddns-update-style interim;
ignore client-updates;

subnet 192.168.1.0 netmask 255.255.255.0 {
 option routers 192.168.1.1;
 option subnet-mask 255.255.255.0;
 option domain-name-servers 192.168.1.1;
 option ntp-servers pool.ntp.org;
 option time-offset -18000;

range dynamic-bootp 192.168.1.128 192.168.1.254;
default-lease-time 21600;
max-lease-time 43200;
}

Keep in mind that this assumes that the only things on this network are devices that belong to the phone system (this setup will hand out an IP address to any device that requests it). If you have a more complex environment, you will need to configure the DHCP daemon to handle the various devices it is serving. For example, you might want to devise a scope that restricts IP addresses in your voice LAN to Polycom phones. Since all Polycom IP desk phones have 00:04:f2 as their OUI (Organizationally Unique Identifier), you might choose to restrict scope based on that.

Note

In a Microsoft DHCP environment, the tftp-server-name is referred to as Boot server host name. It is defined under option 66.

The DHCP protocol is far more flexible than is often realized, because in most environments it is not used for complex provisioning tasks. With a little care and attention, you can devise a DHCP environment that serves both your voice and data devices and greatly simplifies administrative workload when adding new devices.

FTP server

FTP is currently our favorite[62]way to configure Polycom sets. We would recommend it over TFTP for any set that allows for both. To install it on your CentOS system, the following command will install VSFTPD, the Very Secure FTP Daemon:

# yum -y install vsftpd

Then, in order to lock things down, we need to prevent anonymous logins with a simple change to the vsftpd config file, /etc/vsftpd/vsftpd.conf:

# anonymous_enable=NO

Restart the server with service vsftpd restart. To ensure that the daemon runs after every reboot, run chkconfig vsftpd on.

Now, we have to create a user account and group for the sets to use. In this case, we will create an account for the Polycom sets:

# groupadd PlcmSpIp
# useradd PlcmSpIp -g PlcmSpIp -p PlcmSpIp
# passwd PlcmSpIp

Set the password to PlcmSpIp (the default FTP password for Polycom sets). This can be changed, but will then require manual configuration from each set in order to advise them of their nonstandard credentials.[63]

For added security, let’s make sure the FTP server keeps that account in a chroot jail:

# echo PlcmSpIp >> /etc/vsftpd/vsftpd.chroot_list

That pretty much does it as far as preparing the operating system to provide the required services to the phones.

In the next few sections we have provided instructions for various popular SIP telephones. Choose the section that applies best to the phone that you are planning to use (whether a hard- or soft-phone). You will note that we have given all of these phones the exact same unique identifier. If you plan on installing more than one of them, you will need to ensure that they have unique names, and be sure to update your sip.conf file to include those device definitions.

CounterPath’s X-Lite Softphone

CounterPath’s X-Lite softphone has become very popular with the Asterisk community. It is simple, functional, easy on the eyes, and—most importantly—free.

In this section we will be configuring the X-Lite softphone to connect to Asterisk. The IP address of the phone is 192.168.1.250, and Asterisk is located at 192.168.1.100. The X-Lite is available for Microsoft Windows, Mac, and Linux. You can obtain a copy of X-Lite from http://www.counterpath.com/index.php?menu=download.

Now let’s configure our softphone for connecting to our Asterisk box. To configure X-Lite, click on the Settings button, as circled in Figure 4.2, “X-Lite configuration”.

Figure 4.2. X-Lite configuration

X-Lite configuration

Select System SettingsSIP Proxy[Default], which will display the default configuration for the softphone. Configure the screen as shown in Figure 4.3, “X-Lite user configuration”.

Figure 4.3. X-Lite user configuration

X-Lite user configuration

If you have not already started Asterisk, then start it now (see Chapter 3, Installing Asterisk for help installing and starting Asterisk). If Asterisk is running in the background, you can reconnect to the CLI by running the following command:

# asterisk -rvvv

You will then be given the Asterisk CLI like so:

*CLI>

If Asterisk was already running before changing the sip.conf as instructed in this chapter, then reload the dialplan and SIP channel with the following two commands:

*CLI> dialplan reload

*CLI> sip reload

In your X-Lite softphone client, close the Settings windows by clicking the BACK button until the windows are all closed. You should see X-Lite try to register to Asterisk, and if successful, you will see the following at the Asterisk CLI:

-- Registered SIP '1000' at 192.168.1.250 port 5061 expires 3600

You can verify the registration status at any time like so:

*CLI> sip show peers

Name/username              Host            Dyn Nat ACL Port     Status    
1000/1000                  192.168.1.250    D   N      5061    OK (63 ms)
1 sip peers [1 online , 0 offline]

More detailed stats of the peer can be shown as follows with sip show peer 1000:

*CLI> sip show peer 1000


  * Name       : 1000
  Secret       : <Not set>
  MD5Secret    : <Not set>
  Context      : phones
  Subscr.Cont. : <Not set>
  Language     : 
  AMA flags    : Unknown
  Transfer mode: open
  CallingPres  : Presentation Allowed, Not Screened
  Callgroup    : 
  Pickupgroup  : 
  Mailbox      : 
  VM Extension : asterisk
  LastMsgsSent : 32767/65535
  Call limit   : 0
  Dynamic      : Yes
  Callerid     : "" <>
  MaxCallBR    : 384 kbps
  Expire       : 1032
  Insecure     : no
  Nat          : RFC3581
  ACL          : No
  T38 pt UDPTL : No
  CanReinvite  : Yes
  PromiscRedir : No
  User=Phone   : No
  Video Support: No
  Trust RPID   : No
  Send RPID    : No
  Subscriptions: Yes
  Overlap dial : Yes
  DTMFmode     : rfc2833
  LastMsg      : 0
  ToHost       : 
  Addr->IP     : 192.168.1.250 Port 5061
  Defaddr->IP  : 0.0.0.0 Port 5060
  Def. Username: 1000
  SIP Options  : (none)
  Codecs       : 0x8000e (gsm|ulaw|alaw|h263)
  Codec Order  : (none)
  Auto-Framing:  No 
  Status       : Unmonitored
  Useragent    : X-Lite release 1105d
  Reg. Contact : sip:1000@192.168.1.250:5061

Polycom’s IP 430

A lot of folks say configuring Polycom phones is difficult. From what we can tell, they base this on one of two reasons: 1) The Polycom web-based interface is horrible, or 2) the automatic provisioning process is painful and confusing.

With respect to item 1, we agree. The web interface on the Polycom phones has got to be one of the most annoying web interfaces ever developed for an IP telephone. We don’t use it, and we don’t recommend it.[64]

So that leaves us with some sort of server-based configuration. Fortunately, in this regard, the Polycom IP phones are superb—so much so that we can pretty much forgive the web interface. Set configurations are stored in files on a server, and each set navigates to the server, downloads the configuration files that are relevant to it, and applies them to itself.

DHCP server

If you cannot control your DHCP server, you may have to manually specify the FTP server information on the phone. This is done by rebooting the set, pressing the setup button before the set begins the load process, and specifying the address of the FTP server in the small boot menu that these phones offer.

Protocol to use for downloading

The Polycom phones are able to download their configuration by one of three protocols: TFTP, HTTP, and FTP.

Right off the bat we are going to tell you to avoid TFTP. It is not secure, and the set cannot use date information to determine which versions of various files are the most current. It works, but there are better ways, and we are not going to discuss it further.

Polycom phones can pull their config data using HTTP as well, but it has not proven to be popular, and so we are going to move on.

FTP is currently the preferred method of allowing Polycom phones to obtain their configuration. It works well, is fairly easy to configure, and is well supported by the community.

FTP

FTP is currently our favorite way to configure Polycom sets. To install it on your CentOS system, the following command will install VSFTPD, the Very Secure FTP Daemon:

# yum -y install vsftpd

Then, in order to lock things down, we need to prevent anonymous logins, with a simple change to thevsftpd config file, /etc/vsftpd/vsftpd.conf:

# anonymous_enable=NO

Restart the server with service vsftpd restart. To ensure that the daemon runs after every reboot, run chkconfig vsftpd on.

Now, we have to create a user account and group for the Polycom sets to use:

# groupadd PlcmSpIp
# useradd PlcmSpIp -g PlcmSpIp -p PlcmSpIp
# passwd PlcmSpIp

Set the password to PlcmSpIp (the default FTP password for Polycom sets). This can be changed, but will then require manual configuration from each set in order to advise them of their nonstandard credentials.[65]

For added security, let’s make sure the FTP server keeps that account in a chroot jail:

# echo PlcmSpIp >> /etc/vsftpd/vsftpd.chroot_list

That pretty much does it as far as preparing the operating system to provide the required services to the phones.

The Polycom configuration files

While there seem to be a lot of different files that are needed to make a Polycom set work, they are each fairly easy to understand.

The bootROM

This can best be described as the BIOS and operating system of the phone. Perhaps there is a more technical explanation, but why make things confusing? The bootROM should not need to be updated regularly, but it is good to keep an eye on the current releases to see if a newer bootROM has features that will be of benefit in your environment. This file will be named bootrom.ld.

The application image

Since Polycom sets are capable of supporting other VoIP protocols (MGCP is supported, for example), the protocol that this set will employ forms part of the application image that the phone will download and run. If the image on the set is already correct, this file is not actually needed on the FTP server; however, it is common to have this file available to ensure that the most recent version of the protocol is available for the sets to download. You will sometimes receive phones that are not running the latest version, so having the most current image will ensure that all sets are up-to-date.

The sip.cfg file

There is normally only one version of this file on a system, but it can be named anything you want, and there can be as many different versions of this file as are needed. For example, if you had an office where there were two different languages in use, some users might prefer French on their set, and others English. In that case, you’d create a french.sip.conf file and an english.sip.conf file to handle each case. Name this file as you see fit, but pick a name that makes sense so that future administrators have a chance to make sense of your design choices.

The master config file for each phone

This file is very simple and small. It is named to match the MAC address of each phone (so each set will need its own copy of this file) and tells the set what other files it needs to download in order to configure itself. This is the first config file each set will read. In this file will be a reference to the application image this set will use (currently named sip.ld), as well as the names of the XML files that have the parameters for this phone (the .cfg files). A master config file for a set might look something like this:

'<?xml version="1.0" standalone="yes"?>'
'<!-- Default Master SIP Configuration File-->'
'<!-- Edit and rename this file to <Ethernet-address>.cfg for each phone.-->'
'<!-- $Revision: 1.14 $  $Date: 2005/07/27 18:43:30 $ -->'
'<APPLICATION APP_FILE_PATH="sip.ld" 
  CONFIG_FILES="phone1.cfg, sip.cfg" 
  MISC_FILES="" 
  LOG_FILE_DIRECTORY="" 
  OVERRIDES_DIRECTORY="" 
  CONTACTS_DIRECTORY=""
/>'

Note the name of the application file that we want this set to use, and the config files that it will be trying to find and apply.