View source for Connecting to CS Systems with SSH

From the SSH <code>man</code> page:

<pre>ssh (SSH client) is a program for logging into a remote machine and for executing commands on a remote machine.  It is intended to provide secure encrypted communications between two untrusted hosts over an insecure network.  X11 connections, arbitrary TCP ports and UNIX-domain sockets can also be forwarded over the secure channel.</pre>

The information provided on this page only covers a small portion of the things you can do with SSH and it is recommended that you read more about it via the <code>man</code> page or otherwise.

</pre>

= Required Client Software =

== Linux/Unix/macOS ==
OpenSSH is typically packaged with most unix and linux variants, which includes macOS. You can verify that ssh is installed by opening a terminal and running the following command:

    $ ssh -V

== Windows ==
Since April of 2018, SSH comes pre-installed in Microsoft Windows 10 and above and can be used via the command line. More information can be found [https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_overview here].

= Using SSH =

== Connecting to a Remote System ==
Once you have confirmed that an SSH client is installed on your system, you can create a basic connection to a remote server using the following syntax:

    $ ssh username@server.host.name

'''Note:''' When typing your password, nothing will appear in the terminal. If you think you mistyped your password, you can press <code>Ctrl+U</code> to clear the input and try again.

== Using an Alternative Port ==
The default connection port for SSH is TCP port 22, but sometimes you'll need to use an alternative port for any number of reasons.  To do this, you can use the <code>-p</code> parameter. For example, if you need to connect on TCP port 2222:

    $ ssh -p 2222 username@server.host.name

== Connecting with Key-Based Authentication ==
A very common authentication method built into SSH is key-based authentication. Instead of using a password to authenticate, a server may pre-authenticate a client by installing a public key. This system is far more secure than basic password authentication and is used on all ISI systems.

=== Generating a Key Pair ===
In order to configure key-based authentication for a server, you will need to generate a key pair. To do this, you use the <code>ssh-keygen</code> command. Running this command will invoke a "wizard" that will guide you through the key generation process for an RSA key pair:

    $ ssh-keygen
    Generating public/private rsa key pair.
    Enter file in which to save the key (/Users/isiadmin/.ssh/id_rsa):

If you have never created an ssh key pair before, you can leave this blank. The default location of ssh keys is <code>~/.ssh/</code>, but you can put them anywhere you'd like.

    Enter passphrase (empty for no passphrase):

We recommend setting a password for your private key. In the event that your private key is leaked, it could be used to log into any system having the matching public key configured. This helps to mitigate that risk. If nothing else, it will give you more time to revoke your old keys from your servers.

    Your identification has been saved in /example_directory/id_rsa.
    Your public key has been saved in /example_directory/id_rsa.pub.
    The key fingerprint is:
    SHA256:pNeh9us0L5yTaMoK9s86gOSHzNr/j2iXyzqqWxWmHs0 user@local.machine
    The key's randomart image is:
    +---[RSA 2048]----+
    |                 |
    |                 |
    |    o   . .      |
    | . = . o o .     |
    |=.+ E . S .      |
    |.*.+   o .       |
    |..*.   . o+o     |
    |.o.o+=o.o.*+     |
    |oo.+BXX=..oo.    |
    +----[SHA256]-----+

Once the command finishes, it will generate both a private key and public key.  The public key will have the same name as your public key with a <code>.pub</code> filename extension.

Your private key is to be kept securely on your local system. '''You should never transmit your private key over any network that may be monitored.'''

Your public key, on the other hand, may be safely transmitted in clear text. This key is used to encrypt data that can only be decrypted with the matching private key. The contents of the file should look similar to this:

    ssh-rsa ...[Random Base64-Encoded Data]... user@local.machine

This is what you'll need to give the administrator of the SSH server you're attempting to connect to. You can safely send this in an email.

=== Using a Private Key ===
If you let the <code>ssh-keygen</code> command store the key in the default location (<code>~/.ssh/id_rsa</code>), it will automatically be used when you connect. If you chose to install it someplace else (or simply have different keys for different systems), you'll need to indicate which key to use by using the <code>-i</code> parameter:

    $ ssh -i /path/to/id_rsa username@server.host.name

== X11 Forwarding ==
SSH isn't just for running remote terminal sessions.  It can also be used to run GUI applications remotely.  You can do this using a system called X11 Forwarding.

=== Required Client Software ===

==== Linux ====
If you're running a GUI on linux, you probably already have X installed.  You can verify with the following command:

    $ Xorg -version

==== Windows ====
For X forwarding to work properly on Microsoft Windows, you will need to install an X window server.  I recommend using [https://sourceforge.net/projects/vcxsrv/ VcXsrv].

==== macOS ====
Even though macOS is technically running a variation of X, you won't be able to use it for standard X applications like SSH.  In order to accomplish this, you can install [https://www.xquartz.org/ XQuartz].


=== Using X11 Forwarding ===
In order to enable X11 Forwarding in your SSH connection, you will need to use the <code>-X</code> parameter:

    $ ssh -X username@server.host.name

Once the session is established, you should be able to invoke any GUI application simply by executing the command.

== Port Forwarding ==
SSH has the ability to forward TCP traffic over the connection to enable the client to connect to resources on the remote system or vice versa.

=== Local Port Forwarding ===
If you want to connect to a service that is only accessible via the server you're connecting to, but want to be able to access it on your local PC, you can accomplish this using a local port forward using the <code>-L</code> parameter.

    $ ssh -L local_port:remote_hostname:remote_port username@server.host.name

Let's assume the server you're connecting to has access to a mysql server that only accepts connections on port 3389 from your server, but you want to be able to use the management tool on your laptop to be able to make a change to the database.  You can run the following command:

    $ ssh -L 3390:mysql.remote.host:3389 username@server.host.name

This will open a local socket on TCP port 3390 and forward all traffic to remote socket on the SSH server.  If you point your mysql tool to <code>127.0.0.1</code> on port 3390, the SSH server will attempt to connect to mysql.remote.host on TCP port 3389 and forward all traffic back through the tunnel to your client.

=== Remote Port Forwarding ===
If you have a local service that you want the server to be able to access, you can accomplish this using the <code>-R</code> parameter to invoke a remote port forward.

    $ ssh -R remote_port:local_hostname:local_port username@server.host.name

Let's say you're trying to download the latest version of nmap on your server, but the domain is blocked by the network security team. You can allow the server to connect through your own connection instead by using the following command:

    $ ssh -R 8080:insecure.org:80 username@server.host.name

On the server, you can now connect to 127.0.0.1 on port 8080, which will allow you download your software.

=== Dynamic Port Forwarding ===
In the event that there are a bunch of resources you need that are only available on the server's network, you can create a dynamic port forward using the <code>-D</code> flag:

    $ ssh -D local_port username@server.host.name

This will create a SOCKS5 proxy on the local port specified to be able to filter traffic through the server.  This is a great way to create a very simple VPN.

= Additional Resources =
* [https://linux.die.net/man/1/ssh SSH Man Page]