dns

Added in v1.12.0 Experimental

dns configures the host's resolver to send lookups to nameservers reachable over Nebula, such as a lighthouse serving DNS. It can do this for a set of domains (split DNS), or for every lookup on the host.

dns:
  enabled: true
  nameservers:
    - 192.168.100.1
  match_domains:
    - mesh.example.com
  search_domains:
    - mesh.example.com
  identity: nebula

This is supported on macOS and Windows. It needs Nebula to run as root on macOS, or as LocalSystem on Windows, for example as a service. On other platforms, Nebula logs a warning and leaves the host's DNS settings alone; the tunnel still comes up.

Caution

On Windows, running Nebula as an elevated Administrator instead of LocalSystem can leave Nebula's DNS rules in effect after it stops, which can break DNS resolution on the host.

Nebula removes the DNS settings it applied when it stops; it does not restore older values. If Nebula crashes, its settings stay in place until Nebula starts again with the same dns.identity, which clears them whether or not dns is enabled.

A dns stanza that fails to load stops Nebula from starting, and fails a reload.

dns.enabled

Default: false Reloadable

Set to true to manage the host's DNS settings. Turning it off on reload removes the settings Nebula applied.

Nebula must have a tun device, so this can't be used with tun.disabled. On Windows, tun.dev must also be set.

dns.nameservers

Required Reloadable

A list of nameserver IP addresses to send matching lookups to. At least one is required when dns.enabled is true.

dns.match_domains

Default: dns.search_domains Reloadable

A list of domain suffixes whose lookups go to dns.nameservers. Lookups for other names use the host's usual resolver.

When match_domains is not set, it defaults to dns.search_domains. One of the two must be set.

Caution

An explicitly empty list, match_domains: [], sends every lookup on the host to dns.nameservers. If those nameservers are only reachable over Nebula, the host can't resolve anything while the tunnel to them is down.

The root domain, ., is not accepted. Use match_domains: [] instead.

dns.search_domains

Reloadable

A list of domains to try when looking up a bare name, such as host1 for host1.mesh.example.com. When dns.match_domains lists domains, each must fall under one of them.

dns.identity

Default: nebula

The name Nebula records its DNS settings under, so it can find and remove them later without touching settings made by anything else. It must start with a lowercase letter or digit, and hold only lowercase letters, digits, ., _, and -, up to 63 characters.

When more than one Nebula on a host manages DNS, give each its own identity. Otherwise each one clears the others' settings when it starts.

A change to identity takes effect after a restart.