DOCSEARCHbyAlgolia
Submit Docs

Nebula Documentation

website·Indexed 34 days ago

https://nebula.defined.net/docs/

Documentation for Nebula, a scalable overlay networking tool. Includes guides on NAT traversal, lighthouse discovery, PKI configuration, firewall security groups, and relay support introduced in v1.6.0. Covers configuration for TUN interfaces, SSH debugging consoles, and Prometheus stats integration.

Tokens
16.5K
Snippets
99
Records
134
Agent score
67%

What's inside Nebula

  1. Overview of Nebula overlay networking

    Nebula is a self-hosted, peer-to-peer, layer 3 virtual overlay network designed for speed, security, and scalability. It creates on-demand, encrypted tunnels between hosts across any IP network without requiring open firewall ports. It supports TCP, UDP, and ICMP traffic via a TUN adapter with split-tunneling and utilizes the Noise Protocol Framework for mutual authentication.

  2. Overview of Nebula unsafe_routes for subnet routing

    The unsafe_routes feature allows Nebula to route traffic destined for a specific local subnet through a specific host on the overlay network. This enables remote access to devices on a physical LAN (e.g., printers, proprietary hardware) that cannot have the Nebula agent installed.

  3. Define local network range hints using local_range

    The local_range configuration option is used to define a hint about the local network range. This helps the system speed up the discovery of the fastest path to a Nebula node that is network-adjacent. Note that local_range is deprecated in favor of preferred_ranges.
    local_range: '172.16.0.0/24'

  4. Understand Nebula network components

    A Nebula network consists of three primary components:

    • Lighthouse: A specialized Nebula host that tracks all other hosts in the network and helps them discover each other.
    • Certificate Authority (CA): Consists of a CA certificate (distributed to all hosts) and a private key (kept secret/offline). The CA is used to sign keys for every host added to the network to ensure trust and prevent impersonation.
    • Hosts: Any node in the network (server, laptop, mobile device). Each host has a unique certificate (containing name, IP, and group membership) and a private key used to validate identity when creating tunnels.

  5. Prerequisites for configuring unsafe_routes

    To configure subnet routing via unsafe_routes, you need:

    1. A working Nebula overlay network with a lighthouse and at least two hosts: one Linux host acting as the router and one client host (Linux, macOS, or Windows).
    2. The nebula-cert binary for signing certificates.
    3. The ca.key and ca.crt files for the overlay network.
    4. Root access to the Linux router host and the client host.
    5. A CA capable of signing certificates with subnets. If the CA was created without the -subnets flag, it is compatible. You can verify this by running nebula-cert print -path ca.crt and checking if the Subnets field is empty or contains the target CIDR.
    nebula-cert print -json -path ca.crt | jq .details

  6. Use PKCS11 for private key storage

    Starting in v1.10, Nebula supports using a PKCS11 URL to reference a private key stored in an HSM.

    Prerequisites:

    • Nebula must be built from source with cgo and pkcs11 tags (e.g., using make bin-pkcs11).
    • Only P256 is supported; Curve25519 is not supported via PKCS11.
    • The key must be uniquely identifiable via id and object parameters.
    • The key's CKA_DERIVE attribute must be CK_TRUE.
    • Derivations must be possible via the CKM_ECDH1_DERIVE mechanism.
    • The HSM must allow the derivation output to be extracted (CKA_EXTRACTABLE == CK_TRUE).
    pki:
  # Reference pin via file
  key: 'pkcs11:id=1234;object=nebula%20key?module-path=/usr/lib64/pkcs11/my-module.so&pin-source=/path/to/pin-file'
  # OR specify the pin directly
  # key: "pkcs11:id=1234;object=nebula%20key?module-path=/usr/lib64/pkcs11/my-module.so&pin-value=1234"

  8. Route traffic to non-Nebula nodes using unsafe routes

    Unsafe routes allow routing traffic over Nebula to hosts or services that cannot run the Nebula agent.

    Critical Requirement: The Nebula certificate of the via node MUST have the target route defined in its subnets list, otherwise traffic will be silently refused.

    tun:
  unsafe_routes:
    - route: 172.16.1.0/24
      via: 192.168.100.99
      mtu: 1300
      metric: 100
      install: true # Whether to install this route in the system routing table

  9. Upgrade Nebula hosts to support v2 certificates and IPv6

    To enable IPv6 support and v2 certificate formats, all hosts in the network must be upgraded to Nebula v1.10 or later. Older versions cannot validate v2 certificates. This upgrade must be completed across all hosts before proceeding with the certificate migration.

  10. Clean up after v2 certificate migration

    Once all hosts are migrated to v2 certificates and the network is stable, perform the following cleanup to remove legacy v1 dependencies:

    1. Remove the v1 CA certificate from the pki.ca trust bundle on all hosts.
    2. Reload Nebula on all hosts.
    3. Delete any backup files containing v1 certificates and keys.

  11. Create a dedicated system user for Nebula

    To improve security on Linux, run Nebula as a dedicated unprivileged system user instead of root. This limits the impact of a potential compromise. You must create the user and ensure they own the configuration directory with restricted permissions to protect private keys and CA material.
    sudo useradd --system --shell /usr/sbin/nologin nebula
sudo chown -R nebula:nebula /etc/nebula
sudo chmod 0700 /etc/nebula

  12. View Nebula logs and service status on macOS

    For installations using Homebrew on Apple Silicon, logs are stored in /opt/homebrew/var/log/nebula.*. On Intel processors, the default prefix is /usr/local. You can view logs via the terminal or by opening /opt/homebrew/var/log/nebula.log in the Console.app (use Cmd + Shift + G in the file picker to enter the path).
    # Follow Nebula logs
sudo tail -f /opt/homebrew/var/log/nebula.*

# Check Nebula service status
launchctl list homebrew.mxcl.nebula