Category Archives: Telephony

We've covered lots of Asterisk® territory these past few months, but one of the real stumbling blocks has been reliable incoming fax support. Yes, Asterisk has some fax support built into the product; however, to use it you have to invest in Digium® hardware. Not that we're cheap or anything (we are actually!), but we wanted a fax solution that didn't rely on hardware. Stated another way, we wanted a pure software solution to faxing just like Asterisk provides a pure software solution to PBX telephony for those that want to use it. And we wanted reliable delivery of faxes using VoIP lines including IAX and SIP trunks, not just Ma Bell's PSTN lines. Well, we've finally found a solution, and it works reliably with Asterisk@Home 1.5 as well as Asterisk@Home 2.x. For those not using Asterisk@Home, the solution we're covering works reliably with Asterisk 1.09 as well as Asterisk 1.2 and 1.2.1. This tutorial assumes you're using Asterisk@Home, but the concepts will work equally well with "pure Asterisk" assuming you know what you're doing.

2008 Update: This article has been updated to support Asterisk 1.4. Click here for the latest article.

2011 Update: This article has been updated to support Asterisk 1.8 using HylaFax, AvantFax, and IAXmodem. Click here for the latest article.

The way this works is pretty straightforward. A fax machine calls your regular Asterisk phone number, no dedicated fax line required. When Asterisk answers the call, it listens for a fax tone. If it hears one, it reroutes the incoming call to a context which then processes the incoming fax. The fax is saved as a TIFF image, converted to a PDF document, and emailed to the address specified in your Asterisk@Home setup: AMP->Setup->General Settings. If a fax tone isn't detected, the call is processed as an incoming voice call according to the rules you've set up for incoming calls.

Prerequisites. As previously noted, you won't need any special hardware to make our incoming fax solution work with Asterisk. All you need is Asterisk@Home and Newman Telecom's NVfaxdetect, which is FREE for the downloading. You'll also need the Fax-to-PDF conversion tools which are included with Asterisk@Home. Your system also must be configured to send emails reliably. If you followed our tutorial for setting up your Asterisk@Home system, you should be all set. Otherwise, start there in the Activating Email Delivery of VoiceMail Messages section. Finally, if you're using an IAX or SIP trunk, you'll need a line from a VoIP provider with an uncompressed codec (such as ulaw), and you need an ITSP that knows what it's doing and supports incoming faxes. HINT: TelaSIP lines work. BroadVoice lines usually don't.

An equally important requirement for this project is following along carefully with this tutorial. We're going to be recompiling a modified Asterisk as part of this project and, if you screw it up by not paying careful attention to the details, not only will your system not accept faxes, it probably won't accept phone calls either when we're finished. Having said that, there is nothing hard about this project. You just need to type carefully and not skip any steps. So let's get started.

Installing Fax-to-PDF Conversion Tools. Let's begin with the easy stuff. First, you'll need to install the Fax-To-PDF conversion tools that are already scripted in Asterisk@Home. Log in to your server as root. At the command prompt, type install-pdf. Your system will whir away for a couple minutes after which you'll get a completed message that looks something like this:

Running Transaction
Installing: xorg-x11-font-utils ######################### [1/8]
Installing: ttmkfdir ######################### [2/8]
Installing: xorg-x11-xfs ######################### [3/8]
Installing: chkfontpath ######################### [4/8]
Installing: urw-fonts ######################### [5/8]
Installing: VFlib2 ######################### [6/8]
Installing: ghostscript-fonts ######################### [7/8]
Installing: ghostscript ######################### [8/8]

Installed: ghostscript.i386 0:7.07-33
Dependency Installed: VFlib2.i386 0:2.25.6-25 chkfontpath.i386 0:1.10.0-2 ghostscript-fonts.noarch 0:5.50-13 ttmkfdir.i386 0:3.0.9-14.1.EL urw-fonts.noarch 0:2.2-6.1 xorg-x11-font-utils.i386 0:6.8.2-1.EL.13.20 xorg-x11-xfs.i386 0:6.8.2-1.EL.13.20
Complete!


For those running Asterisk with flavors of Linux other than CentOS, the install command you'll need above is yum -y install ghostscript.

Routing Your Incoming Faxes. To specify where you want incoming faxes delivered, start up the Asterisk Management Panel (AMP) by pointing a web browser to the IP address of your Asterisk server. Then choose AMP->Setup->General Settings. In the Fax Machine section, leave the extension of fax machine set to System. For the email fax delivery address, enter a valid email address where you want the PDF copies of faxes to be sent. Click the Submit Changes button and then click the red bar to reload Asterisk.

Downloading NVfaxdetect. Log in to your Asterisk server as root, stop Asterisk, and download NVfaxdetect using the following commands:

amportal stop
cd /usr/src/asterisk/apps
wget http://www.newmantelecom.com/download/asterisk/faxdetect/1.0.6/app_nv_faxdetect.c


NOTE: Some intermittent problems have been reported downloading the source code from Newman Telecom. If you have a problem, you can download the patched source code directly from Nerd Vittles. Here's the link for Asterisk@Home 1.5 systems:

wget http://nerdvittles.com/aah15/app_nv_faxdetect.c

And here's the link for Asterisk@Home 2.x systems:

wget http://nerdvittles.com/aah2/app_nv_faxdetect.c


Modifying the NVfaxdetect Source Code. Skip this section if you downloaded the source for your version of Asterisk@Home directly from Nerd Vittles. Otherwise, a change needs to be made in the NVfaxdetect source code whether you are running Asterisk@Home 1.5 or Asterisk@Home 2.x. Edit the source code by issuing the following command: nano -w app_nv_faxdetect.c.

If you're using Asterisk@Home 1.5, search for the word CALLERID in the source file: Ctrl-W, CALLERID. When it finds the match, you'll be in the middle of three lines of code that look like this:

// Use the second one for recent Asterisk releases
#define CALLERID_FIELD cid.cid_num
//#define CALLERID_FIELD callerid

Change these three lines so that the first define line is commented out and the second one is uncommented. Your code should look like the following when you're finished:

// Use the second one for recent Asterisk releases
//#define CALLERID_FIELD cid.cid_num
#define CALLERID_FIELD callerid

Once you complete the change, save the file: Ctrl-X, Y, then press Enter.

If you're using Asterisk@Home 2.x, we need to make a different change in the source code. Search for #include with the command: Ctrl-W, #include. When the match is found, move the cursor up one line, press the Enter key, and insert the following code:

Ignore the two dots in the right column above. WordPress quirk! Once you make this addition, save the file: Ctrl-X, Y, then press Enter.

Adjusting Makefile. Regardless of your version of Asterisk@Home, we need to modify Makefile to include this code in the Asterisk executable: nano -w Makefile. With AAH 2.x, search for the word "experimental": Ctrl-W, experimental. Move down one line and press Enter. With AAH 1.5, search for the expression "#APPS+": Ctrl-W,#APPS+. Move up one line and press Enter. Now, with either version, add the following making sure there is no pound sign (#) at the beginning of the line:

APPS+=app_nv_faxdetect.so

Once you make this addition, save the file: Ctrl-X, Y, then press Enter.

Recompiling Asterisk. Now we're ready to recompile and reinstall the Asterisk application with your new NVfaxdetect code. Issue the following commands:

cd /usr/src/asterisk
make
make install

You'll get some warning messages when the install completes. You can safely ignore them. When the install is finished, you can restart Asterisk and use the Command Line Interface (CLI) to make certain that NVfaxdetect installed properly:

amportal start
asterisk -r
set verbose 10
show application nvfaxdetect

The following CLI message should be displayed:

This application listens for fax tones (on IAX and SIP channels too)
for waitdur seconds of time. In addition, it can be interrupted by digits,
or non-silence. Audio is only monitored in the receive direction. If
digits interrupt, they must be the start of a valid extension unless the
option is included to ignore. If fax is detected, it will jump to the
'fax' extension. If a period of non-silence greater than 'mindur' ms,
yet less than 'maxdur' ms is followed by silence at least 'sildur' ms
then the app is aborted and processing jumps to the 'talk' extension.
If all undetected, control will continue at the next priority.
waitdur: Maximum number of seconds to wait (default=4)
options:
'n': Attempt on-hook if unanswered (default=no)
'x': DTMF digits terminate without extension (default=no)
'd': Ignore DTMF digit detection (default=no)
'f': Ignore fax detection (default=no)
't': Ignore talk detection (default=no)
sildur: Silence ms after mindur/maxdur before aborting (default=1000)
mindur: Minimum non-silence ms needed (default=100)
maxdur: Maximum non-silence ms allowed (default=0/forever)
Returns -1 on hangup, and 0 on successful completion with no exit conditions.

For questions or comments, please e-mail support@newmantelecom.com.


Adjusting Your Dialplans to Implement Fax Detection. The final step in this process is to adjust the Asterisk dialplans to implement fax detection and process incoming faxes. Several different methods are shown below. Choose the one that applies to your deployment of Asterisk.

For those using a standard Asterisk 1.5 or Asterisk 2.x install with no Stealth AutoAttendant, you'll need to make the following changes to both the [from-pstn-reghours] and [from-pstn-afthours] contexts in the extensions.conf config file.

To modify [from-pstn-reghours], use the Asterisk Management Portal (AMP) to access AMP->Maintenance->Config Edit->extensions.conf->from-pstn-reghours. Delete all of the existing code:

exten => s,1,GotoIf($[${FAX_RX} = disabled]?from-pstn-reghours-nofax,s,1:2) ; if fax detection is disabled, then jump to from-pstn-nofax - else continue
exten => s,2,Answer
exten => s,3,Wait(1)
exten => s,4,SetVar(intype=${INCOMING})
exten => s,5,Cut(intype=intype,-,1)
exten => s,6,GotoIf($[${intype} = EXT]?7:9) ; If INCOMING starts with EXT, then assume its an extension
exten => s,7,Wait(3) ;wait 3 more second to make sure this isn't a fax before dialing someone
exten => s,8,Goto(ext-local,${INCOMING:4},1)
exten => s,9,GotoIf($[${intype} = GRP]?10:12) ; If INCOMING starts with GRP, then assume its a ring group
exten => s,10,Wait(3)
exten => s,11,Goto(ext-group,${INCOMING:4},1)
exten => s,12,GotoIf($[${intype} = QUE]?13:15)
exten => s,13,Wait(3)
exten => s,14,Goto(ext-queues,${INCOMING:4},1)
exten => s,15,Goto(${INCOMING},s,1) ; not EXT or GR1 - it's an auto attendant
exten => fax,1,Goto(ext-fax,in_fax,1)
exten => h,1,Hangup

Then insert the following new code in the [from-pstn-reghours] context and click the Update button:

exten => s,1,GotoIf($[${FAX_RX} = disabled]?from-pstn-reghours-nofax,s,1:2); if fax detection is disabled, then jump to from-pstn-nofax - else continue
exten => s,2,Answer
exten => s,3,Playtones(ring) ; play fake ring so caller doesn't wonder whats going on
exten => s,4,NVFaxDetect(10) ; while playing ring sound, detect faxes for 2 rings (goes to "fax" extension if detected)
exten => s,5,SetVar(intype=${INCOMING})
exten => s,6,Cut(intype=intype,-,1)
exten => s,7,GotoIf($[${intype} = EXT]?8:9) ; If INCOMING starts with EXT, then assume its an extension
exten => s,8,Goto(ext-local,${INCOMING:4},1)
exten => s,9,GotoIf($[${intype} = GRP]?10:11) ; If INCOMING starts with GRP, then assume its a ring group
exten => s,10,Goto(ext-group,${INCOMING:4},1)
exten => s,11,GotoIf($[${intype} = QUE]?13:14)
exten => s,13,Goto(ext-queues,${INCOMING:4},1)
exten => s,14,Goto(${INCOMING},s,1) ; not EXT or GRP - it's an auto attendant
exten => fax,1,Goto(ext-fax,in_fax,1)
exten => h,1,Hangup

Now we need to make a similar change in the [from-pstn-afthours] context. Replace the following code:

exten => s,1,GotoIf($[${FAX_RX} = disabled]?from-pstn-afthours-nofax,s,1:2) ; if fax detection is disabled, then jump to from-pstn-nofax - else continue
exten => s,2,Answer
exten => s,3,Wait(1)
exten => s,4,SetVar(intype=${AFTER_INCOMING})
exten => s,5,Cut(intype=intype,-,1)
exten => s,6,GotoIf($[${intype} = EXT]?7:9) ; If INCOMING starts with EXT, then assume its an extension
exten => s,7,Wait(3) ;wait 3 more second to make sure this isn't a fax before dialing someone
exten => s,8,Goto(ext-local,${AFTER_INCOMING:4},1)
exten => s,9,GotoIf($[${intype} = GRP]?10:12) ; If INCOMING starts with GRP, then assume its a ring group
exten => s,10,Wait(3)
exten => s,11,Goto(ext-group,${AFTER_INCOMING:4},1)
exten => s,12,GotoIf($[${intype} = QUE]?13:15)
exten => s,13,Wait(3)
exten => s,14,Goto(ext-queues,${AFTER_INCOMING:4},1)
exten => s,15,Goto(${AFTER_INCOMING},s,1) ; not EXT or GR1 - it's an auto attendant
exten => fax,1,Goto(ext-fax,in_fax,1)
exten => h,1,Hangup

Replace the above code with the following new code and then click the Update button:

exten => s,1,GotoIf($[${FAX_RX} = disabled]?from-pstn-afthours-nofax,s,1:2); if fax detection is disabled, then jump to from-pstn-nofax - else continue
exten => s,2,Answer
exten => s,3,Playtones(ring) ; play fake ring so caller doesn't wonder whats going on
exten => s,4,NVFaxDetect(10) ; while playing ring sound, detect faxes for 2 rings (goes to "fax" extension if detected)
exten => s,5,SetVar(intype=${AFTER_INCOMING})
exten => s,6,Cut(intype=intype,-,1)
exten => s,7,GotoIf($[${intype} = EXT]?8:9) ; If INCOMING starts with EXT, then assume its an extension
exten => s,8,Goto(ext-local,${AFTER_INCOMING:4},1)
exten => s,9,GotoIf($[${intype} = GRP]?10:11) ; If INCOMING starts with GRP, then assume its a ring group
exten => s,10,Goto(ext-group,${AFTER_INCOMING:4},1)
exten => s,11,GotoIf($[${intype} = QUE]?13:14)
exten => s,13,Goto(ext-queues,${AFTER_INCOMING:4},1)
exten => s,14,Goto(${AFTER_INCOMING},s,1) ; not EXT or GRP - it's an auto attendant
exten => fax,1,Goto(ext-fax,in_fax,1)
exten => h,1,Hangup


For those using the Nerd Vittles' Stealth AutoAttendant to process incoming calls, you'll need to adjust the extension 111 script in your extensions_custom.conf file. Here's the NVfaxdetect setup that we use which also includes the BlackList, CallerID, and Bluetooth Proximity Detection systems we've previously built. So, yes, we do eat our own dog food. Special note: We don't accept faxes on our Southern Bell PSTN line (111,6,Goto(9)). If you'd prefer to accept them, then change Goto(9) to Goto(7).

exten => 111,1,LookupBlacklist ; If CID blacklisted, goto 102 ; Check for creeps
exten => 111,2,Answer
exten => 111,3,GotoIf($["${CALLERIDNUM:0:2}" = "00"]?4:7) ; Special Handling for SPA-3000
exten => 111,4,SetCIDNum(${CALLERIDNUM:2})
exten => 111,5,LookupBlacklist ; If CID blacklisted, goto 106 ; Gotta do it again after adjusting CallerID
exten => 111,6,Goto(9)
exten => 111,7,Playtones(ring) ; play fake ring so caller doesn't wonder whats going on
exten => 111,8,NVFaxDetect(10) ; while playing ring sound, detect faxes for seconds (goes to "fax" extension if detected)
exten => 111,9,SetMusicOnHold(default)
exten => 111,10,Wait(1)
exten => 111,11,GotoIf($["${CALLERIDNUM}" = ""]?who-r-u,s,1)
exten => 111,12,GotoIf($["foo${CALLERIDNUM}" = "foo"]?who-r-u,s,1)
exten => 111,13,GotoIf($["${CALLERIDNAME:0:9}" = "Anonymous"]?who-r-u,s,1)
exten => 111,14,GotoIf($["${CALLERIDNAME:0:7}" = "Unknown"]?who-r-u,s,1)
exten => 111,15,GotoIf($["${CALLERIDNUM:0:7}" = "Private"]?who-r-u,s,1)
exten => 111,16,GotoIf($["${CALLERIDNAME:0:7}" = "Private"]?who-r-u,s,1)
exten => 111,17,GotoIf($["${CALLERIDNUM:0:10}" = "Restricted"]?who-r-u,s,1)
exten => 111,18,GotoIf($["${CALLERIDNAME:0:11}" = "OUT OF AREA"]?who-r-u,s,1)
exten => 111,19,GotoIf($["${CALLERIDNUM:0:4}" = "PSTN"]?who-r-u,s,1)
exten => 111,20,GotoIf($["${CALLERIDNUM:0:3}" = "199"]?who-r-u,s,1)
exten => 111,21,GotoIfTime(${REGTIME}|${REGDAYS}|*|*?25)
exten => 111,22,Background(silence/2)
exten => 111,23,VoiceMail(204@default)
exten => 111,24,Hangup
exten => 111,25,AGI(calleridname.agi)
exten => 111,26,Background(custom/welcome)
exten => 111,27,DigitTimeout,2
exten => 111,28,ResponseTimeout,2
exten => 111,102,Goto(custom-blacklisted,s,1)
exten => 111,106,Goto(custom-blacklisted,s,1)
exten => fax,1,Goto(ext-fax,in_fax,1)
exten => t,1,Background(pls-hold-while-try)
exten => t,2,AGI(homecheck.agi)
exten => t,3,GotoIf($["${WARD:0:2}" = "OU"]?custom-outhouse,s,1:4)
exten => t,4,Dial(local/222@from-internal,20,m)
exten => t,5,VoiceMail(204@default)
exten => t,6,Hangup
exten => t,105,Voicemail(204@default)
exten => t,106,Hangup
exten => i,1,Playback(wrong-try-again-smarty)
exten => i,2,Goto(111,26)
exten => o,1,Macro(rg-group,20,,200-201-204-210)
exten => o,2,VoiceMail(204@default)
exten => o,3,Hangup
exten => h,1,Hangup


After you finish up the remainder of this tutorial and try a test fax, you may need to adjust the number in the NVfaxdetect lines (s,4 or 111,8) of the above contexts. The original tutorial we read on this topic had 4 for the value which was supposed to mean 4 seconds; however, Asterisk read it as 4 milliseconds. 10 works on both of our Asterisk systems, one version 1.5 and one version 2.2. YMMV. Others have had luck deleting the number altogether leaving just the open and closed parentheses. Try different approaches until it works reliably on your system. What you're striving for is just enough time to detect a fax without putting regular callers to sleep waiting on your fax detection mechanism to complete its task.

Whether you're using a standard Asterisk@Home 1.5 or 2.x or the Stealth AutoAttendant, you'll also need to modify the incoming fax context. Just choose the code below that matches your version of Asterisk and replace the existing content in [ext-fax]: AMP->Maintenance->Config Edit->extensions.conf->ext-fax. Don't forget to restart Asterisk after making these changes. From a command prompt while logged in as root, the following command will do it in Asterisk@Home 2.2: amportal restart. For Asterisk@Home 1.5 users, it takes two commands: amportal stop then amportal start. Then you'll be ready to start receiving junk faxes just like we do. Enjoy!

For Asterisk@Home 1.5 systems whether you're using the Stealth AutoAttendant or not, replace the existing contents of [ext-fax] with the following code. If you cut-and-paste, be sure to replace the typographic quote marks in line h,2 with regular quotation marks or expect smoke.

exten => s,1,Answer
exten => s,2,Goto(in_fax,1)
exten => in_fax,1,StopPlaytones ; you must do this or it will play ring sounds over your fax
exten => in_fax,2,GotoIf($[${FAX_RX} = system]?3:analog_fax,1)
exten => in_fax,3,Macro(faxreceive)
exten => in_fax,7,Hangup
exten => analog_fax,1,GotoIf($[${FAX_RX} = disabled]?3:2) ;if fax is disabled, just hang up
exten => analog_fax,2,Dial(${FAX_RX},20,d)
exten => analog_fax,3,Hangup
exten => out_fax,1,txfax(${TXFAX_NAME}|caller)
exten => out_fax,2,Hangup
exten => h,1,system(tiff2ps -2eaz -w 8.5 -h 11 ${FAXFILE} | ps2pdf - ${FAXFILE}.pdf)
exten => h,2,system(mime-construct --to ${EMAILADDR} --subject "Fax from ${CALLERIDNUM} ${CALLERIDNAME}" --attachment ${CALLERIDNUM}.pdf --type application/pdf --file ${FAXFILE}.pdf)
exten => h,3,system(rm ${FAXFILE} ${FAXFILE}.pdf)
exten => h,4,Hangup()


For Asterisk@Home 2.x systems whether you're using the Stealth AutoAttendant or not, replace the existing contents of [ext-fax] with the following code. If you cut-and-paste, be sure to replace the typographic quote marks in line h,2 with regular quotation marks or expect smoke.

exten => s,1,Answer
exten => s,2,Goto(in_fax,1)
exten => in_fax,1,StopPlaytones ; you must do this or it will play ring sounds over your fax
exten => in_fax,2,GotoIf($[${FAX_RX} = system]?3:analog_fax,1)
exten => in_fax,3,Macro(faxreceive)
exten => in_fax,7,Hangup
exten => analog_fax,1,GotoIf($[${FAX_RX} = disabled]?3:2) ;if fax is disabled, just hang up
exten => analog_fax,2,DBGet(DIAL=DEVICE/${FAX_RX}/dial);
exten => analog_fax,3,Dial(${DIAL},20,d)
exten => analog_fax,4,Hangup
exten => out_fax,1,txfax(${TXFAX_NAME}|caller)
exten => out_fax,2,Hangup
exten => h,1,system(tiff2ps -2eaz ${FAXFILE} | ps2pdf - ${FAXFILE}.pdf)
exten => h,2,system(mime-construct --to ${EMAILADDR} --subject "Fax from ${CALLERIDNUM} ${CALLERIDNAME}" --attachment ${CALLERIDNUM}.pdf --type application/pdf --file ${FAXFILE}.pdf)
exten => h,3,system(rm ${FAXFILE} ${FAXFILE}.pdf)
exten => h,4,Hangup()


R.I.P. WordPress Cut-And-Paste Nightmare. For long-time readers of this column, you know what a royal pain cutting-and-pasting has been at Nerd Vittles thanks to the WordPress blog's proclivity for changing quotation marks (used in many Asterisk commands) to 'smart quotes'. The original version of this column introduced an entirely new problem when WordPress replaced double-hyphens (used in many Linux commands) with 'long hyphens.' The end result of these quirks has been that, while the code worked great on our development systems, it blew up when you used cut-and-paste to move it to your Asterisk server. This all came to a head this past week when this article on faxing hit the street and blew up on every reader's system because of the double-hyphens (h,2 above), a problem that neither we nor anyone else in the WordPress blog community had ever documented.

Just like everything else that's great about the Open Source community, there is always someone smart enough not only to recognize a problem but also to fix it. So our hat is forever tipped to Alex King, one of WordPress's most ardent supporters. He wrote about the smart quotes problem and then he single-handedly fixed it with his WP Unformatted Plugin. As luck would have it, the plugin also resolves the double-hyphen problem. It just took us a while to discover the plugin. But there's nothing like an extra scoop of egg on your face to make you scratch a little harder for a solution. We were either going to solve the formatting problems or give WordPress the heave-ho. Now that we've implemented the plugin, we'll be using it regularly and, as quickly as we can, we'll go back and rework all of our previous articles just as we have this one. Hopefully the problem is history both for you and for us. Should you see any Nerd Vittles code that still looks like it has quotation marks pointing in two different directions, please let us know. And ... our apologies for the mess.

Some Recent Nerd Vittles Articles of Interest...

Want a rock-solid PBX at a rock-bottom price: free! Yep, it's been a week and here we go again! Asterisk@Home 2.2 has hit the street primarily because of a bug-fix release of Asterisk®! Now you get the latest version of Asterisk (version 1.2.1), and you also get the latest and greatest version of Linux, CentOS 4.2; the latest Festival Speech Engine (1.96); the latest version of the Asterisk Management Portal (1.10.010); the Flash Operator Panel (version 0.24); Open A2Billing; Digium® card auto-configuration; fax support; loads of AGI scripts including weather forecasts and wakeup calls; xPL support; the SugarCRM Contact Management System with the Cisco XML Services interface and Click-to-Dial support; plus some more bug fixes. And it amazingly still fits on a single CD!

Editor's Note: This version of Asterisk@Home has been superceded. For the latest tutorial on or after March 13, click here.

The installation process is pretty straightforward. You download the 2.2 ISO image from here, burn a CD (click here if you need a refresher course), use an old clunker PC or a $200 WalMart special (see inset), insert the CD you made, plug your machine into the Internet and turn it on. Then watch while Asterisk@Home loads CentOS/4.2 and all the Asterisk and Linux goodies imaginable: Apache, SendMail, Comedian Mail, SugarCRM, MySQL, PHP, phpMyAdmin, SSH, Bluetooth, the Asterisk Management Portal, the Flash Operator Panel, Call Detail Reporting, and on and on. We've covered how to use most of the Linux products in our Mac HOW-TO's (see sidebar), and they work exactly the same way with Asterisk@Home so keep reading. And, yes, this install will reformat (aka ERASE) your hard disk before it begins, but it now warns you first.

Loading CentOS/4 and Asterisk 1.2.1. Here's how the 2.2 install went for us, and we'll walk you through getting everything set up so that it can be used as a production server. Once the install begins, you can expect to eat up about 25 minutes with the CentOS 4.2 install. The install CD then will eject itself, reboot the system, and begin the Asterisk compile and installation. That takes about 25 more minutes to complete.

Securing Your Passwords. When it's finished and reboots, log in as root with password as your password. Type help-aah for a listing of the five passwords that need to be changed. Change them all NOW!

passwd
passwd admin
passwd-maint
passwd-amp
passwd-meetme


Getting the Latest CentOS Updates. Once your system is secure, load all of the application updates for CentOS 4.2 unless you have Digium cards. If you do, read the caution which follows before proceeding. There are about forty of them as we write this so be patient. The update command to issue is yum -y update.

Dec. 27 WARNING: There is an additional wrinkle with running yum update with Asterisk@Home 2.2 if you have Digium cards. Read this SourceForge thread and make sure you understand what's necessary to put Humpty back together again before running yum update if you have Digium cards in your Asterisk system.

Activating Bluetooth Support. Once the updates are completed, activate Bluetooth support if you plan to use it with our Follow-Me Phoning proximity detection application. Run setup, down arrow to System Services, press ENTER, down arrow to bluetooth and press the space bar, tab to OK, press ENTER, tab twice to Quit and press ENTER.

Rebuilding Zaptel. First, reboot your system: shutdown -r now. Because a new version of the kernel is installed as part of the yum update, you'll need to rebuild support for ZAP devices. Log in as root and type the following commands:

cd /usr/src/zaptel
make install-udev
rebuild_zaptel


Reboot your system: shutdown -r now. Now log in as root again and type genzaptelconf. Reboot once more and you're all set to go: shutdown -r now. You only need to rebuild Zaptel when there is a kernel update as there was with this yum update.

Simplifying SSH. If you're going to be connecting to other servers from your new Asterisk@Home 2.2 system using SSH or SCP, then build your new RSA key pair now. This lets you use SSH and SCP (secure copy) without having to enter a password each time. You can also automate backups and proximity detection scripts as we've explained previously here. Log in to your new Asterisk@Home 2.2 server as root. From the command prompt, issue the following command: ssh-keygen -t rsa. Press the enter key three times. You should see something similar to the following. The file name and location in bold below is the information we need:

Generating public/private rsa key pair.
Enter file in which to save the key (/root/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /root/.ssh/id_rsa.
Your public key has been saved in /root/.ssh/id_rsa.pub.
The key fingerprint is:
1d:3c:14:23:d8:7b:57:d2:cd:18:70:80:0f:9b:b5:92 root@asterisk1.local

Now copy the file in bold above to your other Asterisk servers, Linux machines, and Macs. There's probably a way on PCs as well, but I've given up on that platform particularly after Sony's latest security stunt so you're on your own there. From your Asterisk@Home 2.2 server using SCP, the command should look like the following (except use the private IP address of each of your other Asterisk or Linux servers instead of 192.168.0.104). Provide the root password to your other servers (one at a time) when prompted to do so.

scp /root/.ssh/id_rsa.pub root@192.168.0.104:/root/.ssh/authorized_keys

On a Mac running Mac OS X, the command would look like this (using your username and your Mac's IP address, of course):

For user access only: scp /root/.ssh/id_rsa.pub wardmundy@192.168.0.104:/Users/wardmundy/.ssh/authorized_keys
For full root access: scp /root/.ssh/id_rsa.pub root@192.168.0.104:/var/root/.ssh/authorized_keys


Once the file has been copied to each server, try to log in to your other server from your Asterisk@Home 2.2 server with the following command using the correct destination IP address, of course:

ssh root@192.168.0.104

You should be admitted without entering a password. If not, repeat the drill or read the complete article and find where you made a mistake. Now log out of the other server by typing exit.

Installing WebMin. We don't build Linux systems without installing WebMin, the Swiss Army knife of the Linux World. You can use it to start and stop services, check logs, adjust startup scripts, manage cron jobs, babysit your SendMail server, and many, many other tasks that are downright painful without it. If you ever need help from others, WebMin is a great tool for letting others help you.

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. Note that there is a new version of WebMin since our article on Asterisk@Home 2.0. It fixed a major security flaw in some of WebMin's perl scripts so you'll definitely want this upgrade:

cd /root
mkdir webmin
cd webmin
wget http://internap.dl.sourceforge.net/sourceforge/webadmin/webmin-1.250-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. We really don't want the WebMin server starting up each time the OS reboots so do the following. Once you're logged in to WebMin, choose System->Bootup and Shutdown and then click on webmin. Click the No button beside Start at boot time, and then click the Save button. 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 used to be 10000 to 20000 so there's a conflict on port 10000 with WebMin. Beta 6 fixed this, but version 2.2 doesn't have the change. So, if it still says 10000 on your system, 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. Then restart Asterisk: amportal restart. Finally, to stop WebMin when you're finished using it, issue this command: /etc/webmin/stop. You can start it any time you need it, and then use a web browser to access it. But there's no need to consume processing resources running a second web server when you're not using it.

Basic System Configuration. To get a basic Asterisk system up and running, you only need to do a few things. First, you need an Outbound Trunk to actually deliver your outbound calls to Plain Old Telephones (POTS). Second, you need to configure an Outbound Route to tell Asterisk which trunk to use to deliver your outbound calls to the intended recipients. Third, you need to configure at least one extension so that you can plug in some sort of telephone instrument to place and receive calls using your new Asterisk server. The phone can be a hardware device such as an IP telephone or a POTS phone, or it can be a software device such as a free IP softphone. The advantage of IP telephones and softphones is that they require no additional hardware besides your Asterisk server. A POTS phone or our favorite, a 5.8GHz wireless phone system with up to 10 extensions, both require an additional piece of hardware although some of the newer IP wireless phones give you the best of all worlds (see inset). To use a POTS phone, the hardware required is either a circuit board with an FXS port or an external black box (ATA device) such as a Sipura SPA-1001. If you also want to connect your Ma Bell phone line to your Asterisk server, then you need a circuit board with an FXO port or an external black box (ATA device) such as a Sipura SPA-3000. Our favorite is the SPA-3000 because it has both FXO and FXS ports in a box the size of a pack of cigarettes for under $100.

Setting Up An Outbound Trunk. You configure an outbound trunk using your web browser and the Asterisk Management Portal (AMP). But first, you have to have an account with a service provider. This is the company that carries your calls from your Asterisk server to plain old phones in your neighbor's house or Aunt Betty's in California. With VoIP, it's a good idea to have two providers, but today let's start with one. We'll save you some time and lots of money. Unless you make substantial international calls regularly, use TelaSIP/VoipExpress. If you want to know why, read the full article here. Or just try a free call for yourself using our server. Basically, $5.95 a month gets you a local number in your choice of area code with free incoming calls, and 2¢ per minute for outbound calls to anywhere in the U.S. $9.95 a month buys you all of that plus free outbound calls in the area code of the phone number you select. $14.95 a month gets you a number in the area code of your choice with unlimited incoming calls and unlimited outbound calls to anywhere in the U.S. There are no sneaky add-on fees and no obnoxious terms of service. Just be sure to tell them to configure your account for use with Asterisk. They also have very reasonable business plans. If, on the other hand, you'd prefer to try another provider, take a look at our easy setup guides for most of the major VoIP providers here.

Once you have your account name and password, point your web browser to the IP address of your new Asterisk@Home 2.2 server and log in as maint with the password you selected. Then choose AMP->Setup->Trunks->Add SIP Trunk assuming you're using TelaSIP. NOTE to existing users: if you already have an Asterisk server using your TelaSIP account, don't use the same account at the same time on your new Asterisk@Home 2.2 server! Plug in the CallerID number you were assigned for your account. Set Maximum Channels to 2. For the Dial Rules, use the following (substituting your local area code for 404 below):

1|NXXNXXXXXX
NXXNXXXXXX
404+NXXXXXX

In the Outgoing Settings section, name your trunk telasip-gw. Then enter the following for the Peer Details using your own account name for username and fromuser and using your own assigned password for secret:

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

Leave the Incoming Settings section blank, and in the Registration String, enter the following using your account name and password:

youraccountname:yourpassword@gw3.telasip.com

Click the Submit Changes button, and then click the red bar to reload Asterisk. Now we need to add the context which will actually process the incoming calls from TelaSIP. Choose AMP->Maintenance->Config Edit->extensions_custom.conf and add the following code at the bottom of the file substituting your new phone number for 4041234567. Save the file and reload Asterisk to finish the setup. See the Comments to this post for a more versatile approach which will let you use your TelaSIP line for Ring Groups.

[telasip-in]
exten => 4041234567,1,NoOp(Incoming call on TelaSIP #4041234567)
exten => 4041234567,2,Dial(local/200@from-internal,20,m)
exten => 4041234567,3,VoiceMail(200@default)
exten => 4041234567,4,Hangup


Configuring an Outbound Route. Now we need to tell Asterisk where to send our outbound calls when we dial them. To get started, we'll just send everything to the TelaSIP trunk we just configured. Choose AMP->Setup->Outbound Routing->Add Route. For Route Name, use Outside. Leave the password blank. For Dial Patterns, enter the following:

NXXXXXX
NXXNXXXXXX
1NXXNXXXXXX

For the Trunk Sequence, choose SIP->telasip-gw from the drop-down list. Then click Submit Changes. Be sure you also delete the sample outbound route that came with the install, or your outbound calls may go nowhere. Finally, click the red bar to save your new Outbound Routing setup.

Configuring an Extension. You have to have an extension to make and receive calls with Asterisk@Home so let's build one. Choose AMP->Setup->Extensions->SIP to begin. For the Extension Number, let's use 200 to keep things simple. For the Display Name, make up something that tells where this phone will be located, e.g. Kitchen. For the Outbound CID, use 200. For secret, make up a password for this extension. For Voicemail and Directory, choose Enabled. Plug in your password again. Type in your email address, and, if you want to also be paged when you get a new voicemail, type in a pager email address. Click the Yes button beside Email Attachment, and leave the other settings alone. Now click the Submit button. You'll see a couple of ugly error messages. Ignore them. It's a beta bug. Just click the red bar to save your changes and reload Asterisk.

Downloading a Free Softphone to Test Asterisk. Unless you already have an IP phone, the easiest way to get started and make sure everything is working is to install an IP softphone. You can download a softphone for Windows, Mac, or Linux from CounterPath. Or download the pulver.Communicator. Both are free! Just install and then configure with the IP address of your Asterisk@Home 2.2 server. For username and password, use your extension number and password from above. Once you make a few test calls, don't waste any more time. Buy a decent SIP telephone. We think the best value in the marketplace with excellent build quality and feature set is the under $100 GrandStream GXP-2000. It has support for four lines, speaks CallerID numbers, has a lighted display, and can be configured for autoanswer with a great speakerphone. Short of paying three times as much, that's as good as desktop phones get. If you want to use Asterisk throughout your home, buy a good 5.8GHz wireless phone system with plenty of extensions (our two favorites are shown in the insets below) and then purchase an SPA-3000 to connect up both your home phone line and all your cordless phones. Our tutorial will show you how. The final option is to use a wireless IP phone which is the best of both worlds, a cordless phone that talks IP telephony without an ATA blackbox such as the Uniden UIP1868 (see also insets above).

Activating Email Delivery of VoiceMail Messages. When you're out and someone leaves you a voicemail message, Asterisk@Home will let you forward that voicemail message to your email address as a .wav file which can be played within most email client software. Or you can have Asterisk@Home send an instant message to your cell phone or pager telling you who called, what their phone number was, and how long a voicemail message the person left for you. Or you can do both. In addition, you can tell Asterisk@Home whether to delete the voicemail from your Asterisk server after sending it to your email account. In short, you now can manage all of your incoming email and voicemail from a single place, your email client. In order to send out emails from your Asterisk@Home server, you'll need to make two changes. First, make this adjustment to the /etc/hosts file on the server. Since anonymous emails are blocked by most ISPs, you'll need a fully-qualified domain name for your server. If you don't have your own domain, the easiest alternative is to use the fully-qualified domain name that your ISP assigns to the IP address for your broadband connection. Don't forget to update it when your ISP changes your IP address! To find out what your fully-qualified domain name is, go to a command prompt on your Asterisk server and type: nslookup 123.456.789.001 substituting your public IP address for the preceding numbers. Then write down the name entry without the trailing period. Now edit the hosts file: nano /etc/hosts. Move the cursor to the second line which reads 127.0.0.1 asterisk1.local , and then move the cursor over the first letter of the first domain name shown, usually asterisk1.local. Now type in the fully-qualified domain name you previously wrote down and add a space after your entry. Don't erase the existing entry! Save your settings: Ctrl-X, y, enter. Now restart network services on your Asterisk machine: service network restart. Next, you need to modify the email message which delivers your voicemails so that it includes your fully-qualified domain name. Don't do this in AMP, or you'll mess up the formatting of the email message. You can download a fresh copy here if you need it. Instead, use nano: nano -w /etc/asterisk/vm_email.inc. Press Ctrl-W, type /cgi, and press the enter key. You're now positioned where you need to type either the fully-qualified domain name for your Asterisk server or the private IP address if you only want to read your emails from behind your firewall. When you start typing, the text display is going to jump all over the place because of word wrap. Don't freak out. You haven't messed anything up. Once you complete your entry, don't erase or change anything else. Save the file: Ctrl-X,Y, then enter. Now go into AMP->Maintenance->Config Edit->vm_general.inc with a web browser. Change the serveremail entry to an email name at the fully qualified domain you used in your /etc/hosts file above. Then save your configuration and restart Asterisk. If you continue with this setup and still don't receive emails, here's another configuration change that is sometimes necessary. On the Asterisk terminal, log in as root. Switch to the directory where the SendMail configuration file is stored: cd /etc/mail. Make a backup of the config file: cp sendmail.cf sendmail.cf.bak. Then issue the following command: echo CGasterisk.dyndns.org >> sendmail.cf. Substitute the actual domain name of your Asterisk server for asterisk.dyndns.org, but be sure it's preceded by CG with no intervening spaces.Then reboot your server and try again: shutdown -r now. Finally, if your ISP doesn't permit downstream mail servers (that's you), then take a look at this link which will show you how to designate your ISP as your SMTP smart host using SendMail.

To configure the voice mail forwarding options, go into the Setup tab of the Asterisk Management Portal using a web browser. Click on Extensions and then click on an extension you already have configured. In the Voicemail and Directory section of the form, enter either (or both) your email address and your pager or cellphone's text messaging address. To email the voicemails as attachments, just click Yes beside Email Attachment. To delete the voicemail message from your voicemail inbox after sending it to your email address (not recommended until you first get it working correctly), click Yes beside Delete Vmail. For those using a dynamic IP address with phones at remote locations connecting to your Asterisk server, we'll show you how to automate the process of changing your Asterisk server's IP address in a future column.

Call Recording Fixed. This update fixes inbound and outbound call recording which now works reliably. You can set your preferences for call recording when you set up each extension. The recordings are stored in /var/lib/asterisk/monitor unless you set other preferences in agents.conf.

Paging Fixed. If you want to use paging with your Asterisk system, the sound card problems in Asterisk@Home 2.1 and Asterisk 1.2 have been resolved. Review this posting on SourceForge for additional details. It now works with full and half-duplex sound cards. Thanks, Tracy!

Wakeup Calls Broken. Asterisk@Home 2.2 includes part of a new version of the Wakeup Call program. Unfortunately, it doesn't work. Fortunately, the old version still does. And, we've also fixed the code in the new version. To reload the old version, log into your server as root and issue the following commands:

cd /var/lib/asterisk/agi-bin
mv wakeup.php wakeup-new.php
wget http://nerdvittles.com/wakeup.zip
unzip wakeup.zip
rm wakeup.zip
chmod 775 wakeup.php
chown asterisk:asterisk wakeup.php

Or, if you'd prefer to use a patched copy of the new version, log into your server as root and issue these commands instead:

cd /var/lib/asterisk/agi-bin
mv wakeup.php wakeup-new.php
wget http://nerdvittles.com/wakeupnew.zip
unzip wakeupnew.zip
rm wakeupnew.zip
chmod 775 wakeup.php
chown asterisk:asterisk wakeup.php

There are basically two problems with the new wakeup code. The first is that a number of the voice files are assumed to be in /var/lib/asterisk/sounds/extra, a directory which doesn't exist in the Asterisk@Home setup. We've fixed that problem in the wakeupnew.zip file which you can install above. The second problem is that the wakeconfirm application is missing entirely. This is used to prompt the user to answer a question ... to make sure the person is REALLY awake. This application is not enabled in the default setup so just don't activate it until we can do a little more investigative work.

Adjusting Call Parking Extensions. Traditionally, dialing extension 700 parked a call on Asterisk@Home systems, and the call could be picked up by dialing the parked extension in the range of 701 to 799. To retain this setup, you'll need adjust the settings in features.conf. Go to AMP->Maintenance->Config Edit->features.conf and make it look like this:

[general]
parkext => 700 ; What ext. to dial to park
parkpos => 701-799 ; What extensions to park calls on
context => parkedcalls ; Which context parked calls are in


Directory Lookup Fixed. Pressing the pound key (#) from any phone connected to your Asterisk server now calls up a directory lookup function using the Asterisk Management Portal (AMP).

Max Channels Bug. A bug has been reported because of a deprecated command that makes Asterisk@Home's calculation of maximum channels invalid. To fix it, goto AMP->Maintenance->Config Edit->extensions.conf->macro-dialout-trunk and comment out line s,7 so that it looks like this:

;exten => s,7,CheckGroup(${OUTMAXCHANS_${ARG1}})

Then insert a new line s,7 just below it which looks like this:

exten => s,7,GotoIf($[ ${GROUP_COUNT()} > ${OUTMAXCHANS_${ARG1} ]?108)

Then click the Update button and reload Asterisk to activate the change.

Tweaking SIP.conf. There are a few changes we recommend you make in the [general] context of the sip.conf file. Using the Asterisk Management Portal, go to AMP->Maintenance->Config Edit->sip.conf. It's a good idea to include your actual CallerID number of your default outbound trunk here instead of Default. We also recommend that you add allow=gsm just below the existing allow=alaw line in the file. You may also want to include progressinband=yes which assures that callers will hear ring tones when placing calls even if your provider doesn't provide them. This is a fairly common complaint with BroadVoice in particular. Don't forget to reload Asterisk once you make these changes: AMP->Setup->Incoming Calls->Submit Changes and then click the Red bar.

Connecting Remote Extensions or a Remote Asterisk Server. If you plan to connect remote extensions to your Asterisk server, then add the following entries to sip.conf above using your own fully-qualified domain name and the first three octets of the private IP address of your Asterisk server:

externip = myasteriskbox.dyndns.org
localnet=192.168.0.0/255.255.255.0
nat=yes

You'll also either need to define your Asterisk server as a DMZ device in your firewall setup, or you can open the following UDP ports and map all of them to the private IP address of your Asterisk box: 4569, 5004-5082, and 10000-20000. If you only hear half of a conversation with a remote extension, it's usually a NAT problem meaning you probably forgot to do the port mapping drill. We plan to cover remote extensions and interconnecting Asterisk servers in more detail in a future column so stay tuned. In the meantime, if you have a dynamic DNS connection that changes your IP address regularly and you don't want to wrestle with manually updating your Asterisk server each time there's a change, just download chandave's sip reload script and copy it to your /etc/asterisk directory. Then execute the following commands while logged in as root:

chown asterisk:asterisk /etc/asterisk/sip_reload.sh
export EDITOR=nano
crontab -e
00,05,10,15,20,25,30,35,40,45,50,55 * * * * root /bin/sh /etc/asterisk/sip_reload.sh >/dev/null 2>&1

Save your crontab addition in the usual nano way, and you're all set: Ctrl-X, y, then enter. This clever little script will make sure your Asterisk server always knows its own IP address regardless of how often your ISP changes it. And you'll never lose inbound connectivity from remote extensions or servers for over 5 minutes. If you'd like to read the full discussion, visit this link on the Voxilla forum.

Managing Incoming Calls. For long time readers of this column, you already know that our recommended strategy for handling incoming calls is to set up a simple Stealth AutoAttendant. Basically, this is a welcome message that greets your callers and then transfers them to an extension or ring group of your choice. The advantage of this approach is that it also lets callers like you press buttons to navigate through various options on your Asterisk system without advertising them to the public at large. If you're just getting started with Asterisk, you can read all about setting up a Stealth AutoAttendant here. If you'd prefer to manage your incoming calls with AMP, you'll still need to fix the [from-sip-external] context in the extensions.conf file, or all your incoming SIP and IAX calls will ring busy. To fix it, choose AMP->Maintenance->Config Edit->extensions.conf->from-sip-external. Comment out all the lines in the existing file by adding a semicolon at the beginning of each line. Then add the following line, save your changes, and reload Asterisk.

exten => _.,1,Goto(from-pstn-timecheck,s,1)


New Custom Speed Dialing. Asterisk@Home 2.2 has a built-in speed dialing utility. The reserved speed dial numbers are 300 to 399. Adding a number to your speed dial list is easy. Just pick up an extension and dial 300-3xx-6781234567 where 3xx is the speed dial code you want to create and 6781234567 is the phone number you want dialed when you enter the speed dial code. Just make sure you enter the number to be called in a format that is supported by your Asterisk dialplan, i.e. if outside calls need to be preceded by a 1 or a 9, then the number should be entered in a matching format. You can look up speed dial numbers by dialing an asterisk followed by the 3-digit speed dial code, e.g. *301 would tell you the number stored in speed dial 301. If you need additional flexibility with both web browser and phone access as well as 1 to 5-digit speed dial codes, download our free AsteriDex robodialer.

Fixed A2Billing: Asterisk Calling Card Platform. This web-based application allows you to generate and issue calling cards to individuals so that they can place calls remotely through your Asterisk server. If you've always wanted to be just like AT&T, here's your Big Chance! There's very little that you can do with an AT&T calling card that can't be done as well or better by you using A2Billing. And, it won't take an M.B.A. to undercut AT&T's calling card rates and still make buckets of money. All you need now are a few customers. Heck, I'll sign up with you. I sign up for everything. But first, a word of caution. Assuming your Asterisk server has web exposure on the Internet, you need to secure the admin and root passwords in this application whether you use it or not. To access the application, go to http://192.168.0.104/a2billing/ using the actual internal IP address of your Asterisk server. Log in as root with a password of myroot. Click on the ADMINISTRATOR tab in the left column and then click Show Administrator. Now click on the Edit button beside each of the two administrator accounts and change the passwords to something secure. If you really would like to learn more about it, documentation for the application is available here. And, if you decide to use the application, you'll need to uncomment the actual dialplan lines in extensions_custom.conf and reload Asterisk:

; CallingCard application
; un-comment the 5 lines below to use this app
;exten => _X.,1,Answer
;exten => _X.,2,Wait,2
;exten => _X.,3,DeadAGI,a2billing.php
;exten => _X.,4,Wait,2
;exten => _X.,5,Hangup

Footnote: The missing A2Billing code from Asterisk@Home 2.1 has been added. You can read all about the problem here. There's also a pretty good step-by-step setup guide for Asterisk@Home 2.2 here.

SugarCRM Contact Management. Asterisk@Home includes the latest and greatest version of the best open source contact management application on the planet, SugarCRM. You access the application with a web browser: http://192.168.0.104/crm/ substituting the private IP address of your Asterisk box, of course. Specify admin for your username and password for your password. Whether you use the application or not, change the admin password. It's easy. Just click the Administrator link under Welcome admin. Then click the Change Password button. Complete documentation for the application is available here. If contact management is your thing, knock yourself out, and we'll talk to you next spring when you finish getting everything set up to run your business. It's a great product, but be prepared to invest lots of time in the project if you expect to use it productively.

Other Out-of-the-Box Utilities. Asterisk@Home 2.2 comes bundled with a number of additional utilities. Here are some of them. You can retrieve the current time by dialing *60. If the time is wrong, you can reset your default time zone by logging into your server as root and typing config. A current weather report for New York is available by dialing *61. You can change the city by following our previous tutorial which is available here. To set up a wakeup call from any extension, dial *62. To determine the phone number of any extension, just dial *65. You can use the default MeetMe conferencing system from any or all of your extensions by dialing 8 plus the number of an existing extension. Additional conference rooms can be added by editing meetme_additional.conf. Finally, you can record customized voice prompts for your system by dialing 5678 from any extension. Before this will work, edit the extensions_custom.conf file (AMP->Maintenance->Config Edit->extensions_custom.conf) and uncomment the seven lines shown below which are located at the bottom of the file. Just remove the leading semicolons. You'll also need to uncomment the following line near the top of file at the beginning of the [from-internal-custom] context: ;include => custom-recordme.

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

Once you make a recording, it needs to be moved to /var/lib/asterisk/sounds/custom with a new filename.gsm, e.g. mv /tmp/asterisk-recording.gsm /var/lib/asterisk/sounds/custom/hihoney.gsm. Then change the ownership of the file: chown asterisk:asterisk /var/lib/asterisk/sounds/custom/hihoney.gsm. You then can play the recording with a line like this in your dialplan: exten=>s,1,Playback(custom/hihoney) where hihoney is the name you assigned to the recording without its .gsm extension.

Where To Go From Here. After you get a functioning Asterisk system, you're ready to move on to the really cool things that make Asterisk a one-of-a-kind PBX. There are customized weather reports, web and phone-based dialers from a MySQL address book, incoming fax to PDF conversion with email delivery, blacklisting of telemarketers, bluetooth proximity detection so that your home or office calls automatically transfer to your cellphone when you depart with your bluetooth device, and on and on. You'll also want to take a more in-depth look at many of the topics we've covered above. For a complete catalog of all of our Asterisk projects and everything else we've written about Asterisk@Home, go here. Then take a look at a terrific writeup from the other side of the globe: Asterisk@Home for Dumb-Me. Finally, there's an Asterisk@Home Handbook Wiki project under development that's worth a careful look. Enjoy!

Some Recent Nerd Vittles Articles of Interest...

One of the first things you learn after you purchase a new aquarium is that you're much better off with two tanks rather than one. This generally doesn't make the little Mrs. too happy but, after you explain that each dead fish represents a $100 bill, most wives usually come around. YMMV! You'll learn much the same thing with Asterisk®. It's not that new versions are that terrible. They're not. In fact, they're generally a quantum leap better and less buggy than the version you're replacing. It's just that programmers have this death wish to always "improve" everything. I've had lots of programmers work with me over the years, and the hardest thing to get across to them short of branding or tattooing the message directly onto their heads is this: "If It Ain't Broke, Don't Fix It!" The gotcha in Asterisk 1.2 was leaving out the sound card driver, chan_oss.so, which broke every company's paging system ... at least all those companies that now depend upon Asterisk. Digium® apparently has fixed the problem in the just released Asterisk 1.2.1, but it still ranks up there as a big mistake that should and could have been avoided. The silver lining in this tale is that it prompted a single individual, Tracy Carlton, to stay up an entire night trying to figure out what had come unglued. In the process, Tracy uncovered why the chann_oss.so driver has never worked with half-duplex sound cards, you know, the type that comes standard in virtually every PC on the planet. Guess what? Now it works with one simple tweak. You can read all about sound cards and paging in Tracy's post on SourceForge. Don't miss it! And, speaking of not missing it, the next time you come through our hometown of Atlanta, don't miss the new Georgia Aquarium (see insets). Known affectionately as Fish Depot because it was funded privately by Bernie Marcus of Home Depot fame, it's truly one of a kind and destined to become one of this country's national treasures. The Showstopper: an unbelievably friendly, 3,000 pound Beluga whale (inset below). And the mascot: a little orange fish called a garibaldi appropriately named ... Deepo.

What does all this have to do with Backups and Redundancy? Plenty. You'll save yourself and your customers a boatload of grief by thoroughly testing new Asterisk releases before you put them into production. Asterisk is such an exciting technology that it's always tempting to deploy the latest, greatest version immediately to take advantage of some new bell or whistle. The downside is what happened with paging in Asterisk 1.2. I'm no longer dumbfounded by developers that don't try everything before releasing an upgrade. There just isn't time, and usually it's not very exciting work either. Plus, it requires a substantial hardware investment. Your best defense is a sandbox (aka clunker) PC that can be used for all sorts of things. First, you can try out new releases. And second, for about $100 on Ebay, you can buy a great Asterisk@Home PC which can do all sorts of other things, too ... like automatic full system backups. If you're feeling rich, buy another Wal-Mart special for under $200, and you've got a great alternate server/backup/sandbox all rolled into one. Or, if you previously built our dual-system Bluetooth Proximity Detection System, then you're all set. And, yes, we're going to get software RAID 2 working with Asterisk@Home 2 one of these days for those that want a mirrored hard disk, but first things first. RAID doesn't offer the same protection as a good, frequent backup. Mirrored RAID drives immediately copy everything from one disk to another, mistakes and all. So, if you clobber a config file or driver by pressing the wrong button, a mirrored drive won't help you at all. It'll just give you a second copy of your original mess. So today we're going to show you a painless backup strategy that'll get you through almost any disaster except perhaps Katrina or a fire that totally destroys your home or office.

Overview. Our project for today is to build a bullet-proof backup system between your two Asterisk@Home systems. Yes, Asterisk@Home can be configured to make backups, but it puts them on the same hard disk as your system, not too helpful with a disk crash. That's not to say you shouldn't implement the Asterisk@Home backups. They're a great resource when you accidentally clobber something. It's easy: AMP->Setup->Backup and Restore->Add Backup Schedule. Give it a name and set everything to Yes. Then select Run Daily at Midnight. Click Submit Changes and then the red bar to reload Asterisk. Just don't forget to clean out some of the daily backups from time to time. They live in /var/lib/asterisk/backups under a directory name matching whatever you named your backup schedule.

The dual-PC backup system we're going to build today works well for almost any two Linux systems since Asterisk@Home really is a Linux system. It also works swimmingly on systems running BSD or MacOS X. If you need help getting either or both of your Asterisk systems set up, start here. And the software cost of the project: still $0. For those with a small business and one or more satellite offices, next week we'll tackle tying multiple Asterisk systems together for instant communications between your offices. Yet another freebie for those that deploy today's backup system. But we're getting ahead of ourselves. The drill for today is to use our previous SSH automatic login trick to enable us to do scheduled backups in the background on one or both of your systems. Lucky for us, CentOS includes the rsync utility which makes mirror image backups using SSH as the transport between two systems. Here's the step-by-step if you want to follow along.

Password-Free SSH Access. As with our Proximity Detection System, we want to use SSH for our backups to protect our sensitive data. After all, there's no reason that your two Asterisk@Home systems have to be in the same building. One can be across town or around the globe. This backup system will work exactly the same ... just slower. But to automate the process, we need to use crontab to schedule the backups. That means there will be no user interaction in the backup process. As you know, SSH typically prompts for a password when you connect to a remote resource. So here's the trick we introduced in our Bluetooth project. We'll do the same thing for backups. And, if you want to backup both of your systems, you'll need to perform this trick in both directions, i.e. from Server A to Server B and from Server B to Server A. For ease of explanation, we're going to refer to the servers as Asterisk Main and Asterisk Backup. You can extrapolate for your own systems from there. We're going to go through this example assuming you want to backup the data on Asterisk Main to Asterisk Backup. Once you complete the steps, there's no reason you can't reverse the process and also backup Asterisk Backup to Asterisk Main. We'll leave that for you to work out on your own. Just let us know if you get stumped.

To begin, log in to Asterisk Main as root. Then, from the command prompt, issue the following command: ssh-keygen -t rsa. Press the enter key three times. You should see something similar to the following. The file name and location in bold below is the information we need:

Generating public/private rsa key pair.
Enter file in which to save the key (/root/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /root/.ssh/id_rsa.
Your public key has been saved in /root/.ssh/id_rsa.pub.
The key fingerprint is:
1d:3c:14:23:d8:7b:57:d2:cd:18:70:80:0f:9b:b5:92 root@asterisk1.local

Now copy the file in bold above to your Asterisk Backup server from Asterisk Main using SCP. The command should look like the following (except use the private IP address of your Asterisk Backup server instead of 192.168.0.104). Provide the root password to Asterisk Backup when prompted to do so.

scp /root/.ssh/id_rsa.pub root@192.168.0.104:/root/.ssh/authorized_keys

Once the file has been copied, you now should be able to log in to Asterisk Backup from Asterisk Main with SSH without being prompted for a password. Let's try it. Log in to Asterisk Backup from Asterisk Main with the following command using the actual IP address of Asterisk Backup, of course:

ssh root@192.168.0.104

You should be admitted without entering a password. If not, repeat the drill or read the complete article and find where you made a mistake. While you're logged in to Asterisk Backup, let's create the directory where your Asterisk Main system will be stored: mkdir /backup. We're assuming you have sufficient disk space on Asterisk Backup to store the complete contents of Asterisk Main. If you're not sure, issue the df command on both systems and be sure. Here's a sample from our system:

[root@asterisk1 backup]# df

Filesystem 1K-blocks Used  Available Use% Mounted on
/dev/hda2  27980732 4625788 21933596 18% /
/dev/hda1   101086   11077  84790    12% /boot
none         62612       0  62612     0% /dev/shm


The device we care about is /dev/hda2. That's where your backup data will reside. The Available column will tell you how much space is left on Asterisk Backup. When you run the same df command on Asterisk Main, the Used column for /dev/hda2 will tell you how much room you need to reserve on Asterisk Backup to hold the backup. Finally, if you should ever want to delete the /backup directory and all the backup data stored on Asterisk Backup, here's the command to do it: rm -rfd /backup. You get no warnings! Now log out of Asterisk Backup by typing exit. Then rerun the df utility on Asterisk Main to see how much space will be needed for the backup. Incidentally, all of the remaining steps in this tutorial will be performed on Asterisk Main.

Using rsync for Asterisk@Home Backups. There are a number of great tutorials on rsync. If you want to learn more than what's covered below, start here. We did. The actual command we're going to use to make our backups is shown below. It will make the first backup and then freshen it each time you run it in the future. We recommend running the command manually the first time to be sure everything is working as it should. When the rsync session completes (5-10 minutes on a new system with a 100 megabit Ethernet connection between the servers), issue the following command to check the rsync log for errors: tail /var/log/backup.log. If errors are reported, you can open the log with nano (nano /var/log/backup.log) to search for errors (Ctrl-W, failed to open). Then close nano (Ctrl-X, n). Typically, errors involve changes during the backup process, such as deleting a voicemail message while the backup is in process. Normally, running rsync again will solve any problems. Once you get a clean backup, move on to the Automating Backups step below.

rsync -avvz --delete --exclude "/proc/" --exclude "/mnt/" --exclude "[cC]ache" -e ssh / root@192.168.0.104:/backup/ > /var/log/backup.log

WARNING: If you cut-and-paste the code above, make sure you adjust the quotation marks which get mangled by the WordPress blog.
Both Linux and Asterisk like and want regular quotation marks in all commands or disaster awaits!

The only change you'll need to make in the command above is to replace the quotes and the 192.168.0.104 IP address with the actual IP address of your Asterisk Backup server. This will backup everything on Asterisk Main except cache files, the /mnt directory (which includes the contents of any mounted CD-ROM), and the /proc directory (which includes a bunch of stuff that would be unchanged if you did a clean Asterisk@Home install).

Restoring Your Asterisk@Home System. For future reference, to do a full system restore of Asterisk Main with a new hard disk, you would first reinstall Asterisk@Home from the same installation disk used to create Asterisk Main. Then you would restore the backup data from Asterisk Backup by logging into Asterisk Main as root and manually issuing the following commands:

cd /
rsync -avv -e ssh root@192.18.0.104:/backup/ . > /var/log/restore.log

Of course, we're assuming the IP address of your Asterisk Backup server is 192.168.0.104 in the above example so change it to properly reflect your Asterisk Backup's IP address. And don't forget the space and period and space in the above command. That's what tells rsync to restore your backup to the current folder location.

Automating Backups. Now that you have rsync working reliably, we want to automate the Linux backup process so that it runs each night without user intervention. This will assure that you never lose more than one day's data which usually isn't life threatening in the telephone business. If it is, you can adjust the crontab schedule to better meet your requirements. To begin, download the backup script here. Now log in as root and copy the script to /etc/asterisk on your Asterisk Main server. Reset the permissions: chmod 775 /etc/asterisk/backup.sh. Fix the ownership: chown asterisk:asterisk /etc/asterisk/backup.sh. And adjust the IP address in the file to match the IP address of your Asterisk Backup server: nano -w /etc/asterisk/backup.sh. Finally, add the script to your crontab to kick off at 2:01 a.m. each morning, save your update (Ctrl-X, Y, then enter) and you're all set to go.

export EDITOR=nano
crontab -e
01 02 * * * /etc/asterisk/backup.sh >/dev/null 2>&1


Coming Attractions. Yes, we're finally going to cover faxing later this week or early next week. And, the #1 requested feature for Asterisk, call presence monitoring with pickup button support, is now a reality. And soon we'll show you how to use it to mimic the key telephone instruments that corporate America just can't seem to live without. There also are new versions of both Asterisk (1.2.1) and Asterisk@Home (2.2) with more bug fixes so we'll have an updated HOW-TO guide for you shortly. Finally, as mentioned previously, we'll connect up our two new Asterisk servers to communicate with each other and start sharing extensions and dialplans as soon as Weekly UPDATE-itis comes to a close.

BroadVoice in the News. Well, it looks like our old pals at BroadVoice are back in the news ... at least with the Better Business Bureau. See this link where BroadVoice finishes in second place for most complaints out of 77 telephone providers over a three year period. And, better yet, BroadVoice would retain or perhaps better their ranking if the numbers were based upon just the past 12 months. In fact, all but one of the complaints filed against BroadVoice were filed within the past 12 months. And, yes, there is a silver lining to this story, too. BroadVoice for the most part gives BBB complaints the same great treatment that we've received when inquiring about a problem ... nada!

We’ve pretty well documented how you can set up Bluetooth Proximity Detection using a bluetooth headset or cellphone with your Asterisk® PBX. Once configured, phone calls in your home or office can automatically be transferred to your cellphone whenever you take off carrying your bluetooth device. In our original articles, you’ll recall that we recommended a bluetooth headset as the ideal way to track your comings and goings at very little cost. But today, we want to add another bit of magic to the project and also give you something to tell Santa about. It’s the incredible Tom Tom Go, a portable GPS device that has the Garmin’s of the world shaking in their boots because this thing is so easy to use and just does everything right. Having endured absolutely terrible built-in GPS units in both Cadillac and Mercedes Benz automobiles and not-much-better Garmin units, take it from us. Buy a TomTom. Our Cadillac GPS had to be replaced four times and finally with a unit from a later 2005 Escalade before you could store a location and call it up without crashing the entire system. And GM wonders why they’re losing money. Worse yet, to put a name with a location using the Mercedes GPS still requires a trip to the manual. It’s that painful and unintuitive! So, when your friendly car dealer touts the built-in GPS devices in their automobiles, JUST SAY NO! We haven’t seen a built-in unit yet that doesn’t suck.

Some Hints for GPS manufacturers: Nobody wants a GPS that reproduces an entire paper street map on a 4 inch screen. We’re trying to figure out how to get somewhere! What’s important is the name of the street you’re on, the names of the next few cross streets, and how far to drive until the next turn. Which way to turn with a little advance warning is also a nice touch. And, by the way, we’re smart enough to know not to be fiddling with the GPS while the car is moving so don’t lock the damn unit when the car is moving. In case you haven’t heard, some cars can actually have more than one person riding in them at the same time. They’re called passengers, and they can even chew gum and operate a GPS while seated in the passenger seat. Bozos! Here’s the best hint of all: Go buy a TomTom for you and your company and copy what they’ve done.

TomTom at a Glance. With the TomTom, you can either get the flash drive model 300 with the entire U.S. and Canada maps on a single chip, or there’s a hard disk version 700 which also gives you a hands-free speakerphone and phonebook for use with your compatible bluetooth cellphone. Treo 650 fans are SOL. Both TomTom models provide automatic route calculation and turn-by-turn directions through a built-in speaker. And, with either unit, you also can get traffic reports and the latest weather forecasts not to mention points of interest alerts showing where every "safety" camera is located in many European countries. If you can’t figure out how to use a TomTom in under 15 minutes, you need to stay away from anything that uses electricity. Yes, it’s that good. And all the TomTom units are Linux-based so you can download the source code and build your own GPS if that’s your thing. Circuit City will even let you try a TomTom for two weeks and return it for a full refund. So take them up on the offer. Then, if you decide to buy one, take the Circuit City unit back and buy it on the web. It’ll save you over $200! With the current $50 rebate and free U.S. traffic reports, the TomTom Go 300 can be purchased for under $500 with some careful shopping (HINT: PriceGrabber.com). See how nice we are! We could have encouraged you to click on the link below and actually make us a little money … but who needs it, right?

Using a TomTom for Proximity Detection. Once you have your TomTom Go device, you also can use it in our Bluetooth Proximity Detection system in lieu of a headset. Here’s how. Because the TomTom unit is designed to allow you to download weather reports and traffic information using your bluetooth-enabled cellphone, that, of course, means the TomTom unit talks bluetooth. So, just like your bluetooth headset, the only trick is discovering the MAC address of the TomTom’s built-in bluetooth adapter. The device is designed to operate on its internal battery for a day at a time. Thus it’s pretty simple to carry the unit to your Asterisk server and turn it on. Once it’s on, tap the screen once, tap the right arrow icon twice to move to the third page, and then tap TomTom Weather. When prompted whether to set up your wireless internet connection now, tap Yes. While logged into your Asterisk server, type hcitool scan and, presto, your TomTom unit will dutifully report its MAC address for all the world to see:

[root@asterisk1 tmp]# hcitool scan
Scanning ...
00:0F:3D:4B:DF:E0 n/a

N/A doesn’t tell you much, but it’s your TomTom. Trust us on this one. Once you have this tidbit of information, simply edit your ruhome script and plug in the required information:

mainasteriskbox=192.168.0.118
deviceuser=TomTom
devicemac=00:0F:3D:4B:DF:E0


Now, when you drive your automobile into your garage, your home phones will come back to life. The only wrinkle, of course, is that you’ll need to leave your GPS unit powered on while you’re home. Otherwise, powering down the TomTom would tell your Asterisk server that you had departed again. Yeah, you’re right. It’s not ideal, but it did give us the opportunity to offer a great tip for your Christmas wish list. And it ought to get you thinking that this particular device is well-suited to integrate into your home automation system to turn on the lights and hot tub. With home automation system software such as Indigo and its AppleScript object model and dictionary or Salling Clicker, you don’t have to worry about the TomTom turning itself off in the garage because all we really need is the proximity "trigger" to alert Indigo to turn on the lights. Once on, you can program Indigo to define how long the lights stay on before automatically turning themselves off again. Problem solved.

Implementing Proximity Detection on a Single Asterisk@Home 2.1 Server. Our original articles on how to deploy a Bluetooth Proximity Detection System assumed you were using two Asterisk servers, one for phone calls and a second version 2 server for proximity detection. However, now that Asterisk@Home 2.1 is soup, we thought it would be helpful to show you how to run the entire system using a single Asterisk@Home 2.1 server. First, download the updated proximity detection software here. Once you unzip the file, you’ll note that there’s a new ruhome2 file. The only changes you’ll need to make from the original tutorial are to substitute the ruhome2 file for the original ruhome file and to copy homecheck.agi to /var/lib/asterisk/agi-bin on your Asterisk@Home 2.1 server. Don’t forget to reset the file permissions as previously explained. Once you make these two simple changes, the entire proximity detection system can be run from your one and only Asterisk@Home 2.1 server.

Manually Managing In and Out Status with a SIP Phone. We’ve also received several queries from readers asking for a simple way to turn off the proximity detection system and to manually manage your IN or OUT status using buttons on a SIP telephone. In other words, when you leave your home or office, you want to press a button on the phone to tell your Asterisk server whether you’re IN or OUT. Yes, you can do it on a per extension basis using *72, but the proximity detection system transfers all calls based upon the location of your bluetooth device. To do the same thing manually, first remove the ruhome application from your crontab by logging into your server as root and deleting that line (Ctrl-K) from your crontab file. Then save your changes: Ctrl-X, Y, Enter.

export EDITOR=nano
crontab -e

Then add the following code to the [from-internal-custom] context of your extensions_custom.conf file and reload Asterisk. Note that, in the code below, you’ll have to change the name of the file in the /tmp directory from WARD to whatever filename you’re currently using with your proximity detection system. This is the deviceuser variable in your ruhome script. You’ll also need to modify the permissions on this file after logging into your Asterisk server as root, or this won’t work: chmod 666 /tmp/WARD.

exten => 46,1,Answer ; IN to deactivate call forwarding
exten => 46,2,Wait(1)
exten => 46,3,System(cp -f /var/lib/asterisk/agi-bin/notnull.file /tmp/WARD)
exten => 46,4,Playback(call-forwarding)
exten => 46,5,Playback(de-activated)
exten => 46,6,Wait(1)
exten => 46,7,Playback(goodbye)
exten => 46,8,Hangup

exten => 688,1,Answer ; OUT to activate call forwarding
exten => 688,2,Wait(1)
exten => 688,3,System(cp -f /var/lib/asterisk/agi-bin/null.file /tmp/WARD)
exten => 688,4,Playback(call-forwarding)
exten => 688,5,Playback(activated)
exten => 688,6,Wait(1)
exten => 688,7,Playback(goodbye)
exten => 688,8,Hangup

Once you make these changes, you can pick up any extension and dial IN (46) when you’re IN or OUT (688) when you’re away. You can also assign these "extensions" to buttons on almost any SIP telephone instrument if you want one-touch dialing.

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. Then you can skip around to your heart’s content. There’s also an index of all the previous articles which you can review here.

Want a rock-solid PBX at a rock-bottom price: free! Gosh, you haven't heard that since our column three days ago introducing Asterisk@Home 2.0. You didn't know this was going to be a bi-weekly event, did you? Well, neither did we, but we're happy to oblige when a new release hits the street because it always has something great tucked away inside. Asterisk@Home 2.1 was released two days ago and, from the looks of things, it's another winner! You not only get the latest version of Asterisk® (version 1.2), you also get the latest and greatest version of Linux, CentOS 4.2; the latest Festival Speech Engine (1.96); the latest version of the Asterisk Management Portal (1.10.010); the Flash Operator Panel (version 0.24); Digium® card auto-configuration; fax support; loads of AGI scripts including weather forecasts and wakeup calls; xPL support; the SugarCRM Contact Management System with the Cisco XML Services interface and Click-to-Dial support; plus some bug fixes. And there are a few new surprises that we'll get to shortly. Best of all, it amazingly still fits on a single CD!

Editor's Note: This version of Asterisk@Home has been superceded. For the latest tutorial, click here and scroll down the page.

The installation process is pretty straightforward. You download the 2.1 ISO image from here, burn a CD (click here if you need a refresher course), use an old clunker PC or an under $200 WalMart special (see inset), insert the CD you made, plug your machine into the Internet and turn it on. Then watch while Asterisk@Home loads CentOS/4.2 and all the Asterisk and Linux goodies imaginable: Apache, SendMail, Comedian Mail, SugarCRM, MySQL, PHP, phpMyAdmin, SSH, Bluetooth, the Asterisk Management Portal, the Flash Operator Panel, Call Detail Reporting, and on and on. We've covered how to use most of the Linux products in our Mac HOW-TO's (see sidebar), and they work exactly the same way with Asterisk@Home so keep reading. And, yes, this install will reformat (aka ERASE) your hard disk before it begins, but it now warns you first.

Loading CentOS/4 and Asterisk 1.20. Here's how the 2.1 install went for us, and we'll walk you through getting everything set up so that it can be used as a production server. Once the install begins, you can expect to eat up about 25 minutes with the CentOS 4.2 install. The install CD then will eject itself, reboot the system, and begin the Asterisk compile and installation. That takes about 25 more minutes to complete.

Securing Your Passwords. When it's finished and reboots, log in as root with password as your password. Type help-aah for a listing of the five passwords that need to be changed. Change them all NOW!

passwd
passwd admin
passwd-maint
passwd-amp
passwd-meetme


Getting the Latest CentOS Updates. Once your system is secure, load all of the application updates for CentOS 4.2. There are about forty of them as we write this so be patient. The update command to issue is yum -y update.

Activating Bluetooth Support. Once the updates are completed, activate Bluetooth support if you plan to use it with our Follow-Me Phoning proximity detection application. Run setup, down arrow to System Services, press ENTER, down arrow to bluetooth and press the space bar, tab to OK, press ENTER, tab twice to Quit and press ENTER.

Rebuilding Zaptel. First, reboot your system: shutdown -r now. Because a new version of the kernel is installed as part of the update, you'll need to rebuild support for ZAP devices. Log in as root and type rebuild_zaptel. Then reboot. Now log in as root again and type genzaptelconf. Reboot once more and you're all set to go: shutdown -r now. You only need to rebuild Zaptel when there is a kernel update as there was with this yum update.

Simplifying SSH. If you're going to be connecting to other servers from your new Asterisk@Home 2.1 system using SSH or SCP, then build your new RSA key pair now. This lets you use SSH and SCP (secure copy) without having to enter a password each time. You can also automate backups and proximity detection scripts as we've explained previously here. Log in to your new Asterisk@Home 2.1 server as root. From the command prompt, issue the following command: ssh-keygen -t rsa. Press the enter key three times. You should see something similar to the following. The file name and location in bold below is the information we need:

Generating public/private rsa key pair.
Enter file in which to save the key (/root/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /root/.ssh/id_rsa.
Your public key has been saved in /root/.ssh/id_rsa.pub.
The key fingerprint is:
1d:3c:14:23:d8:7b:57:d2:cd:18:70:80:0f:9b:b5:92 root@asterisk1.local

Now copy the file in bold above to your other Asterisk servers, Linux machines, and Macs. There's probably a way on PCs as well, but I've given up on that platform particularly after Sony's latest security stunt so you're on your own there. From your Asterisk@Home 2.1 server using SCP, the command should look like the following (except use the private IP address of each of your other Asterisk or Linux servers instead of 192.168.0.104). Provide the root password to your other servers (one at a time) when prompted to do so.

scp /root/.ssh/id_rsa.pub root@192.168.0.104:/root/.ssh/authorized_keys

On a Mac running Mac OS X, the command would look like this (using your username and your Mac's IP address, of course):

For user access only: scp /root/.ssh/id_rsa.pub wardmundy@192.168.0.104:/Users/wardmundy/.ssh/authorized_keys
For full root access: scp /root/.ssh/id_rsa.pub root@192.168.0.104:/var/root/.ssh/authorized_keys


Once the file has been copied to each server, try to log in to your other server from your Asterisk@Home 2.1 server with the following command using the correct destination IP address, of course:

ssh root@192.168.0.104

You should be admitted without entering a password. If not, repeat the drill or read the complete article and find where you made a mistake. Now log out of the other server by typing exit.

Installing WebMin. We don't build Linux systems without installing WebMin, the Swiss Army knife of the Linux World. You can use it to start and stop services, check logs, adjust startup scripts, manage cron jobs, babysit your SendMail server, and many, many other tasks that are downright painful without it. If you ever need help from others, WebMin is a great tool for letting others help you.

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. Note that there is a new version of WebMin since our article on Asterisk@Home 2.0 earlier this week. It fixed a major security flaw in some of WebMin's perl scripts so you'll definitely want this upgrade:

cd /root
mkdir webmin
cd webmin
wget http://internap.dl.sourceforge.net/sourceforge/webadmin/webmin-1.250-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. We really don't want the WebMin server starting up each time the OS reboots so do the following. Once you're logged in to WebMin, choose System->Bootup and Shutdown and then click on webmin. Click the No button beside Start at boot time, and then click the Save button. 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 used to be 10000 to 20000 so there's a conflict on port 10000 with WebMin. Beta 6 fixed this, but version 2.1 doesn't have the change. So, if it still says 10000 on your system, 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. Then restart Asterisk: amportal restart. Finally, to stop WebMin when you're finished using it, issue this command: /etc/webmin/stop. You can start it any time you need it, and then use a web browser to access it. But there's no need to consume processing resources running a second web server when you're not using it.

Basic System Configuration. To get a basic Asterisk system up and running, you only need to do a few things. First, you need an Outbound Trunk to actually deliver your outbound calls to Plain Old Telephones (POTS). Second, you need to configure an Outbound Route to tell Asterisk which trunk to use to deliver your outbound calls to the intended recipients. Third, you need to configure at least one extension so that you can plug in some sort of telephone instrument to place and receive calls using your new Asterisk server. The phone can be a hardware device such as an IP telephone or a POTS phone, or it can be a software device such as a free IP softphone. The advantage of IP telephones and softphones is that they require no additional hardware besides your Asterisk server. A POTS phone or our favorite, a 5.8GHz wireless phone system with up to 10 extensions, both require an additional piece of hardware although some of the newer IP wireless phones give you the best of all worlds (see inset). To use a POTS phone, the hardware required is either a circuit board with an FXS port or an external black box (ATA device) such as a Sipura SPA-1001. If you also want to connect your Ma Bell phone line to your Asterisk server, then you need a circuit board with an FXO port or an external black box (ATA device) such as a Sipura SPA-3000. Our favorite is the SPA-3000 because it has both FXO and FXS ports in a box the size of a pack of cigarettes for under $100.

Setting Up An Outbound Trunk. You configure an outbound trunk using your web browser and the Asterisk Management Portal (AMP). But first, you have to have an account with a service provider. This is the company that carries your calls from your Asterisk server to plain old phones in your neighbor's house or Aunt Betty's in California. With VoIP, it's a good idea to have two providers, but today let's start with one. We'll save you some time and lots of money. Unless you make substantial international calls regularly, use TelaSIP/VoipExpress. If you want to know why, read the full article here. Or just try a free call for yourself using our server. Basically, $5.95 a month gets you a local number in your choice of area code with free incoming calls, and 2¢ per minute for outbound calls to anywhere in the U.S. $9.95 a month buys you all of that plus free outbound calls in the area code of the phone number you select. $14.95 a month gets you a number in the area code of your choice with unlimited incoming calls and unlimited outbound calls to anywhere in the U.S. There are no sneaky add-on fees and no obnoxious terms of service. Just be sure to tell them to configure your account for use with Asterisk. They also have very reasonable business plans. If, on the other hand, you'd prefer to try another provider, take a look at our easy setup guides for most of the major VoIP providers here.

Once you have your account name and password, point your web browser to the IP address of your new Asterisk 2.0 server and log in as maint with the password you selected. Then choose AMP->Setup->Trunks->Add SIP Trunk assuming you're using TelaSIP. NOTE to existing users: if you already have an Asterisk server using your TelaSIP account, don't use the same account at the same time on your new Asterisk@Home 2.0 server! Plug in the CallerID number you were assigned for your account. Set Maximum Channels to 2. For the Dial Rules, use the following (substituting your local area code for 404 below):

1|NXXNXXXXXX
NXXNXXXXXX
404+NXXXXXX

In the Outgoing Settings section, name your trunk telasip-gw. Then enter the following for the Peer Details using your own account name for username and fromuser and using your own assigned password for secret:

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

Leave the Incoming Settings section blank, and in the Registration String, enter the following using your account name and password:

youraccountname:yourpassword@gw3.telasip.com

Click the Submit Changes button, and then click the red bar to reload Asterisk. Now we need to add the context which will actually process the incoming calls from TelaSIP. Choose AMP->Maintenance->Config Edit->extensions_custom.conf and add the following code at the bottom of the file substituting your new phone number for 4041234567. Save the file and reload Asterisk to finish the setup.

[telasip-in]
exten => 4041234567,1,NoOp(Incoming call on TelaSIP #4041234567)
exten => 4041234567,2,Dial(local/200@from-internal,20,m)
exten => 4041234567,3,VoiceMail(200@default)
exten => 4041234567,4,Hangup


Configuring an Outbound Route. Now we need to tell Asterisk where to send our outbound calls when we dial them. To get started, we'll just send everything to the TelaSIP trunk we just configured. Choose AMP->Setup->Outbound Routing->Add Route. For Route Name, use Outside. Leave the password blank. For Dial Patterns, enter the following:

NXXXXXX
NXXNXXXXXX
1NXXNXXXXXX

For the Trunk Sequence, choose SIP->telasip-gw from the drop-down list. Then click Submit Changes. Be sure you also delete the sample outbound route that came with the install, or your outbound calls may go nowhere. Finally, click the red bar to save your new Outbound Routing setup.

Configuring an Extension. You have to have an extension to make and receive calls with Asterisk@Home so let's build one. Choose AMP->Setup->Extensions->SIP to begin. For the Extension Number, let's use 200 to keep things simple. For the Display Name, make up something that tells where this phone will be located, e.g. Kitchen. For the Outbound CID, use 200. For secret, make up a password for this extension. For Voicemail and Directory, choose Enabled. Plug in your password again. Type in your email address, and, if you want to also be paged when you get a new voicemail, type in a pager email address. Click the Yes button beside Email Attachment, and leave the other settings alone. Now click the Submit button. You'll see a couple of ugly error messages. Ignore them. It's a beta bug. Just click the red bar to save your changes and reload Asterisk.

Downloading a Free Softphone to Test Asterisk. Unless you already have an IP phone, the easiest way to get started and make sure everything is working is to install an IP softphone. You can download a softphone for Windows, Mac, or Linux from CounterPath. Or download the pulver.Communicator. Both are free! Just install and then configure with the IP address of your Asterisk@Home 2 server. For username and password, use your extension number and password from above. Once you make a few test calls, don't waste any more time. Buy a decent SIP telephone. We think the best value in the marketplace with excellent build quality and feature set is the under $100 GrandStream GXP-2000. It has support for four lines, speaks CallerID numbers, has a lighted display, and can be configured for autoanswer with a great speakerphone. Short of paying three times as much, that's as good as desktop phones get. If you want to use Asterisk throughout your home, buy a good 5.8GHz wireless phone system with plenty of extensions (our two favorites are shown in the insets below) and then purchase an SPA-3000 to connect up both your home phone line and all your cordless phones. Our tutorial will show you how. The final option is to use a wireless IP phone which is the best of both worlds, a cordless phone that talks IP telephony without an ATA blackbox such as the Uniden UIP1868 (see also insets above).

Activating Email Delivery of VoiceMail Messages. When you're out and someone leaves you a voicemail message, Asterisk@Home will let you forward that voicemail message to your email address as a .wav file which can be played within most email client software. Or you can have Asterisk@Home send an instant message to your cell phone or pager telling you who called, what their phone number was, and how long a voicemail message the person left for you. Or you can do both. In addition, you can tell Asterisk@Home whether to delete the voicemail from your Asterisk server after sending it to your email account. In short, you now can manage all of your incoming email and voicemail from a single place, your email client. In order to send out emails from your Asterisk@Home server, you'll need to make two changes. First, make this adjustment to the /etc/hosts file on the server. Since anonymous emails are blocked by most ISPs, you'll need a fully-qualified domain name for your server. If you don't have your own domain, the easiest alternative is to use the fully-qualified domain name that your ISP assigns to the IP address for your broadband connection. Don't forget to update it when your ISP changes your IP address! To find out what your fully-qualified domain name is, go to a command prompt on your Asterisk server and type: nslookup 123.456.789.001 substituting your public IP address for the preceding numbers. Then write down the name entry without the trailing period. Now edit the hosts file: nano /etc/hosts. Move the cursor to the second line which reads 127.0.0.1 asterisk1.local , and then move the cursor over the first letter of the first domain name shown, usually asterisk1.local. Now type in the fully-qualified domain name you previously wrote down and add a space after your entry. Don't erase the existing entry! Save your settings: Ctrl-X, y, enter. Now restart network services on your Asterisk machine: service network restart. Next, you need to modify the email message which delivers your voicemails so that it includes your fully-qualified domain name. Don't do this in AMP, or you'll mess up the formatting of the email message. You can download a fresh copy here if you need it. Instead, use nano: nano -w /etc/asterisk/vm_email.inc. Press Ctrl-W, type /cgi, and press the enter key. You're now positioned where you need to type either the fully-qualified domain name for your Asterisk server or the private IP address if you only want to read your emails from behind your firewall. When you start typing, the text display is going to jump all over the place because of word wrap. Don't freak out. You haven't messed anything up. Once you complete your entry, don't erase or change anything else. Save the file: Ctrl-X,Y, then enter. Now go into AMP->Maintenance->Config Edit->vm_general.inc with a web browser. Change the serveremail entry to an email name at the fully qualified domain you used in your /etc/hosts file above. Then save your configuration and restart Asterisk. If you continue with this setup and still don't receive emails, here's another configuration change that is sometimes necessary. On the Asterisk terminal, log in as root. Switch to the directory where the SendMail configuration file is stored: cd /etc/mail. Make a backup of the config file: cp sendmail.cf sendmail.cf.bak. Then issue the following command: echo CGasterisk.dyndns.org >> sendmail.cf. Substitute the actual domain name of your Asterisk server for asterisk.dyndns.org, but be sure it's preceded by CG with no intervening spaces.Then reboot your server and try again: shutdown -r now.

To configure the voice mail forwarding options, go into the Setup tab of the Asterisk Management Portal using a web browser. Click on Extensions and then click on an extension you already have configured. In the Voicemail and Directory section of the form, enter either (or both) your email address and your pager or cellphone's text messaging address. To email the voicemails as attachments, just click Yes beside Email Attachment. To delete the voicemail message from your voicemail inbox after sending it to your email address (not recommended until you first get it working correctly), click Yes beside Delete Vmail. For those using a dynamic IP address with phones at remote locations connecting to your Asterisk server, we'll show you how to automate the process of changing your Asterisk server's IP address in a future column.

Call Recording. This update fixes inbound and outbound call recording which now works reliably. You can set your preferences for call recording when you set up each extension. The recordings are stored in /var/lib/asterisk/monitor unless you set other preferences in agents.conf.

Fixing Paging. If you want to use paging with your Asterisk system, you'll need to perform a little magic to get it working with your sound card in Asterisk@Home 2.1. For the step-by-step, review this posting on SourceForge. It now works with full and half-duplex sound cards. Thanks, Tracy!

Directory Lookup. Pressing the pound key (#) from any phone connected to your Asterisk server now calls up a directory lookup function using the Asterisk Management Portal (AMP).

Tweaking SIP.conf. There are a few changes we recommend you make in the [general] context of the sip.conf file. Using the Asterisk Management Portal, go to AMP->Maintenance->Config Edit->sip.conf. It's a good idea to include your actual CallerID number of your default outbound trunk here instead of Default. We also recommend that you add allow=gsm just below the existing allow=alaw line in the file. You may also want to include progressinband=yes which assures that callers will hear ring tones when placing calls even if your provider doesn't provide them. This is a fairly common complaint with BroadVoice in particular. Don't forget to reload Asterisk once you make these changes: AMP->Setup->Incoming Calls->Submit Changes and then click the Red bar.

Connecting Remote Extensions or a Remote Asterisk Server. If you plan to connect remote extensions to your Asterisk server, then add the following entries to sip.conf above using your own fully-qualified domain name and the first three octets of the private IP address of your Asterisk server:

externip = myasteriskbox.dyndns.org
localnet=192.168.0.0/255.255.255.0
nat=yes

You'll also either need to define your Asterisk server as a DMZ device in your firewall setup, or you can open the following UDP ports and map all of them to the private IP address of your Asterisk box: 4569, 5004-5082, and 10000-20000. If you only hear half of a conversation with a remote extension, it's usually a NAT problem meaning you probably forgot to do the port mapping drill. We plan to cover remote extensions and interconnecting Asterisk servers in more detail in a future column so stay tuned. In the meantime, if you have a dynamic DNS connection that changes your IP address regularly and you don't want to wrestle with manually updating your Asterisk server each time there's a change, just download chandave's sip reload script and copy it to your /etc/asterisk directory. Then execute the following commands while logged in as root:

chown asterisk:asterisk /etc/asterisk/sip_reload.sh
export EDITOR=nano
crontab -e
00,05,10,15,20,25,30,35,40,45,50,55 * * * * root /bin/sh /etc/asterisk/sip_reload.sh >/dev/null 2>&1

Save your crontab addition in the usual nano way, and you're all set: Ctrl-X, y, then enter. This clever little script will make sure your Asterisk server always knows its own IP address regardless of how often your ISP changes it. And you'll never lose inbound connectivity from remote extensions or servers for over 5 minutes. If you'd like to read the full discussion, visit this link on the Voxilla forum.

Managing Incoming Calls. For long time readers of this column, you already know that our recommended strategy for handling incoming calls is to set up a simple Stealth AutoAttendant. Basically, this is a welcome message that greets your callers and then transfers them to an extension or ring group of your choice. The advantage of this approach is that it also lets callers like you press buttons to navigate through various options on your Asterisk system without advertising them to the public at large. If you're just getting started with Asterisk, you can read all about setting up a Stealth AutoAttendant here. If you'd prefer to manage your incoming calls with AMP, you'll still need to fix the [from-sip-external] context in the extensions.conf file, or all your incoming SIP and IAX calls will ring busy. To fix it, choose AMP->Maintenance->Config Edit->extensions.conf->from-sip-external. Comment out all the lines in the existing file by adding a semicolon at the beginning of each line. Then add the following line, save your changes, and reload Asterisk.

exten => _.,1,Goto(from-pstn-timecheck,s,1)


Custom Speed Dialing. Asterisk@Home 2.1 now has a built-in speed dialing utility. The reserved speed dial numbers are 300 to 399. Adding a number to your speed dial list is easy. Just pick up an extension and dial 300-3xx-6781234567 where 3xx is the speed dial code you want to create and 6781234567 is the phone number you want dialed when you enter the speed dial code. Just make sure you enter the number to be called in a format that is supported by your Asterisk dialplan, i.e. if outside calls need to be preceded by a 1 or a 9, then the number should be entered in a matching format. You can look up speed dial numbers by dialing an asterisk followed by the 3-digit speed dial code, e.g. *301 would tell you the number stored in speed dial 301. If you need additional flexibility with both web browser and phone access as well as 1 to 5-digit speed dial codes, download our free AsteriDex robodialer.

A2Billing: Asterisk Calling Card Platform. This web-based application allows you to generate and issue calling cards to individuals so that they can place calls remotely through your Asterisk server. If you've always wanted to be just like AT&T, here's your Big Chance! There's very little that you can do with an AT&T calling card that can't be done as well or better by you using A2Billing. And, it won't take an M.B.A. to undercut AT&T's calling card rates and still make buckets of money. All you need now are a few customers. Heck, I'll sign up with you. I sign up for everything. But first, a word of caution. Assuming your Asterisk server has web exposure on the Internet, you need to secure the admin and root passwords in this application whether you use it or not. To access the application, go to http://192.168.0.104/a2billing/ using the actual internal IP address of your Asterisk server. Log in as root with a password of myroot. Click on the ADMINISTRATOR tab in the left column and then click Show Administrator. Now click on the Edit button beside each of the two administrator accounts and change the passwords to something secure. If you really would like to learn more about it, documentation for the application is available here. And, if you decide to use the application, you'll need to uncomment the actual dialplan lines in extensions_custom.conf and reload Asterisk:

; CallingCard application
; un-comment the 5 lines below to use this app
;exten => _X.,1,Answer
;exten => _X.,2,Wait,2
;exten => _X.,3,DeadAGI,a2billing.php
;exten => _X.,4,Wait,2
;exten => _X.,5,Hangup

Footnote: There's also a little missing A2Billing code which needs to be added. You can read all about it here. There's also a pretty good step-by-step setup guide for Asterisk@Home 2.1 here.

SugarCRM Contact Management. Asterisk@Home includes the latest and greatest version of the best open source contact management application on the planet, SugarCRM. You access the application with a web browser: http://192.168.0.104/crm/ substituting the private IP address of your Asterisk box, of course. Specify admin for your username and password for your password. Whether you use the application or not, change the admin password. It's easy. Just click the Administrator link under Welcome admin. Then click the Change Password button. Complete documentation for the application is available here. If contact management is your thing, knock yourself out, and we'll talk to you next spring when you finish getting everything set up to run your business. It's a great product, but be prepared to invest lots of time in the project if you expect to use it productively.

Other Out-of-the-Box Utilities. Asterisk@Home 2.1 comes bundled with a number of additional utilities. Here are some of them. You can retrieve the current time by dialing *60. If the time is wrong, you can reset your default time zone by logging into your server as root and typing config. A current weather report for New York is available by dialing *61. You can change the city by following our previous tutorial which is available here. To set up a wakeup call from any extension, dial *62. To determine the phone number of any extension, just dial *65. You can use the default MeetMe conferencing system from any or all of your extensions by dialing 8400. Additional conference rooms can be added by editing meetme_additional.conf. Finally, you can record customized voice prompts for your system by dialing 5678 from any extension. Before this will work, edit the extensions_custom.conf file (AMP->Maintenance->Config Edit->extensions_custom.conf) and uncomment the seven lines shown below which are located at the bottom of the file. Just remove the leading semicolons. You'll also need to uncomment the following line near the top of file at the beginning of the [from-internal-custom] context: ;include => custom-recordme.

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

Once you make a recording, it needs to be moved to /var/lib/asterisk/sounds/custom with a new filename.gsm, e.g. mv /tmp/asterisk-recording.gsm /var/lib/asterisk/sounds/custom/hihoney.gsm. Then change the ownership of the file: chown asterisk:asterisk /var/lib/asterisk/sounds/custom/hihoney.gsm. You then can play the recording with a line like this in your dialplan: exten=>s,1,Playback(custom/hihoney) where hihoney is the name you assigned to the recording without its .gsm extension.

Where To Go From Here. After you get a functioning Asterisk system, you're ready to move on to the really cool things that make Asterisk a one-of-a-kind PBX. There are customized weather reports, web and phone-based dialers from a MySQL address book, incoming fax to PDF conversion with email delivery, blacklisting of telemarketers, bluetooth proximity detection so that your home or office calls automatically transfer to your cellphone when you depart with your bluetooth device, and on and on. You'll also want to take a more in-depth look at many of the topics we've covered above. For a complete catalog of all of our Asterisk projects and everything else we've written about Asterisk@Home, go here. Then take a look at a terrific writeup from the other side of the globe: Asterisk@Home for Dumb-Me. Finally, there's an Asterisk@Home Handbook Wiki project under development that's worth a careful look. Enjoy!

Want a rock-solid PBX at a rock-bottom price: free! Gosh, you haven't heard that since our column a few weeks ago introducing Asterisk® 1.2. What a difference two weeks makes. The final version of Asterisk@Home 2.0 was released the day before Thanksgiving and, from the looks of things, it's darn near perfect! You not only get the latest version of Asterisk (version 1.2), you also get the latest and greatest version of Linux, CentOS 4.2; the latest Festival Speech Engine (1.96); the latest version of the Asterisk Management Panel (1.10.010); the Flash Operator Panel (version 0.24); Digium® card auto-configuration; fax support; loads of AGI scripts including weather forecasts and wakeup calls; xPL support; and the SugarCRM Contact Management System with the Cisco XML Services interface and Click-to-Dial support. And it all still fits on a single CD!

NOTE: Version 2.1 was posted late Wednesday, November 30. Our new 2.1 tutorial will be available here on Friday, December 2.

The installation process is pretty straightforward. You download an ISO image from here, burn a CD (click here if you need a refresher course), use an old clunker PC or an under $200 WalMart special (see inset), insert the CD you made, plug your machine into the Internet and turn it on. Then watch while Asterisk@Home loads CentOS/4.2 and all the Asterisk and Linux goodies imaginable: Apache, SendMail, Comedian Mail, SugarCRM, MySQL, PHP, phpMyAdmin, SSH, Bluetooth, the Asterisk Management Panel, the Flash Operator Panel, Call Detail Reporting, and on and on. We've covered how to use most of the Linux products in our Mac HOW-TO's (see sidebar), and they work exactly the same way with Asterisk@Home so keep reading. And, yes, this install will reformat (aka ERASE) your hard disk before it begins, but it now warns you first.

Loading CentOS/4 and Asterisk 1.20. Here's how the 2.0 install went for us, and we'll walk you through the few very minor issues that still remain to be manually tweaked. Once the install begins, you can expect to eat up about 25 minutes with the CentOS 4.2 install. The install CD then will eject itself, reboot the system, and begin the Asterisk compile and installation. That takes about 25 more minutes to complete.

Securing Your Passwords. When it's finished and reboots, log in as root with password as your password. Type help-aah for a listing of the passwords that need to be changed. Change them all NOW!

passwd
passwd admin
passwd-maint
passwd-amp
passwd-meetme


Getting the Latest CentOS Updates. Once your system is secure, load all of the application updates for CentOS 4.2. There are about forty of them as we write this so be patient. The update command to issue is yum -y update.

Activating Bluetooth Support. Once the updates are completed, activate Bluetooth support if you plan to use it with our Follow-Me Phoning proximity detection application. Run setup, down arrow to System Services, press ENTER, down arrow to bluetooth and press the space bar, tab to OK, press ENTER, tab twice to Quit and press ENTER.

Rebuilding Zaptel. First, reboot your system: shutdown -r now. Because a new version of the kernel is installed as part of the update, you'll need to rebuild support for ZAP devices. Log in as root and type rebuild_zaptel. Reboot once more and you're all set to go: shutdown -r now.

Simplifying SSH. If you're going to be connecting to other servers from your new Asterisk@Home 2 system using SSH or SCP, then build your new RSA key pair now. This lets you use SSH and SCP (secure copy) without having to enter a password each time. You can also automate backups and proximity detection scripts as we've explained previously here. Log in to your new Asterisk@Home 2 server as root. From the command prompt, issue the following command: ssh-keygen -t rsa. Press the enter key three times. You should see something similar to the following. The file name and location in bold below is the information we need:

Generating public/private rsa key pair.
Enter file in which to save the key (/root/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /root/.ssh/id_rsa.
Your public key has been saved in /root/.ssh/id_rsa.pub.
The key fingerprint is:
1d:3c:14:23:d8:7b:57:d2:cd:18:70:80:0f:9b:b5:92 root@asterisk1.local

Now copy the file in bold above to your other Asterisk servers, Linux machines, and Macs. There's probably a way on PCs as well, but I've given up on that platform particularly after Sony's latest security stunt so you're on your own there. From your Asterisk2 server using SCP, the command should look like the following (except use the private IP address of each of your other Asterisk or Linux servers instead of 192.168.0.104). Provide the root password to your other servers (one at a time) when prompted to do so.

scp /root/.ssh/id_rsa.pub root@192.168.0.104:/root/.ssh/authorized_keys

On a Mac running Mac OS X, the command would look like this (using your username and your Mac's IP address, of course):

For user access only: scp /root/.ssh/id_rsa.pub wardmundy@192.168.0.104:/Users/wardmundy/.ssh/authorized_keys
For full root access: scp /root/.ssh/id_rsa.pub root@192.168.0.104:/var/root/.ssh/authorized_keys


Once the file has been copied to each server, try to log in to your other server from your Asterisk 2 Server with the following command using the correct destination IP address, of course:

ssh root@192.168.0.104

You should be admitted without entering a password. If not, repeat the drill or read the complete article and find where you made a mistake. Now log out of the other server by typing exit.

Installing WebMin. We don't build Linux systems without installing WebMin, the Swiss Army knife of the Linux World. You can use it to start and stop services, check logs, adjust startup scripts, manage cron jobs, babysit your SendMail server, and many, many other tasks that are downright painful without it. If you ever need help from others, WebMin is a great tool for letting others help you.

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 used to be 10000 to 20000 so there's a conflict on port 10000 with WebMin. Beta 6 fixed this, but the final version doesn't have the change. So, if it still says 10000 on your system, 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. Then restart Asterisk: amportal restart. Finally, to stop WebMin when you're finished using it, issue this command: /etc/webmin/stop. You can start it any time you need it, and then use a web browser to access it. But there's no need to consume processing resources running a second web server when you're not using it.

Basic System Configuration. To get a basic Asterisk system up and running, you only need to do a few things. First, you need an Outbound Trunk to actually deliver your outbound calls to Plain Old Telephones (POTS). Second, you need to configure an Outbound Route to tell Asterisk which trunk to use to deliver your outbound calls to the intended recipients. Third, you need to configure at least one extension so that you can plug in some sort of telephone instrument to place and receive calls using your new Asterisk server. The phone can be a hardware device such as an IP telephone or a POTS phone, or it can be a software device such as a free IP softphone. The advantage of IP telephones and softphones is that they require no additional hardware besides your Asterisk server. A POTS phone or our favorite, a 5.8GHz wireless phone system with up to 10 extensions, both require an additional piece of hardware although some of the newer IP wireless phones give you the best of all worlds (see inset). To use a POTS phone, the hardware required is either a circuit board with an FXS port or an external black box (ATA device) such as a Sipura SPA-1001. If you also want to connect your Ma Bell phone line to your Asterisk server, then you need a circuit board with an FXO port or an external black box (ATA device) such as a Sipura SPA-3000. Our favorite is the SPA-3000 because it has both FXO and FXS ports in a box the size of a pack of cigarettes for under $100.

Setting Up An Outbound Trunk. You configure an outbound trunk using your web browser and the Asterisk Management Portal (AMP). But first, you have to have an account with a service provider. This is the company that carries your calls from your Asterisk server to plain old phones in your neighbor's house or Aunt Betty's in California. With VoIP, it's a good idea to have two providers, but today let's start with one. We'll save you some time and lots of money. Unless you make substantial international calls regularly, use TelaSIP/VoipExpress. If you want to know why, read the full article here. Or just try a free call for yourself using our server. Basically, $5.95 a month gets you a local number in your choice of area code with free incoming calls, and 2¢ per minute for outbound calls to anywhere in the U.S. $9.95 a month buys you all of that plus free outbound calls in the area code of the phone number you select. $14.95 a month gets you a number in the area code of your choice with unlimited incoming calls and unlimited outbound calls to anywhere in the U.S. There are no sneaky add-on fees and no obnoxious terms of service. Just be sure to tell them to configure your account for use with Asterisk. The also have very reasonable business plans. If, on the other hand, you'd prefer to try another provider, take a look at our easy setup guides for most of the major VoIP providers here.

Once you have your account name and password, point your web browser to the IP address of your new Asterisk 2.0 server and log in as maint with the password you selected. Then choose AMP->Setup->Trunks->Add SIP Trunk assuming you're using TelaSIP. NOTE to existing users: if you already have an Asterisk server using your TelaSIP account, don't use the same account at the same time on your new Asterisk@Home 2.0 server! Plug in the CallerID number you were assigned for your account. Set Maximum Channels to 2. For the Dial Rules, use the following (substituting your local area code for 404 below):

1|NXXNXXXXXX
NXXNXXXXXX
404+NXXXXXX

In the Outgoing Settings section, name your trunk telasip-gw. Then enter the following for the Peer Details using your own account name for username and fromuser and using your own assigned password for secret:

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

Leave the Incoming Settings section blank, and in the Registration String, enter the following using your account name and password:

youraccountname:yourpassword@gw3.telasip.com

Click the Submit Changes button, and then click the red bar to reload Asterisk. Now we need to add the context which will actually process the incoming calls from TelaSIP. Choose AMP->Maintenance->Config Edit->extensions_custom.conf and add the following code at the bottom of the file substituting your new phone number for 4041234567. Save the file and reload Asterisk to finish the setup.

[telasip-in]
exten => 4041234567,1,NoOp(Incoming call on TelaSIP #4041234567)
exten => 4041234567,2,Dial(local/200@from-internal,20,m)
exten => 4041234567,3,VoiceMail(200@default)
exten => 4041234567,4,Hangup


Configuring an Outbound Route. Now we need to tell Asterisk where to send our outbound calls when we dial them. To get started, we'll just send everything to the TelaSIP trunk we just configured. Choose AMP->Setup->Outbound Routing->Add Route. For Route Name, use Outside. Leave the password blank. For Dial Patterns, enter the following:

NXXXXXX
NXXNXXXXXX
1NXXNXXXXXX

For the Trunk Sequence, choose SIP->telasip-gw from the drop-down list. Then click Submit Changes and then click the red bar to save your Outbound Routing setup.

Configuring an Extension. You have to have an extension to make and receive calls with Asterisk@Home so let's build one. Choose AMP->Setup->Extensions->SIP to begin. For the Extension Number, let's use 200 to keep things simple. For the Display Name, make up something that tells where this phone will be located, e.g. Kitchen. For the Outbound CID, use 200. For secret, make up a password for this extension. For Voicemail and Directory, choose Enabled. Plug in your password again. Type in your email address, and, if you want to also be paged when you get a new voicemail, type in a pager email address. Click the Yes button beside Email Attachment, and leave the other settings alone. Now click the Submit button. You'll see a couple of ugly error messages. Ignore them. It's a beta bug. Just click the red bar to save your changes and reload Asterisk.

Downloading a Free Softphone to Test Asterisk. Unless you already have an IP phone, the easiest way to get started and make sure everything is working is to install an IP softphone. You can download a softphone for Windows, Mac, or Linux from CounterPath. Or download the pulver.Communicator. Both are free! Just install and then configure with the IP address of your Asterisk@Home 2 server. For username and password, use your extension number and password from above. Once you make a few test calls, don't waste any more time. Buy a decent SIP telephone. We think the best value in the marketplace with excellent build quality and feature set is the under $100 GrandStream GXP-2000. It has support for four lines, speaks CallerID numbers, has a lighted display, and can be configured for autoanswer with a great speakerphone. Short of paying three times as much, that's as good as desktop phones get. If you want to use Asterisk throughout your home, buy a good 5.8GHz wireless phone system with plenty of extensions (our two favorites are shown in the insets below) and then purchase an SPA-3000 to connect up both your home phone line and all your cordless phones. Our tutorial will show you how. The final option is to use a wireless IP phone which is the best of both worlds, a cordless phone that talks IP telephony without an ATA blackbox such as the Uniden UIP1868 (see also insets above).

Activating Email Delivery of VoiceMail Messages. When you're out and someone leaves you a voicemail message, Asterisk@Home will let you forward that voicemail message to your email address as a .wav file which can be played within most email client software. Or you can have Asterisk@Home send an instant message to your cell phone or pager telling you who called, what their phone number was, and how long a voicemail message the person left for you. Or you can do both. In addition, you can tell Asterisk@Home whether to delete the voicemail from your Asterisk server after sending it to your email account. In short, you now can manage all of your incoming email and voicemail from a single place, your email client. In order to send out emails from your Asterisk@Home server, you'll need to make two changes. First, make this adjustment to the /etc/hosts file on the server. Since anonymous emails are blocked by most ISPs, you'll need a fully-qualified domain name for your server. The easiest one to use is the fully-qualified domain name that your ISP assigns to the IP address for your broadband connection. Don't forget to update it when your ISP changes your IP address. To find out what your fully-qualified domain name is, go to a command prompt on your Asterisk server and type: nslookup 123.456.789.001 substituting your public IP address for the preceding numbers. Then write down the name entry without the trailing period. Now edit the hosts file: nano /etc/hosts. Move the cursor to the line which begins 127.0.0.1, and then move the cursor over the first letter of the first domain name shown, usually asterisk1.local. Now type in the fully-qualified domain name you previously wrote down and add a space after your entry. Don't erase the existing entries! Save your settings: Ctrl-X, y, enter. Now restart network services on your Asterisk machine: service network restart. Second, go into AMP->Maintenance->Config Edit->vm_general.inc with a web browser. Change the serveremail entry to an email name at the fully qualified domain you used in your /etc/hosts file above. Then save your configuration and restart Asterisk. If you continue with this setup and still don't receive emails, here's another configuration change that is sometimes necessary. On the Asterisk terminal, log in as root. Switch to the directory where the SendMail configuration file is stored: cd /etc/mail. Make a backup of the config file: cp sendmail.cf sendmail.cf.bak. Then issue the following command: echo CGasterisk.dyndns.org >> sendmail.cf. Substitute the actual domain name of your Asterisk server for asterisk.dyndns.org, but be sure it's preceded by CG with no intervening spaces.Then reboot your server and try again: shutdown -r now.

To configure the voice mail forwarding options, go into the Setup tab of the Asterisk Management Portal using a web browser. Click on Extensions and then click on an extension you already have configured. In the Voicemail and Directory section of the form, enter either (or both) your email address and your pager or cellphone's text messaging address. To email the voicemails as attachments, just click Yes beside Email Attachment. To delete the voicemail message from your voicemail inbox after sending it to your email address (not recommended until you first get it working correctly), click Yes beside Delete Vmail. If you want to further customize the email message which is sent, just edit vm_email.inc from AMP's Maintenance->Config Edit screen using your favorite web browser. For those using a dynamic IP address with phones at remote locations connecting to your Asterisk server, we'll show you how to automate the process of changing your Asterisk server's IP address in a future column.

Fixing Call Recording. This link explains the process as well as we could. After making the two changes, call recording inbound and outbound works reliably.

Fixing Paging. If you want to use paging with your Asterisk system, you'll need to perform a little magic to get it working with your full duplex sound card in Asterisk@Home 2.o. For the step-by-step, review this posting on SourceForge.

Fixing Directory Lookup. Usually, pressing the pound key (#) from any phone connected to your Asterisk server calls up a directory lookup function using the Asterisk Management Portal (AMP); however, Digium renamed one of the voice prompts in the 1.2 release of Asterisk which broke this function in AMP. If you simply log into your server as root and issue the following command, it will create a symbolic link to the renamed file and will permanently fix the problem:

ln -s /var/lib/asterisk/sounds/dir-intro-fn.gsm /var/lib/asterisk/sounds/dir-intro-oper.gsm


Managing Incoming Calls. For long time readers of this column, you already know that our recommended strategy for handling incoming calls is to set up a simple Stealth AutoAttendant. Basically, this is a welcome message that greets your callers and then transfers them to an extension or ring group of your choice. The advantage of this approach is that it also lets callers like you press buttons to navigate through various options on your Asterisk system without advertising them to the public at large. If you're just getting started with Asterisk, you can read all about setting up a Stealth AutoAttendant here. If you'd prefer to manage your incoming calls with AMP, you'll still need to fix the [from-sip-external] context in the extensions.conf file, or all your incoming SIP and IAX calls will ring busy. To fix it, choose AMP->Maintenance->Config Edit->extension.conf->from-sip-external. Comment out all the lines in the existing file by adding a semicolon at the beginning of each line. Then add the following line, save your changes, and reload Asterisk.

exten => _.,1,Goto(from-pstn-timecheck,s,1)


Where To Go From Here. Once you've got a functioning Asterisk system, you're ready to move on to the really cool things that make Asterisk a one-of-a-kind PBX. There are customized weather reports, web and phone-based dialers from a MySQL address book, incoming fax to PDF conversion with email delivery, blacklisting of telemarketers, bluetooth proximity detection so that your home or office calls automatically transfer to your cellphone when you depart with your bluetooth device, and on and on. You'll also want to take a more in-depth look at many of the topics we've covered above. For a complete catalog of all of our Asterisk projects and everything else we've written about Asterisk@Home, go here. Then take a look at a terrific writeup from the other side of the globe: Asterisk@Home for Dumb-Me. Finally, there's an Asterisk@Home Handbook Wiki project under development that's worth a careful look. Enjoy!

Want a rock-solid PBX at a rock-bottom price: free! It’s been over a year since the initial release of Asterisk®, and this week the new stable 1.2 release finally hit the street. If you’re just dying to try it and can’t wait for Asterisk@Home to catch up so that you’ll have all your favorite goodies to go with Asterisk, here’s the quick solution for you. First, download and install the latest Asterisk@Home 2.0 beta. This may not work with Asterisk@Home versions below 2.0! See the Comments to today’s article before you try it. The drill is pretty simple. You download an ISO image from here, burn a CD (click here if you need a refresher course), use an old clunker PC or a shiny new WalMart special (see inset for the unbelievable price!), insert the CD, plug your machine into the Internet and turn it on. Then watch while Asterisk@Home loads CentOS/4 and all the Asterisk and Linux goodies you’ll ever need: Apache, SendMail, Comedian Mail, SugarCRM, MySQL, PHP, phpMyAdmin, SSH, and on and on. We’ve covered how to use most of these products in our Mac HOW-TO’s (see sidebar), and they work exactly the same way with Linux so keep reading. And, yes, this install will reformat (aka ERASE) your hard disk before it begins. Once it’s finished, change all the default passwords by logging in to your new Asterisk@Home server as root with password as your password, and type help-aah for a list of the passwords that need to be changed, or go here for our complete security tutorial. A list of new features in Asterisk 1.2 is available here.

Editor’s Note: This version of Asterisk has been superceded. For the latest tutorial on or after February 1, click here.

When you finish the Asterisk@Home 2.0 beta install, we’ll first get the latest updates for CentOS/4. Then we’ll load the new Asterisk 1.2 stable release. Here’s how. Log in to your new Asterisk server as root, or better yet, use SSH to log in as root, and then cut and paste each command below in order:

amportal stop
yum -y update

amportal start


Checking Your Install. The Asterisk@Home install takes a little less than an hour, and the Asterisk 1.2 upgrade will set you back another 30 minutes or so. Not bad for free! Once Asterisk restarts, you should be able to log in to your Asterisk Management Portal by pointing a web browser at the IP address of your Asterisk system. Now choose AMP->Maintenance->Asterisk Info and make sure everything is up an running. The Version block should display Asterisk 1.2.0 with the time that you completed the build. If you’ve already got an IP phone or if you’d like to try a free IP-based softphone with your PC, go here next. Last but not least, you need a phone number and service provider so make this link your last stop, and you’ll be off to the races. Enjoy!

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. Then you can skip around to your heart’s content.