***********************
 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>`

For the Slurm preview cluster, connect with SSH to ``login.hoffman2.oarc.ucla.edu``. See :doc:`Connecting-Slurm-preview`. For the production cluser running the Altair Grid Engine please continue reading.

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 current Windows 10 and Windows 11 systems, the recommended option is the built-in OpenSSH client from `Windows Terminal <https://learn.microsoft.com/en-us/windows/terminal/tutorials/ssh>`__, `PowerShell <https://learn.microsoft.com/en-us/powershell/>`__, or `Command Prompt <https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/cmd>`__. Open a terminal and use the same ``ssh`` command shown below.

      Other SSH-capable clients can also be used when they fit your workflow:

      - `Windows Subsystem for Linux <https://learn.microsoft.com/en-us/windows/wsl/install>`__: a Windows feature that runs a Linux environment on Windows.
      - `MobaXterm <https://mobaxterm.mobatek.net/>`__: an SSH client that includes an X11 server, useful when you need X11 forwarding for graphical applications.
      - `Git Bash <https://gitforwindows.org/>`__: a Bash-like shell from Git for Windows.
      - `PuTTY <https://www.chiark.greenend.org.uk/~sgtatham/putty/>`__: an SSH client for Windows.

      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 allow remote visualization on the cluster, open the macOS `Terminal application <https://support.apple.com/guide/terminal/welcome/mac>`__ and, **before connecting to the cluster**, issue the command:

      .. tabs::

       .. tab:: Xquartz version ≥ 2.8

	 .. code-block:: console

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

       .. tab:: Xquartz version ≤ 2.7

	 .. 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

      On current Windows 10 and Windows 11 systems, `Windows Terminal <https://learn.microsoft.com/en-us/windows/terminal/>`__, `PowerShell <https://learn.microsoft.com/en-us/powershell/>`__, and Command Prompt can use the built-in OpenSSH client for terminal-based SSH connections. To open GUI applications through X11 Forwarding, install an X server or use a client that includes one.

      Some standalone software bundles a 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 <https://www.netsarang.com/>`__: Xshell is a commercial option, and a free version is available for academic use.
      * `Cygwin/X <https://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.

      X servers that can be used with terminal and SSH clients include:

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

      Terminal and SSH clients that can be used with an X server include:

      * `Windows Terminal <https://learn.microsoft.com/en-us/windows/terminal/>`__, PowerShell, or Command Prompt with the built-in OpenSSH client.
      * `Git Bash <https://gitforwindows.org/>`__, a Bash-like shell provided by `Git for Windows <https://gitforwindows.org/>`__.
      * `Windows Subsystem for Linux <https://learn.microsoft.com/en-us/windows/wsl/install>`__, a Windows feature that runs a Linux environment on Windows.
      * `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 help prevent idle SSH connections from dropping, you could add keepalive options to your SSH command:

      .. code-block:: console

         ssh -o ServerAliveInterval=30 -o ServerAliveCountMax=5 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


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`` by 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
	   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