Pluggable VPN architecture

VPN/mesh management is optional. LAN-only deployments use vpn.provider: "null".

Interface

D interface VpnProvider (source/lindir/vpn/provider.d):

Backends

Config — Tailscale

"vpn": {
  "provider": "tailscale",
  "apiBase": "https://api.tailscale.com",
  "apiKey": "tskey-api-…",
  "tailnet": "example.ts.net"
}

Create an API access token in the Tailscale admin console with scopes to manage auth keys, devices, and the policy file (ACL). Tags used at enroll (default tag:lindir) must be defined in the ACL tagOwners and allowed for that token / OAuth client.

Hosts already on the mesh do not need a new auth key. Pass skipVpn: true (CLI --skip-vpn, Admin UI checkbox). IdM enroll succeeds even if VPN key creation fails (vpn response may start with error:).

Install the client agent before enroll. For Tailscale/Headscale, the host needs the tailscale binary (and a working tailscaled) before lindir-client enroll without --skip-vpn. Enroll only mints and applies an auth key; it does not install the Tailscale package for you. WireGuard needs wg-quick / wireguard-tools; Pangolin needs newt on PATH (or a unit that reads /etc/newt/newt.env).

Client join

lindir-client enroll consumes structured vpnDetail from the enroll response:

Auth keys, WireGuard private keys, and Newt secrets are never written to audit detail (only kind / address).

Config — Headscale

"vpn": {
  "provider": "headscale",
  "apiBase": "https://headscale.example.com",
  "apiKey": "…",
  "tailnet": "lindir"
}

Policy sync requires Headscale policy.mode: database. File-based policy is read-only via the API.

Connectivity. Headscale (and Tailscale) fleets often reach each other via DERP relays when there is no L2 adjacency between VMs or sites. Mesh pings succeeding only through DERP is normal in cloud and lab topologies — not a failed enroll. Prefer checking tailscale status / tailscale ping before assuming VPN enroll failed.

Kernel noise. Lean cloud kernels may log IPv6 / xt_mark warnings when Tailscale starts. IPv4 mesh can still be healthy; treat those messages as informational unless IPv4 peers also fail.

Config — WireGuard

"vpn": {
  "provider": "wireguard",
  "wireguard": {
    "endpoint": "vpn.example.com:51820",
    "iface": "wg0",
    "serverAddress": "10.66.0.1/24",
    "peerNetwork": "10.66.0.0/24",
    "dns": "10.66.0.1",
    "configDir": "/var/lib/lindir/wireguard",
    "serverPrivateKeyPath": "",
    "applyLive": false
  }
}

WireGuard has no cloud ACL API: syncGroupAcls writes groups.json and refreshes the server config. Bring the interface up yourself, e.g. wg-quick up /var/lib/lindir/wireguard/wg0.conf.

Config — Pangolin

Pangolin (fosrl) exposes sites via its Integration API. Lindir enrolls each host as a Newt site and returns join credentials for the Newt agent.

"vpn": {
  "provider": "pangolin",
  "apiBase": "https://api.pangolin.net/v1",
  "apiKey": "…",
  "pangolin": {
    "orgId": "org_…",
    "endpoint": "https://app.pangolin.net"
  }
}

Create an API key under Organization → API Keys with permission to create/list/delete sites. Self-hosted deployments must enable the Integration API.

syncGroupAcls is a no-op: Pangolin authorizes via roles/users on public and private resources, not Tailscale-style ACL documents. Assign access in the Pangolin dashboard or Integration API after sites exist.

Hosts need the newt binary on PATH (or a newt.service unit that reads /etc/newt/newt.env).

Live behavior

Tailscale

Headscale

WireGuard

applyLive: true brings the interface up with wg-quick when needed and syncs peers with wg syncconf. Generated server conf includes PostUp FORWARD accepts for hub-and-spoke; set net.ipv4.ip_forward=1 on the host (or via the container runtime with --sysctl / privileged).

Pangolin

API

• Host enroll (POST /v1/hosts/enroll) calls vpn.enrollHost (optional tags array on the body); response includes vpn + optional vpnDetail.
• POST /v1/vpn/sync-acls pushes group ACL sync.
• DELETE /v1/hosts/{id} and MDM retire call vpn.removeHost.