Fonctionnement

Fonctionnement

Mode Sidecar (défaut)

Cycle de benchmark (toutes les X heures)
  ├─ Containers "pause bench" stoppés (torrents, Usenet…)
  ├─ Pull ghcr.io/aerya/gluetun-companion-sidecar:latest
  │   (une seule fois par cycle, image conservée en cache ; best-effort :
  │    repli sur le cache si le registre/DNS est momentanément indisponible)
  └─ Pour chaque serveur activé :
       1. Lancement de gluetun-companion-test
          (copie de votre Gluetun, configuré sur le serveur cible)
       2. Lancement de gluetun-companion-sidecar
          (network_mode: container:gluetun-companion-test)
       3. Attente connexion VPN via /health polling (timeout configurable)
       4. Test de débit dans le tunnel VPN (moteur configurable) :
          - Dual (défaut) : Ookla + librespeed en parallèle, iperf3 en fallback
          - Ookla seul, librespeed seul, ou iperf3 seul
          → DL, UL, latence enregistrés par source
       5. Stop + suppression des containers de test (image sidecar conservée)
       → Retry automatique si échec, timeout global par serveur
       → Auto-désactivation si N échecs consécutifs
  └─ Score pondéré (65 % cycle actuel + 35 % historique exponentiel)
  └─ Bascule du vrai Gluetun vers le meilleur (un seul redémarrage)
  └─ Containers "post-bascule" recréés (network namespace inclus)
  └─ Containers "pause bench" relancés (garanti — bloc finally)
  └─ Notification Discord / Apprise (si configurée)

Moteurs de test disponibles (Paramètres → Mesurer → Mode Sidecar) :

• Dual (défaut) — Ookla + librespeed en parallèle ; résultats des deux sources stockés séparément
• Ookla uniquement — CLI Speedtest.net, rarement bloqué par les IPs VPN
• librespeed uniquement — librespeed-cli, serveurs librespeed.org (HTTP)
• iperf3 uniquement — TCP direct vers serveurs publics iperf3 (souvent bloqués par VPN)

Fallbacks :

• iperf3 en dernier recours si toutes les sources principales échouent (activé par défaut)
• Proxy HTTP en fallback si le sidecar échoue complètement (désactivé par défaut)

⚠ Connexion simultanée : le mode sidecar consomme un slot VPN supplémentaire pendant toute la durée du benchmark. Vérifiez les limites de votre fournisseur (AirVPN : 3–5 selon l'abonnement). Companion enchaîne les tests sidecar un par un et attend par défaut 180 s après le nettoyage des containers (sidecar_disconnect_wait_seconds) pour laisser le fournisseur fermer la session VPN avant le serveur suivant. C'est le principal facteur de durée d'un cycle : avec N serveurs, le cycle dure au moins N × ce délai. Si votre abonnement autorise plusieurs connexions simultanées (AirVPN : 3–5), réduisez-le nettement (60 s, voire moins) dans Paramètres → Mesurer pour raccourcir les cycles ; augmentez-le si vous voyez des erreurs « too many connections ». L'image sidecar n'est tirée qu'une fois par cycle puis réutilisée depuis le cache : moins de charge sur le registre/DNS, et un test n'échoue plus (ni ne bascule le serveur) sur un hoquet DNS passager.

Mode Proxy HTTP (optionnel)

Cycle de benchmark (toutes les X heures)
  └─ Pour chaque serveur activé :
       1. Écriture de docker-compose.override.yml
       2. docker compose up -d  ← le vrai Gluetun redémarre
       3. Attente connexion VPN via poll proxy HTTP
       4. Warm-up TCP optionnel (2 s, non comptés)
       5. Download depuis N endpoints → médiane Mbps
       6. Upload → Mbps
       7. Latence TTFB → médiane ms
  └─ Score pondéré → bascule → notification

Activer via Paramètres → Mesurer → Mode Sidecar → désactiver.

Containers à redémarrer après bascule

Dans Paramètres → Décider → Containers à redémarrer après bascule : liste ordonnée de containers recréés après chaque bascule VPN, quel que soit son déclencheur. En mode Compose, Companion utilise docker compose up -d --force-recreate ; en mode Unraid/DockerMan, il recrée les containers via le Docker SDK. Les services utilisant network_mode: service:gluetun sont détectés séparément, rattachés au nouvel identifiant de namespace puis vérifiés ; un événement Docker répare également ce rattachement après une recréation externe de Gluetun. Drag & drop pour réordonner.

Le serveur actif affiché sur le tableau de bord et dans l’API est résolu depuis l’adresse du tunnel réellement sélectionnée par Gluetun et son catalogue de fournisseurs. Les variables SERVER_* restent affichées comme filtres de sélection, mais une liste de candidats n’est plus présentée comme s’il s’agissait du serveur connecté. Les changements réellement observés hors Companion sont ajoutés à l’historique des bascules.

À la fin de chaque benchmark réussi, Companion calcule et conserve le meilleur serveur du profil actif, même lorsque la bascule automatique est désactivée. La notification de fin et l’historique ne laissent donc plus « Meilleur serveur » vide en mode mesure seule.

Containers à stopper pendant le benchmark

Dans Paramètres → Mesurer → Containers à stopper pendant le benchmark : liste de containers stoppés avant le benchmark et relancés après — dans tous les cas, même si le benchmark plante. Si un container est dans les deux listes, la liste de pause a priorité (pas de doublon). Utile pour qbittorrent, sabnzbd, nzbget, transmission.

Contrôle des trackers BitTorrent via le VPN

Dans Paramètres → BitTorrent, Companion peut vérifier si les trackers réellement utilisés par vos torrents sont accessibles depuis le serveur VPN testé ou sélectionné. L'objectif n'est pas de faire un vrai announce complet pour chaque torrent, mais de vérifier la connectivité utile avec quatre niveaux :

D’après la documentation DNS officielle de Gluetun, Gluetun active BLOCK_MALICIOUS=on par défaut. Certaines URL d'annonce peuvent donc être bloquées par ses listes DNS même si le tracker est disponible. Dans Paramètres → BitTorrent → Filtrage DNS Gluetun, Companion permet de conserver cette protection tout en autorisant des domaines précis via DNS_UNBLOCK_HOSTNAMES, ou de désactiver entièrement BLOCK_MALICIOUS en dernier recours. Le réglage est écrit dans docker-compose.override.yml, appliqué immédiatement en recréant Gluetun et conservé lors des bascules suivantes. La désactivation globale réduit la protection DNS de tous les containers partageant le réseau de Gluetun ; l'exception ciblée est recommandée.

1. DNS — le domaine du tracker peut être résolu.
2. Port — le port TCP/UDP du tracker répond.
3. Endpoint tracker — l'URL /announce ou le handshake UDP tracker répond. Une réponse HTTP 400, 401, 403 ou invalid request peut être considérée comme joignable : le tracker refuse la requête de test, mais il est bien accessible.
4. Score agrégé — si le pourcentage de trackers accessibles dépasse le seuil configuré (80 % par défaut), le serveur VPN est réputé compatible.

Ce seuil évite les faux négatifs : un tracker privé ou public peut être temporairement down, sans que le serveur VPN soit mauvais. Companion conserve l'historique par URL afin de distinguer progressivement un tracker globalement indisponible d'un tracker bloqué seulement sur certains chemins VPN.

Deux usages sont séparés dans Paramètres → BitTorrent :

• Activer le contrôle trackers pendant les vérifications VPN lance la découverte avant benchmark, puis teste pour chaque serveur soit toutes les URLs détectées, soit uniquement celles cochées, selon le périmètre choisi.
• Exiger un résultat trackers OK pour les bascules automatiques et les pools transforme ce score en critère d'éligibilité : pendant un benchmark, les serveurs sous le seuil sont exclus du choix final ; dans une rotation de pool, les serveurs déjà connus sous le seuil sont ignorés, tandis que les serveurs jamais testés restent candidats.

La page Serveurs affiche une colonne Trackers avec le dernier résultat connu par serveur (OK, pourcentage sous seuil, ou — si jamais testé). Cette colonne est triable afin d'isoler rapidement les serveurs compatibles ou problématiques.

Les trackers HTTP/HTTPS sont testés via le proxy HTTP Gluetun quand il est configuré. Les trackers UDP nécessitent que Companion puisse envoyer de l'UDP depuis le chemin VPN ; si votre installation ne fournit que le proxy HTTP, ils peuvent être listés et gérés, mais leur test réel dépendra de votre topologie réseau.

Clients BitTorrent et découverte des trackers

Companion peut gérer plusieurs sources BitTorrent : par exemple un qBittorrent principal, un autre qBittorrent dédié au cross-seed, et un rTorrent/ruTorrent. Chaque client configuré contient :

• type : qBittorrent ou rTorrent / ruTorrent RPC2 ;
• URL API/WebUI ;
• identifiants ;
• container Docker associé, optionnel ;
• filtres de catégorie ou tags ;
• options pour inclure/exclure les torrents en pause ou les torrents privés.

Pour qBittorrent, Companion utilise l'API Web : liste des torrents, puis endpoint trackers par hash. Pour rTorrent/ruTorrent, Companion utilise XML-RPC/RPC2 et récupère les trackers par torrent.

La découverte est toujours faite avant de stopper les containers configurés dans “Containers à stopper pendant le benchmark”. Ainsi, si qbittorrent ou rutorrent est arrêté pendant la mesure, Companion utilise la liste de trackers déjà mise en cache. L'interface déduit un nom lisible du domaine de chaque tracker, affiche son taux de réussite cumulé et permet de trier par nom ou résultat. Les URLs peuvent être activées ou ignorées une par une, ou toutes à la fois avec Tout cocher / Tout décocher, quand le périmètre « trackers cochés » est utilisé. Elles sont normalisées sans passkey (?passkey=..., authkey, token, segments privés du chemin, etc.) pour éviter d'exposer des secrets dans l'interface.

Inventaire des ports forwardés VPN

Dans Paramètres → Port Forwarding, Companion gère les ports entrants nécessaires aux clients BitTorrent par fournisseur VPN. Trois états sont possibles :

• Désactivé — les règles restent stockées mais ne sont pas appliquées.
• Actif manuel — les règles peuvent être déclarées, vérifiées et synchronisées à la demande.
• Actif automatique (par défaut dès que le port forwarding est activé ; désactivable) — quand Gluetun bascule vers un autre serveur ou fournisseur VPN (bascule manuelle, benchmark ou rotation de pool), Companion applique automatiquement les règles du fournisseur courant. Cela couvre aussi les bascules ProtonVPN vers un autre serveur du même fournisseur, où le port NAT-PMP peut changer. Après une reconnexion Gluetun détectée par Docker, Companion relit aussi le port natif et le propage si nécessaire. Enfin, un contrôle périodique (toutes les 5 min) compare le port natif /v1/portforward au dernier port appliqué : si Gluetun a renouvelé le port sans redémarrage du container (renouvellement NAT-PMP par exemple), les règles sont réappliquées automatiquement.

Chaque entrée contient :

• nom lisible ;
• fournisseur (AirVPN, ProtonVPN, Custom WireGuard, etc., ou Manual) ;
• mode (Manual ou Natif Gluetun) ;
• port manuel, optionnel en mode natif ;
• protocoles TCP et/ou UDP ;
• client BitTorrent lié, optionnel ;
• commande optionnelle on_port_change ;
• note libre.

Pour une règle manuelle/statique, l'interface vérifie :

• présence du port dans FIREWALL_VPN_INPUT_PORTS ;
• présence du port dans FIREWALL_INPUT_PORTS ;
• publication Docker du port sur le container Gluetun, par protocole ;
• port d'écoute qBittorrent lorsque l'entrée est liée à un client qBittorrent.

Pour une règle Natif Gluetun, ces ports statiques ne sont pas requis. Companion vérifie plutôt que le Control Server répond, qu'un port dynamique est attribué et que le client lié utilise ce même port. L'interface affiche donc Port natif Gluetun, Control Server et non requis à la place des contrôles FIREWALL_* et Docker.

Le bouton Synchroniser met à jour le port d'écoute du client lié : qBittorrent via l'API Web (/api/v2/app/setPreferences + relecture de vérification), ou rTorrent via XML-RPC (network.port_range.set + relecture — support bêta, implémenté selon la spec XML-RPC mais pas encore validé sur une instance rTorrent réelle ; le hook on_port_change reste disponible en repli). En mode Natif Gluetun, Companion lit d'abord le Control Server Gluetun (GET /v1/portforward) puis pousse le port retourné vers le client.

Tester l'accessibilité depuis Internet : le bouton Tester depuis Internet de chaque règle effectue une connexion TCP réelle depuis Companion vers IP_publique_VPN:port. Companion sortant par la connexion de votre box (pas par le tunnel VPN), ce test exerce le vrai chemin entrant : Internet → fournisseur VPN → Gluetun → client. TCP uniquement — l'UDP n'a pas de handshake et n'est pas vérifiable ainsi. Les indicateurs de configuration (firewall, publication Docker, port d'écoute) restent des contrôles locaux ; ce bouton est le seul qui prouve l'accessibilité réelle. Pour une contre-vérification manuelle externe : canyouseeme.org ou yougetsignal.com (IP publique VPN et port à saisir à la main — ces sites ne sont pas pré-remplissables).

Pour activer le support natif Gluetun, exposez son Control Server. Le port interne reste 8000, mais le port hôte peut être différent : avec 8043:8000, l'URL depuis Companion est par exemple http://host.docker.internal:8043. Si votre environnement exige d'ajouter le Control Server à FIREWALL_INPUT_PORTS, indiquez le port interne 8000, pas 8043.

Laissez le champ URL vide si l'autodétection Docker fonctionne. Avec un mapping personnalisé, Portainer ou Synology, renseignez-le explicitement : l'URL doit être joignable depuis le container Companion, pas seulement depuis l'hôte ou un navigateur. Si Gluetun utilise une auth apikey, renseignez la même valeur dans X-API-Key. Companion utilise /v1/portforward comme source principale et retente l'endpoint legacy /v1/openvpn/portforwarded si nécessaire.

# Depuis l'hôte Docker
curl -i http://127.0.0.1:8043/v1/portforward

# Depuis Gluetun
docker exec gluetun wget -S -O- http://127.0.0.1:8000/v1/portforward

La réponse attendue est HTTP/1.1 200 OK avec un port. Un 401 ou 403 signifie que l'authentification a été refusée. La méthode recommandée est une clé API générée avec docker run --rm qmcgaw/gluetun genkey, configurée dans Gluetun puis recopiée dans Companion. Sur un LAN entièrement maîtrisé, HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE={"auth":"none"} est possible mais fortement déconseillé par Gluetun ; ne publiez jamais ainsi le Control Server sur Internet.

ProtonVPN et qBittorrent

ProtonVPN attribue un port NAT-PMP aléatoire, susceptible de changer à chaque connexion ou renouvellement. Il ne faut donc ni saisir un port fixe, ni publier ce port dans le Compose Docker. Dans le profil VPN ProtonVPN, activez Port forwarding ; Companion écrit alors VPN_PORT_FORWARDING=on pour ce profil et peut limiter la sélection aux serveurs P2P / port-forwarding avec PORT_FORWARD_ONLY=on. Les autres types Gluetun disponibles (Streaming, Secure Core, Tor, Free) peuvent aussi être choisis depuis le profil ou le catalogue quand ils sont utiles. Configurez ensuite une règle avec le fournisseur ProtonVPN, le mode Natif Gluetun et le client qBittorrent concerné. Companion :

1. lit le port courant dans GET /v1/portforward ;
2. l'envoie à qBittorrent via /api/v2/app/setPreferences ;
3. relit les préférences qBittorrent pour confirmer l'application ;
4. vérifie toutes les 5 minutes si Gluetun a renouvelé le port et le réinjecte si nécessaire ;
5. recommence après une reconnexion Gluetun, une bascule vers ProtonVPN ou une bascule entre serveurs ProtonVPN.

Avec ProtonVPN en OpenVPN, le nom d'utilisateur OpenVPN doit aussi porter le suffixe +pmp. Avec ProtonVPN en WireGuard, ce suffixe n'est pas utilisé. Les intégrations natives de Gluetun ouvrent elles-mêmes le port dynamique côté VPN : FIREWALL_VPN_INPUT_PORTS, FIREWALL_INPUT_PORTS et un mapping Docker statique ne sont pas requis pour ce port.

Pour AirVPN, Companion ne crée pas le port sur le panel AirVPN. Le flux attendu est :

1. réserver le port dans le panel AirVPN ;
2. publier le port sur Gluetun, par exemple 19975:19975/tcp et 19975:19975/udp ;
3. ajouter le port à FIREWALL_INPUT_PORTS et FIREWALL_VPN_INPUT_PORTS ;
4. déclarer le port dans Companion ;
5. lier le port au client qBittorrent concerné ou ajouter une commande on_port_change ;
6. activer l’application automatique si les règles doivent suivre les changements de fournisseur VPN.

Pour rTorrent/ruTorrent, liez simplement un client de type rTorrent à la règle : la synchronisation XML-RPC s'applique automatiquement (bêta — voir ci-dessus). Pour les autres clients, les serveurs WireGuard personnels ou tout besoin spécifique, utilisez on_port_change pour appeler un script ou une commande maîtrisée. Les variables disponibles sont {port}, {provider}, {name}, {protocols} et {client}. Exemple :

/compose/hooks/update-rtorrent-port.sh {port}

Une règle Custom WireGuard peut ainsi servir à un serveur WireGuard personnel : le port est déclaré en manuel, ou récupéré par un hook externe, puis Companion exécute la commande lorsque la règle devient applicable.

Bandeau « Test en cours » et bouton Arrêter

Pendant tout test actif (benchmark complet, observation continue, test rapide proxy, sidecar, rotation de pool), un bandeau vert s'affiche en haut de chaque page avec le type de test en cours, le serveur testé, la progression en % (barre + pourcentage) et une estimation du temps restant calculée sur la durée moyenne des serveurs déjà testés ce cycle.

Le bouton Arrêter est disponible pour tous les modes :

• Benchmark / Observation / Sidecar — arrêt après le serveur en cours (≤ 2 secondes).
• Test rapide (proxy) — arrêt après l'échantillon en cours (≤ durée d'un échantillon, typiquement 8 s).
• Rotation de pool — signal d'arrêt envoyé ; la rotation se termine proprement.

La demande d'arrêt est persistée côté serveur : recharger ou quitter la page ne la réinitialise pas, le bandeau reste sur « Arrêt demandé… » jusqu'à l'arrêt effectif.

Sélecteur de serveurs AirVPN

Sur Serveurs → + Ajouter des serveurs AirVPN : un modal charge les données en direct depuis l'API AirVPN (cache 5 min côté serveur). Quatre onglets :

• Serveurs — liste complète avec barre de charge colorée (vert/orange/rouge), nombre d'utilisateurs, statut de santé, tri par colonne, recherche en temps réel
• Par pays — sections collapsibles par pays avec flag emoji, badge 🏆 Best sur le serveur le moins chargé, bouton "Sélectionner tous" par pays
• ⭐ Recommandés — serveurs répondant aux critères de présélection : charge < 70 % et bande passante AirVPN annoncée ≥ 5 Gbit/s ; badge vert indiquant le nombre disponible. Le peering réel entre votre accès et le serveur VPN n'est pas connu à l'import : il est approché ensuite par les benchmarks Companion (latence, jitter, perte, débit).
• ↔ Changements — diff depuis la dernière consultation : nouveaux serveurs apparus (ajoutables en un clic), serveurs disparus de l'API, changements de charge ≥ 10 % (avec flèche ↑↓ et delta), top 5 pays classés par pourcentage de serveurs sains puis charge moyenne

Les serveurs déjà dans la base sont grisés et leur case à cocher est désactivée. La barre de recherche filtre simultanément tous les onglets. Sélection multiple, ajout en un clic.

Vérification rapide avant benchmark (option)

Activer via Paramètres → Mesurer → Éviter les tests inutiles.

Lorsque cette option est activée, chaque cycle commence par un test de débit sur le serveur actuellement actif uniquement — avant de stopper des containers ou de relancer Gluetun :

• Dans la plage (défaut ±15 %) : le benchmark complet est ignoré. Aucun container n'est stoppé, Gluetun n'est pas relancé, aucune interruption VPN. Le cycle se termine en quelques secondes.
• Hors plage : le benchmark complet se lance normalement — tous les serveurs sont testés, le meilleur est sélectionné.

Implémentation : la vérification rapide passe exclusivement par le proxy HTTP de Gluetun — aucun container sidecar créé, aucune attente de reconnexion VPN. Résultat obtenu en 10–15 secondes.

Idéal pour des intervalles fréquents (ex. toutes les 2–3 h) où l'on veut un contrôle rapide sans le coût d'un benchmark complet à chaque fois.

La tolérance est configurable (1–100 %). Une valeur de 15 signifie : si le débit actuel est compris entre 85 % et 115 % du dernier résultat connu, le benchmark complet est ignoré.

Optimisation horaire (option)

Activer via Paramètres → Mesurer → Optimiser l’heure.

Companion analyse l’historique des tests pour calculer, pour chaque tranche horaire (0h–23h), le débit moyen et le coefficient de variation (CV = σ/μ). Une heure avec un débit élevé et une faible variance est une bonne fenêtre de benchmark — les mesures y sont représentatives et reproductibles.

Score par heure = débit_moyen × max(0, 1 − CV/100)

• 🟢 Bonne fenêtre — score ≥ 70 % du maximum
• 🔴 À éviter — score < 50 % du maximum

Quand c’est utile : si votre FAI régule la bande passante à certaines heures (throttling le soir, par exemple), ou si les serveurs VPN que vous utilisez sont significativement plus chargés à certains moments de la journée. Dans ce cas, benchmarker aux heures creuses donne des mesures plus fidèles à la réalité d’usage.

Quand c’est inutile : si votre réseau est stable 24h/24 et que vos serveurs VPN ont une charge relativement constante, cette option n’apportera rien de concret. Elle ne change pas quel serveur est le plus rapide — elle change seulement quand vous le mesurez.

Prérequis : au moins 6 tests dans au moins 8 tranches horaires différentes. Les résultats se stabilisent après plusieurs jours de benchmarks automatiques. En dessous de ce seuil, les moyennes par heure sont trop sensibles aux valeurs aberrantes pour être fiables.

Décalage automatique (sous-option) : si le cycle planifié tombe sur une heure défavorable, le benchmark est décalé d’un maximum de 3 h vers la prochaine fenêtre favorable. Si aucune n’est trouvée dans ce délai, le benchmark s’exécute immédiatement. Une fois terminé, le planificateur reprend son intervalle normal.

Stabilité de la fenêtre optimale : la meilleure heure n’est confirmée et notifiée qu’après deux cycles consécutifs pointant vers la même heure. Cela évite les fausses alertes dues au bruit statistique (une seule mesure exceptionnelle suffisait autrefois à faire changer la fenêtre).

Cette option est complémentaire du cycle automatique — elle ne le remplace pas. L’intervalle configuré reste la référence ; le décalage adaptatif n’ajuste que le prochain déclenchement si l’heure est jugée défavorable.

Sélection intelligente du benchmark (recommandée pour les gros catalogues)

Activer via Paramètres → Mesurer → Combien de serveurs tester.

Deux modes sont disponibles :

• Tout tester — mode exhaustif : tous les serveurs actifs compatibles passent dans le cycle. C'est utile pour construire une base initiale, mais très long avec des catalogues comme NordVPN.
• Sélection intelligente — mode recommandé : Companion teste les N meilleurs serveurs déjà connus selon le profil d'usage actif, ajoute quelques serveurs jamais testés, puis rafraîchit quelques résultats plus anciens que X jours.

Les quotas configurables sont rangés dans Options avancées de la sélection intelligente :

• Top connus — nombre de serveurs déjà mesurés à garder selon le profil d'usage.
• Nouveaux — nombre de serveurs jamais benchmarkés à explorer à chaque cycle.
• Anciens après J + À rafraîchir — âge minimum et nombre de résultats anciens à recontrôler.

Mettre un quota à 0 désactive cette partie. Le dashboard rappelle le mode utilisé, le nombre de serveurs estimé et le mode de test (sidecar ou proxy) avant lancement manuel.

Observation continue pyramidale

Activer via Paramètres → Mesurer → Combien de serveurs tester → Observation continue pyramidale.

Ce mode sert à rendre les profils d'usage sérieux sans lancer un benchmark gigantesque à chaque fois. Il transforme le cycle automatique en collecte progressive :

• Exploration — teste un lot de serveurs jamais mesurés, par rotation quotidienne dans la liste.
• Confirmation — reprend les serveurs qui ont déjà quelques mesures, jusqu'au seuil “confirmé”.
• Finalistes — concentre les mesures sur les meilleurs candidats qui n'ont pas encore assez d'historique.
• Rafraîchissement — recontrôle quelques serveurs matures dont les mesures sont devenues anciennes.

En observation continue, Companion ne fait pas de quick check, ne coupe pas les containers configurés dans “Containers à stopper pendant le benchmark” et ne bascule pas automatiquement de serveur. Le but est d'accumuler de l'historique utilisable, pas de perturber l'usage courant.

Le dashboard affiche l'état live de l'observation : serveur en cours, prochain serveur, progression du cycle, dernières lignes d'activité Companion et lien direct vers /history pour consulter les résultats enregistrés. Un watchdog interne vérifie régulièrement que l'observation reprend bien après un redémarrage ou quand le cycle automatique classique est en pause.

Si le cycle automatique classique est aussi activé, il garde un objectif différent : comparer la sélection configurée à intervalle régulier et, si l'auto-switch est activé, basculer Gluetun vers le meilleur serveur. Lorsqu'un cycle planifié arrive pendant l'observation continue, Companion met l'observation en pause, lance le benchmark complet normal (avec pause des containers si configurée), puis reprend l'observation via le watchdog. Les rotations de pool et les tests manuels (rapides ou complets) sont également prioritaires : ils interrompent l'observation en cours, s'exécutent, puis l'observation reprend si nécessaire.

Les profils ne doivent pas être compris comme une magie immédiate : avec une ou deux mesures, ils donnent seulement une indication. Ils deviennent vraiment pertinents quand les serveurs ont plusieurs benchmarks complets, idéalement à des heures différentes.

Serveurs autorisés avant benchmark (option)

Activer via Paramètres → Mesurer → Quels serveurs autoriser.

Ces règles réduisent la liste avant un benchmark complet. Les serveurs exclus restent visibles dans /servers et peuvent toujours être testés manuellement.

Par défaut, le benchmark teste toutes les entrées activées dans /servers, quel que soit leur type Gluetun. Avec Types Gluetun autorisés, vous sélectionnez exactement quels types participeront au cycle :

Type	Variable Gluetun	Usage typique
Nom	SERVER_NAMES	Serveurs AirVPN individuels, nom précis
Pays	SERVER_COUNTRIES	Sélection géographique large
Ville	SERVER_CITIES	Sélection géographique précise
Région	SERVER_REGIONS	Région / état
Hostname	SERVER_HOSTNAMES	Hostname FQDN

• Tous cochés (défaut) : comportement identique à avant — aucun filtrage.
• Certains cochés : seules les entrées des types cochés sont testées ; les autres restent dans /servers et peuvent être testées individuellement via le bouton « Tester maintenant ».

Utile si vous avez des entrées de type country/region pour une bascule de secours mais ne souhaitez les tester que ponctuellement, sans les inclure dans chaque cycle automatique.

Éviter les serveurs AirVPN chargés (option, dédié AirVPN)

Activer via Paramètres → Mesurer → Quels serveurs autoriser → Éviter les serveurs AirVPN chargés.

Lorsque vous avez ajouté un grand nombre de serveurs AirVPN (type SERVER_NAMES), le benchmark complet peut être très long. Ce pré-filtre permet d'ignorer automatiquement les serveurs surchargés au moment du lancement du cycle :

• Charge max (%) — 0 = désactivé. Ex : 70 → les serveurs affichant une charge > 70 % dans le cache AirVPN sont ignorés pour ce cycle.
• Utilisateurs max — 0 = désactivé. Ex : 30 → les serveurs avec plus de 30 utilisateurs connectés sont ignorés.

Les deux seuils sont indépendants et cumulables — un serveur est ignoré dès qu'au moins un seuil activé est dépassé.

Données utilisées : la table interne airvpn_snapshot, mise à jour toutes les 5 minutes depuis l'API airvpn.org/api/status/. Aucun appel API supplémentaire n'est effectué au lancement du benchmark.

Serveurs sans données : un serveur de type name sans entrée dans le snapshot (provider non-AirVPN, serveur hors API) n'est jamais filtré — il est toujours inclus dans le benchmark.

Périmètre : ce filtre ne s'applique qu'aux serveurs de type name (AirVPN). Les entrées de type country, city, region, hostname ne sont jamais affectées.

Les serveurs ignorés restent dans /servers, peuvent être testés manuellement, et seront à nouveau candidats au prochain cycle si leur charge a baissé entre-temps.

Écoute Docker events

Un thread daemon démarre avec Companion et surveille en continu le flux d'événements Docker filtré sur le container Gluetun. À chaque événement start reçu :

Événement Docker "start" reçu sur le container Gluetun
  ├─ Redémarrage initié par Companion ? (fenêtre de 180 s)  → ignoré silencieusement
  ├─ Cooldown actif ? (5 min depuis le dernier déclenchement) → ignoré
  ├─ Benchmark déjà en cours ?                               → ignoré
  └─ OK — programmation d'un quick check différé
       1. Attente de N secondes (= valeur « Délai de reconnexion »)
          pour laisser le VPN se reconnecter
       2. Quick check via le proxy HTTP sur le serveur actif
          ├─ VPN pas encore prêt (pas de réponse proxy)
          │    → log d'avertissement, abandon
          ├─ Aucun résultat de référence en base
          │    → résultat enregistré comme nouvelle référence, fin
          ├─ Débit dans la plage ±N %
          │    → log OK, fin
          └─ Dérive détectée (débit hors plage)
               ├─ Bascule auto activée → benchmark complet immédiat
               └─ Bascule auto désactivée → log d'avertissement uniquement

Suppression des redémarrages Companion : quand Companion bascule vers un serveur (switch_server()), il active une fenêtre de suppression de 180 secondes. Tout événement start reçu pendant cette fenêtre est ignoré — ce mécanisme évite une boucle infinie où Companion déclencherait lui-même un quick check après chaque bascule qu'il vient d'initier.

Badge dans l'historique : les tests déclenchés par un événement Docker sont marqués docker_event en base. Un badge sombre auto apparaît sur la ligne correspondante dans l'historique (/history), avec un tooltip explicatif.

Prérequis : le socket Docker (ou le proxy Tecnativa) doit être accessible depuis Companion, et la variable GLUETUN_CONTAINER doit correspondre au nom exact du container Gluetun.

Score de confiance par serveur

Un indicateur coloré est affiché sur la page Serveurs (colonne Fiabilité) et dans l'Historique pour chaque serveur. Il reflète la fiabilité des mesures accumulées.

Niveau	Conditions
🟢 Élevé	≥ 5 mesures et variabilité < 40 %
🟡 Modéré	2–4 mesures ou variabilité 40–70 %
🔴 Faible	≤ 1 mesure, variabilité > 70 % ou échecs consécutifs

La variabilité (coefficient de variation) mesure l'écart-type des débits rapporté à la moyenne : 0 % = résultats identiques à chaque test, 100 % = résultats très dispersés. Les tests proxy_qc sont exclus du calcul.

Le score influence légèrement la sélection automatique du meilleur serveur : HIGH × 1,0 · MEDIUM × 0,95 · LOW × 0,85 appliqués sur le score pondéré.

Profils d'usage

Companion propose 6 profils d'usage sélectionnables depuis la page Serveurs (barre de pills) ou depuis Paramètres → Décider → Profil d'usage.

Le profil actif détermine comment le meilleur serveur est sélectionné à la fin de chaque cycle de benchmark, en pondérant différemment les métriques mesurées.

Important : un profil d'usage n'est fiable que si l'historique est suffisant. Au début, Companion peut surtout comparer le débit disponible ; la latence, le jitter, la perte de paquets, l'upload, le monoflux DDL et la stabilité ne deviennent discriminants qu'après plusieurs benchmarks complets par serveur. Pour construire cet historique sans tester tout le catalogue en boucle, utilisez l'observation continue pyramidale dans Paramètres → Mesurer.

Profil	Critère principal	Usage typique
Équilibré (défaut)	Score pondéré existant (débit + historique + stabilité)	Usage général — comportement identique à avant
Jeu en ligne	Faible latence + faible jitter	FPS, MMO, jeux compétitifs
BitTorrent	Upload multiflux maximal	qBittorrent, Transmission, Deluge
DDL (mono-flux)	Débit monoflux	Usenet (SABnzbd), téléchargeurs directs (JDownloader)
Téléchargement (multi-flux)	Débit download multiflux maximal	Radarr/Sonarr, transferts volumineux
Streaming vidéo	Débit stable + faible jitter	Jellyfin, Plex, lecture directe

Algorithme : pour chaque résultat du cycle en cours, Companion calcule le _weighted_score (débit + historique + stabilité), puis normalise [0,1] l'ensemble des résultats sur chaque axe. La combinaison pondérée des scores normalisés détermine le meilleur serveur selon le profil actif. Le profil Équilibré reproduit exactement le comportement antérieur — aucune régression.

Profil DDL et test monoflux : le profil DDL exploite une métrique supplémentaire, le débit monoflux (dl_single_mbps), mesurée après le test principal (connexion VPN déjà établie, sans surcoût de reconnexion). Ce test est optionnel et désactivé par défaut — activer via Paramètres → Mesurer → Mesure de vitesse → Test monoflux (DDL).

Page Serveurs : la barre de profils affiche le meilleur serveur pour le profil actif (calculé sur les moyennes historiques). Ce serveur est mis en évidence par un badge 🏆 sur sa ligne (masqué en profil Équilibré).

Score explicable : chaque serveur affiché dans la vue tableau dispose d'un bouton 📊 (icône graphique) à côté de son nom. Un clic ouvre un popover détaillant la contribution de chaque métrique au score final — débit download, upload, latence, jitter, perte de paquets — sous forme de barres de progression pondérées, avec les valeurs brutes mesurées. Seules les métriques effectivement utilisées par le profil actif sont affichées.

Fenêtre temporelle de scoring : par défaut, les moyennes utilisées pour le classement des serveurs sont calculées sur les 30 derniers jours. Ce paramètre est ajustable dans Paramètres → Décider → Fenêtre de scoring : 7 j, 14 j, 30 j, ou toutes les données. Une fenêtre courte favorise les performances récentes ; une fenêtre longue lisse les pics ponctuels.

Détection d'outliers : option activable dans Paramètres → Décider → Filtrage des valeurs aberrantes. Lorsqu'elle est active, les mesures isolées manifestement hors-norme sont ignorées lors du calcul des moyennes et du scoring — elles restent visibles dans l'historique. Exemple concret : si un serveur donne habituellement 80–100 Mbps et qu'un test exceptionnel affiche 5 ou 200 Mbps (pic réseau passager, saturation ponctuelle, test raté), cette valeur est écartée des calculs. La méthode IQR détermine automatiquement la plage normale par serveur et par métrique (débit, latence, jitter…) sans seuil à configurer. Requiert au minimum 4 mesures par serveur pour s'appliquer.

Profils VPN (WireGuard & OpenVPN)

Les profils VPN permettent de gérer plusieurs fournisseurs ou identités VPN — en WireGuard comme en OpenVPN — dans une seule instance Companion, avec bascule automatique optimisée entre eux. Les 24 fournisseurs du wiki Gluetun sont intégrés (voir le tableau des fournisseurs).

Création d'un profil

Dans Paramètres → Profils VPN :

1. Choisissez le provider dans le menu déroulant → les champs de configuration apparaissent dynamiquement selon les variables requises par Gluetun pour ce fournisseur
2. Si le fournisseur gère les deux types, choisissez le type de connexion (WireGuard ou OpenVPN) — les champs s'adaptent au type sélectionné
3. Remplissez les champs (clé privée, identifiants OpenVPN, etc.) — les champs marqués 🔒 sont chiffrés avant stockage
4. Nommez le profil (ex. « Mullvad — Suède », « PIA — OpenVPN US »)
5. Les options Actif et Rotation autorisée permettent d'inclure ou exclure le profil des cycles automatiques

Sécurité des secrets : les valeurs chiffrées sont préfixées enc: en base. Elles ne sont déchiffrées qu'au moment de la construction de l'override Compose ou du lancement d'un container sidecar — jamais exposées dans les logs ni dans l'export de configuration.

WireGuard : deux clés différentes — la clé privée WireGuard du profil principal est obligatoire pour connecter et basculer Gluetun. La clé privée Sidecar est une seconde identité réservée aux benchmarks isolés ; la renseigner ne remplace jamais la clé principale.

Profils OpenVPN

Pour les fournisseurs OpenVPN, le profil porte selon le cas :

• Identifiants — OPENVPN_USER / OPENVPN_PASSWORD (la majorité des fournisseurs : ExpressVPN, IPVanish, NordVPN, PIA, Surfshark, TorGuard, VyprVPN…) ; attention, plusieurs fournisseurs utilisent des identifiants de service distincts du login du site web (NordVPN, ProtonVPN, Surfshark, Windscribe)
• Certificat et clé client — CyberGhost, VPN Unlimited et AirVPN (OpenVPN) demandent en plus (ou à la place) un certificat et une clé client : collez le contenu base64 sur une seule ligne, sans les lignes BEGIN/END, dans les champs OPENVPN_CERT / OPENVPN_KEY — aucun fichier à monter
• Clé chiffrée + passphrase — SlickVPN et VPN Secure utilisent une clé client chiffrée (OPENVPN_ENCRYPTED_KEY) avec sa passphrase (OPENVPN_KEY_PASSPHRASE)

À la bascule, Companion écrit VPN_TYPE=openvpn et les variables OPENVPN_* dans l'override Compose, en blanchissant les identifiants des autres fournisseurs/types pour éviter toute fuite. En mode sidecar, les profils OpenVPN sont testés avec leurs propres identifiants (pas de clé sidecar dédiée — la plupart des fournisseurs autorisent plusieurs connexions simultanées par compte).

Le mode Custom OpenVPN (VPN_SERVICE_PROVIDER=custom + VPN_TYPE=openvpn) couvre tout fournisseur absent du catalogue Gluetun. Dans Paramètres → Profils VPN → Configurations Custom OpenVPN, Companion peut téléverser un fichier .ovpn ou .conf, détecter ceux déjà montés dans Gluetun, les lister et créer automatiquement le profil correspondant.

Le même dossier hôte doit être monté dans les deux containers :

# Compose de Gluetun
services:
  gluetun-airvpn:
    volumes:
      - /home/aerya/docker/gluetun/openvpn:/gluetun/openvpn:ro

# Compose de Companion
services:
  gluetun-companion:
    volumes:
      - /home/aerya/docker/gluetun/openvpn:/openvpn
    environment:
      - OPENVPN_CONFIG_DIR=/openvpn
      - OPENVPN_CONTAINER_DIR=/gluetun/openvpn

Les fichiers téléversés apparaissent ainsi dans Gluetun sous /gluetun/openvpn/nom-du-profil.ovpn. La détection peut aussi inventorier d'autres fichiers .ovpn ou .conf déjà présents sous /gluetun, sans docker exec.

Comme indiqué par Gluetun, les éventuels fichiers annexes référencés par la configuration (ca.crt, clé, script…) doivent également être montés sous /gluetun et référencés avec un chemin absolu. Si le fichier contient un nom d'hôte dans sa directive remote, remplacez-le par une adresse IP afin que le pare-feu de démarrage de Gluetun n'ait pas besoin d'une résolution DNS préalable.

Custom WireGuard : serveur personnel unique

Le provider Custom WireGuard sert aux configurations Gluetun VPN_SERVICE_PROVIDER=custom, notamment quand vous avez un seul serveur WireGuard personnel ou un fournisseur sans catalogue de serveurs Gluetun.

Dans ce mode, Companion ne renseigne aucune variable SERVER_* (SERVER_NAMES, SERVER_COUNTRIES, etc.). Les champs du profil custom décrivent directement l'unique endpoint WireGuard :

• WIREGUARD_ENDPOINT_IP
• WIREGUARD_ENDPOINT_PORT
• WIREGUARD_PUBLIC_KEY
• WIREGUARD_PRIVATE_KEY
• WIREGUARD_ADDRESSES
• WIREGUARD_PRESHARED_KEY si votre configuration l'utilise

La ligne ajoutée dans Serveurs devient simplement un nom de suivi statistique, par exemple Serveur perso, Home-WG ou VPS-Paris. Elle permet d'attacher les benchmarks, l'historique, Prometheus et Grafana à ce serveur, sans faire de comparatif entre plusieurs destinations.

Configuration recommandée :

1. Créez un profil Custom WireGuard dans Paramètres → Profils VPN.
2. Copiez les valeurs de votre fichier WireGuard .conf dans les champs du profil.
3. Ajoutez une seule entrée dans Serveurs avec un nom libre.
4. Assignez cette entrée au profil Custom WireGuard.
5. Laissez l'observation ou les benchmarks planifiés mesurer régulièrement ce serveur.

À la bascule, Companion écrit VPN_SERVICE_PROVIDER=custom, VPN_TYPE=wireguard et les variables WIREGUARD_* dans docker-compose.override.yml, puis laisse toutes les variables SERVER_* vides.

⚠️ Clé WireGuard sidecar par profil (recommandée)

Si vous utilisez le mode sidecar pour les benchmarks avec WireGuard, le plus fiable est de donner à chaque profil WireGuard sa propre identité sidecar dédiée. Companion permet aussi, en option avancée, de réutiliser la configuration WireGuard du profil principal.

Cette section ne concerne que les profils WireGuard : les profils OpenVPN sont testés directement avec leurs propres identifiants (la section Clé sidecar dédiée est masquée pour eux).

Pourquoi c'est recommandé : les containers sidecar de test clonent l'environnement de votre container Gluetun principal, y compris sa WIREGUARD_PRIVATE_KEY. Quand un container de test initie un nouveau handshake WireGuard avec la même clé depuis une adresse IP différente, certains fournisseurs VPN mettent à jour la route du peer… et le tunnel de votre Gluetun principal peut tomber.

Pourquoi il n'y a pas de clé globale : une clé AirVPN ne peut pas s'authentifier auprès de Mullvad ou Proton, et inversement. Une clé sidecar partagée entre plusieurs providers est donc invalide par nature — chaque profil doit porter sa propre configuration.

Solution : dans Paramètres → Profils VPN, modifiez chaque profil et renseignez la section Clé sidecar dédiée :

• Clé privée sidecar — nouvelle clé privée générée auprès du même fournisseur que le profil (ex. wg genkey pour les providers qui l'acceptent, ou depuis votre espace client)
• Adresse IP sidecar — l'adresse IP assignée à cette clé par votre fournisseur (format CIDR, ex. 10.x.x.x/32)
• Clé pré-partagée sidecar — uniquement si votre fournisseur en exige une

Cas AirVPN / device : réexporter la configuration du même device AirVPN redonne normalement le même PrivateKey, PresharedKey et Address. Pour obtenir un triplet différent dédié au sidecar, créez un deuxième device/peer côté AirVPN, même s'il correspond au même serveur physique chez vous.

Option avancée : cochez Réutiliser la configuration WireGuard du profil principal si vous acceptez que le sidecar utilise les mêmes identifiants WireGuard que Gluetun principal. C'est pratique pour les fournisseurs qui le tolèrent, mais cela peut perturber le tunnel principal chez d'autres.

Si un profil n'a ni clé sidecar dédiée ni option de réutilisation activée, ses serveurs sont ignorés en mode sidecar (aucun résultat d'échec enregistré — ils sont simplement exclus du cycle). Si le fallback proxy est activé, ils basculent automatiquement en mode proxy.

Liaison serveurs ↔ profils

Sur la page Serveurs :

• La colonne Provider affiche le profil VPN assigné à chaque serveur
• Si aucun profil n'est assigné, un menu déroulant permet l'assignation directe depuis le tableau
• Le filtre ?profile=<id> (dropdown dans la barre de filtres) limite l'affichage aux serveurs d'un profil ou aux serveurs non assignés (__none__)
• Les serveurs sans profil pendant qu'au moins un profil est configuré sont signalés par une alerte (serveurs orphelins)

Benchmark multi-profil — flux d'exécution

Cycle de benchmark avec profils VPN
  ├─ Chargement et déchiffrement des identifiants (WireGuard ou OpenVPN)
  │    pour chaque profil_id distinct dans la liste de serveurs
  │    → cache en mémoire pour la durée du cycle (secrets déchiffrés, non persistés)
  └─ Pour chaque serveur activé :
       1. Récupération de l'extra_env du profil associé
          (VPN_SERVICE_PROVIDER, VPN_TYPE, WIREGUARD_* ou OPENVPN_*)
       2. Mode sidecar :
          ├─ profil OpenVPN → container sidecar lancé avec les identifiants du profil
          │   (la plupart des fournisseurs autorisent plusieurs connexions simultanées)
          ├─ profil WireGuard avec clé sidecar dédiée → container sidecar lancé avec la clé sidecar
          │   (évite le conflit de peer avec le tunnel Gluetun principal)
          ├─ profil WireGuard autorisant la réutilisation → sidecar avec les vars du profil principal
          └─ profil WireGuard sans clé sidecar ni réutilisation → serveur IGNORÉ pour ce cycle
             (si fallback proxy activé → test en mode proxy à la place)
       3. Mode proxy : test via le proxy HTTP Gluetun (pas de container sidecar)
  └─ Sélection du meilleur serveur selon la politique de rotation :
       ├─ none        → contraint au profil du serveur Gluetun actuellement actif
       ├─ conditional → bascule cross-profil si gain > seuil (défaut 10 %)
       └─ free        → meilleur global, tous profils confondus
  └─ Bascule Gluetun :
       → écriture de VPN_SERVICE_PROVIDER + VPN_TYPE + identifiants dans l'override Compose
         (les identifiants des autres fournisseurs/types sont blanchis)
       → docker compose up -d (un seul redémarrage Gluetun)

Politique de rotation

Mode	Comportement
none	Companion cherche le meilleur serveur dans le profil actuellement actif. Si aucun résultat n'est disponible pour ce profil (tous exclus, tous orphelins), aucune bascule.
free	Tous les serveurs testés sont candidats — le meilleur global est retenu sans égard au profil.
conditional	Le benchmark est global, mais la bascule vers un autre profil n'a lieu que si score_meilleur_global > score_meilleur_du_profil_actif × (1 + seuil/100). Autrement, le meilleur serveur du profil actif est conservé.

Le seuil du mode conditional est configurable de 1 à 100 % dans les Paramètres. Un seuil de 10 % signifie : « ne change de profil que si le gain est supérieur à 10 % ».

---

Pools de rotation

Les pools de rotation permettent de basculer vers un serveur d'un groupe prédéfini sans déclencher de benchmark complet. Accessible depuis la page Rotation dans la barre de navigation.

Création d'un pool

Dans Rotation → Nouveau pool :

1. Donnez un nom au pool (ex. « Gaming FR », « Fallback EU »)
2. Choisissez le mode de sélection :
   • 🎲 Aléatoire — random.choice() parmi les candidats
   • 🔄 Tour à tour — cycle alphabétique avec curseur persistant entre deux rotations
   • 🏆 Meilleur débit historique — candidat avec le meilleur débit moyen historique
3. Ajoutez un ou plusieurs critères pour construire les serveurs candidats :
   • Tous les serveurs actifs — inclut l'intégralité des serveurs activés dans Companion
   • Serveur précis — saisissez le nom exact ; l'autocomplete propose les serveurs existants
   • Type de filtre Gluetun — choisissez la variable (SERVER_COUNTRIES, SERVER_NAMES, etc.) et optionnellement une valeur (vide = tous les serveurs de ce type)
   • Profil VPN — tous les serveurs assignés à un profil WireGuard ou OpenVPN spécifique
   • Top N par métrique — ajoute ou restreint selon les meilleurs historiques de débit, jitter, perte ou DNS
   • Bande passante AirVPN min. — ajoute les serveurs AirVPN dont la capacité annoncée (bw_max) atteint au moins la valeur choisie
4. Choisissez comment combiner les règles :
   • Ajouter les résultats de chaque règle — chaque règle ajoute des serveurs ; les doublons sont fusionnés automatiquement.
   • Garder seulement les serveurs qui respectent toutes les règles — plus strict, utile pour faire « France + profil AirVPN + Top débit ».
5. Ajoutez si besoin des exclusions du pool : ces serveurs restent actifs dans Companion, mais ce pool ne les choisira jamais.
6. Définissez une limite finale optionnelle : si renseignée, seuls les N meilleurs débits historiques restent éligibles après règles et exclusions.
7. Configurez la planification : rotation automatique toutes les N heures (désactivée = manuel uniquement)
8. Activez Mesurer après bascule si vous souhaitez enregistrer le débit après chaque rotation. Cette mesure ne sert pas à choisir le serveur.

L'aperçu est mis à jour en temps réel dans le modal : candidats avant exclusions, nombre de serveurs exclus, serveurs utilisables et limite finale éventuelle.

Flux d'exécution d'une rotation

Rotation déclenchée (manuelle ou automatique) :
  1. Résolution des candidats
     ├─ règles ajoutées ensemble ou croisées selon le mode choisi
     ├─ retrait des exclusions explicites du pool
     ├─ retrait des serveurs connus incompatibles trackers (si option activée)
     └─ limite finale par débit historique (si activée)
  2. Sélection du serveur cible (random / round-robin / meilleur débit historique)
  3. switch_server() → écriture docker-compose.override.yml + docker compose up -d
     └─ Si profil VPN associé : injection de VPN_SERVICE_PROVIDER, VPN_TYPE et WIREGUARD_* ou OPENVPN_* dans l'override
  4. Attente reconnexion VPN + recréation des containers `network_mode: service:gluetun`
  5. Si mesure après bascule activée :
     ├─ Attente reconnexion VPN (connection_wait_seconds)
     ├─ Test proxy rapide (proxy_qc)
     └─ Enregistrement dans speed_tests (test_trigger='pool_rotation')
  6. Mise à jour de l'état du pool (last_rotated_at, next_rotation_at, dernier serveur, dernier débit/erreur, curseur round-robin)
  7. Notification Discord/Apprise (si activé)

Planification automatique

Le scheduler vérifie toutes les 5 minutes si des pools ont une rotation en attente (next_rotation_at <= now). Si un benchmark est en cours, la rotation est différée au prochain tick (sans modifier next_rotation_at).

Les rotations de pool et les benchmarks partagent le même verrou opérationnel : une rotation ne se déclenche pas pendant un benchmark actif, et inversement.

Quand au moins un pool de rotation automatique est actif, le cycle automatique classique de Paramètres → Mesurer passe en pause : le toggle est désactivé dans l'UI, les benchmarks manuels restent disponibles, et les rotations de pool deviennent le planificateur principal. Cette mise en pause persiste au redémarrage du container : Companion détecte les pools actifs au démarrage et ne relance pas le cycle benchmark même si la base de données conservait auto_benchmark=1.

Les rotations de pool sont visibles sur le dashboard / et dans /history. Une bascule apparaît comme activité de pool ; si l'option Mesurer après bascule est activée, le test proxy_qc reçoit aussi le badge pool.

Notifications de rotation de pool

Type	Sévérité	Contenu
🟡 Rotation de pool	Moyen	Nom du pool, mode (auto/manuel), serveur précédent → nouveau, débit si mesure après bascule activée, IP publique

---

Score de sélection — composantes de stabilité

Le score final de sélection intègre désormais quatre composantes de fiabilité, toutes pondérées par le curseur Priorité débit vs stabilité (Paramètres) :

score = (w_cur × débit_actuel + w_hist × historique_exp)
        × confidence_factor
        × effective_stability

effective_stability = 1 − (stability_weight/100) × (1 − raw_stability)

raw_stability = jitter_factor × loss_factor × reconnect_factor

Composante	Source	Pénalité max
Jitter	Mesuré à chaque test (jitter_ms)	−15 % à 150 ms
Perte paquets	Mesuré à chaque test (packet_loss_pct)	−25 % à 10 % de perte
Reconnexions involontaires	Docker events sur 30 j (test_trigger=docker_event)	−10 % par reconnexion, max −30 %
Confiance (variance historique)	Coefficient de variation sur tous les tests de la fenêtre de scoring (proxy_qc exclus)	−15 % (LOW) · −5 % (MEDIUM)

Curseur Priorité débit vs stabilité (Paramètres → Décider) :

• 0 — seul le débit compte, toutes les pénalités sont désactivées
• 30 (défaut) — 30 % des pénalités sont appliquées
• 100 — pénalités complètes — un serveur à 300 Mbps avec 3 reconnexions involontaires + jitter élevé peut perdre jusqu'à ~40 % de score

Un serveur à 200 Mbps sans reconnexion et avec un jitter stable sera préféré à un 300 Mbps qui déconnecte toutes les heures, dès lors que stability_weight ≥ ~20.

Vue patterns horaires (/history/patterns)

Accessible depuis Historique → Patterns horaires, cette vue affiche les performances moyennes par tranche horaire (0h–23h) pour un serveur donné.

• Graphique en barres colorées selon les performances relatives au maximum du serveur : 🟢 ≥ 85 % · 🟡 65–85 % · 🟠 45–65 % · 🔴 < 45 %
• Heures en heure locale (variable d'environnement TZ respectée)
• Meilleure et pire heure affichées en stat cards
• Tests rapides (proxy_qc) exclus
• Visualisation pure — cette vue n'influence pas le planificateur. C'est l'Optimisation horaire dans les Paramètres qui utilise ces données pour décaler les benchmarks automatiques.
• Utile pour visualiser si un serveur VPN donné a des performances qui varient significativement selon l'heure

Détection de nouveaux serveurs AirVPN

Fonctionnalité désactivée par défaut, uniquement pour les utilisateurs AirVPN. Activable dans Paramètres → Notifications.

Logique :

1. Toutes les 24 h, Companion récupère la liste AirVPN via airvpn.org/api/status/
2. Il compare avec les serveurs configurés (type name) pour déterminer quels pays vous utilisez
3. Si un nouveau serveur apparaît dans un de ces pays, il est stocké dans la base pendant 7 jours

Surfaces UI :

• Badge +N sur le bouton Ajouter des serveurs AirVPN (page Serveurs)
• Bannière dismissable en haut de la page Serveurs : « 3 nouveaux serveurs disponibles dans vos pays (NL, FR) » avec lien vers le modal
• Onglet Changements dans le modal d'ajout : section Nouveaux serveurs détectés avec badge ⭐ Nouveau et case à cocher pour ajout direct ; filtre de recherche unifié

Notification Discord/Apprise : Envoyée uniquement lors de la découverte de nouveaux serveurs, regroupée par pays. Utilise le champ Mention Discord global (voir Notifications contextuelles).

Après 7 jours, les serveurs quittent automatiquement la liste des "nouveaux". Les serveurs ajoutés à votre liste ne s'affichent plus dans le badge/bannière.

Notifications contextuelles

Companion envoie des alertes ciblées via webhook Discord et/ou Apprise selon les événements. Chaque type d'alerte est activable indépendamment dans Paramètres → Notifications.

Type d'alerte	Sévérité	Activé par défaut	Déclenchement
🔴 Panne VPN / basculement de secours	Critique	✅	Gluetun reste indisponible après le délai de grâce ; résultat de la tentative de secours
🔴 Auto-exclusion serveur	Critique	✅	Un serveur est désactivé après N échecs consécutifs
🔴 Benchmark sans résultat	Critique	✅	Le cycle complet se termine sans aucun résultat valide
🟡 Bascule automatique	Moyen	✅	Companion bascule vers un meilleur serveur
🟡 Rotation de pool	Moyen	✅	Un pool de rotation bascule vers un nouveau serveur (auto ou manuel)
🟡 Nouveaux serveurs AirVPN	Moyen	(selon détection AirVPN)	Nouveaux serveurs détectés dans vos pays
🔵 Bascule manuelle	Info	❌	Bascule déclenchée manuellement depuis l'UI
🔵 Début de benchmark	Info	❌	Cycle confirmé ; peut annoncer des interruptions VPN temporaires et les containers mis en pause
🔵 Fin de benchmark	Info	❌	Cycle de benchmark terminé avec succès
🔵 Déjà sur le meilleur	Info	❌	Le serveur actif est déjà le meilleur — aucun changement
🔵 Résultat quick check	Info	✅	Benchmark rapide manuel terminé (serveur, vitesse, delta vs baseline)
🔵 Changements catalogue	Info	❌	Serveurs ajoutés ou supprimés lors d'un refresh catalogue (détail par provider)
🔵 Fenêtre optimale changée	Info	❌	L'heure globale optimale de benchmark a changé (basé sur les patterns historiques)

Mention Discord globale : un seul champ Mention Discord (ex. <@123456789> pour un utilisateur, <@&987654321> pour un rôle) s'applique à toutes les alertes. Un seuil de sévérité est configurable :

• Critique uniquement (défaut) — mention uniquement pour les alertes 🔴
• Moyen et critique — mention pour 🔴 et 🟡
• Toutes — mention pour toutes les alertes

La mention est injectée dans le payload Discord via allowed_mentions pour garantir la délivrance même sur les serveurs avec restrictions de mentions.

---

Jitter & Packet Loss

Chaque test mesure automatiquement la stabilité de la connexion VPN, en plus du débit.

Méthode selon le mode :

• Mode proxy — 21 sondes TTFB (Time To First Byte) réparties sur 3 cibles (Cloudflare, Google, Quad9). La variance des temps de réponse donne le jitter, les requêtes échouées donnent le taux de perte.
• Mode sidecar — l'endpoint /ping du container sidecar effectue des handshakes TCP sur les mêmes 3 cibles (20 tentatives chacune). Retombe sur None si l'ancienne version du sidecar ne supporte pas /ping.

Métriques produites :

• jitter_ms — écart-type des temps de réponse (ms) — représente la variabilité/instabilité
• packet_loss_pct — pourcentage de requêtes/paquets perdus
• ping_min_ms / ping_max_ms — meilleur et pire temps de réponse

Surfaces UI :

• Page Serveurs — colonne Stabilité : point coloré 🟢 (jitter < 15 ms, perte < 1 %) / 🟡 (< 50 ms, < 5 %) / 🔴 (au-delà), tooltip avec valeurs détaillées
• Historique — colonnes Jitter et Perte avec code couleur identique par ligne
• Patterns horaires — le tooltip de chaque barre inclut le jitter moyen de la tranche horaire

Intégration dans le score de sélection : Le score est multiplié par un facteur de pénalité cumulatif :

• Jitter : max(0.85, 1 − jitter_ms / 1000) → pénalité jusqu'à −15 %
• Perte : max(0.75, 1 − packet_loss_pct / 40) → pénalité jusqu'à −25 %

Un serveur rapide mais instable sera donc déclassé au profit d'un serveur légèrement moins rapide mais fiable.

Endpoint Prometheus /metrics

L'endpoint GET /metrics expose les métriques clés au format texte Prometheus, sans dépendance externe.

Métriques disponibles (par serveur) :

• gluetun_companion_server_avg_dl_mbps — débit download moyen (benchmarks complets uniquement, proxy_qc exclu)
• gluetun_companion_server_avg_ul_mbps — débit upload moyen
• gluetun_companion_server_avg_latency_ms — latence moyenne
• gluetun_companion_server_test_count — nombre total de tests
• gluetun_companion_server_failure_count — nombre de tests échoués
• gluetun_companion_server_consecutive_failures — échecs consécutifs en cours
• gluetun_companion_server_enabled — 1 si activé pour le benchmark
• gluetun_companion_server_active — 1 si c'est le serveur Gluetun actuellement actif
• gluetun_companion_server_last_benchmark_ts_seconds — timestamp Unix du dernier test enregistré

Les métriques serveur portent les labels server, provider et profile, ce qui permet à Grafana de proposer automatiquement des filtres quand vous ajoutez des serveurs, fournisseurs ou profils VPN.

Métriques globales :

• gluetun_companion_switches_total — nombre total de bascules
• gluetun_companion_switches_success_total — bascules réussies
• gluetun_companion_benchmark_running — 1 si un benchmark est en cours
• gluetun_companion_benchmark_total_servers, gluetun_companion_benchmark_done_servers, gluetun_companion_benchmark_remaining_servers — progression du cycle en cours
• gluetun_companion_continuous_observation_enabled, gluetun_companion_continuous_observation_running — état de l'observation continue
• gluetun_companion_rotation_pools_total, gluetun_companion_rotation_pools_enabled, gluetun_companion_rotation_pools_auto_enabled — état global des pools
• gluetun_companion_rotation_pool_last_speed_mbps, gluetun_companion_rotation_pool_last_rotation_timestamp_seconds, gluetun_companion_rotation_pool_next_rotation_timestamp_seconds — métriques par pool, avec label pool
• gluetun_companion_last_switch_timestamp_seconds — timestamp Unix de la dernière bascule

Authentification : par défaut ouvert (standard pour un réseau interne). Deux façons de protéger /metrics par Bearer token : définir la variable d'environnement METRICS_TOKEN, ou configurer un token API dans Paramètres → Maintenance → REST API (les deux sont supportés, METRICS_TOKEN a la priorité).

Scrape Prometheus (à ajouter dans prometheus.yml) :

scrape_configs:
  - job_name: gluetun-companion
    static_configs:
      - targets: ['gluetun-companion:8765']
    # Si METRICS_TOKEN est défini :
    # bearer_token: your-secret-token

---

REST API

L'API est désactivée par défaut. Pour l'activer : Paramètres → Maintenance → REST API → Générer un nouveau token.

Authentification : toutes les requêtes doivent inclure l'en-tête :

Authorization: Bearer <votre-token>

Endpoints disponibles :

Méthode	URL	Description
GET	/api/v1/status	Serveur actif, état VPN, benchmark en cours, prochain cycle
GET	/api/v1/servers	Liste complète des serveurs avec débit moyen, jitter, fiabilité
GET	/api/v1/history	Historique des tests (?limit=50&offset=0&server=Castor)
GET	/api/v1/switches	Historique des bascules (?limit=20)
POST	/api/v1/benchmark/trigger	Déclencher un benchmark complet (asynchrone, HTTP 202)
POST	/api/v1/benchmark/trigger-quick	Déclencher un test rapide proxy (asynchrone, HTTP 202)

Exemples curl :

# Statut
curl -H "Authorization: Bearer <token>" http://localhost:8765/api/v1/status

# Déclencher un benchmark
curl -X POST -H "Authorization: Bearer <token>" http://localhost:8765/api/v1/benchmark/trigger

# Historique des 10 derniers tests du serveur Castor
curl -H "Authorization: Bearer <token>" \
  "http://localhost:8765/api/v1/history?limit=10&server=Castor"

Codes de retour :

• 200 — succès (GET)
• 202 — déclenchement accepté (POST trigger)
• 401 — token invalide ou absent
• 403 — API désactivée (aucun token configuré)
• 409 — un benchmark est déjà en cours (POST trigger)

Les POST triggers retournent immédiatement — le benchmark tourne en arrière-plan. Utilisez GET /api/v1/status pour suivre la progression (benchmark_running).

Cycle automatique vs déclenchement manuel

Dans Paramètres → Mesurer : le cycle automatique peut être désactivé via le toggle Activer le cycle de benchmark automatique. Le champ intervalle est alors grisé. Deux boutons restent disponibles à tout moment (dashboard et paramètres) :

• Benchmark rapide — teste uniquement le serveur actif via le proxy HTTP de Gluetun ; résultat en quelques secondes, aucune interruption VPN, résultat sauvegardé dans l'historique (méthode proxy_qc).
• Benchmark complet — lance un cycle complet immédiatement, quels que soient le cycle automatique et l'option Vérification rapide. Utilise la méthode configurée (sidecar ou proxy), label affiché entre parenthèses sur le bouton.

Estimation de durée : le dashboard affiche sous les boutons une fourchette ~min–max / serveur et un total estimé pour la sélection réellement testée, calculés à partir de wait_secs, duration, samples, retries, du mode (proxy/sidecar), des filtres et de la sélection intelligente. Une alerte ⚠️ s'affiche automatiquement si le total pessimiste dépasse 30 minutes. La même estimation est recalculée en temps réel dans Paramètres → Mesurer après chaque modification.

---