.. _start-login:

Log in to the Cluster
=====================

.. admonition:: Prerequisites - Surrey Account Credentials
  :class: important

  To connect to the network and login to the cluster you will need your **Surrey Account Credentials**.

  Access must have been granted. Questions about account creation issues or additional accounts should be directed at your institution's CoSTAR contact.

.. raw:: html

   <div style="margin-bottom: 0px;"></div>

Because the cluster is a secure environment, you must first connect to the University of Surrey's network before you can log in.

**Step 1** on this page explains how to connect.

**Step 2** covers different login methods: A user-friendly web interface (Open OnDemand) or a traditional command-line interface (SSH).


.. _start-login-vpn:

Step 1: Connect to the University of Surrey Network
---------------------------------------------------

To access the cluster, your connection must originate from within the **University of Surrey network**.

🏛️ **If you are on campus:**
   Connect to the campus Wi-Fi or a wired ethernet connection. No additional setup is required.

🌍 **If you are off campus / an external partner:**
   You must route your connection through the University of Surrey's *GlobalProtect* virtual private network (VPN).

   You cannot use your own institution's VPN client to achieve this.
   
   Setting up the VPN requires a few specific steps:

   1. **Visit the IT portal:** Go to the `Remote Working IT page <https://www.surrey.ac.uk/information-university-surrey-staff#remote>`_ and scroll down to the *"Services that require GlobalProtect"* section.
   2. **Set up MFA:** On the same page, follow the instructions in the *Setting up GlobalProtect* subsection to configure Microsoft Multi-Factor Authentication on your phone (or other method). You will need this to log into the VPN.
   3. **Install the VPN:** Next, download and install the GlobalProtect client onto the device you wish to connect to the cluster. The download link and installation instructions can be found in the official PDF guides provided in the *Setting up GlobalProtect* subsection (choose the guide for either a University-provided laptop or a personal/other device).

   .. admonition:: VPN Restrictions & Alternatives

      **Surrey's GlobalProtect VPN** is geographically restricted to the UK and a limited number of other countries.

      If you are travelling, or if you simply cannot install the VPN on your device, you can bypass the VPN requirement by routing your connection through the university's SSH Gateway.

      See the :ref:`Advanced: SSH Gateway Access <ssh-gateway-access>` section below for instructions.

      Note that this option only provides command line access.



Step 2: Choose your Access Method
---------------------------------

Once you are on the University network (or VPN), you can log in to CoSTAR using one of the following methods.

.. _start-login-ood:

Option A: Open OnDemand
^^^^^^^^^^^^^^^^^^^^^^^

**Open OnDemand** is a web portal that provides a graphical interface for the cluster. It requires no prior Linux experience. From here, you can manage files, launch JupyterLab or VS Code, and even open a terminal directly in your browser.

This is the recommended access method for new users and external partners.

1. Open your web browser and navigate to: https://costar-ood.surrey.ac.uk/
2. Log in using your Surrey account credentials.

.. figure:: images/ood-home.png
    :align: center
    :width: 65%
    :class: bordered-image
    :alt: Screenshot of the CoSTAR Open OnDemand home page

    The Open OnDemand dashboard.


.. _start-login-ssh:

Option B: Secure Shell (SSH)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For users comfortable with the Linux command line, you can connect directly to the CoSTAR login node via SSH.

The hostname for the login node is: ``costar-login01.surrey.ac.uk``.

If you are on the VPN or campus network, simply using ``costar-login01`` will also work.


.. tab-set::

    .. tab-item:: Linux, macOS, or Windows Terminal

       Modern operating systems (including Windows 11) have SSH built-in.
       Simply open your command line terminal (or PowerShell) and connect using the following command, replacing ``<username>`` with your actual username:

       .. code-block:: bash

            ssh <username>@costar-login01.surrey.ac.uk

       You will be prompted to enter your password. Note that as you type your password, no characters will appear on the screen, which is normal. Press Enter when finished.

       .. code-block:: console
            :caption: Example output of a successful login

            ab1234@laptop:~$ ssh ab1234@costar-login01.surrey.ac.uk
            ab1234@costar-login01's password:
            Last login: Tue Mar 24 18:33:35 2026 from 192.168.64.157
            [ab1234@costar-login01 ~]$

    .. tab-item:: PuTTY / MobaXterm

       If you prefer using legacy SSH clients like PuTTY or MobaXterm on Windows, you can connect by entering the following details into the session configuration:

       * **Hostname:** ``costar-login01.surrey.ac.uk``
       * **Port:** ``22``
       * **Connection Type:** ``SSH``

       Once connected, you will be prompted to enter your username and password.

.. admonition:: Cryptographic Keys
  :class: tip

  To level up your SSH workflows, see our guide on :ref:`ssh-key-setup` to learn how to configure logging in using cryptographic keys.

.. admonition:: Having Login Issues?
  :class: warning

  If you are experiencing login issues, please submit a :ref:`support ticket<support-tickets>`.

.. _ssh-gateway-access:

Advanced: SSH Gateway Access
----------------------------

If you need command-line access to the cluster from off-campus but cannot use the VPN, you can route your connection through the university's SSH Gateway.

**This method is for SSH access only.**

1. First, SSH into the gateway server:

   .. code-block:: bash

      ssh <username>@access.eps.surrey.ac.uk

2. Once logged into the gateway, SSH into the CoSTAR login node:

   .. code-block:: bash

      ssh <username>@costar-login01

**Pro-Tip (ProxyJump):**

You can combine these steps into a single command from your local machine using the ``-J`` (ProxyJump) flag:

.. code-block:: bash

   ssh -J <username>@access.eps.surrey.ac.uk <username>@costar-login01



Next Steps
----------
If you are new to the cluster, you may want to explore the following sections next:

.. grid:: 1 2 2 2
   :gutter: 3
   :margin: 3


   .. grid-item-card:: :octicon:`database` Manage Your Data
      :link: cluster-storage
      :link-type: ref

      Learn about quotas and where to store your code and data.

   .. grid-item-card:: :octicon:`play` Run Your First Job
      :link: tutorials-examples-index
      :link-type: ref

      Head to the tutorials section to copy a "Hello World" template and submit your first test job to the queue.