Nebula static_host_map: the address a lighthouse cannot give

Every lighthouse can tell a host about every other peer except where the lighthouse itself lives. Something has to be known before the overlay exists, and Nebula puts that something in one small map. The map pairs an overlay identity with an address that works on the ordinary network. Everything learned later depends on that pairing being right.

Two addresses with two jobs

Each Nebula host owns an overlay address that stays fixed while the device moves between networks. That address is the identity used by certificates, firewall rules and peer relationships, and on its own it routes nowhere. The reachable endpoint is a different thing: a hostname or address on the underlying network plus a UDP port, and it changes whenever the machine changes location. The static map is the join between the two.

Only hosts that must be dialed cold belong in the map, which usually means the lighthouses and perhaps a relay. Keeping that list short is a design goal, because every manual entry becomes a fact somebody has to maintain. Confusing the two address types is the usual configuration mistake: a public address placed in the lighthouse list does not make discovery start.

Identity goes where identity is expected. Reachability goes in the map.

static_host_map:
  "10.42.0.1": ["lighthouse-01.example.net:4242"]

lighthouse:
  am_lighthouse: false
  hosts:
    - "10.42.0.1"

Anatomy of a map entry

The key is the overlay address written as a quoted string, and the value is a list of endpoints, so one identity can have several entry points. Each endpoint carries a host and a port, and the port must match what the far side actually listens on. Nebula's default is UDP 4242, which is a starting point rather than a promise about your deployment.

Several endpoints are useful when a lighthouse has more than one path in, such as a public address and a private address for hosts on the same segment. The client tries them in order, so put the most reliable one first. For IPv6, bracket the address before appending the port; getting that wrong produces a parse error that points at the wrong line.

A wrong port produces silence instead of an error, because UDP has no handshake to refuse. That makes the entry format worth checking against the Nebula static_host_map reference rather than memory. The reference also covers endpoint lists and DNS refresh behaviour.

Bootstrap has to work before the overlay

A DNS name in the map must resolve through the resolver the host has before any tunnel exists, which is the ordinary system resolver. Test it from the same machine, at boot, with the overlay stopped. A name that only resolves through the overlay's own DNS cannot bootstrap the overlay. The same test applies to the route: a firewall rule that permits the overlay but not the first UDP exchange blocks the initial packet.

Probe the port with a UDP tool instead of assuming it is open. Confirm that any port forwarding on the path targets the correct internal host and that a return path exists. If the hostname resolves to several addresses, test each one, because a client may choose an address you never checked.

Static entries are dialed directly and never consult a lighthouse. That is why a failure here looks like a plain timeout with no peer involved.

What happens after the first handshake

Once a host reaches a lighthouse, it learns about peers and their reachable addresses without more manual entries. Hosts that have moved since the last connection become discoverable through that channel. This is the payoff for keeping the manual map small.

Hosts can also advertise additional reachable addresses of their own, which is how a peer behind a known public address helps others find it. Those advertisements are learned, not typed into the static map.

Refresh behaviour matters for endpoints written as DNS names, because a resolved address can change while the process keeps running. Nebula's settings control how those lookups happen, including which resolver is used, so read them instead of assuming the system default. On a host whose resolver changes when a tunnel comes up, the wrong setting can turn a working bootstrap into a name that stops resolving mid-session. Pinning the lookup to a stable resolver is often the difference between a reliable overlay and an intermittent one.

When discovery works and one peer does not

If lighthouses are reachable and most peers connect, the bootstrap is not the problem. The remaining pair either cannot find a usable path to each other or is failing above reachability. Adding another spelling of the lighthouse address cannot repair either case.

Check the pair before editing the map that everything else already relies on. A map change disturbs every host, so it is the last thing to touch, not the first.

Start with certificates from the same authority, because a rejected handshake can look like an unreachable peer from a distance. Then check whether the pair can establish a direct path and whether a relay is configured for networks that refuse direct traffic. A relay adds a hop and a dependency, but it is a supported answer, and fixing the peer path is a different task from fixing discovery.