Skip to main content

lighthouse

lighthouse:
  am_lighthouse: false
  serve_dns: true
  dns:
    host: 0.0.0.0
    port: 53
  interval: 60
  hosts:
    - '192.168.100.1'

  remote_allow_list:
    '172.16.0.0/12': false
    '0.0.0.0/0': true
    '10.0.0.0/8': false
    '10.42.42.0/24': true

  local_allow_list:
    interfaces:
      tun0: false
      'docker.*': false
    '10.0.0.0/8': true

  advertise_addrs:
    - '1.1.1.1:4242'
    - '1.2.3.4:0' # port will be replaced with the real listening port

  calculated_remotes:
    10.0.10.0/24:
      - mask: 192.168.1.0/24
        port: 4242

lighthouse.am_lighthouse​

Default: False

am_lighthouse is used to enable lighthouse functionality for a node. This should ONLY be true on nodes you have configured to be lighthouses in your network

lighthouse.serve_dns​

Default: False

serve_dns optionally starts a DNS listener that responds to A and TXT queries and can even be delegated to for name resolution by external DNS hosts. To enable listening on IPv6 in addition to IPv4, set lighthouse.dns.host to '[::]'.

The DNS listener can only respond to requests about hosts it's aware of. For this reason, it can only be enabled on Lighthouses.

A records contain the Nebula IP for a host name and can be queried by any host that can reach the DNS listener, regardless of whether it is communicating over the Nebula network.

TXT records can only be queried over the Nebula network, and contain certificate information for the requested host IP address.

For example, if 192.168.100.1 was your Lighthouse node running a DNS server and you wanted to find the Nebula IP address of a host named web01:

$ dig @192.168.100.1 +short web01 A

192.168.100.5

Or if you wanted to get certificate information about the host:

$ dig +short @192.168.100.1 192.168.100.5 TXT

"Name: web01" "Ips: [192.168.100.5/24]" "Subnets []" "Groups [servers web]" "NotBefore 2021-06-15 14:19:22 +0000 UTC" "NotAFter 2022-04-28 21:49:15 +0000 UTC" "PublicKey dde33784fb2bbada73f8bf4cafbf9271dc864b770b1e44002f81563856711f7c" "IsCA false" "Issuer 91f795c52f601d3110ee5232b22c13a89a76d3e3fb89bed3c21929c873cb6ec9"
note

To allow hosts to make queries against the DNS server over the Nebula network, don't forget to allow access in the firewall.

The below example config will allow any host on the network to query the lighthouse for DNS

firewall:
  inbound:
    - port: 53
      proto: udp
      group: any

lighthouse.dns​

dns is used to configure the address (host) and port (port) the DNS server should listen on. By listening on the host's Nebula IP, you can make the DNS server accessible only on the Nebula network. Alternatively, listening on 0.0.0.0 will allow anyone that can reach the host to make queries.

The default value for dns.port is 53 but you must set an IP address.

See the serve_dns docs for more information.

lighthouse:
  dns:
    # The DNS host defines the IP to bind the dns listener to. This also allows binding to the nebula node IP.
    host: 0.0.0.0
    port: 53

lighthouse.interval​

Default: 10

interval specifies how often a nebula host should report itself to a lighthouse. By default, hosts report themselves to lighthouses once every 10 seconds. Use caution when changing this interval, as it may affect host discovery times in a large nebula network.

lighthouse.hosts​

warning

This should be empty on lighthouse nodes

hosts is a list of lighthouse hosts this node should report to and query from. The lighthouses listed here should be referenced by their nebula IP, not by the IPs of their physical network interfaces.

lighthouse:
  hosts:
    - '192.168.100.1'

lighthouse.remote_allow_list​

remote_allow_list allows you to control ip ranges that this node will consider when handshaking to another node. By default, any remote IPs are allowed. You can provide CIDRs here with true to allow and false to deny. The most specific CIDR rule applies to each remote. If all rules are "allow", the default will be "deny", and vice-versa. If both "allow" and "deny" rules are present, then you MUST set a rule for "0.0.0.0/0" as the default. Similarly if both "allow" and "deny" IPv6 rules are present, then you MUST set a rule for "::/0" as the default.

lighthouse:
  remote_allow_list:
    # Example to block IPs from this subnet from being used for remote IPs.
    '172.16.0.0/12': false
    # A more complicated example, allow public IPs but only private IPs from a specific subnet
    '0.0.0.0/0': true
    '10.0.0.0/8': false
    '10.42.42.0/24': true

lighthouse.local_allow_list​

local_allow_list allows you to filter which local IP addresses we advertise to the lighthouses. This uses the same logic as remote_allow_list, but additionally, you can specify an interfaces map of regular expressions to match against interface names. The regexp must match the entire name. All interface rules must be either true or false (and the default will be the inverse). CIDR rules are matched after interface name rules. Default is all local IP addresses.

lighthouse:
  local_allow_list:
    # Example to block tun0 and all docker interfaces.
    interfaces:
      tun0: false
      'docker.*': false
    # Example to only advertise this subnet to the lighthouse.
    '10.0.0.0/8': true

lighthouse.advertise_addrs​

advertise_addrs are routable addresses that will be included along with discovered addresses to report to the lighthouse. The format is "ip:port". port can be 0, in which case the actual listening port will be used in its place, useful if listen.port is set to 0. This option is mainly useful when there are static IP addresses the host can be reached at that nebula can not typically discover on its own (e.g. when port forwarding or when the node has multiple paths to the internet.)

lighthouse.calculated_remotes​

danger

EXPERIMENTAL: This option may change or disappear in the future. This setting allows nebula to "guess" what the remote might be for a host while it waits for the lighthouse response.

For any Nebula IPs in the range, it will apply the mask and add the calculated IP as the initial remote (while it waits for the response from the lighthouse). Both CIDRs must have the same mask size. For example, Nebula IP 10.0.10.123 will have a calculated remote of 192.168.1.123.

calculated_remotes:
  10.0.10.0/24:
    - mask: 192.168.1.0/24
      port: 4242