Documentation
A broadcast domain like a switch, over an encrypted mesh
VIGIL-MESH is an L3 overlay that delivers what every L3 VPN lacks: broadcast. Each network is a logical broadcast domain — broadcast, multicast and link-local IP reach every member as if on a switch, without the fragility of a stretched real L2 (no ARP, no spanning-tree, no MAC learning). Multicast is encrypted end to end, and the relay replicates it without being able to read it.
What works just like on a LAN
On an ordinary local network, your devices find each other on their own: the printer announces itself, the TV appears, the game controller finds the match. That magic doesn't rely on configuration but on broadcast — packets sent "to everyone on the link". This is precisely the layer that L3 VPNs drop, and that VIGIL-MESH restores identically across the encrypted mesh.
Concretely, link-local discovery and announcement protocols cross the network as if they shared a single cable:
- mDNS/Bonjour — printers, Chromecast, AirPlay, file shares
- SSDP/UPnP — TVs, media boxes, home-automation gateways
- WS-Discovery — ONVIF cameras and devices, network scanners
- LLMNR and NetBIOS-NS — legacy name resolution on Windows machines
- LAN games — match and lobby discovery on the local segment
- Business UDP broadcast — announcements from PLCs, sensors and proprietary services
For all of these, the behavior is indistinguishable from an L2: a discovery started from one member reaches the other members of the network, wherever they physically sit.
| On a physical LAN | On your VIGIL network |
|---|---|
| ✓ Printer discovery (mDNS/Bonjour) | ✓ Printer discovery (mDNS/Bonjour) |
| ✓ Chromecast / AirPlay | ✓ Chromecast / AirPlay |
| ✓ LAN games | ✓ LAN games |
| ✓ Business UDP announcements | ✓ Business UDP announcements |
Why VIGIL doesn't stretch a real L2 — and why that's an advantage
Restoring broadcast doesn't mean stretching a real L2 network across the world. The overlay stays resolutely L3: each member gets a TUN interface that carries IP packets. This isn't a limitation you have to accept, it's an engineering decision — everything that makes a stretched L2 fragile is deliberately left out:
- No ARP flooded across the whole mesh, so no address-resolution storm.
- No spanning-tree, so no slow reconvergence and no loops to break.
- No MAC learning, so no table to saturate and no learning flapping.
The principle fits in one sentence: one network = one logical link. VIGIL keeps the best of L2 — broadcast — without inheriting the mechanisms that make an oversized collision domain collapse.
The mesh is ONE link: mDNS arrives with TTL 255 intact
Many link-local protocols protect themselves by requiring a TTL of 255 on reception: if the packet has been routed (and therefore decremented), it is rejected. This is the case for strict mDNS stacks. An overlay that routes naively breaks these protocols without warning.
VIGIL treats the network as a single logical link: the link-local TTL is carried end to end without decrement. An mDNS packet sent with TTL 255 arrives with TTL 255. The receiving stack considers it legitimately local — because, from the broadcast point of view, it is.
Multicast is encrypted, and the relay replicates it without being able to read it
Broadcasting in clear text across a shared relay would defeat the point. Each multicast sender owns its own sender key: a 32-byte ChaCha20-Poly1305 symmetric key, specific to that sender and to a given epoch. It is distributed to authorized members through the end-to-end encrypted sessions — never by the relay.
The key rotates on three occasions: when a group member is revoked, when the sender restarts, and at the latest every 24 hours. A member who has left can therefore no longer decrypt subsequent broadcasts.
On the relay side, the multicast group identifier is only an opaque hash (BLAKE2s). The vigie replicates the packet to the right receivers without knowing which application group it corresponds to, and without ever accessing its content.
No storm, no loop
Broadcast is powerful but dangerous: poorly bounded, it degenerates into a broadcast storm. VIGIL applies a two-stage storm control.
- Per sender: a token bucket of 200 packets/s and 512 kbit/s, applied both on send and on fan-out.
- Per network, on the vigie side: a global ceiling of 2,000 replicated packets/s, regardless of the number of senders.
- Golden rule: a receiver never re-emits a broadcast packet. No loop can form.
- Strict deduplication on the (group, sender index, epoch, counter) quadruplet: a packet duplicated by the mesh is delivered only once.
A runaway sender is throttled at its source; a whole network stays capped at the vigie; and the absence of re-emission by receivers structurally forbids loops.
Automatic subscriptions: your IP stack does the work
You have nothing to declare. The agent acts as a local IGMPv3 (IPv4) and MLDv2 (IPv6) querier on the TUN interface. When an application subscribes to a multicast group, your operating system announces it as on any network — and the agent detects it.
Subscriptions are then propagated automatically across the mesh: a broadcast is only replicated to the members that are actually interested. Zero configuration, zero list of groups to maintain by hand.
It also works offline and TCP-only
Broadcast doesn't depend on the internet. On an island cut off from the rest of the world — an isolated site, a job site with no uplink — mDNS and link-local announcements keep flowing between the verified members present on-site. Local discovery survives the outage.
And where UDP is blocked, a compliance profile carries multicast through a TCP fan-out: broadcast stays functional, encapsulated in the only allowed transport.
The limits, stated plainly
The trust model is stated just as plainly: the guarantee is authenticity at the group level. Any authorized member of a group can send and decrypt that group's broadcasts — which is exactly the model of a physical LAN, where anyone plugged into the switch takes part in the same broadcast domain.