network-manager
The network front door. It owns zones.json (the desired network state) and
reconciles four infrastructure planes — OPNsense, Proxmox, the switch, and access
points — by orchestrating their controllers. Adding or deleting a zone authors
the config and drives every plane so a new VLAN actually reaches the firewall,
the Proxmox hosts, the physical switch, and the WiFi.
What it owns
zones.json at ${TAPPAAS_CONFIG:-/home/tappaas/config}/zones.json. Each top-level
key is a zone (keys beginning _ are documentation blocks, preserved but not
treated as zones). A zone records its type / typeId, vlantag, ip (CIDR),
bridge, state, reachability (access-to), per-module pinhole allowance
(pinhole-allowed-from), and optional variant/SSID. Auto-allocated VLANs use
the 60–99 window within each type band; zone names must be camelCase.
Changing a zone's policy — modify --set
network-manager modify rossen --set access-to=internet,mgmt
network-manager modify rossen --set 'pinhole-allowed-from=["home","work"]'
A zone's policy fields — access-to, pinhole-allowed-from, description,
isolated, tier, the DHCP options — are changed by a verb rather than by
hand-editing zones.json, which is the anti-pattern ADR-014 D1 named. Lists
take either the comma form or JSON.
Like enable/disable/bind, this authors zones.json only and prints the
reconcile --apply to run: the operator decides when the firewall changes.
What it refuses, and why the two refusals read differently (ADR-020 D6):
| Field | ||
|---|---|---|
vlantag, ip, type, typeId, subId, bridge |
immutable |
The zone's identity. Changing a VLAN would strand every guest tagged into it — that is delete-and-re-add, with the guests moved deliberately. |
state |
has a verb | enable / disable / manual, which guard the Mandatory transition. |
environment |
has a verb | bind --environment, which checks the environment exists and keeps one zone per environment, so a typo fails at the command. |
SSID |
has a verb | ap-manager's ssid add / modify --zone / remove: the WiFi network is ap-manager's, and the zone only shows which one bridges to it. |
A --set naming any of those is refused before anything is written, and a
mixed --set is rejected whole — zones.json and the planes never move apart.
Each field's cost is declared as changeClass in schemas/zones-fields.json.
Commands
One compiled CLI, network-manager:
network-manager list [--state S] [--type T] [--tier N] [--json]
network-manager exists <name>
network-manager show <name> (alias: get)
network-manager add <name> [options]
network-manager delete <name> [--check]
network-manager enable|disable|manual <name> [--force]
network-manager bind <zone> --environment <env> [--add] | --unbind [--environment <env> [--own]]
network-manager set-ssid <zone> <ssid> | --clear (ap-manager's writer; use ap-manager ssid)
network-manager reconcile [--apply] [--only opnsense|proxmox|switch|ap]
network-manager topology [--json] [--live | --diff] [--health <file> | --no-health] [--no-positions]
network-manager init [<profile>] --name <N> [--from <tpl>] [--out <f>] [--force]
network-manager retire [--apply]
network-manager validate [--zones <file>] [--config-dir <dir>] [--strict]
[--effective]
network-manager merge [--diff] [--config-dir <dir>] [--template <tpl>]
network-manager distribute [--zones <file>] [--dry-run]
network-manager wgvpn <setup|add-peer|remove-peer|list|config> [options]
network-manager wan ipv6-relearn [--check | --apply]
network-manager -h | --help
The zone keyword is an optional, legacy prefix — add and zone add are
equivalent. (validate keeps the alias zones-check.)
list / exists / show / add / delete — CRUD on zones.json
network-manager list # name / state / vlan
network-manager list --state Inactive # which zones are defined-but-off
network-manager list --type Client # + tier and environment columns
network-manager list --tier 6 # the no-egress zones
network-manager exists srvHome # exit 0/1
network-manager show srvHome # print the zone object (alias: get)
list filters combine (--state Active --type Service); --json emits the
matching names as an array. --type Client|IoT|Guest (and any --tier query)
adds tier, environment and isolated columns — which is how you answer
"which client zones exist, and which environment does each serve?"
add <name> authors a new zone and reconciles all four planes (so the
VLAN reaches everything). Options:
--archetype <A>— the preferred way to create a zone (ADR-014 D5). Stamps a tier-correcttype/typeId/tier/isolatedand theaccess-toseed, then auto-allocates the VLAN/IP — no hand editing, and the result passesvalidateunmodified. One of:control,service,trusted-client,guest,dmz,iot-local,iot-cloud,iot-cams,iot-untrust. Cannot be combined with--type/--typeId/--from-zone(the archetype already defines them); the combination is refused rather than resolved.--environment <env>— the environment the new zone belongs to, in the same command (seebindbelow): for a Service zone the environment whose zone it is (refused when that environment already has one), for a Client/IoT/Guest/DMZ zone the environment(s) it serves (a,bfor several). The environments must exist.--from-zone <src>— inherit type/typeId/bridge/access-to/pinhole from<src>.--type <T>— zone type (defaultService).--typeId <N>— numeric type band (default2).--vlan <tag>— explicit VLAN tag (else auto-allocated 60–99 in the band).--variant <name>— tag the zone with this variant (metadata).--no-activate— authorzones.jsononly; skip the all-plane reconcile.--check— dry-run: show what would change, mutate nothing.
Before it authors, add asks the firewall what it carries (opnsense-firewall
segments). A VLAN tag or subnet that is already there on a segment zones.json
never knew — one built by hand in OPNsense, or left behind by a deleted zone —
is refused with the holder named, on --check too. The allocation is not
retried: TAPPaaS's own numbers stay the same on every site, and the operator
moves the site's own segment to a free tag, then adds again. init (a later
profile on a running site) and merge (a template zone new in a release)
make the same check. A firewall that cannot be asked is said, and the check
covers zones.json only, as before.
delete <name> disables the zone, reconciles all planes, then removes the
key. --check dry-runs it.
A zone authored the low-level way (--type/--from-zone) is deliberately left
untiered — validate notes it — rather than being given a guessed rank.
network-manager add cams --archetype iot-cams --environment warmelo
network-manager add lab --archetype service --environment lab
network-manager add labNet --from-zone srvHome --vlan 275 # low-level escape
network-manager add labNet --check # preview
network-manager delete labNet
bind — link a zone to its environment
A zone names its environment in one field, environment; the environment file
names no zone.
- A Service zone names the environment whose zone it is, as a string — its
own zone, where its modules run by default. Every environment has exactly
one (the Management zone
mgmtis themgmtenvironment's).environment-manager add|modify --zonesets it for you. - A Service zone naming a list of environments (even of one) is a shared
service zone: it serves each, owns none, and derives no edge. A module of
any environment it lists may be installed there (
--zone0 <zone>); see ZONES.md. - A Client, Guest or IoT zone names the environment it serves, or a
list of them when it serves several (it gets the edges of each). A
client zone reaches its services, and an IoT zone is reached by them; writing
that as a literal service-zone name does not survive install (
initrenamessrv→<defaultEnvironment>, and the literal is stranded), so the edge is derived from the environment's current zone on every reconcile. - A DMZ zone may name the environment(s) it fronts; that derives nothing.
- Overlay and WAN zones name none.
network-manager bind home --environment warmelo # home serves warmelo
network-manager bind home --environment lab --add # ... and lab as well
network-manager bind home --unbind --environment lab # ... no longer lab
network-manager bind lab --environment lab # lab is the lab environment's zone
network-manager bind srvWork --environment custB --add # srvWork is shared: it serves custB too
network-manager bind srvWork --unbind --environment custB # ... no longer custB (a list of one stays shared)
network-manager bind srvWork --unbind --environment custA --own # ... the last one left owns it
network-manager bind iotCams --unbind # clears the link
A Service zone's own environment is one name; --add makes it a shared
service zone (the environment it was the own zone of then needs another), and a
plain bind on a shared zone is refused. --own turns a shared zone left with
one environment into that environment's own zone, unless it already has one.
The Management zone is never shared. bind refuses an unknown environment, a second Service zone for an
environment, and taking a Service zone away from the
environment it belongs to (move the environment with environment-manager modify
<env> --zone <zone>), and prints the edge the link derives. Like
enable/disable it does not reconcile; apply with network-manager reconcile
--apply.
Authored vs. effective — zones.json and zones.effective.json
zones.json is authored state: what the operator wrote. The edges an
environment link derives are never written back into it — if they were, the 3-way merge would treat
them as operator edits and pin them, so clearing a link would strand its edges.
Instead, every authored write (and the start of every reconcile) renders
zones.effective.json beside it, and that is what the consumers read:
zone-manager (the OPNsense plane), rules_manager (per-module pinhole/egress
validation) and the Caddy access lists. It is generated — never hand-edit it.
distribute still pushes the authored file, since the nodes need only
vlantag/ip.
An unresolvable environment link (an environment that does not exist, or one no
Service zone names) is non-fatal on a zone add (a missing environment file
must not block authoring) but fatal to reconcile and an error in
validate, which also refuses an environment named by no Service or Management
zone, or by two.
enable / disable / manual — atomic zone state change
The operator state verbs (was zone-state.sh): enable → Active,
disable → Inactive, manual → Manual. They mutate zones.json
atomically and deliberately do not touch the planes — apply when ready with
network-manager reconcile --apply. Guards: an unknown zone is refused (the
known zones are listed), a same-state verb is a no-op (exit 0), and leaving the
Mandatory state (e.g. dmz) is refused without --force. Mandatory and
Disabled are intentionally not exposed as verbs (Disabled is reserved for
the delete lifecycle).
network-manager enable srvTest
network-manager disable srvTest
network-manager disable dmz --force # Mandatory zones refused otherwise
reconcile — the 4-plane converge loop
network-manager reconcile # dry-run: report drift on every plane
network-manager reconcile --apply # converge every plane
network-manager reconcile --only switch # one plane only
network-manager reconcile --apply --only proxmox
--only <plane> is one of opnsense | proxmox | switch | ap. Default is a
non-mutating dry-run. Exit 0 = in sync, 2 = drift reported (dry-run, not a
failure), 1 = a hard error (a plane errored, or Proxmox still drifts after
--apply).
The opnsense plane's dry-run runs zone-manager in check mode with
--detailed-exitcode, which lists every firewall rule --apply would create,
renumber or delete — deletions by the orphan reaper included — and then the
pinhole validator (#645). Before this, a dry-run listed no rule at all, so a
deletion could not be reviewed before it happened.
init [<profile>] (alias zones-init) — composable install profiles
init applies an additive, idempotent profile bundle to zones.json
(ADR-014 D7). It replaces the old single flat transform that shipped ~23 zones
and then inactivated the ones it did not want.
| Profile | Zones |
|---|---|
core (default) |
mgmt · wan · netbird/edge/admin overlays · <N> (the renamed srv, Active) · home · guest · dmz (Mandatory) |
iot |
iotLocal · iotCloud · iotCams · iotUntrust — all Active, each bound to the default environment |
network-manager init core --name acme # the minimal coherent install
network-manager init iot --name acme # opt in to the IoT segment set
Properties, all unit-asserted:
- Additive — a profile only ever adds its zones, plus the
access-toentries its zones need on zones from another profile (init iotgives the service and client zones reach to the devices). It never removes or deactivates anything. - Idempotent — re-applying a profile is a byte-level no-op.
- Order-independent —
coretheniot==iotthencore. - Non-destructive — existing zones always win. A re-run can never
rebuild a live file from template defaults; operator zones, custom states and
edited access lists survive.
--forcere-stamps this profile's zones from the template. srv → <N>is the only rename, applied to keys, to every zone reference, and to theenvironmentplaceholder.home/guestkeep their names: the zone key drives the client DNS domain<zone>.internal.
A site with no smart-home devices simply never runs init iot and never carries
those zones. Extra service zones, a second client segment and so on come from
add --archetype or environment add --create-zone, not from dormant template
entries.
retire — remove zones a release stopped shipping
Deleting a zone from the template does not remove it from an existing
install: the 3-way merge keeps anything present locally but absent upstream
(which is right — it is what stops a release silently deleting an operator's
zone). retire is the explicit, guarded cleanup.
network-manager retire # dry-run: what would go, and what is kept
network-manager retire --apply # commit
It considers exactly srvHome, srvWork, srvCust, srvDev, srvTest,
iot, test, testAllowA, testAllowB, testPinhole — an explicit list,
never "everything Inactive". A zone is removed only when it is both
- not
Active/Mandatory/Manual(it provisions nothing today), and - not named by any installed module's
zone/zone0.
Anything else is kept and reported with the reason. References to a retired zone
are stripped from every other zone's access-to/pinhole-allowed-from.
srv (the rename source) and work (a legitimate client zone that is merely
switched off) are never retired.
validate (alias zones-check) — offline consistency audit
validate is the standardized verb (ADR-007); zones-check is kept as an
alias. Both run the same read-only zones.json audit.
network-manager validate # = zones-check
network-manager zones-check
network-manager validate --strict # warnings become errors
--zones <file>— zones.json to check (default$TAPPAAS_CONFIG/zones.json).--config-dir <dir>— installed module configs dir (default$TAPPAAS_CONFIG).--strict— promote warnings to errors.
Exit 0 ok, 1 on dangling references / missing required fields / lost zones.
validate --effective — audit the graph the planes actually receive
validate audits the authored zones.json by default. A client or IoT
zone's environment link contributes an edge that exists only in the rendered document, so an
authored-scope run cannot judge it — and says so in its output. Add
--effective to render the links and check the real graph:
network-manager validate # authored: authoring mistakes
network-manager validate --effective # rendered: what zone-manager receives
This matters for the tier checks: a client zone's edge to its service zone lives
only in the render, so --effective is where I1 can see it.
distribute (alias zones-distribute) — push zones.json to the Proxmox nodes
zones-distribute is kept as an alias.
network-manager distribute
network-manager distribute --dry-run # list target nodes, no copy
--zones <file>— zones.json to distribute (default$TAPPAAS_CONFIG/zones.json).--dry-run— list the nodes that would receive it; copy nothing.
topology — the physical site, derived (ADR-034 D5)
The document is read from the CMDB (ADR-040 D10, plan step 4;
where each field comes from): the
same buildTopology() as the live join, fed by sourcesFromCmdb() (src/topology-cmdb.ts), so the
health findings are those the last health-manager assess stored, and validate is not run. Two
things stay read: wan-address.json, this manager's own record, and asset-manager's faceplate
catalog. When the CMDB does not answer, or does not yet hold what the document needs, the live join
runs and stderr says why. sources names a store whose node or switch reports are over 30 minutes
old; cmdb-refresh runs the seven reports it needs (site, module, switch, ap, asset, network and
backup) every 5 minutes. A node that cannot be read keeps its last
network, where the live join shows no uplinks. The rest of this section is the join, either way.
network-manager topology # the WAN path, nodes, switch ports, LAGs, findings
network-manager topology --json # the document the console's Physical view draws
network-manager topology --json --health v.json # reuse a `health-manager validate --json`
network-manager topology --live # join the planes instead of reading the CMDB
network-manager topology --diff # build both, list what differs: exit 1 if anything does
One read-only document joined from what the other verbs already report: site.json,
site-manager node list and node network show (bonds, legs, LLDP peers, the wan port),
switch-manager list / list-ports / lag list (ports, VLANs, LAGs, drift), ap-manager
list, zones.json, module-manager module list (guests and their run state),
backup-manager peers and health-manager validate (findings). It stores nothing.
The join reconciles the sources' spellings: a switch compares by name without case or
punctuation (USW Pro XG 10 PoE is LLDP's USW-Pro-XG-10-PoE), an LLDP Port 11 is port
11, a NIC is matched by name or MAC with LLDP first, a device port whose target is a node
is that node's wan uplink, and a device port in the wan zone with no target is the ISP
hand-off. What does not reconcile — a node LLDP sees on a port the inventory does not give it, a
switch nobody registered — is a topology finding. Health findings are placed on the object
they name; a lan-uplink finding is also put on the node's LAG and switch ports. A source that
does not answer is listed under sources and its part is left empty.
On a site with more than one switch a node's legs read <switch>:<port>. An MLAG pair (from
switch-configuration-actual.json) is drawn under Switches with its peer link; its member
ports read peer-link, and a LAG across the pair is drawn once, under the pair (mlagPairs in
--json). A LAG is formed only when every member is enabled, has link and is aggregated;
otherwise it says how many members are active and why. A disabled port reads disabled. The
pair's live state is switch-manager mlag-pair list.
The positions come from asset-manager export (config/positions.json and the faceplate
catalog): positions in --json holds the site's locations (the primary first, each with its
place, its rooms and the devices at it placed nowhere), the rooms with their location, each
rack with its placements resolved to their devices and faceplates (live port state on every
plate port), the devices placed nowhere, and the cables — every link the switches and LLDP
see, mapped to faceplate ports, plus the ones asset-manager records (the ISP's modem, a
patch panel), each with the link speed seen where one is recorded — and assets, every asset
asset-manager records with its stage (operational derived from its role) and its ports by
connector and speed (ADR-040 D7, D9). devices lists the machines, the devices switch ports
name, the assets asset-manager records that play no node, switch or AP (by their role's name,
else their own; with asset and portSpecs), and the devices a switch port sees that no
record names.
Every device — node, switch, access point, device — carries location (a name of
site.json locations: a recorded device's own, a switch's or an access point's when its
location text names one, else the primary), placement ({room, rack, u}, or null) and
source: cluster, module, switch-configuration, recorded or seen. A seen device
comes from a switch port: each MAC its controller reports behind the port (neighbors in
switch-manager list-ports --json, with what LLDP and the lease say), or a port that is up with
nothing reported or recorded on it; a port of a node, an access point, a switch or the ISP, a
port a recorded cable lands on and a MAC on an asset's port or a node's NIC are accounted
for. It is named by its MAC (else <switch>:<port>), at the switch's location, placed nowhere,
and asset-manager asset record records it. A placement whose device is gone, and once the
site has a rack a device placed nowhere at a location that has a room, are topology findings.
--no-positions leaves them out (what asset-manager itself reads, to check device names).
wan ipv6-relearn — re-learn the WAN's IPv6 router
network-manager wan ipv6-relearn # = --check
network-manager wan ipv6-relearn --apply
For the day the ISP replaces its router: the firewall keeps routing IPv6 to the old one and
health-manager's ipv6-egress gate warns, naming this verb. --check sends one router
solicitation on the WAN and prints what the firewall records (the router, the default route
and whether its router answers, the WAN_DHCP6 gateway, the delegated prefix, whether rtsold
runs), the router answering now, and what --apply would do. --apply, through the opnsense
controller (ipv6-manager relearn), in this order:
- records the router that answers, as rtsold's own script does (
ifctl -6rd); - re-runs the firewall's IPv6 WAN event (
configctl interface newipv6 <wan> force): the default route and theWAN_DHCP6gateway move to it, the filter is reloaded; - starts rtsold only if it is not running;
- runs the network module's IPv6 converge (
ipv6-manager apply), so the zones follow a changed prefix.
Why not configctl interface reconfigure wan, which re-learns the router too, or a restart of
rtsold: both make rtsold's script reload dhcp6c, which releases the DHCPv6 lease and solicits
a new one, and a new lease can bring a new delegated prefix: every zone renumbers and devices
keep the old addresses for an hour. The IPv6 WAN event alone changes only the route
and the gateway, and the lease stays. The network module's DESIGN.md (The WAN's IPv6 router)
has the reasoning from OPNsense's scripts.
wgvpn — the admin VPN (ADR-010 §6, §8.4.6)
The operator's WireGuard session into the management plane. It terminates on
OPNsense and lands in the admin overlay zone (10.255.1.0/24), which one
least-privilege rule lets reach mgmt. No satellite is needed: a Site with a
public IP is reached directly, a CGNAT Site through a satellite carrying the
admin-vpn role, which only relays the UDP.
network-manager wgvpn setup # idempotent; the cicd install runs it
network-manager wgvpn add-peer --name laptop --pubkey <key> # prints the device's client config
network-manager wgvpn list
network-manager wgvpn remove-peer laptop
network-manager wgvpn config laptop [<host:51821>] # print a config again (v2: DNS + published names)
add-peer's endpoint is --endpoint if given, else the address of a registered
satellite with the admin-vpn role, else a placeholder. The tool is bash
(wgvpn/wgvpn.sh, linked as network-manager-wgvpn); it was satellite-manager
admin. Runbook for Mac and Linux devices: ADMIN-VPN.md.
Reports to the CMDB
ADR-040 D4: network-manager report sends what the network is to the CMDB
(cmdb-controller) as one observation; --json prints it instead.
| Class | From | Attributes | Relations |
|---|---|---|---|
zone |
zones.json |
vlan, subnet, ipv6Subnet (the zone's /64 number), tier, dhcp {start, end} (an Active or Mandatory zone, .50–.250 unless DHCP-start/-end say), desired |
serves each environment it names |
address |
dns-manager leases --json, dns-manager list --json |
ip, family, reservation (the reserved MAC), leaseUntil | member-of the zone its IP is in |
dns-name |
host entries (internal), Caddy domains (public) | fqdn, target, public | |
proxy-route |
caddy-manager list --json |
host, path, target, gate (forward auth), allowedZones (the zones its access list allows) | serves <module>:<service> for each service the module's JSON provides |
vpn-peer |
network-manager wgvpn peers |
publicKey, endpoint, allowedIps |
A source that does not answer is named on stderr and its part left out. A reference the CMDB cannot resolve (an environment or service nobody has reported yet) is dropped from the batch and the rest sent.
A report writes only what it sees and the CMDB's expiry never ends a CI, so the
report also ends the live dns-name and address objects its sources no longer
show (--json prints those with end: true). Only this report writes the two
classes. A source that did not answer ends nothing of its kind: an internal name
needs the host entries, a public name the Caddy read, an address with a
reservation the host entries, one with only a leaseUntil the leases, and one
with both or neither (a host entry without a MAC is the usual case) both reads.
A name with no public, an object with no ip and an operator's recorded object
are not ended. A CMDB that cannot be read ends nothing, says so on stderr, and the
report goes out as before; TAPPAAS_CMDB=off does not read it.
Changes: add, delete, enable/disable/manual, bind, modify,
set-ssid, merge, retire --apply, reconcile --apply and wgvpn
add-peer/remove-peer report the zones (or peer) they touched as a change,
with the console's job id (TAPPAAS_JOB_ID) and the actor; a deleted zone or
removed peer is ended. reconcile without --apply reports the zones as an
observation. Nothing is polled for the CMDB; a report the CMDB cannot take is
spooled under config/.cmdb-spool/ and never fails the verb. TAPPAAS_CMDB=off
sends nothing.
report --discover (ADR-040 D15) adds a second report from one read-only pass
of opnsense-firewall discover: on the network module's CI (vm) the OPNsense
version and firewall: {rules, aliases, nat, routes, certificates, packages,
dhcpRanges, dhcpHosts, interfaces, vlans} — rules and aliases by UUID, each rule
with its position in evaluation order (by sequence) and that sequence;
interfaces and vlans here are the ones no zone declares. Each list is sorted by
uuid (else name), and a NAT entry carries no place in the model, so an unchanged
firewall gives the same firewall on every pass; a pass that misses one of its
sections leaves firewall out, and the CMDB keeps the last full one.
A zone gets its interface and live dhcp range; DNS overrides are dns-names;
every WireGuard peer gets lastHandshake. A section the firewall does not answer
is named on stderr. --json prints an array. Until the metamodel has its fields (vm.firewall`, `zone.interface`, `vpn-peer.lastHandshake), cmdb-controller refuses these attributes; the plain report is sent on its own and stands.
Legacy bash tools
Only zone-reconcile is still linked onto PATH during the transition (plus
network-manager-wgvpn, which network-manager wgvpn runs).
migrate-zone-keys-*.sh is a one-shot migration helper, not an on-PATH tool.
Retired (ADR-007 Phase 7.5 / post-implementation refactor):
apply-zones-merge.sh → network-manager merge (alias zones-merge, ADR-007
"Design A"); zone-controller.sh → network-manager add/delete (the native
zone lifecycle); zone-state.sh → network-manager enable/disable/manual.