The ssh command explained (Windows)

What the ssh command does

ssh (Secure Shell) opens an encrypted connection from your computer to another computer, usually a server, and gives you a command line on it. Everything you type, and everything the server answers, is scrambled on the way, so nobody on the network can read your password or your commands.

The same connection can also run a single command, carry file transfers (scp, sftp, rsync) and tunnel other network traffic. This page explains each use, one step at a time.

The basic shape

• options change how it connects (port, key, tunnels…). The full list is further down.
• user is your login name on the server. If you leave it out, ssh uses your local user name.
• host is the server's name or IP address.
• command is optional. If you give one, ssh runs it and comes back; if not, you get a shell.

Your first login

• >ssh deploy@203.0.113.10Copy

  Log in as the user deploy on that address

• >ssh deploy@web-01.example.comCopy

  The same with a name instead of numbers

• >ssh web-01.example.comCopy

  Use your local user name as the login name

• >ssh -l deploy web-01.example.comCopy

  Another way to give the user name (-l, a lowercase L)

• >ssh -p 2222 deploy@web-01.example.comCopy

  The server listens on port 2222 instead of the normal 22

You are asked for a password (nothing appears while you type, which is normal) or, if you set up a key, you go straight in. To leave, type exit or press Ctrl+D.

The first-connection question (host keys)

The first time you connect to a server, ssh shows something like this:

The authenticity of host 'web-01.example.com (203.0.113.10)' can't be established.
ED25519 key fingerprint is SHA256:Kx3m0yQ4mPq8wZ1nT7vB2cD9eF5gH6jL8aR0sUiYtXo.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

This is a safety check. The fingerprint is a short code that identifies that server. Think of it as checking a stranger's name before you hand over a package.

• If you can, compare the fingerprint with the real one. The server's administrator can show it with ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub (run on the server).
• Type yes if it matches, or if you trust the network and the server is your own. ssh remembers it in C:\Users\you\.ssh\known_hosts and will not ask again.
• Type no if anything looks odd.

• >ssh-keygen -R web-01.example.comCopy

  After you are sure the server was rebuilt: forget the old fingerprint

• >ssh-keygen -lf C:\Users\you\.ssh\known_hostsCopy

  List the fingerprints you have already accepted

Run one command on a server

Put the command after the host. ssh runs it, prints the answer on your screen and returns to your own prompt.

• >ssh deploy@web-01 "uptime"Copy

  Run uptime on the server

• >ssh deploy@web-01 "df -h /"Copy

  Check free disk space

• >ssh deploy@web-01 "sudo systemctl status nginx"Copy

  Check a service

• >ssh deploy@web-01 "ls /var/log | wc -l"Copy

  Quotes make the whole command run on the server, pipe included

• >ssh deploy@web-01 "cat /etc/os-release" > %TEMP%\os.txtCopy

  Save the server's answer into a file on your own computer

• >ssh -t deploy@web-01 "sudo nano /etc/hosts"Copy

  -t gives the command a real terminal, needed for editors and sudo prompts

Log in with a key instead of a password

A key pair is two files. The private key stays on your computer and must never be shared. The public key is copied to the server. When you connect, ssh proves you hold the private key without sending it. It is safer than a password and lets you skip typing one.

• >ssh-keygen -t ed25519 -C "me@example.com"Copy

  Make a key pair. Press Enter to accept the default file name and choose a passphrase

• >type %USERPROFILE%\.ssh\id_ed25519.pubCopy

  Print your PUBLIC key (the one you share)

Windows has no ssh-copy-id. Use this PowerShell line instead; it adds your public key to the server:

• >type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh deploy@web-01 "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"Copy

  Append your public key on the server

• >ssh -i %USERPROFILE%\.ssh\id_ed25519 deploy@web-01Copy

  Use one specific key file

• >ssh-add %USERPROFILE%\.ssh\id_ed25519Copy

  Unlock the key once so you do not retype its passphrase

• >ssh-add -lCopy

  List the keys your agent holds

If ssh-add says the agent is not running, open PowerShell as administrator and run Set-Service ssh-agent -StartupType Automatic; Start-Service ssh-agent.

Shortcuts: the config file

Typing long commands gets old. Put your servers in the config file, C:\Users\you\.ssh\config, and give each one a short name (an alias).

Host web
    HostName 203.0.113.10
    User deploy
    Port 2222
    IdentityFile C:/Users/you/.ssh/id_ed25519

Host *
    ServerAliveInterval 30
    ServerAliveCountMax 4

Now ssh web does everything the long command did. scp, sftp and rsync understand the same names. The Host * block applies to every server: here, it sends a small keep-alive message every 30 seconds so idle sessions are not dropped by routers.

Go through a jump host

Some servers are not reachable from the internet. You first log in to a bastion (or jump host), and it forwards you to the hidden server. With -J you do both steps in one command.

• >ssh -J jump@bastion.example.com deploy@10.0.0.5Copy

  Reach 10.0.0.5 through the bastion

• >ssh -J jump1@a.example.com,jump2@b.example.com deploy@10.0.0.5Copy

  Two jump hosts in a row

• >scp -J jump@bastion.example.com file.zip deploy@10.0.0.5:~Copy

  File copies can jump too

In the config file, the same thing is one line: ProxyJump jump@bastion.example.com under the hidden server's Host block.

Port forwarding (tunnels)

A tunnel carries other network traffic through your SSH connection. There are three kinds. The numbers below are the port that is opened on the side named first.

• >ssh -L 5432:127.0.0.1:5432 deploy@web-01Copy

  Now connect your database program to 127.0.0.1:5432 on your own computer

• >ssh -L 8080:intranet.local:80 deploy@web-01Copy

  Open http://localhost:8080 to reach intranet.local as the server sees it

• >ssh -R 9000:localhost:3000 deploy@web-01Copy

  The server's port 9000 now reaches your computer's port 3000

• >ssh -D 1080 deploy@web-01Copy

  SOCKS proxy at localhost:1080

• >ssh -N -L 5432:127.0.0.1:5432 deploy@web-01Copy

  -N means "no shell, only the tunnel"; leave the window open

• >ssh -f -N -L 5432:127.0.0.1:5432 deploy@web-01Copy

  -f sends it to the background after login

Options reference

Useful -o settings

Escape codes: unstick a frozen session

If a session freezes (for example, the Wi-Fi dropped), typing does nothing. ssh has escape codes that work even then. Press Enter first, then type the keys one after another:

Common errors and fixes

When in doubt, add -v: the last few lines before the failure usually name the cause.