From postmarketOS
Jump to navigation Jump to search


Wireguard is modern, low-latency VPN, available in upstream Alpine repo. Not only it is fast and secure, but also very simple and straightforward in configuration. Among all VPN techlologies, it is the simplest (from user's viewpoint) and the least wayward one.

Wireguard tunnel

To enable wireguard tunneling, your kernel must be compiled with its support - which results in wireguard.ko driver module somewhere (depending on kernel version) in /lib/modules/kernel-version/kernel. Strange enough, wireguard support is disabled in default Alpine kernel - and thus in pmOS, too. You need to rebuild the kernel with the following settings:


or, in terms of menuconfig tree,

Device Drivers  --->
    [*] Network device support  --->
        [*] Network core driver support
        <M>   WireGuard secure network tunnel

_*_ Cryptographic API  --->
    <M> ECDSA (NIST P192, P256 etc.) algorithm

While running pmOS, you can check the details by running below command in terminal

$ modinfo wireguard

It prints module details like filename, author, etc. If it prints something like:

modinfo: module '/lib/modules/${uname -r}/wireguard' not found

the kernel must be rebuilt, see below.

wg-quick and nftables

wg-quick is a popular script that does a lot of routine work to set up the IP stack on top of the newly created Wireguard intreface: IP address, routing, DNS, and firewall settings. For the latter task, it relies heavily onto nftables, which, it turn, also requires kernel support as follows:


or, in menuconfig:

Networking support  --->
    Networking options  --->
    [*] Network packet filtering framework (Netfilter)  --->
            IP: Netfilter Configuration  --->
                _*_ IPv4 nf_tables support
                <M> nf_tables fib / ip route lookup support
            IPv6: Netfilter Configuration  --->
                _*_ IPv6 nf_tables support
                <M> nf_tables fib / ip route lookup support
            Core Netfilter Configuration  --->
                <M> Netfilter nf_tables support
                [*]   Netfilter nf_tables netdev tables support
                <M>   Netfilter nf_tables fib inet support
                <M>   Netfilter nf_tables netdev fib lookups support

Note that some of these settings depend upon the previous ones. These settings are present in default Alpine kernel configurations but not in pmOS ones.

Note To consider including the the above settings, as well as other nftables modules, into default kernels, address your merge requests to Alpine and pmOS maintainers, respectively.


Recompiling kernel

To add the above settings to the kernel yourself:

1. Remove the existing chroot and packages

$ pmbootstrap -y zap -p

2. Configure the kernel

$ pmbootstrap kconfig edit YOUR-KERNEL-PACKAGE

This invokes menu tool for kernel configuration and packs the new configuration file back into the package. Set the abovementioned options. See Kernel configuration for package naming and other details.

3. Rebuild the kernel for your particular installation

$ pmbootstrap build --force YOUR-KERNEL-PACKAGE

4. Build and install pmOS in your usual way

$ pmbootstrap install ...

Setup and usage

To use Wireguard tunnels, you need wireguard-tools-wg-quick package. It may be added manually after installation, or included in your basic software suite at pmbootstrap init step. There is no separate wireguard package in Alpine and pmOS. There are other Wireguard tools to be considered as well.

Standard location for configuration of Wireguard tunnels is /etc/wireguard/interface.conf. The directory should be readable for root only (chmod 700, and chmod 600 for files in it) as it contains private keys of the host. Once wg-quick is installed, tunnels may be started/stopped as follows:

$ sudo wg-quick up INTERFACE
$ sudo wg-quick down INTERFACE

with INTERFACE being a name of one of the .conf files.

Integration with other applications

GUI applications

As of now, there is no dedicated GUI application for Wireguard management in Linux. (Unlike the other OSes.) Use terminal instead. Probably someone will write it one day, or adopt the existing Android/IOS app for pmOS phones (apart from desktops/notebooks). In some desktop environments, there are (or may appear in the future) Wireguard plugins for their regular network management tools.

NetworkManger integration

In mobian there is easy way to manage Wireguard with automatically filled pre and post hooks.

$ nmcli connection import type Wireguard file /path/to/wg.conf

However, because of (probably) some lack in packaging, pre and post hooks interfaces are not set properly. So you are connected to your rely but DNS doesn't work.

DNS dependence

In certain use cases, you may need to use a particular DNS server at the other side of the tunnel instead the default one. To that purpose, there is the DNS= setting in config file for wg-quick. (But not for wireguard itself !)

To perform the task, wg-quick and probably other tools running on top of Wireguard itself need addtitional tools to set up DNS for wireguard interface. In most distributions and packages, openresolv|resolvconf are listed as recommended - but not mandatory - dependencies.

In Alpine and pmOS, wireguard-tools-wg-quick does install openresolv unconditionally, thus DNS setting works out of the box.

In other distributions and setups (including Network Manager as described above?) you may need to install this dependence manually.