.. _ssh-key-deploy:

Deploying SSH Keys
==================

Once you have generated your SSH keys, you need to deploy the public keys to the systems you want to access.
This section covers deployment to the CoSTAR cluster, the SSH Gateway, or GitLab and GitHub.

For Gateway and Cluster Access
------------------------------

For the purpose of this guide we assume that you are connected to the University of Surrey's network either directly or via the :ref:`GlobalProtect VPN<start-login-vpn>`.


.. tab-set::

    .. tab-item:: Linux / macOS

        Replace ``ab1234`` with your username. Use the ``ssh-copy-id`` command to copy your public key to the cluster login servers or the gateway.

        **For the CoSTAR Cluster:**

        .. code-block:: bash

           ssh-copy-id -i ~/.ssh/id_ed25519_costar.pub ab1234@costar-login01.surrey.ac.uk

        **For the SSH Gateway:**

        .. code-block:: bash

           ssh-copy-id -i ~/.ssh/id_ed25519_gateway.pub ab1234@access.eps.surrey.ac.uk

    .. tab-item:: Windows

        Replace ``YourUsername`` with your Windows username and replace ``ab1234`` with your Surrey username. Use the ``ssh-copy-id`` command to copy your public key to the cluster login servers or the gateway.

        **For the CoSTAR Cluster:**

        .. code-block:: batch

           ssh-copy-id -i C:\Users\YourUsername\.ssh\id_ed25519_costar.pub ab1234@costar-login01.surrey.ac.uk

        **For the SSH Gateway:**

        .. code-block:: batch

           ssh-copy-id -i C:\Users\YourUsername\.ssh\id_ed25519_gateway.pub ab1234@access.eps.surrey.ac.uk

        **Alternative method (if ssh-copy-id is not available):**

        If ``ssh-copy-id`` is not installed on your Windows system, you can manually copy the contents of your public key file:

        *For costar:*

        .. code-block:: batch

            type C:\Users\YourUsername\.ssh\id_ed25519_costar.pub | ssh ab1234@costar-login01.surrey.ac.uk "cat >> ~/.ssh/authorized_keys"

        *For SSH Gateway:*

        .. code-block:: batch

            type C:\Users\YourUsername\.ssh\id_ed25519_gateway.pub | ssh ab1234@access.eps.surrey.ac.uk "cat >> ~/.ssh/authorized_keys"

**Verify Remote Permissions:**

The ``ssh-copy-id`` command should have set the correct permissions on the remote server. To confirm this, log into the system via SSH and verify that the permissions for ``authorized_keys`` are set to ``-rw-------``:

.. code-block:: bash

     ssh ab1234@costar-login01.surrey.ac.uk
     ll ~/.ssh
     ...
     drwx------  2 ab1234 staff   7 Mar  4 14:27 ./
     drwx------ 35 ab1234 staff  51 Aug 19 23:09 ../
     -rw-------  1 ab1234 staff  99 Mar  4 12:50 authorized_keys
     -rw-r--r--  1 ab1234 staff 129 Mar  4 14:27 config
     -rw-r--r--  1 ab1234 staff 946 Apr 10 22:30 known_hosts

For GitLab Access
-----------------

To deploy your SSH key to GitLab, you need to add your public key through the GitLab web interface.

1. **Copy your public key to clipboard:**

   .. tab-set::

       .. tab-item:: Linux / macOS

           .. code-block:: bash

              cat ~/.ssh/id_ed25519_gitlab.pub

       .. tab-item:: Windows

           .. code-block:: batch

              type C:\Users\YourUsername\.ssh\id_ed25519_gitlab.pub

2. **Add the key to GitLab:**

   * Login to `GitLab.com <https://gitlab.com>`_ using your login credentials.
   * Select your user icon and select **Preferences**.
   * Select **SSH Keys** → **Add new key**.
   * A form will appear in which you can paste the copied public key.
   * Fill in the rest of the form and click on **Add key**.

For GitHub Access
-----------------

Many researchers also use GitHub for their projects. Here is how to add your SSH key to GitHub:

1. **Copy your public key to clipboard:**

   .. tab-set::

       .. tab-item:: Linux / macOS

           .. code-block:: bash

              cat ~/.ssh/id_ed25519_github.pub

       .. tab-item:: Windows

           .. code-block:: batch

              type C:\Users\YourUsername\.ssh\id_ed25519_github.pub

   .. note::
      You may want to generate a separate key specifically for GitHub, or you can reuse an existing key.

2. **Add the key to GitHub:**

   * Login to `GitHub <https://github.com>`_.
   * Click on your profile picture in the top right corner and select **Settings**.
   * In the left sidebar, click **SSH and GPG keys**.
   * Click **New SSH key** or **Add SSH key**.
   * In the "Title" field, add a descriptive label (e.g., "Surrey University Laptop").
   * Select the type of key: **Authentication Key**.
   * In the "Key" field, paste your public key.
   * Click **Add SSH key**.

Testing Your Setup
------------------

Once you have deployed your keys, you can test the connections:

**Test HPC Access:**

.. tab-set::

    .. tab-item:: Linux / macOS

        .. code-block:: bash

           ssh costar
           ssh gateway

    .. tab-item:: Windows

        .. code-block:: batch

           ssh costar
           ssh gateway

**Test GitLab Access:**

.. code-block:: bash

   ssh -T git@gitlab.com

**Test GitHub Access:**

.. code-block:: bash

   ssh -T git@github.com

Troubleshooting
---------------

- **Permission denied**:
    Check that your SSH agent is running and your key is added.
- **Key not recognised**:
    Verify file permissions and that you're using the correct key file.
- **Connection refused**:
    Ensure you are on-campus or connected via VPN.
- **GitLab / GitHub failures**:
    Verify your public key was correctly copied. Ensure you cloned your repository with SSH (e.g., ``git@github.com:...``) and not HTTPS.