Mon connecteur est hors ligne

Un connecteur passe normalement à l'état En ligne dans les 30 secondes suivant l'installation. Si ce n'est pas le cas, ou si un connecteur précédemment sain bascule vers Hors ligne, Dégradé ou Nécessite une récupération, utilisez ce guide d'exploitation.

Signification des statuts

• Hors ligne : le connecteur n'est pas connecté actuellement, mais il peut se rétablir de lui-même après une interruption réseau transitoire ou un redémarrage de processus.
• Dégradé : au moins un chemin d'exécution est défaillant, mais ce ne sont pas tous les chemins du connecteur qui sont indisponibles.
• Nécessite une récupération : le connecteur n'est plus dans un chemin de reconnexion normal. Traitez ce cas comme une perte d'identité durable, un repli d'amorçage invalide ou un autre cas de récupération borné. Dans cet état, le connecteur ne réessaie pas silencieusement le jeton d'amorçage d'origine ; il échoue en mode fermé (fail-closed) et attend un flux de récupération explicite initié par un opérateur.

Mode autonome ou récupération guidée

La manière dont le connecteur se rétablit après un redémarrage dépend de la présence d'un stockage d'identité durable.

Mode	Posture de stockage	Résultat d'exécution	Action de l'opérateur
Mode autonome	Un /data durable ou PAM_AGENT_DATA_DIR est monté et intact	Le connecteur charge son bundle d'identité au démarrage et effectue une reconnexion mTLS sans intervention de l'opérateur	Aucune
Récupération guidée	Aucun /data persistant ou le volume d'identité a été perdu / recréé vide	Le connecteur ne peut pas se reconnecter normalement et entre dans l'état needs_recovery tout en conservant la configuration du connecteur dans le plan de contrôle	Émettre un nouveau jeton d'enrôlement à usage unique et réappairer le connecteur

En mode autonome, le connecteur charge son bundle d'identité au démarrage et effectue une reconnexion mTLS sans aucune action de l'opérateur. C'est le comportement par défaut pour les déploiements VM, Docker et Kubernetes correctement configurés. Les redémarrages, les pods replanifiés et la recréation de conteneurs réussissent tous automatiquement tant que le stockage durable subsiste.

En récupération guidée, le connecteur n'a pas d'identité locale et ne peut pas se reconnecter. La configuration du connecteur -- affectation à l'organisation, ID de point de terminaison et réseaux autorisés -- est conservée dans le plan de contrôle, mais un nouvel enrôlement est requis. Il s'agit de l'état explicite needs_recovery.

Le retrait de l'amorçage intervient après le premier enrôlement réussi et le premier battement de cœur (heartbeat) en ligne confirmé. Une fois que le bundle d'identité du connecteur est persisté sur le stockage durable et que le plan de contrôle enregistre ce battement de cœur, le jeton d'amorçage est consommé et retiré. Tous les redémarrages ultérieurs doivent utiliser l'identité persistée pour la reconnexion mTLS. Il n'existe aucun chemin -- dans l'un ou l'autre mode -- où un connecteur précédemment enrôlé reviendrait silencieusement au jeton d'amorçage comme identifiant de redémarrage normal.

Vérifications rapides

1. L'hôte est-il actif ? Connectez-vous à la machine du connecteur en SSH ou RDP ; vérifiez que Docker / le service natif est en cours d'exécution.
   • Docker : docker ps | grep vaultpam-connector — le conteneur doit être Up.
   • systemd : systemctl status vaultpam-connector.
2. L'hôte peut-il atteindre le plan de contrôle ? Depuis la machine du connecteur :

   curl -v https://<control-plane-host>/healthz

   Si cela échoue, vous avez un problème de réseau / DNS / pare-feu. Les ports 443 (HTTPS du plan de contrôle) et, en option, 51820/udp (tunnel inverse VPN) doivent être ouverts en sortie.
3. Le jeton d'enrôlement est-il toujours valide ? Les jetons expirent au bout de 4 heures par défaut. Si le connecteur n'est jamais passé en ligne et que le jeton a expiré, générez-en un nouveau depuis Connecteurs → sélectionner le connecteur → Régénérer le jeton.
4. Le connecteur a-t-il perdu son stockage d'identité durable ? Un connecteur précédemment appairé devrait redémarrer à partir de l'identité persistée sous /data ou PAM_AGENT_DATA_DIR.
   • Docker : vérifiez que le conteneur monte toujours le même volume nommé ou le même bind mount sur /data.
   • Natif / VM : vérifiez que le service pointe toujours vers le même chemin d'hôte durable et que l'utilisateur du connecteur peut le lire.
   • Kubernetes : vérifiez que le pod monte toujours le PVC attendu et qu'il n'a pas été redéployé sur un emptyDir ou une autre couche éphémère.

Identifier la classe de défaillance

1. Échec d'amorçage au premier démarrage

Utilisez cette branche si le connecteur ne s'est jamais appairé avec succès.

Signaux courants :

• le connecteur n'est jamais passé Online
• les journaux indiquent une expiration du jeton, une révocation du jeton, un échec de validation de la CSR ou un échec de confiance dans la CA
• l'interface affiche toujours un état d'intégration ou d'activation plutôt que ready

Récupération :

1. Corrigez le problème de confiance, de réseau ou de jeton.
2. Générez un nouveau jeton d'enrôlement si l'original a expiré ou a été révoqué.
3. Réessayez l'appairage.

2. Échec de reconnexion normale

Utilisez cette branche si le connecteur s'est déjà appairé auparavant et possède toujours son identité durable.

Signaux courants :

• état Offline temporaire après un redémarrage, un déploiement ou une instabilité réseau
• activité d'alerte cp_tunnel_heartbeat_timeouts_total
• le répertoire de données local est toujours présent et lisible

Récupération :

1. Rétablissez l'accessibilité HTTPS sortante vers le plan de contrôle.
2. Vérifiez que le connecteur possède toujours son bundle d'identité local sur le stockage durable.
3. Redémarrez une fois le processus ou le pod du connecteur.
4. Vérifiez que le connecteur revient à l'état Online sans utiliser de nouveau jeton d'enrôlement.

3. Perte d'identité durable ou repli d'amorçage invalide

Utilisez cette branche si le connecteur s'est déjà appairé auparavant, mais se comporte désormais comme un tout nouveau connecteur.

Signaux courants :

• l'interface ou l'API affiche Needs recovery
• les journaux indiquent 401 ENROLLMENT_TOKEN_INVALID après un appairage précédemment réussi
• les alertes 401 du point de terminaison d'enrôlement augmentent fortement après un redémarrage
• le montage de stockage durable a été remplacé, supprimé ou recréé vide

Récupération :

1. Arrêtez le connecteur ou réduisez le pod à zéro avant de modifier les identifiants.
2. Essayez d'abord de rattacher le stockage durable d'origine.
3. Si l'identité d'origine est perdue, traitez ce cas comme un reprovisionnement contrôlé :
   • révoquez le jeton d'amorçage périmé s'il existe encore
   • émettez un nouveau jeton d'enrôlement à usage unique depuis le plan de contrôle
   • assurez-vous que le stockage durable est correctement monté avant de redémarrer
   • appairez exactement une fois avec le nouveau jeton
4. Vérifiez que les redémarrages ultérieurs réutilisent l'identité persistée au lieu de demander un autre jeton.
5. Confirmez que la configuration de connecteur conservée est toujours présente ; si la configuration est manquante, faites remonter le problème comme une question de déploiement distincte.

Ne traitez pas des tentatives d'amorçage répétées comme un chemin de redémarrage normal.

Journaux à inspecter

• Docker : docker logs -n 200 vaultpam-connector.
• Natif : /var/log/vaultpam/connector.log (Linux) ou %PROGRAMDATA%\VaultPAM\connector.log (Windows).

Erreurs courantes :

Fragment de journal	Signification	Correction
x509: certificate signed by unknown authority	L'hôte ne fait pas confiance à la CA	Importez le bundle de certificats de la CA (/etc/vaultpam/ca.crt) — voir le guide d'exploitation affiché lors de l'installation
connection refused	Réseau bloqué	Vérifiez la liste d'autorisation en sortie du pare-feu d'entreprise
enrolment token revoked	Quelqu'un a cliqué sur Révoquer dans l'interface	Générez un nouveau jeton
401 ENROLLMENT_TOKEN_INVALID après que le connecteur a déjà été appairé une fois	Le connecteur a perdu son identité persistée et est revenu à l'amorçage	Rattachez le répertoire de données durable d'origine s'il est disponible. Si l'identité est perdue, générez un nouveau jeton et réappairez sur un stockage durable

Validation après récupération

Après toute correction :

1. Confirmez que le connecteur atteint l'état Online.
2. Redémarrez le connecteur une fois de plus.
3. Confirmez qu'il se reconnecte sans nouveau jeton d'enrôlement.
4. Confirmez que le chemin de stockage durable contient toujours l'état du connecteur après le redémarrage.
5. Capturez les preuves pour l'audit :
   • le statut du connecteur avant et après
   • la ligne de journal qui prouve que la reconnexion ou le renouvellement a réussi
   • toutes les entrées d'audit endpoint.cert_renewed ou gateway.enrollment_failed liées à l'incident
   • le nom de l'alerte et la fenêtre temporelle si la surveillance s'est déclenchée

Toujours bloqué

Contactez le support et joignez : la version du connecteur, la fin des journaux (log tail), la sortie de curl -v https://<control-plane-host>/healthz.

Articles connexes

• Appairer votre premier connecteur
• Qu'est-ce qu'un connecteur ?