WireGuard VPN Client

WireGuard is built into the Linux kernel and natively supported by Ubiquiti UniFi. The setup is straightforward: configure the WireGuard server on Prevernal (the Burnage Mad House router), generate a client configuration file from the UniFi interface, and import it into NetworkManager on the desktop. Once done, connecting to the home network from anywhere is a single click.

This page covers the complete workflow: server-side setup on UniFi and desktop client configuration on Kubuntu.

Server-side setup on UniFi (Prevernal)

Enable WireGuard VPN Server

Log into the UniFi Network application for Prevernal. Navigate to Settings > VPN > VPN Server. Click Create New and select WireGuard.

Configure the server:

The dedicated VPN client subnet (10.1.254.0/24) should not overlap with any of the existing VLANs in the network design. It sits within the 10.1.0.0/16 block for Burnage but is kept separate from the named VLANs.

Dynamic DNS

If your home internet connection does not have a static public IP address, configure a DDNS hostname so the VPN endpoint address is stable. Under Advanced, enable Use Alternate Address for Clients and enter your DDNS hostname. This hostname is used as the Endpoint in all client configuration files.

The DDNS setup itself is covered in the router section of this series.

Port forwarding

If the UniFi gateway is behind a NAT firewall, the WireGuard port (default 51820, or whichever port you chose) needs to be forwarded to the UniFi gateway’s WAN IP address. For a home internet connection where the UniFi router is directly connected to the ISP modem in bridge mode, this is not needed. For a connection where another router sits between the ISP and Prevernal, add a UDP port forward.

Adding a client

Under the WireGuard server configuration, click Add Client. Give the client a descriptive name matching the device it will be used on, for example desktop-burnage.

After adding a client, share the configuration file with the recipient. On mobile devices, the WireGuard VPN configuration can be automatically added by scanning the QR code.

For the desktop, click Download under Configuration File. This produces a .conf file containing everything the desktop needs to connect.

The configuration file looks similar to:

[Interface]
PrivateKey = <client private key>
Address = 10.1.254.2/32
DNS = 10.1.0.1

[Peer]
PublicKey = <Prevernal's public key>
PresharedKey = <preshared key>
AllowedIPs = 0.0.0.0/0
Endpoint = vpn.yourdomain.net:51820

Before importing this file, modify the AllowedIPs line for split tunnelling. The default 0.0.0.0/0 routes all traffic through the VPN. For a roaming desktop where you only want internal network traffic through the tunnel, change it to cover the three site subnets:

AllowedIPs = 10.1.0.0/16, 10.2.0.0/16, 10.3.0.0/16

This routes only traffic destined for the internal network through the VPN. Internet traffic uses whatever connection you are currently on.

Add PersistentKeepalive = 25 to the [Peer] section. This sends a keepalive packet every 25 seconds, which maintains the tunnel through NAT and prevents connections dropping when idle.

The final client configuration file should look like:

[Interface]
PrivateKey = <client private key>
Address = 10.1.254.2/32
DNS = 10.1.0.1

[Peer]
PublicKey = <Prevernal's public key>
PresharedKey = <preshared key>
AllowedIPs = 10.1.0.0/16, 10.2.0.0/16, 10.3.0.0/16
Endpoint = vpn.yourdomain.net:51820
PersistentKeepalive = 25

Desktop client setup on Kubuntu

Installation

WireGuard is built into the Linux kernel on Kubuntu 24.04. Install the tools:

sudo apt install wireguard wireguard-tools

Importing the configuration

Move the downloaded configuration file to the WireGuard directory and lock it down:

sudo mkdir -p /etc/wireguard
sudo mv ~/Downloads/desktop-burnage.conf /etc/wireguard/home.conf
sudo chmod 600 /etc/wireguard/home.conf
sudo chown root:root /etc/wireguard/home.conf

Import it into NetworkManager:

sudo nmcli con import type wireguard file /etc/wireguard/home.conf

Verify it appears in the connection list:

nmcli con show

A connection named home should appear with type wireguard.

Connecting via the KDE network applet

The VPN connection is now available in the KDE system tray network applet under VPN Connections. Toggle it on and off from there without opening a terminal.

To connect from the command line:

nmcli con up home

To disconnect:

nmcli con down home

DNS when connected

The DNS server specified in the configuration (10.1.0.1) is applied as a per-connection DNS override when the VPN is active. Internal hostnames resolve through the tunnel automatically.

Verify DNS is routing correctly when connected:

resolvectl status

The WireGuard interface should show 10.1.0.1 as its DNS server. Internal domain queries go through the tunnel; external queries go through your local Unbound instance.

Auto-connect when away from home

To connect the VPN automatically when the desktop is on an external network rather than one of the three home subnets, add the dispatcher script covered in the WireGuard section of the network configuration pages:

sudo tee /etc/NetworkManager/dispatcher.d/40-wireguard-autoconnect << 'EOF'
#!/usr/bin/env bash
INTERFACE=$1
ACTION=$2
VPN_CONNECTION="home"

if [[ "$INTERFACE" == wg* ]]; then
    exit 0
fi

case "$ACTION" in
    up)
        SUBNET=$(nmcli -g IP4.ADDRESS device show "$INTERFACE" 2>/dev/null | \
            head -1 | awk -F'.' '{print $1"."$2}')
        if [[ "$SUBNET" == "10.1" ]] || \
           [[ "$SUBNET" == "10.2" ]] || \
           [[ "$SUBNET" == "10.3" ]]; then
            exit 0
        fi
        nmcli con up "$VPN_CONNECTION" &
        ;;
    down)
        nmcli con down "$VPN_CONNECTION" 2>/dev/null
        ;;
esac
EOF

sudo chmod 0744 /etc/NetworkManager/dispatcher.d/40-wireguard-autoconnect
sudo chown root:root /etc/NetworkManager/dispatcher.d/40-wireguard-autoconnect

Adding clients for other sites

Create separate client entries in UniFi for each roaming device. Each client gets its own configuration file with a unique private key, address, and optionally a different AllowedIPs depending on which subnets the device needs to reach.

A laptop used at all three sites might have:

AllowedIPs = 10.1.0.0/16, 10.2.0.0/16, 10.3.0.0/16

A client used only to access Burnage resources:

AllowedIPs = 10.1.0.0/16

Each device gets its own client entry on the UniFi router and its own address within the 10.1.254.0/24 VPN client subnet.

Testing

With the VPN connected, test reachability across all three sites:

# Prevernal (Burnage Core)
ping -c3 10.1.0.1

# Vernal (Fallowfield Core)
ping -c3 10.2.0.1

# Estival (The Lighthouse Core)
ping -c3 10.3.0.1

Test internal DNS resolution through the tunnel:

dig server.yourdomain.net +short

Check the WireGuard interface status:

sudo wg show

A recent handshake time confirms the tunnel is active and traffic is flowing.

Troubleshooting

Connection stays in Connecting state:

If the state does not move from Connecting to Connected, there is likely an issue with authentication or the server is not reachable. Check whether the keys and server address match the information in the configuration file. Also verify the UDP port is reachable from outside:

nc -u -v vpn.yourdomain.net 51820

DNS not resolving internal names when connected:

resolvectl status wg0

If the DNS server is not showing, reload the connection:

nmcli con down home && nmcli con up home

Cannot reach sites 2 or 3 (Fallowfield / The Lighthouse):

The desktop tunnel connects to Prevernal only. Traffic to the other sites routes through Prevernal via the inter-site connections. Verify the inter-site VPN between routers is active in the UniFi dashboard.

Connection drops when changing networks:

WireGuard handles roaming gracefully. If connections are dropping, verify PersistentKeepalive = 25 is set in the peer configuration.

Store the client configuration file securely. It contains the private key that authenticates the desktop to the VPN. Anyone with this file can connect to your home network as this client. The file permissions set above (600, root-owned) are the minimum. Keep a copy in KeePassXC.