Mijn connector is offline

Een connector schakelt normaal gesproken binnen 30 seconden na installatie naar Online. Als dit niet gebeurt, of als een eerder gezonde connector naar Offline, Degraded of Needs recovery valt, gebruik deze runbook.

Wat de status betekent

• Offline: de connector is momenteel niet verbonden, maar kan zichzelf herstellen na een voorbijgaande netwerkonderbreking of procesherstart.
• Degraded: ten minste één runtime-pad is niet in orde, maar niet elk connectorpad is onderbroken.
• Needs recovery: de connector bevindt zich niet langer in een normaal herconnectpad. Behandel dit als duurzaam identiteitsverlies, ongeldige bootstrap-fallback of een ander begrensd herstelensgeval. De connector probeert de originele bootstrap-token in deze toestand niet achtergrond opnieuw uit; deze faalt dicht en wacht op een expliciet door de operator geïnitieerde herstellingsstroom.

Autonoom modus versus geleide herstel

Hoe de connector herstelt na een herstart, hangt af van of duurzame identiteitsopslag aanwezig is.

Modus	Opslagstatus	Runtime-resultaat	Actie operator
Autonoom modus	Duurzame /data of PAM_AGENT_DATA_DIR is gemonteerd en intact	De connector laadt zijn identiteitsbundel bij opstarten en voert mTLS-herverbinding uit zonder operator-inmenging	Geen
Geleide herstel	Geen persistent /data of de identiteitsvolume is verloren gegaan/opnieuw leeg gemaakt	De connector kan niet normaal herverbinden en gaat naar needs_recovery terwijl de connectorconfiguatie in het controleplan behouden blijft	Mint een nieuwe eenmalige inschrijvingstoken en koppel de connector opnieuw

De connector laadt zijn identiteitsbundel bij opstarten en voert mTLS-herverbinding uit zonder enige operator-actie in autonoom modus. Dit is de standaard voor correct geconfigureerde VM-, Docker- en Kubernetes-implementaties. Herstarts, opnieuw geplande pods en containerrecreatie zijn allemaal automatisch succesvol zolang de duurzame opslag aanwezig blijft.

Bij geleide herstel heeft de connector geen lokale identiteit en kan niet herverbinden. De connectorconfiguatie -- organisatietoewijzing, eindpunt-ID en toegestane netwerken -- blijft behouden in het controleplan, maar een nieuwe inschrijving is vereist. Dit is de expliciete toestand needs_recovery.

Bootstrap-pensionering vindt plaats na de eerste succesvolle inschrijving en de eerste bevestigde online heartbeat. Zodra de connector-identiteitsbundel is behouden voor duurzame opslag en het controleplan die heartbeat registreert, wordt de bootstrap-token verbruikt en met pensioen gegaan. Alle daaropvolgende herstarts moeten de behouden identiteit voor mTLS-herverbinding gebruiken. Er is geen pad -- in geen van beide modus -- waar een eerder ingeschreven connector achtergrond naar de bootstrap-token terugvalt als normale herstartreferentie.

Snelle controles

1. Is de host actief? SSH of RDP naar de connectormachine; bevestig dat Docker/de native service wordt uitgevoerd.
   • Docker: docker ps | grep vaultpam-connector — de container moet Up zijn.
   • systemd: systemctl status vaultpam-connector.
2. Kan de host het controleplan bereiken? Van de connectormachine:

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

   Als dit mislukt, hebt u een netwerk-/DNS-/firewallprobleem. Poorten 443 (control plane HTTPS) en optioneel 51820/udp (VPN reverse tunnel) moeten open staan voor uitgaand verkeer.
3. Is de inschrijvingstoken nog geldig? Tokens verlopen standaard na 4 uur. Als de connector nog nooit online is geweest en de token is verlopen, genereer dan een nieuwe uit Connectors → selecteer connector → Regenerate token.
4. Heeft de connector zijn duurzame identiteitsopslag verloren? Een eerder gekoppelde connector moet opnieuw opstarten vanuit de behouden identiteit onder /data of PAM_AGENT_DATA_DIR.
   • Docker: bevestig dat de container nog steeds hetzelfde benoemde volume of bind mount op /data monteert.
   • Native/VM: bevestig dat de service nog steeds naar hetzelfde duurzame hostpad verwijst en dat de connector-gebruiker het kan lezen.
   • Kubernetes: bevestig dat de pod nog steeds de verwachte PVC monteert en niet opnieuw is geïmplementeerd op emptyDir of een ander efemeer niveau.

Identificeer de foutklasse

1. Bootstrap-fout bij eerste opstarten

Gebruik deze tak als de connector nooit succesvol is gekoppeld.

Veelvoorkomende signalen:

• de connector werd nooit Online
• logboeken tonen token-vervaldatum, token-intrekking, CSR-validatiefout of CA-vertrouensfout
• de UI toont nog een inboarding- of activeringsstatus in plaats van ready

Herstel:

1. Los het vertrouwens-, netwerk- of tokenprobleem op.
2. Genereer een frisse inschrijvingstoken als de origineel is verlopen of ingetrokken.
3. Herpairing.

2. Normale herverbindingsfout

Gebruik deze tak als de connector eerder is gekoppeld en nog steeds zijn duurzame identiteit heeft.

Veelvoorkomende signalen:

• voorbijgaande Offline na herboot, implementatie of netwerkflap
• cp_tunnel_heartbeat_timeouts_total waarschuwingsactiviteit
• de lokale gegevensmap is nog steeds aanwezig en leesbaar

Herstel:

1. Herstel de uitgaande HTTPS-bereikbaarheid naar het controleplan.
2. Bevestig dat de connector nog steeds zijn lokale identiteitsbundel op duurzame opslag heeft.
3. Start het connectorproces of pod eenmaal opnieuw.
4. Valideer dat de connector naar Online terugkeert zonder een nieuwe inschrijvingstoken te gebruiken.

3. Duurzaam identiteitsverlies of ongeldige bootstrap-fallback

Gebruik deze tak als de connector eerder is gekoppeld, maar zich nu gedraagt als een gloednieuwe connector.

Veelvoorkomende signalen:

• UI of API toont Needs recovery
• logboeken tonen 401 ENROLLMENT_TOKEN_INVALID na een eerder succesvolle koppeling
• inschrijvingseindpunt 401 waarschuwingen pieken na herstart
• de duurzame opslagmount is vervangen, verwijderd of opnieuw leeg gemaakt

Herstel:

1. Stop de connector of schaal de pod naar nul voordat u referenties wijzigt.
2. Probeer eerst de originele duurzame opslag opnieuw vast te stellen.
3. Als de originele identiteit weg is, behandel dit als gecontroleerde herprovisie:
   • trek de achtergebleven bootstrap-token in als deze nog bestaat
   • mint een frisse eenmalige inschrijvingstoken van het controleplan
   • zorg ervoor dat de duurzame opslag correct is gemonteerd voordat u opnieuw start
   • koppel exact eenmaal met de nieuwe token
4. Valideer dat daaropvolgende herstarts de behouden identiteit opnieuw gebruiken in plaats van om een ander token te vragen.
5. Bevestig dat bewaarde connectorconfiguatie nog aanwezig is; als configuratie ontbreekt, escaleer dit als een afzonderlijk implementatieprobleem.

Behandel herhaalde bootstrap-herpoging niet als een normaal herstarpad.

Logboeken om te controleren

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

Veelvoorkomende fouten:

Logboekfragment	Betekenis	Oplossing
x509: certificate signed by unknown authority	Host vertrouwt de CA niet	Importeer de CA-certificaatbundel (/etc/vaultpam/ca.crt) — zie de runbook afgedrukt tijdens installatie
connection refused	Netwerk geblokkeerd	Controleer de ausgaande allowlist van de bedrijfsfirewall
enrolment token revoked	Iemand heeft Revoke in de UI geklikt	Genereer een nieuwe token
401 ENROLLMENT_TOKEN_INVALID nadat de connector al eenmaal is gekoppeld	De connector verloor zijn behouden identiteit en viel terug naar bootstrap	Verbind de originele duurzame gegevensmap opnieuw als deze beschikbaar is. Als de identiteit weg is, genereer dan een frisse token en koppel opnieuw op duurzame opslag

Post-herstellingsvalidatie

Na elke fix:

1. Bevestig dat de connector Online bereikt.
2. Start de connector nog eenmaal opnieuw.
3. Bevestig dat deze opnieuw verbindt zonder een frisse inschrijvingstoken.
4. Bevestig dat het duurzame opslagpad nog steeds de connectortoestand na de herstart bevat.
5. Leg het bewijs vast voor audit:
   • connectorbetatus voor en na
   • de logboekregel die bewijst dat herverbinding of vernieuwing succesvol was
   • alle endpoint.cert_renewed of gateway.enrollment_failed auditinggegevens gekoppeld aan het incident
   • de waarschuwingnaam en het tijdvenster als bewaking werd geactiveerd

Nog steeds vast

Neem contact op met ondersteuning en voeg toe: connectorversie, logboekstert, uitvoer van curl -v https://<control-plane-host>/healthz.

Gerelateerde artikelen

• Koppel uw eerste connector
• Wat is een Connector?