Guardian Stack
The guardian is your organisation's control suite: one stack on your own host that admits every machine, renews every credential and acts on running machines.
What the Guardian Does
The guardian runs your organisation's sovereign network, a tree of realms with your own realm at the top. It holds the realm's key, creates sub-realms, admits machines and keeps every credential current. Only the guardian can admit a machine to your network.
| What it does | How |
|---|---|
| Admits every machine | An operator commissions each machine in the console. The machine joins with its manifest, a single file the guardian issues for it. A machine cannot enrol itself. |
| Renews every credential | Each machine renews its own credential with the guardian. Every renewal also brings the machine's list of bootstrap nodes up to date. |
| Holds the realm's key | The keys of your realm and of every sub-realm stay sealed in the guardian's state store. A key is unsealed only to make one signature. |
| Acts on running machines | The guardian's root node in each realm blocks and unblocks machines, moves them between compartments and sets the networks a gateway serves. Machines hold none of these powers. |
| Shows the fleet | The console shows telemetry from every machine. It also keeps a record of every renewal and every control action, refusals included. |
| Decides who operates it | The guardian manages sign-in, its four roles and the accounts that hold them, under the compliance profile you choose. |
You deploy the guardian on your own host, and VeilNet does not run it. VeilNet issues your realm credential and hands it over on hard media. For an online deployment, VeilNet also renews that credential.
Services in the Stack
The guardian ships as one stack of seven services, which Docker Compose runs on a single host. Every component is open source under a permissive licence, and there is no paid tier. The stack is built to meet three baselines: US DoD, Australian ISM and UK NCSC.
The services sit on two networks:
- An edge network for every service behind the front door, the stack's only entry point.
- An internal network with no route off the host, for the two stores.
Operators and machines reach the guardian through one front door, on port 443. Operators work in the console, which passes each request to the API server. A machine renews with the API server, where the signer signs its credential with the realm's key, unsealed only for that signature. Each machine sends telemetry with its own credential, and the metrics store keeps it. The admin node, the guardian's root node in each realm, also runs in the API server. It dials out to your bootstrap nodes, and nothing dials in to it. The only other outbound call renews the realm credential with VeilNet, for an online deployment only.
| Service | What it does |
|---|---|
| Front door | Terminates TLS on 443/tcp, the only port the stack publishes. It sends each request to sign-in, the console, machine renewal or telemetry. |
| Identity service | Decides who can operate the guardian. It runs on its own, or signs people in through your own identity provider. It shows the system-use notice before every sign-in. |
| Operator console | Where operators commission, revoke and control machines, create sub-realms, manage accounts and view the fleet. |
| API server | Serves the console and handles renewals from machines. The signer and the admin nodes run inside it. |
| Signer, in the API server | Signs every credential the guardian issues. It joins no network. |
| Admin node, one per realm, in the API server | The guardian's own anchor in each realm, also called the root node. It issues the realm's commands and holds no realm key. |
| State and audit store | Stores every realm, machine, renewal, account change and control action, and audits every write. It holds the realm keys, sealed. |
| Telemetry intake | Accepts metrics and flow records from every machine. Each machine reports with its own collector credential. |
| Metrics store | Keeps telemetry for 90 days for the console. It is on the internal network only. |
The Signer and the Admin Node
Two parts of the API server take part in your network for the guardian. The signer signs credentials, and the admin node acts on machines.
The signer
The signer signs every credential the guardian issues: sub-realm delegations, machine credentials, the admin nodes' own credentials and control credentials.
The signer holds no key of its own, and it joins no network. The realm's key stays sealed in the state store. For each signature, the guardian unseals the key and passes it to the signer, and the key is never written anywhere.
If the signer keeps failing, every console page shows this banner: The signer keeps failing. Nothing can be commissioned and no node can renew while it is down. The API server restarts the signer every 30 seconds. To find the cause, check the API container's log.
The admin node (root node)
The root node is the guardian's own anchor in each realm, and it runs inside the stack. The console calls it the admin node. It issues the realm's commands: blocks, compartment moves, telemetry requests and the networks a router serves. It holds no key of its own.
Each realm gets its admin node when the realm is created, and loses it when the realm is archived.
- It only dials out, over UDP, to your bootstrap nodes. Nothing dials in to it, so it needs no published port.
- It carries no data and relays traffic for no one.
- Between actions, it holds only the telemetry power. It asks each member for a report every 30 seconds by default.
- For each operator action, it is lent the one power that the action needs, for ten minutes at most. Each realm runs one action at a time.
Between actions, the admin node holds only the telemetry power. For one block, it is lent the block power as well, for ten minutes at most. When the action is done, it goes back to telemetry only, whether or not the action worked. The block stays in force after the power has gone.
To see whether console control is on, and which powers your realm credential grants, open Settings → Realm control. For how operators act through the admin node, see Realm Control.
Who Renews What
| Who | Renews | If it fails |
|---|---|---|
| VeilNet | Your realm credential, for an online deployment. This is your network's only link to VeilNet. | Nothing in your network stops. The guardian records the failure and retries. |
| The guardian | Your bootstrap nodes' credentials, every sub-realm delegation and every machine's credential. | The machine retries every minute and keeps working with the credential it holds. |
| The guardian | Each admin node's standing credential, daily. The admin node holds this credential between actions. | The guardian tries again at the next round, every 30 seconds by default. |
If the realm credential lapses, your network loses its link to VeilNet, but nothing is revoked. The guardian keeps commissioning, renewing, revoking and blocking, and machines keep exchanging data. See Online, Offline and Expired.
What the Guardian Is Not
- The guardian is not on the data path. Machines exchange data directly or through your bootstrap nodes, encrypted end to end. No traffic between machines passes through the guardian.
- The guardian is not a relay. Anchors choose their own routes, and your bootstrap nodes relay the traffic. The admin nodes relay nothing.
- Machines do not need the guardian at every moment. If the guardian goes down, machines keep exchanging data. Only commissioning, renewal and control wait until it is back. A machine that is due to renew retries every minute. A credential lasts 90 days by default, so the guardian can be down for a long time before any credential lapses.
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.