Exclusive Access · Invitation Only

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 (or yaml) to any command for machine-readable output (the default is a human table/JSON view).
  • Add -h to 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:

AreaGroups
Status & systemstatus version metrics hardware pull
System managementconfig service tls update license
Networkingnetwork nic ipam dhcp dns vlan vxlan geneve vrf route
Securityfirewall rules
Traffic shaping & visibilitybandwidth quota flow
Services & HAlb l7lb bgp gateway nat64 ha bond cluster
Access controluser group role acl token realm apikeys
Tenants & billingtenant billing
Operationstask 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, and cluster forget and cluster pin-members. Those answer this 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>), with via_node naming the server it came through. The server you type on records it too, with the server asked as target and 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 show there 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 on and off, 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.
  • --node with 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, --node answers that there is no other server to run the command on, and a server not yet on this version answers update <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

CommandPurpose
config set [<key> <value>]Change a whitelisted operational setting (run with no args to list keys)
config showPrint the decoded on-disk configuration (secrets redacted)
config dumpDump the on-disk configuration
config encodeWrite the node's signed configuration from flags (used by the installer)
config exportPrint 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.

CommandPurpose
service statusShow each service (aliases: list, top, ls, ps)
service <name> onEnable a service (also service on <name>)
service <name> offDisable 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.

CommandPurpose
api-token generateMint a strong random token, store it, print it once
api-token setStore a token you supply, read from stdin
api-token statusReport whether a token is set — never prints the value
api-token clearRemove 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.

CommandPurpose
tls infoLive certificate: mode (ca-signed/self-signed), expiry, SAN domains
tls showThe certificate / key / public-key file locations
tls pubkeyPrint the public-key file location
tls requestRequest a CA-signed certificate from the panel now (online); a request waiting for your approval answers "status": "pending" and exits 0
tls pullPull this node's CA-signed certificate now (collect it once approved)
tls regenerateGenerate a fresh certificate now (hot-reloaded, no restart)
tls csrGenerate a key + CSR locally without contacting the panel (offline)
tls install <cert> [chain]Install a signed certificate obtained out-of-band
tls pending-statusReport any pending certificate request (online or offline)
tls reset-pendingDiscard a pending offline CSR so you can start fresh
tls resetClear the current certificate + pending request and re-obtain a fresh one
tls domain listList 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.

CommandPurpose
update statusWhat runs, what is installed, staged and offered, and what can be rolled back to (contacts nothing)
update checkAsk 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 --offlineThe 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

CommandPurpose
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 renewForce a license renewal for this machine
license refreshRe-fetch the signed license for this machine
license load <file>Load a signed license file manually
license statusFull 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.

CommandPurpose
network createCreate a network (--name --cidr [--gateway --vlan --tenant] [--host-gateway [--snat] [--dhcp]])
network host-gateway <id> [--snat] [--dhcp] or network host-gateway <id> --offSet a network's host gateway; the flags given are the whole setting
network listList 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.

CommandPurpose
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

CommandPurpose
nic listList detected network interfaces
nic detectRe-scan and list interfaces
nic accelShow the acceleration mode (hardware vs software) per interface

ipam

CommandPurpose
ipam poolsList IP pools
ipam allocationsList every allocation (optional tenant id)
ipam allocateAllocate an IP address
ipam releaseRelease an IP address

dhcp

CommandPurpose
dhcp leasesList DHCP leases
dhcp reservationsList 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.

CommandPurpose
dns zonesList 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).

CommandPurpose
vlan listList 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).

CommandPurpose
macbind listList 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

CommandPurpose
vxlan listList 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 fdbDump the overlay forwarding database

route

Static routes (optionally in a non-main table) and the policy rules that steer traffic into those tables.

CommandPurpose
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 listList 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

CommandPurpose
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 listList firewall rules; a rule saved with a setting that is not enforced carries not_enforced entries
firewall delete <id>Delete a rule
firewall defaultShow 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 conntrackShow 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/listAttach a time-of-day/day-of-week activation window (UTC) to a rule; it applies to new connections only
firewall connlimit set/clear/statusPer-address connection limits (IPv4; counts the connections an address opened that carried traffic in the last minute)
firewall blocklistShow 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.

CommandPurpose
rules listList 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

CommandPurpose
bandwidth listList 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 poolShow 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.

CommandPurpose
quota listList 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

CommandPurpose
flow listList active flows (optional state filter)
flow statsAggregate flow statistics

Services & HA

lb

L4 virtual IPs (VIPs) with a backend pool.

CommandPurpose
lb listList VIPs
lb createCreate a VIP; add its backends with lb add-backend
lb showShow a VIP's detail
lb backends <id>List a VIP's backends
lb add-backend / lb remove-backendAdjust 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 deleteDelete a VIP

l7lb

The HTTP (layer-7) load balancer: pools of backends, and frontends that route to them. See Load Balancer.

CommandPurpose
l7lb statusFrontends (listening, or why not), pools (loaded, or why not), and each backend's health and requests in progress
l7lb pool listList 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 listList frontends
l7lb frontend add <json>Create a frontend; listening port 0 is refused
l7lb frontend remove <name>Remove a frontend

bgp

CommandPurpose
bgp statusEngine status
bgp neighborsList peers
bgp routes / bgp ribRoute table / RIB
bgp fibThe routes the node has installed in its routing table, and under not_installed the ones it could not install, with the reason
bgp peerManage 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 announcementsList active announcements
bgp prefix-listManage prefix-lists (add <json> / list)
bgp route-mapManage route-maps (add <json> / list)
bgp policyBind import/export route-maps (import/export <neighbor> <route-map> / list)
bgp import-policyManage import policy
bgp rpki configure <rtr-addr> [--reject-invalid] / enable / disableRoute-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

CommandPurpose
gateway statusHA status of this node and its peer
gateway failoverTake the VIP onto this node; refused while the pair's heartbeat runs
gateway failbackRelease 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.

CommandPurpose
ha statusShow HA status (active/standby/solo, VIP, peer)
ha set-peerRefused: the pair's settings cannot be set on the node
ha configureRefused: 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).

CommandPurpose
bond listList 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 NSet 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.

CommandPurpose
cluster statusThis 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 listThe 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> --previewShow 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 leaveTake 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 EBring 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> --clearSet, 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 --yesMake 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

CommandPurpose
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 listEvery 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-stdinSet 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

CommandPurpose
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

CommandPurpose
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

CommandPurpose
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

CommandPurpose
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).

CommandPurpose
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.

CommandPurpose
apikeys mint <label>Mint a new key (secret shown once)
apikeys listList 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.

CommandPurpose
tenant listList 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 NSet 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 NCap 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 NCap 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 NRefused 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.

CommandPurpose
billing suspend <tenant-id>Suspend a tenant
billing resume <tenant-id>Resume a tenant
billing limit <tenant-id> --rate-mbps NApply 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").

CommandPurpose
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

CommandPurpose
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 listList 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

CommandPurpose
alert statusAlerting status (counts + action-dispatch success/failure)
alert list [firing/acknowledged/resolved]List alerts, newest first, optionally in one state
alert historyEvery 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 listList 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 listList 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

CommandPurpose
heal statusLatest health-check results
heal checkForce 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).

CommandPurpose
container listList 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.

CommandPurpose
tag <vm/network/volume/image/tenant/node> <id>Show the object's tags and notes
tag <kind> <id> <tag>… / tag <kind> <id> --clearSet its tags, replacing the ones it has, or remove them all
note <kind> <id> --file F / --stdinSet 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

CommandPurpose
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 listList installed plugins
plugin showShow plugin detail
plugin removeRemove 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 disableEnable / disable a plugin (enable re-verifies it first)
plugin store add <signed-store-file>Trust an external plugin store (verified offline)
plugin store listList 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

CommandPurpose
node infoNode information: hardware id, agent version
node maintenance showThis 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 onPut 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 offEnd this member's maintenance. An evacuation does not end it, and ending it stops the member's evacuation before its next move
node evacuation-planWhere 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.

CommandPurpose
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:

FlagKeeps
--since, --untilRecords from / up to a time (RFC 3339, 2026-09-29T00:00:00Z, or Unix seconds)
--principalOne principal, exactly as listed ("api key ak-12ab", root)
--kindOne kind of principal: operator-token, operator-key, tenant-key, root, system, unauthenticated
--tenantRecords made with one tenant's keys
--actionActions starting with this (vms. for every machine action)
--objectObjects starting with this (/vms/vm-1a2b3c4d)
--outcomesuccess, 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.

CommandPurpose
compute statusWhether 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 catalogueList 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> --yesDelete 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 discCreate 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 NA 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 GiBGrow 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 USet 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> --yesDelete 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 autoMove 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.

CommandPurpose
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 NGrow a volume; it cannot shrink
volume delete <id> --yesDelete 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 listList 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> --yesDelete 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 NKeep 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> --yesRemove a volume's schedule; the backups it made stay
volume schedule run <volume>Run a volume's schedule now
schedule listEvery 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.

CommandPurpose
storage target listList 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 FAdd 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> --yesExport 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 --yesSet 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> --yesDelete 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

CodeMeaning
0Success
1General error
2Invalid arguments
3Agent unreachable (is cenvero-stratum.service running?)
4Operation 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.
↓ This page as JSON ↓ All documentation as JSON