SSH: Secure Remote Access

ssh (secure shell) is the protocol underneath two things you will do constantly: authenticating to github without typing a password, and logging into a remote machine — a university server, a computing cluster — to run something too heavy for your laptop. Both uses share the same mechanism: a keypair, generated once.

What ssh actually does¶

ssh opens an encrypted connection between two machines and authenticates you to the remote one — normally with a password, or, better, with a keypair. A keypair is two mathematically linked files: a private key, which never leaves your machine, and a public key, which you hand out freely to anything you want to trust you. The remote side (github, a cluster login node) challenges your machine to prove it holds the private key matching a public key already on file; if the proof succeeds, you are in, with no password ever sent over the network. This is both more secure than a password and more convenient — nothing secret crosses the network, and there is nothing to retype.

Generating a keypair¶

# macOS / Linux
ssh-keygen -t ed25519 -C "you@example.com"
# press Enter to accept the default location (~/.ssh/id_ed25519),
# and set a passphrase if you want an extra layer of protection

# Windows (PowerShell, built-in OpenSSH)
ssh-keygen -t ed25519 -C "you@example.com"
# key lives in %USERPROFILE%\.ssh\id_ed25519

This creates two files: id_ed25519 (private — keep it secret, never share it, never commit it) and id_ed25519.pub (public — safe to share; this is what you hand to github or a server administrator).

Authenticating to github¶

Add the contents of id_ed25519.pub to github, under Settings -> SSH and GPG keys -> New SSH key. Then:

ssh -T git@github.com            # test the connection
git clone git@github.com:org/repo.git

The test command should greet you by username rather than asking for a password — that confirms the keypair is working.

Connecting to a remote server¶

The same keypair works for logging into any server that has your public key on file — most commonly a university or HPC login node for thesis-scale computation.

ssh your-username@cluster.example.edu

Once connected, you have a terminal on the remote machine: the navigation and file commands from the terminal-commands page work exactly the same there. To move files between your laptop and the remote machine without a full session, use scp for single files, or rsync for whole directories (it only transfers what actually changed):

scp results.csv your-username@cluster.example.edu:~/project/
rsync -av local_folder/ your-username@cluster.example.edu:~/remote_folder/

Going deeper: ssh-agent

An ssh-agent caches your unlocked key for the session, so you do not retype a passphrase on every connection.

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Going deeper: managing several hosts with ~/.ssh/config

One block per remote turns a long command into a short name:

Host github.com
    User git
    IdentityFile ~/.ssh/id_ed25519

Host cluster
    HostName cluster.example.edu
    User your-username
    IdentityFile ~/.ssh/id_ed25519

With this in place, ssh cluster replaces ssh your-username@cluster.example.edu, and the right key is picked automatically for each host.

Going deeper: running Jupyter on a remote machine

A cluster’s login node often has no browser, but you can still use its Jupyter through a tunnel: start the notebook server remotely on a fixed port, then forward that port to your laptop.

# on the remote machine
jupyter notebook --no-browser --port=8888

# on your laptop, in a new terminal
ssh -L 8888:localhost:8888 your-username@cluster.example.edu

Open localhost:8888 in your own browser; the notebook is running remotely, but reachable through the tunnel exactly as if it were local.

Resources¶

GitHub Docs — Connecting to GitHub with SSH — github’s own reference for generating a key and adding it to your account.
Project Pythia — Getting started with GitHub — geoscience-oriented walkthrough that includes ssh setup alongside github basics.