Zone Definitions in TAPPaaS¶

Introduction¶

zones.json defines the security zones of a TAPPaaS installation. Each top-level key is a zone with its network configuration, access policy, and DHCP settings. Keys beginning with _ (e.g. _README) are documentation blocks and are ignored by every consumer.

network-manager owns the entire zones lifecycle. It is the single front door for the network: it does CRUD on zones.json (the desired network state), transforms the distributed template at install, reconciles release drift on every update, audits consistency, distributes the file to the Proxmox nodes, and reconciles the four infrastructure planes (OPNsense, Proxmox, switch, access points) so a zone's VLAN actually reaches the firewall, the hosts, the physical switch, and the WiFi. There is no separate zone-controller — the desired-state authority lives inside network-manager.

Modules connect to zones via their module.json (zone0, ingress/egress). The zones.json template ships under this directory; the live, per-installation copy lives at ${TAPPAAS_CONFIG:-/home/tappaas/config}/zones.json.

The legacy variant-manager and apply-zones-merge.sh are retired. Variants were replaced by ADR-007 environments (config/environments/<env>.json); the bash merge was ported into network-manager merge (see below). The full design is in the appendix "Zones lifecycle…" sections A–D of docs/design/ADR-007-implementation.md.

The zone object¶

Auto-allocated VLANs use the 60–99 window within each type band. Zone keys match ^[a-z][a-z0-9-]*$ (camelCase template zones like srvHome/iotCams; renamed per-installation zones use hyphens, e.g. myOrg-private).

Zone types¶

Zone state¶

Access Model: Tiers and the Isolation Invariant¶

Two independent mechanisms control reachability between zones:

Zones are organised into trust tiers:

Isolation invariant. Tier-4 zones (iotCams, iotUntrust) have "access-to": [] and must never appear in any zone's access-to. Access into them is granted only by per-module pinhole declaration. Adding an isolation zone to a non-mgmt access-to would nullify the pinhole mechanism — every host in the source subnet would gain unconditional zone-wide reach. iotCams in particular must stay purpose-limited (GDPR Art. 25). The sole exception is mgmt (Tier-0 control plane), which reaches all zones for operational visibility.

Access matrix (✅ access-to · 🔓 pinhole-only · ❌ deny):

The canonical, machine-adjacent version of this model — including the PR review checklist, mDNS policy, and IoT classification decision aid — lives in the _README block at the top of zones.json. Keys beginning with _ are documentation and are ignored by all consumers.

network-manager commands (the zones lifecycle)¶

One compiled CLI, network-manager, owns every flow that touches zones.json:

environment-manager calls network-manager when an environment needs a zone created or checked; domain/cert lifecycle stays with environment-manager.

The per-installation rename and the three-file model¶

The distributed template encodes the generic, org-agnostic zones (srv, home, guest, the per-category srvHome/srvWork/… etc.). A fresh install runs network-manager init --name <N> once to stamp the zones for the installation named <N>:

• rename srv → <N> (forced Active — the default service zone), home → <N>-private, guest → <N>-guest;
• state → Inactive on the per-category zones it supersedes (srvHome, srvWork, srvCust, srvDev, work), except any zone still referenced by a deployed module's zone0 (the occupancy guard, so a live service is never silently de-provisioned);
• rewrite every zone-name reference (access-to, pinhole-allowed-from, …) through the rename map.

So a brand-new myOrg system has an Active footprint of myOrg, myOrg-private, myOrg-guest, iotLocal, iotCloud, iotCams (+ dmz Mandatory; mgmt/netbird Manual); everything else is Inactive/Disabled — defined, ready to activate.

Zone stability — installed modules stay put¶

A zone kept Active by the occupancy guard (a legacy zone such as srvWork still hosting deployed modules) is the intended steady state, not a migration TODO. Already-installed modules stay in their zone; the network lifecycle never moves a running service to another zone and never auto-inactivates a zone that has live services. To relocate a module to a different zone, back up its data, uninstall it, and reinstall it in the target zone — there is no in-place re-home (a zone change means a new VLAN/subnet/IP and re-wired dependents).

Three files, run on every update (rename-aware 3-way merge)¶

Keeping the rename robust across releases uses three files in ${CONFIG_DIR}, all in the installation's renamed namespace:

• zones.json — current: the live, per-installation zones.
• zones.json.orig — baseline: the version of the source the current was last merged from.
• zones.rename.json — source: the upstream repo template with this installation's rename applied (regenerated on demand from site.json .name; never hand-edited).

network-manager merge runs on every update-tappaas:

1. read the current repo template → apply the same rename algorithm → (re)write zones.rename.json (re-basing upstream changes into the renamed namespace);
2. 3-way merge current vs baseline vs source — per field: state is operator-pinned, never adopted; every other field adopts the source when current == orig, else the local edit wins. Zone-level: source-only → ADD; current-only → keep + warn; same vlantag / different name → flag a possible rename (do not auto-rename);
3. write merged → zones.json and advance zones.json.orig ← zones.rename.json.

Because srv/home/guest never appear in zones.rename.json (they are renamed away), the "source-only → ADD" rule can never re-create them — which is what closes the recurring duplicate-VLAN corruption the old apply-zones-merge.sh had.

Example Configuration¶

{
    "mgmt": {
        "type": "Management",
        "state": "Manual",
        "typeId": "0",
        "subId": "0",
        "vlantag": 0,
        "ip": "10.0.0.0/24",
        "bridge": "lan",
        "access-to": ["internet", "srvHome", "srvWork", "home", "dmz"],
        "pinhole-allowed-from": [],
        "description": "Control plane: hypervisors, backup, firewall, identity, cicd"
    },
    "srvHome": {
        "type": "Service",
        "state": "Active",
        "typeId": "2",
        "subId": "10",
        "vlantag": 210,
        "ip": "10.2.10.0/24",
        "bridge": "lan",
        "access-to": ["internet", "iotCloud", "iotLocal"],
        "pinhole-allowed-from": [],
        "description": "Personal services: home automation, personal apps"
    },
    "iotCams": {
        "type": "IoT",
        "state": "Active",
        "typeId": "4",
        "subId": "30",
        "vlantag": 430,
        "ip": "10.4.30.0/24",
        "bridge": "lan",
        "access-to": [],
        "pinhole-allowed-from": ["srvHome", "srvWork"],
        "description": "Surveillance: cameras + NVR, fully isolated"
    }
}

Note iotCams.access-to is []: an NVR in srvHome/srvWork reaches the cameras only through an explicit per-module pinhole, never via access-to.

Computed Values¶

• vlantag: typeId * 100 + subId (e.g. typeId=2, subId=10 → 210)
• ip: 10.<typeId>.<subId>.0/24 (e.g. typeId=2, subId=10 → 10.2.10.0/24)

WiFi: the SSID field¶

A zone may declare an optional SSID field — the WiFi network name broadcast on that zone's VLAN. It is consumed by the ADR-008 WiFi tooling (see network/scripts/README.md):

• setup-wlan-secrets.sh walks the active zones that declare an SSID, lets you set the real name (replacing the shipped <PLACEHOLDER>), and stores the WPA passphrase in a 0600 secrets file (never in zones.json).
• ap-manager maps each SSID to its zone's VLAN on the WiFi controller.

The passphrase and per-SSID security level are not stored here — only the SSID name and (via vlantag) its VLAN.

Field Reference¶

For complete field definitions including all possible values, defaults, and validation rules, see schemas/zones-fields.json: all available fields and their types, valid values for enumerated fields (including the state enum), defaults, computed-field formulas, and the special access-control values.

Per-Module Firewall Rules¶

Zone-level rules govern coarse access between zones. Per-module rules (network:rules capability) declare each module's ingress/egress contract in its own JSON and are validated against the zone-level policy:

• Every ingress.from zone must be in the destination zone's pinhole-allowed-from.
• Egress to a zone not in the source zone's access-to is permitted but warned.

A peer that is another module's name is resolved via an OPNsense host alias populated with the peer's FQDN (<vmname>.<zone0>.internal), kept fresh by OPNsense Unbound against dnsmasq — DHCP IP changes do not require rule rewrites.

See network/README.md for the full schema, sequence bands, and CLI reference.