WireGuard-VPN op uw eigen server opzetten

Wat op alle vier de distributies hetzelfde is, en wat niet

WireGuard maakt sinds kernel 5.6 vast deel uit van de Linux-kernel. Op Debian 13, Debian 12, Ubuntu 24.04 en Ubuntu 22.04 hoeft u daarom geen DKMS-module meer te bouwen, geen backport-repository toe te voegen en geen vreemde sleutel te importeren. Alle vier leveren bovendien dezelfde versie van de userland-tools (upstreamversie 1.0.20210914), dat wil zeggen: de commando's wg en wg-quick gedragen zich overal identiek.

De verschillen zitten uitsluitend in de omgeving eromheen, en juist daar lopen de meeste handleidingen vast:

• Pakketfilter: wireguard-tools beveelt nftables of iptables aan. Omdat apt het eerste beschikbare alternatief pakt, komt op een slanke Debian-installatie nftables terecht en niet iptables. De overal klakkeloos overgenomen iptables -t nat -A POSTROUTING-regels doen daar helemaal niets, zolang u dat pakket niet alsnog installeert.
• DNS-doorgifte: voor de regel DNS = roept wg-quick steevast het programma resolvconf aan. Op Ubuntu levert het pakket systemd-resolved een compatibiliteitslaag mee, op een minimale Debian-installatie bestaat vaak helemaal geen resolvconf. Wilt u het alsnog installeren, dan heet het passende pakket op Debian en op Ubuntu 22.04 openresolv; op Ubuntu 24.04 bestaat dat pakket niet meer. Dit raakt alleen Linux-clients, geen telefoons.
• Firewall-frontend: Ubuntu-images hebben vaak een actieve ufw aan boord, Debian meestal niet. ufw blokkeert het doorsturen standaard, ook wanneer net.ipv4.ip_forward op 1 staat.

Controleer eerst waarmee u te maken hebt:

apt-get update
apt-get install -y wireguard wireguard-tools nftables qrencode
wg --version
apt-cache policy wireguard-tools

Meldt wg --version een versienummer, dan is het userland aanwezig. Of de kernel meewerkt, ziet u pas bij de eerste wg-quick up. Blijft daarbij de melding RTNETLINK answers: Operation not supported of Unable to access interface: Protocol not supported staan, dan draait er een kernel zonder WireGuard-ondersteuning, meestal een heel oude of een sterk uitgeklede containerkernel.

Sleutelparen aanmaken zonder uzelf problemen te bezorgen

WireGuard kent geen gebruikersnamen en geen certificaten. Per deelnemer is er precies één sleutelpaar, daarnaast optioneel een gedeelde preshared key als extra symmetrische laag. Maak beide aan met een ingestelde umask, anders liggen de privésleutels voor iedereen leesbaar op de schijf:

umask 077
wg genkey | tee /etc/wireguard/server.key | wg pubkey > /etc/wireguard/server.pub
wg genkey | tee /etc/wireguard/telefoon.key | wg pubkey > /etc/wireguard/telefoon.pub
wg genpsk > /etc/wireguard/telefoon.psk
ls -l /etc/wireguard

De map /etc/wireguard hoeft u daarvoor niet zelf aan te maken, het pakket wireguard-tools levert die al mee met modus 0700. Belangrijker is een eigenaardigheid van umask: de waarde geldt alleen in de shellsessie waarin u hem instelt. Maakt u de sleutels in twee etappes aan, bijvoorbeeld omdat de verbinding tussendoor is weggevallen en u opnieuw hebt ingelogd, dan werkt u daarna weer met het standaardmasker, en komen server.key en telefoon.psk met 0644 op de schijf terecht. Zet de rechten daarom aan het eind nog eens uitdrukkelijk goed:

chmod 600 /etc/wireguard/*.key /etc/wireguard/*.psk

Drie fouten komen hier telkens terug:

1. Publieke en privésleutel verwisseld. Beide zijn Base64-strings van 44 tekens en zien er identiek uit. Staat er in [Interface] PrivateKey per ongeluk een publieke sleutel, dan start de tunnel toch, maar komt er nooit een handshake tot stand. Dat kunt u altijd afleiden: wg pubkey < /etc/wireguard/server.key moet exact de inhoud van server.pub opleveren.
2. Regeleinde meegekopieerd. Sleutels die u met de muis uit een terminal kopieert, slepen graag witruimte mee. wg beantwoordt dat met Key is not the correct length or format.
3. Bestandsrechten. Vergeet u umask 077, dan waarschuwt wg-quick bij de start met Warning: `/etc/wireguard/wg0.conf' is world accessible. Dat is geen cosmetica, in dit bestand staat de privésleutel in leesbare vorm.

De serverconfiguratie

Bepaal eerst de naam van uw internetinterface. Op virtuele machines heet die, afhankelijk van het image, eth0, ens3 of enp1s0:

ip route show default

Maak daarna /etc/wireguard/wg0.conf aan. Kies voor het tunnelnetwerk een bereik dat u onderweg niet in een hotelwifi tegenkomt, dus liever niet 192.168.0.0/24 of 192.168.1.0/24:

[Interface]
Address = 10.8.0.1/24
ListenPort = 51820
PrivateKey = INHOUD_VAN_SERVER_KEY

PostUp = nft add table ip wgnat
PostUp = nft add chain ip wgnat postrouting '{ type nat hook postrouting priority srcnat; policy accept; }'
PostUp = nft add rule ip wgnat postrouting ip saddr 10.8.0.0/24 oifname "eth0" masquerade
PostDown = nft delete table ip wgnat

[Peer]
# telefoon
PublicKey = INHOUD_VAN_TELEFOON_PUB
PresharedKey = INHOUD_VAN_TELEFOON_PSK
AllowedIPs = 10.8.0.2/32

Vervang eth0 door uw werkelijke interface. Blijft u liever bij iptables, installeer dan iptables alsnog en gebruik in plaats daarvan:

PostUp = iptables -t nat -A POSTROUTING -s 10.8.0.0/24 -o eth0 -j MASQUERADE
PostDown = iptables -t nat -D POSTROUTING -s 10.8.0.0/24 -o eth0 -j MASQUERADE

Twee details die zelden genoemd worden. Ten eerste: elke PostUp-regel wordt via een shell uitgevoerd, en breekt er één met een fout af, dan draait wg-quick de hele start terug. Een typefout in de nft-regel leidt dus niet tot een half werkende tunnel, maar tot helemaal geen tunnel. Ten tweede: AllowedIPs betekent aan de serverkant iets heel anders dan aan de clientkant. Hier is het een toewijzingstabel die vastlegt welk afzenderadres bij welke peer hoort. Zet u bij twee peers hetzelfde adres, dan wint de peer die als laatste is geladen en blijft de andere stil. Elke client krijgt precies één /32.

Zet de rechten goed en controleer de syntaxis voordat u start:

chmod 600 /etc/wireguard/wg0.conf
wg-quick strip wg0

wg-quick strip toont de configuratie zonder de regels die alleen wg-quick zelf kent. Loopt het commando door, dan is het bestand formeel in orde. Meldt het wg-quick: Line unrecognized, dan hebt u meestal een optie in de verkeerde sectie gezet, bijvoorbeeld DNS onder [Peer].

IP-forwarding blijvend inschakelen

Zonder forwarding eindigt elk pakket in de server zelf. Schakel het meteen en blijvend in:

echo 'net.ipv4.ip_forward=1' > /etc/sysctl.d/99-wireguard.conf
sysctl --system
sysctl net.ipv4.ip_forward

Het laatste commando moet net.ipv4.ip_forward = 1 teruggeven. Wilt u ook IPv6 door de tunnel sturen, dan hoort net.ipv6.conf.all.forwarding=1 er in hetzelfde bestand bij.

Draait ufw, dan is dat nog niet genoeg. ufw hanteert een eigen forwardingbeleid dat los van de kernelschakelaar werkt. Open de poort en sta de doorvoer uitdrukkelijk toe:

ufw allow 51820/udp
ufw route allow in on wg0 out on eth0

Het typische foutbeeld bij vergeten forwarding is bijzonder verraderlijk: de handshake lukt, de ping naar 10.8.0.1 lukt, maar alles daarachter blijft onbereikbaar. Wie alleen naar de handshake kijkt, zoekt daarna urenlang op de verkeerde plek.

wg-quick als service instellen

Het pakket levert een template-unit mee; de naam achter de @ is de naam van het configuratiebestand zonder extensie:

systemctl enable wg-quick@wg0
systemctl start wg-quick@wg0
systemctl status wg-quick@wg0
journalctl -u wg-quick@wg0 -n 50 --no-pager

Een valkuil die veel mensen pas na weken opmerken: SaveConfig = true. Deze optie schrijft bij het stoppen van de service de draaiende toestand terug naar het bestand. Daarbij gaan alle commentaarregels, alle PostUp-regels in hun oorspronkelijke volgorde en elke met de hand aangebrachte structuur verloren. Voor een server waarvan u de configuratie zelf bijhoudt, laat u die optie weg.

Controleer na de start de toestand niet aan de exitcode, maar aan de interface:

wg show
ip -brief address show wg0
ss -ulpn

ss -ulpn moet een luisteraar op UDP-poort 51820 tonen. wg show somt de peers op, op dit moment nog zonder handshake.

Clientconfiguratie en QR-code voor de telefoon

Het clientbestand maakt u het best op de server aan, want daar staan alle sleutels toch al. Let op: aan de clientkant betekent AllowedIPs iets anders, namelijk welke bestemmingen door de tunnel moeten gaan. 0.0.0.0/0, ::/0 betekent: alles.

mkdir -p /etc/wireguard/clients

Inhoud van /etc/wireguard/clients/telefoon.conf:

[Interface]
PrivateKey = INHOUD_VAN_TELEFOON_KEY
Address = 10.8.0.2/32
DNS = 9.9.9.9, 149.112.112.112

[Peer]
PublicKey = INHOUD_VAN_SERVER_PUB
PresharedKey = INHOUD_VAN_TELEFOON_PSK
AllowedIPs = 0.0.0.0/0, ::/0
Endpoint = uw.server.adres:51820
PersistentKeepalive = 25

PersistentKeepalive = 25 is bij telefoons geen luxe. NAT in mobiele netwerken vergeet UDP-toewijzingen vaak na 30 tot 60 seconden; zonder keepalive kan de server een bestaande verbinding niet meer uit zichzelf aanspreken.

De QR-code maakt u rechtstreeks in de terminal aan:

qrencode -t ansiutf8 < /etc/wireguard/clients/telefoon.conf

In de WireGuard-app tikt u op de plus, kiest u de import via QR-code en houdt u de camera op de terminal. Twee praktische tips: verklein het lettertype in de terminal voordat u de code aanmaakt, anders past hij niet in beeld. En verwijder het bestand daarna niet meteen, u hebt het bij een wissel van apparaat weer nodig. Wie het toch verwijdert, moet een nieuw sleutelpaar aanmaken, want de privésleutel valt niet uit de publieke terug te rekenen.

Waaraan u ziet dat het echt werkt

Dat systemctl start zonder uitvoer terugkomt, betekent alleen dat de interface bestaat. De eigenlijke test bestaat uit drie fasen, en u loopt ze het best in deze volgorde door:

wg show wg0 latest-handshakes
wg show wg0 transfer

Fase één, de handshake. latest-handshakes geeft per peer een Unix-tijdstempel. Staat daar 0, dan is er nog nooit een verbinding tot stand gekomen. In de uitgebreide weergave van wg show leest u in plaats daarvan latest handshake: 42 seconds ago.

Fase twee, de datastroom. Bij transfer staan de ontvangen en de verzonden bytes. Alleen verzonden bytes zonder ontvangen bytes betekent: uw pakketten gaan naar buiten, er komt niets terug. Dat is bijna altijd een firewall of een verkeerd endpoint, nooit een sleutelprobleem.

Fase drie, de werkelijke route. Op de client controleert u of het verkeer wel echt de tunnel in wordt geleid:

ip route get 1.1.1.1

Staat daar dev wg0, dan klopt de routing. Pas daarna heeft het zin om een pagina te bekijken die uw publieke IP-adres toont. Laat die het adres van uw server zien, dan bent u klaar.

Foutopsporing: geen handshake

Het meest voorkomende foutbeeld van allemaal. Schakel eerst de logging van de kernelmodule in, die levert het antwoord meestal binnen tien seconden:

echo 'module wireguard +p' > /sys/kernel/debug/dynamic_debug/control
dmesg -w

Start nu op de client een verbindingspoging en lees mee. De drie meldingen waar het om draait:

• wireguard: wg0: Handshake for peer 1 (...) did not complete after 5 seconds, retrying (try 2) en verder niets. Bij de server komt geen enkel pakket aan. Controleer dat met tcpdump -n -i eth0 udp port 51820. Ziet u daar niets, dan ligt het aan de firewall vóór de server, aan de poort of aan het feit dat de client in een netwerk zit dat uitgaand UDP filtert. Een test vanuit het mobiele netwerk in plaats van vanuit de bedrijfswifi scheidt die gevallen netjes.
• wireguard: wg0: Invalid handshake initiation from .... Er komen wel pakketten aan, maar ze passen niet. Bijna altijd klopt de publieke sleutel van de server in het clientbestand niet, of staat de preshared key maar aan één kant ingevuld. Een preshared key moet aan beide kanten identiek zijn of aan beide kanten ontbreken.
• Helemaal geen melding, terwijl tcpdump wel pakketten laat zien. Dan luistert WireGuard op een andere poort of op een ander adres. Controle via ss -ulpn.

Een zelden gedocumenteerd bijzonder geval is de kloktijd. WireGuard stopt in het eerste handshakebericht een tijdstempel en de server onthoudt per peer de hoogste waarde die hij ooit heeft gezien. Oudere tijdstempels verwerpt hij, dat is de bescherming tegen replay. Heeft een apparaat zijn klok ver in de toekomst gezet en eenmaal verbinding gemaakt, dan komt het na het corrigeren van de klok niet meer door. De server houdt die toestand in het geheugen, dus helpt het volgende: klok goed zetten en daarna op de server wg-quick down wg0 en wg-quick up wg0. Na het opnieuw opbouwen is de blokkade weg.

Zet de logging daarna weer uit, ze is nogal spraakzaam:

echo 'module wireguard -p' > /sys/kernel/debug/dynamic_debug/control

Foutopsporing: DNS werkt niet

Symptoom: de tunnel staat, ping 1.1.1.1 werkt, maar geen enkele naam laat zich omzetten. Er zijn precies drie oorzaken.

Ten eerste: de resolver is niet bereikbaar. Zet u DNS = 10.8.0.1 in de configuratie, dan moet er op de server ook werkelijk een nameserver op dat adres luisteren. Een kaal Debian of Ubuntu heeft er geen. Ofwel u zet een publieke resolver in de configuratie die via de tunnel bereikt wordt, ofwel u richt er zelf een in. Voor die tweede weg volstaat dnsmasq met een klein bestand onder /etc/dnsmasq.d/wireguard.conf:

interface=wg0
bind-dynamic
no-resolv
server=9.9.9.9
server=1.1.1.1
cache-size=1000

bind-dynamic is belangrijk, omdat wg0 bij de start van dnsmasq mogelijk nog niet bestaat. no-resolv is op Ubuntu verplicht: zonder die regel leest dnsmasq /etc/resolv.conf, vindt daar het stub-adres 127.0.0.53 van systemd-resolved en bouwt een lus. En het punt waar u op Ubuntu het vaakst over struikelt: dnsmasq bezet poort 53. Op een systeem met een actieve systemd-resolved is die poort al vergeven, beide services botsen en dnsmasq start niet. De regels interface=wg0 en bind-dynamic zijn daarom geen cosmetica, maar voorkomen dat dnsmasq zich aan alle adressen bindt. Controleer daarna met ss -ulpn dat dnsmasq en systemd-resolved niet om poort 53 vechten.

Ten tweede: de resolver valt buiten de AllowedIPs. Wie in plaats van 0.0.0.0/0 maar een paar netwerken door de tunnel stuurt en als DNS-server een adres invult dat niet in die lijst staat, stuurt de aanvragen langs de tunnel heen het lokale netwerk in.

Ten derde, alleen op Linux-clients: resolvconf ontbreekt. De regel DNS = geeft wg-quick door aan een programma met de naam resolvconf. Ontbreekt dat, dan breekt de start af met /usr/bin/wg-quick: line 32: resolvconf: command not found. Controleer eerst of het programma er wel is:

command -v resolvconf

Bij het alsnog installeren lopen de distributies uiteen, en precies daarop stranden klakkeloos overgenomen handleidingen op Ubuntu 24.04. Daar bestaat het pakket openresolv noch in main, noch in universe; de aanroep eindigt met E: Package 'openresolv' has no installation candidate:

Op Ubuntu 24.04 is resolvconf een virtueel pakket dat eenduidig naar systemd-resolved verwijst en daarbij /usr/sbin/resolvconf aanmaakt, dus precies het binaire bestand dat wg-quick voor de DNS-regel aanroept. U kunt daar net zo goed meteen systemd-resolved installeren. Wilt u één regel die op alle genoemde systemen werkt, neem dan deze:

apt-get install -y openresolv || apt-get install -y resolvconf

Op Ubuntu 24.04 bestaat daar een variant op die na een upgrade vanaf 22.04 opduikt: Failed to resolve interface "tun.wg0": No such device. De oorzaak is een achtergebleven oud resolvconf-pakket uit 22.04, inclusief /etc/resolvconf/interface-order, dus niet het virtuele pakket met dezelfde naam uit 24.04. Op grond van dat bestand zet wg-quick een tun. vóór de interfacenaam, en daar kan de compatibiliteitslaag van systemd-resolved niets mee. De oplossing is het oude pakket verwijderen, zodat alleen de laag van systemd-resolved overblijft.

Foutopsporing: MTU-problemen

Het onaangenaamste foutbeeld, omdat alles lijkt te werken. De handshake staat, ping loopt, SSH loopt, maar webpagina's laden half en blijven hangen, grote downloads breken af, en juist HTTPS is getroffen. De reden: kleine pakketten passen, grote niet.

WireGuard verpakt elk pakket met 60 byte extra wanneer de tunnel over IPv4 loopt (20 byte IP, 8 byte UDP, 32 byte WireGuard), en 80 byte wanneer hij over IPv6 loopt. wg-quick trekt daarom standaard 80 byte van de vastgestelde pad-MTU af en komt op een normaal traject van 1500 uit op 1420. Dat is bewust behoudend en klopt in de meeste gevallen.

Het klopt niet wanneer het traject smaller is dan 1500, bijvoorbeeld bij DSL met PPPoE (1492), achter nog een tunnel of in sommige mobiele netwerken. Meet de werkelijke pad-MTU vanaf de client naar het publieke adres van de server, met gezette don't-fragment-bit en zonder tunnel:

ping -M do -s 1472 -c 3 DOELADRES

1472 plus 28 byte header levert 1500 op. Komt ping: local error: message too long, mtu=... of Frag needed and DF set terug, verlaag de waarde dan stapsgewijs tot het lukt: 1464, 1444, 1414, 1372. Bij de gevonden waarde telt u 28 op en trekt u er 80 af. Bij 1464 komt dat dus neer op 1492 pad-MTU en 1412 tunnel-MTU.

Ingevuld wordt dat in de sectie [Interface], aan de kant die het probleem heeft:

MTU = 1412

De snelle tegentest voordat u lang gaat rekenen: zet bij wijze van proef MTU = 1280. Dat is de kleinste MTU die IPv6 garandeert en die werkt praktisch overal. Laden uw pagina's daarmee netjes, dan lag het aan de MTU en kunt u rustig naar de optimale waarde toewerken. Blijft het probleem, dan zit het ergens anders.

Op de server zelf is een verkeerde MTU zeldzamer, maar wel mogelijk: staat daar een waarde die hoger is dan het traject aankan, dan ziet u het effect alleen bij bepaalde bestemmingen. Een blik op ip -brief address show wg0 en ip link show wg0 laat de actueel ingestelde waarde zien.

Peers tijdens bedrijf wijzigen zonder iedereen eruit te gooien

De reflex om na elke wijziging systemctl restart wg-quick@wg0 te typen, verbreekt alle bestaande verbindingen en bouwt de NAT-regels opnieuw op. Op een server met meerdere gebruikers is dat onnodig grof. WireGuard kan de configuratie tijdens bedrijf bijwerken:

wg syncconf wg0 <(wg-quick strip wg0)

Het commando vergelijkt het bestand met de draaiende toestand en past alleen de verschillen aan. Bestaande peers houden hun sessie. Let erop dat de processubstitutie met <(...) bash of zsh vereist; in een kale sh mislukt ze. Een losse peer voegt u ook rechtstreeks toe:

wg set wg0 peer PUBLIEKE_SLEUTEL allowed-ips 10.8.0.3/32

Die wijziging leeft alleen in het geheugen. Schrijf haar daarnaast in het configuratiebestand, anders is de peer na de volgende herstart verdwenen. Dat is trouwens de meest voorkomende oorzaak van de zin "gisteren werkte het nog".

Wilt u een WireGuard-endpoint blijvend en met een vast adres draaien, dan is een eigen server daarvoor de logische basis. Bij KernelHost draaien KVM-rootservers en dedicated servers in het datacenter maincubes in Frankfurt am Main (TÜV TIER3+) in ons eigen netwerk, op PrePaid-basis en zonder minimale looptijd. Aansluitend interessant zijn onze artikelen over SSH-beveiliging en over het instellen van ufw.