Nebula Overlay Networking

The cert library provides tools for interacting with Nebula-style certificates and authorities. It supports two versions of the certificate format:

• v1: A deprecated version based on protobuf.
• v2: The current, recommended version which uses asn.1 DER encoding. v2 supports both IPv4 and IPv6 and is designed to be more resilient to future certificate format changes.

When building applications, ensure you are targeting the v2 format for compatibility and future-proofing.

While the default is Curve25519, you can use NIST Curve P256 for specific compliance requirements. When creating a CA with the P256 curve, the CA will sign certificates using ECDSA P256, and hosts will use P256 for ECDH handshakes.

./nebula-cert ca -curve P256

To run a Nebula node, you need the Nebula binary, a config.yml file, the CA certificate (ca.crt), and the node's specific certificate and key ({host}.crt and {host}.key).

Configuration Requirements

• Lighthouse Node: Must have am_lighthouse: true set in config.yml.
• Standard Hosts: Must define the lighthouse in the static_host_map section and add the lighthouse to the lighthouse's hosts section.

Running the service

Execute the binary pointing to your configuration file:

./nebula -config /path/to/config.yml

Run the built Nebula image using docker run. Note the following requirements:

• Network Capabilities: The --cap-add NET_ADMIN flag is required to allow Nebula to create the tun adapter on the host. If you have disabled the tun device in your configuration, this capability is not necessary.
• Configuration: Use --volume ./config:/config to mount a local directory containing your config.yml and any other required files into the container's /config directory.
• Network Mode: The --network host flag is used to run the container on the host's network stack.

docker run \
    --name nebula \
    --network host \
    --cap-add NET_ADMIN \
    --volume ./config:/config \
    --rm \
    nebulaoss/nebula

For compliance requirements, Nebula can be built using the GOEXPERIMENT=boringcrypto setting. Use the following make targets:

• make bin-boringcrypto
• make release-boringcrypto

To establish the root of trust for your Nebula network, use the nebula-cert tool to create a Certificate Authority. This generates ca.key and ca.cert files.

Security Warning: The ca.key file is extremely sensitive as it is used to sign all node certificates. Store it securely and never copy it to individual nodes. By default, CAs have a 1-year lifetime.

./nebula-cert ca -name "Myorganization, Inc"

You can install Nebula on various Linux distributions and macOS using the following package managers:

• Arch Linux: sudo pacman -S nebula
• Fedora Linux: sudo dnf install nebula
• Debian Linux: sudo apt install nebula
• Alpine Linux: sudo apk add nebula
• macOS (Homebrew): brew install nebula
• Docker: docker pull nebulaoss/nebula

Once you have a CA, use nebula-cert sign to generate certificates for individual nodes. You can assign IP addresses and membership to user-defined groups for traffic filtering.

Example for a network using 192.168.100.x/24:

./nebula-cert sign -name "lighthouse1" -ip "192.168.100.1/24"
./nebula-cert sign -name "laptop" -ip "192.168.100.2/24" -groups "laptop,home,ssh"
./nebula-cert sign -name "server1" -ip "192.168.100.9/24" -groups "servers"
./nebula-cert sign -name "host3" -ip "192.168.100.10/24"

To build Nebula from source, ensure you have go installed, clone the repository, and navigate to the nebula directory.

• Build for all platforms: make all
• Build for a specific platform (e.g., Windows): make bin-windows

The v1 certificate format is defined in cert_v1.proto. To use these definitions in Go, you must have protoc installed. You can use the provided Makefile to compile the definitions using the specific protobuf version required by the project's go.mod.

make proto

To use an HSM instead of generating keys locally, provide a PKCS#11 URL using the -pkcs11 flag.

Important Constraints:

• When using -pkcs11, you cannot use the -out-key flag because the private key never leaves the HSM.
• The only supported curve for PKCS#11 is P256.

# Example: Using an HSM (requires -pkcs11, cannot use -out-key)
nebula-cert ca -name "HSM CA" -pkcs11 "url_to_p11_module" -out-crt ca.crt -curve P256