Nebula Network Overlay

Nebula Overview

Nebula is a scalable overlay networking tool that focuses on performance, simplicity, and security. It creates a mesh network between nodes, allowing them to communicate securely regardless of their physical network location.Key features of Nebula include:

• Encrypted communication using noise protocol
• Certificate-based authentication and authorization
• NAT traversal capabilities
• Lightweight and efficient design

Certificate Management

Nebula uses X.509 certificates for node authentication and authorization. The Gitpod Gateway manages these certificates as follows:

1. The Gateway Server acts as the Nebula network’s Certificate Authority (CA).

2. When a new node (environment, lighthouse, proxy, or runner) joins the network, it requests a certificate from the Gateway Server.

3. The Gateway Server generates a unique certificate for the node, including:

   • Node IP address
   • Node name
   • Groups the node belongs to (for use in the firewall)
   • Validity period

4. The Gateway Server doesn’t store certificates.

5. Nodes use their certificates to authenticate with other nodes in the network.Note: The Gateway Server handles certificate rotation automatically. Ensure nodes can reach the Gateway Server to obtain updated certificates before expiration.

Security Features

Nebula provides several security features that the Gitpod Gateway leverages:

• Encrypted Communication:The noise protocol encrypts all traffic between Nebula nodes.
• Fine-grained Access Control: The Gateway Server defines firewall rules based on node groups and IP addresses.
• Short-lived Certificates: The Gateway Server issues certificates with limited validity periods to reduce the risk of compromise.
• Mutual Authentication: All nodes in the network authenticate each other, preventing man-in-the-middle attacks.

NAT Traversal and Peer Discovery

Nebula uses a combination of techniques to enable communication between nodes behind NATs:

• Lighthouse Nodes: These nodes have public IP addresses and act as rendezvous points for other nodes.

• UDP Hole Punching: Using UDP hole-punching techniques, Nebula attempts to establish direct connections between nodes using UDP hole-punching techniques.

• Fallback Routing: If a direct connection is impossible, traffic routes through Lighthouse nodes (this requires both nodes to be able to reach the Lighthouse node)The peer discovery process works as follows:

1. A node joins the network and connects to a Lighthouse node (can be multiple).

2. The node informs the Lighthouse of its public and private IP addresses.

3. When the node wants to communicate with another node, it asks the Lighthouse for that node’s information.

4. The nodes attempt to establish a direct connection using the provided information.

5. If direct connection fails, communication routes through the Lighthouse.