© 2008 by the Rector and Visitors of the University of Virginia.

The information contained on the University of Virginia’s Department of Information Technology and Communication (ITC) website is provided as a public service with the understanding that ITC makes no representations or warranties, either expressed or implied, concerning the accuracy, completeness, reliability or suitability of the information, including warrantees of title, non-infringement of copyright or patent rights of others. These pages are expected to represent the University of Virginia community and the State of Virginia in a professional manner in accordance with the University of Virginia’s Computing Policies.

ITCWeb:SSH Tunneling to Use Licensed Products Using Licensed Products through SSH Tunneling

Table of Contents

In order to comply with the terms and conditions of the license agreements with our software vendors, we now require that all users who wish to use licensed software such as Matlab, IDL, etc. from home must authenticate that they are members of the UVa community authorized to use the software. In general, we recommend that Windows and Mac users should make use of the Virtual Private Network (VPN) client UVa Anywhere. However, the VPN can complicate other network use of the machine while it is in operation. Furthermore, there is currently no UVa VPN client for Unix systems such as Linux, so an alternative method, valid for all users eligible for an account on blue.unix, makes use of tunnels through Secure Shell (ssh). With ssh tunneling, the user authenticates through blue.unix, which then passes information to and from the license manager. Since authentication is via blue.unix, in order to use ssh tunneling you must have an account on blue.unix and you must know your password there, which in general is not the same as other passwords such as your mail password. Please see the ITC accounts Web page for information about getting a blue.unix account.

Most of the software available from our Unix license server makes use of the FlexLM license manager. This requires that two ports be specified. Ports are channels over which information is communicated between two machines; they are identified by numbers. The numbers of the ports used for a particular software product can be obtained from the ITC Software Licensing Database. Log in to the database, select the product, then click on "access license codes and program files" to find the port numbers that must be tunneled. Usually these numbers will be at the top of the page that is revealed when the license codes are accessed.

Follow the instructions below for your operating system to create an ssh tunnel for a particular software package. Note to laptop users: if you have a laptop that is used both on and off grounds, it is probably simplest to use the ssh tunnel in both cases.

Windows

SecureCRT is an ssh client for Windows that is available under license to UVa students, faculty, and staff. To use SecureCRT to set up an ssh tunnel, first open SecureCRT. Create a new connection session to blue.unix.virginia.edu with a name such as tunnel1. The screenshot indicates the icon for a new connection.

Set up this connection with the name of blue.unix.virginia.edu as the connection host. Select properties for the connection. Under Categories-> Connection, select Port Forwarding. Do not select remote port forwarding. Clicking on Port Forwarding should bring up a form.

Click add. Give the port a name such as port1 and enter the first port number obtained from the ITC Software Licensing Database. These port numbers are on the page containing the license codes for the software you are trying to use. We will use 9998 for this example. Check Destination host is different from the SSH server and enter the name of the license manager (lm1.license.virginia.edu) Enter the same port number again as the destination port. Click OK to return to the form.

Select add again and repeat this process for the second port, giving it a different name such as port2 as shown in the next screenshot. We will use 9999 for this second port for purposes of illustration. Optionally, you can use the browse button (the square containing the dots to the right of the Application text field) to navigate to the executable you wish to run, such as matlab.exe. This will automatically invoke the application you wish to run as soon as you complete your tunnel connection under this session. This step is not required; the space for the executable may be left blank and the application launched in the normal way after the connection is established.

Finish the second port and return to the main connection screen.

Click OK to save the session.

Because we now use a cluster of license servers rather than a single system, it is necessary to set up two tunnels per product. Repeat the above instructions for another session, naming it something like tunnel2 and substituting lm2 for lm1 but using the same port numbers. The lm1.license.virginia.edu server should usually be the master server, but occasionally lm2.license can be the master. When initiating a tunnel, start with tunnel1; if it does not work you can then try tunnel2.

If you wish to tunnel to multiple licensed products, you can continue to stack ports in this manner; just be sure to add the required two ports per product exactly as in the example above with port1 and port2. In this case you may not want to automatically start an application upon connection. If you prefer, you can create separate sessions for each product you wish to tunnel. Keep in mind that you cannot mix lm1 and lm2 in the same session.

Now you must add the name of the license servers to your hosts file. In Windows 2000, this file is located in C:\Winnt\system32\drivers\etc whereas in Windows XP it is in the C:\Windows\system32\drivers\etc directory. Open the file in a text editor such as Notepad. (Do not use Word or another word processor.) The file should contain a line

127.0.0.1 localhost
Immediately below this line, add two lines 
127.0.0.1 localhost lm1.license.virginia.edu
127.0.0.1 localhost lm2.license.virginia.edu
This tells your machine to send all connections to lm1.license.virginia.edu through the local system. Thus when Matlab requests a connection to the license server, that request will be routed through the local host and sent over the ssh tunnel.

Return to the SecureCRT connection window. Click on the new tunnel connection. It will ask for your user id and password. Use your blue.unix/Home Directory user id and password. Once these have been entered, the connection is established and your tunnel is in operation. You can leave the connection open for as long as you wish to use the software product; it will not interfere with other uses of the network.

Linux

Obtain the port numbers from the ITC Software Licensing Database. For this example, assume that the product to be run is Matlab and the ports are 9998 and 9999.

As root, add the names of the license server to your /etc/hosts file. This file should contain a line

127.0.0.1 localhost
Immediately below this, add the lines 
127.0.0.1 localhost lm1.license.virginia.edu lm1.license.Virginia.EDU 
127.0.0.1 localhost lm2.license.virginia.edu lm2.license.Virginia.EDU
The two names for the license servers accommodate the case sensitivity of Unix. After making this change, restart your network or reboot your computer.

Equating lm1.license.virginia.edu to localhost tells your machine to send all connections to lm1.license.virginia.edu through the local system. The ssh tunnel then forwards the communications via blue.unix to the license server.

To initiate the tunnel, type the command: 

ssh -L 9998:lm1.license.virginia.edu:9998 \
        -L 9999:lm1.license.virginia.edu:9999 blue.unix.virginia.edu
The backslash is the standard shell continuation line and must be immediately followed by <enter>. The command may also be typed on a single line. Note that the name of the license server is case-insensitive in this context.

If your login id differs between your Linux workstation and your blue.unix account, add the option -l blue-userid; for example: 

ssh -L 9998:lm1.license.virginia.edu:9998 \
        -L9999:lm1.license.virginia.edu:9999  \
        -l mst3k blue.unix.virginia.edu

Multiple licensed products can be treated by adding -L options. For example, if another product runs on ports 9991 and 9992, the command to initiate the tunnel would become 

ssh -L 9998:lm1.license.virginia.edu:9998 \
        -L 9999:lm1.license.virginia.edu:9999 \
        -L 9991:lm1.license.virginia.edu:9991 \
        -L 9992:lm1.license.virginia.edu:9992 \
         blue.unix.virginia.edu

You may put this command into a script for your convenience. An example script is here. Read the comments at the beginning of the script and be sure to edit it appropriately before attempting to use it. Put the script into some convenient directory and make it executable: 

chmod u+x tunnel.sh
You may then invoke the script with the command 
./tunnel.sh
The license server now consists of a failover cluster and this means that occasionally the master server can change. The lm1.license.virginia.edu server should usually be the master server, but somtimes lm2.license might be the master. When initiating a tunnel, start with lm1; if it does not work you can then try lm2. To set up a tunnel with lm2, use exactly the same command as above with the same port numbers, but substitute lm2.license.virginia.edu for lm1.license.virginia.edu. If you use scripts you may wish to have scripts named something like matlab1.sh and matlab2.sh to account for these possibilities.

Mac OS X (version 10.2 and up)

Obtain the port numbers from the ITC Software Licensing Database. For this example, assume that the product to be run is Matlab and the ports are 9998 and 9999. You will need to replace those numbers with the actual ports.

As administrator or root, to the file /etc/hosts add the lines 

127.0.0.1 localhost lm1.license.virginia.edu lm2.license.Virginia.EDU
You may need to use a terminal and a command-line editor such as vi to effect this change. The two names for the license server accommodate the case sensitivity of Unix. After making this change, reboot your computer.

Equating lm1.license.virginia.edu to localhost tells your machine to send all connections to lm1.license.virginia.edu through the local system. The ssh tunnel then forwards the communications via blue.unix to the license server.

Open a Terminal (Applications->Utilities->Terminal). Type 

ssh -L 9998:lm1.license.virginia.edu:9998      \
        -L 9999:lm1.license.virginia.edu:9999 blue.unix.virginia.edu
The backslash is the standard shell continuation line and must be immediately followed by <enter>. The command may also be typed on a single line. Note that the name of the license server is case-insensitive in this context.

If your login id differs between your Linux workstation and your blue.unix account, add the option -l blue-userid; for example: 

ssh -L 9998:lm1.license.virginia.edu:9998  \
        -L 9999:lm1.license.virginia.edu:9999  \
        -l mst3k blue.unix.virginia.edu

as for Linux above. The Linux instructions for opening multiple tunnels will also work under OSX.

The script referenced above may also be used under Mac OSX. To use this script, copy it to some convenient directory. Open a terminal. Change directory to the location of the file. For example, suppose tunnel.sh is on your Desktop. Open the terminal window. 

ls Desktop
You should see tunnel.sh among the files. Move it to your home directory: 
mv Desktop/tunnel.sh .
The period at the end is required. Make the file executable: 
chmod u+x tunnel.sh
Edit the file tunnel.sh as appropriate for your user ID and port numbers. See the comments at the top of the file for instructions. To use the script, type 
./tunnel.sh
and type your blue.unix password when requested.

The license server now consists of a failover cluster and this means that occasionally the master server can change. The lm1.license.virginia.edu server should usually be the master server, but somtimes lm2.license might be the master. When initiating a tunnel, start with lm1; if it does not work you can then try lm2. To set up a tunnel with lm2, use exactly the same command as above with the same port numbers, but substitute lm2.license.virginia.edu for lm1.license.virginia.edu. If you use scripts you may wish to have scripts named something like matlab1 and matlab2 to account for these possibilities.

Getting Help

For any questions about or problems with using ssh tunneling, please contact the Research Computing Support Group at 243-8800, or email res-consult@virginia.edu.