16. Configuring an Asterisk server¶

If you want to set up Calculate Directory Server as an IP dial system, you should use Asterisk, a software implementation of a telephone PBX released under the GPL licence, that supports various VoIP protocols. To configure Asterisk, you will need to edit files /etc/asterisk.

This article describes how to configure a regular Asterisk server.

Problem specification¶

Say you have one running Asterisk server and you need to set up another one for a new office.
Two analog lines are provided for it.
One line is used for telephone calls and the other one is for faxes.
The interface card installed on the server will be Digium AEX804E; it uses PCI-Express motherboard interface and has 8 ports, with a 4-FXO ports module and an echo cancellation module.
The existing server is in Saint-Petersburg, the new one will be located in Moscow.
The two servers must be connected and have an intergrated internal phone numbering scheme.
The Moscow server will comply to the following procedure when receiving a call on the main line:
A call is received → the system plays the greeting and suggests adding an extension number → if the extension is not added, the call will be passed on to a secretary in Saint-Petersburg → if the secretary does not answer, the call will be passed on to users of the Moscow server → if users in Moscow do not answer, the call will be passed on the to users in Saint-Petersburg.
Calls going to the fax line must be addressed to the fax receiver.
To be able to fax through SIP, you will need an FXS gateway, e.i. Linksys SPA2102.
Incoming calls must go to the first available line. If the main phone line is busy, it goes to the fax line.
Calls from a Moscow server to Saint-Petersburg (area code 812) must go through the server in Saint-Petersburg.
All the settings below were tested on and apply to the following versions of packages:
- net-misc/asterisk-1.6.2.17.3
- net-misc/dahdi-2.4.1
- net-misc/dahdi-tools-2.4.1

Install the Asterisk server¶

Before you start configuring, you must install the Asterisk package and the accompanying packages onto your Calculate Directory Server.

Configuring USE flags for the new packages¶

Create /etc/portage/package.use/asterisk; this file will contain all USE flags required by your packages.

net-misc/asterisk alsa caps iconv jabber ldap samples speex ssl vorbis dahdi span
net-misc/asterisk-core-sounds alaw g722 g729 gsm siren14 siren7 sln16 ulaw wav
net-misc/asterisk-extra-sounds alaw g722 g729 gsm siren14 siren7 sln16 ulaw wav
net-misc/asterisk-moh-opsound alaw g722 g729 gsm siren14 siren7 sln16 ulaw wav
media-libs/speex sse ogg

For the net-misc/asterisk package, add the flags dahdi (for phones), span (for faxes) and vorbis (optional; supports the Vorbis codec). For other packages, add support for all available codecs.

Installing the required packages¶

Now, when you have specified the USE flags, install the packages.
Please execute:

emerge -a asterisk dahdi dahdi-tools

The following package list will be returned:

These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild  N     ] net-libs/libpri-1.4.11.4
[ebuild  N     ] sys-libs/slang-2.2.2  USE="pcre png readline zlib -cjk" 
[ebuild  N     ] dev-libs/iksemel-1.3  USE="-gnutls" 
[ebuild  N     ] media-libs/spandsp-0.0.6_pre12-r1  USE="mmx sse sse2 sse3 -doc (-fixed-point) -static-libs
[ebuild  N     ] net-misc/dahdi-2.4.1  USE="flash" 
[ebuild  N     ] dev-libs/newt-0.52.12  USE="gpm nls -tcl" 
[ebuild  N     ] net-misc/dahdi-tools-2.4.1  USE="-ppp" 
[ebuild  N     ] net-misc/asterisk-1.6.2.17.3  USE="alsa caps dahdi iconv jabber ldap samples span speex ssl vorbis -doc -freetds -lua -newt -oss -postgres -radius -snmp -sqlite" 
[ebuild  N     ] net-misc/asterisk-extra-sounds-1.4.11  USE="alaw g722 g729 gsm siren14 siren7 sln16 ulaw wav" LINGUAS="fr" 
[ebuild  N     ] net-misc/asterisk-moh-opsound-2.03  USE="alaw g722 g729 gsm siren14 siren7 sln16 ulaw wav"[ebuild  N     ] net-misc/asterisk-core-sounds-1.4.19  USE="alaw g722 g729 gsm siren14 siren7 sln16 ulaw wav" LINGUAS="fr" 

Would you like to merge these packages? [Yes/No]

Say yes and wait until the packages are merged. It is now time for setup.

Basic setup of SIP¶

The goal is set; let us configure our new server.

Creating accounts¶

Begin by adding several local SIP users. To do this, edit the file /etc/asterisk/sip.conf.

Add a template for the SIP phones' common settings:

[office-phones](!) 
type=friend 
context=outcoming-sip 
secret=xxxxxxxx 
host=dynamic 
nat=no 
qualify=yes 
canreinvite=no 
callgroup=1 
pickupgroup=1 
dtmfmode=auto 
disallow=all 
allow=g722

Let us see this code fragment. The template is set with an exclamation point in brackets put near the section name [phones](!)

type — type of connection (peer — outcoming calls only, user — incoming calls, friend — both incoming and outcoming calls)
context — context in /etc/asterisk/extension.conf that will be applied when a number is dialed
secret — password for a SIP phone
host — phone host name (dynamic host name)
nat — network address translation
qualify — checking the phone
canreinvite — direct access to another phone number, avoiding Asterisk
callgroup — call group number
pickupgroup — pick-up group number
dtmfmode=auto — dtmf mode (auto|inband|info|rfc2833)
disallow=all — disallows all codecs
allow=g722 — allows using codec g722

Then add sections for every phone set:

[001](office-phones)
callerid="Manager 1" <800>
[002](office-phones)
callerid="Manager 2" <801>
[003](office-phones)
t38pt_udptl=yes
callerid="Msk Fax" <802>
disallow=all
allow=alaw
allow=ulaw

For faxing, you will have to reset the supported codecs, since receiving the fax signal requires the codec g711 (alaw and ulaw), while t38pt_udptl=yes allows using the t.38 protocol for sending faxes.

Basic setup of the dialing scheme¶

Your phones and your FXS gateway can be now registered on the server, but they cannot yet actually make calls. To mend this, you will have to add an outcoming SIP to /etc/asterisk/extensions.conf

Configuring internal numbers¶

For your convenience, put all local numbers in one section:

[msk-local-phones]
exten => 800,1,Log(NOTICE,"800 ACCOUNT")
exten => 800,2,Dial(SIP/001,120,Tt)
exten => 801,1,Log(NOTICE,"801 ACCOUNT")
exten => 801,2,Dial(SIP/002,120,Tt)
exten => 802,1,Log(NOTICE,"802 ACCOUNT")
exten => 802,2,Dial(SIP/003,120,Tt)

Make a hang-up section, too:

[handup-sip]
exten => _X!,1,HangUp()

Then add our sections in [outcoming-sip]:

[outcoming-sip]
include => msk-local-phones
include => handup-sip

Now, when you have restarted Asterisk, you will be able to make calls inside your server zone to numbers 800, 801 and 802 respectively. Launch the console manager of your Asterisk server by running asterisk -r and reload; this will make Asterisk re-read all settings. Or you can also re-read them one by one, by running sip reload to restart SIP settings and dialplan reload to restart the dialing scheme.

If you execute sip show peers, you will see the list of available users on the server, which of them are registered now and what their IPs are.

Configure the connections of the two servers and calls passed between them¶

At this stage, your users in Moscow are already able to call each other, but you also have users on the Saint-Petersburg server they should be able to join as well. To allow this, you have to set up a connection between your two Asterisk servers.

Setting up a connection between two Asterisk servers through the SIP protocol¶

On the Moscow server, append the following lines to /etc/asterisk/sip.conf:

in the [general] section:

register => msk_asterisk:XXXXXXXXX@192.168.0.30/spb_asterisk

and make a new section at the end of the file:

[spb_asterisk]
type=friend
secret=XXXXXXXXX
context=spb_incoming
host=dynamic
qualify=yes
dtmfmode=rfc2833
disallow=all
allow=ulaw

The procedure that has to be followed on the Saint-Petersburg server is very similar:

in [general]:

register => spb_asterisk:XXXXXXXXX@192.168.1.25/msk_asterisk

and making a new section at the end of the file:

[msk_asterisk]
type=friend
secret=XXXXXXXXX
context=msk_incoming
host=dynamic
qualify=yes
tmfmode=rfc2833
disallow=all
allow=ulaw

Let me explain what it all means.

register => msk_asterisk:XXXXXXXXX@192.168.0.30/spb_asterisk

This line tells your Moscow server to register on the server in Saint-Petersburg, 192.168.0.30/spb_asterisk, with login msk_asterisk and password XXXXXXXXX.

These were actually specified when you created the section [msk_asterisk] on your server in Saint-Petersburg. Accordingly, this server will register on the Moscow server, 192.168.1.25/msk_asterisk with the login and password specified in the [spb_asterisk] section of the Moscow server configuration.

Configuring the dialing scheme for server connection¶

Now the two servers are connected; the dialing scheme must be defined to allow Moscow users to make calls to Saint-Petersburg and vice versa.

To do this, create the [spb-local-phones] section in the file /etc/asterisk/extensions.conf on your Moscow server; there you will define your users in Saint-Petersburg:

[spb-local-phones]
exten => 500,1,Dial(SIP/spb_asterisk/500,120,Tt)
exten => 501,1,Dial(SIP/spb_asterisk/501,120,Tt)
(... и т. д.)

Note the difference from defining local users.

In you had exten => 800,2,Dial(SIP/001,120,Tt) for local users - that is, you called the user with login 001 by dialing 800, now you have exten => 500,1,Dial(SIP/spb_asterisk/500,120,Tt) - i.e., you are calling the user with number 500 that is on the spb_asterisk server.

In the existing section [outcoming-sip], add a new new section with local numbers of the Saint-Petersburg server:

[outcoming-sip]
include => msk-local-phones
include => spb-local-phones
include => handup-sip

Create the [spb_incoming] section to handle calls coming from Saint-Petersburg:

[spb_incoming]
include => msk-local-phones
include => handup-sip

In Saint-Petersburg, proceed by analogy:

[msk-local-phones]
exten => 800,1,Dial(SIP/msk_asterisk/800,120,Tt)
exten => 801,1,Dial(SIP/msk_asterisk/801,120,Tt)
exten => 802,1,Dial(SIP/msk_asterisk/802,120,Tt)

[outcoming-sip]
include => msk-local-phones
include => spb-local-phones
include => handup-sip

[msk_incoming]
include => spb-local-phones
include => handup-sip

Restart the SIP settings and the dialing scheme. Now all our users in Moscow as well as in Saint-Petersburg (both servers running Calculate Directory Server with Asterisk) can join each other.

Set Digium AEX804E and configure the dialing scheme¶

OK, now your users in Moscow can call each other, can call their colleagues in Saint-Petersburg, but they still cannot call standard numbers. You must configure your interface card to allow them to.

Setting up the system to work with the interface card¶

For the interface card to be operational, you will need the packages net-misc/dahdi and net-misc/dahdi-tools.

Once these packages are installed, comment the line containing the card module in /etc/modprobe.d/dahdi.blacklist.conf, so that the module is launched by the system.

It should look like this:

# blacklist all the drivers by default in order to ensure that
# /etc/init.d/dahdi installs them in the correct order so that the spans are
# ordered consistently.

blacklist wct4xxp
blacklist wcte12xp
blacklist wct1xxp
blacklist wcte11xp
#blacklist wctdm24xxp
blacklist wcfxo
blacklist wctdm
blacklist wctc4xxp
blacklist wcb4xxp
blacklist wcopenpci
blacklist zaphfc

In your case, you will need the module wctdm24xxp: this module is used by the cards TDM2400P/AEX2400, TDM800P/AEX800 and TDM410P/AEX410.

Now configure channels on your card. To do this, you will edit the /etc/dahdi/system.conf file.

Your card has a module trunk including 4 FXO ports, with channels numbered from 5 to 8 (if you look on your card, these will be 4 left ports. Channels are numbered from right to left; consequently, the eighth channel is at the extreme left and the first channel is at the extreme right.)

Append the following to the configuration file:

fxsks=5
fxsks=6
fxsks=7
fxsks=8

The lines above mean that channels from 5 to 8 use fxsks signaling.

Explaining FXO and FXS concepts¶

Let us take a break and try to understand what are FXO and FXS and which signaling belongs where.

An FXO (Foreign eXchange Office) port receives the line from the exchange; that is, it acts as a terminal device (a phone set) and uses fxsks signaling.

An FXS (Foreign eXchange Station) port generates the ready signal and the line voltage; that is, it acts as an exchange and uses fxoks signaling.

Thus the ports have names which correspond to the nature of their connections, and use signaling that is appropriate in their case.

Setting up FXO channels on your Asterisk server¶

Launch the dahdi daemon with /etc/init.d/dahdi start and enter dahdi_cfg -vv to see if it works as expected.

The program will return:

DAHDI Tools Version - 2.4.1

DAHDI Version: 2.4.1
Echo Canceller(s):
Configuration
======================

Channel map:

Channel 05: FXS Kewlstart (Default) (Echo Canceler: none) (Slaves: 05)
Channel 06: FXS Kewlstart (Default) (Echo Canceler: none) (Slaves: 06)
Channel 07: FXS Kewlstart (Default) (Echo Canceler: none) (Slaves: 07)
Channel 08: FXS Kewlstart (Default) (Echo Canceler: none) (Slaves: 08)

4 channels to configure.

etting echocan for channel 5 to none
Setting echocan for channel 6 to none
Setting echocan for channel 7 to none
Setting echocan for channel 8 to none

Now you have to configure channels right on the Asterisk server. To do so, edit the /etc/asterisk/chan_dahdi.conf file.

It it the [channels] section, namely, that needs editing:

[channels]
usecallerid=yes
hidecallerid=no
callwaiting=no
threewaycalling=yes
transfer=yes
echocancel=yes
echotraining=yes
signaling=fxs_ks
context=incoming_fxo
group=1
channel=>7
context=incoming_fxo_fax
group=1
channel=>8

The available options are:

usecallerid=yes — enables passing CallerIDs
hidecallerid=no — tells that CallerIDs will be passed for outcoming calls
callwaiting=no — disables deferred calls
threewaycalling=yes — enables connecting a third user
transfer=yes — enables call redirections
echocancel=yes — enables echo cancellation
echotraining=yes — sets the echotraining mode on, to accelerate echo cancellation setup
signaling=fxs_ks — tells to use fxs signaling
group=1 — channel group

The first context defines how calls are handled for channel 7; the second context does the same for channel 8. The main line is on channel 7, while channel 8 is used for faxing. The group=1 parameter, set for both channels, puts them together in one group. This will permit you to make calls through the first available line.

Configuring the dialing scheme for receiving calls¶

You can now configure the dialing scheme for receiving calls on your lines.
Create the context [incoming_fxo] in /etc/asterisk/extensions.conf:

[incoming_fxo]
exten => s,1,Answer()
exten => s,n,Ringing()
exten => s,n,Queue(welcome,n,,,12)
exten => s,n,GotoIfTime(19:15-8:00,*,*,*?allRing:default)
exten => s,n(allRing),NoOp()
exten => s,n,Queue(allNoFaxes,r,,,600)
exten => s,n,HangUp()
exten => s,n(default),NoOp()
exten => s,n,Queue(secretary,r,,,6)
exten => s,n,Queue(msk-manager1,r,,,10)
exten => s,n,Queue(spb-managers,r,,,600)
include => handup-sip

Here you are answering the call and sending it to the relevant queue.
Queue(welcome,n,,,12) send the call to the queue welcome for 12 seconds; the n parameter allows to dial while the call is in the queue and the Music On Hold (MOH) is playing. In the welcome queue, on the other had, the greeting message will be played, as we will describe later.
GotoIfTime(19:15-8:00,*,*,*?allRing:default) verifies the condition: if it is from 7.15 p.m. to 8.00 a.m., to to the allRing tag, else to the default tag. All phone sets will thus ring when the majority of staff are not in office, and in working hours the normal order is respected. Then, under the default tag, your call will go to the secretary for 6 seconds, then, for 10 seconds, to managers in Moscow and, finally, for 600 seconds, to managers in Saint-Petersburg. The r parameter in a Queue() call tells the program to play ringing instead of MOH.

You will also need a context for the second line; create the section [incoming_fxo_fax] in /etc/asterisk/extensions.conf:

[incoming_fxo_fax]
exten => s,1,Answer()
exten => s,2,NoOp()
exten => s,n,Ringing()
exten => s,n,Queue(msk-faxes,r,,,600)
include => handup-sip

On this line, you will be just sending the call to fax for 600 seconds.

Creating call queues¶

Let us see how queues are described. This is done in the /etc/asterisk/queues.conf file:

[welcome]
strategy = ringall
musicclass=welcome
context=all-local-sip

[secretary]
strategy = ringall
musicclass=default
context=all-local-sip
; Secretary
member => SIP/spb_asterisk/550,1

[spb-managers]
strategy = ringall
musicclass=default
context=all-local-sip
; Managers
member => SIP/spb_asterisk/500,1
member => SIP/spb_asterisk/501,1
; (… и т. д.)

[msk-faxes]
strategy = ringall
musicclass=default
context=all-local-sip
; Moscow Fax
member => SIP/002,1

[msk-manager1]
strategy = ringall
musicclass=default
context=all-local-sip
; Moscow Managers
member => SIP/001,1

The main parameters used to described queues are:

strategy — strategy of handling incoming calls; it can take the following values:
- ringall — all available members will be called, until anyone of them answers (is set by default);
- leastrecent — the least recent member will be called;
- fewestcalls — the member who was called the less will be called;
- random — an available member will be chosen randomly;
- rrmemory — a recursive call with memory; the last queue member will be remembered;
musicclass — sets the music or the message to be played while waiting in this queue (to be specified in /etc/asterisk/musiconhold.conf);
context — sets the context that will handle calling the number while in the queue;
member — sets the queue members who will handle the call. A record will be created for each member.

To handle extensions in the welcome queue, you have specified the context [all-local-sip]; it must contain all local numbers in Moscow and in Saint-Petersburg. A record must be done accordingly in /etc/asterisk/extensions.conf:

[all-local-sip]
include => msk-local-sip
include => spb-local-sip
include => handup-sip

Calls will be queued and handled as described below:
The function Queue(welcome,n,,,12) in the dialing scheme sends the incoming call to be handled in the welcome queue. During 12 seconds, the person who called will hear the greeting message and, since you have specified the n parameter, will be able to dial an extension number that will be handled by the all-local-sip context. When 12 seconds have elapsed and if no extension has been dialed, the call will be discarded from the queue and handled according to the dialing scheme.

When the function Queue(msk-manager1,r,,,10) is called, the call will be handled for 10 seconds by the queue msk-manager1. Since you have specified the r parameter, the person who is calling will hear buzzing while they are waiting. Meanwhile, the call will be handled according to the strategy you specified - in this case, ringall (i.e. the specified queued members will be called). If any member in the queue takes the phone, the connection is established. Otherwise, if nobody takes the phone within 10 seconds, the call will be handled according to the dialing scheme.

Customizing the Music On Hold (MOH) message¶

OK, incoming calls on your standard lines are handled and the greeting message is played ( the_welcome_ class being specified for the queue welcome); let us see how it is defined. MOH is described in /etc/asterisk/musiconhold.conf.

When installing Asterisk, this file contains this:

[general]

[default]
mode=files
directory=moh

You will need to append the following section to it:

[welcome]
mode=files
sort=alpha
directory=/etc/asterisk/moh1

By this record, you tell the Asterisk server to play files from the directory /etc/asterisk/moh1 by alphabetic order. The recorded message is put in this directory. To decrease server load, you should first convert the message with ffmpeg@ (the package media-video/ffmpeg is pre-installed in Calculate Linux Desktop) to the most commonly used codecs: _alaw, ulaw, g722, g729, gsm and in Asterisk Native SLN, for Asterisk to be able to convert immediately.

For instance, to convert to Native SLN with ffmpeg, execute:

ffmpeg -i "[input file]" -ar 8000 -ac 1 -acodec pcm_s16le -f s16le "[output file].sln"

To convert the existing mp3 files to mono wav and ulaw pcm, enter:

for f in `ls *.mp3` ; do FILE=$(basename $f .mp3) ; ffmpeg -i $FILE.mp3 -ar 8000 -ac 1 -ab 64 $FILE.wav -ar 8000 -ac 1 -ab 64 -f mulaw $FILE.pcm -map 0:0 -map 0:0 ; done

Configuring the dialing scheme for incoming calls¶

All you have to do now is to configure incoming calls bound for standard numbers. Create the [city-calls] section in /etc/asterisk/extensions.conf, containing:

[city-calls]
exten => _98812XXXXXXX,1,Dial(SIP/spb_asterisk/${EXTEN})
exten => _98812XXXXXXX,2,Congestion
exten => _9XXXXXXX,1,Dial(DAHDI/g1/8495${EXTEN:1})
exten => _9XXXXXXX,2,Congestion
exten => _98.,1,Dial(DAHDI/g1/${EXTEN:1})
exten => _98.,2,Congestion

Including it in the [outcoming-sip] section:

[outcoming-sip]
include => local-sip
include => spb-local-sip
include => city-calls
include => handup-sip

That is, whenever a number in Saint-Petersburg (area code 812) is called, the call will be sent to the spb_asterisk server and handled by it. When there is a call to a standard number (7 digits), it will be extended to 10 digits, including the area code (here, 8495 which is the code for Moscow, where your server is located), while complete 10-digit numbers are accepted as they are.

In the Dial(DAHDI/g1/${EXTEN:1} command:

DAHDI — indicates you make calls with an FXO card
g1 — channel group 1 (you specified this when configuring FXO channels); the call is made through the group so that, if the main line is busy, the call goes to the fax line;
${EXTEN} and ${EXTEN:1} — the dialed number. The complete syntax is ${EXTEN:x:y}, where x is the original state and y is the number of the returned digits.

Conclusion¶

The Asterisk server in thus set its basic configuration, in keeping with your needs. However, those are only main settings, that allow issuing and receiving calls. The Asterisk server provides unlimited telephony solutions for configuring and running an office IP-PBX. We hope that this article helped you understand how Asterisk works; now you can devise your own configuration.