Ce document est basé sur la version de développement (Asterisk SVN-trunk-r30630M futur 1.4) d'Asterisk passé en 1.4-beta en octobre 2006.

Bien que beaucoup de précautions aient été prise lors de la préparation de ce document, il est plus que possible que des erreurs, omissions, incorrections y soit décelés. Il y a certainement un grand nombre de fautes de français, alors corrigeons tous ensemble s'il vous plait.

TableOfContents

Introduction

La première chose que j'ai apprise en écrivant ce guide est que définir une infrastructure aussi versatile qu'Asterisk peut être un exercice périlleux.  Subitement, j'ai réalisé ce que voulait vraiment dire l'angoisse de la page blanche. 

Les télécommunications, comme disait Mark Spencer ont été  l'une des contrés les moins explorés dans le monde du libre, aussi peu que ne le sont les techniques de protection contre la copie dans ce monde. Asterisk est l'une des première expérience retentissante pour combler ce vide si confortable pour cette vieille grosse industrie léthargique rompue à la tâche de la livraison de PC cadencés à 700Mhz  embarquant une version de VxWorks vieille de 15 ans et Windows NT 4 pour pas moins de 15.000€ pour faire office de Commutateur.

Asterisk est une plat-forme libre et flexible constituant un point de convergence de diverses technologies autour de la téléphonie.

Matériel

Les fournisseurs de matériels fonctionnant avec Asterisk sont très nombreux, nous ne citeront ici que les plus populaires. Vous trouverez pléthores d'informations sur [http://www.voip-info.org/wiki/view/Asterisk+hardware http://www.voip-info.org/wiki/view/Asterisk+hardware] et la liste ne cesse de croître tous les jours.

Distribution GNU/Linux et Serveurs de Régression

Il faut noter que Digium Inc. effectue des tests de Régression pour la version « Asterisk Business Edition » et les distributions testée avec « Asterisk Business Edition » sont:

• RedHat Enterprise 3 (ES)

• Fedora Core 3

Les serveurs utilisés à ce propos sont:

• Dell Poweredge 2850
• HP Proliant DL360

Téléphonie

Dans cette section nous parlons de cartes TDM numériques et analogiques ainsi que de quelques terminaux (Adaptateurs ATA et postes IP).

Digium Inc.

Cartes numériques zaptel-compatible

• TE405P et TE410P: Cartes T1/E1 de quatre ports supportant les technologies voix et données sur T1 et E1 avec une configuration de port indépendante. Il s'agit de cartes pour des slots 5-vols et 3,3 volts respectivement.
• TE407P et TE412P: Cartes T1/E1 de quatre ports supportant les technologies voix et données sur T1 et E1 avec une configuration de port indépendante. Il s'agit de cartes pour des slots 5-vols et 3,3 volts respectivement. Elles disposent en plus, d'un module matériel de suppression d'écho
• TE205P et TE210P: Cartes T1/E1 de deux ports supportant les technologies voix et données sur T1 et E1 avec une configuration de port indépendante. Il s'agit de cartes pour des slots 5-vols et 3,3 volts respectivement.
• TE207P et TE212P: Cartes T1/E1 de deux ports supportant les technologies voix et données sur T1 et E1 avec une configuration de port indépendante. Il s'agit de cartes pour des slots 5-volts et 3,3 volts respectivement avec module de suppression d'echo.
• TE110P: Carte T1/E1 d'un port avec les mêmes fonctionnalités que les cartes de la série TE ci-dessus.
• B410P et B405P: Cartes de quatre ports RNIS accès de base.

Cartes analogiques zaptel-compatible

• TDM400P: Carte supportant jusqu'à quatre ports FXS ou FXO via des modules permettant de se connecter aux téléphones analogues.
• TDM2400P: Carte supportant jusqu'à 24 ports FXS ou FXO en groupe de 4 pour un total de six modules par carte.
• Module FXS: Module vert FXS utilisé avec la TDM400P
• Module FXO: Module rouge utilisé avec la TDM400P

Adaptateurs de Téléphones Analogiques (ATA)

• IAXy S101I: Adaptateur de téléphone analogique utilisant le protocole IAX. Il existe en trois variante avec des alimentation (Européenne, Nord-Américaine et Anglaise).

Notons que le choix de ce type de matériel peut se révéler périlleux. Il peut être bon de recourir à la revue de la communauté avant d'acquérir du nouveau matériel (e.g. lisez les commentaires utilisateurs sur http://www.asteriskguru.com/tutorials/st_302_ip_phone_hardphone.html).

Autres Fournisseurs matériel

Sangoma

Les cartes produites par Sangoma sont devenu très populaires dans la communauté Asterisk. Ils produisent des cartes A101, A102, A104 et A104d qui sont respectivement des cartes T1/E1 à un, deux et quatre ports. La A104d est une carte quatre port avec un module de suppression d'écho à 128ms. Des cartes à 8 ports T1/E1 haute densité sont également disponible (http://www.sangoma.com/press/corporate/2006_04_05_A108_Card). De plus ils fournissent les cartes A200 et A200d qui sont des cartes analogiques extensibles FXS/FXO de 2 à 24 ports.

Les pilotes de ces cartes sont disponibles sur le site de Sangoma ([http://wiki.sangoma.com/ http://wiki.sangoma.com/])

Xorcom

Xorcom produit Astribank-8 spécialement conçu pour Asterisk. Ce Channel Bank dispose entre autre de huit port FXS et se connecte à Asterisk via une connections USB-2 directe. Le pilote est fournit avec le paquetage zaptel.

Architecture

Les blocs essentielles à la constitution d'Asterisk sont: Les pilotes de canaux, les applications et le dialplan.

Canaux et Pilotes de Canaux

Un canal est l'unité atomique qui transporte un appel au sein d'Asterisk. Il peut s'agir d'une connection physique à une ligne téléphonique ou à un poste téléphonique comme il peut s'agir d'une connection logique induite par un appel en provenance d'un réseau de données. Avec Asterisk, chaque Canal est géré par un pilote (channel driver) qui en connaît les moindres détails et qui n'expose que le strict nécessaire à la couche supérieure du PBX. Généralement, un pilote de Canal lit dans un fichier de configuration les informations concernant le matériel/protocole qu'il doit gérer puis entre en attente de modification d'états sur les canaux physiques/logiques. Dés qu'un changement d'état survient, (Sonnerie par exemple), le pilote crée une structure de données de type channel et y attache tous les callbacks nécessaires à la communication. Le pilote démarre ensuite le PBX (ast_pbx_start) en passant la référence à la structure de données crée. ast_pbx_start démarre alors un thread pour la gestion du canal. Ainsi, tant que l'appel n'est pas raccroché, le pilote ne s'occupera pas de ce canal en particulier. Le thread du PBX utilisera le canal, lisant, écrivant, multiplexant ce canal avec d 'autres canaux (en utilisant l'appel système select sur le descripteur de fichier du canal). Dés que le canal est raccroché, le pilote reprendra la surveillance du canal dans l'attente du prochain changement d'état.

Applications

Les applications rendent des services lorsqu'un appel est traité dans le système. Pour chaque appel, une suite d'applications est exécuté en série dans l'ordre dans lequel elles sont défini dans le diaplan. Une application très utile est l'application Dial. Certaines applications utilisent un fichier de configuration comme l'application VoiceMail

Dialplan

Le dialplan définit les instructions de traitement d'appel, il est configuré à travers extensions.conf et/ou extensions.ael. Nous les décrirons un plus en détails dans une autre section.

Démarrer Asterisk

Asterisk s'intègre parfaitement au schéma de démarrage classiques et des exemples de scripts init SYSV sont fourni dans la distribution (contrib/init.d). Chaque distribution fournissant Asterisk l'intègre à son système de démarrage et définit un mechanisme générique de configuration de démarrage permettant d'activer telle ou telle autre option. Nous listerons les paramètres utilisés dans la distribution officielle.

Syntaxe générique de Configuration

Asterisk utilise principalement des fichiers de configuration pour son opération. Il esiste un certain nombre de convention qu'on retrouve dans tous les fichiers de configuration d'Asterisk:

• La plupart des fichiers de configuration supporte l'inclusion d'autres fichiers de même nature à travers la directive #include (#include <NomFichier.conf>). Il est généralement possible dans ces cas de recourir à des jokers comme '*' (#include <iaxutil-*.conf>)BR Lorsque le paramètre execincludes est à yes dans la section options du fichier asterisk.conf, il est possible de verser la sortie d'une commande dans un fichier (#exec <Commande>)

• Le point-virgule est utilisé et conseillé pour les commentaires dans les fichiers de configuration. Il est possible de faire des commentaires multi-ligne en utilisant la syntaxe ;-- --;

• La plupart des fichiers de configuration utilisent un découpage par section et chaque section contient des éléments d'assignation (option=valeur).BR Pour certains fichiers (zapata.conf notamment), la configuration est légèrement différente: Les options sont globalement défini, puis dés qu'un objet est spécifié, les options défini lui sont appliquées:

                context=incoming
                callerid=8647288
                channel=>1-2

• Il existe également un mécanisme de définition de templates:BR [section](options)BR option=valeurBR Par exemple:BR [section]BR option1=valeur [section](+)BR option2=valeurBR Cette syntaxe instruit que la section en (+) est la continuité de la première section généralement défini dans un autre fichier et inséré avec #include.

BR [section](!)BR option=valeurBR

Cette configuration en point d'exclamation instruit l'analyseur qu'il s'agit juste d'une template et ne devrait pas être utilisé par Asterisk en l'état. On peut alors faire réfèrence à ce template dans d'autres section fonctionnelles en utilisant la syntaxe [section](nomSection1, [nomSection2])BR BR [sectionA]BR option1=valeurBR BR [sectionB]BR option2=valeurBR BR [sectionX](sectionA,sectionB)BR option3=valeurBR BR se traduirait par:BR [sectionX]BR option1=valeurBR option2=valeurBR option3=valeurBR

Pense-bête Codecs

Les principaux Canaux

Le Canal Zap

Il s'agit généralement d'interface physique au RTC. Nombre de ces cartes sont produites par Digium Inc.. Certains fabriquant de carte produisent également des wrapper permettant plus ou moins de traiter leurs équipements comme des canaux zap (e.g. [http://www.junghanns.net/en/home.html http://www.junghanns.net/en/home.html]). Ces cartes sont généralement de type FXS, FXO, PRI et BRI. Certaines de ces cartes sont des cartes de haute densité modulaires permettant de disposer de plusieurs ports sur le même slot PCI 2.2.

La configuration des canaux zap s'effectue principalement au moyen du fichier zapata.confFootNote(Jim Dixon les a ainsi nommé en réfèrence à Emiliano Zapata « Since this concept was so revolutionary, and was certain to make a lot of waves in the industry, I decided on the Mexican revolutionary motif, and named the technology and organization after the famous Mexican revolutionary Emiliano Zapata. I decided to call the card the 'tormenta' which, in Spanish, means 'storm' but contextually is usually used to imply a big storm, like a hurricane or such »). Les configurations bas niveau des cartes se fait par le fichier /etc/zaptel.conf, partie du paquetage zaptel.

FXO et FXS

Pour faire la différence entre FXS et FXO il faut chercher la partie de la connections qui génère la tonalité. Une carte FXO ne génère pas de tonalité. Un port fournit la tonalité et le voltage nécessaire à la sonnerie alertant le terminal connecté lors de l'arrivée d'un appel.

zconfig.h

Certaines options de configuration sont accessible par la modification du fichier zconfig.h du paquetage zaptel. Certains paramètres peuvent être modifiés lors du chargement des pilotes de cartes dont vous disposez (modprobe wctdm boostringer=1). Parmi ces options on peut citer:

• BOOST_RINGER permet d'augmenter le voltage envoyé à un téléphone de 70 à 89V. Ceci peut être utile lorsque certains téléphones connectés au canal zap ont du mal a détecter la sonnerie.
• CONFIG_ZAPTEL_MMX pour les optimisations MMX
• Choix de l'algorithme de suppression de l'écho (ECHO_CAN_KB1, ECHO_CAN_MG2, etc)
• Suppression agressive de résidu d'écho: AGGRESSIVE_SUPPRESSOR
• ZapRAS pour trnsformer Asterisk en RAS.

zaptel.conf

Ce fichier est analysé par l'outil de configuration des interfaces zaptel ztcfg. On y définit les spans, la liste de périphériques regroupant les canaux et les tonalités.

        span=1,0,0,cas,hdb3,yellow,crc4

Il faut noter que les framing utilisés pour les E1 (à moins qu'il ne s'agisse d'un channel Bank) sont cas ou ccs et le coding est ami ou hdb3. On peut utiliser le mot clé crc4 pour activer la vérification du CRC4 sur la ligne.

        fxsks=25,27,28,29
        fxoks=1-12,19

Une carte FXS est définit par le fait qu'elle connecte un terminal/station, donc elle doit se comporter comme une CO en utilisant une signalisation FXO.

        defaultzone=fr
        loadzone=fr

zapata.conf

Ce fichier contient essentiellement deux section qui sont [trunkgroups] et [channels]. La section trunkgroups est utilisé pour les liaisons NFAS et GR-303 de Bellcore. La section [channels] contient toutes les définitions des attributs de canaux utilisés par Asterisk.

        language=fr
        context=nomades
        internationalprefx=00
        nationalprefix=9
        localprefix=8

        signalling=fxs_ks
        sendcalleridafter=2
        cancallforward=yes (*72+Numéros active et *73 désactive)
        group=3
        stripmsd=1
        callerid=asreceived
        channel => 1-13

Commandes CLI

        reload chan_zap.so
        zap show cadences
        zap show channel <channel>
        zap show channels
        zap show status
        pri show span <span>
        pri show spans
        pri show debug
        pri debug span <span>
        pri intense debug span <span>
        pri set debug file

IAX2

IAX2 est le protocole de téléphonie sur IP standard de fait (et pas encore standard de jurée) dans la communauté Asterisk. Il possède des caractéristiques intéressantes comme le 'trunk' ou une excellente immunité aux réseaux à translation d'adresse/port. Contrairement aux protocoles effectuant la signalisation sur un port différent de celui qui transporte le média, IAX utilise le même port pour la signalisation et pour le transport du média.

        reload chan_iax2.so ou iax2 reload
        iax2 debug
        iax2 show netstats|threads|stats
        iax2 trunk debug
        iax2 jb debug

SIP

SIP est un standard de jurée (IETF 02/1996 draft-ietf-mmusic-sip-00 ) de Téléphonie sur IP, il utilise RTP pour le transport du média. Il s'agit d'un protocole de signalisation au niveau de la couche application (c'est même la principale source de ses problèmes). SIP peut utiliser TCP ou UDP pour le transport même si l'implémentation Asterisk n'est pas encore TCP capable. dans channels/chan_sip.c on peut lire:

 * Implementation of RFC 3261 - without S/MIME, TCP and TLS support
 * Configuration file \link Config_sip sip.conf \endlink
 *
 *
 * \todo SIP over TCP
 * \todo SIP over TLS
 * \todo Better support of forking
 * \todo VIA branch tag transaction checking
 * \todo Transaction support
 *
 * \ingroup channel_drivers
 *
 * \par Overview of the handling of SIP sessions
 * The SIP channel handles several types of SIP sessions, or dialogs,
 * not all of them being "telephone calls".
 * - Incoming calls that will be sent to the PBX core
 * - Outgoing calls, generated by the PBX
 * - SIP subscriptions and notifications of states and voicemail messages
 * - SIP registrations, both inbound and outbound
 * - SIP peer management (peerpoke, OPTIONS)
 * - SIP text messages

Bien que SIP ne soit pas le seul protocole de voix sur IP du marché, il semble bénéficier d'une large adoption aussi bien par les constructeurs de terminaux que par les développeurs, cela est en partie du à la disponibilité des spécifications.

Une configuration de base sip.conf ressemble à ceci:

[general]
context=Hell
srvlookup=yes
tos_sip=cs3
tos_audio=ef
tos_video=af41
useragent=AUFSIPUA Pwrd by Asterisk PBX 
externip = 1.2.3.4
externhost=foo.baz.bar
localnet=192.168.0.0/255.255.0.0
localnet=10.0.0.0/255.0.0.0
localnet=172.16.0.0/12
localnet=169.254.0.0/255.255.0.0

[tom]
type=friend
secret=s3cr3t
qualify=10 
disallow=all
allow=speex
allow=gsm
allow=alaw
nat=no 
host=dynamic
canreinvite=no
context=hackers


        reload chan_sip.so ou sip reload
        sip show objects
        sip show peers
        sip show settings|domain|channels|subscriptions
        sip show peers like <regex>

ALSA / OSS

Il s'agit du pilote de canal console permettant entre autre de tester la configuration.

Pseudo canal Agent

Ce canal est principalement utilisé pour l'identification des agents (télé-acteurs, télé-conseillers, télé-spameurs, télé-marketeurs, etc).

Pseudo canal Local

Ce canal permet pour créer une boucle sur le PBX lui même. Il est utilisé pour le routage récursif.

Jingle

Le support de Jingle sous Asterisk se limite au support du protocole propriétaire GoogleTalk. chan_jingle utilise res_jabber pour l'accès au serveur Jabber.

H.323

Protocole de téléphonie IP de jurée de l'ITU H.323. Il existe Trois implémentations H.323 pour Asterisk: Une implémentation inclus dans la distributions officielle d'Asterisk, une autre produite par Objective Systems et distribuée avec asterisk-addons (asterisk-addons/asterisk-ooh323c) et enfin une dernière produite par inaccessnetworks

• ([http://www.inaccessnetworks.com/projects/asterisk-oh323 http://www.inaccessnetworks.com/projects/asterisk-oh323])

Skinny/SCCP

Skinny est un protocole propriétaire de Cisco utilisé avec le PBX Cisco Call Manager. Asterisk supporte ce protocole via chan_skinny

UNISTIM

Il s'agit d'un protocole propriétaire de Nortel (voir http://mlkj.net/UNISTIM/)

CAPI/MISDN

Il s'agit des principaux pilote de canaux utilisé pour l'accès aux cartes RNIS d'accès de base. Ils supportent toutes les cartes gérées par les infrastructure du noyau (CAPI2 et MISDN). chan_misdn commençe à s'imposer et fournit déjà une ensemble impressionnant de fonctionnalités (mode NT/TE, Crypto (Blowfish), app_sendText, détection DTMF, etc).

VPB

Asterisk supporte les cartes Voicetronix ([http://www.voicetronix.com/index.htm http://www.voicetronix.com/index.htm]) à travers chan_vpb

MGCP

MGCP est aussi un standard de jurée de l'IETF de plus en plus supplanté par SIP et IAX. Asterisk supporte MGCP à travers chan_mgcp

Dialplan

Les contextes sont utilisés par Asterisk pour diviser le Dialplan en unités logiques, chacune avec la possibilité de traitement différent pour les mêmes extensions. Les contextes peuvent avoir leurs propres modèle de sécurité et peuvent inclure d'autres contextes. Les contextes sont souvent vu comme des unités organisationnelles d'entreprise avec les mêmes droits d'accès à des ressources que le contexte permet de regrouper.

Les mécanisme d'inclusion de contexte peuvent dépendre de date/heure particulière

extensions.conf

Le premier outil de configuration du dialplan est le fichier extensions.conf.

Commandes CLI

        show dialplan|hints|switches
        show dialplan [[exten@]contexte]
        extensions reload
        add extension <exten>,<priorité>,<app>,<arg-app> into contexte [replace]
        remove extension <exten@context> [priorité]
        include <contexte> in <contexte>
        dont include <contexte> in <contexte>
        save dialplan <FichierDestination>

Exstensions

Une extension Asterisk n'est pas liée à une interface, elle est constituée d'un ensemble d'application dont la séquence est déterminée par la priorité attaché à l'application.

        exten => extension,priorité[+offset][(alias)],Application(args)

        [default]
        exten => 205,1,Goto(phrase-menu,s,1)

        [phrase-menu]
        exten => s,1,Answer 
        exten => s,2,DigitTimeout,5 ; Délai d'attente de DTMF
        exten => s,3,ResponseTimeout,10 ; Délai d'attente de réponse 
        exten => s,4,BackGround(custom/phrase-menu) ; Menu principal play.

        ; Phrase Recording
        exten => 1,1,Wait(1)
        exten => 1,2,Read(PHRASEID|custom/entrer-num-phrase)
        exten => 1,3,Wait(2)
        exten => 1,4,Record(custom/${PHRASEID}:gsm)
        exten => 1,5,Wait(2)
        exten => 1,6,Playback(custom/${PHRASEID})
        exten => 1,7,Wait(1)
        exten => 1,8,Goto(s,2)
        
        ; Phrase review
        exten => 2,1,Wait(1)
        exten => 2,2,Read(PHRASEID|custom/entrer-numm-phrase)
        exten => 2,3,Wait(1)
        exten => 2,4,Playback(custom/${PHRASEID})
        exten => 2,5,Wait(1)
        exten => 2,6,Goto(s,2)

        exten => t,1,Hangup

        exten => i,1,Playback(custom/option-invalide)
        exten => i,2,Goto(s,2)

La modification d'une extension peut être pénible puisqu'il faut généralement ré-ordonner les priorités des applications mise en jeu. Asterisk fourni les priorités n et s qui signifient:

• s (same) même priorité que la précédente

  n (next) prochaine priorité disponible

        [phrase-menu]
        exten => s,1(entree),Answer 
        exten => s,n,DigitTimeout,5 ; Set Digit Timeout to 5 seconds
        exten => s,n,ResponseTimeout,10 ; Set Response Timeout to 10 seconds
        exten => s,n,BackGround(custom/phrase-menu) ; Play main menu.

        ; Phrase Recording
        exten => 1,1,Wait(1)
        exten => 1,n,Read(PHRASEID|custom/enter-phrase-num)
        exten => 1,n,Wait(2)
        exten => 1,n,Record(custom/${PHRASEID}:gsm)
        exten => 1,n,Wait(2)
        exten => 1,n,Playback(custom/${PHRASEID})
        exten => 1,n,Wait(1)
        exten => 1,s+1,Goto(s,entree)

Asterisk fournit un mécanisme de groupage sous la forme de modèle permettant d'exprimer un groupe d'extension de façon concise:

        exten => _0[8,9]XXXX,1,Dial(Zap/g1/${EXTEN:1}|20|tT)

Il est important de noter qu'une extension peut être résolue par plusieurs modèles, auquel cas le mécanisme de tri d'Asterisk effectuera l'arbitrage. Pour éviter de subir ce tri, on peut utiliser le mécanisme d'inclusion qui donne la priorité aux extensions directes (non inclues)

Au lieu de :

        [exemple] 
        exten => _918.,1,Dial(Zap/g1/${EXTEN}) 
        exten => _.,1,Dial(Zap/g2/${EXTEN}) 
        exten => h,1,Hangup 

Utilisez

        [exemple]
        include => sous-exemple
        exten => h,1,Hangup
        exten => _918.,1,Dial(Zap/g1/${EXTEN})


        [sous-exemple]
        exten => _.,1,Dial(Zap/g2/${EXTEN})

Extensions et priorités spéciales

Les extensions ne sont pas que numériques, Asterisk fournit des extensions spéciales permettant d'effectuer certaines tâches prédéfinies:

Il existe une priorité spéciale 'hint' permettant à Asterisk de communiquer l'état d'un canal à un équipement externe sans révéler la nomenclature externe qui s'avère inutile dans nombre de cas (voir http://www.voip-info.org/wiki/view/Asterisk+standard+extensions)

        exten => 200,hint,SIP/tom 
        exten => 200,1,Dial(SIP/tom)

switch

Asterisk utilise le mot clé pour la résolution d'extensions inconnues au PBX local.

        switch => IAX2/utilisateur:passe@montreal/contextext

il existe deux variantes de switch qui se distinguent essentiellement par le moment où les substitutions de variables (interpolations) s'opèrent: Il s'agit de lswitch et de eswitch.

Variables et expressions

Des variables peuvent être défini en utilisant la fonction Set:

        Set(variable=valeur) ; variable accessible par ${variable}

Il existe nombre de variables prédéfinies par Asterisk et définies à plusieurs niveau (variables de canaux, variable défini par certaines applications, variables de CDR, etc).

Il est possible d'extraire des sous chaînes de variables avec la syntaxe:

        ${variable:offset:longueur}

Des variables statiques peuvent être définies dans la section [globals] du fichier extensions.conf

        [globals]
        CONSOLE=/dev/sound/dsp
        IAXINFO=utilisateur:passe
        TRUNK=IAX2/utilisateur:passe@quebec
        GTIMEOUT=37

Asterisk est capable d'évaluer des expressions et reconnaît un grand nombre d'opérateurs:

        exten => 1,1,Set(variable1=$[1+102])
        exten => 1,2,Set(variable2=$[${EXTEN}+${variable1}+200])

Fonctions prédéfinit et Macro

        ${IF(<expr>?<vrai>:<faux>)}
        ${EXISTS(<donnés>)}
        ${ISNULL(<données>)}
        ${REGEX("<regex>" <données>)}

Les macros sont implémentés comme des contextes particuliers avec des noms de type:

        [macro-NomMacro]


        [macro-BoiteVocale]
        exten => s,1,Set(LANGUAGE()=fr)
        exten => s,n,Set(TIMEOUT(absolute)=60)
        exten => s,n,Voicemail(u${ARG1})
        exten => s,n,Macro(fastbusy)
        exten => s,s+100,Voicemail(b${ARG1})

        [home]
        exten => 600,1,Dial(IAX2/tom|${GTIMEOUT}tT)
        exten => 600,2,Macro(BoiteVocale|600@home)

extensions.ael (version 2)

AEL est un langage de description du dialplan d'Asterisk. On a souvent reproché au dialplan d'Asterisk de ne pas être lisible, certains prétendent qu'AEL est une sorte de poudre aux yeux pour visuellement parer à cette limitation s'il en est. En tous les cas, extensions.ael est 'compilé' et la sortie est identique à la syntaxe extensions.conf. Le module pbx_ael.so qui analyse le fichier extensions.ael est complétement différent de l'analyseur du fichier extensions.conf (pbx_config.so). La sortie de pbx_ael.so est injectée dans le dialplan comme ceci:

SALAM*CLI> show dialplan inter2
[ Context 'inter2' created by 'pbx_ael' ]
  '123456789' =>    1. Set(x=$[ 0 ])                              [pbx_ael]
                    2. GotoIf($[ ${x}<10 ]?3:6)                   [pbx_ael]
                    3. Verbose(x is ${x} !)                       [pbx_ael]
                    4. Set(x=$[ ${x}+1 ])                         [pbx_ael]
                    5. Goto(2)                                    [pbx_ael]
                    6. NoOp(Finish for-123456789-1)               [pbx_ael]
                    7. NoOp(123)                                  [pbx_ael]
                    8. NoOp(456)                                  [pbx_ael]
                    9. NoOp(789)                                  [pbx_ael]
                    10. Dial(SIP/514)                             [pbx_ael]
                    11. Goto(sw-11-${DIALSTATUS}|1)               [pbx_ael]
                    12. NoOp(Finish switch-11)                    [pbx_ael]
  'sw-11-"CHANUNAVAIL"' => 1. Verbose("Channel isnt available")   [pbx_ael]
                    2. Goto(123456789|12)                         [pbx_ael]
  '_sw-11-.' =>     1. Verbose(${DIALSTATUS})                     [pbx_ael]

Le fichier extensions.ael produisant ce dialplan est le suivant:

context inter2 {
     123456789 => {
             for(x=0; ${x}<10; x=${x}+1) {
                     Verbose(x is ${x} !);
             };
             NoOp(123);
             NoOp(456);
             NoOp(789);

             Dial(IAX2/tom);
             switch(${DIALSTATUS}) {
                  case "CHANUNAVAIL":
                          Verbose("Canal non disponible, Tom couche les mômes");
                                break;
                  default:
                         Verbose(${DIALSTATUS});
            };
     };
};

Commande CLI

        ael reload
        ael debug contexts
        ael debug macros
        ael debug read
        ael debug tokens
        ael no debug

Utilitaires AEL

L'outil aelparse est fourni avec la distribution Asterisk sous utils/aelparse pour debugger un fichier ael. Le programme accepte principalement deux arguments:

        -d: spécifie l'emplacement du fichier ael à analyser (par défaut sous              /etc/asterisk)
        -n: Montre juste les erreurs et les warnings.

Syntaxe du 'langage'

L'exemple ci-dessous montre globalement la structure d'un fichier ael:

        if (${x}=1) {
              NoOp(hello!); 
                goto s|debut;
        } else {
              NoOp(Goodbye!); 
                goto s|milieu;
        }

Mots clés du 'langage'

Les mots clés sont sensible à la casse:

 * abstract
 * context
 * macro
 * globals
 * ignorepat
 * switch
 * if
 * ifTime
 * else
 * random
 * goto
 * jump
 * return
 * break
 * continue
 * regexten
 * hint
 * for
 * while
 * case
 * pattern
 * default NOTA: le mot clé "default" peut être utilisé comme un nom de contexte
 * catch
 * switches
 * eswitches
 * includes

Commentaires

Les commentaires sont marqués par // et se terminent avec la fin de la ligne.

Contextes

        context NomContexte {

        }

Un contexte abstrait est un contexte uniquement destiné à être inclus par d'autres contextes:

        abstract context NomContext {

        }

Extensions

context inter2 {
   123456789 => {
           for(x=0; ${x}<10; x=${x}+1) {
                   Verbose(x is ${x} !);
           };
           NoOp(123);
           NoOp(456);
           NoOp(789);

           Dial(IAX2/tom);
           switch(${DIALSTATUS}) {
                case "CHANUNAVAIL":
                        Verbose("Canal non disponible, Tom couche les mômes");
                        break;
                default:
                        Verbose(${DIALSTATUS});
          };
   };
};

Inclusions

        context chefprj {
            includes {
                 local;
                 international;
            }
        }
        #include "/etc/asterisk/sousdir.ael"

Switches

        context default {
            switches {
                 DUNDi/e164;
                 IAX2/paris;
            };
            eswitches {
                 IAX2/context@${CURSERVER};
            }
        }

Variables

        globals {
                CONSOLE=/dev/sound/dsp;
                IAXINFO=utilisateur:passe;
                TRUNK=IAX2/utilisateur:passe@quebec;
                GTIMEOUT=37;
        }

        context default {
          TRUNK=IAX2/paris;
            switches {
                 DUNDi/e164;
                   ${TRUNK};

            };
            eswitches {
                 IAX2/context@${CURSERVER};
            }
        }

Boucles

        context boucles {
            1 => {
                 for (x=0; ${x} < 3; x=${x} + 1) {
                      Verbose(x est ${x} !);
                 }
            }
            2 => {
                 y=10;
                 while (${y} >= 0) {
                      Verbose(y est ${y} !);
                      y=${y}-1;
                 }
            }
        }

Macro

        macro std-exten( ext , dev ) {
               Dial(${dev}/${ext},20);
               switch(${DIALSTATUS) {
               case BUSY:
                       Voicemail(b${ext});
                       break;
               default:
                       Voicemail(u${ext});

               }
               catch a {
                       VoiceMailMain(${ext});
                       return;
               }
        }

puis

        context exemple {
            _5XXX => &std-exten(${EXTEN}, "IAX2");
            _6XXX => &std-exten(, "IAX2");
            _7XXX => &std-exten(${EXTEN},);
            _8XXX => &std-exten(,);
        }

Goto et Labels

context gotoexemple { 
        s =>  { 
                begin: 
                        NoOp(Boucle infini!); 
                        Wait(1); 
                        goto begin; 
        }; 
        3 => { 
                goto s|begin; 
        }; 
        4 => { 
                goto gotoexemple|s|begin; 
        }; 
}; 

context gotoexemple2 { 
        s => { 
                end: 
                        goto gotoexemple|s|begin 
        }; 
}; 

Pour plus de détails sur AEL2 lisez le document doc/ael.txt dont cette section est extraite.

Infrastructure « RealTime » (ARA)

En plus des stockage sur fichier classique, Asterisk fournit un mécanisme dynamique permettant d'utiliser des SGBDR. Les pilotes les plus unifiés sont construits sur res_odbc et res_config_odbc et utilisent UnixODBC (htt://www.unixodbc.org). D'autre travaux sont en cours et devraient fournir à terme res_config_pgsql, res_config_ldap (voir l'une des branches de développement de Olle E. Johansson sur [http://svn.digium.com/view/asterisk/team/oej/res_config_ldap/ http://svn.Digium Inc..com/view/asterisk/team/oej/res_config_ldap/]).

extconfig.conf

La configuration ARA s'opère au moyen du fichier avec une syntaxe semblable à celle-ci:

        <famille> => <PiloteRealTime>, <NomBaseDonnées>[,<table>]

        [settings]
        extensions => odbc,telephonie,extensions
        iaxpeers => odbc,telephonie,iax
        iaxusers => odbc,telephonie,iax
        sipusers => odbc,telephonie,sip
        sippeers => odbc,telephonie,sip
        voicemail => odbc,telephonie,voicemail2
        jingle.conf => odbc,telephonie ; (table ast_config  utilisée)

res_odbc.conf

        [ENV]

        [telephonie]
        enabled => yes
        dsn => telephonie
        username => tom
        password => s3cr3t
        pre-connect => yes

Structures de tables

Voici quelques exemple de schéma PostgreSQL de base:

CREATE TABLE iax (
    name character varying(30) NOT NULL,
    username character varying(30),
    type character varying(6) NOT NULL,
    secret character varying(50),
    md5secret character varying(32),
    dbsecret character varying(100),
    notransfer character varying(10),
    inkeys character varying(100),
    outkeys character varying(100),
    auth character varying(100),
    accountcode character varying(100),
    amaflags character varying(100),
    callerid character varying(100),
    context character varying(100),
    defaultip character varying(15),
    host character varying(31) DEFAULT 'dynamic'::character varying NOT NULL,
    mailbox character varying(50),
    deny character varying(95),
    permit character varying(95),
    qualify character varying(4),
    disallow character varying(100),
    allow character varying(100),
    ipaddr character varying(15),
    port integer DEFAULT 0,
    regseconds integer DEFAULT 0,
    language character varying(5) DEFAULT 'fr'::character varying,
    add_date timestamp without time zone DEFAULT now(),
    rent boolean DEFAULT true,
    acctid bigint DEFAULT 0
);
CREATE TABLE extensions (
    id serial NOT NULL,
    context character varying(20) DEFAULT ''::character varying NOT NULL,
    exten character varying(20) DEFAULT ''::character varying NOT NULL,
    priority smallint DEFAULT 0 NOT NULL,
    app character varying(20) DEFAULT ''::character varying NOT NULL,
    appdata character varying(128));
CREATE TABLE voicemail (
    customer_id bigint DEFAULT (0)::bigint NOT NULL,
    context character varying(50) DEFAULT ''::character varying NOT NULL,
    mailbox bigint DEFAULT (0)::bigint NOT NULL,
    password character varying(4) DEFAULT '0'::character varying NOT NULL,
    fullname character varying(50) DEFAULT ''::character varying NOT NULL,
    email character varying(50) DEFAULT ''::character varying NOT NULL,
    pager character varying(50) DEFAULT ''::character varying NOT NULL,
    stamp timestamp(6) without time zone NOT NULL,
    uniqueid serial NOT NULL
);

CREATE TABLE ast_config (
 id int(11) NOT NULL auto_increment,
 cat_metric int(11) NOT NULL default 0,
 var_metric int(11) NOT NULL default 0,
 commented int(11) NOT NULL default 0,
 filename varchar(128) NOT NULL default '',
 category varchar(128) NOT NULL default 'default',
 var_name varchar(128) NOT NULL default '',
 var_val varchar(128) NOT NULL default '',
 PRIMARY KEY  (id),
 KEY filename_comment (filename,commented)
);

DUNDI

DUNDI est un protocole P2P utilisé pour localiser les passerelles Internet vers des services de téléphonie. Il s'agit d'un protocole distribué sans autorité centrale. DUNDI permet de déterminer des chemin d'accès qui sont ensuite utilisés pour accéder aux ressources localisées à travers les standards de téléphonie sur IP.

Commanes CLI

        dundi show peer <identité>
        dundi show peers
        dundi show transaction
        dundi show requests
        dundi show precache
        dundi show mappings|identité
        dundi query <identité>[@contexte]
        dundi lookup <numero>[@contexte] [bypass]
        dundi precache <numero>[@contexte]
        dundi flush
        dundi store history
        dundi debug     

Crypto

DUNDI est un protocole crypté, les pairs de clé doivent être générés sur les systèmes Asterisk qui veulent l'utiliser.

dundi.conf

        [general]
        autoanswer=yes
        department=Infrstructures Techniques
        organization=Fongibilité Asymétrique
        locality=Dakar
        country=SN
        mail=dundi@courriel.com
        phone=+2215555555
        bindaddr=0.0.0.0
        port=4520
        entityid=00:50:BA:1E:64:BC

        [mappings]
        contexte_dundi => contexte_local,poids,tech,dest[,options]

Les correspondances 'mapping' fournissent la relation entre les contextes DUNDI et les contextes locaux au PBX:

senegal => local,0,IAX2,dundi:${SECRET}@dakar.example.com/${NUMBER},
                                                        nounsolicited,nocomunsolicit,nopartial

Le fichier dundi.conf définit également les homologues sous la forme:

        [00:11:22:44:88:FF] 
        model = symmetric
        host = montreal.example.com
        inkey = montreal
        outkey = dakar
        include = senegal
        permit = senegal
        qualify = yes
        dynamic=yes

Les derniers aspects consistent à définir les accès aux ressources pointées par les correspondances 'mappings' (iax.conf pour permettre les appels, auquel cas on peut utiliser le mot de passe généré par Asterisk toutes les heures et stocké dans dundi/secret dans la base BerkeleyDB d'Asterisk) et à définir les contextes dans lesquels des recherches DUNDI peuvent s'effectuer (switch => DUNDI/montreal par exemple).

Voicemail

La configuration statique du système de messagerie vocale s'effectue au travers du fichier voicemail.conf. Les paramètres les plus utilisés sont:

        [default]
        3131 => 0000,Tom Tom,tomy@exemple.com
        3132 => 0000,Jr Sant,jrstan@exemple.com,jrsant@pagerexemple.com

L'accès à la messagerie vocale se fait par les applications VoiceMail() et VoiceMailMain() dans le dialplan.

AGI

Les AGI peuvent être écrit dans n'importe quel langage de programmation. Ils communiquent avec Asterisk à travers les descripteurs de fichier standards STDIN, STDOUT et STDERR..

Les AGI sont invoqués directement dans le dialplan comme toutes les applications (AGI(), EAGI(), DeadAGI() et FastAGI()). Au démarrage, Asterisk envoie une liste de variables ainsi que leurs valeurs à l'AGI qu'il a démarré, ces pairs ressemblent à ceci:

        agi_request: Dial.py
        agi_channel: Zap/2-1
        agi_language: fr
        agi_callerid:
        agi_context: topsecret
        agi_extension: 313
        agi_priority: 1

Ces pairs sont suivi d'une ligne vide pour signifier à l'AGI qu'Asterisk attend des commandes pour le contrôle du dialplan.

Commandes AGI

Les commandes AGI peuvent être obtenu avec la commnde show agi en console:

Pour chaque commande envoyée, Asterisk répondra dans un style http et la réponse détermine le statut de la commande. Les réponses ressemblent à ceci:

        200 result=1 (VariableTest)

Voici une routine Perl permettant de traiter la réponse d'Asterisk aux commandes, ce type de sous routine est généralement fournit par les wrappers AGI:

sub checkresult {
        my ($res) = @_;
        my $retval;
        $tests++;
        chomp $res;
        if ($res =~ /^200/) {
                 $res =~ /result=(-?\d+)/;
                 if (!length($1)) {
                          print STDERR "FAIL ($res)\n";
                          $fail++;
                 } else {
                          print STDERR "PASS ($1)\n";
                          $pass++;
                 }
        } else {
                 print STDERR "FAIL (unexpected result '$res')\n";
                 $fail++;
        }

Perl est très populaire pur l'écriture des AGI et James Golovich a produit une excellent wrapper permettant d'accéder aux commandes AGI d'Asterisk d'une façon beaucoup plus simple (Asterisk::AGI). Vous trouverez cette bibliothèque sur [http://asterisk.gnuinter.net/ http://asterisk.gnuinter.net]. Il existe également une bibliothèque AGI PHP sur http://phpagi.sourceforge.net.

AGI en Python

Dans cet exemple nous allons utiliser http://sourceforge.net/projects/pyst pour écrire un petit AGI remplaçant la commande Dial. Cet AGI va vérifier dans une table de la base, parmi une liste de fournisseurs, laquelle elle devra choisir pour envoyer l'appel en fonction de la capacité de la route. Il est trivial de l'améliorer pour générer des pondérations dynamiques en fonctions des statistiques sur la qualité des route créant ainsi un système de routage dynamique convergeant.

Table

CREATE TABLE fournisseurs (
    id serial NOT NULL,
    peer character varying(256),
    capacite integer,
    proto character varying(16) DEFAULT 'IAX2'::character varying,
    occurrence integer DEFAULT 0,
    dernierefois timestamp without time zone
);

#!/usr/bin/python
import psycopg, sys, time
from asterisk import agi
lcAGI = agi.AGI()
db = psycopg.connect("user=test dbname=s3cr3t")
curs = db.cursor()
def getFournisseurs():
        # Chercher les fournisseurs en évitant les plus récent
        curs.execute("SELECT id, peer FROM fournisseurss  WHERE 
                                        occurrence < capacity ORDER BY dernierefois")
        return curs.fetchone()
def INCoccurrence(id):
        curs.execute("UPDATE fournisseurss SET occurrence = occurrence + 1,                                              dernierefois = now() WHERE id=%s" % id)
        db.commit()
        return 0
def DECoccurrence(id):
        curs.execute("UPDATE fournisseurs SET  occurrence = occurrence - 1 WHERE                                                                                        id=%s" % id)
        db.commit()
        return 0
dest = lcAGI.env['agi_extension']
try:
        (id, name) = getFournisseurs()
except:
        id = 0

if id:
        INCoccurrence(id)
        #TODO: Utiliser le protocole pour construire le paramètre du Dial
        lcAGI.set_variable("PeerId", id)
        lcAGI.appexec("Dial", "SIP/%s@%s|70" % (dest, name))

else:
        # Plus de ligne, à inscrire dans le journal
        fd = open('/var/log/NoLines','a')
        fd.write('%s | %s | %s | Plus de ligne\n' % (time.ctime(), exten,                                                               lcAGI.env['agi_calleridname']))
        fd.close()
curs.close()
db.close()

Debugger les AGI

Les AGI peuvent être difficile à debugger. Une technique simple consiste à simuler le comportement d'Asterisk en console en exécutant directement l'AGI. Vous pouvez également activer le debug des AGI en console (agi debug)

AMI

Asterisk fournit un autre mécanisme puissant pour exposer les routines internes du PBX et envoyer des événements (abonnement aux événement) sur un port TCP (5038 par défaut) déterminé. Cette interface acceptera également des commandes une fois l'authentification établie. Vous pouvez vous connecter sur cet interface à partir de votre application pour recevoir les événements et envoyer des commandes. Il est même possible de s'abonner aux CDR. Un excellent exemple utilisant cet interface est MozPhone ([http://www.sysnux.pf/sections/telephonie http://www.sysnux.pf/sections/telephonie])

Applications et fonctions

Asterisk est fourni avec pléthores de fonctions et d'applications traitant de tous les domaines liés de près ou de loin au PBX. Vous aurez un excellent aperçu en scrutant les sorties de commandes suivantes:

        show applications
        show application <NomApplication>
        show functions 
        show function <NomFonction>

Ressources

Asterisk: The future of Telephony.: O'Reilly & Associates , Inc., 2005FootNote(Disponible en téléchargement sur http://www.asteriskdocs.org/modules/tinycontent/index.php?id=11)

par :Jared Smith, Jim Van Meggelen et Leif Madsen

ISBN: 0-596-00962-3

[http://www.oreilly.com/catalog/asterisk/ http://www.oreilly.com/catalog/asterisk/]

Le guide de référence Wiki pour Asterisk

[http://www.voip-info.org/wiki-Asterisk http://www.voip-info.org/wiki-Asterisk]

The Asterisk Asterisk Documentation Project

[http://www.asteriskdocs.org/ http://www.asteriskdocs.org]

Digium Inc. Issue Tracker

[http://bugs.digium.com/main_page.php http://bugs.digium.com/main_page.php]

Asterisk.org

[http://www.asterisk.org/ http://www.asterisk.org]

Distribution GNU/Linux centré sur Asterisk: AstLinux

[http://www.astlinux.org/ http://www.astlinux.org/]

AstriCon

[http://www.astricon.net/ http://www.astricon.net]

Daily Asterisk News

[http://www.sineapps.com/news.php http://www.sineapps.com/news.php]

Documentation en ligne Digium Inc.

[http://www.digium.com/en/supportcenter/documentation/ http://www.digium.com/en/supportcenter/documentation/]

Zaptel Under the Hood

[http://zapteldoc.blogspot.com/ http://zapteldoc.blogspot.com/]

Asterisk SS7

[http://www.voip-info.org/wiki-Asterisk+SS7 http://www.voip-info.org/wiki-Asterisk+SS7]

OpenPBX.org

[http://www.openpbx.org/ http://www.openpbx.org]

Freeswitch

[http://www.freeswitch.org/ http://www.freeswitch.org/]

Yate (Yet Anothet Telephony Engine)

[http://yate.null.ro/ http://yate.null.ro/]

Listes de diffusion (svn-commits, asterisk-addons-commits, Asterisk-Announce, asterisk-biz, asterisk-bsd, asterisk-bugs, asterisk-ss7, dundi, asterisk-video, etc)

[http://lists.digium.com/mailman/listinfo/ http://lists.digium.com/mailman/listinfo/]