Client¶
A JANUS client is a WireGuard endpoint that has been declared as a Device in a deployment and provisioned with a configuration. This page covers how a client gets its configuration, what that configuration contains, how the client's key is handled, and what the reference Linux client supports.
Repository ownership
The JANUS Native Client is implemented, packaged and released from the
janus-client repository. access-concentrator owns the server/
Controlplane side — including the public, versioned Client Contract
(clientcontract) and the server-side assembly of the client manifest — but
does not build, package or release the Client. This page describes the
client-visible configuration contract and the server-side behaviour it relies
on.
Two client modes¶
JANUS provisions clients in one of two modes:
- Generic WireGuard. A single
.conffile that pins one gateway public key and one endpoint. This is a first-class mode and is unchanged. - JANUS-aware. A versioned manifest that names the Device's stable
identity, the closed set of gateways the Device is eligible at, each
gateway's public key and externally reachable endpoint, the client's addresses
and authorized destinations, and the failover timing policy. This mode exists
because a WireGuard peer has exactly one public key and one endpoint and
WireGuard has no health or selection semantics — a single
.confcannot express automatic failover between distinct gateways.
How a client gets its configuration¶
The enrolment flow¶
Enrolment is user-initiated in the self-service portal, and the same operation is available through the self-service API. The user does the following:
- Generate a WireGuard keypair on the device.
- Paste only the public half into the portal's Add a device form:
| Field | Required | Notes |
|---|---|---|
name |
yes | Lowercase letters, digits and hyphens. |
displayName |
no | A human label. |
publicKey |
yes | The public half of a keypair generated on the device. |
- Submit the form. The portal sends
{name, displayName?, publicKey}toPOST /api/v1/self/devices.
The server builds the whole Device declaration itself: the owner is the linked desired-state User, the addresses come from the declared pool, the gateway comes from the deployment policy, and the device is enabled. The caller supplies only a name and a public key, so self-authorization is impossible by construction. Device names are unique per deployment and a per-user bound is enforced server-side before any write.
The new Device is authored into Git desired state as a declared, enabled object. Normal reconciliation does the rest — the enrolment itself programs nothing.
enabled here is an access state
A device's enabled flag is an access state, never an activity state. It
means the device is declared and authorized. It does not mean the device is
currently connected or passing traffic.
What the generated configuration contains¶
The configuration is assembled server-side from the device's profile, then completed in the browser. The exact keys are:
# Janus WireGuard client configuration
# Deployment: <deployment>
# Device: <device>
# Name: <displayName> (only if set)
# Owner: <owner>
#
# The private key below belongs to this device only. JANUS never holds a
# copy of it: keep the file treated as a secret.
[Interface]
PrivateKey = <the device's own private key | a non-key sentinel value>
Address = <addr[, addr...]>
DNS = <dns[, dns...]> (only if configured)
[Peer]
# The gateway this device is configured to attach to. Attachment is
# placement, not identity: the device keeps its identity if it moves.
PublicKey = <gateway public key>
Endpoint = <endpoint>
AllowedIPs = <sorted, comma-joined>
PersistentKeepalive = <n> (only if greater than 0)
Assembly fails closed: a profile with no assigned address, no registered public key, no gateway public key, no endpoint, or no authorized network produces no configuration at all. The last case is deliberate — default-deny means a device the compiled policy authorizes nothing for has no access, so issuing a configuration would claim reachability the gateway will not enforce. If an account has no authorized network, the portal shows a warning instead of a configuration.
How the configuration is delivered to the user¶
The device profile and the server-assembled text travel to the browser as non-executable data islands. The user pastes the device's private key into a password field and clicks Assemble configuration and QR code. That action:
- replaces the
PrivateKey =line with the pasted key, in the page; - draws the QR code locally as inline SVG from the assembled text;
- reveals Download .conf and Copy configuration.
The download filename is janus-<device>.conf. The copy action writes the text
to the clipboard, and the QR code is shown in the Scan on a phone panel
rendered from the same assembled text.
No network request carries the private key. The assembly, QR rendering and download all happen in the browser; the key never leaves the page.
For a client that accepts the private key separately, the server-assembled
configuration is also shown as a code block with the sentinel value on the
PrivateKey = line.
Key handling — JANUS never sees a client private key¶
This is a hard invariant:
- The private key is generated on the device and stays on the device.
- JANUS holds only the public key. The Device profile has no private-key field at all, so a private key cannot be stored or transmitted by accident.
- The server-assembled configuration writes a sentinel value, not a key:
<PRIVATE KEY: paste the key generated on this device>. That value is deliberately not a valid WireGuard key, so a client that imports the file unchanged fails loudly instead of silently coming up with no tunnel. - The JANUS-aware manifest has no private-key field by construction.
The JANUS-aware manifest¶
The manifest is a versioned provisioning document, schema
janus-client-manifest/v1. Its fields are:
| Field | Meaning |
|---|---|
schemaVersion |
janus-client-manifest/v1; a client must refuse a version it does not implement. |
deployment, device, deviceUuid |
The Device's stable identity. |
devicePublicKey |
The device's public key. |
addresses |
The client's addresses. |
allowedIPs, persistentKeepalive, dns |
Authorization and interface settings. |
preferredGateway, gateways[] |
The eligible ingress set: each gateway's name, public key, endpoint and priority. |
failover |
Timing policy only: enabled, probeIntervalSeconds, failureThreshold, holdDownSeconds, failbackMode, failbackHoldDownSeconds. |
Default failover timing: probe every 5s, failure threshold 3, hold-down 30s,
failback hold-down 120s, failback mode manual. Eligibility is a closed
set: the manifest can never offer a gateway the Device is not eligible at, and
failover.enabled is false for a single eligible gateway.
No UI delivers the manifest
The manifest exists in the API response (GET
/api/v1/self/devices/{name}/config), but no WebUI or portal screen
downloads or serves it to a client. The reference daemon reads the
manifest from a local file. Provisioning a JANUS-aware client is therefore
an out-of-band file-placement step, not a portal download.
The Linux client¶
The reference client is two binaries:
janus-client— the command-line interface. It is a platform-neutral IPC client of the daemon and holds no privilege.janus-clientd— the background runtime. It is Linux only and owns all active client runtime state: the WireGuard backend, the client-owned private key, the failover runtime and the local management socket. It requires exactly one privilege,CAP_NET_ADMIN.
There is no single config file. Provisioning is two input files read by the daemon:
| File | Default path | Notes |
|---|---|---|
| Manifest (JSON) | /etc/janus-client/manifest.json |
Schema janus-client-manifest/v1. A broken manifest fails closed. |
| Private key | /etc/janus-client/private.key |
Must not be group- or world-readable. Must contain a valid WireGuard key. Never logged, transmitted or serialized. |
On any load failure the daemon does not exit: it reports a fixed, path-free reason and keeps serving, so a bare installation can say why it is not connected instead of restart-looping. The management socket is created before the runtime starts, so a status query always has something to answer.
Connect, disconnect and status¶
There is no explicit connect or disconnect verb. The runtime brings the interface up and programs the peer automatically, on the manifest's probe interval. Status is queried over the local socket:
Failover¶
The failover engine is a pure decision engine with a fixed set of states:
PRIMARY_HEALTHY, PRIMARY_SUSPECT, FAILOVER_PENDING, SECONDARY_ACTIVE,
RECOVERY_OBSERVING, FAILBACK_PENDING, PRIMARY_ACTIVE_AGAIN,
NO_ELIGIBLE_GATEWAY, plus the non-running states UNPROVISIONED and
BACKEND_UNAVAILABLE.
Its guarantees:
- It selects only within the manifest's eligible set and never invents a gateway.
- It never changes the client's identity, addresses or AllowedIPs.
- A single failed probe is never enough; hold-down bounds switch frequency to prevent flapping.
- Failback is manual by default.
- When every eligible gateway has failed it reports
NO_ELIGIBLE_GATEWAYand keeps the last peer. - "Reachable" for the active peer means a handshake within the configured handshake maximum age (default 3m).
Supported and unsupported platforms¶
- The daemon (
janus-clientd) exists for Linux only. It uses the Linux WireGuard backend and requiresCAP_NET_ADMIN. - The CLI (
janus-client) is platform-neutral and cross-builds for linux/amd64, windows/amd64 and darwin/arm64, so the same command contract exists on every client target. Only the Linux daemon exists today: on Windows and macOS there is no daemon for the CLI to talk to. - Automatic multi-gateway failover requires more than one eligible gateway. With a single eligible gateway there is no failover, only health reporting.
Boundaries¶
- The client never receives its own authorization from the gateway. The gateway enforces access; the client's configuration only configures reachability to a gateway.
- Attachment to a gateway is placement, not identity: the device keeps its identity if it moves between gateways.
- A revoked or disabled device is authorization-withdrawn and is issued no configuration; the device loses access as the change is applied.
Related¶
- WebUI — the operator surface (gateway and device enrollment; the user's own device lifecycle is in the self-service portal)
- API — the self-service endpoints behind enrolment
- Command-line interface —
janus-clientandjanus-clientd - Configuration — the Device object
- Troubleshooting — when a device does not connect