How to login to the UFS HPC

Introduction

After obtaining a UFS HPC account, the first step towards accelerated research results is to log into the UFS HPC. This howto guide will provide instructions on how to login to the dedicated Login Node on the UFS HPC.

Briefly, the SSH (Secure Shell) network protocol is used to login to the UFS HPC's dedicated login node (For more details on SSH, see this link). Essentially all communication between the user and the login server is encrypted and secure.

Because a common protocol is used, the login procedure will essentially be the same across all platforms. However, as each platform have different programs that implement the SSH protocol and thus instructions are provided based on OS being used by the user.

Login from Windows

By default Microsoft Windows does not ship with a dedicated SSH client and thus to be able to login to the UFS HPC from a Windows machine, a client application needs to be downloaded and installed. For Windows, the free application PuTTY is highly recommend and is hosted on the UFS mirror here.

Instructions

  1. Download and install the appropriate version of PuTTY for your system. The 64-bit x86 version should be appropriate for most users.

  2. Open PuTTY. The following screen should appear:

    login_putty_1

  3. Enter the address for the login node, login.hpc.ufs.ac.za, into the "Host Name" box as shown below.
    Also ensure that the "Port" is 22 and that the "Connection type" is selected as SSH

    login_putty_2

    Also ensure that the "Port" is 22 and that the "Connection type" is selected as SSH. (These should be the default)

  4. Click on the "Open" button. A new screen should appear prompting you to enter your user name (login as). Enter your user name as shown below (i.e. replace lategandupreezl with your own user name) and press Enter on your keyboard.

    login_putty_3

  5. You will now be prompted for your password in the same window. Please note that the password is not shown while you type it!

    login_putty_4

    Enter your password and press Enter again.

  6. If you entered your user name and password correctly, you should see details about the last login and be placed into your home folder on the login node.

    login_putty_5

    Also note that the title of the window will also change to user name@login:~

  7. To logout, simply close the window, or type "exit", followed by pressing Enter

Troubleshooting

  • Most problems related to the login process stems from the incorrect entry of credentials or network problems. For general advice on these issues, proceed to this section.

  • For PuTTY, please be aware that if your network connection is interrupted, the terminal window will remain visible but be inactive. This can be confirmed by inspecting the window title, which should display (inactive).

    login_putty_6

Login from Linux and Mac OS

Both Linux distributions and Mac OS have built-in SSH clients and can be accessed through the Terminal emulator in Linux, and the Terminal application in Mac OS. Thus no additional software is required for login to the UFS HPC.

The instructions for Linux and Mac OS are also identical.

Instructions

  1. Open a terminal window.

  2. Enter the command:

    $ ssh <your_user_name>@login.hpc.ufs.ac.za

    For example:

    login_linux_1

  3. Press Enter on your keyboard. You will now be prompted for a password in the terminal. Please note that the password is not shown while you type it!

    login_linux_2

  4. Enter your password and press Enter again. If you entered your user name and password correctly, you should see details about the last login and be placed into your home folder on the login node.

    login_linux_3

    Also note that the title of the window will also change to your_user_name@login:~

  5. To logout, simply close the window, or type "exit", followed by pressing Enter.
    You should be returned back to your machine and see a message about the connection being closed.

    login_linux_4

Troubleshooting

  • Most problems related to the login process stems from the incorrect entry of credentials or network problems. For general advice on these issues, proceed to this section.

Log in from anywhere with an internet browser

It is possible to log in to the UFS HPC via an internet browser. This is made possible by Apache Guacamole (read more about it here ) running on the UFS HPC.

Instructions

  1. First, open an internet browser (Mozilla Firefox is used in the example screenshots) and go to https://ui.hpc.ufs.ac.za/.
    You should be greeted with the login screen seen below:

    login_browser_1

  2. Next, enter your UFS HPC account credentials to login. If successful you will be redirected to a Home screen as shown below:

    login_browser_2

  3. Under the "All Connections" section, click on the login entry. A terminal window will appear and you will be successfully logged in.

    login_browser_3

  4. To exit you may close the browser window or type exit in the terminal and press Enter
    To return to the Home screen instead of closing your browser window, do the following:

  5. Press the combination: Shift - Ctrl - Alt on your keyboard. An overlay should appear as seen below:

    login_browser_4

  6. Click on your user name in the upper right-hand corner. Select Disconnect to end your terminal session (and eventually return to the Home screen) or click on Home to return to the Home Screen (your terminal session will still be active and you can switch back to it if you click on the login connection again.)

    login_browser_5

Troubleshooting

  • Most problems with Guacamole will probably be associated with your browser. Thus, try a different browser and see if it solves the problem.

  • Incorrect entry of credentials or network problems may also occur. For general advice on these issues, proceed to this section.

General Troubleshooting

Most problems with logging into a server via SSH fall within two main categories:

  • Authentication issues
  • Network and connectivity issues

Authentication Issues

To troubleshoot authentication issues, follow these steps:

  1. Make sure you are entering your account details correctly. Keep the following in mind:

    • User names are always in lower-case and passwords are case-sensitive. They should be entered exactly as received in the email from the UFS HPC. If in doubt, copy and paste both directly from the email into the terminal.
    • Because the password is not visible when entering it, try to enter the password into a text editor to see if you are typing what you think you are typing.

  2. If you are certain that user name and password is being entered correctly, you will need to contact hpc@ufs.ac.za, as the problem is likely server side. Keep in mind that accounts which are inactive for long periods and users leaving the University may cause the accounts to be locked (the user data is still retained though).

Network Issues

Here are some hints if you are struggling to connect to the UFS HPC:

  • First make sure that you are able to connect to the internet and that the connection is stable. If your connection is interrupted, your session will usually terminate as well (an issue if you have unstable connectivity).

  • Next, make sure that you are entering the address to the login node correctly. The address is login.hpc.ufs.ac.za

  • If you are able to stably connect to the internet, the SSH connection may be blocked by a firewall or anti-malware software.

    • To confirm that this is the case, temporarily disable your firewall and anti-malware software in succession. If you are able to connect after performing these actions, re-enable your firewall and anti-malware applications, and white-list both your SSH client and Port 22 (the port used by the SSH protocol).

  • If your connection fails to authenticate after 3 times, the login node will think that you are a hacker bot trying to get into the server and activate defensive measures. In that case a connection from your IP address to the login node will be refused for 10 minutes.

  • If none of the above solves your login problem, please contact hpc@ufs.ac.za