Using Experimental Lighthouse DNS with Nebula
Lighthouse DNS in nebula is experimental and should not be considered to be a robust solution. For details, see the limitations listed below.
Nebula comes with built-in DNS server support via Lighthouse hosts.
Lighthouse DNS can generate DNS records based on dynamic nebula hosts, useful if you are spinning up new nebula hosts on demand.
This guide assumes you already have a working Lighthouse and at least one other host communicating with it. If you haven't setup a Nebula network yet, check out the Quick Start guide.
You'll then want to set up the lighthouse as a DNS server for the other two hosts. This can be either the public static lighthouse IP or the private nebula IP depending on the Lighthouse's configuration.
First, spin up a lighthouse and 2 hosts. Then add
to your lighthouses's Nebula config. By setting
[::], nebula will bind to all interfaces
including both the public and nebula IP. Binding to only the nebula IP, for example
lighthouse.dns.host: 10.0.0.1 will
ensure the DNS is only accessible to hosts that are allowed to contact the lighthouse via nebula.
Only Lighthouses should have
lighthouse.serve_dns enabled, as DNS info is collected when hosts report to the
lighthouse. Nebula will not honor the option if enabled on a non-lighthouse host.
Next, add a firewall rule in your lighthouse config that enables UDP on port
53 (or the port
lighthouse.dns.port) for all hosts you want to be able to query DNS on the lighthouse. For example to
allow any host on the nebula network:
- port: 53
Then you can run
dig against it to test! For example, I made a host named
lighthouse as my lighthouse with nebula IP
alice-laptop with nebula IP
100.100.0.2 as my host, and I set up my lighthouse with the above
config / firewall rule.
dig @100.100.0.1 +short alice-laptop A
I can also query the TXT record for the nebula IP for certificate info. Each piece of info is delivered within quotes
and as a
"Key: Value" format.
dig @100.100.0.1 +short "100.100.0.2" TXT
"Name: alice-laptop" "Ips: [100.100.0.2/22]" "Subnets " "Groups [role:Laptop]" "NotBefore 2022-12-06 21:34:25 +0000 UTC" "NotAFter 2024-05-13 17:37:27 +0000 UTC" "PublicKey 2c4828672fef1306124df94eb0fecd753e462e1bd4107f866f4e1a463550eb1b" "IsCA false" "Issuer 5b568aedaa5d97746e870f01a356ba474cf3251c0e743499ec668f93efa77f51"
If I then host a server on
[::]:3000 (ex, by creating an index.html file and then running
python3 -m http.server 3000 on a *nix host) on
alice-laptop and set up a firewall rule that allows this to be
bob-laptop, I can request it with
curl using the custom DNS resolver. (In a production environment,
you may choose to configure the system resolver.)
curl --dns-servers "100.100.0.1" http://alice-laptop:3000
<div>hello i am a website</div>
- The built-in DNS server will only respond to queries for known Nebula hosts and will not make upstream queries to a secondary DNS server (e.g. for supporting both internal DNS and public DNS.)
- A host's hostname is restricted to the name in its certificate.
- There is no way to register additional hostnames (e.g. additional CNAMEs for a given Nebula host, or additional A records for managing non-Nebula hosts.)
- Duplicate names in certificates will result in non-stable answers from the DNS server.
- If the name in the Nebula certificate is not a valid hostname, Lighthouse DNS will return an empty result.
An alternative approach to DNS would be to point public DNS records at private nebula IP addresses. For example, you can
create a public DNS A record pointing to
10.0.0.23 for your private team wiki. While this does make your internal IP
address visible to the internet, only users on your nebula network will be able to access it.
- How do hostnames turn into DNS host names?
- If the hostname is a valid DNS name, it will be resolved by the Lighthouse DNS resolver.
- Do Lighthouse DNS queries support Unicode?
- DNS only supports ASCII, but has support for Unicode via punycode, for
example:Nebula supports full unicode strings in the host name, but for hosts to be discovered via Lighthouse DNS, they must conform to the DNS spec. https://www.punycoder.com/ is a useful tool for conversion.
# `alice-xn--3s8h` = `alice-💻` in punycode.
dig @100.100.0.1 +short alice-xn--3s8h A
- DNS only supports ASCII, but has support for Unicode via punycode, for example:
- Are the domain names case-sensitive?
- Currently the DNS server matches names case sensitively, though DNS is meant to resolve case-insensitively. slackhq/nebula/issues/776 is tracking this issue.
- How do duplicate hostnames get resolved?
- In nebula, a node's IP address is the only identifier that MUST be globally unique. Therefore, it's possible to have two hosts with the same certificate name, but different IP addresses. Unfortunately, this can cause inconsistent results when querying for these hosts' hostname as the DNS query is ambiguous. The lighthouse will return the nebula IP of whichever host it has most recently performed a handshake with.
- How does the lighthouse learn about hosts?
- Hosts connect to the lighthouse as they normally do, and in doing so the lighthouse learns about their cert. Due to this fact, the lighthouse can only answer questions about hosts it has seen since last start.
- Can the lighthouse resolve its own name?
- As of nebula
v1.6.1, no, the lighthouse only responds about hosts it has handshaked with, it never handshakes with itself. slackhq/nebula/issues/271 is tracking this feature.
- As of nebula