Mein Connector ist offline

Ein Connector wechselt normalerweise innerhalb von 30 Sekunden nach der Installation auf Online. Falls dies nicht geschieht oder ein zuvor fehlerfreier Connector auf Offline, Degraded oder Needs recovery wechselt, verwenden Sie dieses Runbook.

Was der Status bedeutet

• Offline: Der Connector ist derzeit nicht verbunden, kann sich aber nach einer vorübergehenden Netzwerkunterbrechung oder einem Prozessneustart von selbst wiederherstellen.
• Degraded: Mindestens ein Laufzeitpfad ist fehlerhaft, aber nicht jeder Connector-Pfad ist ausgefallen.
• Needs recovery: Der Connector befindet sich nicht mehr in einem normalen Wiederverbindungspfad. Behandeln Sie dies als Verlust der dauerhaften Identität, ungültigen Bootstrap-Fallback oder einen anderen abgegrenzten Wiederherstellungsfall. Der Connector versucht in diesem Zustand nicht stillschweigend, das ursprüngliche Bootstrap-Token erneut zu verwenden; er schlägt fehl und schließt ab (fail closed) und wartet auf einen ausdrücklich vom Operator initiierten Wiederherstellungsablauf.

Autonomer Modus vs. geführte Wiederherstellung

Wie sich der Connector von einem Neustart erholt, hängt davon ab, ob ein dauerhafter Identitätsspeicher vorhanden ist.

Modus	Speicherzustand	Laufzeitergebnis	Operator-Aktion
Autonomer Modus	Dauerhaftes /data oder PAM_AGENT_DATA_DIR ist gemountet und intakt	Der Connector lädt sein Identitätsbündel beim Start und führt die mTLS-Wiederverbindung ohne Eingriff des Operators durch	Keine
Geführte Wiederherstellung	Kein persistentes /data oder das Identitäts-Volume ging verloren / wurde leer neu erstellt	Der Connector kann sich nicht normal wiederverbinden und wechselt in needs_recovery, während die Connector-Konfiguration in der Control Plane erhalten bleibt	Ein neues Einmal-Enrollment-Token erzeugen und den Connector erneut koppeln

Der Connector lädt im autonomen Modus sein Identitätsbündel beim Start und führt die mTLS-Wiederverbindung ohne jegliche Operator-Aktion durch. Dies ist die Standardeinstellung für korrekt konfigurierte VM-, Docker- und Kubernetes-Bereitstellungen. Neustarts, neu geplante Pods und das erneute Erstellen von Containern gelingen alle automatisch, solange der dauerhafte Speicher erhalten bleibt.

Bei der geführten Wiederherstellung verfügt der Connector über keine lokale Identität und kann sich nicht wiederverbinden. Die Connector-Konfiguration -- Organisationszuordnung, Endpoint-ID und zulässige Netzwerke -- bleibt in der Control Plane erhalten, es ist jedoch ein neues Enrollment erforderlich. Dies ist der ausdrückliche Zustand needs_recovery.

Die Bootstrap-Stilllegung erfolgt nach dem ersten erfolgreichen Enrollment und dem ersten bestätigten Online-Heartbeat. Sobald das Identitätsbündel des Connectors im dauerhaften Speicher persistiert ist und die Control Plane diesen Heartbeat erfasst hat, wird das Bootstrap-Token verbraucht und stillgelegt. Alle nachfolgenden Neustarts müssen die persistierte Identität für die mTLS-Wiederverbindung verwenden. Es gibt -- in keinem der beiden Modi -- einen Pfad, in dem ein zuvor registrierter Connector stillschweigend als normaler Neustart-Berechtigungsnachweis auf das Bootstrap-Token zurückgreift.

Schnellprüfungen

1. Ist der Host aktiv? Stellen Sie per SSH oder RDP eine Verbindung zum Connector-Rechner her; bestätigen Sie, dass Docker / der native Dienst läuft.
   • Docker: docker ps | grep vaultpam-connector — der Container sollte Up sein.
   • systemd: systemctl status vaultpam-connector.
2. Kann der Host die Control Plane erreichen? Vom Connector-Rechner aus:

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

   Falls dies fehlschlägt, liegt ein Netzwerk-/DNS-/Firewall-Problem vor. Die Ports 443 (Control Plane HTTPS) und optional 51820/udp (VPN-Reverse-Tunnel) müssen ausgehend geöffnet sein.
3. Ist das Enrollment-Token noch gültig? Tokens laufen standardmäßig nach 4 Stunden ab. Falls der Connector nie online gegangen ist und das Token abgelaufen ist, erzeugen Sie ein neues über Connectors → Connector auswählen → Token neu erzeugen.
4. Hat der Connector seinen dauerhaften Identitätsspeicher verloren? Ein zuvor gekoppelter Connector sollte aus der persistierten Identität unter /data oder PAM_AGENT_DATA_DIR neu starten.
   • Docker: Bestätigen Sie, dass der Container weiterhin dasselbe benannte Volume oder denselben Bind-Mount unter /data mountet.
   • Nativ / VM: Bestätigen Sie, dass der Dienst weiterhin auf denselben dauerhaften Host-Pfad verweist und dass der Connector-Benutzer ihn lesen kann.
   • Kubernetes: Bestätigen Sie, dass der Pod weiterhin den erwarteten PVC mountet und nicht auf emptyDir oder eine andere flüchtige Schicht neu bereitgestellt wurde.

Die Fehlerklasse identifizieren

1. First-Boot-Bootstrap-Fehler

Verwenden Sie diesen Zweig, falls der Connector nie erfolgreich gekoppelt wurde.

Häufige Anzeichen:

• der Connector wurde nie Online
• Logs zeigen Token-Ablauf, Token-Widerruf, CSR-Validierungsfehler oder CA-Vertrauensfehler
• die Benutzeroberfläche zeigt weiterhin einen Onboarding- oder Aktivierungszustand statt ready

Wiederherstellung:

1. Beheben Sie das Vertrauens-, Netzwerk- oder Token-Problem.
2. Erzeugen Sie ein neues Enrollment-Token, falls das ursprüngliche abgelaufen ist oder widerrufen wurde.
3. Wiederholen Sie die Kopplung.

2. Normaler Wiederverbindungsfehler

Verwenden Sie diesen Zweig, falls der Connector zuvor gekoppelt wurde und noch über seine dauerhafte Identität verfügt.

Häufige Anzeichen:

• vorübergehendes Offline nach einem Neustart, Deploy oder Netzwerk-Flap
• Aktivität beim Alarm cp_tunnel_heartbeat_timeouts_total
• das lokale Datenverzeichnis ist weiterhin vorhanden und lesbar

Wiederherstellung:

1. Stellen Sie die ausgehende HTTPS-Erreichbarkeit zur Control Plane wieder her.
2. Bestätigen Sie, dass der Connector sein lokales Identitätsbündel weiterhin im dauerhaften Speicher hat.
3. Starten Sie den Connector-Prozess oder Pod einmal neu.
4. Validieren Sie, dass der Connector ohne Verwendung eines neuen Enrollment-Tokens zu Online zurückkehrt.

3. Verlust der dauerhaften Identität oder ungültiger Bootstrap-Fallback

Verwenden Sie diesen Zweig, falls der Connector zuvor gekoppelt wurde, sich nun aber wie ein brandneuer Connector verhält.

Häufige Anzeichen:

• die Benutzeroberfläche oder API zeigt Needs recovery
• Logs zeigen 401 ENROLLMENT_TOKEN_INVALID nach einer zuvor erfolgreichen Kopplung
• Alarme über 401 am Enrollment-Endpoint steigen nach dem Neustart sprunghaft an
• der dauerhafte Speicher-Mount wurde ersetzt, entfernt oder leer neu erstellt

Wiederherstellung:

1. Stoppen Sie den Connector oder skalieren Sie den Pod auf null, bevor Sie Berechtigungsnachweise ändern.
2. Versuchen Sie zunächst, den ursprünglichen dauerhaften Speicher erneut anzuhängen.
3. Falls die ursprüngliche Identität verloren ist, behandeln Sie dies als kontrollierte Neubereitstellung:
   • widerrufen Sie das veraltete Bootstrap-Token, falls es noch existiert
   • erzeugen Sie ein neues Einmal-Enrollment-Token aus der Control Plane
   • stellen Sie sicher, dass der dauerhafte Speicher korrekt gemountet ist, bevor Sie erneut starten
   • koppeln Sie genau einmal mit dem neuen Token
4. Validieren Sie, dass nachfolgende Neustarts die persistierte Identität wiederverwenden, anstatt ein weiteres Token anzufordern.
5. Bestätigen Sie, dass die erhaltene Connector-Konfiguration weiterhin vorhanden ist; falls die Konfiguration fehlt, eskalieren Sie dies als separates Bereitstellungsproblem.

Behandeln Sie wiederholte Bootstrap-Versuche nicht als normalen Neustart-Pfad.

Zu prüfende Logs

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

Häufige Fehler:

Log-Fragment	Bedeutung	Behebung
x509: certificate signed by unknown authority	Der Host vertraut der CA nicht	Importieren Sie das CA-Zertifikatsbündel (/etc/vaultpam/ca.crt) — siehe das während der Installation ausgegebene Runbook
connection refused	Netzwerk blockiert	Prüfen Sie die ausgehende Allowlist der Unternehmens-Firewall
enrolment token revoked	Jemand hat Revoke in der Benutzeroberfläche angeklickt	Erzeugen Sie ein neues Token
401 ENROLLMENT_TOKEN_INVALID, nachdem der Connector bereits einmal gekoppelt war	Der Connector hat seine persistierte Identität verloren und ist auf Bootstrap zurückgefallen	Hängen Sie das ursprüngliche dauerhafte Datenverzeichnis erneut an, falls verfügbar. Falls die Identität verloren ist, erzeugen Sie ein neues Token und koppeln Sie erneut auf dauerhaftem Speicher

Validierung nach der Wiederherstellung

Nach jeder Behebung:

1. Bestätigen Sie, dass der Connector Online erreicht.
2. Starten Sie den Connector noch einmal neu.
3. Bestätigen Sie, dass er sich ohne ein neues Enrollment-Token wiederverbindet.
4. Bestätigen Sie, dass der dauerhafte Speicherpfad nach dem Neustart weiterhin den Connector-Zustand enthält.
5. Erfassen Sie die Nachweise für die Prüfung:
   • Connector-Status vor und nach der Behebung
   • die Log-Zeile, die belegt, dass die Wiederverbindung oder Erneuerung erfolgreich war
   • alle endpoint.cert_renewed- oder gateway.enrollment_failed-Audit-Einträge, die mit dem Vorfall verbunden sind
   • der Alarmname und das Zeitfenster, falls die Überwachung ausgelöst hat

Immer noch festgefahren

Wenden Sie sich an den Support und geben Sie an: Connector-Version, Log-Auszug, Ausgabe von curl -v https://<control-plane-host>/healthz.

Verwandte Artikel

• Koppeln Sie Ihren ersten Connector
• Was ist ein Connector?