Nebula — The Cyber Toolchain

Nebula v1.12.0

Thu, 29 Oct 2026 15:18:31 GMT

Nebula adds UDP/TUN offloads, a local control API with `nebula ctl`, FIPS 140-3 mode, CPU thread pinning, and experimental split-DNS support⁠︀︄︇︀︅︉︀︅︀︀︃︀︀︅︅︀︅︊︀︄︆︀︃︄⁠ • Enable Linux TUN offloads (TSO/USO) and UDP GSO/GRO for higher throughput with `tun.use_offloads` and `listen.udp_offloads` in config (off by default; will be on by default in a future release).⁠︀︄︇︀︅︉︀︅︀︀︃︀︀︅︅︀︅︊︀︄︆︀︃︄⁠ • Pin each I/O routine's thread to a CPU on Linux when `routines` is above 1, controlled by `tun.pin_threads` (default `true`), `tun.pin_threads_key` (`pid` or `port`), and `tun.cpu_affinity`. • Access every SSH debug command through a new local control socket via `nebula ctl `, with access restricted to the running user, root, or a group named in `local_api.control.group`; set a per-instance path with `local_api.control.socket`. • Query node identity over HTTP through the new opt-in info socket: `GET /v1/identity` for the local node, `GET /v1/identity/` for another host, and `/pem` under either path for the certificate. • Build CGO-free FIPS 140-3 binaries with `make fips140` or `make release-fips140`; these restrict operation to P256 certificates and AES, and `nebula-cert ca` and `keygen` default to `-curve P256` in those builds. • Configure split DNS or full DNS override with the experimental `dns` stanza, pointing the host resolver at `dns.nameservers` for `dns.match_domains` or all lookups (macOS and Windows only, off by default). • Nebula now batches outbound UDP sends on Linux, up to 128 packets per `sendmmsg` call. Breaking changes: • Building Nebula or embedding it as a library now requires Go v1.27.3. • A firewall rule `group` that YAML reads as a float, a date, a map, or a nested array is now rejected on startup and reload instead of being silently converted to a string (e.g. `group: 1.10` used to match group `1.1`). A null `group` or `groups` is rejected when no `host`, other group, or `cidr` limits the rule. • A `pki.blocklist` entry that is not a hex SHA-256 fingerprint now causes Nebula to refuse to start and fail a reload. • On Linux, Nebula refuses a `tun.dev` that already exists (including a persistent device created with `ip tuntap add` or systemd-networkd); remove it and let Nebula create the device. • `tun.mtu` and any route `mtu` above 8937 is capped to 8937 with a warning. • SSH debug server commands now exit with status 1 when they refuse; with `-json` or `-pretty` they report refusal as `{"ok":false,"reason":...}`. Every command now accepts `-json` and `-pretty`. • `nebula` and `nebula-service` refuse to start when given an argument that is not a flag (previously ignored). • Embedders: `config.C.RegisterReloadCallback` callbacks now take (*config.C, *config.Reload); `ReloadConfig` and `ReloadConfigString` return a `config.ReloadResult`; `ReloadConfigString` used to return an `error`, now it is the result's `Err`. • Embedders: `overlay.Device` no longer embeds `io.ReadWriteCloser`; `NewMultiQueueReader` and `SupportsMultiqueue` are replaced by `Queues`; `udp.Conn` gained `WriteBatch`, `IPv4Only`; `ListenOut` takes a flush callback; `ReloadConfig` takes a `*config.Reload`; `udp.NewListener` and `udp.NewGenericListener` take a `udp.Settings`. • Embedders: SSH debug commands moved to the new `commands` package; `sshd.RegisterCommand` and `sshd.Command` are removed; `sshd.NewSSHServer` takes a `*commands.Registry`; `firewall.ProtoTCP`, `ProtoUDP`, `ProtoICMP`, and `ProtoICMPv6` are now `iputil.IPProtocol*`. • The SSH debug server's `start-cpu-profile`, `stop-cpu-profile`, `save-heap-profile`, `save-mutex-profile`, and `mutex-profile-fraction` commands, and `sshd.sandbox_dir`, are removed. Full history on Cyber Toolchain: https://cybertoolchain.io/tools/nebula

Nebula v1.11.0

Thu, 23 Jul 2026 18:24:53 GMT

Nebula v1.11.0 adds macOS network-change rebinding, IPv6 rejects, stdin/stdout cert I/O, and six breaking config changes. • Adds automatic listener rebind and lighthouse re-query on macOS when the underlay network changes (wifi↔wired), controlled by `listen.rebind_on_network_change` (default `true`). • Generates IPv6 reject packets for blocked traffic, matching existing IPv4 reject behavior. • Accepts `-` as a path in `nebula-cert` subcommands to read from stdin or write to stdout. • Searches for both `config.yml` and `config.yaml` automatically in service and CLI modes. • Adds version labels to Docker/OCI images. • Signs Windows release binaries. • Supports port-free ICMP firewall rules — port is no longer required in ICMP rule definitions. • Tracks ICMP traffic per-flow via connection tracking. • Returns `NODATA` instead of `NXDOMAIN` from the embedded DNS server when a name exists but lacks the requested record type, fixing `AAAA`-first resolvers (busybox/Alpine). • Records the local Nebula host's own details in the DNS server. • Reloads the firewall automatically when unsafe networks in the certificate change, without requiring a restart. • Triggers an immediate lighthouse update when reconnecting to or adding a lighthouse instead of waiting for the next tick. • Adds `Control.Wait`, a new API method that blocks until Nebula has fully stopped and returns the first fatal reader error. Breaking changes: • Logging has switched from logrus to Go's structured `slog`: log levels are now upper case (`level=INFO`), trace prints as `level=DEBUG-4`, timestamps are always RFC3339Nano, `logging.timestamp_format` is ignored, and some messages were reworded. Embedders must update constructors to accept `*slog.Logger`. • `firewall.inbound_action` and `firewall.outbound_action` were each applied to the opposite direction; this is now corrected. If you set either, you are currently getting the behavior of the other and likely need to swap them before upgrading. • On Windows, Nebula now installs WFP PERMIT filters for the nebula adapter and listener port by default, bypassing Windows Defender Firewall (WDF) inbound rules for those. Set `tun.windows_bypass_wdf` and `listen.windows_bypass_wdf` to `false` to leave WDF in charge. • On Windows, the Nebula device network category is now set to `private` instead of whatever Windows chose (usually `Public`). Set `tun.network_category` to `unset` to keep the old behavior. • Reject packets for non-TCP traffic now use ICMP code 13 (communication administratively prohibited) instead of code 3 (port unreachable). Anything keying off the old code needs updating. • The SSH debug server's profiling commands (`start-cpu-profile`, `save-heap-profile`, `save-mutex-profile`) are now confined to `sshd.sandbox_dir` (default `$TMP/nebula-debug`). Absolute paths outside that directory are rejected; the directory is not created automatically. Scripts using paths elsewhere must set `sshd.sandbox_dir` accordingly. Full history on Cyber Toolchain: https://cybertoolchain.io/tools/nebula

Nebula v1.10.1

Fri, 16 Jan 2026 15:44:17 GMT

Nebula v1.10.1 adds a config option to control acceptance of recv_error packets. • Adds a config option to control whether `recv_error` packets are accepted, defaulting to `always`. Full history on Cyber Toolchain: https://cybertoolchain.io/tools/nebula

Nebula v1.10.0

Thu, 04 Dec 2025 19:53:38 GMT

Nebula v1.10.0 adds IPv6 overlay support, a new v2 certificate format, packet marking for iptables/nftables, ECMP for unsafe_routes, and PKCS11 P256 key support. • Supports IPv6 and multiple IPv4/IPv6 addresses in the overlay network. • Introduces a new v2 ASN.1-based certificate format with a unified interface for external implementations. • Adds packet marking on Linux to better target Nebula packets in iptables/nftables rules. • Adds ECMP (Equal-Cost Multi-Path) support for `unsafe_routes`. • Adds PKCS11 support for P256 keys when built with the `pkcs11` tag. • Accepts encrypted CA passphrase from an environment variable. • Allows handshaking with any trusted remote. • Allows library users with userspace networking to configure the `logger` and build version. • Logs a warning when a firewall rule contains an `any` that negates a more restrictive filter. Breaking changes: • `default_local_cidr_any` now defaults to false — firewall rules targeting `unsafe_routes` entries must explicitly declare the destination via the `local_cidr` field, or traffic that previously matched will no longer match. Full history on Cyber Toolchain: https://cybertoolchain.io/tools/nebula

Nebula v1.9.6

Fri, 18 Jul 2025 12:55:16 GMT

Nebula v1.9.6 adds opt-in inactive tunnel dropping to reclaim resources from stale connections. • Adds `tunnels.drop_inactive` config option to automatically drop inactive tunnels (disabled by default). Full history on Cyber Toolchain: https://cybertoolchain.io/tools/nebula

Nebula v1.9.4

Mon, 09 Sep 2024 18:20:34 GMT

Nebula v1.9.4 adds UDP dialing support in gVisor and exposes internal state programmatically via control object. • Supports UDP dialing when running under gVisor. • Exposes Nebula internal state programmatically via the control object, enabling richer integrations and tooling. Full history on Cyber Toolchain: https://cybertoolchain.io/tools/nebula

Nebula v1.9.0

Wed, 08 May 2024 14:39:56 GMT

Adds official distroless Docker image, loong64 support, inlined SSH host keys, and sshd.trusted_cas for certificate trust. • `tun.unsafe_routes` is now reloadable without restart • Adds official `nebulaoss/nebula` distroless Docker image containing `nebula` and `nebula-cert` binaries • Provides experimental binaries for the `loong64` architecture • SSH daemon supports inlined host keys • SSH daemon supports certificates with `sshd.trusted_cas` Breaking changes: • Support for the deprecated `local_range` option is removed; migrate to `preferred_ranges` • Windows builds now require at least Windows 10 or Windows Server 2016 due to Go 1.22 toolchain changes Full history on Cyber Toolchain: https://cybertoolchain.io/tools/nebula

Nebula v1.8.0

Wed, 06 Dec 2023 19:48:03 GMT

Nebula v1.8.0 adds systemd readiness, RIO on Windows, and lighthouse requery limits. • `pki.disconnect_invalid` defaults to true, disconnecting tunnels when certificates expire • New config option `timers.requery_wait_duration` (default `60s`) limits busy tunnel lighthouse queries • Linux: Notify systemd of service readiness via `examples/service_scripts/nebula.service` • Windows: Use Registered IO (RIO) for ~50x throughput improvement Breaking changes: • `pki.disconnect_invalid` now defaults to true, causing tunnel disconnection upon certificate expiration Full history on Cyber Toolchain: https://cybertoolchain.io/tools/nebula

Nebula v1.7.0

Wed, 17 May 2023 15:13:17 GMT

Nebula v1.7.0 adds encrypted CA keys, `local_cidr` firewall rules, SSH mutex profiling, and P256/BoringCrypto support. • `nebula-cert ca` now accepts the `-encrypt` flag to encrypt CA private keys with a passphrase using AES-256-GCM and Argon2id. • New firewall rule type `local_cidr` allows filtering destinations based on the local interface's CIDR, useful when using `unsafe_routes`. • `unsafe_route` config entries now support an `install` option to control whether the route is installed in the system routing table. • New tun option `tun.use_system_route_table` (true/false) enables managing unsafe routes directly on the system route table with gateway routes (Linux only). • Metric `certificate.ttl_seconds` is now exposed via stats for monitoring certificate expiration. • New tun option `punchy.respond_delay` allows configuring the delay before attempting punchy responds (default 5 seconds). • SSH commands added to capture a mutex profile for debugging concurrency issues. • Config option `lighthouse.calculated_remotes` enables handshakes without a lighthouse in certain configurations. • Support for P256 curves and BoringCrypto has been added for certificate generation and validation. Full history on Cyber Toolchain: https://cybertoolchain.io/tools/nebula

Nebula v1.6.0

Thu, 30 Jun 2022 20:25:51 GMT

Nebula v1.6.0 adds experimental relay support for NAT traversal, lighthouse IP reporting, hot reloading for `punchy`/`lighthouse`, and Windows ARM64. • `nebula` clients can now be configured to act as relays for other clients behind stubborn NATs • Adds configuration option to report manually specified `ip:port`s to lighthouses • Introduces Windows arm64 build support • `punchy` and most `lighthouse` config options now support hot reloading • Promotes `routines` config from experimental to supported feature • Adds `listen.send_recv_error` to control `recv_error` message conditions Breaking changes: • `x509` config stanza support has been removed, requiring migration from the old stanza. Full history on Cyber Toolchain: https://cybertoolchain.io/tools/nebula