STUND  = Socket TUNnel Daemon

Introduction

This is for those who already thoroughly understand IP and TCP and are familiar
with socket forwarding - for example as available in "ssh" and "term".
If you do not understand what this means then STUND is not for you just yet.
Learn about the basics first. Having said that, STUND is very simple in
concept but without the underlying knowledge it is difficult to understand how
to deploy it and it could cause unwanted side effects(like getting you fired!).

All STUND does is to intercept IP packets arriving from your kernel at a slip
device which it has set up itself for this purpose. It then sends these packets
via the TCP layer to a partner STUND on another machine (yes - it does work
with them both on the same hosts too). Packets arriving via the TCP layer are
stuffed back into the slip interface as if they came from its "pointopoint"
partner.


The need for STUND

Having read the introduction you probably wonder why anyone needs this; after
all with tunnelling available now as part of Linux and with socket forwarding
available in well established packages this just looks like overkill.

OK. I have a distant computer which acts as my remote entry point into an
important network. It is on the internet but the only access allowed is via
an ssh login. So far so good, I can get on to it and then telnet elsewhere
(the internet part of the link is encrypted so no worries). I can improve
things a little by forwarding sockets. This lets me telnet onto a port on my
localhost and it looks just as if I am directly on a machine behind the
firewall. However when it comes to ftp this just does not work (if you have
enough experience to use STUND you will know why!); the firewall has
masqueraded my packets and the ftp server can't setup a socket stream for the
data transmission. Some ftp servers co-operate with proxies but by no means
all.

The solution is STUND. I can then setup a slip interface on my machine with
an official address within the organisation I am logging on to. I do the same
on the host where I log onto with ssh. I get them talking to each other via
the sockets that ssh has forwarded for me. Hey presto - it looks for all the
world as if my machine is really connected to the company network. I can do
everything just as if I were on the local LAN (just a bit slower -:)

You will need root access to set up the interfaces. No problem on your own
machine of course but it might be on the company firewall! The solution is to
be able to get to a machine on the network where you do have root access and
set a forwarded socket there. You might have to hack a bit with ARP to get it
to work as you want; however if you doing tricks like this you may want to
talk to those responsible for the network first. As STUND was conceived with
the idea of simply exploiting the encrypted channel over the internet that ssh
offers I prefer to leave the "hacking" ideas to other. 

*** WARNING ***
If you get into trouble for doing what you're not supposed to do then don't
blame me.
*** WARNING ***

How to use STUND


1 Compilation

1.1. Get the sources. I hope that the usual ftp servers will keep it.
1.2. Do "tar -tzf". Decide where you want to put it then do "tar -xzf". 
1.3. Check that you have everything. There is a packing list.
1.4. Check the PGP signature.
1.5. See if configure.h needs editing. 
1.6. Do a "make". If you need to repeat it do a "make clean" first. 
1.7. If its not clean then your on your own I am afraid. I work about 16 hours
     a day as it is so I don't have time to provide support. However if you
     fix it please provide me with the diffs and I will try to keep it up to
     date.
1.8. Install "stund" wherever you like to keep such things -:)

It's much better and safer to do this than to just get an executable from
someone.


2 Local testing

2.1 Bring up you machine with a modern Linux - I used 2.0.29 and I have made
    no attempt to verify compatibilty. Also make sure you have modern
    networking software. You will need "slip" compiled into the kernel (I had
    problems with it as a module - maybe you'll have better luck -:). If at
    all possible you should prove that slip does in fact work in the normal
    way before you use STUND.
2.2 Use ifconfig to ensure that the loopback interface is up and nothing else.
2.3 See that you get the help message by doing:
	stund -h
2.4 Start the server:
	stund -s 200 -l 192.168.199.1 -r 192.168.199.2
    If you get "port in use" messages then try another one but do please use
    the same one for the client in the next step.
2.5 Start the client:
	stund -c 200 -l 192.168.199.2 -r 192.168.199.1

    If all is well the server and client will disappear into the background. 
    Do a "ps -aexf" to check.
    Check also that the sl0 and sl1 interfaces have been created.
2.6 Setup the routes:
	route add 192.168.199.1 sl1
	route add 192.168.199.2 sl0
    Do this carefully. Note that each address appears twice on your machine and
    you could route directly by mistake!!!
2.7 Test the IP/TCP tunnel using ping:
	ping 192.168.199.1
    Use iconfig to see that the counts are clocking up on both sl0 and sl1.
    The local interface will clock up at least twice as fast (can be much 
    more). If they are not incrementing but the ping works then your routes
    are wrong. If ping doesn't work at all then your routes are probably wrong.
2.8 If the ping works you can try it the other way too. You can also convince
    yourself that telnet and ftp all work too. If you are intending to use ssh
    then this is a good time to experimet with that locally until you really
    do understand what is going on with socket forwarding. If the pings don't
    work then I suggest you have a look at the source code and see if you can
    figure it out. Please send me the diffs.
2.0 Repeat the test but start the server:
        stund -s 200 -aR
     and the client with:
	stund -c 200 -l 192.168.199.2 -r 192.168.199.1 -R
    You will not then need to add any routes manually (check using route -n).


Remote testing

*** You do have permission to do this don't you? ***

I will assume that you have made a connection with ssh and have forwarded port
200 so that your localhost is listening on 200 and will forward this to port
201 on the remote host. I will assume that the remote host is 192.168.100.1
(ie you did "ssh 192.168.100.1 -L200:localhost:201"). I will assume that you
want your machine to be 192.168.100.199 and that you are going to use
192.168.100.70 as the "pointopoint" address on the distant host.

3.1 On the remote host start the server STUND:
	stund -s 201 -l 192.168.100.70 -r 192.168.100.199
3.2 On the local machine start the client STUND:
	stund -c 200 -l 192.168.100.199 -r 192.168.100.70
3.3 Check that both STUND have gone into background and use ifconfig to note
    the interface numbers. I will assume "sl0".
3.4 On the remote host set up the routes:
	route add 192.168.100.70 sl0
	route add 192.168.100.199 sl0
3.5 On the local machine (assuming the rest of the 192.168.100.0 net is
    reachable via the machine you logged onto):
	route add -net 192.168.100.0 sl0
3.6 On the remote machine:
	ping 192.168.100.70		should be very quick
	ping 192.168.100.199		should be subject to network delay
3.7 On the local machine:
	ping 192.168.100.199		should be very quick
	ping 192.168.100.70		should be subject to network delay
	ping 192.168.100.?		? = any other machine on this net
                                        which is up
3.8 From your local machine you should now have access just as if you were on
    the 192.168.100.0 net local to the remote machine.
3.9 If there are other nets reachable via the remote machine then add routes
    for these locally:
	route add -net 192.168.101.0 sl0
    This may or may not work depending on whether the machines on the very
    remote net (192.168.101.0 in the example) can route back to you via the
    remote machine (read up about ARP).
3.10 Repeat the tests using the automated features of version 0.13.
     Start the server:
         stund -s 201 -aLR
     Start the client:
	stund -c 200 -l 192.168.100.199 -r 192.168.100.70 -LR
     The routes to the local and remote addresses will have been added
     on both local and remote machines.

If you are doing this without the goodwill and consent of the network
authority at the remote end you may well find that there are firewall
restrictions in place too (but as you need root access to get this far that
shouldn't hold you up for too long -:)


Version 0.13 Features

This version introduced featues which make starting up STUND a little easier.
The creation of the interface is delayed until the TCP connection is made.
You can start the server or the client with a -a argument instead of telling
it the IP addresses and mtu; it takes what its partner gives it. Extra argumentsare now available to add routes automatically.


Terminating STUND

As of version 0.12 STUND will die quietly when any of the following events
happen:

	The interface is brought down. That means you can do:
		 "ifconfig sl? down" and the local STUND which is servicing
		this inerface will die.

	Its partner STUND dies. This means that if the socket level layer
	reports errors then STUND dies.

In effect you can kill both STUND by bringing down any one of the interfaces.
The other one may wait until it tries to send/receive traffic before it decides
to die - but die it will!


Restarts

You can restart the interface and open TCP sessions will resume.


Cautions

Risky areas: don't try it between different versions of networking software.
It was always understood that both ends were running up to date Linux and
network software (more than likely exactly the same). There is no protocol to
negotiate the connection; don't try mixed mtu sizes: keep the remote/local
addresses in step (i.e. the client should be a mirror image of the sever).
If you do try any of these please provide me with feedback - but don't wait
for an answer.


Conclusion

Please don't use this for defeating firewalls; it is sure to annoy someone.
There is a desperate need for software such as STUND to enable fully
functional encrypted connections over the internet at very low cost. Discuss
it with your management. If you firm is relatively small and forward looking
then they will be convinced. If you work for a mega giant then forget it
- they want to pay millions for 56 bit security which carries a warranty
rather than risk real security with no warranty.

I do hope STUND is useful to you in same way - even if it's just some example
code.


Bugs and enhancemnets

See the sources code. Obvious deficiencies are marked /* FIXME */
Nice to have (coming soon?):
	Change the mode of operation so that the server waits for incoming
	connections and fork/execs children to set up the interface.


Licence and disclaimer

See the source code. This is my copyright but you can use and distribute it
as per the licence in the source code.

I am in no way responsible for the consequences of using this software.
You are not obliged to use. You can read the source and make sure you are
happy with it first. If you are in any doubt the don't use it.

Current version is 0.13 as at 4-JUL-97. This is the second version I have
made available. It is very much an ALPHA version. It may bite; please be
careful.

If you want to feedback any comment or diffs (even better) then please do
so but I may not be able to reply let alone implement any changes in future.
If you want to volunteer to look after this little baby you will certainly
get a sympathetic reply!!!!


Acknowledgements

Grateful thanks to countless people I have never met and probably never will,
all those who contibuted to Linux, the authors of "ssh" and last but not least
those behind "diald".

I can recommend both these. Although I stopped using diald in favour of a
manual system for bringing up slip connections it provided the inspiration
for this project - how else would I have come upon the idea of hacking into
and out of a slip interface. Good luck to you all.

Incidently STUND solves one of the bugbears of diald.
If you set up a connection using dynamic addresses (ISP assigned) and the
line goes down you loose all open connections (unless you happen to get
the same IP again - about as likely as winning the lotto). If you have used
STUND you are able to setup the interfaces again even through a competely
different set of IP addresses for the TCP part of it.

Allan Latham <alatham@flexsys-group.com>  4-JUL-97.
