CHAPITRE 6 : Provisioning Physique (wazo-provd)
6.1 Introduction à wazo-provd
wazo-provd est le service de provisioning des terminaux physiques. Il génère les fichiers de configuration pour les téléphones SIP, ATA et gateways en se basant sur des plugins.
6.1.1 Architecture de Provisioning
┌─────────────────────────────────────────────────────────────────────────────┐
│ ARCHITECTURE PROVISIONING WAZO │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ PHONE │ │ wazo-provd │ │ wazo-confd │
│ (Boot) │ │ (Serveur) │ │ (Config) │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
│ 1. DHCP Request │ │
│──────────────────────►│ │
│ │ │
│ 2. DHCP Response │ │
│ + HTTP URL │ │
│◄──────────────────────│ │
│ │ │
│ 3. HTTP Provisioning │ │
│ Request │ │
│──────────────────────►│ │
│ │ 4. Get config │
│ │──────────────────────►│
│ │◄───────────────────────│
│ │ │
│ 5. Generate PJSIP │ │
│ + Base config │ │
│◄───────────────────────│ │
│ │ │
│ 6. Apply config │ │
│ (Auto-register) │ │
6.1.2 Composants Clés
| Composant | Description |
|---|---|
| Plugin | Module spécifique à un modèle de téléphone (Snom, Yealink, Polycom) |
| Template | Fichiers de configuration Jinja2 générés par plugin |
| Device | Enregistrement du terminal (MAC, vendor, model) |
| Configuration | Ensemble des paramètres应用到 un device |
6.2 Gestion des Devices
6.2.1 CRUD des Devices
Endpoint
GET/POST /api/provd/0.1/devices
GET/PUT/DELETE /api/provd/0.1/devices/{device_id}
Création d’un Device
curl -k -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: {token}" \
-H "Wazo-Tenant: {tenant_uuid}" \
-d '{
"mac": "001122334455",
"ip": "192.168.1.100",
"vendor": "Snom",
"model": "D345",
"plugin": "snom",
"description": "Telephone Alice",
"template": "standard"
}' \
"https://wazo.example.com:8667/api/provd/0.1/devices"
Payload Détaillé
| Champ | Type | Description |
|---|---|---|
mac |
string |
Adresse MAC du terminal (format: 001122334455) |
ip |
string |
Adresse IP actuelle (optionnel, mis à jour automatiquement) |
vendor |
string |
Fabricant (Snom, Yealink, Polycom, etc.) |
model |
string |
Modèle spécifique |
plugin |
string |
Plugin à utiliser (doit correspondre au vendor) |
template |
string |
Template de configuration |
description |
string |
Description libre |
status |
string |
Statut: autoprov, configured, waiting |
Réponse
{
"id": "device-uuid-001",
"mac": "001122334455",
"ip": "192.168.1.100",
"vendor": "Snom",
"model": "D345",
"plugin": "snom",
"status": "autoprov",
"template": null,
"config_version": null,
"created_at": "2026-03-07T15:30:00.000000Z",
"updated_at": "2026-03-07T15:30:00.000000Z"
}
6.2.2 États d’un Device
| État | Description |
|---|---|
autoprov |
Device détecté, en attente de configuration |
waiting |
En attente de synchronisation |
configured |
Configuration appliquée |
failed |
Échec de configuration |
6.2.3 Liste des Plugins Disponibles
curl -k -X GET \
-H "X-Auth-Token: {token}" \
"https://wazo.example.com:8667/api/provd/0.1/plugins"
{
"items": [
{"name": "snom", "version": "3.3.1"},
{"name": "yealink", "version": "85.0.1.20"},
{"name": "polycom", "version": "5.9.2"},
{"name": "aastra", "version": "3.3.1-SP4"}
]
}
6.3 Mécanisme de Synchronisation
6.3.1 Processus de Synchronisation Complet
La synchronisation est le processus par lequel un terminal téléphone récupère et applique sa configuration.
┌─────────────────────────────────────────────────────────────────────────────┐
│ PROCESSUS DE SYNCHRONISATION │
└─────────────────────────────────────────────────────────────────────────────┘
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ DEVICE │ │ wazo-provd │ │ wazo-confd │
│ (Telephone) │ │ │ │ │
└──────┬───────┘ └──────┬───────┘ └──────────────┘
│ │ │
│ 1. Boot & DHCP │ │
│─────────────────────►│ │
│ │ │
│ 2. HTTP GET │ │
│ /provd/.../mac │ │
│─────────────────────►│ │
│ │ │
│ │ 3. Lookup device │
│ │─────────────────────►│
│ │◄─────────────────────│
│ │ │
│ │ 4. Generate config │
│ │ (Jinja2 templates) │
│ │ │
│ 5. Return config │ │
│ (SIP credentials, │ │
│ proxy, codecs) │ │
│◄─────────────────────│ │
│ │ │
│ 6. Apply & Register│ │
│ to SIP proxy │ │
│ │ │
│ │ 7. REGISTER event │
│ │◄─────────────────────│
6.3.2 Étapes de Synchronisation API
Étape 1 : Associer une Ligne au Device (wazo-confd)
# Créer d'abord la ligne dans confd (voir Chapitre 3)
# ...
# Puis lier la ligne au device dans provd
curl -k -X PUT \
-H "Content-Type: application/json" \
-H "X-Auth-Token: {token}" \
-H "Wazo-Tenant: {tenant_uuid}" \
-d '{"line_id": 42}' \
"https://wazo.example.com:8667/api/provd/0.1/devices/device-uuid-001"
Étape 2 : Appliquer un Template
curl -k -X PUT \
-H "Content-Type: application/json" \
-H "X-Auth-Token: {token}" \
-H "Wazo-Tenant: {tenant_uuid}" \
-d '{"template": "standard"}' \
"https://wazo.example.com:8667/api/provd/0.1/devices/device-uuid-001/config"
Étape 3 : Déclencher la Synchronisation
curl -k -X PUT \
-H "X-Auth-Token: {token}" \
"https://wazo.example.com:8667/api/provd/0.1/devices/device-uuid-001/synchronize"
Attention : La synchronisation déclenche un redémarrage du téléphone. Planifiez cette opération pendant les heures creuses.
Vérification du Statut
curl -k -X GET \
-H "X-Auth-Token: {token}" \
"https://wazo.example.com:8667/api/provd/0.1/devices/device-uuid-001"
{
"id": "device-uuid-001",
"mac": "001122334455",
"ip": "192.168.1.100",
"status": "configured",
"remote_address": "192.168.1.100:5060",
"plugin": "snom",
"template": "standard",
"config_version": 17,
"lines": [
{
"id": 42,
"name": "alice-line-001",
"exten": "1001"
}
],
"updated_at": "2026-03-07T16:00:00.000000Z"
}
6.3.3 Détection Automatique (Auto-provisioning)
Wazo détecte automatiquement les nouveaux appareils via :
- DHCP : Le serveur DHCP informe provd des nouvelles demandes
- HTTP : Le téléphone boot et contacte le serveur provisioning
Pour désactiver l’auto-provisioning :
# Via configuration système
# /etc/wazo-provd/conf.d/custom.yml
enabled_autoprov: false
6.4 Templates de Configuration
6.4.1 Concept des Templates
Les templates définissent la configuration appliquée à un device. Ils utilisent le moteur Jinja2.
Hiérarchie des Templates
┌─────────────────────────────────────────────────────────────────────────────┐
│ HIÉRARCHIE TEMPLATES WAZO │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────┐
│ GLOBAL │
│ (système) │
└────────┬────────┘
│
┌────────┴────────┐
│ │
┌─────▼─────┐ ┌───▼────┐
│ PLUGIN │ │ CUSTOM │
│ Templates │ │Templates│
└─────┬─────┘ └───┬────┘
│ │
└────────┬────────┘
│
┌──────▼──────┐
│ DEVICE │
│ (final) │
└─────────────┘
6.4.2 Création d’un Template Personnalisé
Les templates personnalisés s’ajoutent au niveau du plugin :
# Emplacement des templates
/var/lib/wazo-provd/plugins/wazo-sn
om-3.3.1/templates/
# Créer un template personnalisé
mkdir -p /var/lib/wazo-provd/plugins/wazo-sn
om-3.3.1/templates/custom
Exemple de Template Personnalisé
{# /var/lib/wazo-provd/plugins/wazo-sn
om-3.3.1/templates/custom/base.tpl #}
{% extends "base.tpl" %}
{% block sip_settings %}
{{ parent() }}
phone_setting.display_method: 0
phone_setting.backlight_level: 3
{% endblock %}
6.4.3 Variables de Template
| Variable | Description | Exemple |
|---|---|---|
{{ line.endpoint.username }} |
Identifiant SIP | alice_auth |
{{ line.endpoint.password }} |
Mot de passe SIP | P4ssw0rd! |
{{ line.extension }} |
Numéro interne | 1001 |
{{ wazo_server_ip }} |
IP serveur Wazo | 192.168.1.1 |
{{ wazo_proxy_ip }} |
IP du proxy SIP | 192.168.1.1 |
6.5 Association Ligne-Terminal
6.5.1 Linking Device ↔ Line
L’association device↔line peut se faire de deux manières :
Méthode 1 : Via provd (Provisioning)
# Dans provd - Associer une ligne existante
curl -k -X PUT \
-H "Content-Type: application/json" \
-H "X-Auth-Token: {token}" \
-H "Wazo-Tenant: {tenant_uuid}" \
-d '{"line_id": 42}' \
"https://wazo.example.com:8667/api/provd/0.1/devices/device-uuid-001"
Méthode 2 : Via confd (Configuration)
# Dans confd - Associer un device à une ligne
curl -k -X PUT \
-H "Content-Type: application/json" \
-H "X-Auth-Token: {token}" \
-H "Wazo-Tenant: {tenant_uuid}" \
-d '{"device_id": "device-uuid-001"}' \
"https://wazo.example.com:9486/api/confd/1.1/lines/42/device"
Note : Les deux méthodes synchronisent automatiquement l’autre côté.
6.6 Scénario Complet : Provisioning d’un Téléphone
# =============================================================================
# ÉTAPE 1 : Créer l'endpoint SIP dans confd
# =============================================================================
curl -k -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: {token}" \
-H "Wazo-Tenant: {tenant_uuid}" \
-d '{
"name": "snom-d345-001",
"auth_section_options": [
["username", "alice_sip"],
["password", "S3cur3P4ssw0rd!"]
],
"endpoint_section_options": [
["disallow", "all"],
["allow", "ulaw,alaw,g722"],
["context", "default"]
]
}' \
"https://wazo.example.com:9486/api/confd/1.1/endpoints/sip"
# Réponse : {"uuid": "endpoint-sip-uuid", ...}
# =============================================================================
# ÉTAPE 2 : Créer la ligne SIP
# =============================================================================
curl -k -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: {token}" \
-H "Wazo-Tenant: {tenant_uuid}" \
-d '{
"context": "default",
"name": "alice-line-001",
"protocol": "sip"
}' \
"https://wazo.example.com:9486/api/confd/1.1/lines"
# Réponse : {"id": 42, ...}
# =============================================================================
# ÉTAPE 3 : Lier endpoint à la ligne
# =============================================================================
curl -k -X PUT \
-H "X-Auth-Token: {token}" \
-H "Wazo-Tenant: {tenant_uuid}" \
"https://wazo.example.com:9486/api/confd/1.1/lines/42/endpoints/sip/endpoint-sip-uuid"
# =============================================================================
# ÉTAPE 4 : Créer l'extension
# =============================================================================
curl -k -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: {token}" \
-H "Wazo-Tenant: {tenant_uuid}" \
-d '{
"exten": "1001",
"context": "default"
}' \
"https://wazo.example.com:9486/api/confd/1.1/extensions"
# Réponse : {"id": 88, ...}
# =============================================================================
# ÉTAPE 5 : Lier extension à la ligne
# =============================================================================
curl -k -X PUT \
-H "X-Auth-Token: {token}" \
-H "Wazo-Tenant: {tenant_uuid}" \
"https://wazo.example.com:9486/api/confd/1.1/lines/42/extensions/88"
# =============================================================================
# ÉTAPE 6 : Créer le device dans provd
# =============================================================================
curl -k -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: {token}" \
-H "Wazo-Tenant: {tenant_uuid}" \
-d '{
"mac": "001122334455",
"vendor": "Snom",
"model": "D345",
"plugin": "snom",
"description": "Telephone Alice - Bureau Paris"
}' \
"https://wazo.example.com:8667/api/provd/0.1/devices"
# Réponse : {"id": "device-uuid-001", "status": "autoprov", ...}
# =============================================================================
# ÉTAPE 7 : Associer la ligne au device
# =============================================================================
curl -k -X PUT \
-H "Content-Type: application/json" \
-H "X-Auth-Token: {token}" \
-H "Wazo-Tenant: {tenant_uuid}" \
-d '{"line_id": 42}' \
"https://wazo.example.com:8667/api/provd/0.1/devices/device-uuid-001"
# =============================================================================
# ÉTAPE 8 : Appliquer le template et synchroniser
# =============================================================================
# Appliquer template
curl -k -X PUT \
-H "Content-Type: application/json" \
-H "X-Auth-Token: {token}" \
-H "Wazo-Tenant: {tenant_uuid}" \
-d '{"template": "standard"}' \
"https://wazo.example.com:8667/api/provd/0.1/devices/device-uuid-001/config"
# Synchroniser (déclenche reboot du téléphone)
curl -k -X PUT \
-H "X-Auth-Token: {token}" \
"https://wazo.example.com:8667/api/provd/0.1/devices/device-uuid-001/synchronize"
# =============================================================================
# ÉTAPE 9 : Vérifier le status final
# =============================================================================
curl -k -X GET \
-H "X-Auth-Token: {token}" \
"https://wazo.example.com:8667/api/provd/0.1/devices/device-uuid-001"
# Réponse attendue :
# {
# "id": "device-uuid-001",
# "status": "configured",
# "ip": "192.168.1.100",
# "remote_address": "192.168.1.100:5060",
# "lines": [{"id": 42, "exten": "1001"}]
# }
6.7 Troubleshooting Provisioning
6.7.1 Commandes de Diagnostic
# Voir les logs de provisioning
journalctl -u wazo-provd -f
# Liste des devices avec status
curl -k -H 'X-Auth-Token: {token}' \
"https://wazo.example.com:8667/api/provd/0.1/devices" | jq '.items[].status'
# Vérifier plugin installé
curl -k -H 'X-Auth-Token: {token}' \
"https://wazo.example.com:8667/api/provd/0.1/plugins" | jq '.items[].name'
6.7.2 Problèmes Courants
| Problème | Cause | Solution |
|---|---|---|
Device toujours autoprov |
Plugin manquant | Installer le plugin correspondant |
Échec synchronize |
Timeout réseau | Vérifier connectivité téléphone |
| Pas de registration | Mauvais credentials | Vérifier endpoint SIP dans confd |
| Config non appliquée | Template invalide | Vérifier syntaxe Jinja2 |
Résumé du Chapitre 6
| Ressource | Endpoints Clés | Point Critique |
|---|---|---|
| Device | POST /devices, /devices/{id}/synchronize |
MAC obligatoire |
| Plugin | /plugins |
Doit correspondre au vendor |
| Template | /devices/{id}/config |
Jinja2, hérité plugin |
| Association | PUT /devices/{id} avec line_id |
Sync auto confd↔provd |
| Synchronisation | /devices/{id}/synchronize |
Déclenche reboot |
Résumé des Chapitres 5 & 6
Services Avancés (Chapitre 5)
| Objet | Relations | Clé |
|---|---|---|
| Queue | → Agents, Skills, Schedule | strategy, timeout |
| Ring Group | → Users, Extensions | extension, strategy |
| IVR | → Destinations imbriquées | choices[] |
| Conference | → Extension | pin |
| Schedule | → Timeperiods, Timerules | timezone |
Provisioning (Chapitre 6)
| Objet | Relations | Clé |
|---|---|---|
| Device | → Plugin, Template, Line | mac, status |
| Plugin | → Templates | Vendor/Model |
| Template | → Jinja2 vars | Héritage |
| Synchronisation | → reboot automatique | /synchronize |
Fin des Chapitres 5 et 6 — Suite : Chapitre 7 (CTI, WebSockets, Temps Réel)
Natif
Limité
Chaînage : Récupérez le champ 