Network Services Control

The agent runs a small set of network services alongside the data plane — among them the built-in DNS resolver and the DHCP server. Each one is independently switchable, so an operator can turn DNS or DHCP on or off, see whether it is actually listening, and tune how it binds and who may talk to it. This page covers the service command group, the DNS and DHCP configuration knobs, and the dns … / dhcp … operator commands. For zone and pool concepts, see DHCP & DNS.

The `service` command group

cenvero-str-ctl service shows and toggles the agent's switchable network services: the REST, gRPC and WebSocket management APIs, the Prometheus metrics endpoint, DNS, and DHCP. The local control socket that cenvero-str-ctl itself rides is always up and is deliberately not a toggleable service — it cannot be turned off.

Seeing what is running

cenvero-str-ctl service status

Network services
================
SERVICE        ENABLED  ADDRESS            STATE      NOTE
REST API       on       0.0.0.0:7070       listening
gRPC API       on       0.0.0.0:7071       listening
WebSocket API  on       0.0.0.0:7072       listening
Metrics        on       127.0.0.1:9090     listening
DNS            on       10.0.0.1:53        listening
DHCP           on       :67                listening

ENABLED reflects the operator switch (applied at next restart); STATE is a live listen probe.
Apply a change with:  systemctl restart cenvero-stratum

The two columns mean different things:

ENABLED is the operator switch — what the agent would start on its next restart.
STATE is a live probe of the address: listening (something is bound there now), down (nothing is), or unknown (the address could not be probed).

status also answers to list, top, ls, and ps, and a bare cenvero-str-ctl service prints the same table. Add --format json (or yaml) for machine-readable output.

Turning a service on or off

Both word orders work, as do the enable/disable aliases:

# Turn the DNS resolver off
sudo cenvero-str-ctl service dns off

# Turn the DHCP server back on (these are equivalent)
sudo cenvero-str-ctl service dhcp on
sudo cenvero-str-ctl service on dhcp
sudo cenvero-str-ctl service enable dhcp

Toggling a service records its enable flag in the agent's local override store — the same mechanism config set uses — so the change persists across reboots. It is not applied to the running process immediately: it takes effect on the next agent restart. The command reminds you how:

Service dns (DNS) disabled.
Verify with:  cenvero-str-ctl service status

sudo systemctl restart cenvero-stratum

DNS and DHCP only switch their network listeners. With DHCP off, the agent stops binding UDP :67 (it hands out no addresses) but the lease table and its expiry bookkeeping keep running, so existing leases are still tracked. With DNS off, the resolver does not bind a port; zone and record data is untouched and still served over the management API. Turning the service back on and restarting re-binds it.

The IPC control socket cannot be disabled — asking to turn off ipc (or socket) is refused with an explanation rather than silently accepted, because it is the channel this very command travels over.

Configuring DNS

The agent is authoritative for the zones you create (for example app-net.internal — creating a network does not create one) and acts as a recursive forwarder for everything else. Two settings control where it listens and who may use it for recursion.

Listen address

By default the resolver listens on UDP port 53 of the management bridge's IPv4 address, as the bridge has it when the agent starts. If the management bridge has no address it uses the workload bridge's, and if neither has one it uses loopback (127.0.0.1:53). It is never bound to every interface at once (0.0.0.0:53).

On a server with a single network card the management bridge carries the host's own address — often a public one — so by default the resolver answers there. Recursion is still refused to clients outside the allowed set (below), but your zones are answered to anyone who can reach the address. Pin the resolver to a private address, or filter port 53 upstream, if that is not what you want.

To pin it to a specific address, set dns_listen_addr to an IP address (port 53 is assumed) or address:port. config set takes the key and value positionally:

sudo cenvero-str-ctl config set dns_listen_addr 10.0.0.1:53

A bare address such as 10.0.0.1 is saved as 10.0.0.1:53. An IPv6 address is written [fd00::1]:53 (or bare, fd00::1). A hostname or a port outside 1-65535 is refused. If the node finds a value it cannot listen on — for example one written by an older version — it logs a warning and uses the default address instead of leaving DNS down.

Setting it back to empty reverts to the bridge-address default:

sudo cenvero-str-ctl config set dns_listen_addr ""

The address change is applied on the next agent restart; confirm the resulting bind with service status.

Allowed clients (recursion ACL)

Recursion — forwarding a query for a name outside the local zones to an upstream resolver — is gated by a client ACL so the agent is never an open resolver. Set the allowed clients as a comma-separated list of IPs and/or CIDRs:

sudo cenvero-str-ctl config set dns_allowed_clients "10.20.0.0/24,10.30.0.0/24"

When the list is empty (the default) it falls back to the loopback and private ranges (127.0.0.0/8, ::1/128, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7). A query from a client outside the allowed set is refused, not silently forwarded. Authoritative answers for the local zones are always returned regardless of the ACL.

Zones, records, and forwarders

Day-to-day zone and record management uses the dns command group:

Command	Purpose
`dns zones`	List the authoritative zones with their ids
`dns zone add <name>`	Create a zone
`dns zone delete <zone_id>`	Delete a zone
`dns records` / `dns list [zone_id]`	List records (all zones, or one zone)
`dns record add <zone_id> <name> <type> <value> [ttl]`	Add a record to a zone
`dns record delete <record_id>`	Remove a record

Zones and records are addressed by their numeric ids, which dns zones and dns list report:

# List zones to find the zone id, then add and remove a record
cenvero-str-ctl dns zones
sudo cenvero-str-ctl dns record add 1 api A 10.20.0.55 300
cenvero-str-ctl dns list 1
sudo cenvero-str-ctl dns record delete 3

dns add and dns delete are shorthand aliases for dns record add and dns record delete.

Upstream forwarders (the resolvers recursion is sent to) are managed live with the dns forwarder list/set/add/remove commands and take effect on the running agent; persist them across restarts with config set dns_upstreams <ip,...>. See DHCP & DNS → Upstream forwarders.

Configuring DHCP

The DHCP server leases addresses from the address pool of the scope a request matches. It listens on UDP :67 on every interface while it is enabled, but answers a request only from the scope that matches the interface it arrived on (or its relay), and sends the reply back out of that same interface.

Scopes

A scope binds a client subnet to its own address pool and the reply parameters advertised to clients on that subnet — the server identity, gateway, subnet mask, DNS servers, and an optional per-scope lease length. network create does not make one: until a scope exists for a subnet, the server has nothing to offer there. Multiple scopes let one agent serve several subnets.

A request that reaches the node directly is matched to the scope whose subnet contains an address the node holds on the interface the request arrived on, so give the node an address in the network's subnet on that bridge (normally the gateway). A relayed request is matched by the address of the DHCP relay that forwarded it (its giaddr). See DHCP & DNS → How a request finds its scope.

There are two ways to add a scope:

Over the API — POST /api/v1/dhcp/scopes, listed with GET and removed with DELETE; see the API Reference. A scope added this way is kept by the node and survives an agent restart; adding one for a subnet that already has a scope replaces it, and DELETE removes it for good.
In the node configuration (dhcp_scopes), which is delivered with the node's signed configuration and applied every time the agent starts. It is not a config set key. Removing one of these over the API lasts only until the next start, when the configuration applies it again; an API scope for the same subnet takes its place.

Each scope carries:

Field	Meaning
`subnet`	The client subnet the scope serves (CIDR)
`pool_id`	The address pool addresses are leased from (required — a scope with no pool has nothing to offer)
`server_ip`	The DHCP server identity advertised to clients (when empty, the node's own address on the client's subnet)
`gateway`	The default gateway offered to clients
`subnet_mask`	The subnet mask offered to clients (when empty, the mask of `subnet`)
`dns`	The DNS server(s) offered to clients
`lease_seconds`	Optional per-scope lease length (0 = the server default)

Reservations and leases

Use the dhcp command group to inspect leases and to pin or release an address:

Command	Purpose
`dhcp leases`	List current leases (MAC, IP, hostname, expiry)
`dhcp reserve`	Pin a specific IP to a MAC (a static lease)
`dhcp release`	Release a lease/reservation early

The reserved IP selects its own pool, so these commands identify a client by MAC rather than by network:

# Always hand db-primary the same address
sudo cenvero-str-ctl dhcp reserve \
  --mac 52:54:00:de:ad:01 \
  --ip 10.30.0.10 \
  --hostname db-primary

# Inspect what is leased, and what is pinned
cenvero-str-ctl dhcp leases
cenvero-str-ctl dhcp reservations

# Release a reservation before re-provisioning a workload
sudo cenvero-str-ctl dhcp release --mac 52:54:00:ab:01:02

Once any endpoint or MAC binding exists on the node, the server answers only hardware addresses the node has a binding for. A request from any other hardware address gets no offer at all — silence, not a refusal — and the agent logs a warning for it.

A reservation pins the address only — it does not create a DNS record. To make the hostname resolve to the reserved IP, add a DNS record for it with dns record add (or the API). See DHCP & DNS → Reservations for how reservations and the lease table behave in more depth.

Quick reference

Task	Command
See every service's switch + live state	`cenvero-str-ctl service status`
Turn DNS off / on	`sudo cenvero-str-ctl service dns off` / `… dns on`
Turn DHCP off / on	`sudo cenvero-str-ctl service dhcp off` / `… dhcp on`
Apply a service toggle	`sudo systemctl restart cenvero-stratum`
Set the DNS listen address	`sudo cenvero-str-ctl config set dns_listen_addr <ip>:53`
Set the DNS recursion allow-list	`sudo cenvero-str-ctl config set dns_allowed_clients <cidrs>`
Reserve / release a DHCP address	`sudo cenvero-str-ctl dhcp reserve …` / `dhcp release …`
Manage a DNS record	`sudo cenvero-str-ctl dns add …` / `dns delete …`