SSD Nodes Learn Hosting plans →
Guides Matt ConnorPar Matt Connor

Gluetun unhealthy ou bloqué en redémarrage

Votre conteneur gluetun redémarre en boucle ou reste unhealthy. Lisez ses logs, distinguez un arrêt du processus d'un contrôle en échec, corrigez le compose.

Pourquoi gluetun redémarre en boucle ou reste unhealthy

Un conteneur gluetun qui redémarre en boucle s'arrête puis est relancé par sa politique restart: une configuration refusée est une cause à chercher dans les logs, mais un manque de mémoire peut aussi faire tuer son processus par le noyau. Un conteneur qui reste unhealthy est une panne différente: le processus tourne toujours, mais un contrôle de santé configuré a épuisé ses tentatives sans succès. Les services qui passent par gluetun perdent le réseau si le tunnel tombe, mais l'échec du contrôle ne prouve pas que tout leur trafic échoue. La première étape consiste donc à savoir laquelle des deux pannes vous avez, pas à changer une variable au hasard.

gluetun écrit la cause exacte de son refus avant de s'arrêter. On lit ses logs d'abord, on touche au fichier compose ensuite.

Tous les exemples de ce guide sont épinglés sur l'image qmcgaw/gluetun:v3.41.3, vérifiée le 22 novembre 2026. Les noms des variables d'environnement de gluetun changent d'une version à l'autre, donc un extrait copié sur un forum peut être juste pour une autre version que la vôtre.

Séparer les deux pannes en deux commandes

docker ps -a --filter name=gluetun
docker inspect --format '{{.State.ExitCode}}' gluetun
docker inspect --format '{{json .State.Health}}' gluetun

Si la colonne d'état affiche Restarting suivi d'un code de sortie, le processus meurt puis Docker le relance: cet état ne dit ni pourquoi il s'arrête, ni si le tunnel a déjà été monté. Vérifiez les logs et le champ OOMKilled de docker inspect pour rechercher aussi un manque de mémoire. Si elle affiche Up suivi de (unhealthy), le processus vit et c'est le contrôle de santé qui échoue. Le champ Health retourné par docker inspect contient les dernières sorties du test, ce qui vous dit ce que Docker a réellement exécuté et ce qu'il a lu en retour.

Un point que beaucoup de tutoriels laissent croire faux: pour un conteneur autonome, Docker ne le redémarre pas simplement parce qu'il est unhealthy. Les politiques restart réagissent à la fin du processus, pas à l'état de santé. Si votre conteneur autonome passe en unhealthy et redémarre, cherchez un arrêt du processus ou l'action d'un outil tiers de votre pile (un conteneur de type autoheal, ou un gestionnaire de mises à jour). En mode Swarm, l'orchestrateur remplace une tâche dont le contrôle de santé échoue par une nouvelle tâche et un nouveau conteneur.

Lire les logs de gluetun avant tout

docker logs --tail 80 gluetun
docker logs -f gluetun

Au démarrage, gluetun affiche les versions d'Alpine, d'OpenVPN et d'iptables, puis un résumé des réglages qu'il a retenus. Ce résumé permet de vérifier les valeurs qu'il affiche, mais certains réglages lus correctement en sont absents: avec UPDATER_PERIOD=0, par exemple, la section de mise à jour n'est pas affichée. Une valeur affichée différente de celle attendue invite à vérifier une faute de frappe dans le nom, le service dans le fichier compose ou le chargement du fichier .env. Ajoutez LOG_LEVEL=debug quand le résumé ne suffit pas.

Si vous avez repris un extrait ancien, surveillez aussi les avertissements de dépréciation. gluetun garde les anciens noms de certaines variables et prévient avec un message qui commence par You are using the old, puis nomme la variable actuelle. Ce message est une bonne nouvelle: la valeur a été lue. L'absence de cet avertissement ne permet pas de conclure qu'une variable a été ignorée.

Pourquoi épingler une version, et jamais :latest

Le tag :latest de gluetun ne désigne pas la dernière version stable: il suit la branche master, donc du code de développement. C'est documenté par le projet lui-même, qui recommande un tag de version pour la stabilité. Écrivez qmcgaw/gluetun:v3.41.3 (ou ghcr.io/qdm12/gluetun:v3.41.3), et changez ce numéro quand vous décidez de mettre à jour, pas quand le registre décide pour vous.

Le deuxième argument est plus concret. Dans la v3.41.3, HEALTH_TARGET_ADDRESS est encore accepté comme ancien nom de HEALTH_TARGET_ADDRESSES, avec l'avertissement décrit plus haut. En revanche, HEALTH_VPN_DURATION_INITIAL, qui traîne encore dans beaucoup d'extraits de forum, n'a plus aucun effet dans cette version: si elle est posée, gluetun se contente d'écrire HEALTH_VPN_DURATION_INITIAL is obsolete dans ses logs, sans nommer de remplaçant. HEALTH_VPN_DURATION_ADDITION subit le même sort. Si vous ne lisez pas cette ligne, vous croyez avoir allongé un délai, et vous n'avez rien changé. C'est exactement pour cela qu'une configuration gluetun doit être lue en face de la documentation de la version que vous faites tourner.

Cause 1: NET_ADMIN absent, ou /dev/net/tun inaccessible

gluetun écrit des règles de pare-feu et crée une interface réseau. Sans la capacité NET_ADMIN, il ne peut faire ni l'un ni l'autre, et il s'arrête.

services:
  gluetun:
    image: qmcgaw/gluetun:v3.41.3
    container_name: gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    volumes:
      - ./gluetun:/gluetun
    ports:
      - 8888:8888/tcp
    environment:
      - VPN_SERVICE_PROVIDER=protonvpn
      - VPN_TYPE=wireguard
      - WIREGUARD_PRIVATE_KEY=votre_cle_base64
      - SERVER_COUNTRIES=France
      - TZ=Europe/Paris
    restart: unless-stopped

Deux réglages distincts, deux erreurs distinctes. Quand NET_ADMIN manque, l'échec vient de la partie pare-feu, et le wiki du projet documente un Permission denied (you must be root) observé quand Portainer n'applique pas la capacité comme prévu. Quand le périphérique TUN manque, gluetun essaie d'abord de créer le nœud /dev/net/tun lui-même: un échec à cette étape produit creating TUN device file node. La suggestion d'ajouter --device /dev/net/tun accompagne un échec ultérieur à l'ouverture du nœud créé, avec unix opening TUN device file et operation not permitted. Le projet documente aussi un operation not supported à l'ouverture du périphérique, qui indique généralement que le module noyau tun manque sur l'hôte.

Sur un VPS en virtualisation KVM, vérifiez que le périphérique existe avant de l'exposer avec la ligne devices. Sur un conteneur LXC, le cas est différent: le projet documente l'erreur operation not permitted à la création du nœud, avec la commande Proxmox pct set 12345 -dev0 /dev/net/tun suivie de pct reboot 12345 pour exposer le périphérique au conteneur. En Podman sans privilèges, la documentation cite container_use_devices=true côté SELinux, et l'ajout de NET_RAW en plus de NET_ADMIN pour la partie pare-feu. Vérifiez côté hôte avec ls -l /dev/net/tun avant d'accuser votre fichier compose.

Cause 2: un fournisseur ou un VPN_TYPE que l'image ne connaît pas

VPN_SERVICE_PROVIDER et VPN_TYPE sont validés au démarrage. Un nom inconnu donne une erreur qui contient VPN provider name is not valid, et une valeur autre que openvpn ou wireguard donne VPN type is not valid. Ces deux lignes sont claires, mais on ne les voit que si on lit les logs jusqu'au bout.

Le piège est ailleurs. L'image porte un fournisseur par défaut (Private Internet Access), donc oublier VPN_SERVICE_PROVIDER ne produit pas l'erreur que vous attendez: si VPN_TYPE est lui aussi absent, gluetun valide la configuration du fournisseur par défaut en OpenVPN et se plaint d'un identifiant vide avec un message contenant user is empty. Vous cherchez alors un problème de clé WireGuard, alors que le programme ne sait même pas que vous visez WireGuard.

Pour les fournisseurs qu'un lecteur français a le plus de chances d'avoir, les valeurs exactes documentées sont protonvpn, mullvad et nordvpn. Recopiez la valeur depuis la page du fournisseur dans le wiki de gluetun plutôt que de la deviner: les majuscules sont converties en minuscules dans la v3.41.3, mais les espaces ne sont pas supprimés par cette normalisation.

Cause 3: une clé collée dans la mauvaise forme

WIREGUARD_PRIVATE_KEY attend une clé de 32 octets en base64, et rien d'autre. Beaucoup de lecteurs collent la ligne entière de leur fichier de configuration, PrivateKey = ..., ou le fichier .conf complet. gluetun tente alors d'analyser cette chaîne, échoue, et l'erreur contient private key is not valid, suivie de la raison technique de l'analyse. Retirez le nom du champ, le signe égal, les espaces autour, et tout retour à la ligne qui se serait invité.

Le second réglage dépend du fournisseur, et c'est une différence réelle entre eux. Chez Mullvad, WIREGUARD_ADDRESSES est obligatoire et attend l'adresse de l'interface au format CIDR, telle qu'elle figure dans la configuration téléchargée. Chez ProtonVPN et chez NordVPN, la documentation ne demande que la clé privée. Si l'adresse manque là où elle est requise, l'erreur contient interface address is not set. Pour ProtonVPN, notez que la clé se récupère en générant une configuration WireGuard depuis votre compte, et que cette valeur vaut pour tous leurs serveurs.

Une clé qui a fonctionné pendant des mois peut cesser de fonctionner sans que vous ayez rien touché. La documentation de gluetun place d'ailleurs la validité des identifiants et des clés en premier dans la liste des causes d'un échec répété au démarrage, et mentionne le cas WireGuard chez ProtonVPN. Régénérez la clé avant de réécrire tout votre compose.

Cause 4: un filtre de serveur qui ne correspond à aucun serveur

gluetun embarque une liste de serveurs dans l'image, et vos variables SERVER_* la filtrent. Deux échecs différents en découlent. Si la valeur n'existe pas dans le référentiel, la validation la rejette avec un message du type the country specified is not valid, the city specified is not valid ou the server name specified is not valid. Si les valeurs existent mais que leur combinaison ne laisse aucun serveur, la sélection échoue plus loin, avec un message contenant no connection to pick from. Ce second cas est le plus déroutant, parce que chaque variable prise séparément semble correcte.

docker run --rm -v ./gluetun:/gluetun qmcgaw/gluetun:v3.41.3 format-servers -protonvpn

Cette commande affiche les serveurs connus de l'image pour un fournisseur, avec leur pays, leur ville et leur nom d'hôte. C'est la référence à utiliser pour écrire vos filtres. Un filtre SERVER_HOSTNAMES limité à un serveur ne laisse plus de solution si ce serveur disparaît de la liste. Les filtres propres à un fournisseur se combinent vite en ensemble vide, par exemple un pays précis plus SECURE_CORE_ONLY ou PORT_FORWARD_ONLY chez ProtonVPN, OWNED_ONLY chez Mullvad, SERVER_CATEGORIES chez NordVPN. Retirez tous les filtres, vérifiez que le tunnel monte, puis remettez-les un par un. Si votre besoin réel est un port entrant, la logique est décrite dans le fonctionnement de la redirection de port avec gluetun plutôt que dans un filtre de plus.

Épingler une version a un coût ici: la liste embarquée vieillit avec l'image. Vous pouvez la rafraîchir sans changer de version, avec la commande update du même binaire, ou laisser UPDATER_PERIOD faire le travail. Le wiki recommande une période d'au moins 360h (15 jours) pour éviter de multiplier les requêtes aux fournisseurs: la valeur par défaut est 0, qui désactive la mise à jour, et 480h est un exemple de durée valide. Le seul plancher imposé par le code de la v3.41.3 est d'une minute. Le wiki prévient en revanche que chaque mise à jour envoie une rafale de requêtes DNS over HTTPS, qui peuvent être bloquées si vous avez activé BLOCK_MALICIOUS=on.

Cause 5: un healthcheck qui tue un tunnel encore en train de monter

L'image v3.41.3 déclare son propre contrôle de santé:

HEALTHCHECK --interval=5s --timeout=5s --start-period=10s --retries=3 CMD /gluetun-entrypoint healthcheck

Ce test interroge le serveur de santé interne, qui vit par défaut sur 127.0.0.1:9999. Ce serveur répond selon trois contrôles: un contrôle au démarrage, avec un délai d'attente de six secondes, qui ouvre une connexion TCP puis TLS vers les adresses de HEALTH_TARGET_ADDRESSES (cloudflare.com:443 et github.com:443 par défaut), un petit contrôle toutes les minutes, en ICMP vers les adresses de HEALTH_ICMP_TARGET_IPS (1.1.1.1 et 8.8.8.8 par défaut), et un contrôle complet toutes les cinq minutes. Quand un contrôle échoue, gluetun redémarre le client VPN à l'intérieur du conteneur, pas le conteneur. Ce comportement s'éteint avec HEALTH_RESTART_VPN, ce qui est très utile le temps d'un diagnostic: le tunnel reste en place, les logs arrêtent de défiler, et vous voyez enfin la vraie erreur au lieu d'une suite de reconnexions.

Si le contrôle ICMP échoue avec une erreur de permission, gluetun bascule définitivement sur une requête DNS en UDP non chiffrée pour la durée de vie du conteneur, en l'annonçant dans ses logs par une ligne qui contient permanently falling back to. Un réseau qui ignore les paquets ICMP provoque des délais dépassés et des contrôles en échec, sans déclencher cette bascule. La variable HEALTH_SMALL_CHECK_TYPE permet de forcer ce choix: le code de la v3.41.3 la lit, avec icmp par défaut et dns comme seule autre valeur acceptée. Les pages healthcheck du wiki consultées ne la présentent pas, donc sa liste de valeurs est à vérifier dans le code source de la version de votre image.

Dernier cas: votre fichier compose déclare son propre bloc healthcheck pour gluetun, avec un start_period trop court. Docker marque alors le conteneur unhealthy pendant que le tunnel monte; avec depends_on et condition: service_healthy, Compose attend un contrôle réussi avant de démarrer les services dépendants. Cet état ne redémarre pas à lui seul les services déjà lancés: la propagation documentée avec restart: true sous depends_on concerne une opération explicite de Compose. Écrire ce bloc demande de connaître le temps de démarrage réel du service, comme expliqué dans la façon d'écrire un healthcheck Docker Compose qui laisse le service démarrer. La règle simple: si l'image fournit déjà un contrôle de santé, ne le remplacez pas sans raison.

Mes autres conteneurs tombent aussi: qui est en cause?

Un service routé par gluetun utilise network_mode: "service:gluetun" dans le même fichier compose, ou network_mode: "container:gluetun" s'il est lancé séparément. La documentation précise que depends_on n'est pas nécessaire dans le premier cas. Ce partage d'espace réseau explique la cascade: tant que gluetun n'est pas en marche, Docker refuse de démarrer un conteneur qui doit rejoindre son espace réseau, et un conteneur déjà lancé perd tout accès réseau pendant que gluetun redémarre.

Le test d'isolement consiste à retirer temporairement la ligne network_mode du service dépendant et à le démarrer seul: s'il monte correctement, le partage réseau avec gluetun est une piste à vérifier. Pendant ce test, son trafic ne passe plus par le VPN. La manière de relancer un seul service sans toucher au reste de la pile est décrite dans le démarrage d'un seul service avec docker compose up.

Deux détails de configuration produisent des symptômes proches sans être des pannes de gluetun. Les ports d'un conteneur routé par le tunnel se publient sur le service gluetun, jamais sur le conteneur dépendant, ce qui est la première chose à vérifier quand une interface web devient injoignable alors que le tunnel est sain, et l'accès depuis votre réseau local aux conteneurs placés derrière gluetun traite le sujet en détail. Ensuite, changer une variable d'environnement recrée le conteneur gluetun, pas seulement son processus: après un docker compose up -d, vérifiez que les dépendants sont bien revenus, et relancez-les sinon. La différence entre relancer et recréer est expliquée dans ce que font vraiment restart, recreate et rebuild avec Compose.

Quand la configuration de départ est saine, la panne suivante à comprendre n'est plus le démarrage mais la coupure: un tunnel qui tombe en cours de route, et ce que le pare-feu interne laisse passer à ce moment. C'est le sujet de ce que fait le kill switch de gluetun quand le VPN tombe. Si tout passe sauf la résolution de noms, la piste est ailleurs encore, du côté du résolveur, et la correction du DNS à travers un tunnel WireGuard couvre ce cas. Si le tunnel monte mais que les gros transferts se bloquent, regardez le réglage du MTU et les lenteurs WireGuard, car gluetun expose WIREGUARD_MTU pour cette raison. Et pour repartir d'une base propre plutôt que d'un extrait de forum, une configuration gluetun qui fonctionne du premier coup sert de référence.

La boucle de diagnostic, dans l'ordre

  1. Regardez l'état avec docker ps -a: Restarting veut dire que le processus s'arrête puis est relancé, unhealthy veut dire que le contrôle de santé échoue.
  2. Lisez docker logs --tail 80 gluetun jusqu'à la dernière ligne, et cherchez le résumé des réglages retenus juste après les lignes de version.
  3. Comparez les valeurs affichées dans ce résumé à ce que vous croyez avoir écrit, en gardant à l'esprit que certains réglages n'y figurent pas.
  4. Posez HEALTH_RESTART_VPN sur la valeur qui désactive le redémarrage automatique, le temps de lire une erreur stable au lieu d'une boucle.
  5. Réduisez la configuration au minimum, sans aucun filtre de serveur, vérifiez que le tunnel monte, puis remettez un réglage à la fois.

Cette boucle vaut mieux qu'une liste de correctifs, parce qu'elle marche aussi pour les pannes que ce guide ne décrit pas. Le conteneur vous dit ce qui ne va pas. Le travail consiste à le lire.

FAQ

Pourquoi gluetun affiche unhealthy alors que mes téléchargements passent?

Le contrôle de santé de gluetun ne mesure pas votre trafic: il ouvre ses propres connexions vers des cibles fixes, en TCP plus TLS vers les adresses de HEALTH_TARGET_ADDRESSES et en ICMP vers celles de HEALTH_ICMP_TARGET_IPS. Si les tentatives d'un contrôle échouent, l'état passe à unhealthy même si le tunnel transporte encore vos données; les autres cibles servent de repli, donc une seule cible injoignable ne suffit pas à faire échouer tous les essais. Regardez la sortie du test avec docker inspect --format '{{json .State.Health}}' gluetun, puis changez la cible du contrôle au lieu de changer votre configuration VPN.

Ai-je besoin de /dev/net/tun en plus de NET_ADMIN?

Ce sont deux permissions différentes. NET_ADMIN autorise gluetun à écrire ses règles de pare-feu et à configurer l'interface, et sans elle l'échec ressemble à un problème de droits root. gluetun essaie de créer /dev/net/tun lui-même si le périphérique manque; dans la v3.41.3, la suggestion d'ajouter --device /dev/net/tun accompagne une erreur operation not permitted à l'ouverture du nœud après sa création, pas un échec de création. Mettez les deux, c'est ce que fait l'exemple officiel.

Mes autres conteneurs tombent avec gluetun, faut-il les corriger aussi?

En général non. Un conteneur en network_mode: "service:gluetun" partage l'espace réseau de gluetun, donc il perd le réseau quand gluetun redémarre, et Docker refuse même de le démarrer tant que gluetun n'est pas en marche. Pour isoler le problème, retirez la ligne network_mode et lancez ce service seul: s'il démarre normalement, vérifiez son accès au réseau partagé avec gluetun. Son trafic sort alors sans passer par le VPN. Pensez aussi à vérifier que vos ports sont publiés sur le service gluetun et non sur le service dépendant.

Faut-il utiliser l'image latest ou une version épinglée?

Épinglez. Le tag :latest de gluetun suit la branche de développement master, pas la dernière version stable, donc il peut changer de comportement sans que vous ayez rien touché. Les noms des variables d'environnement évoluent aussi: dans la v3.41.3, certains anciens noms sont encore acceptés avec un avertissement dans les logs, et d'autres, comme HEALTH_VPN_DURATION_INITIAL, n'ont plus aucun effet et ne produisent qu'une ligne is obsolete dans les logs. Écrivez un tag de version dans votre fichier compose, gardez la documentation de cette version sous la main, et changez le numéro quand vous décidez de mettre à jour.

Cet article vous a-t-il été utile ?