{
    "product": "Cenvero Stratum",
    "generated_at": "2026-08-03T07:18:47+00:00",
    "format": "cenvero-docs-v1",
    "document_count": 1,
    "documents": [
        {
            "slug": "tls-and-license",
            "title": "TLS/SSL & License Operations",
            "category": null,
            "url": "https://www.stratum.cenvero.com/docs/tls-and-license",
            "headings": [
                {
                    "level": 1,
                    "text": "TLS/SSL & License Operations"
                },
                {
                    "level": 2,
                    "text": "Part A — TLS/SSL certificates"
                },
                {
                    "level": 3,
                    "text": "The private key never leaves the node"
                },
                {
                    "level": 3,
                    "text": "How a node gets its CA-signed certificate"
                },
                {
                    "level": 3,
                    "text": "Trusting your account root"
                },
                {
                    "level": 3,
                    "text": "Inspecting the certificate"
                },
                {
                    "level": 3,
                    "text": "Renewal"
                },
                {
                    "level": 3,
                    "text": "Offline / air-gapped install"
                },
                {
                    "level": 3,
                    "text": "Starting over"
                },
                {
                    "level": 3,
                    "text": "TLS command reference"
                },
                {
                    "level": 2,
                    "text": "Part B — License activation & recovery"
                },
                {
                    "level": 3,
                    "text": "Activating a node"
                },
                {
                    "level": 3,
                    "text": "Checking license status"
                },
                {
                    "level": 3,
                    "text": "Renewing"
                },
                {
                    "level": 3,
                    "text": "Recovery / reinstall"
                },
                {
                    "level": 3,
                    "text": "License command reference"
                },
                {
                    "level": 2,
                    "text": "Next steps"
                }
            ],
            "word_count": 1793,
            "markdown": "# TLS/SSL & License Operations\n\nThis guide covers two day-to-day operational flows for a Cenvero Stratum node:\n\n- **Part A — TLS/SSL certificates:** how each node\n  gets a trusted certificate for its management API (REST, gRPC and WebSocket all\n  share one cert), how you approve it, and how to operate it online or air-gapped.\n- **Part B — License activation & recovery:**\n  how to activate a license, confirm the machine, renew, and bring a reinstalled\n  node back online.\n\nAll commands are run on the node with `cenvero-str-ctl` (the agent's CLI). All\napprovals happen in your account in the management panel.\n\n---\n\n## Part A — TLS/SSL certificates\n\nThe agent serves its management API over TLS and manages the certificate\nlifecycle for you. There are two ways a node can be certified:\n\n- **Account CA (recommended):** every node gets a leaf certificate signed by\n  **your account's certificate authority**. Trust your one account root on each\n  machine that talks to the fleet and it then trusts *every* node — no per-node\n  cert wrangling. This is the mode a registered node uses automatically.\n- **Self-signed (bootstrap / no account CA):** until a node has obtained its\n  account-CA certificate it serves a temporary, locally-generated self-signed\n  certificate so the API is never offline. A registered node only ever uses\n  self-signed as a short-lived placeholder while its CA certificate is pending.\n\n### The private key never leaves the node\n\nIn every flow, the node generates its **own private key locally** and only ever\nsends a **CSR** (certificate signing request) to the panel. Your private key is\nnever transmitted, never stored in the panel, and never leaves the host.\n\n### How a node gets its CA-signed certificate\n\n**1. Request.** The node generates a key + CSR on disk and submits the CSR to the\npanel. This happens **automatically when the node registers** (in account-CA\nmode), or you can trigger it now with:\n\n```bash\nsudo cenvero-str-ctl tls request\n```\n\nWhile the request is outstanding, the node keeps serving a **temporary\nself-signed certificate** so its API stays up.\n\n**2. Approve.** Open your account and go to **Account → TLS** (`/account/tls`).\nYour pending request is listed there. Before approving, verify it is really\nyour machine — the page shows the bound **Hardware ID**, which you can compare\nagainst the node's own:\n\n```bash\ncenvero-str-ctl hardware\n```\n\nClick **Approve** when it matches. (You can also **Reject**; the node can\nresubmit later.) The first certificate for any node always needs this manual\napproval.\n\n**3. Collect.** The node pulls its signed certificate and hot-swaps it in with no\nrestart. It does this automatically — a node awaiting approval re-checks the\npanel roughly **every 10 minutes** — or you can collect it immediately after\napproving:\n\n```bash\nsudo cenvero-str-ctl tls pull\n```\n\nOnce a healthy CA-signed cert is held, the fast re-check stops; the agent then\njust renews on the normal schedule (and re-arms the fast pull automatically as\nexpiry approaches).\n\n> The certificate is **bound to your machine's hardware identity** and to the\n> node's registered IP. The panel sets the certificate's identity (SAN) itself\n> from the node's registered IP — values in the CSR are not trusted to widen it.\n\n### Trusting your account root\n\nDownload your **account root certificate** from **Account → TLS** (or the node\ntrusts its own account root automatically once it installs a CA-signed cert).\nInstall that one root on any machine or client that connects to your fleet, and\nit will trust every node certificate your account signs — and only those (the\nroot is scoped to your account, not a public CA). The TLS page shows the\ncross-OS trust instructions.\n\n### Inspecting the certificate\n\n```bash\ncenvero-str-ctl tls info\n```\n\n`tls info` reports the **live** certificate from the running agent:\n\n- **mode** — `ca-signed` (your account-CA leaf, what you want) or `self-signed`\n  (a temporary local cert).\n- **ca_pending** — `true` while the node is still serving the self-signed\n  fallback and waiting for its panel-approved CA certificate.\n- the certificate **expiry** and the configured **SAN domains**.\n\nTo see only outstanding requests:\n\n```bash\ncenvero-str-ctl tls pending-status\n```\n\nThis reports any **online CA request** awaiting approval in the panel, and\n(separately) any **offline CSR** written by `tls csr` that is still awaiting\n`tls install`. It is read-only and never touches the live certificate.\n\n### Renewal\n\nCA-signed certificates renew automatically before they expire — the node submits\na renewal CSR for its existing identity. By default a renewal still needs admin\napproval, but you can enable **auto-renew** for your account (a master switch\nunder your account settings): with it on, renewals for an **already-approved**\nidentity are signed automatically. The *first* certificate for any node always\nneeds manual approval regardless of this setting.\n\n### Offline / air-gapped install\n\nFor a node that cannot reach the panel, certify it out of band:\n\n**1. Generate a key + CSR on the node** (the key stays on the node):\n\n```bash\nsudo cenvero-str-ctl tls csr > node.csr\n```\n\nThe CSR is printed to stdout (the private key and CSR are also written under\n`/etc/cenvero-str/tls/`).\n\n**2. Get the CSR signed** against your account CA in the panel — paste it at\n**Account → TLS** (or have an admin sign it manually) — and download the\nsigned leaf (plus the chain, if offered).\n\n**3. Install the signed certificate** on the node, pairing it with the retained key\n(hot-reloaded, no restart):\n\n```bash\nsudo cenvero-str-ctl tls install node-leaf.pem chain.pem\n```\n\nThe chain file is optional. Installation **fails closed**: if the signed\ncertificate does not match the pending key, nothing is swapped in.\n\nIf a request was rejected or you abandoned the offline flow, clear the pending\noffline CSR/key (the live certificate is untouched) so you can start a fresh one:\n\n```bash\nsudo cenvero-str-ctl tls reset-pending\n```\n\n### Starting over\n\nTo completely re-do a node's certificate — clear the live cert/key **and** any\npending CSR, then obtain a fresh one:\n\n```bash\nsudo cenvero-str-ctl tls reset\nsudo cenvero-str-ctl tls pull\n```\n\nIn account-CA mode `tls reset` submits a **new** CSR that you must approve again\nin **Account → TLS**; without an account CA it produces a fresh self-signed\ncertificate. Run `tls pull` afterwards to submit/collect the new certificate\nimmediately, or wait for the next automatic pull.\n\n### TLS command reference\n\n| Command | What it does |\n|---------|--------------|\n| `tls request` | Submit a CA-signing request to the panel now (online). |\n| `tls info` | Show the live cert: mode, expiry, SANs, `ca_pending`. |\n| `tls pull` | Collect the CA-signed cert now (no-op if already held). |\n| `tls pending-status` | Report any pending online CA request or offline CSR. |\n| `tls csr` | Generate a key + CSR locally **without** contacting the panel (offline). |\n| `tls install <leaf> [chain]` | Install an out-of-band-signed cert, pairing it with the CSR's key. |\n| `tls reset-pending` | Discard a pending **offline** CSR/key (live cert untouched). |\n| `tls reset` | Clear the live cert + any pending CSR and re-obtain a fresh one. |\n\n> A single `cenvero-str-ctl pull` re-checks **both** the TLS certificate and the\n> license at once — handy right after you approve a node in the panel.\n\n---\n\n## Part B — License activation & recovery\n\nA license is a digitally signed document that binds your plan and an expiry to a\nspecific machine. The agent verifies it locally on every boot and continuously\nwhile running. For the plan/enforcement model and offline behaviour, see\n[Licensing](/docs/licensing).\n\n### Activating a node\n\n**1. Send the activation request** from the node with your license key:\n\n```bash\nsudo cenvero-str-ctl license activate CNVR-XXXX-XXXX-XXXX-XXXX\n```\n\nThis records a **pending per-machine activation** for your account — it never\nauto-issues. The command prints the machine's Hardware ID. (If you have\nalready confirmed this machine, the signed license is returned immediately and\ninstalled.)\n\n**2. Confirm the machine in your account.** Activation is per machine and you\nconfirm each one yourself — Stratum never silently binds a machine. Find the\npending activation in your account, verify the **Hardware ID** matches the\nnode's own (`cenvero-str-ctl hardware`), and confirm it.\n\n**3. Install the signed license.** Once confirmed, the running agent picks up and\ninstalls the license automatically. To fetch it immediately instead of\nwaiting:\n\n```bash\nsudo cenvero-str-ctl license fetch CNVR-XXXX-XXXX-XXXX-XXXX\n```\n\n(Or run `cenvero-str-ctl pull` to re-sync the license and the TLS cert at\nonce.)\n\n### Checking license status\n\n```bash\ncenvero-str-ctl license status\n```\n\nThis is **read-only** and works offline from the on-disk license. It shows who\nthe license was issued to/by, the serial, plan and release channel; validity\n(valid-until, the enforcement state, days remaining or days into grace); the full\nfeature catalogue with each capability enabled/disabled; that the license is\n**bound to this machine's hardware identity** (and whether this machine matches);\nand the signing key id.\n\n```text\nplan         enterprise\nserial       7F3A-21C9-...\nissued_to    acme-corp\nhardware_id  9b2c… (matches this host)\nvalid_until  2026-07-04T00:00:00Z\nstate        active   (27 days remaining)\n```\n\n### Renewing\n\nAfter you renew (extend) the license in the panel, pull the refreshed license to\nthe node:\n\n```bash\nsudo cenvero-str-ctl license refresh   # alias of `license renew`\n```\n\nConfirmed machines also **auto-renew silently** before expiry with no action from\nyou, as long as the license and the activation are still valid and within your\npurchased term. A node in Warning, Grace, or Frozen returns to Active the moment\nit receives a valid, longer-dated license. (See\n[Licensing → Enforcement](/docs/licensing) for the warn → grace → freeze model.)\n\n### Recovery / reinstall\n\nIf a node is **reinstalled** — fresh disk, restored snapshot, or otherwise — it\nloses its local state, including its **credentials** and any cached license. To\nbring it back online:\n\n**1. Re-activate with the same license key** on the reinstalled host:\n\n```bash\nsudo cenvero-str-ctl license activate CNVR-XXXX-XXXX-XXXX-XXXX\n```\n\nBecause the license is **bound to the machine's hardware identity** and the\nhardware is unchanged, the machine is recognised as the one you already\nconfirmed and the signed license is reinstated.\n\n**2. Re-register the node.** The reinstalled node re-registers automatically\nusing your **license key** and is re-issued fresh credentials — you do not\npaste anything by hand; it happens as the agent comes back up.\n\n- If the hostname is owned by a **different** license/customer, re-registration\n  is refused (this protects other tenants).\n- Once re-registered, the node can pull its CA-signed TLS certificate again.\n\n**3. Re-issue the TLS certificate.** The reinstalled node has no CA-signed cert\nyet. Once it has re-registered it submits a fresh CSR; approve it at\n**Account → TLS** (verify the Hardware ID first), then it collects the signed\ncert as in **Part A**. Run\n`cenvero-str-ctl pull` to do the TLS + license sync immediately.\n\n> **No re-purchase needed.** A reinstall reuses your existing license and node\n> slot — you re-activate and re-register the same machine; you do not buy a new\n> license.\n\n### License command reference\n\n| Command | What it does |\n|---------|--------------|\n| `license activate <key>` | Send this machine's activation request (confirm it in your account). |\n| `license fetch <key>` | Fetch the signed license once the machine is confirmed. |\n| `license status` | Show the full installed-license picture (read-only, offline). |\n| `license renew` / `license refresh` | Force a license renewal for this machine. |\n| `license load <file>` | Load a signed license XML manually. |\n\n---\n\n## Next steps\n\n- **[Installation](/docs/installation)** — activation during first-time setup.\n- **[Licensing](/docs/licensing)** — plans, enforcement, revocation, offline use.\n- **[Upgrades](/docs/upgrades)** — keeping the agent current.\n"
        }
    ]
}