# slackhq/nebula architecture

> Architecture diagram of the GitHub repository slackhq/nebula, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/slackhq/nebula
- Repository: https://github.com/slackhq/nebula

## Overview

##### Main Components
- Nebula Binary (Main Overlay Network Service):
- This is represented by the “nebula” command under the cmd/nebula directory. It includes modules for connection management, UDP communications, tunneling (via various platform-specific implementations like “overlay/tun_*” and “wintun”), routing, and encryption.
- Certificate Authority and Certificate Management:
- The “nebula-cert” tool (found under cmd/nebula-cert) and the cert/ directory contain functionality to create a certificate authority, sign node certificates, and manage public-key infrastructure. This is the root of trust for the network.
- Nebula Service (optional or infrastructure-oriented component):
- Found under cmd/nebula-service, this component deals with additional host operations such as logging and notification.
- Configuration Management:
- The config/ directory and examples/config.yml indicate how each node reads its configuration (including details about lighthouse definitions, static host maps, firewall rules, and group definitions).
- Networking Subsystems:
- Several packages (udp, overlay, connection_manager, handshake, noise, iputil, etc.) contribute to lower-level networking: establishing encrypted connections (using the Noise Protocol Framework), managing tunnels (with platform-specific tun implementations), and handling NAT traversal through lighthouses.
- Testing, Build and CI/CD Integration:
- There are several GitHub workflows and Makefiles embedded within the file tree that govern code quality, formatting, and cross-platform builds. Although these are not core runtime components, they show how the project ensures reliability and maintainability.

##### Relationships and Interactions
- Trust and Security Flow:
- Each Nebula node verifies peer certificates during the handshake (using Noise Protocol modules such as “noise” and “noiseutil”).
- Control vs. Data Plane:
- The configuration and control modules in the Nebula binary handle command and control (e.g., lighthouse discovery, host mapping, and firewall filtering) while the overlay and udp modules manage the actual encrypted data traffic.
- Communication Flow:
- That secure point-to-point communication is achieved by integrating certificate validation, ECDH key exchanges, and AES-256-GCM encryption.

##### Architectural Patterns and Principles
- Modular Design:
- The clear separation between certificate management (nebula-cert), network connectivity (nebula binary), and configuration demonstrates modularity.
- Peer-to-Peer and Distributed Control:
- Nodes interact directly in a decentralized manner; however, discovery is assisted by lighthouses that are configured as a stable point.
- Platform-Specific Implementations:
- Different tunnels and network interfaces (e.g., in overlay, udp, and wintun packages) indicate the necessity for platform-specific adaptations – highlight these as submodules under the main overlay networking component.
- Security Focus:
- Cryptographic operations and certificate verification throughout the design. Components like “cert”, “noise”, and “pki” are central to maintaining trust and encryption.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Components
    CA["Certificate Authority\n(nebula-cert & cert/)"]:::security
    NB["Nebula Node\n(nebula binary)"]:::core
    NS["Nebula Service\n(cmd/nebula-service)"]:::aux
    CM["Configuration Management\n(config/ directory)"]:::config
    CEX["Config Example\n(examples/config.yml)"]:::config
    CICD["CI/CD & Build\n(.github/ workflows, Makefile)"]:::ci
    NWS["Networking Subsystems\n(UDP, Overlay, Connection Manager, Noise)"]:::network

    %% Networking Modules Subgraph
    subgraph "Networking Modules"
        direction TB
        UDP["UDP Communication\n(udp/)"]:::network
        Overlay["Overlay/Tunneling\n(overlay/ & tun implementations)"]:::network
        ConnMgr["Connection Manager\n(connection_manager.go)"]:::network
        Noise["Noise Protocol\n(noise.go)"]:::security
        NoiseUtil["Noise Utilities\n(noiseutil/)"]:::security
    end

    %% Relationships and Interactions
    CA -->|"issues-cert"| NB
    CA -->|"verifies-cert"| NWS
    CM -->|"feeds-config"| NB
    CEX -->|"example-config"| NB
    NWS -->|"enables-data-path"| NB
    NB -->|"logs/telemetry"| NS
    CICD -->|"ensures-quality"| NB
    NB ---|"P2P-handshake"| NB

    %% Link Networking Modules to Networking Subsystems node
    UDP --> NWS
    Overlay --> NWS
    ConnMgr --> NWS
    Noise --> NWS
    NoiseUtil --> NWS

    %% Click Events
    click NB "https://github.com/slackhq/nebula/tree/master/cmd/nebula"
    click CA "https://github.com/slackhq/nebula/tree/master/cmd/nebula-cert"
    click NS "https://github.com/slackhq/nebula/tree/master/cmd/nebula-service"
    click CM "https://github.com/slackhq/nebula/tree/master/config/"
    click CEX "https://github.com/slackhq/nebula/blob/master/examples/config.yml"
    click CICD "https://github.com/slackhq/nebula/tree/master/.github/"
    click UDP "https://github.com/slackhq/nebula/tree/master/udp/"
    click Overlay "https://github.com/slackhq/nebula/tree/master/overlay/"
    click ConnMgr "https://github.com/slackhq/nebula/blob/master/connection_manager.go"
    click Noise "https://github.com/slackhq/nebula/blob/master/noise.go"
    click NoiseUtil "https://github.com/slackhq/nebula/tree/master/noiseutil/"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px
    classDef security fill:#f8d7da,stroke:#721c24,stroke-width:2px
    classDef config fill:#d4edda,stroke:#155724,stroke-width:2px
    classDef network fill:#fff3cd,stroke:#856404,stroke-width:2px
    classDef ci fill:#d1ecf1,stroke:#0c5460,stroke-width:2px
    classDef aux fill:#e2e3e5,stroke:#41464b,stroke-width:2px
```
