VNET 0.9
=========

Ananth I. Sundararaj and Peter A. Dinda
Department of Computer Science
Northwestern University

Copyright (c) 2004 by Ananth I. Sundararaj and Peter Dinda

vnet-help@cs.northwestern.edu

http://virtuoso.cs.northwestern.edu


Contents:
=========

1. Description
2. Licensing
3. Files
4. Installation
5. Usage
6. Protocol
7. Example Scenario


1. Description
--------------

VNET is a general daemon for bridging Ethernet networks using TCP
connections. VNET consists of a client and a server. The client is
used simply to instruct the servers to do work on its behalf. The
servers are responsible for handling the bridging between the Ethernet
networks.

The concept of VNET is described in the following paper:

A. Sundararaj, P. Dinda, "Towards Virtual Networks for Virtual Machine
Grid Computing", Proceedings of the third USENIX Conference on Virtual
Machine Technology (VM04), May 2004.


2. Licensing
------------

Please see the included file LICENSE


3. Files
--------

README          This file
LICENSE         Licensing information

Makefile        Makefile for the VNET server and client

vnet.cc         VNET server
client.cc       VNET client

config.h        associated files
config.cc
util.h
util.cc
socks.h
socks.cc
handler.h
handler.cc
raw_ethernet_packet.h
raw_ethernet_packet.cc

4. Installation
---------------

VNET needs to be installed as root. The Makefile will install it
as a setuid root program in /usr/bin.

To build VNET, you need a recent version of GCC.  We use compiled it 
with GCC 2.96 on Red Hat Linux 7.2, and GCC 3.2.2 on Red Hat Linux 9.0.

You will also need OpenSSL, libpcap, and libnet.  Your kernel
must be compiled to include packet filtering.

The distribution includes binaries for RH 9.0.

1. tar -xzvf vnet-0.9.tgz
untar and unzip the file

2. cd vnet-0.9

3. make clean depend all
create all the executables

4. make install  (this must be run as root)
sets the executable vnet to run as root
intsall the executables in /usr/bin/

5 make clean
remove all the object files and executables


5. Usage
--------


VNET server:

vnet password [-s] -h <_|host> -p <port> -d <devices>+

password        - password needed before VNET will do anything
-s              - encrypt the TCP connection
-h <_|host>     - bind address "_"=INADDR_ANY
-p <port>       - bind port
-d <devices>+   - list of ethernet devices that can be used for proxying

VNET client

vnetclient [-s] [-p password1] [-o port1] -h <host1> -c <command>

-s              - encrypt the TCP connection
-p <password1>  - the password to the VNET server the client is 
                  connecting to (default action is prompting for password)
-o <port1>      - the port on the VNET server the client is connecting to 
                  (4455 is the defaukt port)
-h <host1>      - the host on which the VNET server is running
-c <command>    - the command to be issued to the VNET server

command can be one of the following:

echo            - open an interactive session with the VNET server to 
                  issue commands interactively
handlers        - get a list of currently active handlers
devices         - get a list of devices the VNET server currently knows about
close -i <pid>  - close an existing handler
handle [-a port2] [-b password2] -d <host2> -e <device1> -f <device2> -g <first config local|remote> -j <addresses+>
                - establish a handler (a bridging connection)
-a <port2>      - the port on the second VNET server that this contacted 
                  VNET server should connect to (default 4455)
-b <password2>  - the password to the second VNET server that this 
                  contacted VNET server should connect to
                  (else prompted for password)
-d <host2>      - the host on which the second VNET server 
                  (that this contacted VNET server should connect to) 
                  is running
-e <device1>    - the device on the first VNET server that is part of 
                  the handler
-f <device2>    - the device on the second VNET server that is part of 
                  the handler
-g <local|remote>

- "local" means that the packets whose *destination* address matches one 
  of the addresses listed in -j <addresses+> will be forwarded by the 
  first VNET server to the second VNET server. 

- "remote" means that packets whose *source* addresses matches 
  one of the addresses listed in -j <addresses+> will be forwarded 
  by the first VNET server to the second VNET server.

- the second VNET server will be "remote" or "local" depending on 
  whether the first VNET server is "local" or "remote" respectively

- A forwarded packet is retransmitted by the destination bridge.

-j <addresses+> - The list of addresses to be proxied for. 
 The first address specified SHOULD NOT be the broadcast or a multicast 
 address, the specific MAC address of the VM interface should always be
 listed first.  IF YOU GET THIS WRONG YOU WILL PROBABLY TRIGGER AN
 ARP STORM ON ONE OR BOTH NETWORKS.


6. Protocol
-----------

A VNET server can be contacted by a client or by another VNET
server. client<->VNET server communication is all text-based.  VNET
server<->VNET server communication is text-based until a BEGIN is
accepted.  At this point, the TCP connection is "bootstrapped" and
used to communicate raw ethernet packets.

The protocol is driven by the client or by the VNET server that
initiates the communication.  In response to client requests, the VNET
server responds with "OK" for success and "NOK" for failure.

All TCP connections have the option of being encrypted using SSL.

Connection establishment
========================

client or (first) VNET server (acting as client) does active open 
to a second VNET server.

client:

HELLO password version

vnet server:

OK version    

or

NOK string


Connection teardown
===================

Initiated by client.  This teardown is only done for non-bootstrapped
connections.  If a connection has been bootstrapped and you want to 
disconnect, just close the connection.

client:

DONE

vnet server:

OK string

or

NOK string


Configuration requests
======================

Get a list of devices the server VNET server knows about
----------------------------------------------------

client:

DEVICES?

vnet server:

OK string
number_of_devices
device1
device2
...

or

NOK string


Get a list of currently active handlers
---------------------------------------

client:

HANDLERS?

vnet server:

OK string 
number_of_handlers
identifier local_config local_address local_port local_device <-> remote_config remote_address remote_port remote_device addresses+
...

The "local" side of this is what the handler looks like from the
perspective of the first VNET server that we are connected to.  The remote side
is the other VNET server.  

a "config" is either "LOCAL" or "REMOTE".  "LOCAL" means that packets
whose *destination* address matches one of the addresses given will be
forwarded to the other bridge.  "REMOTE" means that packets whose
*source* addresses meatches in the addresses list will be forwarded.
A forwarded packet is retransmitted by the destination bridge.
Broadcast addresses are OK.  If one side is "LOCAL", the other should
be "REMOTE" and vice-versa.

The addresses and ports reflect the TCP connection between the two
participating bridges. 

or

NOK string


Closing a handler
-----------------

client:

CLOSE identifier

vnet server:

OK string

or

NOK string


Creating a handler
------------------

client:

HANDLE password_of_remote_bridge local_config local_device
remote_config remote_address remote_port remote_device addresses+

vnet server:

[attempts to initiate handler with other VNET server using HELLO/BEGIN"

OK string

or

NOK string


VNET Server to VNET server
================

In response to a HANDLE request, a VNET server (client now) will attempt to
establish a connection with the specified remote VNET server (server now)
and bootstrap it to the point where the two VNET servers will handle
ethernet traffic flowing between the two networks.

Connection establishment
------------------------

Identical to the "HELLO" exchange above, except using the password
provided to the VNET server (now acting as client).  

Connection bootstrap
--------------------

client:

BEGIN local_config local_device remote_config remote_device addresses+

Please read the information on the HANDLE request.  "local" is on the
client.  "remote" is on the server.  "config" is LOCAL or remote, as
above.  The addresses are the list of addresses to be handled by the handler.

vnet server:

OK
[switch to binary mode and handle until eof or close]

client:

[switch to binary mode and handle until eof or close]

or

vnet server:

NOK string

client:

[tries again]


7. Example Scenario
-------------------

Consider two Ethernet networks
169.125.44.0/24 (called the 44 network)
169.125.42.0/24 (called the 42 network)

One of the machines on the 44 network (machine44-1) has a virtual
machine running on it.  The virtual machine has its host-only
networking enabled and it is brought up as a machine on the 42 network
(say machine42-1) and its MAC address is: 00:01:02:03:04:05

Now we wish to use VNET to bridge this virtual machine to the 42
network even though it is currently on the 44 network.

We choose a machine on the 42 network as the proxy machine (say machine42-2)

We will now run the VNET server on machine44-1 and machine42-1 as follows:

machine44-1:
vnet password1 -s -h _ -p 4455 -d vmnet1

machine42-2:
vnet password2 -s -h _ -p 4455 -d eth0

We can run the vnet client on any machine and any network (say machine42-3):

machine42-3:
vnetclient -s -h machine42-2 -c handle -d machine44-1 -e eth0 -f vmnet1 -g local -j 00:01:02:03:04:05 ff:ff:ff:ff:ff:ff

The client will first prompt for the password for the vnet server on
machine42-2 and then for the vnet server on machine44-1

At the end of this, a handler will be established that will bridge the
two ethernet networks for the 00:01:02:03:04:05 address.  In other
words, for all intents and purposes, the virtual machine (machine42-1)
will appear to have its network interface plugged into the 44 network
at the same location as machine44-1.
