Asterisk Documentation

Safaa shaaban hasan

1.1.Introduction
This the documentation installing and configuring.
AsteriskIntermediate level - assumes basic knowledge of networking,linux
systems,and VoIPWe’ll be building a real live Asterisk box as we progress
through this documentationIt also attempts to provide primers on the key
technicaldisciplines that are required to successfully create and manage
Asterisk solutions.
1.2.Concept:
Asterisk is…
 An open source software development project
 written in the C Programming Language.
 running on Linux (or other types of Unix)
 powering Business Telephone Systems
 connecting many different Telephony protocols
 a toolkit for building many things:
o an IP PBX with many powerful features and applications
o VoIP Gateways
o Conferencing systems
o and much, much more
 supporting VoIP Phones as well as PSTN and POTS
 speaking SIP , the most common VoIP protocol, among others

1.3.Who Uses Asterisk?

Asterisk is created by communication system developers, for communication
system developers. As an open source project, Asterisk is a
collaborationbetween many different individuals and companies, all of which
need a flexible communications engine to power their applications.
1.4.Installing Asterisk
get you up and running with your own Asterisk installation
There are various ways toget started with Asterisk on your own system:
Install an Asterisk-based Linux distribution such as
AsteriskNOWInstalling AsteriskNOW:
This Linux distribution has been carefully customized and tested with Asterisk, and
installs all of the packagesneeded for its use. It is the officially recommended
development and runtime platform for Asterisk and Digium hardware, including
Digium phones.This guide provides a brief overview of installation, configuration,
and maintenance of your system:
1-After logging in to your Ubuntu as an user, issue following command to switch
to root
tala@tala-SATELLITE-c50-B:~$ sudosu
Now you are root, but you need to set password with command
Passwd

3-Update Your System

apt-get update && apt-get upgrade –y
4-Install Required Dependencies
apt-get install build-essential wget libssl-dev
libncurses5-dev libnewt-dev libxml2-dev linux-headers-$
(uname -r) libsqlite3-dev uuid-dev git subversion
5-Now when we are root and dependencies are satisfied, we can move to /usr/src/
dir and download asterisk there

cd /usr/src
wget downloads.asterisk.org/pub/telephony/asterisk/asterisk-13-current.tar.gz
6-Next we unpack it.
tar zxvf asterisk-13-current.tar.gz

7-Now we need to cd into the newly unpacked directory, but we don't really know
what the directory is called. It starts with asterisk-13 and then there is minor
version which is at the time of writing this article is 13.10.0 but might change
down the road because wget command we have further up
So we use * (yes, asterisk) to make this guide future proof:
cd asterisk-13*

8-Download Asterisk source files

-wget http://downloads.asterisk.org/pub/telephony/dahdi-linux-
complete/dahdi-linux-complete-current.tar.gz
-wget http://downloads.asterisk.org/pub/telephony/libpri/libpri-current.tar.gz
wget -http://downloads.asterisk.org/pub/telephony/asterisk/asterisk-12-
current.tar.gz
-git clone https://github.com/akheron/jansson.git

9-Compile and install DAHDI.

cd /usr/src
tar xvfz dahdi-linux-complete-current.tar.gz
cd dahdi-linux-complete-*
make all
make install
make config

10-Compile and install LIBPRI.

cd /usr/src
tar xvfz libpri-current.tar.gz
cd libpri-*
make
make install
10-we need pjproject as asterisk 13 introduces the support for pjsip. So we will
compile it first:
cd /usr/src/pjproject
./configure --enable-shared --disable-sound --disable-resample --disable-video
--disable-opencore-amr
make dep
make
make install

11-Compile and Install jansson

cd /usr/src/jansson
autoreconf -i
./configure
make
make install

And now we commence to configuring and compiling the Asterisk code

12-cd ..
contrib/scripts/get_mp3_source.sh
contrib/scripts/install_prereq install

This will install mp3 tones and satisfy additional dependencies which might take
some time and ask you for your country code.
13-cd /usr/src
tar xvfz asterisk-12-current.tar.gz
14-compile and install asterisk

cd asterisk-*
./configure

15-menuselect
You will be prompted at the point to pick which modules to build. Most of them
will be enabled, but if you want to have MP3 support, you need to manually turn
on 'format_mp3' on the first page.
After selecting 'Save & Exit' you can then continue

16-insall asterisk
make
make install

make config

17-for start asterisk:

/etc/init.d/asterisk start
and then we can enter asterisk console with command
asterisk -rvvv

1.5Intro to Asterisk Configuration Files

In this section, we'll introduce you to the Asterisk configuration files, and show
you how to use some advanced features.
1.5.1Config File Format
Asterisk is a very flexible telephony engine. With this flexibility, however, comes a
bit of complexity. Asterisk has quite a few configuration files which control
almost every aspect of how it operates. The format of these configuration files,
however, is quite simple. The Asterisk configuration files are plain text files,
and can be edited with any text editor.
1.5.2Configuration of Asterisk channels:
-sip.conf: Configure SIP channels
1.5.3Configuration of the Dialplan:
-extensions.conf : The Dialplan
1.5.4Configuration of specific Dialplan Commands:
 musiconhold.conf: MusicOnHold configuration
 queues.conf: Queue configuration
 voicemail.conf: VoiceMail configuration

1.5.5Comments
We can (and often do) add comments to the Asterisk configuration files.
Comments help make the configuration files easier to read, and can also be
used to temporarily disable certain settings.
 1.5.5.1Comments on a Single Line
Single-line comments begin with the semicolon (;) character. The Asterisk
configuration parser treats everything following the semicolon as a comment.
To expand on our previous example: ; this entire line is a comment

1.6.Creating SIP Accounts:

In order for our two phones to communicate with each other, we need to configure
an account for each phone in the channel driver which corresponds to the protocol
they'll be using. Since both the phones are using the SIP protocol, we'll configure
accounts in the SIP channel driver configuration file, called sip.conf . (This file
resides in the Asterisk configuration directory, which is typically /etc/asterisk .)
Let's name your phones Alice and Bob , so that we can easily differentiate between
them. Open sip.conf with your favorite text editor, and spend a minute or two
looking at the file. (Don't let it overwhelm you — the sample sip.conf has a lot of
data in it, and can be overwhelming at first glance.) Notice that there are a couple
of sections at the top of the configuration, such as [general] and [authentication],
which control the overall functionality of the channel driver. Below those sections,
there are sections which correspond to SIP accounts on the system. Scroll to the
bottom of the file, and add a section for 7001 and 7002. You'll need to choose your
own unique password for each account, and change the permit line to match the
settings for your local network. After completing this guide your Asterisk will be
able to :
 Host calls locally
 Access mail boxes
We will be editing the following files:

 sip.conf
 extensions.conf
 voicemail.conf

These files are located in:

 /etc/asterisk

1.6.1.Making a backup of sip.conf

Type the following to move the original sip.conf
sudo mv /etc/asterisk/sip.conf /etc/asterisk/sip.conf.orig

Creating a new sip.conf and configuring it

Type the following to create a new sip.conf.
You can save this file by first pressing ESC then letting go.
Followed by holding Shift and : then letting go again.
Now type wq! followed by pressing enter.
Your file is now saved.
After adding the two sections above to your sip.conf file, go to the Asterisk
command-line interface and run the sip reload command to tell Asterisk to
re-read the sip.conf configuration file.
sip reload

1.7.Registering Phones to Asterisk:

The next step is to configure the phones themselves to communicate with Asterisk.
The way we have configured the accounts in the SIP channel driver,
Asterisk will expect the phones to register to it. Registration is simply a
mechanism where a phone communicates "Hey, I'm 7001 phone... here's my
username and password. Oh, and if you get any calls for me, I'm at this particular
IP address." Configuring your particular phone is obviously beyond the scope of
this guide, but here are a list of common settings you're going to want to set in your
phone, so that it can communicate with Asterisk:
Registrar/Registration Server - The location of the server which the phone
should register to. This should be set to the IP address of
your Asterisk system.
*SIP User Name/Account Name/Address - *The SIP username on the remote
system. This should be set to 7001 on one phone and 7002 on the other. This
username corresponds directly to the section name in square brackets in sip.conf.
SIP Authentication User/Auth User - On Asterisk-based systems, this will be the
same as the SIP user name above. You can tell whether or not your phone has
registered successfully to Asterisk by checking the output of the sip show peers
command at the Asterisk CLI.
sip show peers:

1.8.Creating Dialplan Extensions

The last things we need to do to enable 7001 and 7002 to call each
other is to configure a couple of extensions in the dialplan.
Let's take a quick look at the dialplan, and then add two extensions.
Open extensions.conf , and take a quick look at the file. Near the top of
the file, you'll see some general-purpose sections named [general] and
[globals].Any sections in the dialplan beneath those two sections is
known as a context . The sample extensions.conf file has a number of
other contexts, with names like [demo] and [default].

1.8.1Making a backup of extensions.conf

Type the following to move the original extensions.conf
sudo mv /etc/asterisk/extensions.conf /etc/asterisk/extensions.conf.orig

Go to the bottom of your extensions.conf file, and add a new context named
[users].
1.8.2Creating a new extensions.conf and configuring it
Type the following to create a new extensions.conf
sudo vi /etc/asterisk/extensions.conf
You can save this file by first pressing ESC then letting go.
Followed by holding Shif and : then letting go again.
Now type wq! followed by pressing enter.
Your file is now saved.
fter adding that section to extensions.conf , go to the Asterisk command-line
interface and tell Asterisk to reload the dialplan by typing the command dial
plan reload . You can verify that Asterisk successfully read the configuration file by
typing dialplan show users at the CLI
tala-SATELLITE-C50-B*CLI> dialplan show

Now we're ready to make a test call!

Making a Phone Call:
At this point, you should be able to pick up 7001 phone and dial extension 7001 to
call 7002, and dial 7002 from 7002 phone to call 7001.
 As you make a
few test calls, be sure to watch the Asterisk command-line interface (and ensure
that your verbosity is set to a value three or higher) so that you can see

the messages coming from Asterisk, which should be similar to the ones below:
As you can see, 7001 called extension 7001 in the [users] context, which in turn
used the Dial application to call 7001 phone. 7001 phone rang, and then
answered the call. Asterisk then bridged the two calls (one call from 7002 to
Asterisk, and the other from Asterisk to 7001), until Alice hung up the phone.
Contexts, Extensions, and Priorities
The dialplan is organized into various sections, called contexts. Contexts are the
basic organizational unit within the dialplan, and as such, they keep
different sections of the dialplan independent from each other. We'll use contexts
to enforce security boundaries between the various parts of our dialplan,
as well as to provide different classes of service to groups of users.
Within each context, we can define one or more extensions . As explained in the
previous module, an extension is simply a named set of actions. Asterisk
will perform each action, in sequence, when that extension number is dialed. The
syntax for an extension is:
exten => number,priority,application([parameter[,parameter2…]])
exten => 6001,1,Dial(SIP/demo-alice,20)
In this case, the extension number is 6001 , the priority number is 1 , the
application is Dial() , and the two parameters to the application are SIP/demo-alice
and 20 .
Within each extension, there must be one or more priorities . A priority is simply a
sequence number. The first priority on an extension is executed first.
When it finishes, the second priority is executed, and so forth.
Priority number can also be simplied by using the letter n in place of the priority numbers greater
than one. The letter n stands for next , and when Asterisk
sees priority n it replaces it in memory with the previous priority number plus one. Note that you
must still explicitly declare priority number one.
exten => 6123,1,do something
exten => 6123,n,do something else
exten => 6123,n,do something different
Answer, Playback, and Hangup Applications
As its name suggests, the Answer() application answers an incoming call. The Answer()
application takes a delay (in milliseconds) as its first parameter.
Adding a short delay is often useful for ensuring that the remote endpoing has time to begin
processing audio before you play a sound prompt. Otherwise,
you may not hear the very beginning of the prompt.
Knowing When to Answer a Call
When you're first learning your way around the Asterisk dialplan, it may be a bit confusing
knowing when to use the Answer() application, and when not to.
If Asterisk is simply going to pass the call off to another device using the Dial() application, you
probably don't want to call the answer the call first. If, on the
other hand, you want Asterisk to play sound prompts or gather input from the caller, it's probably
a good idea to call the Answer() application before doing
anything else.
The Playback() application loads a sound prompt from disk and plays it to the caller, ignoring
any touch tone input from the caller. The first parameter to
the dialplan application is the filename of the sound prompt you wish to play, without a file
extension. If the channel has not already been answered, Playba
ck() will answer the call before playing back the sound prompt, unless you pass noanswer as the
second parameter.
To avoid the first few milliseconds of a prompt from being cut off you can play a second of
silence. For example, if the prompt you wanted to play was
hello-world which would look like this in the dialplan:
exten => 1234,1,Playback(hello-world)
You could avoid the first few seconds of the prompt from being cut off by playing the silence/1
file:
exten => 1234,1,Playback(silence/1)
exten => 1234,n,Playback(hello-world)
Alternatively this could all be done on the same line by separating the filenames with an
ampersand (&):
exten => 1234,1,Playback(silence/1&hello-world)

Adding Voice Mail to Dialplan Extensions

Adding voicemail to the extensions is quite simple. The
Asterisk voicemail module provides two key applications for
dealing with voice mail. The first,

named VoiceMail() , allows a caller to leave a voice mail

message in the specified mailbox. The second, called
VoiceMailMain() , allows the mailbox owner

to retrieve their messages and change their greetings.

VoiceMail Application

The VoiceMail() applications takes two parameters:

1. Mailbox

This parameter specifies the mailbox in which the voice mail

message should be left. It should be a mailbox number and a
voice

mail context concatenated with an at-sign ( @ ), like

6001@default . (Voice mail boxes are divided out into various
voice mail

context, similar to the way that extensions are broken up into

dialplan contexts.) If the voice mail context is omitted, it will
default

to the default voice mail context.

2. Options
One or more options for controlling the mailbox greetings. The
most popular options include the u option to play the
unavailable

message, the b option to play the busy message, and the s

option to skip the system-generated instructions.

VoiceMailMain Application

The VoiceMailMain() application allows the owner of a voice

mail box to retrieve their messages, as well as set mailbox
options such as greetings and

their PIN number. The VoiceMailMain() application takes two

parameters:

1. Mailbox - This parameter specifies the mailbox to log into. It

should be a mailbox number and a voice mail context,
concatenated with an

at-sign (@), like 6001@default. If the voice mail context is

omitted, it will default to the default voice mail context. If the
mailbox number is

omitted, the system will prompt the caller for the mailbox
number.

2. Options - One or more options for controlling the voicemail

system. The most popular option is the s option, which skips
asking for the

PIN number

Configuring Voice Mail Boxes

Now that we've covered the two main voice mail applications,
let's look at the voicemail configuration. Voice mail options
and mailboxes are configured in

the voicemail.conf configuration file. This file has three major

sections:

The [general] section

Near the top of voicemail.conf , you'll find the [general]

section. This section of the configuration file controls the
general aspects of the voicemail system,

such as the maximum number of messages per mailbox, the

maximum length of a voicemail message, and so forth. Feel
free to look at the sample voicem

ail.conf file for more details about the various settings.

The [zonemessages] section

The [zonemessages] section is used to define various

timezones around the world. Each mailbox can be assigned to
a particular time zone, so that times

and dates are announced relative to their local time. The time
zones specified in this section also control the way in which
times and dates are announced,

such as reading the time of day in 24-hour format.

Voice Mail Contexts

After the [general] and [zonemessages] sections, any other

bracketed section is a voice mail context. Within each context,
you can define one or more
mailbox. To define a mailbox, we set a mailbox number, a PIN,
the mailbox owner's name, the primary email address, a
secondary email address, and a list

of mailbox options (separated by the pipe character), as shown

below:

mailbox=>pin,full name,email address,short email

address,mailbox options

Making a backup of voicemail.conf

Type the following to move the original voicemail.conf
sudo mv /etc/asterisk/voicemail.conf /etc/asterisk/voicemail.conf.orig

Creating a new voicemail.conf and configuring it

Type the following to create a new voicemail.conf
sudo vi /etc/asterisk/voicemail.conf
[main]
7001 => 123

7002 => 456

You can save this file by first pressing ESC then letting go.
Followed by holding Shift and : then letting go again.
Now type wq! followed by pressing enter.
Your file is now saved.

Reloading Asterisk to apply the configuration

You can restart asterisk by any of the following ways:

sudo /etc/init.d/asterisk restart

and then call

Now that we've defined the mailboxes, we can go into the Asterisk CLI and type voicemail
reload to get Asterisk to reload the voicemail.conf file. We can
also verify that the new mailboxes have been created by typing voicemail show users
Now that we have mailboxes defined, let's add a priority to extensions 6001 and 6002 which will
allow callers to leave voice mail in their respective
mailboxes. We'll also add an extension 6500 to allow Alice and Bob to check their voicemail
messages. Please modify your [users] context in extensions.
conf to look like the following:
[users]
exten => 6000,1,Answer(500)
exten => 6000,n,Playback(hello-world)
exten => 6000,n,Hangup()
exten => 6001,1,Dial(SIP/demo-alice,20)
exten => 6001,n,VoiceMail(6001@vm-demo,u)
exten => 6002,1,Dial(SIP/demo-bob,20)
exten => 6002,n,VoiceMail(6002@vm-demo,u)
exten => 6500,1,Answer(500)
exten => 6500,n,VoiceMailMain(@vm-demo)

Reload the dialplan by typing dialplan reload at the Asterisk CLI. You can then test the voice
mail system by dialing from one phone to the other and
waiting twenty seconds. You should then be connected to the voicemail system, where you can
leave a message. You should also be able to dial extension
6500 to retrieve the voicemail message. When prompted, enter the mailbox number and PIN
number of the mailbox.
While in the VoiceMainMain() application, you can also record the mailbox owner's name,
unavailable greeting, and busy greeting by pressing 0 at the
voicemail menu. Please record at least the name greeting for both Alice and Bob before
continuing on to the next section.
recored voice mail