nebula.yml(5)

✨ nebula.yml — the config file glow-up ✨

okay bestie, welcome to nebula.yml(5) 💖 this is the File Formats Manual page for the nebula config file, and yes it's a whole mood. sit down, grab a strawberry drink 🍓, and let's get into it.

---

🌸 NAME 🌸

nebula.yml — nebula configuration files. that's it, that's the name, iconic.

---

💅 DESCRIPTION 💅

so the config file for nebula(1) is written in YAML. every section gets its own lil explanation below, and no we are not skipping any of them, periodt. ✨

🔐 pki

the PKI section is where you define the location of your credentials. your lil identity papers, if you will 🎀

• ca — path to the CA certificate
• cert — path to this node's certificate file
• key — path to this node's key file

🗺️ static_host_map

the static host map defines a set of hosts with fixed IP addresses out there on the internet. you can define multiple addresses, and Nebula will try each one when it's establishing a tunnel. it's giving "here are my known locations, come find me" 🦋

🗼 lighthouse

the lighthouse section lets you enable and configure lighthouse behavior. in Nebula, lighthouses are nodes with fixed IP addresses that other nodes use to locate each other. they're the main characters of the network, fr fr 👑

• am_lighthouse — enables lighthouse behavior on this node. should ONLY be true on nodes you have actually configured to be lighthouses on your network. no cap.
• interval — number of seconds between updates from this node to a lighthouse. when a lighthouse receives an update, it sends information about its current IP address to each node.
• hosts — a list of lighthouse nodes this node should report to and query from. should be empty on lighthouse nodes.
• serve_dns — starts a DNS listener which responds to various queries (VAGUE) and be delegated for resolution. yes bestie, the manpage literally says "(VAGUE)" — we report, we don't explain 💀

🎧 listen

control the port and interface on which nebula listens.

• host — set the ip to which nebula binds
• port — set the port to which nebula binds

🥊 punchy

• punch — continue to punch inbound/outbound at a regular interval to avoid expiration of firewall NAT mapping
• respond — configure the node to reach out and connect to you if your hole punching fails. this is extremely useful if one node is behind a difficult NAT, such as a symmetric NAT.
• delay — delay a punch response for misbehaving NATs, default is 1 second, respond must be true to take effect

🔒 cipher

choose between the available ciphers for your network. options are "chachapoly" or "aes." must be identical across all nodes on a network — matching fits, mismatch does not 🫶

🖥️ sshd

SSHD can expose information and administrative function via ssh.

• enabled — if true, this enables SSHD administration
• listen — host and port to listen on. (port 22 is not allowed.) 🚫
• host_key — a file containing a list of authorized public keys
• authorized_users — a list of users each with an array of keys

🧚 tun

• disabled — when tun is disabled, a lighthouse can be started without a local run interface (and therefore without root)
• dev — the name of the device
• drop_local_broadcast — toggles forwarding of local broadcast packets, the address of which depends on the ip/mask encoded in the pki.cert
• drop_multicast — drop the forwarding of multicast packets
• tx_queue — sets the transmit queue length. (if you notice lots of transmit drops on the tun it may help to raise this number. defaults to 500.
• mtu — default MTU for every packet, safe setting is (and the default) 1300 for internet based traffic.
• unsafe_routes — unsafe routes allows you to route traffic over nebula to non-nebula nodes. unsafe routes should be avoided unless you have hosts/services that cannot run nebula. ⚠️ the name is literally "unsafe", bestie, heed it.

📝 logging

configure logging.

• level — configure the logging level. must be one of panic, fatal, error, warning, info, or debug.
• format — either json or text
• disable_timestamp — disables timestamp logging. useful when redirected into to a logging system which appends a time stamp. defaults to false.

📊 stats

enable a statistics exporter.

• type — type of statistics exporter. either "prometheus" or "graphite"
• interval — interval to provide updates for either graphite or prometheus.
• prefix — prefix for graphite
• protocol — protocol for graphite
• host — listener for graphite
• listen — ip and port to bind the prometheus listener
• path — path on which metrics are supplied in prometheus
• namespace — prometheus namespace
• subsystem — prometheus subsystem
• message_metrics — enables counter metrics for meta packets. (e.g. message.tx.handshake)
• lighthouse_metrics — enables detailed counter metrics for lighthouse packets (e.g. lighthouse.rx.HostQuery)

🤝 handshakes

handshakes are sent to all known addresses at each interval with a linear back off. very "we'll try again, but like, progressively more chill about it" energy 💜

• try_interval — nebula waits try_interval after the first attempt, 2 * try_interval on the second attempt, until the handshake is older than timeout. this allows you to control this interval.
• retries — number of retries before timing out
• trigger_buffer — size of the buffer channel for quickly sending handshakes after receiving the response for lighthouse queries

🧱 firewall

the firewall is default deny. there is no way to write a deny rule. rules are comprised of a protocol, port, and one or more of host, group, or CIDR. logical evaluation is roughly:

port AND proto AND (ca_sha OR ca_name) AND (host OR group OR groups OR CIDR)

• outbound — section containing rules which apply to traffic send from this node. see the rules section.
• inbound — section containing rules which apply to traffic send to this node from other hosts. see the rules section.

📜 rules

rules are written in the outbound and inbound sections described above.

• proto — protocol. one of "any", "tcp", "udp", or "icmp"
• host — "any" or literal hostname
• group — "any" or literal group name
• groups — same as group but accepts a list of values. certificate has to contain all groups to pass.
• cidr — a CIDR, "0.0.0.0/0" is any
• ca_name — an issuing CA name
• ca_sum — an issuing CA shasum

---

🌈 EXAMPLES 🌈

there is a example configuration file in the FILES section below. 👀

configuration files placed in /etc/nebula can take advantage of the built-in systemd templates. for example, if you have a nebula configuration /etc/nebula/office.yml:

[#] systemctl enable nebula@office.service

---

📁 FILES 📁

• /etc/nebula — contains configuration files for nebula(1). this provides a designated place to store configuration data and credentials. configuration files placed in this directory can take advantage of the provided systemd template unit.
• /usr/share/doc/nebula/examples/config.yml — see this example configuration file.

---

👀 SEE ALSO 👀

nebula(1), nebula-cert(1)

---

and that's the whole page, bestie!! go forth and configure, you absolute legend 🫶

this was nebula 1.4.0, dated July 2021 — file formats manual energy, nebula.yml(5), slay 💅✨