Configure multicast and groups

Multicast groups

A multicast group gathers the members interested in the same broadcast. On the application side, nothing changes compared with a classic LAN: an application subscribes to a group address, sends or receives on that group, and VIGIL takes care of replicating the packets to the subscribed members only. You have no group table to keep by hand.

Link-local broadcast is handled the same way: the VIGIL network behaves as a single logical link, so that broadcast and link-local multicast cross the mesh without being naively routed. The “one network = one logical link” model this behavior rests on is described in /en/docs/l2-multicast.

• A group is identified at the application level by its multicast address; on the relay side, it only appears as an opaque identifier.
• Replication is targeted: a packet destined for a group is only sent to the members actually subscribed to that group, never to the whole network.
• A single network can carry many simultaneous groups — service discovery, business announcements, LAN games — with no cross configuration.

Automatic subscriptions (IGMPv3/MLDv2 querier, zero configuration)

You have no subscription to declare manually. The agent plays the role of local IGMPv3 (IPv4) and MLDv2 (IPv6) querier on each machine's TUN interface. When an application subscribes to a group, the operating system's IP stack announces it exactly as on any network, and the agent detects it immediately.

These subscriptions are then propagated through the mesh, so that the broadcast is only replicated to the members actually interested. There is neither a group list to maintain nor per-machine configuration: the operating system does the subscription work, the agent listens to it and derives the map of members to serve.

1. 1
   An application subscribes to a groupIt joins a multicast address as on an ordinary LAN; no VIGIL parameter is required.
2. 2
   The local querier detects the subscriptionThe agent, IGMPv3/MLDv2 querier on the TUN interface, picks up the announcement emitted by the system's IP stack.
3. 3
   The subscription propagates through the meshThe member is now counted among the group's receivers, and only receives the traffic of the groups it is actually subscribed to.

Storm control

Broadcast is powerful but dangerous: poorly bounded, it degenerates into a broadcast storm. VIGIL applies a two-stage storm control — per sender and per network — complemented by structural safeguards that prevent loops. These are the main ceilings to know if a deployment generates a lot of multicast traffic.

• Per sender: a token bucket of 200 packets/s and 512 kbit/s, applied both to emission and to replication (fan-out).
• Per network, on the vigie side: a global ceiling of 2,000 replicated packets/s, independent of the number of senders.
• Never an echo: a receiver never re-emits a received broadcast packet, which structurally rules out loops.
• Strict deduplication on the quadruple (group, sender index, epoch, counter): a packet duplicated by the mesh is delivered only once.

Broadcast security

Broadcasting in the clear through a shared relay would be a contradiction. Each multicast sender holds its own sender key: a 32-byte ChaCha20-Poly1305 symmetric key, specific to that sender and to a given epoch. It is distributed to the authorized members via the end-to-end encrypted sessions — never through the relay.

The key rotates on three occasions: on the revocation of a group member, on the sender's restart, and at the latest every 24 hours. A member that has left the group can therefore no longer decrypt the following broadcasts. On the relay side, the group identifier is only an opaque hash (BLAKE2s): the vigie replicates the packet to the right receivers on the strength of that identifier, without knowing which application group it corresponds to nor accessing its content.