SSH guides
Answers to the problems you meet when you work on servers over SSH, with commands you can copy. They are written for OpenSSH, so most of them apply whatever client you use.
Error messages
What each message means and how to fix it.
- SSH tunnel: "bind: Address already in use" and "remote port forwarding failed"
Fix bind Address already in use, channel_setup_fwd_listener and remote port forwarding failed. Find what holds the port and make your tunnel fail clearly.
- "channel 3: open failed: administratively prohibited: open failed"
channel open failed: administratively prohibited means sshd or authorized_keys forbids this forward. Check AllowTcpForwarding, PermitOpen and restrict.
- client_loop: send disconnect: Broken pipe: keep SSH from dropping
Fix "client_loop: send disconnect: Broken pipe" and "packet_write_wait": set ServerAliveInterval, understand NAT timeouts, and when to use tmux instead.
- ssh: connect to host port 22: Connection refused
What "ssh: connect to host port 22: Connection refused" means and how to find the cause: sshd stopped, wrong port, listen address or a firewall rule.
- "kex_exchange_identification: read: Connection reset by peer"
kex_exchange_identification: Connection reset by peer or Connection closed by remote host. Check penalties, MaxStartups, TCP wrappers, firewalls and tunnels.
- ssh: connect to host port 22: Operation timed out / Connection timed out
Why SSH says "Operation timed out" or "Connection timed out": firewalls, security groups, routing or a wrong address, and how to find which one it is.
- "Could not open a connection to your authentication agent": how to fix it
Fix Could not open a connection to your authentication agent: start ssh-agent with eval, repair a stale SSH_AUTH_SOCK, or set up the agent on Windows.
- "ssh: Could not resolve hostname": causes and fixes
Fix ssh: Could not resolve hostname, nodename nor servname provided or Name or service not known: find the typo, the missing alias, the port or the DNS issue.
- How to debug an SSH connection
Debug SSH step by step: read ssh -v output line by line, check the real settings with ssh -G, and see the server's reasons with sshd -d and sshd -T.
- "git@github.com: Permission denied (publickey)": how to fix it
Fix git@github.com: Permission denied (publickey) and Could not read from remote repository. Test with ssh -T, then check the key, the agent and the account.
- WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! What to do
What "REMOTE HOST IDENTIFICATION HAS CHANGED" means, how to tell a rebuild from an attack, check the new fingerprint out of band, and use ssh-keygen -R.
- "Host key verification failed" in SSH, scripts and CI
Why SSH prints Host key verification failed, how to tell an unknown host from a changed key, and the safe way to fix it in scripts, cron and CI.
- Load key: "invalid format" or "error in libcrypto"
Fix Load key invalid format and error in libcrypto: line endings, missing final newline, public key used by mistake, PPK file, or a damaged CI secret.
- What is known_hosts, and how do you verify an SSH host fingerprint?
What the SSH known_hosts file is, its format and hashed entries, how to verify a host fingerprint, plus ssh-keyscan, accept-new, UpdateHostKeys and SSHFP.
- SSH "no matching key exchange method found" or "no matching host key type found": how to fix it
Fix "no matching key exchange method found", "no matching host key type found" and "no matching cipher found" for one old host, safely, with ssh config.
- "sign_and_send_pubkey: no mutual signature supported": how to fix it
sign_and_send_pubkey: no mutual signature supported means your RSA key needs SHA-1 for an old server. Check it, then fix it safely for that one host.
- "ssh: connect to host port 22: No route to host"
ssh: connect to host port 22: No route to host. Tell a machine that is down from a firewall rule or a broken route, with a command for each cause.
- "Permission denied, please try again." with the right password
SSH says Permission denied, please try again. Find out if it is the password, the user name, root login rules, a locked account or AllowUsers.
- "WARNING: connection is not using a post-quantum key exchange algorithm": what it means
OpenSSH 10.1 and later warn when a connection is not using a post-quantum key exchange algorithm. What it means, how to check the server and how to fix it.
- "Pseudo-terminal will not be allocated because stdin is not a terminal": meaning and fix
Why SSH prints Pseudo-terminal will not be allocated because stdin is not a terminal, and when to use -T, -t, -tt or a command to make it go away.
- SFTP: "subsystem request failed on channel 0" and "Connection closed"
sftp or scp says subsystem request failed on channel 0, then Connection closed. The server has no Subsystem sftp line. How to check, fix and work around it.
- SSH "Too many authentication failures": how to fix it
Fix "Too many authentication failures" in SSH: your agent offers too many keys before the right one. Use IdentitiesOnly and IdentityFile for each host.
- "Error opening terminal" and "unknown terminal type" over SSH
Fix Error opening terminal, 'xterm-256color': unknown terminal type and similar messages. Copy the terminfo entry to the server, or set a common TERM.
- WARNING: UNPROTECTED PRIVATE KEY FILE: how to fix bad permissions
Fix the SSH error "UNPROTECTED PRIVATE KEY FILE" and "bad permissions" with chmod 600, plus the server side checks on ~/.ssh and StrictModes.
Keys and login
Create keys, log in without passwords and fix login failures.
- The authorized_keys file explained
How the SSH authorized_keys file works: line format, options, the permissions sshd insists on, AuthorizedKeysFile, and which line wins when a key appears twice.
- How to convert a .ppk key to OpenSSH, and back
Convert a .ppk key to OpenSSH format with one command, and an OpenSSH key to .ppk. Commands for both directions, passphrases and PPK version 3.
- How to disable password login for SSH
Turn off SSH password login without locking yourself out: drop-in files that override sshd_config, KbdInteractive, UsePAM, sshd -T, and reloading safely.
- How to use a YubiKey or FIDO2 key with SSH (ed25519-sk)
Create an ed25519-sk SSH key on a YubiKey or other FIDO2 key: resident keys, verify-required, the server version you need, and the macOS built-in ssh problem.
- How to generate an ed25519 SSH key
Generate an ed25519 SSH key with ssh-keygen, add a passphrase, copy the public key to a server or GitHub and test the login. For macOS, Linux and Windows.
- How to add an SSH key to GitHub
Add an SSH key to your GitHub account: generate it, paste the public key in settings, check the host fingerprint with ssh -T, and switch a repo to SSH.
- How to fix "Permission denied (publickey)" in SSH
Fix SSH Permission denied (publickey): see which key ssh -v offers, read the server log, then install the key or fix the user, permissions or old RSA settings.
- How to recover an SSH public key from the private key
Lost your .pub file? Run ssh-keygen -y to get the public key back from the private key, and check whether a .pub file really belongs to a private key.
- RSA vs ed25519 SSH keys: which should you use?
Use ed25519 for new SSH keys, RSA only for systems that need it. Security level, key sizes, compatibility and how to reach old servers, with tested commands.
- How to add an SSH key to ssh-agent and the macOS Keychain
Stop typing your SSH key passphrase on a Mac: UseKeychain, AddKeysToAgent, ssh-add --apple-use-keychain, IdentitiesOnly, and what happens after a restart.
- SSH certificate authentication explained
Set up SSH certificates with ssh-keygen -s: a CA, TrustedUserCAKeys, principals, validity, host certificates, @cert-authority and revoking a certificate.
- How to use the same SSH keys on several computers
Use SSH on a laptop, a desktop and a phone: one key per device in authorized_keys, or one key copied safely. Commands, risks and what to do when a device is lost.
Configuration and many servers
Make connections short to type and easy to keep in order.
- How to import your SSH config into an SSH config manager
Get ~/.ssh/config ready to import: list every host, Include files too, check each one with ssh -G, export them to CSV and bring keys and known_hosts along.
- How to manage many SSH servers
Keep many SSH servers in order: naming, Host patterns, Include per project, one key per purpose, an inventory, hashed known_hosts, and when Ansible fits.
- How to use multiple GitHub accounts with SSH
Use two GitHub accounts on one machine: one key each, Host aliases in ~/.ssh/config, IdentitiesOnly, and includeIf so each folder commits with the right email.
- How to save frequently used terminal commands (SSH snippets)
Keep the commands you run over SSH: a longer shell history, Ctrl-R with tags, aliases and functions, RemoteCommand per host, and what never to save.
- The SSH config file, with examples
How ~/.ssh/config works, with examples: Host patterns, why the first value wins, Include, Match, and ssh -G to see the settings ssh will really use.
- SSH multiplexing with ControlMaster and ControlPersist
Reuse one SSH connection for many sessions with ControlMaster, ControlPath and ControlPersist. Check it with -O check, close it with -O exit, know the limits.
Tunnels and jump hosts
Reach what is behind a server, safely.
- How to keep an SSH tunnel alive with autossh and systemd
A permanent SSH tunnel with autossh and a systemd unit using Restart=always, ServerAliveInterval and ExitOnForwardFailure, plus a dedicated, restricted key.
- How to connect to PostgreSQL or MySQL through an SSH tunnel
Reach a private PostgreSQL or MySQL database through an SSH tunnel: exact commands, ports, bind addresses, TLS checks, and a tunnel-only user with PermitOpen.
- Jump host vs bastion host: what is the difference?
Jump host vs bastion host: what each term means, how ProxyJump and ProxyCommand pass through them, and what turns a jump host into a real bastion.
- How to use ProxyJump and a jump host in SSH
Reach private servers through a jump host with ssh -J and ProxyJump: multiple hops, why it is safer than agent forwarding, and ProxyCommand for old versions.
- How to set up a reverse SSH tunnel behind NAT
Reach a machine behind NAT by running ssh -R from it to a server with a public address. Tested examples, GatewayPorts, and how to keep it private.
- How to set up an SSH bastion host
Set up an SSH bastion that forwards only to chosen servers: sshd config with Match, AllowTcpForwarding, PermitOpen and ForceCommand, then ProxyJump and logs.
- How to use SSH as a SOCKS proxy
Turn any SSH server into a SOCKS proxy with ssh -D 1080. Test it with curl, set up a browser, keep DNS off your local network, and keep the port private.
- SSH tunnel manager: save, start and stop port forwards
Save SSH tunnels in ~/.ssh/config with LocalForward, RemoteForward and DynamicForward, start them with ssh -f -N and stop them cleanly with ssh -O exit.
- SSH tunnels explained: local, remote and dynamic port forwarding
SSH port forwarding with tested examples: local -L, remote -R and dynamic -D tunnels, several ports, jump hosts, ssh config, GatewayPorts and common errors.
- How to SSH to a server without a public IP or behind CGNAT
Four ways to reach a machine with no public IPv4 address or behind CGNAT: a VPN or overlay network, a reverse tunnel, IPv6, and router port forwarding.
Securing a server
Reduce what an attacker can try, and what a mistake can break.
- SSH agent forwarding risks, and what to use instead
What ssh -A really exposes: root on the remote host can use your forwarded agent socket while you are connected. How ProxyJump and ssh-add -c reduce the risk.
- How to avoid running commands on the wrong server
Make production look different with a red prompt, a tmux status bar and a terminal color. Plus rm guards, dry runs and bracketed paste, and their limits.
- How to change the SSH port without locking yourself out
Change the SSH port in a safe order: firewall, SELinux, sshd_config, ssh.socket on recent Ubuntu, then test before closing port 22. And what it protects.
- How to check SSH login attempts on Linux
See failed and successful SSH logins with journalctl, auth.log, /var/log/secure, last, lastb and who. What each log line means and which ones to worry about.
- How to disable root login over SSH
Set PermitRootLogin no without locking yourself out: what each value does, why a drop-in file can override your change, and how to check with sshd -T.
- How to set up fail2ban for SSH
Set up fail2ban for SSH: jail.local, the sshd jail, bantime, findtime, maxretry, the systemd backend, checking status and unbanning, and what it does not stop.
- How to harden sshd_config: a checklist you can test
Harden sshd_config step by step: root login, passwords, AllowUsers, forwarding and algorithms, with sshd -t and sshd -T checks that keep you from a lockout.
- How to prevent accidental rm -rf on Linux servers
Protect a Linux server from an accidental rm -rf: rm -I and --preserve-root=all, safe-rm, guards in scripts, chattr +i, a trash, snapshots and recovery.
- How to restrict an SSH key to one command or address
Limit an SSH key with restrict, command=, from= and permitopen= in authorized_keys. Includes SSH_ORIGINAL_COMMAND, a wrapper script and gaps we found.
- How to revoke an SSH key when someone leaves
Find a departing person's SSH key by fingerprint, remove it, block it with RevokedKeys and a KRL, end open sessions, and use short-lived certificates.
- How to share SSH access without sharing your private key
Give teammates SSH access the right way: an account or key per person, expiry dates, short-lived certificates, clean removal, and terminal sharing with tmux.
- How to add two-factor authentication to SSH with TOTP
Require an SSH key plus a TOTP code with libpam-google-authenticator and AuthenticationMethods on Debian or Ubuntu, and keep a way back in if it goes wrong.
- How to use sudo over SSH without leaking your password
A password typed at a sudo prompt over ssh -t is encrypted. What leaks is echo pass | sudo -S. Safe ways to run sudo remotely, with NOPASSWD rules and visudo.
- How to allow SSH in ufw without locking yourself out
Allow SSH in ufw before enabling it: allow, limit, a custom port, one IP only, and a timed safety net so a mistake does not cut you off from your server.
SSH on each system
Turn SSH on and set it up on the system you have.
- How to create a user with SSH access and sudo
Create a Linux user who can log in with an SSH key and use sudo: adduser, the sudo or wheel group, and the exact permissions for .ssh and authorized_keys.
- How to enable SSH on a Mac
Turn on Remote Login on macOS in System Settings or with systemsetup, limit who can log in, and fix the Full Disk Access error that systemsetup shows.
- How to enable SSH on a Raspberry Pi
Turn on SSH on a Raspberry Pi with Imager, raspi-config, the desktop or a file on the SD card, with headless setup and how to find the address.
- How to enable SSH on Ubuntu
Install openssh-server on Ubuntu, start it, open the firewall and test the login. Includes why ssh.service can look inactive while SSH works on recent releases.
- How to generate an SSH key on Windows
Generate an SSH key on Windows with ssh-keygen in PowerShell, start the ssh-agent service to type the passphrase once, and copy the public key.
- How to install OpenSSH Server on Windows 11
Install OpenSSH Server on Windows 11 with PowerShell: Add-WindowsCapability, the sshd service, the firewall rule and administrators_authorized_keys.
- Serial console on a Mac with screen and /dev/tty.usbserial
Open a serial console on a Mac: find the /dev/cu.usbserial port, connect with screen or cu at the right speed, set parity and flow control, and exit screen.
- ssh-copy-id on Windows: the PowerShell command that works
Windows OpenSSH has no ssh-copy-id. This PowerShell one-liner does the same job for Linux servers, plus a separate method for Windows servers.
- How to SSH into a Docker container
Open a shell in a Docker container with docker exec, locally or on a remote host over SSH. Fixes for common errors, and when sshd in a container makes sense.
- telnet: command not found on Mac? How to use Telnet on macOS
Why macOS has no telnet command, how to test a port with nc instead, how to install telnet with Homebrew, and when switches and routers still need it.
Sessions and tmux
Keep work alive and control your sessions.
- How to keep an SSH session alive after disconnect with tmux
Run tmux on the server and your work survives a dropped SSH connection. Start, detach, attach, list and kill sessions, plus nohup and systemd-run alternatives.
- Mosh vs SSH: what is the difference
Mosh keeps a terminal alive when your network changes, over UDP ports 60000 to 61000. How it differs from SSH, how to install it, and what it cannot do.
- How to run a command on multiple servers over SSH
Run one command on many servers over SSH: a loop, parallel jobs with xargs and GNU parallel, parallel-ssh, tmux synchronize-panes, and a safe way to roll out.
- How to run a command over SSH
Run remote commands with ssh user@server 'command'. Quoting rules, heredocs, exit codes, why ssh in a while loop stops after one host, and when -n and -t help.
- How to kill a frozen SSH session: escape sequences
Press Enter, then ~ and . to close a frozen SSH session. The full list of escape sequences, ~C, ~^Z, nested sessions, and how to change the escape character.
- How to record an SSH session on Linux
Record an SSH session and play it back: script and scriptreplay, asciinema, tlog on the server, and sudo I/O logs. Plus how to keep passwords out of them.
- tmux cheat sheet: commands and keys
The tmux commands and keys you actually use: sessions, windows, panes, copy mode, scripting and config. Every entry checked on tmux 3.5a with default bindings.
- tmux vs screen: what is the difference
tmux and GNU screen both keep terminal sessions running after you disconnect. How their keys, panes, scripting and serial port support compare, side by side.
- How to use X11 forwarding over SSH
Run Linux graphical programs over SSH with ssh -X. The difference between -X and -Y, what the server needs, XQuartz on Mac, common errors and the security risk.
SFTP and file transfer
Move files around over SSH.
- How to edit remote files over SSH
Edit a file on a server over SSH: nano or vim in the session, sudoedit, scp down and back up, vim scp://, an sshfs mount, or an editor with a remote mode.
- How to use rsync over SSH
Sync folders with rsync over SSH: -avz, the trailing slash rule, a custom port with -e, resuming with --partial, and how to use --dry-run before --delete.
- scp examples: copy files and folders over SSH
Tested scp examples: upload, download, copy a folder with -r, use another port with -P, copy between two servers with -3, and when you need the legacy -O flag.
- scp vs SFTP vs rsync: which one to use
Use scp for a quick copy, SFTP to browse or resume, and rsync to sync folders and send only changes. Examples, the trailing slash rule, and using a custom port.
- sftp commands: get, put, ls, lcd and batch mode
The sftp commands you need, tested: connect, get, put, ls, lcd, resume with reget, and script transfers with batch mode -b, including its key-only login rule.
- How to mount a remote folder over SSH with sshfs
Mount a server folder as a local one with sshfs. Mount and unmount commands, reconnect and other options, what to do when it breaks, and macFUSE on Mac.
SSH from a phone
What you need to work on a server from your phone.
- How to transfer files to a server with SFTP from an iPhone
Transfer files from an iPhone to a server over SFTP: why the Files app is not enough, what to look for in an app, and how to set up an sftp-only user.
- How to SSH from an Android phone
What you need to SSH from Android: how to judge a client, keys on the phone, why background sessions die, and the OpenSSH commands on the phone.
- How to SSH from an iPhone
What you need to SSH from an iPhone: a reachable server, a key made for the phone, and tmux, because iOS suspends apps in the background and connections drop.
Encrypted vaults
How the encryption works and what it protects.
- Argon2id explained: what m, t and p mean and what to choose
Argon2id makes each password guess cost memory. What m, t and p mean, the RFC 9106 and OWASP values, why it beats PBKDF2 on GPUs, with examples you can run.
- What does end to end encrypted mean for a password vault?
End to end encrypted means your device encrypts the vault with keys the server lacks. What the server still sees, what stays exposed, and what to ask a vendor.
- SSH password manager: how to store SSH passwords securely
Where to keep SSH passwords: keys first, the risks of sshpass -p, the macOS Keychain and secret-tool for passwords you must keep, and what a manager should do.