CLI Reference
cenvero-str-ctl is the operator interface to a node. It talks to the running
agent over a local socket, so it only works on the node itself and needs
root for any command that changes state. The socket is always available — it is
the node's management lifeline and can never be disabled.
cenvero-str-ctl <group> <command> [args] [flags]
- Add
--format json(oryaml) to any command for machine-readable output (the default is a human table/JSON view). - Add
-hto any group or command for its full help, subcommands, and flags. - On a member of a cluster, add
--node <id or name>to run a command on another server of the cluster — see Running a command on another server. - The same managers are reachable over the node's REST API; this CLI is the local equivalent.
The command groups, by area:
| Area | Groups |
|---|---|
| Status & system | status version metrics hardware pull |
| System management | config service tls update license |
| Networking | network nic ipam dhcp dns vlan vxlan geneve vrf route |
| Security | firewall rules |
| Traffic shaping & visibility | bandwidth quota flow |
| Services & HA | lb l7lb bgp gateway nat64 ha bond cluster |
| Access control | user group role acl token realm apikeys |
| Tenants & billing | tenant billing |
| Operations | task backup alert heal container plugin node audit tag note |
Running a command on another server
sudo cenvero-str-ctl --node edge-3 firewall connlimit status
sudo cenvero-str-ctl --node edge-2 alert condition list
--node <id or name> runs the command on another server of the cluster. An id is
matched first, then a name, exactly (Edge-3 is not edge-3). If two servers
share the name, the command is refused and their ids are listed: name one by its
id. Naming the server you are on runs the command there by the same rules.
- The server you name decides what it runs: the commands the API also offers, except installing or changing plugins, the certificate commands that stay on the node (
tls csr,tls install, the resets), registering an image, adding a layer-7 frontend (it names certificate files on that server), restoring a backup, attaching a container, the serial console, the access-control commands (user,group,role,acl,token,realm), making or revoking an operator API key, andcluster forgetandcluster pin-members. Those answerthis command cannot be run on another server; run it there. - That server's licence and plan apply: if its licence is frozen it refuses changes, whatever the licence of the server you type on.
- That server's audit log records the command as
root (node <your server's id>), withvia_nodenaming the server it came through. The server you type on records it too, with the server asked astargetand the command run there. A command that only reads is recorded on neither. - A task the command begins there (an update, a rolling update, a machine or storage operation, making a backup) is owned by root of the server you typed on:
task showthere gives its owner as{"kind":"root","id":"root","via":"node <your server's name>"}. A rolling update started that way names your server on every member it updates. - A layer-7 pool that a frontend with that server's own certificate routes to cannot be changed with
--node(l7lb pool add,l7lb backend add,l7lb backend remove), as over the API: run the command on that server. - Commands that work on the machine you type on are refused with
--node:license,hardware,node info,config show,config dump,config set,config encode,api-token,tls show,tls pubkey,service onandoff,vm console,audit export,image register --path,iso register --path, and any command with--offline. Run them on that server. - Files you name (a machine's user data or SSH keys, notes, a certificate to install) are read on the machine you type on, and their contents are sent.
- Limits: a command may be at most 256 KB and its answer at most 8 MB; a larger answer is replaced by a message that the command ran. If the server does not answer within 5 minutes, or the connection drops, you are told the command may have run there: check before running it again.
--nodewith an empty value is refused, so an unset variable in a script never runs a command here. On a server that is in no cluster,--nodeanswers that there is no other server to run the command on, and a server not yet on this version answersupdate <name> to run commands on it from another server.
Status & system
status
cenvero-str-ctl status # health summary: version, license, data plane, bridges, cluster
version
cenvero-str-ctl version # agent version
metrics
cenvero-str-ctl metrics # current metrics snapshot
hardware
Print this machine's hardware ID — the value an activation or SSL request is bound to. Use it to verify a pending request in your account before approving it.
cenvero-str-ctl hardware
pull
Force an immediate pull of the node's CA-signed TLS certificate and a license re-sync (fetch a pending activation, auto-renew, re-evaluate) now, instead of waiting for the next background poll. Run it right after approving a node's SSL/license in your account.
sudo cenvero-str-ctl pull
System management
config
| Command | Purpose |
|---|---|
config set [<key> <value>] | Change a whitelisted operational setting (run with no args to list keys) |
config show | Print the decoded on-disk configuration (secrets redacted) |
config dump | Dump the on-disk configuration |
config encode | Write the node's signed configuration from flags (used by the installer) |
config export | Print the node's settings — firewall rules, the default action, networks and address pools — as one document, secrets left out |
config set writes to an operator local-overrides file that the agent layers
on top of its configuration at the next restart — and that a panel re-sync will
not clobber (local always wins). Use the positional config set <key> <value>
form, or the --api-bind / --api-rate-limit / --api-rate-burst shortcuts.
Apply with systemctl restart cenvero-stratum; verify with config show.
sudo cenvero-str-ctl config set api_rate_limit 2000
sudo cenvero-str-ctl config set --api-bind 10.0.0.5 --api-rate-limit 2000 --api-rate-burst 200
sudo cenvero-str-ctl config set # list every settable key
Settable keys: log_level, api_bind_address, api_rate_limit,
api_rate_burst, api_allowed_ips, api_allowed_origins,
api_read_timeout_secs, api_write_timeout_secs, api_idle_timeout_secs,
port_rest, port_grpc, port_websocket,
metrics_bind_addr, dns_listen_addr, dns_allowed_clients, dns_upstreams,
heal_interval_seconds, heal_disabled_checks, interface_reconcile_mode,
interface_hard_block, allow_untranslated_private_egress, and the six service switches (rest_disabled,
grpc_disabled, websocket_disabled, metrics_disabled, dns_disabled,
dhcp_disabled). Identity, the license server, the API token, the HA pair's
shared key and the TLS paths are refused — they are panel- or
identity-owned, not local operational settings. The cluster_* keys are
refused with what to run instead: a cluster is formed with cluster create
and joined with cluster join --code. The cluster and HA heartbeat ports
(port_cluster, port_ha_heartbeat) are refused too: the other nodes connect
to the fixed ports. See
Configuration for the full field reference.
config show / dump are read-only and decode the actual on-disk file (table,
--format json, or --format yaml); pass --include-secrets to reveal redacted
values, or --file <path> to inspect a specific file. config encode is what the
installer uses to write the node's configuration and prints the resulting
api_token.
service
See and toggle the agent's network services. service status shows each service's
ENABLED switch, its ADDRESS:PORT, and a live STATE. Toggle a service on
or off; the change applies on the next agent restart.
| Command | Purpose |
|---|---|
service status | Show each service (aliases: list, top, ls, ps) |
service <name> on | Enable a service (also service on <name>) |
service <name> off | Disable a service (also service off <name>) |
Toggleable services: rest, grpc, websocket, metrics, dns, dhcp.
Disabling rest warns first (it also serves the operator/billing API). The IPC control socket is not toggleable — it is how this CLI reaches the agent.
sudo cenvero-str-ctl service status
sudo cenvero-str-ctl service rest off
sudo cenvero-str-ctl service websocket on
sudo systemctl restart cenvero-stratum # apply
Enabling rest, grpc or websocket is only half of it — the management APIs
also require an API token before they will serve, so a service you switch on with
no token configured stays down. See api-token below.
api-token
Manage the bearer token the management APIs (REST, gRPC, WebSocket) require. With no token the agent refuses to open a management API at all rather than serve one without a credential, so this is what turns them on.
| Command | Purpose |
|---|---|
api-token generate | Mint a strong random token, store it, print it once |
api-token set | Store a token you supply, read from stdin |
api-token status | Report whether a token is set — never prints the value |
api-token clear | Remove it; the APIs stop serving at the next restart |
sudo cenvero-str-ctl api-token generate
sudo cenvero-str-ctl service on rest
sudo systemctl restart cenvero-stratum
generate shows the token once and it is not recoverable afterwards — copy it
then. To choose the value yourself, pipe it in so it never reaches your shell
history; there is deliberately no flag to pass it as an argument:
printf '%s' "$MY_TOKEN" | sudo cenvero-str-ctl api-token set
Tokens shorter than 16 characters are refused. The value is stored in your local
overrides, so a later configuration sync from the panel will not discard it. It is
not settable through config set, which rejects credential keys for the same
shell-history reason.
A management API binds only when all three hold: a token exists, the service is on, and the node has a TLS certificate — the agent never serves plaintext.
tls
Manage the management API's TLS certificate. After install the node serves a temporary self-signed certificate; in CA mode it obtains a CA-signed certificate once you approve the request in your account (Certificates). The private key never leaves the node.
| Command | Purpose |
|---|---|
tls info | Live certificate: mode (ca-signed/self-signed), expiry, SAN domains |
tls show | The certificate / key / public-key file locations |
tls pubkey | Print the public-key file location |
tls request | Request a CA-signed certificate from the panel now (online); a request waiting for your approval answers "status": "pending" and exits 0 |
tls pull | Pull this node's CA-signed certificate now (collect it once approved) |
tls regenerate | Generate a fresh certificate now (hot-reloaded, no restart) |
tls csr | Generate a key + CSR locally without contacting the panel (offline) |
tls install <cert> [chain] | Install a signed certificate obtained out-of-band |
tls pending-status | Report any pending certificate request (online or offline) |
tls reset-pending | Discard a pending offline CSR so you can start fresh |
tls reset | Clear the current certificate + pending request and re-obtain a fresh one |
tls domain list | List the hostnames the certificate is asked to cover |
tls domain add <domain> | Add a hostname and request a new certificate (waits for your approval in CA mode) |
tls domain remove <domain> | Remove a hostname and request a new certificate (waits for your approval in CA mode) |
sudo cenvero-str-ctl tls info
sudo cenvero-str-ctl tls pull # collect the CA-signed cert after approval
sudo cenvero-str-ctl tls domain add api.example.net
The certificate always covers the node's IP(s) plus loopback; a hostname you point
at the node's IP can be added with tls domain add. Names must be plain hostnames:
a wildcard, a space or anything else is refused. In CA mode the new certificate
waits for your approval: the command saves the name and reports "status": "pending" (exit code
0). Once approved the node installs it automatically, or collect it at once with
tls pull. Certificate changes work whatever the state of the licence, and one
runs at a time. See TLS & Licensing.
update
Pull-based agent updates from your licensed release channel.
| Command | Purpose |
|---|---|
update status | What runs, what is installed, staged and offered, and what can be rolled back to (contacts nothing) |
update check | Ask the update server what it offers (no download) |
update apply [--wait] | Install the version on offer and restart the agent into it (alias update now); --wait follows it through the restart |
update rollback [--wait] | Return to the version this server last ran, and restart into it |
update rollback --offline | The same with the agent stopped, for a version that does not start; refused while the agent runs |
cenvero-str-ctl update status
sudo cenvero-str-ctl update apply --wait
sudo cenvero-str-ctl update rollback --wait # back to the version that ran before
update apply verifies the download's checksum and signature, installs it in one
step and restarts the agent into it; a version already installed and waiting for
a restart is not downloaded again. If a new version fails to start twice in a row,
the previous one is restored automatically. update rollback returns to the
version the server last ran; with a version installed and not yet run, it only
removes that install. If there is nothing to roll back to it reports *"no previous
version to roll back to"*. An apply and a rollback run as tasks, one at a time.
None of these commands is stopped by a frozen licence. Re-applying a version at or
below the highest version this node has ever run is refused by downgrade
protection — to move forward again, install a newer release. On a member of a
cluster, update every server with cluster update. See Upgrades.
license
| Command | Purpose |
|---|---|
license activate <license-key> | Send this machine's activation request (confirm it in your account) |
license fetch <license-key> | Fetch the signed license once it has been confirmed |
license renew | Force a license renewal for this machine |
license refresh | Re-fetch the signed license for this machine |
license load <file> | Load a signed license file manually |
license status | Full installed-license picture: identity, validity/state, features, hardware binding |
The license key is positional, not a flag. Activation binds the license to this machine's hardware ID and waits for you to confirm the machine in your account; the agent then installs the signed license automatically.
Every command that installs a license (activate once confirmed, fetch, renew,
refresh, load) has the running agent load it at once. If the agent is not
running, the license is still saved, and the agent loads it when it starts.
sudo cenvero-str-ctl license activate CNVR-XXXX-XXXX-XXXX-XXXX
sudo cenvero-str-ctl license status
license status is read-only and works offline from on-disk state, so it still
answers when the agent is down or the node cannot reach the license server.
The same picture is available over the API as GET /api/v1/license, which reads
the running agent rather than the disk — useful for checking a fleet's expiry
dates without a shell on every box. See API Reference.
See Licensing for the warning → grace → freeze model.
Networking
network
A network is a managed private network: a CIDR pool whose usable host IPs are each materialized into an endpoint profile (a fixed IP paired with a generated MAC). You attach a workload by claiming a free endpoint — the endpoint is the workload's network identity.
| Command | Purpose |
|---|---|
network create | Create a network (--name --cidr [--gateway --vlan --tenant] [--host-gateway [--snat] [--dhcp]]) |
network host-gateway <id> [--snat] [--dhcp] or network host-gateway <id> --off | Set a network's host gateway; the flags given are the whole setting |
network list | List networks |
network show <id> | Network detail + its endpoints |
network endpoints <id> | List a network's endpoint profiles (IP ↔ MAC) |
network attach <id> [--ip] [--mac] | Claim an endpoint (optionally a specific IP and MAC) |
network set-mac <endpoint-id> <mac> | Change an endpoint's MAC, keeping its IP |
network detach <endpoint-id> | Free a bound endpoint |
network delete <id> | Delete a network |
sudo cenvero-str-ctl network create --name app-net --cidr 10.20.0.0/24 --gateway 10.20.0.1
sudo cenvero-str-ctl network attach <network-id> --ip 10.20.0.50
Each endpoint is an IP paired with a MAC address, and the MAC is assigned for you.
Pass --mac when the workload already has a fixed address of its own — a virtual
machine image, or an appliance whose license is tied to one — so the fabric
accepts the address it will actually send from:
sudo cenvero-str-ctl network attach <network-id> --ip 10.20.0.50 --mac 52:54:00:ab:01:02
# ...or change it afterwards, keeping the same IP
sudo cenvero-str-ctl network set-mac <endpoint-id> 52:54:00:ab:01:02
On a cluster, an endpoint attached before every member ran a version that supports this keeps a MAC you set on this server only, until you attach it again: see Endpoints.
A MAC must be unique across endpoints, and a multicast address is refused — one can never be a source address, so traffic from it would be dropped.
--host-gateway puts the network's gateway on the node so workloads can reach
it; --snat adds internet access through the node's public address (the node's
uplink must be configured) and --dhcp serves the network over DHCP. See
The host gateway.
sudo cenvero-str-ctl network create --name web --cidr 10.60.0.0/24 --gateway 10.60.0.1 --host-gateway --snat
sudo cenvero-str-ctl network host-gateway <network-id> --off
routed
Public addresses your provider routes to this server, handed to virtual machines
one at a time (vm create --public-ip auto|<address>). See
Public Addresses.
| Command | Purpose |
|---|---|
routed add <address or prefix> [--tenant T] [--description TEXT] | Add one address or a block (up to a /20); --tenant reserves it for one tenant |
routed list [--tenant T] | The blocks, what is free, and which virtual machine uses each address |
routed remove <id or prefix> | Remove a block no virtual machine uses |
sudo cenvero-str-ctl routed add 203.0.113.16/29 --description "provider subnet"
cenvero-str-ctl routed list
nic
| Command | Purpose |
|---|---|
nic list | List detected network interfaces |
nic detect | Re-scan and list interfaces |
nic accel | Show the acceleration mode (hardware vs software) per interface |
ipam
| Command | Purpose |
|---|---|
ipam pools | List IP pools |
ipam allocations | List every allocation (optional tenant id) |
ipam allocate | Allocate an IP address |
ipam release | Release an IP address |
dhcp
| Command | Purpose |
|---|---|
dhcp leases | List DHCP leases |
dhcp reservations | List static MAC→IP reservations |
dhcp reserve <mac> <ip> [--hostname] | Pin a static MAC→IP reservation |
dhcp release <mac> | Remove a static reservation, returning the address to the pool |
sudo cenvero-str-ctl dhcp reserve 52:54:00:ab:01:02 10.0.0.50 --hostname db01
A reserved address is handed out on the client's next request, survives an agent
restart, and appears immediately in dhcp leases.
dns
Manage authoritative zones, records, recursive forwarders, and DNSSEC.
| Command | Purpose |
|---|---|
dns zones | List zones |
dns records [zone_id] / dns list [zone_id] | List records (optionally for one zone) |
dns add <zone_id> <name> <type> <value> [ttl] [source_subnet] | Add a record (A, AAAA, CNAME, TXT, NS or PTR) |
dns delete <record_id> | Delete a record |
dns dnssec <zone> | Show a zone's DNSSEC keys + the DS record to lodge with the parent; never makes keys |
dns zone list/add <name>/delete <zone_id> | Zone CRUD |
dns record list [zone_id]/add .../delete <record_id> | Record CRUD |
dns record update <record_id> <name> <type> <value> [ttl] [source_subnet] | Change a record in place; a TTL or source subnet left out is kept |
dns forwarder list/set <ip…>/add <ip…>/remove <ip…> | Manage recursive forwarders |
Each forwarder is an IP or IP:port (bare IPs default to :53). A dns forwarder
change applies at once and is kept across restarts; the last forwarder cannot be
removed. A forwarder named twice is kept once, and the limit of 8 counts the
forwarders after the repeats are dropped. See
DHCP & DNS.
sudo cenvero-str-ctl dns zone add app-net.internal
sudo cenvero-str-ctl dns add 1 api A 10.20.0.55 300
vlan
A per-VLAN allow/deny table. An empty table means every VLAN is allowed (default).
| Command | Purpose |
|---|---|
vlan list | List the allow/deny policy |
vlan deny <id> | Lock down a VLAN (an id from 1 to 4094) |
vlan allow <id> | Record an explicit allow |
vlan clear <id> | Clear a VLAN's policy (back to default-open) |
macbind
The MAC addresses the workload bridge lets through. A virtual machine or a managed
endpoint is let through while it is attached, and a routed public address for its
machine; those bindings are released with the workload. A binding you add here is
an operator's binding, and it stays until you remove it. A binding takes only the
MAC address: the bridge lets that address through on every port and VLAN, so a
port, a VLAN or a mode is refused. A listing names the kind of owner of each
binding (operator, endpoint or routed).
| Command | Purpose |
|---|---|
macbind list | List the bindings, what each one lets through, and the kind of owner of each |
macbind add <mac> | Let a MAC address through the workload bridge (an operator's binding) |
macbind remove <mac> | Remove an operator's binding, which frees the MAC. A binding a workload or a routed address holds is not removed here: detach the workload or release the address instead |
sudo cenvero-str-ctl macbind add 52:54:00:ab:01:02
cenvero-str-ctl macbind list
sudo cenvero-str-ctl macbind remove 52:54:00:ab:01:02
If a MAC address is already held by a binding, an attach that needs it is refused, and the refusal says what holds it and how to free it.
vxlan
| Command | Purpose |
|---|---|
vxlan list | List overlay networks |
vxlan create <vni> <subnet> | Create an overlay network; the answer says whether its device is up, and why when it is not built. The subnet is kept across restarts |
vxlan delete <vni> | Delete an overlay network. The one a cluster network uses on this server is refused: it is removed when the server leaves that cluster network |
vxlan peers <vni> | List a VNI's remote peers |
vxlan peer-add <vni> <host> <mac> <vtep_ip> | Add a remote peer — vtep_ip must be an IP address; pass "" as <mac> when you do not know it (broadcast and unknown traffic is then sent to the peer, and its addresses are learned) |
vxlan peer-remove <vni> <host> | Remove a remote peer |
vxlan fdb | Dump the overlay forwarding database |
route
Static routes (optionally in a non-main table) and the policy rules that steer traffic into those tables.
| Command | Purpose |
|---|---|
route list [table] | List routes (optional table id) |
route add <json> | Add a route — JSON {destination,gateway,interface,metric,table}; the route reaches the server with its metric. A default route in the main table, any route in the local table, a route the server already has, and one that would carry or contain the server's own network, gateway or addresses another way are refused (why) |
route delete <id> | Delete a route by id |
route rule list | List policy-routing rules |
route rule add <json> | Add a rule — JSON {priority,from,to,fwmark,iif,oif,table}; priority and table from 1 to 2147483647. A rule that would send the server's own traffic to a table that cannot carry it is refused |
route rule delete <id> | Delete a policy-routing rule by id |
Security
firewall
| Command | Purpose |
|---|---|
firewall allow <json> | Add an allow rule — JSON rule object, e.g. '{"source_ip":"10.20.0.0/24","protocol":"tcp","dest_port":443}' |
firewall deny <json> | Add a deny rule (same JSON rule object) |
firewall list | List firewall rules; a rule saved with a setting that is not enforced carries not_enforced entries |
firewall delete <id> | Delete a rule |
firewall default | Show the default action for traffic no rule matches (allow or deny) |
firewall default set <action> | Set the default action, allow or deny (kept across restarts) |
firewall conntrack | Show the established IPv4 and IPv6 connections the node is tracking |
firewall conntrack-flush [address] | Forget the tracked connections, IPv4 and IPv6, so rule changes apply to ones that are already open (optionally just those to or from one IPv4 or IPv6 address) |
firewall schedule set/clear/list | Attach a time-of-day/day-of-week activation window (UTC) to a rule; it applies to new connections only |
firewall connlimit set/clear/status | Per-address connection limits (IPv4; counts the connections an address opened that carried traffic in the last minute) |
firewall blocklist | Show the addresses the node blocks on its own and when each block ends |
firewall unblock <address> | Lift an automatic block now, whatever the state of the licence |
A rule may match protocol (tcp, udp, icmp), source_ip, dest_ip,
source_port, dest_port (with dest_port_max for a range), interface,
mac, level and priority. Rules apply to traffic as it arrives on the
workload bridge and on the forwarding interfaces (gateway_wan_interface,
gateway_lan_interface), and the replies to a TCP or UDP connection a rule
admits are admitted too, so chain and stateful can be left out; any other
value for them, an unrecognised key, or an address, MAC or protocol that cannot
be read is refused with an error. See Firewall.
On a member of a cluster, firewall deny refuses a rule whose source is a
member's address when it could drop the cluster's own traffic. See
Members' addresses are never blocked.
rules
Address blocks: drop every packet that arrives from one IPv4 address, or from
the IPv4 addresses a name resolves to. A block is checked on the uplink, the
workload bridge and the forwarding interfaces, before the firewall's rules, so a
firewall allow rule does not lift it, and it also stops connections that are
already open. Rules apply to the node they are added on. For ports, protocols,
address ranges, IPv6, allow rules or dropping everything no rule allows, use
firewall.
| Command | Purpose |
|---|---|
rules list | List all rules; a rule not enforced as written carries not_enforced entries, as does a disabled rule, and a rule with an expiry shows expires_at |
rules add <json-rule> | Block one IPv4 address or name |
rules remove <id> | Remove a rule by id |
rules batch <json-rule-array> | Add several blocks at once; if one is refused, none is added |
rules preset <name> | Not available: the answer gives the firewall commands that do what the preset described |
A rule — the argument of rules add, or one element of the rules batch array —
has an id you choose, an action of DROP, and exactly one condition:
{"type":"IP","operator":"eq","value":"203.0.113.7"} or
{"type":"FQDN","operator":"eq","value":"blocked.example.com"}. A rule is
enabled unless it says "enabled": false; a disabled rule is kept, blocks
nothing and is flagged by rules list. No command switches a stored rule on: to
make one block, remove it with rules remove <id> and add it again without
"enabled": false. A name is looked up when the rule is added and again every
five minutes. An address the name resolves to is not blocked when it is no host's
(0.0.0.0/8, loopback, link-local, multicast or broadcast), one of the node's own
addresses, or its default gateway; rules list shows each one under the rule's
not_enforced, and the name's other addresses are blocked. A rule may carry
a schedule (a UTC window: start and end as HH:MM, days_of_week 0–6
with 0 = Sunday) and ttl_seconds, counted from when the rule is added; an
expired rule stays in rules list, marked expired, until you remove it. Any
other action or condition, a level other than global, or a tenant_id is
refused with an error that says what to do instead.
sudo cenvero-str-ctl rules add '{"id":"block-1","action":"DROP","enabled":true,"conditions":[{"type":"IP","operator":"eq","value":"203.0.113.7"}]}'
Rules added before these checks may hold settings that were never enforced,
such as the rules of a preset, which were stored but never applied.
rules list flags each with not_enforced, and the node logs one warning per
rule when it starts; remove them with rules remove <id>. An enabled stored
rule that drops or rejects an address keeps blocking every packet from it, even
where its other conditions were meant to narrow it.
On a member of a cluster, a rule that drops or rejects a member's address is
refused, and the answer says to take that member out with
cluster remove <node-id> first: a block of it would cut this node off from
it. See
Members' addresses are never blocked.
Traffic shaping & visibility
bandwidth
| Command | Purpose |
|---|---|
bandwidth list | List per-MAC rate limits and shared pools |
bandwidth set <json-limit> | Create/update a per-MAC rate limit |
bandwidth delete <id> | Remove a per-MAC rate limit; the MAC's other limits still hold |
bandwidth pool | Show limits and pools (the same view as list) |
Shared pools are created and filled over the API (/api/v1/bandwidth/pools) — see
API Reference.
quota
Monthly per-MAC usage caps that reset at the start of each UTC month.
| Command | Purpose |
|---|---|
quota list | List quotas with their status |
quota set <json> | Create/update a quota; an enforced quota's action must be throttle |
quota get <mac> | Show one MAC's quota + status |
flow
| Command | Purpose |
|---|---|
flow list | List active flows (optional state filter) |
flow stats | Aggregate flow statistics |
Services & HA
lb
L4 virtual IPs (VIPs) with a backend pool.
| Command | Purpose |
|---|---|
lb list | List VIPs |
lb create | Create a VIP; add its backends with lb add-backend |
lb show | Show a VIP's detail |
lb backends <id> | List a VIP's backends |
lb add-backend / lb remove-backend | Adjust backends live |
lb drain <vip_id> <backend_id> | Not available yet: refuses and changes nothing (see Load Balancer) |
lb set-health <vip_id> <backend_id> <up/down> | Force one backend up or down by hand — a manual override, not the health-check setup. Kept when the node restarts; a configured check can change it back |
lb out-of-rotation <vip_id> <backend_id> | Take a backend out of rotation until you put it back: its connections, existing ones too, move to the other backends at once. A health check never puts it back, and it stays out when the node restarts |
lb back-in-rotation <vip_id> <backend_id> | Put a backend back in rotation: it takes new connections again once it is healthy |
lb delete | Delete a VIP |
l7lb
The HTTP (layer-7) load balancer: pools of backends, and frontends that route to them. See Load Balancer.
| Command | Purpose |
|---|---|
l7lb status | Frontends (listening, or why not), pools (loaded, or why not), and each backend's health and requests in progress |
l7lb pool list | List pools |
l7lb pool add <json> | Create a pool, or change an existing one's algorithm and health check. An existing pool keeps its backends: naming different ones is refused |
l7lb pool remove <name> | Remove a pool that no frontend routes to |
l7lb backend list <pool> | A pool's backends, with their ids, health and requests in progress |
l7lb backend add <pool> <host:port> | Add a backend to a pool |
l7lb backend remove <pool> <host:port/id> | Remove a backend from a pool, by its address (host:port) or its id |
l7lb frontend list | List frontends |
l7lb frontend add <json> | Create a frontend; listening port 0 is refused |
l7lb frontend remove <name> | Remove a frontend |
bgp
| Command | Purpose |
|---|---|
bgp status | Engine status |
bgp neighbors | List peers |
bgp routes / bgp rib | Route table / RIB |
bgp fib | The routes the node has installed in its routing table, and under not_installed the ones it could not install, with the reason |
bgp peer | Manage peers (add/list/remove); removing a peer removes its import and export policies |
bgp announce <prefix> [next-hop] / bgp withdraw <prefix> | Advertise / withdraw an IPv4 prefix; without a next hop, each peer is sent this node's address on the session |
bgp announcements | List active announcements |
bgp prefix-list | Manage prefix-lists (add <json> / list) |
bgp route-map | Manage route-maps (add <json> / list) |
bgp policy | Bind import/export route-maps (import/export <neighbor> <route-map> / list) |
bgp import-policy | Manage import policy |
bgp rpki configure <rtr-addr> [--reject-invalid] / enable / disable | Route-origin validation against an RTR cache (BGP) |
bgp rpki status / bgp rpki validate <cidr> <origin-as> | The cache's state and the held routes counted by validation state; how one prefix and origin would validate |
bgp evpn enable [--vtep IP --rd RD] / disable / status / show / local-mac <add/remove> <vni> <mac> [ip] | The EVPN address family: routes are exchanged, not used for forwarding |
gateway
| Command | Purpose |
|---|---|
gateway status | HA status of this node and its peer |
gateway failover | Take the VIP onto this node; refused while the pair's heartbeat runs |
gateway failback | Release the VIP from this node; refused while the pair's heartbeat runs, and on a node without a partner |
ha
Gateway high-availability: two paired nodes run active/standby and the active node
owns a virtual IP (VIP), taking it over on failover. A node with no peer is
active and holds its VIP itself.
| Command | Purpose |
|---|---|
ha status | Show HA status (active/standby/solo, VIP, peer) |
ha set-peer | Refused: the pair's settings cannot be set on the node |
ha configure | Refused: the pair's settings cannot be set on the node |
A pair's settings (peer address, priority, VIP, and a shared secret) reach a
node only in its delivered configuration, read at agent boot; setting up a pair
yourself comes in a later release (see
Gateway High Availability). Use
ha status (or gateway status) for live status and gateway failover /
gateway failback for manual moves; the same are on the REST API.
bond
Combine physical NICs into a bond for redundancy or throughput. A bond is created
with a device name you choose (use the cnv- prefix, max 15 chars) in one of two
modes: active-backup (one member carries traffic, another takes over on failure)
or 802.3ad (LACP aggregation, needs a matching switch port-channel).
| Command | Purpose |
|---|---|
bond list | List bonds |
bond show <id> | Show a bond (mode, MTU, active member, members, and members not put back at a restart under held, including those waiting for the server's default route at boot) |
bond create --name <dev> --mode active-backup/802.3ad [--mtu N] | Create a bond; it keeps its MTU (68 to 9216, 1500 by default) and is rebuilt when the agent restarts |
bond add-member <id> --iface <nic> | Enslave a NIC; not one that carries the way the node is reached, has addresses of its own, or is already in a bridge or bond |
bond remove-member <id> --iface <nic> | Release a NIC; from a bond the node is reached through, only one with no link |
bond set-mtu <id> --mtu N | Set the MTU across the bond + members; refused on a bond the node is reached through |
bond delete <id> | Delete a bond (releases its members first); refused for a bond the node is reached through |
sudo cenvero-str-ctl bond create --name cnv-bond0 --mode active-backup
sudo cenvero-str-ctl bond add-member <bond-id> --iface cnv-nic-1
sudo cenvero-str-ctl bond set-mtu <bond-id> --mtu 9000
create prints the bond's logical id (e.g. bond-1a2b…); use that id — not the
device name — with the other subcommands. Members are referenced by interface name.
cluster
Form a cluster, join one, and manage its members (agent 1.0.0-rc.81 or later on
every member; see Clustering Overview). Every one
runs from any member: a change that only the cluster's leader can make is passed
to it. Most need clustering in the node's licence. Five work whatever the
licence says, without clustering in it and while it is frozen: status,
join-code list, join-code revoke, remove and leave. forget always
works, as root on the node itself.
| Command | Purpose |
|---|---|
cluster status | This node's role (leader, follower, candidate; disabled on a node that is not in a cluster, not running when it could not start — the agent log says why), the leader, the cluster's id and name, how many members vote, and every member: its id, name, address, role, whether it votes, whether it is online and when it was last seen. On a member that is not taking part in its cluster, error says why (see Clustering Overview). Works without clustering in the licence |
cluster create --name <name> --bind <ip> [--wait] | Form a cluster with this node as its first member. --bind is this node's own address for the others (port 7073) |
cluster join-code create [--expires 15m] | Make a join code: shown once, works once, expires after --expires (60s to 24h; 15 minutes by default) |
cluster join-code list | The join codes, with their state (active, used, revoked, expired), who made them and which node used them — never the codes. Works without clustering in the licence |
cluster join-code revoke <id> | Withdraw a code that has not been used. Works without clustering in the licence and while it is frozen |
cluster join --code <code> --bind <ip> [--adopt-cluster-tenants] [--discard-local-identity] [--wait] | Join this node to a cluster. --code - reads the code from standard input. --adopt-cluster-tenants lets the cluster's tenant records win over this node's where they conflict. An account of this node with the same id as one of the cluster's, but different, stops the join and is listed; --discard-local-identity gives this node's own accounts up and keeps only the cluster's |
cluster join --code <code> --preview | Show what the join would meet — the cluster, its member count, the tenants shared and merged, any conflicts, and (as options_given_up) this node's own settings the cluster's would replace: its brand, tags' colours or notification settings — and change nothing. It also lists, as floating_given_up, the floating addresses this node holds that the cluster holds for another member; the join gives each one up. It takes --adopt-cluster-tenants and --discard-local-identity as the join does |
cluster update [--version V] [--plan] [--wait] | Update every server of the cluster to the version they are offered, one at a time, stopping at the first that does not come back healthy; --plan shows what it would do and changes nothing (see Upgrades) |
cluster remove <node-id> | Take a member out of the cluster; the others refuse it at once. Works without clustering in the licence and while it is frozen |
cluster leave | Take this node out of its cluster; it becomes standalone and keeps its own objects. On a member that is not the leader it answers once the leader has taken it out; if the leader's answer is lost, it is refused and says what to run (see Remove a node, or leave). Works without clustering in the licence and while it is frozen |
cluster rekey [<node-id>] [--wait] | Give a member (this node when none is named) a new identity |
cluster ca rotate [--wait] | Replace the cluster's certificate authority; the members keep their identities and move to the new one |
cluster placement [--vcpus N] [--memory-mib N] [--disk-gib N] [--image ID] [--network NET]… [--tenant T] [--group G] [--routed R] [--cpu-model M] | Every member's answer for a machine of this size: whether it can take it, its rank, and each member's reasons. Creates nothing (Placing machines) |
cluster image list / cluster image show <id> | The cluster image library: each image, its members' copies and the machines that use it (The cluster image library) |
cluster image add --name N --url U --sha256 S or --catalogue E | Bring an image into the library on the member --node names (this node when none is named), checked against its SHA-256 |
cluster image replicate <id> | Copy an image to the member --node names |
cluster image evict <id> <node> | Remove a member's copy of an image. Run it on the member it names: --node names that member too |
cluster image delete <id> | Remove an image from the library. Its copies stay on the members that hold them, as ordinary images |
image publish <id> | Publish this node's image to the library, with the same id |
cluster network list / cluster network show <id> | The cluster networks, with their members, host gateway, machines, state and whether they are released for machines (Cluster networks) |
cluster network create --name N --cidr C --gateway G --tenant T [--mtu N] [--host-gateway] [--dhcp] | Create a cluster network. --dhcp needs --host-gateway, and --dhcp=false with --host-gateway is refused |
cluster network host-gateway <id> --member M / cluster network host-gateway <id> --clear | Set, or clear, the member that runs a network's host gateway |
cluster network delete <id> | Delete a cluster network that no machine is attached to |
cluster usage <tenant> | A tenant's machines and volumes across the cluster, and each member's share |
cluster forget --yes | Make this node standalone without the others' agreement — for a node removed while it was down, or whose identity expired. Root, on the node itself; changes nothing on the others |
The commands that start work — create, join --code, rekey, ca rotate —
answer with a task at once; --wait follows it until it
ends.
# On the first node
sudo cenvero-str-ctl cluster create --name prod --bind 10.0.0.5 --wait
# On any member: a code for the next node
sudo cenvero-str-ctl cluster join-code create --expires 30m
# On the new node: paste the code and press Enter (it is read from standard input)
sudo cenvero-str-ctl cluster join --code - --bind 10.0.0.6 --wait
sudo cenvero-str-ctl cluster status
The cluster commands manage the whole cluster from any member; the other
command groups work on the node they run on, or, with --node, on another member
(see Running a command on another server).
Another member's machines, networks and other objects are also managed from the
web console or the
API.
Two commands are only for a cluster set up by hand with an earlier version,
before join codes existed: cluster join <node-id> <address>, run on its
leader, adds a member (a cluster formed with join codes refuses it: add nodes
with a join code), and cluster pin-members, run on its leader, records the
identity of every member so they can use the features above. cluster profile
still exists but is refused: every node runs the same services.
Access control
Accounts, groups, roles, permissions, API tokens and sign-in methods (see
Accounts and Access Control). Run as root on the node,
these commands act as an Administrator and never ask for a password to be
confirmed. Every one answers with the API's own sentences; add --json to
print the API's answer. Passwords and client secrets are read from a prompt or
standard input, never from the command line. The user, group, role, acl,
token and realm commands are never held back by the licence. In a
cluster they change the whole cluster, from any
member.
Quote a token id in the shell ('alice@local!ci'): an unquoted ! can be taken
as a history expansion.
user
| Command | Purpose |
|---|---|
user add <name>@<realm> [--display-name N] [--email E] [--role R [--path P]] [--require-tfa] [--expires DATE] [--password-stdin] | Create an account; --role gives it a role at once, on --path (/ when none is given); --password-stdin reads its first password |
user list | Every account, with whether it has a second factor and its last sign-in on this node |
user show <id> | One account |
user set <id> [--enabled=false] [--expires DATE or never] [--display-name N] [--email E] [--require-tfa=true or false] | Disable or enable it, set or lift its expiry, change its name or email, require a second factor |
user passwd <id> --password-stdin | Set a Stratum account's password: asked twice at a prompt, or the first line of standard input |
user delete <id> | Delete an account, with its tokens, second factor and permissions |
user tfa show <id> | Whether it must use a second factor, what it has set up, how many recovery codes are left |
user tfa reset <id> | Remove its authenticator and recovery codes; it sets them up again at its next sign-in |
# The first administrator (it sets up an authenticator app at its first sign-in)
sudo cenvero-str-ctl user add alice@local --role Administrator --password-stdin
# A support account for one tenant, with a password from a script
printf '%s\n' "$PASSWORD" | sudo cenvero-str-ctl user add bob@local --display-name Bob --role Support --path /tenants/t-acme --password-stdin
DATE is a day (2027-01-01, midnight UTC) or a time
(2027-01-01T00:00:00Z).
group
| Command | Purpose |
|---|---|
group add <id> [--comment C] | Create a group |
group list / group show <id> | Groups and their members |
group member add <group> <user> | Add an account to a group |
group member remove <group> <user> | Take an account out of a group |
group delete <id> | Delete a group and its permissions (its members keep their accounts) |
role
| Command | Purpose |
|---|---|
role list / role show <id> | Roles and their privileges (role show Administrator lists every privilege) |
role add <id> --privileges A,B [--require-tfa] | Create a custom role; its name starts with a capital letter |
role set <id> [--privileges A,B] [--require-tfa=true or false] | Change a custom role (--privileges replaces the whole list) |
role delete <id> | Delete a custom role and every permission that gives it |
The built-in roles — Administrator, Operator, Auditor, VMAdmin, VMUser, NetworkAdmin, StorageAdmin, TenantManager, Billing, Support and NoAccess — cannot be changed.
acl
| Command | Purpose |
|---|---|
acl list [--path P] [--user U or --group G or --token T] | Permissions, filtered |
acl add --path P (--user U or --group G or --token T) --role R [--no-propagate] | Give a role on a path; --no-propagate keeps it to the path itself |
acl remove <entry-id> | Remove a permission (its id is in acl list) |
sudo cenvero-str-ctl acl add --path /tenants/t-acme --group acme-support --role Support
sudo cenvero-str-ctl acl add --path /vms/vm-1a2b3c4d --user bob@local --role NoAccess --no-propagate
token
| Command | Purpose |
|---|---|
token add <user> <name> [--comment C] [--expires DATE] [--no-privsep] | Make an API token; its secret is printed once. Without --no-privsep it holds only the permissions you give the token itself |
token list [<user>] | An account's tokens, or every token, the operator API keys included |
token revoke <token-id> | Revoke a token for good; it stops working at once |
sudo cenvero-str-ctl token add alice@local ci --comment "deploy pipeline" --expires 2027-01-01
sudo cenvero-str-ctl acl add --path /vms --token 'alice@local!ci' --role VMUser
sudo cenvero-str-ctl token revoke 'alice@local!ci'
realm
Sign-in methods: the built-in local, and identity providers (OpenID Connect).
| Command | Purpose |
|---|---|
realm list / realm show <id> | Sign-in methods and their settings (a client secret is never shown) |
realm add-oidc <id> --issuer URL --client-id ID --redirect-uri URL [--client-secret-stdin] [flags] | Add an identity provider; repeat --redirect-uri for each node |
realm set <id> [flags] | Change one: the same flags, plus --enabled=false and --default; the client secret stays unless a new one is given |
realm test <id> | Check the provider's settings and signing keys, changing nothing |
realm delete <id> | Delete a sign-in method that holds no accounts |
The settings add-oidc and set take: --display-name, --comment,
--issuer, --client-id, --client-secret-stdin, --redirect-uri,
--username-claim (preferred_username, email or sub), --groups-claim,
--group-map provider-group=group (repeatable), --scopes, --algorithms,
--no-autocreate and --trust-provider-mfa.
printf '%s\n' "$CLIENT_SECRET" | sudo cenvero-str-ctl realm add-oidc corp --display-name "Corporate sign-in" \
--issuer https://id.example.net/realms/corp --client-id stratum --client-secret-stdin \
--redirect-uri https://node1.example.net:7070/console/auth/oidc/callback \
--groups-claim groups --group-map stratum-ops=ops
sudo cenvero-str-ctl realm test corp
apikeys
Operator API keys. Each one is an API token of the built-in account
apikeys@local, holding Administrator on / unless you narrow it, and these
commands keep working as they always have.
| Command | Purpose |
|---|---|
apikeys mint <label> | Mint a new key (secret shown once) |
apikeys list | List keys (no secrets) |
apikeys revoke <id> | Revoke a key by id |
token list shows the same keys as apikeys@local!<id>, and acl add --token
narrows one. For a new script, an API token of an account made for it is usually
the better choice.
Tenants & billing
tenant
Tenants are your downstream customers on this node, each with a resource quota and optional scoped API keys.
| Command | Purpose |
|---|---|
tenant list | List tenants |
tenant create --name <name> | Create a tenant |
tenant delete <id> | Delete a tenant — also removes its scoped API keys, quota, private networks, and IPAM pools/allocations |
tenant quota <id> | Show a tenant's quota on this node: its bandwidth cap, its machine and address caps with their counts, and any rule limit still stored (listed under not_enforced) |
tenant quota-set <id> --max-bandwidth-bps N | Set a tenant's bandwidth cap (0 = unlimited). Only what you pass changes; nothing to change, a negative value, or an unknown tenant is refused |
tenant quota-set <id> --max-vms N | Cap the tenant's virtual machines: on this node, or across the cluster once every member runs a version that supports it (0 = unlimited; Compute, early access). Lowering it never touches existing machines |
tenant quota-set <id> --max-ips N | Cap the addresses the tenant holds on this node (0 = unlimited). A new address past the cap is refused; lowering it never releases one |
tenant quota-set <id> --max-rules N | Refused unless N is 0: nothing enforces a rule limit, because a tenant owns no firewall rules |
tenant key-generate <id> [--name <label>] [--ttl 720h] | Mint a scoped API key for a tenant |
tenant key-list <id> | List a tenant's scoped API keys |
tenant key-revoke <key-id> | Revoke a scoped API key |
A scoped key authenticates as the tenant but is confined to that tenant's resources: it can read its tenant, quota and billing state, manage its own tenant's keys, and see and run its own machines (start, stop, restart, consoles, password resets) — the web console's customer portal — but creating or deleting machines, networks or volumes and changing the tenant, its quota or its billing state (suspend, resume, limit) stay with the operator. The secret is shown only once, at mint time. In a cluster where every member runs this release, a tenant's keys work on every member (see Tenants & Bandwidth).
billing
Drive one of your customers' (a tenant's) account state — the same actions your billing system calls over REST.
| Command | Purpose |
|---|---|
billing suspend <tenant-id> | Suspend a tenant |
billing resume <tenant-id> | Resume a tenant |
billing limit <tenant-id> --rate-mbps N | Apply an aggregate rate cap (Mbps; 0 = unlimited) |
billing unlimit <tenant-id> | Remove a tenant's rate limit |
billing status <tenant-id> | Show a tenant's billing state |
See Billing Integration.
Operations
task
Every operation on a virtual machine, an image or a volume is recorded as a
task: who started it, what it acts on, how far it got, a log, and how it ended.
The commands that start one print its id in their answer ("task").
| Command | Purpose |
|---|---|
task list [--state S] [--type T] [--object ID] [--owner ID] [--tenant T] [--since WHEN] [--limit N] | Tasks, newest first. --state takes a comma-separated list (queued, running, succeeded, failed, cancelled, interrupted); --type a type (vm.start) or a prefix ending in a dot (backup.); --object a machine, image, volume, snapshot or backup id; --owner a key id, or root for this command line; --since a time (2026-09-29T12:00:00Z) or a duration back from now (24h) |
task show <id> | One task: state, progress, who started it, when |
task log <id> [--start N] [--follow] | Its log as text; --follow keeps printing until the task ends. --format json prints the page as it comes from the agent |
task cancel <id> | Stop an image download or import, a backup or a restore, a node's update until it is installed, or the cluster's rolling update before its next server; anything else finishes or rolls back on its own |
cenvero-str-ctl task list --state running
cenvero-str-ctl task log tsk-3f2a0c1e9b7d-0mumq7fmz-a05dee --follow
A task that was running when the agent stopped reads interrupted until the
agent, once running again, finishes or undoes the operation; the task then ends
with that outcome, and its log says so. Tasks are kept for 30 days (at most
20,000). The same tasks are served at /api/v1/tasks (see
API Reference).
backup
| Command | Purpose |
|---|---|
backup create [config/full] | Create a backup (default config); it answers the backup by its id and its file's name, as the API does |
backup restore <id/file> | Unpack a full backup, named by its id or its file's name, into the node's restore/ area; to complete the rollback, stop the agent, put the unpacked snapshot in place, and start it again. A config backup is an export for your records and is refused |
backup list | List backups, each by its file's name (never where it is on the server), as the API lists them |
backup schedule add <expression> [config/full] [retention] | Add a schedule (e.g. daily@03:00 full 7) |
backup schedule remove <id> | Remove a schedule |
alert
| Command | Purpose |
|---|---|
alert status | Alerting status (counts + action-dispatch success/failure) |
alert list [firing/acknowledged/resolved] | List alerts, newest first, optionally in one state |
alert history | Every alert kept (resolved alerts are kept for 30 days, at most 10,000 alerts) |
alert ack <alert_id> | Acknowledge a firing alert, recorded as the user running the command (it stays open until its condition clears) |
alert resolve <alert_id> | Resolve a firing or acknowledged alert by hand; if its condition still holds it fires again after its cooldown |
alert condition list | List threshold conditions |
alert condition add <json> | Add a condition, e.g. '{"metric_type":"pps","operator":"gt","threshold":1000,"duration_secs":60}'; prints it with its new id. A key that is not a condition field is refused |
alert condition remove <id> | Remove a condition (its open alerts resolve) |
alert action list | List configured actions across all conditions (never shows a webhook's secret) |
alert action add <condition_id> <websocket/log/webhook/email> [config] | Attach an action; for webhook, config is a public http(s) URL and the output shows the signing secret once; for email, up to 10 addresses separated by commas (a mail server must be set in the notification settings) |
How conditions fire and resolve, and how to verify a webhook's signature, is in Monitoring.
heal
| Command | Purpose |
|---|---|
heal status | Latest health-check results |
heal check | Force an immediate health-check run |
container
Attach a container's network namespace to a managed network using the same plumbing a VM endpoint uses (a managed IP + MAC, a veth pair into the network's bridge).
| Command | Purpose |
|---|---|
container list | List attached containers |
container show <id> | Show an attachment by its logical id |
container attach --runtime <lxc/docker/podman> --network <id> --netns-pid <pid> [--ip <ip>] [--firewall] | Attach a container netns |
container detach <id> | Detach (tears down the veth, frees the endpoint) |
sudo cenvero-str-ctl container attach --runtime docker --network net-1 --netns-pid 12345
--netns-pid is the PID of any process inside the container (e.g. its init).
attach prints a logical container id; use that id with show / detach.
When the network belongs to a tenant, the container's port on the bridge is
separated from every other tenant's workloads before the container's interface
comes up (see Tenants & Bandwidth). If that separation cannot
be applied on this node, attach fails with an error instead of attaching the
container without it.
tag and note
Tags and notes on an object — a machine, network, volume, image, tenant or this node — as the web console shows them.
| Command | Purpose |
|---|---|
tag <vm/network/volume/image/tenant/node> <id> | Show the object's tags and notes |
tag <kind> <id> <tag>… / tag <kind> <id> --clear | Set its tags, replacing the ones it has, or remove them all |
note <kind> <id> --file F / --stdin | Set its notes from a file or standard input; an empty one clears them |
A tag starts with a lower-case letter or digit and holds at most 32 lower-case
letters, digits, ., _ or -; an object has at most 16. Notes are plain text
of at most 8 KiB. Tags organise objects: they never grant or take away access. A
tenant's tags and notes are never shown to the tenant. If someone changed the
object's tags or notes since they were read, the change is refused; read them
again and reapply.
plugin
| Command | Purpose |
|---|---|
plugin install <target> | Install a plugin — a bare <name> from the official store, <username>/<name> from a trusted external store, or a local package path |
plugin list | List installed plugins |
plugin show | Show plugin detail |
plugin remove | Remove a plugin |
plugin verify <name> | Re-check an installed plugin: its files are the ones that were signed, and its certificate is genuine, covers this node and is not revoked. Exits non-zero if it does not pass |
plugin verify <path> | Run every install check on a package file without installing it. Exits non-zero if it would be refused |
plugin enable / plugin disable | Enable / disable a plugin (enable re-verifies it first) |
plugin store add <signed-store-file> | Trust an external plugin store (verified offline) |
plugin store list | List trusted plugin stores |
plugin store remove <username> | Remove a trusted external store |
The official Cenvero store is always present (its plugins install as a bare
<name>). An added external store's plugins install as <username>/<name>. See
Plugins.
node
| Command | Purpose |
|---|---|
node info | Node information: hardware id, agent version |
node maintenance show | This member's maintenance: whether it is on, since when, and the last evacuation run this member started. Add --node for another member (Maintenance and evacuation) |
node maintenance on | Put this member into maintenance: nothing is placed on it and nothing moves onto it, and its machines keep running. --evacuate also moves its machines off, as a task that reports each move, and --mode takes auto (the default) or offline; live is not available yet (Maintenance and evacuation) |
node maintenance off | End this member's maintenance. An evacuation does not end it, and ending it stops the member's evacuation before its next move |
node evacuation-plan | Where each machine of this member would move, or why it stays. Changes nothing (Maintenance and evacuation) |
audit
The node's audit log: every change made on the node, by whom, from where, on what, and how it ended. See Monitoring for what is recorded.
| Command | Purpose |
|---|---|
audit list [filters] [--limit N] [--before N] [--order asc] | Records, newest first, 100 at a time (at most 1,000). The answer's next is the --before of the following page |
audit export [filters] [--output FILE] | Every matching record as JSON lines, oldest first, fingerprints included. --output writes a file readable only by root; without it, standard output |
audit verify [--checkpoint N:HASH] | Check that no record was changed, removed or added afterwards. Prints the first broken record if there is one and exits non-zero; prints the newest record's number and hash (last_seq, head_hash) to keep off the node, and checks one you kept |
Filters, for list and export:
| Flag | Keeps |
|---|---|
--since, --until | Records from / up to a time (RFC 3339, 2026-09-29T00:00:00Z, or Unix seconds) |
--principal | One principal, exactly as listed ("api key ak-12ab", root) |
--kind | One kind of principal: operator-token, operator-key, tenant-key, root, system, unauthenticated |
--tenant | Records made with one tenant's keys |
--action | Actions starting with this (vms. for every machine action) |
--object | Objects starting with this (/vms/vm-1a2b3c4d) |
--outcome | success, failure or refused |
sudo cenvero-str-ctl audit list --since 2026-09-29T00:00:00Z --outcome refused
sudo cenvero-str-ctl audit export --output /root/audit-$(date -u +%F).jsonl
sudo cenvero-str-ctl audit verify
Virtual machines (Compute, early access)
Needs a licence that includes Compute for every change; looking always works. See Compute.
| Command | Purpose |
|---|---|
compute status | Whether virtual machines are available on this node, and why not |
image register --name N --url URL --sha256 HEX [--wait] | Register a base image from a URL (the SHA-256 is required) |
image register --name N --path FILE [--sha256 HEX] [--wait] | Register a base image from a file on this node |
image catalogue | List the cloud images the node can install (The image catalogue) |
image register --name N --catalogue ID [--wait] | Install a catalogue image; it takes the entry's address and checksum, so give no URL or SHA-256 |
image list / image show <id> / image delete <id> | List, show, delete (refused while a machine uses it) |
iso list / iso show <id> | List the installation discs in the disc library, or show one with the machines that hold it |
iso register --name N --url URL --sha256 HEX [--wait], or iso register --name N --path FILE [--wait] | Add an installation disc, from an address with its SHA-256 or from a file on this node (Installation discs) |
iso delete <id> --yes | Delete a disc that no machine holds |
vm create --name N --image ID [--vcpus N] [--memory MiB] [--disk GiB] --network NET[=IP]… [--public-ip auto or IP]… [flags], or vm create --name N --iso ID --disk-gib GiB [--vcpus N] [--memory MiB] --network NET[=IP]… [flags] to install from a disc | Create and start a machine (all flags). The disc flags are --iso, --driver-iso, --disk-gib, --boot-order and --protected. --placement auto lets a cluster choose the member, and --anti-affinity sets a group; both are described in Placing machines. --pool names the pool the machine's disk and seed image are kept in (see the storage pools section of backups); the default pool when it is left out |
vm cdrom list <id> / vm cdrom set <id> --slot N --iso ID / vm cdrom remove <id> --slot N | A machine's two CD-ROM drives: list them, put a disc in one (--iso "" ejects it), or remove one (CD-ROM drives) |
vm options show <id> / vm options set <id> [--name N] [--protected=true] [--boot-order LIST] [--start-at-boot=false] [--anti-affinity GROUP] | A machine's name, protection, boot order and start-at-boot setting; --protected=false clears protection (Options). --anti-affinity sets the machine's group, and an empty value clears it (Placing machines) |
vm cloud-init show <id> / vm cloud-init set <id> [--hostname H] [--dns LIST] [--ssh-key-file F]… [--user-data-file F] [--apply-again] | A machine's first-boot settings, without their secrets (show), and changes to them, which apply at its next start (First boot) |
vm list [--tenant T] / vm show <id> | List, show |
vm start <id> / vm stop <id> [--timeout S] / vm force-stop <id> / vm restart <id> [--force] | Start and stop (Lifecycle) |
vm resize <id> --disk GiB | Grow a stopped machine's disk |
vm update <id> [--vcpus N] [--memory MiB] | Change CPUs and memory: live within the machine's maximums, otherwise at its next restart (Resizing) |
vm nic add <id> --network NET[=IP] or --public-ip auto or IP [--bandwidth-mbps N] | Add an interface, also to a running machine |
vm nic remove <id> <nic> / vm nic replug <id> <nic> | Remove an interface (by index, name or address); reconnect a running machine to a recreated one |
vm password <id> --user U | Set a guest account's password through the guest agent (read from the terminal or standard input, never the command line) |
vm guest-agent <id> | Whether the guest agent answers, and the guest's own addresses |
vm console <id> [--force] | The serial console on this terminal; Ctrl+] disconnects (Consoles) |
vm delete <id> --yes | Delete a machine and its disk; the disk's backups stay (Snapshots, backups and schedules) |
vm template <id> --name N [--shared] | Make a stopped machine's boot disk into a template; --shared lets other tenants' machines use it (Templates and clones) |
vm clone <id> --name N --network NET [--network NET]… [--hostname H] [--tenant T] [--pool P] | Clone a stopped machine into a new one, with its boot disk copied and its own identity. --pool keeps the clone's boot disk on pool P, as the API's pool does; without it the default pool is used (Templates and clones) |
vm disks <id> | List a machine's disks: its boot disk and its attached volumes, each with its role, size, state, and how many snapshots and complete backups it has (The boot disk) |
vm snapshot list <id> | List a machine's snapshots of its boot disk (Taking a snapshot) |
vm snapshot create <id> [--name N] [--no-quiesce] | Take a snapshot of a machine's boot disk; its file systems are frozen first when the guest agent answers, unless --no-quiesce is given (Taking a snapshot) |
vm backup list <id> | List a machine's backups of its boot disk (Taking a backup) |
vm backup create <id> [--kind KIND] [--keep N] | Back up a machine's boot disk. KIND is full or incremental (by default, incremental when the disk has an earlier backup to build on); --keep sets how many backups taken by hand the disk keeps, and 0 keeps every one; a schedule's keep is not changed by it (Taking a backup) |
vm migrate <id> --to <member> or --to auto [--mode MODE] [--wait] | Move a machine to another member. --to takes a member's ID, as cluster status lists it, or auto to let the cluster choose. --mode takes offline or auto, which stop the machine, copy its disks and check them, then start it there; or live, which moves the machine while it runs, with its disks on storage that both members share. --wait follows the move's task and exits with an error if the move did not succeed (Moving machines between nodes) |
vm migrations <id> | A machine's moves of the last 30 days, newest first |
vm bulk-migrate <id>... --to <member> or --to auto | Move several machines in one task. Every machine is judged before any moves, and a machine another member holds is refused: run the command on the member that holds the machines, or add --node for it (Maintenance and evacuation) |
migration show <id> | A move: its phase, its steps and, while the copy runs, its bytes |
migration cancel <id> | Cancel a move until its commit (a move while running only until its switch). Run it on the member the machine moves from; from another member, add --node with that member |
migration decide <id> --lost <member> --owner <member> [--source-down] | Decide a move whose member was lost during its switch, its release or its start: the member named as owner takes the machine. Run it on the member that takes the machine, or with --node set to it; --source-down confirms that a lost old member is down (Deciding a member lost during a live move) |
Every change above prints the id of the task that records it; follow
it with task log <id> --follow.
Volumes, snapshots and backups (Compute, early access)
Volumes, their snapshots and their backups, and each volume's backup schedule. A
machine's boot disk is one of the volumes: volume list shows it with the role
boot. Changes need a licence that includes Storage and is not frozen; reading
always works. The rules are on Snapshots, backups and schedules.
| Command | Purpose |
|---|---|
volume list / volume show <id> | List the volumes, or show one. A machine's boot disk has the role boot and its machine's id |
volume create --name N --size-gib N [--tenant T] [--image ID] [--pool ID] | Create a data volume. --pool names the pool it is kept in (see storage pool list); the default pool when it is left out |
volume attach <id> --vm VM / volume detach <id> | Attach a volume to a machine, or detach it. A boot disk cannot be detached |
volume resize <id> --size-gib N | Grow a volume; it cannot shrink |
volume delete <id> --yes | Delete a volume. A boot disk is kept with its machine |
snapshot create <volume> [--name N] [--no-quiesce] | Take a snapshot of a volume, with its file systems frozen when the guest agent answers unless --no-quiesce is given |
snapshot list [--volume V] / snapshot show <id> | List snapshots, or show one |
snapshot revert <id> --yes [--discard-newer] | Put a volume back to a snapshot. Stop its machine, or detach the volume, first; --discard-newer also deletes the snapshots taken after it |
snapshot delete <id> | Delete a snapshot; its data is merged back into the volume |
volume-backup create <volume> [--kind KIND] [--keep N] [--wait] | Back up a volume. KIND is full or incremental, and --keep sets how many restore points the volume keeps |
volume-backup list [--volume V] / volume-backup show <id> | List backups, or show one |
volume-backup restore <id> [--name N] [--pool ID] | Restore a backup into a new volume (the default), kept in the pool named by --pool; the default pool when it is left out |
storage pool list | List the node's storage pools, the default pool first, and the kinds of pool this node can use (backends, each with available) |
storage pool show <pool> | Show one pool: its kind, its state and how full it is, and the name of its directory for a directory pool (not its full path) |
storage pool create --name N [--backend KIND] [--location L] | Create a pool. KIND is dir (a directory pool, the default), thin-provisioned or zfs (a block pool, offered where this node has its tools). --location names a directory pool's directory, or a block pool's place on the host: group/pool for thin-provisioned, and pool or pool/dataset for zfs. A block pool needs --location. See Storage pools |
storage pool delete <pool> --yes | Delete a pool that holds no volumes. The default pool cannot be deleted. Deleting a block pool removes the node's record only: the thin-provisioned pool or ZFS dataset on the host is left as it was |
volume-backup restore <id> --in-place --yes [--discard-snapshots] [--wait] | Restore a backup over its volume's contents. The machine must be stopped; --discard-snapshots deletes the volume's snapshots |
volume-backup retention <volume> --keep N | Keep only the newest N backups taken by hand; 0 keeps every one. A schedule's keep is not changed |
volume-backup delete <id> --yes [--with-dependents] | Delete a restore point; --with-dependents also deletes the later incremental backups that build on it |
volume schedule show <volume> | A volume's backup schedule, with its times in UTC |
volume schedule set <volume> --expression EXPR --kind KIND --keep N [--enabled=false] | Set a volume's backup schedule. EXPR is daily@HH:MM, weekly@DAY-HH:MM or every-Nh, in UTC; KIND is full or incremental; --keep is 1 to 1000 |
volume schedule remove <volume> --yes | Remove a volume's schedule; the backups it made stay |
volume schedule run <volume> | Run a volume's schedule now |
schedule list | Every backup schedule on the node |
To work on a machine's boot disk from the command line, use its volume id, which
volume list shows with the role boot.
Backup targets (off-site copies, early access)
Off-site copies are sent to backup targets. Changing a target needs a licence that includes Storage and is not frozen; reading always works. The rules are on Off-site copies.
The secret access key is never a command-line argument. Give it with --secret-file, which
reads the contents of a file that holds it, with any trailing line break removed, or with
--secret-stdin, which reads one line from standard input.
| Command | Purpose |
|---|---|
storage target list | List the backup targets, the oldest first |
storage target show <target> | Show one target. Its secret is never shown: only the last four characters of its key id, and whether a secret is set |
storage target create --name N --endpoint URL --bucket B --access-key-id ID --secret-file F | Add a target. --secret-stdin takes the place of --secret-file. --endpoint starts with https://; --region defaults to us-east-1; --prefix defaults to cenvero-stratum/; --path-style addresses the bucket in the path |
storage target set <target> [flags] | Change a target; only the flags given change. To change the credentials, give --access-key-id with --secret-file or --secret-stdin |
storage target test <target> | Test the address and the credentials: a small test file is written, read back and removed |
storage target key-export <target> --yes | Export the target's key, on the node that holds it. The key is printed in the answer; keep it where only the operator can read it |
storage target key-import <target> --key-file F --yes | Set the target's key from the export it printed, on the node that needs it. The key comes from the file given with --key-file (its contents, with any trailing line break removed), or from standard input with --key-stdin. It is refused while this node holds copies on the target and can read the key the target has. It cannot be sent to another node with --node |
storage target copies <target> | List the copies the target holds, and whether each can be restored from this node; a copy that cannot says why |
storage target copy-check <target> <copy> | Check one copy the target holds now: its length, the checksum the target reports, its record, and one part of its data read back with the target's key. The answer says whether it passed, and a copy that failed says why. The check changes no data, and an alert on copy_check_failed follows a failure |
storage target restore <target> <copy> [--name N] [--pool P] | Restore a copy into a new volume on this node, as a task. --name names the volume, and --pool the pool it is kept in; the default pool when --pool is left out |
storage target delete <target> --yes | Delete a target that no schedule and no backup names |
Give the secret from a file with --secret-file, or type it at the prompt with --secret-stdin:
sudo cenvero-str-ctl storage target create --name offsite --endpoint https://storage.example.net --bucket stratum-backups --access-key-id KEY_ID --secret-file /root/offsite.secret
sudo cenvero-str-ctl storage target create --name offsite-two --endpoint https://storage.example.net --bucket stratum-backups --access-key-id KEY_ID --secret-stdin
sudo cenvero-str-ctl storage target test <target>
sudo cenvero-str-ctl storage target key-export <target> --yes
sudo cenvero-str-ctl storage target key-import <target> --key-file /root/offsite.key --yes
sudo cenvero-str-ctl storage target copies <target>
sudo cenvero-str-ctl storage target restore <target> bk-3b8e0a71 --name restored-data
A backup or a schedule names its target with --target, given the target's id from
storage target list:
sudo cenvero-str-ctl vm backup create vm-3f9a1c2e --target tgt-3b8e0a71
sudo cenvero-str-ctl volume-backup create vol-7d4e2f10 --target tgt-3b8e0a71 --wait
sudo cenvero-str-ctl volume schedule set vol-7d4e2f10 --expression daily@02:30 --kind incremental --keep 7 --target tgt-3b8e0a71
volume schedule set replaces the schedule as a whole, so a schedule set without --target
has no target, and its backups are not copied. The rules are on
Naming a target, and the API names the same fields:
see Backup targets.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Invalid arguments |
| 3 | Agent unreachable (is cenvero-stratum.service running?) |
| 4 | Operation blocked by license enforcement (see Licensing) |
See also
- API Reference — the same managers over REST, plus the WebSocket event stream and the gRPC health check.
- Configuration — the node config model and every field.
- Operations — day-2 running, updates, and troubleshooting.