Monthly Archives: October 2005

This is the second in our series of articles showing how to deploy a Bluetooth Proximity Detection system with Asterisk®@Home. Part I is here. When we’re finished, your system will automatically transfer incoming calls in your home or office to your cellphone or any other phone whenever you leave home base carrying your bluetooth-enabled cellphone or your bluetooth headset. You’ll recall that we recommended the headset approach because cellphones have a nasty habit of putting themselves and their bluetooth adapter to sleep when you’re not on the phone. If bluetooth on the phone is sleeping, we lose our ability to detect your comings and goings so be reasonable and do it our way. Use a bluetooth headset. Once you remove the earpiece, the bluetooth headset fits comfortably in your pocket and isn’t much larger than a flash drive. For our purposes the bluetooth headset will be functioning primarily as an electronic key although there’s no reason you can’t also use it in conjunction with either your bluetooth cellphone, or a softphone connected to your primary Asterisk@Home PBX, or all of the above. The major difference in our approach and some of the other proximity detection systems which (still) are on the drawing boards is cost. Our bluetooth headset "key" costs roughly $30 delivered to your door. Most of the corporate dream systems require a $200 badge (to do the same thing) and then an incredibly expensive server (to do what we’re doing with an old clunker PC). So, yes, open source technology is a very good thing for all of us. And it deserves your financial support. Here’s a link if you’d like to make a contribution in any amount to the Asterisk@Home project. End of sermon.

NOTE: This article has been updated. For the current article, click here.

Installing Asterisk@Home. Today, we need to do a lot of the grunt work to get our system configured with the necessary software to support proximity detection. You’ll recall from the previous article that we’ve decided to use the Asterisk@Home 2 beta build for this project because we need Linux CentOS/4 that’s included to make everything work. So Step 1 is to download and install the Asterisk@Home 2 beta. From our previous Asterisk@Home installation tutorial, you’ll recall the drill involves downloading the .iso image, burning a CD, finding a clunker PC with a hard disk you don’t mind wiping clean (a WalMart special (inset) oughta work just fine!), booting from the install CD after connecting the new PC to your network behind the same firewall as your primary Asterisk@Home system, and then answering a few prompts. If you need a refresher course, review the original installation article or visit the new Asterisk@Home Wiki. Once you get Asterisk@Home 2 up and running, you need to secure your system as outlined in the above article. And then review the security article that will tell you how to lock down MySQL. Now run yum -y update to get CentOS/4 current, and you’re all set. Finally, a word about the beta itself. Some folks get nervous about using beta software. Don’t. Remember, we’re only using Asterisk@Home 2 for proximity detection at this juncture, and nothing in CentOS/4 is beta. By the time we get everything working, the full-blown Asterisk@Home 2 product will probably be on the street, and you can repeat this drill in your sleep to get ready for our next mega-project: Building A Redundant Asterisk@Home System.

Overview. Now that we have Asterisk@Home 2 up and running, we need to do a couple of additional Linux things. First, we need to add the Linux bluetooth software to your system. And then we need to install WebMin, the Linux answer to the Swiss Army knife. Once we get our software configured, we’ll plug in our dLink DBT-120 bluetooth adapter and take our new system for a spin. We’ll test our ability to detect other bluetooth devices such as a bluetooth-enabled cellphone or a bluetooth headset. Then we’ll be ready for Chapter 3 where we’ll actually start telling our primary Asterisk server when we’re IN and when we’re OUT.

Installing Linux Bluetooth Software. For the remainder of this article, we’re going to be working exclusively with your new Asterisk@Home 2 beta system so, when the instructions say to do something on your Asterisk box, that means on your Asterisk@Home 2 beta system not your primary Asterisk@Home PBX that is handling your phone calls. Log in to your new Asterisk box as root.

For those using Asterisk@Home 2.0 beta 6 or later, the bluetooth software comes preinstalled with CentOS 4.2 so you can skip this next download and install step. If you have an older version of the Asterisk@Home 2.0 betas, then, to download and install the bluetooth software for Linux, issue the following command:

yum install bluez-libs bluez-pin bluez-utils bluez-hcidump bluez-utils-cups

Your system will alert you that there are some dependencies and ask if you want to download them as well. Answer ‘yes’ and the download and install should proceed without incident. Once everything finishes, plug in your dLink DBT-120 USB bluetooth adapter and restart your system: shutdown -r now. When your system reboots or if you’re running beta 6 or later, log in as root and issue the following command:

/etc/init.d/bluetooth restart

You’ll probably be told that your system couldn’t stop bluetooth (because it wasn’t running) and then it’ll restart. Now let’s make sure everything is running that should be:

/etc/init.d/bluetooth status

You should see messages that look like this:

hcid (pid somenumber) is running ...
sdpd (pid somennumber) is running ...

If you’re alerted that some other application isn’t running, we don’t care. Now let’s be sure the system has found your bluetooth adapter:

hcitool dev

You’ll get a response telling you the system found device hci0 with the MAC address of the adapter. If you have a bluetooth-enabled cellphone, go get it now and be sure it’s on with bluetooth-enabled and not in sleep mode. Now issue the following command:

hcitool scan

The system will whir away for a few seconds and then will report back the bluetooth name assigned on your cell phone. It’s probably your name. Didn’t know you were advertising, did you? Note: you can’t do this with a bluetooth headset, but we’ll get to that in a minute. There are two ways to automatically start the bluetooth software when you boot CentOS. We’ll show you both, but you’ll probably want to install WebMin for future use anyway. The quick and dirty method is to run setup while logged in as root. Use the down arrow key to highlight System Services and press ENTER. Now use the down arrow to move down to bluetooth. Then press the space bar. Tab to the OK button and press ENTER. Now tab twice to the Quit button and press ENTER. Restart your server and you’re all set: shutdown -r now.

Let’s take a bluetooth break and install WebMin. We’re doing this primarily to show a simpler way of auto-enabling bluetooth at startup, but you’ll find lots of other uses for WebMin down the road.

Installing WebMin. There are lots of ways to install WebMin. We prefer the easy way which is to issue the following commands at a Linux prompt after logging in as root. Note: WebMin updates come out all the time. If you want to be sure you start with the latest and greatest version, go to their web site first and write down the number of the current version. Then substitute it below when issuing these commands:

cd /root
mkdir webmin
cd webmin
wget http://unc.dl.sourceforge.net/sourceforge/webadmin/webmin-1.240-1.noarch.rpm
rpm -Uvh webmin*


WebMin runs its own web server on port 10000. To start WebMin, issue this command: /etc/webmin/start. You access it with a web browser pointed to the IP address of your Asterisk box at that port address, e.g. http://192.168.0.108:10000. The login name is root. Then type in your root password and press enter. The main WebMin screen will display. Before we forget, we need to also make one change to the new Asterisk@Home configuration to avoid problems down the road. The default RTP listening ports for Asterisk@Home are 10000 to 20000 so there’s a conflict on port 10000. We just need to change it to 10001. Log in as root and, using an editor, call up the rtp.conf file: nano /etc/asterisk/rtp.conf. Now change the rtpstart port from 10000 to 10001 and save the change: Ctrl-W, Y, and press Enter.

Now back to WebMin. From the Main Screen of WebMin, click the System button and then the Bootup and Shutdown link. Find bluetooth in the list of applications and click on it. The Action Details screen should show that bluetooth is running. Now click the Yes button beside "Start at Boot Time?" and then click the Save button to reconfigure your server. That wasn’t hard, was it? We can stop WebMin now by issuing the following command: /etc/webmin/stop. No need to waste processing cycles for a tool we’re not using.

Configuring a Bluetooth Headset for Proximity Detection. As we mentioned in our first article, our device preference for the proximity detection project is a bluetooth-enabled headset. The two least expensive ones (about $30 including shipping) are the Plantronics M3000 if there are any left and the IOgear GBE201W7 from Buy.com. Remember, we’re going to be using the headset primarily as a "key" to tell Asterisk when we’re home and when we’re not. Cadillac charges about $400 for their electronic keys so this one’s a bargain. You obviously can use it for other stuff, too, but for now let’s get our "key" working. The hardest part of this drill is figuring out the MAC address of the headset. If yours happens to have 12 hex digits written on the box, lucky you! Otherwise, the only trick here is to put your headset in discovery mode. On the M3000, you activate discovery mode by simultaneously holding down the UP volume and Command buttons for about two seconds. When the light begins alternating between red and green, let go. With the IOgear unit, turn off the device and then hold down the multi-function button for about nine seconds. The red LED will turn on and then the blue LED will begin rapidly flashing. If only the blue LED is lit, you screwed up. Try again. Now from a Linux command prompt in close proximity to your headset, issue this command:

hcitool scan

You’ll get a response that looks something like one of the following:

Scanning ...
00:03:89:43:84:E2 M3000 by Plantronics
00:0e:a1:21:39:fc IOGEAR BT Headset


Write down the MAC address of your headset including the colons between the hex code digits. This is the notation we’ll be using to actually check whether your headset is within range. Here’s the command so try it out substituting the MAC address of your headset for mine below:

hcitool name 00:03:89:43:84:e2

Now run the command again and change the last digit of the MAC address to another hex number:

hcitool name 00:03:89:43:84:e6

There are two important points here. First, with the hcitool name syntax, the headset does not have to be in discovery mode which is just what we need for our proximity checking. And second, you’ll notice you got the device name when hcitool could find the headset and a null string when it couldn’t. So we can use a simple Linux bash script to determine whether your headset is within range by just checking whether a null string is returned to the above query. Wouldn’t you think some commercial developer could have figured this out and included it in their highly touted Proximity Checking products? Apparently not.

We’ll leave you with a simple script today to play with until we tackle Chapter 3. This script implements what we’ve just demonstrated. All you need to do is create a new file in the /tmp directory of your new Asterisk server: nano whereib. Then cut-and-paste the code below and modify the MAC address shown for deviceid= to match your headset. Then save the file: Ctrl-X, Y, and press enter. Now make the file executable: chmod 755 whereib. And then run it: ./whereib. Once it’s running, turn on your bluetooth headset and walk around your home or office. Then come back and check the display. It should report when you’re in range and when you’re not. I think you’ll be pleasantly surprised by the range of your bluetooth devices so the basement furnace room may not be a bad location for your new server after all. You can end the script by pressing CTRL-C. In our next article, we’ll wrap up the bluetooth proximity series with Chapter 3 where we’ll get everything connected up to your primary Asterisk server which will handle the actual call forwarding when you’re away from your home or office.

#!/bin/bash
# Syntax: ./whereib
# On a clunker PC it takes about 20 seconds for a test to fail
# and it takes about 5 seconds for a test to succeed, i.e. BT MAC found

count=0
while [ $count -lt 1 ] ; do
hcitool name $deviceid > /tmp/$devicename
if [ -s /tmp/$devicename ] ; then
echo $devicename IN RANGE ;
date
else
echo $devicename OUT OF RANGE ;
date
fi
sleep 7
done


Some Interesting Bluetooth Reads. Here are a few articles to give you an idea where all the bluetooth proximity detection stuff is headed. If it’s good enough for Bill Gates’ home, it’s good enough for yours.

Other Asterisk Tutorials. There are numerous additional articles in this Asterisk HOW-TO series to keep you busy. You can read all of them by clicking here and scrolling down the page. We recommend reading at least the first four or five articles from the bottom up so that the learning curve is less painful. Then you can skip around to your heart’s content.

This is the first in a series of articles that will provide step-by-step instructions for implementing Bluetooth Proximity Detection. We’re going to focus on using it with Asterisk®@Home, a terrific PBX which also happens to be free. But your imagination is really the only limitation. At the very least, when we’re finished, you’ll be able to walk out of your home or office carrying your bluetooth phone or headset and have your Asterisk server automatically transfer your incoming calls to your cellphone. And, when you return carrying your bluetooth phone or headset, Asterisk will automatically cancel the call transfers and reactivate delivery of incoming calls to the designated phones in your home or office. As simple as this concept may sound, the devil is in the details. So we want to spend today warning you of all the minefields that lie ahead and telling you what hardware you’ll need to make things work. If you hurry, you can implement the whole system for just over $50, and we’ll show you how to do it without even owning a bluetooth cellphone. In subsequent articles, we’ll put the pieces together and get a basic system working. Then we’ll add more bells and whistles and give you some implementation and deployment suggestions. You’ll quickly come to appreciate how Bluetooth Proximity Detection can be used to implement all sorts of other features. When we’re finished, you’ll also appreciate the potential of bluetooth to revolutionize the workplace. And it goes far beyond your phone system. Imagine an automated IN/OUT message board in businesses such as real estate or the advertising potential to tailor TV display ads in stores based upon not only your presence but also the type of cellphone you are carrying. Your office can even kiss its old punch clock goodbye when we’re finished. For those with new Cadillac or Mercedes automobiles, you can unlock your car and start it just by approaching the vehicle with your "key" still in your pocket. So where do we start?

NOTE: This article has been updated to take advantage of TrixBox, freePBX, and the iPhone. For the current article, click here.

Overview. The basic idea behind proximity detection is that we run a software application on a computer to "watch" for approaching people. We then want it to do something when you (or a customer) gets within range. How do it know? Well, in our case, this is where Bluetooth comes in. Unlike motion detectors which can’t tell the difference between a human and a gorilla, bluetooth devices all have a unique MAC address just like a network card. And most bluetooth devices also have a name. So long as the bluetooth device is configured to advertise its presence, we can detect when it is within range and when it’s not. That’s the second major difference between bluetooth and traditional motion detectors. Ever been in a public restroom or an office when all the lights went out because everybody was sitting too still for too long? So motion detectors have some limitations. Bluetooth doesn’t. In case you’ve been living under a rock for the past six years, bluetooth is a wireless communications protocol that uses short range radio frequency to connect devices into wireless personal area networks (PANs). The most common Class II 2.5mW devices have a range of 32 feet (10 meters). Class I devices have a range of up to 100 meters. Most bluetooth cellphones, headsets, and computer peripherals such as mice and keyboards are Class II devices. If you want more background, go here.

Prerequisites. For our proximity detection project, we’re going to connect a bluetooth network adapter to an Asterisk@Home box and make it our master. That simply means we’re going to use this network adapter to look for other bluetooth devices within range. The only limitation is you can’t have your Asterisk@Home box shoved in a closet in the basement if you want this to work. It will need to be within 30 feet or so of where you’ll be when you’re at home or in the office. If this doesn’t work for you, then here’s an alternative. Just get in the habit of putting your cellphone or bluetooth headset down near your Asterisk@Home box when you’re "in" and take it with you when you’re "out." Many offices, particularly in the real estate business, have a receptionist with agent mailboxes immediately beside or behind the receptionist desk. Just put your Asterisk box with its bluetooth adapter under the receptionist’s desk and leave your cellphone or wireless headset in your mailbox whenever you return to the office. The adapter we recommend which is quirk-free is dLink’s DBT-120. You can find them on the net for about $30, but you can usually beat that price by watching the Sunday circulars for computer and office depot/max stores in your area … if you don’t mind mail-in rebates. But, do you really want the PBX for your whole office sitting under the receptionist’s desk? Probably not. But don’t worry, we’ve got some other tricks up our sleeve so keep reading.

We keep mentioning a headset so we won’t keep you in suspense any longer. You don’t need a bluetooth cellphone to make our proximity detection project work. A bluetooth wireless headset works just as well. In fact, it works better! And you’ll have a great addition to your computer system and cellphone as an added bonus. Cellphones have a nasty habit of putting themselves in sleep mode very quickly when not in use to conserve battery power. The only problem is that most, if not all, cellphone makers turn off the bluetooth adapter when they activate sleep mode because they’re all so short-sighted that the only thing they think you use bluetooth for is to talk to your wireless headset or exchange files with your PC. Stupid! Bluetooth headsets on the other hand are always on listening for a call. The one we like has a rated standby time of 200 hours between battery charges so it’s perfect for this project. These devices typically cost anywhere from $50 to $100 but, if you hurry, there’s a vendor selling our favorite, the Plantronics M3000, for under $20. Here’s the link at PriceGrabber. Don’t wait. They’re never this cheap, and this vendor only has 50 of them. And Buy.com has a similar unit from IOgear for about the same price once you factor in the cost of shipping. Will you need to wear your bluetooth headset and look like a Nerd to make this work? Not at all. Just turn it on, stuff it in your pocket, and call it a key.

Now let’s address the computer issues. First, your machine obviously needs USB adapter support so you have a place to plug in your bluetooth adapter. Second, we need a machine that can run software that can detect bluetooth devices. Having spent a week scouring the Internet and testing various products which touted their bluetooth proximity detection, let me save you some time. If you are fortunate enough to have a Sony Ericsson phone with bluetooth, some of the commercial products such as BluePhoneElite for the Mac or Salling Clicker for Mac or Windows work great for proximity detection. There’s even an open source product, Romeo for the Mac, that works. If you have a single-tasking Palm device including the Treo 650 cellphone, don’t waste your time. And bluetooth headsets aren’t detected at all by any of the products. This is primarily because proximity detection was considered a gee-whiz extra in most of these products so it’s not implemented very well. The good news is that, if you happen to have a bluetooth cellphone that does work with one of these products, it might make proximity detection more practical because you could handle the proximity interaction with your desktop machine instead of with your telephone system’s PBX. But, who cares. We just want it to work.

So where does that leave us on the computer front? The bottom line is you’re going to need a Linux machine and a fairly current version of the Linux operating system to get the bluetooth tools installed that we need. As luck would have it, the new Asterisk@Home 2.0 beta release works great … and it’s free. And it automatically installs CentOS/4, the free knock-off of RedHat’s commercial Enterprise Linux 4. Because Asterisk@Home is free and will run on any old clunker PC, you may want to install the Asterisk@Home 2.0 beta on a dedicated machine and just use it for proximity detection. This solves the colocation problem with your main PBX, and it has the added benefit of reducing the load on your primary Asterisk server. The other terrific benefit of this approach is you’ll have a hot standby system for your main PBX, and we’ll integrate that into our tutorials one of these days, too. When your one and only Asterisk@Home box dies, do you really want to be without phone service? Keep in mind that proximity detection also takes some horsepower because we’ll be running a script once a minute to see who’s in and who’s not. And, no, Asterisk@Home 1.5 won’t work. Believe me, we’ve tried and it was just about as frustrating as trying to use a Treo 650 for proximity detection. A total bust!

Well, that covers the basics and provides you the information you’ll need to start assembling the pieces for the proximity detection project. We’ll leave it to you to get your bluetooth hardware ordered and to get your Asterisk@Home 2.0 beta up and running before moving on to Chapters 2 and 3.

Some Recent Nerd Vittles Articles of Interest…

This is the second in our two-part roundup of the best unlimited calling plans for Asterisk®. You can read the first installment here. The number of options for Asterisk residential users wanting an unlimited international calling plan has fluctuated between zero and one depending upon how brave you were in dealing with BroadVoice's Terms of Service. Frankly, we've pretty much written off BroadVoice's so-called unlimited international calling plans for residential use because of the number of backbilling complaints logged on the Voxilla Forum.

Finally, there's not only some competition but also a ray of hope. Axvoice Inc. has recently announced two new unlimited residential calling plans with full bring-your-own-device support for Asterisk. An $18.99 plan provides unlimited calling within the U.S. and Canada. Spending $4 more buys you unlimited calling within the U.S., Canada, and all or parts of the following countries: Buenos Aires, Argentina; Australia; Chile; Denmark; France; Germany; Hong Kong; Ireland; Israel; Italy; Monterey and Mexico City, Mexico; Netherlands; Norway; Moscow and St. Petersburg, Russia; Singapore; South Korea; Spain; Sweden; Taiwan; United Kingdom; and Vatican City. As usual, mobile, premium, and special numbers are not included in the program. The fine print places a 4,000 minute usage cap on residential service before it is considered business use. This seems more than reasonable considering that such a number gives the residential user over two hours of free calls per day, every day of the year. Stated another way, the $22.99 international calling plan provides up to 4,000 minutes of calling per month to 24 countries for an average per minute cost that works out to just over a half cent a minute. Compared to the BroadVoice approach which leaves you guessing (at your financial peril) what the usage caps are for their various unlimited* calling plans, the Axvoice approach is a breath of fresh air. If you need to stretch your minutes and receive significant numbers of incoming calls, you can supplement your all-you-can-eat plan with a BYOD plan featuring unlimited, free incoming calls for $8.99 a month. Or you could simply add another all-you-can-eat plan for an additional 4,000 minutes. You can't beat the price, and all of Axvoice's plans include two free incoming DID numbers from a broad selection of area codes within the U.S. and Canada. Currently Axvoice is waiving the $9.99 setup fee for bring-your-own-device users. How do the calls sound? Ours sound great. Your mileage may vary. But you can try it for yourself with their 30-day money-back guarantee. So you really have nothing to lose by trying out their service. And, if you stay with Axvoice, all of their bring-your-own-Asterisk plans are month to month so there are no long term commitment issues.

The equally important question for Asterisk users is always the same. Does it work well with Asterisk? Again, the good news is that, once configured, Axvoice and Asterisk are a match made in heaven. In fact, Axvoice uses Asterisk at their end so you wouldn't expect anything less. Axvoice is a relatively new company, but you'll notice some marked differences from BroadVoice if you've endured BroadVoice support with their long waiting times and frequent disconnects while on hold. I think I was one of the first home users that wanted to set up Axvoice service with Asterisk so I can't say it was painless, but I can pretty much assure you that the process will be close to painless for you. We wrote down the answers! At least as this article goes to press, when you sign up on their site, you won't be greeted by much of any documentation pertaining to Asterisk configuration. All that's about to change if you keep reading here. Again, they're a new company, and we pretty much knew going in that it probably would be a bumpy ride. At least for the first three days, we weren't disappointed. The good news is that email inquiries always were returned with a helpful answer within an hour or so. And calls to their toll-free number were answered in less than a minute both during the business day and at night. You really couldn't ask for much more.

I think it would be fair to say that Axvoice's typical customer up to now has pretty much been like Vonage's, dumb as a brick about technology and looking for a good deal on an unlimited VoIP calling plan. So, when you call for customer service, the typical first response is to inquire about your router/firewall. And they fully expect you to answer by saying, "What's that?" Unlike Vonage, Axvoice fully supports Asterisk with an open SIP configuration. But it took some perseverance to get to the person who knew the answers. Some of the first-level customer service reps were having a difficult time both with English and trying to understand that we, too, had an Asterisk server ... at our home. "Really?" was a typical response. Once we got by all of that, the Asterisk configuration information was detailed and to the point. The other wrinkle we experienced had to do with their support for the G.729 codec. We only have one license which may have been the problem. Outgoing calls with G.729 worked fine, but incoming calls that first hit our AutoAttendant and then get transferred to a default extension lost the outgoing part of the audio. This may be because Asterisk treats the two voicepaths (incoming and the answering extension) as two separate channels requiring two, rather than one, G.729 license. When payday rolls around, we'll splurge for another $10 G.729 license from Digium®, and let you know the results. In the meantime, the default ulaw codec works great.

Configuring Asterisk Trunk for Axvoice. Assuming you decide to take the dare and sign up for a test run, what you're going to need to get Asterisk running with Axvoice is your account ID (not a phone number) and your password. If you've followed along in our previous Asterisk@Home tutorials, then the process to set up Axvoice will be familiar. Be sure UDP ports 5004-5082 and 10000-20000 are opened on your firewall and pointing to your Asterisk server. We'll create a trunk for Axvoice and then add Axvoice to our dialplan to take advantage of their calling plan. Using the Asterisk Management Portal, goto AMP->Setup->Trunks and Add a New SIP Trunk. You can leave the CallerID field blank since this is configured on Axvoice's web portal. For maximum channels, enter 2. For Outgoing Dial Rules, enter the following but be aware that this dialplan will allow international calling to many country codes that are NOT free under the Axvoice unlimited international calling plan. If this is a problem in your household, you'll need to make your dialplan much more country-code specific.

1+NXXNXXXXXX
1NXXNXXXXXX
011X.

For Outgoing Settings, name your trunk axvoice and then enter the following Peer Details substituting your username (3 entries) and password (1 entry) where appropriate:

allow=ulaw
authname=yourusername
canreinvite=no
context=from-sip-external
defaultip=sip.axvoice.com
disallow=all
dtmfmode=rfc2833
fromdomain=sip.axvoice.com
fromuser=yourusername
host=sip.axvoice.com
insecure=very
nat=yes
secret=yourpassword
type=friend
user=phone
username=yourusername

Leave the Incoming Context and Details blank. Enter your registration string as follows using your actual username and password. Then save the trunk and click the red bar to reload Asterisk.

yourusername:yourpassword@sip.axvoice.com

You will recall from our previous article on the subject that the [from-sip-external] context passes incoming calls to our Stealth AutoAttendant for processing. So Axvoice incoming calls will be handled in the same way as incoming calls from your other PSTN and VoIP trunks.

Adjusting Outgoing Dialplans for Axvoice. To adjust your dialplans to take maximum advantage of Axvoice, choose AMP->Setup->Outbound Routing. Then for your Local, InState, TollFree, and US dialplans, edit each of them and Add the SIP/axvoice trunk. Then use the arrow keys to move Axvoice to the top of each list. You'll also want to add a new International route with the following Dial Pattern: 011X. which designates all calls beginning with 011 and at least two more digits as international calls. Now choose SIP/axvoice as your one and only trunk for international calls. If you want a fallback trunk, Voxee would be our recommendation. They have incredibly low per minute rates. Now save your trunk settings and leave the international dialplan at the bottom of your list of Dialplan Routes.

Making a Test Call Using Axvoice. To be sure everything is working swimmingly, start up Asterisk in interactive mode using the Command Line Interface (CLI) so that you can actually watch what's happening when calls are placed and received. This works best if you connect to your Asterisk server through SSH from a Mac or PC. SSH comes with every Mac and the syntax is simple: ssh root@AsteriskIPaddress. If you're still chained to Microsoft, download Putty from the Mother Country, and you can do the same thing using a Windows machine. Once you're logged in as root, issue the following command: asterisk -r. Quit ends your Asterisk CLI session, and exit logs you out of your SSH session. Now issue the command: set verbose 10 to get maximum information. Then place a U.S. or international call and watch what happens. You should see something similar to the following which shows that the call was placed using the new axvoice trunk:

-- Called axvoice/18435551212
-- SIP/axvoice-2cbf is ringing


Asterisk: The Future of Telephony. O'Reilly Publishing finally released a great book on Asterisk last week. The book is available directly from the publisher or from Amazon. In addition, O'Reilly is providing the PDF version at no cost under a Creative Commons License. It's a carefully written book and an easy read for beginners as well as those with lots of Asterisk miles under the belt. It does not cover Asterisk@Home. And what more can we say about O'Reilly Publishing. O'Reilly is simply one terrific company that just keeps getting better! Some other Asterisk books are now available as well. You can read all about them here. And at least one Asterisk@Home book is currently under development ... not from us. We don't do books. You can always tell when a new technology is really taking off by watching for book publications. For those that have been following these tutorials, I think you understand why Asterisk is finally earning its rightful place in the limelight.

Other Tutorials. There are numerous additional articles in this Asterisk HOW-TO series to keep you busy. You can read all of them by clicking here and scrolling down the page. We recommend reading at least the first four or five articles from the bottom up so that the learning curve is less painful. Disclaimer: As we have mentioned previously, we typically sign up for referral credits when we try out a new VoIP service. If our referral credit links give you heartburn, don't use them. We do it to help defer costs of this column. It doesn't influence our views of the providers as you probably can tell from our discussions of BroadVoice. They too have a referral credit program, and we still don't like their current terms of service. Fortunately, thanks to Axvoice, international callers finally have another viable unlimited calling plan option.

Coming Thursday: AsteriDex -- The Poor Man's Rolodex. We're excited about our latest free software offering and think you will be, too. AsteriDex is a web-based application that lets you store phone numbers of all your friends and business associates in a simple-to-use MySQL database. But, it's much more with Asterisk! Just call up the application in your favorite web browser from anywhere and click on the contact you want to call. AsteriDex will first call you at the number you've designated for this contact, and then AsteriDex connects you to your contact through an outbound call made using your Asterisk server. For those lucky enough to have GrandStream's GXP-2000 IP phone with AutoAnswer, you can even configure AsteriDex to automatically activate the speakerphone and then place the call to the contact you've selected. In short, it works exactly like Microsoft's TAPI software without the configuration nightmare or your favorite (required) Micro$oft bloatware. Installation and configuration for your Asterisk@Home system is a snap and takes less than 10 minutes. It also works with vanilla Asterisk running the Asterisk Management Panel (AMP) software. Someone is probably saying, "Can't you do the same thing with CRM?" Well, yes and no. If you need full-blown contact management, then sure you can. Just be sure to save an extension for the account you are using to log in using the format sip/204. CRM will dial out using your default Asterisk outbound dialing rules, and it works great. But be prepared to spend several months getting all your contact information entered. AsteriDex is quick to implement and simple to use because it only does one thing: places calls for you using a web interface to all your favorite callees. The software is distributed without charge pursuant to the Creative Commons License.

The real payoff for installing that fancy Asterisk PBX in your basement comes when you’re on the road and want to make free phone calls either to or through your home system. There are probably a million ways to do this. Most of them are painful. This is particularly true with SIP-based telephones and all the problems associated with configuring NAT and firewalls and STUN servers. So, as usual, we’re going to take the low road and do things the easy way. We’ll give you one solution that really works … every time! When we’re finished, you’ll have a device about the size and weight of a pack of cigarettes to carry on your trip. And all you’ll need when you arrive at your destination is a 10/100 network connection with a cable and a plain old telephone with a plain old phone cord. Once you connect the two devices, you simply pick up the phone and dial calls just as if you were sitting in your kitchen at home. And incoming calls work just as if you had added another phone in your upstairs bedroom. It’ll even flash at you when you have voicemail waiting. For those with kids in college, this is the perfect addition for the dorm room if you want to avoid cellphone hell. And the one-time, non-recurring cost: under $100.

To make all this magic work, you’ll need to purchase Digium®’s S101I, affectionately known as the IAXy Version 2, a NAT-transparent, FXS device providing a POTS telephone interface to your Asterisk® PBX using an IAX connection. You can buy one directly from Digium, the makers of Asterisk, by going here. Be sure you order it with a power adapter for your particular country. Buying the device directly from Digium is an especially good idea because you can call them should you ever have a configuration problem. Hopefully you won’t after you finish reading this article.

IAXy IP Configuration. Once your IAXy arrives, it’s configuration time. First things first. You can download Digium’s installation guide or just keep reading for a bit more hand-holding. The device needs to be connected to a network that has a DHCP server so that an IP address is automatically handed out to the IAXy when you plug it in. Before you power up the unit, plug in a plain old telephone and connect the IAXy to your router using a 10/100 network cable. Then plug in the power adapter. The hardest part of this drill is probably figuring out what IP address was assigned to the device. On most routers, you can use a web browser to access the router configuration. Usually there’s an option to display Attached Devices. Typically, the last device you plug in gets the highest IP address so take a look and write it down. Write down the MAC address of the unit, too. Luckily, you can ping the IAXy to see whether it’s alive. So, from your desktop machine, ping the IP address you wrote down, e.g. ping 192.168.0.123. If you don’t get a reply, that’s the wrong number. Try another one. If you do get a reply, unplug the IAXy and ping the same IP address again. If you get a reply, that’s obviously not your IAXy because it’s unplugged so start over. If you don’t get a reply, you’ve got the right number. Now plug it back in and do it one last time to be sure you still have the same number. Before you forget, go into your router configuration now and permanently assign this IP address to the IAXy. It’s usually named something like Reserved IP Table, and you’ll find it in the LAN IP setup screen on most routers. Finally, if your Asterisk server is behind your router/firewall, you’ll need to open UDP Port 4569 on your router and map it to the private IP address of your Asterisk server, not your IAXy. On most routers, you’ll find port mapping under a heading of Services or Rules. IAX is not a common protocol so you may need to create it. Just name it IAX, specify UDP as the protocol, choose port 4569, and save your settings. Then add a rule that maps this IAX port to the private IP address of your Asterisk machine. Whew!

IAXy Provisioning Utility. One more knuckle drill, and then it’s pretty smooth sailing. This isn’t the Windows world so you’ll need to compile the IAXy provisioning utility on your particular flavor of Linux. We use this utility to actually configure the IAXy device. Nothing here is difficult. Just follow the steps in order. Go to your Asterisk server, switch to root user access, and issue the following commands to download and compile the source code for the IAXy provisioning utility:

$ cd /usr/src
$ export CVSROOT=:pserver:anoncvs@cvs.digium.com:/usr/cvsroot
$ cvs login (the password is anoncvs)
$ cvs co iaxyprov
$ cd iaxyprov
$ make
$ chmod 775 iaxyprov


Configuring Asterisk to Support IAXy. We need to take a break here an actually set up an extension for your IAXy device to use. If you’re using Asterisk@Home or at least the Asterisk Management Panel, go to AMP->Setup->Extensions and click Add Extension. Enter the following using whatever extension and password you prefer:

phone protocol: IAX2
extension number: 222
extension password: 1234
full name: IAXY

If you want to activate voice mail for this extension, choose Voicemail and Directory Enabled and make the VoiceMail Password match your extension password. If you want email delivery of your voicemail messages, fill in the appropriate blanks. Then save your settings by clicking Add Extension. Click the Red Bar to reload your Asterisk configuration.

IAXy Configuration File. The next step is to decide where you will be using your IAXy device. If it will always be outside your firewall, then we only need to configure the device to use the public IP address of your Asterisk machine. If it will always be inside your firewall, then we just need to assign the private IP address of your Asterisk machine (assuming it’s behind your router/firewall). If you want to be able to move the device inside and outside your firewall, then we need to assign two IP addresses: the public and private IP addresses of your Asterisk server. The only other gotcha here is that if your Internet Service Provider assigns you a dynamic IP address, you will need to reconfigure the public IP address of your IAXy device every time your ISP changes your dynamic address. There is no DynDNS support for the IAXy at this time.

We’re going to initially configure your IAXy device for use inside your firewall where your Asterisk server also lives. Then we can play with it to make sure it’s working. Then we’ll walk through the steps to change the configuration. The IAXy configuration file and the provisioning utility we built earlier live in the /etc/src/iaxyprov directory on your Asterisk machine. It’s a good idea to switch to root user access whenever you work here just to keep all the files protected from snoopy people. Let’s make a duplicate of the IAXy config file just in case something gets screwed up: cp /usr/src/iaxyprov/iaxy.conf.sample /usr/src/iaxyprov/iaxy.conf. Now open iaxy.conf using your favorite editor: nano iaxy.conf. It should look like this:

;
; IAXY Provisioning description
;
dhcp
;ip: 216.207.244.130
;netmask: 255.255.255.192
;gateway: 216.207.244.129
codec: ulaw
;codec: adpcm
server: 192.168.0.1
;altserver: 192.168.0.2
user: myuser
pass: mypass
register
;heartbeat
;debug
;
; Feature tuning (default is all enabled)
;

You only need to change three items in the file. For server, replace this IP address with the private IP address of your Asterisk server. For user, plug in the extension number you assigned to the IAXy. And for pass, enter the password you assigned to this extension. Save your changes and exit from the editor: Ctrl-X, y, enter. To actually load the configuraton into the IAXy, issue the following command using the IP address assigned to your IAXy:

./iaxyprov 192.168.0.100 iaxy.conf

If there is no error in your config file, you will get a screenful of feedback from the IAXy device within about 10 seconds. Just disconnect power to the IAXy and then reconnect it, and you’re in business. If you get nothing on the screen after issuing the above command, then there is an error in your config file or your IAXy device is not connected to the network with the IP address shown in the iaxyprov command line you entered. Check your work and try again.

Reprovisioning the IAXy. Loading a new configuration into the IAXy is easy now that you know the drill. It’s always a good idea to reset the IAXy to its factory default settings before loading a new configuration. Here’s how:

Once the IAXy is restored to its factory defaults, you simply repeat the configuration steps above to reprovision the unit. To use the unit on the outside of your firewall, edit the iaxy.conf file and change the server IP address to the public IP address of your Asterisk server. Save your change and then load the new settings with the same iaxyprov command line we used above (assuming your IAXy is still plugged in behind your firewall). Note that you will not be able to test the device behind your firewall so take the unit to a friend’s house (with broadband) and try it out with any plain old telephone. If you want to use the IAXy both inside and outside your firewall, we’ve had good luck simply plugging in both IP addresses. Leave your private IP address in the server line, and uncomment the altserver line by removing the leading semicolon. Then enter your public IP address here, and reprovision the unit as previously explained.

Asterisk Dialplan Quirk. If you’re used to ringing all your phones for incoming calls, you’ll quickly discover that the addition of an IAX phone device complicated things a bit. You can’t mix and match device types in a Dial command. For example, exten => 1234,1,Dial(IAX2/277&SIP/204,20,r) won’t work. There’s a simple way to get around this limitation. Use a ring group which includes both SIP devices and IAX2 devices such as the IAXy. The syntax for the Dial command would look like this assuming 299 was your Ring Group: Dial(local/299@from-internal,20,m).

Activating MD5 password encryption. One great addition to the version 2 IAXy was support for MD5 password encryption. If you’ll be using the device in public places or hotels, you’ll want to use this. One quick change in your Asterisk configuration is all that’s required. Using AMP->Maintenance->Config Edit, edit the iax.conf file. Just add the following line in the [general] section of the file:

auth=md5

Save your change and restart Asterisk, and you’re all set to hit the road. Enjoy!

Coming Attractions. We’ve been working on another web application using Asterisk that builds on our previous CallMe application. For lack of a better name, we call this one The Poor Man’s Rolodex. When it’s soup, it will let you create a protected web page with the names and phone numbers of all your favorite people and places. Making a selection on the web page passes a command to a PHP script that talks to your Asterisk PBX. It first rings one or more phones in your home or business. Only when the call is answered does it place an outgoing call to the person or place you selected on the web page. It then automatically connects them to the phone you picked up. If you happen to have GrandStream’s GXP-2000, you can even configure that phone to go off-hook and turn on the speakerphone when the incoming call from your ‘Rolodex’ arrives. In short, this little ditty will give you everything Microsoft’s TAPI gateway provides without any of Microsoft’s proprietary baggage.

Some Recent Nerd Vittles Articles of Interest…

One of the really terrific features of Asterisk® is it’s ability using DISA (Direct Inward System Access) to provide dial tone to an incoming caller. This allows a caller to Phone Home and place outgoing calls through a remote Asterisk server to take advantage of all those VoIP cost savings we’ve been discussing ad nauseum. You obviously need to be thinking about security before you implement DISA but, properly secured, DISA is one of the most powerful functions of your Asterisk PBX so why not use it to your advantage. But there are some wrinkles. Suppose you’re traveling in a foreign country that charges a $14 minimum for any completed call to the U.S. regardless of duration. Or you may just be at a neighbor’s house and want to make a quick call on your nickel to check on Aunt Betty in Paris. Or you may be on a Nextel free incoming call plan and don’t want to burn up your cellphone minutes placing outgoing calls directly with your cellphone.

Several weeks ago, we provided a quick and dirty HOW-TO on activating a DISA callback using a web browser and entering a specific command to your Asterisk@Home’s web server. But there may be folks that don’t want the security risks associated with supporting a web server. So today we want to revisit our original Phone Home column and give you three different ways to implement DISA. The three methods are the following: (1) the AutoAttendant, (2) the CallMe Web Interface, and (3) the One Ringy-Dingy. These obviously can be mixed and matched to meet your own specific requirements.

AutoAttendant DISA. The simplest DISA implementation is to add an option to your AutoAttendant. With this option, you phone home, pay the costs of the call, and while still connected make another call through your Asterisk server by picking the DISA selection when your AutoAttendant plays. You’ll be prompted for a password and, after entering it correctly, Asterisk will provide dialtone for your use. The drawback of this option is obviously the cost, if any, of the call to your home base. If that’s not a problem, then this is a great solution. And it’s very easy to implement. Take a look at the [from-external-custom] code in our Securing Your Asterisk@Home PBX article for all the details. But basically you only need to add a couple of lines to your AutoAttendant to support DISA. Choose the number that people will press to activate DISA and pick a very secure password, and you’re all set. Assuming the number to press is 4 and your chosen password was 1234588, here’s how to set up the AutoAttendant code to implement DISA. It doesn’t get much easier than this.

exten => 4,1,Authenticate(1234588)
exten => 4,2,Background(pls-wait-connect-call)
exten => 4,3,DISA(no-password|from-internal)


CallMe Web Interface. We’ve put together a little web application (actually a PHP script) so that, using a web browser on the road, you can tell your Asterisk server to call you and provide dialtone to any number you specify. The only prerequisite here is that we don’t want to sell the farm, i.e. provide free dial tone service and unlimited international calling for all the world’s hackers and crackers. We also don’t want to have to go through a bunch of authentication steps to access the web site and put the call in motion. So here’s the design. We have a PHP script which you can download here. It needs to be renamed to callme.php. Then copy it into the /var/www/html directory on your Asterisk server. You’ll also need to tell your firewall/router to route HTTP or port 80 traffic to the internal IP address of your Asterisk server. This is usually done under the Services or Rules menus on most routers. You’ll want to specify that all port 80 traffic be allowed through the firewall all of the time. Be sure you’ve changed ALL of your Asterisk passwords before you do this!

To use this script from the Internet, you’ll probably want to have to have a more permanent fully-qualified domain name associated with your Asterisk server. We explained here how to do this using dyndns.org. If you use a SIP provider with your Asterisk server, the syntax is as follows: http://asterisk.dyndns.org/callme.php?number=sip/bv/4045551212 where asterisk.dyndns.org is the fully-qualified domain name for your Asterisk server and 4045551212 is the area code and number where you wish to accept a call with dialtone, and bv is the outgoing trunk name of your SIP provider. If you use an IAX provider with your Asterisk server, the syntax is as follows: http://asterisk.dyndns.org/callme.php?number=iax2/goiax/14045551212 where asterisk.dyndns.org is the fully-qualified domain name for your Asterisk server and 14045551212 is the all-important 1 followed by the area code and number where you wish to accept a call with dialtone, and goiax is the outgoing trunk name of your free IAX provider. Nothing else needs to be changed. To dial a local extension, use this syntax: http://asterisk.dyndns.org/callme.php?number=sip/204 where asterisk.dyndns.org is the fully-qualified domain name for your Asterisk server and 204 is the local number to ring. Beginning on the first ring, Asterisk will start prompting for a password. It doesn’t care whether the call is answered or not, and it times out after 10 seconds. After three unsuccessful password attempts (each timeout counts as 1), Asterisk hangs up. Stated another way, you have about 30 seconds to enter your password after the phone first rings. Then Asterisk disconnects the call. To enter your password, key in the touchtone numbers which match the numerical password code you specified in your [callout] context (see below). Then press the pound (#) key. Note that a web page will not display at this web address unless you enter the portion of the address following the question mark. Nor will a call be placed unless the sip/bv/ syntax precedes a phone number. We did this for security reasons.

Before the above script will work, you also need to add the following context to the bottom of the extensions_custom.conf configuration file discussed above. Make sure you change the password 24681234 to something very secure. After all, it’s your phone bill! Once you make this change, it won’t take effect until you restart Asterisk. The easiest way to do that is to access setup within AMP, click Incoming Calls, then click the Submit Changes button, then click on the red bar which appears. Count to 10 and your changes should be operational.

[callout]
exten => s,1,Authenticate(24681234)
exten => s,2,DISA(no-password|from-internal)


One Ringy-Dingy. As we mentioned at the beginning of this article, there may be times when you don’t have access to a web browser and the cost of completed outgoing calls is astronomical. Or you may just find it more convenient to place a quick call to your Asterisk server rather than firing up a web browser. For the One Ringy-Dingy option to work, you must place a call to your Asterisk server from a phone that can accept incoming calls directly (not most hotel rooms or pay phones), and you must call from a phone with a legitimate CallerID number. Ideally, for this option to work in an unattended way all the time, you’d want to have a separate Direct-Inward-Dial (DID) number dedicated to this task. Why? Because, once Asterisk detects one ring on this number, it will issue a Congestion tone (fast busy) and immediately build and then process a DISA script to call you back. That obviously isn’t a desirable response on your regular phone number. We still will configure DISA to prompt for a password when the return call is answered, but callers may be a little surprised if they call you at home, hear a fast busy, and then immediately get a return call from your home asking them for a password.

Here are the steps to get this set up. We’ll tweak our Asterisk@Home/AMP dial-in context to turn on support for tracking incoming calls by DID. Then, for security, we’ll build a separate context for this DID number to isolate it from our default AutoAttendant which manages the rest of our incoming calls. Once we have the DID context created, we’ll build a DID entry in AMP to support this incoming line. Next, we’ll drop in the code to actually process the incoming call and build and execute the scripts necessary to make the return call. There are several new and very important Asterisk features that we’ll be taking advantage of. First, we’ll be executing code based upon a ringing phone line as opposed to an answered call. Second, we’ll show you how to execute context code and scripts after a call ends. And finally, we’ll be setting a maximum call limit on the outgoing DISA calls just to provide some food for thought on how you can better harrass your teenagers. So let’s get started.

Tweaking the Dial-In Context. From our previous articles, you will recall that Asterisk@Home and other Asterisk systems using the Asterisk Management Portal (AMP), rely upon the [from-sip-external] context in extensions.conf to process incoming calls. Right now, we have that context pointed to our AutoAttendant context which we built in the extensions_custom.conf file. You can read all about how to build the AutoAttendant here. The AutoAttendant implementation effectively disabled support for AMP’s DID Routes, but it secured your Asterisk system by reducing the number of points of attack to one, i.e. every incoming call had to flow through our one AutoAttendant. For those just getting started with Asterisk, this was a good thing. But, now that you’re an expert, we need a little more flexibility because we want to set up a DID line just to handle requests for DISA services, and we don’t want incoming calls on that line going to our AutoAttendant. Why? Because, with a separate DISA DID, we can eliminate any costs in placing calls to the Asterisk server requesting remote dial tone. How? This DID will never be answered. All it will do is ring once or twice before handing out a Congestion tone, and that activity will be sufficient to capture the incoming call’s CallerID and then set in motion the DISA return call process … hence the name One Ringy-Dingy. Won’t the telemarketers be thrilled! Just think of this DID as a toll-free number without having to pay for a toll-free number. To turn on support for AMP’s DID Route management, just add the following line to your [from-sip-external] context, and be sure you add it immediately below the [from-sip-external] label. See how easy this is when there’s some documentation (HINT!).

include => ext-did


Configuring an AMP DID Route. Now that we’ve activated DID Route support for Asterisk, let’s actually build a DID Route to show you how it’s done. This presupposes that you’ve ordered an additional DID from one of your providers and that you already have a trunk for that provider set up. When you order the additional DID, make sure that you specify that you do not want voicemail activated on this DID. Or, if you have control of the voicemail setup for this DID, turn it off. The reason is that, when incoming calls to this number get a congestion tone from Asterisk, that will activate the voicemail option with most providers. That, in turn, defeats our purpose of not answering calls ringing on this DID line to save money.

To create the DISA DID route, use a web browser to access the Asterisk Management Portal. Then choose AMP->Setup->DID Routes. Plug in the DID phone number you wish to assign to DISA duty. For the Destination, click on the Custom App button, and then enter the following: custom-teliax-in,8435551212,1 substituting your actual DID number. Click the Submit button and then the red bar to reset Asterisk. Note that AMP does no error checking for this custom context other than looking for the word "custom." Remember, we haven’t even built this context yet! But let’s do it now.

DISA Custom Contexts. For our One Ringy Dingy example, we’re going to use two different providers. The DID line is rented from Teliax.com. That’s where you call to trigger a callback. But Teliax is just too expensive for actual outgoing or incoming calls so we’re using two TelaSIP trunks (with permission): one to return the call to the original caller (that’s you or me) and one to place our outgoing DISA call (to the callee). If you happen to use TelaSIP, remember that you don’t need two separate accounts for the outbound calls since TelaSIP gives you two voice paths with your single line account.

There are three separate contexts we need to create at the bottom of extensions_custom.conf file to make all of this work. Keep in mind that there are three steps in the One Ringy-Dingy process: (1) you place a call to your DID number, and your Asterisk server detects the incoming call; (2) your Asterisk server calls you back, and you’re given dialtone after successfully entering your DISA password; and (3) your Asterisk server lets you to place an outgoing DISA call for a specified length of time to anywhere permitted in this context’s custom DISA dialplan. Here are the three contexts to support the three functions: (1) [custom-teliax-in] listens to the DID line for an incoming call and then sets up and executes the code setting the return call in motion; (2) [custom-telasip-callout] actually manages the return call once someone answers and authenticates the user for DISA service; and (3) [custom-telasip] sets the dialplan and timeout options for the call and then actually connects and times the call if the caller satisfies the dialplan rules. If you’re a little confused at this point, an example may help. Skip down to the Free Samples section below and actually try a test call to see how all this works. Then come back, and we’ll finish building it for your own Asterisk system.

Incoming Call Context. So a user first calls your DID number to initiate a DISA callback. Let’s start with the code that handles the incoming call on your DID line:

[custom-teliax-in]
exten => 8436541010,1,NoOp(Incoming call from Teliax #8436541010)
exten => 8436541010,2,Congestion
exten => 8436541010,3,Hangup
exten => h,1,SetCIDNum(${CALLERIDNUM:2})
exten => h,2,System(echo channel: SIP/telasip-gw/${CALLERIDNUM} > /tmp/${CALLERIDNUM})
exten => h,3,System(echo context: custom-telasip-callout >> /tmp/${CALLERIDNUM})
exten => h,4,System(echo extension: ${CALLERIDNUM} >> /tmp/${CALLERIDNUM})
exten => h,5,System(echo priority: 1 >> /tmp/${CALLERIDNUM})
exten => h,6,System(echo callerid: 2025560000 >> /tmp/${CALLERIDNUM}) ; Your CallerID for your TelaSIP account goes here
exten => h,7,System(echo sleep 30 > /tmp/${CALLERIDNUM}.2)
exten => h,8,System(echo cp /tmp/${CALLERIDNUM} /var/spool/asterisk/outgoing >> /tmp/${CALLERIDNUM}.2)
exten => h,9,System(chmod 775 /tmp/${CALLERIDNUM}.2)
exten => h,10,System(/tmp/${CALLERIDNUM}.2)
exten => h,11,Hangup()

Let’s walk through each line of the script so that you’ll know what needs to be changed on your own system if you use this. The first three lines get processed every time someone calls your dedicated DISA DID number. Adjust the numbers in each line to match your DISA line’s 10-digit CallerID number. Line 1 just outputs a message to the console indicating that there’s an incoming call on this line. Line 2 sends the Congestion tone back to the incoming caller. Line 3 is just a safety net to be sure the call is hung up as far as Asterisk is concerned. The next 11 lines beginning with exten=>h tell Asterisk what to do when it detects that the caller has hung up on the call. This code gets processed after the caller hangs up or after Asterisk processes the Hangup command in the third line.

Line h,1 is very important. Different providers relay CallerID numbers in different ways. Teliax sends a U.S. number as +14041234567. Many providers (including BroadVoice and TelaSIP) just send the ten-digit number for incoming U.S. calls. You need to know this because we’ll need to format the CallerID number properly to match what your outgoing provider expects to see when you process the return call in step 2. So how do you know what the CALLERIDNUM format is? Run asterisk -r from a command window and watch the information about an incoming call on the DID line you plan to use. If the format is a 10-digit number, then change SetCIDNum(${CALLERIDNUM:2}) to SetCIDNum(${CALLERIDNUM:0}) which means "use every digit as received." If the number is in the format 1+8901234567 then leave the expression the way it is. It basically says strip off the first two digits and store the rest as the CallerID number.

Line h,2 is where you identify which of your VoIP providers will be used to place the return call in step 2. If you’re using TelaSIP (as we are here), then just make sure the outbound trunk name matches your entry for this provider under AMP->Setup->Trunks. If you’re using an IAX provider instead of a SIP provider, change SIP to IAX2 as well. Finally, be sure what is now a 10-digit CallerID number is formatted properly for the return call through your dialback provider. TelaSIP wants a 10-digit number. GoIAX, for example, expects to receive a 1 and then the area code and number. For GoIAX, just insert a 1 before the CallerID number.

Line h,3 identifies the context which will actually place the return call. Line h,6 is where you specify the CallerID number of your Asterisk trunk that will be placing the return call. Teliax, for example, lets you spoof the CallerID for your calls so this is where you would enter the main number of the White House (if that’s your thing): 2024561414. Finally, in line h,7 you can set how much of a delay will be imposed before your Asterisk system places the return call. It’s set to 30, but you can change it to meet your requirements. The rest of this code should work as is.

Callback Context. Now we’re ready for Asterisk to place the return call. The previous code actually sets the call in motion with a 30 second delay and then a call to the CallerID number specified using the [custom-telasip-callout] context. But here’s the code that actually manages the callback. It also prompts for the DISA password once someone answers. Line s,3 is where you set the DISA password. Make it secure! Remember: IT’S YOUR PHONE BILL!

[custom-telasip-callout]
exten => s,1,Background(silence/2)
exten => s,2,Background(asterisk-friend)
exten => s,3,Authenticate(6373)
exten => s,4,Background(pls-wait-connect-call)
exten => s,5,DISA(no-password|custom-telasip)

When someone answers the return phone call, Asterisk counts to 2 and then says, "Asterisk is your friend. Please enter your password and press the pound key." That’s the person’s clue to enter their DISA password. Three guesses and Asterisk hangs up. If the password is successfully entered, Asterisk provides dialtone and passes the call to the [custom-telasip] context in s,5.

DISA Outbound Call Context. Once dialtone is provided, the user can enter whatever digits are permitted in the [custom-telasip] context’s dialplan. Here’s ours:

[custom-telasip]
exten => _1NXXNXXXXXX,1,AbsoluteTimeout(600)
exten => _1NXXNXXXXXX,2,Macro(dialout-trunk,8,${EXTEN:1},)
exten => _1NXXNXXXXXX,3,Macro(outisbusy) ; No available circuits
exten => T,1,Playback(thank-you-for-calling)
exten => T,2,Playback(goodbye)
exten => T,3,Hangup

Lines 1, 2, and 3 specify that the user has one and only one dialing option: dial 1 and then a 3-digit U.S. area code and then a 7-digit U.S. phone number. Line 1 is where you set the maximum duration for the call in seconds (600=10 minutes). Line 2 is where you really have to be careful. It has three gotcha’s. First, you need to identify which trunk will be used to place the DISA call. If your provider only offers one dial path per circuit, then this trunk cannot be the same one as what’s specified in custom-telasip-in,h,2 above or you’ll get an "all circuits are busy" message. In short, you need one outbound trunk for the callback and another outbound trunk to place the actual DISA call from dialtone. If you use TelaSIP’s residential plan, then you can use the same trunk for both. Second, you need to know the number of the dialout trunk to be used for the DISA call. AMP numbers all of your outbound trunks. If you look in the [globals] context at the top of the extensions_additional.conf file, you’ll see all of your outbound trunks labeled as OUT_1, OUT_2, etc. Find the number of the one that matches the name of the outbound trunk you want to use for your DISA call. Replace the "8″ in line 2 of [custom-telasip] with the appropriate number you wrote down. Don’t use OUT_8, just 8. Third, you’ve got to get the DISA number dialed by the user properly formatted for the provider that will be handling the call. In our case, we accepted only numbers beginning with 1 plus a U.S. area code plus a 7-digit number, but TelaSIP doesn’t want the 1 so we strip it off. If, however, your provider (such as GoIAX) expects a 10-digit number with a leading 1, then you’d adjust line 2 above to look like this: exten => _1NXXNXXXXXX,2,Macro(dialout-trunk,8,${EXTEN},). This tells Asterisk not to strip off the first digit before sending the rest to dialout-trunk 8. The extension entries beginning with an upper case T tell Asterisk what to do when the maximum duration of a call expires.

That about does it. To complete your work, save the three new contexts to extensions_custom.conf and then restart Asterisk.

Making a Test Call. To be sure everything is working as it should, start up Asterisk in interactive mode using the Command Line Interface (CLI) so that you can actually watch what’s happening when calls are placed and received. This works best if you connect to your Asterisk server through SSH from a Mac or PC. SSH comes with every Mac and the syntax is simple: ssh root@AsteriskIPaddress. If you’re still chained to Microsoft, download Putty from the Mother Country, and you can do the same thing using a Windows machine. Once you’re logged in as root, issue the following command: asterisk -r. Quit ends your Asterisk CLI session, and exit logs you out of your SSH session. Now issue the command: set verbose 10 to get maximum information. Then place a call to your DISA DID number from your cellphone and watch what happens. You should see the call being processed without being answered. Asterisk will then issue a Congested tone and disconnect. Your CLI display will remain quiet for 20 seconds, and then the return call will be placed. When you answer the call, you’ll be prompted for your password. Enter it, wait for dial tone, dial a number with 1, then area code, then 7-digit number and watch what happens. If the call fails, exit from CLI by typing Quit. Change to the /tmp directory: cd /tmp. Do a directory listing in reverse date order: ls -all -t -r. At the bottom of the list should be two files with the area code and number of your cellphone. One will have a .2 extension. Display the contents of the file without the extension: cat 6781234567 using your cellphone number. The contents should look something like this. If not, check your typing in the contexts we added and try again. Keep in mind that editing either of these two files is pointless. They both get built on the fly in the h section of the [custom-teliax-in] context depending upon the CallerID of the caller. Linux will automatically handle deletion of files from the /tmp directory in due course.

[root@asterisk1 tmp]# cat 6781234567
channel: SIP/telasip-gw/16781234567
context: custom-telasip-callout
extension: 6781234567
priority: 1
callerid: 2025560000

And, yes, we know the extension specified does not match the extension (s) actually entered in the [custom-telasip-callout] context. But, fear not, your call will fall back to the s extension when Asterisk can’t find an entry matching your cell phone number. Why did we do this? Well, you may want to have Asterisk do something special when it knows it’s you calling from your cellphone or one of your kids calling from your house at the lake. For example, you might want to provide a wide open dialplan for yourself with a different password as well. Remember, people can spoof your CallerID number so make the password VERY SECURE! Here’s how it would look. Substitute your own cellphone number and a new password. Once you make the changes, restart Asterisk and then place another call from your cellphone to your DISA DID and try entering a local extension or a foreign phone number if your regular dialplan supports it. Enjoy!

[custom-telasip-callout]
exten => 6781234567,1,Background(silence/2)
exten => 6781234567,2,Background(asterisk-friend)
exten => 6781234567,3,Authenticate(63738488537)
exten => 6781234567,4,Background(pls-wait-connect-call)
exten => 6781234567,5,DISA(no-password|from-internal)

exten => s,1,Background(silence/2)
exten => s,2,Background(asterisk-friend)
exten => s,3,Authenticate(6373)
exten => s,4,Background(pls-wait-connect-call)
exten => s,5,DISA(no-password|custom-telasip)


Free Samples. Everybody loves free samples so here’s one for you. You may remember Gene Willingham and the good folks at TelaSIP, the winner and least expensive provider in our unlimited U.S. long distance calling shootout. In a moment of weakness, TelaSIP’s agreed to let you try out our One Ringy-Dingy service (known affectionately around our house as the One Rinky-Dink Service because of the amount of time we’ve wasted on this). Anyway, it uses our Asterisk server and TelaSIP’s long distance bandwidth. Calls are limited to 10 minutes after which the callee will hear "Goodbye" followed by a click. You’ll get two beeps followed by a fast busy. In other words, time’s up! Here’s how to use this free service. Call from a phone in the U.S. with CallerID. Call the number shown on the map (inset) which is one of our DIDs in Charleston, South Carolina. The call will never be answered so you won’t be billed for the long distance call. Within 10 seconds, you should hear a fast busy. Just hang up, and our Asterisk server will call you back within 30 seconds. Listen carefully! You’ll be provided a random password for your call, and then you’ll be prompted to key it in. With your phone keypad, just do that and press the pound key (#). If you get a message that it’s incorrect, just try again (HINT: I told you to listen carefully). We used to have a fixed password, but the war-dialers were abusing the system so now it’s random. Back to the drawing boards, boys! Once you successfully enter the password, you’ll then get a DISA dial tone. Dial 1 and then the area code and phone number of someone you love (in the United States only). This is an excellent way for you to check out the voice quality of TelaSIP calls without spending a dime. Just don’t abuse the offer or this paragraph may magically disappear … as will the free calls. For those that don’t know us, we don’t record your calls, and we don’t store the number of the person you’re calling although the Asterisk logs probably have it for a while anyway. For security purposes, we do log your CallerID and the time of your call just in case you do something you shouldn’t be doing and the FBI traces the call back to us. If any of the above offends you, exercise your constitutional right to not use this free service. And a final reminder: none of this works if you don’t have CallerID enabled when you call. How would we know where to call you back? You won’t believe how many calls we receive with a CallerID of Asterisk. That obviously won’t work either.

Homework. There’s really a fourth DISA option. Under this scenario, you would call your home number, have the AutoAttendant answer, and then press 4 for DISA. After providing your password, Asterisk would hang up and call you back with DISA dial tone using the same type scripts we implemented in One Ringy Dingy above. The advantage of this approach is you don’t need a separate DID line to support DISA. The disadvantage is you have to pay for a one minute phone call to your home number each time you want remote dial tone. But it would save the expense of lengthy calls to your home just to use your outbound trunks. We’ll leave it to you to figure this one out. It shouldn’t take you long now that you understand how all the pieces fit together.

Some Recent Nerd Vittles Articles of Interest…

If you’re one of the 75,000+ Broadband Reports VoIP Forum subscribers who took advantage of the Staples/Vonage million dollar giveaway of easily unlocked Linksys PAP2 terminal adapters this past week and now you’d like to do more with VoIP than just make phone calls, welcome! For the rest of us including those that have been following our Asterisk articles these past few months, you already know that the hardest part of using Asterisk@Home or any other flavor Asterisk PBX is finding reliable, cost-effective VoIP providers that support home users of Asterisk. For business users, the prospects are even more bleak! With pay-as-you-go service, most providers don’t care what you connect with including Asterisk, and our experience suggests that Voxee.com (1¢ – 2¢ for most of the world with six second billing increments for U.S. calls) remains the best and most economical alternative, but it’s for outgoing calls only. And, yes, we love GoIAX.com with their free outbound calls within the U.S., and we love IPkall and Stanaphone for free incoming calls as long as you don’t mind a Washington state or New York City phone number. But, if there is one thing you can count on in the VoIP world, it’s this: free calling in or out probably won’t last forever. You do the math! Footnote: Matthew Simpson, who started the GoIAX service, promises us he’ll keep it going "forever" provided the cost of stamping out abusers doesn’t start outweighing the benefits of keeping the free service operational. We obviously wish him all the luck in the world and hereby donate this terrific, new (and free) firewall to assist in his efforts. He’s probably going to need it.

More problematic is finding a provider in the United States that supports Asterisk with an unlimited residential calling plan and a local phone number at a decent price. While BroadVoice advertises incredibly cheap international calling plans as unlimited with local phone numbers in most U.S. area codes, their fine print and the number of complaints of backbilling and other financial shenanigans posted on the Voxilla forum suggest that you’d better be extremely careful if you elect to use one of BroadVoice’s so-called Unlimited* Calling Plans with much of any call volume. As your Mama used to say, "If something sounds too good to be true, it probably is." For our review of international calling plans, go here. Last week we reviewed Yahoo’s dialpad service, but the voice quality of the calls just wasn’t satisfactory at least for our purposes, and there was no support for incoming calls with a local phone number. We personally liked Teliax, but they charged 2¢ a minute (rounded to whole minutes) for outgoing and incoming calls plus $5 a month for a local number (DID). And, when something comes unglued at their end, good luck getting it fixed. We had a DID that worked reliably and then all of a sudden you got a fast busy when folks called the number. In short, the calls never made it to our Asterisk server at all, and we showed them our logs to prove it. Unfortunately, explaining the situation to the Teliax support folks was a bit like talking to a toddler. They heard the words, but … Suffice it to say, the line remained dead in the water for almost a week before magically coming back to life. So we’re kissing Teliax goodbye for breaking Telecom Rule #1: When someone calls, our phone needs to ring! Then we looked at VoicePulse Connect with free incoming calls and a local number of your choice, but it’s $11 a month, and you then have to pay 4¢ a minute for outgoing U.S. calls. Yes, VoicePulse has all-you-can-eat plans, but they won’t support Asterisk. They will let you purchase a second line for Asterisk and pay 4¢ a minute for U.S. calls. We can do about as well with a WalMart phone card. So where does that leave us? Exhausted but persevering…

Just when we thought the Asterisk landscape was looking pretty bleak in the U.S. all-you-can-eat department, we stumbled upon a VoIP provider that loves and actually uses Asterisk, has state-of-the-art servers and a network backbone to match, demonstrates incredible depth of experience in the VoIP market, doesn’t play mind games with unconscionable terms of service (i.e. unlimited long distance calling means unlimited long distance calling), and has dirt cheap all-you-can-eat U.S. residential calling plans with local phone numbers for incoming calls. How much? $14.95 a month with no hidden "recovery" fees. For business users, you won’t find a better collection of business offerings on the planet. There are cradle-to-grave plans, or you can do-it-yourself for $40 per trunk with $1 DID’s and unlimited U.S. local and long distance calling. Even with its $100 monthly minimum, the latter is a great deal on PSTN origination and termination service for almost any size business. If you’re a small business and these plans don’t quite meet your needs, send them an email, and I’m pretty sure they’ll work out some cost-effective arrangement that meets your needs. Having tried dozens of VoIP providers over the past few months, suffice it to say, we’ve learned to spot the duds, the con artists, and the crappy providers just about as quickly as you can sign up for service. What you won’t get with this provider is a splashy web site with flashing signs promising you the moon … only to learn (later) that your free trip was just one way. Nor will there be a lot of hand-holding support although we received a return support call from the founder of the company in less than 30 minutes, and he didn’t know us from Adam. If you want handholding, then Vonage with a locked PAP2 phone adapter and no Asterisk server may be your best ticket to experience VoIP. Or here’s a cheaper alternative. BellSouth will sell you residential CallerID in Atlanta for only $8 a month … no phone line, no free calls to anywhere, no dial tone, no phone, just CallerID. And they wonder why their customers are leaving in droves.

So, where were we? If you’re comfortable with Asterisk and just looking for rock-solid reliable calls and an unlimited U.S. calling plan where you can actually hear the person at the other end of the line, then we’ve found a provider for you at a very reasonable price. Have we dragged this out long enough? The winner is VoipXpress aka TelaSIP. Congratulations to Jacob Brassington, who correctly guessed the winner in a posted comment following last week’s column. We didn’t publish the wrong guesses to protect the innocent. Our recommendation is that you try the $14.95 VoipXpress Premium plan for yourself. And, yes, the company founder, Gene Willingham, will give you your money back if you’re not satisfied. Or, if you just don’t trust anybody without a little personal testing, sign up for the VoipXpress Basic plan which is free with 4¢ per minute pay-as-you-go domestic calls.

Full Disclosure & Freebies. Like most other VoIP providers, VoipXpress helps a bit to defray the costs of the bandwidth for this blog if you sign up using the link we’ve provided. Sorry, but we’re addicted to referral credits, and you, too, can get them once you sign up for service. Anyway, it costs you nothing and helps us a little. But, if the referral stuff bothers you, just delete the PARTNER portion of the link to VoipXpress once you arrive on their web site. We like their service with or without referral credits. You will get a freebie, however, if you use our link. During October, VoipXpress will give you a second DID number in your choice of area code at no additional charge. Their DID’s are normally $1.95 a month, the best residential DID bargain around for those that need or want numbers in multiple places. Just mention Nerd Vittles when you sign up during October to get your second DID in almost any area code at no cost.

Configuring Asterisk@Home for VoipXpress. Now let’s get VoipXpress working with your Asterisk@Home system. The VoipXpress servers are actually maintained by their parent company, TelaSIP. We need to add a simple context to process incoming calls and then add a new trunk in our Asterisk@Home system. Finally we’ll reconfigure the outbound dialing routes to take advantage of the VoipXpress unlimited calling plan. Here’s how.

Point your web browser to your Asterisk@Home server’s IP address and choose AMP->Maintenance->Config Edit and choose extensions_custom.conf. We’re assuming you heeded our advice in our Securing Asterisk column and have already added a [from-external-custom] context to your extensions_custom file. If not, do that first! Now scroll to the bottom of the file and add the following new context substituting your Telasip assigned phone number for 4561234567. If you received two DIDs from TelaSIP, add three additional exten lines with your second number. Then click the Update button to save your changes.

[telasip-in]
exten => 4561234567,1,NoOp(Incoming call from TelaSIP #4561234567)
exten => 4561234567,2,Goto(from-external-custom,s,1)
exten => 4561234567,3,Hangup

Now let’s add a trunk for TelaSIP. Choose AMP->Setup->Trunks. Then click Add SIP Trunk. Why SIP and not IAX? The simple answer is there’s less call overhead between you and the provider. With SIP, only signalling information is passed to your provider while the data for the call itself (i.e. the heavy lifting) is strictly between you and the person you’re calling. Now where were we? For your Outbound Caller ID, fill in the local phone number provided by Telasip. For Maximum Channels, enter 2. That means that, unlike most providers of unlimited service, your account can handle two simultaneous calls in or out of your house with TelaSIP. For Dial Rules, enter the following substituting your local area code for 404:

1|NXXNXXXXXX
NXXNXXXXXX
404+NXXXXXX

In the Outgoing Settings section, name your trunk telasip-gw and then enter the following PEER details using your TelaSIP-assigned username and password:

context=telasip-in
dtmfmode=rfc2833
host=gw3.telasip.com
insecure=very
secret=yourpassword
type=peer
username=yourusername

Leave the Incoming Settings User Context and User Details blank. For your Registration string, enter the following: yourusername:yourpassword@gw3.telasip.com using your actual username and password assigned by TelaSIP. Click Submit Changes and then the red bar to restart Asterisk.

Adjusting Your Dialplans To Support VoipXpress/TelaSIP. If you’re using the Outbound Dialplans that we’ve built in the last few episodes, then it’s a simple matter to move SIP/telasip-gw up this list of priorities. Using AMP->Setup, click the Outbound Routing tab and then select each of the following routes: Local, Tollfree, and US. For each route, add a new Trunk Sequence by clicking the Add button and choosing SIP/telasip-gw. Then move it to the top of your Trunk Sequence list for each route to make it your first outbound dialing priority. Save your changes and restart Asterisk.

Making a Test Call Using TelaSIP. To be sure everything is working swimmingly, start up Asterisk in interactive mode using the Command Line Interface (CLI) so that you can actually watch what’s happening when calls are placed and received. This works best if you connect to your Asterisk server through SSH from a Mac or PC. SSH comes with every Mac and the syntax is simple: ssh root@AsteriskIPaddress. If you’re still chained to Microsoft, download Putty from the Mother Country, and you can do the same thing using a Windows machine. Once you’re logged in as root, issue the following command: asterisk -r. Quit ends your Asterisk CLI session, and exit logs you out of your SSH session. Now issue the command: set verbose 10 to get maximum information. Then place a U.S. long distance call and watch what happens. You should see something similar to the following which shows that the call was placed using the new telasip-gw trunk:

-- Called telasip-gw/8435551212
-- SIP/telasip-gw-2cbf is ringing


Coming Attractions. Next week, we still have Digium®’s IAXy device to configure so that you can take a phone with you on the road and connect back to your Asterisk® server to make calls. And with the IAXy 2 (now shipping), you can even use MD5 encryption for your passwords to further protect your Asterisk system. We’ll show you how. Then we’ll turn our attention to faxing and show you how to reconfigure Asterisk@Home to perform double-duty as not only a versatile PBX but also a sophisticated fax machine. You won’t need any special fax detection hardware to make this work, and Asterisk@Home will automatically detect and capture incoming faxes using your VoIP line. No dedicated fax line required! Then Asterisk@Home will convert the faxes into PDF documents and forward them to any email address you choose. This works great with your SIP line from TelaSIP by the way and works rarely with VoIP service from BroadVoice … yet another reason to put on your traveling shoes.

For those on the West Coast, don’t forget that next week is the big Asterisk convention in Anaheim: Astricon 2005. It’s not too late to register. And all your favorite nerds will be there, except us unfortunately. It should be a great time to learn all about Asterisk and to hear and see what’s on the drawing boards.

Last but not least, we previously walked you through adding entries to extensions_custom.conf to blacklist your "favorite" callers. But, in a coming article, we’ll show you how to do the same thing automatically at the touch of a button on your phone. In addition, there are some easy tools to manually add and remove blacklisted callers from Asterisk’s internal database, and we’ll show you how to access them from your phone. As the holiday and election seasons approach, you’ll be glad you’ve mastered blacklisting. Have a great weekend.

Other Tutorials. There are numerous additional articles in this Asterisk HOW-TO series to keep you busy. You can read all of them by clicking here and scrolling down the page. We recommend reading at least the first four or five articles from the bottom up so that the learning curve is less painful. Finally, if you just want to brush up on your phone etiquette, don’t miss Lily Tomlin’s "This Is A Recording" (See inset of "Ernestine" pictured with a vintage tip-and-ring switchboard). There is no finer tutorial on the planet: "We don’t care. We don’t have to. We’re the phone company."

Now that you've gotten your feet wet with our Asterisk@Home series, we want to catch our breath today and make sure your system is locked down. After all, you don't want the entire world making free phone calls on your nickel! Just as unsecured SendMail servers can be used as SPAM relay hosts, misconfigured Asterisk® servers also can be used as relay hosts to place calls to anywhere by anybody. In our second article we covered the basics of resetting all of the default passwords that come with Asterisk@Home. If you skipped that step, now would be a great time to be sure you've changed ALL of them. Just go back and reread the Securing Asterisk section of that article for the details.

Update: For the latest information, please read our Primer on Asterisk Security.

One of our few criticisms of Asterisk is its support of the goto command coupled with undocumented context subroutines and macros which are scattered across more than a dozen configuration files in applications such as the Asterisk Management Portal (AMP). For those of you that cut your teeth on the BASIC programming language, you know the tendency of applications to turn into spaghetti code, i.e. code so convoluted with goto's and undocumented subroutine calls that it's difficult to trace how an application actually plays out when it's executed. This, in turn, makes it extremely difficult to secure such applications because of the complexity of tracing through all the hoops executed when the program is in use.

Particularly for home or small office use, the major security risk with an Asterisk system is incoming call vulnerability. Someone connects to your system through the Internet and then places an outgoing call through your system to a coconspirator on some desert island on the other side of the globe that legally charges $12.00 a minute for calls. Cruise ships charge about the same thing! If you're not careful, you get stuck with the phone bill. Our solution to this incoming call vulnerability is to circle our wagons and strictly limit the number of Asterisk contexts used to process incoming calls. If you're lost in the ozone at this point, don't worry. Just keep reading, and we'll walk you through what all this means and what you can do to easily protect your system.

In Asterisk@Home, the context that controls incoming calls via IP is [from-sip-external] which can be found in extensions.conf using AMP->Maintenance->Config Edit. We previously showed you how to set up a Stealth AutoAttendant. We strongly recommend you use that or something similar to manage all incoming calls to your Asterisk server. This is the main reason we recommend against DID routing with Asterisk@Home. Using a single AutoAttendant assures that every incoming call lands in the same place and callers can only do the things you permit in this one context. Keep in mind that any extension command you have set up anywhere in the [from-internal-custom] context can be executed using this AutoAttendant. It doesn't really matter whether it is above or below the AutoAttendant code! And, of course, if you provide access to Asterisk's DISA service with either an insecure password or no password or if you took our advice and built speed-dial numbers but the calls are routed to Hong Kong, then you're on your own. IT'S YOUR PHONE BILL!

Why did we place the AutoAttendant code in the [from-internal-custom] context? Because we needed access to it for our Sipura SPA-3000 to handle incoming PSTN calls. In summary, you just need to be careful what options you provide in your AutoAttendant and the remainder of the [from-internal-custom] context because anyone can call you and choose any available option throughout that context. And keep in mind that your phone doesn't necessarily ring when someone hits your AutoAttendant so you may not know your system is being attacked unless you review your call logs frequently: AMP->Reports->Call Logs. Remember, any other Asterisk server on the planet can call your server via an IP connection. All it takes is the domain name or IP address of your Asterisk server, and they can at least attempt to make a connection. The only question is what can they do once they get there. And that's up to you! Finally, you need to carefully test your system by placing calls to yourself and pressing every button on your phone including 0, *, and #. Then try placing calls to local and long distance numbers while the AutoAttendant is playing. If they go through, you've got a problem. Last but not least, go into your VoiceMail system (just as a caller would) and dial the same numbers as above making sure there is no back door there that you don't know about. Remember, we showed you how to open the DISA backdoor in VoiceMail so make sure all of your voicemail passwords are secure if you implemented that tip.

Assuming you have deployed the Stealth AutoAttendant and added it to your [from-internal-custom] context in the extensions_custom.conf file, here is our recommended configuration for the [from-sip-external] context in the extensions.conf file. Be sure every other line in this context is commented out with a semicolon at the beginning of each line. Then restart Asterisk.

exten => _.,1,Wait(1)
exten => _.,2,Goto(from-internal-custom,111,1)


Our personal preference is to create a duplicate AutoAttendant context for your incoming VoIP connections. This eliminates the risk of inadvertently exposing some other extension code lurking elsewhere in your [from-internal-custom] context with IP connections. This new context can use identical code to the Stealth AutoAttendant we previously built, or you can customize it as desired. Place the new context at the bottom of the extensions_custom.conf file and then adjust your [from-sip-external] code to look like the following. Don't forget to restart Asterisk.

exten => _.,1,Wait(1)
exten => _.,2,Goto(from-external-custom,s,1)


Update: If you want to retain the flexibility to use the Asterisk Management Panel's DID Routes functionality to map incoming calls from certain trunks to different contexts or extensions, then insert the following code just below the [from-sip-external] label:

include => ext-did


And here's the sample code to insert in your extensions_custom.conf file. If you cut-and-paste the code below, don't forget to replace the opening and closing typographic quote characters with the standard quotation mark character or you'll get unexpected results with Asterisk.

[from-external-custom]
exten => s,1,Zapateller(answer|nocallerid)
exten => s,2,Wait(1)
exten => s,3,SetMusicOnHold(default)
exten => s,4,GotoIf($["${CALLERIDNUM}" = ""]?who-r-u,s,1)
exten => s,5,GotoIf($["foo${CALLERIDNUM}" = "foo"]?who-r-u,s,1)
exten => s,6,GotoIf($["${CALLERIDNAME:0:9}" = "Anonymous"]?who-r-u,s,1)
exten => s,7,GotoIf($["${CALLERIDNAME:0:7}" = "Unknown"]?who-r-u,s,1)
exten => s,8,GotoIf($["${CALLERIDNUM:0:7}" = "Private"]?who-r-u,s,1)
exten => s,9,GotoIf($["${CALLERIDNAME:0:7}" = "Private"]?who-r-u,s,1)
exten => s,10,GotoIf($["${CALLERIDNUM:0:10}" = "Restricted"]?who-r-u,s,1)
exten => s,11,GotoIf($["${CALLERIDNUM:0:4}" = "PSTN"]?who-r-u,s,1)
exten => s,12,DigitTimeout,3
exten => s,13,ResponseTimeout,3
exten => s,14,Background(custom/welcome)

exten => i,1,Playback(wrong-try-again-smarty)
exten => i,2,Goto(s,16)


Here's how the AutoAttendant code above works. Pressing zero activates the directory, pressing 1 rings the ring group (222) for all extensions, pressing 4 gives access to external dial tone if the password 1234588 is correctly entered, pressing no key (the t timeout entries) rings the main home phone extension, 204. Users can also enter 3-digit extension numbers beginning with a 2. If you didn't insert the following two contexts from our previous Asterisk column, then you'll need to add them to the bottom of [from-external-custom] to manage callers without CallerID:

[who-r-u]
exten => s,1,Background(privacy-unident)
exten => s,2,Background(vm-rec-name)
exten => s,3,Wait(2)
exten => s,4,Record(/tmp/asterisk-stranger:gsm|5|15)
exten => s,5,Background(pls-hold-while-try)
exten => s,6,Goto(ext-park,70,1)
exten => s,7,VoiceMail(204@default)
exten => s,8,Playback(Goodbye)
exten => s,9,Hangup

[ext-park]
exten => 70,1,Answer
exten => 70,2,SetMusicOnHold(default)
exten => 70,3,SetCIDNum(200|a)
exten => 70,4,SetCIDName(Parked Call Info|a)
exten => 70,5,ParkAndAnnounce(silence/9:asterisk-friend:/tmp/asterisk-stranger:vm-isonphone:at-following-number:PARKED|40|local/204@from-internal|who-r-u,s,7)
exten => 70,6,Hangup


MySQL Security Alert. Recently, we happened to look at how security was set up on MySQL with Asterisk@Home. This may also apply to those using plain-old Asterisk with the Asterisk Management Portal. In any case, you need to check your system NOW! Using the Asterisk Management Portal, go to AMP->Maintenance->phpMyAdmin. Then click on the Database pulldown in the left pane and choose mysql. When the tables display, click on the user table. Now click the Browse tab at the top of the right pane. The entry we care about is the second one: asterisk1.local for root user access. If your password field is blank, you've got a potential security problem. What this entry means in layman's terms is anyone on the Internet can connect to your MySQL databases as root with no password. The only roadblock is being able to spoof the default hostname of your Asterisk@Home server. And hostname spoofing has been a reported vulnerability of MySQL so it's just not worth taking a chance. Keep in mind that all of your VoIP account usernames and passwords are stored in a MySQL table when you use the Asterisk Management Portal (AMP). Not a healthy situation when it's your wallet that's at risk. To fix the problem permanently, just click on the pencil beside the second record. When the record displays, click on the function pulldown in the password row and choose Encrypt. Then make up a password that's secure and enter it in the password value field. Click Go to save your update. Now click the Browse tab again and be sure an encrypted password is shown for both root user entries in the table. We don't care about the blank password for the blank user because you'll note that all the database privileges are set to N for this account. Fixed!

Other Security Advisories. We also recommend that you frequently review the Secunia web site for Asterisk security advisories. They also have an RSS Feed for those of us who are forgetful.

Other Asterisk Articles. There are numerous additional articles in this Asterisk HOW-TO series to keep you busy. You can read all of them by clicking here and scrolling down the page. We recommend reading the articles from the bottom up so that the learning curve is less painful. Sleep well. Your Asterisk server is now at least a little bit more secure, and you know a good bit more about how the pieces actually fit together and why.