# Connection problems

The connection check names the stage that failed. Find your symptom here for what it means and what to change.

Source: https://opafra.com/docs/troubleshooting/connections

---

The connection check walks five stages in order and stops at the first hard failure, so
the result names the thing that actually broke rather than saying the host is down.

Find the symptom below. Opafra shows the same guidance in the interface when a check
fails.

## Hostname does not resolve

DNS has no record for the name. Check the spelling, or use the IP address instead.

If the name is internal only, Opafra needs a resolver that can see your private zone.

```bash
dig +short <host>
```

## DNS lookup timed out

The resolver did not answer in time, which usually means a private or split-horizon zone
Opafra cannot reach. Use the IP address, or expose the zone to the resolver Opafra uses.

## Port closed on the host

The host answered and actively refused the connection, so nothing is listening on that
port. Confirm sshd is running, and check the port if SSH is not on 22.

```bash
sudo systemctl status ssh
```

## No answer on the SSH port

Packets are being dropped rather than refused, which points at a firewall or a security
group rather than at the host. Allow inbound TCP on the SSH port from Opafra's egress
addresses.

```bash
nc -vz -w 5 <host> <port>
```

## Host is not reachable

There is no route to the host. If it sits in a private subnet, set the server it is
reached through in **Reachable via**. Otherwise confirm the machine is running and has a
route from Opafra.

## Bastion could not be reached

This server is reached through a bastion, and the bastion itself did not answer.

> **Note**
>
> The target may be perfectly healthy. What failed is the path to it. Test the bastion on
> its own first, then retry this host.

## Bastion chain is not usable

The path loops back on itself, is more than three hops deep, or names a server that no
longer exists. Open the server and pick a bastion that is reachable directly.

This is a configuration problem rather than a network one, so retrying will not help.

## Authentication rejected

The host refused the credentials. Check the username matches an account on the server, and
that the credential you selected is the one that account accepts.

```bash
ssh -v -p <port> <user>@<host> true
```

## SSH key not accepted

The server did not accept this key. Add the matching public key to the account's
`authorized_keys`, and make sure the home directory is not group writable, which sshd
refuses on principle.

```bash
ssh-copy-id -p <port> -i <key>.pub <user>@<host>
```

## Host key does not match

The key this host presents differs from the one recorded for it.

> **Warning**
>
> This happens routinely after a rebuild or re-image, and it also happens when traffic is
> being intercepted. Those are indistinguishable from Opafra's side, which is why the
> connection is refused rather than accepted silently. Verify the new fingerprint out of
> band before accepting it.

```bash
ssh-keyscan -p <port> <host> | ssh-keygen -lf -
```

## Sudo needs a password

Login worked, but `sudo` prompts for a password, so privileged steps cannot run
unattended. A run is not an interactive session and cannot answer the prompt.

This is a **warning, not a failure**. The server is registered and usable, and plans that
never elevate work fine. Grant passwordless sudo only if your plans need it, and prefer
scoping it to the specific commands over `NOPASSWD: ALL`.

## Could not read host facts

The session opened but host details could not be gathered. Usually a restricted shell, a
forced command in `authorized_keys`, or a missing core utility.

Also a warning rather than a failure. Give the account a normal login shell if you want
facts, which conditions can then reference as `{{ facts.x }}`.

## Check timed out

The host did not finish in time. The whole check is capped at 30 seconds, so this means
something is genuinely slow rather than merely busy.

Retry once. If it persists, look for a saturated link or a login shell that waits on
something at startup.

## Nothing above matches

Run the connection by hand from a machine that can reach the host, and compare the host,
port, username and key with what you entered. The verbose output names the exact step that
failed.

```bash
ssh -v -p <port> <user>@<host> true
```

## Next steps

- [Registering servers](/docs/inventory/servers) for the five stages in context
- [Run problems](/docs/troubleshooting/runs) for failures after the connection works