Install a Gateway¶
A Gateway is the JANUS data-plane component. It receives the desired state
compiled for it by the Controller, applies it to its own runtime domain
(WireGuard, routes, nftables), and reports back what it actually applied. Client
tunnels terminate at a Gateway. A physical Gateway node may serve several
Deployments; each (Gateway node, Deployment) pair is a separate runtime
domain.
The Gateway is a data plane, not a remote shell
It accepts desired state, applies it, and reports applied state. The Controller cannot run arbitrary commands on it.
See Gateway agent for how delivery and application work, and Data plane for what the Gateway enforces.
Prerequisites¶
| Requirement | Detail |
|---|---|
| Operating system | Debian 13 (trixie), amd64 |
| Kernel networking | in-kernel WireGuard support (no out-of-tree module or DKMS build), plus the wireguard-tools utility (wg) |
| Firewalling | nftables — the forward path is compiled into an atomic nftables rule set |
| Network namespaces | the runtime domains use host-level network namespaces (ip netns), which is why the Gateway runs unprivileged with only the capabilities it needs |
| Controller | a reachable Controller HTTPS front door and its CA, so the Gateway can enrol |
| Privileges | root/sudo to install the package and manage the service |
Package¶
Install janus-gateway:
The package depends on ca-certificates, adduser, nftables and
wireguard-tools, and installs:
| Path | Purpose |
|---|---|
/usr/bin/janus-gateway |
the Gateway agent |
/usr/bin/gateway-apply |
the privileged data-plane helper (the only component that touches the kernel) |
/etc/janus/gateway.yaml |
Gateway configuration (conffile) |
/etc/janus/gateway.env |
environment (conffile, 0640 root:janus-gateway) |
/usr/lib/systemd/system/janus-gateway.service |
the service |
/usr/lib/tmpfiles.d/janus-gateway.conf |
re-creates the runtime directories on every boot |
/var/lib/janus/gateway/ |
Gateway state (0700 janus-gateway) |
/var/lib/janus/gateway/state/ |
received-and-validated candidate state |
It creates the system user and group janus-gateway, and adds the janus-gateway
user to the janus-controller group if it is not already a member. It also
creates /run/netns and /run/access-concentrator as root:janus-gateway 0770
via its tmpfiles entry and postinst, because the data-plane service runs
unprivileged and cannot create directories directly in /run.
The service must not be filesystem-sandboxed: it creates host-level network
namespaces, so it runs as the unprivileged janus-gateway user with
NoNewPrivileges=true and only the capabilities the data plane needs
(CAP_NET_ADMIN, CAP_SYS_ADMIN), never as root.
The package enables (does not start) janus-gateway.service.
Configure the Controller endpoint¶
The Controller is reached through its HTTPS front door; the Management API on
its loopback port is not exposed to the network. Edit /etc/janus/gateway.yaml:
label: janus-gateway
controller:
url: https://<controller-front-door> # a locator, not identity
caFile: /etc/janus/credentials/controller-ca.crt # trust the front door's CA
identity:
file: /var/lib/janus/gateway/identity.json
agent:
listen: :9443
stateDir: /var/lib/janus/gateway/state
Key meanings:
| Key | Meaning |
|---|---|
label |
a display label only; it is not identity |
controller.url |
the Controller front-door URL — a locator, not identity |
controller.caFile |
the CA that signed the front-door certificate; it builds a private trust pool for this one connection and never disables verification |
identity.file |
the durable Ed25519 identity file (created 0600 on first use; never leaves the host) |
agent.listen |
the data-plane agent listener the Controller delivers compiled state to |
agent.stateDir |
where received-and-validated candidate state is persisted |
agent.tls.* |
the agent's operational server certificate, its private key and the Controller CA it verifies. All are provisioned AUTOMATICALLY: the Gateway generates the key locally and obtains the certificate from the Controller once its identity is approved and bound; no certificate is placed by hand. |
caFile is the Controller's exported CA for a private/front-door deployment, or
the public CA chain for a real FQDN. Place it where the janus-gateway user can
read it. A certificate the Gateway does not trust is a caFile problem — never a
reason to disable verification.
Enrol¶
Enrolment establishes durable cryptographic trust between this Gateway and the Controller. Run it from the Gateway host:
On first use the Gateway generates its durable Ed25519 identity and prints its gateway id and fingerprint:
created new gateway identity jg_... (fingerprint SHA256:...)
enrollment requested
gateway id: jg_...
fingerprint: SHA256:...
state: pending
The request creates a pending record. It grants nothing yet. An
administrator must approve the fingerprint — compared out of band — before the
Gateway is trusted. --wait blocks until the decision arrives.
The Gateway CLI is:
| Command | Purpose |
|---|---|
janus-gateway run [--config PATH] |
run the agent (this is what the service runs) |
janus-gateway enroll [--config PATH] [--controller URL] [--wait] |
enrol with the Controller |
janus-gateway status [--config PATH] [--controller URL] |
report id, fingerprint and enrolment state |
janus-gateway version |
build metadata |
Enrolment flags include --identity, --hostname, --wait and --timeout
(default 10m).
Approve on the Controller¶
As an authenticated administrator — through the WebUI, or the janus CLI with an
API token — compare the fingerprint, then approve:
janus enrollment list --state pending
janus enrollment show <gateway-id>
janus enrollment approve <gateway-id>
Approval establishes durable cryptographic trust. Once approved, the Gateway authenticates every request with its key; it reconnects after a restart without re-approval, and changing its address or hostname does not require re-enrolment.
Provision the GatewayNode¶
An approved identity is trusted but not yet a placement target. In the WebUI
(Platform → Enrollment), use Provision GatewayNode on the approved record and
give the node a name; the Controller authors a GatewayNode bound to the enrolled
identity. You supply only the node name — never the jg_... id, a fingerprint or
a WireGuard key. Once the node exists, place a Deployment on it and the Gateway
learns its runtime identity and WireGuard keys automatically. (The equivalent API
is POST /api/v1/gateway-enrollments/<id>/provision.)
Identity and key material¶
| Material | Where it lives | Notes |
|---|---|---|
| Ed25519 identity keypair | /var/lib/janus/gateway/identity.json (0600) |
generated locally on first use; the private key never leaves the host |
| Gateway id | derived (digest of the public key) | jg_<base32>; immutable |
| Fingerprint | derived (SHA-256 of the public key) | SHA256:<base64>; the value an administrator compares out of band |
| WireGuard interface private key (automatic) | /var/lib/janus/gateway/keys/wg-private.key (owner janus-gateway, 0600) |
generated locally on first use; the matching public key is REPORTED through the authenticated control plane and never authored in desired state |
| Inter-Gateway fabric keys (automatic) | /var/lib/janus/gateway/keys/fabric/<gatewayNode>__<deployment>.key |
generated locally per (Gateway node, Deployment) participant; the public key is reported automatically; a missing key fails the fabric apply closed |
The identity is independent of hostname and address. It survives a restart, a reboot and a package upgrade.
Start, run and verify¶
sudo systemctl start janus-gateway
janus-gateway status # as janus-gateway; uses controller.url
systemctl status janus-gateway --no-pager
journalctl -u janus-gateway -n 40 --no-pager
To confirm the Gateway is enrolled and delivering state:
janus-gateway status # gateway id, fingerprint, enrollment state
systemctl is-active janus-gateway
curl -fsS http://127.0.0.1:8081/readyz # on the Controller host, not here
janus-gateway status reports the gateway id, the fingerprint and the enrollment
state without any secret. The Gateway never prints its private key.
janus-gateway run sends a liveness heartbeat every 30 seconds while approved; a
heartbeat failure is logged and retried and never stops the data plane.
Delivery versus application is reported separately: a Gateway that received state is not shown as having applied it until application succeeds. See Operations.
Enable the data plane (optional)¶
With agent.applyHelperPath unset the agent only receives and validates state
and never touches the kernel — the fail-closed default. To have the Gateway
actually apply traffic, enable the privileged helper in /etc/janus/gateway.yaml:
agent:
applyHelperPath: /usr/bin/gateway-apply
privateKeyFile: /var/lib/janus/gateway/keys/wg-private.key
The Gateway generates its WireGuard interface private key locally on first use
(owner-only, in its own state tree) and derives the public key from it. The
JANUS-managed WireGuard public key is provisioned through the authenticated
control-plane lifecycle — never by hand. Do not run wg genkey/wg pubkey,
do not paste a public key into desired state, and there must be no WireGuard-key
step on the normal install path. Only externally-controlled client/device keys may
be supplied by an operator.
Break-glass / recovery only (never normal provisioning): if a key must be pre-seeded for disaster recovery, that is an explicitly documented recovery procedure performed by a qualified operator, not a step of the supported install.
The agent never applies on its own — application is requested by the Controller
(delivery.autoApply), which delivers the candidate, the agent validates and
persists it, and the Controller then calls POST /api/v1/apply.
Revoke¶
A revoked Gateway fails closed immediately: its signed requests are refused and it cannot silently re-enrol. Re-trusting it requires a new explicit decision.
Upgrade behaviour¶
sudo apt-get install -y ./janus-gateway_<new-version>_amd64.deb
sudo systemctl restart janus-gateway
gateway.yaml(includingcontroller.urlandcaFile) is a conffile and is preserved across an upgrade.- The durable identity and the enrollment trust record survive, so no re-enrolment is needed.
- A running unit is restarted onto the new binary.
Remove and purge¶
sudo dpkg -r janus-gateway # stop + disable
sudo dpkg -P janus-gateway # also remove package-owned configuration
Both preserve /var/lib/janus/gateway/identity.json. Destroying a node's
cryptographic identity as a side effect of removing a package would force a
re-enrolment on a Controller that still trusts it. Remove the identity explicitly
only if re-enrolment is intended.
Limitations¶
- With
applyHelperPathunset the Gateway receives and validates state but never touches the kernel — it does not enforce traffic. - The Gateway does not generate WireGuard or fabric keys: a missing key fails the corresponding apply closed.
- A dedicated management UI runs centrally, not on the Gateway; the Gateway host has no local web interface.
Related¶
- Controller installation — install this first.
- Gateway agent — delivery and application of state.
- Data plane — the enforced forward path.
- Site Edge — the provider-facing participant.
- Operations — watching enrolled state and delivery.
- Troubleshooting — when enrolment or delivery fails.