TLS/SSL & License Operations

This guide covers two day-to-day operational flows for a Cenvero Stratum node:

Part A — TLS/SSL certificates: how each node gets a trusted certificate for its management API (REST, gRPC and WebSocket all share one cert), how you approve it, and how to operate it online or air-gapped.
Part B — License activation & recovery: how to activate a license, confirm the machine, renew, and bring a reinstalled node back online.

All commands are run on the node with cenvero-str-ctl (the agent's CLI). All approvals happen in your account in the management panel.

Part A — TLS/SSL certificates

The agent serves its management API over TLS and manages the certificate lifecycle for you. There are two ways a node can be certified:

Account CA (recommended): every node gets a leaf certificate signed by your account's certificate authority. Trust your one account root on each machine that talks to the fleet and it then trusts every node — no per-node cert wrangling. This is the mode a registered node uses automatically.
Self-signed (bootstrap / no account CA): until a node has obtained its account-CA certificate it serves a temporary, locally-generated self-signed certificate so the API is never offline. A registered node only ever uses self-signed as a short-lived placeholder while its CA certificate is pending.

The private key never leaves the node

In every flow, the node generates its own private key locally and only ever sends a CSR (certificate signing request) to the panel. Your private key is never transmitted, never stored in the panel, and never leaves the host.

How a node gets its CA-signed certificate

1. Request. The node generates a key + CSR on disk and submits the CSR to the panel. This happens automatically when the node registers (in account-CA mode), or you can trigger it now with:

sudo cenvero-str-ctl tls request

While the request is outstanding, the node keeps serving a **temporary self-signed certificate** so its API stays up.

2. Approve. Open your account and go to Certificates (/account/tls). Your pending request is listed under Requests waiting for you. Before approving, verify it is really your machine — the page shows the bound Hardware ID, which you can compare against the node's own:

cenvero-str-ctl hardware

Click Approve when it matches. (You can also Reject; the node can resubmit later.) The first certificate for any node always needs this manual approval.

3. Collect. The node pulls its signed certificate and hot-swaps it in with no restart. It does this automatically — a node awaiting approval re-checks the panel roughly every 10 minutes — or you can collect it immediately after approving:

sudo cenvero-str-ctl tls pull

Once a healthy CA-signed cert is held, the fast re-check stops; the agent then just renews on the normal schedule (and re-arms the fast pull automatically as expiry approaches).

The certificate is bound to your machine's hardware identity and to the node's registered IP. The addresses on it are set by the panel from the node's registered IP (plus loopback) — addresses in the CSR are never trusted. Domain names are carried only once you have approved them; see *Domain names on the certificate* below.

Trusting your account root

Download your account root certificate from **Certificates › Trust your certificate authority** in your account (or the node trusts its own account root automatically once it installs a CA-signed cert). Install that one root on any machine or client that connects to your fleet, and it will trust every node certificate your account signs — and only those (the root is scoped to your account, not a public CA). The same section shows a one-line trust command for each operating system.

Inspecting the certificate

cenvero-str-ctl tls info

tls info reports the live certificate from the running agent:

mode — ca-signed (your account-CA leaf, what you want) or self-signed (a temporary local cert).
ca_pending — true while the node is still serving the self-signed fallback and waiting for its panel-approved CA certificate.
the certificate expiry and the configured SAN domains.

To see only outstanding requests:

cenvero-str-ctl tls pending-status

This reports any online CA request awaiting approval in the panel, and (separately) any offline CSR written by tls csr that is still awaiting tls install. It is read-only and never touches the live certificate.

Renewal

CA-signed certificates renew automatically before they expire — the node submits a renewal CSR for its existing identity. By default a renewal still needs your approval, but you can switch on automatic certificate renewal for your account (Settings › Certificates): with it on, renewals for an already-approved identity are signed automatically. The first certificate for any node always needs manual approval regardless of this setting, and so does a renewal that asks for a domain name the node was not approved for before.

Domain names on the certificate

The certificate always covers the node's registered IP and loopback. To have it cover a hostname too — a name you have pointed at the node's address — add it on the node:

sudo cenvero-str-ctl tls domain add api.example.net
cenvero-str-ctl tls domain list
sudo cenvero-str-ctl tls domain remove api.example.net

Adding or removing a name makes the node request a new certificate:

Before the current certificate is due for renewal, the new request waits for your approval in Certificates in your account. The approval screen lists the names being asked for, and only those names are signed. If the node changes its names after you open the page, the approval is refused and you are asked to look again.
At renewal, with auto-renew on, a certificate carrying only names you have approved before is signed automatically — so dropping a name costs nothing then. A renewal that adds a name waits for your approval like a first request.
Names must be plain hostnames: letters, digits and hyphens in dot-separated labels. Wildcards (*.example.net) and IP addresses are not accepted as names, and are left off the certificate.

Until the new certificate is approved and collected, the node keeps serving the one it has. On a node with an account-CA certificate, tls domain add therefore ends by reporting "status": "pending" — a successful exit: the name is saved and the request is waiting in Certificates in your account. tls info and tls pending-status show domain_change_pending: true for as long as the certificate being served does not carry the names you have configured.

Once you approve it, the node installs the new certificate on its own within about ten minutes. To collect it straight away:

sudo cenvero-str-ctl tls pull

pull does the same. While the change is still waiting for approval they report it as pending rather than "up to date". If you reject the request the node keeps asking; remove the name (tls domain remove) to withdraw it.

Offline / air-gapped install

For a node that cannot reach the panel, certify it out of band:

1. Generate a key + CSR on the node (the key stays on the node):

sudo cenvero-str-ctl tls csr > node.csr

The CSR is printed to stdout (the private key and CSR are also written under /etc/cenvero-str/tls/).

2. Get the CSR signed against your account CA in the panel — paste it under Certificates › Advanced › Sign your own certificate — and download the signed leaf (plus the chain, if offered).

3. Install the signed certificate on the node, pairing it with the retained key (hot-reloaded, no restart):

sudo cenvero-str-ctl tls install node-leaf.pem chain.pem

The chain file is optional. Installation fails closed: if the signed certificate does not match the pending key, nothing is swapped in.

If a request was rejected or you abandoned the offline flow, clear the pending offline CSR/key (the live certificate is untouched) so you can start a fresh one:

sudo cenvero-str-ctl tls reset-pending

Starting over

To completely re-do a node's certificate — clear the live cert/key and any pending CSR, then obtain a fresh one:

sudo cenvero-str-ctl tls reset
sudo cenvero-str-ctl tls pull

In account-CA mode tls reset submits a new CSR that you must approve again in Certificates in your account; without an account CA it produces a fresh self-signed certificate. Run tls pull afterwards to submit/collect the new certificate immediately, or wait for the next automatic pull.

TLS command reference

Command	What it does
`tls request`	Submit a CA-signing request to the panel now (online).
`tls info`	Show the live cert: mode, expiry, SANs, `ca_pending`, `domain_change_pending`.
`tls pull`	Collect the CA-signed cert now — including one for a changed domain name (no-op if the held cert is current).
`tls pending-status`	Report any pending online CA request or offline CSR.
`tls csr`	Generate a key + CSR locally without contacting the panel (offline).
`tls install <leaf> [chain]`	Install an out-of-band-signed cert, pairing it with the CSR's key.
`tls reset-pending`	Discard a pending offline CSR/key (live cert untouched).
`tls reset`	Clear the live cert + any pending CSR and re-obtain a fresh one.
`tls domain list` / `add <name>` / `remove <name>`	Manage the hostnames on the certificate (adding one needs approval).
`tls regenerate`	Request and install a certificate for the current names now.

A single cenvero-str-ctl pull re-checks both the TLS certificate and the license at once — handy right after you approve a node in the panel.

Part B — License activation & recovery

A license is a digitally signed document that binds your plan and an expiry to a specific machine. The agent verifies it locally on every boot and continuously while running. For the plan/enforcement model and offline behaviour, see Licensing.

Activating a node

1. Send the activation request from the node with your license key:

sudo cenvero-str-ctl license activate CNVR-XXXX-XXXX-XXXX-XXXX

This records a pending per-machine activation for your account — it never auto-issues. The command prints the machine's Hardware ID. (If you have already confirmed this machine, the signed license is returned immediately and installed.)

2. Confirm the machine in your account. Activation is per machine and you confirm each one yourself — Stratum never silently binds a machine. Find the pending activation in your account, verify the Hardware ID matches the node's own (cenvero-str-ctl hardware), and confirm it. Pending activations are listed under Nodes › Needs confirmation.

3. Install the signed license. Once confirmed, the running agent picks up and installs the license automatically. To fetch it immediately instead of waiting:

sudo cenvero-str-ctl license fetch CNVR-XXXX-XXXX-XXXX-XXXX

(Or run cenvero-str-ctl pull to re-sync the license and the TLS cert at once.)

Checking license status

cenvero-str-ctl license status

This is read-only and works offline from the on-disk license. It shows who the license was issued to/by, the serial, plan and release channel; validity (valid-until, the enforcement state, days remaining or days into grace); the full feature catalogue with each capability enabled/disabled; that the license is bound to this machine's hardware identity (and whether this machine matches); and the signing key id.

plan         enterprise
serial       7F3A-21C9-...
issued_to    acme-corp
hardware_id  9b2c… (matches this host)
valid_until  2026-07-04T00:00:00Z
state        active   (27 days remaining)

Renewing

After you renew (extend) the license in the panel, pull the refreshed license to the node:

sudo cenvero-str-ctl license refresh   # alias of `license renew`

Confirmed machines also auto-renew silently before expiry with no action from you, as long as the license and the activation are still valid and within your purchased term. A node in Warning, Grace, or Frozen returns to Active the moment it receives a valid, longer-dated license. (See Licensing → Enforcement for the warn → grace → freeze model.)

Recovery / reinstall

If a node is reinstalled — fresh disk, restored snapshot, or otherwise — it loses its local state, including its credentials and any cached license. To bring it back online:

1. Re-activate with the same license key on the reinstalled host:

sudo cenvero-str-ctl license activate CNVR-XXXX-XXXX-XXXX-XXXX

Because the license is bound to the machine's hardware identity and the hardware is unchanged, the machine is recognised as the one you already confirmed and the signed license is reinstated.

2. Re-register the node. The reinstalled node re-registers automatically using your license key and is re-issued fresh credentials — you do not paste anything by hand; it happens as the agent comes back up.

If the hostname is owned by a different license/customer, re-registration is refused (this protects other tenants).
Once re-registered, the node can pull its CA-signed TLS certificate again.

3. Re-issue the TLS certificate. The reinstalled node has no CA-signed cert yet. Once it has re-registered it submits a fresh CSR; approve it under Certificates in your account (verify the Hardware ID first), then it collects the signed cert as in Part A. Run cenvero-str-ctl pull to do the TLS + license sync immediately.

No re-purchase needed. A reinstall reuses your existing license and node slot — you re-activate and re-register the same machine; you do not buy a new license.

License command reference

Command	What it does
`license activate <key>`	Send this machine's activation request (confirm it in your account).
`license fetch <key>`	Fetch the signed license once the machine is confirmed.
`license status`	Show the full installed-license picture (read-only, offline).
`license renew` / `license refresh`	Force a license renewal for this machine.
`license load <file>`	Load a signed license XML manually.

Next steps

Installation — activation during first-time setup.
Licensing — plans, enforcement, revocation, offline use.
Upgrades — keeping the agent current.

↓ This page as JSON ↓ All documentation as JSON