Hack49.Build a Four-Line Phone Server

Hack 49. Build a Four-Line Phone Server

Create a simple, fully functional small-office PBX.

An Asterisk server can be the nerve center of two kinds of telephony networks: an all-VoIP network that uses only IP-based connections to route calls, or a hybrid VoIP/legacy network that uses both IP and time division multiplexing (TDM) technologies to route calls.

In this hack, you'll use a Digium TDM400P card to turn your Asterisk server into a full-blown PBX that can support up to four legacy phones (or four legacy phone lines) at a time. These legacy devices will be able to call, and be called by, VoIP phones. This setup is depicted in Figure 4-10.

Figure 4-10. Asterisk as a simple small-office PBX

The TDM400P card has four modular interfaces that can host either FXO or FXS modules. FXO modules allow you to connect phone lines to your server, and FXS modules let you connect phones. You can use any combination of FXO and FXS modules (up to four) on a single TDM400P, so you can connect two analog phones and two phone lines, or one phone line and three analog phones, and so on. When you purchase the TDM400P card, you can specify what combination of interfaces you'd like. Here's the main thing to remember, so you don't get the wrong configuration: the redcolored FXO modules connect phone lines, and the green-colored FXS modules connect phones. So, if you want three analog phones to share a single analog phone line, you would use three FXS modules and one FXO module.

The Linux driver framework that allows Asterisk to use the TDM400P card is called Zaptel, and if you worked your way through "Turn Your Linux Box into a PBX" [Hack #41], you've already got the Zaptel drivers installed. Since these drivers don't yet work with Mac OS X, you'll be able to use the TDM400P card only on i386 Linux. I'll cover enabling the drivers in a moment.

If you're using certain servers, the TDM400P might not be compatible with certain Dell PowerEdge servers. Also, some Intel equipment has known issues with the TDM400P card. So check Digium's web site (http://www.digium.com/) to be sure: you could save yourself some time and aggravation. VoiceTronix makes alternative cards that you might want to consider, too.

But first, you need to get the card installed. This is pretty straightforward. If you've got a spare PCI slot, you're ready to snap the card into place. There are four numbered modules on the card, which correspond to the four numbered eight-wire jacks on the case plate of the card. Before inserting the card, screwing down the back brace, and replacing the PC's cover, you might want to note which jacks are for connecting phones and which are for connecting phone lines. It's hard to know once the case is on.

There's one more thing to connect after the TDM400P is slipped into place: a four-wire hard-drive power cable that runs from one of the PC's power leads to a power connector on the card. This cable brings power to the card above and beyond what's available from the PCI bus so that the card can provide ring voltage to any phones that are connected. You don't need to connect this little power cable if you aren't using FXS modules.

Once the card is in and your Linux box is booted up, you'll need to make sure the Zaptel drivers that were compiled when you first installed Asterisk are loaded before Asterisk is launched as a part of your normal system startup. To accomplish this, execute these commands before Asterisk is launched, perhaps in /etc/rc.d/rc.local:

 /sbin/modprobe zaptel /sbin/modprobe wctdm ztcfg 

Note the difference between this startup routine, which provides driver support for both analog phones and analog phone lines, and that of "Connect a Legacy Phone Line Using Zaptel" [Hack #44], which provides driver support only for phone lines. The addition of wctdm is the difference.

Run make config in your Zaptel and Asterisk source directories to create startup scripts that are customized for your Linux distribution.

The wcfxs driver needs to be modprobed only if you're using FXO modules (with phone lines attached), and the wctdm driver needs to be modprobed only if you're using FXS modules (with analog phones attached). The ztcfg application tests the Zaptel driver configuration and returns nothing if it's valid. If there's a hardware error or a problem with the Zaptel configuration files, which we're about to discuss, ztcfg will return an error description to the standard error output.

The /etc/zaptel.conf settings tell the Zaptel driver framework which modules on the TDM400P card are which. For a card with two FXO and two FXS modules, a configuration file like this would be used:

 ; zaptel.conf example loadzone = us defaultzone=us fxsks=1,2 fxoks=3,4 

The numbers assigned, 1 through 4, are channel numbers that Asterisk will use to refer to activity on each module. Within Asterisk, each legacy interface port on the TDM400P has its own channel. Since the point of this hack is to build a four-line phone server, we're going to assume that all of the channels are using the same type of signaling:

 ; zaptel.conf example loadzone = us defaultzone=us fxsks=1,2,3,4 

In this case, there are four FXO interfaces, to which we're going to connect one phone line apiece. fxsks (FXS Kewlstart) signaling is specified because the phone company switch to which these phones connect expects us to be using a telephone. Ordinarily, telephones interface to that phone-company switch (called a foreign exchange office in signal-ese) using electro-mechanical line signaling (called FXS signaling in Asterisk slang). Hence, our switch will be pretending to be a phone by using FXS signaling on its FXO interfaces. Confused yet? No worriesonce your server is up and running and your TDM400P is functioning as planned, you'll probably never need to mess with it again.

Now that you've saved zaptel.conf, bring up /etc/asterisk/zapata.conf in a text editor and make sure it resembles this example precisely:

 [channels] language=en context=default signalling=fxs_ks usecallerid=yes hidecallerid=no callwaiting=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes callreturn=yes group=1 channel => 1 channel => 2 channel => 3 channel => 4 

This block of config fine-tunes the settings of the four Zaptel channels that are provided by the card (for a concise description of what all of these settings do, check out Chapter 17 of O'Reilly's really amazing book, Switching to VoIP). Save this file before proceeding.

4.10.1. Set Up Incoming Calls

Now, pay a visit to /etc/asterisk/extensions.conf. Here, you'll need to adjust the default context section of the file so that incoming calls on the four lines can be handled appropriately.

Take a look at this sample default context section in extensions.conf, which deals with incoming calls from the TDM400P-connected phone lines (and from any other channels that point to the default context):

 [default] exten => s,1,Dial(SIP/100,30) exten => s,2,Voicemail(100) exten => s,3,Hangup 

So, as of right now (or at least after you reboot your Asterisk box or load the kernel modules manually), incoming phone calls to the connected phone lines will ring on the SIP phone configured as SIP peer 100. For a refresher on SIP peers, refer back to "Connect a Phone Line Using an FXO Gateway" [Hack #43].

4.10.2. Set Up Station-to-Station Calls

If you'd like your SIP phones to be able to call each other, be sure to add the following extension to the default context:

 exten => _1XX,1,Dial(SIP/${EXTEN},30) exten => _1XX,2,Voicemail(${EXTEN}) exten => _1XX,3,Hangup 

The _1XX pattern matches any phone numbers dialed that are three digits long and begin with 1. It deals with them by attempting to ring the SIP peer that is registered with a user ID that matches the extension number dialed, and then sends them to the appropriate voicemail box after 30 seconds if the SIP peer doesn't answer.

4.10.3. Set Up Outgoing Calls

Now, you've got to make it so that any connected phones can place calls using the four lines that you've just hooked up to the installed FXO modules. This is accomplished by a special pattern-matching extension in those phones' contexts. For SIP phones, this is established in sip.conf. Let's say that a SIP phone's context is [private-phones]. To allow this SIP phone to dial out using your newly connected phone lines, you'll need to make sure there is a context in extensions.conf that looks something like this:

 [private-phones] exten => _NXXXXXX,1,Dial(Zap/g1/${EXTEN}) exten => _NXXXXXX,2,Congestion exten => _1NXXNXXXXXX,1,Dial(Zap/g1/${EXTEN}) exten => _1NXXNXXXXXX,2,Congestion exten => 911,1,Dial(Zap/g1/911) exten => 911,2,Congestion 

The string patterns _NXXXXXX and _1NXXNXXXXXX are actually masks designed to identify phone numbers that are 7 and 11 digits long, respectively. This way, if the dialed number is 7 or 11 digits long, Asterisk knows it must dial the number (represented by the variable ${EXTEN}) using the group of four phones (Zap/g1) you previously defined in zapata.conf. The 911 extension performs call routing to the phone company's Public Safety Answering Point (PSAP), via the standard 911 phone number. (In countries other than the United States, local jurisdictions will use different numbers for this purpose, so check with your local emergency dispatch authority to find out what number to use.)

Add a _011X extension to enable international dialing.

Of course, none of this is going to work until the drivers are loaded and the dial plan is reread by Asterisk, so give your machine a reboot, or load the modules and restart Asterisk manually. Then, call and be calledon the cheap. The coolest thing about the PBX you've just built is its cost effectiveness. To buy a four-line business phone system new is usually more expensive than equipping an Asterisk box like you've done in this hack. Plus, you've got access to Asterisk's programmable dial plan and application programming interfaces (the Asterisk Gateway Interface and Asterisk Manager API), giving you a metric ton more capabilities than a low-end commercial PBX.