{"id":35452809,"url":"https://github.com/erykjj/nebulder","last_synced_at":"2026-01-18T07:13:57.520Z","repository":{"id":189832769,"uuid":"678996446","full_name":"erykjj/nebulder","owner":"erykjj","description":"Build self-updating Nebula deployment packages based on a simple network outline","archived":false,"fork":false,"pushed_at":"2026-01-13T23:53:46.000Z","size":42787,"stargazers_count":11,"open_issues_count":0,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-14T00:43:05.784Z","etag":null,"topics":["mesh-generation","mesh-network","nebula","nebula-update","nebula-vpn","overlay-network","vpn-setup"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/erykjj.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-08-15T21:49:26.000Z","updated_at":"2026-01-13T23:53:40.000Z","dependencies_parsed_at":"2023-08-22T00:55:20.893Z","dependency_job_id":"3c702f33-82c2-45a6-b8b1-78bc036e3aa9","html_url":"https://github.com/erykjj/nebulder","commit_stats":null,"previous_names":["erykjj/nebulder"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/erykjj/nebulder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erykjj%2Fnebulder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erykjj%2Fnebulder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erykjj%2Fnebulder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erykjj%2Fnebulder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/erykjj","download_url":"https://codeload.github.com/erykjj/nebulder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erykjj%2Fnebulder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28532783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mesh-generation","mesh-network","nebula","nebula-update","nebula-vpn","overlay-network","vpn-setup"],"created_at":"2026-01-03T04:08:46.673Z","updated_at":"2026-01-18T07:13:57.515Z","avatar_url":"https://github.com/erykjj.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nebulder v2[^*]\n\nPronounced \"NEH-byool-der\" (/ˈnɛb.jʊl.dɚ/) - a composite of *Nebula* + *builder*\n\n## Python script to \"build\" deployment packages for [Nebula](https://nebula.defined.net/docs) mesh/overlay networks\n\nThe script has only been tested under Linux and the latest *nebula-cert* binary has to be in your path. It requires Python3 and PyYAML: `pip install pyyaml`\n\n\u003cdetails\u003e\u003csummary\u003e[EXPAND] HOWTO\u003c/summary\u003e\u003cbr/\u003e\n\n1. Define your mesh network by creating an 'outline' (config file in YAML format) listing all the nodes (including at least one lighthouse)\n   - See the [*sample_outline.yaml*](https://github.com/erykjj/nebulder/blob/main/res/sample_outline.yaml) for format layout and available attributes\n2. If you want to set up auto-updating (Linux, macOS, Windows), you will need to include an *update.conf* file next to your outline ([*sample_update.conf*](https://github.com/erykjj/nebulder/blob/main/res/sample_update.conf))\n    - Indicate a web server with basic auth where each node will check for updates\n    - If you want to receive notifications via *ntfy.sh*, provide the channel these notifications will be sent to\n3. Execute this *nebulder.py* script. It will generate the *config.yaml* interface configuration file and other necessary files for each device/node in its own deployment package/folder\n    - An `update_password` key will be automatically generated (if it doesn't already exist) for each node/lighthouse; this will be used to encrypt the zipped update packages. The modified outline will replace the original - keep this safe ;-)\n4. If installing *for the first time* (or updating the binaries), place the latest **binaries** from the [Nebula repo](https://github.com/slackhq/nebula/releases/latest) into each node's deployment folder[^#] - make sure they are for the correct OS/architecture:\n    - Linux and macOS will need the *nebula* binary\n    - Windows will need *nebula.exe* as well as the *dist* directory tree (*wintun.dll* driver)\n5. Copy each deployment package to the corresponding device\n6. Execute the deployment script on each device (from within package folder copied to the device):\n    - On **Linux** (requires *systemd*) execute `sudo bash deploy.sh` to install or update. The script will (re)place the binary in `/usr/lib/nebula/[tun_device]/` and the config and keys in `/etc/nebula/[tun_device]/`, and will create and (re)start a *systemd* service. The *tun_device* (mesh network name from the outline YAML) is used as a subdirectory to support multiple independent Nebula networks on the same machine\n      - A *remove.sh* script is also included for removing/cleaning up\n    - On **Windows**, execute (as Administrator in *PowerShell*) the *deploy.ps1* script; the install directory on Windows (for *all* files) is `C:\\nebula\\[tun_device]\\`; the script will also install and start a Windows service\n    - For installation on mobile devices (**Android and iOS**), follow the [Nebula documentation](https://nebula.defined.net/docs/guides/quick-start/). QR codes are included in the package to make the process simpler, but there is no script included and you'll need the official apps\n    - On **MacOS** we follow a similar approach to Linux, except for using `/usr/local/lib` and `/usr/local/etc/`, and *launchd* for background services\n7. **Lighthouses** need to be reachable from other nodes, so they typically require a public IP address. You may need to set up NAT/port forwarding, dynamic DNS, or use a cloud VPS for this purpose; you may also have to tweak your system firewall to allow UDP connections through to your network interface\n8. If you set up **auto-update**, when you execute *nebulder.py* with `-Z`, it will generate zipped and encrypted deployment/update packages (which only the designated node will be able to open); copy these (along with the *version.txt* file) to your web server's update directory\n    - The update service that has been configured on each node checks for updates every 15 min\n    - It will check if the contents of *version.txt* are different from the local version, which would indicate that an update package for the node should be available\n    - It will then attempt to download, decrypt, unzip and deploy it automatically\n    - If you configured *ntfy.sh* notifications, you'll receive confirmation messages for successful updates or error alerts\n\nNOTE: Keep in mind that (by design and by default) Nebula certificate authority keys expire in 1 year, and so do all the certificates signed with these keys. Within that period, you can re-use the *ca.key* to generate more devices/nodes, or update existing ones with new binaries. So, **keep *ca.key* (and your outline) safe**. To renew (i.e., generate new certificate authority keys), remove the *ca.key* and *ca.crt* files from the destination directory, re-run the `nebulder.py` script, and deploy again on every device; or, upload the update packages to your server for nodes with auto-update enabled to deploy themselves. Keep in mind that while deploying; the nebula service on the node goes down; also, if changing the certificate authority, there may be a lost connection until the node and lighthouse(s) are using the same updated certificate.\n\u003c/details\u003e\u003cbr/\u003e\n\n\u003cdetails\u003e\u003csummary\u003e[EXPAND] Command-line usage\u003c/summary\u003e\u003cbr/\u003e\n\n```\nusage: python3 nebulder.py [-h] [-v] [-o directory] [-Z] [-V id] outline\n\nGenerate Nebula configs based on a network outline\n\npositional arguments:\n  outline        Network outline (YAML format)\n\noptions:\n  -h, --help     show this help message and exit\n  -v, --version  show program's version number and exit\n  -o directory   Output directory (defaults to dir where outline is located)\n  -Z             Zip and encrypt packages (for auto-update)\n  -V id          Config version number or id (optional)\n```\n\nNOTE: `-V id` is optional; versioning is via an auto-incrementing *version.txt* file (starting at \"v1.0.0\" by default), or one can specify the version number/id\n\u003c/details\u003e\u003cbr/\u003e\n\n____\n## Feedback\n\nFeel free to [get in touch and post any issues and suggestions](https://github.com/erykjj/nebulder/issues).\n\n[![RSS of releases](res/rss-36.png)](https://github.com/erykjj/nebulder/releases.atom)\n\n____\n[^*]: Due to changed paths, etc., if you are upgrading the nodes from v1, ensure you clean up their current installs first; otherwise, you may have conflicting services\n[^#]: The binaries (and the Windows *wintun* driver) only need to be in the package folder for initial deployment or if updating theses binaries on the node(s)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferykjj%2Fnebulder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferykjj%2Fnebulder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferykjj%2Fnebulder/lists"}