Troubleshooting

What the app's messages for an SSH VPN profile mean, what to do about each, and where to look on the server.

Where this page comes from

Each message below is the one the app showed in the case named beside it, on the iPhone and on Android, against our OpenSSH test server; see Test results.

Messages while connecting

The app shows these in the Connection Failed alert, and writes them to its log after closing with reason:.

MessageWhat it meansWhat to do
Cannot find the server. Check the Server field and the network.The name in Server did not resolve (ssh-host-unknown).Check the name for typos, and that it resolves on the phone's network. An IPv4 address works as well as a name.
The server refused the connection on port 2223. Check the Port field.The server answered, but nothing listens on that port (ssh-port-closed).Check Port: the server's SSH port, 22 unless its Port setting says otherwise. On the server, ss -tlnp | grep sshd shows the ports sshd listens on.
The server did not answer on port 2222. Check the Server and Port fields and the network.Nothing answered within 15 seconds: a firewall on the way drops the connection, or the address is wrong (ssh-port-no-answer).Check Server and Port, and that the server's firewall lets the port in (ufw status).
SSH handshake failed (Failed getting banner). Check that Port is the server's SSH port.Something answered on that port, but not an SSH server: in our case a web server (ssh-port-other-service). The words in brackets are libssh2's.Use the server's SSH port.
The server's host key does not match Host Key. The server presented ED25519 SHA256:….The fingerprint in Host Key is not the one of the key the server showed. The message names that key. We saw it for a fingerprint of the server's ECDSA or RSA key on a server that has an ED25519 key, and for a fingerprint of no key of the server (ssh-hostkey-ecdsa-not-shown, ssh-hostkey-rsa-not-shown, ssh-hostkey-wrong).Read the fingerprint of the server's ED25519 key with ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub on the server and compare it with the one in the message. If they differ, the phone did not reach your server: do not connect. If the server's keys were made again, enter the new fingerprint.
Authentication failed. Check the username and password.The server refused the login: a wrong password, or a user it does not have (ssh-wrong-password, ssh-wrong-user).Check the Username and Password. On the server, passwd <user> sets the password again, and journalctl -u ssh shows Failed password for or Invalid user.
The server does not take a password for this user (it offers: publickey).The server allows only key logins for the user: PasswordAuthentication no and no keyboard-interactive login (ssh-password-login-off). The methods in brackets are the ones the server offers.The app logs in with a password. Set PasswordAuthentication yes for the VPN's users, as OpenSSH server does in their Match Group block.
The server does not let this user forward TCP connections (AllowTcpForwarding or PermitOpen on the server).The login worked, but the server refuses to forward TCP for the user: AllowTcpForwarding no (ssh-no-forwarding), or a PermitOpen that does not allow the destination. The app checks this before it calls itself connected.Set AllowTcpForwarding local (or yes) for the user, and no PermitOpen line.
The UDP relay (HEV) is unavailable on the server. Turn UDP Relay off, or ask the administrator to install or start it.With UDP Relay on, the app found no relay at 127.0.0.1:1080 on the server (ssh-udp-relay-stopped).On the server: systemctl status hev-socks5-server, and ss -tlnp | grep 1080. Or turn UDP Relay off: everything but UDP still works.
Could not connect after 2 attempts. (The server refused the connection on port 2222. Check the Port field.)With Auto Reconnect on and Retry Times set, the first connection failed that many times; the reason follows in brackets (ssh-retry-before-connect).The reason in brackets says what to fix.

Messages after the VPN was up

These end a VPN that was connected, when Auto Reconnect is off or out of attempts. The app keeps the reason; its log names it after closing with reason:. With Auto Reconnect on, the app opens a new SSH session instead, and the connections that were open start again.

MessageWhat it meansWhat to do
The server closed the connection (auto reconnect is off).The server ended the session, for example when an administrator ended the user's sessions (ssh-life-server-ends-no-reconnect).Turn Auto Reconnect on: the app then logs in again.
The connection was reset (auto reconnect is off).The TCP connection to the server broke (ssh-life-reset-no-reconnect).Turn Auto Reconnect on.
Could not reconnect after 2 attempts. (The server refused the connection on port 2222. Check the Port field.)The connection broke, and the server did not answer within the attempts that Retry Times allows (ssh-life-retry-exhausted).Leave Retry Times empty to keep trying, and check the server.
The connection was closed while the device slept.On Sleep Off closed the connection when the phone slept, and Auto Reconnect is off, so nothing connected it again (ssh-life-sleep-modes).Use On Sleep Pause or Stay, or turn Auto Reconnect on.

A connection that goes quiet

When the network path to the server dies without a reset, nothing tells the phone. The app sends a keepalive every 15 seconds and counts the session as broken at the latest when the server has answered nothing for 50 seconds; Auto Reconnect then opens a new one as soon as the server can be reached. In ssh-life-silent-drop-reconnect the iPhone tried a new connection 26 seconds after the path went dead, and Android 51 seconds after. An idle VPN stays up: the app answers the server's own keepalives, so even a server with a short ClientAliveInterval keeps the session (ssh-server-keepalive-idle).

UDP does not work

Looking at the server

journalctl -u ssh --since "10 min ago"
ss -tnp state established '( sport = :22 )'
systemctl status hev-socks5-server

The journal shows each login (Accepted password for, or Accepted keyboard-interactive/pam for), each refused one, and the reason a session ended. ss lists the open SSH connections with the address each comes from. pkill -u <user> ends a user's sessions.

The app's log

At every Log Level the log shows the server and port the app connects to, the server's host key with its fingerprint, the login, and the reason a session ended. Expert adds the transfer counters, every 5 seconds while traffic moves; Debug adds a line for each connection through the tunnel and, on iPhone, the packet engine's own lines. No level writes the password. Setting up the app says where the log is.