Mój konektor jest offline

Konektor zwykle przełącza się na Online w ciągu 30 sekund od instalacji. Jeśli tak się nie stanie lub jeśli wcześniej sprawny konektor przejdzie w stan Offline, Degraded lub Needs recovery, skorzystaj z tego runbooka.

Co oznacza status

• Offline: konektor nie jest obecnie połączony, ale może samodzielnie odzyskać łączność po przejściowej przerwie w sieci lub ponownym uruchomieniu procesu.
• Degraded: co najmniej jedna ścieżka wykonawcza jest niesprawna, ale nie wszystkie ścieżki konektora są niedostępne.
• Needs recovery: konektor nie znajduje się już na normalnej ścieżce ponownego połączenia. Potraktuj to jako trwałą utratę tożsamości, nieprawidłowy fallback bootstrapu lub inny ograniczony przypadek odzyskiwania. W tym stanie konektor nie ponawia po cichu prób z oryginalnym tokenem bootstrapu; zawodzi w sposób zamknięty (fail closed) i czeka na wyraźny przepływ odzyskiwania zainicjowany przez operatora.

Tryb autonomiczny a odzyskiwanie z asystą

Sposób, w jaki konektor odzyskuje łączność po ponownym uruchomieniu, zależy od tego, czy dostępna jest trwała pamięć tożsamości.

Tryb	Stan pamięci masowej	Zachowanie wykonawcze	Działanie operatora
Tryb autonomiczny	Trwały /data lub PAM_AGENT_DATA_DIR jest zamontowany i nienaruszony	Konektor ładuje swój pakiet tożsamości przy starcie i wykonuje ponowne połączenie mTLS bez interwencji operatora	Brak
Odzyskiwanie z asystą	Brak trwałego /data lub wolumen tożsamości został utracony / odtworzony jako pusty	Konektor nie może normalnie połączyć się ponownie i wchodzi w stan needs_recovery, zachowując konfigurację konektora w control plane	Wygeneruj nowy jednorazowy token rejestracji i ponownie sparuj konektor

W trybie autonomicznym konektor ładuje swój pakiet tożsamości przy starcie i wykonuje ponowne połączenie mTLS bez żadnego działania operatora. Jest to wartość domyślna dla poprawnie skonfigurowanych wdrożeń na maszynach wirtualnych (VM), w Dockerze oraz w Kubernetes. Ponowne uruchomienia, ponownie zaplanowane pody i odtworzenie kontenerów — wszystko to powiedzie się automatycznie, dopóki trwała pamięć masowa przetrwa.

W odzyskiwaniu z asystą konektor nie ma lokalnej tożsamości i nie może połączyć się ponownie. Konfiguracja konektora — przypisanie do organizacji, identyfikator punktu końcowego oraz dozwolone sieci — jest zachowana w control plane, ale wymagana jest nowa rejestracja. Jest to wyraźny stan needs_recovery.

Wycofanie bootstrapu następuje po pierwszej udanej rejestracji i pierwszym potwierdzonym sygnale heartbeat online. Po zapisaniu pakietu tożsamości konektora w trwałej pamięci masowej i zarejestrowaniu tego sygnału heartbeat przez control plane token bootstrapu zostaje zużyty i wycofany. Wszystkie kolejne ponowne uruchomienia muszą korzystać z zachowanej tożsamości do ponownego połączenia mTLS. Nie istnieje żadna ścieżka — w żadnym z trybów — w której wcześniej zarejestrowany konektor po cichu wracałby do tokenu bootstrapu jako normalnego poświadczenia przy ponownym uruchomieniu.

Szybkie kontrole

1. Czy host działa? Połącz się przez SSH lub RDP z maszyną konektora; potwierdź, że Docker / usługa natywna jest uruchomiona.
   • Docker: docker ps | grep vaultpam-connector — kontener powinien być w stanie Up.
   • systemd: systemctl status vaultpam-connector.
2. Czy host może osiągnąć control plane? Z maszyny konektora:

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

   Jeśli to się nie powiedzie, masz problem z siecią/DNS/zaporą. Porty 443 (HTTPS control plane) oraz opcjonalnie 51820/udp (odwrotny tunel VPN) muszą być otwarte wychodząco.
3. Czy token rejestracji jest nadal ważny? Tokeny domyślnie wygasają po 4 godzinach. Jeśli konektor nigdy nie był online, a token wygasł, wygeneruj nowy w Connectors → wybierz konektor → Regenerate token.
4. Czy konektor utracił swoją trwałą pamięć tożsamości? Wcześniej sparowany konektor powinien uruchamiać się ponownie z zachowanej tożsamości w /data lub PAM_AGENT_DATA_DIR.
   • Docker: potwierdź, że kontener nadal montuje ten sam nazwany wolumen lub bind mount w /data.
   • Natywnie / VM: potwierdź, że usługa nadal wskazuje na tę samą trwałą ścieżkę hosta i że użytkownik konektora może ją odczytać.
   • Kubernetes: potwierdź, że pod nadal montuje oczekiwany PVC i nie został ponownie wdrożony na emptyDir lub inną warstwę efemeryczną.

Zidentyfikuj klasę awarii

1. Niepowodzenie bootstrapu przy pierwszym uruchomieniu

Użyj tej gałęzi, jeśli konektor nigdy nie sparował się pomyślnie.

Typowe sygnały:

• konektor nigdy nie osiągnął stanu Online
• logi pokazują wygaśnięcie tokenu, odwołanie tokenu, niepowodzenie walidacji CSR lub niepowodzenie zaufania CA
• interfejs nadal pokazuje stan onboardingu lub aktywacji zamiast ready

Odzyskiwanie:

1. Napraw problem z zaufaniem, siecią lub tokenem.
2. Wygeneruj nowy token rejestracji, jeśli oryginalny wygasł lub został odwołany.
3. Ponów parowanie.

2. Niepowodzenie normalnego ponownego połączenia

Użyj tej gałęzi, jeśli konektor był wcześniej sparowany i nadal ma swoją trwałą tożsamość.

Typowe sygnały:

• tymczasowy stan Offline po ponownym uruchomieniu, wdrożeniu lub krótkotrwałej przerwie w sieci
• aktywność alertu cp_tunnel_heartbeat_timeouts_total
• lokalny katalog danych jest nadal obecny i możliwy do odczytania

Odzyskiwanie:

1. Przywróć wychodzącą osiągalność HTTPS do control plane.
2. Potwierdź, że konektor nadal ma swój lokalny pakiet tożsamości w trwałej pamięci masowej.
3. Uruchom ponownie proces lub pod konektora jeden raz.
4. Zweryfikuj, że konektor powraca do stanu Online bez użycia nowego tokenu rejestracji.

3. Utrata trwałej tożsamości lub nieprawidłowy fallback bootstrapu

Użyj tej gałęzi, jeśli konektor był wcześniej sparowany, ale teraz zachowuje się jak całkowicie nowy konektor.

Typowe sygnały:

• interfejs lub API pokazuje Needs recovery
• logi pokazują 401 ENROLLMENT_TOKEN_INVALID po wcześniej udanym parowaniu
• alerty 401 z punktu końcowego rejestracji gwałtownie rosną po ponownym uruchomieniu
• punkt montowania trwałej pamięci masowej został zastąpiony, usunięty lub odtworzony jako pusty

Odzyskiwanie:

1. Zatrzymaj konektor lub przeskaluj pod do zera przed zmianą poświadczeń.
2. Najpierw spróbuj ponownie podłączyć oryginalną trwałą pamięć masową.
3. Jeśli oryginalna tożsamość zniknęła, potraktuj to jako kontrolowane ponowne udostępnienie:
   • odwołaj nieaktualny token bootstrapu, jeśli nadal istnieje
   • wygeneruj nowy jednorazowy token rejestracji z control plane
   • upewnij się, że trwała pamięć masowa jest poprawnie zamontowana, zanim uruchomisz ponownie
   • sparuj dokładnie raz z nowym tokenem
4. Zweryfikuj, że kolejne ponowne uruchomienia ponownie wykorzystują zachowaną tożsamość zamiast prosić o kolejny token.
5. Potwierdź, że zachowana konfiguracja konektora jest nadal obecna; jeśli konfiguracji brakuje, eskaluj to jako osobny problem wdrożeniowy.

Nie traktuj wielokrotnych prób bootstrapu jako normalnej ścieżki ponownego uruchomienia.

Logi do sprawdzenia

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

Typowe błędy:

Fragment logu	Znaczenie	Naprawa
x509: certificate signed by unknown authority	Host nie ufa CA	Zaimportuj pakiet certyfikatu CA (/etc/vaultpam/ca.crt) — zobacz runbook wydrukowany podczas instalacji
connection refused	Sieć zablokowana	Sprawdź listę dozwolonych połączeń wychodzących w firmowej zaporze
enrolment token revoked	Ktoś kliknął Revoke w interfejsie	Wygeneruj nowy token
401 ENROLLMENT_TOKEN_INVALID po tym, jak konektor był już raz sparowany	Konektor utracił swoją zachowaną tożsamość i wrócił do bootstrapu	Ponownie podłącz oryginalny trwały katalog danych, jeśli jest dostępny. Jeśli tożsamość zniknęła, wygeneruj nowy token i sparuj ponownie na trwałej pamięci masowej

Walidacja po odzyskaniu

Po każdej naprawie:

1. Potwierdź, że konektor osiąga stan Online.
2. Uruchom konektor ponownie jeszcze raz.
3. Potwierdź, że łączy się ponownie bez nowego tokenu rejestracji.
4. Potwierdź, że ścieżka trwałej pamięci masowej nadal zawiera stan konektora po ponownym uruchomieniu.
5. Zbierz materiał dowodowy na potrzeby audytu:
   • status konektora przed i po
   • linię logu, która dowodzi, że ponowne połączenie lub odnowienie się powiodło
   • wszelkie wpisy audytu endpoint.cert_renewed lub gateway.enrollment_failed powiązane z incydentem
   • nazwę alertu i okno czasowe, jeśli monitoring zadziałał

Nadal utknąłeś

Skontaktuj się z pomocą techniczną i dołącz: wersję konektora, końcówkę logu, dane wyjściowe curl -v https://<control-plane-host>/healthz.

Powiązane artykuły

• Sparuj swój pierwszy konektor
• Czym jest konektor?