nebula.yml - nebula configuration files
Configuration file for nebula(1) are written in YAML. Each section
is described below:
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
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.
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.
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
- 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
Choose between the available ciphers for your network. Options are
"chachapoly" or "aes." Must be identical across all
nodes on a network.
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
- 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.
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.
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 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
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 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
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
- /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.