Architecture

How Managed Nebula works

Managed Nebula is a management layer on top of Nebula, our open-source overlay networking tool. Nebula handles the hard parts of networking: host discovery, encrypted tunnels between hosts, relaying, NAT traversal, and peer-to-peer connectivity. Defined Networking adds the operational layer that makes Nebula practical at scale: a web UI and API for managing hosts, automated certificate issuance and rotation, SSO integration, role-based firewall policies, traffic relaying, and audit logging.

Here's what runs where:

• Defined Networking's cloud (admin.defined.net, api.defined.net): The admin panel, API, certificate authority, configuration storage, and audit logs.
• Your infrastructure: Every host runs DNClient, an instance of Nebula instrumented to pull configuration changes from our API. Your lighthouses handle peer discovery. Your relays forward traffic when direct connections aren't possible. All data-plane traffic flows directly between your hosts — it never touches our infrastructure.

Management plane, not control plane

This distinction matters. Defined Networking operates a management plane: we handle enrollment, certificate issuance, certificate rotation, configuration distribution, and audit logging. DNClient polls our API continuously to pick up changes. When you update a firewall rule or block a host, that change propagates to your fleet nearly instantly.

But we are not in the critical path of your network's operation. Once a host has its certificate and configuration, it operates fully independently of our cloud. Lighthouses, which you operate on your own infrastructure, handle peer discovery. Tunnels are established directly between hosts. If Defined Networking's API becomes unreachable, your existing network keeps running. Hosts maintain their tunnels, traffic flows, and firewall rules continue to be enforced. No ongoing connectivity to Defined Networking is required for the overlay network to function. You lose the ability to push new configuration changes until connectivity is restored, but your network does not go down.

This is a deliberate architectural choice. Some overlay network architectures place a coordination server in the critical path for key exchange and peer discovery, meaning that if the coordination service goes down, hosts cannot establish new connections. With Managed Nebula, your lighthouses are the coordination infrastructure, and they run on your machines.

Certificate-based host identity

Every host on a Managed Nebula network has a certificate signed by the network's certificate authority (CA). The CA is created and managed by Defined Networking — we hold the CA private key and use it to issue host certificates. For details on how we protect CA private keys, see Securing the keys to your kingdom.

Identity is cryptographically encoded in each certificate: the host's name, overlay IP address, and group memberships are all embedded in the signed certificate. Hosts cannot modify their own certificates — any modification invalidates the CA signature. A host cannot impersonate another host, claim a different IP address, or grant itself access to groups it doesn't belong to. These properties are enforced cryptographically, not by trusting a central server at connection time.

Tunnel establishment

Nebula uses the Noise Protocol Framework (Noise_IX pattern) for tunnel establishment. Each connection begins with an ephemeral Diffie-Hellman key exchange, providing Perfect Forward Secrecy: compromise of a host's long-term private key does not allow decryption of previously captured traffic. Both hosts mutually authenticate by verifying that the other holds a valid certificate signed by a trusted CA. The private key for each host is generated locally and never leaves the host.

Certificate lifecycle

Defined Networking automatically rotates CAs periodically and distributes updated CA certificates to all hosts. When a host's certificate is rotated, only that host needs to receive its new certificate — there is no need to distribute new keys or certificates to every other peer on the network. Peers validate certificates against the CA, so individual host certificate rotations are transparent to the rest of the network.

If a host needs to be removed from the network, an administrator blocks it via the admin panel or API. In an instant, all other hosts on the network receive an updated configuration and stop trusting the blocked host's certificate.

Nebula's cryptographic implementation has been reviewed in a third-party security audit. The Nebula source code is publicly available for independent review.

Built-in stateful firewall

Nebula includes a stateful packet filter that operates at the overlay network level. Every packet entering a host through the Nebula tunnel is evaluated against the host's firewall rules before it reaches the operating system's network stack.

In Managed Nebula, firewall rules are defined centrally in the admin panel and organized around roles and tags. Each host is assigned a role (e.g., "web-server", "database", "developer-endpoint"), and inbound firewall rules specify which roles and tags are allowed to connect on which protocols and ports. By default, a new role permits only ICMP — all other inbound traffic is denied.

This means you don't need to manage iptables rules, security groups, or host-level firewall configurations separately. The firewall policy travels with the host's Nebula configuration, is enforced regardless of the underlying network, and updates automatically when you change rules in the admin panel. Because the firewall operates on the encrypted overlay, it applies consistently whether the host is in a data center, a coffee shop, or behind carrier-grade NAT.

Connectivity and NAT traversal

Nebula uses UDP hole punching to establish direct peer-to-peer connections between hosts whenever possible. When a direct connection cannot be established — common with symmetric NAT or carrier-grade NAT — Nebula automatically selects a relay to forward traffic. Traffic forwarded through relays remains end-to-end encrypted; relays can see packet routing metadata but cannot read or modify the contents.

Open-source foundation

Nebula is open source under the MIT license, developed at github.com/slackhq/nebula. Managed Nebula runs the same Nebula — not a fork, or proprietary reimplementation. DNClient wraps Nebula with the management integrations (enrollment, automatic certificate updates, centralized config), but the networking, encryption, and firewall are Nebula.

This has a practical consequence: there is no lock-in at the protocol level. You can export your Nebula host configurations, create your own CA, sign new host certificates, and run Nebula directly without DNClient or Defined Networking's cloud. The overlay network is built on the same software you'd use with open-source Nebula — Managed Nebula removes the operational overhead of managing it yourself.