Xmppophone

Module Intermédiaire de gestion convergente de la presence entre SIP (Freeswitch) et XMPP(Ejabberd)

Introduction

Ce module a pour but de permettre d'obtenir une certaine convergence dans le signalement de la présence sur le protocole de messagerie instantanée XMPP (connu aussi sous le nom de Jabber) via des informations extérieures provenant du protocole de VOIP SIP.

Le cas d'usage standard est le suivant :

  1. Bob et Alice sont connectés sur XMPP avec leurs clients respectifs.
  2. Bob appelle John au téléphone depuis son téléphone professionnel VOIP SIP.
  3. Alice doit pouvoir savoir directement depuis l'interface de son client que Bob est occupé afin de ne pas le déranger durant son appel.

La solution présente ici pour résoudre ce cas d'usage est d'avoir un module intermédiaire qui sera capable de communiquer et de recevoir des informations depuis les deux serveurs des deux protocoles : SIP (Freeswitch), XMPP(Ejabberd).

Architecture du module

--------------(1)      (2) --------------- FS pythonESL  --------------
|            =============>   Module     ===============>             |
| Ejabberd   |  XMLRPC    |   python     |(5)        (6)| Freeswitch  |
|            |            |  (Xmppophone)|              |             |
|            <=============              |              |             |
|-------------(3)      (4)----------------              ---------------
  ^                                                            ^
  |                                                            |
  |   Xmpp                                                     |  SIP
  |                                                            |
  V                                                            v
-------------                                               ------------
| CLient    |                                               |  Client  |
|  XMPP     |                                               |  SIP     |
|           |                                               |          |
-------------                                               ------------

                           ____________
                           |Xmppophone |
                           |           |<=||
              AD-HOC       |           |  ||
              Command      |___________|  ||
[Client XMPP]-  -  -  -  ->[ Bot XMPP  ]  ||
        ^                   ^ (7)         ||
        | XMPP          XMPP|            //
        v___________________v           //  XMLRPC
        |      Serveur       |<========//
        |          Ejabberd  |
        |____________________|

Principe du module

Le module est à l'écoute de diverses informations provenant d'ejabberd et de freeswitch, il garde ainsi une base de données interne pour pouvoir dès qu'un appel commence ou termine (SIP) pouvoir modifier l'information de présence des utilisateurs XMPP. Pour ce faire le module se base sur des commandes ejabberd (dont certaines proviennent d'un module réalisé dans ce but). Ejabberd peut alors traiter l'information.

Le fonctionnement actuel est globalement le suivant pour le lancement d'un appel :

  • Freeswitch transmet une information de début d'appel via le téléphone "1000@monfreeswitch"
  • Le module python regarde les utilisateurs XMPP concernés par l'appel et envoie en se connectant en admin les commandes à ejabberd pour changer les présences.
  • Ejabberd via les modules, "se fait passer" pour les utilisateurs concernés et envoie les messages XMPP nécessaires à la diffusion des changements d'état.

Depuis la version 0.6 du module, un système de commandes ad-hoc xmpp à été ajouté, il permet d'exécuter depuis les clients le supportant des commandes sur le contact xmpp designé comme bot jabber tel que le lancement d'un appel, la possibilité de rejoindre un salon ou d'envoyer un contact dans une conference téléphonique.

Installation

Le module s'installe comme tout paquet python mais nécessite des configurations pour être fonctionnel.

exemple d'installation en mode éditable:

cd xmppophone
pip install -e .

Configuration Ejabberd

Prérequis

Coté XMPP avec ejabberd les modules suivants sont nécéssaires :

  • mod_muc_admin
  • mod_admin_extra
  • ejabberd_xmlrpc (3)

Attention, certains de ceux-ci ne sont pas disponibles de base dans la version jessie d'ejabberd, il convient de prendre la version d'ejabberd provenant des backports. (16.02 ou supérieure)

Les modules suivants ont été réalisés dans le but de ce système et sont aussi nécessaires:

  • mod_muc_admin_extra (ajoute des commandes)
  • mod_xmlrpc_event (1) (permet de signaler via xmlrpc les changements de presence d'un utilisateur).

Ce dernier demande l'installation du package erlang-xmlrpc pour fonctionner correctement. Ces derniers modules doivent être compilés puis installés sur le système.

Compilation module ejabberd
  1. On récupère la version qui va bien de ejabberd :
apt-get install -t jessie-backports ejabberd erlang-dev erlang-tools
  1. compilation
(cd mod_muc_admin_extra && mkdir ebin && \
 erlc -o ebin -I /usr/lib/x86_64-linux-gnu/ejabberd-16.02/include \
 -DLAGER -pa /usr/lib/x86_64-linux-gnu/ejabberd-16.02/ebin *.erl )
(cd mod_xmlrpc_event && mkdir ebin && \
 erlc -o ebin -I /usr/lib/x86_64-linux-gnu/ejabberd-16.02/include \
 -DLAGER -pa /usr/lib/x86_64-linux-gnu/ejabberd-16.02/ebin *.erl )
  1. on a maintenant nos modules compilés en .beam dans mod_*/ebin, on peut par exemple les placer à l'emplacement des autres modules

exemple : /usr/lib/x86_64-linux-gnu/ejabberd-16.02/ebin/mod_muc_admin_extra.beam

Exemple de fichier de configuration
## ...
hosts:
    - "mondomaine"
  ## ...
  listen:

      ## ...

    -
      port: 4560
      module: ejabberd_xmlrpc
      access_commands:
        xmlrpc_access:
          commands: all
          options: []

      ### ...
  acl:
    admin:
       user:
           - "admin": "mondomaine"
  ## ...
  access:
      ## ...
      xmlrpc_access:
        admin: allow
      ## ...
  commands_admin_access:   xmlrpc_access
  ## ...
  modules:
    ## ...
    mod_muc_admin: {}
    mod_admin_extra: {}
    ## specials module
    mod_xmlrpc_event: {}
    mod_muc_admin_extra: {}
  ##...
mod_xmlrpc_event:
  host: "localhost" #default : "localhost"
  port: 8123    #default : 8000
  path: "/"  #default : "/"

Configuration Freeswitch

Pour que le module fonctionne, il faut que freeswitch ait le module python ESL. (6)

Celui existe pour python3 pour l'instant uniquement dans pip3 (le paquet debian des dépôts officiels de freeswitch est pour python2) :

pip3 install FreeSWITCH-ESL-Python

Configuration Module python

Il existe pour le moment 2 fichiers de configuration dans le module :

  • l'un pour le module en lui-même : ./xmppophone.ini ou /etc/xmppophone.ini
  • l'autre pour les tests d'integration dans ./xmppophone_integ_tests.ini ou /etc/xmppophone_integ_tests.ini
xmppophone.ini

Cette configuration déterminera le bon fonctionnement du module en production (configuration des connexions avec ejabberd et freeswitch).

Equivalence Architecture (voir schéma) :

  • section [xmpp_listener] -> (2)
  • section [ejabberd] -> (4)
  • section [freeswitch] -> (5)
  • section [xmpp_bot] -> (7)

A noter que le bot xmpp peut utiliser les même informations de connexion XMPP que la connexion à ejabberd.

La section [admins] à pour but de lister les comptes administrateurs pour l'accès aux commandes d'administration du module via XMPP.

La section [appearance] permet de personnaliser le fonctionnement du module.

xmppophone_integ_tests.ini

Le test d'intégration permet de vérifier en partie la bonne configuration du serveur ejabberd.

Pour que le test d'intégration fonctionne correctement, il faut :

  • créer auparavant 2 comptes de test dont un avec la capacité d'accéder aux commandes XML-RPC (voir config Ejabberd).
  • créer un salon xmpp persistant.
  • renseigner ces élements dans xmppophone_integ_tests.ini.
  • remplir le fichier xmppophone.ini correctement.

Les tests d'intégrations utilise les deux fichiers de configurations afin de déterminer les paramètres avec lesquels tester.

Utilisation

Lancement programme après installation :

xmppophone

Divers

Test changement état global d'un utilisateur
usage: xmppophone_cmd [-h] [--show {dnd,away,online,xa,}] user host status

Tests

Les tests peuvent étre effectuer avec nosetests ou py.test pour python3.

Attention !, la commande de tests globale tentera de lancer les tests d'intégration en plus des tests unitaires. Ces derniers nécessites un environnement fonctionnel (notamment une instance d'Ejabberd) et des fichiers de configurations correctements complétés afin de fonctionner.

Lancement tests unitaires
py.test-3 -k"unit_test"

ou

nosetests -I"integ_test"
Lancement tests d'intégration
py.test-3 -k"integ_test"

ou

nosetests -I"unit_test"
source repositoryxmppophone repo
test environmentxmppophone test env
owned byddouard
may be discussed on<not specified>
use license<not specified>