WireGuard® is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography.
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.
Device Type | OS Version |
---|---|
Raspberry Pi 3 | 2.80.3+rev1 |
Raspberry Pi 3 | 2.83.21+rev1 |
Raspberry Pi 4 (using 64bit OS) | 2.83.10+rev1 |
Generic x86_64 | 2.83.18+rev1 |
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.
You can one-click-deploy this project to balena using the button below:
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.
Name | Description |
---|---|
SERVER_HOST |
External IP or domain name for docker host. Used in server mode. If set to auto the container will try to determine and set the external IP automatically. |
SERVER_PORT |
External port for docker host. Defaults to 51820 . |
PEERS |
Number of peers to create confs for. Can be a number like 4 or a list of names such as myPC,myPhone,myTablet . |
PEER_DNS |
DNS server set in peer/client configs. Defaults to 1.1.1.1 . |
CIDR |
Internal network CIDR for the wireguard and server and peers. Defaults to 10.13.13.0/24 . |
ALLOWEDIPS |
The IPs/Ranges that the peers will be able to reach using the VPN connection. If not specified the default value is 0.0.0.0/0, ::0/0 . This will cause ALL traffic to route through the VPN, if you want split tunneling, set this to only the IPs you would like to use the tunnel AND the ip of the server's WG ip, such as 10.13.13.1. |
DISABLE_USERSPACE |
Optionally disable the fallback wireguard-go userspace module. |
SET_HOSTNAME |
Set a custom hostname on application start. Defaults to wireguard . |
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/
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.
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.
Please open an issue or submit a pull request with any features, fixes, or changes.
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.