VoIPowering Your Office With Asterisk: Mastering Dialplan Basics

The dialplan sets up the basic nuts and bolts of how calls are processed. To build one, you need to understand configuration files, today's mission.

By Carla Schroder | Posted Jun 19, 2006
Page of   |  Back to Page 1
Print ArticleEmail Article
  • Share on Facebook
  • Share on Twitter
  • Share on LinkedIn

Last week we were introduced to "real Asterisk." Today we're going to get up close and personal, and poke around under the hood. The heart of Asterisk is the dialplan, and the key to Asterisk happiness is understanding how to create one. The dialplan controls how all calls are handled, both inbound and outbound.

Asterisk configuration files
Asterisk has more configuration files than you can shake a stick at, but we're going to focus on the fundamental ones:

  • extensions.conf
  • sip.conf
  • iax.conf
Asterisk comes with a large number of sample configuration files, which you don't want to use yourself, but are great for studying. Look in /etc/asterisk/.

extensions.conf is for configuring dialplans. sip.conf and iax.conf are for setting up incoming and outbound channels. SIP is probably the most popular VoIP protocol, and virtually all IP phones support it. IAX is used primarily for VoIP servers to talk to each other, then the signal can be converted to SIP for phones that don't support IAX. We'll talk more about these next week.

Dialplan components
A dialplan has four elements:

  • extensions
  • contexts
  • priorities
  • applications
The extensions.conf file has these sections:
  • [general]
  • [globals]
  • [contexts]
Don't change the "general" or "globals" keywords. "Contexts" is a category. You will likely have multiple contexts, and these all have names that you choose, like "local," "branch_office," "just_for_me," whatever you like.

Extensions
The word "extensions" is a bit unfortunate, because it sounds like plain old telephone extensions. But Asterisk extensions are sturdy little workhorses that do all kinds of things. Extension syntax looks like this:

exten => name,priority,application( )

A real-life extension looks like this:

exten => 555,1,Answer( )
The extension name is 555. Names can be either words or numbers. This extension is simple: when someone dials 555, it has the highest priority, and the action is to answer. Usually multiple extensions are required to handle a single call; these are called contexts.

Contexts
Named groups of extensions are called contexts. Each context is a separate unit, like a function in a software program, and does not interact with other contexts unless it is configured to do so. We used contexts in VoIPowering Your Office with Asterisk: Getting Free Long Distance, Part 2:

[dundi-priv-local]
  exten => 15035551212,1,Answer( )
  exten => 15035551212,n(call),Dial(SIP/200)
  exten => 15035551212,n,Voicemail(u200)
  exten => 15035551212,n,Hangup( )
There are four actions to be taken in this example. The first is to answer; "n" means go to the "next" action, which is to dial 200 and use the SIP protocol. The next action is to go to voicemail. After all that, hangup.

The second line demonstrates an interesting and powerful feature, the Dial command. The Dial command includes a boatload of commands and options. You could also include a login and password, an IP address, or an entirely different phone number.

n(call) shows how to use a text label. This is just a comment to help you remember what the command does. Text labels are enclosed in parentheses and follow priorities. It's a bit confusing because command options, which follow applications, are also enclosed in parentheses. Text labels are optional; you don't have to use them.

Priorities
You must always specify a number 1 priority; this is the first command Asterisk follows when processing a call. It doesn't have to be in any particular order, because Asterisk goes by the priority number. Additional extensions can either be numbered in sequence, or just use "n" and list them in sequence. With numbered priorities, our dundi-priv-local context could look like this:

[dundi-priv-local]
  exten => 15035551212,4,Hangup( )
  exten => 15035551212,2(call),Dial(SIP/200)
  exten => 15035551212,3,Voicemail(u200)
  exten => 15035551212,1,Answer( )
I don't know why anyone would want to do this, but it can be done. If you are numbering your priorities and accidentally skip one, Asterisk will stop there and not continue.

Applications
There are meelyuns of applications included in Asterisk. Well, more like dozens, which you will find in the "Application Reference" in "Asterisk: The Future of Telephony."

Playback is a fun one, and useful for testing. It plays a sound file:

exten => 555,n,Playback(ima_lumberjack_and_Im_OK)

Asterisk comes with a bunch of sound files in the sounds/ directory. To use this in testing, use it with the s (start) extension. This is a special built-in extension for handling calls without specific destinations:

[test-incoming]
    exten => s,1,Answer( )
    exten => s,n,Playback(ima_lumberjack_and_Im_OK)
    exten => s,n,Hangup( )
You could use this in place of the dundi-priv-local context in VoIPowering Your Office with Asterisk: Getting Free Long Distance, Part 2. It doesn't let you do a two-way conversation, it just verifies that your configuration works.

It's crucial to understand dialplans, so your homework is to study your sample configuration files. Next week we'll go in-depth on the other two key parts of having a functioning Asterisk VoIP system, the sip.conf and iax.conf files.

Resources
VoIP-Info.org
Asterisk Documentation Project has a downloadable free copy of the book "Asterisk: The Future of Telephony." It can also be purchased at the usual outlets. (Hint: supporting authors financially is a splendid thing to do.) This book is an essential reference, and contains all the Asterisk commands and configuration options.

Comment and Contribute
(Maximum characters: 1200). You have
characters left.
Get the Latest Scoop with Enterprise Networking Planet Newsletter