homelab-wireguard-vpn

VPN WireGuard pour le réseau domestique

WireGuard est un protocole VPN moderne et rapide. C'est le choix idéal pour l'accès distant à un réseau domestique — plus simple à configurer qu'OpenVPN et plus rapide que la plupart des alternatives.

Tous les exemples de configuration montrent des configurations courantes. Examinez chaque commande — en particulier les règles de forwarding iptables et les permissions des fichiers de clés — avant de les appliquer à votre système, et effectuez les modifications pendant une fenêtre de maintenance.

Quand l'utiliser

• Mise en place d'un serveur WireGuard sur un Raspberry Pi, un hôte Linux, pfSense ou un routeur
• Génération de paires de clés WireGuard et rédaction de fichiers de configuration peers
• Configuration de l'accès distant depuis un téléphone ou un ordinateur portable vers le réseau domestique
• Explication du split tunnel (routage uniquement du trafic domestique) vs tunnel complet (routage de tout le trafic)
• Dépannage des connexions WireGuard qui ne s'établissent pas
• Automatisation de la génération de configuration peer pour plusieurs clients

Comment fonctionne WireGuard

Votre téléphone (client WireGuard)
    │
    │  Tunnel UDP chiffré (port 51820)
    │
Votre routeur domestique (serveur WireGuard — nécessite une IP publique ou DDNS)
    │
    Votre réseau domestique (192.168.1.0/24, NAS, Pi, etc.)

Chaque appareil possède une paire de clés (clé publique + clé privée).
Le serveur connaît la clé publique de chaque client.
Le client connaît la clé publique + endpoint (IP:port) du serveur.
Le trafic est chiffré de bout en bout sans serveur central ni autorité de certification.

Configuration du serveur (Linux)

# Installation de WireGuard
sudo apt update && sudo apt install wireguard -y

# Génération de la paire de clés du serveur — créez des fichiers avec des permissions privées dès le début
sudo mkdir -p /etc/wireguard
sudo sh -c 'umask 077; wg genkey > /etc/wireguard/server_private.key'
sudo sh -c 'wg pubkey < /etc/wireguard/server_private.key > /etc/wireguard/server_public.key'

# Écriture de la configuration du serveur — remplacez la valeur réelle de la clé privée
# Ne stockez pas les clés privées dans le contrôle de version et ne les partagez pas
sudo tee /etc/wireguard/wg0.conf << 'EOF'
[Interface]
Address = 10.8.0.1/24              # Sous-réseau VPN — le serveur obtient .1
ListenPort = 51820
PrivateKey = <collez_ici_la_clé_privée_du_serveur>

# Règles de forwarding ciblées : autoriser le trafic VPN entrant/sortant, pas un FORWARD ACCEPT global
PostUp   = iptables -A FORWARD -i wg0 -o eth0 -j ACCEPT
PostUp   = iptables -A FORWARD -i eth0 -o wg0 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
PostUp   = iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -D FORWARD -i wg0 -o eth0 -j ACCEPT
PostDown = iptables -D FORWARD -i eth0 -o wg0 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
PostDown = iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

[Peer]
# Téléphone — remplacez par la clé publique réelle du téléphone
PublicKey = <clé_publique_du_téléphone>
AllowedIPs = 10.8.0.2/32

[Peer]
# Ordinateur portable — remplacez par la clé publique réelle de l'ordinateur portable
PublicKey = <clé_publique_de_l'ordinateur_portable>
AllowedIPs = 10.8.0.3/32
EOF
sudo chmod 600 /etc/wireguard/wg0.conf

# Remplacez eth0 par le nom de votre interface de sortie réelle
# Vérifiez avec : ip route show default

# Activation du forwarding IP (requis pour le routage du trafic via le serveur)
echo "net.ipv4.ip_forward=1" | sudo tee /etc/sysctl.d/99-wireguard.conf
sudo sysctl --system

# Démarrage de WireGuard et activation au démarrage
sudo wg-quick up wg0
sudo systemctl enable wg-quick@wg0

Configuration du client

# Génération d'une paire de clés unique pour chaque appareil client
# Exécutez sur le client, ou sur le serveur et transférez la clé privée de manière sécurisée — jamais en texte clair
umask 077
wg genkey | tee phone_private.key | wg pubkey > phone_public.key

# Fichier de configuration client (phone_wg0.conf) :
[Interface]
PrivateKey = <clé_privée_du_téléphone>
Address = 10.8.0.2/32
DNS = 192.168.1.2                  # Optionnel : utilisez Pi-hole pour le DNS via le tunnel

[Peer]
PublicKey = <clé_publique_du_serveur>
Endpoint = votre-ip-domestique.ddns.net:51820  # Votre IP publique ou nom d'hôte DDNS
AllowedIPs = 192.168.1.0/24            # Split tunnel : uniquement le trafic du réseau domestique
# AllowedIPs = 0.0.0.0/0, ::/0        # Tunnel complet : tout le trafic via le VPN

PersistentKeepalive = 25              # Maintient le trou NAT ouvert (requis pour les clients mobiles)

Split tunnel vs Tunnel complet

# Split tunnel : AllowedIPs = 192.168.1.0/24
  Seul le trafic destiné à votre réseau domestique passe par le VPN.
  Le trafic Internet (YouTube, Spotify) passe directement — meilleures performances sur mobile.
  Idéal pour : "Je veux juste accéder à mon NAS et mon Pi depuis n'importe où."

# Tunnel complet : AllowedIPs = 0.0.0.0/0, ::/0
  TOUT le trafic passe par votre connexion Internet domestique.
  Utile pour : utiliser le DNS/Pi-hole domestique pour le blocage de pubs.
  Inconvénient : votre vitesse de téléchargement domestique devient un goulot d'étranglement partout.

# Split tunnel multi-sous-réseaux (cas d'usage le plus courant pour un réseau domestique) :
  AllowedIPs = 192.168.10.0/24, 192.168.20.0/24, 192.168.30.0/24, 10.8.0.0/24
  Route tous vos VLANs via le tunnel ; le trafic Internet reste direct.

Génération de clés et gestion des peers

import subprocess

def generate_keypair() -> tuple[str, str]:
    """Génère une paire de clés WireGuard. Retourne (clé_privée, clé_publique)."""
    private = subprocess.check_output(["wg", "genkey"]).decode().strip()
    public = subprocess.run(
        ["wg", "pubkey"], input=private.encode(), capture_output=True
    ).stdout.decode().strip()
    return private, public

def generate_preshared_key() -> str:
    return subprocess.check_output(["wg", "genpsk"]).decode().strip()

def build_client_config(
    client_private_key: str,
    client_vpn_ip: str,       # ex. "10.8.0.3"
    server_public_key: str,
    server_endpoint: str,     # ex. "home.example.com:51820"
    allowed_ips: str = "192.168.1.0/24",
    dns: str = "",
) -> str:
    dns_line = f"DNS = {dns}\n" if dns else ""
    return f"""[Interface]
PrivateKey = {client_private_key}
Address = {client_vpn_ip}/32
{dns_line}
[Peer]
PublicKey = {server_public_key}
Endpoint = {server_endpoint}
AllowedIPs = {allowed_ips}
PersistentKeepalive = 25
"""

def build_server_peer_block(
    client_public_key: str,
    client_vpn_ip: str,
    comment: str = "",
) -> str:
    comment_line = f"# {comment}\n" if comment else ""
    return f"""
{comment_line}[Peer]
PublicKey = {client_public_key}
AllowedIPs = {client_vpn_ip}/32
"""

Gardez les clés privées hors du contrôle de version. Si vous utilisez ce script, écrivez les clés dans des fichiers avec le mode 600 et ne les loggez ou imprimez jamais.

WireGuard sur pfSense / OPNsense

# pfSense : VPN → WireGuard → Ajouter un tunnel
  Clés d'interface : Générer (crée automatiquement la paire de clés)
  Port d'écoute : 51820
  Adresse de l'interface : 10.8.0.1/24

# Ajouter un peer (un par client) :
  Clé publique : <clé publique du client>
  IPs autorisées : 10.8.0.2/32

# Assigner l'interface WireGuard :
  Interfaces → Affectations → Ajouter (sélectionnez wg0)
  Activer l'interface, pas d'IP nécessaire (elle est définie dans la configuration du tunnel)

# Règles de pare-feu :
  WAN → Autoriser le trafic UDP entrant sur le port 51820 (pour que les clients puissent joindre le serveur)
  Interface WireGuard → Autoriser le trafic vers les réseaux LAN que vous souhaitez rendre accessibles

DDNS (DNS dynamique) pour serveurs domestiques

La plupart des connexions Internet domestiques ont une IP dynamique. Utilisez DDNS pour que votre endpoint VPN reste accessible après un changement d'IP.

# Option 1 : Cloudflare DDNS — stockez les identifiants dans un fichier de secrets, pas en ligne
# Entrée docker-compose utilisant un fichier env :
  ddns-updater:
    image: qmcgaw/ddns-updater
    env_file: ./ddns.env   # stockez zone_id et token ici, pas dans le compose
    restart: unless-stopped

# ddns.env (chmod 600, pas commité dans git) :
# SETTINGS_CLOUDFLARE_ZONE_ID=votre_zone_id
# SETTINGS_CLOUDFLARE_TOKEN=votre_token_api

# Option 2 : DuckDNS (gratuit, simple)
  Inscrivez-vous sur duckdns.org → obtenez un token et un sous-domaine (mamaison.duckdns.org)
  Stockez le token dans /etc/ddns.env (mode 600), puis utilisez un petit script appartenant à root :

  # /usr/local/bin/update-duckdns
  #!/bin/sh
  set -eu
  . /etc/ddns.env
  curl --fail --silent --show-error --max-time 10 \
    --get "https://www.duckdns.org/update" \
    --data-urlencode "domains=mamaison" \
    --data-urlencode "token=${DUCKDNS_TOKEN}" \
    --data-urlencode "ip="

  # Tâche cron :
  */5 * * * * /usr/local/bin/update-duckdns >/dev/null 2>&1

Dépannage

# Vérifier l'état de WireGuard et la dernière poignée de main
sudo wg show

# Si "latest handshake" est "jamais" ou très ancien, le tunnel n'est pas connecté.
# Vérifiez :
# 1. Le port UDP 51820 est-il ouvert sur le routeur/pare-feu ?
sudo ufw status  # ou vérifiez les règles du pare-feu pfSense/UniFi

# 2. La clé publique du serveur dans la configuration client est-elle correcte ?
sudo wg show wg0 public-key   # Comparez avec ce qui est dans la configuration client

# 3. Le forwarding IP est-il activé sur le serveur ?
cat /proc/sys/net/ipv4/ip_forward  # Devrait être 1

# 4. La valeur AllowedIPs du client couvre-t-elle l'IP que vous essayez d'atteindre ?
# Si AllowedIPs = 192.168.1.0/24 et que vous essayez d'atteindre 192.168.3.5, cela ne routera pas.

# Vérifiez les logs du noyau pour les erreurs WireGuard
dmesg | grep wireguard

# Redémarrez WireGuard
sudo wg-quick down wg0 && sudo wg-quick up wg0

Anti-patrons

# MAUVAIS : Stocker les clés privées dans le contrôle de version ou les partager
# Les clés privées sont équivalentes à des mots de passe — ne les commitez jamais dans git

# MAUVAIS : Utiliser AllowedIPs = 0.0.0.0/0 sur mobile sans considérer l'impact
# Le tunnel complet route tout le trafic mobile via votre téléchargement domestique — généralement lent

# MAUVAIS : Ne pas définir PersistentKeepalive sur les clients mobiles
# Les clients mobiles derrière NAT laissent les tunnels inactifs tomber sans cela

# MAUVAIS : Ouvrir le port 51820 dans le pare-feu mais oublier le forwarding IP sur le serveur
# Le tunnel se connecte mais aucun trafic n'est routé — déroutant à déboguer

# MAUVAIS : Partager une paire de clés entre plusieurs appareils clients
# Chaque appareil doit avoir sa propre paire de clés unique — les clés partagées cassent le modèle de sécurité

# MAUVAIS : Utiliser une règle iptables "FORWARD ACCEPT" trop large
# Limitez les règles de forwarding à l'interface wg0 et à la direction uniquement

Bonnes pratiques

• Générez une paire de clés unique par appareil client — ne réutilisez jamais les clés
• Utilisez le split tunnel (AllowedIPs = <sous-réseaux domestiques>) pour le mobile
• Définissez PersistentKeepalive = 25 sur tous les clients mobiles
• Utilisez DDNS si votre FAI attribue une IP dynamique ; stockez les identifiants dans des fichiers env, pas en ligne
• Utilisez des règles de forwarding iptables ciblées (entrant sur wg0 uniquement) plutôt qu'un FORWARD ACCEPT global
• Ajoutez l'IP de Pi-hole comme DNS = dans les configurations client pour bénéficier du blocage de pubs via le VPN
• Changez périodiquement la paire de clés du serveur et mettez à jour toutes les configurations client

Compétences associées

• homelab-network-setup
• homelab-vlan-segmentation
• homelab-pihole-dns