Asterisk 1.4 - 1.6

Buy the book at amazon.com

1.2. A simple PBX system

What does the simplest PBX system look like? It needs only two telephones and a "black box" connecting them to each other. In this case, the "black box" is a conventional PC in which we will install Asterisk; the two telephones are what we call "softphones", so named because they are implemented entirely in software. We'll install those softphones on a PC as well. As such, the requirements for the following example are themselves simple: all you need is a typical PC where you can install a current Linux distribution.[1]

Objectives

  • Transform a regular PC with a freshly installed Linux distribution into a mini-PBX.
  • Install and configure two VoIP telephones and assign them extension numbers 2000 and 2001
  • Call extension 2001 from 2000 and vice-versa.

Requirements

You will need a reasonably modern PC with sufficient memory. Though it's possible to install Asterisk on older hardware, the process will take longer and our 30 minute promise won't apply. (Working with older hardware can also be frustrating.) As a minimum, you should have a 500 MHz Pentium-class system with at least 512 MB RAM and at least 20 GB of hard disk. Asterisk will run on any current Linux distribution. These are available in retail stores, through mail order, or, if you have a broadband connection, by downloading them from the Internet.[2]
Make sure the distribution you use is current.
The example details below assume you are using a Debian Linux[3]distribution. The individual configuration instructions are entered on the command line.[4]

Which Asterisk version?

Asterisk Version 1.4 was released in late 2006 and may be considered stable. This book will focus primarily on 1.4; except where otherwise noted, commands described here may also be used with Asterisk 1.2.

Which Linux distribution is best for Asterisk?

Any discussion about the most appropriate Linux distribution for Asterisk quickly acquires a religious tone. The author chose Debian, but we've allowed space for installation instructions specific to other distributions in the Appendix because we fundamentally support user choice. Unfortunately, later chapters go into considerable technical detail and it simply isn't possible to include examples for each of the distributions specifically referenced in this book, let alone the myriad distributions available. For this reason, unless otherwise noted, assume that we are using Debian in the examples.

Why don't we use Asterisk packages with apt-get or rpm?

There's a really simple reason for this: currency.
As of this writing, no Linux distribution has even a half-way current version of Asterisk in its stable tree. The Asterisk project is extremely active and ever-changing. It just doesn't make sense to install a 1.0 version when 1.4 has been in release for over a year and is simply better in nearly every respect.

Note

It is true that packages have certain advantages, and they can make updating much easier. We hope that package-based installs will make more sense in future.
In return for the work of compiling the source packages you'll be rewarded with the knowledge that your Asterisk system is the most current it can be, and you won't be at the mercy of the package maintainers for your specific distribution.

Installing from current Asterisk sources

You can find Asterisk installation instructions for many of the more widely used Linux distributions in the Appendix. Use these instructions (see Appendix A, Installation instructions for Asterisk 1.4) to install your preferred Linux distribution. In the book, we assume a Debian installation (see Section A.1, “Installing Asterisk 1.4.x on Debian Linux 4.0 (Etch)”). Return to the next section when you've finished installing Linux.

Configure the Asterisk server

You will find all of the Asterisk configuration files for a standard install in the /etc/asterisk directory:
debian:/usr/src# cd /etc/asterisk 
debian:/etc/asterisk# ls
adsi.conf           cdr_tds.conf     indications.conf  privacy.conf
adtranvofr.conf     codecs.conf      logger.conf       queues.conf
agents.conf         dnsmgr.conf      manager.conf      res_odbc.conf
alarmreceiver.conf  dundi.conf       meetme.conf       rpt.conf
alsa.conf           enum.conf        mgcp.conf         rtp.conf
asterisk.adsi       extconfig.conf   misdn.conf        sip.conf
asterisk.conf       extensions.ael   modem.conf        sip_notify.conf
cdr.conf            extensions.conf  modules.conf      skinny.conf
cdr_custom.conf     features.conf    musiconhold.conf  telcordia-1.adsi
cdr_manager.conf    festival.conf    osp.conf          voicemail.conf
cdr_odbc.conf       iax.conf         oss.conf          vpb.conf
cdr_pgsql.conf      iaxprov.conf     phone.conf        zapata.conf
debian:/etc/asterisk#
Yes, this is a pretty hefty list, but don't let it scare you off. For our mini-PBX, we only need to worry about two specific files. First, we need to move the files created with make samples to /etc/asterisk/backup/ (so that we might retrieve them for later use; it is generally a good practice to copy original files to a backup directory when you are making changes):
debian:/etc/asterisk# mkdir backup
debian:/etc/asterisk# mv sip.conf backup/
debian:/etc/asterisk# mv extensions.conf backup/
debian:/etc/asterisk#
Using your favorite editor[5]create a new /etc/asterisk/sip.conf and enter the following:[6]
[general]
port = 5060
bindaddr = 0.0.0.0
context = others

[2000]
type=friend
context=my-phones
secret=1234
host=dynamic

[2001]
type=friend
context=my-phones
secret=1234
host=dynamic
We write a very simple dialplan in /etc/asterisk/extensions.conf:
[others]

[my-phones]
exten => 2000,1,Dial(SIP/2000)
exten => 2001,1,Dial(SIP/2001)
Are we serious? These few lines are enough to configure a PBX? The conventional wisdom says that Asterisk is unfathomably complex. Let's give it a try! Start Asterisk with the shell command asterisk -c:
debian:/etc/asterisk# asterisk -c
Asterisk 1.4.2, Copyright (C) 1999 - 2005 Digium.
Written by Mark Spencer <markster@digium.com>
=========================================================================
[ Booting...Nov 20 18:59:28 NOTICE[14937]: cdr.c:1185 do_reload: CDR 
simple logging enabled.
.........................................................................
............................................... ]
Asterisk Ready.
*CLI>
When Asterisk is started this way we also get a console that lets us communicate with the running Asterisk process. What we see now is the Asterisk CLI (command line interface) which lets us interactively control Asterisk. Our first action will be to stop Asterisk immediately with the command stop now:
*CLI> stop now
debian:/etc/asterisk#

Now we must connect two SIP phones to the mini-PBX. If you don't have any physical phones, you can use software phones (“softphones”) which you can download from the Internet.

Warning

If you intend to use a single test PC for these examples, you will have to set the SIP port on the softphone to 5061, since Asterisk will already be using the standard SIP port 5060 for its own SIP connections!

Tip

Set both the Registrar and Proxy addresses in the SIP phones to the IP address of your Asterisk server. Some phones won't accept any blank fields, even if the fields aren't needed for your situation. Set them to a meaningless value if necessary. Sadly, there's no hard and fast rule here; it depends on the phone. Sometimes a little trial and error is unavoidable.
For the user configuration on the phone, use the extension information we set in /etc/asterisk/sip.conf. SIP extension 2000 must be configured this way:
  • User: 2000
  • Password: 1234
  • SIP-Registrar: IP address of your Asterisk server
  • SIP-Proxy: IP address of your Asterisk server
If you don't know the address of your Asterisk server (and assuming it has one network card and one IP address) you can find it with this command:
debian:/etc/asterisk# ifconfig | grep Bcast | sed s/Bcast.*//
          inet addr:23.3.19.73
In this case, the IP address is 23.3.19.73.
Now we start Asterisk again, this time with more verbose console logging so that we can see what it is doing when we try to place a call. We do this by adding the parameters -vvvvvc after the command (the 5 v's mean “verbosity level 5”). This will let us see when the SIP phone registers with the PBX:
debian:/etc/asterisk# asterisk -vvvvvc
[...]
Asterisk Ready.
*CLI>
Once you've configured your SIP phones, it's time to register them with the server. To be absolutely sure, turn the phone off and then on again (or, in the case of a softphone, close and open the application). This can require a bit of patience; some SIP phones are rather slow and can take up to a few minutes to finish rebooting. If all goes well, we should see the phones registering with Asterisk:
*CLI>     -- Registered SIP '2000' at 87.143.3.144 port 5060 
expires 120 -- Unregistered SIP '2000'

*CLI>     -- Registered SIP '2001' at 87.143.3.145 port 5060 
expires 120 -- Unregistered SIP '2001'
Once the phones are registered, we can make some calls. This part is easy - using extension 2000, dial 2001. If you are able to have a conversation, you've succeeded! Your first mini-PBX with Asterisk is working.

Tip

If you miss the registration message in all the excitement, you can check to see if your phones have registered by entering sip show peers in the Asterisk CLI. This will give you a list of all the configured and registered SIP phones. With sip show peer 2000 you will get much more detailed information about SIP extension 2000.
You can stop Asterisk at any time by typing stop now in the Asterisk CLI.

An answering machine

Asterisk comes complete with a built-in voicemail module but it has to be configured in /etc/asterisk/voicemail.conf before we can use it. As a first step (which you should make a routine) we copy the default files into our previously created backup directory:
debian:/# cd /etc/asterisk
debian:/etc/asterisk# mv voicemail.conf backup/
Now we can create a new /etc/asterisk/voicemail.conf and type the following into it:
[general]
format = wav

[default]
2000 => 4711,Joe Bloggs,joeb@megacorp.biz
2001 => 0815,Darlene Doe,dard@megacorp.biz
We've just configured two default mailboxes (yes, it is that simple). We're not quite done yet, though. We need to add a few more lines in /etc/asterisk/extensions.conf to tie these mailboxes to our phones and make them accessible. Make sure to add the ",20" at the end of the Dial() command:
[others]

[my-phones]
exten => 2000,1,Dial(SIP/2000,20)
exten => 2000,2,VoiceMail(2000,u)

exten => 2001,1,Dial(SIP/2001,20)
exten => 2001,2,VoiceMail(2001,u)

exten => 2999,1,VoiceMailMain(${CALLERID(num)},s)
Done! Now just start Asterisk with asterisk -vvvvvc

Tip

In a running Asterisk console, the command reload is sufficient.
and make a call to the extension 2000. After 20 seconds (the reason for the "20" at the end of the Dial() command), the call is sent to voicemail. If extension 2000 is busy, the call goes directly to voicemail. You can check for messages at extension 2000 by dialling 2999, which will send you to the voicemail retrieval menu.
For more details on configuring voicemail (such as adding password security or a description of the voicemail menu) see Chapter 4, Voicemail.

What did we just do?

With this success under our belts, let's go through the configuration files line by line, beginning with /etc/asterisk/sip.conf. This will help us understand what Asterisk is doing and why.
[general]
port = 5060
bindaddr = 0.0.0.0
context = others
In the first section, called [general], we set global configuration values. The standard port for SIP connections is 5060. The bindaddr = 0.0.0.0 value tells Asterisk to listen for connections on all the IP addresses configured on the system. Most systems will have only a single IP address. If you have multiple physical or virtual interfaces configured, or even multiple instances of Asterisk running, and you want to decide which IP addresses Asterisk will accept connections on, you can specify those addresses with the bindaddr value.
The context value is special and needs a bit more explanation, so we'll go into that in more detail elsewhere in the book. As you go through the instructions and examples, you'll become more comfortable with the idea of “context” as it applies to Asterisk and learn how to employ it.
[2001]
type=friend
context=my-phones
secret=1234
host=dynamic
The [2001] section defines parameters for the 2001 SIP extension. We use a number by convention; though most people expect extensions to have numbers, SIP extensions can also be defined with an alphanumeric identifier -- for example, [Reception-1]. The parameter type=friend simply means that this SIP extension can both accept and make calls.[7]
Again we encounter that ominous value, context. We are calling the context my-phones in /etc/asterisk/extensions.conf; When we look at that file in the next section, the application of contexts should become clearer.
The secret value sets a password for the SIP extension. We use this to prevent an unauthorized device from registering as extension 2001. It's best to use numbers here, since it's also easier to enter numbers with most telephone sets. The term host=dynamic tells Asterisk that it doesn't matter if the IP address of the SIP extension 2001 changes.

extensions.conf - the Asterisk dialplan

The /etc/asterisk/extensions.conf -- known as the “dialplan” -- is the heart of every Asterisk configuration (see also Chapter 3, Programming in the dialplan). In a sense, you can equate them with a switchboard used in early telephone systems. The dialplan determines which phones can make calls to other phones, and how.
The dialplan is divided into contexts.
[others]
The first section of the configuration is the context [others]. As we are not using it in this example, it can be empty.
[my-phones]
exten => 2000,1,Dial(SIP/2000,20)
exten => 2000,2,VoiceMail(2000,u)
Asterisk always uses a context when handling a call from one phone to another. The context name is limited only by your imagination, but must be consistent across configuration files. This means that if you refer to a context my-phones in /etc/asterisk/sip.conf, you must use the same name in the relevant part of /etc/asterisk/extensions.conf. This context is critical to the operation of the phone! It determines what extension numbers can be dialled and which actions will be allowed.

Important

The context of the phone you are calling to is irrelevant here. Understanding this distinction is vital for successful configuration.
The syntax of a dialplan entry always follows this convention:
exten => Number,Priority,Application
When a number is dialled, Asterisk checks to see if it matches a dialplan entry. If a match is found, that entry is read and executed. If there is more than one applicable entry for a dialled number, Asterisk will execute the entry with the priority 1 first. The third parameter ("Application") defines what Asterisk actually does with the call.
Based on our sample configuration (see above), this is what happens when we make a call from extension 2001 to extension 2000:
  • Asterisk looks up the context for the calling extension (2001) in /etc/asterisk/sip.conf. In our example, this context is [my-phones]. Asterisk uses this context to decide which set of entries in /etc/asterisk/extensions.conf it should use.
  • Having found the context [my-phones] in /etc/asterisk/extensions.conf, Asterisk executes the entries matching the dialled number, 2000, in order of priority. Our example has two matching lines.
  • The matching entry with the priority 1 is executed first, no matter the physical order of the entries. Here, the entry with priority 1 has the command Dial(SIP/2000,20). The Dial() application is run with the parameters given; it looks for the entry for 2000 in /etc/asterisk/sip.conf and rings it for 20 seconds (hence the ",20" after SIP/2000).
  • If the SIP extension 2000 is not answered within 20 seconds, Dial() completes and the priority is increased by 1.
  • The matching entry with the next priority -- exten => 2000,2,VoiceMail(2000,u) -- is now executed. Asterisk runs the VoiceMail() application with the parameters "2000" and "u". The "2000" is for the mailbox number as configured in /etc/asterisk/voicemail.conf; the "u" tells Asterisk to use the standard "unavailable" message. By now you've probably figured out that we picked a number for simplicity's sake; we could just as easily have used 5555 or joebloggs.
Of course, voicemail is no good unless you can retrieve messages others have left for you. We enable access with this entry:
exten => 2999,1,VoiceMailMain(${CALLERID(num)},s)
Ah -- our first exposure to a dialplan function in Asterisk! We call the application VoiceMailMain() with the function ${CALLERID(num)} as a parameter. The ${CALLERID(num)} function returns the number of the calling party. In this way, VoiceMailMain() always knows to retrieve messages for the phone from which it was called. If the parameter is not supplied, it will ask the caller for the mailbox number. The ",s" parameter tells VoiceMailMain() not to ask the caller for a password.

voicemail.conf - The voicemail system

The voicemail module (see also Chapter 4, Voicemail) is configured in /etc/asterisk/voicemail.conf in much the same way as the dialplan (/etc/asterisk/extensions.conf):
[general]
format = wav

[default]
2000 => 4711,Joe Bloggs,joeb@megacorp.biz
2001 => 0815,Darlene Doe,dard@megacorp.biz
The [general] section is where define global parameters, such as the file format used for saving the voice messages, are defined. Actual mailboxes are defined in a context called [default]; here you see the lines defining the mailboxes for extension 2000 and 2001, complete with passwords (4711 and 0815). After the password, there is a field for the name of the mailbox owner and that person's e-mail address. Messages are attached as WAV-format files to an e-mail and sent to the intended recipient.

Calling the public telephone network

Now, you're probably thinking “It's nice that we have a working telephone system, but what good is it if you can't make calls to the big wide world?” With your permission, an additional 10 minutes of your time, and an Internet connection, we will solve that problem too. You'll need an account with a SIP telephony provider.
The example below shows a sample configuration for a connection to a SIP telephony provider. There are many SIP providers available; a quick Google™ search will give you a selection of providers you can try out. Once configured, this will allow you to make calls to the PSTN (Public Switched Telephone Network) from your Asterisk extensions. The SIP provider account information must first be entered in /etc/asterisk/sip.conf:
[general]
port = 5060
bindaddr = 0.0.0.0
context = others

register => 5587572:UHDZJD@my-voip-provider.com/5587572
;              ^       ^       ^                    ^
;              |       |       |                    |
;             User Password  Provider              User

[2000]
type=friend
context=my-phones
secret=1234
host=dynamic

[2001]
type=friend
context=my-phones
secret=1234
host=dynamic

[ext-sip-account]
type=friend
context=from-voip-provider
username=5587572
fromuser=5587572
secret=UHDZJD
host=my-voip-provider.com
fromdomain=my-voip-provider.com
qualify=yes
insecure=very
nat=yes
The SIP provider will provide you with a username (5587572 in our example) and password (UHDZJD in our example) when you open your account. Once the SIP account is configured, we still need to add an entry to /etc/asterisk/extensions.conf to allow outgoing calls:
[others]

[my-phones]
exten => 2000,1,Dial(SIP/2000,20)
exten => 2000,2,VoiceMail(2000,u)

exten => 2001,1,Dial(SIP/2001,20)
exten => 2001,2,VoiceMail(2001,u)

exten => 2999,1,VoiceMailMain(${CALLERID(num)},s)

exten => _0[1-9].,1,Dial(SIP/${EXTEN}@ext-sip-account)
Once these new entries have been entered, save the file and start Asterisk as before, with asterisk -vvvvvc so that we get the CLI. Wait a few seconds for the SIP phones to register. Now simply dial a number.

Tip

When dialing through most VoIP providers, you need to dial the complete number, including predial digit (1 in North America) and area or city code, even if the call is a local call in your calling area. For North America, this means you would be dialling the predial digit, followed by the full 10 digit number including area code, even in regions that do not already have 10 digit local dialing. (Later on, we'll show you some techniques that you can use in /etc/asterisk/extensions.conf so that you don't need to dial the full number for local calls in areas where it is not normally required.)

Warning

Most SIP providers charge a per-minute rate for local calls and many require pre-payment. An advantage is that there is no monthly flat-rate for most SIP accounts.
If everything is working as it should, you will hear the remote line ringing and be able to observe the call progress in the CLI.
It's a bit early to explain exactly how this works; more on that later.
[8]

Taking calls from the public telephone network

The last step is a small one: we want to be able to take incoming calls via our SIP provider on extension 2000. To do this, we need to add another context to /etc/asterisk/extensions.conf:
[others]

[my-phones]
exten => 2000,1,Dial(SIP/2000,20)
exten => 2000,2,VoiceMail(2000,u)

exten => 2001,1,Dial(SIP/2001,20)
exten => 2001,2,VoiceMail(2001,u)

exten => 2999,1,VoiceMailMain(${CALLERID(num)},s)

exten => _0[1-9].,1,Dial(SIP/${EXTEN}@ext-sip-account)

[from-voip-provider]
exten => 18885556266,1,Dial(SIP/2000)
Done!
In our example, the number 18885556266 is the PSTN number (also called a DID; more on that later) given to your account by your SIP provider.
You can, of course, configure voicemail for calls coming in from the PSTN:
[others]

[my-phones]
exten => 2000,1,Dial(SIP/2000,20)
exten => 2000,2,VoiceMail(2000,u)

exten => 2001,1,Dial(SIP/2001,20)
exten => 2001,2,VoiceMail(2001,u)

exten => 2999,1,VoiceMailMain(${CALLERID(num)},s)

exten => _0[1-9].,1,Dial(SIP/${EXTEN}@ext-sip-account)

[from-voip-provider]
exten => 18885556266,1,Dial(SIP/2000,20)
exten => 18885556266,2,VoiceMail(2000,u)
If you were so inclined, you could just leave things like this and start using your new mini-PBX, but what fun would that be? This chapter was only meant to show you how quickly you can build a working Asterisk system. In the coming chapters, we'll fill in the gaps and show you just how much you can really do with Asterisk.

[1] Our “Hello World” is even more fun if you have more than one computer connected by a local area network. You can use one computer as the Asterisk server and the others for the softphones.

[2] Here are URLs for a few of the more popular distributions:

[3] The current Debian "stable".

[4] You will need to call up a console window (such as xterm or konsole) if you are using a window manager.

[5] If you haven't yet chosen a favorite editor, we recommend nano. In Debian Linux this is installed (as the root user) with the command apt-get -y install nano. You then edit files by invoking nano filename. Nano provides a menu of its most important commands at the bottom of the screen.

[6] The simple passwords depicted here are, of course, only for testing and demonstration purposes. For actual production installations, you should use much stronger passwords.

[7] The entry type= has three possible values (we'll address these in more detail in a later chapter):

  • friend: can make and accept calls.
  • peer: can only make calls.
  • user: can only accept calls.

[8] Not too much at once! For now, all you need to know is that the ${EXTEN} variable always contains the number dialled by the caller for the specific instance (see Chapter 3, Programming in the dialplan).