Control and Data Planes
Your machines run both the control plane and the data plane, and only renewal requests and telemetry reach your guardian.
Where the Planes Run
The control plane decides who is admitted, where each machine is, which route traffic takes and whom to refuse. The data plane carries the traffic between your machines. In VeilNet, both run on your machines, over the same links.
Your guardian's signer signs each machine's credential, and the machine presents it to its peers. From then on, the peers make every decision among themselves. No service outside the mesh takes part, so no outage outside the mesh can take the network down.
Solid lines show data, sent directly between machines or through a relay that cannot read it. Dashed lines show control traffic on the same links: admission, gossip, routing and the commands the root node issues. Dotted lines show what reaches the guardian: renewal requests and telemetry. The guardian hosts the root node, but no data passes through the guardian.
Checks for Each Plane
Before traffic flows between two machines, each end checks whether they share a realm and whether their taints allow it. Data traffic and control traffic face different checks:
| Traffic | What it carries | What it must pass |
|---|---|---|
| Data | Frames, messages and streams between two machines | Same realm, and one machine's taints must include all of the other's |
| Control | Orders, and advertisements in the realm's knowledge | Same realm only. Taints do not apply |
A machine with taints of its own therefore still receives its realm's controls and still relays for its realm.
Both planes pass through relays in the same way, encrypted end to end. A relay from another realm carries the traffic but cannot read it.
Gossip Controls
Gossip controls are the signed messages that run a realm. They travel from member to member over the mesh, with no server in between. Each member checks every control against the realm tree, and trusts nothing about the member that passed it on.
| Orders | The realm's knowledge | |
|---|---|---|
| What it is | An instruction from one member to one other member. It ends when it is answered | Advertisements that every member stores, each for as long as it lasts |
| Kinds | Telemetry: report your status. Subnets: route these networks. Taints: move to these taints | Blocks, unblocks, and the record a moved machine publishes of its new taints |
| How it travels | Point to point, encrypted end to end, directly or through relays. If there is no route to the target, the order fails at once | Through a tree in which each member hands it to up to eight others, so the whole realm has it in a few rounds. The issuer learns how many members it reached |
| How long | Until the sender stops waiting. That is at most ten minutes, and never after the sender's own credential expires | Until it ends or is lifted. A member that was offline catches up when it reconnects |
| Power needed | telemetry, subnets or taint | block |
On your network, the guardian's root node in each realm issues the gossip controls. The console calls it the admin node.
The root node holds the block, taint or subnets power only for the one action it is carrying out. As a result, no long-lived credential exists that could block or move every machine in a realm. This matters because credentials are revoked by expiry, and a stolen credential with a power works until it lapses.
What Reaches the Guardian
Your guardian receives renewal requests and telemetry, never traffic. Renewal requests and exported telemetry reach the guardian over TLS, on its single published port. Current readings travel over the mesh to the root node in each realm.
- Renewal requests. A machine asks to renew when two thirds of its credential's life has passed, and at every start. If an attempt fails, it retries every minute. The guardian's signer signs a new credential, and the machine installs it without dropping a session. The guardian refuses a machine that you have revoked.
- Exported telemetry, on by default. Each machine sends its metrics and flow records with a separate credential, not the one it renews with. The guardian keeps them for 90 days. A flow record names the peer, the transport, the destination port and both overlay addresses, and counts bytes and packets in each direction. For a circuit that the machine relays, the record names only the two neighbouring hops and counts bytes. The contents of traffic are never sent.
- Current readings, over the mesh. The root node sends a machine a telemetry order, and the machine answers with a report about itself: its uptime, the number of peers it knows, its connections, reachability, MTU, the routes it serves and its own counters. The report never includes the machine's peers, its traffic or the names of its taints.
If the guardian goes down, the network keeps running. Data and admission never pass through the guardian, and every block already issued stays in force on each member that holds it.
Only the tasks that need the guardian wait: commissioning, new commands and renewal. Machines retry renewal every minute, and their credentials last up to 90 days. To see where telemetry appears, see Telemetry in the guardian docs.
Inspecting a Machine
On each machine, conflux controls its anchor through a local control socket. Only the socket's owner can read it, a token protects it, and it cannot listen on the network. Every command below uses that socket:
| Run | To see |
|---|---|
sudo conflux events | Blocks, unblocks and renewals as they reach this machine, and peers as they connect and disconnect |
sudo conflux blocks | The blocks in force in this machine's realm |
sudo conflux metrics | The realm's knowledge on this machine: anchor_knowledge_held, anchor_knowledge_published_total, anchor_knowledge_learned_total and anchor_knowledge_refused_total |
sudo conflux telemetry -from ID | Another member's report about itself, if this machine's credential carries the telemetry power. ID is the full AnchorID that conflux status prints |
sudo conflux status | The telemetry row, which shows where this machine exports its telemetry and what it exports |
A refused order comes back with the rule that refused it and the end that applied the rule, this machine or the target. You can therefore tell a refusal from a fault.
An order with no route to its target fails at once, instead of opening a connection. To give it a route, run sudo conflux connect -to ID first, or wait for a route.