{ "product": "Cenvero Stratum", "documentation_url": "https://www.stratum.cenvero.com/docs", "generated_at": "2026-08-03T06:43:14+00:00", "format": "cenvero-docs-v1", "includes_html": false, "document_count": 30, "documents": [ { "slug": "introduction", "title": "Introduction", "category": null, "url": "https://www.stratum.cenvero.com/docs/introduction", "headings": [ { "level": 1, "text": "Introduction" }, { "level": 2, "text": "What you get" }, { "level": 2, "text": "Every node is the same node" }, { "level": 2, "text": "The two bridges" }, { "level": 2, "text": "How a node is managed" }, { "level": 2, "text": "Where to go next" } ], "word_count": 581, "markdown": "# Introduction\n\nCenvero Stratum is a software-defined networking platform for bare-metal\ninfrastructure. It runs your entire network stack — switching and routing,\nDHCP and DNS, load balancing, firewalling, and multi-host clustering — as a\nsingle agent on the servers you already own. There is no external controller to\noperate, no hardware appliance to buy, and no per-port licensing.\n\nA node runs a single agent. It handles packet processing in the kernel, manages\nthe host's network interfaces — putting them back if something changes them\noutside Stratum — and coordinates with its peers in a high-availability cluster.\nThe result is a complete, self-contained fabric that behaves the same on one\nserver or a thousand.\n\n## What you get\n\n- **In-kernel data plane.** Packet processing happens in the kernel on a fast\n path for line-rate forwarding, with an optional kernel module that detects\n out-of-band changes to managed interfaces so the agent reconciles them back to\n their intended configuration.\n- **Batteries included.** DHCP, authoritative DNS, an L4 load balancer, a\n zero-trust firewall, BGP edge routing, and per-tenant bandwidth control ship in\n the box — no add-ons.\n- **Multi-host by default.** Nodes form a high-availability cluster and stretch a\n VXLAN overlay across hosts, racks, and data centers. A workload's endpoint\n keeps its addressing as it moves between hosts.\n- **Operable.** A single configuration file per node, one CLI\n (`cenvero-str-ctl`), and a management panel for fleet-wide releases, updates,\n and licensing.\n\n## Every node is the same node\n\nThere is one kind of node. It hosts workloads and attaches their endpoints to\nthe fabric, *and* it routes traffic between the fabric and the outside world —\nNAT, upstream route exchange, north-south load balancing. You do not pick a node\ntype at install, and any node can take on any of that later.\n\nWhat limits a node is how many interfaces it has free, not what it was\ninstalled as. See [Nodes and Interfaces](/docs/nodes).\n\n> Earlier versions split nodes into Compute and Gateway. That split has been\n> removed, and a node updating from an older version is migrated automatically.\n\n## The two bridges\n\nStratum separates management traffic from workload traffic on every node:\n\n- A **management bridge** — agent control, clustering, and HA signalling.\n- A **workload bridge** — carries workload traffic.\n\nThis keeps the control plane reachable even when workload networks are\nsaturated or misconfigured.\n\n## How a node is managed\n\nThe agent reads a single configuration file per node, keeps its local\nstate on disk, and writes its own logs. You drive it locally with\n`cenvero-str-ctl` and centrally from the management panel.\n\n## Where to go next\n\nIf you are evaluating or learning:\n\n- **[Concepts](/docs/concepts)** — the vocabulary used throughout these docs.\n- **[How Stratum Works](/docs/architecture)** — the components, the packet path, and what survives what.\n\nIf you are deploying:\n\n- **[Installation](/docs/installation)** — get the agent onto a node and activated.\n- **[Quick Start](/docs/quickstart)** — define a network and attach your first endpoint.\n- **[Configuration](/docs/configuration)** — the node configuration model in depth.\n\nIf you are running it:\n\n- **[Operations](/docs/operations)** — logs, updates, health checks, troubleshooting.\n- **[Monitoring](/docs/monitoring)** — which source answers which question.\n- **[Security Model](/docs/security)** — what is enforced, and your hardening checklist.\n- **[Licensing](/docs/licensing)** — plans, activation, and enforcement.\n- **[API Reference](/docs/api)** — the agent's local REST/operator API.\n\nThe whole documentation set is also downloadable as JSON from the\n[documentation index](/docs), for offline reading or indexing.\n\n> Stratum is licensed software. Installation and binary downloads require a\n> valid license — see [Licensing](/docs/licensing) to get one.\n" }, { "slug": "concepts", "title": "Concepts", "category": null, "url": "https://www.stratum.cenvero.com/docs/concepts", "headings": [ { "level": 1, "text": "Concepts" }, { "level": 2, "text": "The building blocks" }, { "level": 2, "text": "Addressing" }, { "level": 2, "text": "Overlays" }, { "level": 2, "text": "Policy and protection" }, { "level": 2, "text": "Traffic control" }, { "level": 2, "text": "Routing" }, { "level": 2, "text": "Clustering" }, { "level": 2, "text": "Licence and lifecycle" }, { "level": 2, "text": "Where to go next" } ], "word_count": 1001, "markdown": "# Concepts\n\nThe words used throughout these docs, and what they mean in Stratum specifically.\nSeveral are general networking terms that carry a narrower meaning here — those\nare the ones worth reading even if the term is familiar.\n\n## The building blocks\n\n**Node** — one physical server running the agent. Nodes are peers, and there is\nonly one kind: every node hosts workloads and routes. What differs between two\nnodes is the interfaces they hold and what you have put on them — see\n[Nodes and Interfaces](/docs/nodes).\n\n**Network** — a subnet the fabric carries, with its own address range, gateway,\nand policy. This is the unit you create first and attach everything else to. A\nnetwork can exist on one node or stretch across many.\n\n**Endpoint** — the attachment point where a workload joins a network. It has an\naddress and a hardware address, and the fabric enforces both: traffic claiming to\ncome from an endpoint must actually match its registration.\n\n**Tenant** — an ownership boundary. Networks, endpoints, and bandwidth allowances\nbelong to a tenant, which is what lets one node carry several customers' traffic\nwithout them reaching each other. Suspending a tenant affects everything under it\nat once.\n\n**Workload** — whatever is using an endpoint: a virtual machine, a container, or a\nphysical host on a port.\n\n## Addressing\n\n**IPAM** *(IP address management)* — the record of which addresses in a network are\nallocated, reserved, or free. Reservations tie an address to a specific hardware\naddress so a workload always gets the same one.\n\n**Floating address** — an address that is not permanently attached to one node.\nIt lives on whichever node currently holds a role, and moves when that role moves.\nThis is how gateway failover keeps a stable address.\n\n**VIP** *(virtual IP)* — the address clients connect to for a load-balanced\nservice. The load balancer accepts traffic on the VIP and distributes it to\nbackends.\n\n## Overlays\n\nThese four terms describe one mechanism, and they are easy to confuse.\n\n**Underlay** — the ordinary network that already connects your nodes. Whatever\ncarries traffic between their real addresses.\n\n**Overlay** — a network Stratum builds *on top of* the underlay so that workloads\non different nodes appear to share a subnet. It exists only as far as the nodes\nare concerned; the underlay sees only traffic between nodes.\n\n**VNI** *(virtual network identifier)* — the number that identifies one overlay.\nNodes sharing an overlay must use the same VNI; different overlays use different\nones, which is what keeps them separate over the same underlay.\n\n**VTEP** *(tunnel endpoint)* — the address a node sends and receives overlay\ntraffic from. In practice this is the node's own address on the underlay. Each\nnode must know the others' VTEPs, or it has nowhere to send overlay traffic — see\n[Networking Overview](/docs/networking/overview).\n\n**Encapsulation** — wrapping an overlay packet inside an underlay packet for the\ntrip between nodes, and unwrapping it on arrival. This is why an overlay packet is\nslightly larger than the payload it carries, and why overlay networks want a\nlittle headroom in the underlay's maximum packet size.\n\n## Policy and protection\n\n**Rule** — one firewall decision: match traffic by direction, address, protocol\nand port, then allow or deny it. Rules are evaluated in priority order.\n\n**Default action** — what happens to traffic no rule matched. Set it to deny for a\nzero-trust posture, where traffic is refused unless something explicitly permits\nit. See [Zero-Trust Firewall](/docs/networking/firewall).\n\n**Stateful** — a firewall that remembers established conversations, so replies to\ntraffic you allowed are permitted without a matching rule in the other direction.\n\n**Connection tracking** — the table of those remembered conversations. It is worth\nknowing this exists because it explains a common surprise: tightening a rule\naffects *new* connections, while ones already established keep going until they\nend or are flushed.\n\n**Anti-spoofing** — enforcing that traffic from an endpoint carries that\nendpoint's registered addresses, so one workload cannot impersonate another.\n\n**Block list** — addresses refused outright, checked before the rules.\n\n## Traffic control\n\n**Shaping** — limiting how much bandwidth something may use. Applied on the way\nout of an interface.\n\n**Quota** — a cap on total volume over a period, as opposed to a rate limit.\n\n**Accounting** — the record of how much traffic something actually used, which is\nwhat billing integrations read.\n\n## Routing\n\n**BGP** — the protocol nodes use to exchange routes with your upstream routers, so\nthe rest of your network learns how to reach the fabric.\nSee [BGP Edge Routing](/docs/networking/bgp).\n\n**Peer / neighbour** — the router on the other end of a BGP session.\n\n**Announce** — offering a network to your peers, so traffic for it is sent to this\nnode.\n\n**NAT** *(network address translation)* — rewriting addresses in transit. Two uses\nhere: letting many private workloads share one public address on the way out, and\npublishing an internal service on a public address and port. See\n[Gateway NAT](/docs/networking/gateway-nat).\n\n## Clustering\n\n**Cluster** — nodes that share configuration and coordinate with each other.\n\n**Leader** — the member that currently accepts changes to shared state. Chosen by\nelection; losing it triggers a new election and does not stop traffic.\n\n**Heartbeat** — the frequent signal between two nodes paired for high\navailability, so each knows the other is alive. Missing several in a row is what\ntriggers failover.\n\n**Failover** — a standby taking over from a failed peer, including the floating\naddress.\n\n## Licence and lifecycle\n\n**Activation** — binding a licence to one specific machine. A licence covers a\nnumber of machines; each is activated separately.\n\n**Enforcement state** — how the agent is currently treating the licence: *active*,\n*warning* as expiry approaches, *grace* just past it, and *frozen*. Frozen blocks\nchanges only — traffic never stops. See [Licensing](/docs/licensing).\n\n**Release channel** — whether a licence runs released builds or pre-release ones.\nThe two must match, and the agent refuses a build from the wrong channel.\n\n**Manifest** — the signed list of available releases the agent checks when looking\nfor an update.\n\n## Where to go next\n\n- **[How Stratum Works](/docs/architecture)** — how these pieces fit together.\n- **[Quick Start](/docs/quickstart)** — put the main ones to use.\n- **[CLI Reference](/docs/cli)** — the commands behind each concept.\n" }, { "slug": "architecture", "title": "How Stratum Works", "category": null, "url": "https://www.stratum.cenvero.com/docs/architecture", "headings": [ { "level": 1, "text": "How Stratum Works" }, { "level": 2, "text": "What happens when you change something" }, { "level": 2, "text": "How traffic moves through a node" }, { "level": 3, "text": "Where a packet can be stopped" }, { "level": 2, "text": "The two networks on every node" }, { "level": 2, "text": "One kind of node" }, { "level": 2, "text": "More than one node" }, { "level": 2, "text": "What survives what" }, { "level": 2, "text": "Where a node keeps its state" }, { "level": 2, "text": "Ways to reach a node" }, { "level": 2, "text": "Where to go next" } ], "word_count": 1145, "markdown": "# How Stratum Works\n\nBackground reading for operating a node: what happens when you run a command,\nhow traffic moves through a node, and what keeps working when something fails.\nNothing here is configured directly — for the commands see the\n[CLI Reference](/docs/cli), and for the vocabulary see [Concepts](/docs/concepts).\n\n## What happens when you change something\n\nEvery change follows the same path, and knowing it explains most of what you will\nsee in practice.\n\nWhen you add a firewall rule, create a network, or set a bandwidth limit, the\nagent checks the request, records it, and applies it to the traffic path. The\ncommand returns once all three have happened — so when a command reports success,\nthe change is already live. There is no separate \"apply\" step and no delay to\nwait out.\n\nApplying a change and carrying traffic are separate jobs. That has one important\nconsequence:\n\n> **If the agent stops, traffic keeps flowing.** Everything already configured\n> stays in force. What you lose is the ability to *change* anything — no new\n> rules, no new networks, no API — until it is running again.\n\nThis is why an expired or revoked licence freezes changes but never drops\ntraffic, and why a node that has lost contact with the panel keeps forwarding\nexactly as it was. It also means a node whose agent has quietly died can look\ncompletely healthy from the outside, which is worth remembering when something\nseems fine but will not accept changes.\n\n## How traffic moves through a node\n\nTraffic is inspected as it arrives and again as it leaves.\n\n**On the way in**, a packet is checked in order, and the cheapest checks come\nfirst so unwanted traffic is discarded before it costs anything:\n\n1. **Obviously unwanted traffic is dropped** at the network card.\n2. **The sender is verified.** On a workload network, a packet must carry the\n address and hardware address the endpoint is registered with. This is what\n stops one workload impersonating another — it is enforced on every packet, not\n assumed.\n3. **Policy is applied** — your firewall rules, in priority order, plus any\n blocked addresses.\n4. **The packet is delivered.** Locally if the destination is on this node, over\n the overlay if it is on another node, or out through the gateway if it is\n leaving the fabric.\n\n**On the way out**, traffic passes the shaping stage, where bandwidth limits and\ntraffic priority apply.\n\nNot every stage runs on every packet: anything you have not enabled is not in\nthe path at all, and a packet that never leaves the fabric never reaches the\ngateway stage.\n\n### Where a packet can be stopped\n\nWhen traffic is not arriving, it was stopped at one of those points, and each has\na different way of showing it:\n\n| Symptom | Likely stage | Where to look |\n|---|---|---|\n| Nothing arrives from one workload | Sender verification | Check the endpoint's registered address and MAC |\n| Some traffic passes, some does not | Firewall policy | `firewall list` — check order and the default action |\n| A change did not take effect on an existing connection | Policy applies to new connections | Existing connections continue until they end; flush them to force re-evaluation |\n| Traffic reaches the node but not the internet | Gateway | `gateway status`, and see [Gateway NAT](/docs/networking/gateway-nat) |\n| Traffic does not reach another node | Overlay | `vxlan peers` — see [Networking Overview](/docs/networking/overview) |\n\n## The two networks on every node\n\nEvery node keeps its own traffic separate from your workloads':\n\n- **`cnv-mgmt-br0`** — the agent's own traffic: the API, clustering, and\n failover signalling.\n- **`cnv-user-br0`** — workload traffic.\n\nThey are separate so a saturated or misconfigured workload network cannot cost\nyou access to the node. If you can reach the management side you can still reach\nthe agent, read its state, and repair the workload side. Keep the management\nnetwork reachable only by operators.\n\nInterfaces Stratum manages start with `cnv-`. The names are short because the\nkernel limits interface names to 15 characters.\n\n## One kind of node\n\nEvery node runs the same agent and does the same work: it hosts workloads and\nattaches them to the fabric, and it moves traffic between the fabric and the\noutside world — address translation, routing to upstream networks, north-south\nload balancing. There is no node type to choose.\n\nNodes differ only in what you give them: the interfaces they hold and the\nworkloads and networks you put on them. A node with nothing attached is an edge\nrouter; a node you never point at an uplink simply forwards nothing outward.\nSee [Nodes and Interfaces](/docs/nodes).\n\n> The Compute/Gateway split from earlier versions has been removed. Nodes\n> updating from an older version are migrated with no operator action.\n\n## More than one node\n\nNodes are peers. There is no controller to install, and no single node whose loss\nstops the others forwarding.\n\n- **A network can span nodes**, so two workloads on different hosts share a\n subnet and keep their addresses if they move between hosts. See\n [Networking Overview](/docs/networking/overview).\n- **Shared configuration** is agreed between cluster members through an elected\n leader. Losing the leader starts an election; it does not interrupt traffic.\n- **Gateway failover**: a pair of nodes watch each other continuously and\n share an address that moves to the survivor. See\n [Gateway High Availability](/docs/clustering/high-availability).\n\n## What survives what\n\n| Event | Traffic | Changes |\n|---|---|---|\n| The agent stops or crashes | Keeps flowing | Blocked until it restarts |\n| The agent is restarted automatically | Keeps flowing | Brief pause |\n| The node reboots | Interrupted, then restored from the node's own records | Resume once started |\n| The licence expires or is revoked | Keeps flowing | Frozen — see [Licensing](/docs/licensing) |\n| The cluster leader is lost | Keeps flowing | Brief pause during the election |\n| Contact with the panel is lost | Keeps flowing | Local changes still work |\n\n## Where a node keeps its state\n\n| Path | Holds |\n|---|---|\n| `/etc/cenvero-str/` | The node's configuration. |\n| `/var/lib/cenvero-str/` | The node's own records and licence material. |\n| `/var/log/cenvero-str/` | Logs. |\n| `/run/cenvero-str/` | Runtime files, recreated on every boot. |\n\n**Back up the first two.** They are what a node needs to come back as itself. See\n[Operations](/docs/operations).\n\n## Ways to reach a node\n\n| Interface | Port | Use |\n|---|---|---|\n| Command line | — | `cenvero-str-ctl`, on the node itself. Always available. |\n| REST API | 7070 | Automation and integrations. Off until you set a token. |\n| gRPC | 7071 | Streaming integrations. |\n| WebSocket | 7072 | Live event feed. |\n\nThe command line works locally and needs no network, so it keeps working when the\nAPI is switched off or misconfigured — which makes it the right tool for\nrecovering a node. See the [Management API Reference](/docs/api) for the network\ninterfaces, and [Operations](/docs/operations) for turning them on.\n\n## Where to go next\n\n- **[Concepts](/docs/concepts)** — the vocabulary used across these docs.\n- **[Security Model](/docs/security)** — what is enforced, and what is yours to configure.\n- **[Networking Overview](/docs/networking/overview)** — networks, overlays, and routing.\n- **[Operations](/docs/operations)** — running, updating, and troubleshooting a node.\n" }, { "slug": "nodes", "title": "Nodes and Interfaces", "category": null, "url": "https://www.stratum.cenvero.com/docs/nodes", "headings": [ { "level": 1, "text": "Nodes and Interfaces" }, { "level": 2, "text": "Compute mode has been removed" }, { "level": 3, "text": "It was not a security boundary" }, { "level": 2, "text": "What a node does" }, { "level": 2, "text": "Interfaces: the thing that actually limits a node" }, { "level": 3, "text": "What that means in practice" }, { "level": 3, "text": "The two forwarding interfaces are not roles" }, { "level": 3, "text": "On a host with one physical card" }, { "level": 2, "text": "Combining interfaces: link bonding" }, { "level": 2, "text": "Reading a node back" }, { "level": 2, "text": "Choosing a layout" }, { "level": 2, "text": "See also" } ], "word_count": 1775, "markdown": "# Nodes and Interfaces\n\nEvery node runs the same agent and does the same job: it carries workloads, enforces policy on their traffic, and routes between the networks it holds and whatever lies beyond them. There is no node type to pick and nothing at install time that decides which of those a node is allowed to do.\n\nWhat actually shapes a deployment is **interfaces** — how many a node has, and what each one is already doing. That is what this page is about.\n\n## Compute mode has been removed\n\nEarlier versions asked each node to be one of two things: *Compute*, which hosted workloads but did not route, or *Gateway*, which routed. **That split is gone. Every node routes.**\n\nYou do not have to do anything about it. A node updating to this version has its configuration rewritten as part of the update — no reinstall, no mode to choose, no command to run. Networks, endpoints, firewall rules, tenants and addressing are untouched, and a node that was already a gateway carries on exactly as before.\n\nWhy it went:\n\n- **It could only be decided once.** The mode was fixed at install and could not be changed afterwards, so getting it wrong meant reinstalling a live, licensed machine to correct a single setting.\n- **Almost nobody actually chose it.** The installer never asked and never wrote the setting, and a node without it was treated as Compute — so nearly every node was Compute by accident rather than by intent.\n- **It broke routed addressing.** A Compute node did not route between networks. On a single-card dedicated server — the common shape — that made routed additional addresses, which is how most providers sell extra IPs, simply not work.\n\n### It was not a security boundary\n\nWorth being explicit about, because it is the one thing people assume they are losing.\n\nCompute mode never decided who may talk to whom. It happened not to route, which closed one path as a side effect — that is not the same as a policy, and it protected nobody deliberately. What keeps traffic separated is enforced in the path the packet is already taking, and does not depend on whether a node routes:\n\n- **Sender verification.** Traffic from an endpoint must carry the address and hardware address that endpoint is registered with, checked on every packet. This is what stops one workload impersonating another.\n- **Firewall policy.** Your rules are applied wherever traffic enters the node, so a rule is in force at every entry point rather than on one interface.\n- **Different customers cannot reach each other.** Traffic between the private networks of two *different* tenants is refused outright, in the packet path, whether or not you have written a single firewall rule. This replaced what the old mode was accidentally doing, and it is stronger: private addresses are not reachable from outside either, so there is no route around it.\n- **Your own networks are yours to decide about.** Two networks belonging to the same tenant are not separated by default — that is the firewall's decision. Set its default action to `deny` and the separation becomes explicit and auditable rather than incidental. See [Zero-Trust Firewall](/docs/networking/firewall) and [Security Model](/docs/security).\n\nOne thing that is deliberately *not* blocked: two workloads reaching each other by their **public** addresses, when both are on the same node. That traffic is turned around inside the node instead of going out to your provider and back — faster, and it never touches your uplink. Blocking it would separate nothing, because a public address is reachable from the internet anyway; it would only make the same conversation slower. It is still fully metered and still bound by every bandwidth limit and quota. See [Gateway NAT](/docs/networking/gateway-nat).\n\n## What a node does\n\nOne node handles all of it:\n\n- **Carries workloads.** Endpoints attach to networks, and the node enforces each endpoint's identity.\n- **Serves the networks it holds.** Addressing, DHCP, DNS, firewall policy, bandwidth limits and quotas.\n- **Routes.** Between its own networks, and out to whatever is upstream — including address translation so a private subnet reaches the internet over one public address, published services, and route exchange with your upstream routers.\n- **Cooperates with its peers.** Shared state, a stretched overlay, and failover of a floating address between a pair of nodes.\n\nNothing on that list is reserved for a particular kind of node. What limits a node is how many interfaces it has free, which is the next section.\n\n## Interfaces: the thing that actually limits a node\n\nThis is the part worth understanding properly, because it — not any node setting — is what constrains a deployment.\n\n**An interface can carry only one fast-path attachment.** They cannot be stacked. So each of these jobs needs its *own* interface:\n\n| Job | Needs its own interface |\n|---|---|\n| Management (agent, cluster, failover signalling) | the management bridge |\n| Workload traffic | the workload bridge |\n| The uplink the node forwards out of | the WAN interface |\n| The inward side it forwards to | the LAN interface |\n| L4 load balancer VIP traffic | a dedicated VIP interface |\n\n> **You do not need a separate physical card for each.** A VLAN sub-interface or a virtual interface counts as its own interface for this purpose. What you cannot do is point two of these jobs at the *same* interface.\n\n### What that means in practice\n\nA node that hosts workloads and nothing else needs two interfaces:\n\n```\ncnv-mgmt-br0 management (agent, cluster, HA channel)\ncnv-user-br0 workloads\n```\n\nA node that also forwards traffic across its edge, and load-balances, needs more, because the uplink, the inward side and the VIP each want their own:\n\n```\ncnv-mgmt-br0 management (the first card is its port)\ncnv-nic-1 the internet-facing uplink\ncnv-nic-2 the inward side\ncnv-nic-3 load-balancer VIP traffic\n```\n\nSo the answer to \"how many cards does this node need?\" is **one per distinct job it is doing** — a node doing more jobs needs more interfaces. Add the load balancer and it needs one more again.\n\nIf you skip the load balancer's interface, everything else still works — you simply have no L4 balancing, and the symptom is a VIP that looks perfectly configured and passes no traffic. See [Load Balancer](/docs/networking/load-balancer).\n\n### The two forwarding interfaces are not roles\n\nThe node's configuration names two interfaces for the forwarding path. They are placements, not roles: the node decides which direction a packet is going from its routing table, not from which setting named an interface. So the question to ask when planning is not \"which one is the WAN\" — it is \"are there two free interfaces\". See [Configuration](/docs/configuration).\n\n### On a host with one physical card\n\nWorth being direct about, because it is the common shape on a dedicated server with a single public address.\n\n**Hosting workloads on one card is fine.** The uplink is enslaved to the management bridge, which carries the host's address, and the workload bridge carries workloads. Two interfaces, one card, nothing contended:\n\n```\ncnv-mgmt-br0 management (holds the host address; cnv-nic-0 is its port)\ncnv-user-br0 workloads\n```\n\n**Forwarding between two separate interfaces is a different matter.** Both sides want their own fast-path attachment, and on a one-card host both candidates are already spoken for: the workload bridge carries the workload attachment, and the management path deliberately carries none at all — attaching workload anti-spoofing to the host's own path has taken a machine off the network before, which is why that exclusion exists.\n\nA VLAN sub-interface or a virtual interface pair is what creates the missing one. **We have not validated that layout, and we would rather say so than hand you a configuration to try on a machine you cannot get back.** If you need it on single-card hosts, talk to us before you build a product around it.\n\n## Combining interfaces: link bonding\n\nBonding is the other half of the interface story. Instead of splitting jobs across interfaces, it joins several physical interfaces into **one logical interface** that the rest of Stratum treats as a single NIC — so a bond can be the workload bridge's uplink, or the interface the node forwards out of.\n\nThere are two modes, and they answer different questions.\n\n| Mode | What it gives you | What it needs |\n|---|---|---|\n| **`active-backup`** | **Survival.** One member carries all traffic; if its link dies, another takes over. Throughput stays that of a single link. | Nothing from your switch — the members can even go to two different switches, which is what protects you from losing one. |\n| **`802.3ad`** (LACP) | **Capacity and survival.** Traffic is spread across all members, so total throughput can exceed one link, and a failed member drops out. | A matching port-channel configured on the switch. Without it the bond will not come up. |\n\n> **Two links does not mean one connection goes twice as fast.** With LACP, traffic is distributed *per conversation* — each connection picks a member and stays on it. Ten connections spread across two links; one large single transfer still rides one link at that link's speed. If you need a single stream faster, you need a faster link, not more of them.\n\nPick `active-backup` when you want redundancy and control nothing about the switch. Pick `802.3ad` when you own the switch configuration and want the aggregate capacity.\n\nThe bond becomes a normal interface once created, so everything in the interface table above applies to it — a bond can hold one job, not several. See [CLI Reference](/docs/cli) for the `bond` commands.\n\n## Reading a node back\n\nTo see what a node is — its hardware id, its agent version, and what it believes about itself:\n\n```bash\ncenvero-str-ctl node info\n```\n\nThe interfaces it uses are in its configuration, which you inspect rather than edit:\n\n```bash\nsudo cenvero-str-ctl config show\n```\n\nSee [Configuration](/docs/configuration) for every field, and how a configuration reaches a node.\n\n## Choosing a layout\n\n| You want | Use |\n|---|---|\n| A single node to learn on, or a self-contained deployment | One node — it hosts workloads *and* reaches the internet |\n| More workload capacity | More nodes in one cluster; each carries workloads and its own policy |\n| No single point of failure at the edge | Two nodes paired for high availability, sharing a floating address that moves to the survivor |\n| A node dedicated to edge traffic | A node with no workloads attached — same software, you simply give it nothing to host |\n\n## See also\n\n- [Gateway NAT & Internet Access](/docs/networking/gateway-nat) — reaching the internet and publishing services.\n- [Load Balancer](/docs/networking/load-balancer) — why the L4 balancer needs its own interface.\n- [BGP Edge Routing](/docs/networking/bgp) — exchanging routes with upstream routers.\n- [Gateway High Availability](/docs/clustering/high-availability) — a redundant pair sharing a floating address.\n- [Configuration](/docs/configuration) — the interface fields, and how configuration is delivered.\n" }, { "slug": "installation", "title": "Installation and First Configuration", "category": null, "url": "https://www.stratum.cenvero.com/docs/installation", "headings": [ { "level": 1, "text": "Installation and First Configuration" }, { "level": 2, "text": "Before you begin" }, { "level": 2, "text": "1. Get a licence key" }, { "level": 2, "text": "2. Check the kernel first" }, { "level": 2, "text": "3. Run the installer" }, { "level": 3, "text": "Unattended install" }, { "level": 2, "text": "4. Know what you just installed" }, { "level": 2, "text": "5. Activate the node" }, { "level": 2, "text": "6. See what is actually running" }, { "level": 2, "text": "7. Understand what is exposed" }, { "level": 2, "text": "8. Turn on the management API — only if you need it" }, { "level": 3, "text": "Generate one on the node" }, { "level": 3, "text": "Supply your own instead" }, { "level": 3, "text": "Check or remove it" }, { "level": 3, "text": "At install time, if you prefer" }, { "level": 3, "text": "Then enable the APIs you want" }, { "level": 2, "text": "9. Get the node its certificate" }, { "level": 2, "text": "10. Configure the node's job" }, { "level": 2, "text": "Verify the install" }, { "level": 2, "text": "Troubleshooting" }, { "level": 2, "text": "Where to go next" }, { "level": 2, "text": "Take this guide with you" } ], "word_count": 2701, "markdown": "# Installation and First Configuration\n\nThis is the complete guide: a bare server at the start, a licensed node carrying\nreal traffic at the end. Work through it in order. Nothing here assumes you have\nused Stratum before.\n\nThere are two halves. **Install** (steps 1–5) gets the agent running and\nlicensed. **Configure** (steps 6–10) is the part people skip and then wonder why\nnothing responds — a freshly installed node deliberately starts with almost\neverything switched off.\n\n## Before you begin\n\n| Requirement | Detail |\n|-------------|--------|\n| Operating system | Debian 11+, Ubuntu 22.04+, RHEL 8+, Rocky Linux 8+, or AlmaLinux 8+ |\n| Kernel | 5.8 or newer with kernel type information enabled (`CONFIG_DEBUG_INFO_BTF=y`) |\n| Architecture | x86-64 (amd64) or arm64 |\n| Privileges | `root` — the agent manages interfaces and loads the in-kernel data plane |\n| Network | Outbound HTTPS to your panel |\n| Interfaces | One is enough to start. Two (management + workload) is the recommended layout |\n| Licence | A valid key. The download itself is gated on it |\n\nA stock Debian 12 kernel is **older than this** and will not run the data plane.\nThe installer checks before it changes anything — see step 2.\n\n## 1. Get a licence key\n\nYou cannot download anything without one. The key gates the installer, the\nbinaries, and every later update.\n\nRegister on the site, place an **order** for the plan and node count you want,\nfollow the payment instructions, and submit your transaction reference and\nproof. Payment is verified by a person, and the licence is issued once it is —\nlicences are never handed out automatically. It then appears in your account\nwith its key.\n\nSee [Licensing](/docs/licensing) for the full model, and\n[Your Account](/docs/your-account) for where the key lives.\n\n## 2. Check the kernel first\n\nThe data plane runs inside the kernel, so the kernel has to be new enough. The\ninstaller does not guess: it loads the real data plane as a dry run before\ntouching your system, and stops if that fails.\n\nIf your kernel is too old, it tells you and offers three ways forward:\n\n- **Auto-upgrade** — installs a newer kernel, reboots, and resumes the install by itself.\n- **Show commands and stop** — prints exactly what to run, and changes nothing.\n- **Abort** — nothing is touched.\n\nA piped, non-interactive install never reboots you silently. It stops with the\nmanual instructions unless you explicitly ask otherwise with\n`CENVERO_KERNEL_UPGRADE=auto`.\n\n## 3. Run the installer\n\n```bash\ncurl -sSL -H \"X-License-Key: YOUR_LICENSE_KEY\" \\\n https://stratum.cenvero.com/install | bash\n```\n\nSubstitute your own key, and your own panel host if you self-host. The key can\nalso travel as `?key=YOUR_LICENSE_KEY` in the URL or as an\n`Authorization: Bearer YOUR_LICENSE_KEY` header — prefer the header, since URLs\nend up in logs.\n\nEvery artifact is verified before it is written to disk: it must match the\nchecksum the panel advertises over TLS, **and** carry a valid publisher\nsignature. An artifact that fails either check is refused. The same verification\nruns on later self-updates.\n\nThe installer prompts for host IP, subnet, gateway, the interfaces to use, and\nthe address pool. It reads those prompts from the terminal directly, so it still\nworks under `curl … | bash`.\n\n### Unattended install\n\nSupply every setting through the environment and it runs with no prompts:\n\n```bash\nCENVERO_LICENSE_KEY=... \\\nCENVERO_HOST_IP=203.0.113.10 \\\nCENVERO_SUBNET=203.0.113.0/24 \\\nCENVERO_GATEWAY=203.0.113.1 \\\nCENVERO_MGMT_NIC=eth0 \\\nCENVERO_VM_NIC=eth1 \\\nCENVERO_POOL_START=203.0.113.100 \\\nCENVERO_POOL_END=203.0.113.200 \\\n bash install.sh\n```\n\n| Variable | Purpose |\n|----------|---------|\n| `CENVERO_LICENSE_KEY` | Your licence key |\n| `CENVERO_HOST_IP` | This node's management address |\n| `CENVERO_SUBNET` | The management subnet, in CIDR form |\n| `CENVERO_GATEWAY` | Default gateway |\n| `CENVERO_MGMT_NIC` | Interface for management traffic |\n| `CENVERO_VM_NIC` | Interface for workload traffic |\n| `CENVERO_POOL_START` / `CENVERO_POOL_END` | Address range handed out to workloads |\n| `CENVERO_API_TOKEN` | Off unless set. `auto` generates one, or supply your own. Can also be done later — see step 8 |\n| `CENVERO_KERNEL_UPGRADE` | `auto`, `manual`, or `skip` for the kernel check in step 2 |\n| `CENVERO_REINSTALL` | Set to `1` to re-run over an existing install, keeping config and data |\n| `CENVERO_PANEL_URL` | Your panel, if you self-host |\n| `CENVERO_CHANNEL` | Pins this node to one release channel |\n| `CENVERO_API_DOMAIN` | Extra hostname to include on the node's certificate |\n\nThe installer is **idempotent**. It detects a previous install and stops rather\nthan overwriting your configuration and state. Use `CENVERO_REINSTALL=1` when\nyou genuinely mean to re-run.\n\n## 4. Know what you just installed\n\nTwo names look alike and are not the same thing. This trips up nearly everyone\nonce:\n\n| Name | What it is |\n|------|-----------|\n| `cenvero-stratum` | The **service**. This is what `systemctl` acts on |\n| `cenvero-str-ctl` | The **command-line tool**. It talks to the running service |\n\nSo restarting the node is:\n\n```bash\nsystemctl restart cenvero-stratum\n```\n\n`systemctl restart cenvero-str-ctl` fails with \"unit not found\" — that is the\nCLI, not a service. And `cenvero-str-ctl restart` is not a command either: the\nCLI talks *to* the agent, it does not start or stop it.\n\nWhere things live:\n\n| Path | Contents |\n|------|----------|\n| `/etc/cenvero-str/` | Node configuration |\n| `/var/lib/cenvero-str/` | State and local data |\n| `/var/log/cenvero-str/` | Logs |\n| `/run/cenvero-str/` | The local control socket |\n\n## 5. Activate the node\n\nActivation binds the licence to this specific machine and pulls down its signed\nlicence.\n\n```bash\nsudo cenvero-str-ctl license activate CNVR-XXXX-XXXX-XXXX-XXXX\n```\n\nThe key is **positional** — there is no `--key` flag. This raises an activation\nrequest for this machine, which you then **confirm in your account**. Once you\nconfirm, the agent installs the signed licence on its own and begins enforcing\nit.\n\nTo check where it has got to:\n\n```bash\ncenvero-str-ctl license status\ncenvero-str-ctl hardware\n```\n\n`hardware` prints this machine's hardware id, which is what you match against\nthe pending request in the panel when you have several machines activating at\nonce.\n\nIf activation is refused with a **node quota** message, this licence's node\nslots are all in use. Each machine you approve takes one slot; a machine you\nreject or revoke gives its slot back.\n\n---\n\nAt this point the node is installed and licensed. Everything below is\nconfiguration — and a fresh node starts with most services deliberately off, so\nthis half is not optional.\n\n---\n\n## 6. See what is actually running\n\n```bash\ncenvero-str-ctl status\ncenvero-str-ctl service\n```\n\n`service` is the one to read carefully. It looks like this:\n\n```text\nSERVICE ENABLED ADDRESS STATE NOTE\nREST API off 203.0.113.10:7070 down no api_token configured\ngRPC API off 203.0.113.10:7071 down no api_token configured\nWebSocket API off 203.0.113.10:7072 down no api_token configured\nMetrics on 127.0.0.1:9090 listening -\nDNS on 127.0.0.1:53 listening -\nDHCP on :67 listening -\n```\n\nRead it as three independent columns:\n\n- **ENABLED** is your switch — what you asked for. It takes effect at the next restart.\n- **STATE** is a live check of whether something is actually listening right now.\n- **NOTE** explains any gap between the two.\n\nA service can be enabled and still down. That is not a contradiction: it means\nyour switch was recorded but something else is stopping the service from\nstarting, and NOTE tells you what. For the three management APIs, that something\nis almost always a missing API token — see step 8.\n\nThe local control socket is always up and is not a service you can toggle. That\nis why `cenvero-str-ctl` keeps working even with every network API off.\n\nApply an enable/disable change with:\n\n```bash\nsystemctl restart cenvero-stratum\n```\n\n## 7. Understand what is exposed\n\nDefault ports, and who can reach them:\n\n| Port | Service | Bound to | Reachable from |\n|------|---------|----------|----------------|\n| 7070 | REST API | node address | the network — **off until you configure a token** |\n| 7071 | gRPC API | node address | the network — **off until you configure a token** |\n| 7072 | WebSocket API | node address | the network — **off until you configure a token** |\n| 9090 | Metrics | `127.0.0.1` | this machine only |\n| 53 | DNS | `127.0.0.1` | this machine only |\n| 67 | DHCP | all interfaces | the local network |\n\nTwo things worth taking in.\n\nThe three management APIs are **off by design**, not broken. With no API token\nconfigured the agent refuses to open a management API at all, rather than\nopening one with no credential on it. If you never turn them on, you manage the\nnode from the panel and from `cenvero-str-ctl` locally, and nothing is listening\non those ports.\n\nDHCP is the one service bound to every interface, because it has to answer\nbroadcasts from clients that do not have an address yet. On a node with a public\naddress, that means UDP/67 is reachable from outside unless your firewall drops\nit. Worth a rule if the node faces the internet.\n\n## 8. Turn on the management API — only if you need it\n\nYou need this if something other than you at a terminal has to drive the node:\nyour own automation, a script, an orchestrator. If the panel and the CLI are\nenough, skip this step and leave the surface closed.\n\nThe token is **not created for you**, and that is deliberate — a node that minted\nits own API credential would be granting access nobody asked for. You ask for one\nexplicitly, at any time, on a node that is already running. You do not need to\nreinstall anything.\n\n### Generate one on the node\n\nThe usual way. The node mints a strong random token, stores it, and shows it to\nyou:\n\n```bash\nsudo cenvero-str-ctl api-token generate\n```\n\nIt prints the token **once**. Copy it then — it is not displayed again, and\nthere is no command that will show it back to you. If you lose it, generate a\nnew one; that replaces the old, and anything still using the old token starts\ngetting 401 after the next restart.\n\n### Supply your own instead\n\nIf you need a specific value — one your automation already holds, or one from\nyour secret manager — pipe it in. Piping keeps it out of your shell history,\nwhich is why there is no flag to pass it as an argument:\n\n```bash\nprintf '%s' \"$MY_TOKEN\" | sudo cenvero-str-ctl api-token set\n```\n\nAnything under 16 characters is refused. A token short enough to guess is worse\nthan no token at all, because you would believe the API was protected.\n\n### Check or remove it\n\n```bash\ncenvero-str-ctl api-token status # is one set? (never prints the value)\ncenvero-str-ctl api-token clear # remove it — the APIs stop at the next restart\n```\n\n`status` deliberately reports only whether a token exists, never what it is.\n\n### At install time, if you prefer\n\n`CENVERO_API_TOKEN=auto` mints one during the install, and\n`CENVERO_API_TOKEN=` sets yours — the same result, before the node first\nstarts. It is entirely optional: generating one later is fully supported and\nchanges nothing else about the node.\n\nWhichever way you set it, the token is kept in your local overrides, so a later\nsync from the panel will not discard it.\n\n### Then enable the APIs you want\n\n```bash\ncenvero-str-ctl service on rest\nsystemctl restart cenvero-stratum\n```\n\nThe API speaks **HTTPS**, never plaintext, so reach it as\n`https://:7070/…`. An `http://` URL will fail even with everything\nconfigured correctly. Your node's certificate is signed by your own account\nauthority, so a browser warns until you trust that root.\n\nThe name comes after `on` — `service on rest`, not `service rest on`. Valid\nnames are `rest`, `grpc`, `websocket`, `metrics`, `dns` and `dhcp`, and `off`\ntakes the same form.\n\nThe API binds only when **all three** hold: a token is configured, the service is\non, and the node has a TLS certificate (step 9 — the agent refuses to serve\nplaintext). If any one is missing, the port stays closed and a browser gets\n\"connection refused\". `cenvero-str-ctl service status` tells you which.\n\nEvery protected endpoint then requires that token as a bearer credential.\n[API Reference](/docs/api) has the details.\n\n## 9. Get the node its certificate\n\nThe node serves its APIs over TLS. Ask the panel to sign a certificate for it:\n\n```bash\nsudo cenvero-str-ctl tls request\n```\n\nYou then **approve the request in your account**, under TLS. Once approved:\n\n```bash\nsudo cenvero-str-ctl tls pull\ncenvero-str-ctl tls info\n```\n\n`tls info` should report `mode: ca-signed` with an expiry. Note the commands\nhere are `tls info` and `tls pending-status` — there is no `tls status`.\n\nRenewal is automatic. See [TLS and Licence](/docs/tls-and-license).\n\n## 10. Configure the node's job\n\nNow give the node something to do. There is no node type to pick — every node\nhosts workloads *and* routes. What it can do is limited only by how many\ninterfaces it has free, which [Nodes and Interfaces](/docs/nodes) explains.\n\n**Define networks and addressing.** Create the networks your workloads sit on\nand the pools they draw addresses from:\n\n```bash\ncenvero-str-ctl network list\ncenvero-str-ctl ipam pools\ncenvero-str-ctl ipam allocations\n```\n\nSee [Networking Overview](/docs/networking/overview).\n\n**Set up DNS and DHCP.** Both are already listening. What they lack is your\nzones, scopes and reservations. See [DHCP and DNS](/docs/networking/dhcp-dns).\n\n**Write firewall rules.** A new node has no rules of its own. See\n[Firewall](/docs/networking/firewall).\n\n**Add a path to the internet.** Source-NAT lets a private tenant subnet reach\nthe internet through one public address. See\n[Gateway and NAT](/docs/networking/gateway-nat).\n\n**Set bandwidth and quotas.** Your plan already caps the node's total speed.\nThese divide it up between tenants. See [Tenants](/docs/tenants).\n\n## Verify the install\n\nRun through this list. Everything should be true before you put real traffic on\nthe node.\n\n| Check | Command | Expected |\n|-------|---------|----------|\n| Service is up | `systemctl status cenvero-stratum` | active (running) |\n| Agent responds | `cenvero-str-ctl status` | reports its state |\n| Licence is live | `cenvero-str-ctl license status` | active, with an expiry |\n| Certificate is signed | `cenvero-str-ctl tls info` | `mode: ca-signed` |\n| Services match intent | `cenvero-str-ctl service` | what you enabled is listening |\n| Node is healthy | `cenvero-str-ctl heal` | all checks pass |\n| Metrics answer | `curl 127.0.0.1:9090/metrics` | a metrics response |\n\n## Troubleshooting\n\n**`systemctl restart cenvero-str-ctl` says unit not found.** The service is\n`cenvero-stratum`. `cenvero-str-ctl` is the CLI.\n\n**`cenvero-str-ctl restart` says unknown command.** The CLI talks to the agent;\nit does not control the service. Use `systemctl restart cenvero-stratum`.\n\n**The REST, gRPC and WebSocket APIs are all `down`.** Expected on a fresh node\nwith no API token. This is fail-closed behaviour, not a fault. Fix it with\n`cenvero-str-ctl api-token generate`, then `service on rest`, then restart.\n\n**The API port refuses the connection** (`ERR_CONNECTION_REFUSED`, or `curl`\nreporting connection refused). Nothing is listening there. Enabling the service\nis only half of it — without a token the server does not start, so the port stays\nclosed. Check `cenvero-str-ctl api-token status` first, then\n`cenvero-str-ctl service status`: the row should read enabled and `listening`.\n\n**`service on rest` said it was enabled, but ENABLED still shows `off`.** Your\nswitch *was* saved — confirm with `cenvero-str-ctl config show`. On builds\nbefore this behaviour was corrected, the ENABLED column also folded in whether\nan API token exists, so a service you had genuinely enabled still displayed as\noff when no token was configured. Set a token (step 8) and the row resolves.\nENABLED now reports only your switch.\n\n**`curl 127.0.0.1:9090` returns 404.** That port serves `/metrics` and nothing\nelse. The bare root is not a page. Use `curl 127.0.0.1:9090/metrics`.\n\n**Activation fails with a node quota message.** Every slot on the licence is\ntaken. Reject or revoke a machine you no longer run and its slot comes back, or\nraise the node count on the licence.\n\n**`tls pull` succeeds but the panel shows nothing to approve.** The node needs\nto be registered before it can raise a request. Check `cenvero-str-ctl license\nstatus` first — if the node never registered, that is the thing to fix, and a\nnode quota message is the usual reason.\n\n**The install stopped over the kernel.** Your kernel is older than the data\nplane needs. Step 2 covers your options.\n\n**Something else.** `cenvero-str-ctl heal` runs the health checks, and the logs\nare in `/var/log/cenvero-str/`.\n\n## Where to go next\n\n- [Quick Start](/docs/quickstart) — define a network and attach a workload\n- [Configuration](/docs/configuration) — the node configuration in full\n- [Nodes and Interfaces](/docs/nodes) — what a node does, and the interfaces it needs\n- [Networking Overview](/docs/networking/overview) — how traffic moves\n- [Clustering Overview](/docs/clustering/overview) — join this node to others\n- [Operations](/docs/operations) — day-to-day running\n- [Upgrades](/docs/upgrades) — keeping the node current\n\n## Take this guide with you\n\nEvery page here is downloadable, so you can keep it alongside your runbooks or\nfeed it to your own tooling:\n\n- **This page** — [installation.json](/docs/installation.json)\n- **The whole documentation set** — [docs.json](/docs.json)\n\nBoth return the Markdown source, so they stay readable offline and are not tied\nto this site. Add `?include=html` to either for the rendered HTML as well.\n" }, { "slug": "quickstart", "title": "Quick Start", "category": null, "url": "https://www.stratum.cenvero.com/docs/quickstart", "headings": [ { "level": 1, "text": "Quick Start" }, { "level": 2, "text": "1. Define a network" }, { "level": 2, "text": "2. Attach a workload to an endpoint" }, { "level": 2, "text": "3. Add a firewall policy" }, { "level": 2, "text": "4. Define a load-balanced VIP" }, { "level": 2, "text": "5. Confirm" }, { "level": 2, "text": "Where to go next" } ], "word_count": 505, "markdown": "# Quick Start\n\nThis walkthrough takes an installed, activated node and gets a workload onto a\nmanaged network with DHCP, DNS, and a firewall policy — end to end.\n\nIf you have not installed the agent yet, start with\n[Installation](/docs/installation).\n\n## 1. Define a network\n\nA *network* is a managed private network: an IP CIDR whose usable host addresses\nare each materialized into an **endpoint profile** (an IP paired with a generated\nMAC). Create one with the CLI:\n\n```bash\nsudo cenvero-str-ctl network create \\\n --name app-net \\\n --cidr 10.20.0.0/24 \\\n --gateway 10.20.0.1\n```\n\nStratum allocates the segment on the workload bridge, starts a DHCP server\nfor the pool, and serves authoritative DNS for the network's zone.\n\nList what you have:\n\n```bash\ncenvero-str-ctl network list\n```\n\n```text\n{\n \"data\": {\n \"networks\": [\n {\n \"id\": \"net-069088314b4e4712\",\n \"name\": \"app-net\",\n \"cidr\": \"10.20.0.0/24\",\n \"gateway\": \"10.20.0.1\",\n \"vlan\": 0,\n \"tenant_id\": \"\",\n \"created_at\": \"2026-07-24T20:53:31Z\"\n }\n ]\n },\n \"status\": \"ok\"\n}\n```\n\nNote the generated `id` — the other `network` commands refer to a network by\nthat id, not by its name.\n\n## 2. Attach a workload to an endpoint\n\nClaim a free endpoint for your workload. Stratum returns the endpoint's IP and a\ngenerated MAC, wires it into the bridge, and programs the data plane (including\nthe IP↔MAC anti-spoof binding) for it:\n\n```bash\nsudo cenvero-str-ctl network attach net-069088314b4e4712 --ip 10.20.0.50\n```\n\nConfigure your workload's interface with the returned MAC and it picks up the\nendpoint's IP from DHCP, a working default gateway, and DNS — no guest agent\nrequired.\n\n```bash\ncenvero-str-ctl network endpoints net-069088314b4e4712\n```\n\n```text\n{\n \"data\": {\n \"endpoints\": [\n {\n \"id\": \"ep-3f2a91c7\",\n \"network_id\": \"net-069088314b4e4712\",\n \"ip\": \"10.20.0.50\",\n \"mac\": \"52:54:00:ab:cd:01\",\n \"state\": \"bound\"\n }\n ]\n },\n \"status\": \"ok\"\n}\n```\n\n## 3. Add a firewall policy\n\nEach firewall rule is a single JSON object. Allow inbound HTTP and HTTPS to the\nendpoint, and let it reach out. Ports are matched one at a time, so HTTP and\nHTTPS are two rules:\n\n```bash\nsudo cenvero-str-ctl firewall allow '{\"chain\":\"forward\",\"dest_ip\":\"10.20.0.50\",\"protocol\":\"tcp\",\"dest_port\":443,\"stateful\":true}'\n\nsudo cenvero-str-ctl firewall allow '{\"chain\":\"forward\",\"dest_ip\":\"10.20.0.50\",\"protocol\":\"tcp\",\"dest_port\":80,\"stateful\":true}'\n\nsudo cenvero-str-ctl firewall allow '{\"chain\":\"forward\",\"source_ip\":\"10.20.0.50\",\"stateful\":true}'\n```\n\n`\"stateful\": true` puts the flow in the connection-tracking table so return\ntraffic is admitted automatically. See [Firewall](/docs/networking/firewall) for\nthe full policy model and every rule field.\n\n## 4. Define a load-balanced VIP\n\nDeclare an L4 virtual IP, then attach a backend to it so you can scale\nhorizontally later:\n\n```bash\nsudo cenvero-str-ctl lb create '{\"id\":\"web-lb\",\"frontend_ip\":\"10.20.0.10\",\"frontend_port\":80,\"protocol\":\"tcp\",\"algorithm\":\"least-conn\"}'\n\nsudo cenvero-str-ctl lb add-backend '{\"vip_id\":\"web-lb\",\"id\":\"web-1\",\"ip\":\"10.20.0.50\",\"port\":80,\"weight\":1}'\n```\n\nAdd and remove backends live with `lb add-backend` / `lb remove-backend`. See\n[Load Balancer](/docs/networking/load-balancer).\n\n## 5. Confirm\n\n```bash\ncenvero-str-ctl status\n```\n\nYou now have a workload on a managed network with DHCP, DNS, a firewall policy,\nand a load-balancer VIP defined — all from one agent.\n\n## Where to go next\n\n- **[Configuration](/docs/configuration)** — the node configuration model in depth.\n- **[Clustering Overview](/docs/clustering/overview)** — stretch the network across hosts.\n- **[CLI Reference](/docs/cli)** — every command in one place.\n" }, { "slug": "configuration", "title": "Configuration", "category": null, "url": "https://www.stratum.cenvero.com/docs/configuration", "headings": [ { "level": 1, "text": "Configuration" }, { "level": 2, "text": "How configuration is delivered and layered" }, { "level": 3, "text": "How the config is signed and verified" }, { "level": 2, "text": "Launch flags" }, { "level": 2, "text": "Identity and node fields" }, { "level": 2, "text": "Paths" }, { "level": 2, "text": "Ports" }, { "level": 2, "text": "API" }, { "level": 2, "text": "TLS" }, { "level": 2, "text": "Cluster" }, { "level": 2, "text": "Gateway and HA" }, { "level": 2, "text": "Overlay (VXLAN) and load balancer" }, { "level": 2, "text": "Intrusion detection (IDS)" }, { "level": 2, "text": "DNS" }, { "level": 2, "text": "DHCP" }, { "level": 2, "text": "Metrics" }, { "level": 2, "text": "Network services (on/off switches)" }, { "level": 2, "text": "Operator local overrides" }, { "level": 3, "text": "Settable keys (the local whitelist)" }, { "level": 3, "text": "Keys that cannot be set locally" }, { "level": 2, "text": "What is *not* in this file" }, { "level": 2, "text": "Ports summary" }, { "level": 2, "text": "A note on time" }, { "level": 2, "text": "Next steps" } ], "word_count": 2853, "markdown": "# Configuration\n\nThe agent starts from sensible **built-in defaults** and, on top of those, loads\nan optional node configuration file. If the file is absent the defaults are used,\nso a freshly-installed node runs without any config at all. Point the agent at a\nspecific file with `--config `.\n\n```bash\n# Run with the default config (if one is present)\ncenvero-stratum\n\n# Or an explicit path\ncenvero-stratum --config /etc/cenvero-str/config.cenvero-stratum\n```\n\nThis page is the **full reference** for every configuration field: what it is,\nits type, default, accepted values, and which command controls it. Use it\nalongside the [CLI Reference](/docs/cli).\n\n## How configuration is delivered and layered\n\nThere are three layers, applied in order — **each later layer wins**:\n\n1. **Built-in defaults.** Compiled into the agent (the table values marked\n *default* below). A node with no config file at all runs entirely on these.\n2. **The node config file** (`config.cenvero-stratum`). A **signed** configuration\n file the provisioning tooling and the panel produce — it is not hand-edited.\n The panel delivers this file already signed; the agent verifies it on load (see\n below). Distributing one signed file rolls identical settings across a fleet.\n3. **Operator local overrides** (`config.local.cenvero-stratum`). A small sidecar\n you set on the node itself with `cenvero-str-ctl config set` / `service`. These\n take precedence over the panel-delivered config **and survive a panel re-sync**\n — see the *Operator local overrides* section below.\n\n> The provisioning installer writes the *initial* config file for you; you don't\n> author it by hand. Day-to-day local adjustments go through `config set` and\n> `service`, which write the override sidecar — never the main file.\n\n### How the config is signed and verified\n\nThe node config and the override sidecar are stored as signed configuration files\nthe agent loads directly — they are not hand-written text.\n\nFor production, the panel **cryptographically signs** the config it delivers, and\nthe agent **verifies that signature on load** so it refuses to boot from a forged\nor tampered file delivered over the network. The trust model is deliberately\nfail-closed where it matters and permissive where it can't hurt you:\n\n- **No file on disk** — the agent boots on built-in defaults (a fresh node still\n comes up).\n- **A signed config** (the normal panel-delivered case) — the signature **must**\n verify; a tampered or wrong-key file is **rejected**.\n- **An unsigned local bootstrap config** (what the installer writes on first\n install) — accepted with a loud log warning, so a brand-new node can start,\n register, and sync. A network attacker can't exploit this: substituting an\n unsigned file only yields installer defaults, and the next panel-signed config\n still must verify.\n\nYou inspect (never edit) the on-disk file with `cenvero-str-ctl config show`,\nwhich decodes and prints it; secret values are redacted unless you add\n`--include-secrets`.\n\n```bash\nsudo cenvero-str-ctl config show # decoded, secrets redacted\nsudo cenvero-str-ctl config show --format json # machine-readable\n```\n\n## Launch flags\n\nA handful of settings can be overridden at process launch (these affect that one\nrun; persistent changes belong in the config or the override sidecar):\n\n| Flag | Type | Default | What it does |\n|------|------|---------|--------------|\n| `--config ` | path | (none) | Path to the node config file. If omitted, built-in defaults are used. |\n| `--bind ` | IP | (from config) | Override the API bind address for this run. |\n| `--log-level ` | enum | `info` | Log verbosity: `debug`, `info`, `warn`, or `error`. |\n| `--allow-unsigned-config` | flag | `false` | **Dev only, insecure.** Load the config without verifying its signature. Never use in production. |\n\n## Identity and node fields\n\nThese describe the node itself. `node_id` and `license_server` are\n**panel/identity-owned**: set at install or by the panel-signed config (and, where\nnoted, refused by `config set` — see *Keys that cannot be set locally* below).\n`log_level` is the exception — it is operator-settable, per its row.\n\n| Key | Type | Default | Accepted values | What it does | Controlled by |\n|-----|------|---------|-----------------|--------------|---------------|\n| `node_id` | string | (empty) | UUID | Stable node identity; binds the license. Also the VXLAN VTEP source fallback when it parses as an IP. | Install / panel |\n| `license_server` | string (URL) | `https://license.cenvero.com` | Base URL | License/activation server. Empty falls back to the built-in default. | Install / panel |\n| `log_level` | enum | `info` | `debug`, `info`, `warn`, `error` | Agent log verbosity. | `config set log_level` |\n\n> **There is no node-mode setting any more.** Older versions carried a\n> `node_mode` field that chose between a Compute node and a Gateway node. Every\n> node now routes, the field is gone, and a node updating from an older version\n> has its configuration migrated automatically — see\n> [Nodes and Interfaces](/docs/nodes).\n\n## Paths\n\nFilesystem locations the agent uses. These follow the standard `cenvero-str`\nlayout and are set by the installer; they are not adjusted with `config set`.\n\n| Key | Type | Default | What it does |\n|-----|------|---------|--------------|\n| `data_dir` | path | `/var/lib/cenvero-str/` | Persistent state — the node's own records and supporting files. |\n| `config_dir` | path | `/etc/cenvero-str/` | Configuration directory (holds the config file and the override sidecar). |\n| `socket_path` | path | `/run/cenvero-str/cenvero-str.sock` | Unix socket `cenvero-str-ctl` uses to talk to the agent. |\n\n## Ports\n\nThe agent listens on a fixed set of ports. The defaults rarely need changing; when\nthey do, the five listen ports are settable via the local override sidecar. Open\nthese between cluster members on the **management network only**.\n\n| Key | Type | Default | Protocol | Purpose | Controlled by |\n|-----|------|---------|----------|---------|---------------|\n| `port_rest` | int (1-65535) | `7070` | HTTPS | REST management API. | `config set port_rest` |\n| `port_grpc` | int (1-65535) | `7071` | TCP | gRPC management API (node-to-node control). | `config set port_grpc` |\n| `port_websocket` | int (1-65535) | `7072` | WebSocket | Live events / streaming. | `config set port_websocket` |\n| `port_cluster` | int (1-65535) | `7073` | TCP | Cluster state replication. | `config set port_cluster` |\n| `port_ha_heartbeat` | int (1-65535) | `7074` | UDP | Gateway HA heartbeat. | `config set port_ha_heartbeat` |\n\n## API\n\nThe local management API (REST / gRPC / WebSocket). The bind address, rate limits,\nand allow-lists are settable locally; the **bearer token is a credential** and is\nrefused by `config set` (rotate it at install or via the panel).\n\n| Key | Type | Default | Accepted values | What it does | Controlled by |\n|-----|------|---------|-----------------|--------------|---------------|\n| `api_bind_address` | IP | `0.0.0.0` | Any IP (use `0.0.0.0` / `::` for all interfaces) | IP the REST/gRPC/WebSocket APIs listen on. A host:port or hostname is rejected — this is an IP only. | `config set api_bind_address` |\n| `api_rate_limit` | int (≥ 0) | `1000` | `0` disables the limiter | Requests per minute per key. | `config set api_rate_limit` |\n| `api_rate_burst` | int (≥ 0) | `100` | `0` or higher | Burst allowance above the per-minute rate. | `config set api_rate_burst` |\n| `api_allowed_ips` | list of IP/CIDR | (empty) | Comma-separated IPs/CIDRs; empty = allow all | IPs/CIDRs allowed to reach the API. | `config set api_allowed_ips` |\n| `api_allowed_origins` | list of string | (empty) | Comma-separated origins; empty = same-host only | Allowed WebSocket `Origin` values. | `config set api_allowed_origins` |\n| `api_token` | string (secret) | (empty) | Bearer token | Token required for protected REST/gRPC/WS endpoints. Empty means the local management API is **disabled**. | Install / panel (refused by `config set`) |\n\n> Set the API token at install time with\n> `cenvero-str-ctl config encode --generate-api-token` (mints a fresh random token\n> and enables the API). It is a credential, not an operational setting.\n\n## TLS\n\nTLS material for the management API. Paths are managed by the certificate manager\n(`cenvero-str-ctl tls ...`) — they are **not** set with `config set`.\n\n| Key | Type | Default | What it does | Controlled by |\n|-----|------|---------|--------------|---------------|\n| `tls_auto_generate` | bool | `true` | Auto-generate a self-signed certificate on first start. | Install / cert manager |\n| `tls_cert_path` | path | `/etc/cenvero-str/tls/server.crt` | TLS certificate. | Cert manager (refused by `config set`) |\n| `tls_key_path` | path | `/etc/cenvero-str/tls/server.key` | TLS private key. | Cert manager (refused by `config set`) |\n| `tls_pubkey_path` | path | `/etc/cenvero-str/tls/server.pub` | TLS public key file. | Cert manager (refused by `config set`) |\n| `grpc_client_ca_dir` | path | (empty) | When set, contains `ca.pem` used to require + verify gRPC client certificates (mTLS). | Provisioned (refused by `config set`) |\n\n## Cluster\n\nClustering identity and transport security. These are panel-orchestrated /\nprovisioned and are **not** set with `config set`. Cluster TLS material is\nmandatory — clustering refuses to start without it (no plain-TCP downgrade).\n\n| Key | Type | Default | What it does | Controlled by |\n|-----|------|---------|--------------|---------------|\n| `cluster_enabled` | bool | `false` | Whether this node participates in a cluster. | Panel |\n| `cluster_bind_addr` | string | (empty) | Address the cluster transport binds. | Panel (refused by `config set`) |\n| `cluster_bootstrap` | bool | `false` | Whether this node bootstraps a new cluster. | Panel |\n| `cluster_cert_dir` | path | (empty) | Directory holding `cert.pem`, `key.pem`, and `ca.pem` for cluster mTLS. | Provisioned (refused by `config set`) |\n\n## Gateway and HA\n\nThese name the two interfaces the node's forwarding path is placed on, and\nconfigure the HA pairing. Naming the interfaces is what puts NAT and routing on\nthem — there is no separate switch to turn the gateway path on. Leave them empty\nand the node still hosts workloads and serves its networks; it simply forwards\nnothing across an edge. The **HA shared key is a cluster secret** and is refused\nby `config set` (it must match the peer).\n\n| Key | Type | Default | What it does | Controlled by |\n|-----|------|---------|--------------|---------------|\n| `gateway_wan_interface` | string | (empty) | The outward-facing interface the forwarding path (NAT + routing) uses. | Install / panel |\n| `gateway_lan_interface` | string | (empty) | The inward-facing interface the forwarding path uses. | Install / panel |\n| `wan_dhcp` | bool | `false` | Run the built-in DHCP client on the WAN interface to obtain the uplink address. When false, the WAN address is static/config. | Install / panel |\n| `gateway_vip` | string (IP) | (empty) | Virtual IP the HA pair owns; the ACTIVE node assumes it and announces it via gratuitous ARP, releasing it on losing ACTIVE. Empty registers no VIP. | Install / panel |\n| `gateway_peer_addr` | string | (empty) | HA peer address (`host` or `host:port`; the HA heartbeat port is appended when absent). Empty disables HA peering (solo gateway). | Install / panel |\n| `gateway_priority` | int | `0` | Biases which node becomes ACTIVE; higher wins. `0` leaves the manager default. | Install / panel |\n| `gateway_shared_key` | string (secret) | (empty) | Shared key authenticating the HA heartbeat; **must match the peer**. | Install / panel (refused by `config set`) |\n\n## Overlay (VXLAN) and load balancer\n\n| Key | Type | Default | What it does | Controlled by |\n|-----|------|---------|--------------|---------------|\n| `vtep_local_ip` | string (IP) | (empty) | Underlay source IP for VXLAN tunnels. Empty falls back to `node_id` **only if** it parses as an IP (a hostname `node_id` is rejected with a warning). | Install / panel |\n| `lb_interface` | string | (empty) | VIP-facing interface the L4 load balancer uses. Empty leaves the load balancer unattached. Must be a **dedicated** interface — not one already used by the bridge or gateway data plane. | Install / panel |\n\n## Intrusion detection (IDS)\n\nOpt-in per-source scan/flood detection on an interface's ingress.\n\n| Key | Type | Default | What it does | Controlled by |\n|-----|------|---------|--------------|---------------|\n| `ids_interface` | string | (empty) | Interface whose ingress the IDS collector watches. Empty leaves IDS disabled. May be an interface already used by the data plane — typically the uplink/WAN or `cnv-user-br0`. | Install / panel |\n| `ids_auto_block` | bool | `false` | `false` = **alert only** (a detection raises an event but does not touch traffic). `true` adds a confirmed scanner/flooder's IPv4 source to the firewall blocklist with an auto-expiring TTL. Opt-in because a false positive would cut off a legitimate source. | Install / panel |\n\n## DNS\n\nThe built-in resolver. The listen address and client ACL are settable locally;\nDNSSEC is panel-managed.\n\n| Key | Type | Default | Accepted values | What it does | Controlled by |\n|-----|------|---------|-----------------|--------------|---------------|\n| `dns_listen_addr` | string | (empty) | IP, or `host:port`, or empty | Address the DNS server binds. Empty binds the management bridge address only (not the WAN), so the resolver isn't exposed by default. | `config set dns_listen_addr` |\n| `dns_allowed_clients` | list of IP/CIDR | (empty) | Comma-separated IPs/CIDRs; empty = local/private ranges | Clients permitted to query the resolver. Empty falls back to local/private ranges — never an open resolver. | `config set dns_allowed_clients` |\n| `dnssec_enabled` | bool | `false` | `true`/`false` | Authoritative DNSSEC signing (per-zone keys, RRSIG/DNSKEY served when the client sets the DO bit). Default off = unsigned answers (back-compat). | Install / panel |\n\n## DHCP\n\nThe built-in DHCP server. Per-network scopes are panel-managed (set as\noperational resources, not in the static config); the **DHCP service itself** is\ntoggled with `service dhcp`.\n\n| Key | Type | Default | What it does | Controlled by |\n|-----|------|---------|--------------|---------------|\n| `dhcp_scopes` | list | (empty = single default pool) | Per-network DHCP scopes: each binds a client subnet to its own IPAM pool and reply parameters (gateway / mask / DNS / lease length). Matched by `giaddr` (relayed) or the receiving interface (directly attached). | Panel / API |\n\n## Metrics\n\n| Key | Type | Default | What it does | Controlled by |\n|-----|------|---------|--------------|---------------|\n| `metrics_bind_addr` | string (host:port) | `127.0.0.1:9090` | Address the Prometheus `/metrics` endpoint binds. Defaults to loopback so it isn't exposed on `0.0.0.0`; point it at a management address to scrape it off-box. The host must be an IP, not a hostname. | `config set metrics_bind_addr` |\n\n## Network services (on/off switches)\n\nEach network service can be turned on or off. These are stored **inverted** as\n`*_disabled` keys, so the default — every service running — is preserved for any\nolder config. The friendly front door is `cenvero-str-ctl service on|off`;\nthe raw equivalent is `config set _disabled true|false`, and the two\nround-trip with `config show`. All default to **enabled**.\n\n| Service name | `config` key | Default | What it gates |\n|--------------|--------------|---------|---------------|\n| `rest` | `rest_disabled` | enabled | The REST management API (also serves the operator/billing API). |\n| `grpc` | `grpc_disabled` | enabled | The gRPC management API. |\n| `websocket` | `websocket_disabled` | enabled | The WebSocket management API. |\n| `metrics` | `metrics_disabled` | enabled | The Prometheus `/metrics` endpoint. |\n| `dns` | `dns_disabled` | enabled | The built-in DNS server bind (on top of the listen-address gate). |\n| `dhcp` | `dhcp_disabled` | enabled | The built-in DHCP protocol server bind (the lease table still runs). |\n\n```bash\n# Toggle a service (writes the override sidecar; applies on restart)\nsudo cenvero-str-ctl service dns off\nsudo cenvero-str-ctl service status # ENABLED / ADDRESS / live STATE per service\n\n# Equivalent raw form\nsudo cenvero-str-ctl config set dns_disabled true\n```\n\n> The **IPC control socket is not a toggleable service** — it is how\n> `cenvero-str-ctl` talks to the agent, so it can never be disabled. Disabling the\n> REST API is allowed but warns first, because it also carries the operator/billing\n> API.\n\n## Operator local overrides\n\n`config set` and `service` never touch the main `config.cenvero-stratum` file.\nThey write a separate **operator local-overrides sidecar**\n(`config.local.cenvero-stratum`, mode `0600`) in the config directory. The agent\noverlays this on top of its config at boot, so:\n\n- A locally-set field **takes effect on the next agent restart**, and\n- it **survives a configuration re-sync from the panel** (which rebuilds the main\n config from defaults but never touches the sidecar). Local always wins.\n\n```bash\n# The general form is: config set \nsudo cenvero-str-ctl config set api_rate_limit 2000\n\n# Legacy shortcut flags for the three most common API keys\nsudo cenvero-str-ctl config set --api-bind 10.0.0.5 --api-rate-limit 2000 --api-rate-burst 200\n\n# Run with no value to list every settable key\nsudo cenvero-str-ctl config set\n\n# Apply the change\nsudo systemctl restart cenvero-stratum\n```\n\n### Settable keys (the local whitelist)\n\nOnly these safe operational keys can be set locally. Everything else is refused.\n\n`log_level`, `api_bind_address`, `api_rate_limit`, `api_rate_burst`,\n`api_allowed_ips`, `api_allowed_origins`, `api_read_timeout_secs`,\n`api_write_timeout_secs`, `api_idle_timeout_secs`, `port_rest`, `port_grpc`,\n`port_websocket`, `port_cluster`, `port_ha_heartbeat`, `metrics_bind_addr`,\n`dns_listen_addr`, `dns_allowed_clients`, `dns_upstreams`,\n`heal_interval_seconds`, `heal_disabled_checks`, and the six service switches\n(`rest_disabled`, `grpc_disabled`, `websocket_disabled`, `metrics_disabled`,\n`dns_disabled`, `dhcp_disabled`).\n\n### Keys that cannot be set locally\n\nIdentity, the license server, credentials, and signing / cluster-secret / TLS\nmaterial are **refused** by `config set` with an explanation — they are panel- or\nidentity-owned and must never come from a local edit:\n\n| Refused key | Why |\n|-------------|-----|\n| `node_id` | Panel-assigned identity; binds the license. |\n| `license_server` | Panel-controlled (set at install / by the signed config). |\n| `api_token` | A credential — rotate it at install/panel, not via `config set`. |\n| `gateway_shared_key` | A cluster secret that must match the HA peer. |\n| `cluster_bind_addr` | Clustering identity/secret is panel-orchestrated. |\n| `cluster_cert_dir` | Cluster mTLS material is provisioned. |\n| `grpc_client_ca_dir` | gRPC client-mTLS CA material is provisioned. |\n| `tls_cert_path` | TLS material is managed by the cert manager. |\n| `tls_key_path` | TLS material is managed by the cert manager. |\n| `tls_pubkey_path` | TLS material is managed by the cert manager. |\n\n## What is *not* in this file\n\nOperational resources — **networks, endpoints, IP pools, firewall rules, load\nbalancers, DNS/DHCP zones** — are **not** part of the node config. They are\nmanaged at runtime through the agent's API and `cenvero-str-ctl` (and replicated\nacross a cluster), not baked into the static node config. Use the relevant\n[CLI](/docs/cli) command group for each.\n\n## Ports summary\n\nOpen these between cluster members on the management network only:\n\n| Port | Protocol | Purpose |\n|------|----------|---------|\n| 7070 | HTTPS | Management API |\n| 7071 | TCP | Node-to-node control |\n| 7072 | WebSocket | Live events / streaming |\n| 7073 | TCP | Cluster state replication |\n| 7074 | UDP | Gateway HA |\n\n## A note on time\n\nStratum works in UTC everywhere and cross-checks the host clock against NTP.\nLarge time drift is treated as a tamper signal for licensing, so keep `chronyd`\nor `systemd-timesyncd` running on every node.\n\n## Next steps\n\n- **[CLI Reference](/docs/cli)** — the full command surface.\n- **[Clustering Overview](/docs/clustering/overview)** — joining nodes into a cluster.\n- **[Licensing](/docs/licensing)** — how enforcement interacts with the agent.\n" }, { "slug": "operations", "title": "Operations & Troubleshooting", "category": null, "url": "https://www.stratum.cenvero.com/docs/operations", "headings": [ { "level": 1, "text": "Operations & Troubleshooting" }, { "level": 2, "text": "Systemd units" }, { "level": 2, "text": "Logs" }, { "level": 2, "text": "Network services: on / off" }, { "level": 2, "text": "Changing settings" }, { "level": 2, "text": "Updates" }, { "level": 2, "text": "Health checks" }, { "level": 2, "text": "Troubleshooting" }, { "level": 3, "text": "The agent won't start" }, { "level": 3, "text": "`cenvero-str-ctl` says the agent is unreachable (exit code 3)" }, { "level": 3, "text": "License is not active" }, { "level": 3, "text": "TLS certificate is pending" }, { "level": 3, "text": "Node is not registered" }, { "level": 3, "text": "\"REST API disabled\" — set an API token" }, { "level": 3, "text": "Where to look first" }, { "level": 2, "text": "Next steps" } ], "word_count": 1943, "markdown": "# Operations & Troubleshooting\n\nDay-to-day operation of a Stratum node: managing its systemd units, finding the\nlogs, turning individual network services on and off, changing settings, applying\nupdates, and a runbook for the issues you are most likely to hit.\n\nEverything here runs **on the node itself** as `root`. The operator tool,\n`cenvero-str-ctl`, talks to the running agent over a local socket — see the\n[CLI Reference](/docs/cli) for the full command surface.\n\n## Systemd units\n\nA node runs three systemd units, installed and enabled by the installer:\n\n| Unit | What it does |\n|------|--------------|\n| `cenvero-stratum` | The agent itself — control plane, APIs, and the in-kernel data plane. |\n| `cenvero-str-watchdog` | A small separate watchdog that monitors the agent and restarts it if it stops responding. It is bound to the agent (`BindsTo`), so it follows the agent's lifecycle. |\n| `cenvero-str-network` | A one-shot boot unit that brings up the host uplinks and the two bridges (`cnv-mgmt-br0`, `cnv-user-br0`) **before** the agent starts, so the interfaces are present when the agent attaches to them. |\n\nManage them with the usual `systemctl` verbs:\n\n```bash\n# Status and recent log lines for the agent\nsystemctl status cenvero-stratum\n\n# Start / stop / restart the agent (the watchdog follows it)\nsudo systemctl restart cenvero-stratum\nsudo systemctl stop cenvero-stratum\nsudo systemctl start cenvero-stratum\n\n# The watchdog and the boot-time network unit\nsystemctl status cenvero-str-watchdog\nsystemctl status cenvero-str-network\n```\n\nRestarting the agent is safe: because the data plane runs in the kernel and the\ninterfaces stay held across the swap, the brief restart does **not** tear down\nexisting traffic. Stopping the agent leaves the kernel data plane and the bridges\nin place.\n\n> Do not disable `cenvero-str-network` while the node is in service — it owns the\n> host networking the agent attaches to.\n\n## Logs\n\nThe agent logs structured JSON to standard out, which under systemd is captured\nby the **journal**. That is the first place to look:\n\n```bash\n# Follow the agent's live log\njournalctl -u cenvero-stratum -f\n\n# Last 200 lines\njournalctl -u cenvero-stratum -n 200\n\n# Since a time, or only errors and worse\njournalctl -u cenvero-stratum --since \"1 hour ago\"\njournalctl -u cenvero-stratum -p err\n\n# The watchdog has its own unit log\njournalctl -u cenvero-str-watchdog -n 100\n```\n\nOn-disk files live under **`/var/log/cenvero-str/`** — most notably the installer\nlog written during install. The agent's self-healing service prunes old rotated\nlog files (older than 7 days) from this directory when disk space runs low, so it\nis also where any rotated logs accumulate.\n\nTurn up the detail when you need it (see *Changing settings* below):\n\n```bash\nsudo cenvero-str-ctl config set log_level debug\nsudo systemctl restart cenvero-stratum\n```\n\nValid levels are `debug`, `info`, `warn`, and `error`. Set it back to `info` when\nyou are done — `debug` is noisy.\n\n## Network services: on / off\n\nThe agent exposes several **network services** you can independently enable or\ndisable. View them and their live state with `service status`, and flip each one\nwith `service on|off`:\n\n```bash\n# See every service: its switch, its address:port, and whether it is listening\ncenvero-str-ctl service status\n\n# Turn services off / on\nsudo cenvero-str-ctl service rest off\nsudo cenvero-str-ctl service metrics on\n```\n\nThe toggleable services are:\n\n| Service | Name | What it is |\n|---------|------|------------|\n| REST API | `rest` | The HTTPS management & operator/billing API. |\n| gRPC API | `grpc` | The gRPC management API. |\n| WebSocket API | `websocket` | The live-events / streaming API. |\n| Metrics | `metrics` | The Prometheus `/metrics` endpoint. |\n| DNS | `dns` | The built-in DNS server. |\n| DHCP | `dhcp` | The built-in DHCP server. |\n\nThe verb-first form works too — `service off rest`, `service on dns` — and `-h`\non the group shows the help.\n\nA few notes:\n\n- **A change takes effect on the next agent restart.** After toggling a service,\n apply it with `sudo systemctl restart cenvero-stratum`, then re-check with\n `service status`.\n- **The local control socket can never be disabled** — it is how `cenvero-str-ctl`\n reaches the agent (including the command you just ran). Trying to turn it off is\n refused with an explanation.\n- **Disabling the REST API cuts off remote callers.** The REST API also serves the\n operator/billing API (tenant suspend/resume/limit). Turning it off is allowed —\n it is your call — but the command warns you first; the local socket and the panel\n are unaffected.\n\nUnder the hood, `service on|off` writes the matching off-switch into the\nsame operator local-overrides file that `config set` uses (see below), so a panel\nre-sync never clobbers your choice.\n\n## Changing settings\n\n`config set` adjusts a node's **operational settings** on a running node. It\nrecords your change in an operator local-override file that takes precedence over\nthe panel-delivered config and **survives a re-sync** — it never edits the signed\nnode config itself.\n\n```bash\n# Inspect the active configuration (paths, ports, API settings, services)\ncenvero-str-ctl config show\n\n# Change a setting, then restart to apply it\nsudo cenvero-str-ctl config set api_rate_limit 2000\nsudo systemctl restart cenvero-stratum\n```\n\nThe key names match what you see in `config show`, so the same name round-trips\nbetween the two. Commonly-set keys include:\n\n| Key | Meaning |\n|-----|---------|\n| `log_level` | Agent log level: `debug`, `info`, `warn`, `error` |\n| `api_bind_address` | IP the REST/gRPC/WebSocket APIs listen on (e.g. `0.0.0.0` or a management IP) |\n| `api_rate_limit` / `api_rate_burst` | API requests per minute per key, and the burst allowance (`0` rate disables the limiter) |\n| `api_allowed_ips` | Comma-separated IPs/CIDRs allowed to reach the API (empty = allow all) |\n| `port_rest`, `port_grpc`, `port_websocket` | API listen ports |\n| `metrics_bind_addr` | Prometheus metrics bind address `host:port` |\n| `dns_listen_addr`, `dns_allowed_clients` | Built-in DNS server bind address and allowed clients |\n\nRun `cenvero-str-ctl config set -h` for the full whitelist and per-key help.\n\n> **What you cannot set locally.** Identity, signing, and cluster-secret fields —\n> `node_id`, `license_server`, `api_token`, `gateway_shared_key`, and TLS/cluster\n> material — are **not** settable with `config set` by design. They are\n> panel-assigned or provisioned. Reaching for one returns a clear message telling\n> you where it is managed instead (e.g. TLS material is handled by\n> `cenvero-str-ctl tls …`, and the API token is rotated via the installer/panel).\n>\n> **Every `config set` change applies on the next restart.** It is saved\n> immediately, but the running agent only picks it up when it restarts.\n\n## Updates\n\nUpdates are **pull-based**: the agent polls a signed manifest from the panel and,\nwhen a newer fully-verified release for its channel is available, downloads,\nverifies, and applies it on its own. You can check or trigger this manually:\n\n```bash\n# What's installed now\ncenvero-str-ctl status\n\n# Ask the agent to check the manifest for a newer release (no download)\ncenvero-str-ctl update check\n\n# Apply an available update now (otherwise it applies on the next poll)\nsudo cenvero-str-ctl update apply\n```\n\n`update check` reports the current version, the latest on offer for your license\nchannel, and whether an update is available — without downloading anything. If the\npanel is unreachable it says so plainly rather than failing hard. `update apply`\nperforms the pull, checksum + publisher-signature verification, an atomic\nin-place swap, and a watchdog-supervised restart, with self-rollback if the\npost-restart health check fails. See [Upgrades](/docs/upgrades) for the full\nmodel (channels, downgrade protection, and rollback).\n\nA node in the **Frozen** license state keeps running its current version but\ncannot pull updates until the license is renewed.\n\n## Health checks\n\nThe agent continuously self-checks core subsystems (disk space, memory, the\ndatabase, the bridges, and the in-kernel data plane) and attempts an automatic\nrepair when one fails. Inspect or force a run:\n\n```bash\n# Latest result for every health check\ncenvero-str-ctl heal status\n\n# Force an immediate run now\nsudo cenvero-str-ctl heal check\n```\n\n---\n\n## Troubleshooting\n\n### The agent won't start\n\n**1. Read the journal** — it almost always names the cause:\n\n```bash\njournalctl -u cenvero-stratum -n 100 --no-pager\nsystemctl status cenvero-stratum\n```\n\n**2. Confirm you are running as `root`** and the host network came up:\n\n```bash\nsystemctl status cenvero-str-network\n```\n\nThe network unit must succeed first — it creates the bridges the agent attaches\nto. If it failed, fix the host networking and `sudo systemctl restart\ncenvero-str-network`.\n\n**3. Inspect the config the agent is loading:**\n\n```bash\nsudo cenvero-str-ctl config show\n```\n\nA config that fails to decode falls back to defaults with a note in the output.\nA *signed* config that fails verification is **rejected** — re-fetch a fresh\npanel-signed config rather than hand-editing the file.\n\n**4. Check disk space** and the data directory (`/var/lib/cenvero-str/`). A full disk\nstops the agent from writing its state; the health check reclaims rotated logs\nbut a genuinely full volume needs operator action.\n\n### `cenvero-str-ctl` says the agent is unreachable (exit code 3)\n\nThe CLI talks to the agent over its local socket. If commands report the agent is\nunreachable, the agent process is not running — start it and re-check:\n\n```bash\nsudo systemctl start cenvero-stratum\ncenvero-str-ctl status\n```\n\n### License is not active\n\nCheck the installed license and this machine's hardware identity:\n\n```bash\nsudo cenvero-str-ctl license status\n```\n\n- **Expired / in grace / frozen** — renew it. Existing traffic keeps running even\n when frozen; only new or changing operations are blocked. Renew with\n `sudo cenvero-str-ctl license renew` (or fetch a fresh one after renewing in\n your account). See [Licensing](/docs/licensing) for the warn → grace → freeze\n model.\n- **Not activated** — activate this machine with `sudo cenvero-str-ctl license activate CNVR-XXXX-XXXX-XXXX-XXXX`, then confirm it in your account.\n- **Hardware-ID unavailable** — `license status` shows the machine's hardware ID.\n The binding requires firmware/hardware identifiers that are not exposed inside\n generic virtual machines, so a node must be **bare metal**. If the ID shows as\n unavailable, you are likely running in an unsupported virtualized environment.\n- **Wrong release channel** — a stable license runs only stable builds and a\n pre-release license runs only beta/RC builds; a mismatch fails closed. Make sure\n the build you installed matches your license's channel.\n\n### TLS certificate is pending\n\nAfter install the agent generates its own certificate; if a customer-approval or\ndomain step is outstanding the certificate can show as pending. Confirm what the\nagent is using and re-issue if needed:\n\n```bash\nsudo cenvero-str-ctl config show # shows the TLS cert/key paths in use\nsudo cenvero-str-ctl tls -h # certificate management commands\n```\n\nTLS material is managed by the certificate manager (`cenvero-str-ctl tls …`), not\n`config set`. Adding or removing a SAN domain re-generates the certificate.\n\n### Node is not registered\n\nRegistration binds the node to its license and mints its node token. If a node\nnever registered, re-check connectivity to the panel and the license, then let it\nre-register:\n\n```bash\ncenvero-str-ctl status # shows license + registration state\nsudo cenvero-str-ctl license activate CNVR-XXXX-XXXX-XXXX-XXXX\n```\n\nRegistration needs outbound HTTPS to your management/license server and a valid\nlicense. If the panel is unreachable, the agent keeps retrying — fix connectivity\nand it completes on its own.\n\n### \"REST API disabled\" — set an API token\n\nIf a client gets a *REST API disabled* (or 401/unauthorized) response, two\nsettings govern access:\n\n**1. Is the service enabled?** Confirm with `cenvero-str-ctl service status`. If\n`rest` is **off**, turn it back on and restart:\n\n```bash\nsudo cenvero-str-ctl service rest on\nsudo systemctl restart cenvero-stratum\n```\n\n**2. Is an API token set?** The REST/gRPC/WebSocket APIs require the bearer token\nto be configured. `config show` reports **Token set: yes/no**. The token is a\n**credential**, so it is *not* set with `config set` — it is provisioned by the\ninstaller (which generates one and prints it) or rotated via the panel. If no\ntoken is set, re-run the installer / fetch a panel-signed config to provision\none, then restart the agent.\n\n### Where to look first\n\n| Symptom | First check |\n|---------|-------------|\n| Agent down / crash-looping | `journalctl -u cenvero-stratum -n 100` |\n| CLI \"agent unreachable\" | `systemctl status cenvero-stratum` |\n| License problems | `cenvero-str-ctl license status` |\n| A service not answering | `cenvero-str-ctl service status` |\n| Settings not taking effect | Did you `systemctl restart cenvero-stratum`? |\n| Overall health | `cenvero-str-ctl heal status` |\n\n## Next steps\n\n- **[CLI Reference](/docs/cli)** — the full command surface.\n- **[Configuration](/docs/configuration)** — the node config and what it controls.\n- **[Licensing](/docs/licensing)** — the enforcement state machine.\n- **[Upgrades](/docs/upgrades)** — how updates are pulled and verified.\n" }, { "slug": "monitoring", "title": "Monitoring & Observability", "category": null, "url": "https://www.stratum.cenvero.com/docs/monitoring", "headings": [ { "level": 1, "text": "Monitoring & Observability" }, { "level": 2, "text": "Status: is this node healthy?" }, { "level": 2, "text": "Metrics: how much of what" }, { "level": 2, "text": "Flows: who is talking to whom" }, { "level": 2, "text": "Alerts: tell me when something happens" }, { "level": 2, "text": "Audit: who changed what" }, { "level": 2, "text": "Live events" }, { "level": 2, "text": "What to watch" }, { "level": 2, "text": "Reaching a node from a collector" }, { "level": 2, "text": "Where to go next" } ], "word_count": 903, "markdown": "# Monitoring & Observability\n\nWhat a node can tell you about itself, and which source to reach for. There are\nfive, and picking the wrong one is the usual reason a question feels hard to\nanswer.\n\n| Source | Answers | Shape |\n|---|---|---|\n| **Status** | Is this node healthy right now? | One snapshot |\n| **Metrics** | How much of what, over time? | Counters and gauges |\n| **Flows** | Who is actually talking to whom? | Live connections |\n| **Alerts** | Tell me when something crosses a line | Push |\n| **Audit** | Who changed what, and when? | Append-only history (API only) |\n\nLogs sit underneath all of them — see [Operations](/docs/operations) for reading\nthem.\n\n## Status: is this node healthy?\n\nThe first command to run, and usually the only one needed:\n\n```bash\ncenvero-str-ctl status\n```\n\nIt reports whether the agent is running, the licence state, the data plane, and\nthe bridges. When something is wrong this is where it shows up first.\n\nHealth checks run on their own schedule and record their results:\n\n```bash\ncenvero-str-ctl heal status # latest result for every check\ncenvero-str-ctl heal check # force a run now, don't wait for the schedule\n```\n\n`heal status` is the better command when you want to know whether a problem is\n*recurring* rather than whether it is happening this second.\n\n## Metrics: how much of what\n\n```bash\ncenvero-str-ctl metrics\ncenvero-str-ctl metrics --format json\n```\n\nA snapshot of the node's counters. The JSON form is what you scrape into whatever\nyou already use for graphing — the same data is available over the API at\n`GET /api/v1/metrics` for a collector that cannot run commands on the node.\n\nFor traffic volume specifically — how much a tenant or endpoint used, rather than\nhow the node is behaving — use accounting instead, which is what billing reads:\n\n```bash\ncenvero-str-ctl bandwidth list # configured limits\ncenvero-str-ctl quota list # volume caps and consumption\n```\n\n## Flows: who is talking to whom\n\nMetrics tell you a link is busy. Flows tell you *what* is making it busy.\n\n```bash\ncenvero-str-ctl flow list # live connections\ncenvero-str-ctl flow stats # aggregate view\n```\n\nThis is the tool for \"the network is slow\", \"is this rule doing anything\", and\n\"what is this host actually connecting to\". Over the API, flows can also be\nexported for offline analysis.\n\nTwo things to know. Flows show conversations the data plane is currently tracking,\nso a connection that finished is gone — this is a live view, not a history. And a\nlong-established connection appears even after you have tightened a rule against\nit, because existing conversations survive a policy change until they end or are\nflushed. That surprise is covered in\n[Zero-Trust Firewall](/docs/networking/firewall).\n\n## Alerts: tell me when something happens\n\nEverything above is you asking. Alerts are the node telling you.\n\n```bash\ncenvero-str-ctl alert condition list # what is being watched\ncenvero-str-ctl alert list # what is currently firing\ncenvero-str-ctl alert history # what has fired before\ncenvero-str-ctl alert status # is alerting itself working?\ncenvero-str-ctl alert ack # acknowledge a firing alert\n```\n\nConditions define what to watch for. Actions define what happens when one fires,\nso an alert can reach a system you already run rather than waiting to be noticed.\n\n**Check `alert status` occasionally.** It reports whether action dispatch is\nsucceeding. Alerting that is configured but silently failing to deliver is worse\nthan no alerting, because it is mistaken for quiet.\n\n## Audit: who changed what\n\nAn append-only record of changes made through the agent, with who made them and\nwhen. Reach for it when the question is \"why is this configured like this\" or\n\"what changed just before it broke\" — that second question is answered faster here\nthan in the logs.\n\nThe audit trail is available over the API at `GET /api/v1/audit`; there is no CLI\ncommand for it, so reading it needs the API turned on (see\n[Security Model](/docs/security)). On a node where the API is off, the agent's\nlogs in `/var/log/cenvero-str/` are the fallback — see\n[Operations](/docs/operations).\n\n## Live events\n\nFor a continuous feed rather than polling, the agent publishes events over a\nWebSocket on port 7072, grouped into categories (traffic, bandwidth, security,\nDHCP, DNS, network, alerts, system, load balancing, and clustering) so a consumer\ncan subscribe to only what it cares about. See the\n[Management API Reference](/docs/api).\n\n## What to watch\n\nIf you are setting up monitoring for the first time, start here:\n\n- **Agent up, and licence not frozen.** A frozen licence blocks changes silently\n from a traffic standpoint — everything keeps flowing, so nothing looks wrong\n until a change fails. Watch the licence state, not just the process.\n- **Health-check results.** Repeated failures of one check are the earliest\n warning of most problems.\n- **Certificate expiry.** See [TLS/SSL & Licence Operations](/docs/tls-and-license).\n- **Gateway failover events.** A failover that happened and recovered is easy to\n miss, and it usually means something is worth investigating.\n- **Cluster leadership changes.** Occasional is normal; frequent is not.\n- **Alert dispatch failures.** As above — verify the alerting path works.\n\n## Reaching a node from a collector\n\nThe CLI works over a local socket and needs no network, which is why it keeps\nworking when the API is off. A remote collector needs the API turned on, which\nmeans a token and an address allowlist — see [Security Model](/docs/security)\nbefore exposing it.\n\n## Where to go next\n\n- **[Operations](/docs/operations)** — logs, health checks, and troubleshooting.\n- **[Management API Reference](/docs/api)** — the endpoints behind these commands.\n- **[Security Model](/docs/security)** — before exposing the API to a collector.\n" }, { "slug": "security", "title": "Security", "category": null, "url": "https://www.stratum.cenvero.com/docs/security", "headings": [ { "level": 1, "text": "Security" }, { "level": 2, "text": "Protected without any setup" }, { "level": 2, "text": "Your checklist" }, { "level": 2, "text": "Available if you want it" }, { "level": 2, "text": "What is *not* protected" }, { "level": 2, "text": "If a node may be compromised" }, { "level": 2, "text": "Reporting a security issue" }, { "level": 2, "text": "Where to go next" } ], "word_count": 746, "markdown": "# Security\n\nWhat Stratum protects on its own, what you need to set up yourself, and what it\ndeliberately does not protect against. The last part matters most: assuming a\nboundary exists where it does not is how people get hurt.\n\n## Protected without any setup\n\nYou do not need to configure any of this.\n\n- **The management API is closed until you open it.** It will not serve requests\n without a token, and there is no insecure fallback.\n- **The API is encrypted.** There is no unencrypted way in.\n- **Repeated failed sign-ins are locked out**, and an attacker cannot turn that\n lockout into a way of denying access to a legitimate user.\n- **Configuration and licences are verified before they are trusted.** Anything\n altered in transit, or issued by anyone other than Cenvero, is refused —\n checked on the node itself, so it works offline.\n- **Workloads cannot impersonate each other.** Traffic from a workload must match\n what that workload is registered as. This is enforced on every packet.\n- **Changes made outside Stratum are undone.** If something alters an interface\n Stratum manages, it is put back.\n\n## Your checklist\n\nNone of this happens on its own.\n\n**Deny by default in the firewall.** Until you do, traffic matching no rule is\nallowed. See [Zero-Trust Firewall](/docs/networking/firewall).\n\n**Treat the API token as a credential.** It grants full control of the node.\nCreate it at install time, keep it out of shell history and version control, and\nreplace it if it may have been exposed.\n\n**Limit who can reach the API.** It can be restricted to specific addresses. An\nAPI reachable from the internet is a mistake even with a strong token — keep it\non your management network.\n\n**Keep the management network private.** Stratum assumes only your operators can\nreach it.\n\n**Keep nodes updated.** Updates are pulled, never pushed, so a node nobody\nupdates stays vulnerable. See [Upgrades](/docs/upgrades).\n\n**Back up `/etc/cenvero-str/` and `/var/lib/cenvero-str/`.** They are what a node\nneeds to come back as itself.\n\n## Available if you want it\n\n- **Stricter interface protection.** By default an unauthorised change to a\n managed interface is undone shortly after it happens. On a suitably configured\n kernel it can be refused outright instead. Off unless you enable it.\n- **Client certificates** on the streaming interface, in addition to a token.\n- **Intrusion detection**, surfacing scanning and flooding patterns. Off by\n default.\n\n## What is *not* protected\n\n**Someone with root on the node.** The design protects against what arrives over\nthe network, not against an administrator of the machine itself. Anyone with root\ncan stop or replace what is running there. Verification exists to stop a remote\nattacker substituting configuration or licences — it does not, and cannot,\nconstrain someone who already owns the box.\n\n**Interface protection is repair, not prevention.** By default a change is\ndetected and undone, so there is a window where it applied. Treat it as\ntamper-evidence with automatic repair rather than a lock.\n\n**Plugins are trusted code.** Signing proves a plugin is genuinely the one its\ndeveloper published and has not been altered since. That is authenticity, not\ncontainment — a plugin you install runs with real access to the node, exactly\nlike any other software you install as root. **Only install plugins from sources\nyou trust.** See [Installing Plugins](/docs/plugins/installing).\n\n**A frozen licence is not a security control.** It blocks changes; traffic keeps\nflowing. To take a node out of service, isolate it on the network.\n\n**Existing connections survive a rule change.** Tightening a rule governs new\nconnections; conversations already open continue until they end. If you are\ncutting traffic off during an incident, clear them explicitly — see\n[Zero-Trust Firewall](/docs/networking/firewall).\n\n## If a node may be compromised\n\n1. **Isolate it on the network**, upstream — not using the node's own firewall.\n2. **Revoke its licence** from your account. That stops it making changes; it\n does not stop traffic.\n3. **Collect evidence before restarting anything.** Logs are in\n `/var/log/cenvero-str/`. Restarting is the first instinct and it can cost you\n the answer.\n4. **Replace the API token** and any tenant keys the node held.\n5. **Rebuild rather than clean up.** If root was obtained, reinstall.\n\n## Reporting a security issue\n\nReport it through your account rather than publicly, with enough detail to\nreproduce it.\n\n## Where to go next\n\n- **[Zero-Trust Firewall](/docs/networking/firewall)** — the policy model in full.\n- **[TLS/SSL & Licence Operations](/docs/tls-and-license)** — certificates and licences.\n- **[Operations](/docs/operations)** — logs, health checks, and recovery.\n" }, { "slug": "cli", "title": "CLI Reference", "category": null, "url": "https://www.stratum.cenvero.com/docs/cli", "headings": [ { "level": 1, "text": "CLI Reference" }, { "level": 2, "text": "Status & system" }, { "level": 3, "text": "`status`" }, { "level": 3, "text": "`version`" }, { "level": 3, "text": "`metrics`" }, { "level": 3, "text": "`hardware`" }, { "level": 3, "text": "`pull`" }, { "level": 2, "text": "System management" }, { "level": 3, "text": "`config`" }, { "level": 3, "text": "`service`" }, { "level": 3, "text": "`api-token`" }, { "level": 3, "text": "`tls`" }, { "level": 3, "text": "`update`" }, { "level": 3, "text": "`license`" }, { "level": 2, "text": "Networking" }, { "level": 3, "text": "`network`" }, { "level": 3, "text": "`nic`" }, { "level": 3, "text": "`ipam`" }, { "level": 3, "text": "`dhcp`" }, { "level": 3, "text": "`dns`" }, { "level": 3, "text": "`vlan`" }, { "level": 3, "text": "`vxlan`" }, { "level": 3, "text": "`route`" }, { "level": 2, "text": "Security" }, { "level": 3, "text": "`firewall`" }, { "level": 3, "text": "`rules`" }, { "level": 2, "text": "Traffic shaping & visibility" }, { "level": 3, "text": "`bandwidth`" }, { "level": 3, "text": "`quota`" }, { "level": 3, "text": "`flow`" }, { "level": 2, "text": "Services & HA" }, { "level": 3, "text": "`lb`" }, { "level": 3, "text": "`bgp`" }, { "level": 3, "text": "`gateway`" }, { "level": 3, "text": "`ha`" }, { "level": 3, "text": "`bond`" }, { "level": 3, "text": "`cluster`" }, { "level": 2, "text": "Tenants & billing" }, { "level": 3, "text": "`tenant`" }, { "level": 3, "text": "`apikeys`" }, { "level": 3, "text": "`billing`" }, { "level": 2, "text": "Operations" }, { "level": 3, "text": "`backup`" }, { "level": 3, "text": "`alert`" }, { "level": 3, "text": "`heal`" }, { "level": 3, "text": "`container`" }, { "level": 3, "text": "`plugin`" }, { "level": 3, "text": "`node`" }, { "level": 2, "text": "Exit codes" }, { "level": 2, "text": "See also" } ], "word_count": 3607, "markdown": "# CLI Reference\n\n`cenvero-str-ctl` is the operator interface to a node. It talks to the running\nagent over a local socket, so it only works **on the node itself** and needs\n`root` for any command that changes state. The socket is always available — it is\nthe node's management lifeline and can never be disabled.\n\n```bash\ncenvero-str-ctl [args] [flags]\n```\n\n- Add `--format json` (or `yaml`) to any command for machine-readable output\n (the default is a human table/JSON view).\n- Add `-h` to any group or command for its full help, subcommands, and flags.\n- The same managers are reachable over the node's [REST API](/docs/api); this CLI\n is the local equivalent.\n\nThe command groups, by area:\n\n| Area | Groups |\n|---|---|\n| Status & system | `status` `version` `metrics` `hardware` `pull` |\n| System management | `config` `service` `tls` `update` `license` |\n| Networking | `network` `nic` `ipam` `dhcp` `dns` `vlan` `vxlan` `geneve` `vrf` `route` |\n| Security | `firewall` `rules` |\n| Traffic shaping & visibility | `bandwidth` `quota` `flow` |\n| Services & HA | `lb` `l7lb` `bgp` `gateway` `nat64` `ha` `bond` `cluster` |\n| Tenants & billing | `tenant` `apikeys` `billing` |\n| Operations | `backup` `alert` `heal` `container` `plugin` `node` |\n\n---\n\n## Status & system\n\n### `status`\n\n```bash\ncenvero-str-ctl status # health summary: version, license, data plane, bridges, cluster\n```\n\n### `version`\n\n```bash\ncenvero-str-ctl version # agent version\n```\n\n### `metrics`\n\n```bash\ncenvero-str-ctl metrics # current metrics snapshot\n```\n\n### `hardware`\n\nPrint this machine's **hardware ID** — the value an activation or SSL request is\nbound to. Use it to verify a pending request in your account before approving it.\n\n```bash\ncenvero-str-ctl hardware\n```\n\n### `pull`\n\nForce an immediate pull of the node's CA-signed TLS certificate **and** a license\nre-sync (fetch a pending activation, auto-renew, re-evaluate) now, instead of\nwaiting for the next background poll. Run it right after approving a node's\nSSL/license in your account.\n\n```bash\nsudo cenvero-str-ctl pull\n```\n\n---\n\n## System management\n\n### `config`\n\n| Command | Purpose |\n|---|---|\n| `config set [ ]` | Change a whitelisted operational setting (run with no args to list keys) |\n| `config show` | Print the decoded on-disk configuration (secrets redacted) |\n| `config dump` | Dump the on-disk configuration |\n| `config encode` | Write the node's signed configuration from flags (used by the installer) |\n\n`config set` writes to an **operator local-overrides** file that the agent layers\non top of its configuration at the next restart — and that a panel re-sync will\n**not** clobber (local always wins). Use the positional `config set `\nform, or the `--api-bind` / `--api-rate-limit` / `--api-rate-burst` shortcuts.\nApply with `systemctl restart cenvero-stratum`; verify with `config show`.\n\n```bash\nsudo cenvero-str-ctl config set api_rate_limit 2000\nsudo cenvero-str-ctl config set --api-bind 10.0.0.5 --api-rate-limit 2000 --api-rate-burst 200\nsudo cenvero-str-ctl config set # list every settable key\n```\n\n**Settable keys:** `log_level`, `api_bind_address`, `api_rate_limit`,\n`api_rate_burst`, `api_allowed_ips`, `api_allowed_origins`,\n`api_read_timeout_secs`, `api_write_timeout_secs`, `api_idle_timeout_secs`,\n`port_rest`, `port_grpc`, `port_websocket`, `port_cluster`, `port_ha_heartbeat`,\n`metrics_bind_addr`, `dns_listen_addr`, `dns_allowed_clients`, `dns_upstreams`,\n`heal_interval_seconds`, `heal_disabled_checks`, and the six service switches\n(`rest_disabled`, `grpc_disabled`, `websocket_disabled`, `metrics_disabled`,\n`dns_disabled`, `dhcp_disabled`). Identity, the license server, the API token, and\nany signing/cluster-secret/TLS material are **refused** — they are panel- or\nidentity-owned, not local operational settings. See\n[Configuration](/docs/configuration) for the full field reference.\n\n`config show` / `dump` are read-only and decode the actual on-disk file (table,\n`--format json`, or `--format yaml`); pass `--include-secrets` to reveal redacted\nvalues, or `--file ` to inspect a specific file. `config encode` is what the\ninstaller uses to write the node's configuration and prints the resulting\n`api_token`.\n\n### `service`\n\nSee and toggle the agent's network services. `service status` shows each service's\n**ENABLED** switch, its **ADDRESS:PORT**, and a live **STATE**. Toggle a service on\nor off; the change applies on the next agent restart.\n\n| Command | Purpose |\n|---|---|\n| `service status` | Show each service (aliases: `list`, `top`, `ls`, `ps`) |\n| `service on` | Enable a service (also `service on `) |\n| `service off` | Disable a service (also `service off `) |\n\nToggleable services: `rest`, `grpc`, `websocket`, `metrics`, `dns`, `dhcp`.\nDisabling `rest` warns first (it also serves the operator/billing API). The **IPC\ncontrol socket is not toggleable** — it is how this CLI reaches the agent.\n\n```bash\nsudo cenvero-str-ctl service status\nsudo cenvero-str-ctl service rest off\nsudo cenvero-str-ctl service websocket on\nsudo systemctl restart cenvero-stratum # apply\n```\n\nEnabling `rest`, `grpc` or `websocket` is only half of it — the management APIs\nalso require an API token before they will serve, so a service you switch on with\nno token configured stays `down`. See `api-token` below.\n\n### `api-token`\n\nManage the bearer token the management APIs (REST, gRPC, WebSocket) require. With\nno token the agent refuses to open a management API at all rather than serve one\nwithout a credential, so this is what turns them on.\n\n| Command | Purpose |\n|---|---|\n| `api-token generate` | Mint a strong random token, store it, print it **once** |\n| `api-token set` | Store a token you supply, read from **stdin** |\n| `api-token status` | Report whether a token is set — never prints the value |\n| `api-token clear` | Remove it; the APIs stop serving at the next restart |\n\n```bash\nsudo cenvero-str-ctl api-token generate\nsudo cenvero-str-ctl service on rest\nsudo systemctl restart cenvero-stratum\n```\n\n`generate` shows the token once and it is not recoverable afterwards — copy it\nthen. To choose the value yourself, pipe it in so it never reaches your shell\nhistory; there is deliberately no flag to pass it as an argument:\n\n```bash\nprintf '%s' \"$MY_TOKEN\" | sudo cenvero-str-ctl api-token set\n```\n\nTokens shorter than 16 characters are refused. The value is stored in your local\noverrides, so a later configuration sync from the panel will not discard it. It is\nnot settable through `config set`, which rejects credential keys for the same\nshell-history reason.\n\nA management API binds only when **all three** hold: a token exists, the service\nis on, and the node has a TLS certificate — the agent never serves plaintext.\n\n### `tls`\n\nManage the management API's TLS certificate. After install the node serves a\ntemporary self-signed certificate; in CA mode it obtains a CA-signed certificate\nonce you approve the request in your account (Account → TLS). The private key never\nleaves the node.\n\n| Command | Purpose |\n|---|---|\n| `tls info` | Live certificate: mode (`ca-signed`/`self-signed`), expiry, SAN domains |\n| `tls show` | The certificate / key / public-key file locations |\n| `tls pubkey` | Print the public-key file location |\n| `tls request` | Request a CA-signed certificate from the panel now (online) |\n| `tls pull` | Pull this node's CA-signed certificate now (collect it once approved) |\n| `tls regenerate` | Generate a fresh certificate now (hot-reloaded, no restart) |\n| `tls csr` | Generate a key + CSR locally **without** contacting the panel (offline) |\n| `tls install [chain]` | Install a signed certificate obtained out-of-band |\n| `tls pending-status` | Report any pending certificate request (online or offline) |\n| `tls reset-pending` | Discard a pending offline CSR so you can start fresh |\n| `tls reset` | Clear the current certificate + pending request and re-obtain a fresh one |\n| `tls domain list` | List the SAN domains on the certificate |\n| `tls domain add ` | Add a SAN domain (regenerates the certificate) |\n| `tls domain remove ` | Remove a SAN domain (regenerates the certificate) |\n\n```bash\nsudo cenvero-str-ctl tls info\nsudo cenvero-str-ctl tls pull # collect the CA-signed cert after approval\nsudo cenvero-str-ctl tls domain add api.example.net\n```\n\nThe certificate always covers the node's IP(s) plus loopback; a domain you point at\nthe node's IP can be added with `tls domain add`. See\n[TLS & Licensing](/docs/tls-and-license) for the approval flow.\n\n### `update`\n\nPull-based agent updates from your licensed release channel.\n\n| Command | Purpose |\n|---|---|\n| `update check` | Report current vs latest version + channel (no download) |\n| `update apply` | Download, verify, and apply an available update now (alias `update now`) |\n| `update rollback` | Roll back to the previously-installed version |\n\n```bash\ncenvero-str-ctl update check\nsudo cenvero-str-ctl update apply\nsudo cenvero-str-ctl update rollback # undo the last apply\n```\n\n`update apply` verifies the download's signature, swaps the binary atomically, and\nrestarts under watchdog supervision with self-rollback if the post-restart health\ncheck fails. A node in the **Frozen** license state keeps running but cannot pull\nupdates until the license is renewed. See [Upgrades](/docs/upgrades).\n\n`update rollback` restores the binary that the most recent `update apply`\npreserved, undoing that update; restart the agent (`systemctl restart\ncenvero-stratum`) to run the restored version. If no update has been applied on\nthis node there is nothing to restore and it reports *\"no previous version to roll\nback to\"*. Rollback is a change, so it is refused while the license is **Frozen**.\nRe-applying a version at or below the highest version this node has ever run is\nrefused by downgrade protection — to move forward again, install a newer release.\n\n### `license`\n\n| Command | Purpose |\n|---|---|\n| `license activate ` | Send this machine's activation request (confirm it in your account) |\n| `license fetch ` | Fetch the signed license once it has been confirmed |\n| `license renew` | Force a license renewal for this machine |\n| `license refresh` | Re-fetch the signed license for this machine |\n| `license load ` | Load a signed license file manually |\n| `license status` | Full installed-license picture: identity, validity/state, features, hardware binding |\n\nThe license key is **positional**, not a flag. Activation binds the license to this\nmachine's hardware ID and waits for you to confirm the machine in your account; the\nagent then installs the signed license automatically.\n\n```bash\nsudo cenvero-str-ctl license activate CNVR-XXXX-XXXX-XXXX-XXXX\nsudo cenvero-str-ctl license status\n```\n\n`license status` is read-only and works offline from on-disk state, so it still\nanswers when the agent is down or the node cannot reach the licence server.\n\nThe same picture is available over the API as `GET /api/v1/license`, which reads\nthe running agent rather than the disk — useful for checking a fleet's expiry\ndates without a shell on every box. See [API Reference](/docs/api).\n\nSee [Licensing](/docs/licensing) for the warning → grace → freeze model.\n\n---\n\n## Networking\n\n### `network`\n\nA *network* is a managed private network: a CIDR pool whose usable host IPs are\neach materialized into an **endpoint profile** (a fixed IP paired with a generated\nMAC). You attach a workload by claiming a free endpoint — the endpoint *is* the\nworkload's network identity.\n\n| Command | Purpose |\n|---|---|\n| `network create` | Create a network (`--name --cidr [--gateway --vlan --tenant]`) |\n| `network list` | List networks |\n| `network show ` | Network detail + its endpoints |\n| `network endpoints ` | List a network's endpoint profiles (IP ↔ MAC) |\n| `network attach [--ip] [--mac]` | Claim an endpoint (optionally a specific IP and MAC) |\n| `network set-mac ` | Change an endpoint's MAC, keeping its IP |\n| `network detach ` | Free a bound endpoint |\n| `network delete ` | Delete a network |\n\n```bash\nsudo cenvero-str-ctl network create --name app-net --cidr 10.20.0.0/24 --gateway 10.20.0.1\nsudo cenvero-str-ctl network attach --ip 10.20.0.50\n```\n\nEach endpoint is an IP paired with a MAC address, and the MAC is assigned for you.\nPass `--mac` when the workload already has a fixed address of its own — a virtual\nmachine image, or an appliance whose licence is tied to one — so the fabric\naccepts the address it will actually send from:\n\n```bash\nsudo cenvero-str-ctl network attach --ip 10.20.0.50 --mac 52:54:00:ab:01:02\n\n# ...or change it afterwards, keeping the same IP\nsudo cenvero-str-ctl network set-mac 52:54:00:ab:01:02\n```\n\nA MAC must be unique across endpoints, and a multicast address is refused — one\ncan never be a source address, so traffic from it would be dropped.\n\n### `nic`\n\n| Command | Purpose |\n|---|---|\n| `nic list` | List detected network interfaces |\n| `nic detect` | Re-scan and list interfaces |\n| `nic accel` | Show the acceleration mode (hardware vs software) per interface |\n\n### `ipam`\n\n| Command | Purpose |\n|---|---|\n| `ipam pools` | List IP pools |\n| `ipam allocations` | List every allocation (optional tenant id) |\n| `ipam allocate` | Allocate an IP address |\n| `ipam release` | Release an IP address |\n\n### `dhcp`\n\n| Command | Purpose |\n|---|---|\n| `dhcp leases` | List DHCP leases |\n| `dhcp reservations` | List static MAC→IP reservations |\n| `dhcp reserve [--hostname]` | Pin a static MAC→IP reservation |\n| `dhcp release ` | Remove a static reservation, returning the address to the pool |\n\n```bash\nsudo cenvero-str-ctl dhcp reserve 52:54:00:ab:01:02 10.0.0.50 --hostname db01\n```\n\nA reserved address is handed out on the client's next request, survives an agent\nrestart, and appears immediately in `dhcp leases`.\n\n### `dns`\n\nManage authoritative zones, records, recursive forwarders, and DNSSEC.\n\n| Command | Purpose |\n|---|---|\n| `dns zones` | List zones |\n| `dns records [zone_id]` / `dns list [zone_id]` | List records (optionally for one zone) |\n| `dns add [ttl] [source_subnet]` | Add a record |\n| `dns delete ` | Delete a record |\n| `dns dnssec ` | Show a zone's DNSSEC keys + the DS record to lodge with the parent |\n| `dns zone list/add /delete ` | Zone CRUD |\n| `dns record list [zone_id]/add .../delete ` | Record CRUD |\n| `dns forwarder list/set /add /remove ` | Manage recursive forwarders |\n\nEach forwarder is an IP or `IP:port` (bare IPs default to `:53`). `dns forwarder`\nchanges apply to the running agent; persist them across restarts with\n`config set dns_upstreams `.\n\n```bash\nsudo cenvero-str-ctl dns zone add app-net.internal\nsudo cenvero-str-ctl dns add 1 api A 10.20.0.55 300\n```\n\n### `vlan`\n\nA per-VLAN allow/deny table. An empty table means every VLAN is allowed (default).\n\n| Command | Purpose |\n|---|---|\n| `vlan list` | List the allow/deny policy |\n| `vlan deny ` | Lock down a VLAN |\n| `vlan allow ` | Record an explicit allow |\n| `vlan clear ` | Clear a VLAN's policy (back to default-open) |\n\n### `vxlan`\n\n| Command | Purpose |\n|---|---|\n| `vxlan list` | List overlay networks |\n| `vxlan create ` | Create an overlay network |\n| `vxlan delete ` | Delete an overlay network |\n| `vxlan peers ` | List a VNI's remote peers |\n| `vxlan peer-add ` | Add a remote peer |\n| `vxlan peer-remove ` | Remove a remote peer |\n| `vxlan fdb` | Dump the overlay forwarding database |\n\n### `route`\n\nStatic routes (optionally in a non-main table) and the policy rules that steer\ntraffic into those tables.\n\n| Command | Purpose |\n|---|---|\n| `route list [table]` | List routes (optional table id) |\n| `route add ` | Add a route — JSON `{destination,gateway,interface,metric,table}` |\n| `route delete ` | Delete a route by id |\n| `route rule list` | List policy-routing rules |\n| `route rule add ` | Add a rule — JSON `{priority,from,to,fwmark,iif,oif,table}` |\n| `route rule delete ` | Delete a policy-routing rule by id |\n\n---\n\n## Security\n\n### `firewall`\n\n| Command | Purpose |\n|---|---|\n| `firewall allow` | Add an allow rule |\n| `firewall deny` | Add a deny rule |\n| `firewall list` | List firewall rules |\n| `firewall delete` | Delete a rule |\n| `firewall conntrack` | Show the connection-tracking table |\n| `firewall conntrack-flush [ipv4]` | Drop connection-tracking state so rule changes apply to connections that are already open (optionally just one peer) |\n| `firewall schedule set/clear/list` | Attach a time-of-day/day-of-week activation window (UTC) to a rule |\n| `firewall connlimit set/clear/status` | Per-source concurrent-connection limits (IPv4) |\n\n### `rules`\n\nThe structured firewall rule table (chains, priorities, stateful matching).\n\n| Command | Purpose |\n|---|---|\n| `rules list` | List all rules |\n| `rules add` | Add a rule |\n| `rules remove ` | Remove a rule by id |\n| `rules preset ` | Apply a server preset rule-set atomically |\n| `rules batch ` | Apply a JSON array of rules atomically |\n\n---\n\n## Traffic shaping & visibility\n\n### `bandwidth`\n\n| Command | Purpose |\n|---|---|\n| `bandwidth list` | List per-MAC rate limits and shared pools |\n| `bandwidth set` | Create/update a per-MAC rate limit |\n| `bandwidth pool` | Manage shared bandwidth pools |\n\n### `quota`\n\nMonthly per-MAC usage caps that reset at the start of each UTC month.\n\n| Command | Purpose |\n|---|---|\n| `quota list` | List quotas with their status |\n| `quota set ` | Create/update a quota |\n| `quota get ` | Show one MAC's quota + status |\n\n### `flow`\n\n| Command | Purpose |\n|---|---|\n| `flow list` | List active flows (optional state filter) |\n| `flow stats` | Aggregate flow statistics |\n\n---\n\n## Services & HA\n\n### `lb`\n\nL4 virtual IPs (VIPs) with a backend pool.\n\n| Command | Purpose |\n|---|---|\n| `lb list` | List VIPs |\n| `lb create` | Create a VIP and backend set |\n| `lb show` | Show a VIP's detail |\n| `lb backends ` | List a VIP's backends |\n| `lb add-backend` / `lb remove-backend` | Adjust backends live |\n| `lb drain ` | Stop sending new connections to a backend and let the existing ones finish |\n| `lb set-health` | Configure a VIP's health check |\n| `lb delete` | Delete a VIP |\n\n### `bgp`\n\n| Command | Purpose |\n|---|---|\n| `bgp status` | Engine status |\n| `bgp neighbors` | List peers |\n| `bgp routes` / `bgp rib` / `bgp fib` | Route table / RIB / forwarding table |\n| `bgp peer` | Manage peers (add/list/remove) |\n| `bgp announce` / `bgp withdraw` | Advertise / withdraw a prefix |\n| `bgp announcements` | List active announcements |\n| `bgp prefix-list` | Manage prefix-lists (`add ` / `list`) |\n| `bgp route-map` | Manage route-maps (`add ` / `list`) |\n| `bgp policy` | Bind import/export route-maps (`import/export ` / `list`) |\n| `bgp import-policy` | Manage import policy |\n\n### `gateway`\n\n| Command | Purpose |\n|---|---|\n| `gateway status` | Gateway HA status |\n| `gateway failover` | Trigger a manual gateway failover |\n\n### `ha`\n\nGateway high-availability: two paired nodes run active/standby and the active node\nowns a virtual IP (VIP), taking it over on failover.\n\n| Command | Purpose |\n|---|---|\n| `ha status` | Show HA status (active/standby/solo, VIP, peer) |\n| `ha set-peer` | (Provisioned via the panel-delivered config) |\n| `ha configure` | (Provisioned via the panel-delivered config) |\n\nHA is configured from the panel-delivered configuration (peer address, priority,\nVIP, and a shared secret) and read at agent boot. Use `ha status` and the\n[REST gateway endpoints](/docs/api) for live status and\nmanual failover.\n\n### `bond`\n\nCombine physical NICs into a bond for redundancy or throughput. A bond is created\nwith a device name you choose (use the `cnv-` prefix, max 15 chars) in one of two\nmodes: `active-backup` (one member carries traffic, another takes over on failure)\nor `802.3ad` (LACP aggregation, needs a matching switch port-channel).\n\n| Command | Purpose |\n|---|---|\n| `bond list` | List bonds |\n| `bond show ` | Show a bond (mode, MTU, active member, members) |\n| `bond create --name --mode active-backup/802.3ad [--mtu N]` | Create a bond |\n| `bond add-member --iface ` | Enslave a NIC |\n| `bond remove-member --iface ` | Release a NIC |\n| `bond set-mtu --mtu N` | Set the MTU across the bond + members |\n| `bond delete ` | Delete a bond (releases its members first) |\n\n```bash\nsudo cenvero-str-ctl bond create --name cnv-bond0 --mode active-backup\nsudo cenvero-str-ctl bond add-member --iface cnv-nic-1\nsudo cenvero-str-ctl bond set-mtu --mtu 9000\n```\n\n`create` prints the bond's **logical id** (e.g. `bond-1a2b…`); use that id — not the\ndevice name — with the other subcommands. Members are referenced by interface name.\n\n### `cluster`\n\nInspect this node's clustering state. Every member is the same kind of node, so\nthere is nothing to choose here — `cluster status` reports the local role in the\ncluster (leader or follower), not a node type.\n\n| Command | Purpose |\n|---|---|\n| `cluster status` | Cluster state, leader, and peers |\n| `cluster join` | (Configured via the panel-delivered config / REST API) |\n| `cluster leave` | (Configured via the panel-delivered config / REST API) |\n\nCluster membership is configured through the panel-delivered configuration; peers\nauthenticate with mutual TLS (no join token to type). Use `cluster status` to check\nthe local state. See [Clustering](/docs/clustering/overview).\n\n---\n\n## Tenants & billing\n\n### `tenant`\n\nTenants are your downstream customers on this node, each with a resource quota and\noptional scoped API keys.\n\n| Command | Purpose |\n|---|---|\n| `tenant list` | List tenants |\n| `tenant create --name ` | Create a tenant |\n| `tenant delete ` | Delete a tenant — also removes its scoped API keys, quota, private networks, and IPAM pools/allocations |\n| `tenant quota ` | Show a tenant's bandwidth cap |\n| `tenant quota-set --max-bandwidth-bps N` | Set a tenant's bandwidth cap (`0` = unlimited) |\n| `tenant key-generate [--name