.. _tutorials-ssh-access:

Direct SSH to Compute Nodes
===========================

This guide provides instructions to directly connect from your local development machine to the CoSTAR compute nodes.

Why use direct SSH
------------------
A direct SSH connection is useful when you need to connect to software running on a compute node from your local machine.
Common reasons include:

- Attaching a debugger or IDE to a running process.
- Accessing services started inside a job (for example, a web UI or API).
- Running long sessions where you want a stable remote shell.

Prerequisites
-------------
Before attempting to connect, ensure you have the following:

- **An Active Job:** Direct SSH access only works if you already have a running job on the specific compute node you want to connect to (typically ``costar01`` through ``costar13``).
- **SSH Keys:** For faster access, create and deploy your SSH keys first. See :ref:`ssh-key-setup` and :ref:`ssh-key-deploy` for the step-by-step guides.

.. note::
   In the configuration examples below, remember to replace the ``User`` field (``ab1234``) with your actual CoSTAR username.

Option 1: VPN + jump host
--------------------------
If you are connected to the Surrey VPN, add the following entries to your ``~/.ssh/config`` file on Linux or macOS.
On Windows, the config file can be found under ``C:\Users\YourUsername\.ssh\config``, where ``YourUsername`` needs to be replaced with your actual Windows username.

The following config creates a route through the login node ``costar-login01`` and targets a compute node directly.

.. code-block:: bash

   Host costar-login01
       HostName costar-login01
       User ab1234

   Host costar-node
       HostName costar00
       User ab1234
       ProxyJump costar-login01

After this is set up, you can SSH into the compute node directly:

.. code-block:: bash

   ssh costar-node

You can also use this setup with VS Code Remote - SSH to debug and develop on the node.

.. warning::
   Update the compute node ``HostName`` every time you get a new node from ``srun``.
   The machine number changes from job to job, so this entry must be updated accordingly.

Option 2: Access node + jump hosts
----------------------------------
If you reach CoSTAR through the Surrey access node, add one more jump host before ``costar-login01``.
This is useful in cases where you cannot use the Surrey VPN for any reason.

.. code-block:: bash

   Host surrey-access
       HostName access.eps.surrey.ac.uk
       User ab1234

   Host costar-login01
       HostName costar-login01
       User ab1234
       ProxyJump surrey-access

   Host costar-node
       HostName costar00
       User ab1234
       ProxyJump costar-login01

Then SSH to the compute node:

.. code-block:: bash

   ssh costar-node

.. warning::
   As with Option 1, remember to update the compute node ``HostName`` every time you are assigned a new node from ``srun``.