Cluster.Strategy.WireGuard (libcluster_mesh v0.1.0)

Copy Markdown View Source

libcluster strategy for plain WireGuard meshes, polling wg show <interface> dump.

Useful for hand-built WireGuard networks (including tools that manage raw WireGuard configs). Plain WireGuard has no hostnames, so cluster members are selected by an IPv4 cidr over the peers' allowed-ips, and a peer counts as online when its latest handshake is recent (handshake_max_age, default 180 seconds). Note that WireGuard is silent when idle: an online peer with no traffic can look stale, so either keep persistent_keepalive enabled on the mesh (recommended) or raise handshake_max_age.

Only the peers configured on that one interface are visible, so a spoke in a hub-and-spoke setup discovers the hub and no other spoke: a full cluster needs a full mesh of WireGuard peers.

Requires permission to run wg show (typically root or CAP_NET_ADMIN).

Usage

Start each node with a longname built from its WireGuard IPv4 (e.g. myapp@10.77.0.2), then configure:

config :libcluster,
  topologies: [
    wireguard: [
      strategy: Cluster.Strategy.WireGuard,
      config: [
        node_basename: "myapp",
        interface: "wg0",
        cidr: "10.77.0.0/24"
      ]
    ]
  ]

Options

  • node_basename (required) — node name part before @, shared by all nodes
  • interface (required) — one WireGuard interface name (e.g. "wg0"); the wg show operands "all" and "interfaces" are not interface names
  • cidr (required) — IPv4 CIDR; a peer is a cluster member when its allowed-ips hold a /32 inside it, which is the address it is dialled at. A peer whose only entry covers a range advertises a route, not a host, and is not a member
  • handshake_max_age — seconds since the last handshake for a peer to count as online (default 180)
  • cli — path to the wg binary (default "wg")
  • polling_interval — poll interval in milliseconds (default 5_000)
  • cmd_timeout — CLI timeout in milliseconds (default 10_000)
  • runner — LibclusterMesh.Runner implementation (default runs the CLI)