Documentation
Troubleshooting connection problems
A VIGIL-MESH node opens no inbound port: it always establishes its connections outward, joins the network immediately through a relay, then switches to a direct path as soon as it finds one. Most blockages therefore come down to one of two causes: either the node did not complete its enrolment and has no address, or it is properly connected but stays on the relay for lack of a direct path. This page tells them apart and gives, for each, a course of action.
Quick checklist
Before any deeper diagnosis, run through these checks in order. They isolate the layer at fault in a few minutes: the first one that fails tells you where to look.
- 1Device status in the consoleDoes the device show as active? If it is pending approval, suspended, revoked or expired, it will not connect until that status is resolved.
- 2Assigned addressDoes the node carry a mesh address (100.64.0.0/10 range) on its interface? Without an address, enrolment did not complete — see the dedicated section below.
- 3Network egressCan the machine reach the outside? The node needs outbound access to the vigie. If UDP is filtered, the tcp-only profile takes over; the detail is in /en/docs/depannage-nat.
- 4Peer reachabilitySend a ping to the address of another active device on the same network. A reply confirms the path is established, even if it still goes through the relay.
- 5Topology in the consoleThe console shows the inventory and the links, refreshed roughly every 30 seconds. Let one cycle pass before concluding a device is missing.
The node gets no address
If the VIGIL-MESH interface carries no 100.64.x address, the node did not complete its enrolment. Until the device is admitted into the network and approved, no address is assigned to it and it cannot exchange with anyone.
| Symptom | Probable cause | Fix |
|---|---|---|
| No 100.64.x address on the interface | Enrolment not finalised | Resume the enrolment procedure through to the end and check that the device shows up in the console. |
| Device shown as “pending” in the console | Missing approval | A workspace administrator must approve the device. As long as it is pending, it remains without an address. |
| Address gone after a while | Device suspended, revoked or expired | Check the status in the console; reactivate or re-enrol the device as appropriate. |
| The device appears nowhere | Enrolment never reached the vigie | Check network egress first (next section and /en/docs/depannage-nat), then restart enrolment. |
No direct path: the node stays on the relay
A node with a valid address that reaches its peers fine may nonetheless route all its traffic through the vigie rather than over a direct path. Connectivity works — the relay guarantees an exchange always gets through — but the direct path could not be established. This is acceptable and sometimes unavoidable; it is not a failure strictly speaking, but it adds a detour through the vigie.
The mechanism is described in detail in /en/docs/chemins-relais: the node keeps trying to open a direct peer-to-peer path, and switches to it as soon as it succeeds. Common reasons this switchover fails:
- UDP filtered on both sides: without UDP, the direct path cannot form and traffic stays on the tcp-only profile via the vigie. See /en/docs/depannage-nat.
- Strict (symmetric) NAT on either peer: direct traversal fails and the relay takes over.
- An access policy that does not allow this link: the direct link will not be attempted if policy forbids it — check the access rules in the console.
- Switchover simply not happened yet: the very first traffic goes through the relay by design. Give it a few seconds and watch whether the direct path gets established.