Tunneling to the License Server

title image

or How to Start MATLAB at Home

Thos. STEPLETON, Pittsburgh, Penna.

Note: with some UNIX skills, it's not as time consuming or hard as the length of this document would lead you to believe!

Official Advisory

"On the other, we'd prefer you did not run your own tunnel into the SCS network. The on-campus end of the tunnel you propose is effectively a router. In order to maintain the stability of the network and our ability to identify devices connected to it, we prefer that no unauthorized routers be attached to the network, and we reserve the right to disconnect without notice any machine, including a router, which causes ir is involved in any network problems. You certainly should not encourage other people to set up routers attached to the SCS network."

Intro

If you're like me, you have a copy of MATLAB on your MacOS X or other UNIX box that falls under the CMU site license. This means that every time it starts, and sometimes when it's running, MATLAB contacts a special license server machine on the CMU campus to make sure you haven't somehow turned into an elite software pirate since the last time it saw you. This isn't so bad if your computer happens to be at CMU--the license server recognizes your machine as being on the campus network and graciously allows MATLAB to keep running. Off campus, however, it's a different story. Upon seeing your foreign IP address, the license server freaks, and you have to resort to SSHing into your desktop machine at CMU and using slow X forwarding to see all your pretty MATLAB graphics.

You may not be exactly like me, but if you're frustrated by not being able to run your site-licensed software from an off-campus machine, this document may help you figure out a way of sidestepping your problem. With luck, this hack will tide us all over until software companies figure out that license servers are the pits and banish Globetrotter Software (makers of FlexLM®) to the depths of insolvency they deserve.

Method

There are probably many ways to get around the problem described above, but chances are the method described here is the most legal. At its heart is tunneling, which, roughly speaking, is the encapsulation of one data connection within another. You may have heard of Virtual Private Networks (VPNs), where a group of computers connected to the Internet pretend to be on their own private network--VPNs work by tunneling private network traffic in regular Internet TCP/IP connections. We'll be using tunneling in a slightly different way: using our tunnel, we'll smuggle MATLAB's communications with the license server from our computer to a middleman computer at CMU. The license server will think this CMU computer is the one asking for authorization and will grant it freely. Now we can get some work done!

The world will be a better place for researchers when developers realize that license management isn't going to stop anyone with any determination from running their programs, legitimately or otherwise. All it does is waste the time of users and system administrators.

Tools

This is where you'll find out how helpful these instructions will be to you. If you don't have administrative access to any Linux boxes at CMU, if you don't run UNIX at home, or if you have root on your desktop machine at CMU but always keep it running Windows, then these instructions are more likely to be inspirational than practical. Here's what I used:

Computers

Software

(* Not installed by default on facilitized Linux machines.)
(† Not installed by default on MacOS X machines.)

We'll now go over a few of the things you need to know to install this software on your computers. It assumes you've already done this sort thing on your own before, though. If you're not already comfortable mucking around with your system and even compiling and installing software, you may want to think twice before going through with this.

Let's start with the Home side of things. Here you'll need two daemons installed: pppd and vtund. The former comes installed by default on MacOS X and most Linux systems; if you don't have it, it should be easy to come by. The latter is a little more obscure. Major Linux distributions have it as an optional package, and RPMs and .deb files are available on the VTUN website. On OS X, you have to install it yourself. If you're truly hardcore, you'll download it along with all the libraries it needs (lzo, openssl, and more) and set it up on your own. I use Fink instead, which delivers creamy open source software goodness to my OS X machine with a relative minimum of fuss. If you've already got a source-based install of Fink going, just do fink install vtun and you're all set. (Those of you who use a binary Fink install aren't using Jaguar at the time of writing, but maybe vtun is available to you too through the normal means.) (If you haven't tried Fink yet, it's a good thing, but getting it all set up might take more time than all of this is worth.)

Now that you've installed pppd and vtun at home, you should have no trouble doing the same thing on your Linux box at CMU. Once you're done with that, see if iptables is installed (look for /sbin/iptables); if not, your distribution will have a package for you. I snagged mine off www.rpmfind.net, thinking wistfully of the days when I used to administrate Debian systems. Anyway, go ahead and install it. Everything should be ready for...

Configuration

While you were installing all of that software, you may have come up with some idea of exactly how we're going to be tunneling license server data onto the CMU network. In fact, a protocol encapsulation geekfest of operatic proportions will be unfolding itself between your computers. Stand back and think about the overall plan for a second. Assuming you have a standard DSL connection to the Internet, you're already encapsulating your TCP/IP connection to the Internet within a PPP connection to your Internet provider. Now you'll be opening an encrypted TCP/IP-based connection to your CMU computer and encapsulating a PPP connection within that, in which you will adroitly nest TCP/IP traffic bound for the license server! Four levels of encapsulation--what a smorgasbord! On top of all of this, you'll actually be setting up a TCP/IP firewall on your CMU box that allows it to act as your intermediary "inside agent". Surely performing feats like these will help you win friends and influence people.

The vtun daemon is lavishly configurable. Among the things you can specify is what it should do when it establishes and when it terminates a tunnel between two computers. This means we can set it up to automatically take care of all of the housekeeping necessary for doing the crazy stuff outlined in the previous paragraph. All of this info goes into vtund.conf files on your home and CMU computers. On my CMU box, vtund expects to find this file in /etc, the standard place for system-wide configuration files. On my OS X box, Fink's version of vtund looks for it in /sw/etc, but I keep it somewhere else entirely just to be special.

Rather than give you a nice conceptual overview of what we're going to make vtund.conf command vtund to do, I'm going to give you a pair of highly-annotated vtund.conf files for both ends of the connection that do their best to indicate what's going on. You could plunk both files onto your computers without looking at them at all, but you ought to read the commentary. Not only is it entertaining and insightful (and modest!), it also alerts you to things you need to change for your system, like, for example, your secret password for the tunnel.

The CMU computer vtund.conf

#
# The vtund.conf file for the CMU computer.
# This file is full of options that pertain to this computer's role as the
# server, which in this case means it sits around waiting for your home
# computer to instigate a tunnel.
#
# This configuration file requires that your kernel be compiled with
# netfilter (AKA iptables) and iptables_nat available as modules.
# Facilitized machines should be OK in this regard. If you're using an
# older kernel with ipchains or (heaven forfend!) ipfwadm, you'll have
# to modify this file heavily to your needs.
#

# We start with general options. These should be right for most Linux
# installations--hopefully you shouldn't have to use this.
options {
  port 5000;            	# Listen on this port.
  syslog        daemon;		# Syslog facility.
  ppp           /usr/sbin/pppd;	# Path to the PPP daemon
  ifconfig      /sbin/ifconfig;	# Path to ifconfig (not used!)
  route         /sbin/route;	# Path to route (not used!)
  firewall      /sbin/iptables;	# Path to iptables
}

# These are default options for tunnel sessions. Our tunnel session
# configuration ignores these, so you should too.
default {
  compress no;          # Compression is off by default
  speed 0;              # By default maximum speed, NO shaping
}

# Here are the specific options for our license server tunnel. The name
# reflects the fact that we're using PPP in our encapsulation scheme, among
# other things.
license-servers-suck-PPP {
   # Tunnel session password. YOU SHOULD CHANGE THIS! If you don't, someone
   # else will be able to start a tunnel to your machine and--run MATLAB!
   # Seriously, in addition to the fact that CMU probably doesn't want
   # folks violating its site license (we're just "bending" it a bit),
   # it also gives the intruder plenty of ways to try and subvert vtund,
   # which could lead to the subversion of your entire system. So, really,
   # change this.
  pass  IfIDontChangeThisImADork;
   # OK, don't change any of the next five options. They should work on all
   # machines.
  type  tty;            # tty tunnel 
  proto tcp;            # TCP protocol
  comp  lzo:9;          # LZO compression level 9
  encr  yes;            # Encryption
  keepalive yes;        # Keep connection alive

  # This section describes what vtund should do after a tunnel has
  # been established between this computer and your home computer.
  up {
	 # The first thing to do is insert the PPP module into the kernel.
	 # Linux kernels portion some of their functionality into modules,
	 # which can be inserted and removed from the kernel depending on
	 # whether you need to use them. A computer sitting on an ethernet
	 # usually doesn't need the PPP module, so we take the precaution of
	 # installing it. If it's already installed, nothing happens.
        program /sbin/modprobe "ppp_generic" wait;

	 # OK, start the PPP connection! We give ourselves the IP 10.0.0.1
	 # and the home computer the IP 10.0.0.2 (don't worry, your computer
	 # can have multiple IP addressess). All IP addresses starting with 10
	 # are officially designated as local addresses that you can assign
	 # to your own machines at whim.
        ppp "10.0.0.1:10.0.0.2 proxyarp";

	 # Here's where we set up the firewall I was talking about earlier.
	 # WARNING: if your computer is already behaving as a firewall, you
	 # had better be really careful here! I bet this will work, but it's
	 # not my lab network on the line, now is it?
	 #
	 # OK, so the first thing we do is insert the relevant kernel modules.
        program /sbin/modprobe "iptable_nat" wait;
	 # We turn on firewalling functionality (not a precise term--don't
	 # use to impress your friends) in the kernel by putting a '1' into
	 # a special file.
        program /bin/sh "echo 1 > /proc/sys/net/ipv4/ip_forward" wait;
	 # Now we enable the firewall rule that forwards all packets out
	 # of the tunnel not destined for 10.0.0.1 onto the CMU network.
        firewall "-t nat -A POSTROUTING -o eth0 -s 10.0.0.0/24 -j MASQUERADE";
  };

  # This section describes what vtund should do when the tunnel is
  # terminated after a hard day of tunneling.
  down {
	 # We simply disable the firewall rule we set up when we started
	 # the tunnel.
        firewall "-t nat -D POSTROUTING -o eth0 -s 10.0.0.0/24 -j MASQUERADE";

	 # Remember that PPP connection? No reason to stop it--it
	 # killed itself.

	 # Remember all those modules we loaded? Your machine probably has
	 # 1 GB of RAM or something like that--they won't hurt anything by
	 # staying resident in memory. So we could remove them, but we
	 # won't.
  };
}
[ Download this file ]

The home computer vtund.conf

#
# The vtund.conf file for the home computer.
# This file is full of options that pertain to this computer's role as the
# client, which in this case means it contacts the CMU computer to instigate
# a tunnel when you start it.
#

# Here, once again, are general options. These are right for OS X 10.2.2
# and should be right for most Linux installations.
options {
  port 5000;			# Connect to this port.
  timeout 60;			# General timeout
  ppp           /usr/sbin/pppd; # Path to the PPP daemon
  ifconfig      /sbin/ifconfig;	# Path to ifconfig (not used!)
  route         /sbin/route;	# Path to route
  firewall      /sbin/iptables;	# Path to firewall configurator (not used!)
}

# The specific options for our license server tunnel.
license-servers-suck-PPP {
   # You have been properly warned about changing your password. Since
   # you've done that, now you should make certain that your passwords in
   # both the CMU and home computer vtund.conf files are the same. See,
   # I actually lied up there--things won't work if you just use these
   # files without looking at them, since the passwords don't match.
  pass  IAmASuperDorkIfIDontChangeThis;
   # OK, don't change this. I don't think it matters much.
  persist yes;          # Persist mode 

  # This section describes what vtund should do after a tunnel has
  # been established between this computer and the CMU computer.
  up {
	 # First, start the PPP connection! The PPP daemon will get its IP
	 # (10.0.0.2, remember?) from the CMU computer.
	 #
	 # MacOS X doesn't need a PPP module installed into its kernel, but
	 # Linux may. Don't forget to add a line loading the PPP module
	 # (just like the one in the other file) before this line if you're
	 # using Linux at home.
        ppp "noipdefault";

	 # Here's the final component of the setup. We tell OS X to route
	 # all TCP/IP traffic to the license server (which has the IP
	 # 128.2.194.30, it turns out) through our new connection!
	 #
	 # This command is specific to MacOS X! For Linux, I think you
	 # want this instead:
	 #   route "add -host 128.2.194.30 gw 10.0.0.1";
	 # I don't know for sure, though--experiment and let me know!
        route "add -host 128.2.194.30 10.0.0.1";
  };

  # This section describes what vtund should do when the tunnel is
  # terminated after a hard day of tunneling.
  down {
	 # Here we just delete that special routing instruction we specified
	 # when the tunnel was established.
	 #
	 # This command is specific to MacOS X! For Linux, I think you
	 # want this instead:
	 #   route "del -host 128.2.194.30 gw 10.0.0.1";
	 # I don't know for sure, though--experiment and let me know!
        route "delete -host 128.2.194.30 10.0.0.1";

	 # The PPP connection just killed itself--no need to worry about it.
  };
}
[ Download this file ]

Once you've finished putting these files in place, you'll probably want to change the permissions to 600 (owner read/write only), since they have your passwords inside. You may not have any other users on your computer, but sometimes buggy webservers/FTP servers/etc. can allow someone to read world-readable files on your computer from anywhere on the Internet. Best not to risk it.

Hopefully this should take care of all of the configuration. Now you're all set to go!

Usage

Since all of the hard work in setting up the tunnel is done by the up and down parts of the vtund.conf files, usage is about as much like a light switch as UNIX console-based network apps get.

1. Starting the tunnel

The first thing to do is start vtund on your CMU box, since this computer is configured to be the server. Assuming you've stuck the vtund.conf file in the default location (probably etc), issue this command as root, which tells vtund to start up as a server (-s) in the session we named license-servers-suck-PPP. 
  [root@your_rad_CMU_box /]# /usr/sbin/vtund -s license-servers-suck-PPP
You'll be returned to the prompt immediately, since vtund is a daemon. Now you start vtund on the MacOS X side with a command like the following. Here, you're telling it to look for the vtund.conf file in a nonstandard location (-f ~yourname/etc/vtund.conf), to use the license-servers-suck-PPP session, and to connect to the vtun server you just started up at your_rad_CMU_box.cs.cmu.edu . We're also using sudo to get root here, since that's the MacOS X way. 
  [your_rad_osx_box:~] yourname% sudo vtund -f ~yourname/etc/vtund.conf license-servers-suck-PPP your_rad_CMU_box.cs.cmu.edu

2. Starting your favorite FlexLM-encumbered application

Give the two vtunds several seconds to set everything up, then just start the applications normally.

Make sure you keep the tunnel running while you use your application, since many of them like to check with the license server again every so often to make certain you're still using the software legitimately. Ugh. If your network connection drops out for a minute or two occasionally, don't worry, we've configured vtund to reestablish the connection if it can.

3. Closing the tunnel

All you have to do is kill the vtund process on the client side, then the one on the server side after a couple seconds. If they don't die easily, use the -9 flag.

Technically you don't have to kill vtund on the server side, but it's good network citizenship to turn it off when you're not using it. The more network daemons you run as root on your computer, the greater your chances that you're running one with a bug, and thus the greater the chance an attacker can completely subvert your machine. If your machine is subverted, it makes it easier for the attacker to subvert other machines on the CMU network. The moral: don't run network daemons as root unless you have to.

Endnotes

That wraps it up! Please let me know if there are any errors in this document, or if you have any suggestions for improvements! Drop me a line at tss+tunneling AT ri cmu edu.

November 2002. Images and trademarks used without permission and with malicious intent aforethought.
Back to my homepage