Présentation

wg-admin est une interface web conçue pour administrer un hôte WireGuard déjà opérationnel. Le projet parcourt chaque fichier *.conf présent dans /etc/wireguard, les expose dans le tableau de bord et permet d’ajouter, renommer ou supprimer des pairs sans toucher aux paramètres d’interface existants. L’application s’installe via un script install.sh et fonctionne sous Linux avec Python 3.11 ou supérieur ainsi que le paquet wireguard-tools (commande wg).

Fonctionnement et architecture

Le cœur de wg-admin repose sur deux mécanismes : la lecture directe des fichiers de configuration et l’appel à wg syncconf pour appliquer les changements. Lorsqu’un administrateur modifie un pair, le service écrit d’abord le nouveau fichier dans /etc/wireguard, puis exécute wg syncconf <interface> <fichier.conf>. Cette séquence évite le redémarrage de l’interface, ce qui préserve les connexions actives. En cas d’échec, une copie de sauvegarde est créée dans /var/lib/wg-admin/backups/, garantissant la restauration du fichier original.

# Exemple de variables d’environnement par défaut
WG_ADMIN_HOST=127.0.0.1
WG_ADMIN_PORT=8080
WG_ADMIN_CONFIG_DIR=/etc/wireguard
WG_ADMIN_STATE_DIR=/var/lib/wg-admin

Le service écoute par défaut sur l’adresse de boucle locale 127.0.0.1:8080. Cette contrainte de liaison limite l’accès aux processus locaux, incitant les administrateurs à placer un reverse‑proxy (Caddy, nginx) avec TLS devant l’application lorsqu’un accès distant est requis.

Gestion des pairs et sécurité

Chaque nouveau pair déclenche la génération d’une paire de clés, la sélection de la première adresse IPv4 libre dans le sous‑réseau de l’interface, puis l’écriture de la configuration serveur. Les fichiers client peuvent être téléchargés ou convertis en QR‑code, facilitant l’onboarding sur mobile. Les paramètres spécifiques au client (endpoint public, DNS, AllowedIPs) sont stockés séparément dans /var/lib/wg-admin/state.json, évitant toute contamination du fichier serveur. wg-admin ne conserve jamais la clé privée du client sur le serveur, conformément à la philosophie de WireGuard.

Pour exécuter les opérations de lecture et d’écriture, le processus nécessite les capacités CAP_NET_ADMIN ou les privilèges root, car il doit accéder aux répertoires /etc/wireguard et /var/lib/wg-admin. Le projet indique explicitement que le service ne remplace pas wg‑quick ni les scripts PostUp/PostDown déjà en place, préservant ainsi les hooks NAT ou de routage personnalisés.

Déploiement, tests et limites

L’installation se résume à trois lignes : git clone https://github.com/logimaxx/wg-admin.git, cd wg-admin puis sudo ./install.sh. La désinstallation supprime le service mais laisse intacts les fichiers de configuration WireGuard. Le dépôt fournit un environnement de test Python (python3 -m venv .venv) et un script de démonstration qui utilise un répertoire demo/wireguard sans appeler wg. Cette approche montre que la logique métier est décorrélée de l’exécution réelle du binaire, ce qui facilite les tests unitaires (pytest).

Les limites notables proviennent du fait que wg-admin ne génère de QR‑code que pour les pairs créés ou dont les clés sont rotées via l’interface ; les pairs existants restent sans fichier client téléchargeable. De plus, la dépendance à Python 3.11 exclut les systèmes plus anciens sans mise à jour du runtime. Enfin, la sécurité repose sur la configuration du reverse‑proxy : une exposition directe du port 8080 sans TLS constitue un vecteur d’attaque potentiel.