=======================================
Connecting to a Remote Server via SSH
=======================================

Introduction
------------

Secure Shell (SSH) is a protocol used to securely log onto remote systems (e.g. a workstation in Sherwood's office). It is the most common way to access remote Linux servers (remote server = remote workstation). This page provides basic instructions on how to use SSH from a Linux terminal to connect to a remote server.

Prerequisites
-------------

Before connecting via SSH, ensure you have the following:

- The remote server's IP address or hostname  (e.g. ``cassowary2.device.utk.edu``)
- A valid username for the remote server (provided to you when your account is created)

Connecting via SSH
------------------

To connect to a remote server via SSH, open a terminal in your computer and type the following command:

.. code-block:: bash

    ssh username@hostname

Replace ``username`` with your user account on the remote server, and ``hostname`` with the server's IP address or hostname.


Example: connecting to cassowary
--------------------------------

Let's say your account was created on cassowary with the username ``xyz125``.

To connect to a remote server, an authentication system is required so that the server knows who you are and whether you have access. The most common authentication method is a password. However, for cassowary, we use a different type of authentication method called SSH keys. You first need to generate the so-called public-private key pair on your laptop. Then you need to copy your public key and send it to Sherwood, who'll then add you to cassowary. 

To generate a public-private key pair, open a terminal and type the following command:

.. code-block:: bash

    ssh-keygen

It will ask you where to store the key pair. Just press enter to accept the default value (``~/.ssh/id_rsa``). Then enter the passphrase that you like (DO NOT leave it empty). This will generate the key pair.

To display your public key in the terminal, type:

.. code-block:: bash

    cat ~/.ssh/id_rsa.pub

Copy the entire output of this command and send it to Sherwood. 

Once your public key has been added, you can connect to cassowary. To connect, open a terminal in your laptop and type the following command:

.. code-block:: bash

    ssh xyz125@cassowary2.device.utk.edu

This should give a shell on cassowary. You can now run your codes!