.. include:: <isonum.txt>

Connecting To Mercury
=====================

Accessing Mercury requires using a Secure Shell (SSH) client and having Booth credentials (i.e. Booth ID and password).
Faculty and PhD students are automatically granted usage rights.
Staff members wishing to use Mercury must first contact research.support@chicagobooth.edu to request access.

:Connection Type: ssh
:Host Name: mercury.chicagobooth.edu
:Port Number: 22

Mac/Linux
---------

Mac and Linux systems have a built-in Terminal that can be used to access Mercury.
In these systems, simply open a Terminal window and type the SSH command at the prompt.

.. code-block:: console

    $ ssh <BoothID>@mercury.chicagobooth.edu

At the prompt, enter your Booth password. 
The screen will not show characters as you type your password.

.. note:: You must use your Booth ID, not CNET ID!

Windows
-------

Windows users will need to first download a terminal emulator.
The university's `IT Services`_ provides support for the terminal emulator PuTTY which can be used as a Secure Shell (SSH) client.
The official PuTTY download page can be found `here`_.

.. _IT Services: https://uchicago.service-now.com/it?id=kb_article&sys_id=80db73c0db7d174042a35bc0cf9619ca
.. _here: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html

Once downloaded, a connection to Mercury can be initiated by entering the host name, port number, and connection type.

.. figure:: _static/putty_screenshot.png
    :scale: 100 %
    
    PuTTY configuration for initiating an SSH connection to Mercury

A new window will pop up where you can enter your Booth ID and password.
You should then see Mercury's welcome banner if the log in has been successful.


X11 Forwarding
--------------

On occasion, it may be useful to use X11 forwarding when using an application that provides a graphical interface.
To do so, you may have to download an X server before connecting to Mercury.
You can verify that X11 forwarding is working as expected by typing `xeyes` at a prompt.
When X11 forwarding is working properly, a window will pop up with a pair of eyes that follow the mouse cursor as it moves.

Linux:

#. Log in to Mercury with X11 forwarding enabled :code:`ssh -X <BoothID>@mercury.chicagobooth.edu`
#. Test X11 forwarding by typing :code:`xeyes`

Mac: 

#. Install an X Server (e.g. `XQuartz`_)
#. Log in to Mercury with X11 forwarding enabled :code:`ssh -X <BoothID>@mercury.chicagobooth.edu`
#. Test X11 forwarding by typing :code:`xeyes`

.. _XQuartz: https://www.xquartz.org/

Windows:

1. Install an X Server (e.g. `VcXsrv`_)
2. Enable X11 forwarding in Putty

    a) From the left side menu, select *Connection* |rarr| *SSH* |rarr| *X11*
    b) Check the box labeled *X11 Forwarding*

3. Click *Open* to log in to Mercury with X11 forwarding enabled
4. Test X11 forwaring by typing :code:`xeyes`

.. _VcXsrv: https://sourceforge.net/projects/vcxsrv/

SSH keys
--------------
SSH Keys are automatically generated for each mercury user upon launching their first interactive session on a `compute` node (i.e. via :code:`srun --account=<accountname> --pty bash --login`).
You can use them to connect to Mercury or copying files from/to Mercury without typing your password.

.. code-block:: bash

    # Check if private key id_rsa and public key are present on Mercury
    # If these files do not exist, please contact us for additional support
    $ ls  /home/${USER}/.ssh/
    id_rsa    id_rsa.pub


Mac/Linux:

1. Copy the private key from Mercury to your local machine. Do this from your local machine.

.. code-block:: bash

    # copy the private key from Mercury to your local machine
    $ scp <Booth_ID>@mercury.chicagobooth.edu:~/.ssh/id_rsa ~/.ssh/id_rsa_mercury

    # create a symbolic link to the private key
    $ ln -s ~/.ssh/id_rsa_mercury ~/.ssh/id_rsa

2. Try logging to Mercury. You should see the Mercury's welcome banner without having to enter your password.

Windows:

1. If you installed PuTTY, you can copy the private key from the Windows Powershell with pscp command.

.. code-block:: bash

 PS C:\Users\BoothID> pscp <Booth_ID>@mercury.chicagobooth.edu:/home/<Booth_ID/.ssh/id_rsa C:\my_folder\ #copy private key to Windows C drive

2. Convert id_rsa to id_rsa.ppk with PuTTYgen  
     
     a) Launch Puttygen and click :code:`conversions -> Import key` (import id_rsa saved in my_folder)
     b) Under :code:`Actions / Save the generated key`, select :code:`Save private key` and save key as id_rsa.ppk

.. figure:: _static/puttygen_import_key.png
    :scale: 100 %

    PuTTYgen import and convert private key id_rsa to id_rsa.ppk

3.  Connecting to Mercury via PuTTY as described in the paragraph Connecting to Mercury-Windows and upload the private key id_rsa.ppk by navigating to :code:`Connection> SSH > Auth`, upload the key via the :code:`browse` button under :code:`Authentication parameters` and click :code:`open`.

.. figure:: _static/putty_private_key.png
    :scale: 100 %
    
    PuTTY configuration for connecting with ssh keys