Skip to main content

static_host_map

Reloadable

The static host map defines a set of hosts with fixed IP addresses (or DNS names) on the internet (or any network). Entries listed here are dialed directly, without lighthouse mediation, which makes the static host map the bootstrap path for connectivity: it works before — and without — any lighthouse being reachable. Every host must have an entry for each lighthouse in the network, because the discovery service itself cannot be discovered dynamically. See How hosts find each other for when to list other hosts here versus relying on lighthouse discovery or lighthouse.advertise_addrs.

A host can have multiple fixed IP addresses defined here, and nebula will try each when establishing a tunnel. The syntax is:

"<nebula ip>": ["<routable ip/dns name>:<routable port>"]

Example, if your lighthouse has the nebula IP of 192.168.100.1 and has the real ip address of 100.64.22.11 and runs on port 4242:

static_host_map:
  '192.168.100.1': ['100.64.22.11:4242']

Entries may mix literal IPs, DNS names, and IPv6 addresses (bracketed):

static_host_map:
  '192.168.100.1': ['100.64.22.11:4242', 'lighthouse.example.com:4242', '[2001:db8::1]:4242']

DNS names are re-resolved periodically, and again whenever a handshake to that host starts. A failed lookup keeps the last known good addresses; only a not found answer removes them. The static_map settings control the resolution cadence, lookup timeout, and which IP version is used to reach static hosts.

Every host listed in lighthouse.hosts must have an entry here. Nebula refuses to start, and fails a reload that changes lighthouse.hosts, if one is missing. Removing an entry on reload drops its addresses.