Méthodologie de debug VoIP

L'erreur classique : commencer à tcpdumper avant d'avoir compris quel type de problème on a. On finit avec 200 Mo de pcap et aucune piste. La méthode ci-dessous fait gagner 80% du temps de diag.

La pyramide

Toujours diagnostiquer du bas vers le haut. Si une couche est cassée, toutes celles au-dessus le sont aussi.

       ┌──────────────────────┐
   5   │ Application / Métier │  IVR, file, bouton transfert, voicemail
       ├──────────────────────┤
   4   │     Dialplan         │  contexts, extensions, applications
       ├──────────────────────┤
   3   │   Asterisk PJSIP     │  endpoint, AOR, auth, transport
       ├──────────────────────┤
   2   │      RTP             │  audio, codecs, ports
       ├──────────────────────┤
   1   │    Signal SIP        │  REGISTER, INVITE, BYE, OPTIONS
       ├──────────────────────┤
   0   │   IP / Réseau        │  routes, firewall, NAT, DNS, MTU
       └──────────────────────┘

Devant un ticket, vous remontez la pyramide :

Symptôme	Niveau probable
Le téléphone ne s'enregistre pas	0 ou 1
Le téléphone s'enregistre mais le serveur ne le voit pas joignable	1
Tout se passe bien jusqu'à ce qu'on appelle, l'appel échoue	1 ou 4
Ça sonne mais à la prise on a pas d'audio	0 (NAT) ou 2 (RTP)
Audio dans un sens uniquement	0 (NAT/external_media_address)
Le routage interne ne marche pas (1001 → 1002 KO)	4
Le voicemail ne se déclenche pas	5

Les 5 questions de cadrage

Avant de plonger dans les outils, toujours poser :

1. Depuis quand ? Avant/après une modif ? un reboot ? un dist-upgrade ?
2. Quelle population ? Tous les téléphones / un seul / tous les appels entrants / sortants seulement / appels internes ?
3. Reproductible ? À tous les coups / aléatoire / à des heures précises ? La régularité aide énormément.
4. Quelle action déclenche ? Décrocher / appuyer sur un bouton / transférer ?
5. Le réseau a-t-il changé ? Box remplacée, FAI changé, fibre coupée, VPN ajouté ?

90% du temps, ces 5 questions suffisent à viser la bonne couche.

La règle d'or : isoler

Un bug qu'on ne sait pas reproduire en isolation est un bug qu'on ne sait pas fixer. Toujours essayer de réduire le scope :

• "Pas d'audio sur les portables Yealink uniquement" → c'est pas un problème serveur global, c'est un problème endpoint ou signal WiFi/DECT.
• "Pas d'audio chez tout le monde sur les appels entrants" → c'est global, donc côté trunk ou NAT serveur.

Si vous pouvez pas isoler, créez les conditions d'isolation : faites un appel de test avec un seul softphone connu, sur un seul DID connu, à une heure connue. Lancez les outils de capture seulement à ce moment.

Les outils par couche

Couche 0 — Réseau / IP

Outil	Usage
ping <peer>	latence + perte de paquets
mtr <peer>	localiser où la perte se produit
dig/host	DNS résolution
traceroute -T -p 5060	tester le routage SIP exactement
ss -tunlp	qui écoute sur quel port
ip route	table de routage
iptables -L -n / ufw status	firewall local
tcpdump -i any -nn 'port 5060'	capture brute

Couche 1 — Signal SIP

Outil	Usage
asterisk -rx 'pjsip set logger on'	active le log SIP
asterisk -rx 'pjsip show registrations'	trunks register
asterisk -rx 'pjsip show contacts'	endpoints joignables
asterisk -rx 'pjsip show endpoint <name>'	détail endpoint
asterisk -rx 'pjsip send qualify <name>'	force OPTIONS keepalive
Wireshark → Telephony → VoIP Calls	replay graphique

Couche 2 — RTP

Outil	Usage
asterisk -rx 'rtp set debug on'	logue les paquets RTP
asterisk -rx 'core show channels'	sessions actives
asterisk -rx 'core show channel <chan>'	bridge, codec, taille
Wireshark → Telephony → RTP → Stream Analysis	jitter / loss
Wireshark → Play Streams	écouter le RTP capturé

Couche 3 — PJSIP / Asterisk

Outil	Usage
asterisk -rvvvv	console interactive verbeuse
tail -F /var/log/asterisk/full	logs live
fwconsole reload (FreePBX)	recharger la conf

Couche 4 — Dialplan

Outil	Usage
asterisk -rx 'dialplan show <ext>@<ctx>'	voir le dialplan actif
core set verbose 5 puis appel	trace ligne par ligne
FreePBX → Reports → Asterisk Logfiles	UI alternative

Couche 5 — Application / Métier

C'est de la lecture de logs FreePBX + reproduction manuelle pas-à-pas. Souvent un problème de paramétrage IVR/queue/timing.

Le bench séquentiel

Quand un problème complexe apparaît, voici la liste à dérouler :

1. ping des 2 côtés (téléphone vers serveur, serveur vers gateway/SBC).
2. pjsip show contacts → Contact présent ? Avail time récent ?
3. pjsip show registrations → trunks Registered ?
4. Activer le logger PJSIP côté serveur.
5. Reproduire l'appel test.
6. Désactiver le logger PJSIP. Couper le tail.
7. Lire le trace : INVITE part-il ? 200 OK arrive-t-il ?
8. Si signal OK mais audio KO : rtp set debug on, refaire l'appel, chercher où s'arrêtent les paquets RTP.
9. Si signal KO : remonter à la cause (auth, route, codec).

Avec cette séquence, 95% des cas tombent en moins de 15 min.

La règle "diviser par deux"

Pour un bug intermittent sans cause évidente :

• Désactivez la moitié des paramètres récents → bug persiste ?
• Si oui, c'est dans l'autre moitié. Refaites la moitié.
• Bisection en 5-6 itérations max.

Marche pour : les codecs (désactiver ceux ajoutés récemment), les modules FreePBX (désactiver ceux activés récemment), les règles de firewall, etc.

Garder une trace

Toujours noter dans un fichier ce que vous avez essayé, dans quel ordre, avec quels résultats. Sinon vous re-testerez la même chose 3 fois en oubliant. Un simple ~/diag-2026-05-10.md suffit.

Pour les cas qui prennent plusieurs heures, créer un mini-runbook avec : - Symptôme - Hypothèses testées (avec résultat) - Cause racine identifiée - Fix appliqué - Comment éviter à l'avenir

Ces runbooks sont la base de connaissance qui vous fait gagner du temps les fois suivantes.

Suivant : Lire un trace SIP