FluxDeployDocs
Topics: Relay network requirements

Relay network requirements

A relay site needs one wired network. PXE boot and image sync move gigabytes, and both depend on the relay having one stable address that PXE clients and Core can reach.

Why two networks cause trouble

A relay that is connected to Wi-Fi and Ethernet at the same time (or to two wired networks that both have a default gateway) reports both addresses to Core. Whenever one of them drops, even for a moment, the relay's address changes. Each change:

  • Rebuilds and re-sends the relay's boot image. The relay's address is built into its boot image so PXE clients know where to find it, so a new address means a new image - several hundred megabytes over the WAN every time.
  • Breaks Core's calls to the relay. While the relay answers on its other address, Core's requests (log pull, PXE activity, certificate push, the manual boot ISO) time out.
  • Confuses PXE clients that booted with the old address in their boot image.

What FluxDeploy tells you

Core checks every relay site and says so on the site's Overview (with every adapter, its addresses and whether it has a default gateway), on its row on Relay sites, in the Core health score, and as one line on the Dashboard.

What Core sees Severity What it means
A Wi-Fi adapter has an address while another adapter does too Error The relay is on Wi-Fi and another network at the same time.
More than one adapter has a default gateway Error The relay's traffic and its reported address can move between networks.
The relay's only network is Wi-Fi Warning It works, but Wi-Fi is not recommended for a relay.
The relay's address changed twice or more within 24 hours Warning Usually two network connections. Shown for relays too old to report their adapters, and clears by itself after 24 hours without a change.

A single address change - a relay moved to a new subnet, say - raises nothing.

What is not counted

These are normal on a relay and are never judged:

  • Loopback and tunnel interfaces.
  • VPNs: Tailscale, WireGuard, ZeroTier, OpenVPN and TAP adapters, AnyConnect, GlobalProtect, FortiClient, and Linux tun/tap/wg/zt/ppp devices.
  • WSL and Hyper-V virtual switches: vEthernet (WSL) (Connected Cache runs in WSL), the Default Switch, NAT switches, and any internal switch without a default gateway. A vEthernet adapter with a default gateway is an external virtual switch - the host's real wired connection - and is counted like the network card it replaces.
  • Container and VM networks: docker0, Docker's br-... networks, veth pairs, CNI/flannel/calico, podman, libvirt virbr, LXC/LXD bridges, VirtualBox host-only and VMware vmnet adapters.
  • Adapters that are disconnected or have no IPv4 address (a link-local 169.254.x.x address does not count).

How to fix it

Do one of these on the relay:

  1. Disable Wi-Fi (or unplug the second network) so the relay has one wired network. This is the recommended fix.
  2. If the relay genuinely needs both, set its PXE client IP to the wired address on the relay site's General tab. That pins the address built into its boot image, so a Wi-Fi drop no longer changes it. If the second network has a default gateway, remove it so traffic to Core always leaves on the wired network.

The error clears on the relay's next heartbeat (within two minutes) once only one network has an address.

Relays on older versions

A relay reports its network adapters from FluxDeploy 1.4.8 on. Older relays are still covered by the address-change check above, and Core never raises the adapter checks for a relay that has not reported its adapters.