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¶
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:
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, mode0600, 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 removepreserves 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:
- the edge calls
POST /api/v1/site-edge/bootstrap/startwith its edge id, public key, deployment, site and edge name. This is reachable with no prior trust and grants nothing; - the Controller accepts the call only if an enabled
SiteEdgeexists whose(deployment, site, edgeName)match and — for a pre-registered edge — whosespec.identity.publicKeyequals the presented key. It then issues a single-use challenge with a short TTL, recording the candidate key the challenge was issued for; - the edge calls
POST /api/v1/site-edge/bootstrap/finishwith an Ed25519 detached signature over the canonical request string; - 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.servicewith/etc/janus/caddy/site-edge.Caddyfile, exposed on the appliance's management interface with a certificate from Caddy's local CA). It requires thecaddypackage, 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.