Skip to content

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:

sudo dpkg -i janus-gateway_<version>_amd64.deb

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:

sudo -u janus-gateway /usr/bin/janus-gateway enroll --wait

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

janus enrollment revoke <gateway-id> --reason "decommissioned"

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 (including controller.url and caFile) 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 applyHelperPath unset 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.