An SSH failure can happen before the connection reaches the board, when no SSH service is listening, or during login. The exact error message is more useful than “SSH does not work.”
This guide assumes a Linux image and an SSH client on your computer. Service availability and account setup depend on the image you installed.
1. Confirm the board’s current address
Use an HDMI terminal or debug UART to run these commands on the board:
ip addr
ip route
Find the address on the interface connected to your network. Do not use the loopback address 127.0.0.1. Interface names vary, so do not assume yours is eth0.
Compare this with the router’s client list. DHCP addresses can change, and an old address may now belong to another device. For initial troubleshooting, put the computer and board on the same ordinary LAN; guest networks may isolate clients.
See ArmSoM’s network setup guide.
2. Connect using your actual account
On your computer, run the following after replacing both placeholders:
ssh USERNAME@BOARD_IP
Use the account documented or created for your exact image. Do not assume that every ArmSoM or third-party image shares a username and password.
3. Read the error before changing settings
| Message | What to investigate |
|---|---|
| Connection timed out | Incorrect address, network isolation, routing, filtering, or an unresponsive board |
| Connection refused | The destination responded with a refusal; check the SSH service, port, and any active rejection rules |
| Permission denied | The SSH server was reached; check the username and allowed authentication method |
| Host identification has changed | Verify the board’s identity through a trusted local connection, especially after reflashing |
These are diagnostic directions, not definitive diagnoses. Do not bypass host-key checking simply to make an error disappear.
4. Collect a useful client log
Run:
ssh -v USERNAME@BOARD_IP
OpenSSH’s -v option prints connection and authentication diagnostics. See the OpenSSH manual.
If you need help, provide the exact error, image filename, network connection type, and whether local login works. Share the relevant verbose output after removing private hostnames, addresses or paths you do not want public. Never post passwords or private keys.
If the board cannot reach a local login prompt, collect a power-on UART log before troubleshooting SSH.