balena-wireguard

WireGuard® is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography.

Supported Devices

The following device and OS combinations have been somewhat tested. Please consider updating this table and balena.yml if you have tried a new combination.

Note that the Fleet Architecture must match the Device Architecture for kernel module support!

So if using mixed device Fleets, check that the architecture is the same for all devices.

Getting Started

You can one-click-deploy this project to balena using the button below:

Manual Deployment

Alternatively, deployment can be carried out by manually creating a balenaCloud account and application, flashing a device, downloading the project and pushing it via the balena CLI.

Environment Variables

Usage/Examples

Once your device joins the fleet you'll need to allow some time for it to download the application and start the services.

When it's done you can display QR codes for each peer by running show-peer <peer> in the container shell.

For example, the following CLI command will show the QR code for myPhone:

echo "show-peer myPhone; exit;" | balena ssh <UUID> wireguard

Additional usage instructions for wireguard can be found here: https://www.wireguard.com/

Kernel Module

The default behaviour for maximum device compatibility is to compile the Wireguard kernel module on first app start. This allows checking the version of the running Host OS before downloading kernel sources.

You can optionally build the kernel module ahead of time, during the application build stage, by setting the following ARGS in Dockerfile.template.

ARG BALENA_DEVICE_TYPE=%%BALENA_MACHINE_NAME%%
ARG BALENA_HOST_OS_VERSION=2.80.3+rev1

Alternatively, you can set the ARGS via docker-compose.yml file:

services:
  wireguard:
    build:
        context: .
        dockerfile: Dockerfile.template
        args:
            BALENA_DEVICE_TYPE: raspberrypi4-64
            BALENA_HOST_OS_VERSION: 2.85.2+rev3
    privileged: true

This makes for much faster app startup but must match the environment of the target device.

Deploying a release with a pre-built module to an incompatible device type or version may fail to load and instead fallback to the wireguard-go userspace module.

If either of those ARGS are not set, the module build will be postponed until runtime when the device type and Host OS version can be checked by the script.

Userspace Module

If the kernel module fails to build, or load, for any reason including those mentioned above, the application will automatically use the wireguard-go userspace module instead. This operates the same and should work on all platforms but will incur some performance penalties.

Contributing

Please open an issue or submit a pull request with any features, fixes, or changes.

Versioning

Note that the current CI workflow will bump the version in the main branch after the merged balenaCloud release has been deployed as final.

As such, breaking changes may be introduced in x.y.z-rev releases in the balenaCloud dashboard with no indication that the major version was bumped as part of the same merge.

However each balenaCloud release version (draft or final) will be tagged on the associated git commit so that should be used as the source of truth.

Acknowledgements

• https://www.balena.io/blog/how-to-run-wireguard-vpn-in-balenaos/
• https://www.wireguard.com/compilation/
• https://github.com/linuxserver/docker-wireguard
• https://github.com/balena-os/kernel-module-build
• https://github.com/jaredallard-home/wireguard-balena-rpi