Docs / CLI Reference

CENVERO/DOCS

// CLI Reference

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.
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`
Tenants & billing	`tenant` `apikeys` `billing`
Operations	`backup` `alert` `heal` `container` `plugin` `node`

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 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, port_cluster, port_ha_heartbeat, metrics_bind_addr, dns_listen_addr, dns_allowed_clients, dns_upstreams, heal_interval_seconds, heal_disabled_checks, and the six service switches (rest_disabled, grpc_disabled, websocket_disabled, metrics_disabled, dns_disabled, dhcp_disabled). Identity, the license server, the API token, and any signing/cluster-secret/TLS material are refused — they are panel- or identity-owned, not local operational settings. 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 (Account → TLS). 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)
`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 SAN domains on the certificate
`tls domain add <domain>`	Add a SAN domain (regenerates the certificate)
`tls domain remove <domain>`	Remove a SAN domain (regenerates the certificate)

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 domain you point at the node's IP can be added with tls domain add. See TLS & Licensing for the approval flow.

`update`

Pull-based agent updates from your licensed release channel.

Command	Purpose
`update check`	Report current vs latest version + channel (no download)
`update apply`	Download, verify, and apply an available update now (alias `update now`)
`update rollback`	Roll back to the previously-installed version

cenvero-str-ctl update check
sudo cenvero-str-ctl update apply
sudo cenvero-str-ctl update rollback   # undo the last apply

update apply verifies the download's signature, swaps the binary atomically, and restarts under watchdog supervision with self-rollback if the post-restart health check fails. A node in the Frozen license state keeps running but cannot pull updates until the license is renewed. See Upgrades.

update rollback restores the binary that the most recent update apply preserved, undoing that update; restart the agent (systemctl restart cenvero-stratum) to run the restored version. If no update has been applied on this node there is nothing to restore and it reports *"no previous version to roll back to"*. Rollback is a change, so it is refused while the license is Frozen. 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.

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

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 licence 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]`)
`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 licence 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

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.

`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
`dns delete <record_id>`	Delete a record
`dns dnssec <zone>`	Show a zone's DNSSEC keys + the DS record to lodge with the parent
`dns zone list/add <name>/delete <zone_id>`	Zone CRUD
`dns record list [zone_id]/add .../delete <record_id>`	Record CRUD
`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). dns forwarder changes apply to the running agent; persist them across restarts with config set dns_upstreams <ip,...>.

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
`vlan allow <id>`	Record an explicit allow
`vlan clear <id>`	Clear a VLAN's policy (back to default-open)

`vxlan`

Command	Purpose
`vxlan list`	List overlay networks
`vxlan create <vni> <subnet>`	Create an overlay network
`vxlan delete <vni>`	Delete an overlay network
`vxlan peers <vni>`	List a VNI's remote peers
`vxlan peer-add <vni> <host> <mac> <vtep_ip>`	Add a remote peer
`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}`
`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}`
`route rule delete <id>`	Delete a policy-routing rule by id

Security

`firewall`

Command	Purpose
`firewall allow`	Add an allow rule
`firewall deny`	Add a deny rule
`firewall list`	List firewall rules
`firewall delete`	Delete a rule
`firewall conntrack`	Show the connection-tracking table
`firewall conntrack-flush [ipv4]`	Drop connection-tracking state so rule changes apply to connections that are already open (optionally just one peer)
`firewall schedule set/clear/list`	Attach a time-of-day/day-of-week activation window (UTC) to a rule
`firewall connlimit set/clear/status`	Per-source concurrent-connection limits (IPv4)

`rules`

The structured firewall rule table (chains, priorities, stateful matching).

Command	Purpose
`rules list`	List all rules
`rules add`	Add a rule
`rules remove <id>`	Remove a rule by id
`rules preset <web/db/mail/game/minimal/open>`	Apply a server preset rule-set atomically
`rules batch <json-rule-array>`	Apply a JSON array of rules atomically

Traffic shaping & visibility

`bandwidth`

Command	Purpose
`bandwidth list`	List per-MAC rate limits and shared pools
`bandwidth set`	Create/update a per-MAC rate limit
`bandwidth pool`	Manage shared bandwidth pools

`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
`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 and backend set
`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>`	Stop sending new connections to a backend and let the existing ones finish
`lb set-health`	Configure a VIP's health check
`lb delete`	Delete a VIP

`bgp`

Command	Purpose
`bgp status`	Engine status
`bgp neighbors`	List peers
`bgp routes` / `bgp rib` / `bgp fib`	Route table / RIB / forwarding table
`bgp peer`	Manage peers (add/list/remove)
`bgp announce` / `bgp withdraw`	Advertise / withdraw a prefix
`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

`gateway`

Command	Purpose
`gateway status`	Gateway HA status
`gateway failover`	Trigger a manual gateway failover

`ha`

Gateway high-availability: two paired nodes run active/standby and the active node owns a virtual IP (VIP), taking it over on failover.

Command	Purpose
`ha status`	Show HA status (active/standby/solo, VIP, peer)
`ha set-peer`	(Provisioned via the panel-delivered config)
`ha configure`	(Provisioned via the panel-delivered config)

HA is configured from the panel-delivered configuration (peer address, priority, VIP, and a shared secret) and read at agent boot. Use ha status and the REST gateway endpoints for live status and manual failover.

`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)
`bond create --name <dev> --mode active-backup/802.3ad [--mtu N]`	Create a bond
`bond add-member <id> --iface <nic>`	Enslave a NIC
`bond remove-member <id> --iface <nic>`	Release a NIC
`bond set-mtu <id> --mtu N`	Set the MTU across the bond + members
`bond delete <id>`	Delete a bond (releases its members first)

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`

Inspect this node's clustering state. Every member is the same kind of node, so there is nothing to choose here — cluster status reports the local role in the cluster (leader or follower), not a node type.

Command	Purpose
`cluster status`	Cluster state, leader, and peers
`cluster join`	(Configured via the panel-delivered config / REST API)
`cluster leave`	(Configured via the panel-delivered config / REST API)

Cluster membership is configured through the panel-delivered configuration; peers authenticate with mutual TLS (no join token to type). Use cluster status to check the local state. See Clustering.

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 bandwidth cap
`tenant quota-set <id> --max-bandwidth-bps N`	Set a tenant's bandwidth cap (`0` = unlimited)
`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. The secret is shown only once, at mint time.

`apikeys`

Operator API keys for the billing API. A minted key authenticates your billing system against the agent's /api/v1/billing endpoints.

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

`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

`backup`

Command	Purpose
`backup create [config/full]`	Create a backup (default `config`)
`backup restore <id/path>`	Restore from a backup
`backup list`	List backups
`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`	List fired alerts (optional state filter)
`alert history`	Full alert history
`alert ack <alert_id>`	Acknowledge a firing alert
`alert condition list`	List threshold conditions
`alert condition add <json>`	Add a condition, e.g. `'{"metric_type":"pps","operator":"gt","threshold":1000}'`
`alert condition remove <id>`	Remove a condition
`alert action list`	List configured actions across all conditions
`alert action add <condition_id> <websocket/log/webhook> [config]`	Attach an action to a condition

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

`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`	Verify a plugin package signature
`plugin enable` / `plugin disable`	Enable / disable a plugin
`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

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)

CLI Reference

Status & system

status

version

metrics

hardware

pull

System management

config

service

api-token

tls

update

license

Networking

network

nic

ipam

dhcp

dns

vlan

vxlan

route