--- name: "nebula.yml" section: "5" platform: "linux" package: "nebula" version: "1.9.3+dfsg-6+b2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/nebula.yml" --- # nebula.yml(5) nebula configuration files ## NAME **nebula.yml** - nebula configuration files ## DESCRIPTION Configuration file for [nebula(1)](/nebula/1.md) are written in YAML. Each section is described below: ### pki The PKI section defines the location of credentials - 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 on the internet. Multiple addresses may be defined and Nebula will try each when establishing a tunnel. ### lighthouse The lighthouse section allows the entablement and configuration of lighthouse behavior. In Nebula, lighthouses are nodes with ip fixed addresses which other nodes can use to located each other. - am\_lighthouse Enables lighthouse behavior on this node. Should ONLY be true on nodes you have configured to be lighthouses on your network. - 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. ### 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. ### 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. ### 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. - 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)](/nebula/1.md). 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/1.md), [nebula-cert(1)](/nebula-cert/1.md)