homelab-wireguard-vpn

Homelab WireGuard VPN

WireGuard est un protocole VPN rapide et moderne. C’est le bon choix pour un 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 mises en place courantes. Passez en revue 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 dans une fenêtre de maintenance.

Quand l’utiliser

• Mettre en place un serveur WireGuard sur un Raspberry Pi, un hôte Linux, pfSense ou un routeur
• Générer des paires de clés WireGuard et écrire les fichiers de configuration des pairs
• Configurer un accès distant depuis un téléphone ou un laptop vers un réseau domestique
• Expliquer le split tunnel (routage uniquement du trafic domestique) vs le tunnel complet (routage de tout le trafic)
• Dépanner des connexions WireGuard qui ne s’établissent pas
• Automatiser la génération de configuration pour plusieurs clients

Comment fonctionne WireGuard

Votre téléphone (client WireGuard)
    │
    │  Tunnel UDP chiffré (port 51820)
    │
Votre routeur domestique (serveur WireGuard — besoin d’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 du serveur + son point d’accès (IP:port).
Le trafic est chiffré de bout en bout sans serveur central ni autorité de certification.

Configuration du serveur (Linux)

# Installer WireGuard
sudo apt update && sudo apt install wireguard -y

# Générer la paire de clés du serveur — créer les fichiers avec des permissions privées dès le départ
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'

# Écrire la configuration du serveur — remplacer par la valeur réelle de la clé privée
# Ne pas stocker les clés privées dans un système de contrôle de version ni les partager
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 = <coller_la_clé_privée_du_serveur_ici>

# Règles de forwarding ciblées : autoriser le trafic VPN entrant/sortant, pas un FORWARD ACCEPT général
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 — remplacer par la clé publique réelle du téléphone
PublicKey = <clé_publique_téléphone>
AllowedIPs = 10.8.0.2/32

[Peer]
# Laptop — remplacer par la clé publique réelle du laptop
PublicKey = <clé_publique_laptop>
AllowedIPs = 10.8.0.3/32
EOF
sudo chmod 600 /etc/wireguard/wg0.conf

# Remplacer eth0 par le nom réel de votre interface de sortie
# Vérifier avec : ip route show default

# Activer le forwarding IP (nécessaire pour router le trafic via le serveur)
echo "net.ipv4.ip_forward=1" | sudo tee /etc/sysctl.d/99-wireguard.conf
sudo sysctl --system

# Démarrer WireGuard et l’activer au démarrage
sudo wg-quick up wg0
sudo systemctl enable wg-quick@wg0

Configuration du client

# Générer une paire de clés unique pour chaque périphérique client
# Exécuter sur le client, ou sur le serveur et transférer la clé privée de manière sécurisée — jamais en texte brut
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_téléphone>
Address = 10.8.0.2/32
DNS = 192.168.1.2                  # Optionnel : utiliser Pi-hole pour le DNS via le tunnel

[Peer]
PublicKey = <clé_publique_serveur>
Endpoint = votre-ip-maison.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              # Garder le trou NAT ouvert (nécessaire 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) va directement — meilleure performance sur mobile.
  Meilleur 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 des pubs.
  Inconvénient : votre débit montant domestique devient le goulot d’étranglement partout.

# Split tunnel multi-sous-réseaux (cas d’usage le plus courant dans un homelab) :
  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 pairs

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 le matériel de clé dans des fichiers avec le mode 600 et ne le journalisez ni ne l’affichez jamais.

pfSense / OPNsense WireGuard

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

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

# Assigner l’interface WireGuard :
  Interfaces → Assignations → Ajouter (sélectionner wg0)
  Activer l’interface, pas besoin d’IP (elle est définie dans la configuration du tunnel)

# Règles de pare-feu :
  WAN → Autoriser le port UDP 51820 entrant (pour que les clients puissent atteindre 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 point d’accès VPN reste joignable après un changement d’IP.

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

# ddns.env (chmod 600, non commité dans git) :
# SETTINGS_CLOUDFLARE_ZONE_ID=your_zone_id
# SETTINGS_CLOUDFLARE_TOKEN=your_api_token

# Option 2 : DuckDNS (gratuit, simple)
  Inscrivez-vous sur duckdns.org → obtenez un token et un sous-domaine (myhome.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=myhome" \
    --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érifier :
# 1. Le port UDP 51820 est-il ouvert sur le routeur/pare-feu ?
sudo ufw status  # ou vérifier les règles de pare-feu pfSense/UniFi

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

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

# 4. Les AllowedIPs du client couvrent-elles l’IP que vous essayez d’atteindre ?
# Si AllowedIPs = 192.168.1.0/24 et vous essayez d’atteindre 192.168.3.5, cela ne routera pas.

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

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

Antipatterns

# MAUVAIS : Stocker les clés privées dans le contrôle de version ou les partager
# Les clés privées équivalent à des mots de passe — ne jamais les commiter 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 débit montant domestique — généralement lent

# MAUVAIS : Ne pas définir PersistentKeepalive sur les clients mobiles
# Les clients mobiles derrière un NAT laissent tomber les tunnels inactifs 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 ne route — déroutant à déboguer

# MAUVAIS : Partager une paire de clés entre plusieurs périphériques clients
# Chaque appareil doit avoir sa propre paire de clés unique — le partage brise le modèle de sécurité

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

Bonnes pratiques

• Générer une paire de clés unique par périphérique client — ne jamais réutiliser les clés
• Utiliser le split tunnel (AllowedIPs = <sous-réseaux domestiques>) pour les mobiles
• Définir PersistentKeepalive = 25 sur tous les clients mobiles
• Utiliser DDNS si votre FAI attribue une IP dynamique ; stocker les identifiants dans des fichiers d’env, pas en ligne
• Utiliser des règles de forwarding iptables ciblées (entrant uniquement sur wg0) plutôt qu’un FORWARD ACCEPT général
• Ajouter l’IP de Pi-hole comme DNS = dans les configurations client pour obtenir le blocage des pubs via le VPN
• Renouveler périodiquement la paire de clés du serveur et mettre à jour toutes les configurations client

Compétences associées

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