Networking
The lan network
The installer creates one Incus network on every node, named lan. It is a macvlan network on the node's wired LAN port: every VM appears on your LAN as its own device with its own MAC address and gets its address from your router (DHCP), like any other machine.
Because the network has the same name on every node, a VM's network card works unchanged after it moves or fails over — even if the physical port has a different name on each machine. staxmax also pins each VM's MAC address, so a VM usually keeps the same DHCP address after a failover.
A VM made from a cloud image can instead get a Fixed address in the New VM dialog (address, gateway and optional DNS). It is set on first boot, matched to the VM's network card by its MAC address, so it works whatever the guest calls the interface. Copies of the VM (clones, restored backups, VMs from saved images) get DHCP instead, so they do not clash with the original. ISO installs set their address in the installer.
A node cannot reach its own VMs over the lan network — the host and its macvlan guests cannot talk to each other directly. Other machines on the LAN, including the other nodes, can. Use the VM's console in the UI, or connect from another machine, when you need to reach a VM.
How staxmax learns a VM's IP address
Failover checks a VM's last known addresses before starting it elsewhere (see Failover), so staxmax keeps track of them:
- From the Incus guest agent, for guests that run it (most Linux cloud images).
- From the VM's ARP traffic on the LAN, which its node watches, matched by the VM's MAC address. This covers guests without the agent, such as Windows.
A protected VM with no known IP address cannot be taken over automatically unless its node has a smart plug; the Overview lists it as a reason for degraded protection.
VLAN networks
A VM can be placed on a VLAN with VLAN (optional) in the New VM dialog (IDs 1–4094), or later from Edit. For VLAN n, staxmax creates a macvlan network named lan-v<n> on each node, tagged with that VLAN on top of the node's own LAN port. It creates it on the replica node before each copy, and on the target node before a move, so you do not have to set up anything on the nodes.
What you do need:
- Every node's switch port must carry the VLAN, tagged. A VM can only fail over or move to a node whose port carries its VLAN.
- The nodes must be able to reach the VM on that VLAN for automatic failover. While the owner is healthy, the replica node probes each running VLAN VM it covers once a minute. It only takes such a VM over automatically if it has reached it within the last 10 minutes. If the node has no path into that VLAN, silence after a failure proves nothing, so the VM waits for a Force start (or a smart plug) like a VM with no known IP.
A VLAN change on a VM reaches its replica with the next copy.
Direct cables between nodes
A network cable plugged straight between spare wired ports of two nodes becomes an extra heartbeat path, with no configuration: no addresses, no bridge, no switch.
- Any wired port that has a link but no IPv4 address is used. staxmaxd announces itself on it every second (UDP port 7443, to an IPv6 link-local multicast group), signed with the cluster's secret so only members are recognised. Ports are checked for a new cable every 10 seconds.
- When a member's announcement is heard on a port, that member is reachable over the cable through its IPv6 link-local address, and heartbeats go over it as well as the LAN.
- The Nodes page lists it under Heartbeat paths as Direct cable, with the port name and link speed.
The cable is only an extra heartbeat path. It counts for hearing the other node and for checking whether the other machine is still running, but never as the tiebreaker. Unplugging it, or losing link on it, removes the path; it is not taken as a sign that the other node is down.
On two-node clusters with only the LAN between them, the Overview suggests a direct cable. Even a 100 Mb/s USB adapter is enough: heartbeats are tiny. In testing, nodes with the LAN path blocked stayed healthy over the cable alone.
Paths and ports the nodes use
| Port | Protocol | Used for |
|---|---|---|
| 7443 | TCP (HTTPS) | Web UI and API, and node-to-node traffic: heartbeats, the shared VM table, settings, relayed requests. |
| 7443 | UDP | Direct-cable announcements on spare ports (IPv6 link-local only). |
| 8443 | TCP (HTTPS) | The Incus API, used to copy VMs, ISOs and images between nodes. |
The installer opens both TCP ports, and 7443/udp for direct-cable beacons, in ufw when it is active. Node-to-node HTTPS uses certificates pinned when the node joined, so nodes only accept each other.
Heartbeat paths
Each node keeps its own list of the addresses it uses to reach every other node, editable under Nodes → Settings → Heartbeat paths:
- Addresses a node announces for itself are added on their own.
- You can add a path on a second network (for example
10.99.0.2:7443), so one unplugged cable or switch port does not look like a dead node. - An address you remove stays removed, even if the node keeps announcing it.
- Direct cables are found on their own and do not appear in this list.
Heartbeats go out every second over every path; a node counts as reachable as long as any one path answers. The Overview marks protection degraded when any heartbeat path is down.
The tiebreaker (two nodes only)
In a two-node cluster each node also pings its tiebreaker every 2 seconds — your default gateway unless you list other addresses under Settings → Tiebreaker addresses. Pick something that is only reachable when the node's LAN connection is really working, such as your router. With three or more nodes there is no tiebreaker. See Failover.