Wormhole

Installer and manager of a Pi-hosted Wireguard VPN server. Includes Pi-hole ad blocker and unbound DNS resolver.

• Automated install process suitable for headless Raspberry Pi setups
• docker-compose configuration customizable per-device
• Pre-configured network settings, ssh, firewall
• Automatic migration to SSD / USB storage
• Scheduled updates for Raspberry Pi OS, wormhole script and docker setups
• Backups over ssh

1. Client

wormhole-installer bash script uses official Raspberry Pi rpi-imager tool to download and write the OS image to your media. Runs in CLI. Simplifies installation by moving most of the decision making to the admin of wormhole server. Pulls pre-made user-specific configurations from the server. Utilizes image customization feature to pack the wormhole configuration, scripts and services into firstrun.sh. Provides the client with router configuration insructions. Displays progress and a realtime log of the wormhole installer finalizing setup on the node itself after it was powered on.

Hardware:

Linux machine with a SD-card-reader or SATA/NVMe reader. Can also be the same computer as the server.

2. Server

Powered by Node-RED and defined by a single flow.json file.

• Token authentication for clients and nodes
• Defines and serves node configurations to the installer clients
• Serves configuration updates to the live nodes
• Monitors system state of existing Raspberry Pi nodes

3. Node

wormhole - Management utility bash script. Handles administrative functions and provides commands to manually manage docker stacks and environment, backups, updates, migration and configuration changes.

wormholeinstalld.service - Installs everything else and disables itself in the end. Sends logs of the installation process to the server.

wormholed.service - Main background daemon. Handles telemetry reporting to the server and routine checks on every reboot.

Hardware:

Raspberry Pi

Tested on: Raspberry Pi 4B

Docker stacks and services:

• vpn
  • pihole
  • unbound
  • wireguard
• supervisor:
  • dockge
  • uptime kuma
  • glances

Installation

Client:

1. Pick a directory to store wormhole-installer and cd into it:

mkdir ~/wormhole-installer
cd ~/wormhole-installer

2. Get your token and crypto key from the server. Along with server's url they will be stored in ~/.bashrc. Download and install wormhole-installer, run the following command:

curl -f -s -o install.sh -H "Authorization: Bearer <TOKEN>" <URL>/wh/install && bash install.sh <URL>/wh/install <TOKEN> <CRYPTO_KEY>

3. Connect the SD card or any installation media.

4. From any directory, run:

wormhole-installer

To update to the version currently on the server:

wormhole-installer --update

Show options:

wormhole-installer --help

Server:

1. Clone the repository.

2. Get a running Node-RED instance. If you already have Node-RED, you can skip this step.

   Recommended way is as a docker compose project. You can follow the instuctions here or use this repo's provided docker-compose file.

3. Add the Wormhole flow to Node-RED instance

   Hamburger menu -> Import -> Paste flow json or select and import the provided file

4. Customize environment variables in the flow.

   To get to the environment variable editor in Node-RED GUI, double-click the flow's tab name -> Environment Variables (button).

   Alternatively, environment variables can be set in the 'env' section of the flow json file before importing it.

5. Set the value of crypto_key variable in /scripts/res/settings.sh to a custom string.

6. Deploy the flow.

Node:

1. Connect the storage device with an image written by the wormhole-installer to the Raspberry Pi.
2. If Rapsbery Pi was previously configured to boot from a different device type, physically disconnect those storage devices or change the boot order beforehand. They can be reconnected once the installer on the Pi passes the first stage.
3. Wait

Configuration

users:
  default:
    generic:
      hostname: generic
      description: Example of a generic minimal configuration
      device-tag: pi4-64bit
      search: Pi OS
  username:
    empty: null
    config-name:
      hostname: wormholenode
      description: Example of a full custom configuration
      device-tag: pi4-64bit
      search: Pi OS Lite
      timezone: Europe/London
      ip-addr: 192.168.0.11
      domain: https://mydomain.com
      wh-port: 40820
      boot-device: USB
      boot-device2: SDCARD
      autoupdate-self: disabled
      autoupdate-system: 0 3 * * 3
      stacks-dir: /common/custom_docker_dir/
      wifi:
        ssid: WiFi SSID
        password: changeme
        encrypted: false
        loc: GB
      ssh:
        port: 22
        user: sshuser
        encrypted: false
        password: changeme

Backups

To enable backups, add env variables to /etc/environment file on the Node:

• To upload backups to the wormhole server over http(s), add line WH_REMOTE_BACKUP_DESTINATION=server.

• To upload backups via ssh, add line WH_REMOTE_BACKUP_DESTINATION=<username>@<host>:<port>. Edit username, port and host. Skip the port and ":" to use default ssh port 22. Manually generate a key and copy the identity to the destination host.

• To set a custom backup directory, add line WH_REMOTE_BACKUP_DIR=<path>. This directory should exist on the ssh server. Defaults to /home/wormhole/backups

Uninstallation

Client:

Run:

wormhole-installer --uninstall

Alternatively, cd into install directory and run:

./uninstall.sh

Server:

Disable or delete the Node-RED flow

Motivation

Primary goal is simpifying the OS flashing and first setup for the user on the client side by offloading most of the decisions to the user on the server side. Client's installation script is designerd to be simple and interactive, provide detailed instructions and progress status. It also reports progress to the server to simplify support and troubleshooting.

TODOs:

• add compression to wh-backup and restore

Issues:

Feel free to open an issue if you found a bug or have an improvement suggestion.

Acknowledgments

Server running on Node-RED.

Docker-compose project for the node is based on wirehole project. Main functionality provided by:

• WireGuard (image linuxserver/wireguard)
• Unbound (image mvance/unbound-rpi)
• Pi-hole (image pihole/pihole)

Installer makes use of the official Raspberry Pi Imager.

Migration powered by rpi-clone.

License

Unless otherwise specified, all code is released under the MIT License (MIT).

Licenses for other projects

• Node-RED Apache 2.0
• rpi-clone BSD 3-Clause
• rpi-imager LGPL v3
• Docker: Apache 2.0
• WireGuard GPL v2
• Pi-hole EUPL v1.2
• Unbound: BSD License