`nebula`¶

Nebula certificate management runner for Salt master.

This runner handles Nebula VPN certificate generation and management. It reads minion configuration from pillar, generates certificates using the nebula-cert binary, and makes them available via the Salt file server for minion retrieval.

depends:

nebula-cert binary on the Salt master

configuration:

The following options can be set in the master config:

# Path 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 configuration
nebula.ca_name: "My Nebula Network"
nebula.ca_duration: "87600h"    # 10 years
nebula.ca_encrypt: true         # Encrypt CA private key
nebula.ca_passphrase: "secure-passphrase-here"

saltext.nebula.runners.nebula.get_certificate(minion_id, auto_generate=True, validate_existing=True, **_kwargs)[source]¶

Get or generate a Nebula certificate for a minion.

Retrieves the minion’s Nebula configuration from pillar and either returns an existing valid certificate or generates a new one. Generated certificates are automatically copied to the Salt file server for minion retrieval.

minion_id: The minion ID to generate a certificate for. Must have corresponding configuration in pillar under nebula:hosts:<minion_id>.
auto_generate: Whether to automatically generate a certificate if one doesn’t exist or validation fails. Default: True
validate_existing: Whether to validate existing certificates before returning them. If validation fails and auto_generate is True, a new certificate will be generated. Default: True

CLI Example:

salt-run nebula.get_certificate minion_id=web01
salt-run nebula.get_certificate minion_id=web01 auto_generate=False
salt-run nebula.get_certificate minion_id=web01 validate_existing=False

Required pillar structure:

nebula:
  hosts:
    web01:
      ip: "172.25.1.10/20"
      groups:
        - webservers
        - managed
      duration: "720h"

Returns:

Dictionary containing:

success: Whether the operation succeeded
cert_content: PEM-encoded certificate (if successful)
key_content: PEM-encoded private key (if successful)
ca_content: PEM-encoded CA certificate (if successful)
ip: Assigned Nebula IP address
groups: List of groups the certificate is valid for
source: ‘existing’ or ‘generated’
error: Error message (if failed)

Return type:

dict

saltext.nebula.runners.nebula.list_certificates()[source]¶

List all Nebula certificates managed by this runner.

Scans the certificate directory for all .crt files (excluding the CA) and returns information about each certificate.

CLI Example:

salt-run nebula.list_certificates

Returns:

Dictionary containing:

success: Whether the operation succeeded
certificates: List of certificate info dictionaries
total: Total number of certificates found
error: Error message (if failed)

Return type:

dict

Each certificate dictionary contains:

minion_id: The minion ID (derived from filename)
cert_path: Full path to the certificate file
key_path: Full path to the corresponding key file
key_exists: Whether the key file exists
cert_size: Size of the certificate file in bytes
modified: ISO format timestamp of last modification

saltext.nebula.runners.nebula.ca_init(name=None, duration=None, encrypt=None, passphrase=None, force=False)[source]¶

Initialize a new Nebula Certificate Authority.

Creates a new CA certificate and private key for signing host certificates. This should be run once during initial setup of the Nebula network.

name: Name for the CA certificate. Defaults to nebula.ca_name from config or “Salt Managed Nebula Network”.
duration: Validity duration for the CA certificate. Defaults to nebula.ca_duration from config or “87600h” (10 years).
encrypt: Whether to encrypt the CA private key with a passphrase. Defaults to nebula.ca_encrypt from config or False.
passphrase: Passphrase for encrypting the CA private key. Required if encrypt=True. Defaults to nebula.ca_passphrase from config.
force: If True, overwrite existing CA files. Default: False. WARNING: This will invalidate all existing certificates!

CLI Example:

# Basic CA initialization (uses config defaults)
salt-run nebula.ca_init

# With custom name and duration
salt-run nebula.ca_init name="Production Nebula" duration="43800h"

# With encryption
salt-run nebula.ca_init encrypt=True passphrase="secure-passphrase"

# Force regeneration (WARNING: invalidates all certs!)
salt-run nebula.ca_init force=True

Returns:

Dictionary containing:

success: Whether the operation succeeded
ca_crt: Path to the CA certificate
ca_key: Path to the CA private key
name: Name of the CA
duration: Validity duration
encrypted: Whether the key is encrypted
error: Error message (if failed)

Return type:

dict

saltext.nebula.runners.nebula.test_pillar_access(minion_id)[source]¶

Test function to debug pillar access for a minion.

Useful for troubleshooting when certificate generation fails due to missing or incorrect pillar configuration.

minion_id: The minion ID to check pillar data for.

CLI Example:

salt-run nebula.test_pillar_access minion_id=web01

Returns:

Dictionary containing:

success: Whether pillar data was retrieved
pillar_data: Complete pillar data for the minion
nebula_config: Just the nebula section of pillar
host_config: Just the host-specific nebula config
error: Error message (if failed)

Return type:

dict

saltext.nebula.runners.nebula.show_config(minion_id, config_dir='/etc/nebula')[source]¶

Render the Nebula config a target minion would receive, computed on the master.

This compiles the minion’s pillar on the master (via pillar.show_pillar) and assembles the same configuration nebula.build_config would produce on the minion, without contacting the minion. It is handy for previewing or diffing a node’s config, and for the single-master case where you want to render (and then write) the master’s own Nebula config locally rather than standing up a second master to highstate it. For example:

salt-run nebula.show_config minion_id=$(salt-call --local grains.get id --out=newline_values_only) --out=yaml > /etc/nebula/nebula.yml

Because the master has no minion grains for the target, the PKI paths use the standard layout under config_dir (<config_dir>/ca.crt and <config_dir>/<minion_id>.{crt,key}) rather than autodetecting an install.

minion_id: The minion ID to render configuration for.
config_dir: Directory used to construct the pki file paths. Defaults to /etc/nebula.

CLI Example:

salt-run nebula.show_config minion_id=web01
salt-run nebula.show_config minion_id=web01 --out=yaml

Returns:: The assembled Nebula configuration, ready for YAML serialization.
Return type:: dict

nebula¶

`nebula`¶