VOIP for the rest of us

Interested in setting up a PBX with Asterisk for your home or small office, but not
sure where to start? I was in the same position a few months ago, struggling with
the documentation, and trying to piece things together. Things do come together
eventually, but I thought I'd make an effort at an introduction to Asterisk for
newbies, so here it is.

Introduction

Asterisk is software that turns a Linux box into a professional quality PBX using IP
Telephony technologies. You don't have to know every protocol and every acronym
right now. You'll learn all of those in time. I got started by getting a TDM400P
from Digium. This piece focuses on using that card to bridge Asterisk to the analog
phone world. This card allows you to talk to a POTS line provided by Verizon for
instance using an FXO interface, or a standard analog phone using an FXS
interface. There are four slots so you can mix and match. Once you get started
though, I think you'll be so impressed with IP Phones that you'll give up your analog
phones, and just use the Digium card to bridge to your POTS phone lines.

Install Card

First you have to get that card in the box. Presumably you've installed PCI cards
with Linux before, so I won't go into that. What I will recommend is to just include
one FXO interface on the card for starters. This will make my VERY simple
configurations work for you. Put it in the left most slot so it will come up as channel
1.

Configure Card

So you've rebooted and Linux has come up, and you have a root bash prompt, what
now? Well you have to modprobe the hardware to get Linux to see it. But don't go
modprobe-ing just yet. You have to configure the /etc/zaptel.conf file. This file is
not an Asterisk configuration file. It is merely for the Digium hardware. When
Linux loads those drivers, it looks for this configuration file. For the configuration
above you just need these three lines:

loadzone=us
defaultzone=us
fxsks=1

Ok, so go ahead and modprobe now:

$ modprobe zaptel
$ modprobe wcfxs
For this card, no matter what type of interfaces you have on it, you just need these
two drivers. Did you get any errors? Depending on the version of Linux, you may
be using udev. If you are, like I was, you may get some errors about some device
files that are missing:

$ modprobe wcfxs
Notice: Configuration file is /etc/zaptel.conf
line 4: Unable to open master device '/dev/zap/ctl'

You're in luck. The solution is trivial. Well it wasn't for me, but I had no clue! Take
a look at the Asterisk source tree, and you'll find a file README.udev. This file
has some lines which you'll add to the appropriate file in /etc/udev/rules.d and then
you're done. Retry the modprobe (you may have to rmmod first) and be sure there
are no errors. Verify that there are devices in /dev/zap, and you can move on!

Configure Asterisk

Up to this point you were just configuring the hardware. Now you'll look at Asterisk
configuration. Believe it or not, you really only need to configure two files for
starters. They are the zapata.conf file, and the extensions.conf file. If you add an IP
phone, you'll put that configuration in sip.conf. There are lots of files in there which
can confuse a newbie, I know they confused me. When I looked at sip.conf I
thought, well Asterisk is a sip server, so perhaps some of the Asterisk configuration
info is there. Nope, just sip phones go there.

Ok, lets start with the zapata.conf. It tells asterisk about your zaptel device. Asterisk
does not use the zaptel.conf for this, that file is only for Linux, the driver, and is
used during the modprobe phase. There are two types of devices that can be in your
zapata.conf. Telephone lines, and analog phones. Remember an FXO is for a analog
telephone line. For now we'll just deal with that to keep things simple. Here's a
zapata.conf that should work for your one line TDM400P card:

context=incoming
signalling=fxs_ks
echocancel=yes
echocancelwhenbridged=yes
relaxdtmf=yes
rxgain=1.5
txgain=1.5
immediate=no
busydetect=no
callprogress=no
musiconhold=default
usecallerid=yes
callerid=asreceived
channel => 1

Now you're gonna be intimidated by all this telephony gobbledigook, for sure. To
tell you the truth, I don't know what every single one of those lines is for. As I run
into issues, I research each one. There are three lines that I will comment on though.
The context line has a name 'incoming'. Remember this name, as it links us to a
configuration *SECTION* in the extensions.conf file. Also the signaling line. It
looks wrong, but despite the confusion, it is right for your TDM400P with one FXO
interface. See other Asterisk technical documents for details on this. Also important
is the last line, channel. Remember you included one FXO device, so it's channel
one, if you had more this number would correspond to the port on that card.

And now the file which initially will boggle your mind, but eventually you will
grow to love and dream about, the extensions.conf. This is where all the exciting
stuff happens. What to tell the caller the time and date, you can do that here, play an
intro message, record a gsm file, or more importantly tell asterisk which phones
(SIP or analog) should behave as which extension.

This configuration file was originally based on these files, though I've made a lot of
changes.

[globals]

[extensions]

; example of recording gsm file

;
exten => 12,1,Wait(2)
exten => 12,2,Record(/tmp/asterisk-recording:gsm)
exten => 12,3,Wait(2)
exten => 12,4,Playback(/tmp/asterisk-recording)
exten => 12,5,Wait(2)
exten => 12,6,Hangup

; attendant reads back date + time then hangs up

;
exten => 13,1,DateTime()
exten => 13,2,Wait(1)
exten => 13,3,DateTime()
exten => 13,4,Hangup

; attendant reads back calling phone # then hangs up

;
exten => 14,1,Wait(1)
exten => 14,2,SayDigits(${CALLERIDNUM})
exten => 14,3,Wait(1)
exten => 14,4,SayDigits(${CALLERIDNUM})
exten => 14,5,Hangup

; access the voicemail system by using extension 15

;
exten => 15,1,VoicemailMain
exten => 15,2,Hangup

exten => 23,1,Answer

exten => 23,2,Wait,1
exten => 23,3,mp3player(/usr/src/asterisk/sounds/fpm-calm-river.mp3)
exten => 23,4,Wait,20
exten => 23,5,Hangup

[incoming]

; Incoming calls from digium card (channel 1)

;
exten => s,1,Answer
exten => s,2,DigitTimeout(10)
exten => s,3,ResponseTimeout(20)
exten => s,4,Background(vm-extension)

; hangup if caller does nothing

;
exten => t,1,Hangup

; incoming calls can use extensions

;
include => extensions

There's a lot going on here, so I'll explain things at a high level. First off, this file
only manages INCOMING calls right now. We have not configured any phones to
call OUT with yet. First thing, fire up asterisk, and then make a call into your PBX
from another phone, perhaps a cellphone.

For right now, you will just here the attendant say "EXTENSION?". Enter one of
the extensions. Extension 12 in our configuration will record a gsm audio file which
can be used with Asterisk, as we'll explain later. With extension 13, the attendant
will read back the date and time, and with 14 they will read back the calling phone
number. Extension 15 will take you to the voicemail system, which is menu driven,
and similar to other telephone based voicemail systems you've used, perhaps with
your cellphone provider. Lastly we've included extension 23 as a sample of how to
play an mp3 music file.

Configure a SIP Phone

Now that you have seen how incoming calls work, we'll configure a phone to work
with Asterisk. I prefer to use an SIP phone here, as it doesn't complicate the zaptel
configuration. If you want to add an analog phone, you'll first add the FXS module
to your TDM400P, then add a line for that in the zaptel.conf, do the modprobes as
before, and then add some lines in your zapata.conf. There are plenty of documents
to describe this, refer to VOIP-Info for more information.

Ok, SIP phones. I used the Grandstream Budgetone 101 which can be had for as
little as $65. To get this phone to work (after you plug it into your local network)
you'll be doing three things. You will need to let Asterisk to know about the phone
by editing the sip.conf file, configure the phone itself through it's web interface, and
lastly you will need to configure the extensions.conf file to use the phone to make
outgoing calls.

Ok, so fire up your editor, and edit your sip.conf file:

[general]
port=5060
bindaddr=0.0.0.0
tos=lowdelay
disallow=all
allow=ulaw
context=INVALID

[21]
type=friend
#host=192.168.0.15
host=dynamic
musiconhold=default
context=local-access
canreinvite=no
qualify=300
callerid="Budgetone 101 SIP Phone" <21>
mailbox=21
nat=yes

The important things here are the [21] which indicates the login for the phone (see
IP Phone config below), and also the context line. The string 'local-access' indicates
where configurations for this phone go in extensions.conf. This works similar to
how the context of 'incoming' in the zapata.conf file takes you to the 'incoming'
section of the extensions.conf file. The host line of 'dynamic' means use DHCP. I
had some confusing results with this line, so check the wiki or the asterisk-users
email list for the official word. I found a wiki page specific to the Budgetone 101.

Ok next up, you want to bring up the web-based configuration for the Budgetone
101. You can find out the IP address that the phone was given (configured for
DHCP by default) by just using the MENU button on the phone itself. Use the
arrows to get to that item, and note the IP address. Then point your browser there.
The default password is 'admin'. The only fields I changed (well besides changing
the default password!!) is the SIP Server, which is the IP address of your Asterisk
box, the SIP User ID which I set to '21' and the Authenticate ID which I also set to
'21'. Then click 'update' at the bottom, go back to the begining again, login again,
and then click 'reboot'. The phone light should blink on, and you should be good to
go.

Last up is the extensions.conf file. You need to add a section for outbound calling
using the SIP phone, and inbound calls *TO* your sip phone. Remember all the
extensions we created before were sort of virtual, merely performing some function,
and then hanging up.

Here's what I have for incoming calls to the SIP phone:

exten => 21,1,Dial(SIP/21,20)

exten => 21,2,Voicemail(u${EXTEN})
exten => 21,3,Hangup
exten => 21,102,Voicemail(b${EXTEN})
exten => 21,103,Hangup

Add these lines in with the other extensions, perhaps before 23, be sure it goes
ABOVE the [incoming] line. And lastly, at the end of the file add these lines:

[local-trunks]
exten => _9NXXXXXX,1,Dial(Zap/1/${EXTEN:1})
exten => _9NXXXXXX,2,Congestion

exten => _9NXXNXXXXXX,1,Dial(Zap/1/${EXTEN:1})

exten => _9NXXNXXXXXX,2,Congestion

[local-access]
ignorepat => 9 ; Continue dialtone after 9 on zap devices
include => extensions
include => local-trunks ; Access to Local numbers

Ok, now restart asterisk (restart now from the CLI), or to be absolutely sure, use the
kill command, and start it again. Pickup your Budgetone 101 handset, you should
hear dialtone, and the little ethernet rj45 jack symbol should be visible in the upper
left corner. Try dialing the same extensions you dialed before. Now you're internal
(you're not on your cellphone, dialing into the asterisk box from a POTS line). Now
dial 21, you should get voicemail with the busy message. Now use your cellphone,
and dial into your asterisk box again. When asked for extension, enter 21. Do you
hear your Budgetone phone ringing? Let it ring and ring, voicemail should pickup,
but this time you get the unavailable message! Congratulations, you're grooving
with Asterisk!

One more thing I did was create a new intro message. Use extension 12 to record a
GSM message "Welcome to Heavyweight Internet Group, use extension 10 for
Susan, 11 for Jimbob, and 12 for Nadia". Now you'll find a file /tmp/asterisk-
recording.gsm, rename it to iheavy-welcome.gsm, and copy it to
/var/lib/asterisk/sounds. Lastly edit your extensions.conf file one more time, and
change this line:

exten => s,4,Background(vm-extension)

to this line

exten => s,4,Background(iheavy-welcome)

Back to the asterisk command line enter extensions reload. Call into your asterisk
box to hear your brand new welcome message!

Conclusion

There are millions of other cool and exciting things you can do with Asterisk such
as having different welcome messages for different times of day, company
directory, music on hold, and so on. I recommend reading through the wiki to find
more specific information for your setup. Perhaps you can get Asterisk to talk
directly to a VOIP provider that supports IAX (Inter-Asterisk eXchange) protocol
instead of SIP. Find out more on this voip providers page. You may want to
consider getting a switch if you're going to be handling a lot of calls.

For more interesting discussions on VOIP, I recommend Om Malik on Broadband

and the VOIP weblog as two places to find interesting VOIP discussion. And lastly
the most important resource related to Asterisk is the insightful and volumous
asterisk-users email discussion list. A good dose before breakfast makes for a fine
day!

Questions about this piece, email me at: shull at iheavy dot com