Skip to content

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:

table inet access_concentrator        comment "access-concentrator managed schema=v1"
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_forward carries policy 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:

ac:v1:<policy-name>:<content-hash>

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