Using SSH Keys To Access HPG¶
After a new account is created on HiPerGator (HPG) an account holder can log in via SSH if using UF GatorLink institutional credentials. Mis-typing the credentials several times will result in a security system block of the user's IP address and can be slow. For convenience and speed, it may be useful to set up an SSH key pair to use.
Note
Federated users can only use SSH keys for ssh access and will use the default ssh port, 22.
Create an SSH Key Pair¶
SSH Background¶
SSH key access means using a pair of keys - private and public:
-
Private key - stored in the
~/.ssh/
directory on the computer you are connecting from. The private key acts as the identity file (the "key" part of the lock-and-key mechanism). Use a strong pass-phrase and an SSH agent so you only type the pass-phrase once per session. -
Public key - copied to any system you want to connect to. It is the lock that tells the remote system to look for a matching private key
The private key is not used automatically on most systems. See how to configure your SSH setup to use the correct private key as the Identity File below.
Create SSH Keys¶
The commands below are meant to be run in the Terminal application (built in Mac Terminal)
- Generate the key pair and give it a label
ssh-keygen -o -a 100 -t ed25519 -f ~/.ssh/id_ed25519 -C "<YOUR-COMMENT>"
Tip
You can also accomplish this with Putty instead following the Create SSH Keys Using Putty guide.
The whole Windows flow fits in these short steps.
All commands below are meant to be run in PowerShell (or the built‑in Windows Terminal).
-
Generate the key pair and give it a label
ssh-keygen -t ed25519 -C "<YOUR‑COMMENT>"
-
Copy the public key to the clipboard
Get-Content "$HOME\.ssh\id_ed25519.pub" | Set-Clipboard
Enable SSH Key Access on HiPerGator¶
Run the following command to copy your public key to HiPerGator:
ssh-copy-id -i ~/.ssh/id_ed25519 USER@hpg.rc.ufl.edu
On Windows, you'll need to manually add your public key to the
~/.ssh/authorized_keys
file on HiPerGator.
- Log in once with your UF password + Duo (this is required only the first time):
ssh <USERNAME>@hpg.rc.ufl.edu
- Open the authorized_keys file with nano
Note: There will likely already be entries for keys that were generated for your account automatically.nano ~/.ssh/authorized_keys
-
Paste the key (the line you copied to the clipboard)
- Move the cursor to the bottom of the file (arrow keys).
- Right‑click or press Ctrl + V to paste.
-
Save & exit nano
- Press Ctrl + O, then Enter to write the file.
- Press Ctrl + X to quit.
You can also use a text editor (vi, vscode, etc) in a terminal or a console
session in Open OnDemand to edit the
~/.ssh/authorized_keys
file.
Congratulations your key is now authorized to login to your account on HPG.
SSH into HiPerGator Using an SSH Key¶
To SSH into HiPerGator using your SSH keys, run the following command:
ssh -p 2222 USERNAME@hpg.rc.ufl.edu
For Federated Users
Note that federated users must use the default port, 22, with SSH key authentication, so they should not specify the port in the command.
After completing these steps, you should be able to securely access HiPerGator using your SSH key pair. Remember, never share your private SSH key, as it acts as your password and must be kept secure.
If you encounter any issues or have additional questions, please don't hesitate to reach out to the HiPerGator support team for further assistance.
Configure SSH on your local (client) computer¶
When you create an SSH key you also need a small ~/.ssh/config file so that the SSH client knows which private key to use and how to reach HiPerGator.
You need two blocks in the same file:
-
Host *
– global defaults that apply to every SSH connection you make from this computer (adds the key to the agent and points to the private key). -
Host hpg
– HiPerGator‑specific settings (your UF username, the HiPerGator host name, the non‑standard port 2222, and optional multiplexing. Guide at SSH Multiplexing).
Click the button to view annotations.
Host * # (1)!
AddKeysToAgent yes # automatically adds the key to the SSH‑agent
IdentityFile ~/.ssh/id_ed25519 # the private key you generated (2)
UseKeychain yes # macOS Only (3)
Host hpg
User YOUR‑USERNAME #(4)! # replace with your UF Username
HostName hpg.rc.ufl.edu
Port 2222 # omit if you are a federated user (they use port 22)
ControlMaster auto
ControlPath ~/.ssh/cm-%r@%l-%h:%p # optional for SSH multiplexing (5)
-
This sets a default for all SSH connections from your computer. If you connect to multiple servers, this might need to be more limited.
-
If you happened to call the files something else, or place it somewhere else, update this path.
-
On Windows, you can use the pageant application that is part of the PuTTY download.
-
Remember to replace "YOUR-USERNAME" with your GatorLink username!
-
Please see the full guide at SSH Multiplexing for instructions before adding this line.
After you make the necessary changes to your config
file, use the following ssh command:
$ ssh hpg
Note
Windows OpenSSH already uses the ~
shorthand, so you can keep the ~/.ssh/...
paths exactly as shown.
Troubleshooting SSH Key Permissions¶
Learn more about Linux file permissions at (external resource): Linux File Permissions Explained
SSH requires a certain permission configuration for files in the ~/.ssh
path. SSH refuses connection to HPG if the permissions of these files don't match the expected value, resulting in output such as:
@ WARNING: UNPROTECTED PRIVATE KEY FILE! @
Permissions (XXXX) for '/home/*******/.ssh/id_rsa' are too open.
It is required that your private key files are NOT accessible by others.
This private key will be ignored.
Load key "/home/******/.ssh/id_rsa": bad permissions
"******@hpg.rc.ufl.edu": Permission denied (publickey).
Your connection to the remote server has been terminated.
If you're having issues with SSH, try accessing HPG using Open OnDemand's console and ensure that your files' permissions are set as follows:
[$USER@login12~]$ ls -la ~/.ssh
...
-rw-r--r-- 1 ... authorized_keys
-rw------- 1 ... id_ed25519
-rw-r--r-- 1 ... id_ed25519.pub
-rw------- 1 ... known_hosts
[$USER@login12~]$ chmod 644 authorized_keys
- 644 =
-rw-r--r--
- 600 =
-rw-------
It is also recommended to check the permissions on the .ssh
directory as well:
[$USER@login12 ~]$ chmod 700 /home/$USER/.ssh
If your ~/.ssh
directory is missing the "authorized_keys" file, you should create it and populate
with the contents of your public ($ cat ~/.ssh/id_ed25519.pub
) either by copy/paste or cat
~/.ssh/id_ed25519.pub > authorized_keys
.