network:proxy service¶

Publishes a module through Caddy — the module's public face. It owns the hostname, the certificate, the upstream handler and the firewall alias that decides who may reach it. Nothing here touches a guest; the changes land on the proxy and the firewall, and the workload never notices.

10 fields — all in-place, all apply: "reconcile".

The module's public face. Nothing here touches a guest: the changes land on Caddy and the firewall, and the workload never notices. The largest drift blind spot — see recommendation 1.

Why reconcile and not set¶

update-service.sh rewrites this module's whole Caddy site block and its OPNsense alias from the declared values on every pass, then reloads. That is already idempotent and already handles removal — a handler that should no longer exist is deleted, which no scalar field diff can express. Flattening it into set fields would lose that. The manifest declares the class, which is what makes --set sanctioned; the apply stays where the domain knowledge is.

Because there is no report-service.sh, module-manager module drift reports these fields as not-reported rather than comparing them — the converge is trusted to have made config true. That is the blind spot recommendation 1 closes.

Fields¶

network:proxy owns 9 declared field(s). Each table below carries the field's full definition and, where the service applies it, its ADR-020 change semantics.

proxyDomain¶

Public domain name for the reverse proxy. Caddy obtains a TLS certificate for this domain.

About the field. If not set, defaults to . from configuration.json

Why this change class. The public hostname. Changing it re-issues the ACME certificate and moves the handler; the module itself is untouched, so no guest downtime — though clients on the old name stop resolving as soon as DNS follows.

proxyPort¶

Target port on the module VM that the reverse proxy forwards traffic to

About the field. The port the service listens on inside the VM

Why this change class. The upstream port Caddy forwards to. A handler rewrite, applied live.

proxyUpstreamTls¶

Reverse-proxy to an HTTPS upstream instead of plain HTTP. Set true for backends that only speak TLS — e.g. the OPNsense GUI on :8443. network:proxy renders the Caddy upstream as https:// with upstream certificate verification skipped (internal/self-signed backends).

Why this change class. Whether the hop from Caddy to the module is itself TLS. Declared as a string in module-fields.json, so the boolean normalizer is what makes 'true' and true one value.

proxyUpstreamHttp1¶

Force HTTP/1.1 to the upstream (os-caddy HttpVersion=http1). Required for apps whose UI rides a WebSocket behind a TLS upstream — e.g. the UniFi OS console. Without it, Caddy negotiates HTTP/2 with the upstream, which cannot carry a WebSocket Upgrade and returns 500, so the SPA renders blank.

Why this change class. Force HTTP/1.1 upstream, for a backend that cannot speak h2c.

proxyPreserveHost¶

Force the upstream Host header to the public domain (Caddy header_up Host ). Needed for apps that validate a WebSocket's Origin against the Host header — e.g. the UniFi OS console: Caddy otherwise sends the upstream's own hostname, so the browser's Origin (the public domain) ≠ Host and the WebSocket upgrade returns 500, leaving the SPA blank after login. Usually paired with proxyUpstreamHttp1 for WebSocket apps behind a TLS upstream.

Why this change class. Pass the original Host header through, for a backend that generates absolute URLs from it.

proxyTls¶

How network:proxy obtains the public TLS certificate for this domain. OMIT IT to inherit the environment's domains.dnsMode (config/environments/.json) — that is the normal case and the only way one setting governs a whole environment. Set it only to override that environment-wide choice for this one module. 'dns01' binds the TAPPaaS-wide wildcard certificate issued by os-acme-client (acme-setup.sh) via Caddy's per-domain CustomCertificate, and requires a DNS provider that supports DNS-01 plus the wildcard already being in OPNsense Trust; until it is, the public HTTPS endpoint has no cert while the LAN endpoint still works. 'http01' uses classic ACME HTTP-01: Caddy obtains a per-domain cert via the :80 challenge, so the domain MUST be reachable from the internet on port 80, and no DNS API is needed.

Why this change class. Which certificate strategy serves the domain (per-service or the environment wildcard).

proxyAllowedZones¶

Zones (and the literal 'internet') permitted to reach this service through the reverse proxy — or 'none' (no one, except through proxyAccess path rules), or networks named directly, as a.b.c.d/n or x:y::/n: a provider's published caller range, for an endpoint one cloud service must reach without opening it to the whole internet. A malformed network is refused, like an unknown zone. network:proxy compiles this into an os-caddy access list (allow-list by client subnet) attached to the handler; non-matching clients get HTTP 403. On a site with IPv6, each zone's IPv6 network is allowed next to its IPv4 one. Under ADR-021 D2 this is the ONLY place a zone restricts a published service: split-horizon DNS returns the same address (the DMZ gateway) to every caller, so the answer encodes no entitlement and the access list is what narrows it.

About the field. Zero-trust by default: when omitted, a service is reachable only from the internal trusted zones, never the internet. Add 'internet' to publish it publicly (no restriction). Zone names are resolved to subnets via zones.json. Changing this re-applies on the next install/update of the module. TWO values carry real consequence and the rest is belt-and-braces: leaving it UNSET is the normal, correct configuration for a published service, and adding 'internet' is what makes it publicly reachable. Narrowing to a specific list of internal zones filters IN FRONT OF the identity gate, it is not the mechanism protecting the service (ADR-021 Case ⅓) — a zone list that lets someone through still leaves them at an Authentik login, and one that shuts them out only saves them the round trip. Do not use it to separate two populations who are each entitled to a different environment: that binds entitlement to network position, which breaks the moment a legitimate user connects from another zone (the same person on a laptop in home, a phone on guest wifi and the netbird overlay is ONE identity in three zones). Authentik group membership is where that belongs.

Why this change class. Which zones may reach the published name — the difference between an internal service and one exposed to the internet. A live firewall/Caddy change, and the field most worth being able to set through a verb rather than by hand.

proxyAccess¶

Path exceptions to the route's proxyAllowedZones: a list of rules {paths, zones, identityGate}. A request whose path matches a rule gets that rule's zones; every other path keeps the route's. paths are Caddy path matchers starting with / (a trailing * is a prefix match); zones takes the same values as proxyAllowedZones. identityGate false serves the rule's paths without the Authentik gate, for callers that cannot hold a credential at all — a webhook signed in its payload — and then needs a description saying who calls and why (a machine caller that can send a credential uses a service account through the gate instead, ADR-032 D1). Default: as the route. On a gated route Caddy removes the caller's Authorization header before the app. Allowed on the module (primary route) and on each proxyRoutes entry. With proxyAllowedZones ['none'] a route serves only its rules' paths.

About the field. Reachable is not authorized: a public path is protected only by the application (a secret ID in the URL, a signed request). The longest matching path wins. A path of / or /* is refused (set proxyAllowedZones instead), as is the same path in two rules.

Why this change class. Reconciled with the route: one Caddy handle per path, before the catch-all, each with its rule's access list; handles and lists no longer declared are pruned.

proxyRoutes¶

Additional reverse-proxy routes for a VM that serves several endpoints on different ports. Each entry publishes . — where is the environment's primary domain, the same suffix proxyDomain defaults to — forwarding to the module's upstream host on the entry's port. The primary proxyDomain/proxyPort route is unaffected. An entry may set its own proxyAllowedZones (zones, 'internet' or networks) and then gets its own access list; without it the route inherits the primary's. They always inherit the primary route's TLS strategy (proxyTls/dnsMode) and upstream flags (proxyUpstreamTls, proxyUpstreamHttp1, proxyPreserveHost).

About the field. Each entry is { name: , port: <1-65535> }; the FQDN is .. Each route gets its own Caddy handler keyed by 'TAPPaaS: #'. Adding an entry publishes it on the next install/update; removing one tears its route down.

Why this change class. The extra hostnames a single VM publishes. Adding or removing an entry creates or prunes that route live; the primary route and the module itself are untouched.