Quick Start Guide

This guide walks you through setting up a basic Nebula mesh network with saltext-nebula. By the end, you’ll have a working mesh with one lighthouse and one client node.

Prerequisites

  • A working Salt master/minion infrastructure

  • nebula-cert binary installed on the Salt master

  • Nebula package installed on target minions

  • Network connectivity between nodes (UDP port 4242 by default)

Step 1: Install the Extension

On the Salt master:

salt-pip install saltext-nebula

On all minions that will join the mesh:

salt '*' pip.install saltext-nebula
# Or use a state for consistent deployment

Step 2: Configure the Master

Create /etc/salt/master.d/nebula.conf:

# Nebula runner configuration
nebula.cert_dir: /etc/nebula/certs
nebula.ca_key: /etc/nebula/ca/ca.key
nebula.ca_crt: /etc/nebula/ca/ca.crt
nebula.salt_cert_dir: /srv/salt/nebula/certs

# CA settings
nebula.ca_name: "My Nebula Network"
nebula.ca_duration: "87600h"
nebula.ca_encrypt: true
nebula.ca_passphrase: "change-this-to-a-secure-passphrase"

Create the required directories:

mkdir -p /etc/nebula/ca /etc/nebula/certs /srv/salt/nebula/certs
chmod 700 /etc/nebula/ca

Restart the Salt master:

systemctl restart salt-master

Step 3: Create Pillar Configuration

Create /srv/pillar/nebula/common.sls:

nebula:
  lighthouse_port: 4242
  listen_port: 0
  network_cidr: "10.10.10.0/24"
  dns_name: "nebula"

  remote_allow_list:
    '0.0.0.0/0': true
    '::/0': false

  lighthouses:
    lighthouse01:
      nebula_ip: "10.10.10.1"
      public_ip: "YOUR_LIGHTHOUSE_PUBLIC_IP"  # Replace with actual IP

Create /srv/pillar/nebula/lighthouse01.sls:

nebula:
  hosts:
    lighthouse01:
      ip: "10.10.10.1/24"
      is_lighthouse: true
      groups:
        - "lighthouse"
        - "infrastructure"
      duration: "43800h"

      firewall:
        inbound:
          - port: 4242
            proto: udp
            host: any
          - port: any
            proto: icmp
            host: any
        outbound:
          - port: any
            proto: any
            host: any

Create /srv/pillar/nebula/client01.sls:

nebula:
  hosts:
    client01:
      ip: "10.10.10.10/24"
      groups:
        - "clients"
      duration: "8760h"

      firewall:
        inbound:
          - port: any
            proto: icmp
            host: any
        outbound:
          - port: any
            proto: any
            host: any

Update /srv/pillar/top.sls:

base:
  '*':
    - nebula.common
  'lighthouse01':
    - nebula.lighthouse01
  'client01':
    - nebula.client01

Refresh pillar data:

salt '*' saltutil.refresh_pillar

Step 4: Initialize the CA

salt-run nebula.ca_init

Expected output:

success: True
ca_crt: /etc/nebula/ca/ca.crt
ca_key: /etc/nebula/ca/ca.key
name: My Nebula Network
duration: 87600h
encrypted: True

Step 5: Generate Certificates

# Generate certificate for the lighthouse
salt-run nebula.get_certificate minion_id=lighthouse01

# Generate certificate for the client
salt-run nebula.get_certificate minion_id=client01

Step 6: Create the Deployment State

Create /srv/salt/nebula/init.sls:

# Ensure Nebula is installed (adjust for your OS)
nebula_package:
  pkg.installed:
    - name: nebula

# Deploy certificates from master
nebula_certificates:
  nebula.certificates_present:
    - name: nebula_certs_{{ grains['id'] }}
    - auto_renew: true
    - renewal_threshold_days: 30
    - backup_old_certs: true
    - validate_after_deploy: true

# Get installation paths
{% set nebula = salt['nebula.detect_paths']() %}
{% set config = salt['nebula.build_config']() %}

# Ensure config directory exists
nebula_config_dir:
  file.directory:
    - name: {{ nebula.config_dir }}
    - mode: 0750
    - makedirs: True

# Generate configuration from pillar
nebula_config:
  file.serialize:
    - name: {{ nebula.config_file }}
    - dataset: {{ config | tojson }}
    - formatter: yaml
    - mode: 0640
    - require:
      - file: nebula_config_dir

# Validate the configuration
nebula_validate:
  module.run:
    - nebula.validate_config: []
    - onchanges:
      - file: nebula_config

# Enable and manage the service
nebula_service_enable:
  module.run:
    - nebula.service_enable: []

nebula_service:
  module.run:
    - nebula.service_restart: []
    - onchanges:
      - file: nebula_config
      - nebula: nebula_certificates
    - require:
      - module: nebula_service_enable

Step 7: Deploy

Apply the state to your nodes:

# Deploy to lighthouse first
salt lighthouse01 state.apply nebula

# Then deploy to clients
salt client01 state.apply nebula

Step 8: Verify Connectivity

Test that the mesh is working:

# Check certificate status
salt '*' nebula.check_certificate_status

# Test connectivity to lighthouse
salt client01 nebula.test_connectivity

# Or ping from the lighthouse
salt lighthouse01 nebula.test_connectivity target_host=10.10.10.10

Troubleshooting

Certificate Issues

# Check certificate details
salt web01 nebula.check_certificate_status

# Validate certificate chain
salt web01 nebula.validate_certificate

# Force certificate regeneration
salt-run nebula.get_certificate minion_id=web01
salt web01 state.apply nebula

Service Issues

# Check service status
salt web01 nebula.service_status

# View detected paths
salt web01 nebula.detect_paths

# Manually restart
salt web01 nebula.service_restart

Pillar Issues

# Verify pillar data
salt web01 pillar.get nebula

# Test pillar access from master
salt-run nebula.test_pillar_access minion_id=web01

# Refresh pillar
salt web01 saltutil.refresh_pillar

Next Steps