Mi sesión SSH no se inicia

Las sesiones SSH enrutadas a través de VaultPAM dependen de que el connector alcance el host de destino en el puerto TCP 22 (o un puerto SSH personalizado). Cuando una sesión no se abre, casi siempre hay cinco causas raíz responsables. Trabaje a través de ellas en el orden indicado aquí — los problemas del connector y de red son mucho más comunes que los problemas de credenciales o claves.

Síntomas

• Hacer clic en Launch Session muestra un indicador de carga y luego un banner de error.
• La ventana de sesión se abre brevemente y luego se cierra con un mensaje como:
  • SSH connection refused
  • Host unreachable
  • Authentication failed
  • Host key verification failed
  • Permission denied (publickey)
• La sesión nunca aparece en la vista Active Sessions.

Causas

1. El connector está desconectado

El connector que enruta al host de destino debe estar Online. Si está Offline, Degraded o Needs recovery, todos los intentos de sesión a través de él fallarán.

Verificación: Abra Connectors en la barra lateral. Busque el connector asignado al Safe de destino. Confirme que la columna de estado muestra Online.

Solución: Siga el manual My connector is offline.

2. El puerto 22 está bloqueado entre el connector y el host de destino

La máquina del connector debe poder alcanzar el host de destino en el puerto SSH (por defecto 22). Una regla de cortafuegos, grupo de seguridad o cortafuegos basado en host (p. ej., ufw, Windows Firewall) puede estar bloqueándolo.

Verificación: Desde la máquina del connector, ejecute:

nc -zv <target-host> 22

o

ssh -v <username>@<target-host>

Una respuesta Connection refused o timeout confirma un bloqueo de red.

Solución: Actualice el cortafuegos o grupo de seguridad para permitir TCP 22 desde la IP del connector hacia el destino. Si el host de destino utiliza un puerto SSH no estándar, verifique que el puerto correcto esté configurado en la configuración del Safe: Safes → seleccionar Safe → Edit → Connection settings → Port.

3. Nombre de usuario incorrecto

El nombre de usuario utilizado para la conexión SSH debe existir en el host de destino y debe coincidir exactamente (los nombres de usuario de Linux distinguen entre mayúsculas y minúsculas).

Verificación: En Safes → seleccionar Safe → Edit → Credentials, confirme que el nombre de usuario es correcto. Errores comunes: root vs ubuntu, admin vs administrator, o un valor por defecto residual de una plantilla.

Solución: Actualice el registro de credencial para usar el nombre de usuario correcto.

4. Discrepancia de clave de host

VaultPAM registra la clave de host SSH en la primera conexión. Si el host de destino fue reconstruido y sus claves de servidor SSH cambiaron (p. ej., después de una reinstalación del SO), VaultPAM se negará a conectar para proteger contra ataques de intermediario.

Síntomas: El mensaje de error contiene Host key verification failed o REMOTE HOST IDENTIFICATION HAS CHANGED.

Verificación: Abra Safes → seleccionar Safe → Edit → Connection settings. Si hay una huella digital de clave de host almacenada visible, compárela con la clave de host actual ejecutando en la máquina de destino:

ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

Solución: Si el cambio de clave es esperado (reconstrucción legítima), haga clic en Reset host key en la configuración de conexión del Safe. VaultPAM aceptará la nueva clave en el siguiente intento de conexión y la almacenará para verificaciones futuras.

5. Clave SSH faltante o rechazada

Si el Safe está configurado para usar autenticación de clave pública en lugar de checkout de contraseña, el connector debe tener acceso a una clave privada que esté autorizada en el host de destino.

Verificación: En Safes → seleccionar Safe → Edit → Credentials, confirme que el tipo de credencial está establecido en SSH Key y que hay una clave adjunta. Verifique que la clave pública correspondiente esté listada en ~/.ssh/authorized_keys en el host de destino para el usuario configurado.

Solución: Cargue la clave privada correcta al registro de credencial, o agregue la clave pública del connector a authorized_keys en el host de destino.

Pasos de resolución

1. Abra Connectors en la barra lateral y confirme que el connector asignado al Safe de destino muestra Online. Si no es así, siga My connector is offline antes de continuar.
2. Desde la máquina del connector, ejecute nc -zv <target-host> 22 para confirmar que el puerto TCP 22 es accesible. Si está bloqueado, actualice la regla de cortafuegos o grupo de seguridad relevante.
3. Abra Safes → seleccionar Safe → Edit → Credentials y verifique el nombre de usuario. Corríjalo si no coincide con la cuenta del host de destino.
4. Si el error menciona una discrepancia de clave de host, abra Safes → seleccionar Safe → Edit → Connection settings y haga clic en Reset host key, luego reintente la sesión.
5. Si el Safe utiliza autenticación de clave SSH, confirme que una clave privada está adjunta al registro de credencial y que la clave pública coincidente está en ~/.ssh/authorized_keys en el host de destino.
6. Después de cada cambio, reintente la sesión haciendo clic en Launch Session en el Safe.

Ruta de escalamiento

Si ha trabajado a través de las cinco causas y la sesión aún falla:

1. Anote el mensaje de error exacto mostrado en el banner de sesión.
2. En la máquina del connector, recopile las últimas 100 líneas del registro del connector:
   • Docker: docker logs -n 100 vaultpam-connector
   • systemd: journalctl -u vaultpam-connector -n 100
3. Ejecute nc -zv <target-host> 22 desde la máquina del connector e incluya la salida.
4. Abra un ticket de soporte con: nombre del connector, host de destino (enmascarado si es sensible), mensaje de error exacto, salida del registro y resultado de nc.

Artículos relacionados

• My connector is offline
• Rotate a credential