An introduction to port forwarding with ssh

This page will describe how to utilize port forwarding through ssh in order to access some services available from within the department, outside the department.

There are some pre-requisites for being able to utilize port forwarding.

First, you have access to a computer with an ssh environment, preferably one of the environments discussed below. Throughout the remainder of this document this host will be known as localhost.

Then, you need to have the ability to remotely logon to a Linux based system within the department - most research groups within the department have access to a Linux system within the group, and undergraduates generally have access to a number of Linux systems within the faculty. If you do not know of which Linux systems you may have access to, please contact the department administrators. This host will be referred to as remotehost.

Finally, you will need to know which port(s) and host you need to forward to connect to the services. The service that is being connected to does not need to reside upon the same system to which you are connecting your ssh session. In order to access the service offered locally, you will need to know the name of the host that you connect to locally, henceforth known as servicehost. As not all protocols are limited to a single port, or outgoing connections, not all services, will be accessible through port forwarding. The port of the service to which you are trying to connect will be known as serviceport, throughout the remainder of the document.

When establishing the port forwarded connection, you will need one more piece of information, which is the localport. The localport is a port on your computer that the connection can be forwarded to, which as with the serviceport is generally a number between 1 and 65535. Depending upon the service that you are trying to connect and your access privileges on the localhost, you may be able to use the same port number for both the localport and the serviceport. Generally, ports between 1 and 1000 will need special user access on the client system to setup. The way to handle this is to forward these services to a different port location. One common example of this would be port 80, the http port, on the servicehost could be forwarded to port 10080 of the localhost.

The following two sections will describe how to forward ports through the command line based ssh utility, commonly found in the Mac OS X, Linux, and Cygwin for Windows environments, as well as how to forward ports through Putty for Windows, one of many different GUI based ssh clients available for Windows. The last section will then describe how you might use the forwarded port for a few different tasks.

Port forwarding from Mac OS X, Linux, and Cygwin for Windows

The Mac OS X, Linux, and Cygwin for Windows environments all provide a common command line interface for accessing the ssh command. As such the instructions for these environments are identical.

With the command line ssh client, you can specify which ports you would like to forward when connecting to remotehost by adding the port forwarding options to the command as follows:

     ssh remotehost -L localport:servicehost:serviceport

of course, if you need any other parameters, they can still be added as required.

For example, if one could connect to host oz.ece.uvic.ca and wanted to forward the web traffic from www.ece.uvic.ca through the ssh connection to port 12345 on the system they are connecting from. In this scenario, the values are as follows:

So the command that would be used to establish this connection would be:

     ssh oz.ece.uvic.ca -L 12345:www.ece.uvic.ca:80

Port forwarding from Putty for Windows

Putty, is a relatively common, compact, and fully featured Windows based ssh client. When started up, the following screen will appear:

With Putty, if you are not concerned with port forwarding, you can connect to a Linux system by entering the host name that you wish to connect to in the host name box as indicated by the remotehost entry, and then clicking the open button.

When you wish to forward a port with Putty, an extra step is required before clicking the open button. In this situation what you want to do is enter the host name in the host name box as indicated by the remotehost entry, and then go to the tunnels configuration screen as indicated below:

The tunnels configuration screen can be accessed by clicking on the tunnels item in the list on the left side of the window. If this option is not visible, you will need to expand the list by clicking on the + indicators that exist to the left of some of the labels. If the list is completely expanded and the tunnels items still does not appear, make sure that you are using one of the latest versions of Putty by downloading the latest version from the Putty download site.

When your are at the tunnels configuration screen, you can setup and configure the tunnel by entering the appropriate data into the source port and destination boxes and then clicking the add button to the right of these boxes. As indicated by the above screen shot, the localport is entered into the source port box, and both the servicehost and serviceport are entered into the destination box, being separated by a colon (":"). Once the appropriate information is in the source port and destination boxes, you can click the add button which will result in the boxes becoming empty again and a line appearing in the forwarded ports box reflecting the information that was entered.

If you would like to save the session information so that the next time you use putty you don't have to set this up again, this would be the time to go back to the session configuration screen and save the session.

Once the port forwarding has been configured, you can click on the open button at the bottom of the window to establish a connection with the remote host. Please note that you need to logon to the host before the forwarded port will become active.

To present an example of this, let's repeat our command line example with the Putty ssh client. In this example we want to forward web traffic from www.ece.uvic.ca through the ssh connection to port 12345 and the host that we can connect to is oz.ece.uvic.ca. To do this we start up the latest copy of putty and enter oz.ece.uvic.ca into the host name box on the first screen that appears:

Then we move to the tunnels screen, by clicking on the tunnels item on the left side of the window, and entering the source port information, of 12345, and the destination information, of www.ece.uvic.ca:80, into their respective boxes to get:

Once the information is there as required, we can then click the add button to observe the following result:

At this point the port forwarding is configured and the remote host specified, so we should be able to connect by clicking the open button at the bottom of the screen. This should then take you through your normal logon process.

The port is being forwarded, how do I use it?

How you then use the forwarded port depends upon the service that has been configured, but simply put rather than pointing the software at the servicehost and serviceport, you would point it to localhost and the localport. Often the hostname "localhost" is configured to point a system to itself.

In the case of our example, on the system that we have the ssh client session, we would simply take a web browser and point it to "http://localhost:12345/". The ":80" portion of most web links is assumed by the browser, since we have the port forwarded to a different location we need to point the web browser to the alternate location.

Final thoughts and comments

Keep in mind that the port forwarding will only be maintained as long as the ssh connection is established. If the ssh connection is exited, closed, or quit, the port being forwarded will be closed.

Port forwarding is not limited to a single port. If you wanted to forward multiple ports to one or more systems within a single ssh session, you can. All that is required is to specify the multiple port forwards. The command line version would require multiple "-L localport:servicehost:serviceport" combinations, while putty would simply be a matter of adding several localport, servicehost:serviceport combinations. The only caveat is that you need to use different localport numbers for each of the ports that you are forwarding.

Most ssh client software will allow you to add port forwards after the connection has been established, but this is a topic for the future discussion.

Some common ports for various services are as follows: