Ajouter Readme.md

2026-05-19 12:26:34 +00:00
parent 1e25bf9878
commit 321e991285
1 changed files with 120 additions and 0 deletions
--- a/Readme.md
+++ b/Readme.md
@@ -0,0 +1,120 @@
+# VPN Watchdog — WireGuard
+
+Script de surveillance automatique du tunnel WireGuard. Détecte toute fuite ou déconnexion VPN et relance l'interface sans intervention manuelle.
+
+---
+
+## Objectif
+
+Garantir qu'une machine ne tourne **jamais** sans VPN actif.
+
+Cas couverts :
+- Interface `wg0` absente ou non démarrée
+- Tunnel mort (handshake trop ancien)
+- Trafic réseau qui sort hors du tunnel WireGuard (fuite)
+
+---
+
+## Compatibilité
+
+| Critère | Requis |
+|---|---|
+| OS | Linux (testé sur Ubuntu 24.04) |
+| Systemd | Oui — obligatoire |
+| WireGuard | `wg-quick` + interface configurée |
+| Shell | Bash |
+
+---
+
+## Dépendances
+
+| Outil | Usage | Paquet |
+|---|---|---|
+| `wg` | Lecture état WireGuard | `wireguard-tools` |
+| `ip` | Vérification routage | `iproute2` (inclus par défaut) |
+| `systemctl` | Redémarrage du service | systemd |
+| `awk` | Parsing des sorties | `gawk` (inclus par défaut) |
+
+Installation si manquant :
+```bash
+apt install wireguard-tools iproute2
+```
+
+---
+
+## Fonctionnement
+
+Le script s'exécute en 3 étapes séquentielles :
+
+### Étape 1 — Présence de l'interface
+Vérifie que `wg0` est active via `wg show`.  
+Si absente : tente un `systemctl restart wg-quick@wg0.service`.  
+Si le redémarrage échoue : log l'erreur et quitte.
+
+### Étape 2 — Âge du handshake
+Récupère le timestamp du dernier handshake WireGuard.  
+Si supérieur à 180 secondes : le tunnel est considéré mort, WireGuard est redémarré.
+
+### Étape 3 — Vérification du routage
+Exécute `ip route get 8.8.8.8` et vérifie que l'interface de sortie est bien `wg0`.  
+Si le trafic sort par une autre interface (fuite) : redémarre WireGuard et vérifie le résultat.  
+Si le trafic sort toujours hors VPN après redémarrage : log l'erreur et quitte avec code 1.
+
+---
+
+## Installation
+
+**1. Copier le script**
+```bash
+cp vpn_watchdog.sh /usr/local/bin/vpn_watchdog.sh
+```
+
+**2. Rendre exécutable**
+```bash
+chmod +x /usr/local/bin/vpn_watchdog.sh
+```
+
+**3. Créer la tâche cron (toutes les minutes)**
+```bash
+crontab -e
+```
+Ajouter :
+```
+* * * * * /usr/local/bin/vpn_watchdog.sh
+```
+
+---
+
+## Logs
+
+Les événements sont enregistrés dans :
+```
+/var/log/vpn_watchdog.log
+```
+
+Exemple de sortie :
+```
+[2025-05-19 14:00:01] OK : Trafic sur wg0 — VPN actif.
+[2025-05-19 14:01:01] ALERTE : Fuite détectée — trafic sur 'ens18' au lieu de 'wg0'. Redémarrage...
+[2025-05-19 14:01:12] OK : Trafic rétabli sur wg0 après redémarrage.
+```
+
+---
+
+## Configuration
+
+Variables modifiables en tête de script :
+
+| Variable | Défaut | Description |
+|---|---|---|
+| `WG_INTERFACE` | `wg0` | Nom de l'interface WireGuard |
+| `LOG_FILE` | `/var/log/vpn_watchdog.log` | Chemin du fichier de log |
+| `MAX_HANDSHAKE_AGE` | `180` | Seuil en secondes avant de considérer le tunnel mort |
+
+---
+
+## Limitations connues
+
+- Si le réseau physique est indisponible au moment de l'exécution du cron, WireGuard ne peut pas monter — le script échouera et réessaiera à la minute suivante.
+- Le script ne bloque pas le trafic en cas de fuite détectée — il redémarre WireGuard. Une fenêtre de fuite d'une durée maximale d'une minute est possible entre deux exécutions cron.
+- Nécessite les droits root pour `wg show` et `systemctl restart`.