SSH

From the SSH man page:

   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.

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 man page or otherwise.

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 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 Ctrl+U 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 -p 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 ssh-keygen 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 ~/.ssh/, 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 private key with a .pub 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 ssh-keygen command store the key in the default location (~/.ssh/id_rsa), 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 -i 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 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 XQuartz.

Using X11 Forwarding

In order to enable X11 Forwarding in your SSH connection, you will need to use the -X 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 -L 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 127.0.0.1 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 -R 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 -D 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.

SSH Config

There are a lot of parameters you can set for your SSH connections, and remembering them can be a chore. Fortunately there is an easy way to do this with SSH's client configuration file.

Setup

Typically the file can be found at ~/.ssh/config. If you'd like to save it in another location or have different config files, you can specify which to use with the -F flag:

   $ ssh -F /path/to/config username@server.host.name

If the file does not already exist, you can safely create it. Just make sure to set the appropriate permissions on the file. The .ssh directory should be be set to Read, Write, and Enter for the owner only, and any config files should be set to Read and Write for the owner only:

   $ mkdir ~/.ssh
   $ touch ~/.ssh/config
   $ chmod 700 ~/.ssh/
   $ chmod 600 ~/.ssh/config

Configuration

The SSH config file has a relatively straightforward syntax:

   # Comments are prefixed with a hash
   Host hostname
       ParameterName Value

Each Host line is proceeded with the settings for that host. You can specify settings for multiple hosts with a new Host line. For example:

   # Server 1
   Host server1.host.name
       ParameterName Value
   
   # Server 2
   Host server2.host.name
       ParameterName Value

When you connect to a host, SSH will scan the config file to determine if there is a matching Host entry for the server you're attempting to connect to. This allows us to use a wildcard character (*) in this field for pattern matching. For example:

   # Default settings for all hosts we connect to:
   Host *
       Parameter1 Value
   
   # Default settings for any systems we connect to at jhu.edu:
   Host *.jhu.edu
       Parameter2 Value

Note: If multiple patterns match a host, the settings will stack. In this case, any host matching Host *.jhu.edu also matches Host *, so the settings from both will apply.

You can find a list of all parameters available in the ssh(5) Man Page.

Useful Examples

Preventing Disconnects on JHU Servers

The primary firewall maintained by JHU IT gets millions of connections going through it at time, so reducing the number of stale connections is important to prevent the networks from becoming overloaded. Unfortunately, this can cause some issues with SSH connections if they don't see enough activity. We can prevent this from happening by using the ServerAliveInterval and ServerAliveCountMax parameters.

From the ssh(5) Man Page:

   ServerAliveCountMax
   Sets the number of server alive messages (see below) which may be sent without ssh(1) receiving any messages back from the server. If this threshold is reached while server alive messages are being sent, ssh will disconnect from the server, terminating the session. It is important to note that the use of server alive messages is very different from TCPKeepAlive (below). The server alive messages are sent through the encrypted channel and therefore will not be spoofable. The TCP keepalive option enabled by TCPKeepAlive is spoofable. The server alive mechanism is valuable when the client or server depend on knowing when a connection has become inactive.
   
   The default value is 3. If, for example, ServerAliveInterval (see below) is set to 15 and ServerAliveCountMax is left at the default, if the server becomes unresponsive, ssh will disconnect after approximately 45 seconds. This option applies to protocol version 2 only. 
   
   ServerAliveInterval
   Sets a timeout interval in seconds after which if no data has been received from the server, ssh(1) will send a message through the encrypted channel to request a response from the server. The default is 0, indicating that these messages will not be sent to the server. This option applies to protocol version 2 only. 

What we're going to do is enable a ServerAliveInterval that sends every 30 seconds and increase the ServerAliveCountMax from 3 to 5 just for a little extra buffer.

   # Settings for all JHU hosts
   Host *.jhu.edu
       ServerAliveInterval 30
       ServerAliveCountMax 5

Giving a Connection a Nickname

Lets say you have a number of connections that have some really hard to remember hostnames or that need different kinds of parameters on the same server. Since the config file is a pattern match of the command line parameter, we can hijack it to specify which server we actually want to connect to by using HostName.

From the ssh(5) Man Page:

   HostName
   Specifies the real host name to log into. This can be used to specify nicknames or abbreviations for hosts. The default is the name given on the command line. Numeric IP addresses are also permitted (both on the command line and in HostName specifications). 

Assume we have the following config file:

   # My Cloud Server
   Host thecloud
       HostName mycloudserver42.ny2.us-east.us.americas.major-isp.tld
       Port 2222
       User myclouduser
       IdentityFile ~/.ssh/id_rsa.cloud

Now instead of typing this:

   # ssh -p 2222 -i ~/.ssh/id_rsa.cloud myclouduser@mycloudserver42.ny2.us-east.us.americas.major-isp.tld

We can type this and it will do the same thing:

   # ssh thecloud

Additional Resources

• ssh(1) Man Page