Skip to content

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 .conf file 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 .conf cannot 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:

  1. Generate a WireGuard keypair on the device.
  2. 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.
  1. Submit the form. The portal sends {name, displayName?, publicKey} to POST /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:

janus-client status

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_GATEWAY and 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 requires CAP_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.
  • 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-client and janus-clientd
  • Configuration — the Device object
  • Troubleshooting — when a device does not connect