ssh-connection-test

# ssh-connection-test

Guide to testing SSH connections with `sshm test`.

## Test a Single Host

```bash
sshm test web
```

Output:
```
  testing web (deploy@example.com:22)...

  ok  connected  (231ms)
```

## Test All Hosts

```bash
sshm test --all
```

Shows a table of all hosts with connection results and timing.

## Connection Result Types

| Result | Meaning |
|---|---|
| `connected` | SSH handshake succeeded |
| `timeout` | No response within 5 seconds |
| `refused` | Port is closed |
| `host not found` | DNS resolution failed |
| `auth failed` | Host reachable but key rejected |
| `unknown error` | Other SSH error |

## Diagnosing Failures

**timeout** - Host may be down, firewall blocking port, or wrong IP. Check: `ping hostname`, `telnet hostname 22`.

**refused** - SSH service not running on that port. Check if port in config matches actual SSH port.

**host not found** - DNS issue. Try using IP address directly: `sshm edit myhost --host 1.2.3.4`.

**auth failed** - Key not accepted. Check: key exists at IdentityFile path, key is in server's authorized_keys.

## How the Test Works

The test spawns `ssh` with:
- `ConnectTimeout=5` to avoid hanging
- `BatchMode=yes` to prevent interactive prompts
- The host's configured user, hostname, and port
- Runs `true` as the command (exits immediately on success)

The test does not create a persistent connection and does not execute any shell commands that could affect the server.

## Notes

- Connection test uses the host's current config (User, HostName, Port, IdentityFile)
- Test respects IdentityFile if set
- Auth failures are distinguished from unreachable hosts
- Timing shown in milliseconds