Documentation

Résoudre les problèmes de connexion

Un nœud VIGIL-MESH n'ouvre aucun port entrant : il établit toujours ses connexions vers l'extérieur, se raccorde immédiatement au réseau à travers un relais, puis bascule vers un chemin direct dès qu'il en trouve un. La plupart des blocages tiennent donc à l'une de deux causes : soit le nœud n'est pas allé au bout de son enrôlement et n'a pas d'adresse, soit il est bien connecté mais reste sur le relais faute de chemin direct. Cette page les distingue et donne, pour chacune, une marche à suivre.

Checklist rapide

Avant tout diagnostic approfondi, parcourez ces contrôles dans l'ordre. Ils isolent la couche en cause en quelques minutes : le premier qui échoue indique où chercher.

1
Statut de l'appareil dans la consoleL'appareil apparaît-il en statut actif ? S'il est en attente d'approbation, suspendu, révoqué ou expiré, il ne se connectera pas tant que ce statut n'est pas résolu.
2
Adresse attribuéeLe nœud porte-t-il une adresse mesh (plage 100.64.0.0/10) sur son interface ? Sans adresse, l'enrôlement n'a pas abouti — voir la section dédiée ci-dessous.
3
Sortie réseauLa machine peut-elle joindre l'extérieur ? Le nœud a besoin de sortir vers la vigie. Si l'UDP est filtré, le profil tcp-only prend le relais ; le détail est dans /docs/depannage-nat.
4
Joignabilité d'un pairEnvoyez un ping vers l'adresse d'un autre appareil actif du même réseau. Une réponse confirme que le chemin est établi, même s'il passe encore par le relais.
5
Topologie dans la consoleLa console affiche l'inventaire et les liens, rafraîchis toutes les ~30 secondes. Laissez passer un cycle avant de conclure qu'un appareil est absent.

Le nœud n'obtient pas d'adresse

Si l'interface VIGIL-MESH ne porte aucune adresse en 100.64.x, le nœud n'est pas allé au bout de son enrôlement. Tant que l'appareil n'est pas admis dans le réseau et approuvé, aucune adresse ne lui est attribuée et il ne peut échanger avec personne.

Symptôme	Cause probable	Solution
Aucune adresse 100.64.x sur l'interface	Enrôlement non finalisé	Reprenez la procédure d'enrôlement jusqu'à son terme et vérifiez que l'appareil remonte dans la console.
Appareil « en attente » dans la console	Approbation manquante	Un administrateur du workspace doit approuver l'appareil. Tant qu'il est en attente, il reste sans adresse.
Adresse disparue après un temps	Appareil suspendu, révoqué ou expiré	Vérifiez le statut dans la console ; réactivez ou ré-enrôlez l'appareil selon le cas.
L'appareil n'apparaît nulle part	L'enrôlement n'a jamais atteint la vigie	Vérifiez d'abord la sortie réseau (section suivante et /docs/depannage-nat), puis relancez l'enrôlement.

Pas de chemin direct : le nœud reste sur relais

Un nœud avec une adresse valide qui joint bien ses pairs peut néanmoins router tout son trafic à travers la vigie plutôt que par un chemin direct. La connectivité fonctionne — le relais garantit qu'un échange passe toujours — mais le chemin direct n'a pas pu s'établir. C'est acceptable et parfois inévitable ; ce n'est pas une panne au sens strict, mais cela ajoute un détour par la vigie.

Le mécanisme est décrit en détail dans /docs/chemins-relais : le nœud tente en permanence d'ouvrir un chemin direct de pair à pair, et bascule dessus dès qu'il aboutit. Les causes fréquentes d'échec de cette bascule :

UDP filtré des deux côtés : sans UDP, le chemin direct ne peut pas se former et le trafic reste sur le profil tcp-only via la vigie. Voir /docs/depannage-nat.
NAT strict (symétrique) sur l'un ou l'autre pair : la traversée directe échoue et le relais prend le relais.
Politique d'accès qui n'autorise pas ce lien : le lien direct ne sera pas tenté si la politique l'interdit — vérifiez les règles d'accès dans la console.
Bascule pas encore survenue : le tout premier trafic passe par le relais par conception. Laissez quelques secondes et observez si le chemin direct s'établit.

Questions fréquentes

Mon nœud est joignable mais lent : est-ce un problème ?

Souvent non. Si le trafic passe encore par le relais, il fait un détour par la vigie. Vérifiez dans /docs/chemins-relais si un chemin direct a pu s'établir ; sinon, contrôlez que l'UDP n'est pas bloqué (/docs/depannage-nat).

Dois-je ouvrir un port sur le nœud pour qu'il se connecte ?

Non. Un nœud n'ouvre aucun port entrant : il établit toujours ses connexions vers l'extérieur. Aucune règle de pare-feu entrante n'est à créer côté nœud. Ce qui compte, c'est la sortie.

L'appareil n'apparaît pas dans la console, que faire ?

Patientez d'abord un cycle de rafraîchissement (~30 s). S'il reste absent, l'enrôlement n'a probablement pas atteint la vigie : vérifiez la sortie réseau et relancez l'enrôlement.

Après un changement de Wi-Fi, mes connexions ont-elles été coupées ?

Non, la session migre. Le trafic peut repasser brièvement par le relais le temps de retrouver un chemin direct, mais les connexions en cours ne sont pas réinitialisées.

Lire ensuiteNAT et pare-feu : que vérifier →

In English

A node never opens an inbound port: it always connects outward, joins the mesh immediately through a relay, then switches to a direct path once one is available. Most connection issues fall into two buckets: the node has no address (enrolment or approval incomplete), or it has an address but stays on the relay (no direct path).

Work the quick checklist in order — device status, assigned 100.64.x address, network egress, peer reachability, console topology (refreshed roughly every 30 seconds). The first check that fails tells you where to look.

Sessions migrate across network changes, so a brief hop back through the relay after switching Wi-Fi to cellular is normal, not a failure.