WireGuard is a free and open-source VPN, simpler, faster, and more secure than concurrent solutions. It is available as a Linux kernel module, but as a fallback, the Android application contains a user-space implementation that cannot provide the same level of performance and power efficiency as the kernel module.
Although WireGuard was merged into Linux 5.6, most Android devices still use older kernels. There are two methods to install the kernel module on an Android device:
- Patch the kernel during the build process, but the official scripts have been unreliable in the past, and they hook into the Android build process to download the module instead of relying on repo.
- Install a prebuilt module, but they are only available for a restricted set of devices.
This article presents a simple approach for unsupported devices:
- Fetch WireGuard through repo.
- Patch the kernel sources.
- Make the boot image.
- Flash it on the device.
To make the boot image, you need a working LineageOS build environment. See: How to build LineageOS inside a container.
The code samples use the following variables:
SRC_DIR: the top of the source tree (e.g.,
KERNEL_DIR: the relative location of the kernel from
DEVICE: the Android device name (e.g.,
ARCH: the system architecture (e.g.,
Try to make the boot image without WireGuard first, to ensure everything is working properly.
Add the WireGuard module
repository, backported for
older kernel versions, in a local repo manifest (replace
the appropriate path):
The manifest instructs repo to clone the module to
SRC_DIR/kernel/wireguard-linux-compat, and symlink this directory to
repo sync, optionally with
--force-sync, to fetch the module:
§Patch the kernel
The kernel build system needs to know about this module. Add WireGuard to the
Source the WireGuard module config from the
net module config:
Enable WireGuard in the kernel config for the device:
§Make the boot image
Run the pre-build commands:
Then, make the boot image:
§Flash the boot image
There are a few methods to install the boot image (they all end up flashing the boot partition in some way). Depending on how you update your phone, you might prefer to manually flash the boot partition, or to deliver the update through an installation package.
Reboot the device to the bootloader, then run:
This method does not run
/system/addon.d scripts. In particular, Magisk will
not automatically patch the boot image in order to maintain root access.
§Method 2: Patch an installation package
Download the latest installation package for your device.
boot.imginside the archive:
Install with ADB sideload as usual (TWRP ignores invalid signatures, but you may have to sign the build for other recoveries).
After rebooting the device, WireGuard should be using the kernel module as its backend: