Root key
Every organisation on a Nexus Telemetry Fleet server has one root key. It is the key at the top of the organisation’s certificate chain. The root key signs the CA certificates, and the CA certificates sign the collectors’ certificates. See Certificates for the chain, and Best practice for the steps that act on the key.
Root key role
The root key never connects to a collector and no collector ever has it. A collector has the matching root certificate, which is public.
The fleet server does not need the root key from day to day. The root key signs CA certificates in advance, and the fleet server uses those CA certificates to enrol and renew collectors. How far ahead the CA certificates are signed is the signing cover. While there is cover, the root key can be taken off the fleet server and kept somewhere safer, which is the recommended practice. The key is brought back for 2 tasks only: extending the signing cover, and rebuilding a fleet server whose data directory was lost.
Note: the root key is not a backup of the fleet, and restoring it restores the root key only. See Backup and restore for backing up the fleet.
Root key card
The Root key card is on the Certificates page, in the pane opened by the Organisation tile, under the CA certificate card. What it shows depends on the user.
| User | Card shows |
|---|---|
| Owner or Admin of the organisation | The full card, with the actions |
| Operator or Viewer | A Root key card with a green Managed badge, over the line “Held by your organisation’s administrators, backed up and offline. No action needed.”, and an Organisation tile reading Managed by your administrators |
| A reseller, an organisation with customer organisations beneath it, viewing them together | The same card worded for a provider, and Managed by your provider. See Organisations |
No organisation can read or act on another organisation’s root key, or on the fleet server’s own.
States and fingerprint
The badge on the card reads one of 4 states.
| Badge | Colour | Meaning |
|---|---|---|
| Root key: on this server | grey | The key is in the fleet server’s data directory, encrypted. Every fleet server starts here |
| Root key: offline | green | The key has been removed from the fleet server. The fleet runs on signing cover |
| Root key: restored (take offline when done) | amber | The key is back on the fleet server for a task, and is to be removed again afterwards |
| Root key: sealed vault | green | The key was encrypted to the provider’s custody when the organisation was created, and is not on the fleet server |
Green is the recommended state. The Organisation tile reads Root key still on this server until the key is removed, and Root key offline, backed up after.
SHA-256 on the card is the root certificate’s fingerprint. It is public, and it identifies the root that the organisation’s collectors trust. The copy button beside it reads Fingerprint copied after a copy.
Expiry and cover
Root expires is the date the root certificate expires. A new root certificate lasts about 30 years.
Queue covers to is the date the signing cover lasts until, with a rough span and the number of CA certificates signed in advance. Until that date the fleet server enrols and renews on its own.
Recommended next step
Recommended next step is shown while the key is on the fleet server, or
restored to it. It reads Back it up, then take it offline. Restore it once
before
Fleet server root key
The fleet server has a root key of its own. It signs the CA certificates that sign the Fleet Server Certificate, which every collector checks before it connects. The key belongs to the platform organisation, the one that manages the fleet server, and only users with the Owner or Admin role there can open the Fleet server tile. Every other user sees a green tile reading Managed by your provider and No action needed.
Its card is the same as an organisation’s, with 3 differences. It is titled
Transport root key. There is no Recommended next step. And where taking an organisation’s key offline
asks for the organisation’s short name to be typed as confirmation, this key
asks for the word transport. Its backup downloads as
transport-root-bundle.nfkey, and is kept apart from the organisations’
backups.
Managed organisation
On a managed fleet server, the organisation’s root key is encrypted to the provider’s custody when the organisation is created. The card shows Root key: sealed vault, the fingerprint, the expiry and the cover, and no actions. The Organisation tile reads Root key held offline by your provider.
Audit log entries
Every action on a root key writes one entry in the Certificate Audit Log
against fleet-server: Root key backed up, Root key taken offline,
Root key restored, Root key sealed for a root sealed to the
provider’s custody at creation, and Intermediate queue signed when the
cover is extended, by a user or by the fleet server itself. A verify at
the command line writes none.
Initiated By names the organisation’s short name and the user, as
acme/alice, or acme/cli for an action run at the command line, or auto for the fleet server’s own
action. No entry ever records a passphrase or any part of the key.