SSH for Beginners - AtlasOfLivingAustralia/documentation GitHub Wiki

Introduction

ssh is a fundamental tool that allows us to connect to a server safely, transfer files, and perform many other tasks. For example, ansible uses it to connect to our servers to configure them as specified in our service and server inventories and according to the tasks defined in ala-install.

Basic Concepts

SSH keys

ssh uses a system of public and private cryptographic keys. To use a simple comparison, think of a private key as the key to your house, and a public key as a lock (or several locks) that matches that key, which you can place in different locations to open them with the same key.

You can have different public and private keys for different uses (work, home, car, bike, etc.).

You can share the public key in several places (ideally, having the same lock on all the doors of your house or your car). However, the private key should only be shared with family members (or team members), though it is advisable that each person uses their own unique keys and locks to access the same sites.

That is to say, a door can have several locks and be opened with different keys. Here our metaphor gets a bit mixed up, but hopefully, it's clear: imagine a chain with several linked padlocks (see the image). If any neighbor opens their lock with their key, the chain will open. © Linnaea Mallette, Licence: CC0 Public Domain

The same principle applies to SSH. You can configure several public keys on a server account (similar to several chained locks), and anyone who has the private key for one of those locks can access the server.

If the lock is not positioned properly, you will not be able to open that chain (and access the server).

Password access

Yes, you can use a password to access a server without SSH keys—like saying Abracadabra to open a magic door—but SSH keys are a more secure option and are our preferred method.

SSH Key Generation

Just typing:

ssh-keygen

Running this command will prompt you for a filename and a passphrase, and it will generate a key pair for you using default values.

You can also specify more options for that key:

ssh-keygen -q -t rsa -b 2048 -f .ssh/my-key

Adding your public key to a user/server to authorize it

You must authorize the public key on your server by adding it to /home/your-user/.ssh/authorized_keys.

This is like placing a new lock on your chain.

To do this, you can:

  1. Use ssh-copy-id (see more details) to copy the public key to your user/server (recommended): ssh-copy-id -i .ssh/my-key [email protected] (assume your username is jane and 1.2.3.4 is your server's IP).
  2. Or manually edit .ssh/authorized_keys by accessing your user/server via SSH (this is riskier if you are not familiar with the process):
ssh [email protected]
nano .ssh/authorized_keys
# Add the contents of .ssh/my-key.pub and save the file

The next time you access your server, you can use that key instead of the user/server password:

ssh -i .ssh/my-key [email protected]

Public and Private IP Addresses

Not all of our servers are directly connected to the Internet. Our data centers are like an office building where not every office has a door leading directly to the street.

Our servers have public and/or private IP addresses. To use another metaphor: in a building, we cannot give a unique street address to every office. Instead, a street number is shared, and then the floor and door number are used to identify a specific office inside.

Gateways

This also affects security. Imagine the chaos if every office opened directly onto the street. Instead, you typically enter through a main portal or a security checkpoint that grants access to the rest of the building. Sometimes, you must pass through several security checks before reaching the desired office.

In ssh terminology, this is known as a bastion, gateway, or proxyjump. You "jump" to one server to access another—typically an internal server.

SSH Ports

Just as the standard HTTP port is 80 and HTTPS is 443, the default port for SSH is 22. If you "ring the bell" at port 80, the web server answers; at 443, the secure web server answers; and at 22, SSH answers.

Sometimes a different port is used instead of the default 22. This often happens when we have internal servers and the external machine uses port 22 for itself. In these cases, a different port (for example, 22001) is redirected to the internal machine's port 22.

Basic ssh commands

The basic one:

ssh [email protected]

or specifying the key to use:

ssh -i .ssh/my-key [email protected]

Because these commands can be long and difficult to remember, we can edit the .ssh/config file to set up this connection for future reuse by adding:

Host my_server
  HostName 1.2.3.4
  IdentityFile ~/.ssh/my-key
  User jane

With this configuration now we can just type:

ssh my_server

to connect to that IP address with the user jane and using that ssh key.

SSH using gateways

You can access an internal server using a bastion/gateway/proxyjump like so:

ssh -J gateway.l-a.site [email protected]

However, since this command is difficult to memorize and can be even longer if you need to specify keys, it is recommended to use the .ssh/config file instead:

Host my_server
  HostName 1.2.3.4
  IdentityFile ~/.ssh/my-key
  ProxyJump gateway.l-a.site
  User jane

scp, sftp

scp and sftp are two utilities that allow for secure file transfers over SSH.

scp (Secure Copy) is a command-line utility that allows you to securely copy files and directories between two locations. With scp, you can copy a file or directory:

  • From your local system to a remote system
  • From a remote system to your local system
  • Between two remote systems from your local system

Here is the basic syntax of scp:

scp source_file user@dest:/path/to/destination

For example, if you have a file on your local machine called test.txt that you want to copy to a remote machine with IP 1.2.3.4, you could use:

scp test.txt [email protected]:/home/jane

sftp (SSH File Transfer Protocol) is another method of transferring files securely between hosts. It is more interactive and flexible than scp because it allows you to navigate the directory structure, create directories, and delete files on the remote host, among other things.

Here is how you might start a session:

sftp [email protected]

Once connected, you can use ls to list files, cd to change directory, get to download files, and put to upload files.

rsync

rsync is a utility for efficiently transferring and synchronizing files across computer systems. It's commonly used for backups and mirroring and as an improved copy command for everyday use. The rsync command will only transfer changes in the source files to the destination, making it very efficient.

Here is the basic syntax of rsync:

rsync options source destination

For example, to copy a directory from your local system to a remote system, you might use:

rsync -av /local/dir/ [email protected]:/remote/dir/

The -a option is for archive, which preserves permissions, links, etc. The -v option is for verbose, which provides detailed output of what the command is doing.

Or a more complex command like this, which synchronizes a directory recursively (-a) while using sudo to preserve ownership and permissions (useful when transferring data belonging to users other than jane), maintaining hard links (-H), continuing a previous transfer (--partial), and using a specific SSH key:

rsync -aH --partial -e "ssh -i ~/.ssh/some-key" --rsync-path="sudo rsync" /data [email protected]:/data/

SSH Clients

The remote server you want to access runs an SSH server, but to connect to it, you need an SSH client. Since we use OpenSSH on the server side, it is recommended to use OpenSSH on the client side as well.