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, and peer-to-peer connectivity (including via NAT traversal and relaying.) 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, configuration management and deployment, 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. If your network uses a managed lighthouse, we run that too, as a separate deployment from the API.
• Your infrastructure: Every host runs DNClient, an instance of Nebula instrumented to pull configuration changes from our API, along with any lighthouses and relays you choose to operate yourself.
• Between hosts: Data-plane traffic flows directly between hosts wherever a direct connection is possible, and through a relay when it isn’t.

Defined Networking management plane

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.

Our API is not in the path of your network’s traffic. Once a host has its certificate and configuration, it no longer needs to reach api.defined.net in order to operate. Tunnels are established directly between hosts. If our API becomes unreachable, hosts maintain their tunnels, traffic flows, and firewall rules continue to be enforced. You lose the ability to push new configuration changes until connectivity is restored, but your network keeps running.

Lighthouses

Lighthouses handle peer discovery: each host reports the internet address where it can currently be reached, and queries the lighthouse to find the addresses of the peers it wants to talk to. Peer discovery in a Nebula network depends on a lighthouse being reachable. If no lighthouses are reachable, hosts that have already established tunnels keep communicating over them, but a host that needs to locate a peer it isn’t already talking to cannot do so until discovery recovers.

By default, every Managed Nebula network is provisioned with a managed lighthouse Defined Networking operates. The managed lighthouse is a separate deployment so an outage of api.defined.net does not take peer discovery down with it. Nebula uses all available lighthouses, and you can opt-in to running your own lighthouse alongside Defined Networking’s managed lighthouse for additional redundancy—or as a replacement to the managed lighthouse altogether.

By default, a network’s lighthouses also serve as relays. While that setting is on, hosts that cannot reach each other directly may forward traffic through the managed lighthouse. Relayed traffic stays end-to-end encrypted between the two hosts: the relay learns which hosts are talking and how much, but cannot read or alter what they send.

Lighthouse trust model

Some overlay network architectures place a coordination server in the critical path for key exchange, which means the coordination service can observe or influence the keys protecting your traffic. Nebula’s lighthouses do not work this way. A lighthouse learns where a host can be reached and nothing more. It takes no part in the Noise handshake between two hosts, holds none of their key material, and cannot decrypt or forge their traffic.

The managed lighthouse holds a certificate signed by your network’s CA, so that your hosts will accept its discovery responses. That certificate carries no role or tag membership, so it does not satisfy the firewall rules that grant hosts access to one another. Additionally, it is assigned an IP address outside of your network, so Nebula will never accept Layer 3 traffic from a managed lighthouse. A lighthouse that misbehaved could disrupt peer discovery or point a host at the wrong internet address. It could not read your traffic or impersonate one of your hosts, because both ends of every tunnel still authenticate each other against your CA.

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 because any modification would invalidate 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.

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.

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 and denies all other traffic.

This means you don’t need to manage iptables rules, security groups, or host-level firewall configurations separately. The firewall policy is encoded in the host’s Nebula configuration and is enforced regardless of the underlying network. Firewall rule changes you make in the admin panel are applied automatically. 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.

A relay may be a host you have designated as one, or, with the “lighthouses act as relays” network setting (default on), any of the network’s lighthouses.

Open-source foundation

Nebula is open source under the MIT license, developed at github.com/slackhq/nebula. DNClient wraps Nebula with the management integrations (enrollment, automatic certificate updates, centralized config), but the networking, encryption, and firewall are Nebula.

Thus, 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 simply removes the operational overhead of managing it yourself.