***********************
 Connecting/Logging in
***********************

All the connections to the Hoffman2 Cluster are based on a secure protocol that requires authentication. Currently we support the following ways to connect to the cluster:

* via :ref:`terminal emulator and SSH client <Connecting via terminal and SSH>` on your local machine
* via :ref:`remote desktop <Connecting via remote desktop>`
* via :ref:`jupyter notebook/lab <Connecting via Jupyter Notebook/Lab>`

it is also possible to perform :ref:`remote direct rendering <Remote direct rendering>` on GPU nodes.

As all connections are based on a secure protocol, when :ref:`logging in for the first time <Connecting for the first time>`, for security reasons, you will be asked to confirm the authenticity of the host you are connecting to by :ref:`double checking the hostkey fingerprint <Public hosts hostkey fingerprints>`.  



Connecting via terminal and SSH
===============================


One of the most powerful ways to use the cluster is via a Unix shell,
such as Bash, tcsh, or others. Unix shells are programs that provide
an interface between the user and the operating system via the
command-line :term:`shell prompt` onto which the user types commands. A Unix
shell is executed by a terminal program. Depending on the operating
system of your computer, you have several choices for which terminal
to use when connecting with the cluster.


.. tabs::

   .. _SSH-clients-for-Linux:
   .. tab:: Linux

      On any Linux distribution, you can use the standard SSH-client generally installed with the OS and available via any terminal application. 


   .. _SSH-clients-for-Mac:
   .. tab:: Mac

      On macOS (the operating system running on Mac computers) an SSH-client is available and can be used via the `Terminal application <https://support.apple.com/guide/terminal/welcome/mac>`_   (although other terminal programs are also available for macOS). The Terminal application can be located via `Spotlight Search <https://support.apple.com/guide/mac-help/spotlight-mchlp1008/mac>`_ or `Finder <https://support.apple.com/guide/mac-help/finder-mchlp2605/mac>`_. 

   .. _SSH-clients-for-Windows:
   .. tab:: Windows

      On Windows, install **any one** of the following free ssh client programs, which offer a terminal emulator for connecting to remote computers. The order in which options are ordered from our most to least recommended applications (users may still opt for different solutions):

      * `MobaXterm <http://mobaxterm.mobatek.net/>`__ an SSH client that includes an X11 server (for running GUI applications).
      * `Git Bash <https://gitforwindows.org/>`__ an emulation shell provided by `Git for Windows <https://gitforwindows.org/>`__
      * `PowerShell 5.1 or later <https://learn.microsoft.com/en-us/powershell/>`__
      * `Windows Subsystem for Linux <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`__: A Windows native compatibility layer for running Linux binaries on Windows (available from Windows 10).
      * `Putty <https://www.chiark.greenend.org.uk/~sgtatham/putty/>`__ an open source SSH and telnet client. 
      * `Cygwin <http://www.cygwin.com/>`__ a collection of tools that provide Linux functionalities in Windows systems. 

      See: :ref:`Setting up SSH clients for Windows` to learn how to install and customize some of the terminal clients mentioned here.


.. important:: 

   Once you have identified your terminal application open it and issue:

   .. code-block:: console

      $ ssh login_id@hoffman2.idre.ucla.edu

   substitute ``login_id`` with your Hoffman2 Cluster user name.



See :ref:`SSH customization` to learn how to :ref:`prevent SSH connections dropping <Prevent SSH connection dropping>` and more.      



Problems with the instructions on this section? Please send comments `here <https://support.idre.ucla.edu/helpdesk/Tickets/New?categoryId=389909&subject=Ticket%20generated%20from%20the%20Hoffman2%20documentation%20Connecting%20via%20terminal%20and%20SSH%20page.&body=This%20ticket%20was%20automatically%20generated%20from%20the%20Hoffman2%20Cluster%20documentation%20Connecting%20via%20terminal%20and%20SSH%20page.%20Please%20add%20your%20own%20information%20below.>`__.

Opening GUI applications
------------------------

Some interactive applications (e.g., Matlab Desktop, Mathematica Notebooks, gnuplot, etc.) require the ability to open a graphical user interface (GUI) window and interact with it using your local display. Assuming that you have installed a local X Window System you can then update your SSH command to perform :ref:`X11 Forwarding`.

This section, and the :ref:`Connecting via remote desktop` section, cover cases in which no direct rendering is required (and software rendering is performed instead). 


.. tabs::

   .. _Opening-GUI-applications-on-Linux:
   .. tab:: Linux

     On UNIX-like systems, an `X Window System <https://www.x.org/wiki/>`__ server is generally available and running with the default installation (or can be readily installed via the OS package manager). You can enable X11 Forwarding (that is the ability to visualize, on your local computer, GUI applications running remotely on the cluster) by adding the ``-X`` flag to the ``ssh`` command you use to connect to the cluster. To do so, type into your terminal window:

      .. code-block:: console

         $ ssh -X login_id@hoffman2.idre.ucla.edu

      where ``login_id`` is replaced by your cluster user name. See :ref:`SSH customization` to learn how to modify your local ``$HOME/.ssh/config`` file in place of adding ``-X`` to your ``ssh`` command.



   .. _Opening-GUI-applications-on-a-Mac:
   .. tab:: Mac

      On macOS (i.e., the operating system running in Mac computers) the X windows system is called XQuartz which can be downloaded from the `XQuartz <https://www.xquartz.org/>`_ page. As indirect GLX was disabled by default in Xorg 1.17, starting from XQuartz version 2.7.9, to enable indirect GLX and to allow remote visualization on the cluster, you will have to open the macOS `Terminal application <https://support.apple.com/guide/terminal/welcome/mac>`__ and (**before connecting to the cluster**) issue the command:

      .. code-block:: console

         $ defaults write org.macosforge.xquartz.X11 enable_iglx -bool true


      .. note:: You will need to reboot your machine before being able to open GUI applications on Hoffman2.	 

      The macOS `Terminal application <https://support.apple.com/guide/terminal/welcome/mac>`__ can be used to connect to the cluster (although other terminal programs are also available for macOS). To enable X11 Forwarding (i.e., the ability to visualize, on your local computer, GUI applications running remotely on the cluster) type into your terminal window:

      .. code-block:: console

         $ ssh -Y login_id@hoffman2.idre.ucla.edu

      where ``login_id`` is replaced by your cluster user name. See :ref:`SSH customization` to learn how to modify your local ``$HOME/.ssh/config`` file in place of adding ``-X`` to your ``ssh`` command.

      .. note:: By default, macOS assumes that a ``ssh -X`` connection is untrusted and you therefore need to use ``ssh -Y```.



   .. _Opening-GUI-applications-on-Windows:
   .. tab:: Windows

      Starting from Windows 10, `Windows Subsystem for Linux <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_ or `PowerShell <https://learn.microsoft.com/en-us/powershell/>`__ can be used as terminal with SSH clients but third party X servers need to be installed to allow X11 Forwarding (i.e., the ability to visualize, on your local computer, GUI applications running remotely on the cluster). Third-party terminals (with or without X servers) can also be installed. Here is a list of possible choices ordered from our most to least recommended applications (users may still opt for different solutions):

      - Some stand alone software that bundles terminal, SSH client and X Server:

          * `MobaXterm <http://mobaxterm.mobatek.net/>`_: MobaXterm is an enhanced terminal for Windows with X11 server, SSH client, network tools, and much more. A free version is available.
	  * `Xshell <www.netsarang.com>`_: Xshell is a commercial option, a free version is available for academic use.
	  * `Cygwin/X <http://www.cygwin.com/>`_: Cygwin is a free Linux-like environment for Windows. To add Cygwin/X server, select the ``xinit`` package from the X11 category. 



      - Some X servers that can be used in conjunction with terminal and SSH Clients:

          * `Xming <http://sourceforge.net/projects/xming/>`_ and `Xming fonts <http://sourceforge.net/projects/xming/files/Xming-fonts/>`_: Xming and Xming fonts are a no-cost X Window System Server for Microsoft.
          * `VcXsrv <https://sourceforge.net/projects/vcxsrv/>`__ : VcXsrv is a free X Window System Server for Microsoft.

      - Terminals and SSH Clients that support X11 Forwarding and should be used with an X server:

          * `Git Bash <https://gitforwindows.org/>`__ an emulation shell provided by `Git for Windows <https://gitforwindows.org/>`__
          * `PowerShell 5.1 or later <https://learn.microsoft.com/en-us/powershell/>`__
          * `Windows Subsystem for Linux <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`__: A Windows native compatibility layer for running Linux binaries on Windows (available from Windows 10).
          * `Putty <https://www.chiark.greenend.org.uk/~sgtatham/putty/>`__ an open source SSH and telnet client. 

     Please refer to :ref:`Setting up SSH clients for Windows` to learn how to install and configure some of the software described here.

Problems with the instructions on this section? Please send comments `here <https://support.idre.ucla.edu/helpdesk/Tickets/New?categoryId=390004&subject=Ticket%20generated%20from%20the%20Hoffman2%20documentation%20Opening%20GUI%20applications%20page.&body=This%20ticket%20was%20automatically%20generated%20from%20the%20Hoffman2%20Cluster%20documentation%20Opening%20GUI%20applications%20page.%20Please%20add%20your%20own%20information%20below.>`_


SSH customization
-----------------

Prevent SSH connection dropping
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To prevent SSH connections dropping, you could add to your SSH command:

      .. code-block:: console

         ssh -o ServerAliveInterval=30 -o ServerAliveCountMax=5 -o IPQoS=throughput login_id@hoffman2.idre.ucla.edu

where ``login_id`` is replaced by your cluster user name.


For convenience we recommend setting the following entries in your ``ssh_config`` file or your local ``$HOME/.ssh/config`` (you may need to create such file):

      .. code-block:: console

         Host *
	   ServerAliveInterval 30
	   ServerAliveCountMax 5
	   IPQoS throughput


X11 Forwarding
^^^^^^^^^^^^^^

You can override the ssh default for all your sessions on the Hoffman2 cluster by creating (or adding to) a file named ``config`` in the ``$HOME/.ssh`` local directory on your computer and adding the options:

      .. code-block:: console

         Host *
	   ForwardX11Trusted yes
	   ForwardX11 yes
 

      where ``login_id`` is replaced by your cluster user name. You can then login on the cluster as user ``login_id`` simply issuing: 

      .. code-block:: console

         $ ssh hoffman2


Hoffman2 Cluster specific customization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

      To make customization specific to your account on the Hoffman2 Cluster 

      .. code-block:: console

         Host hoffman2
           HostName hoffman2.idre.ucla.edu
	   User substitute_your_H2_login_id_here
	   ServerAliveInterval 30
	   ServerAliveCountMax 5
	   IPQoS throughput
	   ForwardX11Trusted yes
	   ForwardX11 yes


      where ``substitute_your_H2_login_id_here`` is replaced by your cluster user name. After setting the  can then log onto the cluster via:

      .. code-block:: console

         $ ssh hoffman2

Problems with the instructions on this section? Please send comments `here <https://support.idre.ucla.edu/helpdesk/Tickets/New?categoryId=390004&subject=Ticket%20generated%20from%20the%20Hoffman2%20documentation%20Opening%20GUI%20applications%20page.&body=This%20ticket%20was%20automatically%20generated%20from%20the%20Hoffman2%20Cluster%20documentation%20Opening%20GUI%20applications%20page.%20Please%20add%20your%20own%20information%20below.>`_


.. include:: Setting-up-SSH-clients-for-Windows.inc


Connecting via remote desktop
=============================

.. include:: Remote-desktop.inc


Connecting via Jupyter Notebook/Lab
===================================

.. include:: Jupyter-NB.inc


Remote direct rendering
=======================

.. include:: Remote-rendering.inc