Skip to content

Internet egress

JANUS Internet egress lets selected subjects reach the Internet through JANUS while still denying them access to internal JANUS and customer resources.

The one sentence to remember

The provider Gateway owns the Internet uplink. The Site Edge routes. The provider authorizes.

What an Internet grant means

An AccessPolicy whose destination is internet means:

The selected subject may initiate traffic to destinations classified as INTERNET, subject to the policy's services and every other applicable JANUS restriction.

It does not mean allow 0.0.0.0/0 or allow ::/0. It compiles against the deployment's INTERNET set, so it can never authorize an internal destination.

Destination classification

Classification is deployment-scoped and derived at compile time:

INTERNET(family) = ALL(family) - INTERNAL(family) - SPECIAL(family)

SPECIAL — a versioned, in-tree definition (janus-special-v1) covering unspecified, loopback, link-local, multicast, protocol reservations, documentation/example, benchmarking, broadcast, the IPv6 special-use equivalents, and private-use / non-globally-routable space (RFC 1918, CGNAT 100.64.0.0/10, ULA fc00::/7).

Why private space is SPECIAL and not Internet: those ranges are not globally routable, and "an Internet grant must never authorize internal space" is a hard invariant. Private space is therefore never Internet merely because it is not public. If you want a private range reachable, authorize it explicitly as a Resource, or declare it internal. Classification never depends on a live external bogon or unallocated-space feed, so it does not change under you.

INTERNAL — every destination the deployment already knows as internal:

  • Resource addresses and prefixes,
  • Site advertised and tunnel prefixes,
  • Prefix objects,
  • Site Edge declared LAN prefixes,
  • enabled Device overlay addresses,
  • the explicit overrides below.

Public addressing does not imply Internet: a globally routable prefix JANUS knows as internal is still excluded.

INTERNET — the remainder, per address family.

A default route is never a classification input. A declared /0 is representable and reported, but it is ignored here — otherwise it would classify the whole address space as internal.

Explicit internal-prefix overrides

apiVersion: janusaccess.net/v1alpha1
kind: Deployment
metadata:
  name: northwind-prod
spec:
  network:
    internalPrefixes:
      - 10.100.0.0/16
      - 172.20.50.0/24
      - 2001:db8:1234::/48

Deployment-scoped. These are classification overrides only — never routes, never authorizations. A default route is rejected.

Subjects

Exactly one subject per policy:

Subject Field Meaning
User spec.subject.user the user's devices
Group spec.subject.group the member users' devices
Device spec.subject.device exactly that Device — it does not grant the owner's other devices
Prefix spec.subject.prefix an existing deployment-scoped Prefix used as an authoritative source network

A raw CIDR is never a subject. A Prefix subject must resolve to an existing Prefix of the same deployment, must not be a default route or a SPECIAL range, and must have a valid ownership/routing relationship: either it declares a site that exists and actually covers the prefix (advertised or tunnel prefixes), or the prefix must be JANUS-known space (declared by an enabled Resource, a Site advertised prefix, or a Site Edge).

Deployment isolation is preserved: an overlapping CIDR in another deployment is a different object in a different scope.

A Device subject resolves to the device's canonical JANUS tunnel addresses from trusted desired state. A client-supplied address is never accepted as the meaning of a policy.

Services

The service model applies unchanged. An Internet policy is not automatically all protocols and ports: a policy with no services grants nothing, and DNS is reachable only if the services allow it.

How the layers compose

valid source identity
AND AccessPolicy(destination = internet)
AND destination classified INTERNET
AND Site Edge direction admission   (when the flow traverses a Site Edge)
AND route / egress path exists
AND service / port constraint
AND IPv4 NAT requirements where applicable

Every layer may narrow; no layer may widen another.

  • Site Edge roles. A source behind a Site Edge reaches the Internet as a customer → JANUS NEW connection, so the edge must permit ingress. An egress-only edge denies that NEW flow even when the subject has an Internet AccessPolicy.
  • Remote-access subject. A User/Group/Device attached directly to the provider Gateway reaches the Internet at that Gateway and never traverses a Site Edge merely to do so.
  • Orthogonality. destination: internet grants no internal access. A separate normal AccessPolicy may authorize a specific internal Resource; the two are independent.

Where egress happens

The deployment-scoped provider Gateway owns Internet egress: traffic is intentionally carried through JANUS to that Gateway and exits through its external uplink. There is no separate InternetGateway object kind.

Because authorization is compiled at every enabled Gateway the subject may attach to (the device eligibility primitive), a client failover does not silently lose egress. Internet-bound traffic never traverses the inter-Gateway fabric — the fabric is prefix-keyed and carries concrete reachability only.

An Internet connection where traffic exits locally without traversing JANUS is not JANUS Internet egress.

How a customer prefix behind a Site Edge is carried

A prefix behind a Site Edge is carried into JANUS for exactly the address families in which an enabled Internet AccessPolicy names that prefix as its subject. Nothing is carried otherwise.

The carriage set is the deployment INTERNET class expressed as prefixes (the exact complement of SPECIAL + INTERNAL — never a literal default route), because a routed consumer installs routes and a WireGuard peer allowedIPs.

On the edge the carriage is installed as:

  • routes toward the provider attachment interface, in a dedicated policy-routing table (51820) — never the main routing table; and
  • one policy rule iif <customer interface> lookup 51820 at a fixed priority.

Only traffic that arrived on the customer interface consults that table, so the Site Edge appliance's own management and control-plane traffic (Controller communication, enrolment, updates, NTP, platform DNS, health and observability) is never redirected into the customer data path. A destination the carriage does not cover falls through to the ordinary main-table lookup, so the customer's own LAN and JANUS internal prefixes keep resolving as before.

The provider peer's allowedIPs gain the carriage set, so WireGuard genuinely carries it in both directions. Carriage is reachability, never authorization: the provider Gateway still decides, and a carried destination the provider does not authorize is dropped there. A plan that carries Internet destinations without a customer interface fails closed, and the table id and rule priority are canonical constants the privileged side pins independently.

IPv4 NAT

apiVersion: janusaccess.net/v1alpha1
kind: NATPolicy
metadata:
  name: guest-internet-nat
spec:
  site: branch
  mode: masquerade          # or snat
  source:
    prefixes: [10.240.0.0/16]
  destination:
    internet: {}            # not a literal 0.0.0.0/0
  • NAT is applied at the provider Gateway's external egress path, not at the Site Edge customer-side path. Traffic toward an INTERNAL destination that happens to be separately authorized is not Internet-NATed.
  • Modes: masquerade, snat, and none as an explicit no-NAT escape.
  • NAT does not create authorization. NAT is applied only after traffic has been admitted.
  • An snat address must be a public IPv4 address the deployment owns (inside an enabled Gateway's allowed public address space). An unowned address is rejected.
  • Internet NAT is the least-specific NAT entry, so it can never pre-empt an explicit, more specific rule. Site Edge NAT semantics are untouched (most-specific-first, no NAT66, NAT ≠ authorization) and the two placements are distinct.

How an explicit Internet SNAT is placed

An explicit Internet SNAT is a two-stage, deployment-qualified translation, because the configured public address is a provider-owned (host-local) address and the deployment runtime domain is a separate network namespace:

subject -> deployment runtime domain            stage 1 (inside the domain)
        -> provider uplink egress boundary      stage 2 (the FINAL public SNAT)
        -> external provider interface -> Internet
  • Stage 1 (inside the deployment runtime domain). The packet's source is rewritten to a domain-owned transit identity derived from the domain fingerprint. Transit identities live in the domain's separate, explicitly routed transit prefix (100.96.0.0/11, one /27 per domain) — not in the provider /31 link, which stays exactly the two link endpoints and is never widened for this purpose. The prefix is routed to the deployment namespace through that link, and the namespace owns each used transit identity locally, so the provider can route the return back into the owning domain.
  • Stage 2 (provider uplink). The provider host translates that transit address to the configured public address, matched by the domain's uplink veth identity and the transit address. The veth identity is what qualifies the translation per deployment: two deployments that reuse the same internal source space can never merge, and one deployment can hold several distinct Internet SNAT addresses without ambiguity.
  • Scale, determinism, fail-closed. The transit prefix holds 32 addresses and an explicitly routed prefix has no network/broadcast semantics, so all 32 are usable. A deployment with more distinct public SNAT addresses than that fails closed rather than silently dropping a translation. The address→transit assignment is derived from the sorted, de-duplicated intent set, so it is stable across restart and re-apply. The provider refuses to share a transit prefix between two deployments (it would route one deployment's return traffic into another's namespace) and refuses to share an uplink address; both collisions fail closed.
  • Return path. Both stages create ordinary conntrack mappings, so the reply is un-translated at the provider uplink and again inside the domain, exactly as the working masquerade path behaves. Translating directly to the host-local address inside the domain would instead be martian-dropped on the way out and its return consumed by the host's local stack.
  • masquerade is unchanged: the domain rewrites to its uplink address and the provider uplink masquerades it.
  • Neither the /31 nor the transit prefix ever appears on an external interface as a final WAN source, and neither is classified as INTERNET destination space.
  • The compiled NAT rule records its placement as provider-uplink for an Internet snat rule, so the artifact never claims a deployment-domain rule for a translation that happens at the uplink.

The intent is persisted per domain under /run/access-concentrator/uplink-nat/<fingerprint>.json, beside the namespace handles, so a reboot loses the intent and the namespaces together and a re-apply restores both. The packaged gateway ships that parent directory (root:janus-gateway 0770, via its tmpfiles.d entry and its postinst) because the data-plane service runs unprivileged and cannot create a directory directly in /run; the service creates the leaf itself. A missing or unwritable parent is a real deployment error and fails closed — the apply rolls back rather than silently dropping the domain's provider-uplink translation.

IPv6

No NAT66. Internet egress over IPv6 is routed and filtered/authorized normally. If a deployment has no usable routed public IPv6, IPv6 Internet egress is simply unavailable for it — no NAT66 is ever synthesized as a fallback.

DNS implications

There is no hidden port-53 exception:

  • public/external DNS servers are Internet destinations, reachable only if the policy's services allow DNS traffic;
  • an internal JANUS or customer DNS server is INTERNAL and remains denied by an Internet-only grant.

To let an Internet-enabled subject use an internal resolver, grant that separately with a normal AccessPolicy.

Control plane versus data plane

An Internet egress policy applies only to the forwarded customer/client data path. It never alters appliance control-plane traffic: Controller communication, enrolment, updates, time, platform DNS and health/observability are governed separately and are never gated by a subject's Internet policy.

Conversely, appliance control-plane exceptions never provide transit to customer subjects.

For a Site Edge this is enforced structurally, not by policy: the carriage is installed in a separate policy-routing table consulted only through a rule matching the customer interface, and an appliance-originated packet carries no ingress interface, so it can never match that rule and keeps the main table and its management uplink.

Withdrawal and reclassification

Standard JANUS semantics apply — no Internet-specific conntrack behaviour is introduced.

  • Removing the policy, removing the subject or grant, revoking a Device, or changing a Prefix subject withdraws the authorization.
  • INTERNET → INTERNAL reclassification is fail-closed. When a destination becomes INTERNAL, the next applied state's INTERNET set no longer contains it, so NEW connections are denied. There is no stale catch-all rule: the whole rule set is rebuilt atomically in one nftables batch, so there is no window in which the old authorization and the new classification coexist.
  • Withdrawing an Internet SNAT intent removes the provider-uplink translation: the domain's transit address is released and the provider's uplink rule for it disappears on the next rebuild of the uplink table. No stale host-level NAT or policy-routing rule survives.
  • Withdrawing a Prefix Internet grant removes the Site Edge carriage: the carried destinations leave the provider peer's allowedIPs, the carriage routes are removed from the policy table, and the customer-interface policy rule is deleted. Unrelated Site Edge routing (the customer routes and the JANUS routes) is untouched.

Failure modes

Situation Result
Empty or unknown subject, or no destination validation error (fail closed)
Unknown Device or Prefix reference validation error
Prefix that is a default route, SPECIAL, or not owned/routed validation error
Address family with no Internet destinations left no rule compiled for that family
Unauthorized source dropped by the deny-by-default forward path
Internet grant to an INTERNAL destination not matched, dropped
snat address not owned by the deployment validation error
NAT without authorization traffic still dropped

Complete example

apiVersion: janusaccess.net/v1alpha1
kind: AccessPolicy
metadata:
  name: guest-internet
spec:
  subject:
    group: guests
  destination:
    internet: true
  services:
    - {protocol: udp, port: 53}
    - {protocol: tcp, port: 80}
    - {protocol: tcp, port: 443}
  enabled: true

Compatibility

Existing AccessPolicy configurations are unchanged: destination.resource keeps its exact semantics, and a deployment with no Internet policy compiles an artifact with no Internet set. The destinations are a discriminated pair (resource XOR internet); neither one or both is a validation error.