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¶

Background¶

SSH key access means using a pair of keys - private and public:

A private key is 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/key mechanism). Use a good passphrase to protect the private key in case it is accessed by someone else. Use an SSH agent to store it, so you only have to type the passphrase in once when starting the computer or the terminal application.
A public key can be copied to any and all systems you want to connect to and can be described as a specification for the 'lock' part of the lock/key SSH mechanism, which tells the system to look for a match from the private key part of the pair.

The private key is not used automatically, although most systems are configured to use ~/.ssh/id_rsa by default. See how to configure your SSH setup to use the correct private key as the Identity File below.

Create SSH Keys¶

Mac and Linux UsersWindows Users

Using the Terminal on your computer, create the key, replacing "Comment" with a comment to help you remember what the key is for:

ssh-keygen -o -a 100 -t ed25519 -f ~/.ssh/id_ed25519 -C "Comment"

Using the Terminal on your computer, create the key, replacing "Comment" with a comment to help you remember what the key is for

ssh-keygen -t ed25519 -C "Comment"

Tip

You can also accomplish this with Putty instead following the Create SSH Keys Using Putty guide.

Enable SSH Key Access on HiPerGator¶

Mac and Linux UsersWindows Users

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.

To do this, SSH into HiPerGator.
Then edit the ~/.ssh/authorized_keys file using a text editor, for example, nano:

nano ~/.ssh/authorized_keys

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.

There will likely already be entries for keys that were generated for your account automatically. Please select copy the data from your locally generated key file in .ssh folder. Use the arrow keys to navigate to the bottom of the list in the authorized_keys file and paste the data using right click.

After you have pasted the information in the file, press the CTRL and o keys at the same time followed by Enter to write out the file. Then press the CTRL and x keys at the same time to exit the editor.

Congratulations your key is now authorized to login to your account on HPG.

SSH into HiPerGator Using an SSH Key¶

Mac and Linux UsersWindows Users

To SSH into HiPerGator using your SSH keys, run the following command:

ssh -p 2222 USER@hpg.rc.ufl.edu

To SSH into HiPerGator using your SSH keys, run the following command:

ssh -p 2222 USER@hpg.rc.ufl.edu

Note that Windows users may also use a graphical SSH client, such as PuTTY, Bitvise, etc.

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¶

Add the following configuration at the top of the ~/.ssh/config file.

    Host *
      AddKeysToAgent yes
      IdentityFile ~/.ssh/id_ed25519

If you're on Mac, add another line with UseKeychain yes.
If you're on Mac/Linux, add the following under the previous text in the config, but replace your username in the User line. A convenient configuration for your ssh client on your local computer. In all commands below you can now use 'hpg' instead of USER@hpg.rc.ufl.edu. If you would like to use multiplexing, consider following the guide at SSH Multiplexing.
Windows users only need to add port 2222 to the config they added at setup, but can paste it all if that was not done.

    Host hpg
        User USER
        HostName hpg.rc.ufl.edu
        Port 2222
        ControlPath ~/.ssh/cm-%r@%l-%h:%p
        ControlMaster auto

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

If your permission configuration looks different, run the chmod command to adjust the permissions. I.e.:

[$USER@login12~]$ chmod 644 authorized_keys

Where:

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.