Connecting Abilis and Asterisk

Revision History
Revision 5 2007-01-26 LM
Simplified Example 2 with dynamic address. Other minor changes.
Revision 4 2007-01-24 AS
Added /etc/asterisk/extensions.conf context line example.
Revision 3 2007-01-23 LM
Added commands for the examples. Added transcoding delay optimisation and notes related to fax relay.
Revision 2 2007-01-22 LM
Added CTIR examples. General revision.
Revision 1 2007-01-21 AS
Draft Copy

Table of Contents

1. Prerequisites
2. Checklist of parameters
3. Activation of CTIIAX resource in Abilis
3.1. Add CTIIAX resource
3.2. Set proper SRCADD parameter in CTIIAX resource
4. Example 1: Abilis and Asterisk have static IP addresses
5. Example 2: Abilis has static address and Asterisk has dynamic address
6. Configure CTI routings
6.1. Any coder, transcoding disallowed
6.2. Only G.711 on Asterisk, any coder on Cluster, transcoding allowed

Abstract

This document contains instructions for a correct set-up of Abilis CPX and Asterisk interconnection.

1. Prerequisites

  • Abilis CPX 5.7.0 or later.

  • Asterisk 1.2.12 or later.

  • LAN or WAN interconnection between them

  • For WAN interconnection it may be necessary to restrict coder usage to low bit rate coders only

2. Checklist of parameters

Parameters that Abilis operator MUST send to Asterisk operator to allow him to complete the general context and to add the Abilis context in /etc/asterisk/iax.conf file.

Asterisk Context Asterisk Parameter Description Value
general allow Allowed codecs.

In local environment G.711 should be used, in internet environment G.729 is the best choice but licence from Digium costs 10$ for each IAX2 channel.

G.711 is required for IAX FAX.

alaw”, and “G729” if available.
general trunkfreq Frequency for metatrunking bandwidth optimization, in milliseconds. 40
general trunktimestamps Individual miniframe timestamp inside metatrunk frame. yes
abilis type User rights ( to call and be called ). friend
abilis username The username with which Asterisk presents itself to Abilis. Value of USER: parameter in Abilis CPX user table.
abilis secret The password with which Asterisk authenticates to Abilis, and vice versa Abilis authenticates to Asterisk. Value of PASSWORD: and IAX-REG-PASSWORD: parameters in Abilis CPX user table.

For simplicity we use a single user in Asterisk (the context abilis), and this requires that in Abilis the PASSWORD: and IAX-REG-PASSWORD: are set identical.

abilis host The Abilis IP Address or FQDN <ABILIS_IP_ADDRESS> or <ABILIS_FQDN>
abilis trunk Allow metatrunking yes

3. Activation of CTIIAX resource in Abilis

3.1. Add CTIIAX resource

If the CTIIAX resource is not already present in Abilis ( execute d p res:ctiiax to chek it ) you have to add it, otherwise skip this step.

a res:ctiiax

You can view the default CTIIAX port configuration:

[18:55:12] ABILIS_CPX:d p ctiiax

RES:CtiIax - Not Saved (SAVE CONF) --------------------------------------------
       ------------------------------------------------------------------------
       DESCR:IAX2
       LOG:NO         ACT:YES  locport:4569            sesnum:10
       TOS:0-D                 SRCADD:R-ID (000.000.000.000)
       IPSRC:*                 IPSRCLIST:#
       AUTH:MD5                REG-AUTH:MD5            CTIP-TYPE:USER
       LIFETIME:60             REG-LIFETIME:60         ROUTING:EN-BLOC
       RETR-FREQ:400           TRUNK:NO                DIALT:5
       RETR-EXCEED:10000       TRUNK-FREQ:40           T302:15
       RETR-EXCEED-FAST:2000   TRUNK-TS:YES            ROUTE-BY-SD:NO
       PLAY-DTMF:150           CHAN-FREQ:40            PROVIDE-SG:NO
       PLAY-SILENCE:100        MAX-JITTER:500          TRANSFER:IAX
       DETECT-DTMF:40                                  CPO:NO
       DETECT-SILENCE:40                               CPO-STATE:ACCEPT
       NETSTATS:NO                                     CPO-DROP:NO
       HTML-IN:
       HTML-OUT:

Now you have to activate the resource.

s p ctiiax act:yes

By default 10 sessions will be activated, i.e. up to 10 calls can be made between Abilis and Asterisk. If you need different sessions amount set the parameter as you need between 1 and 255.

s p ctiiax sesnum:xxx

Save configuration and reboot.

save conf
warm start

3.2. Set proper SRCADD parameter in CTIIAX resource

If you have an Abilis with only one IP resource and therefore with only one IP address you can skip this step, otherwise you have to choose between:

  • R-ID (router id, the default value)

  • OUT-IP (use the IP address of the IP resource on which the call is sent out)

  • x.x.x.x (one of the IPADD values of the IP resources)

If you have an Abilis with more IP resources and more IP addresses the suggested configuration is OUT-IP.

Once you have set the parameter don't forget to refresh CTIIAX:

init res:ctiiax

4. Example 1: Abilis and Asterisk have static IP addresses

Premise:

  • Abilis has only one IAX2 user, Asterisk.

  • Abilis has the static IP address 192.168.1.254 .

  • Asterisk has the static IP address 192.168.1.100.

  • Abilis has a IAX2 user called asterisk100 with password swordfish.

  • Asterisk has a IAX2 user called abilis.

  • Asterisk provides advanced services like IVR and voice mail, let's say that 10 sessions are needed.

First of all you have to ensure that CTIIAX resource in CPX is running: D P CTIIAX shows the resource configuration and D D CTIIAX shows the current status. If you need, Activation of CTIIAX resource in Abilis will help you to set up CTIIAX resource from scratch.

Now you have to create a IAX2 user representing Asterisk:

a user:asterisk100 password:swordfish iax:yes iax-host:192.168.1.100
s user:asterisk100 iax-maxses-bid:10 iax-number:* iax-trunk:yes iax-reg-user:abilis iax-reg-pass:swordfish

You can show the result in this way (emphasized parameters are the values different from defaults):

[15:45:12] ABILIS_CPX:d user:asterisk100

-------------------------------------------------------------------------------
Parameter:     | Value:
---------------+---------------------------------------------------------------
USER:            asterisk100
PASSWORD:        ********
ENABLED:         YES
IAX:             YES
IAX-HOST:        192.168.1.100
IAX-PORT:        4569
IAX-IP-PERMIT:   *
IAX-MAXSES-BID:  10
IAX-MAXSES-IN:   0
IAX-MAXSES-OUT:  0
IAX-NUMBER:      *
IAX-CG-NUM:      AUTO
IAX-ROUTE-BY-SD: NO
IAX-PROVIDE-SG:  NO
IAX-CONTEXT:
IAX-TYPE:        FRIEND
IAX-AUTH:        SYS
IAX-NETSTATS:    SYS
IAX-TRUNK:       YES
IAX-TRUNK-FREQ:  SYS
IAX-CHAN-FREQ:   SYS
IAX-CPO:         SYS
IAX-CPO-STATE:   SYS
IAX-CPO-DROP:    SYS
IAX-TRANSFER:    SYS
IAX-REG:         NO
IAX-REG-USER:    abilis
IAX-REG-PASS:    ********
IAX-REG-AUTH:    SYS
IAX-HTML-IN:     SYS
IAX-HTML-OUT:    SYS
-------------------------------------------------------------------------------

The CTIIAX table, used to route calls toward IAX users, gets automatically populated with a unique route because you set IAX-NUMBER:* :

[18:55:09] ABILIS_CPX:d ctiiax

- Not Saved (SAVE CONF) -------------------------------------------------------
Total:1         Connected:1         Static:0
CDI:                  USERNAME:                         P:
----------------------------------------------------------
*                     asterisk100                       C

The asterisk configuration file /etc/asterisk/extensions.conf must contain a context for managing the calls. For our convenience we use here the name from-abilis :

[from-abilis]
exten => 123,1,Answer()           ; answer, play, hangup
exten => 123,2,Playback(welcome)
exten => 123,3,Hangup

exten => 222,1,Answer()           ; answer, play, forward call to another number (999)
exten => 222,2,Playback(welcome)
exten => 222,3,Dial(IAX2/abilis/999)

The asterisk configuration file /etc/asterisk/iax.conf must be modified to include the following lines in the general context :

[general]
disallow=all           ; first disallow every coder
allow=alaw             ; then enable only G.711 A-law
trunkfreq=40           ; trunkfrequency 40 msec
trunktimestamps=yes    ; individual miniframes timestamp

and the following lines in the abilis context :

[abilis]
type=friend
username=asterisk100    ;the same of USER: in Abilis
secret=swordfish        ;the same of PASSWORD: and IAX-REG-PASS: in Abilis
host=192.168.1.254      ;Abilis static address
context=from-abilis     ;name of the desired context from extensions.conf
trunk=yes               ;enable trunking

Of course remember to reload asterisk service.

Abilis and Asterisk interconnection is now correctly configured.

5. Example 2: Abilis has static address and Asterisk has dynamic address

Premise:

  • Read and learn Example 1: Abilis and Asterisk have static IP addresses.

  • Abilis has only one IAX2 user, Asterisk.

  • Abilis has the static IP address 192.168.1.254.

  • Asterisk has dynamic IP address.

  • Abilis has a IAX2 user called asterisk100 with password swordfish.

  • Asterisk has a IAX2 user called abilis.

  • Asterisk provides advanced services like IVR and voice mail, let's say that 10 sessions are needed.

The steps are the same as in the Example 1: Abilis and Asterisk have static IP addresses , there is just one parameter different in Abilis and one directive to add in Asterisk configuration. See below.

Do not set Asterisk IP address when adding Asterisk user

a user:asterisk100 password:swordfish iax:yes

or set it to DYNAMIC if the user is already present

s user:asterisk100 iax-host:dynamic

The Abilis user configuration differs from Example 1: Abilis and Asterisk have static IP addresses by the fields emphasized below :

[15:45:12] ABILIS_CPX:d user:asterisk100

-------------------------------------------------------------------------------
Parameter:     | Value:
---------------+---------------------------------------------------------------
USER:            asterisk100
PASSWORD:        ********
ENABLED:         YES
IAX:             YES
IAX-HOST:        DYNAMIC
IAX-PORT:        4569(DYNAMIC)
...
-------------------------------------------------------------------------------

The asterisk configuration file /etc/asterisk/iax.conf must be modified to include in the general context the register directive:

[general]
disallow=all           ; first disallow every coder
allow=alaw             ; then enable only G.711 A-law
trunkfreq=40           ; trunk frequency 40 msec
trunktimestamps=yes    ; individual miniframes timestamp
register=>asterisk100:swordfish@192.168.1.254  ;activate registration TO abilis

Of course remember to reload asterisk service.

Abilis and Asterisk interconnection is now correctly configured.

6. Configure CTI routings

In order to route calls to and from CTIIAX it is necessary to add the appropriate routings in the CTIR table; in the following lines we will shortly describe the routing types and make few simple examples.

The routing types involved with CTIIAX are:

Type Description Transcoding supported
ItoI Voice to IAX NO
CtoI Cluster to IAX YES
HtoI H323 to IAX YES
DtoI Disa to IAX YES
ItoV IAX to Voice NO
ItoC IAX to Cluster YES
ItoH IAX to H323 YES
ItoD IAX to Disa YES
ItoI IAX to IAX YES
[Note] Note

Transcoding is allowed when parameter CODERSOUT <> *.

6.1. Any coder, transcoding disallowed

In this example every call arriving from ISDN/POTS/GSM/CLUSTER is routed to IAX users, and every call arriving from IAX users is first sent to cluster “test”, and in case of failure (NEXT:LIMITED) it is attempted on ISDN/POTS/GSM group G1.

In this situation any coder with maximal speed 6400 (the default for SP:) is allowed, but transcoding is disallowed, which means that the same coder must be used in Asterisk and in the far Abilis where a CtoV or CtoI routing will terminate the call to an ISDN/POTS/GSM port or to another IAX user.

Cluster test is only useful to the example, any cluster can be used.

a cticl id:test

a ctir pr:0 type:vtoi poi:* cdi:*
a ctir pr:1 type:ctoi sr:* cdi:*
a ctir pr:2 type:itoc ds:test cdi:* next:limited
a ctir pr:3 type:itov poo:g1 cdi:*

init ctir
[Tip] Tip

To allow G.729A you have to set SP:8000 in every routing.

[19:50:06] ABILIS_CPX:d ctir

- Not Saved (SAVE CONF) -------------------------------------------------------

---+----+---------+--------+--------+--------------------+---------------------
PR |TYPE|NEXT     |POI/SR  |POO/DS  |CDI                 |CDO
   |TON |SP-SC-DJ-MJ                |CGI                 |CGO
   |T301|IG-OG-SG-DH-DL             |SDI                 |SDO
   |    |FMRELAY-FAXSP-MODSP-FMLEVEL|SGI                 |SGO
   |    |CODERS
   |    |SPOUT-SCOUT-DJOUT-MJOUT
   |    |CODERSOUT
   |    |TI1 .. TI5
-------------------------------------------------------------------------------
0   VtoI NO        *        CtiIax   *                    *
-------------------------------------------------------------------------------
1   CtoI NO        *        CtiIax   *                    *
-------------------------------------------------------------------------------
2   ItoC LIMITED   CtiIax   test     *                    *
-------------------------------------------------------------------------------
3   ItoV NO        CtiIax   G1       *                    *
-------------------------------------------------------------------------------

6.2. Only G.711 on Asterisk, any coder on Cluster, transcoding allowed

In this example every call arriving from ISDN/POTS/GSM/CLUSTER is routed to IAX users, and every call arriving from IAX users is first sent to cluster “test”, and in case of failure (NEXT:LIMITED) it is attempted on ISDN/POTS/GSM group G1.

In this situation only G.711 A-law or u-law is possible between Asterisk and Abilis, but since transcoding is enabled by CODERSOUT <> * the ItoC and CtoI routings will negotiate for the “C” side any coder with maximal speed up 6400 bps.

Cluster test is only useful to the example, any cluster can be used.

a cticl id:test

a ctir pr:0 type:vtoi poi:* cdi:* sp:64000
a ctir pr:1 type:ctoi sr:* cdi:* spout:64000 codersout:G.711
a ctir pr:2 type:itoc ds:test cdi:* next:limited sp:64000 coders:g.711 spout:6400 codersout:*,sys
a ctir pr:3 type:itov poo:g1 cdi:* sp:64000

init ctir
[Tip] Tip

To allow G.729A you have to set SP:8000 in CtoI PR:1 and SPOUT:8000 in ItoC PR:2.

[13:20:31] ABILIS_CPX:d ctir

- Not Saved (SAVE CONF) -------------------------------------------------------

---+----+---------+--------+--------+--------------------+---------------------
PR |TYPE|NEXT     |POI/SR  |POO/DS  |CDI                 |CDO
   |TON |SP-SC-DJ-MJ                |CGI                 |CGO
   |T301|IG-OG-SG-DH-DL             |SDI                 |SDO
   |    |FMRELAY-FAXSP-MODSP-FMLEVEL|SGI                 |SGO
   |    |CODERS
   |    |SPOUT-SCOUT-DJOUT-MJOUT
   |    |CODERSOUT
   |    |TI1 .. TI5
-------------------------------------------------------------------------------
0   VtoI NO        *        CtiIax   *                    *
    Sys  64000 Sys   Sys   Sys       *                    *
-------------------------------------------------------------------------------
1   CtoI NO        *        CtiIax   *                    *
    Sys  6400  Sys   *     *         *                    *
    Dft                              *                    *
         Sys   AUTO  AUTO  Sys       *                    *
         *
         64000 *     *     *
         G.711
-------------------------------------------------------------------------------
2   ItoC LIMITED   CtiIax   test     *                    *
    Sys  64000 Sys   Sys   Sys       *                    *
    Dft                              *                    *
         Sys   AUTO  AUTO  Sys       *                    *
         G.711
         6400  *     *     *
         *,Sys
-------------------------------------------------------------------------------
3   ItoV NO        CtiIax   G1       *                    *
    Sys  64000 Sys   Sys   Sys       *                    *
-------------------------------------------------------------------------------

6.2.1. Transcoding optimisation

When the Abilis-Asterisk interconnection occurs via local LAN, i.e. with high speed, minimal delays, minimal jitter, it is possible to optimise the transcoding so that the Asterisk side uses minimal jitter, therefore minimal delays, while the WAN side uses the values optimal for WAN link.

This is obtained by properly setting DJ, MJ, DJOUT, MJOUT.

s ctir pr:1 djout:0 mjout:80
s ctir pr:2 dj:0 mj:80 djout:sys mjout:sys

init ctir
[Tip] Tip

DJ and MJ in pr:1 as well as DJOUT and MJOUT in pr:2 may assume other values appropriate for the WAN link or specifically required by calls matching the routing. Please refer to online help (d ctir pr: ?) and to Abilis tutorial and technical reference.

6.2.2. Fax

When transcoding takes place in IoC and CtoI, with G.711 toward Asterisk, something interesting happens: on the WAN it is possible to use FAX relay!

It means that if your asterisk is properly set-up to manage faxes via G.711 coder, you can exchange FAX with following characteristics:

  • Use G.711, 64 kbps plus IP overhead on the Abilis-Asterisk interconnection

  • Use G3 Fax relay, 2400/4800/9600/14400 kbps plus IP overhead on the WAN link

If you want to forcedly disable fax relay you have just to set FMRELAY:NO in the desired routing, e.g.

s ctir pr:0 fmrelay:no
s ctir pr:1 fmrelay:no
s ctir pr:2 fmrelay:no
s ctir pr:3 fmrelay:no