Anime-Sanctuary

What is SSH?

SSH is the direct, protected line between your computer and a machine somewhere else. You will see how it works, log in through it and create your first key.

Course
Tutorial 5 of 35
Time
25 min to read
Tested with
Debian 13 (trixie), OpenSSH 10.0p2
What you will be able to do
  • Explain what SSH does and why it is safe.
  • Read an SSH connection: user, host, port.
  • Log in to a server and check its fingerprint.
  • Create an SSH key and log in with it.

Before you start: The words: IP, DNS, domain, port, firewall.

Contents
  1. The idea in one picture
  2. What SSH does
  3. Why a key beats a password
  4. Three words to remember
  5. 1. Open a terminal
  6. 2. Log in to the server
  7. 3. Leave the server
  8. 4. Create your key pair
  9. 5. Copy the public key
  10. 6. Log in again with the key
  11. 7. Send a file with scp
  12. If it fails
  13. Final check
  14. Frequently asked questions
  15. Sources
A padlock, the picture of a connection only you can open

The idea in one picture

SSH is a program that opens a path between your computer and a faraway computer, so you can type instructions to it.

Picture a computer in another building, switched on day and night. You can't touch it, but you want to tell it what to do. You need a way to talk to it from a distance, and that is exactly what SSH does. That distant computer is a server: it stays on to answer requests, such as sending a web page. For a full refresher, see What is a server?.

To talk to it, you use a terminal: a window where you type text instead of clicking. Each line you type is a command, a short instruction. For example, ls (short for "list") asks for the list of files. You press Enter and the machine answers with text. One piece is missing: a path between your terminal and the server. That path is SSH.

The example server runs Linux, a free operating system that comes in many flavors. This course uses the flavor called Debian. Your own computer can run Windows, macOS or Linux. Now let's see how that path is built.

What SSH does

That path is a secret pipe. The name SSH stands for Secure Shell. It has two halves: the client, the ssh program on your computer, which makes the call, and the SSH server on the distant machine, which picks up.

The pipe is encrypted, and that is the whole point. To encrypt is to scramble a message so that only its recipient can read it. Think of a letter in a sealed envelope: anyone who grabs it along the way just gets a sealed envelope. With SSH, every command and every reply travels like that, passwords included. Inside that same pipe, SSH does three jobs.

  • It logs you in. You prove who you are, and the server lets you in.
  • It lets you type commands on the server, as if you were sitting in front of it.
  • It carries files. The scp command copies a file through the same pipe, to or from the server.

Here is the journey of one command, seen from above.

The journey of a command with SSH Your computer sends the ls command through an encrypted pipe to the server. The server sends the list of files back through the same pipe. Your computer Server mon-serveur encrypted pipe ls list 1. command, then 2. reply Unreadable on the way
Text version: you type ls ("list the files") on your computer. The command leaves through the encrypted pipe and reaches the server named mon-serveur. It sends the list back the same way, and you see it on your screen.

The first job, logging in, means proving who you are. So how do you prove it safely?

A laptop showing lines of code

Why a key beats a password

A robot can guess a password. It can't guess an SSH key. A server is plugged into the Internet around the clock, so everyone can see it. Automatic programs, called robots, keep trying to log in day and night, testing thousands of common passwords.

The fix is the SSH key: two files created together, like a lock and its key. Each has its own job.

  • The public key is the lock. You can show it to anyone, and you install it on the server.
  • The private key is the key that opens that lock. Only you have it, and it never leaves your computer.

A robot sees the lock but can't forge the key: there is nothing to guess. One catch: as long as the server also accepts passwords, robots can still try them. Turning passwords off is covered in Secure SSH: turn off passwords. Before you make your pair, let's learn how to tell SSH which server to aim at.

Three words to remember

To aim at a server, SSH needs three pieces of information: the host, the user and the port. Example: alice@203.0.113.10. Here they are one by one.

  • The host: the address of the server, here 203.0.113.10. It works like the street address of a building. It can be a number (an IP address, the number that identifies a machine on the network) or a name like exemple.fr.
  • The user: the account you log in with, here alice. It is your name on the machine.
  • The port number: the front door. A server offers thousands of numbered doors, each for one service. By default SSH knocks on door 22, the one in our example.

These three pieces fit together like this: ssh user@host. The @ sign (read "at") separates the user from the address of the machine. If the port is different, add the option -p (a small setting placed after ssh) and the number, for example ssh -p 2222 alice@203.0.113.10. You now have every piece. Time to get practical and open the window where you type.

1Open a terminal

Every step from here on starts in your computer's terminal and aims at a real server. You need four things:

  • the host;
  • the user;
  • the port, 22 unless told otherwise;
  • the account password.

Your hosting provider, the company that rents you the server, gives you all four.

No server yet? Read on to understand, then come back to practice after Install Debian 13 on a VPS or a dedicated server. Logging in to your brand-new machine, from Windows, macOS or Linux, has its own article: Your first SSH connection. Here, the example server is called mon-serveur. Its host is 203.0.113.10 (an example address, explained in The words: IP, DNS, domain, port, firewall) and the user is alice. Replace these values with yours.

First, open a terminal on your computer:

  • Windows: right-click the Start button, then choose "Terminal" or "Windows PowerShell". PowerShell is a terminal like any other.
  • macOS: press Cmd (the Command key) and Space together, type "Terminal", then press Enter.
  • Linux: look for "Terminal" in your applications, or try Ctrl + Alt + T.

Then check that the ssh program is there. Recent Windows 10 and 11 include it, but an older version may have left it out.

On your computer
ssh -V

A version number appears. The exact number doesn't matter. If the terminal answers "command not found" or "not recognized", you need to install the ssh program. On Windows, open Settings, Apps, Optional features, then add OpenSSH Client (the client is the ssh program from earlier). The terminal is ready, so on to your first login.

2Log in to the server

One command logs you in: ssh, followed by the user and the host. It means "connect me to server 203.0.113.10 as alice". On your first login, SSH asks a question. It isn't an error: "can't be established" means "I cannot yet confirm this is the right server".

On your computer
ssh alice@203.0.113.10
Expected output
The authenticity of host '203.0.113.10 (203.0.113.10)' can't be established.
ED25519 key fingerprint is SHA256:J7SVxQS7TGXBz5Vi/yr3MC9Q6kizl66qzkGBgS7Uht4.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

In plain English: "I don't know this server yet. Here is its fingerprint. Do you want to continue?" The fingerprint is a short string of characters, unique to this server, like a human fingerprint. It lets you check that you are talking to the right server and not to an impostor. ED25519 is the type of key this server uses to introduce itself. SHA256 is the method that computes the fingerprint; the rest of the line is the fingerprint itself.

Compare it with the one from your hosting provider, or with the one you read in the remote console. Never with the one on this page! The remote console is the virtual screen and keyboard that your hosting provider shows on its website (VPS or dedicated server: which one to pick?), and it works without SSH. Read the fingerprint there with the next command, where -lf asks for the fingerprint of a key file.

On the server (in the remote console)
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
Expected output
256 SHA256:J7SVxQS7TGXBz5Vi/yr3MC9Q6kizl66qzkGBgS7Uht4 root@mon-serveur (ED25519)

Only the fingerprint matters, so ignore the end of the line: root is the administrator account of the machine, the one that can do anything. If the two fingerprints are identical, type yes and press Enter. Your computer then remembers the server in its known_hosts file ("known hosts") and won't ask again. The server then asks for alice's password. Type it: nothing appears while you type, and that is on purpose. Press Enter, then type whoami ("who am I?").

On the server (you are logged in)
whoami
Expected output
[...]
alice@mon-serveur:~$ whoami
alice

The text alice@mon-serveur:~$ is called the prompt: the spot where the server waits for your command. The ~ means "your home folder". The prompt changes to show you are on the other side, and everything you type now runs on the server. In this block, [...] marks omitted lines, such as the welcome message from Debian (the system on the example server).

You're in. Now let's see how to get out cleanly.

3Leave the server

To close the connection, type exit and press Enter. The shortcut Ctrl + D does the same.

On the server (you are logged in)
exit
Expected output
logout
Connection to 203.0.113.10 closed.

You're back on your own computer. Closing the window without typing exit works too, but exit shuts the door properly behind you. You know how to get in and out with a password. Now let us replace it with a key, starting by making one.

4Create your key pair

The ssh-keygen program makes the lock and its key in one command. You do this step on your computer, not on the server.

It will ask for a passphrase: a long secret phrase that locks your private key on your computer. If someone steals the file, they cannot use it without the phrase. Don't mix it up with alice's password, which lives on the server. Two secrets, two jobs:

  • the server password opens the account;
  • the passphrase unlocks the key.
On your computer
ssh-keygen -t ed25519 -C "alice@mon-ordinateur"
Expected output
Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/alice/.ssh/id_ed25519):
Enter passphrase for "/home/alice/.ssh/id_ed25519" (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/alice/.ssh/id_ed25519
Your public key has been saved in /home/alice/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:F4eAKXsG+VNWMIJcr1I+PZg1dundOnVVv0FN/AvcaWU alice@mon-ordinateur

Let's look at what you just typed. Two options set up the key:

  • -t ed25519 picks the key type, a modern one and the recommended choice. Keep it as it is;
  • -C "alice@mon-ordinateur" adds a comment, a free label that helps you recognize the key later.

The program then asks three questions:

  1. Where to save the key? Press Enter to keep the suggested location.
  2. Which passphrase? Pick a long phrase you will remember. Nothing appears while you type.
  3. Type it again, to catch a typo.

The end of the output (the fingerprint) is different for every key, and that is normal. Two files appear in the .ssh folder inside your home folder. Its name starts with a dot, which makes it a hidden folder: it doesn't show up in ordinary listings. Here are the two files.

  • ~/.ssh/id_ed25519: the private key;
  • ~/.ssh/id_ed25519.pub: the public key. The "pub" at the end stands for public.

The lock is made. Now it has to be fitted on the server's door.

5Copy the public key to the server

The ssh-copy-id command installs the lock on the server. It logs in with the server password, one last time, and adds your public key to the authorized_keys list of the alice account. The server lets in anyone whose key is on that list.

On your computer
ssh-copy-id alice@203.0.113.10
Expected output
/usr/bin/ssh-copy-id: INFO: Source of key(s) to be installed: "/home/alice/.ssh/id_ed25519.pub"
/usr/bin/ssh-copy-id: INFO: attempting to log in with the new key(s), to filter out any that are already installed
/usr/bin/ssh-copy-id: INFO: 1 key(s) remain to be installed -- if you are prompted now it is to install the new keys
alice@203.0.113.10's password:

Number of key(s) added: 1

Now try logging into the machine, with: "ssh 'alice@203.0.113.10'"
and check to make sure that only the key(s) you wanted were added.

Type the server password when asked. "Number of key(s) added: 1" confirms the key is installed. If ssh-copy-id is missing, for example on Windows, there is another way: display the public key, then paste it on the server. Display the key first.

On your computer
cat ~/.ssh/id_ed25519.pub
Expected output
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIE4zuxA2aSLv95s9TXJ7i89VsXb9YIjbLGa8DQqTFjQw alice@mon-ordinateur

The output is a single line, the public key, and yours will be different. On Windows, open the id_ed25519.pub file in the .ssh folder with Notepad and copy its whole line. Then log in to the server with the server password (step 2).

Once logged in, type the next command, pasting your line in place of the example, between the quotes. Don't copy the example line as it is: it belongs to alice, not to you. Here, the >> sign appends text to the end of a file, and mkdir -p creates the .ssh folder if it doesn't exist yet.

On the server (you are logged in)
mkdir -p ~/.ssh && echo "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIE4zuxA2aSLv95s9TXJ7i89VsXb9YIjbLGa8DQqTFjQw alice@mon-ordinateur" >> ~/.ssh/authorized_keys

The command prints nothing when all goes well. Type exit, then go to step 6 to check that the key works.

6Log in again with the key

With the key installed, ssh asks for your passphrase instead of the server password. Run the step 2 command again.

On your computer
ssh alice@203.0.113.10
Expected output
Enter passphrase for key '/home/alice/.ssh/id_ed25519':
[...]
alice@mon-serveur:~$

The passphrase stays on your computer: it only unlocks the private key, and the server never sees it. If you left it empty, you walk straight in. Type exit to leave. The key works, and the same pipe can carry files too.

7Send a file with scp

The scp command copies a file through SSH. A file on the server is written user@host:path, with a colon between the host and the path. First create a small file on your computer, then send it to the server's /tmp folder (the folder for temporary files).

On your computer
echo bonjour > notes.txt

The echo command writes some text, and the > sign sends it into the file notes.txt instead of printing it.

On your computer
scp notes.txt alice@203.0.113.10:/tmp/notes.txt
Expected output
Enter passphrase for key '/home/alice/.ssh/id_ed25519':
notes.txt                                     100%    8    31.4KB/s   00:00

The progress bar vanishes almost at once for a tiny file, and the speed figures vary. To fetch a file, swap the two locations. The lone dot at the end of the command means the folder you are in.

On your computer
scp alice@203.0.113.10:/tmp/notes.txt .

Here everything worked on the first try. On a real server it won't always go that smoothly, so let's look at the errors you are likely to meet.

If it fails

When something goes wrong, the error message almost always says why. The table below sums up the five most common cases. The ones that need action are explained after it.

To see every step of the connection: the -v option

Run the command again with -v (short for verbose, meaning chatty). SSH describes each step out loud, which shows you where it gets stuck.

On your computer
ssh -v alice@203.0.113.10
Expected output
debug1: Connecting to 203.0.113.10 [203.0.113.10] port 22.
[...]
debug1: Offering public key: /home/alice/.ssh/id_ed25519 ED25519 SHA256:F4eAKXsG+VNWMIJcr1I+PZg1dundOnVVv0FN/AvcaWU
debug1: Server accepts key: /home/alice/.ssh/id_ed25519 ED25519 SHA256:F4eAKXsG+VNWMIJcr1I+PZg1dundOnVVv0FN/AvcaWU
Authenticated to 203.0.113.10 ([203.0.113.10]:22) using "publickey".

This output shows a login that succeeds with the key. When something goes wrong, read the last lines before the error.

ErrorCauseAction
Connection refusedNobody is listening on that port: wrong number, or the SSH service is stoppedCheck the port with your hosting provider
Connection timed outNo answer at all: wrong host, server switched off or firewallRecheck the host, then the state of the server
Permission denied (publickey,password)Typo in the passphrase, the password or the user name, or the public key is not installedRetype with care, or redo step 5
UNPROTECTED PRIVATE KEY FILEPermissions on the private key file are too openchmod 600 on that file
Host key verification failedThe server's fingerprint has changedConfirm it with your hosting provider, then delete the old one

The first two cases fit in one line. With Connection refused, the server can be reached but nothing listens on that port: check the port with your hosting provider. With Connection timed out, it does not answer at all: recheck the host, the state of the server and the firewall (the guard that blocks traffic by port number, covered in The words: IP, DNS, domain, port, firewall). The most common case comes next.

Permission denied (publickey,password)

If a key exists on your computer, ssh first asks for its passphrase, up to three times. It then falls back to the server password. Here is what a series of typos looks like:

On your computer
ssh alice@203.0.113.10
Expected output
Enter passphrase for key '/home/alice/.ssh/id_ed25519':
Enter passphrase for key '/home/alice/.ssh/id_ed25519':
Enter passphrase for key '/home/alice/.ssh/id_ed25519':
alice@203.0.113.10's password:
Permission denied, please try again.
alice@203.0.113.10's password:
Permission denied, please try again.
alice@203.0.113.10's password:
alice@203.0.113.10: Permission denied (publickey,password).

Third case in one line. With UNPROTECTED PRIVATE KEY FILE, the permissions on the private key file (who is allowed to read it) are too open and ssh ignores it. chmod 600 ~/.ssh/id_ed25519 (it changes the file permissions) keeps it for you alone, on Linux and macOS (Windows: not tested).

Host key verification failed

On your computer
ssh alice@203.0.113.10
Expected output
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that a host key has just been changed.
The fingerprint for the ED25519 key sent by the remote host is
SHA256:9h/X/IMga8v03IYij5/hE5uo7OSSl3/giyQCrYa6C0A.
Please contact your system administrator.
Add correct host key in /home/alice/.ssh/known_hosts to get rid of this message.
Offending ECDSA key in /home/alice/.ssh/known_hosts:3
  remove with:
  ssh-keygen -f '/home/alice/.ssh/known_hosts' -R '203.0.113.10'
Host key for 203.0.113.10 has changed and you have requested strict checking.
Host key verification failed.
On your computer
ssh-keygen -R 203.0.113.10
Expected output
# Host 203.0.113.10 found: line 1
# Host 203.0.113.10 found: line 2
# Host 203.0.113.10 found: line 3
/home/alice/.ssh/known_hosts updated.
Original contents retained as /home/alice/.ssh/known_hosts.old

The ssh-keygen -R command deletes the server's entries from known_hosts. It finds three here (only one if you have a single key for this server). Your computer keeps one fingerprint per key type for the same server. ED25519, ECDSA and RSA are three key types: the alert above names ECDSA, while your login uses ED25519. The old file is kept under the name known_hosts.old. You can now fix most problems. Let's check that the essentials stuck.

Final check

Three questions are enough to check you understood. Think before you open the answer.

1. Which file can you give to anyone, the private key or the public key?

The public key, the one that ends in .pub. It is the lock. The private key stays on your computer and is never sent.

2. SSH shows REMOTE HOST IDENTIFICATION HAS CHANGED. What do you do?

You stop. You don't type yes. You check the server's fingerprint with your hosting provider. Only if it matches (for example after a reinstall) do you delete the old one with ssh-keygen -R.

3. In ssh -p 2222 alice@203.0.113.10, what are 2222, alice and 203.0.113.10?

2222 is the port, the front door used instead of 22. alice is the user. 203.0.113.10 is the host, the address of the server.

Next up: the article Install Debian 13 on a VPS or a dedicated server sets up a Debian 13 server of your own. You will then have a real machine to practice on.

Frequently asked questions

What is SSH and what is it for?

SSH is a program that opens an encrypted path between your computer and a distant server. It logs you in, lets you type commands on the server and moves files with scp.

SSH key or password: which one is safer?

The key is safer. A robot can guess a password, but it can't forge the private key, which never leaves your computer. The public key goes on the server, like a lock.

What should I do when SSH shows REMOTE HOST IDENTIFICATION HAS CHANGED?

Stop, and don't type yes. Check the server's fingerprint with your hosting provider. Only if it matches, for example after a reinstall, delete the old one with ssh-keygen -R.