An operator's console, beside a mesh that runs itself

What a guardian is

Everything the network needs runs on its nodes. They admit each other by checking credential chains, find each other by gossip, route and relay among themselves, and hold each other to the realm's blocks. The one node with authority over the rest is the root node: an anchor with full capability, which holds your realm's key and mints every credential beneath it, sub-realms, machines and renewals alike. The key never leaves it. It also runs the realm's gossip controls: signed orders, and signed entries in the realm's knowledge, blocks among them, that every member holds and passes on.

The guardian runs alongside the root node. Its API has the root node mint, and delivers what it mints. Its console is where operators manage credentials and see the network through the telemetry its machines report. It never issues a gossip control itself.

• It is optional. Without it, an operator mints credentials with the CLI on the root node. Those carry no way to renew: each runs to its expiry, and a replacement is minted and installed before then. The network runs exactly the same.
• It is software you deploy, not a console we operate, so an outage or a policy change on our side never reaches the network.
• It is on no path, control or data. Machines admit and route each other, and exchange data directly or through your own genesis nodes, sealed end to end.
• If it goes down, nothing on the network stops. A machine due to renew retries every minute until the guardian is back, and a credential lasts ninety days by default, so an outage has a long way to run before anything lapses.

The stack, role by role

A guardian ships as one stack of services behind a single front door, each with one job. Every third-party component in it is permissively licensed open source, and there is no paid tier anywhere in the stack. The root node it runs alongside is not part of the stack: it is an anchor like any other, with the realm's key and full capability.

Getting started

A first deployment, from the credential your realm starts from to the first machine on the network. We work through it with you, and Deploying a guardian has the details.

1. 01
   Receive your realm credential

   VeilNet issues the credential your realm starts from. A member of your organisation downloads it, or for an offline deployment it is handed over by hand. It carries your realm's root key, how many levels of sub-realm the realm may have, bootstrap addresses and the digests of each release. An online deployment's also carries the address and token it renews with; an offline one's carries neither. Treat it as the most sensitive thing in the deployment.

2. 02
   Prepare a host

   The guardian ships a stack, not a host. Bring a hardened machine with encrypted storage, accurate time, and your own certificates and log collection, under your own change control.

3. 03
   Choose the settings, then install

   Put the realm credential in place for the root node that runs alongside the stack, which keeps the key and does all the minting. Then choose everything else in the settings file: the compliance profile, how operators will sign in, the guardian's host name, where its certificate comes from, and whether machines report telemetry. Setup checks both before it changes anything, refuses to run without the credential, and brings the stack up.

4. 04
   Replace the bootstrap administrator

   The first sign-in is a bootstrap account. Replace it with your own administrators, send the audit trail to your SIEM, and test the break-glass account before you need it.

5. 05
   Commission the genesis tier

   A few machines in the guardian realm itself, each with a public address. Every other machine finds the network through them, and they relay for everything beneath.

6. 06
   Mint sub-realms, if the credential allows them

   One for each site, department or team, each with an address range. Most realm credentials allow none, and then every machine is commissioned into the guardian realm.

7. 07
   Commission the members

   One commission per machine. Each produces a single file, shown once, for that machine's operator.

8. 08
   Enrol each machine

   On the machine, conflux installs the file and joins. From then on, the machine renews itself through the guardian.

   $ sudo conflux enrol --manifest gateway-3.b64
   $ sudo conflux up

Sign-in and roles

Who may operate a guardian is decided by its own identity service, in one of two modes.

The roles are a ladder, each containing the one below, so each person is granted one. No role changes the deployment's settings from the console, which shows them read-only: they are changed on the host, by editing the settings and running setup again.

Realms

The guardian realm, where the root node lives, is the root of the tree. Whether anything sits beneath it is the realm credential's to decide: it is signed with a number of levels of sub-realm, which its tier names. Tiers 0 and 1, the common case, carry none, so every machine sits in the guardian realm and can exchange data with every other.

Where the credential allows them, sub-realms sit directly beneath the guardian realm, one for each site, department or team, and never beneath each other. Each has an address range of its own choosing. Data never crosses between sub-realms, so two of them can share a range, and a site can keep the address plan it already has.

• The genesis tier lives in the guardian realm: machines with public addresses that every other machine starts from, and that relay for everything beneath. They hold no user data of their own.
• A member needs no public address, and exchanges data only inside its own sub-realm. A gateway and every device that reaches its network belong in the same sub-realm.
• Minting a sub-realm is an admin's, and archiving is not its undo: the level of sub-realm it spends is not given back. A sub-realm is archived once every machine in it has been revoked, and from then its delegation is no longer renewed. Its range never changes, because its machines hold addresses from it.

Commissioning a node

A machine is commissioned, never enrolled. The guardian serves no enrolment route at all. A manager or an admin commissions the machine in the console, the root node mints its credential, and the machine's operator is handed one file. Nothing can be commissioned until the realm credential is loaded, or while the root node is down.

Taints are worth getting right at commissioning time, because they do not change afterwards: the credential commits to the set, and every renewal keeps it. A machine commissioned with none is in its realm's default compartment, so an untainted sub-realm is one flat network, and taints divide it further. How taints work.

Renewal

Every machine renews itself through the guardian at two thirds of its credential's life, and at every start, without dropping a session: the guardian takes the request, the root node mints the fresh credential, and the guardian delivers it. A failed attempt is retried every minute. A machine taken off a shelf after a month renews on its next start, and keeps its identity and its address.

A machine's credential lasts ninety days by default, and at most ninety. A sub-realm's delegation lasts 180 days and is renewed fourteen days before it lapses. A machine in a sub-realm is given whichever ends first, its window or its sub-realm's delegation, and commissioning into a sub-realm whose delegation has lapsed is refused. Without a guardian there is no renewal at all: a credential the root node's CLI mints runs to its expiry.

Revocation: expiry and blocks

Revoking a machine in the console is expiry. The faster stop is a block, which comes from the root node rather than the console. Removing a machine now and for good uses both, where both reach.

Expiry: Revoke in the console

Revoke stops the guardian renewing the machine. Nothing is pushed and there is no list to distribute: the machine keeps working until its credential lapses, and from then every peer refuses it. Its collector credential is removed at once, so its telemetry stops. It is one-way. There is no reinstate, and the manifest of a revoked machine is refused, so a machine that should return is commissioned again, as a new identity. A shorter window shortens the wait, at the cost of more frequent renewals.

Block: when the window is too long

For a machine that must be off the network now, a block makes it an outsider to its realm. It is not stopped and is told nothing: its knock is refused, its connections are closed, nothing is dialled, routed, carried or sealed to it, and what it signs no longer counts. Every member holds the block on disk and hands it to members that were away, so it outlives the credential of whoever issued it. It leaves the machine's own credential untouched, which is why it is not a revocation.

The console never issues a block. It is issued through the gossip controls, from the root node or any member granted the block power. Read the machine's AnchorID back first, and revoke it in the console as well, so that it never comes back when a block with an end runs out. A mistaken block is one unblock away from undone. How blocks work.

Observability

Telemetry is on by default, for the whole deployment: every machine reports its own health to the guardian. Each reports with a collector credential of its own, separate from the one it renews with, so one leaking says nothing about another, and revoking a machine cuts its reporting off at once. A machine never reports traffic, and never what it relays.

The console reads seven gauges for each machine: connections, peers known, neighbours, reachability, overlay MTU, routes served and relay circuits. The counters behind them stay in the metrics store for ninety days, for your own monitoring. A machine that has gone silent reads as blank, never as zero: having no connections and not being heard from mean opposite things.

Online, offline or expired

The realm credential is renewed too, and how depends on what VeilNet issued. It is always in one of three states, and none of them stops the network.

Adopting a fresh credential

A fresh credential for the same realm, renewed or re-issued, goes in place of the old file, and is adopted when the stack's API is restarted. It is adopted only if it was issued later than the one held, and one for another realm is refused, leaving the realm already held running. Every sub-realm delegation is signed afresh from it, and nothing is re-commissioned: the realm's key, every sub-realm and every machine stay as they are.

Deployment

A guardian is one stack on one host, set up by a single script from two inputs: the realm credential and a settings file. Deploying a guardian covers the host's requirements, setup, the sign-in and compliance profiles, an air-gapped install, FIPS, backup and upgrades. In short:

Where next

Conflux is what runs on each machine. The architecture shows where the guardian sits in a private sovereign network as a whole.