Configuration Reference
The server settings that change what the app's SSH VPN profiles do, what each field of a profile does on the wire, and the settings the app always uses. OpenSSH server builds the server this page refers to; Test results has the case behind each statement.
Every server setting below was tested by changing it on our OpenSSH 9.6 test server and connecting both phones; the case names in the tables are the rows of Test results. Settings this page describes without a case were left as Ubuntu sets them.
Server settings (sshd_config)
sshd reads /etc/ssh/sshd_config and the files in /etc/ssh/sshd_config.d/; for each setting the first value it reads wins, and the lines under a Match line apply only to the users it names. After a change, sshd -t checks the files and systemctl reload ssh applies them to new connections; sessions that are open keep running.
Logins and forwarding
| Setting | What it does for the app | Cases |
|---|---|---|
PasswordAuthentication yes | The app logs in with the profile's Username and Password. A wrong password or a user the server does not have ends with Authentication failed. Check the username and password. A password may hold any character. | ssh-pass-download, ssh-wrong-password, ssh-wrong-user, ssh-special-password |
PasswordAuthentication noKbdInteractiveAuthentication yes | The server takes the password through its keyboard-interactive (PAM) login instead, and the app answers the prompt with the profile's password. | ssh-kbd-interactive-only |
PasswordAuthentication no (and no keyboard-interactive) | No way in with a password: The server does not take a password for this user (it offers: publickey). | ssh-password-login-off |
AllowTcpForwarding local (or yes) | Needed: every connection of the phone is a TCP forwarding through the session. With no (or a PermitOpen that does not allow the destination) the app refuses to connect: The server does not let this user forward TCP connections (AllowTcpForwarding or PermitOpen on the server). | ssh-pass-download, ssh-no-forwarding |
ForceCommand /usr/sbin/nologin, PermitTTY no, a nologin shell | No effect on the app, which never asks for a shell or a terminal. | every connect case |
Keys, ciphers and the host key
| Setting | What it does for the app | Cases |
|---|---|---|
| Ubuntu 24.04's defaults | The app's sessions use curve25519-sha256 for the key exchange, the server's ED25519 host key, and chacha20-poly1305@openssh.com, which carries its own integrity check (sshd's debug log while the iPhone connected). | ssh-pass-download |
KexAlgorithms curve25519-sha256,curve25519-sha256@libssh.orgCiphers chacha20-poly1305@openssh.com,aes256-gcm@openssh.comMACs hmac-sha2-512-etm@openssh.com,hmac-sha2-256-etm@openssh.com | A hardened set: the app connects. | ssh-server-hardened |
Ciphers aes256-gcm@openssh.com,aes128-gcm@openssh.com, Ciphers aes256-ctr,aes128-ctr, Ciphers chacha20-poly1305@openssh.com | Each alone: the app connects. Their download speeds are in Test results. | ssh-server-aes-gcm, ssh-server-aes-ctr, ssh-server-chacha |
Host keys (/etc/ssh/ssh_host_*_key) | The app asks for the server's keys in OpenSSH's order: ED25519 first, then ECDSA, then RSA. A Host Key must be the fingerprint of the key the server shows: the ED25519 one on a server that has it. A fingerprint of another key ends with The server's host key does not match Host Key. The server presented ED25519 SHA256:…. | ssh-hostkey-ed25519, ssh-hostkey-ecdsa-not-shown, ssh-hostkey-rsa-not-shown, ssh-hostkey-wrong, ssh-hostkey-keygen-line |
HostKeyAlgorithms ecdsa-sha2-nistp256, HostKeyAlgorithms rsa-sha2-512,rsa-sha2-256 | A server that shows only that key: its fingerprint is the one to pin. | ssh-server-hostkey-ecdsa, ssh-server-hostkey-rsa, ssh-server-hostkey-ed25519 |
Banner /etc/issue.net | The text before the login; the app logs in all the same. | ssh-server-banner |
Ports and keepalives
| Setting | What it does for the app | Cases |
|---|---|---|
Port 22 | The profile's Port; empty means 22. Ubuntu 24.04 starts sshd from ssh.socket: after a change of Port, run systemctl daemon-reload and systemctl restart ssh.socket. | ssh-port-empty, ssh-port-2222 |
ClientAliveInterval 5ClientAliveCountMax 2 | The server drops a client that does not answer its keepalives. The app answers them while the session is idle, so a quiet VPN stays up. | ssh-server-keepalive-idle |
The UDP relay (hev-socks5-server)
| Setting | What it does for the app | Cases |
|---|---|---|
port: 1080, listen-address: '127.0.0.1' | Where the app reaches the relay through the session; the app always uses this address and port. With UDP Relay on, the phone's UDP leaves from the server's address. | ssh-udp-download |
| The relay not running | With UDP Relay on, the app refuses to connect: 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 off the relay is not needed, and UDP does not get through. | ssh-udp-relay-stopped, ssh-udp-off-relay-stopped, ssh-udp-off-probe |
What each profile field does
| Field | On the wire |
|---|---|
| Server, Port | The TCP connection of the SSH session; a name is looked up on the phone. A name that does not resolve, a port that refuses or does not answer, and a port where another service answers each have their own message (Troubleshooting). |
| Host Key (SHA256) | Compared with the SHA-256 of the key the server shows in the SSH handshake, before the password is sent. |
| UDP Relay (HEV) | On: before the VPN comes up the app opens a channel to the relay and checks that it answers; then each UDP flow is a channel to the relay, which carries its datagrams inside the session's TCP stream. |
| Username, Password | The SSH login, encrypted by the session. |
| Auto Reconnect, Retry Times | When the session ends or breaks, a new SSH session 2 seconds later; Retry Times limits the attempts. |
| Switch to Wi-Fi When Available | A new SSH session over Wi-Fi when it appears. |
| On Sleep | Pause and Off close the session while the device sleeps; Stay keeps it. |
| Log Level | What the connection log shows; no level writes the password. |
What the app always does
- Each TCP connection of the phone becomes an SSH channel (
direct-tcpip) to its destination, opened by the server; the server looks up names, as the app answers the phone's DNS queries itself with placeholder addresses. - Only IPv4 goes through the tunnel.
- The tunnel's MTU is 1400.
- A keepalive every 15 seconds; a session the server has not answered for 50 seconds counts as broken.
- 15 seconds for the TCP connection and 20 for the SSH handshake and the login.
- No proxy: the app connects to the server directly.