DietPi 10.8: WireGuard-Server und Clients samt QR-Code per dietpi-wireguard

Am 21. Oktober 2026 ist DietPi v10.8 erschienen. Die auffälligste Neuerung für Heimserver und kleine Standorte ist dietpi-wireguard: ein Werkzeug, das WireGuard-Server und deren Clients per Menü oder Kommandozeile verwaltet und eine Client-Config als QR-Code ins Terminal zeichnet. Der Wunsch dazu steht seit September 2019 als Issue 3100 im Projekt, geschlossen wurde er am 3. Oktober 2026. In den Beschreibungen des Wunsches steht schon der Satz „a QR-code is generated for the clients to scan".

Dieser Beitrag beruht auf den Release Notes, dem Skript im Tag v10.8 und einem deutschen Bericht. Ausprobiert haben wir das Tool nicht. Wir kennzeichnen deshalb, was aus dem Skript gelesen ist (verifiziert), was wir daraus ableiten (abgeleitet) und was der Hersteller behauptet (Herstellerangabe).

Was das Tool kann

Laut Release Notes legt dietpi-wireguard Server und Clients an, zeigt Client-Configs als QR-Code, deaktiviert, aktiviert und entfernt Clients, ändert deren Einstellungen und passt Port, Adresse und IPv6 des Servers an. Das Skript selbst (verifiziert, Tag v10.8) kennt diese Unterbefehle: init, list, add <name>, remove, disable, enable, qr <name>, rename, set, server und cleanup. Dazu kommen Optionen wie --endpoint, --dns, --allowed-ips, --keepalive und --psk.

Die Voreinstellungen (verifiziert, Skript und Dokumentation): UDP-Port 51820, Interface wg0, Serveradresse 10.9.0.1/24 und für IPv6 ein Subnetz aus fd10:<n>::1/64. Der Port lässt sich vorab über SOFTWARE_WIREGUARD_PORT in /boot/dietpi.txt setzen. Damit Clients aus dem Internet ankommen, muss der Router den UDP-Port auf das DietPi-System weiterleiten; das steht so in der Dokumentation.

Ablauf von der Sicherung bis zum Widerruf

Die Reihenfolge ist unsere Ableitung aus dem Skript, ausgeführt haben wir sie nicht. Zuerst ein Backup, dann Update und Prüfung, danach Server und Client.

cp -a /etc/wireguard /root/wireguard-backup-$(date +%F)
dietpi-wireguard list
dietpi-wireguard add phone --endpoint vpn.example.org
dietpi-wireguard qr phone

--endpoint ist der öffentliche Hostname oder die öffentliche Adresse des Servers. Fehlt der Port, nimmt das Skript laut seiner Hilfe den ListenPort des Servers. Den QR-Code scannt man in der WireGuard-App auf dem Smartphone. Gezeichnet wird er mit qrencode -t ansiutf8; das Paket qrencode kommt zusammen mit wireguard-tools als Voraussetzung. Im Skript steht ein Hinweis, dass der Code nicht in jedes Terminal passt.

Zum Widerruf gibt es zwei Wege. disable <name> behält den Peer, sodass er sich wieder einschalten lässt. remove löscht ihn nach einer Rückfrage.

Was mit bestehenden Configs passiert

Das Tool kommt ohne eigene Datenbank aus. Im Skriptkopf (verifiziert) steht: „Works with the existing configs in /etc/wireguard, without an own database". Der Server ist die Datei /etc/wireguard/<interface>.conf mit dem ListenPort, Clientnamen stammen aus Dateinamen der Form <interface>-<name>.conf. Die Release Notes sagen, das gelte auch für Server, die nicht über dietpi-software installiert wurden. linuxnews.de schreibt dazu, das Tool greife auf die vorhandenen Konfigurationen unter /etc/wireguard zurück.

Wer ein selbst gebautes Setup hat, sollte eine Stelle im Skript kennen (verifiziert): Neue und geänderte Client-Configs liegen in /etc/wireguard/clients/, Configs aus /etc/wireguard/ werden beim Ändern dorthin verschoben. Deaktivierte Peers wandern aus der Server-Config in /etc/wireguard/<interface>.disabled. Vor jeder Änderung kopiert das Skript die Server-Config nach .<interface>.conf.bak und löscht diese Kopie nach Erfolg wieder. Das Verzeichnis clients entsteht mit den Rechten 0700.

Daraus folgt die Empfehlung (abgeleitet): /etc/wireguard vorher sichern, nach dem ersten Lauf mit ls /etc/wireguard/clients nachsehen und zuerst nur dietpi-wireguard list ausführen, um zu sehen, ob die handgebauten Peers erkannt werden. Ob das bei jedem eigenen Aufbau sauber klappt, haben weder wir noch die Berichte getestet. Dass es gut funktioniere, ist eine Herstellerangabe.

Änderungen an dietpi-software und IPv6

dietpi-software legt den WireGuard-Server jetzt über dietpi-wireguard init an und erzeugt keinen Client mehr. Die Dokumentation sagt: „No client configuration is created during the installation." Wer bisher nach der Installation sofort eine Client-Config vorfand, muss den ersten Client jetzt selbst mit add anlegen.

Neue Server bekommen laut Release Notes ein IPv6-Subnetz (NAT66) samt IPv6-Forwarding, damit Clients IPv6 durch den Tunnel nutzen können; mit der bisherigen Config ging das nicht. Bestehende Server lassen sich über dietpi-wireguard umstellen, etwa mit dietpi-wireguard server ipv6=on. linuxnews.de berichtet dasselbe. Nach einer Änderung von Subnetz oder IPv6 müssen die Clients ihre Config neu importieren, das steht in der Hilfe des Skripts. Wer IPv6 in dietpi-config abschaltet, schaltet es damit auch für die WireGuard-Server ab, weil sie sonst nicht starten könnten.

Der QR-Code ist ein Geheimnis

Aus dem QR-Code entfernt das Skript nur Kommentare (verifiziert). Eine normale Client-Config enthält den privaten Schlüssel des Clients, also steckt er im Code (abgeleitet). Den Code deshalb nicht auf einem geteilten Bildschirm zeigen, nicht in ein Ticket kopieren und nicht in eine Chat-Gruppe schicken. Wer einen Code hat, kann sich als dieser Client anmelden, bis der Peer mit disable oder remove gesperrt ist.

Was sonst im Release steckt

Wer produktiv auf DietPi setzt, sollte die Release Notes ganz lesen, bevor er auf 10.8 hebt. HAProxy ist jetzt ein DietPi-eigenes DEB-Paket, die Worker laufen als Benutzer haproxy, und eine vorhandene /etc/haproxy/haproxy.cfg bleibt unangetastet. Das Paket-Upgrade bekommen laut Release Notes auch Nutzer, die HAProxy früher per apt aus Debian statt über dietpi-software installiert haben. Dazu kommen Softwarenamen statt Nummern (nodered statt 122, Nummern gehen weiterhin) und der Wegfall von dietpi-software free. Immich-ML unterstützt Debian Bookworm und Forky nicht mehr.

Wer WireGuard auf einem Raspberry Pi oder einem kleinen Server betreibt, bekommt mit dietpi-wireguard ein Werkzeug, das mehrere Handgriffe bündelt. Es ist drei Tage alt, Erfahrungswerte aus dem Alltag fehlen also noch. Zuerst auf einer Kopie des Systems ausprobieren, dann erst auf dem Server, über den Außendienst oder Heimbüro ins Netz kommen.

Weiterführende Quellen

• DietPi v10.8, Release Notes auf GitHub: dietpi-wireguard, IPv6, HAProxy, Softwarenamen
• DietPi v10.8 auf dietpi.com: Release-Seite mit Datum
• DietPi-Dokumentation: VPN: Standardport 51820, Portweiterleitung, keine Client-Config bei der Installation
• Skript dietpi-wireguard im Tag v10.8: Befehle, Dateipfade, QR-Code
• Feature-Wunsch: Issue 3100: Ursprung seit 2019
• linuxnews.de: DietPi 10.8 bringt neue WireGuard-Verwaltung: bestehende Configs, IPv6, NAT66
• Wikimedia Commons: DietPi-Logo: Logo, CC BY-SA 4.0, Urheber MichaIng
• Wikimedia Commons: WireGuard-Logo: Logo, gemeinfrei