Nebula lighthouse filters vs firewall: what each one blocks

Watch a Nebula handshake from the wrong end and the two mechanisms look interchangeable. One decides which addresses a node tells the lighthouse about and which remote addresses it will try; the other decides what may pass once the tunnel exists. A filter can stop a connection before any firewall rule is evaluated, and a firewall rule cannot revive an endpoint that discovery removed. The two layers answer different questions, and the order in which they act is the key.

Follow one connection through four stages: the local address advertised, the remote endpoint considered, the handshake, and the overlay traffic. Each stage has its own configuration and its own failure signature.

Start at the local address the node advertises

local_allow_list filters this host's local addresses before they are reported to lighthouses. The entries can be address ranges, and the configuration also supports interface-name patterns. That is useful when a host has container bridges or extra tunnel interfaces that should not become peer endpoints.

Walk the host's interfaces and ask which ones a remote peer could actually reach. A Docker bridge address is local to that host and useless to a peer in another network. Advertising it wastes discovery and can send a peer toward an address that never answers. Anything a peer cannot route to is noise in the lighthouse response.

A narrow allow list is safer than a broad deny list here. If only allow entries are present, the unspecified remainder is excluded; adding a deny entry later changes the default logic and needs its own review. That change deserves a second look at the default.

Then watch the remote endpoint selection

remote_allow_list filters the addresses this host will consider for a remote peer during a handshake. It applies to the underlay address, not to the overlay address the peer will use after the tunnel is up.

A private range can be perfectly usable on a shared office network and meaningless when the two hosts sit in unrelated networks that both use 10.0.0.0/8. The filter lets you prefer the routable path and ignore the coincidence.

When a peer fails to connect, compare the address being tried with the rule that matches it. Enable the handshake logs and read the selected remote address; the log line names the endpoint that survived filtering, which is more useful than the list of addresses the peer owns.

An interface-name filter on the advertising side can remove the endpoint before the receiving side ever sees it. Check both nodes when only one direction fails.

After the handshake, the overlay access rules apply

Nebula firewall rules operate inside the overlay, after the tunnel is established. They match hosts, groups, ports and protocols, and they decide whether a packet may enter or leave the local host. They do not select an underlay endpoint.

This separation explains a common misdiagnosis. An operator adds a firewall rule for a port and still cannot connect, because the lighthouse filter removed the only reachable endpoint. Another operator opens the address filter and still cannot reach the service, because the overlay firewall rejects the port.

Read the failure at the right layer. A handshake that never completes points at discovery, endpoint filtering or the network path. A completed handshake followed by a refused or dropped service connection points at the overlay firewall or the application.

Read the default when mixing allow and deny

The lighthouse configuration supports allow-only, deny-only and mixed lists, and the default for the unspecified remainder differs between those shapes. A mixed list needs an explicit default for the address family; assuming the remainder behaves like the previous configuration is how a working endpoint quietly disappears.

lighthouse:
  local_allow_list:
    interfaces:
      docker0: false
  remote_allow_list:
    192.168.0.0/16: true
    default: false

Treat the default as part of the rule, not as boilerplate. If the family default is deny, every address not listed is excluded, including a new office range that was added after the configuration was written.

Record which addresses were intended to be reachable and test from both sides. A filter that works for one peer pair can fail for another pair whose only common path uses an address the list excludes.

Use relay when no direct endpoint is reachable

If every candidate endpoint is filtered out or unreachable, the answer is not a wider allow list that re-admits addresses you do not trust. Nebula's relay configuration provides an alternate peer path when direct connectivity is not workable.

Relay solves transport and discovery, not authorization, and it does not widen the firewall. The overlay firewall still decides which services may be used, and the relay does not turn lighthouse filtering into an access-control mechanism.

Test the relay path with the direct endpoints disabled and confirm that the intended service still works while an unintended one does not. That single test separates a transport fix from a policy change and keeps the two layers honest.