SolutionBase: Designing a basic Asterisk VOIP system for SIP clients

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.

Author's note

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, 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 gcc, automake, cvs, g++, libncurses5-dev, libssl-dev, slib1g-dev, build-essential, autoconf, bison, flex, and libtool. After these are installed, you will have the proper build environment to download libpri, zaptel and Asterisk sources and compile them. There are instructions available on Asterisk's Web site that outline this process in detail.

For the purposes of this article, we will be using Asterisk 1.2. The other version available is Asterisk 1.4, which has many new features, but is still in beta.

Getting ready

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 su-.

Now you have a root session. Continue by typing emerge -sync, as shown in Figure A. Your machine will begin downloading and updating to the latest ebuilds. Once the sync is complete, you'll be returned to your shell prompt, as shown in Figure B.

Figure A

Get the latest builds by using the emerge command.

Figure B

The latest updates download and install on your computer. You'll return to the command prompt.

The next step is to edit the /etc/portage/package.use file so you can set the USE flags for the Asterisk ebuilds. If this file doesn't exist, create it. After it is created, add the following use flag inside the package.use file:

net-misc/asterisk curl doc h323 odbc pri speex zaptel

as seen in Figure C.

Figure C

You need to add this line to the package.use file.

This will tell emerge 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 emerge -pv net-misc/asterisk 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 Figure D.

Figure D

Check the packages to be installed and any flags.

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

Figure E

The Asterisk build process completes.

Asterisk concepts to know

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.


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 extensions.conf. 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 exten =>. 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.


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 (exten =>123,1,Answer) 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.


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.


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


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.


Now that you're familiar with contexts, let's look at Macros. Macros are a context that begin with macro- in the context definition (i.e., [macro-dialExtension]). 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 macro command:


exten => 123,1,Answer

exten => 123,2,Macro(dialExtension,123,SIP/123)

exten => 123,3,Hangup

Our dialExtension 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.


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 goto 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 verifycreditcard 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 verifycreditcard macro is able to access them. The caller is not able to dial any other extensions that may be present outside of the macro.

Designing the system

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 config files are well-organized and logically named. For example, extensions are defined in the extensions.conf file, and SIP clients in the sip.conf file.

SIP clients

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 sip.conf file, so you can open it using any text editor You'll see a file similar to the one in Figure F.

Figure F

Edit sip.conf using any text editor, like nano.

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 [general]. Here you can define what port we want the SIP clients to access (default is 5060), bind address, and various other options.

To prevent any outside connections to your SIP service, change the option for bindaddr in your sip.conf file under the [general] 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 sip.conf:



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 sip.conf file again. Below is a configuration for Joe's telephone at extension 212.






callerid=("Joe" <212>)






To begin with we see the declaration of the SIP device name contained in the square brackets [212]. Let's break down each of the parameters and what they mean to your SIP device.

  • Type: This value will define what the relationship to the Asterisk server is. Available options: user, peer, and friend.
  • Username: The username the SIP client will use when authenticating.
  • Secret: The password the SIP client must provide along with the username to authenticate with SIP service.
  • Allow: The possible codec that the voice transaction will be on for the device. Before allowing any codec, you should first deny all others.
  • CallerID: This is the string we want your caller ID to appear as when calling someone else.
  • Host: 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.
  • Mailbox: Defines a mailbox and context to associate the SIP client with (more on this later).

Now we are going to replicate the previous configuration, only for your other clients in the office.







callerid=("Bob" <213>)






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.

Extensions revisited

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 extensions.conf configuration file. As with the sip.conf file, you can edit extensions.conf with any text editor, as shown in Figure G.

Figure G

You can edit extensions.conf using any text editor like nano.

For our example, add the following configuration:


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.


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 voicemail.conf file. In this we have the normal series of [general] config 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 [general] section.


format = wav49|gsm|wav

Voicemail definitions follow a familiar format:


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 voicemail.conf file, you'll want to add the following:


212 => 456,Joe Smith,

213 => 789,Bob Barker,

Now, whenever Bob receives a new voicemail, a .mp3 copy will be e-mailed to

Ready to go

At this point, we are able to make phone calls between Bob and Joe. As root on a shell, execute /etc/init.d/asterisk start 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!