tunnel version 3.1.0
Michael Renner <michael.renner@gmx.de>

1.) What is tunnel good for
2.) What does it support, what not
3.) How to configure tunnel
4.) How to configure simple client applications
5.) How to configure complicated applications
6.) Examples
7.) Download



1.) What is tunnel good for

tunnel builds a ssh tunnel through a gateway to forward one or more tcp ports
to the network behind this gateway (the so called intranet). If you don't
have a gate to tunnel through you can use an other mode, where
tunnel first establish a connection from inside the intranet to a trusted
host and tunnel the protocols in a reverse direction. This thrusted host is
connected later from elsewhere using the 'casemate' mode in tunnel.


2.) What does it support, what not

tunnel in the currently existing version supports per default:
+ every single tcp based port/service redirection
+ FLEXlm port tunneling, where two ports have to be redirected
+ Compression if the installed ssh supports it

+ the simple 'gate' mode, where a gate is used to tunnel into an intranet
+ the simple 'reverse' mode, where a host outside is connected out of the intranet
+ the costly 'cassemate' mode, where a connection from inside the intranet
to a truested host is established and later on a connection from an arbitrarily
workstation somewhere is established to this trusted `casemate` host.

tunnel in the currently existing version does not support:
- ftp in any kind
- udp based service like icq


3.) How to configure tunnel

The port for every service can be set global (identical for localhost and
the remote host) or differentiated for the local and the remote side. This
is necessary if the default port is still in use due such a service
runs on the source (local) host.

All ports and hosts can be set either as command line options or
in a rcfile, which is parsed at the start.
The defaultname for this rcfile is ~/.tunnelrc, but this can be changed
by a command line option. If a /etc/tunnelrc is found it is also
considered.

The ports and hosts are definded in a simple syntax, see the
included example for more information:

<service>-host=<hostname>
<service>-intport=<port>
<service>-extport=<port>

Instead of defining internal and external port you can just define a port
which is used at the local and the remote side
<service>-port=<port>

On most systems compression is supported by the parameter
compression=<level>
where level is a value between 0 (that means 'none') and 9, which means 'best' but
may stress your processor.


If you want to connect a FLEXlm server you have to define the tcp and the
internet port to use this service. Read more about this at the bottom of this document

flexlm_<application>_host=<flexlmsserver>
flexlm_<application>_tcp_intport=<port>
flexlm_<application>_tcp_extport=<port>
flexlm_<application>_internet_intport=<port>
flexlm_<application>_internet_extport=<port>

As with the 'normal' ports you can define a port which is used on
both sides of the tunnel:

flexlm_<application>_tcp_port=<port>
flexlm_<application>_internet_port=<port>

One of the three tunnel modes is defined in the same manner:
ssh_gate=<hostname>
ssh_casemate=<hostname>
ssh_reverse=<hostname>
Please note that only one mode is acceptable.

The username which should be used to login to the ssh host can be predefined in
the rcfile:
loginuser=<loginname>

Instead of setting hosts, protocols and ports in the rcfile you are free to
define such thinks as command parameters to the tunnel start. Parameters from
the command line overwrites settings from the rcfile so you can easaly experiment
without the need of modifying your rcfile.
These parameters must start with two leading dashes like in this example:

$ tunnel --http_host=proxy --http_port=8080 --compression=7 --ssh_gate=gate.uni-gabelburg.de

There are some parameter for the command line which can't predefined in the rcfile:

-f <file>, --rcfile=<file> Configfile to use, default is ~/.tunnelrc
-h, --help display this help and exit
-v, --version output version information and exit
--verbose be more verbose in reporting what's going on

When you and others use the same casemate host to tunnel to further networks and
hosts you may find it usefull to shift up all ports by an arbitrary value. This
value can be the uid of your login account (but it have to be the same at every maschine)
or you can define an invented but unique number. This mechanism is activated
by the command line option '--offset'. An example will it make
easyer to understand: you use a maschine called 'hohentwiel' as a cassemate host.
Joe Do also use 'hohentwiel' as his cassemate host. As long as you are only
interested in tunneling different ports and protocols nothing is wrong with this.
But when both of you want to use the same port at the host you run into
truble! To shift the ports by an individual amount will prevent collisions:

You: tunnel --shift=10000 --ssh_gate=hohentwiel.uni-gabelburg.de
Joe: tunnel --shift=12000 --ssh_gate=hohentwiel.uni-gabelburg.de

Your local port 2401 (e.g.) will be shifted to 12401 at the cassemate host. But
Joe Do's cvs port 2401 will be shifted to 14401 at the cassemate host.

You have to give this option also at the other side:

You: tunnel --shift=10000 --ssh_casemate=hohentwiel.uni-gabelburg.de
Joe: tunnel --shift=12000 --ssh_casemate=hohentwiel.uni-gabelburg.de

So your port 12401 will be shifted back to 2401 at your cvs server. And Joe
will also reach port 2401 at his cvs server as long (!) as he gives the
right (this means the same as he used before) shift value while connecting
the cassemate host.
This switch is only available as a command line option at the moment.


When the tunnel is active all connections to a specified local port
is forwarded to the remote host (and port) where the tunnel for this port
ends. Therefore, you have to configure some thinks on your localhost
for the specified protocol:


4.) How to configure simple client applications

If you have to use alternative ports you have to configure the client
to use this non standard port, e.g. for telnet (-L 4711:loginserver.uni-gabelburg.de:23):
$ telnet localhost 4711
of if you want to use 'scp' with this tunnel you also have to define a free port
at the local side and connect this port giving the '-P' parameter to scp.

http:
Make an entry for a proxy server in your browser configuration. In mozilla
choose 'edit/preferences/advanced/proxies' and type 'localhost' and
the proxy port at the local side (remember, that the target of localhost:xxx
is remotehost:yyy, so a conection to the localhost will come out
on the remote side) in the right field.

ica (aka citrix):
make a extra entry for an addintional server in the wfica properties,
take care to set the server name to 'localhost', but do not enable
the 'firewall' option!

ssh/scp/sftp/rsync:

$ ssh -L 4711:fileserv.uni-gabelburg.local:22 gateway.uni.gabelburg.de

$ scp -p 4711 /campus/physik/weltformel.ppt hiwi@localhost:/home/hiwi/
$ scp -p 4711 hiwi@localhost:/home/hiwi/adressbook.txt /tmp/
$ ssh -p 4711 localhost
$ sftp -oPort=4711 localhosts

$ export RSYNC_RSH="/usr/bin/ssh -p 4711"
$ rsync -r -v /campus/physik/weltformel.ppt hiwi@localhost:/home/hiwi/

You may run into trouble while trying to connect to localhost and the connection
comes out at an other maschine: ssh compares the current host key of the connected
maschine with the stored key from a previous connection. When these keys differ the
connection will stop for security reasons. And for sure the host key from your
local maschine will differ from a maschines key connected true a tunnel, but
addressed as localhost! Instead of deleting the old localhost entry from your
~/.ssh/known_hosts each time it is much more clever to prevent that the key for
localhost is checkt. This is done by an additional entry in the /etc/ssh/ssh_config:
NoHostAuthenticationForLocalhost yes
With this setting keys from localhost are not longer checked.

cvs:
This makes a little more work! Lets assume your cvsroot is /home/data/cvsroot.
If you are using the tcsh, put this in your .cshrc:

setenv CVSROOT ':pserver:USER@localhost:/home/data/cvsroot'
setenv CVS_RSH ssh

OR if you are using the bash, put this in your .bashrc:

CVSROOT=':pserver:USER@localhost:/home/data/cvsroot'
CVS_RSH=ssh

cvs login

Now you can do your first checkout. For your convenience, please check
out the scripts of our CVS-server. This will give you the script
tunnelMPI, which simplifies the login process:

cvs co -d scripts-mpi software/scripts


5.) How to configure complicated applications

FLEXlm:
To use FLEXlm for licening e.g. matlab or mathematica you must
match some conditions.
The host on which the FLEXlm server runs must have an entry in the local
/etc/hosts file which refers to 127.0.0.1 e.g.
127.0.0.1 flexlmserv.uni-gabelburg.de
The two ports which FLEXlm use to communicate with the application
must be predefined in the license.dat at the server, e.g.
SERVER flexlmserv.uni-gabelburg.de 690a13d4 27000
DAEMON MLM /opt/matlab_6.5/etc/lm_matlab port=39555
You see, the ports are 27000 (the so called tcp port) and 39555
are used. If you do not have such a 'port=39555' line in your
etc/license.dat ask your adminstrator to add this statement to
the DAEMON line.

mysql:
Due you must connect the localhost with mysql one setting in the /etc/hosts file is
necessary to cloud this fact to mysql, e.g.
127.0.0.1 fakehost
On the remote side mysqld has to configured in a way, that connects from
the gate you appear to connect are granted. Then you have to give the parameter
'-h fakehost -p xyz' whenever you use mysql through the tunnel.


6.) Examples
Asuming you want to scp to fileserver.intern and telnet to loginserv.intern and using
proxy.intern as your http proxyserver as
the user student31415 and using gate.uni-gabelburg.de as your gateway you would give
diferent local and remote port numbers due on your local maschine a sshd and a telnetd
still waiting for connections.

$ tunnel --scp_host=fileserver.intern --scp_intport=4711 --scp_extport=22 \
--telnet_host=loginserve.intern --telnet_intport=3123 --telnet_extport=23 \
--http_host=proxy.intern --http_port=8080 --userlogin=student31415
After that you can use lolalhost on port 8080 as a webproxy, and running
$ telnet localhost 3123
to telnet to the loginserver in the intranet of the university and scp using a command like
$ scp -P 4711 document.tgz student31415@localhost:/home/student31415/

Instead of typing all parameters to the command line you can define everyting in your
system wide /etc/tunnelrc in in your personal ~/.tunnelrc:
scp_host=fileserver.intern
scp_intport=4711
scp_extport=22
telnet_host=loginserve.intern
telnet_intport=3123
telnet_extport=23
http_host=proxy.intern
http_port=8080
userlogin=student31415

and fire up tunnel without further parameter

7.) Download

You can find the script ftp://hyaden.dyndns.org/pub/unix/tunnel.tgz
at it's main location and on may mirrors.