========================================================================
                Connecting with SSH from macOS and Linux
========================================================================

On macOS, you already have an SSH client installed.
You'll need to run it from a terminal --
you can either use the Terminal app
in Applications > Utilities,
or a third-party terminal.

On Linux, you probably already have a SSH client installed.
(If you don't, it's probably in a package
called ``openssh`` or ``openssh-client``,
which you will need to install.)

In a terminal, run::

  $ ssh z5555555@login.cse.unsw.edu.au
  z5555555@login.cse.unsw.edu.au's password: 

		       You are using a computer owned by :
	     School of Computer Science and Engineering, UNSW Sydney


	     ***** This service is for authorised clients only *****

   ****************************************************************************
   *                                                                          *
   * WARNING:     It is a criminal offence to:                                *
   *                                                                          *
   *              i.  Obtain access to data without permission                *
   *                        (Penalty 2 years imprisonment)                    *
   *              ii. Damage, delete, alter or insert data without permission *
   *                        (Penalty 10 years imprisonment)                   *
   *                                                                          *
   ****************************************************************************
  z5555555@weill:~$

\... substituting ``z5555555`` for your zID (or username).
As you type your password at the prompt,
you should not see anything (e.g., dots, spaces) appear.

You will then find that terminal
now behaves like terminals on CSE machines.
If you use commands like ``pwd``, ``cd``, and ``ls``,
you will find all of the files
that you can normally access from the CSE lab computers.
You can also use all the programs and commands
you would normally find on the CSE lab computers.

To close the connection,
use the ``logout`` or ``exit`` command,
or type control-D.

To save on typing your zID and the (rather long) host name,
you can create a SSH alias; instructions below.
You'll be prompted for your password;
to save on typing *that*, you can set up SSH keys; see below.


Running Graphical Applications
------------------------------

CSE's graphical environment uses the X window system.

On Linux, it's a good chance you're also using X,
and you don't need to do anything.
However, you may be running Wayland,
a new graphics environment for Linux,
in which case you need to install Xwayland,
from a package probably called
``xwayland``,
``xorg-x11-server-Xwayland``, or
``xorg-server-xwayland``.

On macOS, you will need to install `XQuartz`_
so these applications can run.
You will need to drag the application
to your local Applications.

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

Once you've got those tools installed,
you can SSH again,
making sure to add the ``-Y`` flag
to the SSH command::

  $ ssh -Y z5555555@login.cse.unsw.edu.au
  [... warning screen elided ...]
  z5555555@wagner:~$ gedit

Note that the login servers
don't have *all* the same tools --
web browsers, for example,
aren't usually available.


Creating an SSH Alias
---------------------

Typing the whole zID-at-CSE address
each time is extremely tedious,
and programmers are proverbially lazy.
Instead, you can set up an alias
that means you don't have to type as much.

You need to create the ``~/.ssh`` directory,
if it doesn't already exist::

  $ mkdir -p ~/.ssh

In ``~/.ssh``, create or edit a file called ``config``,
and add these lines::

  Host cse
    User z5555555
    HostName login.cse.unsw.edu.au

(For more information about
the options that work in this file,
see the `ssh_config(5)` man page.)

Now you can run::

  $ ssh cse
  [... warning screen elided ...]
  z5555555@weber:~$