Il mio connettore è offline

Un connettore normalmente passa a Online entro 30 secondi dall'installazione. Se ciò non accade, o se un connettore precedentemente sano passa a Offline, Degraded o Needs recovery, utilizzare questo runbook.

Cosa significa lo stato

• Offline: il connettore non è attualmente connesso, ma potrebbe recuperarsi autonomamente dopo un'interruzione temporanea della rete o il riavvio del processo.
• Degraded: almeno un percorso runtime non è sano, ma non tutti i percorsi del connettore sono inattivi.
• Needs recovery: il connettore non si trova più in un normale percorso di riconnessione. Trattare come perdita di identità durevole, fallback bootstrap invalido o un altro caso di recupero delimitato. Il connettore non ritenta silenziosamente il token bootstrap originale in questo stato; fallisce in modo chiuso e attende un flusso di recupero esplicito avviato dall'operatore.

Modalità autonoma vs recupero guidato

Il modo in cui il connettore si recupera da un riavvio dipende dalla presenza di archiviazione identità durevole.

Modalità	Postura archiviazione	Risultato runtime	Azione operatore
Modalità autonoma	Durable /data o PAM_AGENT_DATA_DIR è montato e intatto	Il connettore carica il suo bundle di identità all'avvio ed esegue la riconnessione mTLS senza intervento dell'operatore	Nessuno
Recupero guidato	Nessun /data persistente o il volume di identità è stato perso / ricreato vuoto	Il connettore non può riconnettersi normalmente ed entra in needs_recovery preservando la configurazione del connettore nel piano di controllo	Coniare un nuovo token di iscrizione monouso e re-associare il connettore

Il connettore carica il suo bundle di identità all'avvio ed esegue la riconnessione mTLS senza alcuna azione dell'operatore in modalità autonoma. Questo è l'impostazione predefinita per distribuzioni VM, Docker e Kubernetes configurate correttamente. I riavvii, i pod ripianificati e la ricreazione dei contenitori hanno tutti successo automaticamente purché l'archiviazione durevole sopravviva.

Nel recupero guidato, il connettore non dispone di un'identità locale e non può riconnettersi. La configurazione del connettore -- assegnazione organizzazione, ID endpoint e reti consentite -- è conservata nel piano di controllo, ma è richiesta una nuova iscrizione. Questo è lo stato esplicito needs_recovery.

Il ritiro del bootstrap si verifica dopo la prima iscrizione riuscita e il primo heartbeat online confermato. Una volta che il bundle di identità del connettore è persistito nell'archiviazione durevole e il piano di controllo registra quell'heartbeat, il token bootstrap è consumato e ritirato. Tutti i riavvii successivi devono utilizzare l'identità persistita per la riconnessione mTLS. Non esiste alcun percorso -- in entrambe le modalità -- in cui un connettore precedentemente iscritto ritorni silenziosamente al token bootstrap come credenziale di riavvio normale.

Controlli rapidi

1. L'host è attivo? SSH o RDP nella macchina del connettore; confermare che Docker / il servizio nativo è in esecuzione.
   • Docker: docker ps | grep vaultpam-connector — il contenitore dovrebbe essere Up.
   • systemd: systemctl status vaultpam-connector.
2. L'host può raggiungere il piano di controllo? Dalla macchina del connettore:

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

   Se questo fallisce, si ha un problema di rete/DNS/firewall. Le porte 443 (HTTPS del piano di controllo) e facoltativamente 51820/udp (tunnel VPN inverso) devono essere aperte verso l'esterno.
3. Il token di iscrizione è ancora valido? I token scadono dopo 4 ore per impostazione predefinita. Se il connettore non è mai venuto online e il token è scaduto, generarne uno nuovo da Connectors → scegli connettore → Regenerate token.
4. Il connettore ha perso l'archiviazione identità durevole? Un connettore precedentemente associato dovrebbe riavviarsi dall'identità persistita in /data o PAM_AGENT_DATA_DIR.
   • Docker: confermare che il contenitore monta ancora lo stesso volume denominato o il bind mount su /data.
   • Nativo / VM: confermare che il servizio punta ancora allo stesso percorso host durevole e che l'utente del connettore può leggerlo.
   • Kubernetes: confermare che il pod monta ancora il PVC previsto e non è stato ridistribuito su emptyDir o su un altro livello effimero.

Identificare la classe di fallimento

1. Fallimento del bootstrap al primo avvio

Utilizzare questo ramo se il connettore non è mai stato associato con successo.

Segnali comuni:

• il connettore non è mai diventato Online
• i log mostrano scadenza del token, revoca del token, fallimento della convalida CSR o fallimento della fiducia CA
• l'interfaccia utente mostra ancora uno stato di onboarding o attivazione anziché ready

Recupero:

1. Correggere il problema di fiducia, rete o token.
2. Generare un nuovo token di iscrizione se l'originale è scaduto o revocato.
3. Riprovare l'associazione.

2. Fallimento della riconnessione normale

Utilizzare questo ramo se il connettore è stato associato prima e dispone ancora della sua identità durevole.

Segnali comuni:

• Offline temporaneo dopo riavvio, distribuzione o fluttuazione della rete
• attività di avviso cp_tunnel_heartbeat_timeouts_total
• la directory dei dati locali è ancora presente e leggibile

Recupero:

1. Ripristinare la raggiungibilità HTTPS in uscita verso il piano di controllo.
2. Confermare che il connettore dispone ancora del suo bundle di identità locale sull'archiviazione durevole.
3. Riavviare il processo del connettore o il pod una volta.
4. Validare che il connettore torni a Online senza utilizzare un nuovo token di iscrizione.

3. Perdita di identità durevole o fallback bootstrap invalido

Utilizzare questo ramo se il connettore è stato associato prima, ma ora si comporta come un connettore nuovo di zecca.

Segnali comuni:

• l'interfaccia utente o l'API mostra Needs recovery
• i log mostrano 401 ENROLLMENT_TOKEN_INVALID dopo un'associazione precedentemente riuscita
• gli avvisi dell'endpoint di iscrizione 401 aumentano dopo il riavvio
• il mount dell'archiviazione durevole è stato sostituito, rimosso o ricreato vuoto

Recupero:

1. Arrestare il connettore o ridimensionare il pod a zero prima di modificare le credenziali.
2. Tentare di riattaccare prima l'archiviazione durevole originale.
3. Se l'identità originale è scomparsa, trattare come rierogazione controllata:
   • revocare il token bootstrap stantio se esiste ancora
   • coniare un nuovo token di iscrizione monouso dal piano di controllo
   • assicurare che l'archiviazione durevole sia montata correttamente prima di avviare di nuovo
   • associare esattamente una volta con il nuovo token
4. Validare che i riavvii successivi riutilizzino l'identità persistita anziché richiedere un altro token.
5. Confermare che la configurazione del connettore preservata sia ancora presente; se la configurazione è mancante, escalare come problema di distribuzione separato.

Non trattare i tentativi di bootstrap ripetuti come un percorso di riavvio normale.

Log da ispezionare

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

Errori comuni:

Frammento log	Significato	Correzione
x509: certificate signed by unknown authority	L'host non si fida della CA	Importare il bundle di certificati CA (/etc/vaultpam/ca.crt) — vedere il runbook stampato durante l'installazione
connection refused	Rete bloccata	Controllare l'allowlist in uscita del firewall aziendale
enrolment token revoked	Qualcuno ha cliccato Revoke nell'interfaccia utente	Generare un nuovo token
401 ENROLLMENT_TOKEN_INVALID dopo che il connettore è stato già associato una volta	Il connettore ha perso la sua identità persistita e è tornato al bootstrap	Riattaccare la directory dei dati durevole originale se disponibile. Se l'identità è scomparsa, generare un token fresco e associare di nuovo sull'archiviazione durevole

Validazione post-recupero

Dopo qualsiasi correzione:

1. Confermare che il connettore raggiunga Online.
2. Riavviare il connettore ancora una volta.
3. Confermare che si ricollega senza un nuovo token di iscrizione.
4. Confermare che il percorso dell'archiviazione durevole contiene ancora lo stato del connettore dopo il riavvio.
5. Catturare le prove per l'audit:
   • stato del connettore prima e dopo
   • la riga di log che prova il successo della riconnessione o del rinnovo
   • qualsiasi voce di audit endpoint.cert_renewed o gateway.enrollment_failed legata all'incidente
   • il nome dell'avviso e l'intervallo di tempo se il monitoraggio ha attirato

Ancora bloccato

Contattare il supporto e includere: versione del connettore, coda del log, output di curl -v https://<control-plane-host>/healthz.

Articoli correlati

• Pair your first connector
• What is a Connector?