Skip to content

Provisioning gateways

How to create a gateway record, apply its config to hardware, and reconfigure a gateway that's already in service.

Creating a gateway

Create the gateway record in the fleet dashboard. 1. Go to Gateways → Add Gateway. 2. Fill in the gateway details and click Add. 3. Once created, click the Download Config File button to download the .gwc config bundle.

The .gwc is a tar archive of three files:

  • config.json: gateway_id, the management_api URL, the gateway's assigned wg_ip, and the wg_server_public_key / wg_server_endpoint it needs to bring up wg0.
  • pass: the gateway's password. It doubles as both the LuCI/root login and the x-gateway-api-key the gateway sends when registering its WireGuard key with the API.
  • vpn.ovpn: the OpenVPN client config.

There's no WireGuard keypair in the bundle: the gateway generates its own on first boot and only ever sends the public half back to the API (see Registering with WireGuard below).

vpn.ovpn is on its way out

It's only still in the bundle because OpenVPN is still running in parallel during the WireGuard rollout. It'll be dropped once OpenVPN is fully retired.

Applying the bundle

The M2's base firmware ships without any LuCI credentials, so on a factory-clean gateway you can log in to LuCI with no password at all, over LAN.

First flash, always over LAN:

  1. Connect to the gateway over LAN and open LuCI and login as root with no password.
  2. Go to System → Gateway Manager → (Re)configure.
  3. Upload the .gwc bundle downloaded from the fleet dashboard.

Reconfiguring an already-enrolled gateway:

Once a gateway has registered its WireGuard key (see below), LuCI is only reachable over the wg0 tunnel, not the LAN. To reconfigure it, connect over WireGuard (see Remote access), then repeat the same System → Gateway Manager → (Re)configure steps.

Not documented yet

These gateways don't have a LuCI UI. TODO: document how the bundle is applied on this hardware.

Registering with WireGuard

After the bundle is applied, the gateway takes it from there automatically:

  1. It generates its own WireGuard keypair on-device (wg genkey). The private key never leaves the gateway.
  2. It registers the public key with the management API: POST /gateways/{id}/wireguard/register, authenticated with the x-gateway-api-key header from its bundle.
  3. The peer reconciler in the cluster polls the internal peers list roughly every 10 seconds and syncs new peers into the live WireGuard server.

A gateway is typically online within about 10 seconds of registering. No manual approval step is needed.