Przejdź do głównej zawartości
Wersja: najnowsza

My SSH session fails to launch

SSH sessions routed through VaultPAM rely on the connector reaching the target host on TCP port 22 (or a custom SSH port). When a session fails to open, one of five root causes is almost always responsible. Work through them in the order listed here — connector and network problems are far more common than credential or key issues.

Symptoms​

  • Clicking Launch Session shows a spinner and then an error banner.
  • The session window opens briefly and then closes with a message such as:
    • SSH connection refused
    • Host unreachable
    • Authentication failed
    • Host key verification failed
    • Permission denied (publickey)
  • The session never appears in the Active Sessions view.

Causes​

1. Connector is offline​

The connector that routes to the target host must be Online. If it is Offline, Degraded, or Needs recovery, every session attempt through it will fail.

Check: Open Connectors in the sidebar. Find the connector assigned to the target Safe. Confirm the status column shows Online.

Fix: Follow the My connector is offline runbook.

2. Port 22 is blocked between the connector and the target​

The connector machine must be able to reach the target host on the SSH port (default 22). A firewall rule, security group, or host-based firewall (e.g., ufw, Windows Firewall) may be blocking it.

Check: From the connector machine, run:

nc -zv <target-host> 22

or

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

A Connection refused or timeout response confirms a network block.

Fix: Update the firewall or security group to allow TCP 22 from the connector's IP to the target. If the target uses a non-standard SSH port, verify the correct port is configured in the Safe settings: Safes → pick Safe → Edit → Connection settings → Port.

3. Wrong username​

The username used for the SSH connection must exist on the target host and must match exactly (Linux usernames are case-sensitive).

Check: In Safes → pick Safe → Edit → Credentials, confirm the username is correct. Common mistakes: root vs ubuntu, admin vs administrator, or a leftover default from a template.

Fix: Update the credential record to use the correct username.

4. Host key mismatch​

VaultPAM records the SSH host key on first connection. If the target host was rebuilt, its SSH server keys changed (e.g., after OS reinstall), VaultPAM will refuse to connect to protect against man-in-the-middle attacks.

Symptoms: The error message contains Host key verification failed or REMOTE HOST IDENTIFICATION HAS CHANGED.

Check: Open Safes → pick Safe → Edit → Connection settings. If a stored host key fingerprint is visible, compare it against the current host key by running on the target machine:

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

Fix: If the key change is expected (legitimate rebuild), click Reset host key in the Safe connection settings. VaultPAM will accept the new key on the next connection attempt and store it for future verification.

5. Missing or rejected SSH key​

If the Safe is configured to use public-key authentication rather than password checkout, the connector must have access to a private key that is authorised on the target host.

Check: In Safes → pick Safe → Edit → Credentials, confirm the credential type is set to SSH Key and a key is attached. Verify the corresponding public key is listed in ~/.ssh/authorized_keys on the target host for the configured user.

Fix: Upload the correct private key to the credential record, or add the connector's public key to authorized_keys on the target host.

Resolution steps​

  1. Open Connectors in the sidebar and confirm the connector assigned to the target Safe shows Online. If not, follow My connector is offline before continuing.
  2. From the connector machine, run nc -zv <target-host> 22 to confirm TCP port 22 is reachable. If blocked, update the relevant firewall or security group rule.
  3. Open Safes → pick Safe → Edit → Credentials and verify the username. Correct it if it does not match the target host account.
  4. If the error mentions a host key mismatch, open Safes → pick Safe → Edit → Connection settings and click Reset host key, then retry the session.
  5. If the Safe uses SSH key authentication, confirm a private key is attached to the credential record and the matching public key is in ~/.ssh/authorized_keys on the target host.
  6. After each change, retry the session by clicking Launch Session on the Safe.

Escalation path​

If you have worked through all five causes and the session still fails:

  1. Note the exact error message shown in the session banner.
  2. On the connector machine, collect the last 100 lines of the connector log:
    • Docker: docker logs -n 100 vaultpam-connector
    • systemd: journalctl -u vaultpam-connector -n 100
  3. Run nc -zv <target-host> 22 from the connector machine and include the output.
  4. Open a support ticket with: connector name, target host (masked if sensitive), exact error message, log output, and nc result.