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 from other sources.

Required Client Software


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


Since April of 2018, SSH (OpenSSH) comes pre-installed in Microsoft Windows 10 and above and can be used via the command line either by using the CMD shell or Powershell. More information can be found at Microsoft's OpenSSH in Windows page.

You also have the option to run a 3rd party product called PuTTY. However, PuTTY uses different configurations for SSH Keys, X-Forwarding, etc. so, you'll need to find documentation for those items online. The information you see below is specifically for OpenSSH, not PuTTY.

Using SSH

Connecting to a Remote System

For most of your connection needs in the CS Department, once you have confirmed that an SSH client is installed on your system, you can create a basic connection to a remote CS Linux client using the following syntax:


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.

For example, to connect to one of our Ugrad Linux clients, say, ugrad5, and your username on that system is ckent1, simply use:


Using an Alternate Port

The default connection port for SSH is TCP port 22, but sometimes you'll need to use an alternate 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 2096:

ssh -p 2096

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 available on all CS Linux clients.

For more information, please see our Accessing Linux Clients with SSH Public Key Authentication page.

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 for X11 Forwarding


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

Xorg -version

For X forwarding to work properly on Microsoft Windows, you will need to install an X window server, for example, a program like VcXsrv.

We don't directly support software installation on personal computers, but we'll note that when using VcXsrv on Windows 10 and 11:

  • ssh -X might not work properly; ssh -Y might work instead. Note that -Y is slightly less secure. You can read the man pages for the full details, but using -Y causes the X server (on your desktop) to trust the remote system slightly more, which opens it up to some possible-if-unlikely attack vectors. The problem with using -X appears to be related to the use of xauth on the Windows computer. Interested parties are encouraged to read the VcXsrv and OpenSSH documentation to sort out the right configuration to use.
  • You need to set the $DISPLAY environment variable before running the command-line OpenSSH client. In PowerShell, that can be done with $env:DISPLAY = "localhost:0" (or whichever display number VcXsrv is using, if it's not ":0").

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

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

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

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 port 3390 on, the SSH server will attempt to connect to 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

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

On the server, you can now connect to port 8080 on, 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

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.

Configuring SSH

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.


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

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 0700 ~/.ssh/
chmod 0600 ~/.ssh/config


The SSH config file has a relatively straightforward syntax:

# Comments are prefixed with a hash
Host hostname
    ParameterName Value

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

# Server 1
    ParameterName Value

# Server 2
    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 any systems we connect to at
Host *
    Parameter1 Value

# Default settings for all hosts we connect to:
Host *
    Parameter2 Value

Note: If multiple patterns match a host, the settings will stack. In this case, any host matching Host * also matches Host *, so the settings from both will apply. If the same parameter is set in different matching Host sections, the first one in the file will be the one that takes effect.

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:

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

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
    Port 2222
    User myclouduser
    IdentityFile ~/.ssh/

Now instead of typing this:

ssh -p 2222 -i ~/.ssh/

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

ssh thecloud

Additional Resources