Nebula

https://nebula.defined.net/docs/
Admin
Nebula is an open-source, self-hosted, peer-to-peer overlay networking tool designed for fast,...
Tokens:39,006
Snippets:372
Trust Score:9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Set up and start Nebula host

Source: https://nebula.defined.net/docs/guides/quick-start

Commands to set up and start a Nebula host (named server in the example): create /etc/nebula, move the host config, CA certificate, and host certificate/key (renaming them to host.crt and host.key), then launch the nebula binary with the config file.

```bash
mkdir /etc/nebula  

```

```bash
mv config.yaml /etc/nebula/config.yaml  
mv ca.crt /etc/nebula/ca.crt  
mv server.crt /etc/nebula/host.crt  
mv server.key /etc/nebula/host.key  

```

```bash
./nebula -config /etc/nebula/config.yaml  

```

--------------------------------

### tun.unsafe_routes example

Source: https://nebula.defined.net/docs/config/tun

Unsafe routes configuration example with via, mtu, metric, and install options.

```yaml
tun:  
  unsafe_routes:  
    - route: 172.16.1.0/24  
      via: 192.168.100.99  
      mtu: 1300  
      metric: 100  
      install: true # controls whether this route is installed in the systems routing table.  

```

--------------------------------

### tun.routes example

Source: https://nebula.defined.net/docs/config/tun

Route-based MTU override example for the tun.routes option.

```yaml
tun:  
  routes:  
    - mtu: 8800  
      route: 10.0.0.0/16  

```

--------------------------------

### Set up and start Nebula lighthouse

Source: https://nebula.defined.net/docs/guides/quick-start

Commands to set up and start a Nebula lighthouse: create /etc/nebula, move the lighthouse config, CA certificate, and host certificate/key (renaming them to host.crt and host.key), then launch the nebula binary with the config file.

```bash
mkdir /etc/nebula  

```

```bash
mv config-lighthouse.yaml /etc/nebula/config.yaml  
mv ca.crt /etc/nebula/ca.crt  
mv lighthouse.crt /etc/nebula/host.crt  
mv lighthouse.key /etc/nebula/host.key  

```

```bash
./nebula -config /etc/nebula/config.yaml  

```

--------------------------------

### static_map configuration example

Source: https://nebula.defined.net/docs/config/static-map

Example configuration for the static_map section, showing the default values for network, cadence, and lookup_timeout.

```yaml
static_map:  
  network: ip4  
  cadence: 30s  
  lookup_timeout: 250ms  

```

--------------------------------

### Full tun configuration example

Source: https://nebula.defined.net/docs/config/tun

Complete tun configuration block showing all available options with defaults and comments.

```yaml
tun:  
  disabled: false  
  dev: nebula1  
  drop_local_broadcast: false  
  drop_multicast: false  
  tx_queue: 500  
  mtu: 1300  
  routes:  
    - mtu: 8800  
      route: 10.0.0.0/16  
  unsafe_routes:  
    - route: 172.16.1.0/24  
      via: 192.168.100.99  
      mtu: 1300 # mtu will default to tun mtu if this option is not specified  
      install: true # controls whether this route is installed in the systems routing table.  

```

--------------------------------

### handshakes configuration example

Source: https://nebula.defined.net/docs/config/handshake

Example configuration for the handshakes section, setting try_interval to 100ms, retries to 10, and trigger_buffer to 64.

```yaml
handshakes:  
  try_interval: 100ms  
  retries: 10  
  trigger_buffer: 64  
```

--------------------------------

### Logging configuration example

Source: https://nebula.defined.net/docs/config/logging

Shows the default logging configuration block with level, format, and commented-out timestamp options.

```yaml
logging:  
  level: info  
  format: text  
  #disable_timestamp: true  
  #timestamp_format: "2006-01-02T15:04:05.000Z07:00"  

```

--------------------------------

### relay configuration example

Source: https://nebula.defined.net/docs/config/relay

Example configuration for enabling relay support in Nebula. Sets the relay host list, enables acting as a relay with am_relay, and enables using relays with use_relays.

```yaml
relay:  
  relays:  
    - 192.168.100.1  
  am_relay: false  
  use_relays: true  

```

--------------------------------

### Configure stats for Graphite or Prometheus

Source: https://nebula.defined.net/docs/config/stats

Example configuration for the stats section, showing both graphite and prometheus options. Note that the example includes both types in one block, but in practice only one type should be set. The interval is a Go duration, recommended to be 60s. message_metrics and lighthouse_metrics default to false.

```yaml
stats:  
  type: graphite  
  prefix: nebula  
  protocol: tcp  
  host: 127.0.0.1:9999  
  interval: 10s  
  
  type: prometheus  
  listen: 127.0.0.1:8080  
  path: /metrics  
  namespace: prometheusns  
  subsystem: nebula  
  interval: 10s  
  
  message_metrics: false  
  
  lighthouse_metrics: false  

```

--------------------------------

### ECMP support for unsafe_routes example

Source: https://nebula.defined.net/docs/config/tun

Example showing multiple gateways for the same route with equal and custom weighting for ECMP support.

```yaml
unsafe_routes:  
  # Multiple gateways with equal weighting (default weight: 1)  
  - route: 192.168.100.0/24  
    via:  
      - gateway: 10.0.0.1  
      - gateway: 10.0.0.2  
  
  # Multiple gateways with custom weights  
  - route: 192.168.101.0/24  
    via:  
      - gateway: 10.0.0.1  
        weight: 10  
      - gateway: 10.0.0.2  
        weight: 5  

```

--------------------------------

### Ping example lighthouse to verify network

Source: https://nebula.defined.net/docs/guides/quick-start

Ping the example lighthouse at 192.168.100.1 to verify that Nebula hosts can communicate (assuming ICMP is allowed).

```bash
ping 192.168.100.1  

```

--------------------------------

### Configure nftables routing for Nebula

Source: https://nebula.defined.net/docs/guides/unsafe_routes

Create an nftables configuration file (e.g. /etc/nftables-routing.conf) that sets up NAT masquerading and forwarding rules for the example networks. Load it with `sudo nft -f /etc/nftables-routing.conf` and verify with `sudo nft list table nebula_routing`. These rules are not persistent across reboots; you must configure the file to be loaded at boot.

```nftables
table ip nebula_routing  
delete table ip nebula_routing  
table ip nebula_routing {  
  chain postrouting {  
    type nat hook postrouting priority srcnat; policy accept;  
    ip saddr 192.168.100.0/24 ip daddr 192.168.86.0/24 counter masquerade  
  }  
  
  chain forward {  
    type filter hook forward priority filter; policy accept;  
    ct state related,established counter accept  
    iifname nebula1 oifname enp6s0 ip saddr 192.168.100.0/24 ip daddr 192.168.86.0/24 counter accept  
  }  
}  

```

```bash
sudo nft -f /etc/nftables-routing.conf  

```

```bash
$ sudo nft list table nebula_routing  
table ip nebula_routing {  
	chain postrouting {  
		type nat hook postrouting priority srcnat; policy accept;  
		ip saddr 192.168.100.0/24 ip daddr 192.168.86.0/24 counter packets 1 bytes 84 masquerade  
	}  
  
	chain forward {  
		type filter hook forward priority filter; policy accept;  
		ct state established,related counter packets 134763 bytes 123879509 accept  
		iifname "nebula1" oifname "enp6s0" ip saddr 192.168.100.0/24 ip daddr 192.168.86.0/24 counter packets 726 bytes 85482 accept  
	}  
}  

```

--------------------------------

### punchy configuration example

Source: https://nebula.defined.net/docs/config/punchy

Example YAML configuration for the punchy section. Enables periodic empty packets with a 1s delay and response handshakes after a 5s respond delay.

```yaml
punchy:  
  punch: true  
  delay: 1s  
  respond: true  
  respond_delay: 5s  

```

--------------------------------

### lighthouse.local_allow_list YAML configuration example

Source: https://nebula.defined.net/docs/config/lighthouse

Filters local IP addresses advertised to lighthouses. The interfaces map uses regex patterns that must match the entire interface name; all interface rules must be either true or false, with the default being the inverse. CIDR rules are matched after interface name rules. The example blocks tun0 and all docker interfaces, and only advertises the 10.0.0.0/8 subnet.

```yaml
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  

```

--------------------------------

### static_host_map configuration example

Source: https://nebula.defined.net/docs/guides/host-discovery

Shows a static_host_map configuration mapping Nebula IPs to underlay addresses. Entries can be IPv4, DNS names, or bracketed IPv6 literals. Nebula tries each address until a handshake succeeds.

```yaml
static_host_map:  
  '192.168.100.1': ['203.0.113.42:4242']  
  '192.168.100.5': ['server.example.com:4242', '[2001:db8::5]:4242']  

```

--------------------------------

### Get help for a specific command

Source: https://nebula.defined.net/docs/guides/debug-ssh-commands

Use help <command> to see detailed usage information for a command, such as list-hostmap.

```text
> help list-hostmap  
list-hostmap - List all known previously connected hosts  
  -by-index  
    	gets all hosts in the hostmap from the index table  
  -json  
    	outputs as json with more information  
  -pretty  
    	pretty prints json, assumes -json  

```

--------------------------------

### sshd configuration example

Source: https://nebula.defined.net/docs/config/sshd

Enables the Nebula SSH debugging console, listening on 127.0.0.1:2222 with a host key and authorized users or trusted CAs. The host key must be generated first with ssh-keygen and owned by root.

```yaml
sshd:  
  enabled: true  
  listen: 127.0.0.1:2222  
  host_key: /path/to/ssh_host_ed25519_key  
  authorized_users:  
    - user: steeeeve  
      keys:  
        - '[ssh public key string]'  
  trusted_cas:  
    - '[ssh ca public key string]'  

```

--------------------------------

### Check macOS service status with launchctl

Source: https://nebula.defined.net/docs/guides/viewing-nebula-logs

Lists the Homebrew-managed Nebula service on macOS and shows example output. The output includes the log paths, program path, and configuration file used.

```bash
launchctl list homebrew.mxcl.nebula  

```

```bash
{  
	"StandardOutPath" = "/opt/homebrew/var/log/nebula.log";  
	"LimitLoadToSessionType" = "Aqua";  
	"StandardErrorPath" = "/opt/homebrew/var/log/nebula.log";  
	"Label" = "homebrew.mxcl.nebula";  
	"OnDemand" = false;  
	"LastExitStatus" = 256;  
	"Program" = "/opt/homebrew/opt/nebula/bin/nebula";  
	"ProgramArguments" = (  
		"/opt/homebrew/opt/nebula/bin/nebula";  
		"-config";  
		"/opt/homebrew/etc/nebula/config.yml";  
	);  
};  

```

--------------------------------

### Static host map and lighthouse configuration for a non-lighthouse host

Source: https://nebula.defined.net/docs/guides/host-discovery

Every host must statically map each lighthouse's address before discovery can work. The example shows a host that is not a lighthouse (am_lighthouse: false) listing the lighthouse's fixed address in static_host_map and in lighthouse.hosts; the comment marks the entry that must match the lighthouse's own address.

```yaml
static_host_map:  
  '192.168.100.1': ['203.0.113.42:4242'] # the lighthouse  
  
lighthouse:  
  am_lighthouse: false  
  hosts:  
    - '192.168.100.1' # matches the static entry above  

```

--------------------------------

### Configure sshd section in Nebula config

Source: https://nebula.defined.net/docs/guides/debug-ssh-commands

Example configuration for the sshd section. Set listen to localhost for local debugging or to your nebula IP for access over the overlay network. Replace steeeeve and [ssh public key string] with your user and public key.

```yaml
sshd:  
  enabled: true  
  listen: 127.0.0.1:2222  
  host_key: /path/to/ssh_host_ed25519_key  
  authorized_users:  
    - user: steeeeve  
      keys:  
        - '[ssh public key string]'  

```

--------------------------------

### Configure iptables routing for Nebula

Source: https://nebula.defined.net/docs/guides/unsafe_routes

Add iptables rules for NAT masquerading and forwarding for the example networks, replacing `nebula1` and `epn5s0` with the correct interface names if necessary. Verify the rules with `sudo iptables -vL` (shows the second and third rules) and `sudo iptables -t nat -L` (shows the first rule). These rules are not persistent across reboots; you may need to run additional commands (e.g. `iptables-save`) to save them.

```bash
sudo iptables -t nat -A POSTROUTING -s 192.168.100.0/24 -d 192.168.86.0/24 -j MASQUERADE  
sudo iptables -I FORWARD 1 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT  
sudo iptables -I FORWARD 2 -i nebula1 -o enp5s0 -s 192.168.100.0/24 -d 192.168.86.0/24 -j ACCEPT  

```

```bash
$ sudo iptables -vL  
Chain INPUT (policy ACCEPT 10M packets, 6461M bytes)  
 pkts bytes target     prot opt in     out     source               destination  
  
Chain FORWARD (policy ACCEPT 86 packets, 11057 bytes)  
 pkts bytes target     prot opt in     out     source               destination  
 1034 1469K ACCEPT     all  --  epn6s0 nebula1  anywhere             anywhere             ctstate RELATED,ESTABLISHED  
    0     0 ACCEPT     all  --  nebula1 enp6s0  192.168.100.0/24     192.168.86.0/24  
  
Chain OUTPUT (policy ACCEPT 18M packets, 58G bytes)  
 pkts bytes target     prot opt in     out     source               destination  

```

```bash
$ sudo iptables -t nat -L  
Chain PREROUTING (policy ACCEPT)  
target     prot opt source               destination  
  
Chain INPUT (policy ACCEPT)  
target     prot opt source               destination  
  
Chain POSTROUTING (policy ACCEPT)  
target     prot opt source               destination  
MASQUERADE  all  --  192.168.100.0/24     192.168.86.0/24  
  
Chain OUTPUT (policy ACCEPT)  
target     prot opt source               destination  

```

--------------------------------

### Query A record with dig

Source: https://nebula.defined.net/docs/guides/using-lighthouse-dns

Use this command to resolve a hostname to its Nebula IP address via the lighthouse. The example queries the host `alice-laptop` at the lighthouse IP `100.100.0.1` and returns the IP `100.100.0.2`.

```bash
dig @100.100.0.1 +short alice-laptop A  
100.100.0.2  

```

--------------------------------

### Sign host certificates with nebula-cert

Source: https://nebula.defined.net/docs/guides/quick-start

Use these commands on a host with the Nebula certificate authority to generate signed certificates for each host. The example assigns IP addresses from the 192.168.100.x/24 subnet and demonstrates nebula groups for later traffic rules. Run each command once per host, replacing the name and IP as needed.

```bash
./nebula-cert sign -name "lighthouse1" -ip "192.168.100.1/24"  
./nebula-cert sign -name "laptop" -ip "192.168.100.5/24" -groups "laptop"
./nebula-cert sign -name "server" -ip "192.168.100.10/24" -groups "ssh"

```

--------------------------------

### View Linux logs with journalctl

Source: https://nebula.defined.net/docs/guides/viewing-nebula-logs

Follows the Nebula service logs on Linux systems using systemd. Requires installation via a package manager or the example systemd unit from the GitHub repository.

```bash
journalctl --unit=nebula --follow  

```

--------------------------------

### Check Linux service status with systemctl

Source: https://nebula.defined.net/docs/guides/viewing-nebula-logs

Checks the status of the Nebula service on Linux and shows example output. The output includes the service state, main PID, memory usage, and the command line used to start Nebula.

```bash
systemctl status nebula  

```

```bash
# outputs  
● nebula.service - Nebula overlay networking tool  
     Loaded: loaded (/etc/systemd/system/nebula.service; enabled; vendor preset: enabled)  
     Active: active (running) since Wed 2022-11-30 16:07:48 CST; 2min 3s ago  
   Main PID: 546 (nebula)  
      Tasks: 10 (limit: 4560)  
     Memory: 19.2M  
     CGroup: /system.slice/nebula.service  
             └─546 /usr/local/bin/nebula -config /etc/nebula/config.yml  
  
# ... shows nebula logs ...  

```

--------------------------------

### List available SSH debug commands with help

Source: https://nebula.defined.net/docs/guides/debug-ssh-commands

Run help to see all available commands in the Nebula SSH debug server.

```text
steeeeve@nebula > help  
Available commands:  
change-remote - Changes the remote address used in the tunnel for the provided vpn ip  
close-tunnel - Closes a tunnel for the provided vpn ip  
create-tunnel - Creates a tunnel for the provided vpn ip and address  
device-info - Prints information about the network device.  
help - prints available commands or help <command> for specific usage info  
list-hostmap - List all known previously connected hosts  
list-lighthouse-addrmap - List all lighthouse map entries  
list-pending-hostmap - List all handshaking hosts  
log-format - Gets or sets the current log format  
log-level - Gets or sets the current log level  
logout - Ends the current session  
mutex-profile-fraction - Gets or sets runtime.SetMutexProfileFraction  
print-cert - Prints the current certificate being used or the certificate for the provided vpn ip  
print-relays - Prints json details about all relay info  
print-tunnel - Prints json details about a tunnel for the provided vpn ip  
query-lighthouse - Query the lighthouses for the provided vpn ip  
reload - Reloads configuration from disk, same as sending HUP to the process  
save-heap-profile - Saves a heap profile to the provided path  
save-mutex-profile - Saves a mutex profile to the provided path  
start-cpu-profile - Starts a cpu profile and write output to the provided file  
stop-cpu-profile - Stops a cpu profile and writes output to the previously provided file  
version - Prints the currently running version of nebula  

```

--------------------------------

### Logging timestamp_format example

Source: https://nebula.defined.net/docs/config/logging

Sets the timestamp format to RFC3339 with millisecond precision.

```yaml
timestamp_format: "2006-01-02T15:04:05.000Z07:00"

```

--------------------------------

### Run Nebula with unsafe_routes and verify output

Source: https://nebula.defined.net/docs/guides/unsafe_routes

Run Nebula with the new configuration using sudo nebula -config config.yml. The output shows a WARN line indicating the unsafe route is being used, and the interface becomes active on utun10 with network 192.168.100.11/24. After this, hosts on the 192.168.86.0/24 home LAN should be reachable.

```bash
sudo nebula -config config.yml  
INFO[0000] Firewall rule added           firewallRule="map[caName: caSha: direction:outgoing endPort:0 groups:[] host:any ip: proto:0 startPort:0]"  
INFO[0000] Firewall rule added           firewallRule="map[caName: caSha: direction:incoming endPort:0 groups:[] host:any ip: proto:1 startPort:0]"  
INFO[0000] Firewall started              firewallHash=570dd0546e17b139da845c05717d6dc2005fa7083292e1e8f797affab434c4f4  
WARN[0000] Adding UNSAFE Route           route=192.168.86.0/24 via=192.168.100.10  
INFO[0000] Main HostMap created          network=192.168.100.11/24 preferredRanges="[]"  
INFO[0000] UDP hole punching enabled  
INFO[0000] Nebula interface is active    build=1.5.0 interface=utun10 network=192.168.100.11/24 udpAddr="[::]:57027"  

```

--------------------------------

### View macOS logs with tail

Source: https://nebula.defined.net/docs/guides/viewing-nebula-logs

Follows Nebula logs on macOS when installed via Homebrew on Apple Silicon. On Intel processors, use /usr/local instead of /opt/homebrew as the prefix.

```bash
sudo tail -f /opt/homebrew/var/log/nebula.*  

```

--------------------------------

### tunnels configuration example

Source: https://nebula.defined.net/docs/config/tunnels

YAML configuration block that enables automatic dropping of inactive tunnels and sets the inactivity timeout to 10 minutes. Use this to enable tunnel lifecycle management.

```yaml
tunnels:
  drop_inactive: false
  inactivity_timeout: 10m

```

--------------------------------

### Print and sign new host certificate with nebula-cert

Source: https://nebula.defined.net/docs/guides/rotating-certificate-authority

Inspect an existing host certificate with nebula-cert print, then sign a new certificate with the same details using nebula-cert sign. The sign command creates new host1.crt and host1.key files; copy them to the host and update pki.cert and pki.key in the Nebula config.

```shell
$ nebula-cert print -path host1.crt  
NebulaCertificate {  
	Details {  
		Name: host1  
		Ips: [  
			192.168.100.5/24  
		]  
		Subnets: [  
			10.0.0.0/8  
		]  
		Groups: [  
			"prod"  
			"api"  
        ]  
		Not before: 2023-02-30 16:22:00 -0400 EDT  
		Not After: 2023-07-30 16:08:16 -0400 EDT  
		Is CA: false  
		Issuer: d5978d6d54a58e4685551708c5f57fbdd3774be67d470ecb0033cf70bbf5fbb5  
		Public key: 4a915591ff1a6869acb085d0292cbd25ba88624b9729420acb20d03644e0b016  
		Curve: CURVE25519  
	}  
	Fingerprint: 92efefd0575f71c10973dc96d9e2111d62703139383855f5a6a74feea68af05e  
	Signature: dc680011a11078fc00cce84d176662f54c96fa071d1bd49d5410a987f5743c3a641e27142ec19d5ed1929d5464bcdffe927a787b3a4f200b008d84821e3c4a0d  
}  
$ nebula-cert sign -name "host1" -subnets "10.0.0.0/8" -ip "192.168.100.5/24" -groups "prod,api"  
```
Tokens:
Raw