Skip to content
    OpafraDocs

    Connection problems

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

    View as MarkdownOpen in ClaudeOpen in ChatGPT

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

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

    Next steps#