SSH Command: Syntax, Options & Examples

Our Linux server support engineers use the ssh command as the entry point to every remote session. This page documents the command from the OpenSSH client: syntax, the options used in practice, key-based authentication, the client config file, port forwarding, jump hosts, and the errors that stop a connection.

Basic syntax

The general form, per the ssh(1) man page:

ssh [options] [user@]host [command]

Connect as a specific user on a non-default port:

ssh [email protected] -p 2222

If user@ is omitted, ssh uses the local username. If command is given, ssh runs it on the remote host and exits instead of opening an interactive shell: ssh admin@server1 uptime. The default port is 22. The user can also be set with -l user; user@host and -l are equivalent.

Common options

Key-based authentication

Key authentication replaces the password prompt with a keypair. Generate an Ed25519 key, copy the public half to the server, and connect:

# 1. Generate a keypair (creates ~/.ssh/id_ed25519 and id_ed25519.pub)
ssh-keygen -t ed25519 -C "admin@workstation"

# 2. Install the public key on the server (appends to ~/.ssh/authorized_keys)
ssh-copy-id -i ~/.ssh/id_ed25519.pub [email protected]

# 3. Log in without a password
ssh [email protected]

Ed25519 is the current default key type in OpenSSH; ssh-keygen -t rsa -b 4096 remains valid where Ed25519 is not accepted. A passphrase on the private key is optional but protects it if the file is stolen; ssh-agent caches the decrypted key for the session.

Key login fails silently back to password auth when permissions are wrong. The server-side requirement: ~/.ssh must be mode 700 and ~/.ssh/authorized_keys mode 600, owned by the login user. The private key on the client must also be 600, or ssh refuses to use it with an UNPROTECTED PRIVATE KEY FILE warning. See chmod for the permission notation.

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

The ~/.ssh/config file

Per-host defaults live in ~/.ssh/config (documented in ssh_config(5)). Each Host block defines an alias with its own user, port, and key, so a long command line collapses to ssh web1:

Host web1
    HostName server1.example.com
    User admin
    Port 2222
    IdentityFile ~/.ssh/id_ed25519

Host bastion
    HostName bastion.example.com
    User jumpuser

Host db1
    HostName 10.0.5.20
    User admin
    ProxyJump bastion

Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3

The first matching value wins, so host-specific blocks go above the Host * defaults. The file must be mode 600. Any command-line option has a config equivalent; ssh -G web1 prints the effective configuration for a host after all matching is applied.

Port forwarding

Local forwarding (-L) makes a remote service reachable on a local port. The connection goes: local port, through the SSH tunnel, out from the server to the destination. Example — reach a MySQL server that only listens on the remote host's localhost:

ssh -L 3307:localhost:3306 [email protected] -N

Connecting a client to localhost:3307 on the workstation now reaches port 3306 on server1. The destination can also be a third machine reachable from the server: -L 8080:10.0.5.20:80.

Remote forwarding (-R) is the reverse: a port on the server forwards back to a machine on the client side. Example — expose a local development server on port 3000 to the remote host:

ssh -R 8080:localhost:3000 [email protected] -N

Processes on server1 connecting to localhost:8080 reach port 3000 on the workstation. Binding the remote port on interfaces other than loopback requires GatewayPorts yes in the server's sshd_config.

Dynamic forwarding (-D) opens a local SOCKS proxy; any application configured to use it tunnels all its traffic through the server, with the destination chosen per connection:

ssh -D 1080 [email protected] -N

Pointing a browser's SOCKS5 proxy at localhost:1080 routes its traffic out through server1. Combine any forwarding mode with -f -N to hold the tunnel open in the background.

Jump hosts (-J)

When the target is only reachable through a bastion, -J chains the connection without a manual two-step login:

ssh -J [email protected] [email protected]

Multiple hops are comma-separated: -J bastion1,bastion2. Authentication happens against each hop in order, and the equivalent config directive is ProxyJump, as in the db1 block above. -J replaced the older ProxyCommand ssh -W pattern in OpenSSH 7.3.

File transfer over SSH

Three tools ride the same protocol and the same authentication: scp -P 2222 file.tar.gz admin@server1:/var/backups/ copies a single file (note the capital -P for port, unlike ssh); sftp admin@server1 opens an interactive transfer session with get/put commands; and rsync -avz -e "ssh -p 2222" ./dir/ admin@server1:/srv/dir/ synchronizes directory trees and only transfers changed blocks, which makes it the standard choice for repeated copies. All three honor ~/.ssh/config host aliases. Recurring transfers are typically scheduled from crontab with key auth and no passphrase prompt.

Keeping sessions alive

Idle sessions are dropped by NAT gateways and firewalls that expire quiet TCP connections. The client-side fix is protocol-level keepalives in ~/.ssh/config: ServerAliveInterval 60 sends an encrypted probe every 60 seconds of silence, and ServerAliveCountMax 3 disconnects after three unanswered probes. The server-side equivalents are ClientAliveInterval and ClientAliveCountMax in sshd_config. For sessions that must survive a real network drop, run the work inside tmux or screen on the remote host and reattach after reconnecting.

Troubleshooting

• Connection refused — nothing is listening on the port reached. Cause: sshd not running, wrong port, or a firewall rejecting the connection. Fix: on the server, systemctl status sshd (the unit is ssh on Debian/Ubuntu, per the Ubuntu OpenSSH guide), confirm the Port value in /etc/ssh/sshd_config, and check firewall rules.
• Connection timed out — packets are silently dropped rather than rejected. Cause: wrong IP, host down, or a firewall dropping instead of rejecting. Fix: verify the address resolves and is routable, then check network-path firewalls.
• Permission denied (publickey) — the server refused every authentication method it offers. Causes: wrong user, key not in authorized_keys, wrong permissions on ~/.ssh or the key files, or PasswordAuthentication no with no valid key. Fix: confirm the username, re-run ssh-copy-id, apply the 700/600 permissions above, and read /var/log/auth.log or journalctl -u sshd on the server.
• WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED — the server's host key no longer matches the entry in ~/.ssh/known_hosts. Cause: the server was reinstalled, its keys were regenerated, or the connection is being intercepted. Fix: verify the change is legitimate first; then remove the stale entry with ssh-keygen -R hostname and reconnect to accept the new key.
• Debugging any of the above — run the client with ssh -v (up to -vvv). The output shows which config files were read, which keys were offered, which authentication methods the server accepted, and exactly where the exchange stopped.

Server hardening pointers

Settings in /etc/ssh/sshd_config, documented in sshd_config(5); reload sshd after changes. PasswordAuthentication no disables password logins so only keys work — set it only after key login is confirmed working. PermitRootLogin no (or prohibit-password) blocks direct root logins. Port 2222 or another non-standard port cuts automated scan noise; it is obscurity, not access control, and the firewall must allow the new port before the reload. AllowUsers restricts logins to named accounts. Red Hat publishes a fuller checklist in its SSH hardening guide, and the client and daemon behavior is specified end to end in the ssh(1) page on man7.org.

When to hand it over

Lockouts are the common failure: a password-auth change or firewall rule applied over the same SSH session it breaks. Our Linux server support team handles SSH lockout recovery, key rollout across fleets, bastion setup, and sshd hardening as standard cases. An engineer is available on live chat 24/7.