Year of the IPv6 overlay network

Nebula 1.10 is here with IPv6 support in the overlay network, multiple Nebula IPs per host, a new certificate format, and more. This release represents over a year of development effort across numerous pull requests; You can see the full scope in the Nebula v1.10 milestone and the changelog. IPv6 overlay support was one of our oldest and most requested features and it has finally landed in December 2025!

You can grab this update for Nebula OSS in all the usual places, including:

• GitHub
• Homebrew
• Docker
• iOS and iPadOS (Mobile Nebula on the App Store)
• Android (Mobile Nebula on the Google Play Store)
• and various linux distributions.

See the v1.10.0 changelog for the full list of features in this release.

IPv6 adoption, like Linux on the desktop, has been a decades long journey. Almost all devices made in the last decade or two support IPv6, but network admins following outdated security recommendations often disable it, and aging network equipment may not yet support IPv6. With IPv4 address exhaustion becoming increasingly problematic and IPv6 providing virtually unlimited address space, full IPv6 support is table stakes for any modern networking solution.

Supporting IPv6 in Nebula unlocks key capabilities that make network transitions smoother and more flexible. The vast IPv6 address space eliminates addressing conflicts which often occur when connecting multiple IPv4 subnets with overlapping ranges, allowing Nebula to connect multiples jobsites seamlessly. And by adopting IPv6 in your overlay network today, you’re preparing for the inevitable IPv6-dominant future without waiting for your physical networking infrastructure to support it.

Upgrading Nebula to use IPv6 is as straightforward as 1, 2, 3… The process involves upgrading everyone to Nebula v1.10, creating a v2 CA, trusting it on every host, and minting all hosts v2 certs with IPv6 and IPv4 overlay addresses, after which you’ll have a mixed IPv4/IPv6 overlay network up and running.

The beauty of this approach is that you can run both certificate formats simultaneously during the transition, ensuring zero downtime for your network. For detailed steps, check out our comprehensive guide on how to upgrade your OSS Nebula network.

To support IPv6 and multiple IP addresses per host, we’ve introduced a new v2 certificate format that moves from Protocol Buffers to ASN.1. The original v1 format had no true canonical representation and was limited to only supporting IPv4 addresses. The new v2 format fixes these problems. Nebula v1.10.0 supports both formats simultaneously through a unified interface, allowing for seamless migration where hosts can carry both certificate types during the transition period.

The technical details

Protobufs are not canonical, which means anything that marshals the wire format might marshal it differently than the CA did when it signed the certificate, making the signature invalid. It’s never come up in practice but it has been noticed, pretty early after open sourcing (slackhq/nebula#14).

This primarily comes up because we take the public key out of the certificate for a handshake since the noise header contains it, which saves space on the wire. On receipt we take the public key out of the noise header, shove it back into the certificate and marshal it, then verify the signature. If protobuf ever marshalled the struct differently than earlier versions, we would have invalid certs.

ASN.1 has many methods of serialization but we use the canonicalized one and we also moved the public key out of the details envelope so that we no longer have to re-marshal the details section of a cert struct like before. The end result is a more future proof format.

The v2 certificate format also enables assigning multiple overlay addresses to a single host, including both IPv4 and IPv6, or multiple addresses of either type. This is useful for hosts that need to be reachable across multiple subnets within your Nebula network.

# Sign a v2 cert with both IPv4 and IPv6 overlay addresses
nebula-cert sign -name "myhost" -networks "10.10.0.1/24, fd00:10:10::1/64" -ca-crt ca.crt -ca-key ca.key

Each address in -networks becomes a routable overlay address for that host, giving you flexibility for subnetting and service organization within your overlay network.

Deprecated: firewall.default_local_cidr_any now defaults to false. This change improves security by requiring explicit local_cidr declarations in firewall rules that target tun.unsafe_routes. This config option will be removed in a future release.

What changed:

• Old behavior (true): All firewall rules applied to all configured unsafe routes unless explicitly restricted
• New behavior (false): Rules only apply to unsafe routes when local_cidr is explicitly specified

This makes firewall rules more predictable and prevents unintended access to unsafe routes.

What this means for you: If you’re using tun.unsafe_routes (typically for accessing resources outside the Nebula network), you’ll need to update your firewall rules to be more specific. Here’s an example of the change:

# Old behavior (implicit, potentially insecure)
firewall:
  default_local_cidr_any: true  # Old default
  inbound:
    - port: 22
      proto: tcp
      groups: ["ssh-access"]
      # This rule would apply to ALL unsafe_routes

# New behavior (explicit, secure)
firewall:
  default_local_cidr_any: false  # New default
  inbound:
    - port: 22
      proto: tcp
      groups: ["ssh-access"]
      local_cidr: "192.168.1.0/24"  # Explicitly target this unsafe_route

PKCS#11 support for P256 keys (PR #1153, PR #1482): When Nebula is built with the pkcs11 tag, it now supports P256 elliptic curve keys stored in Hardware Security Modules (HSMs) or smart cards. This enables enterprise deployments to meet strict key management requirements by ensuring private keys never exist in software. See the pki.key PKCS#11 support docs for more information.

To use PKCS#11 support:

# Build Nebula with PKCS#11 support
make bin-pkcs11

# Configure with PKCS#11 key reference
pki:
  ca: ca.crt
  cert: host.crt
  key: "pkcs11:token=MyToken;object=MyKey" # PKCS#11 URI format

ECMP support for unsafe_routes (PR #1332): Equal-Cost Multi-Path routing is now available for unsafe_routes, enabling rudimentary load balancing and redundancy within each unsafe route subscribing host. You can now configure multiple gateways for the same route on one host, with optional weighting for unequal load distribution. See the tun.unsafe_routes ECMP configuration docs for more information.

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

The implementation uses hash-threshold mapping (similar to the Linux kernel) to distribute traffic based on packet hashing. When a gateway becomes unreachable, traffic automatically fails over to the remaining available gateways, though this rudimentary load balancing may become uneven until the failed gateway recovers.

SO_MARK socket option support (PR #1331): On Linux systems, Nebula can now mark packets using the SO_MARK socket option to enable advanced routing scenarios. This is particularly useful for full subnet routing (including 0.0.0.0/0) without the complexity of network namespaces, allowing administrators to route Nebula traffic through custom routing tables. See the listen.so_mark docs for more information.

# Mark Nebula packets with firewall mark 4242 (choose a number to associate with Nebula)
listen:
  so_mark: 4242

Configurable logging and versioning for embedded use (PR #1239): Projects integrating Nebula as a library with userspace networking can now configure the logger and build version. This is particularly useful for applications that want to maintain consistent logging patterns or need to track specific Nebula versions in their telemetry.

Previously when integrating Nebula as a library, it wasn’t possible to configure the logger or build version when calling service.New(config *config.C) (*Service, error). Now, service.New requires contructing a Nebula control via nebula.Main, which allows passing a custom build version and logger, then passing the control struct to service.New(control *nebula.Control) (*Service, error).

---

Nebula v1.10 is ready for the next era of networking! Weʼre very excited about IPv6 support in the overlay, and we hope you are too. Whether youʼre running a small team network or managing infrastructure at scale, this release gives you the tools to build networks that are future-proof, flexible, and secure.

Ready to upgrade? Check out the upgrade guide to get started with IPv6 in your Nebula network. And if you’re interested in contributing to Nebula’s future, the GitHub repository is always open to pull requests and feedback.