Asterisk
Asterisk Asterisk
Contents

Asterisk - The Open Source VoIP PBX

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

D.41. voicemail.conf

The voicemail.conf file controls the Asterisk voicemail system (called Comedian Mail). It consists of three main sections. The first, called [general], sets the general system-wide settings for the voicemail system. The second, called [zonemessages], allows you to configure different voicemail zones, which are a collection of time and time zone settings. The third and final section is where you create one or more groups of voicemail boxes, each containing the mailbox definitions.

(For more information on adding voicemail capabilities to your dialplan, see Chapter 6.)

D.41.1. General Voicemail Settings

The [general] section of voicemail.conf contains a plethora of options that affect the entire voicemail system:



format

Lists the codecs that should be used to save voicemail messages. Codecs should be separated with the pipe character (|). The first format specified is the format used when attaching a voicemail message to an email. Defaults to wav49|gsm|wav.



serveremail

Provides the email address from which voicemail notifications should be sent.



attach

Specifies whether or not Asterisk should attach the voicemail sound file to the voicemail notification email.



maxmessage

Sets the maximum length of a voicemail message, in seconds.



minmessage

Sets the minimum length of a voicemail message, in seconds.



maxgreet

Sets the maximum length of voicemail greetings, in seconds.



skipms

Specifies how many milliseconds to skip forward/back when the user skips forward or backward during message playback.



maxsilence

Indicates how many seconds of silence to allow before ending the recording.



silencethreshold

Sets the silence threshold (what we consider "silence"the lower the threshold is, the more sensitive it is).



maxlogins

Sets the maximum allowed number of failed login attempts.



externnotify

Supplies the full path and filename of an external program to be executed when a voicemail is left or delivered, or when a mailbox is checked.



externpass

Supplies the full path and filename of an external program to be executed whenever a voicemail password is changed.



directoryintro

If set, overrides the default introduction to the dial-by-name directory.



charset

Defines the character set for voicemail messages.



adsifdn

Specifies the ADSI feature descriptor number to download to.



adsisec

Sets the ADSI security lock code.



adsiver

Indicates the ADSI voicemail application version number.



pbxskip

Causes Asterisk not to add the string [PBX]: to the beginning of the subject line of a voicemail notification email.



fromstring:

Changes the From: string of voicemail notification email messages.



usedirectory

Permits a mailbox owner to select entries from the dial-by-name directory for forwarding and/or composing new voicemail messages.



pagerfromstring

Changes the From: string of voicemail notification pager messages.



emailsubject

Specifies the email subject of voicemail notification email messages.



emailbody

Supplies the email body of voicemail notification email messages.

Please note that both the emailsubject and emailbody settings can use the following variables to provide more in-depth information about the voicemail:


  • VM_NAME

  • VM_DUR

  • VM_MSGNUM

  • VM_MAILBOX

  • VM_CALLERID

  • VM_CIDNUM

  • VM_CIDNAME

  • VM_DATE



mailcmd

Supplies the full path and filename of the program Asterisk should use to send notification emails. This option is useful if you want to override the default email program.

D.41.2. Voicemail Zones

As voicemail users may be located in different geographical locations, Asterisk provides a way to configure the time zone and the way the time is announced for different callers. Each unique combination is known as a voicemail zone. You configure your voicemail zones in the [zonemessages] section of voicemail.conf. Later, you can assign your voicemail boxes to use the settings for one of these zones.

Each voicemail zone definition consists of a line with the following syntax:

    zonename=timezone | time_format

The zonename is an arbitrary name used to identify the zone. The timezone argument is the name of a system time zone, as found in /usr/share/zoneinfo. The time_format argument specifies how times should be announced by the voicemail system. The time_format argument is made up of the following elements:



' filename'

The filename of a sound file to play (single quotes around the filename are required)



${ VAR}

Variable substitution



A or a

The day of the week (Saturday, Sunday, etc.)



B or b or h

The name of the month (January, February, etc.)



d or e

The numeric day of the month (first, second... thirty-first)



Y

The year



I or l

The hour, in 12-hour format



H

The hour, in 24-hour formatsingle-digit hours are preceded by "oh"



k

The hour, in 24-hour formatsingle-digit hours are not preceded by "oh"



M

The minute



P or p

A.M. or .P.M.



Q

"today", "yesterday," or ABdY (note: not standard strftime value)



q

"" (for today), "yesterday", weekday, or ABdY (note: not standard strftime value)



R

24-hour time, including minutes

For example, the following example sets up two different voicemail zones, one for the Central time zone in 12-hour format, and a second in the Mountain time zone, in 24-hour format:

    [zonemessages]
    central=America/Chicago|'vm-received' Q 'digits/at' IMp
    mountain24=America/Denver|'vm-received' q 'digits/at' H 'digits/hundred' M 'hours'

D.41.3. Defining Voicemail Contexts and Mailboxes

Now that the system-wide settings and voicemail zones have been set, you can define your voicemail contexts and individual mailboxes.

Voicemail contexts are used to separate out different groups of voicemail users. For example, if you are using Asterisk to host voicemail for more than one company, you should place each company's mailboxes in different voicemail contexts, to keep them separate. You might also use voicemail contexts to create per-department dial-by-name directories.

To define a new voicemail context, simply put the context name inside of square brackets, like this:

    [default]

Inside a voicemail context, each mailbox definition takes the following syntax:

    mailbox=password,name[,email[,pager_email[,options]]]

The mailbox argument is the mailbox number.

The password argument is the code the mailbox owner must enter to access his voicemail. If the password is preceded by a minus sign (-), the password may not be changed by the mailbox owner.

The email and pager_email arguments are email addresses where voicemail notifications will be sent. These may be left blank if you don't want to send voicemail notifications via email.

The options argument is a pipe-separated list of voicemail options that may be specified for the mailbox. (These options may also be set globally by placing them in the [general] section.) Valid voicemail options include:



tz

Sets the voicemail zone from the [zonemessages] section above. This option is irrelevant if envelope is set to no.



attach

Attaches the voicemail to the notification email (but not to the pager email). May be set to either yes or no.



saycid

Says the Caller ID information before the message.



cidinternalcontexts

Sets the internal context for name playback instead of extension digits when saying the Caller ID information.



sayduration

Turns on/off the duration information before the message. Defaults to on.



saydurationm

Specifies the minimum duration to say when sayduration is on. Default is 2 minutes.



dialout

Specifies the context to dial out from (by choosing option 4 from the advanced menu). If not specified, dialing out from the voicemail system will not be permitted.



sendvoicemail

Specifies the context to send voicemail from (by choosing option 5 from the advanced menu). If not specified, sending messages from within the voicemail system will not be permitted.



callback

Specifies the context to call back from. If not specified, calling the sender back from within the voicemail system will not be permitted.



review

Allows senders to review/rerecord their messages before saving them. Defaults to off.



operator

Allows senders to hit 0 before, after, or while leaving a voicemail message to reach an operator. Defaults to off.



envelope

Turns on/off envelope playback before message playback. Defaults to on. This does not affect option 3,3 from the advanced options menu.



delete

Deletes voicemails from the server after notification is sent. This option may be set only on a per-mailbox basis; it is intended for use with users who wish to receive their voicemail messages only by email.



nextaftercmd

Skips to the next message after the user hits 7 or 9 to delete or save the current message. This can be set only globally at this time, not on a per-mailbox basis.



forcename

Forces new users to record their names. A new user is determined by the password being the same as the mailbox number. Defaults to no.



forcegreetings

Forces new users to record greetings. A new user is determined by the password being the same as the mailbox number. Defaults to no.



hidefromdir

Hides the mailbox from the dial-by-name directory. Defaults to no.

You can specify multiple options by separating them with the pipe character, as shown in the definitions for mailboxes 9855 and 6522 below.

Here are some sample mailbox definitions:

    [default]
    ; regular mailbox with email notification
    101 => 4242,Example Mailbox,somebody@asteriskdocs.org

    ; more advanced mailbox with email and pager notification and a couple of
    ; special options
    102 => 9855,Another User,another@asteriskdocs.org,pager@asteriskdocs.org,
    attach=no|tz=central

    ; a mailbox with no email notification and lots of extra options
    103 => 6522,John Q. Public,,,tz=central|attach=yes|saycid=yes|
    dialout=fromvm|callback=fromvm|review=yes


Previous Page
Next Page
Asterisk