Nebula Domain Bootstrap
Onboards a Windows machine to the Nebula mesh network and joins it to an Active Directory domain. Designed to be run once by a local Administrator on a fresh Windows install.
Nebula version: 1.10.3 (downloaded from GitHub at install time)
For domain controller setup requirements, see DC-SETUP.md.
Prerequisites
Before running, you need the following per-host files prepared by the domain administrator:
config.yml— Nebula configuration (use forward slashes in all paths)host.crt— Nebula certificate signed by the CAhost.key— Nebula private key
These files are unique to each machine and should be placed in a directory you will run the scripts from.
Package Contents
| File | Purpose |
|---|---|
bootstrap.ps1 |
Runs all three steps in sequence |
install-nebula.ps1 |
Downloads Nebula and installs it as a Windows service |
set-dns.ps1 |
Points the Nebula adapter's DNS at the domain controller |
join-domain.ps1 |
Joins the machine to the domain |
Usage
All scripts require an Administrator PowerShell session. If script execution is blocked, run this first:
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
One-shot bootstrap
From the directory containing your per-host files (config.yml, host.crt, host.key):
& "C:\path\to\nebula\bootstrap.ps1" -DnsServer 10.10.10.13 -Domain "arvandor.internal"
Optionally pass -ComputerName to validate the machine name matches a pre-staged AD object:
& "C:\path\to\nebula\bootstrap.ps1" -DnsServer 10.10.10.13 -Domain "arvandor.internal" -ComputerName "WS-NAME"
This runs all three steps in order, prompts for domain credentials, and offers to restart when finished.
Step-by-step
If you need to run steps individually:
# 1. Install Nebula
& "C:\path\to\nebula\install-nebula.ps1"
# 2. Point DNS at the domain controller
& "C:\path\to\nebula\set-dns.ps1" -DnsServer 10.10.10.13
# 3. Join domain
& "C:\path\to\nebula\join-domain.ps1" -Domain "arvandor.internal"
Parameters
set-dns.ps1
-DnsServer(required) — IP address of the domain controller-InterfaceAlias(optional) — Target a specific adapter. Defaults tonebula1
join-domain.ps1
-Domain(required) — FQDN of the Active Directory domain-ComputerName(optional) — Expected NetBIOS name (max 15 characters). If provided and the current machine name doesn't match, the script warns but proceeds with the join under the current name.
Deployment Flow
- Create a computer object in Active Directory in the appropriate OU
- Sign a Nebula certificate for the machine with the correct group (e.g.,
workstations) - Install Windows on the target machine
- If using a pre-staged AD object: rename the machine to match and reboot before proceeding
Rename-Computer -NewName "WS-NAME" -Restart - As a local Administrator, run the bootstrap with the per-host files
- Restart — the machine will authenticate against the domain controller over Nebula at the login screen and pull Group Policy
Idempotency
All scripts are safe to re-run:
install-nebula.ps1— Skips reinstall if the service is already running with the correct version and matching files. Tears down and rebuilds if the version or files have changed.set-dns.ps1— Overwrites the existing DNS setting on the Nebula adapter.join-domain.ps1— Skips the join if already on the domain.
Architecture
- Nebula provides the encrypted mesh network. It runs as a
LocalSystemservice withdelayed-autostart, depending onTcpipandNlaSvc(Network Location Awareness). This ensures the physical network is connected before Nebula attempts handshakes. - DNS is configured only on the
nebula1adapter. Physical adapters (Wi-Fi, Ethernet) keep their DHCP-assigned DNS so they can reach the internet and Nebula lighthouses independently. - Domain trust flows through the Nebula tunnel. The domain controller is reachable at its Nebula IP, so machines do not need a VPN or physical proximity to the DC.
Troubleshooting
Scripts won't run
PowerShell execution policy is blocking unsigned scripts. Run Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process in the same terminal before retrying. This only affects the current session.
"This script must be run as a machine Administrator"
Right-click PowerShell and select Run as Administrator, or use an elevated terminal.
Nebula service fails to start
Check the Application event log:
Get-WinEvent -FilterHashtable @{LogName='Application'; ProviderName='nebula'} -MaxEvents 10 | Format-List TimeCreated, Message
Common causes:
- "found unknown escape character" — Backslashes in
config.ymlpaths. YAML interprets\as escape characters inside double quotes. Use forward slashes (C:/Program Files/Nebula/ca.crt). - "no config files found" — The service was installed without
-config. Reinstall usinginstall-nebula.ps1.
Handshake timeouts after reboot
Nebula started before the physical network was ready. Verify the service is configured with delayed start and NLA dependency:
sc qc nebula
Expected: START_TYPE: AUTO_START (DELAYED) with DEPENDENCIES: Tcpip, NlaSvc. Re-run install-nebula.ps1 to fix.
DNS resolution fails
Verify DNS is set on the Nebula adapter only:
Get-DnsClientServerAddress -InterfaceAlias "nebula1" -AddressFamily IPv4
If DNS was accidentally set on Wi-Fi/Ethernet, reset it:
Set-DnsClientServerAddress -InterfaceAlias "Wi-Fi" -ResetServerAddresses
Computer name mismatch warning during domain join
The script warns if the machine's current name doesn't match the -ComputerName parameter. If you have a pre-staged AD object, rename the machine and reboot before running bootstrap:
Rename-Computer -NewName "WS-NAME" -Restart
Then re-run bootstrap. The machine will present the correct name to AD and auto-match the pre-staged object.
Cannot reach domain controller at login screen
The Nebula tunnel must be established before Windows attempts domain authentication. Verify:
- Nebula service is running:
sc query nebula - Tunnel is active:
ping 10.10.10.13 - DNS resolves:
nslookup arvandor.internal
If the service is running but handshakes fail, check that the machine's Nebula certificate group has firewall access to the ad group.
License
This project is licensed under the MIT License. See LICENSE for details.