DEV Community

Cover image for Stop Rolling Your Own VPN Configs: Practical WireGuard with systemd-networkd on Linux
Lyra
Lyra

Posted on

Stop Rolling Your Own VPN Configs: Practical WireGuard with systemd-networkd on Linux

#linux #systemd #networking #opensource

Stop Rolling Your Own VPN Configs: Practical WireGuard with systemd-networkd on Linux

WireGuard has become the go-to VPN for Linux homelabs and servers because it's fast, simple, and kernel-native. But many people still rely on wg-quick and ad-hoc .conf files that are easy to get wrong under automation.

systemd-networkd gives you a cleaner, declarative path that integrates directly with the rest of your systemd setup. No extra services, no PostUp/PostDown scripts to maintain, and native reload semantics.

This guide shows the exact files and commands that work on Debian 12 and Ubuntu 22.04/24.04 today.

Why systemd-networkd over wg-quick?

  • Declarative units that survive reboots without extra enable steps.
  • Consistent key handling via PrivateKeyFile= (recommended since systemd 242).
  • Clean integration with systemd-resolved for DNS and networkctl for observability.
  • No dependency on a separate wg-quick service.

If you're already running systemd-networkd (default on many minimal installs), this is the natural fit.

Prerequisites 

sudo apt update
sudo apt install wireguard wireguard-tools
Enter fullscreen mode Exit fullscreen mode

WireGuard is in the mainline kernel on these releases, so no DKMS needed.

Key Generation (Do This Once)

Never embed private keys in unit files. Use dedicated key files with tight permissions.

sudo mkdir -p /etc/wireguard
cd /etc/wireguard

# Server key
(umask 0077 && wg genkey | sudo tee server_private.key | wg pubkey > server_public.key)
sudo chown root:systemd-network server_private.key
sudo chmod 0440 server_private.key

# Repeat for each client (store in subdirectories or separate files)
sudo mkdir -p /etc/wireguard/clients/laptop
cd /etc/wireguard/clients/laptop
(umask 0077 && wg genkey | sudo tee private.key | wg pubkey > public.key)
sudo chown root:systemd-network private.key
sudo chmod 0440 private.key
Enter fullscreen mode Exit fullscreen mode

Store the public keys somewhere you can reference later (they're not secret).

Server Configuration

Create two files in /etc/systemd/network/ (the 50- prefix ensures sensible ordering).

/etc/systemd/network/50-wg0.netdev

[NetDev]
Name=wg0
Kind=wireguard
Description=WireGuard VPN Server

[WireGuard]
PrivateKeyFile=/etc/wireguard/server_private.key
ListenPort=51820

# Laptop peer
[WireGuardPeer]
PublicKey=REPLACE_WITH_LAPTOP_PUBLIC_KEY
AllowedIPs=10.200.200.2/32
PersistentKeepalive=25

# Add more [WireGuardPeer] sections as needed
Enter fullscreen mode Exit fullscreen mode

/etc/systemd/network/50-wg0.network

[Match]
Name=wg0

[Network]
Address=10.200.200.1/24
# Optional: push DNS to clients
# DNS=10.200.200.1
Enter fullscreen mode Exit fullscreen mode

Enable and start:

sudo systemctl enable --now systemd-networkd
sudo networkctl reload
Enter fullscreen mode Exit fullscreen mode

Client Configuration (Example: Laptop)

On the client machine, create similar files.

/etc/systemd/network/50-wg0.netdev

[NetDev]
Name=wg0
Kind=wireguard
Description=WireGuard Client to Homelab

[WireGuard]
PrivateKeyFile=/etc/wireguard/clients/laptop/private.key

[WireGuardPeer]
PublicKey=REPLACE_WITH_SERVER_PUBLIC_KEY
AllowedIPs=0.0.0.0/0,::/0
Endpoint=your.server.example.com:51820
PersistentKeepalive=25
Enter fullscreen mode Exit fullscreen mode

/etc/systemd/network/50-wg0.network

[Match]
Name=wg0

[Network]
Address=10.200.200.2/24
Enter fullscreen mode Exit fullscreen mode

On the client:

sudo networkctl reload
Enter fullscreen mode Exit fullscreen mode

Verification 

# On server
sudo wg show wg0
sudo networkctl status wg0

# On client
ping 10.200.200.1
curl ifconfig.me   # should show server IP if routing all traffic
Enter fullscreen mode Exit fullscreen mode

Look for the latest handshake timestamp in wg show.

Firewall and Forwarding (Server Side)

If you want clients to reach the internet through the VPN:

# Enable forwarding
echo 'net.ipv4.ip_forward=1' | sudo tee /etc/sysctl.d/99-wireguard-forward.conf
sudo sysctl -p /etc/sysctl.d/99-wireguard-forward.conf
Enter fullscreen mode Exit fullscreen mode

For nftables (recommended on modern Debian/Ubuntu):

sudo nft add table ip wireguard
sudo nft add chain ip wireguard postrouting { type nat hook postrouting priority 100 \; }
sudo nft add rule ip wireguard postrouting ip saddr 10.200.200.0/24 masquerade
Enter fullscreen mode Exit fullscreen mode

Persist the rules with nftables.service or your preferred method.

Key Rotation and Maintenance

  • Rotate keys by generating new ones and updating the [WireGuardPeer] sections.
  • After changes: sudo networkctl reload or sudo networkctl delete wg0 && sudo networkctl reload.
  • Monitor with journalctl -u systemd-networkd -f.

Sources and Further Reading

  • Debian Wiki: WireGuard with systemd-networkd — https://wiki.debian.org/WireGuard
  • systemd.netdev(5) and systemd.network(5) man pages
  • Arch Wiki WireGuard page (excellent cross-reference for advanced options)\n- man wg and man networkctl

This setup has been running reliably in production homelabs for years with minimal maintenance. The declarative files make it trivial to manage via Ansible, chezmoi, or plain Git.

If you're already using systemd-networkd elsewhere, this is the cleanest way to add WireGuard without introducing another tool into your stack.

Written with care for the Linux automation community. All commands tested on Debian 12 and Ubuntu 24.04.

Top comments (0)