Bord SIP Kamailio (kamailio)
Bord SIP de la téléphonie Navin : SIP sur UDP, TCP et TLS pour les opérateurs et les téléphones, WebSocket sur TLS pour les softphones WebRTC, anti-flood, anti-bruteforce, gestion du NAT, limites d'appels par tenant et dispatcher vers les pools Asterisk et LiveKit SIP. Le routage des tenants vit dans des tables de hachage remplies par Navin Enterprise par JSONRPC et répliquées par DMQ entre les instances.
Généré depuis catalog/services/kamailio.yaml : ne pas modifier à la main.
Résumé
| |
|---|
| Version | 5.7.4 |
| Usage | installer et configurer |
| Couche | fonctionnelle (catalogue IA) |
| Catégorie | Réseau |
| Méthodes d'installation | package |
| Connexion externe | non |
| Réservé au bac à sable | non |
Licence
| |
|---|
| Identifiant SPDX | GPL-2.0-or-later |
| Politique de licence | exception de licence |
| Exception de licence | LEX-025 (en attente de la décision du client) |
| Remarque de licence | GPL-2.0-or-later : un programme séparé joint par SIP et son interface JSONRPC ; aucun code de Kamailio n'est lié à Navin. Le bundle hors ligne redistribue les paquets de la distribution avec leurs notices et leurs sources. |
| Composant de la plateforme | kamailio |
Paquets et artefacts
Un paquet que publie le projet du service (son image, son archive binaire, son paquet Python ou système) porte la licence du service ; un paquet tiers porte la licence écrite sur sa ligne, lue dans les métadonnées officielles du projet amont.
| Type | Paquet | Version | Licence | Détails |
|---|
| paquet système | kamailio | version du dépôt configuré | GPL-2.0-or-later | famille Debian (apt) |
| paquet système | kamailio-autheph-modules | version du dépôt configuré | GPL-2.0-or-later | famille Debian (apt) |
| paquet système | kamailio-tls-modules | version du dépôt configuré | GPL-2.0-or-later | famille Debian (apt) |
| paquet système | kamailio-websocket-modules | version du dépôt configuré | GPL-2.0-or-later | famille Debian (apt) |
| paquet système | python3 | version du dépôt configuré | PSF-2.0 | famille Debian (apt) |
Systèmes et architectures pris en charge
| Méthode | Systèmes d'exploitation | Architectures |
|---|
package | famille Debian (apt) | x86_64, aarch64 (non restreintes par le descripteur) |
- Pas de méthode
package sur la famille RHEL (dnf) : Aucun paquet maintenu de Kamailio n'existe dans RHEL ni dans EPEL 9 et 10 : les paquets RPM ne sont publiés que par le projet Kamailio (rpm.kamailio.org), un dépôt tiers que le bundle hors ligne ne porte pas. Placer le bord SIP sur Ubuntu 24.04 (universe : Kamailio 5.7.4) ou Debian 13 (Kamailio 6.0.1).
- Méthode
package de la famille Debian (apt) limitée à Ubuntu 24.04, Debian 13 : Seuls Ubuntu 24.04 (5.7.4) et Debian 13 (6.0.1) fournissent un Kamailio contre lequel la configuration générée est validée ; Debian 12 (5.6.4) et Ubuntu 22.04 (5.5.4) n'ont pas les modules et paramètres qu'elle utilise.
Unités de la distribution masquées par la méthode package : kamailio.service. Le postinst des paquets les démarre avec la configuration d'origine : juste après l'installation, l'agent les arrête, les désactive et les masque (tâche systemd.mask, seulement si leur fichier d'unité appartient à un paquet installé), et le composant tourne dans sa propre unité navin-<service>-<component>.service. La désinstallation les démasque seulement.
Systèmes hôtes certifiés : RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). Le contrôle préalable des hôtes accepte ces systèmes (une autre version d'une famille connue donne un avertissement, une version en fin de vie est refusée) et les architectures x86_64 et aarch64.
Prérequis
Hôte
Le descripteur ne déclare aucun contrôle préalable de l'hôte.
Programmes que les commandes et les contrôles du service lancent sur l'hôte, hors des racines gérées : les ajouter à allowed_commands de l'agent (voir Sécurité de l'agent Navin), sinon l'agent les refuse avec command_not_allowed : /usr/bin/python3, /usr/sbin/kamailio, /usr/sbin/kamcmd.
Réseau et ports
| Composant | Nom du port | Port | Ouvert dans le pare-feu de l'hôte |
|---|
kamailio | sip | 5060/udp | oui |
kamailio | sip_tcp | 5060/tcp | oui |
kamailio | sips | 5061/tcp | oui |
kamailio | wss | 7443/tcp | oui |
kamailio | jsonrpc | 5071/tcp | oui |
kamailio | metrics | 5073/tcp | oui |
kamailio | dmq | 5062/tcp (mode ha) | oui |
Services et connexions nécessaires
Détail et résolution : voir Dépendances.
Méthodes et modes d'installation
| Méthode | Défaut | Ce que la méthode utilise |
|---|
package | oui | les paquets système du descripteur, installés par le gestionnaire de paquets de l'hôte |
Composants
| Composant | Type | Méthodes d'installation | Ports |
|---|
Kamailio (kamailio) | maître | package | 5060/udp, 5060/tcp, 5061/tcp, 7443/tcp, 5071/tcp, 5073/tcp, 5062/tcp (mode ha) |
Unique (single) (par défaut)
Un seul bord SIP : un point de défaillance unique pour les appels.
Ce que le mode déploie :
| Composant | Placement |
|---|
kamailio | min 1, max 1 |
Haute disponibilité (ha)
Deux instances actives ou plus qui partagent leurs tables de hachage et compteurs d'appels par DMQ ; les opérateurs et les téléphones les joignent par DNS SRV, plusieurs adresses ou un répartiteur réseau.
Ce que le mode déploie :
| Composant | Placement |
|---|
kamailio | min 2, recommandé 2 |
Installer ce service
L'assistant d'installation du Navin Manager planifie, valide et exécute l'installation ; il faut la permission services:install sur le cluster.
-
Ouvrez l'assistant. Dans Clusters, choisissez l'action de ligne Installer des services du cluster cible. L'assistant s'ouvre sur sa première étape, Service.
-
Choisissez le service. À l'étape Service, sélectionnez Bord SIP Kamailio. La carte affiche la licence GPL-2.0-or-later et les dépendances dont l'installation a besoin.
-
Choisissez les hôtes et le mode. À l'étape Hôtes, cochez les hôtes, puis choisissez le Mode : single (par défaut), ha. Chaque mode déploie les composants listés dans Méthodes et modes d'installation.
-
Liez les dépendances. À l'étape Liaisons, choisissez pour chaque dépendance (asterisk, livekit_sip, rtpengine) Installer avec la plateforme ou Utiliser une connexion existante ; une dépendance facultative peut rester sur Aucune liaison.
-
Configurez. À l'étape Configuration, relisez les paramètres (voir Paramètres de configuration). Les mots de passe laissés vides avec une valeur générée par défaut sont générés et scellés par le Manager.
-
Relisez et installez. À l'étape Installation, le Manager valide le plan et affiche l'ordre d'installation ; quand il indique « Le plan est valide. Prêt pour l'installation. », choisissez Installer. Un mode hautement disponible n'est installé que si ses contrôles HA réussissent.
-
Vérifiez. L'opération se termine quand les contrôles de santé de chaque instance réussissent (voir Contrôles de santé) ; le service apparaît alors en marche dans Services.
Haute disponibilité
Prérequis
| Prérequis | Doit être hautement disponible | Modes | Description |
|---|
asterisk | oui | ha | Un pool de deux nœuds Asterisk ou plus, pour que le dispatcher ait un nœud actif suivant pour chaque tenant. |
Topologie par mode
| Modes | Niveau le plus haut du catalogue | Répartition | Composant du quorum | Domaines de panne | Description |
|---|
single | autonome (standalone) | unique (single) | - | 1 | Un bord SIP : sa perte arrête tous les appels et enregistrements. |
ha | ha (ha) | actif-actif (active-active) | - | 2 | Instances actives avec les mêmes tables de hachage (DMQ) ; les opérateurs et les téléphones utilisent une autre adresse quand l'une est perdue. |
Remarques
- La redondance de l'entrée est hors de Kamailio : enregistrements DNS SRV nommant chaque instance, plusieurs adresses de signalisation déclarées chez l'opérateur, ou un répartiteur réseau pour SIP. Une IP virtuelle n'est pas universelle (elle demande un segment L2 commun ou un mécanisme du cloud) et n'est pas configurée ici.
- DMQ réplique les tables de hachage et les profils de dialogue (compteurs d'appels par tenant), ni les transactions ni les connexions TCP, TLS et WebSocket : les dialogues routés par une instance perdue échouent à leur requête suivante (le Record-Route la nomme), téléphones et softphones se réenregistrent sur une autre instance.
- Une instance redémarrée reçoit les tables d'un pair actif au démarrage (dmq_init_sync) ; un redémarrage complet les vide jusqu'à la réconciliation par Navin Enterprise (core.uptime).
Paramètres de configuration
Réseau
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
Port SIP (sip_port) | port | 5060 | - | non | non | oui | SIP sur UDP et TCP pour les opérateurs et les téléphones (public). |
Port SIP TLS (tls_port) | port | 5061 | - | non | non | oui | SIP sur TLS (public), ouvert tant que TLS est actif. |
Port WSS (wss_port) | port | 7443 | - | non | non | oui | SIP sur WebSocket sécurisé pour les softphones WebRTC du portail (public), ouvert tant que TLS est actif. |
Port JSONRPC (admin_port) | port | 5071 | - | non | non | oui | JSONRPC sur /RPC (HTTPS tant que TLS est actif) sur l'adresse d'administration. Le pare-feu de l'hôte ne l'ouvre qu'aux hôtes du cluster et Kamailio répond 403 à toute source hors des réseaux d'administration. |
Port des métriques (metrics_port) | port | 5073 | - | non | non | oui | Métriques Prometheus sur /metrics (xhttp_prom) sur l'adresse d'administration, à part du JSONRPC. |
Port DMQ (dmq_port) | port | 5062 | - | non | non | oui | Réplication entre les instances (KDMQ sur TCP), ouverte aux seuls hôtes du cluster ; Kamailio refuse une requête KDMQ qui ne vient pas d'un nœud DMQ. (ha) |
Adresse SIP (listen_address) | string | (vide) | - | non | non | oui | Adresse d'écoute de SIP, TLS et WSS ; vide : l'adresse de l'hôte. (portée host) |
Adresse annoncée (advertised_address) | string | (vide) | - | non | non | oui | Adresse ou nom public écrit dans Via et Record-Route quand l'hôte est derrière un NAT 1:1 ; vide : aucune. (portée host) |
Adresse d'administration (admin_address) | string | (vide) | - | non | non | oui | Adresse d'écoute du JSONRPC et des métriques ; vide : l'adresse de l'hôte. (portée host) |
Sécurité
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
Réseaux d'administration (admin_networks) | list | [] | - | non | non | non | Réseaux CIDR autorisés sur le JSONRPC en plus de l'hôte lui-même, par exemple les adresses des nœuds Navin Enterprise (10.0.0.21/32) ; toute autre source reçoit 403. |
Réseaux des métriques (metrics_networks) | list | [] | - | non | non | non | Réseaux CIDR autorisés sur /metrics en plus de l'hôte lui-même ; vide : toute source admise par le pare-feu de l'hôte (les hôtes du cluster). |
TLS (tls_enabled) | bool | true | - | non | non | oui | SIP sur TLS, WSS pour les softphones et HTTPS sur le JSONRPC et les métriques, avec le certificat émis par l'autorité du Manager (clé 0640 root et le groupe kamailio). Désactivé : SIP sur UDP et TCP et HTTP en clair seulement, aucun softphone. |
Certificat public (tls_public_cert_file) | string | (vide) | - | non | non | non | Chemin d'un certificat reconnu par les navigateurs et les opérateurs (chaîne complète, PEM) utilisé à la place du certificat du Manager ; vide : le certificat du Manager. (avancé) |
Clé du certificat public (tls_public_key_file) | string | (vide) | - | non | non | non | Chemin de la clé du certificat public, lisible par le groupe kamailio. (avancé) |
Autorités des opérateurs (tls_client_ca_file) | string | /etc/ssl/certs/ca-certificates.crt | - | non | non | non | Autorités vérifiant les opérateurs joints en SIP TLS. (avancé) |
Secret des softphones (ephemeral_secret) | password | généré | - | non | oui | oui | Secret partagé d'auth_ephemeral, généré et conservé dans le coffre du Manager ; Navin Enterprise le lit dans le coffre et remet au navigateur l'utilisateur <expiration>:<extension> et le mot de passe base64(HMAC(secret, utilisateur)). |
HMAC des softphones (ephemeral_algorithm) | enum | sha256 | sha1, sha256, sha384, sha512 | non | non | oui | Empreinte du HMAC des identifiants éphémères (auth_ephemeral sha_algorithm). |
Durée des identifiants (ephemeral_max_ttl_s) | int | 3600 | min 60, max 86400 | non | non | non | Validité la plus longue acceptée pour un identifiant éphémère, en secondes ; une expiration plus lointaine est refusée par 403. |
Secret des nonces (auth_nonce_secret) | password | généré | - | non | oui | oui | Secret des nonces digest (auth secret), commun aux instances pour qu'un défi de l'une soit valable sur les autres. |
Échecs avant bannissement (ban_failures) | int | 10 | min 2, max 1000 | non | non | non | Authentifications refusées (401 ou 407 avec identifiants, 403) d'une adresse externe avant son bannissement (table ipban). |
Durée du bannissement (ban_time_s) | int | 900 | min 60, max 604800 | non | non | non | Secondes pendant lesquelles une adresse reste dans ipban après son dernier échec. |
Seuil d'inondation (pike_density) | int | 30 | min 5, max 10000 | non | non | non | Requêtes d'une adresse externe par tranche de 2 secondes avant que pike ne la bannisse (opérateurs et nœuds internes exemptés). |
Agents des scanners (scanner_user_agents) | list | ["friendly-scanner", "sipvicious", "sipcli", "sip-scan", "VaxSIPUserAgent", "pplsip", "sundayddr", "iWar", "SIVuS", "smap"] | - | non | non | non | Fragments de User-Agent de scanners SIP connus : leurs requêtes sont ignorées sans réponse et la source est bannie. |
Routage
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
Transport interne (internal_transport) | enum | udp | udp, tcp | non | non | oui | Transport vers les nœuds Asterisk et LiveKit SIP du dispatcher. |
Pools dédiés (dedicated_sets) | json | [] | - | non | non | non | Jeux du dispatcher des pools dédiés : une liste de {set (100 ou plus), destinations [hôte:port]} ; Navin Enterprise route un tenant dédié vers son jeu dans tenant_domains et did_routes. |
Intervalle des sondes (probe_interval_s) | int | 10 | min 2, max 300 | non | non | non | Secondes entre deux sondes OPTIONS SIP de chaque destination. |
Sondes en échec (probe_failures) | int | 3 | min 1, max 20 | non | non | non | Sondes en échec avant qu'une destination soit déclarée hors service. |
Sondes réussies (probe_successes) | int | 2 | min 1, max 20 | non | non | non | Sondes réussies avant qu'une destination redevienne active. |
Destinations essayées (dispatcher_attempts) | int | 3 | min 1, max 10 | non | non | non | Destinations du jeu essayées pour un appel (le nœud du tenant d'abord, puis les suivants actifs sur 408, 500 ou 503). |
Limites
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
Appels simultanés par défaut (default_max_calls) | int | 0 | min 0 | non | non | non | Appels simultanés d'un tenant absent de tenant_limits ; 0 : sans limite. |
Appels par seconde par défaut (default_cps) | int | 0 | min 0 | non | non | non | Appels par seconde d'un tenant absent de tenant_limits ; 0 : sans limite. |
Durée des dialogues (max_call_duration_s) | int | 14400 | min 60, max 86400 | non | non | non | Secondes après lesquelles un dialogue sans BYE sort des compteurs d'appels. |
Réglages
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
Processus de travail (workers) | int | 8 | min 1, max 64 | non | non | oui | Processus de travail SIP par écoute UDP et pour TCP. (recommandé max(4, min(32, host.cpu_count * 2))) |
Connexions maximales (max_connections) | int | 4096 | min 64, max 200000 | non | non | oui | Connexions TCP, TLS et WebSocket au plus. |
Mémoire partagée (Mo) (shm_mb) | int | 256 | min 64, max 16384 | non | non | oui | Mémoire partagée de Kamailio (transactions, dialogues, tables de hachage). |
Mémoire privée (Mo) (pkg_mb) | int | 16 | min 8, max 512 | non | non | oui | Mémoire privée de chaque processus Kamailio. |
Niveau de journalisation (log_level) | int | 2 | min -3, max 3 | non | non | non | Niveau debug de Kamailio : de -3 alerte à 3 débogage, 2 info. |
Dépendances
Pour chaque dépendance active, le Manager prend la première solution parmi : la liaison choisie dans l'assistant ; un service de la même installation qui la fournit ; un service déjà installé dans le cluster ; la seule connexion du type attendu. Sinon, une dépendance facultative reste non liée, et une dépendance obligatoire est ajoutée à l'installation dans son mode par défaut (la colonne ci-dessous nomme le service du catalogue ajouté).
| Liaison | Fournie par | Type de connexion | Point d'accès | Facultative | Quand rien n'est lié | Description |
|---|
asterisk | asterisk | - | sip | non | asterisk est ajouté à l'installation | Pool Asterisk partagé : chaque nœud est une destination du jeu 1 du dispatcher, sondée par des OPTIONS SIP. |
livekit_sip | livekit-sip | - | sip | oui | reste non liée (facultative) | Passerelle LiveKit SIP : ses nœuds forment le jeu 2 du dispatcher, la cible des numéros routés vers la branche ai. |
rtpengine | rtpengine | - | ng | oui | reste non liée (facultative) | Relais média optionnel : avec lui, Kamailio ancre le RTP des appels qui ne sont pas WebRTC (rtpengine_manage). |
Points d'accès
| Point d'accès | Schéma | Composant | Port | Chemin | Paramètre TLS | Paramètres de liaison | Secrets de liaison | Commande de provisionnement |
|---|
sip | sip | kamailio | 5060 (sip_port) | - | - | transports, ephemeral_algorithm | ephemeral_secret | - |
sips | sips | kamailio | 5061 (tls_port) | - | tls_enabled | - | - | - |
wss | wss | kamailio | 7443 (wss_port) | - | tls_enabled | - | - | - |
Commandes
| Commande | Composant | Cible | Description |
|---|
Destinations du dispatcher (dispatcher_list) | kamailio | tous les hôtes | Liste les jeux, destinations et états du dispatcher (A actif, I inactif, D désactivé, P sondé). |
Drainer une destination (dispatcher_state) | kamailio | tous les hôtes | Fixe l'état d'une destination sur chaque instance : d la draine (désactivée : aucun nouvel appel ni sonde, les dialogues en cours se terminent normalement), a la remet en service. Un rechargement du dispatcher ou un redémarrage remet toutes les destinations en service. |
Recharger le dispatcher (dispatcher_reload) | kamailio | tous les hôtes | Recharge dispatcher.list sans redémarrer Kamailio. |
Vider une table de hachage (htable_dump) | kamailio | premier hôte | Affiche les entrées d'une table de routage (lecture seule). |
Durée de fonctionnement (uptime) | kamailio | tous les hôtes | core.uptime de chaque instance : un redémarrage vide les tables de hachage jusqu'à la réconciliation par Navin Enterprise. |
Valider la configuration (validate) | kamailio | tous les hôtes | Exécute kamailio -c sur la configuration générée. |
Paramètres des commandes
| Commande | Paramètre | Type | Défaut | Obligatoire | Description |
|---|
dispatcher_state | Jeu (set) | int | - | oui | Jeu du dispatcher (1 Asterisk, 2 LiveKit SIP, 100 ou plus dédié). |
dispatcher_state | Destination (destination) | string | - | oui | URI telle que listée, par exemple sip:pbx1.example.internal:5070. |
dispatcher_state | État (state) | enum | d | non | d draine, a remet en service. |
htable_dump | Table (table) | enum | did_routes | non | Table de hachage à afficher. |
Contrôles de santé
Vivacité (par instance)
| Composant | Contrôle | Détails |
|---|
kamailio | TCP {{ config.listen_address or host.ip or '127.0.0.1' }}:{{ config.sip_port }} | 20 tentatives ; intervalle 1 s ; délai 3 s |
kamailio | HTTP {{ ('https://' ~ host.fqdn) if config.tls_enabled else ('http://' ~ (config.admin_address or host.ip or '127.0.0.1')) }}:{{ config.metrics_port }}/metrics | Attendu 200 ; Attendu kamailio_ ; 20 tentatives ; intervalle 1 s ; délai 3 s |
Disponibilité (contrôle du service)
| Contrôle | Détails |
|---|
/usr/sbin/kamcmd -s unix:{{ paths.data }}/kamailio_ctl dispatcher.list | Attendu SET ; 10 tentatives ; intervalle 3 s ; délai 10 s |
Contrôles préalables
| Contrôle | Type | Signification | Sévérité | Composants |
|---|
sip_port_free | port_free {"param": "sip_port"} | port 5060 libre sur l'hôte | bloquant | tous les composants |
admin_port_free | port_free {"param": "admin_port"} | port 5071 libre sur l'hôte | bloquant | tous les composants |
Sauvegarde et restauration
Export JSON des tables de routage (tenant_domains, did_routes, trunk_hosts, tenant_limits) de la première instance par JSONRPC ; la restauration les réécrit par htable.sets et htable.seti. Navin Enterprise reste la source de vérité et les réconcilie de toute façon ; la table transitoire ipban n'est pas conservée.
| |
|---|
| Format | kamailio-htables |
| Composant | kamailio |
| Fichiers | {{ backup.dir }}/htables.json |
| Test de restauration | oui |
| Instances arrêtées pendant la restauration | oui |
Désinstallation
Chemins supprimés quand les données sont purgées : {{ paths.data }}, {{ paths.log }}.
Documentation amont