# Nebula Overlay Network

Nebula is a scalable overlay network that provides encrypted connectivity between all VMs regardless of their physical location.

## Architecture

```
                    ┌─────────────┐
                    │ Lighthouse  │
                    │ 10.10.10.10 │
                    └──────┬──────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                 │
    ┌────▼────┐      ┌────▼────┐      ┌────▼────┐
    │ VM 1    │      │ VM 2    │      │ VM 3    │
    │ 10.10.10.11    │ 10.10.10.20    │ 10.10.10.30
    └─────────┘      └─────────┘      └─────────┘
```

## Groups

Nebula uses groups for firewall segmentation:

| Group | Purpose | Can Access |
|-------|---------|------------|
| `admin` | Personal devices | Everything |
| `infrastructure` | Core services | Each other |
| `projects` | Application workloads | Infrastructure |
| `lighthouse` | Nebula relays | - |
| `games` | Game servers | Isolated |

## Setup

### 1. Generate Certificate Authority

```bash
nebula-cert ca -name "Arvandor CA" -duration 87600h
```

This creates:
- `ca.crt` - Certificate (share with all hosts)
- `ca.key` - Private key (keep secure, do not commit!)

### 2. Generate Host Certificates

```bash
# Infrastructure VM example
nebula-cert sign -ca-crt ca.crt -ca-key ca.key \
  -name "dns" \
  -networks "10.10.10.11/24" \
  -groups "infrastructure" \
  -out-crt configs/1001/dns/dns.crt \
  -out-key configs/1001/dns/dns.key

# Application VM example
nebula-cert sign -ca-crt ca.crt -ca-key ca.key \
  -name "app-server" \
  -networks "10.10.10.50/24" \
  -groups "projects" \
  -out-crt configs/4050/app-server/app-server.crt \
  -out-key configs/4050/app-server/app-server.key

# Lighthouse
nebula-cert sign -ca-crt ca.crt -ca-key ca.key \
  -name "lighthouse" \
  -networks "10.10.10.10/24" \
  -groups "infrastructure,lighthouse" \
  -out-crt configs/1000/lighthouse/lighthouse.crt \
  -out-key configs/1000/lighthouse/lighthouse.key
```

### 3. Directory Structure

```
nebula/
├── ca.crt              # Certificate authority (commit this)
├── ca.key              # CA private key (DO NOT COMMIT)
├── configs/
│   ├── 1000/lighthouse/
│   │   ├── lighthouse.crt
│   │   └── lighthouse.key
│   ├── 1001/dns/
│   │   ├── dns.crt
│   │   └── dns.key
│   └── ...
└── README.md
```

### 4. Deploy with Ansible

The `nebula.yml` playbook deploys certificates and configuration:

```bash
ansible-playbook -i inventory.ini playbooks/nebula.yml --limit "new-vm"
```

## Lighthouse Configuration

The lighthouse requires manual configuration (not managed by Ansible):

```yaml
# /etc/nebula/config.yml on lighthouse
pki:
  ca: /etc/nebula/ca.crt
  cert: /etc/nebula/config.crt
  key: /etc/nebula/config.key

static_host_map: {}

lighthouse:
  am_lighthouse: true
  serve_dns: false

listen:
  host: 0.0.0.0
  port: 4242

punchy:
  punch: true
  respond: true

relay:
  am_relay: true

tun:
  dev: nebula1
  drop_local_broadcast: true
  drop_multicast: true

firewall:
  conntrack:
    tcp_timeout: 12h
    udp_timeout: 3m
    default_timeout: 10m

  outbound:
    - port: any
      proto: any
      host: any

  inbound:
    - port: any
      proto: any
      group: admin
    - port: any
      proto: any
      group: infrastructure
    - port: any
      proto: icmp
      host: any
```

## IP Allocation

| VMID Range | Network Segment | Last Octet |
|------------|-----------------|------------|
| 1000-1999  | Management      | 10-19      |
| 2000-2999  | Services        | 20-29      |
| 3000-3999  | Data            | 30-49      |
| 4000-4999  | Workloads       | 50-59      |
| 5000-5999  | Monitoring      | 90-99      |

Example: VMID 3000 → 10.10.10.30