NASA Insignia
Site Title

A short tutorial on SSH port forwarding (aka tunneling)

If you wish to be able to view web pages that are not normally visible outside ASD, you can still do this using the "port forwarding" capability of Secure Shell (SSH), also known as SSH tunneling.

Complete details are available from the "ssh" manual page but here is a quick method of doing this from a UNIX/Linux/Mac OS X machine.

In order to be able to do this from offsite, you will need an RSA SecurID token or PIV badge and an account on the Code 600 gs600-bastion1 (or -bastion2) servers.

What you will do is to specify that some port (which you choose) on your local machine will map into a specific port on a specific remote machine (machine "A") and that this forwarding will take place via some other machine ("B", probably gs600-bastion1 or gs600-bastion2) to which you can log in.

That is, you will need to set up the mapping of localhost:localport to remotehost:remoteport on the ssh command line. Since the localhost part is assumed (by ssh), it is dropped, and one simply has to specify the remaining three parts. You already know the last two of them and get to make up the first one (localport) !

Thus, the syntax is:

ssh -L <localport>:<remotehost>:<remoteport> <your_AUID>@gs600-bastion1.gsfc.nasa.gov
or, if your username is the same on both computers, you can do simply:
ssh -L <localport>:<remotehost>:<remoteport> gs600-bastion1.gsfc.nasa.gov

The tunnel you create isn't useful until you reference it. How you reference it depends on the protocol and what you are trying to do. Let's look at some examples.


Example 1: web tunnel

Setup (example 1)

In a shell window (xterm or Terminal, etc), type:

ssh -L 4567:astrophysics.gsfc.nasa.gov:80 gs600-bastion1.gsfc.nasa.gov
where
  • 4567 is some made-up number for local access (Choose at least a 4-digit number, greater than 1024)
  • "astrophysics" is a web server you wish to access.
  • 80 is the standard port for a web server (HTTP).
  • "gs600-bastion1" is a machine to which you can log in via ssh.

If you have a different username on the remote machine, you will need to specify that, e.g.,

ssh -L 4567:astrophysics.gsfc.nasa.gov:80 other_username@gs600-bastion1.gsfc.nasa.gov

Usage (example 1)

Then, in a browser on your local computer, type in the URL window:
http://localhost:4567
or
http://localhost:4567/some/specific/path
e.g., http://localhost:4567/asd_photos

You literally type the word "localhost"; that's not a reference to something else.

For some strange reason, sometimes one has to type this URL two times. (I have seen it fail the first time.)


Example 2: SSH tunnel

Setup (example 2)

In a shell window (xterm or Terminal, etc), type:
ssh -L 3333:asdwebdev.gsfc.nasa.gov:22 gs600-bastion1.gsfc.nasa.gov

Usage (example 2)

  • To use Secure Copy, the syntax is as follows, as typed on your local computer:
    scp -P <localport> <your_AUID>@localhost:/remote/path/to/file /local/path/to/file
    A specific example might be:
    Copy the file mystuff.txt from my home directory on asdwebdev to the current directory on my local computer:
    scp -P 3333 marida@localhost:~/mystuff.txt .
  • To set up a Secure FTP session, the syntax is:
    sftp -oPort=<localport> <your_AUID>@localhost
    or one can specify a directory to start in:
    sftp -oPort=<localport> <your_AUID>@localhost:/remote/path/to/dir
    A specific example might be:
    sftp -oPort=3333 dfriedla@localhost
  • To set up an SSHFS session, the syntax is:
    sshfs -p <localport> <your_AUID>@localhost:/remote/path/to/dir /local/path/to/mount/point
    A specific example might be:
    sshfs -p 3333 dfriedla@localhost:/software /tmp/software
    For much more information about SSHFS, please read the ASD SSHFS guide. (This is a Mac OS X-oriented document but the command structure is the same for Linux.)

Some common port numbers you might find useful

PortDescription
foo22 standard SSH port (also covers scp and sftp)
80 standard HTTP (web) port
443 standard encrypted HTTP (web) port

Multiple entries

It is also possible to stack up multiple tunnels on a single ssh command line, simply by using multiple "-L localport:remotehost:remoteport" entries (space separated, of course).

Example: multiple entries

Here is a complicated example used by Mike Arida, setting up tunnels of different types to different machines:
alias jump 'ssh -Y -L 1111:pamuk.gsfc.nasa.gov:22 -L 2222:karpuz.gsfc.nasa.gov:22 \
    -L 4444:webdrive.gsfc.nasa.gov:443 -L 5555:astrophysics.gsfc.nasa.gov:80 \
    -L 6666:universedev.gsfc.nasa.gov:443 -L 7777:heasarcdev.gsfc.nasa.gov:80 \ 
    -L 8888:universedev.gsfc.nasa.gov:80 -L 9000:code700.gsfc.nasa.gov:80 \
    -L 9997:idmax.nasa.gov:443 -L 9998:cne.gsfc.nasa.gov:443 \
    -L 9999:cne.gsfc.nasa.gov:80 marida@gs600-bastion2.gsfc.nasa.gov'

Can you do this on MS Windows?

It is also possible to do this with the freeware Windows PuTTY SSH client (available here). You will have to do the same thing of defining local & remote ports and the remote host. The PuTTY web site has its own documentation on port forwarding and the Tunnels panel. .


David Friedlander
4 April 2005, updated & expanded 17 March 2011 (D. Friedlander/M. Arida)
22 Feb 2019 (minor updates)