Machine Lifecycle
Learn how a machine on a sovereign network joins, renews its credential and is removed.
Joining the Tree
Membership is a credential with an end date. A machine joins your tree with one file, the manifest, that the guardian prepares for it. A machine cannot enrol itself.
In the guardian console, commission the machine. You need the manager or admin role. Choose the machine's realm and give it a name. You can also set its taints, an address in the realm's range and whether it exports flow records.
The guardian generates the machine's identity, and the guardian's signer signs its credential. You then get one file, the manifest. It holds everything the machine needs to join and to renew its credential.
No secret is shared across the network. If the credential does not verify, the anchor refuses to start.
The taints you set at commissioning stay in the machine's credential, and every renewal grants the same set. To change them in the credential, commission the machine again with a new identity. To move a running machine, see Moving a Running Member.
Credential Renewal
Every machine must renew its credential before it lapses. The guardian renews machines automatically.
- When. A machine renews when two thirds of its credential's life has passed, and at every start. If an attempt fails, it retries every minute. A credential lasts 90 days by default, which is also the maximum, so a machine renews at day 60 and has 30 days to spare.
- How. The machine asks the guardian for a renewal, and the guardian's signer signs a new credential. The machine installs it in its running anchor, and then sends the new credential to every connected peer. No session drops. If a peer has not received the new credential when the old one lapses, the connection to that peer closes.
- After a long absence. A machine that was off past its credential's expiry renews when it next starts. It keeps its identity and its overlay address.
- Not a move. A renewal must admit the same machine to the same realm with the same taints. A renewal that changes any of these is refused.
The deployment sets how long a credential lasts, up to 90 days. The last third gives a machine time to retry if it is offline or unreachable for a while.
To renew at once after an outage, run sudo conflux renew.
Under anchor:, sudo conflux status also shows renew by. This is the next time the machine loses some of its reach, for any reason. Renew before then.
Removing a Machine
VeilNet has no revocation list. You remove a machine by letting its credential expire, or sooner by blocking it.
| Expiry | Block | |
|---|---|---|
| How | Revoke the machine in the guardian console. Its credential is never renewed again | The guardian's root node in the machine's realm issues a block that names it, with or without an end date |
| Takes effect | When the credential lapses. Every peer refuses it from then on, and live connections close | On each member as the block reaches it, including members that were offline |
| The machine | Is refused by its peers. It does not need to be reachable | Keeps running and is not told. Every member treats it as an outsider. It does not need to be reachable |
| The credential | Lapses | Does not change, and still verifies |
| Undone by | Commissioning the machine again, with a new identity | An unblock, or the end of the block |
Revoking a machine also stops its telemetry at once. To remove a machine at once and for good, use both: block it, and revoke it so that it is never renewed.
Expiry is permanent, but it takes as long as the credential has left to run. A block takes effect on each member as it arrives, and lasts until it ends or a member lifts it. A block does not change the credential. Use both to shut a machine out at once and remove it for good.
Cuts in the Tree
A realm itself is never revoked. If the guardian stops renewing the delegation that created a sub-realm, or cannot renew it, the delegation lapses. The tree is then cut at that point, but nothing beneath the cut is removed.
- Everything beneath the cut carries on as a separate tree. Its machines still admit each other, relay, receive their realm's commands and exchange data.
- Live connections across the cut close when the delegation lapses, and no traffic crosses the cut afterwards.
- The branch keeps its addresses, because they do not depend on anything that expires.
- The branch can still delegate further, within its own depth limit.
Each lapsed delegation makes its own cut. Whether two machines can reach each other depends only on the delegations between their two realms. Two machines in the same realm are never cut apart by anything above them.
To check for a cut, run sudo conflux status and read cut depth under anchor:. It shows 0 while every delegation above the machine is current.
The same rule applies at the top of the tree. If your realm credential lapses, nothing inside your tree stops.