Connecting to HPC

This guide helps you plan the details needed for institutional SSH access and, once your account is authorized, verify a login and small test-file transfer. Cluster policies differ, so use your institution’s instructions for VPN access, authentication, login nodes, and permitted transfer methods.

Before you connect

You need a cluster username, the exact login hostname, and permission to access the system. Ask the HPC support team whether you must connect through a VPN or bastion host, whether keys are accepted, how to register a key, and which host is intended for interactive login. A successful login does not grant access to every project directory or authorize moving regulated data to a personal computer.

Planning check, no cluster required: Suppose you know your username but have not been given a login hostname or authentication instructions. Should you try a guessed host or submit your private key? No. Ask the HPC team for the approved hostname, VPN or bastion requirements, authentication and public-key registration process, and the intended login or transfer endpoint. Keep the private key local; access and data permissions are separate approvals.

The commands below use placeholder values: replace hpc.example.edu and your_username with values from your administrator. Run the local key and transfer commands on your own computer, not in a remote cluster shell. The shell prompt is omitted from code blocks so commands can be copied without copying the prompt.

Create a key pair on macOS or Linux

1. Create the SSH directory if needed and restrict its permissions:

   mkdir -p ~/.ssh
   chmod 700 ~/.ssh

   The directory contains private authentication material and client configuration.

2. Create an Ed25519 key pair at a named path:

   ssh-keygen -t ed25519 -f ~/.ssh/my_hpc_key -C "yourname@example.edu"

   At the passphrase prompt, use a strong passphrase unless your institution specifies another method. The private key is my_hpc_key; the public key is my_hpc_key.pub. Protect and back up the private key appropriately. Never send it to an administrator.

Windows users should use the institution-approved client. MobaXterm supports SSH sessions and an integrated X server; its documented interface and local terminal differ from PowerShell and from the OpenSSH configuration locations on Windows. Use the MobaXterm session/key instructions or Windows OpenSSH instructions for your installation rather than pasting Unix shell commands into an arbitrary Windows prompt. Keep the private key local and provide only its matching public key to the administrator.

Register the public key and set a host alias

Show or copy the public key text with cat ~/.ssh/my_hpc_key.pub, then submit that text through the approved institutional process. Confirm with support when the key has been installed for your account. An authorized administrator typically manages the server-side authorized keys; do not edit cluster account files unless your site explicitly instructs you to.

On macOS/Linux, create or edit ~/.ssh/config:

Host myhpc
    HostName hpc.example.edu
    User your_username
    IdentityFile ~/.ssh/my_hpc_key
    IdentitiesOnly yes
    ServerAliveInterval 60

Keep the file readable only by your user where supported (chmod 600 ~/.ssh/config). Host names a local alias; HostName and User identify the remote endpoint and account; IdentityFile selects the private key. ServerAliveInterval sends periodic client messages, but it cannot override server policy or guarantee that a network connection stays alive. On Windows, use the config file location and path syntax for the OpenSSH client you actually run.

Connect and check the host identity

Run this on your local computer:

ssh myhpc

On first connection, SSH may ask whether to trust the server host key. Verify its fingerprint with your institution through a separate trusted channel before accepting it. This check helps detect an unexpected server identity; do not dismiss a changed-host-key warning without confirmation. Depending on the site, authentication may also require a key passphrase, password, or MFA.

A cluster login prompt or banner indicates that the SSH session reached a remote shell. It does not establish project allocation, data permissions, or that a computation is running. HPC systems commonly require compute work to be submitted through a scheduler; follow the cluster’s user guide and do not run heavy analysis on a login node.

Transfer a small, non-sensitive test file

Use a harmless file first, and identify each side of the transfer explicitly. In scp, a path containing user@host: is remote; an ordinary path is local. On your local macOS/Linux terminal, create the exact small fixture used below:

printf 'HPC transfer test\n' > ~/hpc-transfer-test.txt
cat ~/hpc-transfer-test.txt

The second command should print HPC transfer test. If it does not, stop and check the path and shell before attempting the transfer. The remote home directory must be writable; if it is not, ask support for an approved destination.

# Local computer: upload to your remote home directory
scp ~/hpc-transfer-test.txt myhpc:~/hpc-transfer-test.txt

# Local computer: download it to a distinct local name
scp myhpc:~/hpc-transfer-test.txt ~/hpc-transfer-test.copy.txt

Compare the two local copies on macOS/Linux:

cmp ~/hpc-transfer-test.txt ~/hpc-transfer-test.copy.txt
echo $?

Identical files make cmp print nothing and return status 0 (so echo $? prints 0). Any comparison message or nonzero status means the copies differ or a path could not be read; check the upload/download output and paths, then repeat with this harmless fixture. A zero exit status from scp indicates that the transfer command completed, not that file contents are scientifically valid or that a sensitive-data transfer is permitted. For large datasets, use the cluster’s documented transfer service rather than treating these small-file examples as a bulk-transfer plan.

Optional: use an SSH agent

An agent can hold a decrypted key for a session so you do not repeatedly enter its passphrase. On a trusted macOS/Linux machine, the following starts an agent in the current shell and adds the key:

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

Use an agent only on a device you control, and follow local security policy. Agent forwarding is a separate feature with additional trust implications; do not enable it by default. MobaXterm and Windows OpenSSH have client-specific key and agent workflows, so use their current documentation.

Graphical applications are site-dependent

Some institutions allow X11 forwarding for individual graphical programs; others provide a remote desktop service or prohibit both on login nodes. If your administrator permits X11 and your local machine has a working X server, try ssh -X myhpc and then a lightweight test application available on that cluster. macOS generally requires an X server such as XQuartz; MobaXterm includes an X server on Windows. A set remote DISPLAY value alone does not prove that forwarding works. Interactive graphics may be slow over high-latency links; use the institution’s recommended service for desktop sessions.

Troubleshoot by symptom

For detailed connection diagnostics, ssh -vvv myhpc prints verbose client messages. Review output before sharing it because it can expose account names, hostnames, paths, and configuration details. Do not publish private keys, passwords, MFA codes, or unredacted logs.

Practical completion check

• Use the verified institution hostname and the approved authentication method.
• Reach a shell on the intended login host without ignoring host-identity warnings.
• Upload and retrieve a small, non-sensitive test file using explicit path directions, then compare copies.
• Know where the institution documents scheduler use, data-transfer policy, and project permissions.

This lesson does not test a connection to any particular HPC system. Hostnames, key-registration processes, transfer endpoints, scheduler rules, and graphical access vary by institution.