sib - _s_imple _I_PX _b_ridge

(c) 2001 by Szomraky Stefan (stsz@gmx.net)
special thanks to Woschank Markus (keny@aon.at)

!! Y2K safe (;-) and Kernel 2.2.0 - 2.4.0 tested !!
----
THIS IS GPL SOFTWARE. SEE FILE "COPYING" FOR MORE INFORMATION
----


Contents:
 - -1. Information
 - 0. Prerequisites
 - 1. What is this thing, what features does it have?
 - 2. Why use sib, and not <xyz>? (PROs/CONs)
 - 3. INSTALLATION + QUICKSTART
 - 3.1 Info about tunneling between 2 local Ethernet devices
 - 4. Detailed information about command line
 - 5. What is this <zzz> thing you talk about?
 - 6. Protocol
 - 7. How to read raw Ethernet frames
 - 8. custom filters
 - 9. SIGHUP behaviour
 
*******************
* -1. Information *
*******************
 
 Please drop me a mail if you are using SIB. Only a short one like
   "Works! P133 with P166! game: ..., Kernel 2..."
   (and some additional information if you can/want)
 I want to build a compability list for games, connections, kernels... 
 
 If you have questions, bugreports, or something else to tell, you
 may contact me too.
 
      (stsz@gmx.net)

 Oh, btw: SIB now has a "homepage"!  http://members.aon.at/stsz/sib/

********************
* 0. Prerequisites *
********************
  - GNUMake and GCC (;-)
  - (OPTIONAL) for compression support: the LZO library 
               ( http://wildsau.idv.uni-linz.ac.at/mfx/lzo.html )
	     
  - 1 Linux box on each side connected to the Internet and to the LAN

******************************************************
* 1. What is this thing, what features does it have? *
******************************************************

SIB - simple IPX bridge - is a tool for tunneling IPX (and even IP and 802.3) 
via UDP over a public network (e.g. Internet). It is able to put the interface
it listens on to promiscous mode, so all frames (not only broadcasts, and frames
for the tunneling server) can be received.

Actually every 802.3 frame can be tunneled, but SIB only tunnels IPX frames
per default (this can be changed via command line). SIB also filters SMB over
IPX, to reduce network traffic (this can be disabled too).

Additionally SIB takes care which frames belong to local MAC addresses and 
sends only broadcasts and frame to non-local MACs to the remote host.

A non-plus-ultra is, that SIB can compress every frame it tunnels via LZO,
but you must have LZO lib installed (see 0.)

You may ask yourself: "Why should I need this?"
Well, there are lot of answers, but the main reason is:

1. for games

 Even with KALI for Windows ($14.99) and KALI cracked 1.2 ($0 - but bugs bugs bugs)
 there is no real WHOLE NETWORK to WHOLE NETWORK connection program which can
 tunnel IPX, filter SMB, compress it, and works with 2.4.0.
 And EVERY new game (for Windows) uses IPX for "network" (or should I say 
 Internet ;-) games. (RA2, Q3, HL...) 

2. connecting to Novel Networks

**********************************************
* 2. Why use sib, and not <xyz>? (PROs/CONs) *
**********************************************

PROs I know about:
 - works with 2.4.0
     NO solution I know about worked for ME with 2.4.0

 - maintained
     There ARE IPX bridges, but they don't work and were updated last 1999

 - simple
     I don't even use a config file - so it is kept simple and 
     "installed in 2 minutes"
  
 - filters IP and SMB over IPX
     Most ETH bridges tunnel ALL frames (IP, IPX, ...) even if you want only
     IPX. And those which filter IPX don't filter SMB over IPX.
 
 - multi packet support (splitting) if frame is longer than MTU-(UDP&IP) header
 
 - optional compression with LZO
 - prints out stats if wanted
 - simple sourcecode
 
 + will never break, 40 years warranty, makes your clothes whiter than white
   (even if they were blue), pets your cat, feeds your dog, ...
   FIRST 40 CUSTOMERS WILL RECEIVE A DIGITAL COPY OF THE GPL FOR FREE!!!
  
 - it's from Austria ;-)
   (We were the first who beamed Photons :-) )

**
CONs I know about:
  none ;-)
 
********************************
* 3. INSTALLATION + QUICKSTART *
********************************
 - Download, build and install the LZO library, if not already done. See 0.
   If you don't want compression at all disable the compression support.
   This is done by setting "USELZO" to "no", in src/Makefile (first line)
 - You may want to edit the src/Makefile (first lines) 
   Only needed in special cases.
 - make
 - make install
 
 Now you can establish a tunnel by starting sib on booth sides like this:
 sib -H remote_host_name -p 8999 -i eth0 -v 30 -c
 
 This will put eth0 in promiscous mode, listen on UDP port 8999 for incomming
 packets, enable compression (should be enabled on booth sides) and tunnel all
 IPX frames (but not SMB over IPX) to UDP:remote_host_name:8999
 
 Additionally every 30 seconds statistics will be displayed.


*************************************************************
* 3.1 Info about tunneling between 2 local Ethernet devices *
*************************************************************
 
 SIB actually has no builtin support for that feature, BUT you can now (starting
 with SIB 1.2) run 2 instances of SIB with different local/remote ports:
 
 sib -H localhost -p 8888 -P 9999 -i eth0 [...] &
 sib -H localhost -p 9999 -P 8888 -i eth1 [...] &
 

**********************************************
* 4. Detailed information about command line *
**********************************************

needed options:
-H <host>     connect to remote <host>
-p <port>     set local and remote UDP <port>
-i <if>       capture frames from if

extra options:
-h            this message
-c            use compression (fast LZO)
-q            quiet mode (no stats, information, errors)
-d[MODE]      debug mode & level
-v <SECS>     turn on verbose mode (stats are printed every <SECS> secs)
-k            don't put interface in promisc mode. See notes at the end.
-m            disable MTU size autodiscovery and multipacket frames
-a            turn off MAC filtering
-f <PROTO>    filter <PROTO>. See notes at the end.
-t <PROTO>    tunnel <PROTO>. See notes at the end.
-C <file.so>  use custom filter
-s            don't filter "SMB over IPX".
              (default is to filter all IPX-SMB packets to reduce traffic)

sometimes needed:
-P <port>     local UDP port
-B <IP>       bind to local IP
	      
	      
NOTES: promiscous mode means, that a network interface receives all frames,
         even if the destination MAC does not match (altough that frames are
         filtered by the kernel).
         Without that, only broadcasts and frames for this interface can be
         captured and forwarded.

       PROTO: valid protocols are: IP, IPX and ALL. Default is to tunnel IPX
       only. -t and -f may be specified more than once.
       NOTE: -t ALL tunnels all 802.3 frames


***********************************************
* 5. What is this <zzz> thing you talk about? *
***********************************************
 promiscous mode:
    promiscous mode means, that a network interface receives all frames,
    even if the destination MAC does not match (altough that frames are
    filtered by the kernel).
    Without that, only broadcasts and frames for this interface can be
    captured and forwarded.
 
 LZO: LZO is a compression algorithm.
 
 SMB: This is a procotol used by Windows for this file-sharing stuff.
      Actually it should be used on top of IP, but Windows is able to
      use IPX too. The problem is that this causes imense network traffic
      if Windows decides to use IPX as the preferred protocol between two
      nodes.
      Unless -s is specified, SIB filters out those packets 
      (byte 0x16 = 0x14). Try to specify -s and search for computers in the
      remote network... 

***************
* 6. Protocol *
***************
 Well, there is no REAL protocol used by SIB 1.0h.
 Frames which should be tunneled are encapsulated in a UDP 
 packet and sent. (With compression enabled they get compressed before).
 
 But I was a wise young man and I added a "CONTROL" byte for future implementations.
 This is the first byte in the UDP packets. Versions prior to 1.0h set this
 byte to 0x0 and ignore all incomming frames with a control byte not 0x0.

 Since 1.0h, this control byte is used for the following way:
 
 bits:
 MSB      LSB
   76543210

 Bit | Name    |first  |
 set | MSG_... |version| Function
 ----+---------+-------+------------------------------------------------------  
  0  | LZOFRAME| 1.0h  | If set, the data following the byte is compressed via
     |         |       | LZO compress (1x_1).
     |         |       |
  1  |  SPLIT  | 1.1   | If set, this is a part of a multipacket frame. The 
     |         |       | message consists of of the following elements:
     |         |       | 
     |         |       | The first byte following the control byte is the 
     |         |       |  multipacket sequence. Every split frame gets its own 
     |         |       |  sequence numver. This is for identification purposes.
     |         |       |
     |         |       | The second byte specifies the current part. 
     |         |       | The third byte specifies the part count.
     |         |       | 
     |         |       | After that, the data is appended.
     |         |       | 
     |         |       | See sendFrameUDP_MTU in network.cpp for more details.

 NOTE: Frames with unknown options set have to be ignored.
       Some bits (like 0 and 1) are mutually exclusive.

 This allows me (or even YOU) to add more functionality later. 
 (like better compression negotiation, pinging, identification, authentication, 
  encryption, MAC list XChange, Point-to-Multipoint communication, 
  streaming communication (TCP), ...).
  
 
**************************************
* 7. How to read raw Ethernet frames *
**************************************
 Some of (me too), asked in newsgroups, maillinglists, etc. how to put a
 interface in promiscous mode and read/send raw frames from/to it.
 
 Well, this is done pretty simple, just look at:
  man 7 packet
  man 7 netdevice
  man 2 send
  man 2 bind
  
 or in network.cpp and ether.cpp.
 
 If you are too lazy to look yourself, here are some code snippets:
          
  open a packet socket:
   fd = socket(PF_PACKET, SOCK_RAW, htons(ETH_P_ALL));
  
  bind it to an interface:
   struct sockaddr_ll dev;
   
   dev.sll_family = AF_PACKET;
   dev.sll_protocol = htons(ETH_P_ALL);
   dev.sll_ifindex = getIfIndex( fd, devname);
   
   bind( fd, (struct sockaddr *) &dev, sizeof( dev));
    
  getIfIndex is a function, which returns the interface index of a named device:
   int getIfIndex( int fd, char *devname)
   {
    struct ifreq ix;
    strcpy( ix.ifr_name, devname);
     
    ioctl( fd, SIOCGIFINDEX, &ix);
      
    return ix.ifr_ifindex;
   }
  
  put it in promiscous mode:
   struct ifreq ix;
   
   strcpy( ix.ifr_name, config.interfaceName);
   ioctl( fd, SIOCGIFFLAGS, &ix);
   
   ix.ifr_flags |= IFF_PROMISC;
   ioctl( fd, SIOCSIFFLAGS, &ix);

       
  read from it:
   len = recv( fd, buf, MAX_BUF_LEN, 0);
  
  send to it:
   send( fd, buf, len, 0);
    
  NOTE: The use of read and write is not recommended. 

*********************
* 8. custom filters *
*********************
 If you want to write a custom filter, follow these steps:
 
 1st: edit foo.c. This should include a function called filterFrame, which
      takes 2 options: an unsinged char * and an unsigned int and returns
      an int.
      
      The first one is the pointer to the frame buffer, the second one is 
      the length of the frame.
      
      Your function has to return 1 if the frame should be dropped, 0 if 
      the frame should be go through the other filter steps (MAC filter, IP/IPX
      filter, SMB filter), and -1 if all builtin filters should be bypassed.
 
 2nd: compile it via gcc -shared -Wl,-soname,foo -o foo.so foo.c
 3rd: use it via sib ... -C /.../foo.so

 VOILA    

***********************
* 9. SIGHUP behaviour *
***********************
 Some of you wanted a specific behaviour on SIGHUP, and the most wanted
 was a flush of the local MAC list - so SIB (since 1.2) behaves like that.
 
 Ideal for CRON jobs if you have laptops in your company floating between
 two networks.
  
********************************************************************************
                                   FIN
				   END
				   ENDE
********************************************************************************
		   
(C) 2001 Szomraky Stefan <stsz@gmx.net>
