Renewal
Machines renew their own credentials through the guardian, and the renewal record shows every renewal and every refusal.
- Who
- Nobody: machines renew themselves. Auditors and above read the record
- Where
- Console → Renewals
Renewal Schedule
A machine renews its credential when two thirds of the credential's life has passed, and every time it starts. Renewing does not drop any session. If an attempt fails, the machine tries again every minute.
A machine can renew even after its credential has expired. For example, a machine taken off a shelf after a month renews when it next starts, and keeps its identity and its address.
Your deployment sets how long a machine's credential lasts, up to 90 days. The last third of that time is how long a machine can be offline or unreachable before its credential lapses.
When a renewal fails, the machine never enrols again. Enrolling would give it a new identity and a new address.
Renewal Checks
To renew, the machine calls POST /nodes/<id>/credential on the guardian. The request carries the renewal secret from the machine's manifest and its AnchorID, the machine's identity on the overlay. The guardian then does three things:
- It checks that the machine is still active, that the secret is the one the machine was commissioned with and that the AnchorID belongs to the machine.
- It signs a new credential with the taints the machine was commissioned with. It ignores any taints the machine sends, and a compartment move made in the console does not change them.
- It returns the new credential, the time it ends and the current bootstrap list.
Revoking a machine also stops a renewal in progress. The guardian never hands over the new credential, and the renewal record shows the node was revoked while it renewed.
Credential Lifetimes
Each kind of credential has its own lifetime and renewal:
| Credential | Lasts | Renewed |
|---|---|---|
| A machine's | 90 days by default, and 90 at most. Set it with GUARDIAN_NODE_CREDENTIAL_DAYS | By the machine, at two thirds of its life and at every start |
| A member's, in a sub-realm | As above, but never past its sub-realm's delegation | As above |
| A bootstrap node's | As above, and never cut short to the realm credential's end | As above |
| A sub-realm's delegation | 180 days by default | By the guardian, 14 days before it lapses |
| An admin node's | 7 days. In a sub-realm, never past its delegation | By the guardian, daily |
| The realm credential | See Online, Offline and Expired | Online, by the guardian with VeilNet. Offline, VeilNet hands over a new one |
The guardian refuses to commission a machine into a sub-realm whose delegation has lapsed.
A shorter machine credential means that a revoked machine stops working sooner, but machines renew more often. A block stops a machine faster. See Revocation and Blocks.
Reading the Renewal Record
The renewal record keeps every renewal and every refusal, with the reason and the address the request came from. Auditors and above can read it on the Renewals page, newest first.
Open Renewals and choose Refused. Each row shows the time, the machine and its realm, the reason and the source address.
Guardian console — RenewalsNorthern Commandtier2 · au-ismPlatformDashboardRealmsNodes2RenewalsTelemetryRealmsguardian realm3office14field11lab9DeploymentAccountsStack & complianceSettingsGuardianRenewalsguardian-adminRenewalsEvery time a machine came back for a fresh credential. A bearer of its own, no session, no person.Renewal record412 entries · newest firstAllRenewedRefused↓ Export8 Oct 11:58gateway-3officerenewed—192.0.2.418 Oct 11:42camera-7fieldrenewed—100.64.12.78 Oct 09:16ws-ops-01officerenewed—192.0.2.158 Oct 05:31bootstrap-1guardian realmrenewed—198.51.100.108 Oct 04:17lab-ws-2labrenewed—192.0.2.606 Oct 22:40old-kioskofficerefusedthe node is revoked192.0.2.88Showing 1–20 of 412Rows201
Expiring Machines
The Nodes page marks every machine with a week or less left, and the Expiring filter lists them all. The sidebar shows how many there are next to Nodes. For auditors, it also shows the number of refusals in the last day next to Renewals.
A machine that is only switched off needs no action, because it renews when it next starts. See Renewal Schedule.
If a machine is refused again and again, or should not be renewing at all, revoke it. To shut it out at once, block it as well. See Revocation and Blocks.