Extensions.conf

extensions.conf – This is your Dialplan.

The configuration file “extensions.conf” contains the “dial plan” of Asterisk, the master plan of control or execution flow for all of its operations. It controls how incoming and outgoing calls are handled and routed. This is where you configure the behavior of all connections through your PBX.

The content of “extensions.conf” is organized in sections, which can be either for static settings and definitions, or for executable dialplan components in which case they are referred to as contexts. The settings sections are general and globals and the names of contexts are entirely defined by the system administrator. A special type of contexts are macros, label by a userdefined name prefixed with macro-. These are reusable execution patterns, like procedures in a programming language. Every section in extensions.conf starts with the name of the section contained within square brackets. This gives the extensions.conf file a similar structure to the traditional .ini file format of the Windows world.

Asterisk Dialplan Planning – General discussion about organizing a dialplan

New in Asterisk v1.2: By default, there is a new option called “autofallthrough” in extensions.conf that is set to yes. Asterisk 1.0 (and earlier) behavior was to wait for an extension to be dialed after there were no more extensions to execute. “autofallthrough” changes this behavior so that the call is terminated immediately with BUSY, CONGESTION, or HANGUP based on Asterisk’s best guess. If you are writing an extension for IVR, you must use the WaitExtenapplication if “autofallthrough” is set to yes.

[general]

  • At the top of your extensions.conf file, you configure a few general settings in the section headed [general]. For details, see:

[globals]

Contexts and Extensions

  • After the [general] and [globals] categories, the remainder of the extensions.conf file is taken up by the definition of the Dialplan. The Dialplan consists of a collection of contexts. Each context consists of a collection of extensions. For an introduction to these topics, see:

Extension Patterns

  • When you define the extensions within a context, you may not only use literal numbers, not only alphanumeric names, but also you may define extensions that match whole sets of dialed numbers by using extension patterns. For more information about this, see:

Context Inclusion

One extension context can include the contents of another. For example, consider the following contexts:

Context “default”:

Extension Description

101 Mark Spencer

102 Wil Meadows

0 Operator

Context “local”:

Extension Description

_9NXXXXXX Local calls

include => “default”

Context “longdistance”:

Extension Description

_91NXXNXXXXXX Long distance calls

include => “local”

Here we have defined three extensions:

  • The context default permits dialing three telephone extensions: Mark, Wil, and the Operator.
  • The context local has one extension pattern to permit dialing 7-digit numbers only (local calls), and also includes the context “default”, thus also permitting a user to dial Mark, Wil, or the Operator.
  • The context long distance has one extension pattern to permit dialing a long-distance call, and it also includes the context “local”, thus permitting the user to make local calls and also to dial the extensions of Mark, Wil or the Operator.

Using extension contexts, you can carefully control who has access to toll services.

If more than one pattern matches a dialed number, Asterisk may not use the one you expect. See Sort Order of Extension Patterns.

Adding to an existing section (I believe this is a 1.4 feature; additional info on similar option are in doc/configuration.txt of asterisk src tree)

[section]

label = value

[section](+)

label2 = value2

In this case, the plus sign indicates that the second section (with the same name) is an addition to the first section. The second section can be in another file (by using the #include statement). If the section name referred to before the plus is missing, the configuration fails to load.

When Asterisk receives an incoming connection on a channel, Asterisk looks at the context defined for that channel for commands telling Asterisk what it should do. The context defines different sets of commands depending on what extension the user has dialed. For example, a context might provide one set of commands for what to do if the user dials “123”, and another set of commands for what to do if the user dials “9”, and another set of commands for what to do if the user dials any number beginning with “555”.

For some kinds of connections — such incoming calls from an outside telephone line — the user has not dialed an extension. In that case, Asterisk behaves as if the user had dialed a special extension named “s” (for Start). Asterisk looks for an extension “number” s in the definition of the context for that channel for instructions about what it should do to handle the call.

Let’s say, for example, that you have a channel “Zap/1” which is a connection to a telephone handset in your building. And let’s say that in the configuration file for Zap channels (zapata.conf), you have defined context=john for Zap channel 1. So when you use that handset to dial a number, Asterisk looks for a context with the name “john” in extensions.conf to find out what it should do. You begin the definition of a context in extensions.conf by putting the name of the context in square brackets on a line by itself, like this:

[john]

For each context, you need to define one or more extensions that Asterisk uses to compare against the number dialed. For each extension, you tell Asterisk what to do by listing a set of commands.

Extensions

An extension can be one of two types: a literal or a pattern.

A literal extension can be a number, like 123, and it can also contain the standard symbols * and # that appear on ordinary telephones, so 12#89* is a valid extension. Some telephone keypads have the special DTMF keys labeled A, B, C and D, and extensions can be defined with these letters too. In fact, the name of an extension can contain any letter or number as well as some punctuation marks. Note that many VOIP telephones are able to “dial” extension “numbers” that may be any arbitrary text string, such as “Office”. It is perfectly permissible to define an extension with the name Officein Asterisk.

Extension names may or may not be case sensitive. They are case sensitive in the sense that when Asterisk is trying to match the extension a user dialed against the extensions defined for a context, the extension must match, including case. So if a user dials extension “OFFICE” using their VOIP telephone, Asterisk does not start executing the commands you have defined for an extension named “Office”. On the other hand, extension names are not case sensitive in the sense that you can not define different extensions (in the one context) that have the same names differing only in case. So you can’t define one set of commands for extension “Office” and another set of commands for extension “OFFICE”.

Predefined Extension Names

Asterisk uses some extension names for special purposes:

  • i : Invalid
  • s : Start
  • h : Hangup
  • t : Timeout
  • T : AbsoluteTimeout
  • a : Asterisk extension
  • o : Operator

See Asterisk standard extensions for details.

Defining Extensions

Unlike a traditional PBX, where extensions are associated with phones, interfaces, menus, and so on, in Asterisk an extension is defined as a list of commands to execute. The commands are generally executed in the order defined by their “priority” tag, but some commands, such as the Dial and GotoIf commands, have the ability to redirect somewhere else, based on some condition.

When an extension is dialed, the command tagged with a priority of 1 is executed, followed by command priority 2, and so on. This goes on until:

  • the call is hung up,
  • a command returns a result code of -1 (indicating failure),
  • a command with the next higher priority doesn’t exist (note: Asterisk does not “skip over” missing priorities), or
  • the call is routed to a new extension.

In the syntax of the extensions.conf file, each execution step in an extension is written in this format:

exten = extension,priority,Command(parameters)

where the equal sign can also be ornamented as an arrow, i.e., “=>”, a form most often seen in many examples.

Ok, so a “context” has a name, such as “john”. And in each context, you can define one or more “extensions”. For each extension, you define a set of commands. So how do you define these extensions and the commands to handle them? You need to edit the extensions.conf file with a text editor. However, there are some tools available to help: GUI tool.

The components of an extension execution step or command line are the following:

    • extension is the label of the extension, and can be either a literal constant string (alphanumeric plus a few special symols allowed) or a dynamically evaluated pattern (see below) to match many possible phone numbers, for example. Every command line that is part of a given extensions has this same label.
    • priority is usually an integer (see note, however). It’s just a sequence number for each command line of an extension. The first executable command of an extensions has the priority “1”, so when Asterisk transfers a call to an extension, it looks for a command with priority 1. If there is not a line with a priority of 1, then the extension does not match the dialed number. After executing the priority 1 command, Asterisk increments the priority to “2” unless the command itself determines the next priority to be executed. If this next priority is not defined in the extension, Asterisk finishes processing for this extension, even if there exists another command with a priority higher than the missing one.

Note: Strings may also be used in place of priority in special situations (see Asterisk standard extensions).

    • command is the name of the command (also called an “application”) to execute. See the Asterisk Commands List.
  • parameters depend on the command. Some commands take no parameters, in which case you can omit the parentheses.

Example

exten => 123,1,Answer

exten => 123,2,Playback(tt-weasels)

exten => 123,3,Voicemail(44)

exten => 123,4,Hangup

This is the definiton of a single extension with name “123”. When a call is made to extension 123, Asterisk answers the call itself, play a sound file called “tt-weasels”, give the user an opportunity to leave a voicemail message for mailbox 44, and then hangup.

Note that Asterisk doesn’t care about the order in which you put the lines in the extensions.conf file. You could mix the lines into a different order, like this following example, and it would make no difference because Asterisk uses the priority of each line to determine order of execution:

exten => 123,4,Hangup

exten => 123,1,Answer

exten => 123,3,Voicemail(44)

exten => 123,2,Playback(tt-weasels)

Other options for defining extensions include an option commonly referred to as the ex-girlfriend logic. This logic matches the dialed extension irrespective of its origin based on the callerid of the person calling it. For example:

exten => 123/100,1,Answer()

exten => 123/100,2,Playback(tt-weasels)

exten => 123/100,3,Voicemail(123)

exten => 123/100,4,Hangup()

This matches extension 123 and perform the following options ONLY if the Caller-ID Number of the calling user is 100. This can also be accomplished with pattern matching, as seen below:

exten => 1234/_256NXXXXXX,1,Answer()

and so on…

This matches only 1234 if the Caller ID Number is something beginning with 256. This is very useful to keep locals from dialing your toll-free number and charging you for the call.

You can even do this:

exten => s,1,Answer

exten => s/9184238080,2,Set(CALLERID(name)=EVIL BASTARD)

exten => s,2,Set(CALLERID(name)=Good Person)

exten => s,3,Dial(SIP/goodperson)

(thanks for pointing that out, Brian 🙂 )

Basically the call comes in, at 2 you fork the people you don’t like out, everybody else stays in the path and at 3 everybody is back in the main path.

Syntax for defining a context: keywords exten, include, ignorepat and switch.

One of the banes of this method of storing the extension information is that if you need to insert or delete a priority, you have to manually renumber all numbers after it and all label referrences to it. I’m working on a utility to do this online: give it a try if you like

Since Asterisk 1.2 there is a new way to work around this. Number the first priority and “name” the following priorities “n”. See Asterisk Prioritiesfor further details!

If you are not so familiar with Asterisk dialplan syntax, dialplan priorities, or you simply do not prefer coding using text editors, you may find Visual Dialplan for Asterisk useful tool for your dialplan development. Visual Dialplan for Asterisk is rapid dialplan development tool for Asterisk dialplan development, it provides similar interface and approach like Visual Basic provides for rapid application development for Windows platform (if you are more familiar the Windows environment like I am, although there is Visual Dialplan for Linux too).

You may drag, drop and connect building blocks to make Asterisk dialplan. Then you may configure building blocks to fine tune your dialplan.

Here is the same example above created using Visual Dialplan for Asterisk:

Download above example

Download Visual Dialplan for Asterisk

Variables and expressions

There is support for using variables using the ${VARIABLENAME} construct. You can also use expressions with the $[EXPRESSION] construct, where expressions can be regular expressions, comparision, addition, substraction and much more. See Asterisk variables for standard variables and Asterisk readme.variables for an explanations of expressions.

For more information about using global variables and channel variables in extensions.conf, see

New in 1.2 are dialplan functions, see

Reloading

If you want to reload the dial plan after changes, without reloading all of Asterisk’s config, use the dialplan reload Asterisk CLI command.

Either connect to your asterisk process with asterisk -r or rasterisk and type in the command, or send the command directly with:

asterisk -rx ‘dialplan reload’

One big file or several small?

With the #include <filename> statement in extensions.conf, other files are included. This way you can setup a system where extensions.conf is the main file, users.conf (SEE IMPORTANT NOTE BELOW) contain your local users, services.conf contain various services, like conferencing. This way, the dial plan may be easier to maintain, depending on the size of your setup. The #include <filename> statement is not the same as the include <context> statement. The #include statement works in all Asterisk configuration files.

DO NOT USE users.conf as a filename anymore! This is now a “reserved” filename as of Asterisk 1.4! In general, it is a good idea to divide your extensions.conf file up into subcomponents but put those files in a subdirectory (don’t clutter up /etc/asterisk). For example, have a directory /etc/asterisk/exts and use #include <exts/…>

Sample extensions.conf using the #include statement

#include “my-extra-config-file”

[globals]
ALL=Zap/1&SIP/1000&SIP/1001

[default]
exten => s,1,Answer
exten => s,2,Playback(welcome-message)
exten => s,3,Goto(context-in-include-file,s,1) ; go to context defined in included file

Forwarding to another Asterisk

Syntax:

[iaxprovider]

switch => IAX2/user:[key]@server/context

Specifies forwarding to another server. The user and key needs to be defined in the iax.conf file of the server which is called. The context is a context in the called servers extensions.conf.

Controlling extensions.conf from outside

Macro Examples

Using a macro to create extensions

[globals]
PHONE1=Zap/1
PHONE2=SIP/6002

[macro-oneline]
exten => s,1,Dial(${ARG1},20,t)
exten => s,2,Voicemail(u${MACRO_EXTEN})
exten => s,3,Hangup
exten => s,102,Voicemail(b${MACRO_EXTEN})
exten => s,103,Hangup

[local]
exten => 6601,1,Macro(oneline,${PHONE1})
exten => 6602,1,Macro(oneline,${PHONE2})

Sip header manipulation examples

These examples may be beneficial when interfacing Asterisk with a Nortel SST or an Acme Packet SBC.

Sending RFC-3323 compliant privacy headers in sip calls

ftp://ftp.rfc-editor.org/in-notes/rfc3323.txt

exten => _9.,1,SIPAddHeader(P-Asserted-Identity: <sip:+1${CALLERID(num)}\;user=phone>)

exten => _9.,n,SIPAddHeader(Privacy: user\; header\; session)

exten => _9.,n.SetCallerPres(prohib_not_screened) ; this might not be needed — needs further testing

exten => _9.,n,Set(CALLERID(num)=)

exten => _9.,n,Set(CALLERID(name)=Anonymous)

exten => _9.,n,Dial(SIP/+${EXTEN:1}@sipcarrier)

exten => _9.,n,Hangup()

Sending RFC-3325 compliant privacy headers in sip calls

ftp://ftp.rfc-editor.org/in-notes/rfc3325.txt

exten => _9.,1,SIPAddHeader(P-Preferred-Identity: <sip:+1${CALLERID(num)}\;user=phone>)

exten => _9.,n,SIPAddHeader(Privacy: id)

exten => _9.,n.SetCallerPres(prohib_not_screened) ; this might not be needed — needs further testing

exten => _9.,n,Set(CALLERID(num)=)

exten => _9.,n,Set(CALLERID(name)=Anonymous)

exten => _9.,n,Dial(SIP/+${EXTEN:1}@sipcarrier)

exten => _9.,n,Hangup()

Sending Sip Diversion headers (spawned from dialplan as macro) 

[macro-diversion-header]

exten => s,1,SIPAddHeader(Diversion: <tel:+{ARG1}>\;reason=user=busy\;screen=no\;privacy=off)

Tip: With vim syntax highlighting highlights correct dialplan syntax and may ease dialplan design through these visual aids.

Example files on the net

See also

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.