Asterisk basic configuration principles

In this section we'll have a look at the basic configuration of an Asterisk PBX. Contrary to the TFOT-book, we'll be looking at it from the theory side, and from there go to an example configuration. For this example configuration, we'll start from a server with on the "outside" a POTS line and a SIP account with an Internet provider, and on the "inside" two analogue telephones and a SIP softphone. Our goal is to let the PBX behave as if we don't even have a PBX, but a standard home situation: for an incoming call, all phones ring; and every internal phone can make calls to the outside.

Asterisk channel configuration basics

The first thing to realise is that Asterisk sees each connected telephony device as a "channel". But what is a Channel? To Asterisk, a channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel.

The second thing to realise, is that every type of device attached to the Asterisk PBX have their own specific configuration files. Correctly setting up each (set of) telephony devices makes them available in our Asterisk PBX as channels. Thus, the device configuration files serve as a kind of abstraction layer, and simplify our final Asterisk configuration by putting "channel-specific" information in separate files.

If you've followed the previous Asterisk sections in this Wiki, or followed the first four chapters of the TFOT-book, then you've encountered the following configuration files:

zaptel.conf - in this file, you can set up the most basic parameters for your Zap-type hardware channels, most notably Digium telephony cards. You're configuring the hardware itself, via its driver. You could think of this file as belonging to the hardware, not Asterisk. If you'd have other software on your machine besides Asterisk that could make use of your telephony hardware, then that'd be influenced as well when you change zaptel.conf.
zapata.conf (and possibly zapata-channels.conf if you're on Debian) - this file handles the Asterisk-specific configuration of the hardware telephony channels. It thus "sets up the Zap channels" that Asterisk sees - for incoming and outgoing calls. All parameters that set up the channel are specified here.
vpb.conf - this file is used to configure Voicetronix cards with Asterisk. If you've a Voicetronix card in use, then you've also installed the Voicetronix drivers. This makes the card(s) useable under Linux. But to have Asterisk use the card(s), you need this vpb.conf file. It thus serves the same purpose as zapata.conf.
sip.conf - this file contains all information on all SIP devices that we want to connect to our Asterisk server; be it one or more SIP accounts with Internet providers, or SIP capable telephones (hardware or software). When sip.conf has been set up correctly, we can refer to a SIP device by a friendly name like [1000] or [Jane].
iax.conf - this file is just the same as the sip.conf file, only it handles devices that talk IAX2 protocol instead of the SIP protocol.

These five files define all channels that our basic Asterisk PBX might handle (well, it won't even handle the last one, since we're not connecting any other Asterisk boxes or IAX-(soft)phones to our PBX, and it won't handle the third one if you don't have a Voicetronix card).

As a reference, we're going to list the contents of four example files, and explain what they do in the way of preparing channels for our simple Asterisk server.:

zaptel.conf

# Autogenerated by ./genzaptelconf -- do not hand edit
# Zaptel Configuration File
#
# This file is parsed by the Zaptel Configurator, ztcfg
#

# It must be in the module loading order

# Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER)
fxoks=1
fxoks=2
fxsks=3
# channel 4, WCTDM, no module.

# Global data

loadzone        = nl
defaultzone     = nl

This is a relatively simple file, configuring three Digium modules. As you can see, the genzaptelconf command has generated it for us. It belongs with a Digium TDM410P card, which has two FXS modules in positions 1 and 2, and one FXO module in position 3. The first two non-commented lines define the protocol that the FXS modules must "talk" with the attached devices, which "naturally" is the FXO protocol (yes, FXS talks FXO, and FXO talks FXS... a bit like electric current flowing from negative to positive. It's just a matter of definitions).
The third line defines that the FXO module talks FXS protocol.
The fourth line configures a set of indications to use for the defined channels. Since we're loading "nl", we're configuring Dutch dialtones etcetera for the channels.
Finally, the last line tell the server that any channel that does not have a zone assigned to it, should have the specified default zone configured - Dutch as well in this example.
With this simple file, the driver for our example card (wctdm24xxp, by the way) can set up the hardware just as we want it. Now to tell Asterisk how to use it...

zapata-channels.conf

; Autogenerated by ./genzaptelconf -- do not hand edit
; Zaptel Channels Configurations (zapata.conf)
;
; This is not intended to be a complete zapata.conf. Rather, it is intended
; to be #include-d by /etc/zapata.conf that will include the global settings
;

; Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER)
;;; line="1 WCTDM/0/0"
signalling=fxo_ks
callerid="Channel 1" <6001>
mailbox=6001
group=5
context=from-internal
channel => 1
callerid=
mailbox=
group=
context=default

;;; line="2 WCTDM/0/1"
signalling=fxo_ks
callerid="Channel 2" <6002>
mailbox=6002
group=5
context=from-internal
channel => 2
callerid=
mailbox=
group=
context=default

;;; line="3 WCTDM/0/2"
signalling=fxs_ks
callerid=asreceived
group=0
context=from-pstn
channel => 3
context=default

This second file is also auto-generated. It sets up three channels, associated with the three Digium hardware modules that we've configured with zaptel.conf. Here, we also see how the channel numbers get assigned to the physical ports. The first module gets to be Zap channel 1 (Zap/1), the second Zap/2 and so on. So if we would like our FXO module to be channel 1, and our FXS modules 2 and three, we could rotate the three channel numbers in this file. Probably we'd then also want to rotate the callerid`s though... Furthermore, we don't think it's a good idea to assign channels to Zap devices in a different order than the devices are found in the system - meaning "stick with the default numbering as much as possible".

Note that the way zapata-channels.conf is interpreted, means that any statement like signalling=fxs_ks actually sets the signalling parameter; when the channel => 1 line is reached, then all preceding parameter assignments are applied to that particular channel. This also means that if you somewhere have set a channel to belong to context "foo", and then never set a context again, then every next channel also gets assigned to "foo". So remember: if you don't see a parameter being set with a specific channel, you CANNOT assume that it then has it's default value; if a preceding channel has set that parameter to value "bar", then for your specific channel, it is "bar" also.

An interesting thing to see here is how genzaptelconf deals with the above concept. After defining each channel, it resets the most important parameters (a.o. the ones that should be unique with a channel) to empty or "default". This means that if you yourself are very meticulous, you could do without that safety net, and rewrite the above configuration file as:

signalling=fxo_ks
callerid="Channel 1" <6001>
mailbox=6001
group=5
context=from-internal
channel => 1

signalling=fxo_ks
callerid="Channel 2" <6002>
mailbox=6002
group=5
context=from-internal
channel => 2

signalling=fxs_ks
callerid=asreceived
group=0
context=from-pstn
channel => 3

Note: we like the thoroughnes of the genzaptelconf configuration, but we like the readability of the second file more.

zapata.conf

[trunkgroups]

[channels]
switchtype=national
rxwink=300              ; Atlas seems to use long (250ms) winks
usecallerid=yes
hidecallerid=no
callwaiting=yes
usecallingpres=yes
callwaitingcallerid=yes
threewaycalling=yes
transfer=yes
canpark=yes
cancallforward=yes
callreturn=yes
echocancel=yes
echocancelwhenbridged=yes
rxgain=0.0
txgain=0.0
callgroup=1
pickupgroup=1
immediate=no
#include zapata-channels.conf

Under Debian,

sip.conf

This is a sample configuration for VOIP with XS4ALL

;;/etc/asterisk/sip.conf;;
[general]
context=default
externip=setyoureiphere
dtfmmode=inband
localnet=192.168.70.0/24
port=5060
bindaddr=0.0.0.0
disallow=all
allow=alaw
allow=ulaw
registerattempts=0
defaultexpiry=7200
register => 08787XXXXX:PASSWORD@sip.xs4all.nl/08787XXXXX

[xs4all]
type=friend
username=08787XXXXX
fromuser=08787XXXXX
fromdomain=sip.xs4all.nl
secret=PASSWORD
host=sip.xs4all.nl
insecure=invite
context=fromxs4all
canreinvite=no
dtmfmode=inband
disallow=all
allow=alaw
allow=ulaw

DAHDI

From Asterisk version 1.4, the zaptel hardware driver has been renamed to DAHDI witch stands for "Digium Asterisk Hardware Device Interface". For information on the compilation and installation of DAHDI, see here.

Asterisk dialplans - contexts

A dial plan consists of a number of extensions. Each extensions consists of a number of priorities. Extensions are grouped in contexts. For each priority, an application is called.

[context]
exten => id, priority, command

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 will look 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]

extensions.conf

[globals]

[general]
autofallthrough=yes

[default]
include => fromxs4all

[fromxs4all]
exten => 08787XXXXX,1,Dial(DAHDI/2)
exten => 08787XXXXX,n,Hangup()

[outgoing]
exten => _X.,1,Dial(sip/xs4all/${EXTEN},60,r)

[internal]
exten => 6004,1,Dial(sip/6004)
exten => 6003,1,Dial(sip/6003)
exten => 6005,1,Dial(DAHDI/2)
exten => 6006,1,Answer()
exten => 6006,n,Playback(hello-world)
exten => 6006,n,Hangup()

[phones]
include => internal
include => fromxs4all
include => outgoing

Asterisk basic configuration

Contents