Skip to content

Site Edge

A Site Edge is a JANUS participant that represents a customer site whose network JANUS does not own and whose existing firewall or router must not be reconfigured.

It is one software product, installable from a Debian package on a customer host, and shippable as a virtual or (in future) physical appliance. The site's own network elements stay exactly as they are: the Site Edge terminates JANUS connectivity on behalf of the site.

Customer LAN
    |
JANUS Site Edge        (Debian host, VM appliance, later physical appliance)
    |
WireGuard / JANUS connectivity
    |
JANUS Gateway / provider fabric

Division of responsibility

THE EDGE ROUTES.  THE PROVIDER AUTHORIZES.

A Site Edge carries traffic and never holds JANUS access policy. It never authorizes a packet. Reachability created by the edge is reachability, not permission: the provider Gateway decides, and a carried destination the provider does not authorize is dropped there.

This split is what makes a Site Edge safe to place in a customer network: it cannot grant anything on its own.

The SiteEdge object

SiteEdge is a deployment-scoped object that references an existing Site in the same deployment — the same idiom RoutePolicy, NATPolicy and Prefix already use. It is deliberately not a Gateway, not a GatewayNode and not a Device: those have different trust domains, lifecycles and semantics.

apiVersion: janusaccess.net/v1alpha1
kind: SiteEdge
metadata:
  name: leipzig-edge1
spec:
  enabled: true                      # an ACCESS state, never an activity state
  site: leipzig-warehouse                   # required; must resolve in the same deployment
  roles: [ingress, egress]           # closed set; an empty list fails closed
  attachment:
    primary: fra-01-gw1          # the one provider Gateway this edge attaches to
  identity:
    publicKey: "<edge Ed25519 public key>"   # public material, pre-registered
  wireguard:
    publicKey: "<edge WireGuard public key>" # public material only
  lan:
    prefixes: [192.168.50.0/24, 2a0c:800:1234::/48]
  ha:
    precedence: 10                   # declarative preference, never observed health
Field Required Meaning
spec.enabled yes Whether this edge may participate. An access state — never activity.
spec.site yes An existing Site of the same deployment. A cross-deployment reference fails closed.
spec.roles yes Non-empty subset of {ingress, egress}. Empty or unknown fails closed.
spec.attachment.primary yes when enabled The one deployment-scoped provider Gateway this edge attaches to. Must be enabled and fabric-enabled in the same deployment.
spec.identity.publicKey no The edge's pre-registered Ed25519 control-plane public key. Omit it to onboard the appliance from its own local setup page instead (see below).
spec.wireguard.publicKey no The edge's WireGuard transport public key. Public material only.
spec.lan.prefixes no Customer-local prefixes the edge is authorised to route for. IPv4 and IPv6.
spec.ha.precedence no Declarative redundancy preference (lower wins). No automatic election exists.

Site.spec.wireguard.publicKey is retained and compiled unchanged. It is the site's WireGuard key, not the edge's; a site without any Site Edge object behaves exactly as before.

Validation

An empty, unknown or duplicated role fails closed. A spec.site that does not resolve in-deployment fails closed. A malformed identity key fails closed, as does the same identity key registered to two SiteEdges, a malformed WireGuard key, or a malformed customer prefix. An absent identity key is valid: it means the appliance onboarded from its own local setup page and the key is bound when an administrator approves it. Two enabled edges of one deployment declaring the same customer prefix is ambiguous origination and fails closed.

Customer prefixes accept both address families and any length (/0…/128).

Roles and direction semantics

spec.roles is a set over the closed enum {ingress, egress}.

Role Meaning
ingress customer/site traffic enters JANUS here
egress JANUS traffic exits toward customer-local networks here
[ingress, egress] bidirectional — the combination, not a third value

bidirectional is not a valid value: it is expressed as the two roles.

Direction is enforced, not merely descriptive. A customer source reaching the Internet through JANUS is a customer → JANUS NEW connection, so the edge must permit ingress. An egress-only edge denies that flow even when the subject holds a valid Internet AccessPolicy. ingress-only equivalently denies JANUS-initiated flows toward the customer LAN.

Customer LAN prefixes: declared versus accepted

A prefix in spec.lan.prefixes is declared, not automatically reachable:

accepted = declared prefixes  INTERSECT  prefixes of the enabled Resources
                                         bound to this edge

The explicit binding is Resource.spec.siteEdge (mutually exclusive with Resource.spec.gateway.primary). A declared prefix with no bound Resource never becomes provider reachability, and a default route (/0) is representable and reportable but is never accepted for provider transit.

This is what stops a typo in a lan.prefixes list from advertising a customer's entire address space into JANUS.

Provider attachment

spec.attachment.primary is desired state, not an observation: the edge's session is outbound-initiated toward exactly that Gateway, and the attachment — not a runtime observation — fixes the provider-side path the compiler builds for the edge's accepted prefixes.

The attachment Gateway compiles an additive siteedge-kind fabric peer (edge WireGuard public key, AllowedIPs = accepted prefixes, endpoint-less and outbound-initiated) plus fabric routes, and originates the edge's accepted prefixes on the edge's behalf so the deployment's other participants route toward it.

One attachment only. Multi-attachment and automatic Site Edge HA are deliberately not implemented in this release; a Site may own several SiteEdges for redundancy, ordered declaratively by ha.precedence, but failover is not automatic.

Identity

Each installation generates a local Ed25519 keypair on first start.

  • The private key is generated locally and never leaves the host. It is written only to /var/lib/janus/site-edge/identity.json, mode 0600, and never enters Git, the Controller, the API, the WebUI, a log or evidence.
  • The public key and a human-verifiable SHA256: fingerprint are the only derived values displayed.
  • The edge id (jse_…) is a namespaced digest of the public key, so it is immutable and independent of name, address or Site.
  • The identity survives a restart, a reboot and a package upgrade. A plain apt remove preserves it, so a reinstall resumes without re-enrolment.
  • A missing identity and a corrupt or tampered identity are distinct, diagnosable states. Neither is ever silently regenerated — regenerating would orphan the centrally pre-registered key without an operator decision.

This Ed25519 identity is the durable control-plane identity. There is no second mandatory JANUS-issued operational certificate.

Pre-registration and proof of possession

There are two ways an installed appliance becomes enrolled. Both end with the same proof of possession; they differ only in who supplies the public key.

Pre-registered — the administrator records the key in the SiteEdge object:

Site Edge generates its key locally
        |
Administrator copies the PUBLIC key into the SiteEdge object
        |
Git desired state  (the pre-registration IS desired state)
        |
Site Edge dials the Controller and proves possession -> enrolled

Expected (the normal appliance path) — the SiteEdge object is authored without a key, and the appliance is onboarded from its own local setup page:

Administrator authors the SiteEdge (site, roles, attachment) with no key
        |
Appliance operator opens the local setup page and enters the Controller
address, the deployment and the edge name
        |
Site Edge dials the Controller and proves possession -> PENDING
        |
Administrator sees the pending request (with the fingerprint) and approves it
        |
Enrolled

The appliance names an expected SiteEdge; it can never invent a binding, and a key that is already proven for one binding cannot claim another. Nothing about the expected path lets the appliance authorize itself: the PENDING identity authenticates nothing until an administrator approves it.

Enrolment is a two-step bootstrap:

  1. the edge calls POST /api/v1/site-edge/bootstrap/start with its edge id, public key, deployment, site and edge name. This is reachable with no prior trust and grants nothing;
  2. the Controller accepts the call only if an enabled SiteEdge exists whose (deployment, site, edgeName) match and — for a pre-registered edge — whose spec.identity.publicKey equals the presented key. It then issues a single-use challenge with a short TTL, recording the candidate key the challenge was issued for;
  3. the edge calls POST /api/v1/site-edge/bootstrap/finish with an Ed25519 detached signature over the canonical request string;
  4. the Controller verifies the challenge (exists, unused, inside TTL on the server clock, bound to this edge/deployment/site/name), verifies the signature against the candidate key recorded on the challenge only, and atomically marks the challenge used. A pre-registered edge is enrolled; an expected edge becomes PENDING.

Any failure returns one uniform 401 that reveals nothing.

Property How it is achieved
possession is proven the signature verifies only with the private key
no clock assumption at the edge freshness is the challenge TTL on the server clock
replay resistance server-issued, persisted, single-use challenge that survives a Controller restart
binding to the intended object the challenge and signature cover (deployment, site, edgeName)
no bearer secret nothing transferable authenticates anything
the appliance cannot self-authorize an expected edge stays PENDING until an administrator approves it

After enrolment, ongoing requests use the same Ed25519 signed-request scheme (X-Janus-SiteEdge, X-Janus-Nonce, X-Janus-Timestamp, X-Janus-Signature) with a bounded clock skew and replay checking.

Identity lifecycle

Operation Mechanism
initial generation local Ed25519 keypair on first start, 0600
enrolment pre-registration + proof of possession
reconnect / restart / reboot the durable identity is loaded; no re-enrolment
package upgrade identity and state preserved; a running unit returns on the new binary
revocation POST /api/v1/deployments/{deployment}/siteedges/{name}/revoke (requires siteedge:admin). A revoked identity is terminal and is never re-trusted
replacement leave with --purge-identity, then re-register the new public key centrally and revoke the old one
apt purge removes configuration and state including key material; the next start generates a fresh identity that must be re-registered
cloning a restored image presents the same edge id from a second host; this is detectable and revocable — prevention is not claimed

Installation and services

Item Value
package janus-site-edge (Debian 13, amd64)
binaries /usr/bin/janus-site-edge, /usr/bin/janus-site-edge-apply, /usr/bin/janus-site-edge-webui
configuration /etc/janus/site-edge.yaml (conffile)
reverse proxy config /etc/janus/caddy/site-edge.Caddyfile (conffile, optional)
environment /etc/janus/site-edge.env (0640 root:janus-site-edge)
state /var/lib/janus/site-edge/ (0700 janus-site-edge) — identity.json (0600), state.json
units janus-site-edge.service, janus-site-edge-webui.service, janus-site-edge-apply.service, janus-site-edge-proxy.service (optional)
system user janus-site-edge
package dependencies ca-certificates, adduser, nftables (suggests caddy)
sudo apt install ./janus-site-edge_<version>_amd64.deb
sudo systemctl enable --now janus-site-edge janus-site-edge-webui

Local setup UI

The normal onboarding path is the appliance's own local setup page, so an administrator never needs ssh, a serial console, curl or a hand-copied key:

fresh appliance -> open the local setup page -> enter the Controller address,
the deployment and the edge name -> the Controller shows a PENDING Site Edge
-> approve it in the Admin WebUI -> Enrolled

The page (janus-site-edge-webui) shows the appliance identity and fingerprint, the honest enrolment state, the Controller address, a reachability diagnostic, the version and the last successful contact, and lets the operator send or retry the enrolment request. It is not a second control plane: it exposes no policy, and it never shows private key material.

It is loopback-only (ui.listen is 127.0.0.1:8443; a non-loopback bind is refused), sets framing/referrer/CSP headers, loads no scripts at all, and requires a same-origin CSRF token on every change. The package ships an optional reference reverse proxy (janus-site-edge-proxy.service, a Caddyfile that serves the loopback UI on the appliance's management interface with an internal certificate); a host that already runs a proxy uses that one, and the appliance works without any proxy.

Local CLI

The CLI remains the recovery and scripted surface; the local setup page is the normal human path.

janus-site-edge identity   → edge id, public key, fingerprint, installation id
janus-site-edge status     → enrolment state, controller, binding, last contact
janus-site-edge config     → set the Controller URL and CA
janus-site-edge enroll     → Controller URL + (deployment, site, edge-name) binding
janus-site-edge leave      → de-enrol locally (--purge-identity destroys the key)
janus-site-edge run        → the service
janus-site-edge-webui      → the local setup page (started by its own unit)

The administrator supplies the Controller URL and the binding. The binding is an advertisement that the Controller verifies against the expected SiteEdge object; it is not secret and it is not trusted. The security anchor is proof of possession of the appliance's own key plus the administrator's approval.

Scripted (headless) enrolment, where the appliance has no operator at all:

# 1. pre-register the key centrally: show it, then author it into the SiteEdge
sudo janus-site-edge identity

# 2. point the edge at the Controller
sudo janus-site-edge config --controller https://janus.example.com

# 3. advertise the binding that the Controller will verify
sudo janus-site-edge enroll --deployment northwind-prod --site leipzig-warehouse --edge-name leipzig-edge1

The Controller URL must be a full https:// URL. TLS is never disabled: trust comes from the host trust store (the normal case for an FQDN) or from an explicitly configured Controller CA file. There is no insecure-skip-verify mode.

Reaching the local setup page. The page listens on loopback only (ui.listen: 127.0.0.1:8443), which is a deliberate security boundary: the appliance works with no proxy at all, and only remote access to the page needs one. The package ships a reference reverse proxy for that (janus-site-edge-proxy.service with /etc/janus/caddy/site-edge.Caddyfile, exposed on the appliance's management interface with a certificate from Caddy's local CA). It requires the caddy package, which is a Suggests, not a dependency; a host that already runs nginx/HAProxy/Traefik uses that instead.

A packaged acceptance campaign has executed the whole onboarding path this way — local setup page → proof of possession → PENDING at the Controller → approve in the Admin WebUI → enrolled, with the edge applying its compiled participant profile. An end-to-end packet proof through the edge to a customer host behind it has also been performed: an authorized customer flow completes (HTTP 200) with packet-level corroboration at the edge's customer interface, while a denied port and a denied address are both dropped.

Privilege separation

The unprivileged janus-site-edge service holds no kernel capability and cannot change the data plane. The privileged component is a small local service, janus-site-edge-apply, in unit janus-site-edge-apply.service (User=root, CapabilityBoundingSet=CAP_NET_ADMIN, NoNewPrivileges=true), reachable only over the local Unix socket /run/janus/site-edge-apply.sock (mode 0660 root:janus-site-edge).

It exposes exactly three typed operations — ensure, remove, observe — and is not a command runner: no shell, no argv, no path argument and no file operation exists in a request. Each connection is authorized by its local peer credentials (SO_PEERCRED): exactly one identity may connect. Every request is size-bounded, decoded with unknown fields refused, and the plan is validated independently on the privileged side (interface pinned to edge-wg0, no default route, bounded prefix counts).

Compromising the unprivileged service therefore does not yield root command execution.

JANUS touches only its own objects: the edge-wg0 WireGuard interface and the routes it marks with the JANUS route protocol. The customer-side interface is never created, deleted or reconfigured, and withdrawal removes only JANUS-owned objects. A desired prefix already routed by a non-JANUS owner is a conflict and fails closed.

Control-plane isolation

The edge'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.

This is structural rather than policy-based: Internet 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.

Internet egress through a provider Gateway

A customer source behind a Site Edge can reach the Internet through the provider Gateway. The edge routes; the provider authorizes. See Internet egress for classification, carriage, NAT placement, IPv6 and withdrawal semantics.

No local breakout. A Site Edge never sends customer traffic directly to the Internet from its own host. All egress is carried to the provider Gateway and exits there. A customer's own independent Internet connection, where traffic never traverses JANUS, is not JANUS Internet egress.

Troubleshooting

Start from the three independent surfaces:

# what the edge believes about itself
sudo janus-site-edge identity
sudo janus-site-edge status

# what the edge is doing
systemctl status janus-site-edge
journalctl -u janus-site-edge -n 100 --no-pager
journalctl -u janus-site-edge-apply -n 100 --no-pager
Symptom Look at
status shows controller-not-configured the Controller URL has not been set (config)
status shows registered-awaiting-connection the object exists centrally but the edge has not completed enrolment
status shows never-enrolled the binding does not match an expected SiteEdge, or pre-registration does not match
status shows pending-approval possession was proven; an administrator has not yet approved the appliance in the WebUI. It authenticates nothing until then
status shows revoked the identity was revoked centrally; generate a new identity and re-register
enrolment returns 401 the (deployment, site, edge-name) binding does not match an enabled SiteEdge, the edge id does not derive from the presented key, or — for a pre-registered edge — the key does not equal spec.identity.publicKey
the edge routes nothing check that the Resources are bound with spec.siteEdge and enabled — a declared LAN prefix with no bound Resource is never accepted
customer traffic to the Internet is denied check the edge's roles: Internet egress from a customer source needs ingress
the customer interface was changed by JANUS it should not be — JANUS only owns the edge's WireGuard interface and its own marked routes; collect ip route show and the apply logs

Boundaries in this release

Documented deliberately, so they are not mistaken for features:

  • One provider attachment per edge; no automatic edge HA.
  • No local breakout — the edge never exits to the Internet directly.
  • No automatic MTU/PMTU derivation or validation. An MTU can be supplied in the plan and is applied, but JANUS does not measure or derive a path MTU.
  • The local setup UI is deliberately minimal. It shows identity, enrolment state, the Controller address, diagnostics and version, and it starts/retries enrolment. It is not a policy editor and never becomes a second control plane: the central WebUI and API remain authoritative for all JANUS policy.
  • No NAT66 anywhere in JANUS.
  • No dynamic routing protocols (for example BGP/FRR) — routing is declarative and static.
  • The edge host is the isolation boundary: a Site Edge has no network namespace of its own, unlike a provider Gateway's per-deployment runtime domain.