nebula

Nebula execution module for Salt minions.

Provides path detection, certificate management, configuration building, service control, and connectivity testing for Nebula mesh VPN deployments.

All platform-specific complexity is handled here so that states can remain thin orchestration layers.

depends:

nebula-cert binary for certificate operations

saltext.nebula.modules.nebula.__virtual__()

Always load – path detection handles missing installations gracefully.

saltext.nebula.modules.nebula.detect_paths()

Detect Nebula installation paths based on platform and install method.

Returns all paths needed by states and other module functions, including derived paths for config files, certificates, and backups.

CLI Example:

salt '*' nebula.detect_paths

Returns:

Comprehensive path information including binary_path,

cert_binary_path, config_dir, cert_dir, config_file, ca_file, cert_file, key_file, backup_dir, service_name, install_method, user, group, file_mode, dir_mode, path_sep.

Return type:

dict

saltext.nebula.modules.nebula.parse_cert_expiry(cert_path=None, cert_content=None)

Parse the expiration date from a Nebula certificate.

cert_path

Path to the certificate file.

cert_content

Raw certificate content as a string.

CLI Example:

salt '*' nebula.parse_cert_expiry cert_path=/etc/nebula/host.crt

Returns:

success, expires_at, days_until_expiry (or error).

Return type:

dict

saltext.nebula.modules.nebula.cert_needs_renewal(cert_path=None, buffer_days=30)

Check whether a Nebula certificate needs renewal.

cert_path

Path to the certificate file. Auto-detected if omitted.

buffer_days

Days before expiration to trigger renewal. Default: 30

CLI Example:

salt '*' nebula.cert_needs_renewal
salt '*' nebula.cert_needs_renewal buffer_days=14

Returns:

needs_renewal (bool), reason, and optionally expires_at / days_until_expiry.

Return type:

dict

saltext.nebula.modules.nebula.check_certificate_status(cert_path=None)

Comprehensive certificate status check.

CLI Example:

salt '*' nebula.check_certificate_status

Returns:

minion_id, install_method, paths, existence booleans,

validity, expiry information.

Return type:

dict

saltext.nebula.modules.nebula.validate_certificate(cert_path=None, ca_path=None)

Validate a certificate against the CA using nebula-cert verify.

CLI Example:

salt '*' nebula.validate_certificate

Returns:

valid (bool), error (if invalid).

Return type:

dict

saltext.nebula.modules.nebula.build_config(minion_id=None)

Build a complete Nebula configuration dictionary from pillar data.

Merges common-level settings with host-level overrides. Merge semantics vary by section:

• Firewall inbound/outbound rule lists: host rules replace common rules entirely (not appended), since firewall policy should be defined explicitly per host.

• remote_allow_list: shallow per-key merge (host keys win over common).

• static_host_map: per-overlay-IP override (host/common entries replace the derived endpoint list for that IP, or add a new IP).

• tun / punchy / logging / conntrack: deep-merged over the built-in defaults (common then host), so only overridden keys change.

Lighthouse static_host_map keys are derived from nebula_ip (comma- separated string yields one overlay key per address). Each key maps to the same public endpoint list from public_ip (comma-separated; each value becomes addr:port).

minion_id

Minion to build config for. Defaults to current minion.

CLI Example:

salt '*' nebula.build_config
salt '*' nebula.build_config minion_id=web01

Returns:

Complete nebula configuration ready for YAML serialization.

Return type:

dict

saltext.nebula.modules.nebula.backup_config()

Back up the current Nebula configuration file.

Creates a timestamped copy in the backup directory and updates a last_known_good symlink. Only performs the backup if the service is currently running (i.e. the config is known-good).

CLI Example:

salt '*' nebula.backup_config

Returns:

success (bool), backup_path (if created), message.

Return type:

dict

saltext.nebula.modules.nebula.validate_config()

Validate the current Nebula deployment (certificate chain check).

Runs nebula-cert verify against the deployed CA and host certificate.

CLI Example:

salt '*' nebula.validate_config

Returns:

valid (bool), error (if invalid).

Return type:

dict

saltext.nebula.modules.nebula.rollback_config()

Restore the last known good configuration.

Copies the last_known_good backup over the current config file.

CLI Example:

salt '*' nebula.rollback_config

Returns:

success (bool), message.

Return type:

dict

saltext.nebula.modules.nebula.service_restart()

Restart the Nebula service using the platform-appropriate method.

Handles systemd, OpenRC, snap, and Windows services transparently.

CLI Example:

salt '*' nebula.service_restart

Returns:

success (bool), message.

Return type:

dict

saltext.nebula.modules.nebula.service_status()

Check whether the Nebula service is running.

CLI Example:

salt '*' nebula.service_status

Returns:

running (bool), message.

Return type:

dict

saltext.nebula.modules.nebula.service_enable()

Enable the Nebula service to start on boot.

CLI Example:

salt '*' nebula.service_enable

Returns:

success (bool), message.

Return type:

dict

saltext.nebula.modules.nebula.purge(remove_package=True)

Completely remove Nebula from the system.

Stops the service, removes configuration, certificates, and optionally the package itself. This is a destructive, non-idempotent operation intended for decommissioning a node or starting fresh.

remove_package

Whether to also remove the Nebula package. Default: True

CLI Example:

salt '*' nebula.purge
salt '*' nebula.purge remove_package=False

Returns:

success (bool), actions (list of what was done), errors (list).

Return type:

dict

saltext.nebula.modules.nebula.test_connectivity(target_host=None, timeout=10)

Test Nebula mesh connectivity via ping.

target_host

Nebula IP to ping. Defaults to first lighthouse from pillar.

timeout

Ping timeout in seconds. Default: 10

CLI Example:

salt '*' nebula.test_connectivity
salt '*' nebula.test_connectivity target_host=172.25.0.1

Returns:

success (bool), target_host, ping_success, ping_output.

Return type:

dict