SolutionBase: Designing a basic Asterisk VOIP system for SIP clients

[LEFT][CODE]http://articles.techrepublic.com.com/2415-7343_11-93503.html[/CODE][B]Takeaway:[/B] Asterisk can be a powerful VoIP solution, but configuring it can be tricky; there are no fancy point-and-click GUIs. Brian Smith shows you how to configure Asterisk by fine-tuning the appropriate configuration files.
Asterisk is becoming an increasingly popular way for organizations to deploy VoIP without making a huge investment in proprietary systems. One of the major hurdles to get over when deploying Asterisk is to learn how the different configuration files work together and how to configure the system to answer phones.
In this article, I'm going to explain some of the core concepts that are involved in assembling a SIP based Asterisk Soft PBX environment. By the end of this article, you will have fully functional Asterisk environment capable of SIP client transactions with voicemail features.
[B]Author's note[/B]

For this article, I'll be using Gentoo Linux. Traditionally, Gentoo has a reputation for being difficult to install, but this is no longer true. A Gentoo Live CD install is available from [URL="http://www.gentoo.org/"]Gentoo.org[/URL], which makes installation a snap. I chose Gentoo instead of a more familiar distribution, such as Ubuntu, because a build environment for Asterisk already exists for Gentoo. Asterisk can run on OSX and virtually any other UNIX-based OS. However, if you choose to use another distribution, the install process may be more complex, and you may have to manually compile Asterisk.
If you're using Ubuntu or a distribution that doesn't have a native Asterisk build ready for it, there is quite a bit of leg work you must do first. First, you will need to install additional utilities, such as [I]gcc[/I], [I]automake[/I], [I]cvs[/I], [I]g++[/I], [I]libncurses5-dev[/I],[I] libssl-dev[/I],[I] slib1g-dev[/I],[I] build-essential[/I], [I]autoconf[/I], [I]bison[/I], [I]flex[/I],and[I] libtool[/I]. After these are installed, you will have the proper build environment to download [I]libpri[/I], [I]zaptel[/I] and Asterisk sources and compile them. There are instructions available on [URL="http://www.asterisk.org/support"]Asterisk's Web site[/URL] that outline this process in detail.
For the purposes of this article, we will be using [URL="http://ftp.digium.com/pub/asterisk/asterisk-1.2.17.tar.gz"]Asterisk 1.2[/URL]. The other version available is [URL="http://ftp.digium.com/pub/asterisk/asterisk-1.4.2.tar.gz"]Asterisk 1.4[/URL], which has many new features, but is still in beta.
[B]Getting ready[/B]

Before you begin installation, you need to do a little prep work to your system. The first thing you'll need to do is update your portage repository. To do this, access a shell or terminal to the server. Once at the command prompt, change to SuperUser or root using the command [I]su-[/I].
Now you have a root session. Continue by typing [I]emerge -sync[/I], as shown in [B]Figure A[/B]. Your machine will begin downloading and updating to the latest [I]ebuilds[/I]. Once the sync is complete, you'll be returned to your shell prompt, as shown in [B]Figure B[/B].
[B]Figure A[/B]

[URL="http://i.i.com.com/cnwk.1d/i/tr/contentPics/Asterisk_SIP_a.jpg"][IMG]http://i.i.com.com/cnwk.1d/i/tr/contentPics/Asterisk_SIP_a.jpg[/IMG][/URL]
Get the latest builds by using the[I] emerge[/I] command.

[B]Figure B[/B]

[URL="http://i.i.com.com/cnwk.1d/i/tr/contentPics/Asterisk_SIP_c.jpg"][IMG]http://i.i.com.com/cnwk.1d/i/tr/contentPics/Asterisk_SIP_c.jpg[/IMG][/URL]
The latest updates download and install on your computer. You'll return to the command prompt.

The next step is to edit the [I]/etc/portage/package.use[/I] file so you can set the USE flags for the Asterisk [I]ebuilds[/I]. If this file doesn't exist, create it. After it is created, add the following [I]use[/I] flag inside the [I]package.use[/I] file:
[I]net-misc/asterisk[/I][I] curl doc h323 odbc pri speex zaptel[/I]
as seen in [B]Figure C.[/B]
[B]Figure C[/B]

[URL="http://i.i.com.com/cnwk.1d/i/tr/contentPics/Asterisk_SIP_f.jpg"][IMG]http://i.i.com.com/cnwk.1d/i/tr/contentPics/Asterisk_SIP_f.jpg[/IMG][/URL]
You need to add this line to the [I]package.use[/I] file.

This will tell [I]emerge[/I] to build Asterisk with support for all the features you'll be using for your configuration. As you can see, it includes the download instruction for the Zaptel driver. This is the driver that will support your Digium PRI card, as well as Sonoma and Rhino PRI cards. If you are using a card not supported by the Zaptel driver, you will need to contact your manufacturer to find out which driver you need to install.
At this stage, you can run the [I]emerge -pv net-misc/asterisk[/I] command, which will allow you to preview which packages are going to be installed and what flags will be implemented by each build, as shown in [B]Figure D[/B].
[B]Figure D[/B]

[URL="http://i.i.com.com/cnwk.1d/i/tr/contentPics/Asterisk_SIP_h.jpg"][IMG]http://i.i.com.com/cnwk.1d/i/tr/contentPics/Asterisk_SIP_h.jpg[/IMG][/URL]
Check the packages to be installed and any flags.

To exit the preview and begin with the build process, just enter [I]emerge net-misc/asterisk[/I] and the build process will begin, as shown in [B]Figure E[/B].
[B]Figure E[/B]

[URL="http://i.i.com.com/cnwk.1d/i/tr/contentPics/Asterisk_SIP_i.jpg"][IMG]http://i.i.com.com/cnwk.1d/i/tr/contentPics/Asterisk_SIP_i.jpg[/IMG][/URL]
The Asterisk build process completes.

[B]Asterisk concepts to know[/B]

While Asterisk is compiling, I'll explain some core concepts that you should be familiar with before you begin configuring your system. Don't forget that Asterisk is essentially a framework for VoIP telephony, and you'll build upon this framework to develop your office PBX.
[B]Extensions[/B]

If Asterisk is a framework, then extensions can almost be referred to as a programming language. Like programming languages, your extensions become the step by step instructions of what your dial plan will do. The dial plan is the overall configuration of the extensions and the processes they create. Your dial plan is what will make or break the functionality and security of your PBX configuration, so it is imperative that care is taken to ensure a good telephony experience for you and your customers. Otherwise, now would be a good time to hire on that extra secretary to handle the hate mail your users will send you.
Extension definitions are stored in the file named [I]extensions.conf[/I]. This file contains all the routing information for your incoming and outgoing calls. There are three main sections to the file: globals, contexts and macros. Globals contain all of your global configuration data for your extensions. I'll get to macros and contexts a little later.
An extension definition is comprised of three comma separated parts, pretexted with [I]exten[/I][I] =>[/I]. This pretext notifies Asterisk that we are beginning an extension definition. The format for an extension looks like this:
exten => extension,priority,command(paramiters)
This may seem confusing, but let's look at a sample extension configuration for an after-hours message that you might use if the office is closed.
[office]
exten => 123,1,Answer
exten => 123,2,Playback(office-is-closed.gsm)
exten => 123,3,Hangup
Let's break this down. First, the extension is within a context labeled "office". This office context may be comprised of many different extensions, or even other contexts, which is something you'll be getting more familiar with as we progress. The first line ([I]exten[/I][I] =>123,1,Answer[/I]) says that when extension 123 is called, Asterisks should answer this line. The second line executes the Playback command and passes the argument of the audio file that should be played to the caller. After the message has played, the third line of the extension indicates that Asterisks should hang up the line and disconnect the caller from the phone system.
[B]Contexts[/B]

The next term to familiarize yourself with is contexts. Contexts are every bit as important to understand as the extensions they manage. A context is similar to an Access Control List (ACL). If the extension is the conduit of flow, then the context would be the divider that contains the flow. A context is what controls which extensions can be dialed and what features of the phone system are accessible. Let's look at another example.
[office]
exten => 200,1,Dial(SIP/200,20)
exten => 200,2,Voicemail(200)
exten => 200,3,Hangup
exten => 201,1,Dial(SIP/201,20)
exten => 201,2,Voicemail(201)
exten => 201,3,Hangup
[warehouse]
exten => 300,1,Dial(SIP/300,20)
exten => 300,2,Voicemail(300)
exten => 300,3,Hangup
This example introduces two contexts; office and warehouse. Each extension is instructed to dial the extension's SIP phone, to forward the call to voicemail if it remains unanswered for 20 seconds, and then to hang up. Notice in this example that extension 200 in the office context can call extension 201, but it is not able to dial to extension 300, because that extension resides in the warehouse context.
[B]Macros[/B]

Now that you're familiar with contexts, let's look at Macros. Macros are a context that begin with [I]macro-[/I] in the context definition (i.e., [I][macro-dialExtension][/I]). Once initiated, a macro will jump to the "s" extension. From here, you can begin a normal priority list of instructions.
Let's take the example from above and build on it. This time, however, we do not want to tell the caller that the office is closed; rather, we want to attempt to make the extension live and connect it with a real person.
A macro is initiated through the [I]macro[/I] command:
[office]
exten => 123,1,Answer
exten => 123,2,Macro(dialExtension,123,SIP/123)
exten => 123,3,Hangup
Our [I]dialExtension[/I] macro requires two parameters to be passed to it. First, the extension you are attempting to dial, and then the device the extension's endpoint is at.
[macro-dialExtension]
exten => s,1,Dial(${ARG2},20)
exten => s,2,Voicemail(${ARG1})
Looking at this example, you may notice that there isn't an extension defined. As you know, a context can only call an extension that is defined within itself. At the same time however, callers can be forwarded to another context via the [I]goto[/I] command or a dial command to a device can be executed.
To illustrate this, let's say you have an automated call directory for a credit card company. The system prompts the caller to enter their credit card number, then a macro called [I]verifycreditcard[/I] executes, which plays a message to the caller replaying the entered information and asking the customer to press 1 if correct, or 2 to reenter the information. In that circumstance 1 and 2 would be extensions, but only the [I]verifycreditcard[/I] macro is able to access them. The caller is not able to dial any other extensions that may be present outside of the macro.
[B]Designing the system[/B]

Now that you have a basic understanding of extensions, contexts, and macros, you can begin designing your phone system. For the purposes of this article, we are going to be using T1 PRI line using with a Digium T100 PCI card and using SIP phone clients, which can be either hard or soft phones.
Now it's time to begin setting up the office phone system using your freshly-built Asterisk Soft PBX. Since you have a general understanding of how extensions work with contexts, you'll be able to safely configure your phones to call each other, and eventually the outside world.
In this example, we'll plan to have three SIP client phones connecting to a 24-channel T1 PRI card. You'll be using a network interface card to connect to a network switch which your SIP hard phones are wired to through standard Cat5 cable. There are many methods for wiring your VoIP phones together, including PoE switches and separate networks dedicated for VoIP solutions; however, one big advantage of using VoIP is that you can use your existing network.
Before we dive in, it is important to remember that all the Asterisk [I]config[/I] files are well-organized and logically named. For example, extensions are defined in the [I]extensions.conf[/I] file, and SIP clients in the [I]sip.conf[/I] file.
[B]SIP clients[/B]

Naturally, you'll need something to talk to on the other end of the call, so first you'll need a SIP client. These can be software applications that run on your computer like Kiax, Kphone, or SJPhone.
We'll be working with the [I]sip.conf[/I] file, so you can open it using any text editor You'll see a file similar to the one in [B]Figure F[/B].
[B]Figure F[/B]

[URL="http://i.i.com.com/cnwk.1d/i/tr/contentPics/Asterisk_SIP_m.jpg"][IMG]http://i.i.com.com/cnwk.1d/i/tr/contentPics/Asterisk_SIP_m.jpg[/IMG][/URL]
Edit [I]sip.conf[/I] using any text editor, like [I]nano[/I].

The first thing you need to be aware of is that the SIP service needs to be configured. You'll find it under the heading [I][general][/I]. Here you can define what port we want the SIP clients to [I]access[/I] (default is 5060), [I]bind address[/I], and various other options.
To prevent any outside connections to your SIP service, change the option for [I]bindaddr[/I] in your [I]sip.conf[/I] file under the [I][general] [/I]section to bind SIP to your internal IP address on your network card.
Another important option to be aware of is the context that the incoming SIP connections will be placed in. This can be different from your SIP clients, which can be configured individually. In this example, we know that SIP connections are only going to be coming from an internal network, so it makes no sense to host SIP services on an external T1 connection.
Here is your general configuration thus far for [I]sip.conf[/I]:
[general]
context=office

srvlookup=yes ; to allow for calling other sip clients over the internet
musicclass=default ; for on hold music
Before we can begin to use your phone system, you need to make it accessible to your phones, commonly referred to as clients. In this example, this would be the phones at the office. To do this, we need to edit the [I]sip.conf[/I] file again. Below is a configuration for Joe's telephone at extension 212.
[212]
< type=friend
mailbox=212@office
auth=md5
username=212
secret=p4ssw0rd
callerid=("Joe" <212>)
host=dynamic
disallow=all
allow=gsm
allow=ulaw
allow=alaw
To begin with we see the declaration of the SIP device name contained in the square brackets [I][212][/I]. Let's break down each of the parameters and what they mean to your SIP device.

[LIST][*][B]Type:[/B] This value will define what the relationship to the Asterisk server is. Available options: user, peer, and friend.[*][B]Username: [/B]The username the SIP client will use when authenticating.[*][B]Secret:[/B] The password the SIP client must provide along with the username to authenticate with SIP service.[*][B]Allow: [/B]The possible [I]codec[/I] that the voice transaction will be on for the device. Before allowing any [I]codec[/I], you should first deny all others.[*][B]CallerID[/B][B]:[/B] This is the string we want your caller ID to appear as when calling someone else.[*][B]Host:[/B] This will determine the phone's hostname. If set to dynamic, the phone will register with the SIP server. Other options are either to enter the hostname or IP address of the phone.[*][B]Mailbox:[/B] Defines a mailbox and context to associate the SIP client with (more on this later).[/LIST]
Now we are going to replicate the previous configuration, only for your other clients in the office.
[213]
type=friend
mailbox=213@office
auth=md5
username=213
secret=p4ssw0rd
callerid=("Bob" <213>)
host=dynamic
disallow=all
allow=gsm
allow=ulaw
allow=alaw
You should note that the only thing that changed is the extension that we are calling. As you can now tell, setting up SIP clients is really a simple process.
[B]Extensions revisited[/B]

Now that we have SIP clients configured to authenticate to the Asterisk SIP service, we need to route and connect your SIP clients to each other. To do this, we need to begin modifying the [I]extensions.conf[/I] configuration file. As with the [I]sip.conf[/I] file, you can edit [I]extensions.conf[/I]with any text editor, as shown in [B]Figure G.[/B]
[B]Figure G[/B]

[URL="http://i.i.com.com/cnwk.1d/i/tr/contentPics/Asterisk_SIP_p.jpg"][IMG]http://i.i.com.com/cnwk.1d/i/tr/contentPics/Asterisk_SIP_p.jpg[/IMG][/URL]
You can edit [I]extensions.conf[/I] using any text editor like [I]nano[/I].

For our example, add the following configuration:
[office]
exten => 212,1,Dial('SIP/212',20)
exten => 212,n,Voicemail(212)
exten => 212,n,Hangup
exten => 213,1,Dial('SIP/213',20)
exten => 213,n,Voicemail(213)
exten => 213,n,Hangup
Both extensions are ready to talk to each other. The extension directly dials the SIP device for 20 seconds and then forwards the user to voicemail; then we disconnect.
[B]Voicemail[/B]

You've probably been wondering how we go about getting your voicemail up and running. It's actually pretty simple; first, you'll need to edit your [I]voicemail.conf[/I] file. In this we have the normal series of [I][general][/I] [I]config[/I] options, followed by your context definitions. Be sure to set the voicemail format to record in .mp3, .gsm, and .wav formats. This is done by recording the following option under the [I][general][/I] section.
[general]
format = wav49|gsm|wav
Voicemail definitions follow a familiar format:
[context]
extension => Password, Real Name, Email Address, Pager Email Address, user options
In your example, we are going to setup a mailbox for each of your users. For this, at the end of the [I]voicemail.conf[/I] file, you'll want to add the following:
[office]
212 => 456,Joe Smith,joe@mycompany.com
213 => 789,Bob Barker,bob@mycompany.com
Now, whenever Bob receives a new voicemail, a .mp3 copy will be e-mailed to [EMAIL="bob@mycompany.com"]bob@mycompany.com[/EMAIL].
[B]Ready to go[/B]

At this point, we are able to make phone calls between Bob and Joe. As root on a shell, execute [I]/etc/init.d/asterisk start[/I] and the Asterisk system will start. Now is the time to configure your SIP clients to login. Remember, currently Asterisk only supports SIP over UDP; also remember the username and password of your SIP clients when configuring them. Now, let the phones ring
[/LEFT]