Data plane¶
The data plane is what actually carries — and refuses — client traffic.
The path¶
Client
| WireGuard tunnel
v
Gateway node: the Deployment's runtime domain
| forward path: nftables, default drop
v
Permitted resource (or: dropped)
A client's WireGuard tunnel terminates at a Gateway. Each forwarded packet is evaluated against the policy the Gateway has applied for that Deployment. If a rule authorises the flow it is forwarded; if no rule does, it is dropped. Denial is the absence of an authorising rule, so a mistake fails closed rather than open.
Runtime domains¶
A physical Gateway node may serve several Deployments, and each
(Gateway node, Deployment) pair is an isolated runtime domain with its own
WireGuard interface, routes, firewall table, NAT and conntrack. Two Deployments
on one node therefore cannot see each other's traffic, and they may reuse the
same addresses without colliding.
The WireGuard interface a domain uses is named in its desired state; the
long-standing default is ac-wg0, and cross-Gateway fabric traffic uses a
separate interface (ac-fab0).
Enforcement: a single owned nftables table¶
JANUS owns exactly one nftables table and nothing else on the host:
| Ownership state | Condition | JANUS behaviour |
|---|---|---|
| absent | the table does not exist | it may create it |
| owned | the table exists with the correct marker | it may reconcile rules |
| conflict | the table exists without the marker, or the marker is unreadable | no mutation at all — fails closed |
A conflict is never "resolved" by deleting or overwriting the existing table.
Chains and the fail-closed policy¶
| Chain | Hook | Policy | Purpose |
|---|---|---|---|
ac_forward |
forward | drop | forwarded client traffic — the authorization decision |
ac_input |
input | accept | client → gateway traffic, fail-closed within the WireGuard path |
ac_s2s |
regular | — | site-to-site peer ingress, ends in the terminal drop |
ac_established |
regular | — | accepts established,related, reached without an interface restriction |
ac_default |
regular | — | terminal drop |
Two details are deliberate and load-bearing:
ac_forwardcarriespolicy drop. Forwarded traffic that matches no rule is dropped by the chain's own policy, not by a missing rule.- Return traffic is accepted ungated. Conntrack only marks a flow established after its first packet was accepted by an authorization rule, so accepting established/related traffic on any interface enables the return path without widening authorization.
Scope of enforcement¶
JANUS enforces policy for JANUS-managed traffic only. Packets that did not arrive on a JANUS-managed interface never match its rules and are left to the host's own firewall. JANUS does not take over host firewalling, and its base chains sit at a priority that keeps it below distribution-level connection tracking and above typical container and admin rules.
Rule identity¶
Every rendered rule carries a bounded, deterministic comment:
This makes an individual authorization traceable from the kernel rule back to the object that produced it, without putting user-controlled text — or any secret — into nftables syntax.
Atomic application and verification¶
All JANUS-owned rules are prepared, preflighted (nft -c) and applied as one
atomic transaction (nft -f). A failed transaction leaves the previous kernel
state untouched, so there is no window in which the old rules are gone and the
new ones are not yet installed. After the apply, the rules are read back and
compared with the desired state — command success alone is not treated as
verification.
Both address families are first-class: a rule is rendered for its own family, and a rule is never emitted as a cross-family match.
NAT¶
NAT lives in the same owned table, in one postrouting chain (ac_nat_post). It
is always present; with no NAT policy it performs no translation. That is how
"no NAT" is expressed — an empty owned chain, never an implicit masquerade.
| Mode | Rendered effect |
|---|---|
none |
return — NAT evaluation stops, the packet leaves unmodified |
masquerade |
the kernel picks the source address from the outgoing interface/route |
snat |
translate to the configured address |
The compiled entries arrive in most-specific-first order and are rendered verbatim, because nftables evaluates rules in sequence and has no longest-prefix match. A more specific prefix therefore always wins over a broader one.
none is rendered as an explicit return, not as "emit nothing": without it, a
broader masquerade further down the chain would still match and translate the
traffic.
NAT is translation, not authorization. NAT rules live in the postrouting chain and only translate packets the forward path has already accepted. A destination that no AccessPolicy allows stays denied regardless of a matching NATPolicy.
masquerade and snat are IPv4 only. IPv6 is never translated — there is
no NAT66 — and a policy attempting it is rejected at validation. none is valid
for IPv6.
See Internet egress for where NAT is placed for Internet traffic, and the configuration reference for the object itself.
Cross-Gateway fabric¶
When one Deployment spans several Gateway nodes, traffic between them is carried over a Deployment-scoped fabric. The fabric is prefix-keyed and carries concrete reachability only, and — importantly — it is not implicitly trusted: fabric traffic is subject to the same authorization as any other flow. Internet-bound traffic never traverses the fabric.
Applied-state verification¶
A Gateway does not report itself ready merely because it received state. After
an apply it records the applied artifact, including a content hash, and its
readiness endpoint compares the applied artifact's firewall and NAT identity
comments against the kernel. A mismatch is reported as
firewall_state_mismatch with /api/v1/readyz returning 503, and the Gateway
reports that the kernel does not reflect the intended state.
This is what makes a restart that lost the nftables table visible instead of silent: re-applying the same compiled state restores the kernel without changing the compiled identity.
Fail-closed summary¶
| Situation | Result |
|---|---|
| No authorising rule for a forwarded flow | dropped by the chain policy |
| Authorization rule removed | the next applied state no longer permits the flow |
| Rule set cannot be applied atomically | the previous kernel state is left intact |
| The nftables table is not JANUS-owned | zero mutation |
| The kernel does not match the applied artifact | readiness fails; the Gateway does not claim to be applied |
| NAT policy matches but no access policy does | still dropped |
| A destination becomes internal while an Internet grant exists | new connections denied — the whole rule set is rebuilt in one transaction |
Related¶
- Gateway agent — how state becomes kernel state
- Internet egress
- Site Edge
- Security model
- Operations